90 lines
7.1 KiB
Markdown
90 lines
7.1 KiB
Markdown
---
|
|
id: T-403
|
|
title: 失败分类、证据归档与管理员调和视图
|
|
phase: 4
|
|
deps: [T-208]
|
|
status: TODO
|
|
created: 2026-08-04
|
|
vikunja_task_id: 48
|
|
context_ref: 8600c33
|
|
work_branch: task/t-403-failure-reconciliation-view
|
|
needs_device: false
|
|
needs_human_review: true
|
|
write_paths:
|
|
- docs/tasks/T-403.md
|
|
- admin/internal/taskdetail/**
|
|
- admin/internal/server/task_detail.go
|
|
- admin/internal/server/task_detail_test.go
|
|
- admin/internal/server/task_failure_view_test.go
|
|
- admin/internal/transport/webui/webui.go
|
|
- admin/internal/transport/webui/templates/task-detail.html
|
|
- admin/README.md
|
|
- docs/routes.md
|
|
- docs/08-interaction-checklist.md
|
|
- docs/current-state.md
|
|
---
|
|
|
|
<!-- BEGIN VIKUNJA EXPORT id=48 synced=2026-08-06T02:59:07Z sha256=9a6d7f96c42df181cf6204acdd1d5d179136df36221c1a40517f0d8906a562b9 -->
|
|
## 问题 / 背景
|
|
|
|
T-208 将冻结三闸门、submission fence、一次性 result 和管理员调和事务，T-206 提供状态详情底座。采购管理员仍需要在同一任务详情中看懂围栏前固定失败、围栏后结果不明、已有证据和人工调和历史，并只调用 T-208 已有的同一 submission 调和接口。T-403 只完成失败分类/证据归档事实的展示和调和 UI，不新增失败码、数据库事实或第二套调和事务。
|
|
|
|
## 关联需求与交互
|
|
|
|
- 功能：F-007、F-011、F-017 的管理展示与人工调和入口。
|
|
- 用户故事：US-002、US-004、US-008。
|
|
- 交互：IX-004、IX-009、IX-011。
|
|
- 依赖：T-208；由其传递 T-205 固定事件/失败码、T-210 三类证据、T-206 状态详情和 T-207 恢复边界。
|
|
- API：只消费 T-208 既有 POST /order-submissions/{sid}/reconcile；不新增或重复实现 reconcile store/事务。
|
|
- 后续消费者：T-402 待付款人工收口、T-404 MVP 验收。
|
|
|
|
## 方案
|
|
|
|
1. 扩展任务详情只读模型，按同一 task/authorization/attempt/submission 展示 T-205 已保存的固定 failure code、失败阶段、最后安全步骤、事件时间线、执行摘要及 Gate1/Gate2/Gate3 内部证据；不复制、删除、重命名或重新归类原始事实。
|
|
2. failure code 只使用 T-205/T-208 已有版本化 allowlist。UI 可为现有码提供固定中文解释和安全下一步，但必须同时显示原始 code；未知 code 显示“未知失败码/停止处理”，不得猜测、合并、改写或映射成另一个码。
|
|
3. 围栏前 NEEDS_MANUAL 只展示失败原因、证据和 T-207 已计算的安全恢复资格；T-403 不实现新的重置/取消事务，也不让查看证据触发恢复。
|
|
4. 围栏后以 order_submission 为唯一主线，显示 submission id、三闸门 proof、首次许可事实、result observation、append-only reconciliation records 和当前结论。task.status 与 submission 冲突时以 submission 围栏事实优先并进入安全核查。
|
|
5. RECONCILIATION_REQUIRED 页面只渲染 T-208 已冻结的 CONFIRMED_CREATED、CONFIRMED_NOT_CREATED_OR_CANNOT_COMPLETE、STILL_UNKNOWN 三种结论，并把管理员 session、CSRF、submission id、expected task version 和幂等键提交到既有 reconcile handler。
|
|
6. T-403 不解析或重放 T-208 事务结果，不在 UI 层直接改 task/authorization/attempt/submission。响应不明时冻结原幂等键和原表单，只允许重放既有 reconcile 请求；不生成新结论或乐观更新终态。
|
|
7. 围栏后任何状态都持续显示“可能已创建订单，只能调和同一提交，禁止再次提交”，并彻底隐藏重试下单、重置、取消、释放、重新授权、重新领取和设备继续动作。
|
|
8. 内部 evidence 继续通过受保护 no-store 端点延迟加载；只展示已批准的 Gate1/Gate2/Gate3 PNG。没有 SUBMISSION_RESULT kind，不展示或上传外部支付页、支付凭据、完整 XML、路径或页面全文。
|
|
9. 完整页与抽屉共享同一模板/事实；调和表单具备可见 label、错误关联、焦点恢复、44px 目标、aria-live、响应不明提示和 reduced-motion。只读终态不渲染表单。
|
|
|
|
## 验收要点
|
|
|
|
- 覆盖每个既有固定 failure code、未知 code、最后安全步骤、三类 evidence、空证据和关联冲突；测试只断言显示，不改写原始码。
|
|
- 覆盖 NEEDS_MANUAL、RECONCILIATION_REQUIRED、WAITING_PAYMENT、FAILED 及 submission/task 状态冲突；任何 submission 存在时均无围栏前恢复或再次提交入口。
|
|
- 三种调和结论只调用注入的 T-208 既有 handler/store 一次；T-403 没有第二套 SQL、migration、状态机或直接数据库写入。
|
|
- 同幂等键响应不明重放保持原载荷；异载荷、旧版本、错 submission 的错误按 T-208 原结果展示，不乐观改变页面状态。
|
|
- 完整页/抽屉、键盘、焦点、加载/失败/空态、权限、CSRF、HTML escaping、no-store evidence 和移动宽度通过测试与人工 UI 评审。
|
|
- 静态检查确认没有新 failure/reason 常量、migration、reconcile transaction、client/PDD、提交点击、付款或扣款能力。
|
|
- `go test ./...`、`go test -race ./...`、`go vet ./...`、`go build ./...`、相关前端静态测试、完整 init、上下文、Vikunja export 与 diff-check 通过。
|
|
|
|
## 执行记录
|
|
|
|
### 2026-08-06T02:58:55Z · ila
|
|
|
|
2026-08-06T02:58:54.857Z · Codex
|
|
2026-08-06 管理视图/证据文案把 Gate3 解释为合并式最终提交面板的最终控件金额，不再称确认页金额；历史数据库字段在 T-210 迁移为 gate3_submit_amount 后再消费。外部付款页仍不保存、不上传。
|
|
<!-- END VIKUNJA EXPORT -->
|
|
|
|
## 边界
|
|
|
|
- 2026-08-06 起管理视图把 Gate3 展示为合并式最终提交面板的最终控件金额，不再称确认页金额；
|
|
只消费 T-210 迁移后的 `gate3_submit_amount`，不读取旧 `confirm_amount` / `confirm_page_amount`。
|
|
|
|
- 本任务只展示 T-205/T-208 已有失败、事件、三闸门 evidence、submission 与 reconciliation 事实，
|
|
并把管理员表单提交到 T-208 既有 reconcile handler/store；不得新增或改写 failure/reason code、
|
|
migration、状态机、调和事务或直接数据库写入。
|
|
- 原始 failure code 必须始终可见；固定中文解释只能附加在已有 allowlist 上。未知 code 必须安全失败并
|
|
显示“未知失败码/停止处理”，不得猜测、合并或映射为另一个 code。
|
|
- 任一 submission 的存在都优先于 task.status。围栏后不得显示或提供重试下单、重置、取消、释放、
|
|
重新授权、重新领取、再次提交或设备继续动作；只能查看和调和同一 submission。
|
|
- evidence 只读取 T-210 已批准的 Gate1/Gate2/Gate3 内部 PNG，不上传、删除、重命名或重新归类资产，
|
|
不新增结果截图 kind，不展示外部支付页、支付凭据、完整 XML、文件路径或页面全文。
|
|
- 调和结论只能是 T-208 已冻结的 `CONFIRMED_CREATED`、
|
|
`CONFIRMED_NOT_CREATED_OR_CANNOT_COMPLETE`、`STILL_UNKNOWN`。响应不明时只允许用原幂等键和
|
|
原载荷重放既有请求，不得生成新结论或乐观更新终态。
|
|
- 本任务不修改 `client/` 或拼多多页面判据，不连接真机，不点击“提交订单”，不编写支付、免密支付、
|
|
先用后付或任何扣款能力。
|