--- id: T-210 title: 扩展闸门二与闸门三证据类型 phase: 2 deps: [T-107, T-204, T-302] status: TODO created: 2026-08-04 vikunja_task_id: 43 context_ref: cd47d0c work_branch: task/t-210-gate-evidence-kinds needs_device: false needs_human_review: false write_paths: - 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。 ## 边界 - 证据类型只允许精确的 `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 页面判据，不实现事件、围栏、结果、 提交订单点击或任何付款能力。