ccdi/docs/design/2026-03-23-credit-info-maintenance-design.md

征信维护设计文档

1. 背景

当前仓库已经具备两项征信解析基础能力：

• ccdi-lsfx 已提供 POST /lsfx/credit/parse 征信解析联调接口，可接收 HTML 并返回 lx_header、lx_debt、lx_publictype
• lsfx-mock-server 已支持从征信 HTML 中解析员工姓名和身份证号，能够稳定返回本地联调 payload

本次需求是在“信息维护”菜单下新增“征信维护”菜单，支持批量导入员工征信 HTML 文件并提交上传。系统需要调用现有征信解析接口完成数据解析，并把返回结果批量落库。页面同时要展示当前已维护的员工征信信息，并支持删除现有征信数据。

2. 已确认约束

• 菜单挂在“信息维护”下，页面为独立菜单，不挂到员工维护弹窗内
• 页面主列表按员工维度展示摘要，一行一个员工
• 批量上传按员工维度原子化处理，一个员工失败不影响其他员工
• 负债明细表名固定为 ccdi_debts_info
• 负债信息按照 assets/征信解析/ccdi_debts_info.xlsx 设计
• 负面信息按照接口字段单独设计一张表
• 每个员工只保留最新的征信信息
• 列表操作列支持删除现有征信信息
• 不新增征信主表，主列表通过明细表实时聚合

3. 目标

• 在“信息维护”下新增“征信维护”菜单与页面
• 支持一次上传多个 .html/.htm 征信文件
• 上传后逐文件调用征信解析接口
• 按员工身份证号归户，并按“最新征信优先”规则覆盖写入
• 在页面展示员工维度的征信摘要列表
• 在详情中展示负债明细和负面信息
• 支持按员工删除当前已维护的征信数据

4. 非目标

• 不改造现有 POST /lsfx/credit/parse 的协议语义
• 不新增异步任务、轮询状态页或上传历史模块
• 不保存多版本征信记录
• 不保存原始 HTML 文件或原始 payload JSON
• 不增加说明书之外的补丁性兜底方案

5. 方案对比

5.1 方案 A：三张业务表，增加征信主表

新增征信主表保存员工最新摘要，再配合负债表和负面信息表。

优点：

• 列表查询简单
• 聚合逻辑更少

缺点：

• 引入额外主表，超出本次最短路径
• 同一份摘要数据会与明细形成重复维护

5.2 方案 B：仅保留两张业务表，列表实时聚合

只建设 ccdi_debts_info 与负面信息表，主列表按员工维度实时聚合展示。

优点：

• 满足“负债表固定命名”和“负面信息单独建表”
• 不引入额外主表，路径最短
• 删除和覆盖逻辑仍然清晰，按员工清空两张表即可

缺点：

• 列表查询需要做员工维度聚合

5.3 方案 C：两张业务表加原始 payload 存档

在方案 B 基础上额外保存原始 payload 或原始 HTML。

优点：

• 排查解析问题时信息更全

缺点：

• 增加冗余与维护成本
• 超出当前需求

6. 最终方案

采用方案 B：仅新增 ccdi_debts_info 和 ccdi_credit_negative_info 两张业务表，列表按员工维度实时聚合，不新增征信主表。

选择原因：

• 满足“每个员工只保留最新征信信息”的要求
• 满足“负债信息按 Excel 设计、负面信息单独建表”的要求
• 不额外增加主表，保持最短路径实现
• 删除逻辑直接按员工清理两张业务表，语义明确

7. 总体架构

业务链路如下：

征信维护页面 -> 征信维护业务接口 -> 征信维护服务 -> /lsfx/credit/parse -> 征信解析服务

职责拆分如下：

• 征信维护页面

  • 选择多个 HTML 文件并提交上传
  • 展示员工维度征信摘要列表
  • 打开详情弹窗查看负债明细与负面信息
  • 删除员工当前征信数据

• 征信维护业务接口

  • 对外提供上传、列表、详情、删除接口
  • 不直接把前端耦合到 ccdi-lsfx

• 征信维护服务

  • 逐文件调用征信解析接口
  • 根据员工身份证号归户
  • 校验“是否为最新征信”
  • 单员工事务覆盖写入两张业务表

• ccdi-lsfx

  • 保持现有征信解析客户端能力
  • 继续作为外部征信解析接入边界

8. 数据模型设计

8.1 负债明细表 ccdi_debts_info

一条记录表示一条负债明细，字段按 assets/征信解析/ccdi_debts_info.xlsx 设计：

