baiyue-firstleg/finance/AGENTS.md

# Finance Service Instructions

## 模块定位

- 本模块是独立财务服务，拥有客户结算条款、财务费用来源、CNY 账单与明细、客户资金账户及充值申请、应收款月度统计、客户对账确认、收款及分配、成本及分摊、账单修订、单据编号、幂等记录和财务审计状态。
- 产品范围先读 `../../docs/财务管理/财务管理产品确认表.md` 与 `财务核心五页产品与接口验收契约.md`，跨服务契约再读 `Firstleg-Finance跨服务契约.md`；专题 README、证据矩阵和测试环境报告只用于状态或验收问题，不作为普通开发首读。
- Firstleg 拥有入库/柜次业务费用和履约事实，File 拥有凭证文件；Finance 通过内部接口读取或消费快照，不跨库查询，也不复制上游业务状态机。

## 快速查询

| 目标 | 首选入口 |
|---|---|
| 平台账户、费用池、账单、收款与成本 API | `controller/PlatformFinanceController.java`，统一前缀 `/api/platform/finance/v1` |
| 平台财务凭证上传 | `PlatformFinanceController.java` 的 `POST /vouchers`、`client/FinanceFileClient.java`；文件类型固定 `FINANCE_VOUCHER`，业务 ID/客户范围使用当前客户 ID |
| 客户只读账单、收款与应收 API | `controller/ClientFinanceController.java`，统一前缀 `/api/client/finance/v1` |
| 订单与客户账户、费用来源审核与结算纳入 | `controller/FinancePhase1OperationController.java`、`service/FinancePhase1OperationService.java` |
| 客户财务账户汇总 | `service/FinanceCustomerAccountService.java`、`client/IamCustomerClient.java`；客户主档事实仍归 IAM |
| 客户资金账户、授信与充值 | `controller/ClientFinanceWalletController.java`、`controller/PlatformFinanceWalletController.java`、`controller/InternalFinanceWalletController.java`、`service/FinanceWalletService.java`、`dto/FinanceWalletDtos.java`；支持静态收款码、截图申请、平台审核、手工充扣、授信配置及供业务模块使用的冻结/结算/释放，第三方支付回调尚未接入 |
| 客户对账单 | `controller/ReconciliationStatementController.java`、`service/ReconciliationStatementService.java` |
| 应收款月度统计 | `controller/ReceivableStatisticsController.java`、`service/ReceivableStatisticsService.java`、`dto/ReceivableStatisticsDtos.java`；按结算单生成月份和客户汇总 CNY 正式应收结算单 |
| 应收/应付结算单 | `controller/FinanceSettlementController.java`、`service/FinanceSettlementService.java` |
| 对账单客户确认 | `controller/ClientFinanceController.java`、`service/ReconciliationStatementService.java`；客户接口 `/api/client/finance/v1/statements/{statementId}/confirm` |
| 财务单据编号 | `service/FinanceDocumentNumberGenerator.java`；对账单、应收结算单、应付结算单、充值申请、账户流水分别使用 `REC`、`AR`、`AP`、`RC`、`AC` 前缀 |
| Finance 导出数据 Provider | `controller/FinanceExportProviderController.java`、`service/FinanceExportProviderService.java`；由 File `ExportProviderClient` 按已登记 `exportType` 分批拉取，不从 Admin 直接生成文件 |
| 财务 OpenAPI | 五页 `../../docs/财务管理/openapi/finance-core-five-pages-v1.yaml`；人工财务 `finance-f1-manual-v1.yaml`；资金账户 `finance-wallet-v1.yaml` |
| 业务费用来源事件入口 | 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`；`StatementLine.inboundCode` 从对应费用来源不可变快照读取，供 Client 跳转客户隔离的入仓关系详情 |
| 账期、账单、收款、成本及幂等写模型 | `service/FinanceService.java` |
| Firstleg 费用来源与柜次成本快照 | `client/FirstlegFeeSourceClient.java`、`client/FirstlegCostSnapshotClient.java`；生产端见 `../firstleg/AGENTS.md` |
| Warehouse 供应商校验与名称快照 | `client/WarehouseSupplierClient.java`、`service/FinanceSupplierValidator.java`；供应商事实来源及类别契约见 `../warehouse/AGENTS.md`、`../warehouse/src/main/resources/openapi/supplier-v1.yaml` |
| 收款/成本凭证 | `client/FinanceFileClient.java`；文件归属与下载规则见 `../file/AGENTS.md` |
| 异常与响应包装 | `controller/FinanceExceptionHandler.java`、`controller/FinanceResponses.java` |
| 数据库 | `src/main/resources/db/finance.sql`、`src/main/resources/db/fee-source-event-migration.sql`；存量/测试环境统一入口为 `../deploy/sql/头程数据库统一增量-MySQL8.sql` |
| 配置与网关 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/finance-service.yml`、`../gateway/src/main/resources/application.yml` |
| 独立服务部署链 | `../Jenkinsfile`、`../Jenkinsfile.service`、`../deploy/service-map.yml`、`../deploy/docker-compose.yml`、`../deploy/scripts/deploy-services.sh`；契约检查见 `../scripts/finance-deployment-contract.test.mjs`，部署授权边界见 `../../docs/测试环境Jenkins部署指南.md` |
| 测试环境全链路验收模块 | `../scripts/admin-test-env-modules/finance-full-fixtures.mjs`、`finance-reconciliation-full.mjs`、`finance-settlement-full.mjs` 及同名 `*-contract.test.mjs`；仅表示验收入口，不代表环境已部署或验收通过 |
| 测试 | `src/test/java/com/baiyue/finance/`；执行 `mvn -pl finance -am test` |

