docs(tasks): restore H-410 contract and rework fill-in examples (H-411)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-17 10:04:02 +08:00
parent cbd927a1c3
commit 438328544b
3 changed files with 93 additions and 34 deletions
@@ -78,35 +78,67 @@

 ## 七、填写示例

-> 本节只演示如何填写字段，所有【占位符】必须替换为项目事实；不要把示例当作通用业务规则。
+> 本节演示"填好之后长什么样"。示例采用通用的列表检索和删除场景，把其中的【条目】替换为项目里的真实业务对象（订单、文章、成员……）即可套用；示例不是本项目的需求，不要不加判断地照抄进正式表格。

 ### 示例总表

 | ID | 标题 | 优先级 | 角色 | 要达成的目标 | 关联功能 | 关联交互 | 状态 |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| US-001 | 【完成核心操作】 | P0 | 【目标角色】 | 【完成后得到的价值】 | 【功能 1】 | IX-001 | 【待确认 / 已定】 |
-| US-002 | 【确认执行影响数据的操作】 | P0 | 【目标角色】 | 【理解影响后完成操作】 | 【功能 2】 | IX-002 | 【待确认 / 已定】 |
+| US-001 | 按关键词找到目标【条目】 | P0 | 【管理员】 | 在大量【条目】中快速定位要处理的那一条 | 【条目】检索 | IX-001、IX-003 | 已定 |
+| US-002 | 安全地删除不再需要的【条目】 | P0 | 【管理员】 | 移除失效【条目】，且不因误操作丢数据 | 【条目】管理 | IX-002 | 已定 |

-### US-001 【完成核心操作】
+### US-001 按关键词找到目标【条目】

- 关联页面 / 入口：【页面、命令或入口】
- 使用场景 / 前置条件：【用户已满足的条件】
+- 优先级：P0
+- 关联功能：【条目】检索
+- 关联页面 / 入口：【条目】列表页
+- 关联交互：IX-001、IX-003
+- 角色：【管理员】
+- 使用场景 / 前置条件：已登录且有查看权限；列表中【条目】数量多到无法逐条浏览。

-作为【目标角色】，我想要【完成核心操作】，从而【获得明确价值】。
+**用户故事**
+
+作为【管理员】，我想要按关键词检索【条目】列表，从而不必逐页翻找就能定位要处理的【条目】。
+
+**范围**
+
+- 包含：按关键词过滤列表、显示结果数量、空结果与失败时的反馈。
+- 不包含：高级筛选、排序和保存搜索条件（另立故事）。

 **验收场景**

-1. 假如【前置条件】，当用户【执行目标相关的动作】，那么【可观察到成功结果】。
-2. 假如【异常、权限或边界条件】，当用户尝试该目标，那么系统【解释原因并提供下一步】。
+1. 假如列表中存在匹配【条目】，当用户输入关键词并触发搜索，那么列表刷新为匹配结果，并显示结果数量。
+2. 假如没有匹配结果，当用户搜索，那么显示空状态说明并提供"清除搜索"入口，不当作错误处理。
+3. 假如搜索请求失败，当用户搜索，那么保留已输入的关键词，说明失败原因并允许重试。

-### US-002 【确认执行影响数据的操作】
+**待确认**

- 关联页面 / 入口：【页面、命令或入口】
+- 【关键词匹配哪些字段、是否支持模糊匹配，由产品决策】
+
+### US-002 安全地删除不再需要的【条目】
+
+- 优先级：P0
+- 关联功能：【条目】管理
+- 关联页面 / 入口：【条目】列表页
 - 关联交互：IX-002
+- 角色：【管理员】
+- 使用场景 / 前置条件：已登录且对目标【条目】有删除权限。

-作为【目标角色】，我想要在了解【操作影响】后确认或取消【操作】，从而【避免意外结果】。
+**用户故事**
+
+作为【管理员】，我想要在确认影响后删除失效的【条目】，从而保持列表整洁且不担心误删。
+
+**范围**
+
+- 包含：单条删除、删除前确认、成功与失败反馈。
+- 不包含：批量删除、回收站与恢复（另立故事）。

 **验收场景**

-1. 假如【操作会影响已有数据】，当用户发起【操作】，那么系统【明确说明影响并提供确认与取消】。
-2. 假如用户取消或操作失败，那么系统【保留必要上下文并说明恢复路径】。
+1. 假如目标【条目】存在且用户有权限，当用户发起删除，那么系统先说明影响并要求确认，确认后该【条目】从列表消失并提示成功。
+2. 假如用户在确认对话框中取消，那么不发生任何数据变化，用户回到原位置。
+3. 假如删除请求失败或【条目】已被他人删除，那么系统说明原因、刷新列表，不出现"看起来删了但还在"的中间态。
+
+**待确认**
+
+- 【删除是硬删除还是软删除、是否需要审计留痕，由产品与合规决策】
@@ -102,35 +102,61 @@ P0 交互必须使用本模板；非 P0 交互只有在高风险、不可逆、

 ## 六、填写示例

