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

@@ -1,8 +1,8 @@
 # Firstleg-Finance 跨服务契约（技术草案）
 
-> 版本：V0.3（一期五页来源链路实现对齐）  
-> 日期：2026-08-11  
-> 状态：技术边界和一期产品口径已确认；Firstleg 事件/Relay/快照与 Finance Inbox/来源写入已实现并通过定向测试。
+> 版本：V0.4（费用作废命令与事件回流对齐）  
+> 日期：2026-08-20  
+> 状态：技术边界和一期产品口径已确认；Firstleg 事件/Relay/快照、Finance Inbox/来源写入及 Finance 发起的业务作废闭环均已实现。
 
 本文是 `firstleg-service` 与已落地 `finance-service` 之间的费用来源技术契约。产品范围以《财务一期五页产品与接口验收契约》为准。
 
@@ -60,6 +60,16 @@ supplierId, supplierName, supplierCategory, sourceHash, snapshotVersion
 
 Finance 将完整 DTO 和 `sourceHash` 存入自有来源池。非 `FIRSTLEG_FEE_VOIDED` 事件只接受 `publicationStatus=PUBLISHED`；未发布返回 `FIN-EVT-015`。作废事件允许读取对应作废版本，但只能把既有来源标为 `VOIDED`，不得创建新来源。
 
+### 4.1 Finance 发起业务费用作废
+
+Finance 的客户应收应付页面允许发起 Firstleg 来源作废，但 Finance 不是业务费用事实源，不得先更新 `fin_fee_source`，也不得自行生产 `FIRSTLEG_FEE_VOIDED`。Finance 使用服务间令牌调用：
+
+`POST /internal/firstleg/v1/fee-sources/commands/void`
+
+请求必须携带 `Idempotency-Key`、规范化请求的 `X-Request-Hash`，以及 `sourceType/sourceFeeId/sourceVersion/customerId/inboundId|containerId/operatorId/operatorName/reason`。Firstleg 必须重新校验客户、业务归属、稳定来源 ID 和精确版本，在同一事务中作废业务费用、记录 `fl_finance_fee_source_command` 幂等审计并写入 `FIRSTLEG_FEE_VOIDED` Outbox；相同幂等键同参重放原结果，异参冲突。Finance 只有消费该事件后才将本地来源置为 `VOIDED`。
+
+Firstleg 来源的金额编辑和调整仍必须回到入库费用或柜次费用业务明细完成，由 Firstleg 生成新版本并发布 `FIRSTLEG_FEE_ADJUSTED`。Finance 的本地 edit/adjust 接口对 `sourceSystem=FIRSTLEG` 必须拒绝，不能只修改 `fin_fee_source.amount`。
+
 建议附加只读校验接口：`GET /internal/firstleg/v1/inbounds/{inboundId}/fees/{feeId}/publication`，用于消费重试时快速判断发布状态；该接口不能返回跨客户数据。
 
 ## 5. 消费幂等、乱序与冲突

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

@@ -295,6 +295,7 @@ paths:
     put:
       operationId: editFinanceFeeSource
       summary: 编辑草稿或驳回的费用来源
+      description: sourceSystem=FIRSTLEG 时拒绝本地金额编辑，必须回入库费用或柜次费用业务明细修改并由 Firstleg 发布新版本。
       x-permission: platform:finance:fee-source:edit
       parameters:
         - $ref: '#/components/parameters/FeeSourceId'
@@ -353,6 +354,7 @@ paths:
     post:
       operationId: adjustFinanceFeeSource
       summary: 将已审核费用调整为新草稿版本
+      description: sourceSystem=FIRSTLEG 时拒绝本地金额调整，必须由 Firstleg 业务明细形成新版本并发布 FIRSTLEG_FEE_ADJUSTED。
       x-permission: platform:finance:fee-source:edit
       parameters:
         - $ref: '#/components/parameters/FeeSourceId'
@@ -367,6 +369,7 @@ paths:
     post:
       operationId: voidFinanceFeeSource
       summary: 作废费用来源
