15006a05a7
- 新增数字员工财务报告生成、邮件投递与渲染调度器 - 引入员工画像扫描调度与定时提醒任务 - 完善财务看板快照、排行口径与部门人员占比计算 - 优化数字员工工作看板仪表盘与技能目录 - 增强前端总览页图表、工作台摘要与顶部导航栏交互 - 新增差旅申请规划推动提醒与报销创建会话状态管理 - 补充财务报告、看板调度、数字员工工作记录测试覆盖
329 lines
13 KiB
Markdown
329 lines
13 KiB
Markdown
# 数字员工财务报告体系概念文档
|
||
|
||
更新日期：2026-06-02
|
||
|
||
## 功能一句话
|
||
|
||
让数字员工每周、每季、每年自动汇总企业费用、预算、流程、画像和风险经验，生成图文并茂的 PDF 报告，并按计划投递给财务管理人员。
|
||
|
||
## 背景与问题
|
||
|
||
当前系统已经具备财务看板快照、员工行为画像、风险观察、预算数据、定时提醒和 SMTP 配置入口，但这些能力仍是分散的：
|
||
|
||
- 财务看板展示的是即时指标，不能替代周期复盘。
|
||
- 数字员工已有运行记录，但缺少能给管理层阅读的正式 PDF 报告。
|
||
- 员工画像、预算偏差、风险线索和提醒效果没有被串成企业经验。
|
||
- 周报、季报、年报关注重点不同，不能只用一套普通表格。
|
||
- 邮件投递需要可追踪：生成了什么、发给谁、是否成功、附件是什么。
|
||
|
||
因此本功能新增“财务报告编排员工”，负责把现有沉淀结果组织成管理层报告。
|
||
|
||
## 目标与非目标
|
||
|
||
### 目标
|
||
|
||
- 设计三类周期报告：
|
||
- 周报：每周一上午投递上周财务经营与流程待办。
|
||
- 季报：每季度首周投递上季度预算执行、结构变化和风险复盘。
|
||
- 年报：每年一月投递上一年度费用经营、预算质量、制度经验和改进建议。
|
||
- 报告输出为 PDF，包含图表、重点结论、异常解释和行动建议。
|
||
- 邮件投递给财务管理人员，收件人来自系统设置、角色或配置名单。
|
||
- 报告生成、PDF 渲染、邮件投递都写入数字员工工作记录。
|
||
- 模板可版本化，后续可以调整样式和章节，不影响历史报告。
|
||
|
||
### 非目标
|
||
|
||
- 第一阶段不接入真实外部 BI 平台。
|
||
- 第一阶段不要求复杂拖拽式模板编辑器。
|
||
- 第一阶段不让数字员工自动修改预算、规则或审批结论。
|
||
- 第一阶段不对外发送生产邮件，除非 SMTP 配置和测试收件人已确认。
|
||
- 第一阶段不生成面向普通员工的个人账单报告，先聚焦财务管理层。
|
||
|
||
## 用户与场景
|
||
|
||
- **财务负责人**：阅读周报，知道本周费用规模、预算压力、异常单据和流程卡点。
|
||
- **财务经理**：阅读季报，复盘部门费用结构、预算执行质量和高频风险。
|
||
- **预算管理员**：从报告中看到预算使用率、超支预测、闲置预算和编制提醒。
|
||
- **风控/审计人员**：从报告中看到风险观察、误报样本、制度缺口和重点复核对象。
|
||
- **系统管理员**：查看报告任务是否按计划生成、渲染和发送。
|
||
|
||
## 报告周期与核心用途
|
||
|
||
### 周报
|
||
|
||
定位：经营驾驶舱 + 本周行动清单。
|
||
|
||
适合回答：
|
||
|
||
- 上周花了多少钱，多少单，环比是否异常。
|
||
- 哪些部门、人员、费用类型最突出。
|
||
- 本周有哪些待付款、待补材料、待审批和预算压力。
|
||
- 数字员工发现了哪些风险线索，需要谁处理。
|
||
|
||
### 季报
|
||
|
||
定位：预算执行复盘 + 管理改进。
|
||
|
||
适合回答：
|
||
|
||
- 本季度预算使用是否健康。
|
||
- 哪些部门长期超预算或预算闲置。
|
||
- 哪些费用类型增长过快。
|
||
- 员工画像和供应商画像中出现了什么稳定趋势。
|
||
- 风险规则和制度条款哪里需要人工优化。
|
||
|
||
### 年报
|
||
|
||
定位：年度经营经验沉淀 + 下一年度管理建议。
|
||
|
||
适合回答：
|
||
|
||
- 全年费用结构和预算质量如何。
|
||
- 哪些制度执行效果好，哪些制度经常缺引用或被反馈误报。
|
||
- 哪些部门、岗位、费用类型需要来年重点管理。
|
||
- 数字员工全年沉淀了哪些企业财务经验。
|
||
- 下一年度预算编制、制度修订和风险模型优化建议是什么。
|
||
|
||
## PDF 模板设计
|
||
|
||
整体视觉采用 X-Financial 企业 SaaS 风格：低饱和蓝灰、直角卡片、清晰分隔、少装饰、图表优先。PDF 以 A4 纵向为主，关键图表允许横向宽图。
|
||
|
||
### 统一样式
|
||
|
||
- 字体：中文使用系统黑体或 Noto Sans CJK，数字使用等宽或 Inter 风格数字。
|
||
- 主色：深蓝灰用于标题，财务蓝用于主指标，绿色表示健康，橙色表示预警，红色表示高风险。
|
||
- 页眉：报告名称、周期、生成时间、数字员工名称。
|
||
- 页脚：页码、数据窗口、保密提示。
|
||
- 图表：柱状图、折线图、堆叠条、矩阵热力图、Top N 排行。
|
||
- 每页结构：结论区在上，图表在中，解释和建议在下。
|
||
|
||
### 周报模板
|
||
|
||
建议 8-10 页：
|
||
|
||
1. 封面：报告周期、收件部门、生成时间。
|
||
2. 管理摘要：3-5 条关键结论，突出金额、预算、风险和待办。
|
||
3. 费用总览：报销金额、单数、人均费用、环比变化。
|
||
4. 每日费用趋势：每日金额折线 + 每日单数柱状。
|
||
5. 部门费用排行：Top 部门金额、单数、人均费用。
|
||
6. 预算执行：预算使用率、预警预算池、待释放预占。
|
||
7. 高额单据与个人排行：金额最高单据、金额最高个人、待付款金额。
|
||
8. 流程待办：待审批、待补材料、待付款、待归档。
|
||
9. 风险线索：高风险单据、材料异常、预算压力、重复票据。
|
||
10. 本周行动清单：责任人、事项、建议动作、截止时间。
|
||
|
||
### 季报模板
|
||
|
||
建议 12-16 页：
|
||
|
||
1. 封面。
|
||
2. 季度管理摘要。
|
||
3. 季度费用结构：费用类型占比和季度变化。
|
||
4. 部门预算执行矩阵：部门 x 费用类型预算使用率热力图。
|
||
5. 预算偏差分析：超支、闲置、预占未释放、预测偏差。
|
||
6. 部门经营画像：部门费用强度、流程质量、风险密度。
|
||
7. 员工行为画像：高频报销、退回率、补材料率、异常波动。
|
||
8. 供应商/商户画像：高频商户、集中度、异常关系。
|
||
9. 风险观察复盘：确认率、误报率、高频风险信号。
|
||
10. 制度执行复盘：制度条款命中、缺引用、冲突或过期条款。
|
||
11. 数字员工工作成效：扫描次数、沉淀快照、提醒数量、关闭事项。
|
||
12. 下季度管理建议：预算、制度、流程、风控四类建议。
|
||
|
||
### 年报模板
|
||
|
||
建议 18-24 页：
|
||
|
||
1. 封面。
|
||
2. 年度管理摘要。
|
||
3. 全年费用规模与趋势。
|
||
4. 部门费用结构年度变化。
|
||
5. 预算编制质量：预算准确率、调整频率、超支/闲置分布。
|
||
6. 费用类型策略复盘：差旅、招待、办公、通信等。
|
||
7. 流程效率年度复盘：提交、审批、付款、归档耗时。
|
||
8. 员工画像年度沉淀：费用行为群组和变化。
|
||
9. 供应商画像年度沉淀。
|
||
10. 风险图谱年度复盘。
|
||
11. 制度与规则效果：命中、误报、人工反馈和制度缺口。
|
||
12. 数字员工年度工作记录：任务覆盖、报告、提醒、快照、风险线索。
|
||
13. 下一年度预算编制建议。
|
||
14. 下一年度制度优化建议。
|
||
15. 下一年度风险治理建议。
|
||
16. 附录：指标口径、数据窗口、样本限制。
|
||
|
||
## 邮件投递设计
|
||
|
||
### 收件人
|
||
|
||
收件人优先级：
|
||
|
||
1. 报告任务配置中的固定收件人。
|
||
2. 系统设置中的 `default_receiver`、`notice_email` 或 `admin_email`。
|
||
3. 具有财务管理、预算管理、风控审计角色的员工邮箱。
|
||
|
||
### 邮件内容
|
||
|
||
- 标题：`X-Financial 财务周报 | 2026-05-25 至 2026-05-31`
|
||
- 正文：
|
||
- 报告摘要 3 条。
|
||
- 关键指标 4 个。
|
||
- 待处理行动数量。
|
||
- PDF 附件。
|
||
- 系统内报告详情链接。
|
||
|
||
### 投递追踪
|
||
|
||
每次投递写入数字员工运行记录：
|
||
|
||
- 报告类型：weekly / quarterly / annual。
|
||
- 报告周期。
|
||
- PDF 文件路径或存储 key。
|
||
- 收件人列表。
|
||
- 邮件发送状态。
|
||
- 失败原因。
|
||
- 重试次数。
|
||
|
||
## 后端方案
|
||
|
||
### 新增服务
|
||
|
||
- `finance_report_context.py`：聚合财务看板、预算、风险、画像、提醒、数字员工运行记录。
|
||
- `finance_report_template.py`：定义周报、季报、年报章节和图表配置。
|
||
- `finance_report_renderer.py`：将报告上下文渲染为 HTML，再生成 PDF。
|
||
- `finance_report_mailer.py`：读取 SMTP 配置并发送邮件。
|
||
- `finance_report_scheduler.py`：按周、季、年触发报告生成。
|
||
- `digital_employee_finance_report_task.py`：数字员工任务编排入口。
|
||
|
||
### 数据来源
|
||
|
||
- `expense_claims`、`expense_claim_items`：费用、单据、部门、状态。
|
||
- `budget_allocations`、`budget_transactions`、`budget_reservations`：预算执行。
|
||
- `risk_observations`：风险观察和复核结果。
|
||
- `employee_behavior_profile_snapshots`：员工画像。
|
||
- `agent_runs`、`agent_tool_calls`：数字员工工作记录、提醒扫描、看板快照。
|
||
- `settings`：SMTP 和默认收件人配置。
|
||
|
||
### 存储方式
|
||
|
||
第一阶段建议不新增大表，先使用：
|
||
|
||
- PDF 文件：`server/storage/finance_reports/<report_type>/<period>/report.pdf`
|
||
- 元数据：写入 `agent_runs.route_json.report_delivery`
|
||
|
||
如果后续需要报告列表、重发、下载和归档，再新增 `finance_reports` 表。
|
||
|
||
## 前端方案
|
||
|
||
第一阶段只做必要入口：
|
||
|
||
- 数字员工工作记录中显示“财务周报/季报/年报生成”。
|
||
- 报告运行详情显示摘要、收件人、PDF 路径和发送状态。
|
||
- 系统设置保留 SMTP 配置，不新增复杂模板编辑器。
|
||
|
||
第二阶段新增报告中心：
|
||
|
||
- 报告列表：类型、周期、生成时间、发送状态。
|
||
- 报告详情：PDF 预览、摘要、指标、收件人。
|
||
- 手动生成：选择周期和收件人后触发数字员工。
|
||
- 重发邮件：仅对已有 PDF 重发，不重复计算。
|
||
|
||
## 数字员工新增能力
|
||
|
||
### 必做技能
|
||
|
||
1. **财务报告编排**
|
||
- 把看板、预算、风险、画像和提醒整合为报告上下文。
|
||
- 输出 PDF 和邮件摘要。
|
||
|
||
2. **预算偏差解释**
|
||
- 对预算超支、闲置、预占未释放做原因归因。
|
||
- 输出部门、费用类型和责任人视角建议。
|
||
|
||
3. **流程效率复盘**
|
||
- 沉淀审批、付款、归档耗时。
|
||
- 找出长期卡点和责任角色。
|
||
|
||
4. **制度缺口复盘**
|
||
- 汇总风险观察中缺少制度依据的情况。
|
||
- 提示制度管理员补齐条款，不自动改规则。
|
||
|
||
5. **报告投递与回执跟踪**
|
||
- 记录邮件是否发出、是否失败、是否需要重试。
|
||
|
||
### 可逐步挖掘的高价值技能
|
||
|
||
- **费用结构漂移检测**：发现某部门费用类型占比突然变化。
|
||
- **预算预测与预警**：基于当前消耗预测季度末是否超支。
|
||
- **重复报销关系挖掘**：从员工、商户、发票、地点关系中找重复模式。
|
||
- **供应商集中度监控**：识别费用过度集中到少数商户或供应商。
|
||
- **部门横向对标**：同规模部门人均费用、退回率、补材料率对比。
|
||
- **制度执行热力图**：哪些制度条款最常命中，哪些最常被人工否定。
|
||
- **数字员工建议命中率复盘**：数字员工提醒、风险线索和人工处理结果之间的闭环。
|
||
- **异常趋势早期信号**：在风险尚未形成前发现金额、频次、提交时间的异常变化。
|
||
|
||
## 算法与公式
|
||
|
||
### 周报异常评分
|
||
|
||
$$
|
||
weekly\_alert\_score = 0.35 \times spend\_change + 0.25 \times budget\_pressure + 0.25 \times risk\_density + 0.15 \times process\_delay
|
||
$$
|
||
|
||
其中：
|
||
|
||
- `spend_change`：本周费用环比变化归一化值。
|
||
- `budget_pressure`：预算使用率或预测超支风险。
|
||
- `risk_density`：风险单据金额 / 报销总金额。
|
||
- `process_delay`：逾期待处理事项占比。
|
||
|
||
### 预算预测
|
||
|
||
$$
|
||
predicted\_usage = current\_usage + \frac{current\_usage}{elapsed\_days} \times remaining\_days
|
||
$$
|
||
|
||
当 `predicted_usage > budget_limit` 时，报告标记为预算超支预测。
|
||
|
||
### 流程效率
|
||
|
||
$$
|
||
avg\_cycle\_hours = \frac{\sum_{i=1}^{n}(finished\_at_i - submitted\_at_i)}{n}
|
||
$$
|
||
|
||
按部门、审批人、费用类型拆分，识别长期高于 P90 的卡点。
|
||
|
||
### 报告优先级
|
||
|
||
$$
|
||
section\_priority = 0.4 \times amount\_impact + 0.3 \times risk\_impact + 0.2 \times recurrence + 0.1 \times management\_urgency
|
||
$$
|
||
|
||
用于决定管理摘要中展示哪些结论。
|
||
|
||
## 测试方案
|
||
|
||
- 后端单元测试：报告上下文聚合、模板章节生成、指标计算。
|
||
- PDF 渲染测试：生成 HTML 和 PDF，检查页数、标题、图表占位和附件存在。
|
||
- 邮件测试：使用 mock SMTP，验证标题、收件人、正文和附件。
|
||
- 调度测试：周报、季报、年报触发时间和重复执行保护。
|
||
- 数字员工运行记录测试：确认报告生成和邮件投递写入 `agent_runs`。
|
||
- 容器验证：在 `x-financial-main:/app` 内运行定向 pytest，60s 超时。
|
||
- 手工验证：生成一份周报 PDF，检查图文布局、中文显示、金额格式和页码。
|
||
|
||
## 指标与验收
|
||
|
||
- 可以生成一份周报 PDF，包含摘要、趋势图、部门排行、预算、风险和行动清单。
|
||
- PDF 文件路径写入数字员工运行记录。
|
||
- 邮件 mock 测试能验证附件发送。
|
||
- SMTP 未配置时任务不失败，降级为“生成成功、投递待配置”。
|
||
- 周报、季报、年报模板均有独立章节定义。
|
||
- 报告中的单号、部门、金额、状态来自真实数据库聚合。
|
||
- 数字员工看板能看到报告生成任务和结果摘要。
|
||
|
||
## 风险与开放问题
|
||
|
||
- PDF 渲染依赖中文字体和浏览器/渲染库环境，必须在容器内验证。
|
||
- 真实 SMTP 投递涉及外部邮件服务器，需要先用测试收件人验证。
|
||
- 若后续要求报告下载、重发、审阅状态和历史归档，建议新增 `finance_reports` 表。
|
||
- 季报和年报需要更稳定的画像和风险反馈数据，否则前期只能展示模拟或有限结论。
|
||
- 图表渲染要避免依赖前端 ECharts 截图，优先后端生成可控 SVG/HTML 图表。
|