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

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-07-17 10:04:02 +08:00
co-authored by Claude Fable 5
parent cbd927a1c3
commit 438328544b
3 changed files with 93 additions and 34 deletions
+44 -18
View File
@@ -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-编号;尚未拆任务时写待创建】。