• debt_id：BIGINT 主键，自增
• person_id：VARCHAR(18)，员工身份证号
• person_name：VARCHAR(100)，员工姓名
• query_date：DATE，征信查询日期
• debt_main_type：VARCHAR(50)，负债大类
• debt_sub_type：VARCHAR(50)，负债小类
• creditor_type：VARCHAR(50)，债权人类型
• debt_name：VARCHAR(100)，负债名称
• principal_balance：DECIMAL(18,2)，负债本金余额
• debt_total_amount：DECIMAL(18,2)，负债总额
• debt_status：VARCHAR(20)，负债状态
• create_by：VARCHAR(64)
• create_time：DATETIME
• update_by：VARCHAR(64)
• update_time：DATETIME

建议索引：

• idx_person_id(person_id)
• idx_query_date(query_date)
• idx_person_query_date(person_id, query_date)

8.2 负面信息表 ccdi_credit_negative_info

一条记录表示一个员工当前最新征信对应的负面信息汇总：

• negative_id：BIGINT 主键，自增
• person_id：VARCHAR(18)，员工身份证号
• person_name：VARCHAR(100)，员工姓名
• query_date：DATE，征信查询日期
• civil_cnt：INT，民事案件笔数
• enforce_cnt：INT，强制执行笔数
• adm_cnt：INT，行政处罚笔数
• civil_lmt：DECIMAL(18,2)，民事案件金额
• enforce_lmt：DECIMAL(18,2)，强制执行金额
• adm_lmt：DECIMAL(18,2)，行政处罚金额
• create_by：VARCHAR(64)
• create_time：DATETIME
• update_by：VARCHAR(64)
• update_time：DATETIME

建议索引：

• uk_person_id(person_id) 唯一索引

9. 解析字段映射设计

9.1 归户字段

从解析结果 lx_header 中读取：

• query_cert_no -> 员工身份证号 person_id
• query_cust_name -> 员工姓名 person_name
• report_time -> 征信查询日期 query_date

query_cert_no 作为员工唯一归户标识，并校验该身份证号必须存在于 ccdi_base_staff。

9.2 lx_debt 到 ccdi_debts_info 的映射

lx_debt 当前为 7 组固定字段，每组映射成一条负债明细：

接口前缀	负债大类	负债小类	债权人类型	负债名称
uncle_bank_house	银行	住房贷款	银行	未结清银行住房贷款
uncle_bank_car	银行	汽车贷款	银行	未结清银行汽车贷款
uncle_bank_manage	银行	经营贷款	银行	未结清银行经营贷款
uncle_bank_consume	银行	消费贷款	银行	未结清银行消费贷款
uncle_bank_other	银行	其他贷款	银行	未结清银行其他贷款
uncle_not_bank	非银	非银行贷款	非银	未结清非银行贷款
uncle_credit_cart	银行	信用卡	银行	未结清信用卡

字段映射规则：

• *_bal -> principal_balance
• *_lmt -> debt_total_amount
• *_state -> debt_status

落库过滤规则：

• 当某组 principal_balance、debt_total_amount 都为空或 0，且 debt_status 为空时，不生成明细记录
• 其余情况生成一条明细

9.3 lx_publictype 到 ccdi_credit_negative_info 的映射

按接口字段直接映射：

• civil_cnt -> civil_cnt
• enforce_cnt -> enforce_cnt
• adm_cnt -> adm_cnt
• civil_lmt -> civil_lmt
• enforce_lmt -> enforce_lmt
• adm_lmt -> adm_lmt

10. 最新征信判定与覆盖策略

系统只保留员工最新征信，规则如下：

• 以 person_id 作为员工唯一标识
• 以 query_date 作为征信最新时间判定字段
• 员工上传新文件时：
  • 若库中无现有征信数据，直接写入
  • 若新 query_date 大于等于现有 query_date，覆盖旧数据
  • 若新 query_date 小于现有 query_date，该员工本次文件判定为失败，不覆盖

单员工覆盖写入步骤：

1. 删除 ccdi_debts_info 中该员工旧记录
2. 删除 ccdi_credit_negative_info 中该员工旧记录
3. 插入本次解析后的最新负债明细
4. 插入本次解析后的最新负面信息

以上 4 步置于同一事务中，保证员工维度原子化。

11. 页面设计

11.1 菜单

在“信息维护”下新增菜单：

• 菜单名称：征信维护
• 路由：creditInfo
• 组件：ccdiCreditInfo/index
• 权限前缀：ccdi:creditInfo:*

11.2 顶部操作区

• 批量上传征信 HTML 按钮
• 查询条件：
  • 员工姓名
  • 柜员号
  • 身份证号
  • 是否已维护征信

上传弹窗要求：

• 仅允许选择 .html/.htm
• 支持一次选择多个文件
• 提交后调用业务上传接口
• 接口返回后直接展示成功/失败汇总及失败清单

11.3 主列表

主列表按员工一行展示，字段建议：

• 员工姓名
• 柜员号
• 身份证号
• 所属部门
• 最近征信查询日期
• 负债笔数
• 负债总额
• 民事案件笔数
• 强制执行笔数
• 行政处罚笔数
• 操作

