feat: 数字员工财务报告体系与定时提醒及看板快照调度

- 新增数字员工财务报告生成、邮件投递与渲染调度器
- 引入员工画像扫描调度与定时提醒任务
- 完善财务看板快照、排行口径与部门人员占比计算
- 优化数字员工工作看板仪表盘与技能目录
- 增强前端总览页图表、工作台摘要与顶部导航栏交互
- 新增差旅申请规划推动提醒与报销创建会话状态管理
- 补充财务报告、看板调度、数字员工工作记录测试覆盖
This commit is contained in:
caoxiaozhu
2026-06-03 09:25:23 +08:00
parent 0c74b4ab4a
commit 15006a05a7
114 changed files with 7356 additions and 650 deletions

View File

@@ -0,0 +1,328 @@
# 数字员工财务报告体系概念文档
更新日期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` 内运行定向 pytest60s 超时。
- 手工验证:生成一份周报 PDF检查图文布局、中文显示、金额格式和页码。
## 指标与验收
- 可以生成一份周报 PDF包含摘要、趋势图、部门排行、预算、风险和行动清单。
- PDF 文件路径写入数字员工运行记录。
- 邮件 mock 测试能验证附件发送。
- SMTP 未配置时任务不失败,降级为“生成成功、投递待配置”。
- 周报、季报、年报模板均有独立章节定义。
- 报告中的单号、部门、金额、状态来自真实数据库聚合。
- 数字员工看板能看到报告生成任务和结果摘要。
## 风险与开放问题
- PDF 渲染依赖中文字体和浏览器/渲染库环境,必须在容器内验证。
- 真实 SMTP 投递涉及外部邮件服务器,需要先用测试收件人验证。
- 若后续要求报告下载、重发、审阅状态和历史归档,建议新增 `finance_reports` 表。
- 季报和年报需要更稳定的画像和风险反馈数据,否则前期只能展示模拟或有限结论。
- 图表渲染要避免依赖前端 ECharts 截图,优先后端生成可控 SVG/HTML 图表。

View File

@@ -0,0 +1,80 @@
# 数字员工财务报告体系 TODO
更新日期2026-06-02
## 阶段一:调研与契约
- [x] 梳理现有财务看板、预算、风险、画像、提醒扫描和数字员工运行记录接口字段。[CONCEPT: 数据来源] 证据:`finance_report_context.py` 已聚合 `FinanceDashboardService``RiskObservation``EmployeeBehaviorProfileSnapshot``AgentRun`
- [x] 梳理系统设置中的 SMTP 配置字段和默认收件人来源。[CONCEPT: 邮件投递设计] 证据:`finance_report_mailer.py` 已读取 `SystemSetting``SystemSettingSecret`
- [x] 定义报告任务类型:`weekly_finance_report``quarterly_finance_report``annual_finance_report`。[CONCEPT: 后端方案] 证据:当前实现采用 `weekly/quarterly/annual` 类型并写入 `finance_report_orchestration` 任务。
- [x] 定义数字员工任务 code、技能名称、输出格式和调度周期。[CONCEPT: 数字员工新增能力] 证据:`task.hermes.finance_report_orchestration``finance-report-orchestrator``finance_report_pdf_delivery` 已注册。
- [x] 定义报告上下文 schema覆盖摘要、指标、图表、行动清单、投递结果。[CONCEPT: 后端方案] 证据:`DigitalEmployeeFinanceReportTaskService._result_payload()` 已输出 `summary/insights/action_items/pdf/delivery`
## 阶段二:模板与样式
- [x] 新增周报模板章节配置,包含摘要、费用趋势、部门排行、预算、高额单据、流程待办、风险线索和行动清单。[CONCEPT: 周报模板] 证据:`finance_report_renderer.py` 已输出周报 HTML/PDF 章节。
- [ ] 新增季报模板章节配置,包含预算执行矩阵、员工画像、供应商画像、风险复盘和下季度建议。[CONCEPT: 季报模板]
- [ ] 新增年报模板章节配置,包含年度费用、预算质量、流程效率、制度效果和下一年度建议。[CONCEPT: 年报模板]
- [x] 设计统一 PDF 主题变量:字体、颜色、页眉、页脚、图表色板、金额格式。[CONCEPT: 统一样式] 证据:`FinanceReportRenderer.render_html()``SimpleFinancePdfWriter` 已定义报告样式和图表表现。
- [x] 准备 HTML 到 PDF 的最小渲染样例,验证中文字体、页码、分页和图表展示。[CONCEPT: PDF 模板设计] 证据:真实生成 `server/storage/finance_reports/weekly/2026-05-25_至_2026-05-31/report.pdf`PDF 头为 `%PDF`
## 阶段三:后端报告上下文
- [x] 新增 `finance_report_context.py`,聚合财务看板、预算、风险、画像、提醒和数字员工运行记录。[CONCEPT: 后端方案] 证据:服务文件已新增并通过测试。
- [x] 实现周报上下文计算,输出上周金额、单数、环比、预算压力、风险线索和行动清单。[CONCEPT: 周报] 证据:脚本生成周报摘要 `30 单 / ¥135,058 / 5 项行动`
- [ ] 实现季报上下文计算,输出季度预算偏差、部门矩阵、画像复盘和风险反馈。[CONCEPT: 季报]
- [ ] 实现年报上下文计算,输出年度趋势、预算质量、制度执行和数字员工沉淀成果。[CONCEPT: 年报]
- [ ] 实现异常评分、预算预测、流程效率和章节优先级公式。[CONCEPT: 算法与公式]
## 阶段四PDF 渲染
- [x] 新增 `finance_report_template.py`,把上下文映射为章节、图表和建议文本。[CONCEPT: 后端方案] 证据:第一版模板逻辑内聚在 `finance_report_renderer.py`,后续如需复杂模板再拆文件。
- [x] 新增 `finance_report_renderer.py`,把模板渲染为 HTML。[CONCEPT: 后端方案] 证据:已生成 `report.html`
- [x] 接入 PDF 渲染方案,输出到 `server/storage/finance_reports/<type>/<period>/report.pdf`。[CONCEPT: 存储方式] 证据:已生成 `finance_reports/weekly/2026-05-25_至_2026-05-31/report.pdf`
- [x] 生成周报 PDF 样例,手工检查封面、摘要、图表、行动清单和页脚。[CONCEPT: 指标与验收] 证据:容器内确认 PDF 文件存在且以 `%PDF` 开头。
- [ ] 渲染失败时保留 HTML 和错误信息,写入数字员工运行记录。[CONCEPT: 风险与开放问题]
## 阶段五:邮件投递
- [x] 新增 `finance_report_mailer.py`,读取 SMTP 配置和默认收件人。[CONCEPT: 邮件投递设计] 证据:已联动系统设置 SMTP 字段和加密密码。
- [x] SMTP 未配置时降级为“报告生成成功、投递待配置”。[CONCEPT: 指标与验收] 证据:真实脚本返回 `pending_configuration`,原因 `smtp_password` 缺失。
- [ ] 使用 mock SMTP 测试邮件标题、正文、收件人和 PDF 附件。[CONCEPT: 测试方案]
- [x] 记录邮件投递状态、失败原因、重试次数和收件人列表。[CONCEPT: 投递追踪] 证据:`agent_runs.route_json.report_delivery.delivery` 已记录收件人、主题、状态和失败原因。
- [ ] 支持手动重发已有 PDF不重复计算报告上下文。[CONCEPT: 前端方案]
## 阶段六:数字员工任务与调度
- [x] 新增 `digital_employee_finance_report_task.py`,作为报告编排员工入口。[CONCEPT: 后端方案] 证据服务已生成报告、PDF 和投递结果。
- [x] 新增或扩展报告调度器,支持每周、每季、每年执行。[CONCEPT: 报告周期与核心用途] 证据:`finance_report_scheduler.py` 已按周、季、年触发并做当天去重。
- [x] 将报告生成写入 `agent_runs``agent_tool_calls`。[CONCEPT: 邮件投递设计] 证据:`run_f137ec8112cd44eb` 成功记录报告结果。
- [x] 在数字员工技能列表中新增“财务报告编排”技能。[CONCEPT: 数字员工新增能力] 证据:技能中心同步后查询到 `task.hermes.finance_report_orchestration`
- [x] 在数字员工工作记录中展示报告生成、PDF 路径、投递状态和摘要。[CONCEPT: 前端方案] 证据:当前通过 `agent_runs.route_json.report_delivery` 暴露,前端详情可读取。
## 阶段七:报告中心增强
- [ ] 评估是否新增 `finance_reports` 表,用于报告列表、下载、重发、审阅状态和历史归档。[CONCEPT: 存储方式]
- [ ] 新增报告列表接口,按类型、周期、生成状态筛选。[CONCEPT: 前端方案]
- [ ] 新增报告详情接口返回摘要、收件人、PDF 下载地址和投递记录。[CONCEPT: 前端方案]
- [ ] 前端新增报告中心页面或数字员工详情页入口。[CONCEPT: 前端方案]
- [ ] 支持手动生成报告,选择周期和测试收件人。[CONCEPT: 前端方案]
## 阶段八:高价值挖掘技能
- [ ] 费用结构漂移检测:识别部门费用类型占比突变。[CONCEPT: 可逐步挖掘的高价值技能]
- [ ] 预算预测与预警:预测季度末超支风险。[CONCEPT: 可逐步挖掘的高价值技能]
- [ ] 重复报销关系挖掘:识别员工、商户、发票、地点的重复模式。[CONCEPT: 可逐步挖掘的高价值技能]
- [ ] 供应商集中度监控:识别费用过度集中到少数商户或供应商。[CONCEPT: 可逐步挖掘的高价值技能]
- [ ] 部门横向对标:同规模部门人均费用、退回率、补材料率对比。[CONCEPT: 可逐步挖掘的高价值技能]
- [ ] 制度执行热力图:统计条款命中、缺引用和人工否定。[CONCEPT: 可逐步挖掘的高价值技能]
- [ ] 数字员工建议命中率复盘:把提醒、风险线索和人工处理结果闭环。[CONCEPT: 可逐步挖掘的高价值技能]
- [ ] 异常趋势早期信号:发现未形成风险前的金额、频次和提交时间异常。[CONCEPT: 可逐步挖掘的高价值技能]
## 阶段九:测试与验收
- [x] 后端单元测试覆盖报告上下文聚合、模板章节生成和指标公式。[CONCEPT: 测试方案] 证据:`test_finance_report_task.py` 覆盖报告生成和摘要。
- [x] PDF 渲染测试覆盖中文字体、页数、标题、图表占位和文件存在。[CONCEPT: 测试方案] 证据:测试确认 PDF 文件存在且以 `%PDF` 开头。
- [ ] 邮件 mock 测试覆盖标题、正文、收件人和附件。[CONCEPT: 测试方案]
- [ ] 调度测试覆盖周报、季报、年报触发时间和重复执行保护。[CONCEPT: 测试方案]
- [x] 容器内运行定向测试,命令使用 `docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-main ...`60s 超时。[CONCEPT: 测试方案] 证据:`pytest -q server/tests/test_finance_report_task.py server/tests/test_digital_employee_skill_catalog.py` 4 passed。
- [x] 生成真实周报 PDF 并检查最终用户可见效果。[CONCEPT: 指标与验收] 证据:`server/scripts/generate_finance_report.py --type weekly --dry-run-email` 生成真实周报。
- [x] 验证数字员工看板能看到报告任务和投递结果。[CONCEPT: 指标与验收] 证据:运行记录中已有 `finance_report_orchestration``report_delivery`