From a95258fe81e0cf83c18966cb854f6d296d16600c Mon Sep 17 00:00:00 2001
From: wkc <978997012@qq.com>
Date: Tue, 24 Mar 2026 14:42:38 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E5=BE=81=E4=BF=A1=E7=BB=B4?=
 =?UTF-8?q?=E6=8A=A4=E7=9B=B4=E6=8E=A5=E5=85=A5=E5=BA=93=E8=AE=BE=E8=AE=A1?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...03-24-credit-info-direct-storage-design.md | 253 ++++++++++++++++++
 ...redit-info-direct-storage-design-record.md |  26 ++
 2 files changed, 279 insertions(+)
 create mode 100644 docs/design/2026-03-24-credit-info-direct-storage-design.md
 create mode 100644 docs/reports/implementation/2026-03-24-credit-info-direct-storage-design-record.md

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