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

```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<String> 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. E2E 测试要求

### 6.1 测试目标

在迁移**前**和迁移**后**分别执行相同的 E2E 测试用例，验证功能完全等价，确保迁移过程无业务影响。

### 6.2 迁移前 E2E 测试（基准测试）

| 序号 | 模块 | 测试场景 | 测试路径 |
|------|------|---------|---------|
| 1 | 企业入驻 | 新用户提交入驻申请 → 管理员审批通过 → 企业入驻成功 | POST /gxzx/qyrz/qyrzsq → POST /gxzx/qyrz/qyrzsp → 查询企业列表 |
| 2 | 企业入驻 | 入驻申请审批拒绝 → 验证拒绝原因回写 | POST /gxzx/qyrz/qyrzsp(shjg=5) → 查询申请状态 |
| 3 | 绿色金融-产品管理 | 机构查询、信贷产品列表分页查询、产品详情查询 | POST /gxzx/lsjr/queryJgList → POST /gxzx/lsjr/queryXdbxcpList → GET /gxzx/lsjr/queryXdbxcpxq |
| 4 | 绿色金融-产品管理 | 新增产品 → 审批通过 → 上下架 | POST /gxzx/lsjr/saveOrUpdateCpxx → POST /gxzx/lsjr/cpSp → POST /gxzx/lsjr/cpsxj |
| 5 | 绿色金融-产品管理 | 批量导入产品模板下载 + 导入 | GET /gxzx/lsjr/getTemplate → POST /gxzx/lsjr/pldr |
| 6 | 绿色金融-申请管理 | 提交贷款申请 → 查询申请详情 → 下载申请文件 | POST /gxzx/lsjr/saveDksqxx → GET /gxzx/lsjr/queryXdbxcpsqxq → GET /gxzx/lsjr/querySqFileByid |
| 7 | 绿色金融-申请管理 | 提交投保申请 → 查询申请列表 | POST /gxzx/lsjr/saveTbsqxx → POST /gxzx/lsjr/queryXdbxcpsqList |
| 8 | 绿色交易-资产管理 | 资产类型查询、资产列表分页、资产详情 | GET /gxzx/lsjy/queryZclxList → POST /gxzx/lsjy/queryZcxxList → GET /gxzx/lsjy/queryZcxxxq |
| 9 | 绿色交易-资产管理 | 新增资产 → 审批通过 → 上下架 | POST /gxzx/lsjy/saveOrUpdate → POST /gxzx/lsjy/zcSp → POST /gxzx/lsjy/zcsxj |
| 10 | 绿色交易-资产管理 | 批量删除资产 | POST /gxzx/lsjy/batchDelete |
| 11 | 供需大厅-供需发布 | 发布供需信息 → 审批通过 → 收藏 | POST /gxzx/gxdt/gxfb → POST /gxzx/gxdt/gxfbSp → POST /gxzx/gxdt/gxsc |
| 12 | 供需大厅-供需查询 | 按标签查询供需列表、按企业查询、收藏状态过滤 | POST /gxzx/gxdt/gxxxList → POST /gxzx/gxdt/getGxSqList → POST /gxzx/gxdt/gxfbList |
| 13 | 供需大厅-供需管理 | 供需信息详情查询、供需上架/下架 | GET /gxzx/gxdt/getGxxx → POST /gxzx/gxdt/gxsj |
| 14 | 综合验证 | 所有接口响应格式一致（CommonResult） | 各接口返回结构校验 |
| 15 | 综合验证 | Session 用户信息在迁移前后一致 | 各接口获取当前用户信息对比 |

### 6.3 迁移后 E2E 测试（回归测试）

**路径替换规则：** `/gxzx/` → `/mhzc/`，其余路径不变。

| 序号 | 验证方式 |
|------|---------|
| 1-13 | **路径替换后重复迁移前测试**，验证结果一致 |
| 14-15 | **路径替换后重复迁移前测试**，验证结果一致 |

**新增验证点：**
| 验证项 | 说明 |
|--------|------|
| rzsqjlb 数据完整性 | 迁移前后的入驻申请记录数量一致 |
| 审批消息通知 | 迁移后 xxzx 消息仍能正常发送 |
| Gateway 路由 | /gxzx/** 正确路由到 txw-mhzc |

### 6.4 测试工具建议

- **Postman / Apifox**：接口测试
- **前端联调**：gxzx-web 调用新接口验证完整链路
- **数据库比对**：迁移前后关键表数据一致性校验

### 6.5 判定标准

| 条件 | 结果 |
|------|------|
| 迁移前 15 个测试场景全部通过 | ✅ 基准测试通过 |
| 迁移后相同 15 个场景路径替换后全部通过 | ✅ 迁移成功 |
| 任意场景失败 | ❌ 需排查问题后重新迁移 |

---

## 7. 验收标准

1. **功能完整性**：36 个 API 接口全部迁移，接口签名保持兼容
2. **数据完整性**：9 张表数据完整迁移，rzsqjlb 合并无数据丢失
3. **路由正确性**：gxzx-web 调用 `/gxzx/*` 路径能正确路由到 mhzc 后端
4. **无编译错误**：mvn compile 全部通过
5. **企业入驻流程**：申请→审批→入驻 全流程端到端验证通过
6. **E2E 回归测试**：迁移前 15 个 E2E 测试场景全部通过，迁移后路径替换（/gxzx/→/mhzc/）后相同场景全部回归通过

---

## 8. 后续工作

1. **旧模块废弃**：删除或归档 txw-gxzx 整个模块
2. **前端合并**（可选）：长期可将 gxzx-web 合并到 mhzc-web
3. **数据库清理**：废弃 gxzx 原有表，保留迁移后的新表