优化

财务管理/Firstleg-Finance跨服务契约.md

@@ -106,6 +106,7 @@ Firstleg Outbox 发布采用至少一次投递：指数退避（建议 10s、30s
 | `FIN-EVT-001` | 事件重复且内容一致 | 否，返回原结果 |
 | `FIN-EVT-002` | 事件重复但内容不同 | 否，隔离冲突 |
 | `FIN-EVT-003` | 事件版本不支持 | 否，进入 DLQ |
+| `FIN-EVT-016` | 来源版本已进入非作废对账单或结算单，禁止调整、替代或作废 | 否，保留已冻结单据并修正上游费用 |
 | `FIN-AUTH-001` | 服务令牌无效/过期 | 否 |
 | `FIN-TIME-001` | 财务期间已关闭 | 否，走调整/冲销 |
 

财务管理/openapi/finance-phase1-five-pages-v1.yaml

@@ -32,8 +32,17 @@ x-payable-cost-contract:
   paymentMethods: [ONLINE, BANK_TRANSFER, CASH, OTHER]
   onAccount: 可进入正式 PAYABLE settlement；paidAt/paymentMethod/paymentReferenceNo/paymentVoucherFileIds 必须为空
   directPaid: 必填 paidAt/paymentMethod，paymentReferenceNo 与 paymentVoucherFileIds 至少一项；只计成本，禁止进入 AP 和 outstandingPayable
-  totals: 总成本=有效ON_ACCOUNT来源+有效DIRECT_PAID成本事实；待付=正式AP outstanding；已付=AP paid+DIRECT_PAID
+  operatingFunds: 仅三类运营资金：待收客户款、待付供应商款、已线下支付供应商款；不存在客户线下支付分类，也不新增已收客户款卡片
+  outstandingReceivable: 只聚合非VOIDED正式RECEIVABLE结算单outstanding，不叠加pendingBilling；客户收款只减少该余额并保留收款历史
+  outstandingPayable: 非VOIDED正式PAYABLE结算单outstanding + 尚未进入非VOIDED AP的有效ON_ACCOUNT来源金额；按feeSourceId关联去重
+  paidSupplierAmount: 有效FIRSTLEG_DIRECT_PAID确认成本 + 非VOIDED ON_ACCOUNT AP paidAmount；明细分别标识SUPPLIER_DIRECT_PAID和SUPPLIER_ON_ACCOUNT_PAYMENT
+  totals: 总成本=有效ON_ACCOUNT来源+有效DIRECT_PAID成本事实；待付与已付按上述运营资金公式计算，作废、SUPERSEDED、部分付款和结清不得重复累计
   uniqueness: DIRECT_PAID 按 sourceSystem+sourceType+sourceFeeId+sourceVersion 唯一物化到 fin_cost，禁止与来源重复累计
+x-customer-account-ui-contract:
+  operatingCards: [outstandingReceivable, outstandingPayable, paidCost]
+  operatingCardLabels: [待收客户款, 待付供应商款, 已线下支付供应商款]
+  auxiliaryFields: [pendingBilling, receivedInPeriod, totalCost]
+  rule: 辅助字段只允许用于列表、明细或历史说明，不得生成第四类运营资金卡片；paidCost只属于供应商，禁止解释为客户线下支付。
 x-phase1-p0-contract:
   status: FROZEN
   rule: 所有已列 operation 均为当前目标契约；实现状态不得写入本文件。
@@ -81,6 +90,7 @@ paths:
         - FIN-EVT-013
         - FIN-EVT-014
         - FIN-EVT-015
+        - FIN-EVT-016
         - FIN-EVT-401
       parameters:
         - $ref: '#/components/parameters/InternalServiceToken'
@@ -181,9 +191,11 @@ paths:
       operationId: getCustomerAccountSummary
       summary: 查询客户正式结算口径财务汇总
       description: >-
