# 半年报销模拟数据概念文档 ## 功能一句话 为本地演示环境生成 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 趋势和自定义日期范围。 - 如果后续要支持页面一键生成，需要另行设计权限、审计和清理机制。