html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a18775b261620630b0eb40b3779a8f4ddffb41a5
docs/财务管理/财务核心P0操作契约与验收用例.md
T

12 KiB
Raw Blame History

财务核心 P0 操作契约与验收用例

日期：2026-08-11 适用范围：订单与客户财务闭环及后续确认的费用编辑审核、客户确认操作 状态口径：以下 11 项全部是订单与客户 P0，目标契约已冻结；实现和 Admin 接入证据只维护在 财务核心P0实现证据矩阵.md 机器契约：openapi/finance-core-five-pages-v1.yaml

1. 统一冻结规则

  • 金额只允许 CNY；请求出现其他币种或金额 <= 0 返回 FIN_400。
  • 财务操作全部由平台财务人员人工提交表单。客户只能读取自己的已出账结果，不能审核、生成、调整、作废或登记收付款。
  • 客户账户是账单、费用来源和收付款派生视图，不建设余额表，不提供钱包、预收、充值或余额调整接口。
  • 平台接口使用权限码控制。实体必须按其真实客户归属校验；同一写请求中的来源、对账单、结算单和收付款对象必须属于同一客户。跨客户对象按不存在处理，返回 FIN_404，不得泄露对象是否存在。
  • 所有写操作必须带 Idempotency-Key。请求哈希至少覆盖 method、规范化 path、目标客户、全部 query/body 字段；同键同参重放原结果，同键异参或仍在 PROCESSING 返回 FIN_409，FAILED/超时 PROCESSING 按现有 Finance 恢复规则执行。
  • 带 expectedVersion 的操作使用乐观锁；版本不一致返回 FIN_409。出账后不原地覆盖，调整、作废和重开必须新增 revision 并保留操作人、原因、时间和前后值。
  • 稳定错误码固定为：FIN_400 参数/CNY/金额错误，FIN_404 不存在或跨客户隐藏，FIN_409 状态/版本/重复占用/幂等冲突，FIN_503 File 或内部依赖不可用，FIN_001 未分类服务端错误。认证和权限拒绝使用 HTTP 401/403。
  • 所有成功和业务错误响应固定包含 requestId、traceId、timestamp；成功 body 使用 code="200"，不得返回 Entity、Map 或临时字段。

2. P0 operation 冻结矩阵

P0 operationId 请求 DTO 响应 DTO 权限 状态/隔离与核心验收
P0-01 listDerivedCustomerAccounts AccountListQuery（page/pageSize/keyword/status） AccountPageEnvelope<AccountSummary> platform:finance:account:view 聚合未收、待出账、本期已收、应付；停用客户仍保留历史金额；无钱包字段。验收 AC-01、AC-02
P0-02 listDerivedCustomerAccountLedger AccountLedgerQuery（customerId path、业务类型、日期、分页） LedgerPageEnvelope<LedgerEntry> platform:finance:account:view 只返回指定客户来源/单据/收付款派生流水；日期闭区间；跨客户对象不可混入。验收 AC-03、AC-04
P0-03 getFinanceFeeSource FeeSourceIdPath FeeSourceDetailEnvelope<FeeSourceDetail> platform:finance:customer-arap:list 返回业务关联、版本、审核、占用和操作日志；不接受前端覆盖客户或来源标识。验收 AC-05
P0-04 reviewFinanceFeeSource ReviewRequest FeeSourceDetailEnvelope<FeeSourceDetail> platform:finance:fee-source:review PENDING -> APPROVED/REJECTED；非 PENDING、旧版本、已占用均拒绝。审核通过自动发布并成为结算候选。验收 AC-06、AC-07
P0-05 editFinanceFeeSource / submitFinanceFeeSource / adjustFinanceFeeSource / voidFinanceFeeSource FeeSourceEditRequest / FeeSourceActionRequest FeeSourceDetailEnvelope<FeeSourceDetail> platform:finance:fee-source:edit DRAFT/REJECTED 可编辑并提交；APPROVED 调整回新草稿；作废保留审计。没有“是否结算”开关。验收 AC-08、AC-09
P0-06 createReconciliationStatement CreateReconciliationRequest ReconciliationDetailEnvelope<ReconciliationDetail> platform:finance:reconciliation:create 按截止日或勾选来源生成 DRAFT；来源须同客户、合格且未被有效单据占用，金额由服务端快照读取。验收 AC-10 至 AC-12
P0-07 actionReconciliationStatement ReconciliationActionRequest ReconciliationDetailEnvelope<ReconciliationDetail> 按 action 使用 review/issue/adjust/void 权限 提交、审核、出账、调整、作废、重开均走 revision；ISSUED 冻结来源，调整后总额不得低于已收。验收 AC-13 至 AC-17
P0-08 createReceivableSettlement CreateReceivableSettlementRequest SettlementDetailEnvelope<SettlementDetail> platform:finance:settlement-ar:create 只从同客户 ISSUED 对账单生成，一张有效对账单只能有一个有效应收结算单；直接进入 ISSUED。验收 AC-18、AC-19
P0-09 createPayableSettlement CreatePayableSettlementRequest SettlementDetailEnvelope<SettlementDetail> platform:finance:settlement-ap:create 同客户、同供应商的 APPROVED/PUBLISHED/AVAILABLE/CNY PAYABLE 来源生成；供应商必须 ACTIVE，非空 supplierCategory 必须匹配。直接进入 ISSUED。验收 AC-20、AC-21
P0-10 getSettlement SettlementIdPath SettlementDetailEnvelope<SettlementDetail> AR/AP view 二选一并与单据方向匹配 返回结算单、来源快照、revision 和收付款记录；没有对应方向权限时 HTTP 403。验收 AC-22、AC-23
P0-11 createSettlementPayment CreateSettlementPaymentRequest SettlementDetailEnvelope<SettlementDetail> platform:finance:payment:create 只允许 PAYABLE 的 ISSUED/PARTIALLY_PAID；金额不得超过余额，凭证 File fail-closed；更新为 PARTIALLY_PAID/PAID。验收 AC-24 至 AC-26

