Skip to content

Commit 3b975be

Browse files
AparenciaAparencia
committed
docs(versions): v0.12.2 笔记页信息架构重构版本规划（三栏+收件箱动线+路由收敛）
1 parent 60e7ff1 commit 3b975be

2 files changed

Lines changed: 136 additions & 0 deletions

File tree

‎docs/versions/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
| v0.11.7 | [v0.11.7.md](./v0.11.7.md) — 图文会话：截屏导入 + 跨链路采集体验同步（kind 字段 + 5 命令 + 框选遮罩；排期于 v0.11.6 之后） | 版本文档（规划中 2026-08-22） |
3232
| v0.12.0 | [v0.12.0.md](./v0.12.0.md) — 图文与窗口捕获重塑：正文源多态 + WGC 抗遮挡 + 系统级截屏覆盖层 + DeepSeek 默认化 + vision 精修 + 采集浮窗化（M1-M7，七项改进修正五个断裂） | 版本文档（规划定稿 2026-08-23；**M1-M7 全部已交付**，真机验收待执行） |
3333
| v0.12.1 | [v0.12.1.md](./v0.12.1.md) — OCR 引擎回归修复：oar-ocr auto-download 误关（v0.12.0 构建修复连带）+ 引擎就绪状态真实化（engine_ready 四处落地）+ 图文会话讲者分析误报修复 | 版本文档（代码已交付 2026-08-23，真机验收回归路径待执行） |
34+
| v0.12.2 | [v0.12.2.md](./v0.12.2.md) — 笔记页信息架构重构：三栏布局（组筛选/笔记列表/阅读编辑）+ 收件箱动线（二元论碎片→升笔记补口子）+ 路由信息收敛（ⓘ 弹层）+ 新建零对话框 | 版本文档（规划定稿 2026-08-23） |
3435

3536
## 沉淀规则
3637

