155 lines
6.1 KiB
Markdown
155 lines
6.1 KiB
Markdown
|
# 半年报销模拟数据概念文档
|
|||
|
|
|
|||
|
|
## 功能一句话
|
|||
|
|
|
|||
|
|
为本地演示环境生成 2026 年上半年公司报销、预算和员工组织样本，让财务看板与预算中心能直接呈现半年经营分析效果。
|
|||
|
|
|
|||
|
|
## 背景与问题
|
|||
|
|
|
|||
|
|
当前容器数据库已有员工与预算基础表，但报销样本很少，无法观察半年维度的费用趋势、部门支出结构、预算使用率和风险预警效果。用户希望把公司人数扩充到 100 人，并模拟半年报销数据，用于查看整体分析和预算管控效果。
|
|||
|
|
|
|||
|
|
现状只读检查结果：
|
|||
|
|
|
|||
|
|
- `employees=82`
|
|||
|
|
- `expense_claims=3`
|
|||
|
|
- `budget_allocations=240`
|
|||
|
|
- `budget_transactions=241`
|
|||
|
|
- `risk_observations=0`
|
|||
|
|
- 尚无 `SIM2026` 员工、`SIM-EXP-2026` 报销单和 `SIM-BUD-2026` 预算数据。
|
|||
|
|
|
|||
|
|
## 目标与非目标
|
|||
|
|
|
|||
|
|
目标：
|
|||
|
|
|
|||
|
|
- 把本地演示公司员工补齐到 100 人，不删除已有员工。
|
|||
|
|
- 生成 2026 年 1 月到 6 月的报销单、报销明细和风险观察样本。
|
|||
|
|
- 生成或复用预算额度，并写入预算核销台账，让预算中心能看到真实使用率、预警和超支。
|
|||
|
|
- 保证脚本默认 dry-run，只有显式 `--apply` 才写数据库。
|
|||
|
|
- 生成完成后能用容器内 DB 统计和真实 API 返回值验证。
|
|||
|
|
|
|||
|
|
非目标：
|
|||
|
|
|
|||
|
|
- 不接入真实生产 API，不导入真实个人敏感数据。
|
|||
|
|
- 不删除或重置用户已有数据；如未来需要清理模拟数据，应另走显式确认。
|
|||
|
|
- 不改造预算中心、财务看板和报销审批页面结构。
|
|||
|
|
- 不把模拟数据写入启动流程，避免每次启动自动膨胀数据。
|
|||
|
|
|
|||
|
|
## 用户与场景
|
|||
|
|
|
|||
|
|
- 财务负责人：查看半年费用趋势、待审批金额、风险数量和 SLA。
|
|||
|
|
- 预算管理者：查看部门和费用科目的预算使用率、预警线和剩余额度。
|
|||
|
|
- 产品演示者：用 100 人组织规模演示智能费控、预算中心和分析看板的联动。
|
|||
|
|
|
|||
|
|
## 功能能力
|
|||
|
|
|
|||
|
|
### 输入
|
|||
|
|
|
|||
|
|
- 目标员工数：默认 100。
|
|||
|
|
- 模拟窗口：默认 `2026-01-01` 到 `2026-06-30`。
|
|||
|
|
- 随机种子：固定值，确保样本可复现。
|
|||
|
|
- 执行模式：默认 dry-run，`--apply` 写入数据库。
|
|||
|
|
|
|||
|
|
### 输出
|
|||
|
|
|
|||
|
|
- 新增员工：只补齐缺口，员工编号前缀 `SIM2026`。
|
|||
|
|
- 新增报销单：编号前缀 `SIM-EXP-2026`。
|
|||
|
|
- 新增明细：按报销单生成 1 到 3 条费用明细。
|
|||
|
|
- 新增预算额度：编号前缀 `SIM-BUD-2026`，按部门、季度、费用科目覆盖差旅、招待、办公和通信。
|
|||
|
|
- 新增预算交易：编号前缀 `SIM-BTX-2026`，对已通过、待付款、已付款和完成状态写入 `consume` 台账，对待审批状态写入 `reserve` 台账。
|
|||
|
|
- 新增风险观察：编号前缀 `SIM-RISK-2026`，用于财务看板风险混合和异常数统计。
|
|||
|
|
|
|||
|
|
### 边界
|
|||
|
|
|
|||
|
|
- 如果员工数已经大于等于 100，只新增 0 人，不删除已有员工。
|
|||
|
|
- 如果同编号模拟数据已存在，脚本跳过，保证重复执行不重复膨胀。
|
|||
|
|
- 预算使用率通过交易台账计算，不直接改写预算余额字段。
|
|||
|
|
- 预算超支样本允许存在，用于展示预算效果和预警，但需要控制比例，避免所有部门都显示异常。
|
|||
|
|
|
|||
|
|
## 方案设计
|
|||
|
|
|
|||
|
|
### 后端脚本
|
|||
|
|
|
|||
|
|
新增独立服务模块：
|
|||
|
|
|
|||
|
|
- `demo_company_simulation_seed.py`：封装模拟数据规划、dry-run 统计和 apply 写入。
|
|||
|
|
|
|||
|
|
新增命令脚本：
|
|||
|
|
|
|||
|
|
- `seed_half_year_expense_demo.py`：解析参数并调用服务模块。
|
|||
|
|
|
|||
|
|
### 数据策略
|
|||
|
|
|
|||
|
|
- 组织：复用现有 `OrganizationUnit`，优先使用部门节点和成本中心。
|
|||
|
|
- 员工：补齐到 100 人，按部门规模权重分配，职级覆盖 P3-P8。
|
|||
|
|
- 报销单：按员工、月份、费用类型生成，低频员工 1-2 单，高频角色 4-8 单。
|
|||
|
|
- 风险：约 12%-18% 的报销单带风险标记和 `RiskObservation`。
|
|||
|
|
- 预算：按部门、季度、科目创建模拟预算额度，Q2 相比 Q1 有 8%-18% 增长，部分市场、技术部门科目接近 80% 预警线。
|
|||
|
|
|
|||
|
|
### 运行命令
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-main \
|
|||
|
|
/tmp/x-financial-server-venv/bin/python server/scripts/seed_half_year_expense_demo.py
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
写入时使用：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-main \
|
|||
|
|
/tmp/x-financial-server-venv/bin/python server/scripts/seed_half_year_expense_demo.py --apply
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 算法与公式
|
|||
|
|
|
|||
|
|
### 员工缺口
|
|||
|
|
|
|||
|
|
$$
|
|||
|
|
new\_employees = \max(target\_employees - current\_employees,\ 0)
|
|||
|
|
$$
|
|||
|
|
|
|||
|
|
### 报销金额
|
|||
|
|
|
|||
|
|
每类费用按基础金额、部门系数、职级系数和月度季节系数生成：
|
|||
|
|
|
|||
|
|
$$
|
|||
|
|
claim\_amount = base\_amount(type) \times dept\_factor \times grade\_factor \times month\_factor \times noise
|
|||
|
|
$$
|
|||
|
|
|
|||
|
|
### 预算使用率
|
|||
|
|
|
|||
|
|
预算中心沿用现有计算口径：
|
|||
|
|
|
|||
|
|
$$
|
|||
|
|
usage\_rate = \frac{reserved\_amount + consumed\_amount}{original\_amount + adjusted\_amount} \times 100
|
|||
|
|
$$
|
|||
|
|
|
|||
|
|
### 风险样本概率
|
|||
|
|
|
|||
|
|
风险概率按金额分位和预算压力提升：
|
|||
|
|
|
|||
|
|
$$
|
|||
|
|
risk\_probability = base\_risk + amount\_boost + budget\_pressure\_boost
|
|||
|
|
$$
|
|||
|
|
|
|||
|
|
## 测试方案
|
|||
|
|
|
|||
|
|
- 单元测试：在 SQLite 内存库里验证 dry-run、员工补齐、幂等写入和预算交易统计。
|
|||
|
|
- 容器验证：在 `x-financial-main` 内运行定向测试，单次不超过 60s。
|
|||
|
|
- 运行时验证：执行 dry-run 后检查计划数量；执行 apply 前必须人工确认。
|
|||
|
|
- API 验证：写入后请求财务看板和预算汇总接口，确认 JSON 中员工、报销、预算使用率和风险指标有数据。
|
|||
|
|
|
|||
|
|
## 指标与验收
|
|||
|
|
|
|||
|
|
- 员工总数达到 100。
|
|||
|
|
- `SIM-EXP-2026` 半年报销单不少于 300 单。
|
|||
|
|
- 预算汇总接口返回 Q1、Q2 趋势，且至少有 1 条预算预警。
|
|||
|
|
- 财务看板 `has_real_data=true`，风险数、费用分类、部门排行和预算摘要均非空。
|
|||
|
|
- 重复执行脚本不会新增重复模拟数据。
|
|||
|
|
|
|||
|
|
## 风险与开放问题
|
|||
|
|
|
|||
|
|
- 批量写入数据库属于高风险操作，执行 `--apply` 前必须获得用户明确确认。
|
|||
|
|
- 如果当前数据库已有大量非模拟员工，脚本不会删除员工来凑精确 100 人，只保证不少于目标数。
|
|||
|
|
- 财务看板趋势接口当前最多按 90 天标签解析；半年分析主要依赖预算中心 Q1/Q2 趋势和自定义日期范围。
|
|||
|
|
- 如果后续要支持页面一键生成，需要另行设计权限、审计和清理机制。
|