diff --git a/README.md b/README.md index 9f6a126..f0d9b30 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ | [`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/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) | 系统结构、职责边界、数据模型、开发顺序 | | [`docs/05-coding-rules.md`](docs/05-coding-rules.md) | AI 写代码前必须遵守的硬规则 | @@ -27,6 +28,7 @@ | [`docs/adoption-checklist.md`](docs/adoption-checklist.md) | 已有项目接入 harness 文档的迁移清单 | | [`docs/api.md`](docs/api.md) | API 合约模板 | | [`docs/routes.md`](docs/routes.md) | 页面路由、组件归属、导航规则 | +| [`docs/08-interaction-checklist.md`](docs/08-interaction-checklist.md) | UI 交互、状态反馈、无障碍与验收证据 | | [`docs/clean-state-checklist.md`](docs/clean-state-checklist.md) | 会话收尾检查清单，保证下一轮无需人工修复即可开工 | | [`docs/current-state.md`](docs/current-state.md) | 当前实现状态快照，防止计划和代码现实脱节 | | [`docs/agent-context.json`](docs/agent-context.json) | 机器可读上下文路由：最小必读、任务类型和 SHA 刷新规则 | @@ -67,7 +69,7 @@ 新项目从零开始时，建议复制根目录入口文件和 `docs/` 目录（含 `docs/tasks/`），并按操作系统选择 `init.sh` 或 `init.ps1`。复制后按顺序处理： -1. 从 `docs/01-vision.md` 和 `docs/02-requirements.md` 开始替换业务内容。 +1. 从 `docs/01-vision.md` 和 `docs/02-requirements.md` 开始替换业务内容；有 UI / UX 时，同时完成 `docs/07-user-stories.md` 和 `docs/08-interaction-checklist.md`。 2. 在 `docs/03-tech-stack.md` 固定技术选型，不确定的选项标为待定。 3. 在 `docs/04-architecture.md` 写清事实来源、数据模型、系统边界。 4. 在 `docs/06-tasks.md` 拆出阶段路线图和建议任务；开工时按 `docs/tasks/README.md` 把任务落成 `docs/tasks/T-<编号>.md`，要求 AI 每轮只领取一个任务。 diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index 9d63257..9654812 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -21,6 +21,8 @@ 7. [`tasks/README.md`](tasks/README.md)：任务文件约定（一任务一文件）；本轮任务从 `docs/tasks/` 领取。 8. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。 +若项目有页面、表单、移动端、桌面端或其他用户交互界面，首次接入还必须完成[用户故事清单](07-user-stories.md)和[交互清单](08-interaction-checklist.md)，再开始拆 UI 任务。 + 日常会话不需要机械重读全部文档： 1. 读取仓库级规则和 [`agent-context.json`](agent-context.json)。 @@ -112,6 +114,8 @@ MVP 不做： 做页面 / UI： - 先看 `02-requirements.md` 的对应验收标准。 +- 再看 `07-user-stories.md` 的用户目标和验收场景。 +- 再看 `08-interaction-checklist.md` 的关联 IX 条目、状态和无障碍要求。 - 再看 `routes.md` 的页面职责。 - 最后看 `04-architecture.md` 的组件边界。 diff --git a/docs/02-requirements.md b/docs/02-requirements.md index 8e61732..adf0587 100644 --- a/docs/02-requirements.md +++ b/docs/02-requirements.md @@ -22,11 +22,11 @@ ### 第一版 MVP（最小闭环） -| 功能 | 用户能做什么 | 优先级 | -| --- | --- | --- | -| 【功能 1】 | 【用户动作和结果】 | P0 | -| 【功能 2】 | 【用户动作和结果】 | P0 | -| 【功能 3】 | 【用户动作和结果】 | P0 | +| 功能 | 用户能做什么 | 优先级 | 关联用户故事 | +| --- | --- | --- | --- | +| 【功能 1】 | 【用户动作和结果】 | P0 | US-001 | +| 【功能 2】 | 【用户动作和结果】 | P0 | US-002 | +| 【功能 3】 | 【用户动作和结果】 | P0 | 【US 编号】 | ### 后续迭代 @@ -37,10 +37,18 @@ ## 四、核心用户故事（MVP） -1. 作为【角色】，我打开系统后能【第一步】。 -2. 我可以【关键动作】，并看到【结果】。 -3. 我可以【继续动作】，系统会【保存 / 同步 / 展示】。 -4. 当【异常场景】发生时，系统会【降级 / 提示 / 阻止错误】。 +详细故事以[用户故事清单](07-user-stories.md)为准；本文只维护与功能和优先级对应的总览，避免两处成为相互冲突的权威来源。 + +| 用户故事 | 功能 | 角色 | 目标 / 结果 | 优先级 | 关联交互 | +| --- | --- | --- | --- | --- | --- | +| US-001 | 【功能 1】 | 【角色】 | 【用户想完成什么并得到什么】 | P0 | IX-001、IX-002 | +| US-002 | 【功能 2】 | 【角色】 | 【用户想完成什么并得到什么】 | P0 | 【IX 编号 / 不适用】 | + +每条故事至少明确： + +1. 作为【角色】，我想要【完成目标】，从而【得到价值】。 +2. 当【异常、权限或边界场景】发生时，系统会【给出保护和下一步】。 +3. 有 UI 的故事把点击、输入、加载、校验、成功和失败反馈写入[交互清单](08-interaction-checklist.md)。 ## 五、验收标准（MVP） @@ -49,6 +57,7 @@ - **【功能 1】**：【打开 / 点击 / 输入 / 保存 后，应看到什么结果】。 - **【功能 2】**：【明确时间、状态、数据持久化或错误处理要求】。 - **【功能 3】**：【跨刷新、跨设备、权限、边界情况等要求】。 +- 每条 P0 判据关联至少一个 US 编号；有用户界面的判据同时关联相关 IX 编号。 ## 六、范围边界与决策 @@ -69,4 +78,4 @@ - 【自动化边界风险】：【是否会自动点击、批量提交、爬取、发送消息或触发不可逆操作】。 - 【隐私数据风险】：【是否处理个人信息、敏感文件、聊天记录、定位、联系方式等】。 - 【合规风险】：【版权、平台条款、行业监管、数据跨境、审计留痕等是否需要确认】。 -- 【待确认问题】：【谁来决策，什么时候需要决策】。 \ No newline at end of file +- 【待确认问题】：【谁来决策，什么时候需要决策】。 diff --git a/docs/05-coding-rules.md b/docs/05-coding-rules.md index 31b46dd..44915e7 100644 --- a/docs/05-coding-rules.md +++ b/docs/05-coding-rules.md @@ -13,6 +13,7 @@ ## 1. 动手前 +- 涉及页面、表单、导航或用户可见状态时，先读取关联的 `07-user-stories.md`、`08-interaction-checklist.md`、`routes.md` 和验收标准。 - 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。 - 找到本任务对应的验收标准，写之前就知道“怎么算做对”。 - 先找现有函数、组件、工具和测试，复用优先。 @@ -56,6 +57,7 @@ - [ ] 对得上需求验收标准。 - [ ] 没有夹带无关改动。 - [ ] 涉及文档事实变化时，文档已同步。 +- [ ] 涉及 UI 时，已验证关联 US / IX 的正常、加载、异常、权限和无障碍要求，或记录明确的不适用理由。 - [ ] 已在当前任务文件（`docs/tasks/T-<编号>.md`）的 `## 执行记录` 记录跑过的命令和结果作为证据（约定见 [`tasks/README.md`](tasks/README.md)），不靠"代码已写"判定完成。 - [ ] 回复里如实说明跑了什么命令、结果如何。 @@ -85,4 +87,4 @@ go test ./... ## 9. 拿不准就问 -问题要具体，说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。 \ No newline at end of file +问题要具体，说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。 diff --git a/docs/07-user-stories.md b/docs/07-user-stories.md new file mode 100644 index 0000000..751bb3f --- /dev/null +++ b/docs/07-user-stories.md @@ -0,0 +1,77 @@ +# 用户故事清单 + +> 本文记录“谁在什么场景下，为了获得什么价值，要完成什么目标”。它是产品需求的细化清单，不写接口、数据字段、组件实现或逐个按钮的行为。 +> 页面如何响应操作见[交互清单](08-interaction-checklist.md)；页面入口和导航见[路由与页面结构](routes.md)；接口形状以[API 合约](api.md)为准。 + +## 一、何时使用 + +- 有用户角色、业务目标或交互式界面的项目，必须为每个 P0 闭环维护用户故事。 +- 无图形界面的 CLI、批处理或纯基础设施项目，也可用本文描述操作者目标；没有界面交互时，不必建立交互清单。 +- 一个用户故事描述一个可感知的业务结果，不按“一个页面”“一个按钮”机械拆分。 + +## 二、职责边界与关联 + +| 信息 | 权威文档 | 说明 | +| --- | --- | --- | +| MVP 范围、优先级、非目标 | [需求](02-requirements.md) | 先定做什么，再细化故事。 | +| 用户目标、场景与验收场景 | 本文 | 每个故事使用稳定的 US 编号。 | +| 页面操作、状态与反馈 | [交互清单](08-interaction-checklist.md) | 每项交互使用稳定的 IX 编号，并回链 US。 | +| 页面入口、导航与组件归属 | [路由与页面结构](routes.md) | 不在本文复制路由表。 | +| 接口、事件与错误格式 | [API 合约](api.md) | 不在本文虚构接口路径或字段。 | + +- 用户故事 ID 使用 US-001、US-002 的形式；编号一经引用不要重用。 +- 一条用户故事可以关联多条交互；每条面向用户的 P0 交互都应回链至少一个用户故事。 +- 需求变化时，先更新[需求](02-requirements.md)，再同步本文和受影响的交互清单、任务验收。 + +## 三、用户故事总表 + +| ID | 标题 | 优先级 | 角色 | 要达成的目标 | 关联功能 | 关联交互 | 状态 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| US-001 | 【一句话故事名】 | P0 | 【角色】 | 【用户结果】 | 【功能名】 | IX-001、IX-002 | 【待确认 / 已定】 | +| US-002 | 【一句话故事名】 | P1 | 【角色】 | 【用户结果】 | 【功能名】 | 【IX 编号或不适用】 | 【待确认 / 已定】 | + +## 四、故事详情模板 + +### US-001 【故事标题】 + +- 优先级：【P0 / P1 / P2】 +- 关联功能：【02-requirements.md 中的功能名称】 +- 关联页面 / 入口：【路由、命令或入口名称】 +- 关联交互：【IX-001、IX-002；无 UI 时写不适用】 +- 角色：【谁】 +- 使用场景 / 前置条件：【何时、在什么限制下】 + +**用户故事** + +作为【角色】，我想要【完成的目标】，从而【得到的价值】。 + +**范围** + +- 包含：【本故事必须覆盖的结果】 +- 不包含：【明确不做或由其他故事承担的内容】 + +**验收场景** + +1. 假如【前置条件】，当【用户目标相关的动作发生】，那么【用户可观察到的结果】。 +2. 假如【异常、权限或数据边界】，当【用户尝试目标】，那么【系统如何保护用户并给出下一步】。 +3. 假如【需要保存、同步或恢复】，当【用户离开再返回】，那么【应保留或应丢弃的结果】。 + +**待确认** + +- 【业务规则、角色权限、数据边界或文案决策】 + +## 五、编写规则 + +- 先写角色、目标和价值，再写验收场景；不要把“点击某按钮”当作故事本身。 +- P0 故事必须可独立验收，并明确成功、失败或无权限时用户得到的结果。 +- 同一故事的细粒度点击、输入、加载、校验、确认与撤销，写入[交互清单](08-interaction-checklist.md)。 +- 未确认的规则写为【待确认】，不要让 agent 在代码中自行补全。 +- 需求、优先级或范围改变后，检查关联 US、IX、任务文件和验收标准是否仍一致。 + +## 六、交付前检查 + +- [ ] 每个 P0 功能至少关联一个 US 编号。 +- [ ] 每个故事都说明角色、目标、价值和可验证的验收场景。 +- [ ] UI 故事已关联对应 IX 编号；无 UI 的故事明确标为不适用。 +- [ ] 故事没有复制接口、字段或组件实现细节。 +- [ ] 范围、优先级与[需求](02-requirements.md)一致。 diff --git a/docs/08-interaction-checklist.md b/docs/08-interaction-checklist.md new file mode 100644 index 0000000..3a518f5 --- /dev/null +++ b/docs/08-interaction-checklist.md @@ -0,0 +1,95 @@ +# 交互清单 + +> 本文把用户故事落成可实现、可测试的界面行为：用户如何触发、系统处于什么状态、如何反馈，以及失败时怎样恢复。 +> 本文适用于 Web、移动端、桌面端、插件和其他面向用户的交互界面；纯 CLI 或无界面项目可标记为不适用。 + +## 一、职责边界 + +| 信息 | 写在哪里 | 说明 | +| --- | --- | --- | +| 用户目标、价值与业务验收 | [用户故事清单](07-user-stories.md) | 本文中的每项 UI 交互回链一个或多个 US 编号。 | +| MVP 范围与优先级 | [需求](02-requirements.md) | 交互清单不能扩大需求范围。 | +| 页面入口、路由和组件归属 | [路由与页面结构](routes.md) | 不重复维护页面导航事实。 | +| API、事件和错误格式 | [API 合约](api.md) | 这里只引用合约，不自行定义接口路径、字段或状态码。 | + +- 交互 ID 使用 IX-001、IX-002 的形式；编号一经引用不要重用。 +- 一项交互可以服务多个用户故事；一个故事通常包含多项交互。 +- 有用户可见动作、自动状态变化或关键系统反馈的 P0 页面，都应列入本文。 + +## 二、交互总表 + +先为每个页面或组件列出完整交互，再为高风险、P0 或容易产生歧义的交互补充详情。 + +| ID | 关联用户故事 | 页面 / 组件 | 触发 | 用户目标 | 预期结果 | 优先级 | 状态 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| IX-001 | US-001 | 【页面 / 组件】 | 【点击 / 输入 / 键盘 / 自动】 | 【用户要完成什么】 | 【可观察到的结果】 | P0 | 【待确认 / 已定】 | +| IX-002 | US-001、US-002 | 【页面 / 组件】 | 【触发方式】 | 【用户要完成什么】 | 【可观察到的结果】 | P1 | 【待确认 / 已定】 | + +## 三、交互详情模板 + +### IX-001 【交互标题】 + +- 关联用户故事：【US-001】 +- 关联需求 / 验收：【功能名或验收条目】 +- 页面 / 组件：【路由、界面名称或组件名称】 +- 目标角色：【角色】 +- 前置条件：【登录态、权限、数据存在性、网络或其他条件】 +- 触发方式：【点击 / 键盘 / 输入 / 手势 / 自动触发】 +- 用户操作：【用户具体做什么】 +- 服务 / 数据依赖：【引用 API、事件或本地模块合约；无则写不适用】 + +**正常路径** + +1. 用户【操作】。 +2. 系统【立即可见的响应，例如聚焦、展开、禁用重复提交或显示进度】。 +3. 系统【完成后的状态变化、页面变化或数据刷新】。 +4. 用户看到【成功反馈、下一步入口或返回位置】。 + +**状态与异常清单** + +| 场景 | 必须说明的行为 | 本交互约定 | +| --- | --- | --- | +| 默认 / 可操作 | 控件是否可见、可用，用户如何发现其用途 | 【填写】 | +| 加载 / 提交中 | 是否禁用重复操作、进度如何表达、是否保留上下文 | 【填写】 | +| 成功 | 数据、页面或焦点如何更新，用户如何确认完成 | 【填写】 | +| 空状态 | 无数据时解释原因并给出可执行的下一步 | 【填写 / 不适用】 | +| 输入校验 | 何时校验、错误显示位置、如何修复 | 【填写 / 不适用】 | +| 服务或网络错误 | 可理解的错误、保留的数据、重试或恢复路径 | 【填写 / 不适用】 | +| 权限不足 | 不静默失败，说明限制和可执行的下一步 | 【填写 / 不适用】 | +| 冲突 / 重复提交 | 幂等、刷新或冲突解决方式 | 【填写 / 不适用】 | +| 破坏性操作 | 是否确认、影响范围、取消、撤销或恢复方式 | 【填写 / 不适用】 | +| 中断 / 离线 | 草稿、返回、关闭或网络恢复后的处理 | 【填写 / 不适用】 | + +**可访问性与多端要求** + +- 键盘与焦点：【Tab 顺序、Enter / Escape、路由变化后的焦点位置】 +- 语义与读屏：【控件名称、状态、错误和动态反馈如何被感知】 +- 触控与手势：【不依赖悬停或单一手势；最小可点击区域遵循项目平台规范】 +- 响应式 / 小屏：【窄屏、横屏、缩放或动态文字下的布局和操作】 +- 动效：【是否需要动效、动效表达什么，以及减少动态效果时的降级】 + +**验收证据** + +- 手工验证：【角色、环境、操作和可观察结果】 +- 自动化验证：【测试层级、场景或命令】 +- 关联任务：【T-编号；尚未拆任务时写待创建】 + +## 四、页面级检查清单 + +每个有交互的页面或组件在交付前至少确认： + +- [ ] 已关联用户故事、页面 / 组件和验收条目。 +- [ ] 主操作与次要操作清晰，用户能预测操作后果。 +- [ ] 加载、成功、空、错误、权限和必要的确认 / 撤销场景都有约定。 +- [ ] 表单有可见标签、明确校验和可恢复的错误提示。 +- [ ] 不把颜色、悬停或手势作为唯一信息和操作方式。 +- [ ] 键盘、焦点、读屏、触控目标、缩放和小屏场景已说明或明确不适用。 +- [ ] 页面跳转、返回、关闭和中断后，用户不会丢失未说明的数据或上下文。 +- [ ] 交互没有引入[需求](02-requirements.md)之外的业务范围。 + +## 五、维护规则 + +- 先更新用户故事或需求，再更新受影响的 IX 条目。 +- 交互涉及接口、字段或错误格式变化时，同步更新[API 合约](api.md)；不要只在本文写成事实。 +- UI 任务的任务文件应列出相关 US / IX 编号，并把验证结果记录为完成证据。 +- 不确定的交互规则写为【待确认】，不要以示例行为替代产品决策。 diff --git a/docs/README.md b/docs/README.md index e53d45f..4b4383c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,6 +19,7 @@ - [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。 - [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。 - [需求](02-requirements.md)：要什么、用户故事、验收标准，不写技术实现。 +- [用户故事清单](07-user-stories.md)：用户目标、业务价值、验收场景与 US / IX 关联。 - [技术栈](03-tech-stack.md)：确定使用哪些框架、库、数据库、部署方式。 - [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。 - [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。 @@ -27,6 +28,7 @@ - [已有项目接入清单](adoption-checklist.md)：把本模板补进已有代码库时的迁移步骤和第一轮任务建议。 - [API 合约](api.md)：前后端接口形状、错误格式、鉴权约定。 - [路由与页面结构](routes.md)：页面路由、页面职责、组件归属。 +- [交互清单](08-interaction-checklist.md)：页面 / 组件交互、状态反馈、无障碍与验收证据。 - [当前实现状态](current-state.md)：可覆盖的当前快照，记录仓库现实状态、可运行命令和下一步可做任务。 - [Agent 上下文清单](agent-context.md) / [`agent-context.json`](agent-context.json) / [`Schema`](agent-context.schema.json)：按任务类型选择文档、用提交 / 文件 SHA 避免重复读取。 - [Gitea MCP 接入](gitea-mcp.md)：可选的共享文档、Issue / PR 协调、安全配置和断连降级规则。 diff --git a/docs/adoption-checklist.md b/docs/adoption-checklist.md index 2426152..5d1ed3d 100644 --- a/docs/adoption-checklist.md +++ b/docs/adoption-checklist.md @@ -29,7 +29,7 @@ | `init.sh` 或 `init.ps1` | 标准启动与验证入口，按操作系统二选一 | | `scripts/validate_agent_context.py` | 零第三方依赖校验清单和引用路径 | -推荐随后补齐：`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`、`docs/clean-state-checklist.md`；`progress.md` 可选（历史归档 / 项目级大事记）。 +推荐随后补齐：`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`、`docs/clean-state-checklist.md`；有 UI / UX 的项目再补 `docs/07-user-stories.md` 与 `docs/08-interaction-checklist.md`；`progress.md` 可选（历史归档 / 项目级大事记）。 需要 Gitea 多 Agent 协作时，再复制 `docs/gitea-mcp.md`、`docs/gitea-collaboration.md`、`.gitea/` 模板、`scripts/setup_gitea_labels.py`、`scripts/audit_gitea_coordination.py`、离线治理脚本和测试；先只读预览远端标签差异，再由维护者显式 `--apply`。Actions 工作流仅在仓库已启用 Actions 且 runner 可用时生效。 diff --git a/docs/agent-context.json b/docs/agent-context.json index 1f46645..74e4e49 100644 --- a/docs/agent-context.json +++ b/docs/agent-context.json @@ -20,10 +20,14 @@ "README.md", "docs/README.md", "docs/01-vision.md", - "docs/02-requirements.md" + "docs/02-requirements.md", + "docs/07-user-stories.md", + "docs/08-interaction-checklist.md" ], "ui": [ "docs/02-requirements.md", + "docs/07-user-stories.md", + "docs/08-interaction-checklist.md", "docs/routes.md", "docs/04-architecture.md" ], diff --git a/docs/routes.md b/docs/routes.md index f5fd65b..3b19346 100644 --- a/docs/routes.md +++ b/docs/routes.md @@ -4,12 +4,12 @@ ## 页面路由 -| 路由 | 页面 | MVP 说明 | -| --- | --- | --- | -| `/` | 首页 / 列表页 | 展示主入口 | -| `/items/{id}` | 详情页 | 展示单个资源详情 | -| `/login` | 登录页 | 登录入口 | -| `/settings` | 设置页 | 用户或系统配置 | +| 路由 | 页面 | MVP 说明 | 关联用户故事 | 关联交互 | +| --- | --- | --- | --- | --- | +| `/` | 首页 / 列表页 | 展示主入口 | 【US 编号】 | 【IX 编号】 | +| `/items/{id}` | 详情页 | 展示单个资源详情 | 【US 编号】 | 【IX 编号】 | +| `/login` | 登录页 | 登录入口 | 【US 编号】 | 【IX 编号】 | +| `/settings` | 设置页 | 用户或系统配置 | 【US 编号】 | 【IX 编号】 | ## 页面职责 @@ -31,6 +31,12 @@ - 通过账号 API 建立会话。 - 登录成功后返回原目标页或首页。 +## 交互关联 + +- 每个有用户操作或自动状态变化的页面，关联[用户故事清单](07-user-stories.md)中的 US 编号和[交互清单](08-interaction-checklist.md)中的 IX 编号。 +- 本文只说明页面入口、职责和导航；加载、空、错误、权限、校验、确认、撤销和无障碍等具体行为以交互清单为准。 +- 路由、页面职责或导航规则变化后，检查受影响的 US、IX、API 合约和任务验收是否需要同步。 + ## 组件建议 | 组件 | 归属 | 说明 | diff --git a/docs/tasks/README.md b/docs/tasks/README.md index 309fde3..e13a507 100644 --- a/docs/tasks/README.md +++ b/docs/tasks/README.md @@ -37,6 +37,7 @@ write_paths: # 允许修改的仓库相对路径 --- ## 问题 / 背景 +## 关联需求与交互（如适用） ## 方案 ## 验收要点 ## 边界（不改什么） @@ -49,6 +50,7 @@ write_paths: # 允许修改的仓库相对路径 - 状态：`TODO` · `DOING` · `DONE` · `BLOCKED`。每个 agent 同时最多一个活跃任务；项目可以并行多个写路径互不重叠的任务。 - 每个 agent 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。 - `write_paths` 必须在动手前写清。两个活跃任务路径相同，或一条是另一条的目录前缀，均视为冲突，不能并行。 +- UI 任务在动手前写清关联的 US / IX 编号；无用户界面时，在任务文件中标记交互清单不适用。 - 做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。 - **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——不逐任务追加共享的 `progress.md`（可选历史归档）、也不逐任务覆盖 `current-state.md`（项目级快照，只在启动/验证路径、目录结构或 blocker 变化时更新）。 - **只改自己那个任务文件**；不要编辑别人正在做的任务文件。 diff --git a/docs/tasks/_template.md b/docs/tasks/_template.md index 081a9a4..b2a3ae7 100644 --- a/docs/tasks/_template.md +++ b/docs/tasks/_template.md @@ -18,6 +18,12 @@ write_paths: （现象、根因、为什么要做） +## 关联需求与交互（如适用） + +- 用户故事：【US-编号；无用户故事时说明原因】 +- 交互清单：【IX-编号；无 UI 时写不适用】 +- 相关页面 / 路由：【路径或不适用】 + ## 方案 （怎么改，落到"改哪个文件、改成什么"）