# PRD 实现映射与验收边界

本文对应[产品 PRD](../prd/delivery-harness-product-prd.md)、[v2 API](../api/v2.md)和[试点运行手册](../operations/pilot-runbook.md)。更新日期：2026-10-21。

原整体实现 PR #35 已标记不可合并。修复源码已拆为 23 个按依赖排列的 PR，评测结果摘要另由 [PR #61](https://github.com/diudiu-tech/delivery-harness/pull/61) 补充。2026-10-21 起按用户授权逐项验证并集成 main；本文用于核对实现与验收边界，具体整改入口见[审查整改索引](delivery-harness-review-remediation.md)。是否通过检查必须以对应提交的当前结果为准，本文不替代产品联合评审。

本轮范围为可信决定、存储与审计、身份授权、案件复核、执行队列、版本质量管理和内部工作台。**FR-14 资金执行与实际留存删除均不在本轮实现范围；须在 M2 验收后单独立项，补充决策记录与验收方案。**人工批准和例外提议只形成内部审核记录，不办理赔付。

## 1. 证据分层

| 证据 | 可以证明 | 尚不能证明 |
| --- | --- | --- |
| 核心单元与 JDBC 回归 | 时间、公式、边界、职责分离、CAS、事务回滚、分页和故障分支符合测试预期 | 真实经营政策正确或真实业务数据完整 |
| 本地 HTTP 契约夹具 | 白名单、字段校验、退款余额未知语义、流式响应上限和失败分类生效 | 已接入真实订单系统或真实模型供应商 |
| H2 与真实 Flyway | 类路径迁移、旧数据升级、附件正文分离、时间戳和游标行为可复现 | 指定 PostgreSQL 版本的锁、执行计划、备份恢复与容量已经验收 |
| 本地签名 JWT 夹具 | RS256 验签、issuer/audience/有效期、租户/角色/scope 拒绝路径生效 | 真实组织 IdP 接入、密钥轮换、人员离职撤权和权限审批已验收 |
| MockMvc 演示闭环 | 建案、冻结决定、独立复核、幂等、导出和类型化输入通过 API 回归 | 已完成真实浏览器可用性验收、生产试点或业务效果实验 |
| GitHub 检查 | 对应提交的构建、测试、依赖和 CodeQL 结论 | 其他分支或旧提交也具有同样结论 |

修复过程的本地证据包括完整 core 回归、平台 API 回归和安全/质量 API 回归。构建报告保存在各模块的 `target/surefire-reports/`，core 覆盖率报告在 `harness-core/target/site/jacoco/`，聚合报告在 `harness-api/target/site/jacoco-aggregate/`。它们是运行对应命令后产生的构建产物，不随仓库保存。

每个拆分 PR 都须重新运行格式检查和 `./mvnw clean verify`，在 PR 模板中记录提交 SHA 与当前结果。修复源码的历史覆盖率不能替代新分支的结果；CodeQL 的工作流执行完成也不能替代安全检查本身通过。原 PR 的 CodeQL 失败不得写成“验证通过”。

## 2. 当前技术边界

| 方面 | 实现边界 |
| --- | --- |
| 模块 | common 定义 DTO、枚举、异常；core 承载工作流、运行时接口、JDBC 和业务服务；API 承载认证、类型化 HTTP 接口和静态工作台 |
| 迁移 | core 类路径拥有 V1–V10 SQL/Java 迁移，包含恢复索引、显式摘要投影与评测结果评分回填；测试直接运行 Flyway，不读取 API 相对路径或手工拆 SQL |
| 数据 | 记录 JSON 保存可扩展元数据；case/order/status/state/scope 及队列过滤字段使用 SQL 投影和索引；材料正文独立存放 |
| 时间与分页 | 数据库时间戳按时间排序；审计游标同时绑定 created_at 与 event_id；过滤和权限范围在 SQL LIMIT 之前生效 |
| 身份 | demo 显式 bearer + 本机 Host/Origin 白名单；pilot 使用 OIDC/JWT resource server，校验签名和可信 claims |
| 执行 | 冻结证据/政策/配置；持久任务与幂等键；租约和 fence；恢复、心跳、截止时间独立调度 |
| 决定 | 确定性金额和服务端核验模板；模型只解释允许事实；缺失/冲突不补零或自动授权 |
| 默认演示 | 合成订单、演示身份、demo 启动播种和确定性 runtime；不需要模型服务 |
| pilot | 不播种演示政策、知识和数据集；无已发布配置时拒绝在线执行；v1 返回迁移错误 |

