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-11 18:43:53 +08:00
parent 60d2f8e097
commit 4521cb5218
8 changed files with 80 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
独立任务协作登记.md
+1 -1
View File
@@ -37,7 +37,7 @@
| task_id | display_name | scope | owner | status | worktree/branch | last_update | notes | | task_id | display_name | scope | owner | status | worktree/branch | last_update | notes |
|---|---|---|---|---|---|---|---| |---|---|---|---|---|---|---|---|
| 019ff034-87cb-7d32-8c93-3e8aa992b082 | 三期最终脚本与全量收口 | `baiyue-firstleg/scripts/admin-test-env-*` 状态断言、finalize实际柜次关联、定向与默认全量 | 三期总控 | active | 后端 `test` | 2026-08-11 | 因原全量任务被Finance独占而建立的唯一替代任务；修复后直接跑定向和默认全量，完成后回收到三期长期通道，不再拆分 | | 019ff034-87cb-7d32-8c93-3e8aa992b082 | 三期最终脚本与全量收口 | `baiyue-firstleg/scripts/admin-test-env-*` 状态断言、finalize实际柜次关联、定向与默认全量 | 三期总控 | completed | 后端 `test` | 2026-08-11 | `8a65f18`已推送；完整三期生产者链398/398 PASS、契约8/8、deploymentBlockers=0，已回收到三期长期通道 |
| 019fdf0a-4933-7903-8a0c-10018c379f6f | 后台真实全量测试 | `baiyue-firstleg/scripts/admin-test-env-*` 与测试环境真实 HTTP 验收 | 三期总控 | active | 后端 `test` | 2026-08-11 | 当前基线复跑与下一批 PDA batch/Admin 终验分两轮执行；禁止 mock、放宽断言或 gap 伪装 PASS | | 019fdf0a-4933-7903-8a0c-10018c379f6f | 后台真实全量测试 | `baiyue-firstleg/scripts/admin-test-env-*` 与测试环境真实 HTTP 验收 | 三期总控 | active | 后端 `test` | 2026-08-11 | 当前基线复跑与下一批 PDA batch/Admin 终验分两轮执行；禁止 mock、放宽断言或 gap 伪装 PASS |
| 019febc3-704f-7c72-8e82-dc317f69dc9b | Finance 后端与数据库 | `baiyue-firstleg/finance`、Finance 依赖的 `file/firstleg/gateway/iam` 契约、模块 SQL 与统一 SQL | 财务总控 | active | 共享工作区 | 2026-08-11 | 一期财务后端与数据库实现及专项门禁 | | 019febc3-704f-7c72-8e82-dc317f69dc9b | Finance 后端与数据库 | `baiyue-firstleg/finance`、Finance 依赖的 `file/firstleg/gateway/iam` 契约、模块 SQL 与统一 SQL | 财务总控 | active | 共享工作区 | 2026-08-11 | 一期财务后端与数据库实现及专项门禁 |
| 019febc3-7c39-7ec2-8051-a4cce8d5f104 | Finance F1 接口契约 | `docs/财务管理/` 的 OpenAPI、接口契约、门禁和状态文档 | 财务总控 | active | 共享工作区 | 2026-08-11 | 一期财务接口与验收契约 | | 019febc3-7c39-7ec2-8051-a4cce8d5f104 | Finance F1 接口契约 | `docs/财务管理/` 的 OpenAPI、接口契约、门禁和状态文档 | 财务总控 | active | 共享工作区 | 2026-08-11 | 一期财务接口与验收契约 |
财务管理/F1人工财务契约审查与门禁.md
+3 -3
View File
@@ -92,7 +92,7 @@
| D11 | 客户状态可见性 | **后端完成。** 客户账单只见 `ISSUED/PARTIALLY_PAID/PAID`；客户收款只见 `CONFIRMED`，使用 `ClientReceipt` 专用 DTO 并去除凭证、操作人和内部字段；脱敏测试通过 | 后端门禁关闭；保留跨客户与序列化回归 | | D11 | 客户状态可见性 | **后端完成。** 客户账单只见 `ISSUED/PARTIALLY_PAID/PAID`；客户收款只见 `CONFIRMED`，使用 `ClientReceipt` 专用 DTO 并去除凭证、操作人和内部字段；脱敏测试通过 | 后端门禁关闭；保留跨客户与序列化回归 |
| D12 | Finance 费用来源写入 | **后端完成。** 内部事件入口、令牌鉴权、Inbox 幂等、Firstleg 快照回查、来源写入/替代/作废均已实现；非作废事件必须 `PUBLISHED`，未发布返回 `FIN-EVT-015`；金额必须 `>0`，零/负返回 `FIN-EVT-010`；专项 10/10、Finance 全量 35/35 通过 | 后端门禁关闭；保留真实跨服务 HTTP 冒烟 | | D12 | Finance 费用来源写入 | **后端完成。** 内部事件入口、令牌鉴权、Inbox 幂等、Firstleg 快照回查、来源写入/替代/作废均已实现；非作废事件必须 `PUBLISHED`，未发布返回 `FIN-EVT-015`；金额必须 `>0`，零/负返回 `FIN-EVT-010`；专项 10/10、Finance 全量 35/35 通过 | 后端门禁关闭；保留真实跨服务 HTTP 冒烟 |
| D13 | 柜子费用来源 | **后端完成并验证。** Firstleg 已有柜子费用模型、审核/参与结算/作废、事件、Relay 和内部快照；Firstleg 相关 17/17、Finance 柜子来源消费测试通过 | 后端门禁关闭；测试环境补真实跨服务事件冒烟 | | D13 | 柜子费用来源 | **后端完成并验证。** Firstleg 已有柜子费用模型、审核/参与结算/作废、事件、Relay 和内部快照；Firstleg 相关 17/17、Finance 柜子来源消费测试通过 | 后端门禁关闭；测试环境补真实跨服务事件冒烟 |
| D14 | 一期 5 页 | **FAIL / 一期 P0 未关闭。** 部分五页固定 DTO 路径、Client 脱敏和错误码已经验证；11 个目标 operation 仍真实标记 `NOT_IMPLEMENTED`，且全部属于一期 P0，不得列为后续 | 按《财务一期P0操作契约与验收用例》逐项完成 Controller/DTO、状态机、权限、幂等、错误码、客户隔离和直接行为测试，再完成 Admin 五页端到端验收 | | D14 | 一期 5 页 | **FAIL / 一期 P0 未关闭。** 11 个目标 operation 契约已冻结；实现状态不再写入 OpenAPI 或主契约，G1-G4 证据矩阵当前均未放行 | G1-G4 分别完成组内全部后端直接行为测试和 Admin 真实接入，证据矩阵更新为 `PASS` 后再完成五页端到端验收 |
## 4. 非阻断但需锁定的契约说明 ## 4. 非阻断但需锁定的契约说明
@@ -107,7 +107,7 @@
进入前后端联调前至少满足： 进入前后端联调前至少满足：
1. D1-D8、D10-D13 已具备后端直接证据；D14 当前 FAIL，11 个 operation 全部为一期 P0，任一未完成均不得通过一期完整联调验收。 1. D1-D8、D10-D13 已具备后端直接证据；D14 当前 FAIL，G1-G4 任一组未同时通过后端行为测试与 Admin 真实接入，均不得通过一期完整联调验收。
2. D2 已固定为首期非分页数组；后续若改服务端分页须另行升级契约。 2. D2 已固定为首期非分页数组；后续若改服务端分页须另行升级契约。
3. 幂等门禁已关闭；后续写 operation 继续复用同参重放、异参冲突和恢复语义。 3. 幂等门禁已关闭；后续写 operation 继续复用同参重放、异参冲突和恢复语义。
4. Finance 集成测试覆盖：默认 30 天、CNY 拒绝、出账冻结、300 分 3 单、超额/跨客户/草稿拒绝、部分收款到收清、调整修订、已收不可作废。 4. Finance 集成测试覆盖：默认 30 天、CNY 拒绝、出账冻结、300 分 3 单、超额/跨客户/草稿拒绝、部分收款到收清、调整修订、已收不可作废。
@@ -120,6 +120,6 @@
- **当前阶段：专项修复中。** Finance、SQL、Admin 和 Client 均已有实现，不再按“未开发”管理。 - **当前阶段：专项修复中。** Finance、SQL、Admin 和 Client 均已有实现，不再按“未开发”管理。
- **可继续开发：是。** 11 个 P0 的路径、权限、DTO、状态、凭证、幂等、错误码和客户隔离已经冻结，不再需要新增产品决策。 - **可继续开发：是。** 11 个 P0 的路径、权限、DTO、状态、凭证、幂等、错误码和客户隔离已经冻结，不再需要新增产品决策。
- **可进行接口冒烟：有条件。** 可验证现有路径、鉴权和基础创建/查询，但结果不代表业务验收通过。 - **可进行接口冒烟：有条件。** 可验证现有路径、鉴权和基础创建/查询，但结果不代表业务验收通过。
- **可进入完整联调验收：否。** Finance 来源写入及 `PUBLISHED + amount>0`、现有查询 DTO、完整幂等、File fail-closed、客户脱敏、稳定错误码和柜子来源已经通过后端测试；11 个 P0 operation、Admin 五页接入和真实跨服务冒烟未完成。11 个 P0 不得降级为后续事项。 - **可进入完整联调验收：否。** Finance 来源写入等既有门禁已通过；11 个 P0 的 G1-G4 证据矩阵尚未全部 `PASS`，Admin 五页真实接入和跨服务冒烟也未完成。开发中间态不改变该结论。
本次审查只修订文档与 OpenAPI，未修改 Java、前端或 SQL。 本次审查只修订文档与 OpenAPI，未修改 Java、前端或 SQL。
财务管理/README.md
+4 -1
View File
@@ -1,7 +1,7 @@
# 财务管理闭环盘点与范围建议 # 财务管理闭环盘点与范围建议
> 盘点日期：2026-08-10 > 盘点日期：2026-08-10
> 当前状态：F0/F1 已有 Finance 服务、数据库、权限、Admin/Client 页面和基础接口；费用来源主链、固定 DTO、脱敏、凭证 fail-closed 和稳定错误码已通过后端验证；尚未实现的 11 个 operation 全部属于一期 P0 阻断，不得排到后续 > 当前状态：F0/F1 已有 Finance 服务、数据库、权限、Admin/Client 页面和基础接口；一期 11 个 P0 operation 的目标契约已冻结，实现验收只看独立 G1-G4 证据矩阵，当前四组均为 `FAIL`
> 盘点范围：二期入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现 > 盘点范围：二期入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现
> 结论口径：本文区分“代码已实现”“原型展示”和“建议范围”；原型功能不自动成为开发范围。 > 结论口径：本文区分“代码已实现”“原型展示”和“建议范围”；原型功能不自动成为开发范围。
@@ -17,6 +17,8 @@
一期 11 个 P0 操作、状态机与验收用例：[财务一期 P0 操作契约与验收用例](财务一期P0操作契约与验收用例.md)。 一期 11 个 P0 操作、状态机与验收用例：[财务一期 P0 操作契约与验收用例](财务一期P0操作契约与验收用例.md)。
一期实现与 Admin 接入证据（不反向修改目标契约）：[财务一期 P0 实现证据矩阵](财务一期P0实现证据矩阵.md)。
文档优先级：五页验收契约和本轮产品确认 > 五页目标 OpenAPI > 既有人工 F1 契约/门禁 > 领域模型、历史全量规划和迁移文档。旧文档用于追溯，不得据此把钱包、充值、发票、费用分析或利润表重新纳入一期。 文档优先级：五页验收契约和本轮产品确认 > 五页目标 OpenAPI > 既有人工 F1 契约/门禁 > 领域模型、历史全量规划和迁移文档。旧文档用于追溯，不得据此把钱包、充值、发票、费用分析或利润表重新纳入一期。
旧文档降级规则： 旧文档降级规则：
@@ -38,6 +40,7 @@
- [财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md) - [财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md)
- [财务一期五页 OpenAPI](openapi/finance-phase1-five-pages-v1.yaml) - [财务一期五页 OpenAPI](openapi/finance-phase1-five-pages-v1.yaml)
- [财务一期 P0 操作契约与验收用例](财务一期P0操作契约与验收用例.md) - [财务一期 P0 操作契约与验收用例](财务一期P0操作契约与验收用例.md)
- [财务一期 P0 实现证据矩阵](财务一期P0实现证据矩阵.md)
- [财务历史迁移与上线验收方案](财务历史迁移与上线验收方案.md) - [财务历史迁移与上线验收方案](财务历史迁移与上线验收方案.md)
- [财务F0实施任务拆分](财务F0实施任务拆分.md) - [财务F0实施任务拆分](财务F0实施任务拆分.md)
财务管理/openapi/finance-phase1-five-pages-v1.yaml
+18 -42
View File
@@ -5,9 +5,8 @@ info:
description: >- description: >-
一期领导验收 5 页目标契约：客户账户、客户应收应付、客户对账单、结算单应收、 一期领导验收 5 页目标契约：客户账户、客户应收应付、客户对账单、结算单应收、
结算单应付。只支持 CNY。费用分析、利润表、钱包、预收和充值不属于本契约。 结算单应付。只支持 CNY。费用分析、利润表、钱包、预收和充值不属于本契约。
每个 operation 通过 x-implementation-status 标记当前 Java 实现事实；NOT_IMPLEMENTED 本文件只冻结一期目标契约，不记录开发中间态或测试进度。11 个 P0 operation 的实现与
代表一期 P0 尚未落地，不得排到后续、生成按钮或模拟成功入口。只有 Controller/DTO Admin 接入证据单独维护在财务一期P0实现证据矩阵.md，不得因代码文件出现反复修改本契约。
与直接行为测试均提供证据后，才允许逐项改为 IMPLEMENTED。
servers: servers:
- url: /api - url: /api
x-product-scope: x-product-scope:
@@ -28,15 +27,12 @@ x-product-scope:
x-source-gate: x-source-gate:
eligible: APPROVED + PUBLISHED + settlementIncluded=true + ACTIVE + CNY eligible: APPROVED + PUBLISHED + settlementIncluded=true + ACTIVE + CNY
currentStatus: Finance 已显式校验非作废事件 PUBLISHED、APPROVED、参与结算、CNY、amount>0、客户/版本/方向/来源归属；Inbox 幂等及 fin_fee_source 写入/替代/作废均已验证。 currentStatus: Finance 已显式校验非作废事件 PUBLISHED、APPROVED、参与结算、CNY、amount>0、客户/版本/方向/来源归属；Inbox 幂等及 fin_fee_source 写入/替代/作废均已验证。
x-current-verification: x-phase1-p0-contract:
checkedAt: '2026-08-11' status: FROZEN
source: 当前 baiyue-firstleg 工作树中的 Controller、DTO、Service、Client 和现有 Surefire 报告。 operationCount: 11
testStatus: 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；来源消费专项 10/10。 rule: 11 个 operation 均为一期 P0 目标契约；实现状态不得写入本文件。
x-phase1-p0-gate:
status: FAIL
notImplementedOperations: 11
rule: 11 个 operation 均为一期 P0；必须有一致的 Controller/固定 DTO/权限/状态机/客户隔离/幂等及直接行为测试证据，方可逐项改为 IMPLEMENTED。
contract: ../财务一期P0操作契约与验收用例.md contract: ../财务一期P0操作契约与验收用例.md
evidenceMatrix: ../财务一期P0实现证据矩阵.md
x-idempotency-contract: x-idempotency-contract:
scope: method + normalizedPath + resolvedCustomerId + completeQueryAndBody scope: method + normalizedPath + resolvedCustomerId + completeQueryAndBody
sameKeySameRequest: replay original result sameKeySameRequest: replay original result
@@ -62,8 +58,6 @@ paths:
使用内部服务令牌鉴权；按 eventId 和完整事件请求哈希幂等消费，回查 Firstleg 使用内部服务令牌鉴权；按 eventId 和完整事件请求哈希幂等消费，回查 Firstleg
入库或柜子费用快照，校验客户、版本、审核、参与结算、CNY、方向和来源类型后， 入库或柜子费用快照，校验客户、版本、审核、参与结算、CNY、方向和来源类型后，
写入 fin_inbox_event 与 fin_fee_source。调整新增版本并替代旧 AVAILABLE 版本，作废只改状态不删除历史。 写入 fin_inbox_event 与 fin_fee_source。调整新增版本并替代旧 AVAILABLE 版本，作废只改状态不删除历史。
x-implementation-status: IMPLEMENTED
x-test-evidence: FinanceFeeSourceEventServiceTest 10/10、InternalFinanceFeeSourceControllerTest 2/2、Finance 全量 35/35 BUILD SUCCESS；Firstleg 相关事件/Relay/快照定向测试 17/17
x-authentication: X-Internal-Service-Token x-authentication: X-Internal-Service-Token
x-error-codes: x-error-codes:
- FIN-EVT-001 - FIN-EVT-001
@@ -103,7 +97,7 @@ paths:
operationId: listDerivedCustomerAccounts operationId: listDerivedCustomerAccounts
summary: 查询客户财务账户派生汇总 summary: 查询客户财务账户派生汇总
description: 只读聚合，不返回钱包余额，不提供充值或余额调整动作。 description: 只读聚合，不返回钱包余额，不提供充值或余额调整动作。
x-implementation-status: NOT_IMPLEMENTED x-contract-status: FROZEN
x-delivery-priority: PHASE1_P0 x-delivery-priority: PHASE1_P0
x-request-dto: AccountListQuery x-request-dto: AccountListQuery
x-response-dto: AccountPageEnvelope x-response-dto: AccountPageEnvelope
@@ -130,8 +124,6 @@ paths:
get: get:
operationId: getDerivedCustomerAccount operationId: getDerivedCustomerAccount
summary: 查询客户财务账户详情 summary: 查询客户财务账户详情
x-implementation-status: IMPLEMENTED
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；fivePlatformPageMethodsUseTypedQueryFacade 覆盖该委托
x-permission: platform:finance:bill:view x-permission: platform:finance:bill:view
parameters: parameters:
- $ref: '#/components/parameters/CustomerId' - $ref: '#/components/parameters/CustomerId'
@@ -142,7 +134,7 @@ paths:
get: get:
operationId: listDerivedCustomerAccountLedger operationId: listDerivedCustomerAccountLedger
summary: 查询客户财务派生流水 summary: 查询客户财务派生流水
x-implementation-status: NOT_IMPLEMENTED x-contract-status: FROZEN
x-delivery-priority: PHASE1_P0 x-delivery-priority: PHASE1_P0
x-request-dto: AccountLedgerQuery x-request-dto: AccountLedgerQuery
x-response-dto: LedgerPageEnvelope x-response-dto: LedgerPageEnvelope
@@ -174,8 +166,6 @@ paths:
get: get:
operationId: listFinanceFeeSources operationId: listFinanceFeeSources
summary: 查询客户应收应付费用来源池 summary: 查询客户应收应付费用来源池
x-implementation-status: IMPLEMENTED
x-test-evidence: FinanceReadApiBehaviorTest 3/3、FinanceFeePoolDirectionBehaviorTest 2/2 通过
x-permission: platform:finance:bill:view x-permission: platform:finance:bill:view
parameters: parameters:
- name: customerId - name: customerId
@@ -191,7 +181,7 @@ paths:
get: get:
operationId: getFinanceFeeSource operationId: getFinanceFeeSource
summary: 查询费用来源详情、业务关联和操作记录 summary: 查询费用来源详情、业务关联和操作记录
x-implementation-status: NOT_IMPLEMENTED x-contract-status: FROZEN
x-delivery-priority: PHASE1_P0 x-delivery-priority: PHASE1_P0
x-request-dto: FeeSourceIdPath x-request-dto: FeeSourceIdPath
x-response-dto: FeeSourceDetailEnvelope x-response-dto: FeeSourceDetailEnvelope
@@ -211,7 +201,7 @@ paths:
post: post:
operationId: reviewFinanceFeeSource operationId: reviewFinanceFeeSource
summary: 审核费用来源 summary: 审核费用来源
x-implementation-status: NOT_IMPLEMENTED x-contract-status: FROZEN
x-delivery-priority: PHASE1_P0 x-delivery-priority: PHASE1_P0
x-request-dto: ReviewRequest x-request-dto: ReviewRequest
x-response-dto: FeeSourceDetailEnvelope x-response-dto: FeeSourceDetailEnvelope
@@ -239,7 +229,7 @@ paths:
put: put:
operationId: updateFeeSourceSettlementInclusion operationId: updateFeeSourceSettlementInclusion
summary: 设置参与结算或禁止结算 summary: 设置参与结算或禁止结算
x-implementation-status: NOT_IMPLEMENTED x-contract-status: FROZEN
x-delivery-priority: PHASE1_P0 x-delivery-priority: PHASE1_P0
x-request-dto: SettlementInclusionRequest x-request-dto: SettlementInclusionRequest
x-response-dto: FeeSourceDetailEnvelope x-response-dto: FeeSourceDetailEnvelope
@@ -267,8 +257,6 @@ paths:
get: get:
operationId: listReconciliationStatements operationId: listReconciliationStatements
summary: 查询客户对账单 summary: 查询客户对账单
x-implementation-status: IMPLEMENTED
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；fivePlatformPageMethodsUseTypedQueryFacade 覆盖该委托
x-permission: platform:finance:bill:view x-permission: platform:finance:bill:view
parameters: parameters:
- name: customerId - name: customerId
@@ -280,7 +268,7 @@ paths:
post: post:
operationId: createReconciliationStatement operationId: createReconciliationStatement
summary: 按截止时间或勾选来源生成客户对账单草稿 summary: 按截止时间或勾选来源生成客户对账单草稿
x-implementation-status: NOT_IMPLEMENTED x-contract-status: FROZEN
x-delivery-priority: PHASE1_P0 x-delivery-priority: PHASE1_P0
x-request-dto: CreateReconciliationRequest x-request-dto: CreateReconciliationRequest
x-response-dto: ReconciliationDetailEnvelope x-response-dto: ReconciliationDetailEnvelope
@@ -307,8 +295,6 @@ paths:
get: get:
operationId: getReconciliationStatement operationId: getReconciliationStatement
summary: 查询客户对账单详情、费用明细和支付历史 summary: 查询客户对账单详情、费用明细和支付历史
x-implementation-status: IMPLEMENTED
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；客户详情隔离与固定 DTO 行为有直接覆盖
x-permission: platform:finance:bill:view x-permission: platform:finance:bill:view
parameters: parameters:
- $ref: '#/components/parameters/BillId' - $ref: '#/components/parameters/BillId'
@@ -319,7 +305,7 @@ paths:
post: post:
operationId: actionReconciliationStatement operationId: actionReconciliationStatement
summary: 提交、审核、出账、调整、作废或重开客户对账单 summary: 提交、审核、出账、调整、作废或重开客户对账单
x-implementation-status: NOT_IMPLEMENTED x-contract-status: FROZEN
x-delivery-priority: PHASE1_P0 x-delivery-priority: PHASE1_P0
x-request-dto: ReconciliationActionRequest x-request-dto: ReconciliationActionRequest
x-response-dto: ReconciliationDetailEnvelope x-response-dto: ReconciliationDetailEnvelope
@@ -354,8 +340,6 @@ paths:
get: get:
operationId: listReceivableSettlements operationId: listReceivableSettlements
summary: 查询结算单应收 summary: 查询结算单应收
x-implementation-status: IMPLEMENTED
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；fivePlatformPageMethodsUseTypedQueryFacade 覆盖该委托
x-permission: platform:finance:bill:view x-permission: platform:finance:bill:view
parameters: parameters:
- name: customerId - name: customerId
@@ -367,7 +351,7 @@ paths:
post: post:
operationId: createReceivableSettlement operationId: createReceivableSettlement
summary: 从审核通过的客户对账单生成应收结算单 summary: 从审核通过的客户对账单生成应收结算单
x-implementation-status: NOT_IMPLEMENTED x-contract-status: FROZEN
x-delivery-priority: PHASE1_P0 x-delivery-priority: PHASE1_P0
x-request-dto: CreateReceivableSettlementRequest x-request-dto: CreateReceivableSettlementRequest
x-response-dto: SettlementDetailEnvelope x-response-dto: SettlementDetailEnvelope
@@ -394,8 +378,6 @@ paths:
get: get:
operationId: listPayableSettlements operationId: listPayableSettlements
summary: 查询结算单应付 summary: 查询结算单应付
x-implementation-status: IMPLEMENTED
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；fivePlatformPageMethodsUseTypedQueryFacade 覆盖该委托
x-permission: platform:finance:cost:view x-permission: platform:finance:cost:view
parameters: parameters:
- name: customerId - name: customerId
@@ -407,7 +389,7 @@ paths:
post: post:
operationId: createPayableSettlement operationId: createPayableSettlement
summary: 从审核通过且参与结算的应付来源生成应付结算单 summary: 从审核通过且参与结算的应付来源生成应付结算单
x-implementation-status: NOT_IMPLEMENTED x-contract-status: FROZEN
x-delivery-priority: PHASE1_P0 x-delivery-priority: PHASE1_P0
x-request-dto: CreatePayableSettlementRequest x-request-dto: CreatePayableSettlementRequest
x-response-dto: SettlementDetailEnvelope x-response-dto: SettlementDetailEnvelope
@@ -434,8 +416,6 @@ paths:
get: get:
operationId: listPlatformReceipts operationId: listPlatformReceipts
summary: 平台按客户查询人工收款记录 summary: 平台按客户查询人工收款记录
x-implementation-status: IMPLEMENTED
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；PlatformReceipt 固定 DTO 与客户范围委托已验证
x-permission: platform:finance:receipt:view x-permission: platform:finance:receipt:view
parameters: parameters:
- name: customerId - name: customerId
@@ -451,8 +431,6 @@ paths:
收款总额必须等于 allocations 金额之和；所有结算单必须属于同一客户且为 CNY， 收款总额必须等于 allocations 金额之和；所有结算单必须属于同一客户且为 CNY，
每笔分配不得超过对应未收余额。示例：收款 300 元可分配到 3 张结算单各 100 元， 每笔分配不得超过对应未收余额。示例：收款 300 元可分配到 3 张结算单各 100 元，
共用同一组收款凭证图片。File 校验失败或不可用时必须 fail-closed，不得落库。 共用同一组收款凭证图片。File 校验失败或不可用时必须 fail-closed，不得落库。
x-implementation-status: IMPLEMENTED
x-test-evidence: FinanceServiceValidationTest 10/10、PlatformFinanceControllerBehaviorTest 2/2 通过；覆盖多账单分配和凭证 fail-closed
x-permission: platform:finance:receipt:create x-permission: platform:finance:receipt:create
parameters: parameters:
- $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IdempotencyKey'
@@ -469,8 +447,6 @@ paths:
operationId: listClientVisibleReceipts operationId: listClientVisibleReceipts
summary: 客户只读查询已确认收款和账单分配 summary: 客户只读查询已确认收款和账单分配
description: 使用登录客户身份隔离，不接收 customerId；不返回凭证、操作人、内部备注或 tenantId。 description: 使用登录客户身份隔离，不接收 customerId；不返回凭证、操作人、内部备注或 tenantId。
x-implementation-status: IMPLEMENTED
x-test-evidence: FinanceReadApiBehaviorTest 3/3 通过；ClientReceipt 脱敏序列化和登录客户隔离有直接覆盖
x-permission: merchant:finance:statement:view x-permission: merchant:finance:statement:view
responses: responses:
'200': {$ref: '#/components/responses/ClientReceiptListReadResponse'} '200': {$ref: '#/components/responses/ClientReceiptListReadResponse'}
@@ -478,7 +454,7 @@ paths:
get: get:
operationId: getSettlement operationId: getSettlement
summary: 查询应收或应付结算单详情 summary: 查询应收或应付结算单详情
x-implementation-status: NOT_IMPLEMENTED x-contract-status: FROZEN
x-delivery-priority: PHASE1_P0 x-delivery-priority: PHASE1_P0
x-request-dto: SettlementIdPath x-request-dto: SettlementIdPath
x-response-dto: SettlementDetailEnvelope x-response-dto: SettlementDetailEnvelope
@@ -500,7 +476,7 @@ paths:
post: post:
operationId: createSettlementPayment operationId: createSettlementPayment
summary: 人工登记应付结算单付款并上传凭证 summary: 人工登记应付结算单付款并上传凭证
x-implementation-status: NOT_IMPLEMENTED x-contract-status: FROZEN
x-delivery-priority: PHASE1_P0 x-delivery-priority: PHASE1_P0
x-request-dto: CreateSettlementPaymentRequest x-request-dto: CreateSettlementPaymentRequest
x-response-dto: SettlementDetailEnvelope x-response-dto: SettlementDetailEnvelope
财务管理/财务一期P0实现证据矩阵.md
+42
View File
@@ -0,0 +1,42 @@
# 财务一期 P0 实现证据矩阵
> 日期：2026-08-11
> 目标契约：`openapi/finance-phase1-five-pages-v1.yaml`、`财务一期P0操作契约与验收用例.md`
> 使用规则：本文件只记录验收证据，不反向修改目标契约；Controller 文件、编译成功或开发中间态均不能单独关闭门禁
## 1. 状态更新规则
每个分组只使用两种验收结论：
- `FAIL`：后端直接行为测试或 Admin 真实接口接入任一未通过、未提供或不可复核。
- `PASS`：组内所有 operation 的后端正向/错误态/权限/客户隔离/幂等行为测试全部通过，并且 Admin 已使用真实接口完成对应页面操作验收。
代码文件出现、Controller 映射存在、能够编译、间接测试通过、模拟接口成功均只能写入“观察记录”，不能把 `FAIL` 改为 `PASS`。证据更新时必须记录提交或工作树快照、测试类、通过数量、Admin 用例和日期。
## 2. G1-G4 稳定验收表
| 分组 | 一期 P0 operation | 后端行为测试放行条件 | Admin 真实接入放行条件 | 当前可复核证据 | 结论 |
|---|---|---|---|---|---|
| G1 客户账户 | `listDerivedCustomerAccounts`、`listDerivedCustomerAccountLedger` | 派生金额、分页筛选、日期边界、停用客户历史、跨客户隔离、固定 DTO/追踪字段测试全部通过 | 客户账户列表、筛选、详情入口、流水筛选均调用真实接口；无钱包、充值、预收或余额写入口 | 已观察到同路径 Controller/Service/DTO；所在测试集当前 5 run、1 failure、1 error，不能作为通过证据；未提供 Admin 真实接入验收 | `FAIL` |
| G2 费用来源 | `getFinanceFeeSource`、`reviewFinanceFeeSource`、`updateFeeSourceSettlementInclusion` | 详情、PENDING 审核、非法状态、expectedVersion、占用冻结、完整幂等、跨客户隐藏和 CNY 条件全部通过 | 客户应收应付页详情、审核、参与/禁止结算使用真实接口；权限和服务端错误态可见，不存在假成功 | 已观察到同路径 Controller/Service/DTO；`FinancePhase1OperationBehaviorTest` 当前 5 run、1 failure、1 error，不能作为通过证据；未提供 Admin 真实接入验收 | `FAIL` |
| 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` |
## 3. 单项证据登记
| P0 | operationId | 后端测试证据 | Admin 验收证据 | 最终状态 |
|---|---|---|---|---|
| P0-01 | `listDerivedCustomerAccounts` | 待提供 | 待提供 | `FAIL` |
| P0-02 | `listDerivedCustomerAccountLedger` | 待提供 | 待提供 | `FAIL` |
| P0-03 | `getFinanceFeeSource` | 待提供 | 待提供 | `FAIL` |
| P0-04 | `reviewFinanceFeeSource` | 待提供 | 待提供 | `FAIL` |
| P0-05 | `updateFeeSourceSettlementInclusion` | 待提供 | 待提供 | `FAIL` |
| P0-06 | `createReconciliationStatement` | 待提供 | 待提供 | `FAIL` |
| P0-07 | `actionReconciliationStatement` | 待提供 | 待提供 | `FAIL` |
| P0-08 | `createReceivableSettlement` | 待提供 | 待提供 | `FAIL` |
| P0-09 | `createPayableSettlement` | 待提供 | 待提供 | `FAIL` |
| P0-10 | `getSettlement` | 待提供 | 待提供 | `FAIL` |
| P0-11 | `createSettlementPayment` | 待提供 | 待提供 | `FAIL` |
“待提供”不表示没有代码，只表示尚未形成满足本矩阵规则的可放行证据。目标 OpenAPI 不记录或追踪这些实现状态。
财务管理/财务一期P0操作契约与验收用例.md
+8 -5
View File
@@ -2,7 +2,7 @@
> 日期：2026-08-11 > 日期：2026-08-11
> 适用范围：一期 5 页闭环中尚未实现的 11 个 operation > 适用范围：一期 5 页闭环中尚未实现的 11 个 operation
> 状态口径：以下 11 项全部是一期 P0；只有 Controller/DTO 已落地且直接行为测试通过后，才能逐项把 OpenAPI 的 `NOT_IMPLEMENTED` 改为 `IMPLEMENTED` > 状态口径：以下 11 项全部是一期 P0，目标契约已冻结；实现和 Admin 接入证据只维护在 `财务一期P0实现证据矩阵.md`
> 机器契约：`openapi/finance-phase1-five-pages-v1.yaml` > 机器契约：`openapi/finance-phase1-five-pages-v1.yaml`
## 1. 统一冻结规则 ## 1. 统一冻结规则
@@ -34,6 +34,10 @@
`createReceiptWithAllocations` 已实现，不计入上述 11 项，但仍属于一期 P0 回归门禁：一笔 300 元收款可人工分配到同一客户 3 张各 100 元应收结算单并共用凭证；跨客户、草稿、超额、非 CNY、无有效凭证必须拒绝。 `createReceiptWithAllocations` 已实现，不计入上述 11 项，但仍属于一期 P0 回归门禁：一笔 300 元收款可人工分配到同一客户 3 张各 100 元应收结算单并共用凭证；跨客户、草稿、超额、非 CNY、无有效凭证必须拒绝。
### 2.1 契约与证据分离
本文件不记录 Controller、编译和测试中间态，也不使用 `NOT_IMPLEMENTED/IN_PROGRESS/IMPLEMENTED` 标记。G1-G4 后端行为测试和 Admin 真实接入证据统一见 `财务一期P0实现证据矩阵.md`；开发过程不得反向修改本文件冻结的路径、DTO、状态机和验收标准。
## 3. 状态机 ## 3. 状态机
### 3.1 费用来源 ### 3.1 费用来源
@@ -102,13 +106,12 @@ VOIDED --REOPEN--> ISSUED（新 revision）
| AC-28 | 客户接口只能看到本人 `ISSUED/PARTIALLY_PAID/PAID` 单据和 `CONFIRMED` 收款，不返回凭证、内部备注、供应商成本或其他客户数据 | | AC-28 | 客户接口只能看到本人 `ISSUED/PARTIALLY_PAID/PAID` 单据和 `CONFIRMED` 收款，不返回凭证、内部备注、供应商成本或其他客户数据 |
| AC-29 | 每个写 operation 覆盖同键同参、同键异参、PROCESSING、FAILED/超时恢复；请求哈希改变任一业务字段即视为异参 | | AC-29 | 每个写 operation 覆盖同键同参、同键异参、PROCESSING、FAILED/超时恢复；请求哈希改变任一业务字段即视为异参 |
## 6. 实现状态更新规则 ## 6. 验收证据更新规则
每个 operation 必须同时满足以下证据，才允许把 `x-implementation-status` 从 `NOT_IMPLEMENTED` 改为 `IMPLEMENTED`： 目标契约保持冻结，不跟随实现状态修改。证据矩阵中的单项或分组只有同时满足以下全部证据才允许从 `FAIL` 改为 `PASS`：
1. Controller 存在与 OpenAPI 一致的 method/path、权限和固定 DTO。 1. Controller 存在与 OpenAPI 一致的 method/path、权限和固定 DTO。
2. Service/Repository 实现上述状态、客户归属、CNY、幂等、版本和审计规则。 2. Service/Repository 实现上述状态、客户归属、CNY、幂等、版本和审计规则。
3. 正向、非法状态、跨客户、无权限、同参重放、异参冲突和并发版本行为测试通过。 3. 正向、非法状态、跨客户、无权限、同参重放、异参冲突和并发版本行为测试通过。
4. 涉及凭证的操作补 File fail-closed 测试；涉及客户可见数据的操作补脱敏与状态过滤测试。 4. 涉及凭证的操作补 File fail-closed 测试；涉及客户可见数据的操作补脱敏与状态过滤测试。
5. 文档记录具体测试类、用例数和最近通过结果。只有代码存在、只有编译通过或只有间接测试均不得提前标完成。 5. 证据矩阵记录具体测试类、用例数、Admin 真实用例和最近通过结果。只有代码存在、只有编译通过或只有间接测试均不得提前标完成。
财务管理/财务一期五页产品与接口验收契约.md
+3 -3
View File
@@ -1,12 +1,12 @@
# 财务一期五页产品与接口验收契约 # 财务一期五页产品与接口验收契约
> 日期：2026-08-11 > 日期：2026-08-11
> 状态：产品范围已确认；Finance 来源链与部分五页查询契约已实现并验证；当前 11 个 `NOT_IMPLEMENTED` operation 全部为一期 P0 阻断，禁止排到后续 > 状态：产品范围已确认；一期 11 个 P0 operation 的目标契约已冻结；实现与 Admin 接入只按独立 G1-G4 证据矩阵验收，当前未放行
> 领导验收范围：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付 > 领导验收范围：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付
> 原型依据：`docs/悦/货代SAAS平台后台/货代SaaS平台原型.html` > 原型依据：`docs/悦/货代SAAS平台后台/货代SaaS平台原型.html`
> 目标 OpenAPI：`openapi/finance-phase1-five-pages-v1.yaml`；当前人工接口继续参考 `openapi/finance-f1-manual-v1.yaml`。 > 目标 OpenAPI：`openapi/finance-phase1-five-pages-v1.yaml`；当前人工接口继续参考 `openapi/finance-f1-manual-v1.yaml`。
> 11 个 P0 操作的 DTO、状态机、权限、幂等、错误码、隔离和验收用例以 `财务一期P0操作契约与验收用例.md` 为准。 > 11 个 P0 操作的 DTO、状态机、权限、幂等、错误码、隔离和验收用例以 `财务一期P0操作契约与验收用例.md` 为准；实现证据只维护在 `财务一期P0实现证据矩阵.md`。
## 1. 一期范围结论 ## 1. 一期范围结论
@@ -63,7 +63,7 @@
| 结算单应收 | 后端已新增 `/receivable-settlements` 固定读 DTO 路径；`fin_bill + fin_receipt` 已有人工状态能力 | 关联审核通过的客户对账单，按原型结构形成应收结算页 | IN_PROGRESS/P0 适配 | | 结算单应收 | 后端已新增 `/receivable-settlements` 固定读 DTO 路径；`fin_bill + fin_receipt` 已有人工状态能力 | 关联审核通过的客户对账单，按原型结构形成应收结算页 | IN_PROGRESS/P0 适配 |
| 结算单应付 | 后端已新增 `/payable-settlements` 固定读 DTO 路径并读取人工成本；付款单和完整供应商来源池仍缺失 | 从真实 PAYABLE 来源生成，审核后人工登记付款与凭证 | IN_PROGRESS/P0 | | 结算单应付 | 后端已新增 `/payable-settlements` 固定读 DTO 路径并读取人工成本；付款单和完整供应商来源池仍缺失 | 从真实 PAYABLE 来源生成，审核后人工登记付款与凭证 | IN_PROGRESS/P0 |
Finance 来源写入不再是阻断：内部事件入口、Inbox 幂等、Firstleg 入库/柜子快照、`fin_fee_source` 新版本写入/替代/作废、`PUBLISHED + amount>0` 入池校验、部分五页固定 DTO、完整幂等、File fail-closed、Client 脱敏和稳定错误码均已实现并通过测试。当前 11 个目标 operation 是一期 P0，不是可延期的“剩余优化”；此外还需完成 Admin 五页接入和测试环境跨服务冒烟。 Finance 来源写入不再是阻断：内部事件入口、Inbox 幂等、Firstleg 入库/柜子快照、`fin_fee_source` 新版本写入/替代/作废、`PUBLISHED + amount>0` 入池校验、部分五页固定 DTO、完整幂等、File fail-closed、Client 脱敏和稳定错误码均已实现并通过测试。11 个 P0 operation 不在本契约记录开发中间态；是否放行只看 G1-G4 后端行为测试与 Admin 真实接入证据。
## 4. 费用来源到结算全链路 ## 4. 费用来源到结算全链路
财务管理/财务开工门禁与F0-F1任务清单.md
+1 -1
View File
@@ -48,7 +48,7 @@ G0 允许：完善 API/OpenAPI、数据库迁移草案、契约测试样例、
当前按以下冻结口径修复和补测： 当前按以下冻结口径修复和补测：
- `财务一期P0操作契约与验收用例.md` 中的 11 个 operation 全部为一期 P0；任一项仍为 `NOT_IMPLEMENTED` 时，G2 不得关闭，也不得写入后续排期； - `财务一期P0操作契约与验收用例.md` 中的 11 个 operation 全部为一期 P0；目标契约不跟随开发中间态修改，G1-G4 证据矩阵任一组未同时通过后端行为测试和 Admin 真实接入时均不得关闭；
- 账单聚合维度（首期固定 RMB/CNY）和账期计算规则冻结； - 账单聚合维度（首期固定 RMB/CNY）和账期计算规则冻结；
- 平台出账、关闭、重开和线下异议录入状态冻结；客户首期只读； - 平台出账、关闭、重开和线下异议录入状态冻结；客户首期只读；