# 数字员工财务经验沉淀与定时提醒概念文档

更新日期：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`。
- 审批责任人目前主要通过员工直属领导推断，复杂动态审批流需要后续对接审批路由结果。
- 如果后续需要“已读/已处理/重复提醒抑制”，必须新增提醒表或消息表，并进行数据库迁移确认。