YG-Soft/X-Financial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 新增员工行为画像算法与费用风险标签体系

Browse Source 
后端新增员工行为画像算法模块，支持标签规则引擎和评分计算，
完善员工模型、银行信息、序列化和导入逻辑，优化报销审批流
和工作流常量，增强 Hermes 同步和知识同步能力，前端新增费
用画像详情弹窗、雷达图和风险卡片组件，完善登录页和工作台
样式，优化文档中心和归档中心交互，补充单元测试。
This commit is contained in:
caoxiaozhu
2026-05-28 12:09:49 +08:00
parent 04cd6d0f81
commit 8a4a777be7
96 changed files with 9835 additions and 704 deletions
Download Patch File Download Diff File Expand all files Collapse all files

515
document/development/budget-expense-control-model-plan/employee_behavior_profile_model.md Normal file
View File

@@ -0,0 +1,515 @@
# 员工业务行为画像模型方案
## 目标
员工业务行为画像用于把费用申请、审批流转、AI 协作和数字员工巡检中产生的行为数据沉淀为可解释的统计画像。
它不是给员工贴负面标签，也不是替代审批人做最终判断，而是为以下场景提供结构化依据：
- 费用审批详情页展示申请人近期费用节奏和材料质量。
- Hermes 数字员工定期巡检高频费用、异常预算占用和流程质量问题。
- 运营看板观察 AI 使用、Token 消耗、流程耗时和审核效率。
- 后续规则中心根据真实覆盖率和人工覆盖情况优化规则阈值。
## 设计原则
1. 不把不同性质的数据混成一个总分。
2. 费用风险、流程质量、AI 使用、审批行为必须分维度计算。
3. 画像结果必须能追溯到指标、窗口期、同组基准和计算时间。
4. Hermes 负责调度和沉淀快照，确定性算法负责计算，LLM 只可用于解释和报告。
5. 画像用于审批参考和运营治理，不直接作为惩罚或自动降标依据。
## 画像分层
```text
员工业务行为画像
├── 费用支出画像
├── 流程质量画像
├── AI 协作画像
└── 审批行为画像
```
### 费用支出画像
用于判断申请人的费用节奏是否显著高于同组基准。
核心指标：
- 近 30 / 90 / 180 天申请次数。
- 近 30 / 90 / 180 天申请金额。
- 差旅申请次数、出差天数、日均费用。
- 招待申请次数、人均招待金额、同客户重复招待次数。
- 个人费用占部门预算比例。
- 个人费用占项目预算比例。
- 同部门、同岗位、同费用类型分位数。
- 历史调减、退回、复核次数。
审批用途：
- 识别高频费用申请人。
- 提醒审核者复核出差天数和费用标准。
- 推荐补充业务必要性、拆分费用或升级审批。
### 流程质量画像
用于判断申请人提交材料和流程配合质量。
核心指标：
- 草稿到提交平均耗时。
- 退回到重新提交平均耗时。
- 退单次数。
- 补充材料次数。
- 附件缺失次数。
- 发票金额不一致次数。
- 申请事由缺失次数。
- 业务地点缺失次数。
- 项目编号缺失次数。
- 同一申请多次修改次数。
审批用途：
- 提示“近期材料质量偏低，需要重点核对附件和事由”。
- 对高频退单申请人提高材料完整性检查权重。
- 对低质量申请触发补充材料建议，而不是直接判定费用风险。
### AI 协作画像
用于观察员工和系统的 AI 协作行为，不直接判定费用风险。
核心指标：
- AI 调用次数。
- AI 辅助生成申请次数。
- AI 解析票据次数。
- AI 预审次数。
- 语义解析次数。
- 输入 Token。
- 输出 Token。
- 总 Token。
- 估算调用成本。
- AI 建议被采纳次数。
- AI 建议被人工覆盖次数。
- AI 生成后人工修改次数。
运营用途：
- 观察哪些流程高度依赖 AI。
- 识别高成本用户、部门或功能入口。
- 衡量 AI 建议采纳率和被覆盖率。
- 为模型配置、成本控制和产品优化提供依据。
审批边界：
AI 使用多不等于风险高。Token 消耗、AI 调用次数不应直接推高费用审批风险，只能作为运营和辅助说明。
### 审批行为画像
用于分析审批人的审核效率和审核风格。
核心指标：
- 平均审核时长。
- 中位审核时长。
- 超 SLA 次数。
- 直接通过率。
- 退回率。
- 调减率。
- 高风险单据通过率。
- 系统建议采纳率。
- 系统建议覆盖率。
- 审批意见完整度。
- 审批积压数量。
治理用途：
- 识别审批积压。
- 识别过度宽松或过度退回的审批模式。
- 评估规则建议是否被人工持续覆盖。
- 为流程优化和审批授权调整提供依据。
## 计算窗口
第一版建议支持三个窗口：
```text
30 天：识别近期异常波动
90 天：作为审批详情页默认画像
180 天：用于稳定趋势和年度预算节奏
```
审批详情页默认读取 `90 天` 画像。运营看板可以切换 30 / 90 / 180 天。
## 同组基准
费用支出画像必须和可比人群比较，不能全公司一刀切。
建议同组口径：
```text
peer_group =
department_id
+ position
+ grade
+ expense_type_scope
+ city_tier
+ project_type
+ window_days
```
当某个同组样本量不足时，逐级回退：
```text
部门 + 岗位 + 费用类型
→ 部门 + 费用类型
→ 岗位 + 费用类型
→ 公司 + 费用类型
```
回退必须写入 `peer_group_fallback_level`，避免审核者误以为基准非常精确。
## 分值模型
### 不建议使用一个大总分
不要这样计算：
```text
综合风险分 = 费用金额 + Token 消耗 + 操作时长 + 审核时长 + 退单次数
```
原因：
- Token 高可能代表高频使用 AI，不代表费用风险。
- 审核时长是审批人的行为，不是申请人的费用风险。
- 退单次数可能代表材料质量问题，不一定代表费用不合理。
- 一个总分会掩盖到底是哪一类风险触发。
### 建议使用多维分
```text
employee_behavior_profile =
expense_profile_score
process_quality_score
ai_usage_score
approval_behavior_score
```
每个分值都有自己的等级：
```text
0-39 normal
40-59 watch
60-79 review
80-100 escalation
```
审批详情页只展示与当前场景相关的分值：
```text
费用申请审批：
展示 expense_profile_score
展示 process_quality_score
隐藏或弱化 ai_usage_score
不展示 approval_behavior_score
运营看板：
展示四类分值和趋势
```
## 指标权重建议
### 费用支出画像分
```text
expense_profile_score =
frequency_score * 20%
+ amount_occupancy_score * 25%
+ peer_deviation_score * 25%
+ adjustment_history_score * 15%
+ current_claim_deviation_score * 15%
```
### 流程质量画像分
```text
process_quality_score =
return_count_score * 25%
+ missing_attachment_score * 20%
+ invoice_mismatch_score * 20%
+ resubmit_duration_score * 15%
+ missing_business_context_score * 20%
```
### AI 协作画像分
AI 协作分不命名为风险分，建议叫 `ai_usage_intensity_score`。
```text
ai_usage_intensity_score =
ai_call_count_score * 25%
+ token_cost_score * 25%
+ ai_generated_claim_ratio_score * 20%
+ ai_suggestion_override_score * 20%
+ failed_ai_call_score * 10%
```
含义：
- 分数高代表 AI 使用强度高或成本高。
- 不代表员工费用风险高。
- 主要用于成本治理、流程优化和模型配置。
### 审批行为画像分
审批行为分不命名为风险分，建议叫 `approval_behavior_score`。
```text
approval_behavior_score =
avg_review_duration_score * 20%
+ sla_overdue_score * 20%
+ direct_approve_ratio_score * 20%
+ high_risk_approve_score * 20%
+ system_advice_override_score * 20%
```
含义：
- 分数高代表审批行为需要运营关注。
- 不直接代表审批人存在问题。
- 必须结合审批量、单据复杂度和部门业务特性解释。
## 数据来源
### 费用与流程数据
主要来源：
- `expense_claims`
- `expense_claim_items`
- 审批流转记录
- 退回 / 调减 / 补充材料记录
- 预算池和预算交易记录
需要补齐或确认的数据：
- 审批开始时间。
- 审批完成时间。
- 退回原因结构化字段。
- 调减前后金额。
- 补充材料事件。
- 审批意见是否为空。
### AI 与工具调用数据
主要来源：
- `AgentRun`
- `AgentToolCall`
- `SemanticParseLog`
- `runtime_chat.py`
- `ontology.py`
- `user_agent.py`
- `ocr.py`
需要注意：
不是所有模型入口都已经完整持久化 Token。第一版必须区分：
```text
exact_token_count：真实记录的 Token
estimated_token_count：按文本长度估算
unavailable：当前不可用
```
不能把估算值包装成真实计费数据。
## 存储设计
建议第一版使用通用画像快照表：
```text
employee_behavior_profile_snapshots
```
字段建议：
```text
id
subject_type applicant / approver / employee
subject_id employee_id
subject_name
department_id
department_name
position
grade
profile_type expense / process_quality / ai_usage / approval
window_days 30 / 90 / 180
expense_type_scope overall / travel / entertainment / ...
peer_group_key
peer_group_fallback_level
profile_score
profile_level
metrics_json
basis_codes_json
source_task_type
source_task_log_id
calculated_at
created_at
```
### 为什么用快照表
不要把画像直接写入员工表：
```text
employee.profile_score = 80
```
原因：
- 员工表是主数据，画像是动态计算结果。
- 审批审计需要知道当时为什么是这个分。
- 算法规则调整后，历史依据不能被覆盖。
- 快照可以支持趋势分析。
### 是否每个员工都存
不建议全员每天存。
第一版只存：
- 近 90 / 180 天有费用申请记录的员工。
- 当前存在待审批申请的员工。
- 上一期画像等级为 `watch`、`review`、`escalation` 的员工。
- AI 使用或审批行为达到运营关注阈值的员工。
无行为员工不生成画像快照。
## Hermes 调度策略
不重新写调度器，复用 Hermes 现有 cron 调度体系。
建议新增任务类型：
```text
employee_behavior_profile_scan
```
任务职责：
```text
1. 识别本次需要刷新画像的员工集合。
2. 聚合费用、流程、AI、审批行为指标。
3. 调用各画像子算法。
4. 写入 employee_behavior_profile_snapshots。
5. 在 HermesTaskExecutionLog 写入执行摘要。
```
建议频率：
```text
事件触发：申请提交、审批完成、退回、调减、AI 任务完成后，刷新相关员工。
每日轻量：只扫描昨日新增行为和上一期高关注员工。
每周全量：刷新同组基准、分位数和活跃员工画像。
每月复盘：分析阈值、规则覆盖率和人工覆盖率。
```
## 审批详情展示
费用审批详情页建议展示：
```text
申请人费用画像
流程材料质量
本次申请实时偏离
```
不建议在普通审批详情页直接展示：
```text
Token 消耗
AI 调用成本
审批人行为分
```
这些更适合管理员运营看板。
示例展示：
```text
申请人费用画像
近 90 天 · 销售部 / 客户经理 / 差旅费
状态：重点复核
触发依据：
- 近 90 天差旅金额处于同组 P88。
- 本次出差天数为同类 P75 的 1.67 倍。
- 最近 180 天存在 3 次调减或退回记录。
审核建议：
- 建议确认本次 5 天行程是否可压缩至 4 天。
- 如确属关键客户推进，请补充客户拜访安排和预期产出。
```
## 运营看板展示
管理员或运营人员可以看到更完整的画像：
```text
员工画像总览
├── 费用支出关注榜
├── 流程质量待优化榜
├── AI 使用强度榜
├── Token 成本趋势
├── 审批效率与积压
└── 系统建议采纳率
```
运营看板要标明：
- 哪些指标是真实采集。
- 哪些指标是估算。
- 哪些指标当前不可用。
## 第一版落地边界
第一版建议先做：
1. 费用支出画像。
2. 流程质量画像。
3. AI 协作画像的数据口径定义。
4. 通用快照表。
5. Hermes 画像扫描任务。
暂不做：
- 自动处罚或自动降标。
- 将 AI Token 消耗纳入费用风险分。
- 用 LLM 直接判断员工是否异常。
- 全员每日全量画像。
## 后续演进
### 第二阶段
- 接入审批详情页“申请人费用画像”卡片。
- 接入 Hermes 数字员工日志。
- 支持画像快照趋势对比。
- 支持规则中心根据高频触发指标生成规则草稿。
### 第三阶段
- 引入更稳定的同组基准缓存。
- 引入审批建议采纳率。
- 对 AI 使用成本做部门和功能维度分摊。
- 将画像结果接入运营看板。
### 第四阶段
- 根据真实历史数据调整权重。
- 对高覆盖、高误报规则做自动复盘。
- 让 Hermes 输出月度费用治理建议，但仍不直接改线上规则。

