|
| 1 | +# v3 路线图代码建设顺序分析 |
| 2 | + |
| 3 | +> **状态**: 前瞻分析（未立项，待裁决） |
| 4 | +> 日期：2026-08-21 |
| 5 | +> 依据：[pain-points-v3.md](../product/pain-points-v3.md) 第七部分实施路线图 + 代码库实态盘点（dev 分支，v0.10.2 交付后） |
| 6 | +> 立项后本文档迁移至 `versions/` 跟踪并按归档机制处置。 |
| 7 | +
|
| 8 | +## 一、现状盘点：v3 三层架构中"已建成"与"零代码"的边界 |
| 9 | + |
| 10 | +**公共底座（v3 称"已建成"）——代码验证属实：** |
| 11 | + |
| 12 | +| v3 声称 | 代码实证 | |
| 13 | +|---|---| |
| 14 | +| ASR/OCR/引擎池 | asr.rs / ocr.rs / engine.rs 等全量在位 | |
| 15 | +| 四维解耦（结构密度代理） | video_profile_spec.rs（7 形态）+ video_tier_detect.rs（4 画面档）+ video_profile_domain.rs（领域标签），v0.9.0 已交付并真机验收 | |
| 16 | +| PlatformAdapter | platform_adapter.rs 已落地（v0.9.0 M4） | |
| 17 | + |
| 18 | +**容器地形管线——高度成熟**：捕获→流式 ASR→字幕 OCR 融合→屏卡体系（v0.7.3）→净化链（v0.7.5/6）→结构图（v0.7.7→v0.10.2 重构）→AI 精修/补充/版本链（v0.8.0）→单笔记全功能（v0.10.0，含 tags/properties/pin/时间戳回链）。 |
| 19 | + |
| 20 | +**v3 Phase 1-4 所需的一切——零代码**（全仓 grep `terrain`/`note_group`/`flashcard`/`sm2` 均无命中）： |
| 21 | + |
| 22 | +1. terrain 标记与笔记组模型（Phase 1 核心）完全不存在 |
| 23 | +2. feed 地形进料口不存在——唯一导入路径是 import.rs 的视频文件→会话，没有"短碎片（几句话+几张图）"的采集/导入面 |
| 24 | +3. 学习循环不存在——闪卡 SM-2（REQ-019/020）自 v0.4.0 起两度顺延至今未建；Phase 2 的"组级复习/自测"依赖它从零建起 |
| 25 | +4. 组结算与过程指标埋点不存在 |
| 26 | + |
| 27 | +**既有半基建**：series_detect.rs（v0.7.2 合集检测）+ REQ-078（课程级分组，未实施）——容器地形"组"的现成基础。 |
| 28 | + |
| 29 | +## 二、建设顺序建议 |
| 30 | + |
| 31 | +### Step 0：账务清算（半天~1 天，非代码为主） |
| 32 | + |
| 33 | +- **需求池同步**：requirements-pool.md 滞后——v0.7.3/0.7.5/0.7.7/0.9.0/0.10.x 大量条目仍标"已排期"，实际代码已交付（重构区继承代码所致）。 |
| 34 | +- **REQ-146 真机验收总清**：组模型不应盖在未完成验收的屏卡/净化链上；至少清掉 v0.10.2 M3（会话 33 重跑）。 |
| 35 | + |
| 36 | +### Step 1：Phase 1a — 组数据模型与 terrain 标记（原子层） |
| 37 | + |
| 38 | +- `note_groups` 表：terrain（container/feed）、source（溯源）、domain_tag、kind（课程组/主题组/独立组） |
| 39 | +- `notes.group_id`（ensure_column 幂等迁移，项目惯例） |
| 40 | +- **结构密度路由纯函数**：信号已全部就绪——形态 unknown 比例、画面档位、章节密度、OCR 文本密度、DomainTag 命中度，加权投票复用 vote_detect 范式；输出 `自成一组 | 归主题组 | 建议（待确认）` |
| 41 | +- 单测先行（TDD，golden 路由用例） |
| 42 | +- 决策点：路由误判是 ★★★★ 死法——路由结果可见可改（组卡片显示路由理由+一键改判），与 v0.9.0 检测卡"修改即记忆"交互哲学一致 |
| 43 | + |
| 44 | +### Step 2：Phase 1b — 容器侧组化（接线优先，复用存量） |
| 45 | + |
| 46 | +- 会话→笔记落库时按 series_detect 结果自动归入课程组（兑现 REQ-078，语义升级为"容器组"） |
| 47 | +- 无系列会话按"结构密度高→自成一组"路由 |
| 48 | +- 组列表 UI 按 v3 导航层裁决挂面（容器组出现在每日/会话相关面） |
| 49 | +- 理由：feed 侧连进料口都没有；容器侧组化是对已验收资产的重新组织，风险低、价值立现 |
| 50 | + |
| 51 | +### Step 3：Phase 1c — feed 进料口 + 碎片身份（功能开关，默认关） |
| 52 | + |
| 53 | +- **碎片快速捕获**：文本 + 图片（剪贴板图片复用 REQ-132 预留）——与 v0.10.0 延后清单 #19"快速捕获"合流，一次建设两处兑现 |
| 54 | +- 碎片存储：独立原料层 fragments 新表（不与课程笔记混装是 v3 明确要求；碎片不是笔记，身份诚实，防"假燃料"死法） |
| 55 | +- DomainTag 自动归组 + 用户自建主题组（契约一：粒度对齐领域，拒绝大类） |
| 56 | + |
| 57 | +### Step 4：Phase 2a — 间隔重复引擎（学习循环的地基） |
| 58 | + |
| 59 | +- 整条路线上最大的新建块，Phase 2 全部的前置 |
| 60 | +- SM-2 调度纯函数（AGENTS.md 明确列为关键纯逻辑必须单测） |
| 61 | +- 组→闪卡生成：先本地规则版（structure_note.rs 词汇表块、glossary、重点候选直供），AI 生成为可选增强（复用 ai_client 授权/成本/审计全套） |
| 62 | +- **绑定粒度从一开始就是"组"**，不经历"会话级→再提升"的返工 |
| 63 | + |
| 64 | +### Step 5：Phase 2b — 组级复习/自测界面 + 过程指标埋点 |
| 65 | + |
| 66 | +- 复习面按组组织（容器组与碎片组同一界面同一循环——融合点的最终兑现） |
| 67 | +- 主题自测（碎片组最小验证：碎片闪卡质量是否够用） |
| 68 | +- **同步埋点**：碎片升级率、组结算执行率、主题组活跃数——Phase 4 启用前置判据，必须从 Phase 2 第一天就记 |
| 69 | + |
| 70 | +### Step 6：Phase 3 — 组结算（防沼泽） |
| 71 | + |
| 72 | +- Pre-mortem 最高危项（★★★★★） |
| 73 | +- 阈值/周期触发器 → 结算向导（核心提炼复用 AiRefine 协议、重复合并复用去重纯函数、低价值归档） |
| 74 | +- 结算必须是用户可见的仪式而非静默后台——沼泽化的本质是用户不再回访组 |
| 75 | + |
| 76 | +### Step 7：Phase 4 — 测量层（门控，默认不启动） |
| 77 | + |
| 78 | +- 显影报告/盲测/常模只在 Step 5 碎片升级率数据验证通过后评估；当前不排期 |
| 79 | + |
| 80 | +## 三、依赖图与顺序逻辑 |
| 81 | + |
| 82 | +``` |
| 83 | +Step 0 验收清算 ──► Step 1 组模型+路由（原子层） |
| 84 | + │ |
| 85 | + ┌───────────────┴───────────────┐ |
| 86 | + ▼ ▼ |
| 87 | +Step 2 容器侧组化（存量接线） Step 3 feed 进料口（新建，开关关闭） |
| 88 | + └───────────────┬───────────────┘ |
| 89 | + ▼ |
| 90 | + Step 4 间隔重复引擎（最大新建块） |
| 91 | + ▼ |
| 92 | + Step 5 组级循环 UI + 指标埋点 |
| 93 | + ▼ |
| 94 | + Step 6 组结算 ──► Step 7 测量层（门控） |
| 95 | +``` |
| 96 | + |
| 97 | +三条判断依据： |
| 98 | + |
| 99 | +1. **先容器后 feed**：容器资产已验收、组化是重组不是新建；feed 连进料口都要新建，且 v3 自己裁决 feed 默认关闭。 |
| 100 | +2. **学习循环（Step 4/5）是真正的瓶颈**：Phase 2 名为"统一"，实为"从零建闪卡体系并直接按组粒度建"。既是工作量峰值也是融合成败分叉点（契约二），排在组模型之后立刻启动，不拖到组结算之后。 |
| 101 | +3. **指标埋点与功能同批交付**：v3 的北极星和过程指标是 Phase 4 的门控判据，也是"强行融合"死法的早期探测器，晚埋一个版本就少一个版本的真实数据。 |
| 102 | + |
| 103 | +## 四、待裁决事项 |
| 104 | + |
| 105 | +| # | 事项 | 备选 | |
| 106 | +|---|------|------| |
| 107 | +| 1 | 建设顺序是否采纳 | 全盘采纳 / 调整后采纳 / 推翻重议 | |
| 108 | +| 2 | Step 0 需求池同步与 REQ-146 验收的执行人与时间 | 用户主导 / 代理先行 | |
| 109 | +| 3 | 首个实施版本立项（建议 v0.11.0 = Step 1+2 笔记组基建·容器侧） | 头脑风暴定稿后建 versions/v0.11.0.md | |
0 commit comments