# 数字员工财务报告体系概念文档 更新日期：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.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 图表。