cmbuyer/docs/tasks/T-210.md

id, title, phase, deps, status, created, vikunja_task_id, context_ref, work_branch, needs_device, needs_human_review, write_paths

id	title	phase	deps	status	created	vikunja_task_id	context_ref	work_branch	needs_device	needs_human_review	write_paths
T-210	扩展闸门二与闸门三证据类型	2	T-107 T-204 T-302	TODO	2026-08-04	43	cd47d0c	task/t-210-gate-evidence-kinds	false	false	docs/tasks/T-210.md admin/migrations/00006_gate_evidence_kinds.sql admin/internal/migrations/migrations_test.go admin/internal/evidence/** admin/internal/storage/evidence/** admin/internal/server/evidence_test.go docs/api.md docs/04-architecture.md docs/06-tasks.md

问题 / 背景

T-204 当前数据库和 API 只允许 SKU_PANEL_GATE_1；T-107 将以真机证据批准闸门二规格面板和闸门三确认页截图。T-210 在不改变上传身份、大小、隐私或幂等边界的前提下，安全扩展两个固定证据类型，为 T-305 提供完整三闸门审计。

关联需求与交互

• 功能：F-007、F-013、F-017 的证据部分。
• 依赖：T-107、T-204、T-302。
• 后续消费者：T-205、T-305、T-208。
• 只修改采购服务证据 schema/validation，不修改 client 或页面判据。

方案

1. 新增 00006 迁移，把 evidence kind 白名单精确扩展为 SKU_PANEL_GATE_1、SKU_PANEL_GATE_2、ORDER_CONFIRM_GATE_3；保留所有旧 gate1 资产和审计身份，不把 kind 变成任意字符串。
2. SQLite 表重建/约束迁移必须在事务内保持 foreign_keys=ON，迁移后运行 foreign_key_check；保留 T-302 claim ownership trigger、唯一键、索引、已有外键和所有列约束。不得通过关闭 FK 或丢弃历史行绕过。
3. 降级只在没有 gate2/gate3 资产时允许；存在新事实必须原子拒绝，不能静默把新 kind 改名为 gate1 或删除记录。
4. 领域白名单、multipart handler、store 与返回 DTO 只增加这两个常量；设备认证仍先于 Content-Type/body，首次写入仍要求当前设备未关闭 claim，closed claim 只允许旧 key replay。
5. 三个 kind 均只接受单个显式 INTERNAL_RAW PNG，沿用 10 MiB、像素、SHA-256、原子文件发布、固定字段和不上传 XML/path 的边界。
6. kind 与页面事实固定映射：Gate1/Gate2 只能规格面板，Gate3 只能订单确认页。服务端不解析图片或推断页面；真实性由 T-107/T-305 事件顺序和人工验收保证。
7. 不增加支付页、待付款页、任意截图或自定义 kind，不新增页面自动化、事件写入、围栏、结果或付款能力。

验收要点

• 迁移覆盖升级/重开/保留 gate1、全部约束/trigger/index/FK、错 kind、down 无事实成功和有新事实原子拒绝。
• HTTP/store 覆盖三种精确 kind、大小写/相似/未知拒绝、设备 A/B 隔离、closed claim replay/new key 拒绝。
• 原始 PNG 可含页面显示地址/手机号；仍不解析为字段，不接收 XML/manifest/path/支付页/支付凭据。
• 静态检查没有 client/PDD、event/fail/fence/result、提交订单或付款能力。
• Go full/race/vet/build、完整 init、上下文、Vikunja export 与 diff-check 通过。

执行记录

2026-08-04T14:06:35Z · ila

2026-08-04 从 T-305 拆出服务端证据类型扩展：只在 T-107 取证批准后增加固定 Gate2/Gate3 kind，保留 Gate1 与 T-302 ownership/replay 边界；不让 T-306 或 dry-run 临时改 schema。

2026-08-04T14:39:05Z · ila

2026-08-04 依赖审计反转 T-210/T-205：三种 evidence kind 必须先进入真实 SQLite schema，T-205 才能对 Gate1/2/3 成功事件做真实正向与错 kind/跨归属测试。T-210 改为 00006，依赖 T-107/T-204/T-302。

2026-08-06T02:58:55Z · ila

2026-08-06T02:58:54.857Z · Codex 2026-08-06 T-106 真机结论覆盖旧“Gate3=独立订单确认页”前提。T-210 必须把 Gate3 evidence kind 固定为合并式最终提交面板，并用受保护 migration 把历史 confirm_amount/confirm_page_amount 迁移为 gate3_submit_amount；Gate3 资产记录最终控件结构化金额，必须与 Gate2 顶部总额严格相等。迁移未完成不得让 T-205/T-208 消费或建立围栏。

边界

• 2026-08-06 起 Gate3 kind 固定映射到合并式最终提交面板，不再映射独立订单确认页；本任务必须用 受保护 migration 把旧 confirm_amount / confirm_page_amount 迁移为 gate3_submit_amount。 Gate3 金额只来自结构化最终控件，必须严格等于 Gate2 顶部总额且不得回流 Gate1/Gate2。

• 证据类型只允许精确的 SKU_PANEL_GATE_1、SKU_PANEL_GATE_2、 ORDER_CONFIRM_GATE_3；不得接受自由 kind、别名、大小写变体或客户端自定义值。

• 升级必须保留既有闸门一 asset、哈希、attempt/task/authorization/generation 归属、append-only 约束与 T-302 claim 所有权触发器。迁移期间保持 foreign_keys=ON，完成后必须通过 foreign_key_check；不得删除、重建为空或改写既有证据事实。

• 降级仅在库中不存在新增 kind 的事实时允许；一旦已有闸门二或闸门三证据必须拒绝降级，不能静默 丢弃、改名或降为闸门一。

• 三种证据继续只接受 T-204 已定值的 PNG、大小/分辨率/哈希/幂等与 INTERNAL_RAW 边界；不得 扩展文件类型、上传 XML/manifest/目录、提取或结构化地址与手机号。

• 本任务只扩展服务端证据 allowlist 与契约，不修改 client/PDD 页面判据，不实现事件、围栏、结果、 提交订单点击或任何付款能力。