补充征信维护后端实施记录并修正负面信息表脚本

2026-03-24 09:23:24 +08:00
parent 155adbee7b
commit aaec81f7f8
2 changed files with 234 additions and 0 deletions
--- a/docs/reports/implementation/2026-03-23-credit-info-maintenance-backend-implementation.md
+++ b/docs/reports/implementation/2026-03-23-credit-info-maintenance-backend-implementation.md
@@ -0,0 +1,214 @@
+# 征信维护后端实施记录
+
+## 1. 实施概述
+
+- 实施日期：2026-03-24
+- 实施范围：`ccdi-info-collection` 征信维护后端能力、SQL 脚本、联调验证、环境修正记录
+- 实施结果：代码实现完成，目标测试通过，隔离端口联调通过
+
+本次实现按设计文档完成以下能力：
+
+- 新增 `ccdi_debts_info`、`ccdi_credit_negative_info` 两张业务表脚本
+- 新增“征信维护”菜单与按钮权限脚本
+- 新增征信维护实体、DTO、VO、Mapper、装配器、服务、控制器
+- 支持批量上传征信 HTML、按员工身份证号归户、按最新征信覆盖写入
+- 支持员工维度列表、详情、删除接口
+
+## 2. 实际修改文件
+
+### 2.1 SQL
+
+- `sql/migration/2026-03-23-create-credit-info-tables.sql`
+- `sql/ccdi_credit_info_menu.sql`
+- `sql/migration/2026-03-24-recreate-credit-negative-info-table.sql`
+
+### 2.2 后端代码
+
+- `ccdi-info-collection/pom.xml`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/CcdiDebtsInfo.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/CcdiCreditNegativeInfo.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiCreditInfoQueryDTO.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CreditInfoListVO.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CreditInfoDetailVO.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CreditInfoNegativeVO.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CreditInfoUploadResultVO.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CreditInfoUploadFailureVO.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/CcdiDebtsInfoMapper.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/CcdiCreditNegativeInfoMapper.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/CcdiCreditInfoQueryMapper.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/support/CreditInfoPayloadAssembler.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/ICcdiCreditInfoService.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiCreditInfoServiceImpl.java`
+- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiCreditInfoController.java`
+- `ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiCreditInfoQueryMapper.xml`
+- `ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiDebtsInfoMapper.xml`
+- `ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiCreditNegativeInfoMapper.xml`
+
+### 2.3 测试代码
+
+- `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/support/CreditInfoPayloadAssemblerTest.java`
+- `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiCreditInfoServiceImplTest.java`
+- `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/controller/CcdiCreditInfoControllerTest.java`
+
+## 3. 关键实施说明
+
+### 3.1 解析与落库
+
+- 上传接口调用 `CreditParseClient.parse("LXCUSTALL", "PERSON", tempFile)`
+- 从 `lx_header.query_cert_no` 归户到 `ccdi_base_staff.id_card`
+- 从 `lx_header.report_time` 提取 `query_date`
+- `lx_debt` 按 7 组固定前缀映射为负债明细
+- `lx_publictype` 直接映射为负面信息汇总
+- 同一员工在事务内执行“先删后插”，仅保留最新征信
+
+### 3.2 实际环境偏差与处理
+
+联调时发现开发库已存在同名旧表 `ccdi_credit_negative_info`，结构与本次设计不一致：
+
+- 旧表字段：`id`、`credit_info_id` 等
+- 目标字段：`negative_id`、`person_id`、`person_name`、`query_date` 等
+
+处理步骤：
+
+1. 先核对旧表行数：`SELECT COUNT(*) FROM ccdi_credit_negative_info;`
+2. 确认旧表为空表后，执行重建脚本
+3. 重建后重新执行上传、列表、详情、删除联调
+
+## 4. SQL 执行记录
+
+按仓库约定，涉及中文与建表脚本的执行均使用 `bin/mysql_utf8_exec.sh`：
+
+```bash
+bin/mysql_utf8_exec.sh sql/migration/2026-03-23-create-credit-info-tables.sql
+bin/mysql_utf8_exec.sh sql/migration/2026-03-24-recreate-credit-negative-info-table.sql
+```
+
+执行结果：
+
+- 首次执行建表脚本时，`ccdi_debts_info` 创建成功
+- 由于开发库已存在旧版 `ccdi_credit_negative_info`，脚本在第二张表处提示已存在
+- 通过重建脚本完成 `ccdi_credit_negative_info` 修正
+
+## 5. 测试与验证
+
+### 5.1 单元测试与编译
+
+执行命令：
+
+```bash
+mvn -pl ccdi-info-collection -Dtest=CreditInfoPayloadAssemblerTest test
+mvn -pl ccdi-info-collection -Dtest=CcdiCreditInfoServiceImplTest test
+mvn -pl ccdi-info-collection -Dtest=CcdiCreditInfoControllerTest test
+mvn -pl ccdi-info-collection -Dtest=CreditInfoPayloadAssemblerTest,CcdiCreditInfoServiceImplTest,CcdiCreditInfoControllerTest test
+mvn -pl ccdi-info-collection -am compile
+mvn -pl ruoyi-admin -am package -DskipTests
+```
+
+验证结果：
+
+- `CreditInfoPayloadAssemblerTest` 通过
+- `CcdiCreditInfoServiceImplTest` 通过
+- `CcdiCreditInfoControllerTest` 通过
+- 目标测试集合 7 条全部通过
+- `ccdi-info-collection` 及上游依赖编译通过
+- `ruoyi-admin.jar` 打包成功
+
+### 5.2 隔离端口联调
+
+为避免影响本机已有开发进程，本次联调使用隔离端口：
+
+- Mock 服务：`http://127.0.0.1:8001`
+- 后端服务：`http://127.0.0.1:62319`
+
+登录获取 token：
+
+```bash
+curl -X POST 'http://127.0.0.1:62319/login/test' \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"admin","password":"admin123"}'
+```
+
+上传验证：
+
+```bash
+curl -H "Authorization: Bearer <token>" \
+  -F 'files=@assets/征信解析员工样本/0001_徐伟_2040.html;type=text/html' \
+  'http://127.0.0.1:62319/ccdi/creditInfo/upload'
+```
+
+结果：
+
+- `code = 200`
+- `data.totalCount = 1`
+- `data.successCount = 1`
+- `data.failureCount = 0`
+
+列表验证：
+
+```bash
+curl -H "Authorization: Bearer <token>" \
+  'http://127.0.0.1:62319/ccdi/creditInfo/list?pageNum=1&pageSize=10'
+```
+
+结果摘要：
+
+- 返回 `code = 200`
+- 员工 `徐伟 / 558455197203132040` 可见
+- `queryDate = 2024-12-09`
+- `debtCount = 7`
+- `civilCnt = 2`
+- `enforceCnt = 13`
+- `admCnt = 3`
+
+详情验证：
+
+```bash
+curl -H "Authorization: Bearer <token>" \
+  'http://127.0.0.1:62319/ccdi/creditInfo/558455197203132040'
+```
+
+结果摘要：
+
+- 返回 `code = 200`
+- `negativeInfo` 正常返回
+- `debtList` 返回 7 条明细
+
+删除验证：
+
+```bash
+curl -X DELETE -H "Authorization: Bearer <token>" \
+  'http://127.0.0.1:62319/ccdi/creditInfo/558455197203132040'
+
+curl -H "Authorization: Bearer <token>" \
+  'http://127.0.0.1:62319/ccdi/creditInfo/558455197203132040'
+```
+
+结果摘要：
+
+- 删除接口返回 `code = 200`
+- 删除后详情仍返回员工壳信息，但 `negativeInfo = null`、`debtList = []`
+- 满足“删除后详情为空或提示未维护征信”的预期
+
+## 6. 进程启停记录
+
+本次联调启动的进程：
+
+- Mock 服务：
+  `python3 -m uvicorn main:app --host 0.0.0.0 --port 8001`
+- 后端服务：
+  `java -jar ruoyi-admin/target/ruoyi-admin.jar --server.port=62319 --credit-parse.api.url=http://127.0.0.1:8001/xfeature-mngs/conversation/htmlEval`
+
+处理要求：
+
+- 联调结束后已按仓库约定停止本次启动的后端与 Mock 进程
+- 未触碰本机原有 `8000`、`62318` 端口上的既有开发进程
+
+## 7. 提交记录
+
+本次实施包含以下提交：
+
+- `fc78c2f` 新增征信维护建表与菜单脚本
+- `6959c7a` 新增征信维护对象与依赖骨架
+- `d2e3388` 新增征信解析结果装配器
+- `c22e379` 新增征信维护上传与覆盖服务
+- `155adbe` 新增征信维护查询与接口
--- a/sql/migration/2026-03-24-recreate-credit-negative-info-table.sql
+++ b/sql/migration/2026-03-24-recreate-credit-negative-info-table.sql
@@ -0,0 +1,20 @@
+DROP TABLE IF EXISTS `ccdi_credit_negative_info`;
+
+CREATE TABLE `ccdi_credit_negative_info` (
+  `negative_id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+  `person_id` VARCHAR(18) NOT NULL COMMENT '员工身份证号',
+  `person_name` VARCHAR(100) DEFAULT NULL COMMENT '员工姓名',
+  `query_date` DATE DEFAULT NULL COMMENT '征信查询日期',
+  `civil_cnt` INT DEFAULT 0 COMMENT '民事案件笔数',
+  `enforce_cnt` INT DEFAULT 0 COMMENT '强制执行笔数',
+  `adm_cnt` INT DEFAULT 0 COMMENT '行政处罚笔数',
+  `civil_lmt` DECIMAL(18, 2) DEFAULT 0 COMMENT '民事案件金额',
+  `enforce_lmt` DECIMAL(18, 2) DEFAULT 0 COMMENT '强制执行金额',
+  `adm_lmt` DECIMAL(18, 2) DEFAULT 0 COMMENT '行政处罚金额',
+  `create_by` VARCHAR(64) DEFAULT '' COMMENT '创建者',
+  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `update_by` VARCHAR(64) DEFAULT '' COMMENT '更新者',
+  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  PRIMARY KEY (`negative_id`),
+  UNIQUE KEY `uk_person_id` (`person_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='员工征信负面信息';