X-Financial/document/development/数字员工财务报告体系/CONCEPT.md

数字员工财务报告体系概念文档

更新日期：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 图表。