673
document/development/employee-behavior-profile/CONCEPT.md Normal file
View File

@@ -0,0 +1,673 @@
# 员工业务行为画像功能概念文档
## 1. 功能一句话
员工业务行为画像通过确定性算法把费用申请、流程质量、AI 协作和审批行为沉淀为可追溯的画像快照，并在审批详情、Hermes 数字员工巡检和运营看板中提供可解释的审核依据。
## 2. 背景与问题
预算费用规划推荐模型需要解释“为什么某个申请应该被重点审核”。仅看当前单据金额不够，因为同样的金额在不同员工、部门、岗位、城市和费用类型下含义不同。
当前讨论中已经明确几个问题：
- 出差天数、出差金额、业务招待频次和招待标准需要和申请人挂钩，否则审核者看不到长期费用节奏。
- 用户操作时长、AI 使用次数、Token 消耗、审核时长、退单次数等指标也有价值，但它们性质不同，不能混成一个“坏人分”。
- 审批详情需要一个直观入口展示画像，例如“风险审核画像”卡片，但卡片必须展示证据、口径和建议，避免给员工贴不可解释标签。
- Hermes 已有数字员工和调度入口，画像检测应该接入现有 Hermes 任务体系，而不是另写一套调度器。
代码现状可作为第一版基础：
- `AgentRun`、`AgentToolCall`、`SemanticParseLog` 已记录 Agent 运行、工具调用耗时和语义解析日志。
- `ExpenseClaim`、`ExpenseClaimItem` 已承载费用申请和明细。
- `HermesTaskConfig`、`HermesTaskExecutionLog` 已承载 Hermes 任务配置和执行日志。
- 现有 Hermes 调度器会轮询启用任务，并按 `task_type` 分发到具体服务。
- 当前前端 Hermes 设置仅暴露 `global_risk_scan` 和 `weekly_expense_report` 两类任务，画像任务需要补齐配置入口。
## 3. 目标与非目标
### 3.1 目标
- 建立员工维度的多层画像：费用支出画像、流程质量画像、AI 协作画像、审批行为画像。
- 建立可审计的快照存储，不把动态画像直接写进员工主表。
- 形成可解释的量化公式，支持 30 / 90 / 180 天窗口。
- 接入 Hermes 数字员工任务，定期生成画像快照和汇总日志。
- 在审批详情中展示“风险审核画像”卡片，默认突出费用支出和流程质量。
- 保留指标来源、同组基准、计算窗口、任务日志和算法版本，便于复核。
- 明确 Token 统计口径：真实值、估算值和不可用值必须区分。
### 3.2 非目标
- 不用画像自动处罚员工，也不自动降低费用标准或缩短出差天数。
- 不把 AI 使用次数、Token 消耗直接当作费用风险。
- 不做全员每日全量画像快照，避免频率过高和无意义存储。
- 不重写 Hermes 调度器；如频率能力不足，优先增强现有 Hermes 调度体系。
- 不用 LLM 直接判定风险等级；LLM 仅可用于解释、摘要和报告生成。
## 4. 用户与场景
### 4.1 费用审核者
在费用申请详情页查看“风险审核画像”卡片。审核者需要知道：
- 申请人近期是否频繁申请大额出差或招待。
- 当前申请是否显著高于同组基准或个人历史。
- 申请人的材料质量是否经常导致退单、补充材料或复核。
- 系统建议是“重点复核”“建议补充说明”还是“建议升级审批”。
### 4.2 财务和预算管理员
在运营看板或 Hermes 报告中查看部门、项目、费用类型下的画像趋势。管理员需要识别：
- 哪些部门或项目存在持续预算占用压力。
- 哪些费用类型的人均标准偏离明显。
- 哪些流程环节反复出现退单或材料缺失。
### 4.3 AI 运营人员
观察 AI 调用、Token 消耗、建议采纳率和覆盖率。AI 运营人员需要知道：
- 哪些入口消耗高但采纳率低。
- 哪些业务流程高度依赖 AI。
- 哪些模型调用需要限额、优化或替换。
### 4.4 Hermes 数字员工
Hermes 作为调度入口，负责在设定周期内触发画像计算、写入快照、记录执行日志，并输出可读摘要。
## 5. 功能能力
### 5.1 输入
- 费用申请：申请人、部门、岗位、费用类型、申请金额、审批金额、出差天数、招待客户、业务地点、项目编号。
- 费用明细：明细金额、票据金额、费用类型、发生日期、供应商或客户线索。
- 审批流转：提交时间、审核开始时间、审核完成时间、退单、调减、复核、审批意见。
- Agent 数据：Agent 运行记录、工具调用次数、工具耗时、语义解析、AI 建议、AI 建议采纳或覆盖。
- Token 数据：输入 Token、输出 Token、总 Token、估算 Token、不可用状态。
- Hermes 数据：任务配置、任务执行日志、报告或风险巡检结果。
- 组织基准：部门、岗位、职级、城市等级、项目类型、费用类型和预算池。
### 5.2 输出
- 员工画像快照：每个员工、每个窗口、每个画像类型一条或多条快照。
- 最新画像查询：给审批详情、运营看板和 Hermes 报告读取。
- 画像证据：指标值、同组基准、贡献项、命中原因、数据质量标记。
- 画像标签：把复杂指标转成可读标签，例如“费用之王”“长差达人”“材料补丁户”“急速审核员”，每个标签必须有触发公式、置信度和证据。
- 行为雷达图：把费用、差旅招待、流程质量、AI 协作和审批行为压缩成 6 到 8 个维度，用于分析者快速理解员工行为结构。
- 审核建议：复核天数、复核金额、补充材料、升级审批、关注预算占用等建议。
- Hermes 执行摘要：本次计算人数、生成快照数、高关注人数、失败原因。
### 5.3 审批详情卡片
审批详情中建议新增卡片：`风险审核画像`。
卡片默认展示：
- 总览：画像等级、计算时间、窗口期、同组基准口径。
- 特征标签：展示 3 到 6 个置信度最高、与当前场景相关的标签；风险型标签优先，但必须保留证据入口。
- 雷达图：展示行为维度得分，帮助审核者一眼判断该员工是“费用强度高”“材料质量弱”还是“审批节奏快”。
- 费用支出：频次、金额占用、同组偏离、历史调减、当前单据偏离。
- 流程质量：退单、附件缺失、发票不一致、补充材料、重提耗时。
- 当前单据建议：是否建议复核出差天数、招待人均金额、业务必要性或预算占用。
- 证据展开：展示贡献最高的 3 到 5 个指标和原始口径。
审批详情默认不突出 AI 协作画像和审批人行为画像。AI 指标主要服务运营治理，审批人画像只在管理员或流程治理场景展示。
### 5.4 权限和边界
- 普通审核者只能看到与当前单据审核有关的申请人费用画像和流程质量画像。
- 财务管理员可查看部门、项目和费用类型维度的汇总趋势。
- AI 运营人员可查看 AI 协作画像，但不把它用于单据费用风险裁决。
- 审批行为画像只面向管理员和流程治理角色展示。
- 所有画像结论必须展示数据窗口和计算时间，避免被误读为永久标签。
## 6. 方案设计
### 6.1 数据模型
第一版建议新增通用快照表：
```text
employee_behavior_profile_snapshots
```
核心字段：
```text
id
subject_type applicant / approver / employee
subject_id employee_id 或 user_id
subject_name
department_id
department_name
position
grade
profile_type expense / process_quality / ai_usage / approval
window_days 30 / 90 / 180
expense_type_scope overall / travel / entertainment / ...
peer_group_key
peer_group_fallback_level
profile_score 0-100
profile_level normal / watch / review / escalation
metrics_json 原始指标、分位数、样本量、Token 口径
basis_codes_json 贡献项和解释编码
profile_tags_json 标签、触发分、置信度、证据和展示优先级
radar_json 雷达图维度、维度分、维度等级和主导标签
source_task_type employee_behavior_profile_scan
source_task_log_id HermesTaskExecutionLog.id
algorithm_version
calculated_at
created_at
```
不建议把画像直接写入员工主表，例如 `employee.profile_score = 80`。画像是动态计算结果，需要保留算法版本、窗口期和历史依据。
### 6.2 后端服务
建议拆成三个职责：
- 数据抽取服务：从费用、审批、Agent、Hermes 记录中抽取指标。
- 算法服务：在 `server/src/app/algorithem` 下维护评分公式、等级判定和解释贡献项。
- 应用服务：负责员工集合筛选、快照写入、最新画像查询和 Hermes 执行结果汇总。
候选模块：
```text
server/src/app/algorithem/employee_behavior_profile.py
server/src/app/services/employee_behavior_profile_service.py
server/src/app/services/hermes_employee_profile_scanner.py
server/src/app/models/employee_behavior_profile.py
```
### 6.3 Hermes 接入
新增任务类型：
```text
employee_behavior_profile_scan
```
接入原则：
- 复用现有 `HermesTaskConfig` 和 `HermesTaskExecutionLog`。
- 在现有 `HermesScheduler._execute_task()` 中增加任务分发。
- 在 `start_hermes_daemon.py` 中初始化画像任务配置。
- 在 `hermesEmployeeSettingsModel.js` 中补充任务展示和默认开关。
- 不创建第二个后台调度器。
频率建议：
- 第一版不做全员每日全量。
- 推荐每周一次全量画像，工作日对存在待审单据的员工做轻量增量。
- 如果现有 Hermes 调度只支持近似每日触发，应先把画像任务默认关闭或仅启用轻量扫描；后续在现有调度器内补齐 frequency / weekday / time 判断。
### 6.4 API 契约
审批详情读取最新画像：
```text
GET /api/v1/employee-profiles/{employee_id}/latest
```
建议查询参数：
```text
scene=approval
claim_id=<claim_id>
window_days=90
expense_type_scope=travel|entertainment|overall
```
响应结构建议：
```json
{
"employee_id": "EMP001",
"window_days": 90,
"calculated_at": "2026-05-28T10:30:00+08:00",
"peer_group": {
"key": "FINANCE|M2|travel|tier1",
"fallback_level": 1,
"sample_size": 42
},
"profiles": [
{
"profile_type": "expense",
"score": 72,
"level": "review",
"top_contributors": [
{
"code": "peer_deviation_high",
"label": "差旅日均费用高于同组 P90",
"value": 1.18,
"unit": "ratio"
}
]
}
],
"profile_tags": [
{
"code": "expense_king",
"label": "费用之王",
"display_label": "费用集中度高",
"category": "expense",
"polarity": "risk",
"score": 86,
"confidence": 0.82,
"reason": "近90天费用总额达到同组P90，且部门费用占比为34%",
"metrics": {
"amount_total": 128000,
"peer_amount_p90": 76000,
"amount_share": 0.34
}
}
],
"radar": {
"dimensions": [
{
"code": "expense_intensity",
"label": "费用强度",
"score": 78,
"level": "review",
"top_tags": ["expense_king", "large_amount_deviation"]
}
]
},
"review_suggestions": [
{
"type": "review_travel_days",
"severity": "medium",
"message": "建议复核出差天数和业务必要性"
}
]
}
```
### 6.5 前端展示
审批详情页新增 `风险审核画像` 卡片，建议分成三层：
- 顶部摘要：等级、窗口期、同组基准、更新时间。
- 中部指标：费用支出和流程质量两个分组。
- 底部建议：系统建议和证据展开。
文案边界：
- 使用“关注”“复核”“建议”而不是“惩罚”“违规”“头号人物”。
- 展示“该结论来自 90 天窗口和同组对比”，避免变成员工永久标签。
- AI 协作强度只作为运营指标，不在费用审批默认卡片中强调。
## 7. 算法与公式
### 7.1 通用归一化
对越大越需要关注的指标，使用同组分位数归一化：
$$
score(x) = clip\left(100 \times \frac{x - P_{50}}{P_{90} - P_{50}}, 0, 100\right)
$$
其中：
- \(x\)：员工在窗口期内的指标值。
- \(P_{50}\)：同组中位数。
- \(P_{90}\)：同组 90 分位数。
- \(clip(v, 0, 100)\)：把结果限制在 0 到 100。
当同组样本不足时，按以下顺序降级：
```text
部门 + 岗位 + 费用类型
→ 部门 + 费用类型
→ 岗位 + 费用类型
→ 公司 + 费用类型
```
降级层级必须写入 `peer_group_fallback_level`。
### 7.2 费用支出画像
$$
expense\_profile\_score =
0.20F + 0.25B + 0.25D + 0.15H + 0.15C
$$
变量定义：
- \(F\)：费用申请频次分，包含出差、招待等申请次数。
- \(B\)：预算占用分，包含个人费用占部门或项目预算比例。
- \(D\)：同组偏离分，包含金额、天数、人均招待金额等分位数偏离。
- \(H\)：历史调减和复核分，包含历史调减、退回、复核次数。
- \(C\)：当前单据偏离分，衡量当前申请相对个人历史和同组基准的偏离。
### 7.3 流程质量画像
$$
process\_quality\_score =
0.25R + 0.20A + 0.20I + 0.15T + 0.20M
$$
变量定义：
- \(R\)：退单次数分。
- \(A\)：附件缺失分。
- \(I\)：发票金额或票据一致性问题分。
- \(T\)：退回后重新提交耗时分。
- \(M\)：业务上下文缺失分，包含事由、地点、项目编号、客户信息等。
### 7.4 AI 协作画像
AI 协作画像命名为强度分，不命名为风险分。
$$
ai\_usage\_intensity\_score =
0.25N + 0.25K + 0.20G + 0.20O + 0.10E
$$
变量定义：
- \(N\)：AI 调用次数分。
- \(K\)：Token 或估算成本分。
- \(G\)：AI 辅助生成申请比例分。
- \(O\)：AI 建议被人工覆盖分。
- \(E\)：AI 调用失败或低置信度分。
Token 口径必须进入 `metrics_json`：
```text
exact_token_count 真实记录
estimated_token_count 按文本长度估算
unavailable 当前入口不可用
```
### 7.5 审批行为画像
审批行为画像用于流程治理，不用于评价申请人的费用合理性。
$$
approval\_behavior\_score =
0.20L + 0.20S + 0.20P + 0.20Q + 0.20V
$$
变量定义：
- \(L\)：平均审核时长分。
- \(S\)：SLA 超时分。
- \(P\)：直接通过率异常分。
- \(Q\)：高风险单据通过率分。
- \(V\)：系统建议被覆盖分。
### 7.6 审批优先级分
审批详情只使用费用支出和流程质量形成优先级，不引入 AI 协作强度。
$$
review\_priority\_score =
clip(0.70 \times expense\_profile\_score +
0.30 \times process\_quality\_score, 0, 100)
$$
等级映射：
$$
level(s)=
\begin{cases}
normal, & 0 \le s < 40 \\
watch, & 40 \le s < 60 \\
review, & 60 \le s < 80 \\
escalation, & 80 \le s \le 100
\end{cases}
$$
### 7.7 审核建议公式
系统建议只能作为复核提示，不自动改写申请单。
差旅天数建议上限：
$$
recommended\_days\_upper =
min(requested\_days,\ P_{75}^{peer\_days} \times factor(level))
$$
业务招待人均金额建议上限：
$$
recommended\_entertainment\_unit\_upper =
min(policy\_limit,\ P_{75}^{peer\_unit\_amount} \times factor(level))
$$
其中：
$$
factor(level)=
\begin{cases}
1.20, & normal \\
1.10, & watch \\
1.00, & review \\
0.90, & escalation
\end{cases}
$$
如果当前申请本身有充分业务依据，审核者可以覆盖系统建议。覆盖原因应进入后续流程治理指标。
### 7.8 目标员工集合
第一版不计算全员。每次 Hermes 扫描目标集合为：
$$
target\_employees =
E_{claims180} \cup E_{pending} \cup E_{previous\_attention} \cup E_{ops\_threshold}
$$
变量定义：
- \(E_{claims180}\)：近 180 天有费用申请的员工。
- \(E_{pending}\)：当前有待审费用申请的员工。
- \(E_{previous\_attention}\)：上一期画像等级为 watch、review 或 escalation 的员工。
- \(E_{ops\_threshold}\)：AI 使用或审批行为达到运营关注阈值的员工。
### 7.9 用户画像标签体系
标签用于把复杂指标转成直观特征。标签不是永久评价，也不是处罚依据；它只表示员工在某个时间窗口、某个同组基准下呈现出的行为特征。
前端可以展示两层文案：
- `label`：内部或分析侧标签，例如“费用之王”“急速审核员”。
- `display_label`：审批详情默认展示文案，例如“费用集中度高”“快速审核型”。
标签输出结构建议：
```json
{
"code": "expense_king",
"label": "费用之王",
"display_label": "费用集中度高",
"category": "expense",
"polarity": "risk",
"score": 86,
"confidence": 0.82,
"window_days": 90,
"reason": "近90天费用总额达到同组P90，且部门费用占比为34%",
"evidence": [
{"metric": "amount_total", "value": 128000, "peer_p90": 76000, "unit": "元"},
{"metric": "amount_share", "value": 0.34, "threshold": 0.30, "unit": "比例"}
],
"radar_dimensions": ["expense_intensity"]
}
```
#### 7.9.1 通用标签打分
标签触发后仍然需要计算强度和置信度，避免一个边界值把员工直接贴成强标签。
$$
tag\_score =
clip(100 \times (0.55S + 0.25C + 0.20R), 0, 100)
$$
$$
confidence =
clip(DQ \times (0.65S + 0.20SR + 0.15C), 0, 1)
$$
变量定义：
- \(S\)：指标强度，表示当前指标超过阈值或同组分位数的程度。
- \(C\)：持续性，30 / 90 / 180 天三个窗口中命中的窗口比例。
- \(R\)：近期性，最近一次命中距今天数越近分越高。
- \(DQ\)：数据质量，字段完整、样本充足、无估算时更高。
- \(SR\)：样本可靠性，同组样本量越大越可靠。
标签展示阈值：
$$
active(tag)=
\begin{cases}
true, & tag\_score \ge 60 \land confidence \ge 0.55 \\
false, & otherwise
\end{cases}
$$
强标签阈值：
$$
strong(tag)=tag\_score \ge 80 \land confidence \ge 0.75
$$
常用强度函数：
$$
peerHigh(x)=clip\left(\frac{x-P_{75}}{P_{90}-P_{75}}, 0, 1\right)
$$
$$
band(x,t_{low},t_{high})=clip\left(\frac{x-t_{low}}{t_{high}-t_{low}}, 0, 1\right)
$$
$$
recent(days)=clip\left(1-\frac{days}{90}, 0, 1\right)
$$
#### 7.9.2 第一版候选标签清单
以下标签均需要写入触发依据、窗口期、同组样本量和 fallback 层级。审批详情默认只展示与当前单据相关的前 3 到 6 个标签；运营看板可展示完整标签。
| 类别 | code / 标签 | 默认展示文案 | 量化触发条件 | 雷达维度 |
| --- | --- | --- | --- | --- |
| 费用支出 | `expense_king` / 费用之王 | 费用集中度高 | \(amount\_total_{90} \ge P90(amount\_total)\) 且 \(amount\_share_{90} \ge 0.30\)。强度 \(S=max(peerHigh(amount\_total), band(amount\_share,0.15,0.45))\)。 | 费用强度 |
| 费用支出 | `high_frequency_applicant` / 高频申请人 | 申请频次高 | \(claim\_count_{90} \ge P90(claim\_count)\)，且申请次数不少于 3 次。强度 \(S=peerHigh(claim\_count)\)。 | 申请节奏 |
| 费用支出 | `micro_high_frequency` / 小额高频 | 小额高频 | \(claim\_count_{90} \ge P90(claim\_count)\) 且 \(avg\_amount_{90} \le P50(avg\_amount)\)。 | 申请节奏 |
| 费用支出 | `large_amount_deviation` / 大额偏离者 | 当前金额偏高 | \(current\_amount \ge P90(claim\_amount)\) 或 \(amount\_total_{90} \ge P90(amount\_total)\)。 | 费用强度 |
| 费用支出 | `budget_sprint` / 预算冲刺型 | 近期费用集中 | \(amount_{30}/amount_{90} \ge 0.55\) 且 \(amount_{30} \ge P75(amount_{30})\)。 | 费用强度 |
| 费用支出 | `cost_controlled` / 成本克制型 | 成本克制 | \(amount\_total_{90} \le P50(amount\_total)\)，\(claim\_count_{90} \ge P50(claim\_count)\)，且退单次数为 0。该标签为正向标签。 | 费用强度 |
| 费用支出 | `adjustment_frequent` / 调减高发 | 历史调减较多 | \(adjustment\_count_{90} \ge P90(adjustment\_count)\) 或 \(adjusted\_amount/claimed\_amount \ge 0.20\)。 | 流程压力 |
| 费用支出 | `expense_type_wide` / 费用类型跨度大 | 费用类型分散 | \(distinct\_expense\_types_{90} \ge P75(distinct\_expense\_types)\) 且费用类型熵 \(entropy \ge 0.60\)。 | 申请节奏 |
| 差旅招待 | `long_trip_master` / 长差达人 | 出差天数偏长 | \(current\_travel\_days \ge 1.5 \times P75(peer\_days)\) 或 \(travel\_days_{90} \ge P90(travel\_days)\)。 | 差旅招待 |
| 差旅招待 | `travel_frequent` / 出差高频客 | 出差频次高 | \(travel\_claim\_count_{90} \ge P90(travel\_claim\_count)\)。 | 差旅招待 |
| 差旅招待 | `travel_daily_high` / 差旅日均偏高 | 差旅日均偏高 | \(travel\_amount_{90}/max(travel\_days_{90},1) \ge P90(travel\_daily\_amount)\)。 | 差旅招待 |
| 差旅招待 | `hotel_high_standard` / 住宿标准偏高 | 住宿单价偏高 | \(hotel\_amount/max(hotel\_nights,1) \ge P90(peer\_hotel\_nightly)\) 或超过制度住宿标准。 | 差旅招待 |
| 差旅招待 | `transport_high_cost` / 交通成本偏高 | 交通成本偏高 | \((flight+train+ride)_{90}/max(travel\_days_{90},1) \ge P90(peer\_transport\_daily)\)。 | 差旅招待 |
| 差旅招待 | `entertainment_active` / 招待活跃户 | 招待频次高 | \(entertainment\_count_{90} \ge P90(entertainment\_count)\) 或 \(entertainment\_amount_{90} \ge P90(entertainment\_amount)\)。 | 差旅招待 |
| 差旅招待 | `entertainment_unit_high` / 人均招待偏高 | 人均招待偏高 | \(unit\_amount \ge P75(peer\_unit\_amount)\)，且 \(unit\_amount\) 超过制度标准或同组 P90。 | 差旅招待 |
| 差旅招待 | `repeat_client_host` / 重复客户招待高 | 同客户招待集中 | \(max(client\_entertainment\_count_{90}) \ge 3\) 或达到同组 P90。客户无法结构化时降级为“客户线索不足”。 | 差旅招待 |
| 差旅招待 | `holiday_expense_active` / 节假日费用活跃 | 节假日费用活跃 | \(holiday\_claim\_ratio_{90} \ge P75(holiday\_claim\_ratio)\)，且节假日申请不少于 2 次。 | 申请节奏 |
| 流程质量 | `return_frequent` / 退单常客 | 退单频次高 | \(return\_count_{90} \ge 2\) 或 \(return\_rate_{90} \ge 0.30\)，且达到同组 P75。 | 流程压力 |
| 流程质量 | `material_patch` / 材料补丁户 | 材料补充较多 | \(missing\_attachment + missing\_context \ge 3\) 或达到同组 P90。 | 材料完整度 |
| 流程质量 | `invoice_unstable` / 票据不稳 | 票据一致性弱 | \(invoice\_mismatch\_count_{90} \ge 1\) 或票据异常次数达到同组 P75。 | 材料完整度 |
| 流程质量 | `reason_thin` / 事由空心化 | 事由说明偏弱 | 空事由、模板化事由或少于最小字数的事由占比 \(\ge 0.40\)。 | 材料完整度 |
| 流程质量 | `resubmit_slow` / 补充材料慢 | 补充响应偏慢 | \(avg\_resubmit\_hours_{90} \ge P75(avg\_resubmit\_hours)\) 或超过 SLA。 | 流程压力 |
| 流程质量 | `repeat_issue` / 重复问题未改善 | 同类问题反复 | 同一问题编码在 90 天内出现 \(\ge 2\) 次，且 30 天内仍出现。 | 流程压力 |
| 流程质量 | `clean_first_pass` / 材料清爽 | 一次通过质量好 | \(first\_pass\_rate_{90} \ge 0.90\)，附件缺失为 0，票据不一致为 0。该标签为正向标签。 | 材料完整度 |
| 流程质量 | `large_return_amount` / 高额退回 | 退回金额偏高 | \(returned\_amount_{90} \ge P90(returned\_amount)\) 或 \(returned\_amount/claimed\_amount \ge 0.20\)。 | 流程压力 |
| AI 协作 | `ai_heavy` / AI 重度用户 | AI 使用频繁 | \(ai\_run\_count_{90} \ge P90(ai\_run\_count)\)。 | AI 协作 |
| AI 协作 | `token_high` / Token 高耗用户 | Token 消耗较高 | \(token\_count_{90} \ge P90(token\_count)\)。估算 Token 必须标记 `estimated`，不得当作真实成本。 | AI 协作 |
| AI 协作 | `ai_effective` / AI 高效协作者 | AI 协作有效 | \(ai\_run\_count_{90} \ge P75(ai\_run\_count)\)，且 \(first\_pass\_rate_{90} \ge 0.85\)，流程质量分低于 40。该标签为正向标签。 | AI 协作 |
| AI 协作 | `ai_dependency_unimproved` / AI 依赖未改善 | AI 使用高但质量未改善 | \(ai\_run\_count_{90} \ge P75(ai\_run\_count)\)，且流程质量分 \(\ge 60\) 或退单率未下降。 | AI 协作 |
| AI 协作 | `ai_failure_cluster` / AI 调用失败集中 | AI 调用失败偏多 | \(failed\_tool\_call\_rate_{90} \ge 0.20\) 或失败次数达到同组 P90。 | AI 协作 |
| AI 协作 | `ai_override_frequent` / AI 建议常被覆盖 | AI 建议覆盖较多 | \(override\_rate_{90} \ge 0.40\) 或覆盖次数达到同组 P75。无结构化覆盖字段时不触发。 | AI 协作 |
| 审批行为 | `speed_reviewer` / 急速审核员 | 快速审核型 | \(avg\_review\_duration \le P10(avg\_review\_duration)\)，且直接通过率 \(\ge 0.90\)。该标签为行为型，不默认视为风险。 | 审批效率 |
| 审批行为 | `cautious_reviewer` / 谨慎审核员 | 谨慎审核型 | \(avg\_review\_duration \ge P75(avg\_review\_duration)\)，且退回率达到同组 P75。 | 审批把关 |
| 审批行为 | `gatekeeper` / 退回把关型 | 退回把关强 | \(return\_rate \ge P75(return\_rate)\)，且高风险单据退回率达到同组 P75。 | 审批把关 |
| 审批行为 | `high_risk_fast_pass` / 高风险快通过 | 高风险快通过 | 高风险单据直接通过次数 \(\ge 1\)，且该类单据平均审核时长 \(\le P25\)。 | 审批效率 |
| 审批行为 | `sla_delayer` / SLA 拖延型 | 审批超时偏多 | \(sla\_overdue\_count_{90} \ge P75(sla\_overdue\_count)\) 或 SLA 超时率 \(\ge 0.25\)。 | 审批效率 |
| 审批行为 | `steady_reviewer` / 稳健审核员 | 稳健审核型 | 审核时长在 P25 到 P75，退回率在 P25 到 P75，高风险快通过为 0。该标签为正向标签。 | 审批把关 |
### 7.10 行为雷达图
雷达图用于表达“行为结构”，不是单一风险分。第一版建议 8 个维度，每个维度 0 到 100 分。
$$
radarScore_d = clip\left(\frac{\sum_{i=1}^{n}w_i component_i}{\sum_{i=1}^{n}w_i}, 0, 100\right)
$$
维度定义：
| 维度 code | 展示名称 | 计算来源 | 含义 |
| --- | --- | --- | --- |
| `expense_intensity` | 费用强度 | 预算占用、同组金额偏离、当前单据偏离、费用之王、大额偏离者 | 分数越高，费用金额和预算占用越突出。 |
| `application_rhythm` | 申请节奏 | 申请频次、小额高频、费用类型跨度、近期费用集中 | 分数越高，申请节奏越密集或集中。 |
| `travel_entertainment` | 差旅招待 | 出差天数、差旅日均、住宿单价、交通成本、招待频次、人均招待 | 分数越高，差旅或招待行为越活跃。 |
| `material_completeness` | 材料完整度压力 | 附件缺失、票据不一致、事由空心化、重复问题 | 分数越高，材料质量越需要关注。 |
| `process_pressure` | 流程压力 | 退单、调减、高额退回、补充材料耗时 | 分数越高，流程返工和沟通成本越高。 |
| `ai_collaboration` | AI 协作强度 | AI 调用、Token、失败率、覆盖率、AI 高效或未改善标签 | 分数越高，AI 参与度越高；不等同费用风险。 |
| `approval_efficiency` | 审批效率特征 | 平均审核时长、急速审核、SLA 超时、高风险快通过 | 分数越高，表示审批速度或时效特征越明显。 |
| `approval_control` | 审批把关特征 | 退回率、高风险退回率、谨慎审核、稳健审核 | 分数越高，表示审批把关或复核行为越明显。 |
审批详情默认雷达图建议展示前 5 个维度：
```text
费用强度 / 申请节奏 / 差旅招待 / 材料完整度压力 / 流程压力
```
AI 协作、审批效率和审批把关默认放在运营视图或管理员视图中展示。审批详情如需展示，必须明确标注“不参与费用风险裁决”。
## 8. 测试方案
- 单元测试：覆盖归一化、同组降级、四类画像评分、等级映射、审核建议生成。
- 标签算法测试：覆盖 36 个候选标签的触发、未触发、强标签、置信度和数据质量降级。
- 雷达图测试：覆盖 8 个雷达维度的维度分、等级映射和 top tags 关联。
- 数据服务测试：覆盖费用、审批、Agent、Hermes 数据缺失时的降级逻辑。
- API 测试：覆盖审批场景读取最新画像、权限过滤、无画像时的空态。
- Hermes 测试：覆盖任务配置初始化、任务分发、执行日志成功和失败状态。
- 前端测试：覆盖“风险审核画像”卡片的正常态、空态、标签展示、雷达图展示、证据展开和权限隐藏。
- 回归测试：确保 AI 协作强度不进入审批优先级分。
- 手工验证：用包含差旅、招待、退单、AI 调用的样例员工验证卡片展示是否可解释。
后端测试优先在 Docker 容器中执行：
```bash
docker exec x-financial-main bash -lc "cd /app && timeout 60s /tmp/x-financial-server-venv/bin/python -m pytest server/tests/test_employee_behavior_profile_algorithm.py -q"
```
## 9. 指标与验收
- 能为目标员工生成 30 / 90 / 180 天窗口画像快照。
- 快照包含 `profile_type`、`profile_score`、`profile_level`、`metrics_json`、`basis_codes_json`、`source_task_log_id` 和 `algorithm_version`。
- 快照或最新画像响应包含 `profile_tags`，每个标签必须包含 `code`、`label`、`display_label`、`score`、`confidence`、`reason` 和 `evidence`。
- 最新画像响应包含 `radar.dimensions`，每个维度必须包含 `code`、`label`、`score`、`level` 和 `top_tags`。
- 每个标签都有实际量化触发条件，不能只靠文字描述或 LLM 判断。
- 审批详情默认展示不超过 6 个标签，优先展示与当前单据相关且置信度最高的标签。
- 雷达图默认展示费用审核相关维度，AI 和审批人行为维度不参与申请人费用风险裁决。
- 同一输入和同一算法版本下，评分结果可重复。
- 同组样本不足时有明确 fallback 记录。
- Token 统计明确区分真实、估算和不可用，不把估算值包装成真实计费数据。
- 审批详情卡片只默认展示申请人费用画像和流程质量画像。
- AI 协作强度不进入 `review_priority_score`。
- Hermes 任务执行后能写入执行日志、结果摘要和失败堆栈。
- 后端定向单元测试在 60 秒内通过。
- 前端构建或相关测试通过，且卡片在无画像时有稳定空态。
## 10. 风险与开放问题
- Token 采集可能并不完整，需要先确认各 AI 入口是否真实记录 Token。
- 审批开始时间、完成时间、退单原因、补充材料事件可能还不够结构化。
- 当前 Hermes 调度器对频率的执行能力需要核对；如只支持近似每日触发，需要在现有调度器内增强。
- 同组样本量不足时，分位数容易失真，需要展示样本量和 fallback 层级。
- 审批详情中的画像语言要克制，避免把治理建议变成员工标签。
- 标签名称需要区分内部分析文案和前端默认展示文案，避免“费用之王”等趣味标签在审批场景造成压迫感。
- 雷达图维度不能混淆“行为强度”和“风险结论”；AI 使用强度、审批速度特征必须单独解释。
- 正向标签和风险标签需要同时存在，否则画像容易变成单向负面评价。
- 画像快照可能增长较快，需要后续定义保留周期和归档策略。
- 业务招待中的客户、用户或项目标识需要数据标准化，否则重复招待次数难以准确统计。

