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