新增专项核查页家庭资产负债专项核查设计文档

docs/design/2026-03-24-special-check-family-asset-liability-design.md

@@ -0,0 +1,473 @@
+# 专项核查页员工家庭资产负债专项核查设计文档
+
+## 1. 背景
+
+当前项目详情页已具备“专项排查”页签，但实际内容组件 `ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue` 仍是占位页。
+
+同时，当前仓库已经具备本次专项核查所需的核心数据基础：
+
+- 项目内员工范围可沿用结果总览当前“项目内已入库流水命中的员工”口径
+- 员工年收入可取 `ccdi_base_staff.annual_income`
+- 配偶年收入可取 `ccdi_staff_fmy_relation.annual_income`
+- 家庭资产可取 `ccdi_asset_info`
+- 征信负债可取 `ccdi_debts_info`
+
+本次需求希望在专项核查页新增一个真实业务卡片，对项目内员工的家庭收入、家庭资产、家庭负债进行聚合核查，并输出风险情况。
+
+## 2. 已确认需求
+
+- 范围仅覆盖项目内员工
+- 家庭总年收入 = 员工本人年收入 + 员工配偶年收入（如有）
+- 家庭总资产 = 员工与配偶关联的资产总和
+- 家庭总负债 = 来源于员工与配偶征信中的贷款与负债总和
+- 风险判断基于“家庭总年收入 + 家庭总负债”与“家庭总资产”的倍数关系
+- 在专项核查页面新增卡片，标题固定为“员工家庭资产负债专项核查”
+- 卡片内展示项目内员工核查列表
+- 列表展示每个员工家庭的总收入、总资产、总负债和风险情况
+- 点击详情后，在当前卡片内展开所有数据细项
+- 展示风格需要与结果总览其他组件统一
+
+## 3. 本次确认口径
+
+### 3.1 员工范围
+
+- 沿用结果总览口径，只展示当前项目中“已入库流水命中且可匹配员工主数据”的员工
+- 不额外扩大到项目配置中的全部目标员工
+
+### 3.2 缺失值处理
+
+- 若员工存在配偶关系，但配偶收入、资产或征信负债未维护完整，则缺失值按 `0` 参与计算
+- 不额外显示“待补数据”
+- 不因缺失值阻断风险等级产出
+
+### 3.3 资产口径
+
+- 家庭总资产统一按 `ccdi_asset_info.current_value` 汇总
+- 不使用 `original_value`
+
+### 3.4 负债口径
+
+- 家庭总负债统一按 `ccdi_debts_info.principal_balance` 汇总
+- 不使用 `debt_total_amount`
+
+### 3.5 配偶识别口径
+
+- 配偶统一按 `ccdi_staff_fmy_relation.relation_type = '配偶'` 识别
+
+### 3.6 风险等级边界
+
+- `家庭总年收入 + 家庭总负债 <= 家庭总资产 * 1.5`：正常
+- `家庭总年收入 + 家庭总负债 > 家庭总资产 * 1.5 且 <= 家庭总资产 * 3`：存在风险
+- `家庭总年收入 + 家庭总负债 > 家庭总资产 * 3`：高风险
+
+采用以上边界是为了避免 `1.5` 倍和 `3` 倍临界值出现重复命中或漏判。
+
+## 4. 目标
+
+- 将专项排查页从占位页升级为包含真实业务核查能力的页面
+- 以最短路径新增“员工家庭资产负债专项核查”卡片
+- 输出项目内员工家庭资产、收入、负债对比结果
+- 在不引入新页面、抽屉、弹窗的前提下，支持明细下钻
+- 保持视觉语言、卡片结构、表格节奏与结果总览一致
+
+## 5. 非目标
+
+- 不新增专项核查独立路由
+- 不新增弹窗详情页、抽屉详情页
+- 不将本次专项核查并入结果总览员工结果表
+- 不扩展除配偶外的其他家庭成员收入、资产、负债口径
+- 不补充兜底、降级或额外提示型方案
+
+## 6. 方案对比
+
+### 6.1 方案 A：单卡列表 + 行内展开
+
+- 在专项排查页新增一个独立白色卡片
+- 卡片主区域直接展示项目内员工列表
+- 点击某一行后，在当前行下方展开收入、资产、负债细项
+
+优点：
+
+- 与结果总览的卡片 + 表格阅读节奏最一致
+- 前端实现边界最清晰
+- 用户先看全量结果，再对单个员工下钻，路径最短
+
+缺点：
+
+- 专项层级的整体统计感相对弱一些
+
+### 6.2 方案 B：摘要统计 + 列表
+
+- 卡片顶部先展示专项统计摘要
+- 下方再展示员工列表与展开详情
+
+优点：
+
+- 更像专项看板
+- 能先看到正常、风险、高风险分布
+
+缺点：
+
+- 会额外引入一层聚合展示
+- 会让专项排查页与结果总览的边界变模糊
+
+### 6.3 方案 C：风险分层看板
+
+- 左侧展示风险分层统计
+- 右侧展示员工列表与详情
+
+优点：
+
+- 视觉冲击更强
+
+缺点：
+
+- 会把本次需求扩成新的 dashboard
+- 与“新增统一风格卡片”的最短路径目标不一致
+
+## 7. 最终方案
+
+采用方案 A：单卡列表 + 行内展开。
+
+选择原因：
+
+- 满足“专项排查页新增真实业务卡片”的目标
+- 风格可直接对齐结果总览现有卡片体系
+- 明细展开符合“点开详情展示所有数据细项”的要求
+- 不需要新增平行页面或重型交互容器
+
+## 8. 页面设计
+
+## 8.1 页面整体结构
+
+专项排查页继续作为项目详情页中的内容区，不改造顶部导航和页签切换方式。
+
+本次页面结构调整为：
+
+1. 保留专项排查主容器 `SpecialCheck.vue`
+2. 在主容器中新增“员工家庭资产负债专项核查”主业务卡片
+3. 页面其余静态骨架仍可保留，但本卡片作为当前页核心区块
+
+## 8.2 卡片结构
+
+卡片标题固定为：
+
+- `员工家庭资产负债专项核查`
+
+卡片副标题建议为：
+
+- `展示项目内员工家庭收入、资产、负债对比结果`
+
+卡片主体由两部分组成：
+
+1. 员工家庭核查列表
+2. 行内展开详情区
+
+## 8.3 列表字段
+
+列表建议固定展示以下列：
+
+- 序号
+- 员工姓名
+- 身份证号
+- 所属部门
+- 家庭总年收入
+- 家庭总资产
+- 家庭总负债
+- 风险情况
+- 操作
+
+其中：
+
+- 风险情况使用与结果总览一致的标签式展示
+- 操作列文案统一为 `查看详情`
+
+## 8.4 行内展开详情
+
+点击“查看详情”后，在当前行下方展开，不打开新页面、不弹窗、不抽屉。
+
+展开区固定分为 3 个模块：
+
+### 8.4.1 收入明细
+
+- 本人年收入
+- 配偶年收入
+- 家庭总年收入
+
+### 8.4.2 资产明细
+
+- 本人资产合计
+- 配偶资产合计
+- 资产明细列表
+- 家庭总资产
+
+资产明细列表建议包含：
+
+- 资产名称
+- 资产大类
+- 资产小类
+- 持有人
+- 当前估值
+- 估值日期
+
+### 8.4.3 负债明细
+
+- 本人负债合计
+- 配偶负债合计
+- 负债明细列表
+- 家庭总负债
+
+负债明细列表建议包含：
+
+- 负债名称
+- 负债大类
+- 负债小类
+- 债权人类型
+- 归属人
+- 本金余额
+- 查询日期
+
+## 8.5 页面状态
+
+### 加载态
+
+- 卡片使用结果总览当前一致的白卡骨架态
+- 列表区采用表格骨架或 `el-skeleton`
+
+### 空态
+
+- 当项目下无可核查员工时，卡片主体展示空态
+- 空态文案建议为 `暂无员工家庭资产负债核查数据`
+
+### 异常态
+
+- 接口异常时，不跳出专项排查页
+- 保持当前页卡片容器与空态风格一致
+
+## 9. 前端组件设计
+
+## 9.1 主容器
+
+文件：
+
+- `ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue`
+
+职责：
+
+- 作为专项排查页主容器
+- 接收 `projectId`、`projectInfo`
+- 组织本次专项核查卡片渲染
+- 维护页面加载态、空态
+
+## 9.2 专项核查区块组件
+
+建议新增一个独立区块组件，例如：
+
+- `FamilyAssetLiabilitySection.vue`
+
+职责：
+
+- 负责请求列表数据
+- 负责列表渲染
+- 负责行展开开关
+- 负责触发展开详情查询
+
+## 9.3 展开详情子组件
+
+建议新增轻量明细组件，例如：
+
+- `FamilyAssetLiabilityDetail.vue`
+
+职责：
+
+- 展示收入、资产、负债三组细项
+- 负责金额格式化与分组展示
+
+说明：
+
+- 明细组件仅服务本卡片，不抽象为全局通用组件
+
+## 9.4 前端展示风格
+
+实现时需遵循以下方向：
+
+- 保持与结果总览现有 `section-card / block-header / el-table` 风格统一
+- 不引入另一套专项核查视觉体系
+- 页面细节可结合现有前端风格做适度精修
+- 保持桌面端阅读密度稳定，移动端至少不出现明显布局错乱
+
+## 10. 后端设计
+
+## 10.1 总体原则
+
+本次专项核查新增专项查询接口，不复用结果总览员工结果表。
+
+原因如下：
+
+- 结果总览员工结果表当前承载的是风险模型命中快照
+- 本次专项核查依赖家庭收入、家庭资产、征信负债等明细聚合
+- 若强行复用结果总览结果表，会把结果总览链路与专项核查链路混成一个表用途
+
+因此，本次采用“专项核查专用查询链路”。
+
+## 10.2 查询范围
+
+查询员工集合沿用当前项目结果总览口径：
+
+- 从项目内已入库流水中提取身份证号
+- 与员工主数据匹配
+- 以匹配成功的员工作为本次专项核查名单
+
+## 10.3 聚合逻辑
+
+对每个员工按以下步骤聚合：
+
+1. 取员工本人年收入
+2. 取员工配偶年收入
+3. 取员工本人及配偶名下资产 `current_value`
+4. 取员工本人及配偶征信 `principal_balance`
+5. 计算家庭总年收入、家庭总资产、家庭总负债
+6. 计算 `家庭总年收入 + 家庭总负债`
+7. 输出风险等级
+
+## 10.4 配偶与家庭数据关联
+
+### 收入
+
+- 本人收入：`ccdi_base_staff.annual_income`
+- 配偶收入：`ccdi_staff_fmy_relation` 中 `relation_type = '配偶'` 对应记录的 `annual_income`
+
+### 资产
+
+- 以员工身份证号为 `family_id`
+- 资产持有人范围限定为员工本人身份证号 + 配偶身份证号
+- 资产金额按 `current_value` 汇总
+
+### 负债
+
+- 负债归属人范围限定为员工本人身份证号 + 配偶身份证号
+- 负债金额按 `principal_balance` 汇总
+
+## 10.5 明细返回要求
+
+详情接口必须返回参与计算的原始明细，至少包括：
+
+- 本人收入
+- 配偶收入
+- 本人资产汇总
+- 配偶资产汇总
+- 资产明细列表
+- 本人负债汇总
+- 配偶负债汇总
+- 负债明细列表
+
+这样前端展开后可直接展示风险判定依据，不需要再次拼装额外逻辑。
+
+## 11. 接口设计
+
+建议新增专项核查专用控制器或在专项查询控制器下新增以下两个只读接口。
+
+### 11.1 列表接口
+
+- 路径建议：`GET /ccdi/project/special-check/family-asset-liability/list`
+- 入参：`projectId`
+- 出参：员工家庭核查列表
+
+列表项建议字段：
+
+- `staffIdCard`
+- `staffCode`
+- `staffName`
+- `deptName`
+- `totalIncome`
+- `totalAsset`
+- `totalDebt`
+- `comparisonAmount`
+- `riskLevelCode`
+- `riskLevelName`
+
+### 11.2 详情接口
+
+- 路径建议：`GET /ccdi/project/special-check/family-asset-liability/detail`
+- 入参：`projectId`、`staffIdCard`
+- 出参：单个员工家庭明细
+
+详情结构建议分为：
+
+- `incomeDetail`
+- `assetDetail`
+- `debtDetail`
+- `summary`
+
+## 12. 代码边界建议
+
+### 后端
+
+建议涉及：
+
+- `controller`
+- `service`
+- `mapper`
+- `dto`
+- `vo`
+
+不建议涉及：
+
+- 结果总览结果表结构
+- 银行流水打标链路
+- 现有结果总览接口
+
+### 前端
+
+建议涉及：
+
+- `SpecialCheck.vue`
+- 专项核查 API 文件
+- 专项核查卡片组件
+- 专项核查详情组件
+
+不建议涉及：
+
+- `PreliminaryCheck.vue`
+- 结果总览已有接口文件
+- 项目详情页顶部导航逻辑
+
+## 13. 测试设计
+
+### 13.1 后端验证
+
+至少验证以下内容：
+
+- 项目范围仅包含当前项目已入库流水命中的员工
+- 存在配偶但数据缺失时，缺失值按 `0` 参与计算
+- 家庭总资产按 `current_value` 汇总
+- 家庭总负债按 `principal_balance` 汇总
+- 风险边界值按已确认规则判定
+- 列表接口与详情接口在无数据场景下返回空结果
+
+### 13.2 前端验证
+
+至少验证以下内容：
+
+- 项目详情切换到专项排查页后能正常看到专项核查卡片
+- 卡片风格与结果总览保持一致
+- 列表字段与需求一致
+- 点击“查看详情”在当前行内展开
+- 展开后能看到收入、资产、负债全部细项
+- 空态、加载态、异常态表现稳定
+
+## 14. 实施结论
+
+本次采用“专项排查页新增统一风格业务卡片 + 专项后端查询接口 + 行内展开详情”的最短路径方案：
+
+1. 不复用结果总览员工结果表
+2. 不引入新页面、弹窗或抽屉
+3. 不扩大到配偶之外的家庭成员
+4. 直接在专项排查页承接第一块真实业务能力
+
+## 15. 后续动作
+
+待用户审阅本设计文档后，按仓库规范输出两份实施计划：
+
+- `docs/plans/backend/` 下的后端实施计划
+- `docs/plans/frontend/` 下的前端实施计划