‎docs/versions/v0.12.2.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# v0.12.2：笔记页信息架构重构——三栏布局 + 收件箱动线 + 路由信息收敛
2+
3+
> 状态：**规划定稿（2026-08-23，设计完成待实施）**
4+
> 依据：用户对话 2026-08-23（笔记页截图 4 点抱怨：碎片捕获无头绪 · 分组混乱交互不明 · 路由理由放置存疑 · 需要自主新建笔记）+ 市场调研（捕获收件箱模式 / Gmail 分类透明性 / 自动组织先例）+ 三项用户裁决（方案 A 三栏 · 二元论碎片 · 升笔记轻确认）
5+
> 前置：v0.12.1（OCR 引擎回归修复）交付后开工
6+
7+
## 一句话
8+
9+
笔记页从"550px 一栏塞三职（筛选+列表+详情）"重构为**三栏分工**（组筛选 / 笔记列表 / 阅读编辑），给碎片补上**向上的出路**（升为笔记），把路由理由与组管理**收敛进 ⓘ 弹层**，新建笔记**零对话框**——四个抱怨分别对应：概念分家、职责分离、信息收敛、入口去摩擦。
10+
11+
## 范围
12+
13+
| # | 项目 | 类型 | 落点 |
14+
|---|------|------|------|
15+
| 1 | 三栏布局重构 | **P0** 交互债 | 240px 组侧栏 + 320px 笔记列表（常驻）+ 阅读/编辑（现有 NoteReadingView）；搜索/标签过滤时列表原位切换，不再换布局 |
16+
| 2 | 收件箱动线（碎片→笔记） | **P0** 产品缺口 | 碎片=原料（二元论裁决）；快速记录→收件箱（恒常可见）→ 升笔记/升卡/删除；新增 `promote_fragment_to_note`（事务建笔记+删碎片） |
17+
| 3 | 路由信息收敛 | **P1** 信息债 | 组行小字（系统自动归类/⚠待确认/已改判 + ⓘ）；ⓘ 弹层=人话归因+明细折叠+改判+组管理（闪卡/结算/复习本组/周契约） |
18+
| 4 | 新建笔记零对话框 | **P2** 摩擦 | 去 `window.prompt`；新建即编辑态；落未归组（全部笔记可见） |
19+
| 5 | 文档与治理 | 伴随 | requirements-pool 回填 REQ 编号（实施时）· 本版本文档 · CHANGELOG（交付时） |
20+
21+
## 设计背景
22+
23+
### 1. 市场调研要点（为何这样改）
24+
25+
| 调研结论 | 来源 | 对应变化 |
26+
|----------|------|---------|
27+
| 捕获面必须与检索面互相喂养；胜出模式 =「Capture everywhere, triage in ONE inbox」 | [捕获模式横评（Apple Notes/Notion/Obsidian/MindWiki）](https://mindwiki.io/blog/fastest-capture-inbox-comparison) | 快速记录→收件箱恒常首项，不再藏到 feed 开关后 |
28+
| 自动分类：结果可见、**原因不展示**（Gmail 页签只给"归错了可改"，从不解释信号） | [Gmail Categories 机制](https://reviewmyemails.com/emailalmanac/spam-filters-and-blocklists/fundamentals-of-spam-filtering/gmail-categories-tab-filtering)、[Apple Photos 人物相册：聚类与确认界面分离](https://support.apple.com/en-au/guide/photos/phtad9d981ab/9.0/mac/14.0#1) | 路由理由人话一行 + 信号明细默认折叠（REQ-198 "可见"重释：可见=结果+一句话，非算法原文） |
29+
| 组织范式：过滤器/容器/详情严格分离（Gmail 页签、Apple Notes 文件夹+列表+内容、Notion 视图≠容器） | [NoteLyn 组织系统分析](https://www.notelyn.com/blog/how-to-organize-notes) | 三栏拆分；组行单击=仅过滤 |
30+
| 中文音视频转笔记：听悟/讯飞为"终点/转写工具"（组织缺失或靠用户自理），Ai好记=显式三级目录 | [通义听悟、讯飞听见、Ai好记实测](https://www.cnblogs.com/Agusiling/articles/22165378) | 组=粗粒度容器（课程/主题/独立），不学三级目录（YAGNI） |
31+
| 新建：主流零对话框、第一行即标题（Apple Notes/Notion/Obsidian 快速捕获） | 同上横评 | 去 prompt，新建即编辑 |
32+
33+
### 2. 三栏布局
34+
35+
```
36+
┌──────────────┬───────────────────┬─────────────────────────────┐
37+
│ 笔记组 (240px) │ 笔记列表 (320px) │ 阅读 / 编辑（自适应） │
38+
├──────────────┼───────────────────┼─────────────────────────────┤
39+
│ ⚡ 快速记录 │ 当前视图名 +搜索+排序│ 标题+来源徽标+操作行 │
40+
│ 📥 收件箱 (3) │ 笔记卡片列表 │ Markdown 渲染（回链/任务勾选）│
41+
│ 📁 全部笔记 │ （空态引导） │ 辅助面板：版本时间线/AI补充 │
42+
│ 📁 组… │ │ │
43+
│ ─────────── │ │ │
44+
│ 🎴 复习 12 │ │ │
45+
└──────────────┴───────────────────┴─────────────────────────────┘
46+
```
47+
48+
原 `NoteGroupPanel`（545 行，职责三合一）按职责拆分：组筛选侧栏 + ⓘ 弹层 + 收件箱视图，各自单文件 ≤300 行（AGENTS.md §3.1）。
49+
50+
### 3. 碎片语义：二元论（用户裁决）
51+
52+
**碎片 = 灵感/待处理原料，不是短笔记**。短笔记可直接用「新建笔记」，碎片入口存在的意义是**比新建更轻**（零标题/零选组/零结构）。现状病根：v0.11.4 明确"碎片→笔记升级不做（身份诚实）"——捕获产物只有升卡/删除两条出口，无向上通道 → 永远躺在隐藏 feed 组里 →"无头绪"。
53+
54+
本版补上出口（对 v0.11.4 范围决策的修订）：
55+
56+
```
57+
捕获（快速记录/剪贴板）──► 📥 收件箱（fragment 列表）
58+
│
59+
┌──────────────────┼──────────────────┐
60+
▼ ▼ ▼
61+
✍ 升为笔记 ⚙ 升为闪卡 🗑 删除
62+
（轻确认） （现有多句卡生成） （二次确认）
63+
│
64+
▼
65+
进入笔记链路：编辑/AI精修/版本/归组/生成闪卡/搜索
66+
```
67+
68+
- **升笔记=轻确认**（用户裁决）：碎片卡内联展开标题（预填首句可改）+ 归组下拉（默认未归组）+ 确认 → `promote_fragment_to_note` 事务建笔记+删碎片 → **右侧自动打开新笔记**（闭环可见）。
69+
- **收件箱只装碎片**；未归组**笔记**（`group_id IS NULL`）显示在「全部笔记」——两种实体 UI 分家，各走各的动线（修正：草案中"收件箱=未归组笔记视图"作废，二元论下不成立）。
70+
- 收件箱恒常可见（固定侧栏首项 + 待处理计数），不再依赖 feedCapture 开关隐藏。
71+
- 空态引导：「一句灵感，三种归宿——升为笔记沉淀它，升为闪卡复习它，或删除它。」
72+
73+
### 4. 路由信息收敛（ⓘ 弹层）
74+
75+
组行下方一行小字（`系统自动归类 · ⓘ` / `⚠ 待确认 · ⓘ` / `已改判 · ⓘ`；⚠ 时淡橙描边保留），**组行单击只做过滤**（现状：单击=过滤+展开双动作——"不知道如何去交互"的直接原因）。
76+
77+
ⓘ 弹层四区：
78+
1. 人话归因：`系统按内容特征归入：画面以术语表为主（60 条术语）`；信号明细（术语表成块/画面文字密度等原文）折叠在"查看明细"，默认不展开；
79+
2. 改判：课程组/主题组/独立组 + 领域下拉 + 确认（修改即记忆，REQ-198 保留）；
80+
3. 组管理：⚙ 生成闪卡 ｜ 🧹 结算（含结算计划）｜ 🎴 复习本组 ｜ 📥 移入/移出选中笔记；
81+
4. 周契约卡（REQ-200，组级承诺→组级详情）。
82+
83+
### 5. 新建笔记（去摩擦）
84+
85+
`window.prompt` 移除：点「✍ 新建」→ `create_note(未命名笔记, "")` → 立即进入编辑态聚焦首行（Apple Notes/Notion 式）；落未归组（全部笔记可见）；标题编辑器内可改。
86+
87+
### 6. 后端变更清单
88+
89+
| 变更 | 说明 |
90+
|------|------|
91+
| `promote_fragment_to_note(fragmentId, title, groupId?)` | 新命令；事务建 notes（source=manual, 正文=碎片文本+图）+ 删 fragment；标题必填（前端保证）；groupId 可选 |
92+
| `capture_fragment` / `list_group_fragments` / `delete_fragment` / `update_fragment_group` | 保留，语义不变；删除加二次确认（前端化） |
93+
| feed 组地形 / fragments 表 | 保留不动（免迁移；对比 A-2 一元论：免 fragments→notes 迁移） |
94+
| feedCapture 功能开关 | 语义改为「快速记录入口」开关；默认值建议改开（本重构即转正，不再是预览）——**待实施前用户最终确认** |
95+
96+
### 7. 前端变更清单（组件级）
97+
98+
| 组件 | 动作 |
99+
|------|------|
100+
| `NoteGroupPanel.tsx` | 拆分为 `GroupSidebar.tsx`（筛选侧栏）+ `RouteInfoPopover.tsx`（ⓘ 弹层，≤300 行/文件） |
101+
| `FeedFragmentList.tsx` | 改造为收件箱碎片卡（升笔记内联表单 + 升卡 + 删） |
102+
| `NotesPage.tsx` | 三栏编排；groupFilter 只做过滤 |
103+
| `NoteListView.tsx` | 常驻中部（去掉 flatMode 隐藏依赖） |
104+
| `WeekContractCard.tsx` | 迁入 RouteInfoPopover |
105+
| `handleCreate` | 去 prompt |
106+
107+
## 关键决策与纪律
108+
109+
1. **三元分离**：筛选（侧栏）/ 列表（中部）/ 详情（右侧）各司一职；一个手势只触发一个动作——回应当前"组头单击=过滤+展开"的双动作歧义。
110+
2. **碎片是原料**（二元论，用户裁决）：碎片≠短笔记；补 v0.11.4"升级不做"的出口，范围修订在版本文档记录，不改 ADR。
111+
3. **结果可见、原因不展示**（市场先例）：路由理由人话一行 + ⓘ 明细折叠；REQ-198"可见可改"重释为"决策结果可感知、原因可按需、误判可一键纠正"。
112+
4. **收件箱只装碎片**：未归组笔记不混入收件箱（两种实体、两条动线），延续"活沉淀"（note-design-philosophy）——笔记是过渡态，碎片是最粗的证据。
113+
5. **YAGNI**：不做拖拽归组（保留"移入选中笔记"按钮）、不做碎片批量处理（逐条，学习仪式感）、不做学习循环功能改动（只挪 UI 位置）；三级目录/双链/图谱不做（产品边界，见注记哲学 §二）。
114+
6. **零后端破坏**：Phase 1 纯前端先行；fragments/feed 语义零迁移，单一新命令，测试回归面小。
115+
116+
## 落地顺序
117+
118+
- **Phase 1（纯前端，零后端改动）**：三栏拆分 + 组行交互修正 + ⓘ 弹层（迁入路由理由/改判/组管理/周契约）+ 新建去 prompt + 收件箱视图常驻（碎片列表迁移）。
119+
- **Phase 2（后端 + 开关）**：`promote_fragment_to_note` + 碎片卡升笔记/升卡接线 + feedCapture 开关语义调整（默认值待决）。
120+
- **验收走查**：种子数据过 捕获→升级→编辑→归组→闪卡 全链。
121+
122+
## 验收标准
123+
124+
1. 侧栏组行单击=仅过滤（中部列表切换，无展开动作）；⚠ 待确认组淡橙描边小字显示；ⓘ 弹层四区齐全，明细默认折叠。
125+
2. 快速记录捕获 → 收件箱计数 +1；升笔记（轻确认）→ 右侧自动打开新笔记、碎片从收件箱移除、新笔记在「全部笔记」可见；升卡幂等可重复触发；删除有二次确认；空态文案正确。
126+
3. 「✍ 新建」无 prompt，直接进入编辑态，落未归组；搜索/标签激活时中部列表原位切换为搜索结果（布局不变）。
127+
4. ⓘ 弹层内改判后组行小字变「已改判」且路由记忆生效（再次归组走新偏好）；弹层内生成闪卡/结算/复习本组/周契约可用。
128+
5. 全量回归：`cargo test`（含新命令单测）/ `cargo clippy` / `npx tsc --noEmit` / `npx vitest run` / `npm run build` 全绿；前端组件测试覆盖收件箱状态机（捕获→升笔记→移除）与 ⓘ 弹层交互。
129+
130+
## 关联
131+
132+
- [note-design-philosophy.md](../product/note-design-philosophy.md)（活沉淀：笔记=证据到知识过渡态）
133+
- requirements-pool：REQ-195~198（组容器/路由可见可改·本版重释）、REQ-199~201（内容分型/周契约/feed 消费闭环·本版补升级出口）
134+
- [v0.11.md](./v0.11.md)（v0.11.5 树形合并为本版三栏重构的前身）· [v0.12.0.md](./v0.12.0.md) · [v0.12.1.md](./v0.12.1.md)
135+
- 市场调研：捕获收件箱模式（MindWiki 横评）· 自动组织透明性（Gmail/Apple Photos）· 中文音视频笔记横评（听悟/讯飞/Ai好记）

0 commit comments

Comments
 (0)