createReceiptWithAllocations 已实现，不计入上述 11 项，但仍属于订单与客户 P0 回归门禁：一笔 300 元收款可人工分配到同一客户 3 张各 100 元应收结算单并共用凭证；跨客户、草稿、超额、非 CNY、无有效凭证必须拒绝。

2.1 契约与证据分离

本文件不记录 Controller、编译和测试中间态，也不使用 NOT_IMPLEMENTED/IN_PROGRESS/IMPLEMENTED 标记。G1-G4 后端行为测试和 Admin 真实接入证据统一见 财务核心P0实现证据矩阵.md；开发过程不得反向修改本文件冻结的路径、DTO、状态机和验收标准。

3. 状态机

3.1 费用来源

DRAFT/REJECTED --EDIT/SUBMIT--> PENDING
PENDING --APPROVE--> APPROVED + PUBLISHED（自动成为结算候选）
PENDING --REJECT---> REJECTED
APPROVED --ADJUST--> DRAFT（新版本）
AVAILABLE --对账单占用--> LOCKED --对账单出账--> BILLED
任意未出账有效版本 --VOID--> VOIDED
AVAILABLE --上游调整新版本--> SUPERSEDED

3.2 客户对账单

DRAFT --SUBMIT--> PENDING_REVIEW
PENDING_REVIEW --APPROVE--> APPROVED
PENDING_REVIEW --REJECT--> REJECTED
REJECTED/VOIDED --REOPEN--> DRAFT（新 revision）
APPROVED --ISSUE--> ISSUED（冻结来源）
ISSUED --ADJUST--> ISSUED（新 revision，不覆盖旧版）
DRAFT/PENDING_REVIEW/APPROVED/ISSUED --VOID--> VOIDED（已收金额=0 且无有效结算单）

ADJUST 必须提交至少一条调整行和原因；新总额不得小于已收金额。VOID/REOPEN 必须填写原因。ISSUED 后普通编辑接口不存在。

客户确认状态独立于上述主状态：NOT_REQUIRED --ISSUE--> PENDING_CONFIRMATION --客户确认--> CONFIRMED；调整后重置为 PENDING_CONFIRMATION 并保留历史确认审计。

Client 列表和详情中的“确认账单”均只在待确认且当前成员拥有独立写权限 merchant:finance:statement:confirm 时展示；list/view 只读权限不能替代确认权限。真实客户管理员通过全局 MERCHANT_OWNER 权限模板获得该权限，其他客户角色按授权配置决定是否可确认。

3.3 应收/应付结算单和收付款

