# 数字员工财务报告体系 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`。
