# 征信维护直接入库改造设计文档

## 1. 背景

现有征信维护功能按员工维度设计：

- 上传时要求征信对象身份证号必须存在于 `ccdi_base_staff`
- 页面列表从 `ccdi_base_staff` 出发聚合，只展示员工本人
- 查询区保留了“柜员号”“是否已维护”两个员工口径字段

当前需求调整为：

- 征信维护页面移除“是否已维护”
- 导入时不需要关联柜员或亲属，解析后直接入库
- 页面允许展示导入的柜员亲属征信文件
- 页面不再展示“柜员号”

本次改造的核心是把“员工征信维护”收敛为“征信对象维护”。

## 2. 已确认约束

- 导入时不关联柜员，也不关联亲属
- 解析出征信对象后直接入库
- 页面按征信对象本人维度展示，一行一条征信对象记录
- 柜员亲属征信文件导入后需要单独展示
- 查询区移除“是否已维护”
- 列表移除“柜员号”
- 保持最短路径实现，不新增征信主表，不拆新页面
- 仍然只保留同一证件号的最新征信数据

## 3. 目标

- 将征信维护页从员工口径调整为征信对象口径
- 让任意征信对象在解析成功后都可以直接落库
- 保留现有上传、详情、删除的基本交互
- 保持现有两张征信业务表结构与覆盖写入模式

## 4. 非目标

- 不新增柜员与亲属归属映射字段
- 不新增征信主表或上传历史表
- 不新增异步任务、补偿任务或兜底逻辑
- 不扩展多版本征信存储

## 5. 方案对比

### 5.1 方案 A：页面和上传都彻底去员工化

- 上传时只校验文件合法性和解析结果完整性
- 解析成功后按征信对象本人证件号直接写入
- 页面直接从征信表聚合，不再依赖员工表

优点：

- 完全符合当前需求
- 前后端语义一致
- 实现路径最短

缺点：

- 页面不再补充员工属性

### 5.2 方案 B：上传去员工化，列表保留员工补充信息

- 上传时不校验员工存在
- 列表查询时若命中员工表则补柜员信息，否则为空

优点：

- 能部分保留旧页面字段

缺点：

- 同一页面内记录语义不一致
- 会继续引入“员工口径”和“征信对象口径”混用问题

### 5.3 方案 C：新增征信对象主表

- 上传后先写征信对象主表，再关联两张明细表

优点：

- 后续扩展空间更大

缺点：

- 超出当前需求，属于过度设计

## 6. 最终方案

采用方案 A：页面和上传都彻底去员工化。

选择原因：

- 直接满足“导入时不需要关联柜员或者亲属，直接入库”
- 直接满足“柜员亲属征信文件可独立展示”
- 不新增表，不改菜单结构，保持最短路径
- 能一次性消除“柜员号”“是否已维护”这类旧口径残留

## 7. 总体链路

改造后的链路如下：

`征信维护页面 -> 征信维护接口 -> 征信维护服务 -> 征信解析接口 -> 两张征信业务表`

职责定义：

- 页面负责上传文件、查询列表、查看详情、删除记录
- 接口负责暴露统一的上传、列表、详情、删除能力
- 服务负责解析结果校验、最新日期判断、覆盖写入
- 数据库继续仅使用 `ccdi_debts_info` 与 `ccdi_credit_negative_info`

## 8. 数据口径设计

### 8.1 主键口径

- 统一以解析结果中的 `query_cert_no` 作为征信对象唯一标识，即 `person_id`
- `query_cust_name` 作为征信对象姓名，即 `person_name`
- `report_time` 作为征信查询日期，即 `query_date`

### 8.2 入库口径

- 不校验 `person_id` 是否存在于 `ccdi_base_staff`
- 不校验 `person_id` 是否存在于 `ccdi_staff_fmy_relation`
- 只要解析结果具备完整主键字段，即可继续写入

### 8.3 列表口径

- 页面主列表按征信对象维度展示
- 每个 `person_id` 对应一条摘要记录
- 不再要求该征信对象属于员工或亲属数据域

## 9. 前端页面设计

### 9.1 查询区

保留：

- 姓名
- 身份证号

移除：

- 柜员号
- 是否已维护

### 9.2 列表区

保留字段：

- 姓名
- 身份证号
- 最近征信查询日期
- 负债笔数
- 负债总额
- 民事案件笔数
- 强制执行笔数
- 行政处罚笔数
- 操作

移除字段：

- 柜员号

### 9.3 详情与删除

- 详情继续按 `person_id` 展示征信摘要、负面信息、负债明细
- 删除继续按 `person_id` 删除该征信对象的全部征信数据

## 10. 后端改造设计

### 10.1 上传服务

现状：

- 上传时调用 `ensureStaffExists(personId)`，非员工身份证号会失败

改造后：

- 删除员工存在性校验
- 解析出 `personId/personName/queryDate` 后直接进入最新日期判断
- 通过后继续覆盖写入两张业务表

### 10.2 列表查询

现状：

- 查询 SQL 从 `ccdi_base_staff` 出发
- 强依赖员工表字段

改造后：

- 查询 SQL 直接从征信表聚合
- 以 `ccdi_debts_info` 的聚合结果为主
- 结合 `ccdi_credit_negative_info` 的负面统计
- 按 `person_id` 汇总一条摘要记录
- 支持姓名、身份证号筛选
- 不再接收或使用 `staffId`、`maintained`

### 10.3 DTO 与 VO

- `CcdiCreditInfoQueryDTO` 删除 `staffId`
- `CcdiCreditInfoQueryDTO` 删除 `maintained`
- 列表 VO 不再要求返回柜员号

## 11. 覆盖写入规则

系统继续只保留同一证件号下的最新征信数据：

- 若库中不存在当前 `person_id` 记录，直接写入
- 若新 `query_date` 大于等于库中最新 `query_date`，覆盖旧数据
- 若新 `query_date` 小于库中最新 `query_date`，当前文件失败

覆盖步骤保持不变：

1. 删除 `ccdi_debts_info` 中该 `person_id` 的旧记录
2. 删除 `ccdi_credit_negative_info` 中该 `person_id` 的旧记录
3. 插入新的负债明细
4. 插入新的负面信息

以上步骤在同一事务内完成。

## 12. 测试设计

### 12.1 前端测试

- 查询区不再包含“柜员号”
- 查询区不再包含“是否已维护”
- 列表列定义不再包含“柜员号”
- 页面仍支持姓名、身份证号检索

### 12.2 后端测试

- 非员工身份证号征信可以上传成功
- 查询 DTO 不再包含 `staffId`、`maintained`
- 列表 SQL 不再依赖 `ccdi_base_staff`
- 详情和删除对纯征信对象记录仍然生效
- 旧日期上传仍会失败

## 13. 实施边界

本次改造只覆盖征信维护功能现有页面与接口：

- 不调整菜单权限编码
- 不改造征信解析接口协议
- 不补录柜员或亲属关系字段
- 不新增历史数据迁移脚本

## 14. 后续动作

- 待用户审阅本设计文档后，输出两份实施计划：
  - `docs/plans/backend/` 后端实施计划
  - `docs/plans/frontend/` 前端实施计划