## 契约与边界

- 平台写操作必须校验权限、目标客户、幂等键、请求哈希、乐观锁版本和审计；客户接口只能从登录态取得客户范围，不接受客户端指定客户 ID。
- 出账后的业务来源和账单不得原地覆盖或物理删除；调整、作废、收款分配和修订必须保留可追溯记录。金额使用定点小数，当前业务币种固定为 CNY，长整型 ID 跨前端按字符串传输。
- 对账单出账后将客户确认状态置为 `PENDING_CONFIRMATION`；已出账账单调整后必须清除原确认快照并重新待确认，作废或重开时为 `NOT_REQUIRED`。客户只能确认本企业且状态为 `ISSUED`、`PARTIALLY_PAID` 或 `PAID` 的待确认账单，必须校验登录成员、乐观锁版本和幂等键，并记录确认人姓名快照与确认时间。
- 对账单、应收结算单和应付结算单编号统一按北京时间生成 `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 路由、权限码和契约测试；客户响应不得暴露供应商成本、内部备注、平台凭证或其他客户数据。
- 客户账单明细以业务 `inboundCode` 展示和联查入仓关系；缺失时返回空并显示“—”，不得把 `inboundId`、`sourceId` 或其他内部 ID 当业务编号回退。Finance 只从同客户费用来源快照取值，Client 通过 `first-leg/public.ts` 复用客户隔离的详情组件。
- 修改 Finance 导出字段、筛选或 `exportType` 时，同步检查 `FinanceExportProviderService`、File `ExportDefinitionRegistry`/`ExportProviderClient`、Admin `modules/finance/` 与 `modules/downloads/`、导出权限和双方契约测试；页面只创建异步下载任务，不绕过 File 导出中心直接拼装业务文件。
- Finance 费用池必须保留上游 `direction`、客户/供应商名称和付款证据快照；Firstleg 的 `DIRECT_PAID` 校验仍归 Firstleg。Finance 上传端只创建受客户范围约束的 `FINANCE_VOUCHER` 文件，不替代上游费用审核与付款快照校验。

## 验证

- 文档或索引变更只做路径核对和 `git diff --check`；代码变更至少运行 `mvn -pl finance -am test`。
- 跨服务契约变更同时运行 Finance 与直接生产者/消费者测试。未经用户明确要求，不在本机启动 Java、Nacos 或数据库。