新增征信维护直接入库设计文档
This commit is contained in:
253
docs/design/2026-03-24-credit-info-direct-storage-design.md
Normal file
253
docs/design/2026-03-24-credit-info-direct-storage-design.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# 征信维护直接入库改造设计文档
|
||||
|
||||
## 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/` 前端实施计划
|
||||
@@ -0,0 +1,26 @@
|
||||
# 2026-03-24 征信维护直接入库设计记录
|
||||
|
||||
## 本次产出
|
||||
|
||||
- 新增设计文档 `docs/design/2026-03-24-credit-info-direct-storage-design.md`
|
||||
- 明确征信维护页由“员工征信维护”调整为“征信对象维护”
|
||||
|
||||
## 关键确认结论
|
||||
|
||||
- 导入时不关联柜员
|
||||
- 导入时不关联亲属
|
||||
- 解析成功后直接入库
|
||||
- 柜员亲属征信文件需要独立展示
|
||||
- 查询区移除“是否已维护”
|
||||
- 页面移除“柜员号”
|
||||
|
||||
## 设计结论
|
||||
|
||||
- 上传链路删除员工存在性校验
|
||||
- 列表查询改为直接从征信表按 `person_id` 聚合
|
||||
- 页面按征信对象维度展示摘要
|
||||
- 继续只保留同一证件号的最新征信数据
|
||||
|
||||
## 后续动作
|
||||
|
||||
- 待用户审阅设计文档后，继续输出前端与后端实施计划
|
||||
Reference in New Issue
Block a user