From 2a26e9d6e0a522ed76dc0f0be2c895e26781db69 Mon Sep 17 00:00:00 2001 From: ila Date: Fri, 7 Aug 2026 16:36:19 +0800 Subject: [PATCH] docs: import wiki at afc651f75a3a --- 08-interaction-checklist.-.md | 357 ++++++++++++++++++++++++++++++++++ 1 file changed, 357 insertions(+) create mode 100644 08-interaction-checklist.-.md diff --git a/08-interaction-checklist.-.md b/08-interaction-checklist.-.md new file mode 100644 index 0000000..56cf35f --- /dev/null +++ b/08-interaction-checklist.-.md @@ -0,0 +1,357 @@ + +> 同步来源：[`docs/08-interaction-checklist.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/08-interaction-checklist.md) · commit `afc651f75a3a` + +# 交互清单 + +> 本文把 P0 用户故事转换成可实现、可测试的 Web 和 Android 行为。页面入口见 +> [路由](/chengma/mroubao/wiki/routes)，接口字段见 [API](/chengma/mroubao/wiki/api)。 + +## 交互总表 + +| ID | 用户故事 | 页面/组件 | 触发 | 预期结果 | 优先级 | 状态 | +| --- | --- | --- | --- | --- | --- | --- | +| IX-001 | US-007 | 管理 Web 登录 | 提交账号密码 | 建立管理会话或显示通用错误 | P0 | 已定 | +| IX-002 | US-001 | 新建任务表单 | 填写并提交 | 创建 `PENDING` 任务 | P0 | 已定 | +| IX-003 | US-002 | 任务列表/详情 | 打开、刷新、取消 | 查看最新状态、证据和允许动作 | P0 | 已定 | +| IX-004 | US-007 | App 登录/设备绑定 | 登录或会话恢复 | 建立人员+设备身份 | P0 | T-206 已实现 | +| IX-005 | US-003 | App 任务页 | 点击“获取任务” | 就绪检查后领取一条任务或显示原因 | P0 | T-206 已实现 | +| IX-006 | US-004 | App 执行页 | 确认开始/自动步骤 | 显示步骤并有界执行搜索与候选判断 | P0 | 已定 | +| IX-007 | US-005 | App 候选确认 | 接受/拒绝/转人工 | 停止自动化并回传人员结论 | P0 | 已定 | +| IX-008 | US-006 | App/管理端错误状态 | 自动失败、取消、重试上传 | 显示结构化原因和恢复动作 | P0 | 已定 | +| IX-009 | US-008 | App 候选理由/管理端决策详情 | 接受、拒绝、改选或修正 | 保存逐候选结构化人工标签 | P1 | T-208 已实现 | +| IX-010 | US-009 | App 独立执行设置/同步状态 | 配置模式、离线执行或补报 | 授权内独立执行并可审计同步 | P0 | T-206 离线控制已实现，结果补报待 T-207 | +| IX-011 | US-010 | Admin 候选授权/App 订单执行 | 选择候选并授权、设备领取执行 | 创建一笔可对账的待付款订单并提醒人工付款 | P0 | T-215 至 T-219 已完成 | +| IX-012 | US-011 | Admin 货运导入/列表/详情 | 输入完整单号或日期区间并同步 | 幂等保存货运头与全部商品明细，显示同步结果 | P0 | T-220 至 T-224 | +| IX-013 | US-012 | Admin 货运商品明细 | 核对来源字段、补充参考图并生成 | 创建或重放同一采购任务，不覆盖来源/任务历史 | P0 | T-223 | + +## IX-001 管理 Web 登录 + +- 页面：`/login` +- 角色：采购管理员 +- 前置条件：种子管理账号已建立。 +- 服务依赖：管理会话创建。 +- 关联原型：[管理登录](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/admin-login.html)（T-202）。 + +**正常路径** + +1. 用户输入账号和密码并提交。 +2. 提交期间按钮禁用并显示进度，密码不回显。 +3. 成功后进入原目标页或 `/tasks`。 + +**状态与异常** + +- 默认：账号框自动聚焦；密码可切换显示但默认隐藏。 +- 校验：空字段在字段附近提示；服务端仍执行完整校验。 +- 失败：统一显示“账号或密码不正确”，不暴露账号是否存在。 +- 网络错误：保留账号，清空密码，允许重试。 +- 会话过期：跳转登录并保留安全的返回路径。 + +**可访问性** + +- 标签与输入框显式关联；错误摘要可被读屏感知。 +- Enter 提交；焦点移到首个错误字段。 + +## IX-002 创建采购任务 + +- 页面：`/tasks/new` +- 角色：采购管理员 +- 服务依赖：`POST /api/v1/assets`、`POST /api/v1/tasks` +- 关联原型：[新建任务](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/admin-task-create.html)（T-202）。 + +**正常路径** + +1. 输入标题、SKU、描述、数量、可选商品总预算并选择一张图片。 +2. 浏览器展示图片预览、文件名和大小。 +3. 提交期间锁定重复提交并显示“正在创建”。 +4. 成功后进入任务详情，显示编号和 `PENDING`。 + +**状态与异常** + +- 标题和 SKU 必填，描述可空；数量默认 1，只接受正整数。 +- 商品总预算为空表示不设置上限；填写时表示当前任务全部数量的商品金额上限。 +- 图片类型、大小或解码失败时在图片控件旁提示。 +- 上传成功但创建失败时重用已上传 asset，不重复上传。 +- 网络状态不确定时使用幂等键查询结果，不直接再创建。 +- 离开含未提交内容的表单时提示确认。 + +**可访问性与小屏** + +- 字段错误使用文本说明，不只使用颜色。 +- 图片选择有可访问名称；预览提供来源文件名。 +- 小屏下表单单列，提交按钮不遮挡最后一个字段。 + +## IX-003 查看任务与证据 + +- 页面：`/tasks`、`/tasks/{id}` +- 角色：采购管理员 +- 服务依赖：任务列表、详情、取消和资产读取 API。 +- 关联原型：[任务列表](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/admin-task-list.html)、 + [任务详情](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/admin-task-detail.html)（T-202）。 + +**正常路径** + +1. 列表按最近创建时间展示编号、标题、状态、设备和更新时间。 +2. 进入详情查看原始输入、状态时间线、AI 派生结果、候选和证据。 +3. 仅 `PENDING`/允许状态展示取消命令，取消前二次确认。 + +**状态与异常** + +- 加载：保留页面框架和筛选条件，显示明确进度。 +- 空状态：说明还没有任务并提供“新建任务”入口。 +- 失败：保留上一次内容但标明可能过期，提供重试。 +- 权限不足/不存在：分别处理，但都不泄露任务内容。 +- 截图加载失败：显示占位和重试，不影响其他证据查看。 +- `SUCCEEDED` 详情必须醒目展示“验证完成，未提交订单”。 + +**可访问性** + +- 状态同时使用文字，不只用颜色。 +- 时间线使用有序列表语义；图片有描述性替代文本。 +- 列表在窄屏转换为可扫描行，不使用水平溢出遮挡操作。 + +## IX-004 App 登录与设备绑定 + +- 页面：Android“登录/设备绑定” +- 角色：采购执行员 +- 服务依赖：`POST /api/v1/auth/token`、设备心跳。 +- 关联原型：[App 登录](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/android-login.html)、 + [设备设置](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/android-settings.html)（T-202）。 + +**正常路径** + +1. 用户输入采购账号并确认后端已预授权的当前设备身份。 +2. 成功后令牌存入 Android 安全存储，进入任务页。 +3. App 上报版本和就绪能力，不上传敏感设备内容。 + +**状态与异常** + +- 账号或设备被禁用：解释联系管理员，不反复重试。 +- 未预授权、token 错误或已绑定其他采购员的设备不能在 App 中“重新登记”，联系 + 管理员重新预置。 +- 网络错误：保留非敏感账号字段，密码清空。 +- 会话恢复失败：退出到登录页；活跃任务先查询服务端再决定状态。 +- 退出登录：有运行任务时禁止直接退出，先安全停止。T-204 只实现服务端 token + 签发和验证；本地清除与服务端撤销接入属于 T-206。 + +**可访问性** + +- 支持系统字体缩放；输入与错误不重叠。 +- 软键盘不遮挡提交按钮，返回键不会静默丢失运行状态。 + +## IX-005 手动获取任务 + +- 页面：Android“任务” +- 角色：采购执行员 +- 服务依赖：设备预检、`POST /api/v1/tasks/claim-next` +- 关联原型：[任务主页](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/android-task-home.html)、 + [任务预览](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/android-task-preview.html)、 + [设备设置](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/android-settings.html)（T-202）。 + +**正常路径** + +1. 页面显示无障碍、拼多多、网络和当前任务的就绪状态。 +2. 全部就绪时“获取任务”可用；点击后立即禁用防重复。 +3. 成功后展示任务预览和“开始采购”，此时状态为 `CLAIMED`。 + +**状态与异常** + +- 无任务：显示安静的空状态和手动刷新，不循环弹错。 +- 权限缺失：提供打开对应系统设置的命令。 +- 已有任务：显示“继续任务”，不再领取。 +- 请求超时：保留请求前已安全保存的 claim token/幂等 key，先用同一请求重放并通过 + heartbeat 对比服务端活跃任务，再允许生成新请求。 +- 租约到期：预览页提示任务已释放，返回任务页。 + +**可访问性** + +- 就绪状态使用图标加文字；系统设置命令有明确名称。 +- 主要控件满足 Android 最小触控区域，加载不改变控件尺寸。 + +## IX-006 执行采购任务 + +- 页面：Android“任务执行”及拼多多前台 +- 角色：采购执行员 +- 服务依赖：start、heartbeat、App 本地 AI、event API 和 Android 自动化。 +- 关联原型：[任务预览](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/android-task-preview.html)、 + [任务执行](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/android-task-running.html)（T-202）。 + +**正常路径** + +1. 用户检查原始需求并点击“开始采购”。 +2. App 启动前台服务，进入预检并显示当前步骤。 +3. 解析需求，打开拼多多，搜索并检查最多 5 个候选。 +4. 每一步上报事件；找到结果后进入 `WAITING_CONFIRMATION`。 + +**状态与异常** + +- 运行中禁止第二次开始；持续通知提供“返回任务”和“停止”。 +- App 切换到拼多多时，通知是回到执行页的稳定入口。 +- 用户请求停止后进入“正在安全停止”，不立即在动作中间销毁状态。 +- 进程重启时查询任务和 execution；无法证明可安全恢复则标记失败。 +- 验证码、风控、登录、支付和未知页面立即停止，不展示“自动继续”。 +- AI 超时最多按配置重试；输出无效或低置信度转人工。 +- 候选商品价乘以任务数量达到总预算上限校验失败，或运费/优惠导致总价无法确认时， + 不能进入接受状态。 + +**可访问性与反馈** + +- 当前步骤使用文字和进度列表，不显示虚假百分比。 +- 错误、暂停和等待人工使用不同语义，不只依赖颜色。 +- 通知操作名称明确；动态更新通过适度的 live region/无障碍播报。 + +## IX-007 人工确认候选 + +- 页面：Android“候选确认” +- 角色：采购执行员 +- 服务依赖：`POST /api/v1/tasks/{id}/complete` +- 关联原型：[候选确认](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/android-candidate-confirm.html)、 + [任务结果](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/android-task-result.html)（T-202）。 + +**正常路径** + +1. 展示原始需求、候选标题/价格、匹配项、缺失项和证据截图。 +2. 用户选择“接受候选”“拒绝候选”或“需人工处理”。 +3. 每种选择要求确认并填写简短人工原因；这满足 T-207 第一版审计，不冒充结构化 + 优化标签。 +4. 结果幂等回传，页面显示“验证完成，未提交订单”。 + +**状态与异常** + +- 没有候选时只允许确认“无匹配”或“需人工处理”。 +- 存在商品总价超预算、最终商品金额无法确认或关键属性未知时禁用“接受候选”并 + 说明原因。 +- 回传超时：保留选择和原因，查询最终状态后再重试。 +- 返回键不能恢复自动点击；等待确认一旦到达就是硬停止点。 +- 所有结果都写入 `order_submitted=false`。 + +**可访问性** + +- 候选信息按标题、价格、匹配和风险分组。 +- 确认对话框默认焦点在取消；破坏性/拒绝动作不能与接受动作混淆。 + +## IX-008 失败、取消和恢复 + +- 页面：Android“任务执行/结果”、Web 任务详情 +- 角色：采购执行员、采购管理员 +- 服务依赖：fail、event、asset API。 +- 关联原型：[管理任务详情](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/admin-task-detail.html)、 + [App 任务执行](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/android-task-running.html)、 + [App 任务结果](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/docs/design/android-task-result.html)（T-202）。 + +**正常路径** + +1. 系统停止动作，保存失败步骤和错误类别。 +2. App 显示发生了什么、是否已停止和建议下一步。 +3. 证据上传成功后，管理详情显示相同结论。 + +**状态与异常** + +- 上传失败：本地加密/受控保留待传证据，显示“结果待同步”。 +- 取消：说明不会自动恢复；服务端终态后清理前台服务。 +- 可恢复设备问题：只提供“修复后重新领取/新建尝试”，不原地猜测继续。 +- 安全错误 `SAFETY_*` 不允许自动重试。 +- 清理本地证据仅在服务端确认接收或超过明确保留策略后发生。 + +**验收证据** + +- 每类错误至少有一个自动化或 fake 测试。 +- 验证码/未知页/支付边界至少在受控环境各验证一次安全停止。 + +## IX-009 结构化候选理由 + +- 页面：Android“候选确认”、管理 Web“任务详情/候选决策”。 +- 角色：采购执行员、采购管理员/优化人员。 +- 前置条件：T-207 第一版流程和 T-208 reason schema 已完成。 +- 服务依赖：已实现的 T-208 幂等 human review API。 + +**正常路径** + +1. 用户选择接受项、逐项拒绝、改选或全部无匹配。 +2. 每个决定至少选择一个结构化理由，并明确一个主要理由；备注默认可选。 +3. 选择“其他”时显示 4-200 字备注输入；没有预算时不显示预算类理由。 +4. 改选时先确认原推荐项拒绝理由，再确认替代项选择理由。 +5. 全部拒绝时逐候选确认；允许勾选多个候选后显式批量应用相同理由。 +6. 提交后显示人工结论、模型判断和系统推荐三个独立区块，不合并文案。 + +**状态与异常** + +- 模型理由可以只读展示，但不得预选为人工理由。 +- 网络失败保留本地草稿和独立幂等 key；查询服务端后决定是否重放。 +- 修改已提交结论时明确提示“创建修订版本”，不能覆盖原记录。 +- 理由码失效或与任务不适用时由服务端拒绝并要求重新选择。 + +**可访问性** + +- 理由使用 checkbox/radio 和明确 label，不依赖颜色；主要理由可用单选控件指定。 +- 批量应用前显示候选数量和标题摘要，默认不选中。 + +## IX-010 App 独立执行与同步 + +- 页面：Android“设备设置”“任务执行”和“结果同步”。 +- 角色：采购执行员。 +- 前置条件：设备已绑定；后台任务已领取。 +- 服务依赖：T-206 有限离线授权；T-207 Keystore provider 配置和加密 outbox。 + +**正常路径** + +1. 设置页选择 `MANUAL_FIRST` 或 `AI_ASSISTED`。AI 模式复用 Roubao 现有 provider、 + model、Base URL 和 Key 配置，Key 默认隐藏。 +2. 开始后台任务时固定本次 execution 的模式及非秘密 provenance；任务 payload 不能 + 改写本地 provider 设置。 +3. 管理后端断开时，执行页显示“离线执行”、服务端授权截止时间和待同步项目数；授权 + 内继续本地 workflow。 +4. 恢复连接后先同步任务归属和取消状态，再按依赖顺序幂等上传事件、证据和终态结果。 + +**状态与异常** + +- 旧明文 Key 迁移失败或 Keystore 不可用：禁用真实 VLM 调用，允许用户显式改用 + `MANUAL_FIRST`，不能静默切换。 +- 远程 provider 非 HTTPS、发生重定向或输出无效：停止 AI 分支并转人工，不影响已有 + outbox 和任务证据。 +- 离线授权剩余 5 分钟时持续显示警告；到期时在安全检查点停止，不提供“继续离线”。 +- 离线期间无法保证即时接收管理取消；恢复连接后收到取消必须先停止再上传。 +- 结果补报失败保留加密本地记录和原幂等 key；不能恢复终态后的自动化。 +- App 可以显示 provider 名称和模型，但不得回显 Key、Authorization 或完整敏感 URL。 + +## IX-011 Admin 候选授权与待付款订单 + +- 页面：管理 Web“任务详情/候选确认”、Android“等待授权/订单执行”。 +- 角色：采购管理员、采购执行员。 +- 服务依赖：T-215 order authorization、T-216 device command、T-217/T-218 + 订单自动化与对账。 + +**正常路径** + +1. 任务进入 `WAITING_CONFIRMATION` 后，Admin 查看原始要求、候选标题/SKU/组合价格、 + 模型理由、candidate key 和详情/规格截图。 +2. Admin 单选一个候选，为接受项和其余拒绝项选择结构化理由，并确认“只创建待付款 + 订单，不授权付款”。 +3. 后端生成不可变 `PENDING_DELIVERY` 授权；设备领取后页面显示投递/执行进度。 +4. Roubao 重新定位商品，复核 SKU/数量/价格后只提交一次，再从订单列表读取订单号 + 和下单时间。 +5. Admin 显示“待人工确认付款”，提供订单号、时间和审计证据；人员切换拼多多付款。 + +**状态与异常** + +- 候选证据不完整、任务版本变化、取消已请求或授权过期时禁用授权。 +- 授权尚未投递时改选会创建修订版本；旧授权显示 `SUPERSEDED`，不能覆盖。 +- 投递后不能静默改选；必须先走设备停止/撤销协议。 +- 商品无法重新定位、SKU/数量/价格不一致、地址/运费/优惠导致金额不确定时停止， + 不提交订单。 +- 页面要求添加地址、最终按钮不是唯一的“提交订单”或出现免密/自动扣款语义时停止。 +- 提交响应超时或页面未知时显示“正在对账”，禁止再次提交；没有唯一新订单时转人工。 +- 页面和 App 都不能提供自动付款按钮。 + +**可访问性** + +- 候选使用带完整 label 的 radio；理由用 select/radio，不依赖颜色或图片顺序。 +- 授权按钮文案包含动作结果，确认对话框默认焦点在取消。 +- 状态更新不改变候选卡和按钮尺寸，错误与待付款提醒可被读屏读取。 + +## 通用交互约束 + +- Web 和 App 的所有提交都防重复，网络超时后以服务端状态为准。 +- 状态名称使用用户可理解中文，同时保留稳定机器状态码。 +- 不在 UI 暴露模型密钥、设备令牌、内部堆栈或文件绝对路径。 +- 字体放大、窄屏、软键盘和系统返回操作下，主要命令和错误不能被遮挡。 +- P0 页面实现前按 [`design/README.md`](/chengma/mroubao/wiki/Design) 生成低保真原型并人工确认。