# 财务看板口径重构与画像模拟概念文档

## 功能一句话

把财务看板从“审批过程展示”调整为“财务费用经营分析”，并让半年模拟数据自然形成部门、预算、风险和员工画像。

## 背景与问题

当前财务看板存在三类偏差：

- 费用结构里直接展示 `travel_application` 等技术枚举，业务用户无法理解，且申请类口径不应混入报销费用结构。
- 风险异常分布缺少完整中文映射，`missing_material`、`budget_pressure` 等风险信号以英文或半翻译方式泄露到页面。
- 趋势图和底部卡片仍围绕审批量、审批时长展开，不符合财务看板的核心诉求。

半年模拟数据也需要服务于看板分析，不能只堆单据。它必须能支撑多部门费用排行、预算消耗、风险分布和员工画像。

## 目标

- 费用结构只展示费用科目中文名称，申请类技术值不裸露。
- 风险异常分布统一中文化，并覆盖预算压力、材料缺失、预算超支等常见信号。
- 趋势图改为每日报销数量和每日报销金额。
- “审批瓶颈”改为财务关注项，展示预算、待付款、材料待补、风险金额等财务指标。
- 部门排行按费用金额统计，而不是只看待处理审批金额。
- 模拟数据在写入后可生成员工行为画像快照，画像与报销单据、预算压力和风险观察一致。

## 非目标

- 不重做财务看板整体视觉框架。
- 不新增一套独立画像算法。
- 不修改生产环境数据；所有批量修复只作用于 `SIM2026`、`SIM-EXP-2026`、`SIM-BUD-2026` 等模拟前缀数据。

## 用户与场景

- 财务经理：查看半年费用趋势、部门费用结构、预算执行和风险异常。
- 部门负责人：理解本部门费用消耗和预算压力。
- 审批人：查看员工画像时，能看到基于半年模拟数据形成的费用和流程质量画像。
- 系统演示人员：用 100 人规模的模拟数据演示端到端效果。

## 功能能力

### 费用结构

输入为当前时间范围内有效报销单。

输出为费用科目金额占比：

- 排除草稿、退回、驳回、删除等非有效支出状态。
- `travel_application` 等申请类值不直接展示；若历史数据仍存在，则归一为“差旅费”或从费用结构中排除申请类虚拟项。
- 所有展示名称必须是中文。

### 风险异常分布

输入为风险观察和报销单风险标记。

输出为中文风险类型分布：

- `missing_material`：材料不完整
- `budget_pressure`：预算压力偏高
- `budget_overrun`：预算超支
- `duplicate_invoice`：重复发票
- `split_billing`：拆分报销
- `amount_outlier`：金额异常

未知枚举用“风险观察”兜底，不能把英文下划线文案直接展示给用户。

### 每日报销趋势

趋势图按天返回：

- `claimCount`：每日有效报销单数量
- `claimAmount`：每日有效报销金额

前端使用柱线组合图展示，左轴为单量，右轴为金额。

### 财务关注项

替代原“审批瓶颈”：

- 预算超支：超支预算池数量和金额。
- 预算预警：预算使用率接近上限的池数量。
- 材料待补：材料不完整风险数量。
- 风险金额：当前范围内风险单据金额。
- 待付款：已审批待付款金额。

### 员工画像

模拟数据写入后触发现有 `EmployeeBehaviorProfileService`：

- 生成 30、90、180 天画像快照。
- 画像类型沿用费用支出、流程质量、AI 使用和审批行为。
- 不伪造画像结果，只用模拟报销单、审批记录和风险数据驱动算法。

## 方案设计

### 后端

- 在 `FinanceDashboardService` 中新增费用类型与风险信号归一化方法。
- 将 `_trend` 改为统计每日有效报销数量和金额，同时保留旧字段兼容前端灰度。
- 将 `_department_ranking` 改为按有效费用金额统计。
- 将 `_bottlenecks` 的返回语义改为财务关注项，字段名暂保留，降低接口破坏面。
- 模拟数据脚本增加画像刷新入口，调用现有画像服务生成快照。

### 前端

- `TrendChart` 文案改为“报销单量”和“报销金额”。
- `OverviewView` 标题改为：
  - 报销数量与金额趋势
  - 部门报销排行（费用金额）
  - 财务关注项
- 底部列表继续复用现有紧凑卡片样式，不引入新视觉体系。

### 数据

- 部门分布按业务权重分配，避免只有市场部或技术部。
- 近 10 日和本月窗口保证各核心部门都有可见费用。
- 风险样本覆盖材料缺失、预算压力、重复发票、金额异常等类型。
- 预算台账与报销单金额一致，能体现预警和超支。

## 算法与公式

费用金额：

$$
amount_d = \sum_{c \in C_d} claimAmount(c)
$$

其中 \(C_d\) 为某日有效状态报销单集合。

部门费用排行：

$$
deptSpend_i = \sum_{c \in C_i} claimAmount(c)
$$

预算使用率：

$$
usageRate = \frac{reservedAmount + consumedAmount}{totalAmount} \times 100\%
$$

风险金额：

$$
riskAmount = \sum_{c \in C, hasRisk(c)=true} claimAmount(c)
$$

## 测试方案

- 后端单元测试：验证费用类型中文化、风险信号中文化、趋势字段、部门排行和财务关注项。
- 容器接口测试：在 `x-financial-main:/app` 调用 `/api/v1/analytics/finance-dashboard`。
- 前端构建：使用项目现有 `npm.cmd` 构建路径。
- 数据脚本 dry-run：确认模拟修复仅作用于 `SIM` 前缀数据。
- 画像验证：确认 `employee_behavior_profile_snapshots` 生成模拟员工的快照。

## 指标与验收

- 财务看板接口不再返回 `travel_application`、`missing material`、`budget pressure` 等裸英文展示名。
- 趋势字段包含 `claimCount` 和 `claimAmount`，前端标题不再出现“审批趋势”。
- 部门排行至少覆盖 6 个核心部门的有效费用金额。
- 财务关注项不再显示审批节点或平均处理时长。
- 半年模拟数据可生成 100 人规模下的员工画像快照。

## 风险与开放问题

- 历史非模拟数据可能仍有 `待补充` 部门，当前方案只保证模拟数据合理，不强行修复历史数据。
- 批量修复模拟数据涉及数据库更新和重建模拟预算台账，执行 `--apply` 前需要用户明确确认。
- 前端浏览器验证若环境不稳定，可降级为接口 JSON、构建和容器内测试证据。
