7.1 KiB
7.1 KiB
id, title, phase, deps, status, created, context_ref, work_branch, write_paths
| id | title | phase | deps | status | created | context_ref | work_branch | write_paths | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| T-208 | 候选决策数据与结构化人工理由闭环 | 2 |
|
DOING | 2026-07-28 | 4c3b962 |
null |
|
问题 / 背景
T-207 已能回传候选批次、模型评估、本地推荐和一段 operator_reason，但后端仍把候选
主体保存在不可查询 JSON 中，人工说明也不是可用于离线评估的标签。AI 模式还会在
回传前过滤模型拒绝项，导致无法还原同一次图片搜索实际曝光的候选集合，也无法区分
召回、模型、推荐策略和人工判断各自的问题。
本任务在 20 条真实采购试验前建立可信的数据闭环。它不建设训练管线、外部抓取或
报表，也不改变候选阶段 order_submitted=false 的安全边界。
关联需求与交互
- 功能：F-008。
- 用户故事：US-008。
- 交互：IX-009。
- 依赖：沿用 T-207 的 execution、受控 evidence、加密 outbox 和结果终态；沿用 T-213 的规格选择摘要与组合价格证据。
冻结合约
候选数据层
- 每个 execution 第一版只允许一个候选 search run。
execution_id同时作为 run identity，保存任务内容 hash、精确搜索审计值、App/Android/拼多多版本、开始/接收 时间和采集完整性。 POST /api/v1/tasks/{task_id}/candidates继续作为 App 的批量入口，但候选数组改为 实际检查的原始连续 ordinal0..5项，不再只上传模型通过项。每项 observation 保存可见标题、规格、价格、受限外链和已鉴权 evidence；后端绝不请求外链。- AI 模式逐 observation 保存 model evaluation。确定性 recommendation 可指向任一 原始 ordinal，但目标必须满足本地颜色/尺码硬约束和当前阈值；不得通过重排改写 observation ordinal。MANUAL_FIRST 没有 model run/evaluation/recommendation。
- 后端在保存候选批次的同一事务内写入
candidate_search_runs、candidate_observations、model_runs、candidate_evaluations和candidate_recommendations；旧 JSON 只作为兼容审计 副本，不能继续作为新查询的唯一来源。
人工 review API
新增设备鉴权、claim-scoped、幂等的
POST /api/v1/tasks/{task_id}/human-reviews：
{
"execution_id": "uuid",
"claim_generation": 1,
"task_content_sha256": "64-char-lowercase-hex",
"reason_schema_version": 1,
"outcome": "CANDIDATE_ACCEPTED",
"selected_candidate_ordinal": 2,
"primary_reason_code": "SELECTED_BEST_MATCH",
"note": "",
"supersedes_review_id": null,
"items": [
{
"candidate_ordinal": 1,
"label": "REJECT",
"primary_reason_code": "NOT_BEST_MATCH",
"reason_codes": ["NOT_BEST_MATCH"],
"note": ""
},
{
"candidate_ordinal": 2,
"label": "ACCEPT",
"primary_reason_code": "SKU_MATCH",
"reason_codes": ["SKU_MATCH", "IMAGE_MATCH"],
"note": ""
}
]
}
- review 主理由：
SELECTED_BEST_MATCH、NO_ACCEPTABLE_CANDIDATE、INSUFFICIENT_EVIDENCE、OTHER。 - ACCEPT 理由：
SKU_MATCH、IMAGE_MATCH、PRICE_ACCEPTABLE、EVIDENCE_SUFFICIENT、OTHER。 - REJECT 理由：
SKU_MISMATCH、IMAGE_MISMATCH、PRICE_TOO_HIGH、OUT_OF_STOCK、EVIDENCE_INSUFFICIENT、NOT_BEST_MATCH、OTHER。 OTHER的对应备注必须为 4-200 个字符；其他备注可空，非空时同样最多 200 个字符。- 无预算任务拒绝
PRICE_ACCEPTABLE和PRICE_TOO_HIGH。 - 非空候选批次的 review 必须按 ordinal 恰好覆盖每个 observation。接受时恰好一个
ACCEPT 且等于
selected_candidate_ordinal，其余全部 REJECT；拒绝、无匹配或转 人工时全部为 REJECT。零候选只允许NO_MATCH/MANUAL_REQUIRED和空 items。 - 修订必须引用同一 execution 当前最新 review；服务端追加新版本并建立
supersedes_review_id，不得更新或删除旧版本。
App 与管理端
- App 人工确认不再使用自由文本作为唯一输入。人员必须显式选择候选、接受主理由和 其余候选拒绝主理由，或选择全部拒绝理由；模型理由只读且不会预选人工理由。
- 第一版 UI 允许人员明确把同一拒绝理由批量应用到所有未选候选，但提交 payload 仍展开成逐 observation item。
- App 先把 HUMAN_REVIEW 放入加密 outbox，再加入兼容的 COMPLETE；网络失败保留 同一 idempotency key 和草稿顺序。
- Admin 任务详情按 observation、model prediction、deterministic recommendation、 human review 四个独立区块显示，修订历史按版本可见；受控截图继续走鉴权接口。
验收要点
- migration
up/down/up可重复；有 review 数据时破坏性 down 明确失败。 - 最多 5 个原始曝光 observation 按原 ordinal 可查询，模型拒绝项不会丢失。
- observation、model evaluation、recommendation 和 human label 分表且引用一致。
- human review API 校验理由 allowlist、标签兼容、预算适用性、全候选覆盖、唯一 接受项、幂等重放和追加式 supersedes。
- App 支持选择推荐项、改选、全部拒绝和零候选；每种路径都产生结构化逐候选理由。
- 模型理由不会预填人工理由，旧
operator_reason只保留兼容审计含义。 - Admin/API 能读取当前 review 和历史版本，外链不会触发任何服务端网络请求。
- Android/Go 单元测试、race、migration、Debug/Release 构建和根验证通过。
边界
- 不实现模型训练、指标报表、数据导出、自动标注或跨任务聚合分析。
- 不抓取商品页、图片 URL 或平台全量结果，不宣称为全平台 Top 5。
- 不在本任务创建订单、加入购物车或支付；Admin 下单授权属于后续独立任务。
- 不把 VLM Key、Authorization、完整 endpoint、供应商原始响应或模型理由写成人工 标签。
执行记录
- 2026-07-28：T-213 真机验收提交
4c3b962后领取。审计确认现有execution_candidate_batches/execution_outcomes只能提供 JSON 审计副本和自由 文本说明，AI 模式还会过滤拒绝候选；因此冻结以上归一化数据层和结构化 review 合约后再开始实现。