TurboHR/20260723-优化-6.md

# 劳动用工合规 SaaS — 功能层面优化清单（续三）

> **文档编号**: 20260723-优化-6.md
> **日期**: 2026-07-23
> **来源**: 对 Portal 相关页面、AI 服务、RAG 服务深入研究后得出

---

## 一、高优先级（核心业务缺陷）

### 1. Portal — 工资条确认后无反馈机制

**现状**: 员工点击「确认已阅」后只更新 `confirmedAt`，没有通知 HR 已确认。如果 HR 期望所有员工都确认后才能完成工资条审核流程，当前系统无法感知确认状态。

**建议**:
- 工资条确认后通过 WebSocket 或轮询通知 HR
- 在 Money 页面展示各员工的工资条确认状态（已确认 / 未确认）
- 未确认员工超过 N 人时，HR 收到系统通知
- 员工确认后记录 IP 地址（已有），用于审计

**涉及文件**: `frontend/src/pages/Money.tsx`、`backend/src/routes/portal.routes.ts`、`frontend/src/pages/portal/Payslip.tsx`

---

### 2. AI — 会话上下文无企业数据关联

**现状**: `buildOrgContext` 只返回员工姓名、部门、入职日期和合同类型的摘要，过于粗略。HR 在问「我们公司有几个试用期还没签合同的员工」时，AI 无法基于这些数据准确回答。

**建议**:
- 增强 `buildOrgContext` 的数据粒度：增加合同状态、即将到期天数、特殊状态（孕期/工伤）等
- 将 `riskItem` 的详细描述也传入，而非只传标题
- 考虑将员工数据以结构化 JSON 传入，而非纯文本，便于 AI 理解

**涉及文件**: `backend/src/routes/ai.routes.ts`

---

### 3. Portal — 合同签署确认无电子签名

**现状**: 员工点击「确认签署」后只更新 `status = 'CONFIRMED'`，没有电子签名或意愿确认机制。法律上电子合同需要可靠的电子签名（CA 证书或人脸识别），当前实现不具备法律效力。

**建议**:
- 增加短信验证码二次确认：员工点击确认后，发送验证码到手机，输入后完成签署
- 或对接第三方电子签名服务（如 e签宝、法大大）
- 签署完成后生成带有时间戳的签署记录 PDF
- 签署记录存储签名证据（IP、设备信息、地理位置），用于后续举证

**涉及文件**: `backend/src/routes/portal.routes.ts`、`frontend/src/pages/portal/ContractConfirm.tsx`

---

### 4. AI — 用量限制校验逻辑有误

**现状**: `checkUsageLimit` 函数用 `prisma.auditLog` 的 `detail` 字段（JSON 序列化后的字符串）做 `count`，但 `JSON.stringify({ month })` 的结果与数据库中 `recordUsage` 时写入的 `detail` 字段格式可能不匹配（后者是对象直接存储）。查询条件无法正确匹配，导致限制失效。

**建议**:
- 统一 `auditLog.detail` 字段的存储格式，要么都用 JSON 字符串，要么都用对象
- 或者用独立的 `aiUsage` 表记录 AI 使用次数，按月统计更准确
- `checkUsageLimit` 应在请求前调用，而非请求后（避免超限后才报错）

**涉及文件**: `backend/src/routes/ai.routes.ts`

---

## 二、中优先级（高频操作体验）

### 5. Portal — 入职填报无文件上传

**现状**: `onboardingSchema` 定义了身份证照片、银行流水等字段，但实际表单只提交文本数据，没有文件上传功能。员工入职时仍需线下提交证件复印件。

**建议**:
- 增加文件上传功能（身份证正反面、学历证明、体检报告等）
- 文件上传到 OSS/S3，返回 URL 后存入 `formData`
- 支持员工端在「我的合同」页面查看已上传的入职材料
- HR 在 Roster 页面可查看员工上传的入职材料

**涉及文件**: `backend/src/routes/portal.routes.ts`、`frontend/src/pages/portal/Onboarding.tsx`

---

### 6. AI — RAG 知识库无增量更新机制

**现状**: `seedKnowledgeBase` 初始化知识库后，没有提供增量更新接口。劳动法律法规更新后，系统无法自动同步新法规。`addKnowledge` 接口存在但没有在前端暴露入口。

**建议**:
- 增加「知识库管理」页面，HR 可手动添加/编辑法规条文
- 增加法规有效期字段，过期法规自动失效
- 对接权威劳动法数据库（如北大法宝）的增量更新接口（可选）
- 知识库更新后触发向量重索引

**涉及文件**: `backend/src/routes/ai.routes.ts`、`backend/src/services/rag.service.ts`

---

### 7. Portal — 工资条只能看当前月

**现状**: 员工只能通过月份选择器切换查看历史月份，但无法快速看到工资历史趋势。当员工想对比近半年收入变化时，只能逐月切换。

**建议**:
- 在工资条页面增加「工资趋势」图表（近 6 个月应发金额折线图）
- 增加「收入明细导出」功能，员工可下载自己的历史工资条
- 增加「电子工资条存档」功能，每年自动生成 PDF 年度收入证明（用于贷款、签证等场景）

**涉及文件**: `frontend/src/pages/portal/Payslip.tsx`、`backend/src/routes/portal.routes.ts`