-> 本节只演示如何填写字段，所有【占位符】必须替换为项目事实；示例不定义具体页面、接口或业务规则。
+> 本节演示"填好之后长什么样"，与[用户故事清单](07-user-stories.md)第七节的示例故事对应。示例采用通用的列表检索和删除场景，把【条目】替换为项目里的真实业务对象即可套用；接口一律引用【API 合约中的接口名】，不在本文虚构路径。示例同时演示两种粒度：低风险交互只留总表条目（IX-001、IX-003），破坏性 P0 交互按第三节完整模板展开（IX-002）。

 ### 示例总表

 | ID | 关联用户故事 | 页面 / 组件 | 触发 | 用户目标 | 预期结果 | 优先级 | 状态 |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| IX-001 | US-001 | 【页面 / 组件】 | 【点击、键盘或自动触发】 | 【完成核心操作】 | 【看到明确结果和下一步】 | P0 | 【待确认 / 已定】 |
-| IX-002 | US-002 | 【页面 / 组件】 | 【点击或键盘触发】 | 【确认或取消影响数据的操作】 | 【明确影响并安全完成或取消】 | P0 | 【待确认 / 已定】 |
-| IX-003 | US-001 | 【页面 / 组件】 | 【提交编辑内容】 | 【保存修改】 | 【显示保存结果或可恢复错误】 | P1 | 【待确认 / 已定】 |
-| IX-004 | 【US 编号】 | 【页面 / 组件】 | 【选择或拖入关联文件】 | 【关联所需文件】 | 【显示校验结果与下一步】 | P1 | 【待确认 / 已定】 |
+| IX-001 | US-001 | 【条目】列表页 · 搜索框 | 输入关键词后点击搜索或按 Enter | 按关键词过滤列表 | 列表刷新为匹配结果并显示数量；空结果给出清除入口 | P0 | 已定 |
+| IX-002 | US-002 | 【条目】列表页 · 行内删除 | 点击行内删除按钮 | 删除单条失效【条目】 | 确认影响后该行移除并提示成功 | P0 | 已定 |
+| IX-003 | US-001 | 【条目】列表页 · 列表区域 | 自动（检索请求进行中） | 感知加载进度 | 显示骨架屏，完成后替换为数据或空状态 | P1 | 已定 |

-### IX-001 【提交核心操作】
+IX-001 与 IX-003 规则清楚、风险低，只保留总表条目；IX-002 是破坏性 P0 操作，必须按完整模板展开：

- 关联用户故事：US-001
- 前置条件：【用户具备权限且必填信息有效】
- 用户操作：【触发核心操作】
- 服务 / 数据依赖：【引用已定义的合约或写不适用】
+### IX-002 删除单条【条目】（需确认）
+
+- 关联用户故事：US-002
+- 关联需求 / 验收：【条目】管理中"安全删除"的验收条目
+- 页面 / 组件：【条目】列表页 · 行内删除按钮 + 确认对话框
+- 目标角色：【管理员】
+- 前置条件：已登录；对目标【条目】有删除权限；该行数据存在。
+- 触发方式：点击行内删除按钮。
+- 用户操作：点击删除 → 在确认对话框中确认或取消。
+- 服务 / 数据依赖：【API 合约中的删除接口】；错误格式以合约为准。

 **正常路径**

-1. 用户触发【核心操作】。
-2. 系统立即【给出进行中反馈并避免重复提交】。
-3. 完成后系统【更新可见状态】，并向用户说明【下一步】。
+1. 用户点击行内删除按钮。
+2. 系统弹出确认对话框，写明被删对象名称和影响（如"不可恢复"），默认焦点落在"取消"上。
+3. 用户点击"确认删除"，按钮进入提交中状态并禁止重复提交。
+4. 删除成功后对话框关闭，该行从列表移除，提示"已删除【条目名】"。

-**状态与异常（摘要）**
+**状态与异常清单**

 | 场景 | 必须说明的行为 | 本交互约定 |
 | --- | --- | --- |
