docs(tasks): complete H-410 template consolidation

2026-07-17 09:54:56 +08:00
parent ecd75de825
commit 5d68fca5e7
6 changed files with 88 additions and 15 deletions
@@ -18,7 +18,7 @@
 | [`docs/README.md`](docs/README.md) | 文档导航，总览所有项目文档 |
 | [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) | AI coding agent 的入口、阅读顺序、任务领取规则 |
 | [`docs/01-vision.md`](docs/01-vision.md) | 项目为什么做、为谁做、什么不做 |
-| [`docs/02-requirements.md`](docs/02-requirements.md) | 产品需求、用户故事、验收标准 |
+| [`docs/02-requirements.md`](docs/02-requirements.md) | 产品需求、功能范围、优先级与验收标准 |
 | [`docs/07-user-stories.md`](docs/07-user-stories.md) | 用户目标、业务价值、验收场景与 US / IX 追踪 |
 | [`docs/03-tech-stack.md`](docs/03-tech-stack.md) | 技术选型和运行命令 |
 | [`docs/04-architecture.md`](docs/04-architecture.md) | 系统结构、职责边界、数据模型、开发顺序 |
@@ -37,18 +37,15 @@
 ## 四、核心用户故事（MVP）
-详细故事以[用户故事清单](07-user-stories.md)为准；本文只维护与功能和优先级对应的总览，避免两处成为相互冲突的权威来源。
+详细故事以[用户故事清单](07-user-stories.md)为准；本文只维护功能、优先级与 US 编号的索引，避免两处成为相互冲突的权威来源。
-| 用户故事 | 功能 | 角色 | 目标 / 结果 | 优先级 | 关联交互 |
+| 功能 | 用户故事 | 优先级 |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- |
-| US-001 | 【功能 1】 | 【角色】 | 【用户想完成什么并得到什么】 | P0 | IX-001、IX-002 |
+| 【功能 1】 | US-001 | P0 |
-| US-002 | 【功能 2】 | 【角色】 | 【用户想完成什么并得到什么】 | P0 | 【IX 编号 / 不适用】 |
+| 【功能 2】 | US-002 | P0 |
 | 【功能 3】 | 【US 编号】 | 【P0 / P1 / P2】 |
-每条故事至少明确：
+角色、目标、价值、验收场景和关联交互由[用户故事清单](07-user-stories.md)独占维护；具体页面行为、状态和反馈见[交互清单](08-interaction-checklist.md)。
 1. 作为【角色】，我想要【完成目标】，从而【得到价值】。
 2. 当【异常、权限或边界场景】发生时，系统会【给出保护和下一步】。
 3. 有 UI 的故事把点击、输入、加载、校验、成功和失败反馈写入[交互清单](08-interaction-checklist.md)。
 ## 五、验收标准（MVP）
@@ -75,3 +75,38 @@
 - [ ] UI 故事已关联对应 IX 编号；无 UI 的故事明确标为不适用。
 - [ ] 故事没有复制接口、字段或组件实现细节。
 - [ ] 范围、优先级与[需求](02-requirements.md)一致。
 ## 七、填写示例
 > 本节只演示如何填写字段，所有【占位符】必须替换为项目事实；不要把示例当作通用业务规则。
 ### 示例总表
 | ID | 标题 | 优先级 | 角色 | 要达成的目标 | 关联功能 | 关联交互 | 状态 |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | US-001 | 【完成核心操作】 | P0 | 【目标角色】 | 【完成后得到的价值】 | 【功能 1】 | IX-001 | 【待确认 / 已定】 |
 | US-002 | 【确认执行影响数据的操作】 | P0 | 【目标角色】 | 【理解影响后完成操作】 | 【功能 2】 | IX-002 | 【待确认 / 已定】 |
 ### US-001 【完成核心操作】
 - 关联页面 / 入口：【页面、命令或入口】
 - 使用场景 / 前置条件：【用户已满足的条件】
 作为【目标角色】，我想要【完成核心操作】，从而【获得明确价值】。
 **验收场景**
 1. 假如【前置条件】，当用户【执行目标相关的动作】，那么【可观察到成功结果】。
 2. 假如【异常、权限或边界条件】，当用户尝试该目标，那么系统【解释原因并提供下一步】。
 ### US-002 【确认执行影响数据的操作】
 - 关联页面 / 入口：【页面、命令或入口】
 - 关联交互：IX-002
 作为【目标角色】，我想要在了解【操作影响】后确认或取消【操作】，从而【避免意外结果】。
 **验收场景**
 1. 假如【操作会影响已有数据】，当用户发起【操作】，那么系统【明确说明影响并提供确认与取消】。
 2. 假如用户取消或操作失败，那么系统【保留必要上下文并说明恢复路径】。
