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