-        固定 CNY。累计应收、已收和未结清仅聚合本客户非 VOIDED 的正式 RECEIVABLE
-        fin_settlement；待出账仅聚合合格且尚未进入非 VOIDED 对账单的应收费用来源；
-        未结应付仅聚合本客户非 VOIDED 的正式 PAYABLE fin_settlement。
+        固定 CNY。待收客户款只聚合本客户非 VOIDED 正式 RECEIVABLE fin_settlement 的
+        outstandingAmount，待出账只作为独立信息且不得叠加进待收。待付供应商款为非 VOIDED
+        PAYABLE fin_settlement outstandingAmount，加尚未进入非 VOIDED AP 的合格 ON_ACCOUNT
+        来源金额并按 feeSourceId 去重。paidCost 仅表示已线下支付供应商款，由有效
+        FIRSTLEG_DIRECT_PAID 确认成本与非 VOIDED ON_ACCOUNT AP paidAmount 构成。
       x-permission: platform:finance:customer-account:list
       x-customer-isolation: 所有聚合子查询都必须使用 customerId 约束，空客户返回零值。
       parameters:
@@ -867,7 +879,7 @@ components:
       enum: [UNPAID, PARTIALLY_PAID, PAID, OVERDUE]
     LedgerBusinessType:
       type: string
-      enum: [RECONCILIATION_CREATED, SETTLEMENT_ISSUED, RECEIPT, PAYMENT, ADJUSTMENT, VOID]
+      enum: [RECONCILIATION_CREATED, SETTLEMENT_ISSUED, RECEIPT, SUPPLIER_DIRECT_PAID, SUPPLIER_ON_ACCOUNT_PAYMENT, ADJUSTMENT, VOID]
     TraceMeta:
       type: object
       required: [requestId, traceId, timestamp]
@@ -891,12 +903,20 @@ components:
         customerName: {type: string}
         contactName: {type: string}
         contactPhone: {type: string}
-        outstandingReceivable: {$ref: '#/components/schemas/Money'}
-        pendingBilling: {$ref: '#/components/schemas/Money'}
+        outstandingReceivable:
+          allOf: [{$ref: '#/components/schemas/Money'}]
+          description: 待收客户款；仅正式非VOIDED应收结算单未收余额，不含待出账。
+        pendingBilling:
+          allOf: [{$ref: '#/components/schemas/Money'}]
+          description: 合格但未进入有效对账单的应收来源，仅作独立过程信息，不计入待收客户款。
         receivedInPeriod: {$ref: '#/components/schemas/Money'}
         totalCost: {$ref: '#/components/schemas/Money'}
-        paidCost: {$ref: '#/components/schemas/Money'}
-        outstandingPayable: {$ref: '#/components/schemas/Money'}
+        paidCost:
+          allOf: [{$ref: '#/components/schemas/Money'}]
+          description: 已线下支付供应商款；仅有效DIRECT_PAID确认成本与非VOIDED账期AP已付金额。
+        outstandingPayable:
+          allOf: [{$ref: '#/components/schemas/Money'}]
+          description: 待付供应商款；有效AP未付与尚未制单ON_ACCOUNT来源按feeSourceId去重后的合计。
         status: {type: string, enum: [ACTIVE, DISABLED]}
         lastChangedAt: {type: string, format: date-time}
     AccountDetail:
@@ -912,7 +932,7 @@ components:
       properties:
         customerId: {$ref: '#/components/schemas/Id'}
         currency: {type: string, enum: [CNY]}
-        accountMode: {type: string, enum: [MANUAL_RECEIVABLE_LEDGER]}
+        accountMode: {type: string, enum: [MANUAL_RECEIVABLE_LEDGER], description: 账户为人工财务操作台账；金额口径仍只取正式应收结算单。}
         totalReceivable: {$ref: '#/components/schemas/Money'}
         totalReceived: {$ref: '#/components/schemas/Money'}
         outstandingAmount: {$ref: '#/components/schemas/Money'}
@@ -927,11 +947,19 @@ components:
         currency: {type: string, enum: [CNY]}
         totalReceivable: {$ref: '#/components/schemas/Money'}
         receivedAmount: {$ref: '#/components/schemas/Money'}
-        outstandingReceivable: {$ref: '#/components/schemas/Money'}
-        pendingBilling: {$ref: '#/components/schemas/Money'}
+        outstandingReceivable:
+          allOf: [{$ref: '#/components/schemas/Money'}]
+          description: 待收客户款；仅正式非VOIDED应收结算单未收余额，不含待出账。
+        pendingBilling:
+          allOf: [{$ref: '#/components/schemas/Money'}]
+          description: 独立待出账信息，不得与outstandingReceivable相加形成运营资金卡片。
         totalCost: {$ref: '#/components/schemas/Money'}
