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、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 或数据库。