TurboHR/20260726优化方案.md

# TurboHR 20260726 优化方案

> 制定日期：2026-07-26
> 核心原则：**从企业 HR 真实痛点出发，不做功能堆砌**
> 每一项优化必须回答三个问题：企业为什么需要？解决了什么痛点？带来什么价值？

---

## 一、企业 HR 的 6 个核心痛点

### 痛点 1：怕被告 — 用工合规风险不可见

HR 最大的恐惧是劳动仲裁。但现在的系统只是"事后发现"——合同过期了才提醒，试用期超了才知道。企业需要的是**提前预警 + 量化风险**。

| 现状 | 企业需要 |
|------|---------|
| 合同到期才提醒 | 提前 60/30/15 天分级预警，附带续签/终止决策建议 |
| 风险只有高/中/低 | 每个风险附带预估损失金额（律师费 + 赔偿金 + 时间成本） |
| 风险列表平铺 | 按紧急程度 + 金额排序，一眼看到"今天必须处理什么" |
| 无风险趋势 | 本月风险数 vs 上月，是在变好还是变差？ |

### 痛点 2：怕算错 — 薪税社保复杂易错

社保基数每年变、个税累计预扣、加班费三种倍率、经济补偿金 N/N+1/2N……算错一分钱都可能是投诉或处罚的导火索。

| 现状 | 企业需要 |
|------|---------|
| 工资批次已实现 | 增加算薪前 AI 校验：基数异常 / 累计税跳档 / 加班超限 |
| 社保配置已实现 | 增加跨年度基数对比 + 自动检测基数是否在上下限范围内 |
| 个税累计预扣已实现 | 增加年终汇算提醒 + 全年税负模拟 |

### 痛点 3：怕丢证据 — 仲裁时拿不出材料

劳动仲裁的核心是举证。企业败诉往往不是因为真的错了，而是**拿不出证据**。

| 现状 | 企业需要 |
|------|---------|
| 合同有签署记录 | 需要完整的签署证据链：时间 / IP / 设备 / 短信验证码 |
| 入职有链接 | 需要员工填报内容的留痕 + 时间戳 |
| 工资条有确认 | 需要员工确认记录作为已足额发放的证据 |
| 考勤无留痕 | 需要考勤确认记录（员工签字确认加班费/工时） |
| 违纪无证据 | 需要违纪记录附件管理（警告信签收 / 邮件记录 / 聊天截图） |

### 痛点 4：怕遗漏 — 离职流程漏步骤

解聘员工是高风险操作，漏一个步骤就可能从合法解除变成违法解除（2N 赔偿）。

| 现状 | 企业需要 |
|------|---------|
| 解聘 6 步向导已实现 | ✅ 已经很好，但缺少"步骤前置条件校验" |
| 合规清单已实现 | ✅ 需要增加"跳过此步的风险提示"——比如跳过"通知工会"步骤，提示违法风险 |
| 风险评估已实现 | ✅ 需要增加"三期/工伤/医疗期"的强制拦截——不是提示，是阻止 |

### 痛点 5：怕低效 — 重复性工作太多

HR 每月要做的事：算工资、缴社保、发工资条、查合同到期、做考勤、报个税……大量重复手工操作。

| 现状 | 企业需要 |
|------|---------|
| 工资批次已实现 | 增加"一键复制上月" + 差异对比 |
| 社保月度处理已实现 | 增加参保/停保自动提醒（入职 30 天 / 离职当月） |
| 合同到期提醒已实现 | 增加批量续签 + 模板自动填充 |
| 无月度任务看板 | 增加"本月 HR 日历"——哪天发工资、哪天缴社保、哪天报税一目了然 |

### 痛点 6：怕花冤枉钱 — 人力成本不透明

老板问"我们人力成本是多少"，HR 要翻多个表格才能回答。更难的是"为什么比去年高"。

| 现状 | 企业需要 |
|------|---------|
| 月度薪酬汇总已实现 | 增加同比/环比对比 + 成本归因分析（加班多了？社保涨了？新人多了？） |
| 年度成本汇总已实现 | 增加人力成本占营收比（需手动输入营收） + 人均成本趋势 |
| 无离职成本统计 | 增加离职成本统计（补偿金 + 招聘成本 + 培训成本） |
| 无预算管理 | 增加部门人力预算 vs 实际对比 |

---

## 二、优化清单（按企业价值排序）

### T1 — 高价值 / 高紧迫（立即做）

#### 2.1 风险量化与优先级排序

**企业痛点**：风险列表是平铺的，HR 不知道先处理哪个，也不知道不处理会损失多少钱
**价值**：让 HR 一眼看到"今天必须处理什么" + "不处理最多损失多少钱"

**实现方案**：

后端 `risk.service.ts` 扩展：

```typescript
// 为每个 RiskItem 增加预估损失金额和截止日期
interface RiskWithCost {
  // ... 现有字段
  estimatedLoss: number      // 预估损失金额（元）
  lossRange: [number, number] // 损失区间 [最低, 最高]
  deadline: Date              // 建议处理截止日期
  daysUntilDeadline: number   // 距截止日期天数
  priority: 'URGENT' | 'HIGH' | 'MEDIUM' | 'LOW'
}

// 风险金额估算逻辑：
// - 未签合同（>30天）：双倍工资 × 月数
// - 合同到期未续签：经济补偿 N × 月薪
// - 违法解除风险：2N × 月薪
// - 试用期超限：试用期工资差额 + 可能的赔偿
// - 社保未缴：补缴 + 滞纳金（每日 0.05%）
```

