38 lines
3.8 KiB
Markdown
38 lines
3.8 KiB
Markdown
# Finance Service Instructions
|
|
|
|
## 模块定位
|
|
|
|
- 本模块是独立财务服务，拥有客户结算条款、财务费用来源、CNY 账单与明细、收款及分配、成本及分摊、账单修订、幂等记录和财务审计状态。
|
|
- 产品范围先读 `../../docs/财务管理/README.md` 中已确认的范围、对象、状态和接口约束；任务进度、完成比例、临时阻断和验收结论不写入本文件，也不作为业务契约。
|
|
- Firstleg 拥有入库/柜次业务费用和履约事实，File 拥有凭证文件；Finance 通过内部接口读取或消费快照，不跨库查询，也不复制上游业务状态机。
|
|
|
|
## 快速查询
|
|
|
|
| 目标 | 首选入口 |
|
|
|---|---|
|
|
| 平台账户、费用池、账单、收款与成本 API | `controller/PlatformFinanceController.java`，统一前缀 `/api/platform/finance/v1` |
|
|
| 客户只读账单、收款与应收 API | `controller/ClientFinanceController.java`，统一前缀 `/api/client/finance/v1` |
|
|
| Firstleg 费用来源事件入口 | `controller/InternalFinanceFeeSourceController.java`、`service/FinanceFeeSourceEventService.java` |
|
|
| 查询模型与客户可见性 | `service/FinanceQueryService.java`、`dto/FinanceReadModels.java` |
|
|
| 账期、账单、收款、成本及幂等写模型 | `service/FinanceService.java` |
|
|
| Firstleg 费用来源与柜次成本快照 | `client/FirstlegFeeSourceClient.java`、`client/FirstlegCostSnapshotClient.java`；生产端见 `../firstleg/AGENTS.md` |
|
|
| 收款/成本凭证 | `client/FinanceFileClient.java`；文件归属与下载规则见 `../file/AGENTS.md` |
|
|
| 异常与响应包装 | `controller/FinanceExceptionHandler.java`、`controller/FinanceResponses.java` |
|
|
| 数据库 | `src/main/resources/db/finance.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` |
|
|
| 测试 | `src/test/java/com/baiyue/finance/`；执行 `mvn -pl finance -am test` |
|
|
|
|
## 契约与边界
|
|
|
|
- 平台写操作必须校验权限、目标客户、幂等键、请求哈希、乐观锁版本和审计；客户接口只能从登录态取得客户范围，不接受客户端指定客户 ID。
|
|
- 出账后的业务来源和账单不得原地覆盖或物理删除；调整、作废、收款分配和修订必须保留可追溯记录。金额使用定点小数，当前业务币种固定为 CNY，长整型 ID 跨前端按字符串传输。
|
|
- 费用入池只接受满足上游发布与结算条件的不可变来源版本；来源 ID、版本、客户归属、方向或金额变化时同时核对事件消费、主动快照查询、唯一约束和账单明细消费者。
|
|
- 整柜成本分摊使用 Firstleg 返回的真实客户归属与订单体积快照；不得信任前端提交的订单归属或体积。凭证必须由 File 元数据校验客户和业务类型，依赖不可用时不得静默跳过。
|
|
- 修改平台或客户 DTO 时同步检查 Admin `../../apps/admin-web/src/modules/finance/`、Client `../../apps/client-web/src/modules/finance/`、Gateway 路由、权限码和契约测试；客户响应不得暴露供应商成本、内部备注、平台凭证或其他客户数据。
|
|
|
|
## 验证
|
|
|
|
- 文档或索引变更只做路径核对和 `git diff --check`；代码变更至少运行 `mvn -pl finance -am test`。
|
|
- 跨服务契约变更同时运行 Finance 与直接生产者/消费者测试。未经用户明确要求，不在本机启动 Java、Nacos 或数据库。
|