聚合规则：

• 基础信息来自 ccdi_base_staff
• 最近征信查询日期、负债笔数、负债总额来自 ccdi_debts_info
• 三类负面计数来自 ccdi_credit_negative_info
• 任一业务表存在数据，即视为“已维护征信”

11.4 详情弹窗

详情弹窗分为两部分：

• 摘要区域

  • 员工姓名
  • 身份证号
  • 征信查询日期
  • 负债总额
  • 负债笔数
  • 民事案件笔数
  • 强制执行笔数
  • 行政处罚笔数

• 明细区域

  • 负债信息表格
  • 负面信息汇总卡片

负债表格字段：

• 负债大类
• 负债小类
• 债权人类型
• 负债名称
• 负债本金余额
• 负债总额
• 负债状态

负面信息展示字段：

• 民事案件笔数 / 金额
• 强制执行笔数 / 金额
• 行政处罚笔数 / 金额

11.5 删除交互

列表点击删除时，提示：

确认删除该员工当前已维护的征信信息吗？

确认后删除该员工在两张业务表中的全部数据。

12. 接口设计

新增业务接口，前端不直接调用 /lsfx/credit/parse：

12.1 批量上传

• 方法：POST
• 路径：/ccdi/creditInfo/upload
• 入参：多个 HTML 文件
• 返回：
  • 总文件数
  • 成功数
  • 失败数
  • 失败明细列表

失败明细建议字段：

• fileName
• personId
• personName
• reason

12.2 列表分页查询

• 方法：GET
• 路径：/ccdi/creditInfo/list
• 功能：分页查询员工征信摘要列表

12.3 详情查询

• 方法：GET
• 路径：/ccdi/creditInfo/{personId}
• 功能：查询员工征信摘要、负债明细和负面信息

12.4 删除

• 方法：DELETE
• 路径：/ccdi/creditInfo/{personId}
• 功能：删除员工当前征信数据

13. 后端设计

建议改动集中在 ccdi-info-collection 模块，新增独立征信维护资源。

建议新增：

• controller/CcdiCreditInfoController.java
• service/ICcdiCreditInfoService.java
• service/impl/CcdiCreditInfoServiceImpl.java
• domain/CcdiCreditNegativeInfo.java
• domain/dto/CreditInfoUploadResultDTO.java
• domain/vo/CreditInfoListVO.java
• domain/vo/CreditInfoDetailVO.java
• mapper/CcdiCreditNegativeInfoMapper.java
• mapper/CcdiCreditInfoQueryMapper.java
• resources/mapper/...

职责说明：

• CcdiCreditInfoController

  • 暴露上传、列表、详情、删除接口

• CcdiCreditInfoService

  • 协调解析、归户、最新记录校验、覆盖写入

• CcdiCreditNegativeInfoMapper

  • 维护负面信息表增删查

• CcdiCreditInfoQueryMapper

  • 承担员工维度列表聚合查询和详情聚合查询

14. 异常处理

上传过程中逐文件处理，失败不影响其他员工成功：

• 文件后缀非法：失败原因为“文件格式不支持”
• 解析接口调用失败：失败原因为“征信解析失败”
• 解析成功但身份证号为空：失败原因为“未解析到员工身份证号”
• 身份证号未匹配到员工：失败原因为“未匹配到员工信息”
• 上传征信日期早于当前最新记录：失败原因为“上传征信日期早于当前已维护最新记录”
• 员工覆盖写入事务失败：失败原因为“征信数据保存失败”

删除接口按幂等处理：

• 即使员工当前无征信数据，也返回删除成功

15. 测试方案

15.1 后端测试

• 上传服务测试

  • 单文件解析成功后正确写入两张业务表
  • 同员工新日期文件覆盖旧数据
  • 同员工旧日期文件被拒绝覆盖
  • 一个员工失败不影响其他员工成功
  • 删除后两张表数据均被清空

• 聚合查询测试

  • 只有负债信息
  • 只有负面信息
  • 两者都有
  • 两者都没有
  • 分页下聚合字段正确

• 控制器测试

  • 批量上传成功
  • 混合成功/失败上传
  • 详情查询成功/无数据
  • 删除接口幂等

15.2 前端验证

• 上传多个 HTML 文件并查看结果提示
• 列表按员工维度展示聚合摘要
• 详情弹窗正确显示负债表和负面信息
• 删除后该员工征信摘要即时消失
• 前端生产构建通过

16. 文档与脚本产出要求

本次实施阶段需同步补充：

• 后端实施计划：docs/plans/backend/
• 前端实施计划：docs/plans/frontend/
• SQL 脚本：sql/ 或 sql/migration/
• 实施记录：docs/reports/implementation/

文档落点需遵循仓库目录规范，避免写入错误目录。