---

### 8. AI — 对话流异常时 token 不回收

**现状**: `/chat-stream` 在流式响应中途发生错误时，`recordUsage` 可能不会被调用（因为它在 `res.end()` 之后才调用），导致用户使用了 AI 但次数未记录。

**建议**:
- 将 `recordUsage` 移到请求处理开始前，用 `try/finally` 确保无论成功失败都记录
- 或者使用中间件在响应完成后统一记录
- 增加 `aiUsage` 独立表，用事务保证计数准确性

**涉及文件**: `backend/src/routes/ai.routes.ts`

---

## 三、低优先级（功能补全）

### 9. Portal — 验证码登录安全性不足

**现状**: `codeStore` 使用内存 Map 存储验证码，重启服务器后失效，且在多实例部署时无法共享。5 分钟过期时间也较长，存在被暴力破解风险。

**建议**:
- 生产环境使用 Redis 存储验证码，支持多实例共享和自动过期
- 增加验证码错误次数限制（5 次错误后锁定 15 分钟）
- 验证码增加图形验证码或行为验证码（如滑动拼图）防止机器攻击
- 增加登录失败日志记录

**涉及文件**: `backend/src/routes/portal.routes.ts`

---

### 10. AI — 合同审查结果无结构化存储

**现状**: `reviewContract` 返回纯文本审查结果，用户无法按风险类型检索，也无法统计一段时间内的合同合规趋势。

**建议**:
- 将审查结果结构化存储（风险项、条款位置、严重程度、建议）
- 增加 `contractReviewHistory` 表，记录每次审查的时间、内容摘要
- 前端展示审查结果时，按风险等级分类展示，支持按条款搜索

**涉及文件**: `backend/src/routes/ai.routes.ts`、`backend/prisma/schema.prisma`

---

### 11. Portal — 入职链接无撤回机制

**现状**: HR 生成入职填报链接后无法撤回。如果员工已经收到链接但临时不入职，链接过期前仍然有效，可能被误用。

**建议**:
- 增加「撤销链接」功能，HR 可将已发送的链接置为无效
- 链接撤销后员工访问时提示「该链接已失效，请联系 HR」
- 链接状态增加「已发送」「已使用」「已过期」「已撤销」四种状态

**涉及文件**: `backend/src/routes/employee.routes.ts`、`backend/prisma/schema.prisma`

---

### 12. AI — 对话未设置超时机制

**现状**: AI 服务调用（特别是 `qwen-max` 模型）可能响应很慢，前端没有超时处理。当 AI 服务不可用时，用户只能等待 30 秒才看到错误。

**建议**:
- 后端设置请求超时（如 30 秒），超时时返回友好的错误提示
- 前端增加加载状态超时提示（如 15 秒无响应时显示「AI 服务响应较慢」）
- 增加 AI 服务健康检查接口，前端可在发送请求前检查服务状态

**涉及文件**: `backend/src/services/ai.service.ts`、`frontend/src/pages/AIAssistant.tsx`

---

### 13. Portal — 合同确认链接无重发功能

**现状**: 员工收到合同确认邮件/短信后，如果链接过期或未收到，只能让 HR 重新生成一次。员工端没有「重新发送确认链接」的功能。

**建议**:
- 在员工登录 Portal 后，如果存在待确认合同，显示「合同待确认」提示
- 增加「重新发送确认链接」按钮，员工可自行触发重发
- 链接重发记录需要 HR 审批或系统自动发送（根据企业配置）

**涉及文件**: `frontend/src/pages/portal/MyContract.tsx`、`backend/src/routes/employee.routes.ts`

---

### 14. AI — 案例匹配结果无后续操作

**现状**: `matchCase` 返回的案例分析和建议是纯文本展示，用户无法基于建议快速创建相应的待办事项或调整员工状态。

**建议**:
- 解析案例匹配结果中的「建议」部分，生成可执行的待办事项列表
- 支持用户点击「采纳建议」后，系统自动创建对应操作（如「与员工协商续签」待办）
- 案例匹配结果存入 `AICaseMatch` 表，便于后续审计和分析

**涉及文件**: `backend/src/routes/ai.routes.ts`、`frontend/src/pages/AIAssistant.tsx`、`backend/prisma/schema.prisma`

---

## 四、优先级总览

| 优先级 | 编号 | 功能 | 工作量 |
|--------|------|------|--------|
| P0 | 1 | 工资条确认通知 HR | 中 |
| P0 | 2 | AI 会话上下文数据增强 | 小 |
| P0 | 3 | 合同签署电子签名 | 大 |
| P0 | 4 | AI 用量限制校验修复 | 小 |
| P1 | 5 | 入职材料文件上传 | 中 |
| P1 | 6 | RAG 知识库管理界面 | 中 |
| P1 | 7 | 工资趋势图表+导出 | 中 |
| P1 | 8 | AI 用量记录事务保证 | 小 |
| P2 | 9 | 验证码登录安全加固 | 中 |
| P2 | 10 | 合同审查结构化存储 | 中 |
| P2 | 11 | 入职链接撤回功能 | 小 |
| P2 | 12 | AI 服务超时机制 | 小 |
| P2 | 13 | 合同确认链接重发 | 小 |
| P2 | 14 | 案例匹配结果转待办 | 中 |