# 数字员工工作看板概念文档

## 功能一句话

在分析看板中新增“数字员工看板”，让用户用一个统一视角看到数字员工每天执行了哪些后台分析、整理、积累和评估工作，以及这些工作产生了什么业务结果。

## 背景与问题

当前数字员工已经有“员工技能”和“工作记录”页面，但工作记录偏运行明细，适合追溯单次任务。管理者在分析看板中缺少一个汇总视角，无法快速回答：

- 今天数字员工是否真的在工作。
- 哪些技能执行最多。
- 成功、失败、运行中的任务分别是多少。
- 风险图谱、风险线索、员工画像和知识整理分别产出了什么。
- 最近失败或异常的后台任务是否需要处理。

新增看板后，分析看板承担“经营和运行洞察”入口，数字员工页面继续承担“技能配置、工作记录详情和人工操作”入口。

## 目标与非目标

### 目标

- 在分析看板顶部切换项中新增“数字员工看板”。
- 用真实 `AgentRun` 和 `AgentToolCall` 数据聚合数字员工工作，不使用演示数据伪装真实结果。
- 展示最近 N 天的工作总数、成功数、失败数、运行中数量、产出量和日趋势。
- 区分技能类型：积累、升级、整理、评估。
- 展示最近工作记录，用户能直观看到每天做了什么和产出了什么。

### 非目标

- 不替代数字员工页面的“员工技能”和“工作记录”详情。
- 不让数字员工执行规则中心主流程，也不让数字员工定义、发布或确认风险规则。
- 不展示内部实现名称或技术代号，页面文案统一使用“数字员工”。
- 不在本期新增新的算法执行器，只消费已有执行结果做分析看板聚合。

## 用户与场景

- 财务负责人：查看数字员工每天是否持续产出知识整理、风险观察、画像快照和线索。
- 风控与审计人员：查看评估、升级类任务的失败与产出情况，判断是否需要复核。
- 系统管理员：观察后台任务是否运行稳定，识别失败任务和数据异常。

## 功能能力

### 输入

- `agent_runs`：数字员工运行记录。
- `agent_tool_calls`：每次运行中的工具调用与响应摘要。
- `route_json` / `request_json` / `response_json`：用于识别任务类型、任务编码、报告类型和产出指标。

### 输出

- KPI 指标：工作总数、成功数量、失败数量、运行中数量、业务产出、成功率。
- 每日工作趋势：按日期聚合总数、成功、失败和主要产出量。
- 技能类型分布：积累、升级、整理、评估。
- 工作模块排行：财务风险图谱巡检、员工行为画像巡检、风险线索归集、知识制度整理等。
- 最近工作记录：任务名称、状态、开始时间、耗时、摘要和关键指标。

### 状态

- 成功：`succeeded`、`success`、`completed`、`done`。
- 失败：`failed`、`failure`、`error`、`errored`。
- 运行中：`running`、`pending`。
- 其他状态统一归入“其他”，但不丢弃记录。

### 权限与边界

- 本期沿用分析看板已有访问控制，不新增独立权限。
- 看板只读，不提供运行、定时、编辑技能等操作。
- 单次运行详情仍在数字员工工作记录页面处理。

## 方案设计

### 后端

新增 `DigitalEmployeeDashboardService`：

- 从 `AgentRun` 查询最近 `days` 天数据，最多取 `limit` 条。
- 通过 `agent == "hermes"`、`source == "schedule"`、`route_json` 任务字段、工具名 `digital_employee.*` 和知识整理任务类型识别数字员工工作。
- 从工具响应中提取业务产出指标，例如风险观察数、风险线索数、画像快照数、知识文档数。
- 返回稳定结构，前端只负责展示，不重复推断核心聚合逻辑。

新增接口：

```http
GET /api/v1/analytics/digital-employee-dashboard?days=7&limit=300
```

### 前端

新增 `DigitalEmployeeDashboard.vue`：

- 复用现有 `OverviewView` 的 KPI 卡片、`dashboard-card`、`BarChart` 和企业级直角视觉。
- 使用两列到多列的看板网格，避免新增营销化卡片风格。
- 状态、空数据和加载错误保持与风险看板一致。

接入点：

- `TopBar.vue` 增加“数字员工看板”切换项。
- `OverviewView.vue` 新增 `activeDashboard === "digitalEmployee"` 分支。
- `useOverviewView.js` 新增数据加载、KPI 映射、趋势行和排行行。
- `analytics.js` 新增接口调用和字段归一化。

## 算法与公式

### 成功率

$$
success\_rate = \frac{success\_runs}{max(total\_runs, 1)}
$$

### 失败率

$$
failure\_rate = \frac{failed\_runs}{max(total\_runs, 1)}
$$

### 业务产出量

$$
business\_outputs = risk\_observations + risk\_clues + profile\_snapshots + knowledge\_documents
$$

### 日工作负载

$$
daily\_workload_d = total\_runs_d + business\_outputs_d
$$

以上公式只用于看板展示和排序，不参与规则中心决策。

## 测试方案

- 后端单元测试：构造数字员工运行、普通智能体运行、失败运行和工具响应，验证聚合结果。
- 接口测试：验证 `/analytics/digital-employee-dashboard` 返回字段结构和空数据行为。
- 前端静态测试：验证切换项、接口地址、组件分支和核心文案存在。
- 构建验证：运行前端构建，确保新增 Vue 组件可编译。
- 容器验证：在 `x-financial-main` 中运行后端定向测试，并调用真实接口确认返回 JSON。

## 指标与验收

- 分析看板切换中出现“数字员工看板”。
- 选择该看板后页面显示 KPI、每日工作、技能类型分布、任务排行和最近工作。
- 没有真实数据时显示空状态，不使用伪造业务数。
- 接口返回 `has_real_data`，前端可据此判断真实数据状态。
- 后端定向测试和前端定向测试通过。

## 风险与开放问题

- 旧版 `hermes_task_execution_logs` 中的日志没有完整工具响应，本期优先以 `AgentRun` 为准；如需兼容旧日志，可后续做补充。
- 部分新增技能当前可能只有定义，未必已有真实执行结果，看板会显示为 0 或不出现。
- 如果后续新增数字员工技能，需要同步更新任务类型映射，避免看板归类为“其他”。
