xiaoyu/txw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加 txw-gxzx 迁移到 txw-mhzc 设计方案

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
liulujian 2026-04-13 00:24:18 +08:00
parent 8423f61a3f
commit 856d6a73de
1 changed files with 342 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

342
docs/superpowers/specs/2026-04-13-txw-gxzx-to-mhzc-migration-design.md Normal file
View File

@ -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<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. 验收标准
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 原有表，保留迁移后的新表