docs/财务管理/财务F0实施任务拆分.md

财务 F0 实施任务拆分与验收门禁

本文只拆分技术实施任务，不定义新的业务规则，也不修改现有规划。范围依据《财务服务边界设计》《财务管理产品确认表》和后端仓库现行 Maven、Nacos、Gateway、Docker Compose、Jenkins 约定。

F0 目标：建立可独立构建、部署、回滚的 finance-service 与 baiyue_finance，冻结后续财务共同底座（主体/账套、往来单位快照、币种与精度、期间、编号、来源入池、幂等、权限和审计）的技术承载方式。F0 不交付应收、应付、收付款、核销、发票或利润业务闭环。

1. 实施边界与不变约束

• 根 Maven 聚合新增模块目录 finance/，其 artifactId 固定为 finance-service；Nacos 服务名固定为 finance-service，默认端口 9203，数据库固定为 baiyue_finance。
• Finance 只访问自己的数据库，不建跨库外键、不做跨库 Join、不共享其他服务 Entity；跨服务信息通过 DTO、内部服务令牌和事件协作。
• Firstleg 仍是业务费用来源的唯一生产者；Finance 接收 APPROVED、PUBLISHED、settlementIncluded=true 且未作废/未被有效账单使用的不可变费用版本。
• 产品层仍只有“平台—客户”两级：tenant_id=0 为平台技术作用域，客户数据使用 tenant_id>0；不新增租户选择器或租户级 RBAC。
• 所有财务写操作必须具备幂等键、乐观锁、服务端客户范围校验、权限校验和审计留痕；金额使用定点精度，原币金额不可覆盖。

2. 分阶段任务、依赖与验收命令

F0-1：Maven finance-service 骨架

任务

1. 在根 pom.xml 增加 <module>finance</module>；创建与现有服务一致的 finance/pom.xml、Spring Boot 入口、application.yml、测试目录和 OpenAPI 目录。
2. 复用 common-core、common-web、common-security、common-openapi、common-audit、Nacos Discovery/Config、MyBatis-Plus、Actuator 等既有依赖；不得复制公共安全或审计实现。
3. 配置 FINANCE_DB_URL/USERNAME/PASSWORD、FINANCE_PORT、INTERNAL_SERVICE_TOKEN、Nacos 连接和日志变量；健康检查可在无业务表时启动。
4. 建立 foundation/、source/、idempotency/、audit/ 等包边界，先落 DTO/接口占位和错误码约定，不实现 F1-F4 业务。

依赖：现有根聚合及公共模块可构建；产品确认表 F0-02 至 F0-10 的字段、状态和权限结论至少形成技术草案。

验收门禁

# 以下命令均在 baiyue-firstleg/ 目录执行
mvn -DskipTests validate
mvn -pl finance -am test
mvn -pl finance -am package

必须生成 finance/target/finance-service-1.0.0-SNAPSHOT.jar，应用名和端口默认值分别为 finance-service、9203；禁止通过直接依赖 Firstleg Entity 通过编译。

F0-2：独立数据库与迁移

任务

1. 在 finance/src/main/resources/db/ 建立可溯源的 Finance 基线/兼容迁移：主体/账套、往来单位引用与名称快照、币种/精度、汇率版本预留、财务期间、编号器、来源费用池、Inbox/消费结果、乐观锁/审计所需表和索引。
2. 将 Finance 数据库创建及迁移区块纳入 deploy/sql/头程数据库统一增量-MySQL8.sql；遵守现有入口的 information_schema 判断、幂等写入、只增不删和末尾 PASS 总体验证规则。不得另建日期发布 SQL。
3. 明确所有表的 tenant_id/主体隔离键、金额/币种字段、来源版本/哈希/幂等键唯一约束；不得出现指向其他数据库的外键。
4. 提供只读结构断言脚本或测试资源，覆盖表、索引、精度、唯一键、期间状态和数据库归属。

依赖：F0-1；产品确认表 F0-02 至 F0-08 的未决项需在进入对应业务写入前冻结，未冻结时只允许迁移预留字段。

验收门禁

# 以下命令均在 baiyue-firstleg/ 目录执行
# 模块 SQL/结构测试
mvn -pl finance -am test

# 在获授权的 MySQL 8 测试库执行唯一发布入口（不得在本地自行启动数据库）
mysql --default-character-set=utf8mb4 < deploy/sql/头程数据库统一增量-MySQL8.sql