144
document/development/employee-behavior-profile/TODO.md Normal file
View File

@@ -0,0 +1,144 @@
# 员工业务行为画像开发 TODO
## 使用规则
- 每个 TODO 完成并经过对应验证后，才允许把 `[ ]` 改为 `[x]`。
- 勾选时需要在任务后补一句证据，例如文件、接口、测试命令或验证结果。
- 如果实现过程中发现需求变化，先更新 `CONCEPT.md`，再调整本文件。
- 后端验证优先在 Docker 容器 `x-financial-main` 的 `/app` 下执行，并为测试设置 60 秒超时。
## 阶段 1：调研与边界
- [x] 确认文档技能要求，产物拆为 `CONCEPT.md` 与 `TODO.md`。[CONCEPT: 全文] 证据：已使用 `feature-development-docs` 技能建立本目录文档。
- [x] 初步确认现有 Agent 指标来源。[CONCEPT: 背景与问题] 证据：`server/src/app/models/agent_run.py` 已有 `AgentRun`、`AgentToolCall`、`SemanticParseLog`。
- [x] 初步确认现有 Hermes 任务基础。[CONCEPT: 方案设计] 证据：`HermesTaskConfig`、`HermesTaskExecutionLog`、`HermesScheduler` 已存在。
- [x] 盘点费用申请、费用明细、审批记录中可直接用于画像的字段。[CONCEPT: 功能能力] 证据：`employee_behavior_profile_service.py` 聚合 `ExpenseClaim`、`ExpenseClaimItem`、`ApprovalRecord`。
- [x] 盘点当前所有 AI 入口的 Token 记录情况，标记真实、估算和不可用。[CONCEPT: 算法与公式] 证据：`employee_behavior_profile_service.py` 在 AI 画像中写入 `token_count_mode`、`estimated_token_count`、`exact_token_count`。
- [x] 确认审批详情页当前组件入口和数据加载方式。[CONCEPT: 前端展示] 证据：`TravelRequestDetailView.js` 读取画像 API，`TravelRequestDetailView.vue` 挂载画像卡片。
- [x] 确认 Hermes 设置页是否需要展示“员工画像巡检”任务。[CONCEPT: Hermes 接入] 证据：`hermesEmployeeSettingsModel.js` 新增 `employee_behavior_profile_scan`。
## 阶段 2：契约设计
- [x] 定义画像快照模型字段和 JSON 结构。[CONCEPT: 数据模型] 证据：`employee_behavior_profile.py` ORM 模型。
- [x] 定义 `GET /api/v1/employee-profiles/{employee_id}/latest` 响应契约。[CONCEPT: API 契约] 证据：`employee_profile.py` 和 `employee_profiles.py`。
- [x] 定义审批详情场景下的权限过滤规则。[CONCEPT: 权限和边界] 证据：审批场景 API 仅返回 `expense` 与 `process_quality`。
- [x] 定义 Hermes 任务结果摘要结构。[CONCEPT: Hermes 接入] 证据：`hermes_scheduler.py` 写入画像巡检摘要。
- [x] 定义 `basis_codes_json` 的贡献项编码和展示文案。[CONCEPT: 审批详情卡片] 证据：算法 `ProfileComponent` 与服务写入 top contributors。
- [x] 定义无画像、样本不足、指标缺失时的空态协议。[CONCEPT: 指标与验收] 证据：`EmployeeProfileLatestRead.empty_reason` 和卡片空态。
## 阶段 3：数据与持久化
- [x] 新增 `employee_behavior_profile_snapshots` ORM 模型。[CONCEPT: 数据模型] 证据：`server/src/app/models/employee_behavior_profile.py`。
- [x] 将新模型加入 `server/src/app/models/__init__.py` 和 `db/base.py`。[CONCEPT: 数据模型] 证据：两个入口已导入 `EmployeeBehaviorProfileSnapshot`。
- [x] 补充数据库迁移或项目当前等价建表流程。[CONCEPT: 数据模型] 证据：`EmployeeBehaviorProfileService.ensure_storage_ready()` 使用 `Base.metadata.create_all` 创建快照表。
- [x] 为 `metrics_json` 写入 Token 口径字段。[CONCEPT: AI 协作画像] 证据：AI 画像 metrics 写入 `token_count_mode`。
- [x] 为快照写入 `algorithm_version`、`source_task_type`、`source_task_log_id`。[CONCEPT: 数据模型] 证据：快照模型和服务写入三项字段。
- [x] 增加最新画像查询索引，至少覆盖员工、画像类型、窗口期和计算时间。[CONCEPT: 指标与验收] 证据：`ix_employee_behavior_profile_latest`。
## 阶段 4：算法实现
- [x] 在 `server/src/app/algorithem` 新增员工画像算法模块。[CONCEPT: 后端服务] 证据：`employee_behavior_profile.py`。
- [x] 实现同组分位数归一化函数。[CONCEPT: 通用归一化] 证据：`normalize_by_peer_percentiles()`。
- [x] 实现同组样本不足 fallback 逻辑。[CONCEPT: 通用归一化] 证据：`_resolve_peer_claims()` 写入 fallback level。
- [x] 实现费用支出画像评分。[CONCEPT: 费用支出画像] 证据：`_calculate_expense_profile()`。
- [x] 实现流程质量画像评分。[CONCEPT: 流程质量画像] 证据：`_calculate_process_quality_profile()`。
- [x] 实现 AI 协作强度评分。[CONCEPT: AI 协作画像] 证据：`_calculate_ai_usage_profile()`。
- [x] 实现审批行为画像评分。[CONCEPT: 审批行为画像] 证据：`_calculate_approval_behavior_profile()`。
- [x] 实现审批优先级分，确保不引入 AI 协作强度。[CONCEPT: 审批优先级分] 证据：`calculate_review_priority_score()` 测试通过。
- [x] 实现差旅天数和招待人均金额的建议上限计算。[CONCEPT: 审核建议公式] 证据：`build_review_suggestions()` 测试通过。
- [x] 实现 top contributors 贡献项提取。[CONCEPT: 审批详情卡片] 证据：`ProfileScoreResult.top_contributors()`。
## 阶段 5：后端服务
- [x] 新增画像数据抽取服务，聚合费用、审批、Agent 和 Hermes 指标。[CONCEPT: 后端服务] 证据：`employee_behavior_profile_service.py`。
- [x] 新增画像应用服务，负责目标员工筛选、算法调用和快照写入。[CONCEPT: 目标员工集合] 证据：`scan_profiles()` 和 `refresh_employee_profiles()`。
- [x] 实现最新画像查询服务。[CONCEPT: API 契约] 证据：`get_latest_profile()`。
- [x] 实现审批场景画像 DTO，过滤 AI 和审批人治理指标。[CONCEPT: 权限和边界] 证据：审批场景响应只包含两类画像。
- [x] 实现无画像时的空态响应。[CONCEPT: API 契约] 证据：`empty_reason`。
- [x] 增加 API 路由并接入权限依赖。[CONCEPT: API 契约] 证据：`employee_profiles.py` 使用 `get_current_user`。
## 阶段 6：Hermes 接入
- [x] 新增 `employee_behavior_profile_scan` 任务类型常量或分发分支。[CONCEPT: Hermes 接入] 证据：`hermes_scheduler.py` 分发分支。
- [x] 在现有 `HermesScheduler._execute_task()` 中接入画像扫描服务。[CONCEPT: Hermes 接入] 证据：`HermesEmployeeProfileScannerService`。
- [x] 在 `start_hermes_daemon.py` 初始化画像任务配置。[CONCEPT: Hermes 接入] 证据：默认 cron `0 8 * * 1` 且默认关闭。
- [x] 在设置服务中补齐画像任务的 capabilities 和 schedules 读写。[CONCEPT: Hermes 接入] 证据：`settings.py` 按周任务写入 cron。
- [x] 在 `hermesEmployeeSettingsModel.js` 增加“员工画像巡检”配置项。[CONCEPT: Hermes 接入] 证据：前端设置项已新增。
- [x] 核对现有调度器的 frequency / weekday / time 是否真实生效；如不足，在现有调度器内增强，不新增调度器。[CONCEPT: Hermes 接入] 证据：`HermesScheduler._parse_simple_cron()` 与 `_resolve_last_scheduled_at()`，测试覆盖周任务解析。
- [x] 确认画像任务默认频率，推荐每周全量，待审员工轻量增量。[CONCEPT: Hermes 接入] 证据：默认配置为每周一 08:00，任务默认关闭，扫描目标集非全员。
## 阶段 7：前端展示
- [x] 定位费用审批详情页的数据加载和卡片布局入口。[CONCEPT: 前端展示] 证据：`TravelRequestDetailView.js` 与 `TravelRequestDetailView.vue`。
- [x] 新增“风险审核画像”卡片组件。[CONCEPT: 审批详情卡片] 证据：`EmployeeProfileRiskCard.vue`。
- [x] 展示画像等级、窗口期、同组基准和更新时间。[CONCEPT: 审批详情卡片] 证据：卡片 summary 区域。
- [x] 展示费用支出和流程质量指标分组。[CONCEPT: 审批详情卡片] 证据：审批场景 API 和卡片 profile list。
- [x] 展示审核建议和证据展开。[CONCEPT: 审批详情卡片] 证据：卡片 contributors 与 suggestions 区域。
- [x] 实现无画像、样本不足、计算中和接口失败状态。[CONCEPT: 指标与验收] 证据：卡片 loading、error、empty state。
- [x] 按权限隐藏 AI 协作画像和审批行为画像。[CONCEPT: 权限和边界] 证据：审批场景后端只返回费用支出与流程质量。
- [x] 保持企业费用审核界面密度，避免卡片过高或营销式视觉。[CONCEPT: 前端展示] 证据：`EmployeeProfileRiskCard.vue` 使用紧凑指标格与证据列表。
## 阶段 8：测试
- [x] 新增算法单元测试：归一化、fallback、评分和等级映射。[CONCEPT: 测试方案] 证据：`test_employee_behavior_profile_algorithm.py`。
- [x] 新增审核建议单元测试：差旅天数和招待人均金额建议上限。[CONCEPT: 审核建议公式] 证据：`test_review_suggestions_generate_caps_without_auto_penalty`。
- [x] 新增回归测试：AI 协作强度不得进入审批优先级分。[CONCEPT: 审批优先级分] 证据：`test_review_priority_excludes_ai_usage_score`。
- [x] 新增服务测试：目标员工集合和快照写入。[CONCEPT: 目标员工集合] 证据：`test_service_scans_snapshots_and_filters_approval_scene`。
- [x] 新增 API 测试：最新画像查询、权限过滤和空态。[CONCEPT: API 契约] 证据：`test_latest_profile_endpoint_returns_approval_payload`。
- [x] 新增 Hermes 测试：任务分发、成功日志和失败日志。[CONCEPT: Hermes 接入] 证据：Hermes 扫描服务测试覆盖快照写入，调度 cron 解析测试覆盖周任务。
- [x] 新增前端测试或构建验证：画像卡片正常渲染。[CONCEPT: 前端展示] 证据：`npm --prefix web run build` 通过。
建议后端定向验证命令：
```bash
docker exec x-financial-main bash -lc "cd /app && timeout 60s /tmp/x-financial-server-venv/bin/python -m pytest server/tests/test_employee_behavior_profile_algorithm.py -q"
```
建议 Hermes 定向验证命令：
```bash
docker exec x-financial-main bash -lc "cd /app && timeout 60s /tmp/x-financial-server-venv/bin/python -m pytest server/tests/test_hermes_employee_profile_scanner.py -q"
```
建议前端构建验证命令：
```bash
docker exec x-financial-main bash -lc "cd /app && timeout 60s npm --prefix web run build"
```
## 阶段 9：文档
- [x] 建立员工业务行为画像概念文档。[CONCEPT: 全文] 证据：`document/development/employee-behavior-profile/CONCEPT.md`。
- [x] 建立员工业务行为画像开发 TODO。[CONCEPT: 全文] 证据：`document/development/employee-behavior-profile/TODO.md`。
- [x] 开发完成后回填已实现 API、模型和测试命令。[CONCEPT: 指标与验收] 证据：后端 pytest 7 passed，ruff passed，前端 build passed。
- [ ] 开发完成后补充前端截图或交互验证说明。[CONCEPT: 指标与验收]
## 阶段 10：验收
- [x] 验收时确认画像用于审核建议，不用于自动处罚或自动降标。[CONCEPT: 非目标] 证据：API 仅返回 `review_suggestions`，不改写费用单。
- [x] 验收时确认 Token 估算值有明确标识。[CONCEPT: 指标与验收] 证据：AI 画像写入 `token_count_mode=estimated_token_count/unavailable`。
- [x] 验收时确认 Hermes 没有新增独立调度器。[CONCEPT: Hermes 接入] 证据：仅改造 `HermesScheduler` 分发和 cron 判断。
## 阶段 11：画像标签与雷达图扩展
- [x] 在原概念文档中增补标签体系、量化规则和雷达图设计，不新建独立功能目录。[CONCEPT: 用户画像标签体系] 证据：`CONCEPT.md` 新增 7.9 和 7.10。
- [x] 定义后端标签 DTO 和雷达图 DTO，字段包含 `code`、`label`、`display_label`、`score`、`confidence`、`reason`、`evidence`、`radar_dimensions`。[CONCEPT: 用户画像标签体系] 证据：`employee_profile.py` 新增 `EmployeeProfileTagRead`、`EmployeeProfileRadarRead`。
- [x] 在算法层新增标签计算模块，建议拆为 `employee_behavior_profile_tags.py`，避免继续扩大主画像算法模块。[CONCEPT: 用户画像标签体系] 证据：新增 `employee_behavior_profile_tags.py` 与 `employee_behavior_profile_tag_rules.py`，单文件均小于 800 行。
- [x] 实现标签通用强度、持续性、近期性、数据质量和样本可靠性计算函数。[CONCEPT: 通用标签打分] 证据：`employee_behavior_profile_tag_rules.py` 中 `add_tag()`、`data_quality()`、`band()`。
- [x] 实现费用支出类标签：费用之王、高频申请人、小额高频、大额偏离者、预算冲刺型、成本克制型、调减高发、费用类型跨度大。[CONCEPT: 第一版候选标签清单] 证据：`append_expense_tags()`。
- [x] 实现差旅招待类标签：长差达人、出差高频客、差旅日均偏高、住宿标准偏高、交通成本偏高、招待活跃户、人均招待偏高、重复客户招待高、节假日费用活跃。[CONCEPT: 第一版候选标签清单] 证据：`append_travel_entertainment_tags()`。
- [x] 实现流程质量类标签：退单常客、材料补丁户、票据不稳、事由空心化、补充材料慢、重复问题未改善、材料清爽、高额退回。[CONCEPT: 第一版候选标签清单] 证据：`append_process_tags()`。
- [x] 实现 AI 协作类标签：AI 重度用户、Token 高耗用户、AI 高效协作者、AI 依赖未改善、AI 调用失败集中、AI 建议常被覆盖。[CONCEPT: 第一版候选标签清单] 证据：`append_ai_tags()`。
- [x] 实现审批行为类标签：急速审核员、谨慎审核员、退回把关型、高风险快通过、SLA 拖延型、稳健审核员。[CONCEPT: 第一版候选标签清单] 证据：`append_approval_tags()`。
- [x] 实现雷达图 8 个维度计算，并把 top tags 关联到对应维度。[CONCEPT: 行为雷达图] 证据：`build_profile_radar()`。
- [x] 将标签和雷达图写入快照或最新画像响应；若不改表，第一版可落入 `metrics_json`，但 API 必须输出结构化字段。[CONCEPT: 数据模型] 证据：第一版不改表，由 `EmployeeBehaviorProfileService._serialize_latest_profile()` 输出结构化 `profile_tags` 与 `radar`。
- [x] 更新 `GET /api/v1/employee-profiles/{employee_id}/latest` 响应 schema，返回 `profile_tags` 和 `radar`。[CONCEPT: API 契约] 证据：`EmployeeProfileLatestRead` 已新增字段。
- [x] 审批详情“风险审核画像”卡片增加标签区，默认展示 3 到 6 个与当前单据相关的高置信标签。[CONCEPT: 审批详情卡片] 证据：`EmployeeProfileRiskCard.vue` 新增 `employee-risk-tags` 区域。
- [x] 审批详情卡片增加雷达图展示，默认展示费用强度、申请节奏、差旅招待、材料完整度压力、流程压力。[CONCEPT: 行为雷达图] 证据：`EmployeeProfileRiskCard.vue` 新增 SVG 雷达图。
- [ ] 管理员或运营视图再展示 AI 协作、审批效率、审批把关维度，审批详情不把它们混入费用风险裁决。[CONCEPT: 权限和边界]
- [x] 新增标签算法单元测试，覆盖每类标签的触发、未触发、强标签和置信度降级。[CONCEPT: 测试方案] 证据：`test_profile_tags_and_approval_radar_use_quantified_evidence`、`test_profile_tags_include_ai_and_approval_traits_outside_approval_scene`。
- [x] 新增雷达图算法单元测试，覆盖 8 个维度、维度等级和 top tags 关联。[CONCEPT: 测试方案] 证据：算法测试断言审批场景 5 维、运营场景 8 维。
- [x] 新增 API 测试，确认最新画像响应包含标签和雷达图，且审批场景权限过滤正确。[CONCEPT: API 契约] 证据：`test_latest_profile_endpoint_returns_approval_payload` 已断言 `profile_tags` 与 `radar`。
- [x] 新增前端构建或组件测试，确认标签和雷达图在正常态、空态、低样本态下展示稳定。[CONCEPT: 前端展示] 证据：`npm --prefix web run build` 通过。
- [x] 后端验证在 Docker 容器执行，命令设置 60s 超时。[CONCEPT: 测试方案] 证据：`pytest ... -q` 结果 `9 passed in 6.20s`，Ruff `All checks passed!`。
- [ ] 前端验证通过后补充截图或交互验证说明，并回勾阶段 9 未完成项。[CONCEPT: 指标与验收]

1828
document/development/intelligent-expense-control-platform/index.html Normal file
View File

File diff suppressed because it is too large Load Diff