补充专项核查展开区改版设计文档

2026-03-25 15:29:44 +08:00
parent 78ae93330c
commit 5867cd5057
2 changed files with 337 additions and 0 deletions
--- a/docs/design/2026-03-25-special-check-family-asset-liability-detail-redesign-design.md
+++ b/docs/design/2026-03-25-special-check-family-asset-liability-detail-redesign-design.md
@@ -0,0 +1,302 @@
+# 专项核查员工家庭资产负债展开区改版设计
+
+**日期**: 2026-03-25  
+**模块**: 项目详情 - 专项核查 - 员工家庭资产负债专项核查  
+**作者**: Codex  
+**状态**: 已确认
+
+## 1. 概述
+
+当前专项核查页中的“员工家庭资产负债专项核查”已经具备列表与展开详情能力，但展开区仍沿用“三列卡片 + 表格明细”的结构，与最新原型存在明显差异：
+
+- 信息层级偏散，展开后阅读路径不稳定
+- 逐条明细表过重，不符合当前原型的“汇总式详查”表达
+- 资产、负债、指标和风险结论没有形成清晰的纵向阅读节奏
+
+本次设计只改造展开后的详情展示效果，不调整列表层字段、列顺序、查看详情交互、接口契约和页面路由。
+
+## 2. 设计目标
+
+### 2.1 包含内容
+
+- 仅改造 `FamilyAssetLiabilityDetail.vue` 的展开区展示结构
+- 展开区改为自上而下 5 张纵向汇总卡片
+- 每张卡片标题直接展示该模块汇总数字
+- 卡片内部简洁展示汇总数据的来源项
+- 资产与负债来源项改为按现有类型聚合后全部展示
+- 风险结论按真实风险等级切换样式与文案
+
+### 2.2 不包含内容
+
+- 不调整列表层列顺序、列文案和操作按钮
+- 不改造 `查看详情` 的交互入口和按需加载机制
+- 不新增后端字段、后端接口或路由
+- 不保留现有逐条表格明细展示
+- 不增加兼容分支、降级分支、二级折叠或 tooltip 解释
+
+## 3. 当前上下文
+
+当前前端相关文件：
+
+- `ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilitySection.vue`
+- `ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilityDetail.vue`
+- `ruoyi-ui/src/views/ccdiProject/components/detail/SpecialCheck.vue`
+- `ruoyi-ui/src/api/ccdi/projectSpecialCheck.js`
+
+当前详情接口已返回以下结构：
+
+- `incomeDetail`
+- `assetDetail`
+- `debtDetail`
+- `summary`
+
+其中 `summary` 已包含：
+
+- `totalIncome`
+- `totalDebt`
+- `totalAsset`
+- `comparisonAmount`
+- `riskLevelCode`
+- `riskLevelName`
+
+这意味着本次改版无需调整接口，即可直接支撑总额、净资产、关键指标和风险结果展示。
+
+## 4. 视觉方向
+
+### 4.1 Visual Thesis
+
+展开区改为“工作台式纵向汇总带”，每段只承载一个核心结论，用浅灰标题条、白底内容区和简洁来源项建立稳定层级。
+
+### 4.2 Content Plan
+
+1. 总收入
+2. 总负债
+3. 总资产
+4. 关键指标
+5. 详查结果
+
+### 4.3 Interaction Thesis
+
+- 保留现有“点击列表行内展开”的唯一交互，不额外增加二级折叠
+- 通过模块顺序和标题汇总值强化信息导向，不靠复杂动效制造层级
+- 风险结果卡通过颜色和结论文案形成唯一视觉落点
+
+## 5. 方案比较
+
+### 5.1 方案 A：完全沿用现有三列卡片，仅替换表格样式
+
+做法：
+
+- 保留 `收入 / 负债 / 资产` 三列结构
+- 仅把内部表格改成更轻的列表展示
+
+优点：
+
+- 改动最少
+
+缺点：
+
+- 与原型的纵向分段结构不一致
+- 无法形成“总额 -> 指标 -> 结论”的阅读链路
+
+### 5.2 方案 B：双列摘要面板
+
+做法：
+
+- 左侧聚合资产和负债
+- 右侧聚合指标和结果
+
+优点：
+
+- 信息比较紧凑
+
+缺点：
+
+- 更像通用后台摘要区，不够贴近原型
+- 用户新确认的顺序无法自然落地
+
+### 5.3 方案 C：纵向 5 段汇总卡片
+
+做法：
+
+- 展开区改为 5 张单列卡片，顺序固定为：
+  - 总收入
+  - 总负债
+  - 总资产
+  - 关键指标
+  - 详查结果
+- 每张卡片标题右侧直接展示汇总值
+- 资产、负债卡片内部仅展示聚合后的来源项
+
+优点：
+
+- 最贴近当前确认原型和用户确认顺序
+- 只动详情组件，改动边界最清晰
+- 能自然去掉逐条表格，收拢成简洁汇总式详查
+
+缺点：
+
+- 放弃现有逐条明细表阅读方式
+
+### 5.4 结论
+
+采用 **方案 C：纵向 5 段汇总卡片**。
+
+原因：
+
+1. 完整匹配用户最终确认顺序
+2. 不改接口即可实现
+3. 视觉层级清晰，符合原型的“汇总式展开详情”目标
+
+## 6. 总体设计
+
+### 6.1 展开区结构
+
+展开区固定改为以下顺序：
+
+1. `总收入`
+2. `总负债`
+3. `总资产`
+4. `关键指标`
+5. `详查结果`
+
+每个模块都采用统一结构：
+
+- 标题左侧：模块名称
+- 标题右侧：该模块汇总数字
+- 内容区：来源项或指标项
+
+### 6.2 模块规则
+
+#### 6.2.1 总收入
+
+标题右侧展示 `家庭总年收入`。
+
+内容区固定展示两条来源项：
+
+- 本人收入
+- 配偶收入
+
+不新增额外说明文字。
+
+#### 6.2.2 总负债
+
+标题右侧展示 `家庭总负债`。
+
+内容区展示“按现有负债类型聚合后的来源项”，每条结构统一为：
+
+- 负债类型名
+- 聚合金额
+- 占总负债比例
+
+所有聚合项全部展示，不截断、不合并为“其他”。
+
+#### 6.2.3 总资产
+
+标题右侧展示 `家庭总资产`。
+
+内容区展示“按现有资产类型聚合后的来源项”，每条结构统一为：
+
+- 资产类型名
+- 聚合金额
+- 占总资产比例
+
+所有聚合项全部展示，不截断、不合并为“其他”。
+
+#### 6.2.4 关键指标
+
+标题右侧固定展示指标数 `3`。
+
+内容区固定展示以下 3 项：
+
+- 资产负债率 = 总负债 / 总资产
+- 资产/收入比 = 总资产 / 总收入
+- 负债/收入比 = 总负债 / 总收入
+
+展示格式：
+
+- 百分比项使用 `%`
+- 倍数项使用 `倍`
+- 分母为 `0` 时显示 `-`
+
+#### 6.2.5 详查结果
+
+标题右侧展示 `riskLevelName`。
+
+内容区展示单条结论文案，按真实风险等级切换样式和文案：
+
+- `NORMAL`：结构基本合理
+- `RISK`：负债与收入压力偏高
+- `HIGH`：资产负债结构明显异常
+- `MISSING_INFO`：当前信息不完整
+
+不新增二级解释区。
+
+## 7. 数据映射与计算规则
+
+### 7.1 直接取值
+
+- 总收入：`incomeDetail.totalIncome` 或 `summary.totalIncome`
+- 总负债：`debtDetail.totalDebt` 或 `summary.totalDebt`
+- 总资产：`assetDetail.totalAsset` 或 `summary.totalAsset`
+- 风险等级：`summary.riskLevelCode`、`summary.riskLevelName`
+
+### 7.2 前端计算
+
+- 净资产 = 总资产 - 总负债
+- 资产负债率 = 总负债 / 总资产
+- 资产/收入比 = 总资产 / 总收入
+- 负债/收入比 = 总负债 / 总收入
+
+### 7.3 聚合规则
+
+资产来源项：
+
+- 基于 `assetDetail.items`
+- 按现有类型字段聚合
+- 保留全部聚合项
+
+负债来源项：
+
+- 基于 `debtDetail.items`
+- 按现有类型字段聚合
+- 保留全部聚合项
+
+本次不要求后端新增分类字段，统一由前端基于现有字段归并。
+
+## 8. 样式约束
+
+- 取消现有逐条明细表和表头
+- 资产、负债来源项改为紧凑摘要条目
+- 桌面端可使用两列或三列流式排布承载来源项
+- 窄屏回落为单列
+- 金额统一使用 `¥` + 千分位格式
+- 标题区与内容区仍延续专项核查现有白底大区块语义，不引入新主题色体系
+
+## 9. 验证要点
+
+### 9.1 结构验证
+
+- 展开区顺序必须为：总收入 -> 总负债 -> 总资产 -> 关键指标 -> 详查结果
+- 每张卡片标题中必须出现对应汇总数字
+- 资产与负债来源项不再使用表格
+
+### 9.2 计算验证
+
+- 关键指标基于当前总额值计算，不重复请求接口
+- 分母为 `0` 时显示 `-`
+- 风险结果卡的标题和结论文案与真实风险等级一致
+
+### 9.3 范围验证
+
+- 列表层结构、列顺序和交互不变
+- 接口路径与返回结构不变
+- 项目切换、展开缓存和首次展开按需加载机制不变
+
+## 10. 实施边界
+
+本次前端实施默认只涉及：
+
+- `ruoyi-ui/src/views/ccdiProject/components/detail/FamilyAssetLiabilityDetail.vue`
+
+必要时补充与该组件直接相关的单元测试与样式断言，但不扩大到列表层和后端实现。
--- a/docs/reports/implementation/2026-03-25-special-check-family-asset-liability-detail-redesign-design-record.md
+++ b/docs/reports/implementation/2026-03-25-special-check-family-asset-liability-detail-redesign-design-record.md
@@ -0,0 +1,35 @@
+# 2026-03-25 专项核查员工家庭资产负债展开区改版设计记录
+
+## 本次改动文件
+
+- 新增 `docs/design/2026-03-25-special-check-family-asset-liability-detail-redesign-design.md`
+
+## 本次记录内容
+
+- 明确本次需求只改“员工家庭资产负债专项核查”的展开区，不改列表层
+- 通过多轮确认收敛出最终展示顺序：
+  - 总收入
+  - 总负债
+  - 总资产
+  - 关键指标
+  - 详查结果
+- 明确每张卡片标题必须展示对应汇总数字
+- 明确资产与负债来源项改为“按现有类型聚合后全部展示”
+- 明确逐条明细表不再保留，改为简洁汇总来源项
+- 明确风险结论按真实风险等级切换样式与文案
+- 明确本次改版只依赖现有详情接口，不新增后端字段或兼容方案
+
+## 设计收口说明
+
+- 采用“纵向 5 段汇总卡片”方案，不使用双列面板或二级折叠
+- 关键指标固定为 3 项：
+  - 资产负债率
+  - 资产/收入比
+  - 负债/收入比
+- 净资产只作为计算结果参与指标表达，不单独新增到用户最终确认顺序中
+
+## 评审说明
+
+- 按 brainstorming 规范本应进入 spec review loop
+- 由于仓库 `AGENTS.md` 明确要求“不开启 subagent”，本次改用本地人工自检替代子代理评审
+- 自检结论：文档路径正确、范围边界明确、未引入需求外方案、计算链路完整可落地