diff --git a/docs/superpowers/specs/2026-04-13-txw-gxzx-to-mhzc-migration-design.md b/docs/superpowers/specs/2026-04-13-txw-gxzx-to-mhzc-migration-design.md new file mode 100644 index 0000000..dadf520 --- /dev/null +++ b/docs/superpowers/specs/2026-04-13-txw-gxzx-to-mhzc-migration-design.md @@ -0,0 +1,342 @@ +# txw-gxzx 功能迁移到 txw-mhzc 设计方案 + +## 1. 背景与目标 + +### 1.1 背景 + +碳信网项目目前存在两个独立的后端服务： +- **txw-mhzc（门户站场）**：用户/企业管理、资讯、公共列表、企业入驻 +- **txw-gxzx（供需中心）**：绿色金融、绿色交易、企业入驻、供需大厅 + +两个服务功能上有重叠，且 gxzx 的企业入驻实际通过 Feign 调用 mhzc 完成。长期维护两套独立服务增加复杂度。 + +### 1.2 目标 + +将 **txw-gxzx 全部功能迁移到 txw-mhzc**，形成统一的后端服务。txw-gxzx 模块废弃，gxzx-web 前端路由配置改为调用 mhzc 后端接口。 + +--- + +## 2. 现状分析 + +### 2.1 txw-gxzx 模块结构 + +| 模块 | Controller | API数量 | 业务描述 | +|------|-----------|---------|---------| +| 绿色金融 | `LsjrController` | 14 | 银行/保险机构查询、信贷/保险产品管理、贷款/投保申请 | +| 绿色交易 | `LsjyController` | 8 | 资产类型管理、资产信息管理、审批流程 | +| 企业入驻 | `QyRzController` | 4 | 企业入驻申请、审批、列表查询 | +| 供需大厅 | `GxdtController` | 10 | 供需信息发布、收藏、标签管理 | + +**总计：36 个 API 接口** + +### 2.2 数据库表（9张） + +| 表名 | 说明 | 记录类型 | +|------|------|---------| +| `txw_gxzx_gxxxb` | 供需信息表 | 供需大厅-供需发布 | +| `txw_gxzx_gxbqb` | 供需标签表 | 供需大厅-标签关联 | +| `txw_gxzx_gxscb` | 供需收藏表 | 供需大厅-收藏 | +| `txw_gxzx_qybqb` | 企业标签表 | 供需大厅-企业标签 | +| `txw_gxzx_rzsqjlb` | 入驻申请记录表 | 企业入驻 | +| `txw_gxzx_shqkb` | 审核情况表 | 通用审批流程 | +| `txw_gxzx_dkbxsqxx` | 贷款/保险申请信息表 | 绿色金融-申请 | +| `txw_gxzx_lsjrcpxx` | 绿色金融产品信息表 | 绿色金融-产品 | +| `txw_gxzx_lsjy_zcxx` | 绿色交易资产信息表 | 绿色交易-资产 | + +### 2.3 关键依赖关系 + +``` +txw-gxzx 外部依赖： +├── IMhzcApi (Feign Client) → txw-mhzc +│ └── 仅用于 qyrz 企业入驻（gxzx实际是申请流程层） +├── XxzxApi (消息中心) → 外部框架 +│ └── 审批通过/拒绝后发送系统消息 +└── txw-gxzx-service-api + └── 对外暴露的 Feign 接口（但接口体为空，无实际消费者） +``` + +### 2.4 Gateway 路由配置 + +```yaml +# txw-gateway bootstrap.yml (Nacos) +- id: txw-gxzx + uri: grayLb://txw-gxzx + predicates: + - Path=/gxzx/** + +- id: txw-mhzc + uri: grayLb://txw-mhzc + predicates: + - Path=/mhzc/** +``` + +--- + +## 3. 迁移方案 + +### 3.1 数据库迁移 + +#### 3.1.1 表合并策略 + +| gxzx 表 → mhzc | 合并方式 | +|----------------|---------| +| `txw_gxzx_rzsqjlb` → `txw_mhzc_qyrzsqjlb` | **合并**：字段高度兼容，差异仅 `sqly`(gxzx) vs `sqsm`(mhzc)、多 `ywlx_dm` 字段 | +| 其余 8 张表 | **迁移**：直接迁移到 mhzc 库，表名保持 `txw_gxzx_*` 前缀（避免与其他表名冲突） | + +#### 3.1.2 字段映射（rzsqjlb 合并） + +| gxzx 字段 | mhzc 字段 | 处理方式 | +|-----------|----------|---------| +| `uuid` | `uuid` | 直接映射 | +| `ywlx_dm` | 无 | **废弃**，gxzx 代码中硬编码为 "01"，不做业务判断 | +| `nsrsbh` | `nsrsbh` | 直接映射 | +| `qymc` | `qymc` | 直接映射 | +| `sjhm1` | `sjhm_1` | 直接映射 | +| `sqly` | `sqsm` | 直接映射（含义相同） | +| `lrruuid` | `lrruuid` | 直接映射 | +| `lrrq` | `lrrq` | 直接映射 | +| `shrsfid` | `shrsfid` | 直接映射 | +| `shsj` | `shsj` | 直接映射 | +| `shyj_1` | `shyj_1` | 直接映射 | +| `shjg_1` | `shjg_1` | 直接映射 | +| `dlzh` | `dlzh` | 直接映射 | +| `zsxm_1` | `zsxm_1` | 直接映射 | +| `yh_uuid` | `yh_uuid` | 直接映射 | + +#### 3.1.3 数据迁移脚本 + +```sql +-- 1. 将 gxzx_rzsqjlb 数据迁移到 mhzc_qyrzsqjlb +INSERT INTO txw_mhzc_qyrzsqjlb + (uuid, qymc, nsrsbh, sqsm, lrruuid, lrrq, shrsfid, shjg_1, shyj_1, shsj, sjhm_1, dlzh, zsxm_1, yh_uuid) +SELECT + uuid, qymc, nsrsbh, sqly, lrruuid, lrrq, shrsfid, shjg_1, shyj_1, shsj, sjhm1, dlzh, zsxm_1, yh_uuid +FROM txw_gxzx_rzsqjlb; + +-- 2. 将其余 8 张 gxzx 表迁移到 mhzc 库（表名不变） +-- gxxxb, gxbqb, gxscb, qybqb, shqkb, dkbxsqxx, lsjrcpxx, lsjy_zcxx +-- 直接 RENAME TABLE 或 INSERT INTO ... SELECT +``` + +### 3.2 代码迁移 + +#### 3.2.1 API 层（txw-mhzc-service-api） + +新增 4 个业务接口，补充 gxzx 的功能： + +| 新增接口 | 包路径 | 说明 | +|---------|--------|------| +| `ILsjrApi` | `com.css.txw.mhzc.api` | 绿色金融 Feign 接口 | +| `ILsjyApi` | `com.css.txw.mhzc.api` | 绿色交易 Feign 接口 | +| `IQyRzApi` | `com.css.txw.mhzc.api` | 企业入驻 Feign 接口（补充 gxzx 部分） | +| `IGxdtApi` | `com.css.txw.mhzc.api` | 供需大厅 Feign 接口 | + +**注意**：`txw-gxzx-service-api` 中的 `IGxzxApi` 为空接口体，无实际方法，无需迁移。 + +#### 3.2.2 BIZ 层（txw-mhzc-service-biz） + +迁移文件清单： + +**Controller 层（4个）：** +``` +txw-gxzx-service-biz/controller/ +├── LsjrController.java → txw-mhzc-service-biz/controller/LsjrController.java +├── LsjyController.java → txw-mhzc-service-biz/controller/LsjyController.java +├── QyRzController.java → txw-mhzc-service-biz/controller/QyRzController.java +└── GxdtController.java → txw-mhzc-service-biz/controller/GxdtController.java +``` + +**Service 层（需迁移+新建）：** +``` +txw-gxzx-service-biz/service/lsjr/* → txw-mhzc-service-biz/service/lsjr/* +txw-gxzx-service-biz/service/lsjy/* → txw-mhzc-service-biz/service/lsjy/* +txw-gxzx-service-biz/service/impl/* → txw-mhzc-service-biz/service/impl/* + (TxwGxzxGxbqbServiceImpl, TxwGxzxGxscbServiceImpl, TxwGxzxGxxxbServiceImpl, + TxwGxzxQybqbServiceImpl, TxwGxzxRzsqjlbServiceImpl, TxwGxzxShqkbServiceImpl) +``` + +**Mapper 层（需迁移+合并）：** +``` +txw-gxzx-service-biz/mapper/lsjr/* → txw-mhzc-service-biz/mapper/lsjr/* +txw-gxzx-service-biz/mapper/lsjy/* → txw-mhzc-service-biz/mapper/lsjy/* +txw-gxzx-service-biz/mapper/* → txw-mhzc-service-biz/mapper/* + (TxwGxzxGxbqbMapper, TxwGxzxGxscbMapper, TxwGxzxGxxxbMapper, + TxwGxzxQybqbMapper, TxwGxzxRzsqjlbMapper, TxwGxzxShqkbMapper, + GxzxDkbxsqxxMapper, GxzxLsjrcpxxMapper, GxzxLsjyZcxxMapper) +``` + +**DO/POJO/DTO/VO 层：** +- `pojo/domain/*` → `pojo/domain/` (保持) +- `pojo/dto/*` → `pojo/dto/` (保持) +- `pojo/vo/*` → `pojo/vo/` (保持) +- `pojo/lsjr/*` → `pojo/lsjr/` (保持) +- `pojo/lsjy/*` → `pojo/lsjy/` (保持) + +**Configuration：** +- `GxzxServiceConfiguration.java` → `MhzcServiceConfiguration.java` (合并 MapperScan 路径) + +#### 3.2.3 关键代码改动 + +**1. Feign 调用改为内部服务调用** + +原 gxzx 代码： +```java +// GxzxRzsqjlbServiceImpl.java +@Resource +private IMhzcApi iMhzcApi; + +// 审批通过后调用 mhzc 入驻 +CommonResult qyrz = iMhzcApi.qyrz(reqDTO); +``` + +迁移后：直接注入 mhzc 本地 Service，不走 Feign： +```java +// 改为直接调用本地 TxwMhzcQyxxbService +@Resource +private TxwMhzcQyxxbService qyxxbService; + +// 审批通过后 +qyxxbService.qyrz(reqDTO); +``` + +**2. 企业入驻 Service 合并** + +gxzx 的 `TxwGxzxRzsqjlbServiceImpl` 合并到 mhzc 的 `TxwMhzcQyrzsqjlbServiceImpl`： +- gxzx 申请 → 直接使用 mhzc 的 qyrzsqjlb 表和 Service +- 删除 gxzx 中对 `IMhzcApi.qyrz()` 的 Feign 调用，改为本地 `qyxxbService.qyrz()` +- 审批消息发送（xxzxApi）保留 + +**3. MapperScan 配置合并** + +原 gxzx 配置： +```java +@MapperScan("com.css.txw.gxzx.mapper") +``` + +迁移后合并到 mhzc： +```java +@MapperScan({ + "com.css.txw.mhzc.mapper", + "com.css.txw.gxzx.mapper" // 迁移后改为 mhzc 包下的 gxzx mapper +}) +``` + +**4. 包名重命名** + +迁移过程中将 `com.css.txw.gxzx` 包逐步改为 `com.css.txw.mhzc`： +- `Gxzx*` 类名 → 改为 `Mhzc*` 或保持（视情况） +- `TxwGxzx*` → `TxwMhzc*` + +### 3.3 路由配置变更 + +#### 3.3.1 Gateway 路由（txw-gateway） + +**变更前：** +```yaml +- id: txw-gxzx + uri: grayLb://txw-gxzx + predicates: + - Path=/gxzx/** + +- id: txw-mhzc + uri: grayLb://txw-mhzc + predicates: + - Path=/mhzc/** +``` + +**变更后：** +```yaml +# 删除 txw-gxzx 路由，或将 /gxzx/** 指向 txw-mhzc +- id: txw-gxzx-migrated + uri: grayLb://txw-mhzc + predicates: + - Path=/gxzx/** + +- id: txw-mhzc + uri: grayLb://txw-mhzc + predicates: + - Path=/mhzc/** +``` + +gxzx-web 前端调用 `/gxzx/lsjr/xxx` → 路由到 txw-mhzc 处理。 + +#### 3.3.2 Nacos 配置 + +更新 `txw-gateway.yaml` 和 `txw-mhzc.yaml`（如有服务名配置）。 + +### 3.4 前端适配 + +gxzx-web 前端无需代码迁移，仅需： + +1. **路由配置变更**：将前端 API 请求路径从 `/gxzx/` 改为 `/mhzc/` +2. **接口调用路径**：确保前端调用的接口 URL 与 mhzc 后端一致 + +--- + +## 4. 迁移步骤 + +### 阶段一：数据库迁移（独立执行） + +1. 备份 gxzx 和 mhzc 数据库 +2. 执行数据迁移 SQL（rzsqjlb 合并 + 8张表迁移） +3. 验证数据完整性 + +### 阶段二：API 层建设 + +1. 在 `txw-mhzc-service-api` 中新增 4 个 Feign 接口 +2. 定义 gxzx 各业务模块的请求/响应 DTO + +### 阶段三：业务代码迁移 + +1. 迁移 PO/DO/VO/DTO 到 mhzc 的 pojo 包 +2. 迁移 Mapper 到 mhzc 的 mapper 包（含自定义 SQL） +3. 迁移 Service 到 mhzc 的 service 包 +4. 迁移 Controller 到 mhzc 的 controller 包 +5. 更新 Feign 调用为本地注入 +6. 更新 `MapperScan` 和 `ComponentScan` 配置 + +### 阶段四：依赖配置 + +1. 删除 gxzx-service-biz 对 gxzx-service-api 的依赖（迁移后不再需要） +2. 保留 `txw-gxzx-service-api` 依赖（已有代码可能引用） + +### 阶段五：路由切换 + +1. 更新 txw-gateway 路由配置 +2. 通知前端团队修改 API 调用路径 +3. 灰度验证 + +### 阶段六：旧模块处理 + +1. 保留 txw-gxzx 模块代码（建议添加 deprecated 注释） +2. 或完全删除 txw-gxzx 模块 + +--- + +## 5. 风险点与注意事项 + +| 风险 | 描述 | 缓解措施 | +|------|------|---------| +| Feign 循环依赖 | gxzx → mhzc，迁移后若 mhzc 也需调用 gxzx 会循环 | 迁移后 Feign 调用改为本地注入，消除循环 | +| 表名冲突 | gxzx 表名与 mhzc 现有表可能重名 | gxzx 表保持 `txw_gxzx_*` 前缀，不重命名 | +| 消息通知 | xxzxApi 调用在 gxzx 和 mhzc 中都可能存在 | 保持 Feign 调用方式，不变 | +| 审批流程 | gxzx 的 shqkb 是通用审批表，mhzc 也有类似需求 | shqkb 迁移后作为 mhzc 的通用审批表使用 | +| Session 依赖 | 各 Controller 依赖 SessionUtils 获取当前用户 | 不变，Session 获取方式相同 | + +--- + +## 6. 验收标准 + +1. **功能完整性**：36 个 API 接口全部迁移，接口签名保持兼容 +2. **数据完整性**：9 张表数据完整迁移，rzsqjlb 合并无数据丢失 +3. **路由正确性**：gxzx-web 调用 `/gxzx/*` 路径能正确路由到 mhzc 后端 +4. **无编译错误**：mvn compile 全部通过 +5. **企业入驻流程**：申请→审批→入驻 全流程端到端验证通过 + +--- + +## 7. 后续工作 + +1. **旧模块废弃**：删除或归档 txw-gxzx 整个模块 +2. **前端合并**（可选）：长期可将 gxzx-web 合并到 mhzc-web +3. **数据库清理**：废弃 gxzx 原有表，保留迁移后的新表