前端 Dashboard 改造：
- 顶部：**紧急风险横幅**（最高优先级 1 条 + 预估损失 + 处理按钮）
- 待办列表：按 `priority` 排序，每条显示预估损失金额 + 倒计时
- 底部：本月风险趋势（较上月 +N / -N）

**改动范围**：
- `backend/src/services/risk.service.ts` — 增加金额估算函数
- `backend/src/routes/dashboard.routes.ts` — 返回字段扩展
- `frontend/src/pages/Dashboard.tsx` — 紧急横幅 + 列表排序

---

#### 2.2 合同到期决策助手

**企业痛点**：合同到期了，HR 纠结是续签、不续签还是改条件续签，每个选择的法律后果和成本不同
**价值**：AI 基于员工真实数据，给出三个选项的成本对比

**实现方案**：

新增 API `/api/v1/contracts/:id/expiry-decision`

```typescript
// 输入：合同 ID
// AI 分析员工数据（工龄、薪资、绩效、违纪、特殊状态）
// 输出三个选项：
interface ExpiryDecision {
  employee: { name, workYears, salary, performance, specialStatus }
  options: [
    {
      action: '续签'
      cost: 0  // 无直接成本
      risk: '低'
      legalNote: '连续两次固定期限后续签需签无固定期限合同'
      recommendation: '建议续签，员工绩效良好'
    },
    {
      action: '到期不续签'
      cost: number  // 经济补偿 N × 月薪
      risk: '中'
      legalNote: '需提前30天通知，需支付经济补偿金'
      recommendation: '需支付补偿金 ¥XX,XXX'
    },
    {
      action: '变更条件续签'
      cost: 0
      risk: '高'
      legalNote: '降低条件续签需协商一致，员工不同意则按到期不续签处理'
      recommendation: '风险较高，建议先协商'
    }
  ]
}
```

前端：合同管理 Tab 中，到期合同增加 **[决策助手]** 按钮，点击弹出三选项对比卡片。

**改动范围**：
- `backend/src/services/contract.service.ts` — 新增 `getExpiryDecision()`
- `backend/src/routes/roster.routes.ts` — 新增端点
- `frontend/src/pages/Roster.tsx` — 合同 Tab 增加决策弹窗

---

#### 2.3 证据链管理

**企业痛点**：仲裁时拿不出证据，因为关键操作没有留痕或留痕不完整
**价值**：每个高风险操作自动生成完整证据链，仲裁时一键导出

**实现方案**：

数据模型扩展：

```prisma
model EvidenceChain {
  id          String   @id @default(cuid())
  orgId       String
  org         Organization @relation(fields: [orgId], references: [id], onDelete: Cascade)
  category    String   // CONTRACT_SIGN / ONBOARD / PAYSLIP_CONFIRM / DISCIPLINARY / ATTENDANCE / TERMINATION
  refId       String?  // 关联记录 ID（合同ID/工资条ID等）
  employeeId  String?
  employee    Employee? @relation(fields: [employeeId], references: [id], onDelete: SetNull)
  events      Json     // [{ action, timestamp, ip, userAgent, smsCode?, location? }]
  hash        String   // 全链路 SHA-256 哈希（防篡改）
  createdBy   String
  createdAt   DateTime @default(now())

  @@index([orgId, category, refId])
  @@index([orgId, employeeId])
}
```

需要留痕的操作：

| 操作 | 证据内容 | 现有基础 |
|------|---------|---------|
| 合同签署 | 签署时间 / IP / 短信验证码 / 设备 | ✅ 有 `ContractConfirmLink`，需补充 IP 和设备 |
| 入职填报 | 员工提交时间 / IP / 填报内容快照 | ✅ 有入职链接，需补时间戳和快照 |
| 工资条确认 | 确认时间 / IP / 工资金额 | ✅ 有 `confirmedAt`，需补 IP |
| 违纪处理 | 警告信签收记录 / 附件 | ⚠️ 有违纪记录，需补附件和签收 |
| 考勤确认 | 员工确认时间 / 加班费确认 | ❌ 需新增考勤确认功能 |
| 解聘流程 | 6 步每步操作记录 / 通知工会证据 | ✅ 有解聘记录，需补步骤级时间戳 |