生成成功 -> ISSUED
ISSUED --部分收/付款--> PARTIALLY_PAID
ISSUED/PARTIALLY_PAID --收/付清--> PAID
ISSUED --VOID--> VOIDED（已收付金额=0）
VOIDED --REOPEN--> ISSUED（新 revision）

订单与客户不处理预收、多收、退款、手续费、自动银行对账或汇率折算。人工收付款只能分配到同客户、同方向、CNY 且已出账的结算单。

4. 请求字段条件

  • CreateReconciliationRequest：customerId/currency/generationMode/periodStart/periodEnd 必填；currency=CNY。SELECTED 时 feeSourceIds 至少 1 个，BY_CUTOFF 时服务端按 periodEnd 选择合格来源。
  • ReconciliationActionRequest：action/expectedVersion 必填；REJECT/ADJUST/VOID/REOPEN 时 reason 必填；ADJUST 时 adjustmentLines 至少 1 个，每行包含 statementLineId/adjustedAmount/reason。
  • CreateReceivableSettlementRequest：只提交 reconciliationStatementId/currency；客户、期间、金额和默认 30 天到期日由对账单与客户账期派生，不信任前端重复提交。
  • CreatePayableSettlementRequest：customerId/supplierId/feeSourceIds/dueDate/currency 必填；来源必须同客户、同供应商。
  • CreateSettlementPaymentRequest：transactionDate/amount/currency/method/voucherFileIds/expectedVersion 必填；currency=CNY、金额 >0、至少一张有效付款凭证。

5. 行为验收用例

用例 期望
AC-01/02 账户列表金额可由来源、已出账结算单和收付款重算；响应不存在 balance/recharge/prepayment 字段
AC-03/04 客户 A 流水不出现客户 B 单据；起止日期非法返回 FIN_400
AC-05 详情返回来源版本、业务对象和操作日志；不存在返回 FIN_404
AC-06/07 PENDING 审核成功；重复审核、旧 expectedVersion 返回 FIN_409
AC-08/09 草稿/驳回项可编辑提交，已审核项可调整，非法状态或旧版本返回 FIN_409；审核通过后自动进入结算候选
AC-10/11/12 两种生成模式成功；跨客户、非 CNY、重复占用或不合格来源分别返回 FIN_404/FIN_400/FIN_409，且不产生半成品
AC-13/14 合法提交、审核和出账按状态迁移；非法 action/state 或并发版本返回 FIN_409
AC-15/16/17 ISSUED 调整产生 revision；低于已收拒绝；有收款或有效结算单时作废拒绝；重开保留历史
AC-18/19 ISSUED 对账单生成唯一 AR；重复生成同参重放，异参或已有有效 AR 返回 FIN_409
AC-20/21 同客户同供应商 PAYABLE 来源生成 AP；混客户/供应商、已占用或非合格来源拒绝
AC-22/23 AR/AP 详情 DTO 完整；缺方向权限返回 403，不存在返回 FIN_404
AC-24/25/26 部分付款、付清状态正确；超额/重复/非 CNY/无凭证拒绝；File 不可用返回 FIN_503 且不落付款或更新余额
AC-27 已实现收款回归：300 元分配 3 张 100 元同客户应收单成功并共用凭证
AC-28 客户接口只能看到本人 ISSUED/PARTIALLY_PAID/PAID 单据和 CONFIRMED 收款，不返回凭证、内部备注、供应商成本或其他客户数据
AC-29 每个写 operation 覆盖同键同参、同键异参、PROCESSING、FAILED/超时恢复；请求哈希改变任一业务字段即视为异参

6. 验收证据更新规则

目标契约保持冻结，不跟随实现状态修改。证据矩阵中的单项或分组只有同时满足以下全部证据才允许从 FAIL 改为 PASS：

  1. Controller 存在与 OpenAPI 一致的 method/path、权限和固定 DTO。
  2. Service/Repository 实现上述状态、客户归属、CNY、幂等、版本和审计规则。
  3. 正向、非法状态、跨客户、无权限、同参重放、异参冲突和并发版本行为测试通过。
  4. 涉及凭证的操作补 File fail-closed 测试；涉及客户可见数据的操作补脱敏与状态过滤测试。
  5. 证据矩阵记录具体测试类、用例数、Admin 真实用例和最近通过结果。只有代码存在、只有编译通过或只有间接测试均不得提前标完成。
Reference in New Issue View Git Blame Copy Permalink