docs: establish project harness baseline

2026-07-25 16:59:06 +08:00
commit 50a6d8ee5b
30 changed files with 2742 additions and 0 deletions
@@ -0,0 +1,161 @@
+# 用户故事清单
+
+> 本文描述角色、目标和业务结果。具体按钮、加载和错误反馈见
+> [交互清单](08-interaction-checklist.md)。
+
+## 用户故事总表
+
+| ID | 标题 | 优先级 | 角色 | 要达成的结果 | 关联功能 | 关联交互 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| US-001 | 创建清晰的采购任务 | P0 | 采购管理员 | 把商品资料和硬约束变成可执行任务 | F-001 | IX-002 | 已定 |
+| US-002 | 跟踪任务和查看证据 | P0 | 采购管理员 | 判断任务正在做什么、结果是否可信 | F-002、F-007 | IX-003 | 已定 |
+| US-003 | 安全领取下一条任务 | P0 | 采购执行员 | 在设备就绪时领取且只领取一条任务 | F-003 | IX-005 | 已定 |
+| US-004 | 自动检索并得到候选 | P0 | 采购执行员 | 减少手工提词和逐条比较 | F-004、F-005 | IX-006 | 已定 |
+| US-005 | 在不可逆操作前人工判断 | P0 | 采购执行员 | 接受、拒绝候选或转人工，不被自动下单 | F-006 | IX-007 | 已定 |
+| US-006 | 看懂失败并安全恢复 | P0 | 采购执行员、采购管理员 | 知道失败位置和下一步，避免重复操作 | F-007 | IX-008 | 已定 |
+| US-007 | 建立受控会话和设备身份 | P0 | 采购管理员、采购执行员 | 未授权人员和设备不能接触任务 | F-001、F-003 | IX-001、IX-004 | 已定 |
+
+## US-001 创建清晰的采购任务
+
+- 关联页面：管理 Web `/tasks/new`
+- 前置条件：管理员已登录；参考图片可读取。
+
+作为采购管理员，我想提交商品标题、描述、参考图、数量和预算，从而让采购设备拿到
+没有歧义的原始采购要求。
+
+**范围**
+
+- 包含：输入校验、图片上传、任务编号、`PENDING` 状态。
+- 不包含：批量导入、任务模板、审批流。
+
+**验收场景**
+
+1. 合法输入提交后，任务列表出现唯一编号、摘要和 `PENDING` 状态。
+2. 数量、预算、图片或文本不满足规则时，保留已填内容并指出修复位置。
+3. 网络超时后重复提交同一幂等请求，不产生重复任务。
+
+## US-002 跟踪任务和查看证据
+
+- 关联页面：管理 Web `/tasks`、`/tasks/{id}`
+- 前置条件：管理员有任务查看权限。
+
+作为采购管理员，我想查看任务状态、执行设备、候选和失败证据，从而判断自动化是否
+完成、是否需要人工介入。
+
+**范围**
+
+- 包含：列表、详情、状态时间线、候选摘要、截图、错误。
+- 不包含：生产级报表、财务对账、实时视频。
+
+**验收场景**
+
+1. 任务被领取和执行后，刷新详情能看到服务端最新状态和时间线。
+2. 任务完成后能看到候选匹配理由、人员判断和 `order_submitted=false`。
+3. 失败后能看到错误码、失败步骤、说明和有权限的证据图片。
+4. 无权限访问任务或证据时，明确拒绝且不泄露摘要。
+
+## US-003 安全领取下一条任务
+
+- 关联页面：Android“任务”页
+- 前置条件：采购员已登录、设备已绑定、没有活跃任务。
+
+作为采购执行员，我想在设备就绪时点击获取下一条任务，从而自主控制何时开始采购，
+并避免一台设备同时处理多条任务。
+
+**范围**
+
+- 包含：就绪检查、手动领取、任务预览、无任务反馈。
+- 不包含：后台推送后自动执行、抢单优先级配置。
+
+**验收场景**
+
+1. 设备就绪且有待处理任务时，点击后只出现一条已领取任务。
+2. 没有任务时显示空状态，不把空队列当作错误。
+3. 无障碍缺失、拼多多不可用、设备禁用或已有活跃任务时，说明原因并禁止领取。
+4. 网络超时或重复点击后，刷新服务端状态不会产生重复领取。
+
+## US-004 自动检索并得到候选
+
+- 关联页面：Android“任务执行”页、拼多多 App
+- 前置条件：任务已领取；用户确认开始；拼多多处于可操作状态。
+
+作为采购执行员，我想让系统从图片和文字提取搜索条件并检查少量商品，从而减少人工
+输入和逐条浏览。
+
+**范围**
+
+- 包含：结构化解析、关键词搜索、最多 5 个候选、匹配解释。
+- 不包含：全站爬取、无限翻页、跨平台比价。
+
+**验收场景**
+
+1. 解析结果保留原始数量和预算，并展示搜索词、属性、置信度和警告。
+2. App 能在已验证拼多多版本进入搜索结果并按有界流程检查候选。
+3. 找到候选时给出匹配项、缺失项、价格和判断依据。
+4. 无合理候选、模型低置信度或页面不确定时停止并转人工。
+
+## US-005 在不可逆操作前人工判断
+
+- 关联页面：Android“候选确认”页或拼多多候选/订单确认页
+- 前置条件：自动化已产生候选或“无匹配”结论。
+
+作为采购执行员，我想在订单提交前检查候选并明确接受、拒绝或转人工，从而保持对
+资金和商品选择的控制。
+
+**范围**
+
+- 包含：候选摘要、匹配理由、确认结果、停止自动化。
+- 不包含：提交订单、支付、修改收货地址、自动使用优惠。
+
+**验收场景**
+
+1. 到达人工确认点后自动化不再点击，页面清楚显示等待人员处理。
+2. 接受候选只完成验证任务，结果明确记录 `order_submitted=false`。
+3. 拒绝、无匹配或转人工时记录原因，不偷偷改搜索条件继续尝试。
+4. 任意 MVP 路径都不能到达支付动作。
+
+## US-006 看懂失败并安全恢复
+
+- 关联页面：Android“任务执行/结果”页、管理 Web 任务详情
+- 前置条件：执行期间发生可恢复或不可恢复问题。
+
+作为采购人员，我想知道自动化在哪一步因为什么停止，从而可以修复环境、人工接管或
+决定是否重试，而不是重复下单或丢失证据。
+
+**范围**
+
+- 包含：结构化错误、步骤、必要截图、恢复建议、取消。
+- 不包含：无限自动重试、自动绕过平台提示。
+
+**验收场景**
+
+1. 验证码、风控、登录失效、未知页面和安全边界分别产生可区分错误。
+2. 网络中断时保留本地待上传证据，恢复后用幂等方式补报。
+3. 用户取消时工作流在安全检查点停止，任务不会继续在后台点击。
+4. 重新打开终态任务可以看到相同结果和证据。
+
+## US-007 建立受控会话和设备身份
+
+- 关联页面：管理 Web `/login`、Android“登录/设备绑定”页
+- 前置条件：系统已有种子账号和授权设备。
+
+作为授权用户，我想使用自己的账号和设备身份访问系统，从而让任务创建与执行可追溯，
+并阻止未授权访问。
+
+**范围**
+
+- 包含：登录、退出、设备绑定、会话过期处理。
+- 不包含：自助注册、找回密码、完整用户管理和 SSO。
+
+**验收场景**
+
+1. 正确凭证建立会话，错误凭证不说明具体哪一项错误。
+2. 禁用账号或设备不能建立新会话或领取任务。
+3. 会话过期时保留非敏感界面上下文并要求重新登录。
+4. 管理员会话不能替代设备令牌，设备令牌也不能访问管理页面。
+
+## 待确认
+
+- 管理账号和采购账号的初始化、重置流程。
+- 谁负责确认测试任务、如何标注“候选可接受”的统一口径。
+- 拒绝候选是否允许创建新任务，当前默认只记录结果。