@@ -18,14 +18,20 @@
 ## 二、交互总表
-先为每个页面或组件列出完整交互，再为高风险、P0 或容易产生歧义的交互补充详情。
+> **先总表，后详情（默认只展开 P0）**
 >
 > 1. 先在总表列出每个页面或组件的完整交互集合，确保没有遗漏用户可见动作和关键自动状态。
 > 2. 详情模板默认只填写 P0 交互；P1 / P2 仅在高风险、不可逆、权限敏感或容易产生歧义时补充详情。
 > 3. 简单、低风险且规则清楚的交互只保留总表条目，不为逐个按钮重复填写完整状态表。
 | ID | 关联用户故事 | 页面 / 组件 | 触发 | 用户目标 | 预期结果 | 优先级 | 状态 |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | IX-001 | US-001 | 【页面 / 组件】 | 【点击 / 输入 / 键盘 / 自动】 | 【用户要完成什么】 | 【可观察到的结果】 | P0 | 【待确认 / 已定】 |
 | IX-002 | US-001、US-002 | 【页面 / 组件】 | 【触发方式】 | 【用户要完成什么】 | 【可观察到的结果】 | P1 | 【待确认 / 已定】 |
-## 三、交互详情模板
+## 三、交互详情模板（默认仅 P0）
 P0 交互必须使用本模板；非 P0 交互只有在高风险、不可逆、权限敏感或容易产生歧义时才补充。
 ### IX-001 【交互标题】
@@ -93,3 +99,38 @@
 - 交互涉及接口、字段或错误格式变化时，同步更新[API 合约](api.md)；不要只在本文写成事实。
 - UI 任务的任务文件应列出相关 US / IX 编号，并把验证结果记录为完成证据。
 - 不确定的交互规则写为【待确认】，不要以示例行为替代产品决策。
 ## 六、填写示例
 > 本节只演示如何填写字段，所有【占位符】必须替换为项目事实；示例不定义具体页面、接口或业务规则。
 ### 示例总表
 | ID | 关联用户故事 | 页面 / 组件 | 触发 | 用户目标 | 预期结果 | 优先级 | 状态 |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | IX-001 | US-001 | 【页面 / 组件】 | 【点击、键盘或自动触发】 | 【完成核心操作】 | 【看到明确结果和下一步】 | P0 | 【待确认 / 已定】 |
 | IX-002 | US-002 | 【页面 / 组件】 | 【点击或键盘触发】 | 【确认或取消影响数据的操作】 | 【明确影响并安全完成或取消】 | P0 | 【待确认 / 已定】 |
 | IX-003 | US-001 | 【页面 / 组件】 | 【提交编辑内容】 | 【保存修改】 | 【显示保存结果或可恢复错误】 | P1 | 【待确认 / 已定】 |
 | IX-004 | 【US 编号】 | 【页面 / 组件】 | 【选择或拖入关联文件】 | 【关联所需文件】 | 【显示校验结果与下一步】 | P1 | 【待确认 / 已定】 |
 ### IX-001 【提交核心操作】
 - 关联用户故事：US-001
 - 前置条件：【用户具备权限且必填信息有效】
 - 用户操作：【触发核心操作】
 - 服务 / 数据依赖：【引用已定义的合约或写不适用】
 **正常路径**
 1. 用户触发【核心操作】。
 2. 系统立即【给出进行中反馈并避免重复提交】。
 3. 完成后系统【更新可见状态】，并向用户说明【下一步】。
 **状态与异常（摘要）**
 | 场景 | 必须说明的行为 | 本交互约定 |
 | --- | --- | --- |
 | 加载 / 提交中 | 保留上下文、避免重复操作、表达进度 | 【填写】 |
 | 成功 | 更新结果并给出下一步 | 【填写】 |
 | 输入校验 | 就近说明问题和修复方式 | 【填写 / 不适用】 |
 | 服务或网络错误 | 保留可恢复数据并提供重试路径 | 【填写 / 不适用】 |
