79 lines
4.7 KiB
Markdown
79 lines
4.7 KiB
Markdown
---
|
||
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
|
||
---
|
||
|
||
<!-- BEGIN VIKUNJA EXPORT id=43 synced=2026-08-04T14:39:13Z sha256=db95cfcdb109c264b188336cbf1625411d3457baf8525532613aac7e7487c3fd -->
|
||
## 问题 / 背景
|
||
|
||
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。
|
||
<!-- END VIKUNJA EXPORT -->
|
||
|
||
## 边界
|
||
|
||
- 证据类型只允许精确的 `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 页面判据，不实现事件、围栏、结果、
|
||
提交订单点击或任何付款能力。
|