持久对象包括案件、材料、证据快照、决定、执行/步骤、复核/动作、政策、知识、运行配置、评测、反馈、幂等和审计。资金台账、渠道调用、自动办理、实际留存删除和删除审批流程不属于本轮持久业务实现。

`GET /api/v2/adapters/status` 只返回源契约元数据，不查询订单、不写记录，也不返回 endpoint 或凭证。它不表示外部业务源已通过连通性或数据质量验收。

## 3. FR 功能映射

“已实现”表示修复源码存在对应行为和本地回归；是否合入以独立 PR 为准。

| FR | 修复实现与本地证据 | 仍需实际验收的事项 |
| --- | --- | --- |
| FR-01 身份与授权 | Spring Security 无状态 bearer；demo 独立身份；pilot JWT；Host/Origin；强制审计依赖；租户和城市/站点范围。`PlatformSecurityFilterTest`、`OidcSecurityApiTest`、`DemoIdentityApiTest`、`DisabledDemoIdentityApiTest` | 组织 IdP 联调、真实 roster、撤权/轮换、TLS 网关与权限签字 |
| FR-02 证据与时间轴 | `OrderSource` 冻结源元数据；秒级时间轴与 UNKNOWN/INVALID/不适用；实时源不回退合成事实。`OrderTimelineTest`、`OrderSourceTest`、`TrustedWorkflowTest` | 源字段完整性、时区、承诺时间和历史 ETA/运力语义 |
| FR-03 政策与确定性决定 | 单一审批阈值；共用 `CompensationMethod`；金额精确到分；退款受已核验可退余额约束；绑定缺失时关闭可信入口。`CompensationRuleToolkitTest`、`RuleBaseServiceTest`、政策 API 回归 | 经营政策、生效范围、可退余额业务口径及真实授权 |
| FR-04 引用与文案 | 严格结果结构、引用 ID/路径/值/单位核验、guardrail 与服务端客户说明；代码约束保持 system 层级。`OutputFormatterTest`、`EvidenceValidatorTest`、`GuardrailCheckerTest` | 自由文本事实核查、真实恶意资料和提示注入红队 |
| FR-05 降级与失败 | 依赖失败保留基础结果与执行轨迹；模型解释不可用区分 DEGRADED；任务异常可观察。`TrustedWorkflowTest`、`WorkflowEngineTest`、`ExecutionServiceTest` | 真实故障组合、告警投递和人工响应演练 |
| FR-06 存储与审计 | JDBC 事务内写业务与审计；不可变快照；CAS；附件正文分离；数据库时间戳；双字段审计游标。`PlatformStoreTest`、`IndexedPlatformStoreTest` | PostgreSQL 并发/隔离、迁移窗口、一致备份与恢复验证 |
| FR-07 队列与幂等 | 202 异步提交、持久幂等、全局/租户 admission、公平调度、取消、总 deadline、租约恢复和独立调度。`ExecutionServiceTest` | 实际流量、多实例争用、在线与评测满载 SLO |
| FR-08 案件与独立复核 | 材料核验、领取/转派/审批、证据绑定、POST 导出、类型化输入；案件和决定作者不能自批；作者缺失要求重新分析。`CaseServiceTest`、`CaseRequestValidationTest`、`ExportControllerTest`、`PlatformAcceptanceApiTest` | 真实人员分权、附件制度、审核体验、工单衔接 |
| FR-09 知识生命周期 | 预览、切片、发布/撤回、范围/时点过滤、历史引用；另一人发布。`QualityServiceTest`、知识 API 回归、`RetrievalScoringTest` | 真实语料审查、语料规模与检索效果；未引入向量系统 |
| FR-10 可复现评测 | 冻结数据集/配置、实际调用绑定、精确字段评分、未知标签不当满分、盲集隔离、匹配报告发布门禁。`QualityServiceTest`、`QualityAcceptanceApiTest`、评测契约回归 | 真实标注、一致性、代表性、冻结盲测和业务增益 |
| FR-11 模型配置与退出 | 服务端 endpoint 引用、调用时白名单、总预算和有限重试、明确关闭模型、用量/版本价未知语义。`BoundedLlmClientTest`、网关回归、配置 API 回归 | 供应商协议、真实密钥/连通性、账单核对和退出收益 |
| FR-12 观测与反馈 | SQL 总量、明确标记的最近样本耗时、已知费用与未知数量；反馈每次检查案件范围，独立核验。`OperationsServiceTest`、`QualityServiceTest` | 真实告警平台、处理时长、采用/改判率、单位案件成本实验 |
| FR-13 只读源契约 | 允许主机、无重定向、流式 1 MB 上限、金额/时区/范围校验、可退余额缺失为 UNKNOWN、失败不回退。`OrderSourceTest`、执行范围变化回归 | 真实订单服务联合验收、限流、可退字段与历史上下文 |
| FR-14 资金执行 | **本轮不实现。**内部批准仍为 NOT_EXECUTED；相关演示回归仅证明没有办理资金 | M2 验收后独立立项，单独设计、ADR、权限与渠道验收 |