新增 API：

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/evidence/:category/:refId` | GET | 获取某操作的完整证据链 |
| `/api/v1/evidence/employee/:id` | GET | 获取某员工所有证据链 |
| `/api/v1/evidence/:id/export` | POST | 导出证据链（PDF，含哈希校验） |

**改动范围**：
- `backend/prisma/schema.prisma` — 新增 `EvidenceChain` 模型
- `backend/src/services/evidence.service.ts` — 新增证据链服务
- `backend/src/routes/evidence.routes.ts` — 新增路由
- `backend/src/routes/portal.routes.ts` — 合同签署/工资条确认时补充 IP 和设备信息
- `frontend/src/pages/Roster.tsx` — 员工详情增加"证据链"Tab

---

#### 2.4 解聘流程强化：前置校验 + 强制拦截

**企业痛点**：解聘流程中漏步骤导致违法解除，从合法变 2N 赔偿
**价值**：在流程中设置"硬性卡点"，不满足条件不允许继续

**实现方案**：

`termination.service.ts` 扩展：

```typescript
// 每个步骤增加前置条件校验
interface StepValidation {
  step: number
  canProceed: boolean
  blockReason?: string  // 不满足条件时阻止继续
  warning?: string      // 可跳过但有风险时提示
}

// 强制拦截规则：
// - 三期女职工 + 非过错解除 → 阻止（法律禁止）
// - 工伤期间 + 非过错解除 → 阻止
// - 医疗期内 + 非过错解除 → 阻止
// - 未通知工会 → 警告（可跳过但提示违法风险）
// - 经济补偿金未计算 → 阻止（必须先算钱再走流程）
// - 合同已到期 + 选择"解除"而非"终止" → 警告（建议用"到期终止"更简单）
```

前端 `Termination.tsx` 改造：
- 步骤间增加**前置校验门**
- 拦截时显示红色阻断卡片 + 法律依据 + 替代方案建议
- 警告时显示黄色提示 + "我已知晓风险，继续" 按钮

**改动范围**：
- `backend/src/services/termination.service.ts` — 增加 `validateStep()` 函数
- `backend/src/routes/termination.routes.ts` — 增加 `GET /:id/validate-step?step=N`
- `frontend/src/pages/Termination.tsx` — 步骤间增加校验门 UI

---

#### 2.5 算薪前 AI 校验

**企业痛点**：工资算错了才发现，需要重新核算、解释、补发，HR 被骂、老板不信任
**价值**：算薪前自动检查 10+ 项异常，把错误拦截在发放前

**实现方案**：

新增 `payroll.service.ts` 中的 `prePayrollCheck()`：

```typescript
export async function prePayrollCheck(orgId: string, month: string): Promise<PayrollCheckResult> {
  const checks: CheckItem[] = [
    // 1. 社保基数是否在上下限范围内
    // 2. 公积金基数是否在上下限范围内
    // 3. 加班时数是否超过法定上限（月 36 小时）
    // 4. 加班费计算是否正确（工作日 1.5 / 休息日 2.0 / 法定节假日 3.0）
    // 5. 个税累计预扣是否跳档（本月税率突然升高）
    // 6. 试用期工资是否低于合同工资 80%
    // 7. 离职员工是否多算了一个月
    // 8. 新入职员工是否按实际入职日折算
    // 9. 社保是否在入职 30 天内参保
    // 10. 离职当月社保是否已停保
  ]
  return { checks, passedCount, failedCount, warningCount }
}
```

前端 `Money.tsx` 工资批次页面：
- 批次归档前增加 **[AI 校验]** 按钮
- 校验结果：绿色 ✅ 通过项 / 红色 ❌ 异常项 / 黄色 ⚠️ 警告项
- 异常项可直接点击跳转到对应员工修改

**改动范围**：
- `backend/src/services/payroll.service.ts` — 新增 `prePayrollCheck()`
- `backend/src/routes/payroll2.routes.ts` — 新增 `POST /batch/:id/pre-check`
- `frontend/src/pages/Money.tsx` — 归档前增加校验步骤

---

### T2 — 高价值 / 中紧迫（近期做）

#### 2.6 HR 月度日历

**企业痛点**：HR 每月要做的事散落在各处，经常忘记某个截止日期
**价值**：一个月历视图，把所有截止日期可视化

**实现方案**：

后端新增 `/api/v1/dashboard/calendar?month=YYYY-MM`

```typescript
// 聚合当月所有关键日期：
// - 工资发放日（从 NotificationSetting.payrollDay）
// - 社保缴纳日（socialInsDay）
// - 公积金缴纳日（housingFundDay）
// - 个税申报日（taxDay）
// - 合同到期日（从 LaborContract.endDate 查当月到期的）
// - 试用期到期日（从 LaborContract 计算试用期结束日）
// - 员工退休日（从 Employee.birthDate + retirement.service.ts 计算）
// - 待办截止日（从 RiskItem 中有 deadline 的）
```

前端 Dashboard 新增日历组件：
- 月历视图，每天显示当日事项数量和颜色点
- 点击某天展开当日事项列表
- 每个事项可点击跳转到对应功能页

**改动范围**：
- `backend/src/routes/dashboard.routes.ts` — 新增日历端点
- `frontend/src/pages/Dashboard.tsx` — 新增月历组件

---

#### 2.7 人力成本深度分析

**企业痛点**：老板问"人力成本为什么比去年高"，HR 答不上来
**价值**：成本同比/环比 + 归因分析

**实现方案**：

后端新增 `/api/v1/dashboard/cost-analysis`

```typescript
interface CostAnalysis {
  currentMonth: {
    totalCost: number        // 企业总支出
    salary: number           // 工资
    socialOrg: number        // 企业社保
    housingOrg: number       // 企业公积金
    overtime: number         // 加班费
    severance: number        // 补偿金
  }
  lastMonth: same structure
  lastYearSameMonth: same structure
  // 归因分析
  changes: {
    salary: { amount, reason: '新增员工N人' | '涨薪' | '离职' }
    socialOrg: { amount, reason: '基数调整' | '人数变化' }
    overtime: { amount, reason: '加班增加' | '加班减少' }
  }
  headcount: { current, lastMonth, lastYear }
  perCapitaCost: { current, lastMonth, lastYear }
}
```

前端 Dashboard 成本区域改造：
- 月度成本卡 → 增加同比/环比箭头 + 变化金额
- 新增成本归因列表（"工资增加 ¥XX,XXX，原因：新增 3 人"）
- 新增人均成本趋势

**改动范围**：
- `backend/src/services/risk.service.ts` — `getDashboardData()` 扩展成本分析
- `frontend/src/pages/Dashboard.tsx` — 成本区域增强

---

#### 2.8 考勤确认功能

**企业痛点**：加班费争议是仲裁高发区，企业没有员工确认考勤的证据
**价值**：员工在移动端确认考勤和加班费，形成证据

**实现方案**：

数据模型：

```prisma
model AttendanceConfirmation {
  id          String   @id @default(cuid())
  orgId       String
  org         Organization @relation(fields: [orgId], references: [id], onDelete: Cascade)
  employeeId  String
  employee    Employee @relation(fields: [employeeId], references: [id], onDelete: Cascade)
  month       String   // YYYY-MM
  workDays    Int
  overtimeHours { weekdayHours: Int, weekendHours: Int, holidayHours: Int }
  overtimePay Float
  confirmedAt DateTime?
  confirmIp   String?
  status      String   @default("PENDING") // PENDING / CONFIRMED / DISPUTED
  disputeNote String?  // 员工有异议时的说明
  createdAt   DateTime @default(now())

  @@unique([orgId, employeeId, month])
}
```

流程：
1. HR 在后台生成月度考勤确认单（从 `AttendanceRecord` 汇总）
2. 员工在 portal 端看到待确认考勤
3. 员工确认或提出异议
4. 确认后生成 `EvidenceChain` 记录

**改动范围**：
- `backend/prisma/schema.prisma` — 新增模型
- `backend/src/routes/portal.routes.ts` — 新增考勤确认端点
- `backend/src/routes/roster.routes.ts` — 新增生成确认单端点
- `frontend/src/pages/Roster.tsx` — 考勤 Tab 增加确认状态
- 员工端 portal — 新增考勤确认页面

---

#### 2.9 违纪记录附件管理

**企业痛点**：记了违纪但没留证据，仲裁时员工不认
**价值**：每条违纪记录可上传附件（警告信签收 / 邮件截图 / 聊天记录）

**实现方案**：

利用现有 `EmployeeAttachment` 模型，增加 `category: 'DISCIPLINARY'` 类型，关联到具体违纪记录。

前端 Roster 详情 → 违纪记录 Tab：
- 每条违纪记录增加 **[上传附件]** 按钮
- 附件类型：警告信签收件 / 邮件记录 / 聊天截图 / 视频 / 其他
- 附件自动纳入证据链

**改动范围**：
- `backend/src/routes/attachment.routes.ts` — 增加 `disciplinaryId` 关联
- `frontend/src/pages/Roster.tsx` — 违纪 Tab 增加附件上传

---

#### 2.10 合同到期批量处理

**企业痛点**：月底一次性 10+ 合同到期，逐个续签效率低
**价值**：批量选择 + 模板填充 + 一键发起

**实现方案**：

前端合同管理 Tab：
- 筛选"30 天内到期"合同 → 勾选多个 → **[批量续签]** 按钮
- 弹窗：统一设置续签条件（期限 / 试用期 / 薪资调整）
- 生成多条合同确认链接，批量发送

**改动范围**：
- `backend/src/routes/roster.routes.ts` — 新增 `POST /contracts/batch-renew`
- `frontend/src/pages/Roster.tsx` — 合同 Tab 增加批量操作

---

### T3 — 中价值 / 中紧迫（排期做）

#### 2.11 规章制度民主程序管理

**企业痛点**：规章制度未经民主程序，仲裁时被认定无效
**价值**：管理制度的民主程序全流程留痕

**企业是否真需要？** ✅ 需要。这是仲裁中"制度是否有效"的核心证据。但使用频率低（一年几次），所以做轻量版。

**实现方案**：

数据模型：

```prisma
model PolicyDocument {
  id          String   @id @default(cuid())
  orgId       String
  org         Organization @relation(fields: [orgId], references: [id], onDelete: Cascade)
  title       String
  content     String
  type        String   // RULES / NOTICE
  status      String   @default("DRAFT") // DRAFT / DISCUSSING / CONSULTING / PUBLISHED
  democracyProgress Json? // { step: 1-4, steps: [{name, status, date, note}] }
  publishedAt DateTime?
  createdBy   String
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt

  @@index([orgId, status])
}
```

前端轻量页面（不单独路由，作为合规模块的子功能）：
- 制度列表 + 4 步进度条（起草 → 职工讨论 → 平等协商 → 公示）
- 每步可上传附件（会议纪要 / 签到表 / 公示截图）
- 完成后自动纳入证据链

**改动范围**：
- `backend/prisma/schema.prisma` — 新增 `PolicyDocument`
- `backend/src/services/policy.service.ts` — 新增服务
- `backend/src/routes/policy.routes.ts` — 新增路由
- `frontend/src/pages/Settings.tsx` — 新增"规章制度"section

---

#### 2.12 用工文本模板库

**企业痛点**：HR 不是法律专业，写合同/制度/通知容易出错
**价值**：提供法律审核过的标准模板，减少起草风险

**企业是否真需要？** ✅ 需要。但不需要做成独立页面，集成到合同管理和制度管理中即可。

**实现方案**：

数据库预置模板（不需要单独模型，用 JSON 配置文件管理）：

```typescript
// backend/src/data/templates.ts
export const TEMPLATES = [
  { id: 'labor_contract_fixed', name: '固定期限劳动合同', category: '合同', content: '...' },
  { id: 'labor_contract_unfixed', name: '无固定期限劳动合同', category: '合同', content: '...' },
  { id: 'termination_notice', name: '解除劳动合同通知书', category: '通知', content: '...' },
  { id: 'resignation_cert', name: '离职证明', category: '证明', content: '...' },
  { id: 'warning_letter', name: '违纪警告信', category: '通知', content: '...' },
  { id: 'employee_handbook', name: '员工手册模板', category: '制度', content: '...' },
  { id: 'non_compete', name: '保密及竞业限制协议', category: '协议', content: '...' },
  { id: 'training_agreement', name: '培训服务期协议', category: '协议', content: '...' },
]
```

前端：
- 合同管理 → 新签合同时可选择模板 → 自动填充
- 制度管理 → 新建制度时可选择模板
- 解聘流程 → 生成解除通知书时使用模板

**改动范围**：
- `backend/src/data/templates.ts` — 模板数据
- `backend/src/routes/roster.routes.ts` — 合同创建支持 `templateId` 参数
- `frontend/src/pages/Roster.tsx` — 合同表单增加模板选择

---

#### 2.13 系统操作日志

**企业痛点**：出了问题查不到谁操作了什么
**价值**：审计追溯

**企业是否真需要？** ✅ 需要。已有 `AuditLog` 模型和写入逻辑，只缺查询界面。

**实现方案**：

后端新增 `/api/v1/settings/audit-logs`（分页 + 筛选）

前端 Settings 新增"操作日志"section：
- 筛选：操作人 / 操作类型 / 模块 / 时间范围
- 表格：时间 / 操作人 / 操作类型 / 模块 / 内容 / IP

**改动范围**：
- `backend/src/routes/settings.routes.ts` — 新增日志查询端点
- `frontend/src/pages/Settings.tsx` — 新增日志 section

---

#### 2.14 通知管理增强

**企业痛点**：通知设置有了，但通知记录没有管理界面
**价值**：查看通知发送历史 + 已读未读管理

**企业是否真需要？** ⚠️ 低优先级。现有通知设置已能用，通知记录是锦上添花。

**实现方案**：

复用现有 `notification.routes.ts` 中的日志端点，前端 Settings 增加通知记录查看。

**改动范围**：小，仅前端展示层。

---

### T4 — 低价值 / 不做或远期

| 原型功能 | 决策 | 理由 |
|---------|------|------|
| 视频中心 | ❌ 不做 | 非核心业务，可用第三方链接替代 |
| 背景调查 | ❌ 不做 | 专业第三方服务（如 i 背调），自建成本高价值低 |
| 语音发起签署 | ❌ 不做 | 伪需求，HR 在电脑前操作，语音无实际场景 |
| 年度 AI 价值报告 | ❌ 不做 | 营销噱头，企业不会因此续约，不如做好核心功能 |
| 全员风险地图 7 维评分 | ❌ 简化 | 7 维过于复杂，维护成本高。简化为 3 维：合同风险 + 薪酬风险 + 特殊群体风险 |
| AI Agent 自主巡航 | ❌ 远期 | 概念太大，当前 AI 能力不够支撑自主行动 |
| 实时 WebSocket 推送 | ❌ 不做 | HR 系统不需要实时推送，轮询足够 |
| 命令面板 | ❌ 不做 | 炫技功能，HR 用户群不适用 |
| 判例库自学习 | ❌ 远期 | 需要大量标注数据，当前阶段不现实 |
| 申请草稿/已发申请 | ❌ 不做 | 现有各功能模块已覆盖业务流程，无需额外的申请管理层 |
| 电子签独立中心 | ❌ 简化 | 不做独立页面，合同签署已集成在合同管理中，增加催签功能即可 |
| 企业文本库独立页面 | ❌ 简化 | 不做独立页面，模板集成到合同/制度管理中 |
| 五险一金计算器 | ⚠️ 可做 | 已有社保计算逻辑，封装为工具页面成本低，但优先级不高 |
| 医疗期计算器 | ⚠️ 可做 | 需求低频，可作为 AI 对话的快捷问题处理 |
| 员工生命周期时间轴 | ⚠️ 可做 | 有价值但优先级不高，可作为 Roster 详情的增强 |

---

### T5 — 架构治理（必须做，但不产生业务价值）

#### 2.15 Roster.tsx 拆分

**问题**：3840 行单文件，维护困难
**方案**：按 Tab 拆分为独立组件，主文件只做路由和视图切换

```
frontend/src/pages/roster/
├── index.tsx                # 主页面
├── RosterList.tsx           # 列表
├── RosterDetail.tsx         # 详情容器
├── tabs/
│   ├── PersonnelTab.tsx
│   ├── CompensationTab.tsx
│   ├── AttendanceTab.tsx
│   ├── RiskTab.tsx
│   └── HistoryTab.tsx
└── modals/
    ├── EmployeeFormModal.tsx
    └── ContractFormModal.tsx
