0c74b4ab4a
- 重构 finance_dashboard 口径计算，新增模拟公司画像数据生成与筛选 - 引入 expense_claim_status_registry 统一报销状态流转 - 完善报销草稿流程、Item Sync 与本体解析器 - 优化总览页趋势图、分页组件与请求进度步骤 - 增强报销申请快速预览、本体工具与详情展示 - 新增半年报销模拟数据种子脚本与状态审计工具 - 补充财务看板、报销状态注册与模拟数据测试覆盖
6.1 KiB
6.1 KiB
半年报销模拟数据概念文档
功能一句话
为本地演示环境生成 2026 年上半年公司报销、预算和员工组织样本，让财务看板与预算中心能直接呈现半年经营分析效果。
背景与问题
当前容器数据库已有员工与预算基础表，但报销样本很少，无法观察半年维度的费用趋势、部门支出结构、预算使用率和风险预警效果。用户希望把公司人数扩充到 100 人，并模拟半年报销数据，用于查看整体分析和预算管控效果。
现状只读检查结果：
employees=82expense_claims=3budget_allocations=240budget_transactions=241risk_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% 预警线。
运行命令
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
写入时使用：
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 趋势和自定义日期范围。
- 如果后续要支持页面一键生成，需要另行设计权限、审计和清理机制。