实际留存删除也须在 M2 验收后单独立项。本轮没有可启用的自动删除功能或已完成的删除验收。

## 4. 必须保留的安全与产品语义

1. 可空的权威金额和可退余额表示未知，不能用 0 或订单原金额代替。0 元余额是明确的已知值。JSON 省略 null 时，调用端仍须按未知处理。
2. 执行完成、决定可确定、模型解释可采用、人工批准和资金办理是不同状态。人工批准不能被解释为业务系统已赔付。
3. 案件作者与决定作者来自服务器身份和持久提交人。兼任主管不产生自批豁免；历史决定缺少可证明的作者不能沿用旧领取状态批准。
4. 材料正文和元数据分离。外链与自报损坏不是已核验正文；补证和决定变化使旧审批失效。
5. 正常 GET 不生成默认业务记录；demo 默认资产在启动阶段准备。导出改用 POST。认证失败不逐次落无限审计；已认证授权拒绝按安全边界记录。
6. policy、knowledge、runtime 的作者与发布人必须不同。运行配置发布还须使用同一冻结配置的通过报告；pilot 报告必须记录真实构建 SHA。
7. 只有已认证主体会登记到进程内审核人目录。它不是已完成同步的组织人员目录；重启后真实审核人须重新认证，长期 roster 集成另行验收。
8. 费用统计只汇总已知用量与明确币种/价格版本，未知数量单列；执行成功率和合成评测不能当作真实准确率或节省工时。

## 5. 拆分交付与检查

交付主题按依赖先后为：PRD；可信工作流破坏性语义；LLM 调用边界；存储/迁移/审计；身份授权；只读源与案件材料复核；执行队列；政策/知识/配置/评测/反馈；内部工作台；运行与 API 文档。涉及 CI 的改动独立审查；资金与实际删除不并入这些主题。

提交使用 `<type>/<subject>` 分支名、Conventional Commits 与说明原因的换行正文。v1 降级返回、服务端客户模板、pilot v1 禁用、评分语义、导出方法和严格 JSON 类型等兼容性变化须在相应 PR/提交标记 BREAKING CHANGE。

每个 PR 应回答金额、审批阈值、guardrail、进入模型的内容和日志影响，完成仓库模板的破坏性及安全/数据影响清单。CODEOWNERS 文件变更单独请求对应审查。

```bash
./tools/check-format.sh
./mvnw clean verify
```

最终核对 GitHub 构建、依赖审查及 CodeQL 的实际结论；没有当前提交的绿灯不能宣称可合并。部署前另按运行手册准备真实环境证据，记录“已完成”“未验证”和阻断项，不能用 PRD 的目标值代替测量结果。

## 6. 本轮集成新增验证

- 摘要查询：V8/V9 原子写入与回填显式投影；破坏完整 payload 后列表和运营计算仍成功，证明没有先读取完整对象再删字段。
- 配置范围：全域政策不能暴露受限知识；配置/评测详情与列表均有跨站点拒绝与正向对照。冻结包超过 512 KiB 在写候选前拒绝。
- 并发恢复：确定性交错正常心跳与完成写入，结果不丢失；超过 1,000 租户和整页未过期租约后的任务仍可恢复。
- 工作台：真实本机浏览器完成 DEMO-002 建案、规则引擎 CNY20 建议、独立主管批准，保持未执行；核验身份切换、发布人导航、规则数和运行详情。状态回归另覆盖筛选竞态、审计游标、数值类型、更正核验和凭证清理。
- 反馈回归引用：独立校验边界同时验证完整运行知识范围与每条样本，再允许关联已完成且通过的报告；范围拒绝不推进反馈状态。
- 契约：从实际 MVC/Jackson 元数据生成 OpenAPI，测试覆盖知识搜索别名及 DTO 约束；没有手写大 JSON。
- 评测结果：专用摘要保留样本编号、执行状态、候选/基线评分及失败代码，V10 回填已有结果；`EvaluationResultSummaryTest` 以损坏完整 payload 的探针验证读取仍依赖投影，API 与前端回归覆盖实际评分字段。

这些是本机合成验收；不代表真实身份提供方、PostgreSQL、订单源、模型供应商、生产负载或业务效果已验收。PR #35 保持不可合并；拆分 PR 按依赖集成，具体合并和检查状态以对应 PR 为准；代码合入不代表上线授权或真实业务验收。