88 lines
5.5 KiB
Markdown
88 lines
5.5 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-06T02:59:09Z sha256=091bf2685c5caa42d62bc9229f55787e6418d7f67b8c237c32b640c8b4891d06 -->
|
||
## 问题 / 背景
|
||
|
||
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 消费或建立围栏。
|
||
<!-- END VIKUNJA EXPORT -->
|
||
|
||
## 边界
|
||
|
||
- 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 页面判据，不实现事件、围栏、结果、
|
||
提交订单点击或任何付款能力。
|