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

> 当前状态：开发任务草案；《财务开工门禁与 F0/F1 任务清单》G1 放行前不得据此启动业务开发。  
> 总控门禁：[财务开工门禁与 F0/F1 任务清单](财务开工门禁与F0-F1任务清单.md)。  
>
> 本文只拆分技术实施任务，不定义新的业务规则，也不修改现有规划。范围依据《财务服务边界设计》《财务管理产品确认表》和后端仓库现行 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 的字段、状态和权限结论至少形成技术草案。

**验收门禁**

```bash
# 以下命令均在 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 的未决项需在进入对应业务写入前冻结，未冻结时只允许迁移预留字段。

**验收门禁**

```bash
# 以下命令均在 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 路径和平台/客户访问域已书面冻结。

**验收门禁**

```bash
# 以下命令均在 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` 连接凭据和镜像构建权限。

**验收门禁**

```bash
# 以下命令均在 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 事件与内部查询契约冻结。

**验收门禁**

```bash
# 以下命令均在 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/凭据/测试环境部署目标已配置。

**验收门禁**

```bash
# 以下命令均在 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 事件生产者和测试数据/测试环境可用。

**验收门禁**

```bash
# 以下命令均在 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 验收证据。