# 征信维护后端实施记录

## 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` 新增征信维护查询与接口