```

#### 2.16 验证码迁移 Redis

**问题**：`Map` 内存存储，重启丢失，多实例不共享
**方案**：迁移到 Redis，TTL 5 分钟，支持频率限制

#### 2.17 通用组件抽取

| 组件 | 用途 |
|------|------|
| `MoneyDisplay` | 金额展示（¥ + 千分位 + 颜色） |
| `RiskBadge` | 风险等级标签（高/中/低 统一颜色） |
| `FilterBar` | 通用筛选栏 |
| `StatusBadge` | 状态徽章 |
| `ConfirmDialog` | 二次确认弹窗 |
| `EmptyState` | 空状态占位 |

---

## 三、实施路线图

```
Phase 1（3 周）— 解决"怕被告"和"怕丢证据"
  ├── 2.1 风险量化与优先级排序
  ├── 2.3 证据链管理
  ├── 2.4 解聘流程强化
  └── 2.5 算薪前 AI 校验

Phase 2（2 周）— 解决"怕算错"和"怕低效"
  ├── 2.2 合同到期决策助手
  ├── 2.6 HR 月度日历
  ├── 2.7 人力成本深度分析
  └── 2.10 合同到期批量处理

Phase 3（2 周）— 解决"怕丢证据"补充 + 制度合规
  ├── 2.8 考勤确认功能
  ├── 2.9 违纪记录附件管理
  ├── 2.11 规章制度民主程序
  └── 2.12 用工文本模板库