-        paidCost: {$ref: '#/components/schemas/Money'}
-        outstandingPayable: {$ref: '#/components/schemas/Money'}
+        paidCost:
+          allOf: [{$ref: '#/components/schemas/Money'}]
+          description: 已线下支付供应商款；不存在客户线下支付含义。
+        outstandingPayable:
+          allOf: [{$ref: '#/components/schemas/Money'}]
+          description: 待付供应商款；AP outstanding加未制单有效ON_ACCOUNT来源并去重。
         asOf: {type: string, format: date-time}
         lastChangedAt: {type: string, format: date-time}
     AccountEntryRead:

财务管理/财务一期五页产品与接口验收契约.md

@@ -47,7 +47,7 @@
 
 | 页面 | 原型结构和筛选 | 一期字段 | 一期操作 | 状态与验收 |
 |---|---|---|---|---|
-| 客户账户 | 汇总卡、客户列表、账户详情、流水详情；客户名称/编号、账户状态、余额条件、流水类型和日期 | 客户基本信息、客户编号、联系人、电话、未收余额、待出账金额、本期已收金额、总成本、已付成本、待付金额、账户状态、最后变动时间；流水号、时间、业务类型、关联单据、应收/应付变动、变动后未收余额、操作人、备注 | 详情、查询、重置、导出；**无充值、扣款或余额调整** | 待付只取正式 AP outstanding；已付=AP paid+DIRECT_PAID；总成本=ON_ACCOUNT来源成本+DIRECT_PAID成本事实，不得重复累计 |
+| 客户账户 | 汇总卡、客户列表、账户详情、流水详情；客户名称/编号、账户状态、余额条件、流水类型和日期 | 客户基本信息、客户编号、联系人、电话、未收余额、待出账金额、本期已收金额、总成本、已付成本、待付金额、账户状态、最后变动时间；流水号、时间、业务类型、关联单据、应收/应付变动、变动后未收余额、操作人、备注 | 详情、查询、重置、导出；**无充值、扣款或余额调整** | 运营资金只认三类：待收客户款=正式 AR outstanding，不叠加待出账；待付供应商款=AP outstanding+未制单有效 ON_ACCOUNT 来源并按来源去重；已线下支付供应商款=AP paid+有效 DIRECT_PAID，明细区分账期付款和现场已付。不存在客户线下支付分类，也不新增已收客户款卡片 |
 | 客户应收应付 | 工具栏、组合查询、选中汇总、费用列表、费用详情、审核进度、关联业务、操作记录 | 客户、费用单号、是否已生成对账单、审核状态、应收/应付、结算方式、已付时间/方式/凭证、入仓码/柜次号、业务状态、费用类型、金额、业务发生日、来源类型、来源版本 | 详情、编辑草稿/驳回项、提交审核、审核通过/拒绝、调整、作废、按截止时间或勾选生成；不提供“是否结算”开关 | PAYABLE 必须区分 ON_ACCOUNT/DIRECT_PAID；前者可进入 AP，后者只计成本且排除 AP；同一来源版本只能识别一次成本 |
 | 客户对账单 | 查询区、主表、账单明细、支付历史；审核状态、账单编号、客户、柜次、结算起止日、是否结清、创建日期、最后收款时间 | 对账单号、客户、期间、账期、CNY、总应收、已收、未收、客户确认状态/确认人/确认时间、最后收款时间、是否结清、备注、创建/更新人时间 | 生成草稿、详情、导出、审核、出账、调整、作废；客户在 Client 确认本人已出账账单 | 主状态与客户确认状态独立；出账后 `PENDING_CONFIRMATION`，客户确认后 `CONFIRMED`，调整后重置待确认并保留历史审计 |
 | 结算单应收 | 汇总卡、筛选、列表、详情、费用明细、收款记录；收款状态、客户、结算单号 | 结算单号、客户、CNY、应收、已收、余额、关联对账单、业务期间、生成日、到期日、收款状态、制单人、状态 | 从已出账对账单生成、详情、部分收款、导出、作废/重开；不保留高级查询假入口 | 生成后直接 `ISSUED -> PARTIALLY_PAID -> PAID`；来源已在对账单阶段审核，结算单不重复增加假审批；未收款可作废，调整保留 revision |