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

- 新增数字员工财务报告生成、邮件投递与渲染调度器 - 引入员工画像扫描调度与定时提醒任务 - 完善财务看板快照、排行口径与部门人员占比计算 - 优化数字员工工作看板仪表盘与技能目录 - 增强前端总览页图表、工作台摘要与顶部导航栏交互 - 新增差旅申请规划推动提醒与报销创建会话状态管理 - 补充财务报告、看板调度、数字员工工作记录测试覆盖
2026-06-03 09:25:23 +08:00
parent 0c74b4ab4a
commit 15006a05a7
114 changed files with 7356 additions and 650 deletions
--- a/document/development/数字员工财务经验沉淀与定时提醒/CONCEPT.md
+++ b/document/development/数字员工财务经验沉淀与定时提醒/CONCEPT.md
@@ -0,0 +1,227 @@
+# 数字员工财务经验沉淀与定时提醒概念文档
+
+更新日期：2026-06-02
+
+## 功能一句话
+
+把数字员工定位为后台财务数据分析员：定时沉淀企业财务经验，周期性生成分析报告，并在审批、预算、出差申请和报销流程中生成可追踪的提醒建议。
+
+## 背景与问题
+
+当前数字员工已经具备技能目录、财务看板快照和员工行为画像扫描能力，但业务价值仍偏弱：
+
+- 技能列表数量多，但多数只是能力定义，缺少持续沉淀和行动产出。
+- 员工画像已有数据，但如果不持续沉淀，系统不会随企业数据变多而变聪明。
+- 财务流程中存在大量需要定时推动的事项，例如领导审批、预算编制、出差申请到期、报销补材料和归档。
+- 现在缺少统一的后台提醒扫描结果，无法证明数字员工每天发现了哪些待处理事项、提醒了谁、为什么提醒。
+
+因此本功能把数字员工拆成三条主线：
+
+- **行为沉淀技能**：每天小颗粒沉淀费用、预算、单据、流程、画像经验。
+- **定时提醒技能**：按时间窗口扫描待办事项，生成面向责任人的提醒清单。
+- **周期报告技能**：读取沉淀结果和提醒效果，形成企业财务经验报告。
+
+## 目标与非目标
+
+### 目标
+
+- 建立数字员工“后台分析员”定位，不再把全部技能包装成前台执行能力。
+- 收敛技能体系为行为沉淀、定时提醒、周期报告三类。
+- 第一阶段落地一个真实可运行的 **定时提醒扫描任务**。
+- 提醒扫描使用现有业务数据，不新增数据库结构，结果写入 `agent_runs` 和 `agent_tool_calls`。
+- 提醒扫描至少覆盖：
+  - 待审批单据提醒。
+  - 预算编制/预算缺口提醒。
+  - 出差申请到期后待报销提醒。
+  - 报销逾期、补材料、付款/归档提醒。
+- 数字员工看板能够看到提醒扫描的运行记录和提醒产出数量。
+
+### 非目标
+
+- 第一阶段不做站内信、邮件、短信或企业微信真实投递。
+- 第一阶段不新增提醒表、已读表、重复提醒去重表等数据库结构。
+- 第一阶段不替代审批、付款、预算编制和报销操作，只生成提醒建议。
+- 第一阶段不让数字员工自动修改单据状态、预算状态或审批结果。
+- 第一阶段不做完整报告页面，只把提醒报告结构化写入运行记录。
+
+## 用户与场景
+
+- **部门领导**：每天收到待审批单据汇总，知道待审数量、最高金额、最长等待时间。
+- **预算管理员**：在预算周期临近或预算池缺失时收到编制/补齐提醒。
+- **出差员工**：出差申请结束后未报销时收到报销或延长申请提醒。
+- **财务人员**：看到报销逾期、补材料、付款、归档等流程卡点。
+- **财务负责人**：周期性查看提醒扫描报告，判断哪些流程经常阻塞。
+- **系统管理员**：在数字员工看板查看提醒任务是否稳定运行。
+
+## 功能能力
+
+### 行为沉淀技能
+
+后续应逐步沉淀以下经验快照：
+
+- 费用结构基线：部门、费用类型、月份、单数、金额、均值、P90。
+- 预算执行偏差：使用率、闲置率、超支风险、预测偏差。
+- 报销行为画像：员工/部门报销频率、金额区间、退回率、补材料率。
+- 单据质量经验：缺附件、发票异常、金额不一致、退回原因。
+- 流程效率经验：提交到审批、审批到付款、付款到归档的耗时。
+- 制度执行经验：制度条款命中频率、人工否定频率、制度缺口。
+
+### 定时提醒技能
+
+第一阶段实现 `digital_employee_reminder_scan`，生成统一提醒报告：
+
+- `approval_pending`：待审批提醒。
+- `budget_compilation`：预算编制/预算池缺口提醒。
+- `travel_application_expiry`：出差申请已结束但未报销提醒。
+- `reimbursement_overdue`：报销逾期、补材料、待付款、待归档提醒。
+
+提醒报告只写入数字员工运行记录，结构包含：
+
+- 扫描时间和窗口。
+- 每类提醒数量。
+- 每个收件人的提醒摘要。
+- 关联单据、金额、最长等待时间、建议动作。
+- 是否需要人工处理。
+
+### 周期报告技能
+
+后续在沉淀和提醒任务稳定后生成：
+
+- 每日财务经营摘要。
+- 周度流程效率复盘。
+- 月度预算执行复盘。
+- 半年度企业财务经验报告。
+
+## 方案设计
+
+### 后端
+
+第一阶段新增三个后端模块：
+
+- `digital_employee_reminder_task.py`：执行提醒扫描，写入 `AgentRun`。
+- `digital_employee_reminder_scheduler.py`：后台调度器，默认每天 02:00 扫描，可配置首次延迟用于开发验证。
+- `digital_employee_dashboard.py`：扩展任务类型和指标，让看板统计提醒产出。
+
+提醒扫描复用现有表：
+
+- `expense_claims`：报销单和费用申请单。
+- `employees`：员工、直属领导、角色。
+- `budget_allocations`：预算池。
+- `agent_runs` / `agent_tool_calls`：数字员工运行记录。
+
+### 数据输出结构
+
+运行记录中的 `route_json.report` 使用如下结构：
+
+```json
+{
+  "title": "数字员工定时提醒扫描报告",
+  "generatedAt": "2026-06-02T02:00:00+08:00",
+  "windowDays": 14,
+  "totals": {
+    "recipientCount": 8,
+    "reminderCount": 23,
+    "approvalPendingCount": 7,
+    "budgetReminderCount": 4,
+    "travelApplicationReminderCount": 5,
+    "reimbursementOverdueCount": 7
+  },
+  "recipients": [
+    {
+      "recipientId": "emp-001",
+      "recipientName": "张三",
+      "recipientRole": "manager",
+      "reminders": [
+        {
+          "type": "approval_pending",
+          "priority": "high",
+          "title": "你有 3 笔报销单待审批",
+          "action": "请在今日处理审批待办",
+          "relatedDocuments": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 前端
+
+第一阶段不新增独立页面。数字员工看板通过已有最近运行记录展示：
+
+- 任务名称：定时提醒扫描。
+- 产出数量：提醒数量。
+- 最近摘要：提醒了多少人、多少条事项。
+
+后续可在数字员工工作记录详情中扩展“提醒报告详情”。
+
+## 算法与公式
+
+### 提醒优先级
+
+提醒优先级由等待天数、金额和业务类型决定：
+
+$$
+priority\_score = 0.45 \times wait\_score + 0.35 \times amount\_score + 0.20 \times type\_score
+$$
+
+其中：
+
+- `wait_score = min(wait_days / threshold_days, 1)`
+- `amount_score = min(amount / high_amount_threshold, 1)`
+- `type_score`：审批、预算、出差、报销流程分别给定基础分。
+
+优先级映射：
+
+$$
+priority =
+\begin{cases}
+high, & priority\_score \ge 0.75 \\
+medium, & 0.45 \le priority\_score < 0.75 \\
+low, & priority\_score < 0.45
+\end{cases}
+$$
+
+### 待审批等待天数
+
+$$
+wait\_days = floor((now - submitted\_at) / 86400)
+$$
+
+如果 `submitted_at` 为空，则使用 `updated_at` 或 `created_at` 降级计算。
+
+### 预算缺口识别
+
+当前阶段使用预算池存在性和周期作为提醒依据：
+
+$$
+budget\_gap = active\_allocation\_count = 0
+$$
+
+当当前年度/期间没有有效预算池，或预算池处于非 active/published 状态时，生成预算编制提醒。
+
+## 测试方案
+
+- 后端单元测试：构造员工、领导、报销单、申请单和预算池，验证提醒报告数量与收件人。
+- 看板聚合测试：构造 `digital_employee_reminder_scan` 运行记录，验证 `reminders` 指标被统计。
+- 调度器测试：验证 scheduler 能调用任务服务，不重复启动。
+- 容器验证：在 `x-financial-main:/app` 内运行定向 pytest，60s 超时。
+- 运行时验证：重启容器后查询 `agent_runs`，确认提醒扫描记录成功生成。
+- HTTP 验证：调用 `/api/v1/analytics/digital-employee-dashboard`，确认任务分布包含定时提醒扫描。
+
+## 指标与验收
+
+- `agent_runs` 中出现 `task_type=digital_employee_reminder_scan` 的成功运行。
+- 工具响应包含 `recipient_count`、`reminder_count` 和四类提醒计数。
+- 数字员工看板 `businessOutputs` 计入提醒数量。
+- 最近运行记录展示“定时提醒扫描”。
+- 定向测试通过。
+- 不新增数据库结构，不改变现有单据状态。
+
+## 风险与开放问题
+
+- 第一阶段只生成提醒报告，不做真实消息投递；后续需要站内信/邮件/企业微信时再新增消息模型。
+- 当前预算编制状态模型还不完整，第一阶段只能基于预算池缺口和期间判断。
+- 出差申请到期依赖申请单中的 `application_detail.time`，如果历史数据缺失，只能降级使用 `occurred_at`。
+- 审批责任人目前主要通过员工直属领导推断，复杂动态审批流需要后续对接审批路由结果。
+- 如果后续需要“已读/已处理/重复提醒抑制”，必须新增提醒表或消息表，并进行数据库迁移确认。
--- a/document/development/数字员工财务经验沉淀与定时提醒/TODO.md
+++ b/document/development/数字员工财务经验沉淀与定时提醒/TODO.md
@@ -0,0 +1,39 @@
+# 数字员工财务经验沉淀与定时提醒开发 TODO
+
+## 阶段一：调研与文档
+
+- [x] 梳理现有数字员工技能、画像扫描、财务看板快照和看板聚合链路。[CONCEPT: 背景与问题] 证据：已核对 `agent_foundation_digital_employee_tasks.py`、`digital_employee_dashboard.py`、`employee_profile_scan_task.py`。
+- [x] 梳理审批、预算、出差申请和报销单模型字段。[CONCEPT: 方案设计] 证据：已核对 `approval.py`、`budget.py`、`financial_record.py`、`user_agent_application.py`。
+- [x] 明确第一阶段不新增数据库结构，只用 `agent_runs` 和 `agent_tool_calls` 保存提醒扫描报告。[CONCEPT: 目标与非目标] 证据：`CONCEPT.md` 已写明。
+- [x] 创建概念文档和开发 TODO。[CONCEPT: 全文] 证据：本目录 `CONCEPT.md` 与 `TODO.md`。
+
+## 阶段二：后端提醒扫描任务
+
+- [x] 新增 `digital_employee_reminder_task.py`，定义 `DigitalEmployeeReminderTaskService`。[CONCEPT: 后端] 证据：新增服务文件并通过 ruff。
+- [x] 实现待审批提醒扫描，按直属领导聚合待审批单据。[CONCEPT: 定时提醒技能] 证据：`test_digital_employee_reminder_task.py` 覆盖 `approval_pending`。
+- [x] 实现预算编制/预算缺口提醒，按当前年度和期间识别预算池缺口。[CONCEPT: 定时提醒技能] 证据：`test_digital_employee_reminder_task.py` 覆盖 `budget_compilation`。
+- [x] 实现出差申请到期提醒，识别已结束但未报销或未关闭的申请单。[CONCEPT: 定时提醒技能] 证据：`test_digital_employee_reminder_task.py` 覆盖 `travel_application_expiry`。
+- [x] 实现报销逾期/补材料/付款/归档提醒，识别流程卡点。[CONCEPT: 定时提醒技能] 证据：`test_digital_employee_reminder_task.py` 覆盖 `reimbursement_overdue`。
+- [x] 将提醒报告写入 `AgentRun` 和 `AgentToolCall`，包含 `recipient_count`、`reminder_count` 和分类计数。[CONCEPT: 数据输出结构] 证据：任务服务测试读取返回 summary 与 report。
+
+## 阶段三：调度与看板
+
+- [x] 新增 `digital_employee_reminder_scheduler.py`，默认每天 02:00 扫描，支持开发环境首次延迟运行。[CONCEPT: 后端] 证据：新增调度器并通过 ruff。
+- [x] 在 `main.py` 生命周期中启动和关闭提醒调度器。[CONCEPT: 后端] 证据：`main.py` 已接入 scheduler start/shutdown。
+- [x] 扩展 `DigitalEmployeeDashboardService`，识别 `digital_employee_reminder_scan`。[CONCEPT: 前端] 证据：看板聚合测试覆盖 task type。
+- [x] 看板指标增加提醒产出计数，最近运行记录显示“定时提醒扫描”。[CONCEPT: 指标与验收] 证据：`test_digital_employee_dashboard_service.py` 覆盖 `reminders` 和 `businessOutputs`。
+
+## 阶段四：测试与验证
+
+- [x] 新增后端单元测试，验证四类提醒的收件人、数量和摘要。[CONCEPT: 测试方案] 证据：`server/tests/test_digital_employee_reminder_task.py`。
+- [x] 新增数字员工看板聚合测试，验证提醒数量进入 `businessOutputs`。[CONCEPT: 测试方案] 证据：`server/tests/test_digital_employee_dashboard_service.py`。
+- [x] 在容器内运行 ruff：`docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-main /tmp/x-financial-server-venv/bin/python -m ruff check <changed-files>`。[CONCEPT: 测试方案] 证据：All checks passed。
+- [x] 在容器内运行定向 pytest，超时 60s，验证提醒任务和看板聚合。[CONCEPT: 测试方案] 证据：`5 passed in 3.39s`。
+- [x] 重启 `x-financial-main`，查询 `agent_runs` 确认提醒扫描运行记录成功生成。[CONCEPT: 指标与验收] 证据：`run_4c3a2b847fae4ada` succeeded，提醒 47 人，生成 403 条事项。
+- [x] 调用 `/api/v1/analytics/digital-employee-dashboard`，确认任务分布包含定时提醒扫描。[CONCEPT: 指标与验收] 证据：HTTP 200，`reminders=403`，任务分布包含 `digital_employee_reminder_scan`。
+
+## 后续阶段：消息投递闭环
+
+- [ ] 评估是否新增提醒消息表、已读状态和重复提醒抑制策略。[CONCEPT: 风险与开放问题]
+- [ ] 设计站内信、邮件或企业微信投递通道。[CONCEPT: 非目标]
+- [ ] 设计提醒处理结果回流，用于沉淀“哪些提醒真正有效”。[CONCEPT: 行为沉淀技能]