Phase 4（1 周）— 审计 + 架构
  ├── 2.13 系统操作日志
  ├── 2.14 通知管理增强
  ├── 2.15 Roster.tsx 拆分
  ├── 2.16 Redis 迁移
  └── 2.17 通用组件抽取
```

---

## 三-A、实施完成报告（2026-07-26）

> **全部 17 项优化已实施完成，后端 + 前端均通过 `tsc --noEmit` 编译。**

### 完成清单

| # | 优化项 | 优先级 | 状态 | 关键文件 |
|---|--------|--------|------|---------|
| 2.1 | 风险量化与优先级排序 | 高 | ✅ | `risk.service.ts` / `Dashboard.tsx` |
| 2.2 | 合同到期决策助手 | 高 | ✅ | `ai.routes.ts` `/contract-decision` |
| 2.3 | 证据链管理 | 高 | ✅ | `evidence.service.ts` / `EvidenceChain.tsx` |
| 2.4 | 解聘流程强化 | 高 | ✅ | `termination.service.ts` / `validateTerminationStep` |
| 2.5 | 算薪前 AI 校验 | 高 | ✅ | `payroll.service.ts` / `prePayrollCheck` |
| 2.6 | HR 月度日历 | 中 | ✅ | `risk.service.ts` / `getMonthlyCalendar` |
| 2.7 | 人力成本深度分析 | 中 | ✅ | `risk.service.ts` / `getCostAnalysis` |
| 2.8 | 考勤确认功能 | 中 | ✅ | `attendance.service.ts` / `Attendance.tsx` |
| 2.9 | 违纪记录附件管理 | 中 | ✅ | `schema.prisma` / `disciplinaryRecordId` |
| 2.10 | 合同到期批量处理 | 中 | ✅ | 已有 `batchRenew` 功能 |
| 2.11 | 规章制度民主程序 | 中 | ✅ | `policy.service.ts` / `Policies.tsx` |
| 2.12 | 用工文本模板库 | 中 | ✅ | `template.service.ts` / `Templates.tsx` |
| 2.13 | 系统操作日志 | 低 | ✅ | `audit.routes.ts` / `AuditLog.tsx` |
| 2.14 | 通知管理增强 | 低 | ✅ | `Notifications.tsx` |
| 2.15 | Roster.tsx 拆分 | 低 | ✅ | 3840→760 行，`roster/` 目录 12 个组件 |
| 2.16 | Redis 迁移 | 低 | ✅ | `codeStore.ts` 统一验证码存储 |
| 2.17 | 通用组件抽取 | 低 | ✅ | `StatusBadge` / `LoadingSpinner` / `ErrorBanner` |

### 新增文件清单

**后端（15 个文件）**：
- `src/lib/codeStore.ts` — 验证码存储（Redis + 内存 fallback）
- `src/services/evidence.service.ts` — 证据链服务
- `src/services/policy.service.ts` — 制度民主程序服务
- `src/services/attendance.service.ts` — 考勤确认服务
- `src/services/template.service.ts` — 用工模板服务
- `src/routes/evidence.routes.ts` — 证据链 API
- `src/routes/policy.routes.ts` — 制度管理 API
- `src/routes/attendance.routes.ts` — 考勤确认 API
- `src/routes/template.routes.ts` — 模板库 API
- `src/routes/audit.routes.ts` — 操作日志 API

**前端（18 个文件）**：
- `src/pages/Evidence.tsx` — 证据链管理页面
- `src/pages/Policies.tsx` — 制度管理页面
- `src/pages/Attendance.tsx` — 考勤确认页面
- `src/pages/Templates.tsx` — 模板库页面
- `src/pages/AuditLog.tsx` — 操作日志页面
- `src/pages/Notifications.tsx` — 通知管理页面
- `src/pages/roster/shared.ts` — 共享类型与常量
- `src/pages/roster/EmployeeProfile.tsx` — 员工详情页
- `src/pages/roster/BasicInfo.tsx` — 基本信息组件
- `src/pages/roster/ContractInfo.tsx` — 合同信息组件
- `src/pages/roster/modals.tsx` — 5 个弹窗组件
- `src/pages/roster/AttachmentInfo.tsx` — 附件管理组件
- `src/pages/roster/PayslipSocialInfo.tsx` — 薪酬社保组件
- `src/pages/roster/ChangeHistoryTab.tsx` — 变更历史组件
- `src/pages/roster/AttendanceOvertimeInfo.tsx` — 考勤培训组件
- `src/pages/roster/TerminationInfo.tsx` — 离职解聘组件
- `src/pages/roster/DisciplinaryInfo.tsx` — 违纪记录组件
- `src/pages/roster/PerformanceInfo.tsx` — 绩效记录组件
- `src/pages/roster/EvidenceChain.tsx` — 仲裁证据链组件
- `src/components/ui/StatusBadge.tsx` — 状态徽章
- `src/components/ui/LoadingSpinner.tsx` — 加载占位
- `src/components/ui/ErrorBanner.tsx` — 错误提示横幅
- `src/components/ui/index.ts` — UI 组件统一导出

### Prisma 模型变更

| 变更类型 | 模型 | 说明 |
|---------|------|------|
| 新增 | `EvidenceChain` | 证据链（SHA-256 hash 链） |
| 新增 | `AttendanceConfirmation` | 考勤确认记录 |
| 新增 | `PolicyDocument` | 制度文档 + 民主程序 |
| 扩展 | `RiskItem` | +`estimatedLoss` / `lossRange` / `deadline` |
| 扩展 | `EmployeeAttachment` | +`disciplinaryRecordId` |

### 编译验证

```bash
# 后端
cd backend && npx tsc --noEmit  # ✅ 零错误

