html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
ouyangxq
2026-08-12 09:25:58 +08:00
parent ca2c455c8c
commit 3bb1ab950d
5 changed files with 64 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+3 -1
View File
@@ -7,11 +7,13 @@
- [一期文档](一期/README.md)：一期范围、开发进度和头程订单最小闭环。
- [二期文档](二期/README.md)：预约取货、到仓收货、实测差异和指定库位闭环。
- [三期文档](三期/README.md)：智能排柜、订舱、拖车、PDA 拣货、报关协同和国内出仓闭环。
- [独立任务协作登记](独立任务协作登记.md)：以稳定 `parent_routing_key → routing_key + task_id` 维护总控、可复用下属独立任务及其回传关系。
- [独立任务协作登记](独立任务协作登记.md)：只维护总控与用户可见独立任务的稳定 `task_id`、父子关系和职责范围，不记录动态进度或归档状态。
## 跨阶段参考
- [财务管理闭环盘点与范围建议](财务管理/README.md)：基于当前入库计费、财务原型和现有代码盘点财务闭环、缺口及建议的首期应收边界。
- [墨家设备测量上传接口说明 V3](墨家设备测量上传接口说明-V3.md)：墨家测量设备经 Gateway 上传箱码、尺寸、重量和图片的开放接口契约。
- [统一订单主状态与操作契约](统一订单主状态与操作契约.md)：统一订单七状态、操作编码、内部状态兼容映射，以及与三期一致的 `LOADED` 硬门禁和 `DELIVERED` 可信回传边界。
- [数据库中文注释维护规范](数据库注释维护规范.md)：数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。
- [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、执行边界、健康检查与失败处理。
- `悦/`：产品原型、流程图、历史架构资料和调研数据，仅作为需求参考，不直接等同于已确认范围。
独立任务协作登记.md
+24 -88
View File
@@ -1,103 +1,39 @@
# 独立任务协作登记
> 本文件登记用户可独立打开和查看的 Codex 总控与下属独立任务，不登记子代理。总控负责计划和调度，下属任务保留业务上下文并可自行使用子代理；任务名称始终只是展示标签。
> 仅供用户明确指定的 Codex 总控使用。普通任务和子代理不读取、不登记。
## 启用门禁
## 登记表
默认对话是普通任务，不进入本登记流程。小任务直接在当前对话完成，不登记、不创建下属独立任务，也不因为任务看起来复杂就自行切换为总控。
总控：
只有以下任一条件成立时启用总控模式：
| task_id | display_name | responsibility |
|---|---|---|
| `019ff0da-7699-7532-ac64-703325c995fd` | 全量验收总控 | 统筹 Finance 一期 G1-G4 实现、验证、人工部署准备、Finance-only 验收及正式全量接入 |
| `019ff0db-267e-7112-9c86-af21c5b0c1af` | 财务一期总控 | 接替原财务总控，统一收敛财务一期五页 G1-G4 契约、实现、验证与验收证据 |
- 当前稳定 `task_id` 已登记在下方“总控通道”。
- 用户或任务启动指令明确声明当前任务是总控，并授权其规划、拆分和调度；尚未登记时必须先核对稳定 ID 并补充总控记录。
总控创建、需要长期复用的用户独立任务：
“总控下属独立任务”中的任务默认只是执行任务，可以使用自己的子代理，但不能继续创建用户可见的下属独立任务或自行升级为总控。需要升级时必须由用户明确指定并登记。只有已登记总控创建或明确接管的独立任务才进入本表，其他普通对话不登记。普通任务认为需要长期编排时只能先建议切换，用户确认前不得启动本流程。
| task_id | parent_task_id | display_name | responsibility |
|---|---|---|---|
## 总控通道
## 规则
总控通道持有整体计划、任务拆分、共享契约、结果汇总和后续调度。`idle`、`active`、`blocked` 都表示通道可复用；只有 `archived` 表示不可继续下发。同一 `routing_key` 只能保留一个未归档任务。
- 只有用户明确指定当前对话为总控时才登记；任务规模和模型判断不能自动启用总控。
- 跨对话寻址只使用 `task_id`，名称只用于展示。独立任务创建成功后，先登记稳定 ID、所属总控 ID 和职责，再下发工作。
- 只登记用户可见的长期独立任务；普通对话和 `thread_source=subagent` 子代理不登记。
- 复用前只读核对 ID 是否存在、未归档且职责匹配。异常时停止并告诉用户，不自动创建、归档、解档、恢复或替换任务。
- 本文件只保存稳定 ID、父子关系和职责，不记录状态、进度、排期、工作包、验证结果或临时阻断。
- 上下文过长或需要更换任务时只报告风险和建议，由用户决定。
| routing_key | task_id | display_name | durable_scope | owner | status | last_update | notes |
|---|---|---|---|---|---|---|---|
| `admin-ui.control` | `019fea7a-979f-7252-8963-70687563385f` | Admin UI 总控 | Admin 页面规范、公共组件、交互一致性和跨模块 UI 治理 | Admin UI 总控 | active | 2026-08-11 | 后续 Admin UI 规划、拆分与汇总统一复用此 ID |
| `phase3.control.release-acceptance` | `019fdf57-2f16-7cf1-88f0-a75854ed7629` | 三期总控｜发布与验收 | 三期发布、测试环境验收、阻断分类与最终汇总 | 三期总控 | idle | 2026-08-11 | 后续三期发布与验收规划、拆分和汇总统一复用此 ID |
| `finance.control` | `019feaa3-9f10-7ab0-8023-4b121ff9662c` | 财务总控 | 财务范围、跨端契约、后端/Admin/Client 协调与汇总 | 财务总控 | active | 2026-08-11 | 后续财务规划、拆分与跨端汇总统一复用此 ID |
| `phase3.acceptance.real-full.control` | `019fdf0a-4933-7903-8a0c-10018c379f6f` | 三期真实全量验收总控 | 三期测试环境真实 HTTP 全量验收、返工复验、结果汇总和后续调度 | 三期真实验收总控 | active | 2026-08-11 | 后续同范围验收规划、拆分和汇总统一复用此 ID |
### 总控编排规则
- `routing_key` 按长期职责确定，格式为 `<domain>.<unit>.<responsibility>`；不包含序号、日期、批次、提交号或本轮动作。
- 命中未归档总控后直接使用其 `task_id` 通信；标题相同或不同均不影响寻址。总控开始新一轮工作时改为 `active`，整体计划暂时没有待调度工作时回到 `idle`。
- 总控通道不得使用 `completed`；一轮工作完成后回到 `idle`，继续保留复用资格。
- 用户将任务指定为总控并授权其规划、拆分和执行后，总控可在已确认目标与范围内创建必要的下属独立任务，无需逐项再次确认；超出授权范围仍须用户确认。
- 永久停用才标记 `archived`。创建替代通道时，在新旧记录备注中互相写明 ID，不覆盖或复用旧 ID。
## 总控下属独立任务
下属独立任务负责稳定、可再次进入的业务边界。它可以自行创建和归档内部子代理，但必须由所属总控通过稳定 ID 下发，并将结果回传总控。任务一轮完成后改为 `idle` 并保留，不自动归档；旧功能修改、返工或补验重新激活原任务。
| routing_key | task_id | parent_routing_key | display_name | durable_scope | status | worktree/branch | last_update | notes |
|---|---|---|---|---|---|---|---|---|
当前暂无符合 `thread_source=user` 条件的财务总控下属独立任务；后续只登记上述总控创建或明确接管、且未继承总控完整历史的独立对话。
### 下属任务生命周期
- `planned`：已经规划和登记，尚未开始；`active`：正在执行或等待内部子代理；`blocked`：存在明确阻断；`idle`：本轮已回传并等待总控再次下发。
- 独立任务回传后由总控验收并更新计划。验收通过只把该任务改为 `idle`，不删除登记、不归档聊天、不改写 `task_id`。
- 总控发现旧任务需要修改时，直接向原 `task_id` 下发并改为 `active`；独立任务沿用已有上下文理解需求，内部子代理可根据本轮工作重新创建。
- 只有职责永久撤销、任务损坏、任务被明确替代或用户要求停用时才归档；归档前在备注中说明原因和替代 ID（如有）。
## 下发容量与上下文门禁
- 一个下属独立任务同时只能执行一个 `work_item_id`。`active` 期间，总控不得继续追加新的执行包；只允许针对当前工作包发送必要纠偏、取消或状态查询。
- 尚未下发的工作留在总控计划中，不用消息提前堆进执行任务。当前任务必须先回传最终结果或明确阻断，总控验收并改为 `idle` 后，才能向同一 ID 下发下一工作包。
- 每个工作包必须具备单一目标、稳定范围、完成条件和回传格式。连续发送“请继续”、把多个目标合并到一个执行包，或在执行中改变职责范围，均视为无效调度。
- 新建下属独立任务必须使用不继承总控完整历史的用户任务创建方式，并让它运行在同一工作区；初始消息只发送职责、当前工作包、共享契约和文档入口，不复制总控完整聊天记录。
- 复用前核对 `thread_source=user`、状态、职责匹配和最近一次回传。`thread_source=subagent` 即使能跨任务通信，也不是可复用独立任务；它完成当前内部工作后由父任务汇总并归档。
- 出现完整继承总控历史、近期单轮输入接近模型上下文窗口一半、反复压缩后遗忘事实、响应持续明显变慢或职责漂移时，启动受控换代：当前任务先形成持久化交接摘要，随后创建用户独立后继任务；旧任务归档，新旧记录通过 `supersedes_task_id` 互相指向。累计 `tokens_used` 只作负载参考，不单独触发换代。
## 默认归档策略
- 总控通道和已登记的 `thread_source=user` 下属独立任务：默认不归档，一轮完成后转为 `idle`。
- `thread_source=subagent`：完成或中止且结果已被父任务汇总后默认归档；不得登记或重新唤醒为独立任务。
- 普通用户对话：不纳入本表，由用户按需要归档；不批量恢复，也不因为业务名称相似自动登记。
- 已归档的真实独立任务只有在职责完全一致且上下文仍健康时才恢复原 ID；不健康时按受控换代创建后继任务。
## 已归档任务恢复门禁
归档用于收起明确停用的对话，不等于删除任务或废弃其稳定 ID。准备创建独立任务时，在查询总控通道和下属任务之后、实际创建之前，必须先用本机 `~/.codex/session_index.jsonl`、`~/.codex/state_5.sqlite` 和 `~/.codex/sessions/` 检查是否存在可恢复的已归档用户任务。
- 用户明确要求继续、返工或补验原任务，并且前序目标、交付物与上下文属于同一项工作时，取消归档原 `task_id`，把它重新加入“总控下属独立任务”并标记为 `active`，再向原 ID 下发。
- 只是业务域相同但职责边界不同的新事项时，不占用历史任务；由总控复用其他匹配任务或在授权范围内创建新的下属独立任务。标题、关键词或模块相同不能单独作为恢复依据。
- `thread_source=subagent`、已确认中止的子代理、已经被新任务明确替代的任务，以及损坏或无法读取的任务不得恢复为独立任务。
- 恢复动作不得生成新 ID，也不得把旧 ID 转给另一项工作。恢复后仍沿用原任务的范围和上下文，本轮结束后回到 `idle`；只有满足明确停用条件时才再次归档。
创建前判定顺序固定为：确定总控与子任务 `routing_key` → 查询未归档总控和下属任务 → 本地检查已归档同任务 → 复用原任务、恢复原任务或判定无匹配 → 核对总控的范围内拆分授权 → 创建并登记 → 下发。
## 登记规则
- 总控和下属独立任务都必须登记稳定 `routing_key`；下属任务还必须登记 `parent_routing_key` 和可长期识别的 `durable_scope`，并作为后续复用的强制路由。未由已登记总控创建或明确接管的普通对话不得登记。
- 本表只登记本机元数据为 `thread_source=user` 的用户独立任务；通过子代理创建接口或全量历史分叉产生的 `thread_source=subagent` 不得登记，完成或中止后由父任务汇总并归档。
- 独立任务创建成功并获得平台返回的稳定 ID 后立即登记；没有稳定 ID 不得写入临时名称或自行生成替代 ID。
- 任务名称可以修改，`task_id` 不得复用、改写或转给另一项工作。独立任务本轮完成后保留登记并改为 `idle`；后续原范围返工继续使用原 ID。重要业务结论必须写入对应业务、验收或进度文档。
- 跨任务共享契约由总控记录；独立任务回复必须带回自身 `routing_key`、`task_id`、`parent_routing_key`、状态、变更文件、验证结果、阻断项和建议下一步。
## 通信与汇总格式
总控下发消息至少包含：
## 通信格式
```text
role: controller | independent_task
routing_key: <长期职责键>
task_id: <已登记 ID>
parent_routing_key: <所属总控键；总控自身填 self>
work_item_id: <当前工作包稳定 ID>
目标: <单一交付目标>
task_id: <目标独立任务 ID>
parent_task_id: <所属总控 ID>
职责: <登记范围>
目标: <本轮目标>
范围: <目录/模块>
完成条件: <可客观核验的结束门禁>
共享契约: <依赖的接口、模型或文件>
回传: <状态、变更文件、验证命令/结果、阻断项>
回传: <变更文件、验证结果、阻断项和建议下一步>
```
汇总时按 `parent_routing_key → routing_key + task_id` 聚合，不按 display_name 聚合；同一 ID 的最新状态覆盖旧状态，但保留重要阻断和验证记录。总控验收回传、更新整体计划后，再决定向原任务返工或安排下一项工作。
独立任务按 `parent_task_id` 回传，总控负责汇总；动态信息不写入本文件。
统一订单主状态与操作契约.md
+20 -18
View File
@@ -13,8 +13,8 @@
| `INBOUNDED` | 已入库 | 历史/内部兼容状态；本版本测量完成后不在此状态停留 |
| `WAIT_SPLIT` | 待分柜 | 订单进入分柜处理，尚未完成有效分柜方案 |
| `LOADING` | 装柜中 | 预装清单已确认，正在拣货、装柜和补充证据 |
| `LOADED` | 装柜完成 | 装柜操作已完成，等待派送完成 |
| `DELIVERED` | 派送完成 | 派送完成，订单进入终态 |
| `LOADED` | 装柜完成 | 国内出仓终点；装柜完成硬门禁全部通过 |
| `DELIVERED` | 派送完成 | 海外仓可信回传推进的后续只读状态 |
主状态只表达订单当前所处的产品阶段。订单列表、订单详情、客户进度和 PDA 任务引用同一主状态，不再分别展示“头程订单状态”和“入库单状态”。
@@ -27,8 +27,8 @@
| `CONFIRM_MEASUREMENT` | `WAIT_MEASURE` | `WAIT_SPLIT` | 测量数据点击完成后自动进入待分柜，不需要人工进入分柜 |
| `SMART_SPLIT` | `WAIT_SPLIT` | `WAIT_SPLIT` | 智能分柜或人工调整，生成/更新预装清单 |
| `CONFIRM_PRELOAD` | `WAIT_SPLIT` | `LOADING` | 预装清单确认后进入装柜中 |
| `COMPLETE_LOADING` | `LOADING` | `LOADED` | PDA 拣货、拍照和封签操作完成后确认装柜完成 |
| `COMPLETE_DELIVERY` | `LOADED` | `DELIVERED` | 运营人员确认派送完成 |
| `COMPLETE_LOADING` | `LOADING` | `LOADED` | 订舱、拖车、有效放行回执、PDA 拣货、五类有效照片和锁码文本全部通过服务端门禁后确认装柜完成 |
| `COMPLETE_DELIVERY` | `LOADED` | `DELIVERED` | 仅接受海外仓可信回传；国内 Admin/PDA 不提供该操作入口 |
`SMART_SPLIT` 不改变主状态，只改变预装清单子状态。预装清单子状态固定为：
@@ -36,21 +36,22 @@
待确认 → 确认中 → 已确认
```
## 三、宽松版本规则
## 三、门禁与修改规则
- 本版本不做业务强制门禁，不因为测量缺项、客户未确认、差异未处理、照片或封签不完整而阻止操作员继续操作。
- 本版本不新增异常、驳回、阻塞、取消等主状态。异常说明、差异说明和补充资料作为备注、附件或自定义节点保存。
- 各主状态下的业务资料均允许修改。修改资料不自动回退主状态，也不自动触发新的异常状态。
- 主状态不提供任意下拉框修改，只通过明确的业务操作推进；服务端仍负责身份、权限、客户归属、幂等和审计。
- 重复点击同一操作应保持幂等；已经完成的操作可以重新打开资料编辑，但不能伪造新的状态历史。
- `LOADED` 是派送完成前的稳定状态；本版本不增加“派送中”。
- `WAIT_MEASURE -> WAIT_SPLIT` 必须满足二期测量、审核和费用确认契约；客户确认和差异沟通不单独增加主状态，也不替代服务端门禁。
- `LOADING -> LOADED` 必须由服务端校验订舱完成、拖车完成、有效放行回执、PDA 拣货完成、五类证据各至少一张有效照片及锁码文本；任何一项缺失都不得推进。
- 本版本不新增异常、驳回、阻塞、取消等主状态。异常说明、差异说明和补充资料作为子状态、备注、附件或自定义节点保存。
- `LOADED` 前的业务资料可在权限和状态规则内修改；修改资料不自动回退主状态。`LOADED` 后错误统一线下人工处理，国内系统不提供在线冲正。
- 主状态不提供任意下拉框修改，只通过明确的业务操作推进；服务端负责身份、权限、客户归属、幂等、版本和审计。
- 重复提交同一操作必须保持幂等，不能伪造新的状态历史或绕过前置门禁。
- `LOADED` 是国内出仓终点；本版本不增加“派送中”，也不允许国内运营人员手工推进 `DELIVERED`。
## 四、客户确认和差异
客户确认、差异沟通和客服补充说明均为非阻断操作：
- 客户未确认时，订单仍可继续执行分柜、装柜和派送；测量完成后主状态已经是 `WAIT_SPLIT`。
- 客户提出差异后，平台可以继续分柜、装柜和派送；差异内容保留在订单时间线。
- 客户未确认时，订单仍可继续执行分柜，并在全部服务端硬门禁满足后完成装柜；测量完成后主状态已经是 `WAIT_SPLIT`。
- 客户提出差异后，平台可以继续处理分柜和装柜子流程，但差异不能替代或绕过任何状态门禁；差异内容保留在订单时间线。
- 客户确认不是独立主状态，不改变七个主状态集合。
## 五、自定义节点
@@ -68,7 +69,8 @@
| 订单 `SUBMITTED` | `PENDING_REVIEW` |
| 入库 `WAIT_MEASURE`、`MEASURING`、`MEASURE_PENDING`、`MEASURE_REJECTED` | `WAIT_MEASURE` |
| 入库 `INBOUNDED`、测量审核通过后的历史记录 | `WAIT_SPLIT`（当前主线）或保留为内部兼容值 |
| 分柜、预装、装柜、派送相关新状态 | 分别映射 `WAIT_SPLIT`、`LOADING`、`LOADED`、`DELIVERED` |
| 分柜、预装、装柜相关状态 | 分别映射 `WAIT_SPLIT`、`LOADING`、`LOADED` |
| 海外仓可信派送完成回传 | `DELIVERED`；国内内部状态或人工操作不得映射为该状态 |
`WAIT_PRICING`、`FEE_CONFIRMING`、`INBOUNDING` 等现有自动编排中间态不作为产品主状态展示；由统一订单查询层转换为当前产品阶段。
@@ -80,9 +82,9 @@
→ 仓库测量与客服确认
→ 测量完成并自动进入待分柜
→ 智能分柜并确认预装清单
→ PDA 拣货、拍照、封签
→ 装柜完成
→ 派送完成
→ 完成订舱、拖车、报关放行和 PDA 拣货
→ 五类有效照片及锁码文本通过门禁
→ 装柜完成（LOADED，国内三期终点）
```
每一段均需验证：可推进、可修改、可重复操作、操作有留痕、客户未确认不阻断，并且 Admin、Client、PDA 显示同一主状态。
后续由海外仓可信回传把 `LOADED` 推进为 `DELIVERED`，不属于国内三期验收主链。每一段均需验证：满足门禁时可推进、重复操作幂等、操作有留痕、客户未确认不额外阻断，并且 Admin、Client、PDA 显示同一主状态。
财务管理/README.md
+2 -2
View File
@@ -1,7 +1,7 @@
# 财务管理闭环盘点与范围建议
> 盘点日期：2026-08-10
> 当前状态：F0/F1 已有 Finance 服务、数据库、权限、Admin/Client 页面和基础接口；一期 11 个 P0 operation 的目标契约已冻结，实现验收只看独立 G1-G4 证据矩阵，当前四组均为 `FAIL`
> 当前状态：F0/F1 已有 Finance 服务、数据库、权限、Admin/Client 页面和基础接口；一期 11 个 P0 operation 的目标契约已冻结，本地实现验收按独立 G1-G4 证据矩阵均为 `PASS`；真实 MySQL、测试环境 HTTP 冒烟和领导页面验收仍需单独执行
> 盘点范围：二期入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现
> 结论口径：本文区分“代码已实现”“原型展示”和“建议范围”；原型功能不自动成为开发范围。
@@ -75,7 +75,7 @@
-> 客户只读查询
```
后端当前已完成 Firstleg 真实柜次体积快照、客户归属、成本凭证校验、revision、双权限上传、费用来源事件/Relay/快照、Finance `fin_fee_source` 消费写入和完整幂等；Finance 35/35、Firstleg 549/549（2 skip）、File 114/114、Gateway 26/26、IAM 163/163、Phase3/PDA SQL 12/12、Order SQL 3/3，均 BUILD SUCCESS。当前剩余是 Admin 客户账期/revision 与五页页面动作，以及 11 个目标 operation；完成《F1人工财务契约审查与门禁》剩余门禁后才能宣称一期页面闭环通过验收。
此前基础链路已完成 Firstleg 真实柜次体积快照、客户归属、成本凭证校验、revision、双权限上传、费用来源事件/Relay/快照、Finance `fin_fee_source` 消费写入和完整幂等。在此基础上，固定五页所需的 11 个目标 operation、Admin 页面动作与 IAM 权限目录现已闭环，G1-G4 本地门禁均为 `PASS`；最终直接证据包括 Finance 聚合 82/82、G3 16/16、G4 18/18、收款及 AR 同步 12/12、IAM 168/168、Admin 财务专项 60/60、Admin 全量 654/654 及 Admin 构建通过。真实 MySQL 执行、测试环境 HTTP 冒烟和领导页面验收仍需单独完成，未经当前对话明确授权不触发 Jenkins。
一期范围已重新冻结为原型 5 页：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付。费用分析、利润表、发票和钱包不做，也不保留菜单、路由或假按钮。客户账户改为账单、收款和应收应付来源派生的财务往来总览，不做充值/预收。
财务管理/财务一期P0实现证据矩阵.md
+15 -9
View File
@@ -19,8 +19,8 @@
|---|---|---|---|---|---|
| G1 客户账户 | `listDerivedCustomerAccounts`、`listDerivedCustomerAccountLedger` | 派生金额、分页筛选、日期边界、停用客户历史、跨客户隔离、固定 DTO/追踪字段测试全部通过 | 客户账户列表、筛选、详情入口、流水筛选均调用真实接口；无钱包、充值、预收或余额写入口 | 后端 G1 专项 4/4、Admin G1 专项 15/15、Finance 专项 21/21、Admin typecheck、IAM 166/166、IAM 权限契约 3/3、Finance 权限契约 2/2 通过；统一 SQL 已同步权限目录且未默认授予角色 | `PASS` |
| G2 费用来源 | `getFinanceFeeSource`、`reviewFinanceFeeSource`、`updateFeeSourceSettlementInclusion` | 详情、PENDING 审核、非法状态、expectedVersion、占用冻结、完整幂等、跨客户隐藏和 CNY 条件全部通过 | 客户应收应付页详情、审核、参与/禁止结算使用真实接口；权限和服务端错误态可见，不存在假成功 | 后端 G2 专项 9/9、Admin G2 专项 21/21、Admin typecheck/build、IAM 166/166、IAM 权限契约 3/3、Finance 权限契约 2/2 通过；统一 SQL 已同步权限目录且未默认授予角色 | `PASS` |
| G3 客户对账单 | `createReconciliationStatement`、`actionReconciliationStatement` | BY_CUTOFF/SELECTED、同客户来源、重复占用、提交/审核/出账/调整/作废/重开、revision、乐观锁和完整幂等全部通过 | 客户对账单生成及所有动作使用真实接口；出账冻结、调整历史和错误态在页面可核对 | 已观察到 Controller/Service/DTO 和同路径映射；审计时点编译失败，未发现直接行为测试或 Admin 真实接入验收 | `FAIL` |
| G4 结算与人工收付款 | `createReceivableSettlement`、`createPayableSettlement`、`getSettlement`、`createSettlementPayment`；并回归已实现 `createReceiptWithAllocations` | AR/AP 生成唯一性、方向权限、详情/revision、部分付/付清、File fail-closed、跨客户/供应商、超额、CNY、完整幂等全部通过；收款 300 元分配 3 张 100 元账单通过 | 应收/应付结算页生成、详情、人工收款/付款、凭证和状态刷新均调用真实接口；客户只读脱敏与状态过滤通过 | 已观察到四个 Controller 映射和 DTO；审计时点所引用 Service 不存在且无直接行为测试；未提供 Admin 真实接入验收 | `FAIL` |
| G3 客户对账单 | `createReconciliationStatement`、`actionReconciliationStatement` | BY_CUTOFF/SELECTED、同客户来源、重复占用、提交/审核/出账/调整/作废/重开、revision、乐观锁和完整幂等全部通过 | 客户对账单生成及所有动作使用真实接口；出账冻结、调整历史和错误态在页面可核对 | G3 后端专项 16/16、Finance 聚合 82/82、Admin 财务专项 60/60、Admin 全量 654/654、typecheck/build、IAM 168/168 通过；页面使用冻结 G3 详情 DTO，支持多行调整、驳回、作废和重开 | `PASS` |
| G4 结算与人工收付款 | `createReceivableSettlement`、`createPayableSettlement`、`getSettlement`、`createSettlementPayment`；并回归已实现 `createReceiptWithAllocations` | AR/AP 生成唯一性、方向权限、详情/revision、部分付/付清、File fail-closed、跨客户/供应商、超额、CNY、完整幂等全部通过；收款 300 元分配 3 张 100 元账单通过 | 应收/应付结算页生成、详情、人工收款/付款、凭证和状态刷新均调用真实接口；客户只读脱敏与状态过滤通过 | G4 后端专项 18/18、收款/AR 同步专项 12/12、Finance 聚合 82/82、Admin G3/G4 组件 6/6、Admin 财务专项 60/60、全量 654/654、typecheck/build、IAM 168/168 通过；供应商来自真实往来单位候选 | `PASS` |
## 3. 单项证据登记
@@ -31,12 +31,12 @@
| P0-03 | `getFinanceFeeSource` | G2 后端 9/9 通过 | Admin G2 专项 21/21、typecheck/build、IAM 权限门禁通过 | `PASS` |
| P0-04 | `reviewFinanceFeeSource` | G2 后端 9/9 通过 | Admin G2 专项 21/21、typecheck/build、IAM 权限门禁通过 | `PASS` |
| P0-05 | `updateFeeSourceSettlementInclusion` | G2 后端 9/9 通过 | Admin G2 专项 21/21、typecheck/build、IAM 权限门禁通过 | `PASS` |
| P0-06 | `createReconciliationStatement` | 待提供 | 待提供 | `FAIL` |
| P0-07 | `actionReconciliationStatement` | 待提供 | 待提供 | `FAIL` |
| P0-08 | `createReceivableSettlement` | 待提供 | 待提供 | `FAIL` |
| P0-09 | `createPayableSettlement` | 待提供 | 待提供 | `FAIL` |
| P0-10 | `getSettlement` | 待提供 | 待提供 | `FAIL` |
| P0-11 | `createSettlementPayment` | 待提供 | 待提供 | `FAIL` |
| P0-06 | `createReconciliationStatement` | G3 专项 16/16、Finance 聚合 82/82 通过 | 真实生成接口、冻结详情 GET、Admin 财务专项和全量测试通过 | `PASS` |
| P0-07 | `actionReconciliationStatement` | G3 专项覆盖状态机、revision、版本、跨客户和幂等恢复 | 提交、审核、驳回、出账、多行调整、作废和重开真实接入 | `PASS` |
| P0-08 | `createReceivableSettlement` | G4 专项覆盖正向、唯一性、CNY 和对账单状态 | 从已出账对账单真实生成；应收人工收款同步结算状态 | `PASS` |
| P0-09 | `createPayableSettlement` | G4 专项覆盖正向、跨客户、混供应商、不合格和重复占用 | 真实 PAYABLE 来源与平台往来单位供应商候选接入 | `PASS` |
| P0-10 | `getSettlement` | G4 专项覆盖方向权限、404、来源、revision 和收付款历史 | 应收/应付详情均调用冻结结算详情接口 | `PASS` |
| P0-11 | `createSettlementPayment` | G4 专项覆盖部分付、付清、超额、版本、File fail-closed 和幂等 | 图片凭证上传后调用真实付款接口并刷新状态 | `PASS` |
“待提供”不表示没有代码，只表示尚未形成满足本矩阵规则的可放行证据。目标 OpenAPI 不记录或追踪这些实现状态。
@@ -48,5 +48,11 @@
| G2 | `platform:finance:fee-source:view` | 已进入 IAM 初始化与统一 SQL，未默认授予角色；Admin 已真实接入 | IAM 166/166、IAM 权限契约 3/3、Finance 权限契约 2/2、Admin G2 专项 21/21 通过 |
| G2 | `platform:finance:fee-source:review` | 已进入 IAM 初始化与统一 SQL，未默认授予角色；Admin 已真实接入 | 同上 |
| G2 | `platform:finance:fee-source:settlement` | 已进入 IAM 初始化与统一 SQL，未默认授予角色；Admin 已真实接入 | 同上 |
| G3 | `platform:finance:reconciliation:create/review/issue/adjust/void` | 已进入 IAM 模块迁移与统一 SQL，未默认授予角色 | IAM G3/G4 权限契约 2/2、IAM 168/168 通过 |
| G4 | `platform:finance:settlement-ar:create/view`、`platform:finance:settlement-ap:create/view`、`platform:finance:payment:create` | 已进入 IAM 模块迁移与统一 SQL，未默认授予角色；收款复用既有 `platform:finance:receipt:create` | IAM G3/G4 权限契约 2/2、IAM 168/168、Admin 权限组件用例通过 |
在 IAM 模块权限目录、IAM 初始化 SQL、统一 SQL和对应 IAM 测试证据全部完成前，不因 Finance/Admin 专项测试通过而更新 G1/G2 结论。主契约保持冻结，不写入本门禁的中间状态。
在 IAM 模块权限目录、IAM 初始化 SQL、统一 SQL和对应 IAM 测试证据全部完成前，不因 Finance/Admin 专项测试通过而更新 G1-G4 结论。主契约保持冻结，不写入本门禁的中间状态。
## 5. 环境验收边界
G1-G4 的 `PASS` 表示冻结契约、源码实现、直接行为测试、Admin 真实 API 适配、页面组件测试、IAM 权限目录和统一 SQL 的本地门禁通过。真实 MySQL 执行、测试环境 Finance/Firstleg/File HTTP 冒烟和领导页面验收尚未执行，不属于本次本地 PASS 的部署证据；未经当前对话明确授权，不触发 Jenkins。