-| 加载 / 提交中 | 保留上下文、避免重复操作、表达进度 | 【填写】 |
-| 成功 | 更新结果并给出下一步 | 【填写】 |
-| 输入校验 | 就近说明问题和修复方式 | 【填写 / 不适用】 |
-| 服务或网络错误 | 保留可恢复数据并提供重试路径 | 【填写 / 不适用】 |
+| 默认 / 可操作 | 控件是否可见、可用，用户如何发现其用途 | 有删除权限时按钮在行内可见，图标带可读名称 |
+| 加载 / 提交中 | 是否禁用重复操作、进度如何表达、是否保留上下文 | 确认按钮显示进行中并禁用，对话框保持打开 |
+| 成功 | 数据、页面或焦点如何更新，用户如何确认完成 | 对话框关闭、行移除、提示含【条目名】的成功信息 |
+| 空状态 | 无数据时解释原因并给出可执行的下一步 | 删除最后一条后列表显示空状态和"新建"入口 |
+| 输入校验 | 何时校验、错误显示位置、如何修复 | 不适用（本交互无输入） |
+| 服务或网络错误 | 可理解的错误、保留的数据、重试或恢复路径 | 对话框保留并说明失败原因，可重试或取消 |
+| 权限不足 | 不静默失败，说明限制和可执行的下一步 | 无权限时不渲染按钮；请求被拒时说明所需权限 |
+| 冲突 / 重复提交 | 幂等、刷新或冲突解决方式 | 【条目】已被他人删除时提示"已不存在"并刷新列表 |
+| 破坏性操作 | 是否确认、影响范围、取消、撤销或恢复方式 | 二次确认并写明不可恢复；默认焦点在"取消" |
+| 中断 / 离线 | 草稿、返回、关闭或网络恢复后的处理 | 离线时提示不可用，不做本地假删除；恢复后可重试 |
+
+**可访问性与多端要求**
+
+- 键盘与焦点：对话框打开后焦点移入，Escape 等同取消；删除完成后焦点回到列表的合理位置。
+- 语义与读屏：删除按钮名称含【条目名】；对话框标题、影响说明和结果提示可被读屏感知。
+- 触控与手势：删除按钮满足项目平台的最小可点击区域，不依赖悬停才可见。
+- 响应式 / 小屏：窄屏下确认对话框完整可见，确认与取消按钮不被遮挡。
+- 动效：行移除可用淡出表达；用户开启"减少动态效果"时直接移除。
+
+**验收证据**
+
+- 手工验证：以【管理员】在【环境】删除一条测试【条目】，观察确认对话框、成功提示与列表刷新。
+- 自动化验证：【测试层级、场景或命令】。
+- 关联任务：【T-编号；尚未拆任务时写待创建】。
@@ -6,6 +6,7 @@
 ## 使用规则

 - 每次只领取一个状态为 `TODO` 且依赖均已 `DONE` 的任务。
+- 验收要点一经领取不得改写：完成时只更新状态列，验证证据写入提交信息或汇报；确需重新定义任务时，先经用户确认再修改验收要点。
 - 修改模板前先读 `AGENTS.md`、`CLAUDE.md` 和相关 `docs/` 文件。
 - 新增、改名或删除文档时，同步检查 `README.md` 和 `docs/README.md`。
 - 改完后至少运行：
@@ -77,8 +78,8 @@ 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 | 收编用户故事 / 交互清单的根目录残留示例并收窄文档重叠 | - | 已将根目录草稿收编为 07 / 08 文末的通用填写示例；02 只保留功能 / US 编号 / 优先级索引；08 默认先总表、仅为 P0 或例外交互补详情；已删除根目录草稿并完成导航、上下文和残留校验。 | DONE |
-| H-411 | 返修 H-410：恢复验收契约并重写填写示例 | H-410 | ① 恢复本文件中 H-410 验收要点为落任务时原文（见 ecd75de），状态保持 DONE；「使用规则」新增"验收要点一经领取不得改写，完成时只更新状态并另记证据；确需重新定义任务时先经用户确认"条款；② `docs/07-user-stories.md`、`docs/08-interaction-checklist.md` 的「填写示例」改写为具体但通用的示例（列表检索、删除确认等通用场景，业务对象统一用【条目】占位），每个字段给出真实可读的填法，不再逐字复读模板占位符；③ 08 示例以破坏性 P0 交互演示完整 10 行状态与异常清单和无障碍要求，低风险交互演示"只留总表条目"的用法；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、示例未混入真实业务事实（无具体接口路径 / 真实产品名） | TODO |
+| 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 导航表达） | DONE |
+| H-411 | 返修 H-410：恢复验收契约并重写填写示例 | H-410 | ① 恢复本文件中 H-410 验收要点为落任务时原文（见 ecd75de），状态保持 DONE；「使用规则」新增"验收要点一经领取不得改写，完成时只更新状态并另记证据；确需重新定义任务时先经用户确认"条款；② `docs/07-user-stories.md`、`docs/08-interaction-checklist.md` 的「填写示例」改写为具体但通用的示例（列表检索、删除确认等通用场景，业务对象统一用【条目】占位），每个字段给出真实可读的填法，不再逐字复读模板占位符；③ 08 示例以破坏性 P0 交互演示完整 10 行状态与异常清单和无障碍要求，低风险交互演示"只留总表条目"的用法；④ 验证：`python3 scripts/validate_agent_context.py` 通过、全仓 `.md` 相对链接无断链、示例未混入真实业务事实（无具体接口路径 / 真实产品名） | DONE |

 ## Phase 5 · Harness 评审与健康度层（Tier 2）