docs/reports/implementation/2026-03-24-special-check-family-asset-liability-design-record.md

@@ -0,0 +1,29 @@
+# 2026-03-24 专项核查页员工家庭资产负债专项核查设计记录
+
+## 本次产出
+
+- 新增设计文档 `docs/design/2026-03-24-special-check-family-asset-liability-design.md`
+- 明确专项排查页首个真实业务卡片为“员工家庭资产负债专项核查”
+
+## 关键确认结论
+
+- 员工范围沿用结果总览当前“项目内已入库流水命中员工”口径
+- 配偶缺失数据按 `0` 参与计算
+- 家庭总资产按 `current_value` 汇总
+- 家庭总负债按 `principal_balance` 汇总
+- 详情展示采用当前卡片内行展开
+- 风险等级边界采用：
+  - `<= 1.5 倍` 正常
+  - `> 1.5 倍且 <= 3 倍` 存在风险
+  - `> 3 倍` 高风险
+
+## 设计结论
+
+- 专项排查页不再停留在占位态，需要新增真实业务卡片
+- 前端采用“单卡列表 + 行内展开”方案，与结果总览风格统一
+- 后端新增专项核查专用查询接口，不复用结果总览员工结果表
+- 详情接口需返回收入、资产、负债三组细项，直接支撑前端展开区展示
+
+## 后续动作
+
+- 待用户审阅设计文档后，继续输出前端与后端实施计划