# 冷链履约异常工作台交付提案

## 1. 目标、用户与范围

运营人员需要先处理未交付逾期订单，并追溯其原始事件。站点负责人需要看分层迟交指标，安全负责人需要可靠的导出与会话控制。第一期交付只读工作台、指标 API、事件时间线和受控导出设计；退款、写回调度、客户通知和员工绩效排名不在范围。

R1：按站点、服务等级与状态筛选订单，优先展示 overdue_open。R2：可打开订单事件及截止点，未来事件不参与历史指标。R3：取消／未到期不入成熟分母。R4：分服务比较和样本量提示。R5：服务端角色、站点及 session 检查。R6：加载、空结果、错误与数据延迟状态明确，保留刷新时间。

## 2. 信息结构与完整交互

页面先展示截止点、成熟数、迟交数和开放逾期数，再展示站点图与可筛选订单列表。三个筛选使用 AND 关系，结果数量与订单表同步。订单行展开显示 created、picked_up、delivered 或 cancelled 的完整时间线，明确哪些事件晚于复盘截止点。无结果显示“没有符合条件的订单”，可一键恢复全部。

资料包内工作台可直接筛选与展开全部 216 个订单。生产加载期间禁用重复请求，成功后更新时间；503 时保留上次成功快照并显示数据版本与失败原因，身份过期则清除敏感内容并转企业登录。离线工作台没有生产身份服务或真实导出权限，接口验收在下述集成范围内执行。

## 3. 架构与数据流

来源 A/B → 事件校验与冲突隔离 → 不可变标准事件层 → 按 as_of 聚合的订单视图 → 内网只读 API → 工作台。业务 orders 主表补充 route 和 due_at，事件只决定可见状态。记录 dataset_version、ingested_at 与 source_line，以便对账和重跑。新批次失败时不覆盖上一已核对版本。

企业身份服务颁发受控 session；网关验证 session，API 对每次请求再检查角色与站点范围。浏览器请求的 hub 不是授权依据。operator 仅可访问所属站点；supervisor 与受批次约束的 service 可按授权导出。数据服务不保存用户密码。导出写审计事件，包含 request_id、user、scope、rows、bytes 与 dataset_version，不记录密码和 session 密钥。

## 4. 接口契约

GET /v1/orders?hub=&service=&cohort=&as_of=&cursor=&limit=50：返回 items、next_cursor、total、as_of、dataset_version、updated_at。limit 为 1–100；cursor 为服务端稳定排序游标，同一次分页使用同一快照，避免刷新导致重复／漏项。未知筛选 400，无匹配 200 加空 items。

GET /v1/orders/{order_id}/events?as_of=：返回有序事件与 visible_at_cutoff。权限检查先于返回数据，不存在 404，无权限 403。GET /v1/metrics：返回成熟分母、迟交分子、分层结果和小样本状态，沿用同一快照。

POST /v1/exports：需 supervisor／service，body 含 scope、as_of、dataset_version；成功创建 202 与 job_id，完成后在授权范围内提供下载；operator 403。客户端提交 request_key 用于重复请求去重，服务端审计导出批次，不能以 UI 隐藏替代权限。

统一错误：400 参数、401 缺失／过期 session、403 无权限、404 不存在、409 快照不匹配、429 限流、503 数据源不可用。响应提供 request_id 与可显示的错误原因，不泄露凭据。

## 5. 需求到验收

R1：选择海港＋express＋overdue_open，仅出现匹配订单，恢复全部回到 216。R2：打开订单事件线，与标准事件逐条匹配；未来交付不改变历史状态。R3：216 = 12 取消 + 7 未到期 + 107 准时 + 80 已交付迟交 + 10 未交付逾期。成熟 197、迟交 90。R4：南湾 express n=4 显示待补样本，站点标准化值为空；目标差距 5／15 的边界正确。R5：operator 导出 403，过期 session 401，合法 supervisor 导出 202；operator 选择他站点仍 403。R6：空筛选、503、429、加载、恢复与更新时间逐项验收。

每条需求在 requirements-traceability.csv 映射到接口与用例。离线交互与算法测试能够检查资料成果；R5、生产错误与负载验收必须在后端接入后执行，不把本地页面当成生产权限实现。

## 6. 工作量与里程碑

| 工作项 | 人时 | 交付门禁 |
|---|---:|---|
| 需求、口径与交互设计 | 16 | R1–R6、身份协议、数据契约获确认 |
| 数据接入、聚合与快照 | 28 | 质量对账、未来事件及重跑测试通过 |
| 前端工作台与可访问性 | 24 | 筛选、时间线、空结果及键盘验收 |
| API、权限与导出审计 | 24 | 401／403、站点隔离和批次审计通过 |
| 身份／网关集成与发布准备 | 16 | 客户接入、回退与监控准备完毕 |
| 集成、安全和 UAT 测试 | 24 | R1–R6 全部验收，问题闭环 |
| 运维文档与交接 | 8 | 操作手册、值班和回退演练 |
| 合计 | 140 | 依赖满足后方可排期 |

计划由一位工程师每周投入 35 h，连续四个工作周完成 140 人时。W1：设计 16＋数据 19；W2：数据 9＋前端 24＋API 2；W3：API 22＋集成 13；W4：集成 3＋测试 24＋交接 8。周末与客户审批等待不计入工时；安全审查若排队则调整日历，不能压缩验收。工程能力与 35 h投入是假设，需负责人确认，未给定生产日期或合同金额。

## 7. 运维、支持与回退

监控新批次隔离率、快照更新时间、API 错误、越权拒绝及导出量。用工单记录影响站点、request_id、版本与复现步骤。严重访问故障由技术值班分诊，运营负责人确认业务影响；支持时段、响应目标、数据保留周期与费用另行确认，不承诺未商定 SLA。

回退先将读取切回上一核对快照，保留源数据与隔离记录；API 版本回退仍须保留新加的访问检查，不能为了恢复导出而开放 operator。恢复后以同口径复算 197／90 并对照版本，通知运营负责人确认。发布前另做备份与恢复演练。

## 8. 依赖和待确认项

客户需提供身份协议、允许角色／站点映射、网关访问、源接口可用性和留存要求。并发用户、数据到达延迟、刷新频率、导出上限、审计留存及支持时段在 W1 定稿。当前使用记录回放进行验收，不据此声称已处理生产流量或已改善履约指标。