X-Financial/document/development/employee-behavior-profile/TODO.md

# 员工业务行为画像开发 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: 指标与验收]