优化

finance/AGENTS.md

@@ -22,7 +22,7 @@
 | 财务单据编号 | `service/FinanceDocumentNumberGenerator.java`；对账单、应收结算单、应付结算单分别使用 `REC`、`AR`、`AP` 前缀 |
 | Finance 导出数据 Provider | `controller/FinanceExportProviderController.java`、`service/FinanceExportProviderService.java`；由 File `ExportProviderClient` 按已登记 `exportType` 分批拉取，不从 Admin 直接生成文件 |
 | 五页产品 OpenAPI | `../../docs/财务管理/openapi/finance-phase1-five-pages-v1.yaml`；人工财务补充契约 `finance-f1-manual-v1.yaml` |
-| 业务费用来源事件入口 | Firstleg：`controller/InternalFinanceFeeSourceController.java`、`service/FinanceFeeSourceEventService.java`；海外完整快照：`controller/InternalBusinessFeeSourceController.java`、`service/BusinessFeeSourceEventService.java` |
+| 业务费用来源事件入口 | Firstleg：`controller/InternalFinanceFeeSourceController.java`、`service/FinanceFeeSourceEventService.java`；海外完整快照：`controller/InternalBusinessFeeSourceController.java` 的 `/internal/finance/v1/business-fee-source-events`、`service/BusinessFeeSourceEventService.java`；事件模型 `../common-event-contract/src/main/java/com/baiyue/common/event/BusinessFeeSourceChangedV1.java` |
 | 查询模型与客户可见性 | `service/FinanceQueryService.java`、`dto/FinanceReadModels.java` |
 | 账期、账单、收款、成本及幂等写模型 | `service/FinanceService.java` |
 | Firstleg 费用来源与柜次成本快照 | `client/FirstlegFeeSourceClient.java`、`client/FirstlegCostSnapshotClient.java`；生产端见 `../firstleg/AGENTS.md` |
@@ -43,6 +43,8 @@
 - 对账单、应收结算单和应付结算单编号统一按北京时间生成 `REC/AR/AP-yyMMdd-####`，各前缀每日独立递增且单日最多 9999；不得回退为数据库 ID 拼接、随机数或跨时区日期。
 - 应收款统计只按正式应收结算单的生成月份汇总 CNY 应收、已收和未收，支持可选客户筛选和分页；导出必须通过 Finance Provider + File `FINANCE_RECEIVABLE_STATISTICS` 异步任务，不在 Controller 或 Admin 直接生成文件。
 - 费用入池只接受满足上游发布与结算条件的不可变来源版本；来源 ID、版本、客户归属、方向或金额变化时同时核对事件消费、主动快照查询、唯一约束和账单明细消费者。
+- 海外业务费用事件只接受非 `FIRSTLEG` 来源、`APPROVED` 审核快照和 `PUBLISHED` 活跃版本或明确 `VOIDED` 动作；按 `eventId + payloadHash` 防重放冲突，并以 `sourceSystem + sourceType + sourceFeeId + sourceVersion` 单调落库。事件携带完整客户、业务、方向、供应商、付款与来源哈希事实，Finance 不跨区同步回查 Lastleg。
+- 海外 `PAYABLE + DIRECT_PAID` 审核版本必须生成 `BUSINESS_DIRECT_PAID` 已确认成本并计入已付成本/客户流水；不得进入 ON_ACCOUNT 应付池或再次生成 AP 结算。调整或作废须作废旧版本成本；客户隔离、同键异载荷冲突和已生成单据冻结不得放宽。
 - 整柜成本分摊使用 Firstleg 返回的真实客户归属与订单体积快照；不得信任前端提交的订单归属或体积。凭证必须由 File 元数据校验客户和业务类型，依赖不可用时不得静默跳过。
 - 应付费用来源、成本登记和应付结算单引用的供应商必须通过 Warehouse 校验 ID 与 `ACTIVE` 状态；费用项目 `supplierCategory` 为空时允许任意启用供应商，非空时严格校验类别，不得从费用编码或名称猜测。名称快照只能取 Warehouse 返回值，不能接受自由文本替代。Warehouse 不可用、供应商停用或非空类别不匹配时必须失败关闭；修改该链路时同步检查事件消费、人工成本、结算创建/付款、Nacos 客户端地址和双方契约测试。
 - 修改平台或客户 DTO 时同步检查 Admin `../../apps/admin-web/src/modules/finance/`、Client `../../apps/client-web/src/modules/finance/`、Gateway 路由、权限码和契约测试；客户响应不得暴露供应商成本、内部备注、平台凭证或其他客户数据。