From 6dcecbdc03d0986961294cc83ace8e242c9b1267 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Sun, 26 Jul 2026 20:16:42 +0800 Subject: [PATCH] docs: defer candidate decision data loop --- docs/00-ai-start-here.md | 2 ++ docs/02-requirements.md | 29 +++++++++++++++++++++++++++ docs/04-architecture.md | 34 ++++++++++++++++++++++++++++++++ docs/05-coding-rules.md | 6 ++++++ docs/06-tasks.md | 3 ++- docs/07-user-stories.md | 28 ++++++++++++++++++++++++-- docs/08-interaction-checklist.md | 32 +++++++++++++++++++++++++++++- docs/api.md | 10 ++++++++++ docs/current-state.md | 7 +++++-- docs/routes.md | 2 +- progress.md | 8 ++++++++ 11 files changed, 154 insertions(+), 7 deletions(-) diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index 77de6cb..5b2411d 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -56,6 +56,8 @@ 验证。T-201 后端骨架、T-202 P0 原型、T-203 任务 API/管理 Web、T-204 最小鉴权 和 T-205 原子领取/租约状态机均已完成。下一步按编号开始 T-206，把 Android `HttpTaskSource`、前台服务和已确认的任务页面接到设备 API。 +候选优化数据集已经登记为 T-208；不得跳过 T-206/T-207 的第一版端到端闭环，提前 +建设报表、训练管线或外部商品抓取。 严格按以下顺序推进： diff --git a/docs/02-requirements.md b/docs/02-requirements.md index 0d95f7a..ae3987a 100644 --- a/docs/02-requirements.md +++ b/docs/02-requirements.md @@ -37,6 +37,7 @@ | 功能 | 说明 | 阶段 | | --- | --- | --- | +| F-008 候选决策数据闭环 | 保存每次搜索实际曝光的最多 5 个候选、模型评估、系统推荐和人工理由，为离线评估与优化提供可信样本。 | P1，T-208；不阻塞第一版流程 | | 完整 RBAC | 采购管理员、执行员、审核员和系统管理员的细粒度权限。 | V2 | | 多设备容量调度 | 在当前原子领取/租约基础上增加优先级、容量、运营监控和跨实例调度。 | V2 | | 后台通知 | WebSocket/厂商推送只通知有任务，App 仍通过 claim 领取。 | V2 | @@ -44,6 +45,32 @@ | 多平台比价 | 淘宝、1688、京东等平台。 | V3 | | 支付自动化 | 不在当前规划内，除非另行完成资金和合规评审。 | 未规划 | +### F-008 候选决策数据闭环（后置） + +T-206/T-207 先跑通领取、执行、候选/证据和最小结果回传；T-208 再实现可用于优化的 +完整数据闭环。不能为了建设未来训练数据阻塞第一版端到端流程，但 20 条真实任务试验 +开始前必须完成 T-208，避免试验结束后才发现缺少曝光和人工标签。 + +1. 每次 search run 保存需求快照、精确搜索词、App/拼多多版本、采集时间以及最多 + 5 个实际曝光候选的原始 ordinal。该集合只是特定账号、地区、时间和平台排序下的 + 可见结果，不得宣称为全平台 Top 5。 +2. 每个候选保存可观测标题、价格、规格文本、可选平台商品 ID/规范化链接、截图资产 + 和采集完整性。平台链接和图片链接可能短期有效，只是辅助字段，不能替代受控截图。 +3. 候选观测、模型预测、本地推荐规则和人工结论必须分开保存。模型理由不能自动复制 + 为人工理由，也不能把模型预测当作真实标签。 +4. 人工接受、拒绝、改选和全部无匹配都必须提供理由。第一版允许简短人工说明； + T-208 改为至少一个结构化理由码、一个主要理由和可选备注，选择 `OTHER` 时备注 + 必填。无预算任务不能使用预算匹配或超预算理由。 +5. 拒绝推荐项并改选时，同时记录原推荐项的拒绝理由和替代项的选择理由；全部拒绝时 + 每个候选都要有拒绝理由。允许人员明确选择候选后批量应用同一理由，禁止静默预填 + 模型结论。 +6. 人工修正使用追加版本和 `supersedes` 关系，不覆盖历史；理由 schema、模型、 + prompt、阈值和推荐策略全部版本化。 +7. 后端不得根据 Android 提交的任意 URL 抓取内容。候选截图由 App 有界上传，经真实 + 解码、大小/像素/哈希检查和脱敏后保存；外链只做不可执行文本并清除追踪参数。 +8. 图片保留期限、平台条款、训练用途和人工备注隐私必须在 T-302 前固定。没有人工 + 结论的数据只能用于运行审计，不能计入模型准确率。 + ## 五、业务规则 1. 标题、SKU 和图片必填，描述可为空。 @@ -143,6 +170,8 @@ T-004 已固定首版规则：推荐私有目录为被 Git 忽略的 `private-fi - 不发生重复领取、重复执行导致的不可逆操作或订单提交。 - 每条失败任务都能定位到具体步骤和错误类别。 - 记录每条任务的耗时、人工介入点和候选接受结果，用于决定是否进入 V2。 +- 同时记录实际曝光候选、模型预测、系统推荐和人工结构化理由；准确率以人工结论为 + 标签，不能用模型自己的判断验证模型。 这些比例是进入下一阶段的验证门槛，不是正式生产 SLA。 diff --git a/docs/04-architecture.md b/docs/04-architecture.md index 8368c06..b6ac87f 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -446,6 +446,40 @@ T-205 的最小 execution 表中提前伪造。 - 任务参考图上传可接受 JPEG/PNG/WebP，但后端必须先真实解码、限制字节与像素，再 统一规范化为匿名 JPEG；未来 Android 读取的资产不能依赖原始扩展名或声明 MIME。 +### 后置候选决策数据集（T-208） + +T-207 先完成候选、事件、截图和最小结果回传。T-208 在 `task_executions` 下增加 +独立、不可变的数据层，不把整批候选塞进 `task_events`、`purchase_tasks` JSON 或 +一段不可查询的自由文本： + +| 表 | 主要内容 | +| --- | --- | +| `candidate_search_runs` | execution、需求快照 hash、搜索词、App/拼多多版本、开始/结束时间 | +| `candidate_observations` | run、ordinal、可选平台商品 ID/规范化 URL、可见标题/规格/价格、采集状态和截图 asset | +| `model_runs` | provider/model、prompt/schema/阈值版本、耗时、token/成本和请求/结果 hash | +| `candidate_evaluations` | observation/model run、decision、score/confidence、matched/missing/rejection reasons | +| `candidate_recommendations` | run、推荐 observation、conclusion、确定性策略版本和简短理由 | +| `candidate_human_reviews` | run、最终 outcome、选择项、actor、理由 schema、时间和可空 `supersedes_review_id` | +| `candidate_human_review_items` | review 下每个候选的 `ACCEPT/REJECT`、主要理由和可选备注 | +| `candidate_human_review_reasons` | review item 的多值结构化理由码 | + +四层数据语义不可混用： + +- observation 是 App 当时实际看到的页面事实。 +- prediction 是特定模型版本的输出。 +- recommendation 是本地确定性规则的结果。 +- human label 是采购人员明确提交的结论，才可作为离线准确率标签。 + +现有 `assets.purpose` 在 T-207/T-208 migration 中按实际需要扩展 +`CANDIDATE_SCREENSHOT`、`CANDIDATE_IMAGE` 和 `EXECUTION_EVIDENCE`。第三方商品或 +图片 URL 只保存为长度受限、规范化的辅助观测值；后端不得盲目请求该 URL。主要证据 +必须是 App 上传后由 assetstore 校验、脱敏和受鉴权访问的时间点快照。 + +人工理由使用版本化 allowlist。接受或拒绝至少有一个理由且指定主要理由； +`OTHER` 才要求 4-200 字备注。拒绝推荐后改选必须同时产生一条原推荐项负标签和一条 +替代项正标签；全部无匹配时每个曝光候选都有负标签。人工修正追加新 review 并引用 +旧 review，不能覆盖历史。模型理由可以展示给人员参考，但不能自动成为人工理由。 + ## 六、API 和并发边界 - 合约以 [`api.md`](api.md) 为准。 diff --git a/docs/05-coding-rules.md b/docs/05-coding-rules.md index fc88185..f8ffd2b 100644 --- a/docs/05-coding-rules.md +++ b/docs/05-coding-rules.md @@ -99,6 +99,12 @@ - 通用错误使用稳定 code 和可读 message；内部堆栈只进受控日志。 - 文件访问通过鉴权接口，防止路径遍历和猜测 URL；App 参考图读取必须重新校验当前 task/user/device/generation/token/租约，不能只凭 asset UUID 授权。 +- T-208 候选数据必须分离 observation、model prediction、deterministic + recommendation 和 human label；模型理由不得预填或复制为人工标签。 +- 人工结论使用版本化结构化 reason code；接受/拒绝至少一个理由，`OTHER` 才要求 + 受限备注。人工修正只追加并引用被替代版本，不能覆盖历史。 +- 第三方商品/图片 URL 只作为长度受限的不可执行观测字段；后端不得根据客户端 URL + 发起任意网络请求。候选图片使用鉴权、解码、大小/像素/哈希和脱敏受控上传。 - Go 命令固定 `GOTOOLCHAIN=local`；`go.mod` 不得出现更高 Go 版本或未固定的 `@latest` 依赖。 - 后端不得自动加载 `.env`、默认开启 CORS、使用包级数据库单例，或在库、handler、 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 92dacc4..54d72f9 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -40,6 +40,7 @@ | T-205 | 实现原子 claim、租约和状态机 | T-203、T-204 | 并发领取不重复；非法迁移、过期租约和错误设备被拒绝 | | T-206 | App 接入手动领取和执行进度 | T-202、T-205 | 用户点击后领取一条；前台服务显示步骤；取消安全停止 | | T-207 | 接入候选、事件和截图回传 | T-206 | 幂等回传；管理详情可查看；资源访问受鉴权保护 | +| T-208 | 建立候选决策数据与人工理由闭环 | T-207 | 观测/预测/推荐/人工标签分离；逐候选结构化理由；截图受控留存；不阻塞第一版流程 | ## Phase 3：端到端验证 @@ -47,7 +48,7 @@ | --- | --- | --- | --- | | T-301 | 完成 P0 UI 实现和交互验收 | T-203、T-206 | Web 和 App 的 IX 默认/加载/错误/中断状态均有验证证据 | | T-302 | 建立脱敏、清理和审计策略 | T-207 | 日志/截图不泄密；文件保留和清理可配置；事件可追溯 | -| T-303 | 运行 20 条真实采购任务试验 | T-301、T-302 | 指标按需求统计；失败分类完整；无订单提交 | +| T-303 | 运行 20 条真实采购任务试验 | T-301、T-302、T-208 | 指标按人工标签统计；曝光候选和理由完整；失败分类完整；无订单提交 | | T-304 | 可行性评审和 V2 决策 | T-303 | 对照 80%/70% 门槛给出继续、修正或停止结论 | ## Phase 4：交付验证版 diff --git a/docs/07-user-stories.md b/docs/07-user-stories.md index e5249ac..3c3f489 100644 --- a/docs/07-user-stories.md +++ b/docs/07-user-stories.md @@ -14,6 +14,7 @@ | 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-008 | 积累可信的候选决策样本 | P1 | 采购执行员、优化人员 | 用真实曝光和人工理由评估并改进模型 | F-008 | IX-009 | 已定，T-208 后置 | ## US-001 创建清晰的采购任务 @@ -157,9 +158,32 @@ 3. 会话过期时保留非敏感界面上下文并要求重新登录。 4. 管理员会话不能替代设备令牌，设备令牌也不能访问管理页面。 +## US-008 积累可信的候选决策样本 + +- 关联页面：Android“候选确认”、管理 Web 任务详情。 +- 前置条件：T-206/T-207 第一版领取、执行和结果回传已经跑通。 + +作为采购执行员和后续优化人员，我希望保存每次实际看到的候选、模型判断、系统推荐 +及人员选择/拒绝理由，从而可以区分模型问题、搜索排序问题和页面证据不足，而不是用 +模型自己的结论给模型打分。 + +**范围** + +- 包含：最多 5 个曝光候选、截图、可见标题/规格/价格、可选商品链接、模型 provenance、 + 逐候选评估、推荐策略版本、结构化人工理由和修正审计。 +- 不包含：全站商品抓取、训练管线、自动下载任意外链、平台级 Top 5 声明。 + +**验收场景** + +1. 同一次 execution 可以还原当时的搜索词、候选原始顺序、截图和各层判断。 +2. 接受、拒绝、改选和全部无匹配都有合法人工理由；模型理由不会自动成为人工标签。 +3. 拒绝推荐并改选时，原推荐项有负标签，替代项有正标签。 +4. 人工修正保留旧版本、actor 和时间；离线指标只使用当前有效人工 review。 +5. 外链失效后，授权人员仍能读取保留期内的受控截图证据。 + ## 待确认 - 密码重置流程后置；T-204 使用本地 `authctl` 显式创建种子 ADMIN/BUYER 和预授权 设备，不提供管理 UI 或客户端自助登记。 -- 谁负责确认测试任务、如何标注“候选可接受”的统一口径。 -- 拒绝候选是否允许创建新任务，当前默认只记录结果。 +- T-208 前固定谁负责确认测试任务、理由码 allowlist 和“候选可接受”的统一口径。 +- 拒绝候选是否允许创建新任务仍待定；当前默认只记录结果和理由。 diff --git a/docs/08-interaction-checklist.md b/docs/08-interaction-checklist.md index 3cc63d1..dc4dbcd 100644 --- a/docs/08-interaction-checklist.md +++ b/docs/08-interaction-checklist.md @@ -15,6 +15,7 @@ | 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-001 管理 Web 登录 @@ -203,7 +204,8 @@ 1. 展示原始需求、候选标题/价格、匹配项、缺失项和证据截图。 2. 用户选择“接受候选”“拒绝候选”或“需人工处理”。 -3. 每种选择要求确认，必要时填写简短原因。 +3. 每种选择要求确认并填写简短人工原因；这满足 T-207 第一版审计，不冒充结构化 + 优化标签。 4. 结果幂等回传，页面显示“验证完成，未提交订单”。 **状态与异常** @@ -248,6 +250,34 @@ - 每类错误至少有一个自动化或 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，不依赖颜色；主要理由可用单选控件指定。 +- 批量应用前显示候选数量和标题摘要，默认不选中。 + ## 通用交互约束 - Web 和 App 的所有提交都防重复，网络超时后以服务端状态为准。 diff --git a/docs/api.md b/docs/api.md index 0d4f357..f177a6d 100644 --- a/docs/api.md +++ b/docs/api.md @@ -539,6 +539,16 @@ execution、清除 claim 秘密并追加带用户/设备 actor 的事件。同 k 后端对 MVP 强制 `order_submitted=false`，成功后任务进入 `SUCCEEDED`；这里的成功表示 验证工作流正常结束，业务结果由 `outcome` 表达。 +T-207 第一版要求 `operator_reason` 为人员输入的简短审计说明，但不把它当作可训练 +标签。T-208 在第一版链路跑通后扩展为版本化 `human_review` 合约，至少包含 +`reason_schema_version`、可空选择候选、逐候选 `ACCEPT/REJECT`、主要理由码、 +附加理由码和受限备注。改选必须同时提交原推荐项拒绝理由与替代项选择理由；全部 +无匹配必须覆盖每个曝光候选。具体 endpoint 和 schema 在领取 T-208 时冻结。 + +模型评估理由、确定性推荐理由和 `human_review` 分开保存。服务端不接受客户端把 +模型理由标记为已由人员确认；第三方商品/图片 URL 只作为受限观测字段，不触发后端 +下载，主要证据仍通过鉴权 asset API 上传。 + ### `POST /api/v1/tasks/{task_id}/fail` ```json diff --git a/docs/current-state.md b/docs/current-state.md index 020ee0f..6dc2f66 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -6,8 +6,8 @@ - 日期：2026-07-26 - 阶段：T-205 原子领取、租约和状态机完成，下一步 T-206 -- Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-203 - 均已纳入 Git 历史；T-204 已提交，T-205 与本文同次提交 +- Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-205 + 均已纳入 Git 历史；T-205 提交为 `ce875af` - 生产代码：`android-buyer/` 已接入 Roubao Android 源码 - Android：固定 `main@c8a6d7f03422eb01744b01f3ee77bf7757741f7e`；MIT 许可证已保留 - 后端：Go 1.23.0 + Gin 1.11.0 + SQLite + Goose 3.26.0；已实现图片/任务业务、 @@ -41,6 +41,8 @@ - VLM：需求提取与候选评估均使用严格 schema、0.75 阈值、受控证据源、安全端点和 单次调用边界；候选最多 5 个并按 ordinal 串行评估，本地产生建议并停在人工确认， SKU/数量由本地原值回填，预算保持空，订单提交状态固定为 false +- 后置数据闭环：已登记 T-208，在第一版 T-206/T-207 跑通后分离保存候选观测、 + 模型预测、确定性推荐和人工标签；人工接受/拒绝使用结构化理由，20 条试验依赖它 - 测试设备：OnePlus PKG110，Android 16/API 36；肉包 `1.4.2 (7)`；拼多多 `8.17.0 (81700)` - 设备就绪：肉包采购无障碍已启用并连接；拼多多首页、搜索输入、固定词结果页、 @@ -85,6 +87,7 @@ - 已完成：T-001 至 T-004、T-101 至 T-104、T-201 至 T-205。 - 正在进行：无。 - 下一个可领取任务：T-206 App 接入手动领取和执行进度。 +- 后置任务：T-208 候选决策数据与人工理由闭环；不得跳过 T-206/T-207 提前实现。 ## 当前可运行内容 diff --git a/docs/routes.md b/docs/routes.md index fa46c2a..38109b0 100644 --- a/docs/routes.md +++ b/docs/routes.md @@ -26,7 +26,7 @@ Android 导航名称是逻辑目的地，具体 Compose/Fragment 形式待接入 | `tasks` | 任务主页 | 就绪检查、获取或继续任务 | US-003 | IX-005 | | `task/{id}/preview` | 任务预览 | 检查原始要求并开始 | US-003、US-004 | IX-005、IX-006 | | `task/{id}/running` | 任务执行 | 显示步骤、返回拼多多、安全停止 | US-004、US-006 | IX-006、IX-008 | -| `task/{id}/confirm` | 候选确认 | 接受、拒绝、无匹配或转人工 | US-005 | IX-007 | +| `task/{id}/confirm` | 候选确认 | 接受、拒绝、无匹配或转人工；T-208 增加逐候选结构化理由 | US-005、US-008 | IX-007、IX-009 | | `task/{id}/result` | 任务结果 | 查看终态和同步状态 | US-002、US-006 | IX-007、IX-008 | | `settings` | 设备设置 | 查看权限、版本、后端和模型连接状态 | US-003、US-007 | IX-004、IX-005 | diff --git a/progress.md b/progress.md index e3fa9cf..b182ccb 100644 --- a/progress.md +++ b/progress.md @@ -146,3 +146,11 @@ App 取消确认。 - 影响：后端已具备 Android 手动领取和执行进度所需的稳定协议；T-206 可接入 HTTP TaskSource、凭证/claim token 安全存储和前台执行界面。 + +## 2026-07-26 候选优化数据闭环后置 + +- 类型：范围决策 +- 内容：新增 T-208，在 T-206/T-207 第一版流程完成后保存最多 5 个候选观测、 + 模型预测、确定性推荐、受控截图和逐候选人工理由；四层数据不得混用。 +- 影响：第一版领取与结果回传不被训练数据建设阻塞；20 条真实任务试验开始前完成 + T-208，人工接受、拒绝、改选和无匹配才形成可信优化标签。