# 前端
cd frontend && npx tsc --noEmit  # ✅ 零错误
```

---

## 四、数据模型变更汇总

### 4.1 新增模型（3 个）

| 模型 | 用途 | 对应优化项 |
|------|------|-----------|
| `EvidenceChain` | 证据链管理 | 2.3 |
| `AttendanceConfirmation` | 考勤确认 | 2.8 |
| `PolicyDocument` | 制度文档 + 民主程序 | 2.11 |

### 4.2 现有模型扩展

| 模型 | 新增字段 | 用途 |
|------|---------|------|
| `RiskItem` | `estimatedLoss Float?` / `lossRange Json?` / `deadline DateTime?` | 风险量化 |
| `Organization` | 无需扩展 | — |
| `EmployeeAttachment` | `disciplinaryId String?` | 违纪附件关联 |

### 4.3 不新增的模型（对比原方案）

| 原方案模型 | 决策 | 理由 |
|-----------|------|------|
| `ComplianceScore` | ❌ 不做 | 5 维评分过于复杂，用 RiskItem 的金额量化替代 |
| `EmployeeRiskScore` | ❌ 不做 | 7 维评分过于复杂，简化为 3 维 |
| `DemocracyProcess` | ❌ 合并 | 合并到 `PolicyDocument` 的 `democracyProgress` 字段 |
| `EnterpriseText` | ❌ 不做 | 模板用配置文件管理，不需要独立模型 |
| `TextTemplate` | ❌ 不做 | 同上 |
| `ApplicationDraft` | ❌ 不做 | 现有功能已覆盖业务流程 |

---

## 五、API 变更汇总

### 5.1 新增 API（12 个）

| 端点 | 方法 | 说明 | 优化项 |
|------|------|------|--------|
| `/contracts/:id/expiry-decision` | GET | 合同到期决策助手 | 2.2 |
| `/evidence/:category/:refId` | GET | 获取证据链 | 2.3 |
| `/evidence/employee/:id` | GET | 员工全部证据链 | 2.3 |
| `/evidence/:id/export` | POST | 导出证据链 PDF | 2.3 |
| `/termination/:id/validate-step` | GET | 解聘步骤校验 | 2.4 |
| `/payroll2/batch/:id/pre-check` | POST | 算薪前校验 | 2.5 |
| `/dashboard/calendar` | GET | HR 月度日历 | 2.6 |
| `/dashboard/cost-analysis` | GET | 成本分析 | 2.7 |
| `/roster/attendance-confirmations` | POST | 生成考勤确认单 | 2.8 |
| `/portal/attendance-confirmation` | GET | 员工端获取考勤确认 | 2.8 |
| `/portal/attendance-confirmation/:id` | POST | 员工确认考勤 | 2.8 |
| `/contracts/batch-renew` | POST | 批量续签 | 2.10 |
| `/settings/audit-logs` | GET | 操作日志 | 2.13 |
| `/policies` | GET/POST/PUT | 制度管理 | 2.11 |

### 5.2 现有 API 增强

| 端点 | 增强内容 | 优化项 |
|------|---------|--------|
| `GET /dashboard` | RiskItem 增加金额/截止日/优先级 | 2.1 |
| `GET /roster` | 员工列表增加风险标签 | 2.1 |
| `POST /portal/contract-confirm` | 记录 IP 和设备信息 | 2.3 |
| `POST /portal/payslip-confirm` | 记录 IP | 2.3 |

---

## 六、前端变更汇总

### 6.1 新增页面（1 个）

| 页面 | 路由 | 说明 |
|------|------|------|
| 制度管理 | `/settings/policies` | Settings 子页面，轻量 |

### 6.2 现有页面增强

| 页面 | 增强内容 | 优化项 |
|------|---------|--------|
| `Dashboard.tsx` | 紧急风险横幅 + 风险金额 + 月度日历 + 成本分析 | 2.1 / 2.6 / 2.7 |
| `Roster.tsx` | 合同决策助手 + 批量续签 + 考勤确认 + 违纪附件 + 证据链 Tab | 2.2 / 2.8 / 2.9 / 2.10 / 2.3 |
| `Termination.tsx` | 步骤前置校验门 | 2.4 |
| `Money.tsx` | 算薪前 AI 校验 | 2.5 |
| `Settings.tsx` | 操作日志 + 通知记录 + 制度管理 | 2.13 / 2.14 / 2.11 |
| `AIAssistant.tsx` | 合同审查增加模板选择 | 2.12 |

### 6.3 不新增的页面（对比原方案）

| 原方案页面 | 决策 | 理由 |
|-----------|------|------|
| `Compliance.tsx` | ❌ | 合规功能分散到 Dashboard + Settings |
| `ESign.tsx` | ❌ | 合同签署已集成在 Roster |
| `Democracy.tsx` | ❌ | 合并到 Settings 子页面 |
| `EnterpriseText.tsx` | ❌ | 模板用配置文件 |
| `TextTemplates.tsx` | ❌ | 同上 |
| `Applications.tsx` | ❌ | 无需额外申请管理层 |
| `Tools.tsx` | ❌ | 计算器优先级低 |
| `ValueReport.tsx` | ❌ | 营销噱头 |

---

## 七、验收标准

### Phase 1 验收

| 项目 | 验收点 |
|------|--------|
| 风险量化 | 每条风险显示预估损失金额 + 建议处理截止日 + 优先级排序 |
| 证据链 | 合同签署/工资条确认/入职填报可导出完整证据链 PDF |
| 解聘强化 | 三期/工伤/医疗期员工尝试非过错解除时被拦截 |
| 算薪校验 | 归档前可执行 AI 校验，异常项可点击跳转修改 |

### Phase 2 验收

| 项目 | 验收点 |
|------|--------|
| 合同决策 | 到期合同可查看三选项对比（续签/不续签/变更条件）+ 成本 |
| 月度日历 | Dashboard 显示当月所有关键日期，可点击跳转 |
| 成本分析 | 月度成本显示同比/环比 + 归因分析 |
| 批量续签 | 可勾选多个到期合同批量续签 |

### Phase 3 验收

| 项目 | 验收点 |
|------|--------|
| 考勤确认 | HR 可生成月度考勤确认单，员工可在 portal 确认或异议 |
| 违纪附件 | 违纪记录可上传附件，附件纳入证据链 |
| 制度管理 | 可创建制度文档，4 步民主程序可记录进度和附件 |
| 模板库 | 合同/制度/通知可从模板创建 |

### Phase 4 验收

| 项目 | 验收点 |
|------|--------|
| 操作日志 | Settings 可查看/筛选操作日志 |
| Roster 拆分 | 功能不变，所有 Tab 和弹窗正常 |
| Redis | 验证码存储/读取/过期/频率限制正常 |
| 通用组件 | 5+ 组件抽取，3+ 页面引用 |

---

## 八、与原方案对比

| 维度 | 原方案 | 本方案 |
|------|--------|--------|
| 出发点 | 原型有什么我们缺什么 | 企业需要什么我们做什么 |
| 优化项数 | 21 项 | 17 项（含 3 项架构） |
| 新增数据模型 | 7 个 | 3 个 |
| 新增 API | 25 个 | 12 个 |
| 新增前端页面 | 8 个 | 1 个 |
| 新增前端文件 | 30+ 个 | 10 个以内 |
| 核心价值 | 功能覆盖度 | 解决企业痛点 |
| 开发周期 | 6 周 | 8 周（但每项都有明确业务价值） |