+      description: sourceSystem=FIRSTLEG 时 Finance 仅发起幂等内部命令；Firstleg 原子作废业务费用并发布 FIRSTLEG_FEE_VOIDED，Finance 消费事件后同步本地状态，不执行本地先写或伪造事件。
       x-permission: platform:finance:fee-source:edit
       parameters:
         - $ref: '#/components/parameters/FeeSourceId'

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

@@ -48,7 +48,7 @@
 | 页面 | 原型结构和筛选 | 一期字段 | 一期操作 | 状态与验收 |
 |---|---|---|---|---|
 | 客户账户 | 汇总卡、客户列表、账户详情、流水详情；客户名称/编号、账户状态、余额条件、流水类型和日期 | 客户基本信息、客户编号、联系人、电话、未收余额、待出账金额、本期已收金额、应付余额、账户状态、最后变动时间；流水号、时间、业务类型、关联单据、应收/应付变动、变动后未收余额、操作人、备注 | 详情、查询、重置、导出；**无充值、扣款或余额调整** | 客户主体正常/停用只影响访问和新业务；所有金额可由来源、单据和收付款逐笔追溯，禁止直接写余额 |
-| 客户应收应付 | 工具栏、组合查询、选中汇总、费用列表、费用详情、审核进度、关联业务、操作记录 | 客户、费用单号、是否已生成对账单、审核状态、应收/应付、入仓码/柜次号、业务状态、费用类型、金额、业务发生日、来源类型、来源版本 | 详情、编辑草稿/驳回项、提交审核、审核通过/拒绝、调整、作废、按截止时间或勾选生成；不提供“是否结算”开关 | `DRAFT/REJECTED -> PENDING -> APPROVED`；`APPROVED + PUBLISHED + AVAILABLE + CNY` 自动成为结算候选；同一来源版本不能重复进入有效单据 |
+| 客户应收应付 | 工具栏、组合查询、选中汇总、费用列表、费用详情、审核进度、关联业务、操作记录 | 客户、费用单号、是否已生成对账单、审核状态、应收/应付、入仓码/柜次号、业务状态、费用类型、金额、业务发生日、来源类型、来源版本 | 详情、提交审核、审核通过/拒绝、作废、按截止时间或勾选生成；Firstleg 来源的金额编辑/调整回到入库或柜次业务明细完成；不提供“是否结算”开关 | `DRAFT/REJECTED -> PENDING -> APPROVED`；`APPROVED + PUBLISHED + AVAILABLE + CNY` 自动成为结算候选；作废由 Firstleg 落业务事实并发事件，Finance 消费后同步；同一来源版本不能重复进入有效单据 |
 | 客户对账单 | 查询区、主表、账单明细、支付历史；审核状态、账单编号、客户、柜次、结算起止日、是否结清、创建日期、最后收款时间 | 对账单号、客户、期间、账期、CNY、总应收、已收、未收、客户确认状态/确认人/确认时间、最后收款时间、是否结清、备注、创建/更新人时间 | 生成草稿、详情、导出、审核、出账、调整、作废；客户在 Client 确认本人已出账账单 | 主状态与客户确认状态独立；出账后 `PENDING_CONFIRMATION`，客户确认后 `CONFIRMED`，调整后重置待确认并保留历史审计 |
 | 结算单应收 | 汇总卡、筛选、列表、详情、费用明细、收款记录；收款状态、客户、结算单号 | 结算单号、客户、CNY、应收、已收、余额、关联对账单、业务期间、生成日、到期日、收款状态、制单人、状态 | 从已出账对账单生成、详情、部分收款、导出、作废/重开；不保留高级查询假入口 | 生成后直接 `ISSUED -> PARTIALLY_PAID -> PAID`；来源已在对账单阶段审核，结算单不重复增加假审批；未收款可作废，调整保留 revision |
 | 结算单应付 | 汇总卡、供应商筛选、列表、详情、费用明细、付款记录 | 结算单号、供应商、费用类型、CNY、应付、已付、余额、来源期间、生成日、到期日、付款状态、制单人、状态 | 从审核通过且自动发布的应付来源生成、详情、部分付款、导出、作废/重开；删除利润分析和利润审批按钮 | 生成后直接 `ISSUED -> PARTIALLY_PAID -> PAID`；不重复增加结算单审批；作废/重开保留 revision，付款为后台人工登记和凭证图片 |