数据库执行结果必须为 migration_status = PASS；只读核验 baiyue_finance 存在、Finance 表全部属于该库、无跨库外键，且脚本可重复执行不重复造数。测试环境若不可用，记录阻塞，不以本地模拟成功替代。

F0-3：Gateway 与 OpenAPI 聚合

任务

1. 在 gateway/src/main/resources/application.yml 增加 Finance 显式路由，分别预留平台端 /api/platform/v1/finance/**、客户端 /api/merchant/v1/finance/**（具体资源路径以契约冻结为准）；如需环境开关，再同步 config/nacos/{local,cn}/gateway.yml，该文件不作为路由定义来源。
2. 在 Gateway 应用配置增加 /finance-service/v3/api-docs/** 聚合路由与 Swagger UI 条目；同步 App Scope、CORS、JWT 公开路径检查。
3. 不暴露 Finance 内部事件消费、服务令牌快照或管理端点；下游 Finance 仍必须再次校验客户范围和权限。

依赖：F0-1；Finance Controller/OpenAPI 路径和平台/客户访问域已书面冻结。

验收门禁

# 以下命令均在 baiyue-firstleg/ 目录执行
mvn -pl gateway -am test

用已部署测试环境只读验证：登录后平台/客户路由分别可达，未登录返回 401，错误 App Scope 返回 403，内部路径经 Gateway 不可达，Swagger 聚合返回 Finance 文档；若契约路径未冻结，路由任务保持待办而不提前开放泛匹配。

F0-4：部署、配置与回滚

任务

1. 更新 deploy/service-map.yml（artifact、JAR、9203）和 deploy/docker-compose.yml（镜像、容器、端口、日志、Finance 数据源环境变量）。
2. 更新 Jenkinsfile、Jenkinsfile.service 的服务白名单、Maven 模块/JAR 映射和部署参数，使 finance 可单服务 up、重启和回滚；deploy/scripts/deploy-services.sh 继续接收 Compose 服务名并执行部署前置校验。补充 config/nacos/{local,cn}/finance-service.yml，敏感值全部使用环境变量。
3. 验证镜像构建上下文只包含 Finance JAR 与必要运行文件；健康检查、日志目录和网络与现有服务一致。

依赖：F0-1、F0-2；测试环境具备 baiyue_finance 连接凭据和镜像构建权限。

验收门禁

# 以下命令均在 baiyue-firstleg/ 目录执行
mvn -pl finance -am -DskipTests package
sh deploy/scripts/deploy-services.sh test <image-repository> <image-tag> finance <env-file>
docker compose --project-name firstleg-test --env-file <env-file> -f deploy/docker-compose.yml ps finance

容器注册为 finance-service、监听 9203、Actuator health 为 UP；仅重部署 Finance 不重启其他服务；使用上一镜像标签可回滚，迁移脚本不删除已存在财务数据。生产/预发布部署须另获当前对话授权。

F0-5：IAM 权限与审计接入

任务

1. 在 IAM 迁移中加入 Finance 菜单/API/按钮权限资源的技术占位和角色授权映射，权限码、父菜单、平台/客户 app scope、风险等级在契约冻结后一次性确定；不自行增加租户层级。
2. Finance 接入公共 JWT/授权快照校验和审计 Outbox/审计客户端；为制单、复核、确认、期间开关、来源入池等 F0 写操作定义独立审计事件，记录操作者、客户、主体、幂等键、前后版本和 request/trace id。
3. 服务令牌仅用于受保护的 Firstleg 内部快照/事件协作，禁止作为浏览器权限替代。

依赖：F0-1、F0-2；产品确认表 F0-10 高风险权限结论及 Finance/Firstleg 事件与内部查询契约冻结。

验收门禁

# 以下命令均在 baiyue-firstleg/ 目录执行
mvn -pl iam,finance -am test

验收正常、无权限、跨客户、跨主体、关闭期间写入均分别得到预期业务拒绝；每次成功或拒绝的财务写操作都有可查询审计记录。权限未冻结时不得把占位权限授予生产角色，作为该能力的阻塞项记录。

F0-6：CI/CD 与受影响服务识别

任务

1. 在 Jenkinsfile 的 serviceModules、serviceCheckboxes 和参数 checkbox 中加入 finance；在 Jenkinsfile.service 的 serviceModules、serviceJars、允许服务校验、Maven 模块解析、镜像/部署参数中加入 finance。
2. 保持现有规则：Finance 目录变更只触发 Finance；根 POM、公共模块、deploy/ 或总控流水线变更触发全服务；Finance 与 Gateway/IAM/Firstleg 契约变更按显式勾选或公共路径规则联动。
3. 更新 .gitlab-ci.yml（如继续使用）或等价 CI 配置，确保全量 verify 与 Finance 单服务 package/test 可执行。

依赖：F0-1、F0-4；Jenkins 子 Job/凭据/测试环境部署目标已配置。

验收门禁

# 以下命令均在 baiyue-firstleg/ 目录执行
mvn -DskipTests validate
mvn -pl finance -am clean test
mvn clean verify

通过 Jenkins dry-run/测试 Job 证明：Finance 单独变更不构建无关服务；公共模块变更包含 Finance；构建成功后可独立推镜像并按参数部署。任何缺少子 Job、凭据或环境变量的情况必须在 CI 阻塞项中明确，不得静默跳过。

F0-7：契约、集成与回归测试

任务

1. 冻结 Firstleg 费用 Outbox 事件、来源版本/哈希、内部快照查询、服务令牌和错误码；Finance 建立 Inbox、消费结果、失败重试/DLQ、乱序与冲突处理。
2. 编写单元、Repository/迁移、Controller 安全、契约和端到端回归用例：首次入池、重复事件、重复请求、并发版本冲突、重试恢复、跨客户/币种、已关闭期间和审计完整性。
3. 仅以真实来源快照和财务库台账断言结果；不得用前端静态数字或修改 Firstleg 费用状态冒充财务入池。

依赖：F0-1 至 F0-6；Firstleg 事件生产者和测试数据/测试环境可用。

验收门禁

# 以下命令均在 baiyue-firstleg/ 目录执行
mvn -pl finance -am test
mvn -pl gateway,iam,firstleg,finance -am test
mvn test

所有 F0 正常与异常案例通过；同一来源版本最多生成一条有效来源记录，重试返回原结果；越权、跨币种直接合并、关闭期间直接改账均被服务端拒绝；事件失败可观察、可重试且最终审计完整。

3. 总体验收闸门与阻塞项

F0 只有在 F0-1 至 F0-7 全部通过后才能标记完成，并允许 F1/F2 进入生产数据链路。总体验收至少包含：

1. mvn -DskipTests validate、mvn -pl finance -am test、受影响模块测试和全量 mvn test 均通过。
2. 统一 SQL 返回 migration_status = PASS，Finance 数据库独立、可重复迁移、无跨库外键/Join。
3. Finance JAR、镜像、容器、Gateway 路由、Swagger、Nacos 配置和单服务回滚均可验证。
4. IAM 权限、客户范围、主体范围、期间状态、幂等/乐观锁、审计和事件可靠性均有自动化或测试环境证据。
5. 形成版本化的 Finance/Firstleg 事件与内部查询契约，明确 requestId/traceId、重试、DLQ 和兼容策略。

以下任一项未解决，只阻塞相应能力，不得通过“先做页面/静态数据”绕过：

阻塞项	影响范围	解除条件
F0-02/F0-03/F0-06/F0-07 产品字段或编码未确认	对应主体、币种、期间、编号、入池写入及后续 F1-F4	产品确认表形成结论或明确暂缓和默认值；技术骨架可继续
Finance/Firstleg 事件、快照、服务令牌未冻结	来源入池、幂等消费和集成回归	双方 DTO/OpenAPI/事件版本及错误处理书面确认
MySQL 测试库、镜像仓库、Nacos 或 Jenkins 凭据不可用	迁移、部署、CI 环节	测试环境只读核验/凭据配置完成；不得改用本地后端伪造通过
IAM 权限码/高风险角色未审核	受保护写操作和生产发布	权限资源、app scope、角色授权与审计事件审核通过
受影响模块测试或契约测试失败	F0 总体验收及进入 F1/F2	修复并保留回归用例；不得以跳过测试作为完成证据

4. 交付物清单

• finance/ Maven 服务骨架及单元/契约测试。
• Finance 独立迁移目录、统一增量 SQL 区块及只读结构断言。
• Finance local/cn Nacos 配置、Gateway 路由/OpenAPI 聚合、Compose/service-map/部署脚本变更。
• Jenkins 总控与单服务 Job 的 Finance 构建、镜像、部署映射。
• IAM 权限与审计接入、Firstleg↔Finance 事件/内部查询契约及 F0 验收证据。