txw/docs/superpowers/specs/2026-04-13-txw-gxzx-to-mhzc-migration-design.md

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 路由配置

# 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 数据迁移脚本

-- 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 代码：

// GxzxRzsqjlbServiceImpl.java
@Resource
private IMhzcApi iMhzcApi;

// 审批通过后调用 mhzc 入驻
CommonResult<String> qyrz = iMhzcApi.qyrz(reqDTO);

迁移后：直接注入 mhzc 本地 Service，不走 Feign：

// 改为直接调用本地 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 配置：

@MapperScan("com.css.txw.gxzx.mapper")

迁移后合并到 mhzc：

@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）

变更前：

- id: txw-gxzx
  uri: grayLb://txw-gxzx
  predicates:
    - Path=/gxzx/**

- id: txw-mhzc
  uri: grayLb://txw-mhzc
  predicates:
    - Path=/mhzc/**

变更后：

# 删除 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 原有表，保留迁移后的新表