@@ -18,7 +18,7 @@
 - [`../progress.md`](../progress.md)：可选历史归档 / 项目级大事记；执行记录默认写各任务文件的 `## 执行记录`。
 - [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。
 - [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。
- [需求](02-requirements.md)：要什么、用户故事、验收标准，不写技术实现。
+- [需求](02-requirements.md)：要什么、功能范围、优先级、验收标准，不写技术实现。
 - [用户故事清单](07-user-stories.md)：用户目标、业务价值、验收场景与 US / IX 关联。
 - [技术栈](03-tech-stack.md)：确定使用哪些框架、库、数据库、部署方式。
 - [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。
@@ -77,7 +77,7 @@ Get-ChildItem -Recurse -File
 | H-407 | 增加多 agent 并发任务管理约定 `docs/tasks/` | H-108, H-501 | 新增 `docs/tasks/README.md`（一任务一文件、frontmatter、防撞号、执行记录进任务文件、不逐任务改共享收尾文件）和 `_template.md`；`method-map.md` 增"多 agent 抢改任务文件"失败模式行；`06-tasks.md`/`00-ai-start-here.md` 加多 agent 分支说明；`README.md`/`docs/README.md` 登记；保持通用占位符、不绑业务 | DONE |
 | H-408 | 在 `docs/tasks/README.md` 增加用户指令暗语约定 | H-407 | 触发词表（bug:/需求:/grill:/落task/审/补/做/记backlog:）映射到"分析不改码 / 反方评审 / 落文档并提交 / git 历史核实审核 / 补结论 / 绿灯才提交、红灯报告不提交 / 记待办池"；含默认值（全栈视角、默认提交、只提交相关文件）、无上下文必须先问不得猜、AGENTS.md 为唯一权威源的声明；保持通用、触发词可改名 | DONE |
 | H-409 | 把「一任务一文件」从并发切换模式升级为默认任务管理模式 | H-407, H-408 | ① `docs/tasks/README.md` 改为默认模式文档：删除"仅并发时切换"叙事，单/多 agent 统一走一任务一文件，暗语流程、防撞号、执行记录进任务文件等规则保留；② `docs/06-tasks.md` 降级为只读路线图：仅保留 Phase 划分、里程碑 M1-M4、Backlog 待办池，预置 T-001~T-402 转为"建议拆分清单"（开工时才落成任务文件），不再逐任务跟踪状态；③ `progress.md` 标注为可选/历史归档，执行记录默认写任务文件 `## 执行记录`；`current-state.md` 保留项目级快照职责（启动/验证路径、blocker），任务状态以各任务 frontmatter 为准（可脚本汇总）；④ 同步更新引用方：`00-ai-start-here.md`（开工/收尾流程）、`05-coding-rules.md`（完成定义与证据绑定路径）、`README.md`、`docs/README.md`、`adoption-checklist.md`、`clean-state-checklist.md`、`method-map.md`；⑤ 验证：`rg` 搜"切换/冻结/逐任务追加 progress/覆盖 current-state"等旧流程表述清零，链接引用一致；不改暗语触发词，不引入 Gitea 集成（另见 Obsidian 笔记，暂缓） | DONE |
-| H-410 | 收编用户故事 / 交互清单的根目录残留示例并收窄文档重叠 | - | ① 根目录 `独立交互清单.md`、`用户故事清单.md` 占位符化后收编：内容去业务事实（用户管理 / `/api/users` / 头像上传等改为 `【占位符】`）、编号规范化为 US-001 / IX-001 格式、表格列对齐 `07-user-stories.md` / `08-interaction-checklist.md` 现有表结构、删除不存在的 `design/screenshot.svg` 引用，作为「填写示例」小节分别并入 07 / 08 文末，然后删除根目录这两个文件；② `docs/02-requirements.md` 的"核心用户故事总览表"收窄为 功能 / US 编号 / 优先级 三列，角色、目标、关联交互列移除，由 07 独占，保留"详细故事以 07 为准"的指向；③ `docs/08-interaction-checklist.md` 把"先总表、只为 P0 / 高风险 / 易歧义交互补详情"升格为醒目规则（详情模板默认只覆盖 P0），避免逐交互填全表的官僚化；④ 验证：`python3 scripts/validate_agent_context.py` 通过；`rg` 确认 `design/screenshot.svg`、`用户管理`、`/api/users` 等业务残留清零，根目录无中文文件名残留；07 / 08 / 02 相互链接一致；不改 07 / 08 文件名和编号（阅读顺序已由 README 导航表达） | TODO |
+| H-410 | 收编用户故事 / 交互清单的根目录残留示例并收窄文档重叠 | - | 已将根目录草稿收编为 07 / 08 文末的通用填写示例；02 只保留功能 / US 编号 / 优先级索引；08 默认先总表、仅为 P0 或例外交互补详情；已删除根目录草稿并完成导航、上下文和残留校验。 | DONE |
 ## Phase 5 · Harness 评审与健康度层（Tier 2）