diff --git a/docs/tasks/T-210.md b/docs/tasks/T-210.md new file mode 100644 index 0000000..1d3d15d --- /dev/null +++ b/docs/tasks/T-210.md @@ -0,0 +1,74 @@ +--- +id: T-210 +title: 扩展闸门二与闸门三证据类型 +phase: 2 +deps: [T-107, T-205] +status: TODO +created: 2026-08-04 +vikunja_task_id: 43 +context_ref: 772e379 +work_branch: task/t-210-gate-evidence-kinds +needs_device: false +needs_human_review: false +write_paths: + - docs/tasks/T-210.md + - admin/migrations/00007_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-205;T-204/T-302 由 T-205 传递。 +- 后续消费者:T-305、T-208。 +- 只修改采购服务证据 schema/validation,不修改 client 或页面判据。 + +## 方案 + +1. 新增 00007 迁移,把 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。 + + +## 边界 + +- 证据类型只允许精确的 `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 页面判据,不实现事件、围栏、结果、 + 提交订单点击或任何付款能力。