TurboHR/20260727-优化-梳理.md

# TurboHR 20260727 优化需求梳理

> **来源**：HR 用户测试反馈  
> **日期**：2026-07-27  
> **测试地区**：河北省（重点）  
> **梳理方式**：逐条对照源码分析根因，标注涉及文件和行号

---

## 一、需求分类总览

| # | 模块 | 优先级 | 类型 | 简述 | 根因已定位 |
|---|------|--------|------|------|-----------|
| 1 | 社保政策 | 🔴 高 | Bug+功能 | 仅北京/上海，无法添加其他城市，河北无法使用 | ✅ |
| 2 | 社保政策 | 🔴 高 | 功能 | 河北五险不同上下限，三险与医保需分开 | ✅ |
| 3 | 社保政策 | 🟡 中 | 功能 | 大病险、长护险各地市收费不同，需单独添加险种 | ✅ |
| 4 | 公积金 | 🔴 高 | Bug | 公积金模块无法测算数据，显示报错 | ✅ |
| 5 | 专项附加扣除 | 🟡 中 | 功能 | 无法关联自然人数据，需手动录入，是否可按月累计 | ✅ |
| 6 | 花名册-合同 | 🔴 高 | Bug | 花名册中添加劳动合同信息无法正常保存 | ✅ |
| 7 | 花名册-导入 | 🔴 高 | Bug+UI | 批量导入仅员工基本信息成功，合同/加班/考勤均失败 | ✅ |
| 8 | 花名册-UI | 🟡 中 | UI | 缺少明显的批量导入按钮入口 | ✅ |
| 9 | 薪酬管理 | 🔴 高 | Bug | 创建批次总提示创建失败 | ✅ |
| 10 | 薪酬管理 | 🔴 高 | 功能 | 无法单独添加一个人发薪，必须全员生成再删除 | ✅ |
| 11 | 薪酬管理 | 🟡 中 | 功能 | 缺少工资表导入功能 | ✅ |
| 12 | 个税计算 | 🔴 高 | Bug | 导入工资后显示无个税，未匹配自动算税 | ✅ |
| 13 | 证据链 | 🔴 高 | Bug | 证据链无法查看（手动录入的员工也无法查看） | ✅ |
| 14 | 加班费 | 🟡 中 | 功能 | 加班费倍率硬编码(1.5/2.0/3.0)，需支持公司自定义标准 | ✅ |
| 15 | 考勤对接 | 🟢 低 | 功能 | 考勤制度是否可关联企微等外部系统 | — |
| 16 | 电子签 | 🟢 低 | 功能 | 合同签署是否可关联电子签平台 | — |
| 17 | 文本模板 | 🟡 中 | 功能 | 缺少「个人提出离职」的解除协议模板 | ✅ |

---

## 二、详细分析（含源码根因）

### 2.1 社保政策 — 多城市支持（#1, #2, #3）

**根因分析**：

1. **城市选择为下拉固定列表，无法手动输入**
   - `SocialInsurance.tsx:340-347` — 城市选择是 `<select>` 下拉，选项来自 `GET /social/config/cities` 返回的已有城市列表
   - 如果数据库中只有北京/上海，用户无法选择其他城市
   - **但**新建版本表单 `SocialInsurance.tsx:570` 中城市字段是 `<Input>` 文本框，可以手动输入
   - **真正问题**：城市选择下拉限制了查看范围，用户在新建版本时可以输入「河北」，但切换城市查看时下拉没有「河北」选项

2. **社保上下限单一，无法区分三险与医保**
   - `schema.prisma:389-390` — `SocialInsuranceConfig` 仅有 `baseMin` / `baseMax` 两个字段
   - `payroll.service.ts:37-42` — `calcSocialInsurance()` 使用单一 `actualBase` 计算所有险种
   - 河北省政策：养老/失业/工伤保险基数上下限 ≠ 医疗/生育保险基数上下限

3. **无大病险/长护险字段**
   - `schema.prisma:376-401` — `SocialInsuranceConfig` 无大病险、长护险相关字段
   - `payroll.service.ts:39-40` — 计算仅包含养老/医疗/失业/工伤/生育五险

**修复方案**：

| 改动 | 文件 | 具体内容 |
|------|------|---------|
| Schema 扩展 | `prisma/schema.prisma:376-401` | 新增 `medicalBaseMin Float @default(0)` `medicalBaseMax Float @default(0)` `extraInsurances String? // JSON` |
| 社保计算适配 | `backend/src/services/payroll.service.ts:37-42` | 三险用 `baseMin/baseMax`，医保用 `medicalBaseMin/medicalBaseMax`（为 0 时 fallback 到 baseMin/baseMax） |
| 前端城市选择 | `frontend/src/pages/SocialInsurance.tsx:340-347` | `<select>` 改为 `<input list>` + `<datalist>`，支持手动输入城市名 |
| 新建版本表单 | `frontend/src/pages/SocialInsurance.tsx:568-590` | 新增医保上下限输入框 + 附加险种配置区 |
| 预置河北数据 | seed 脚本或手动 | 添加河北省社保配置（养老/失业/工伤基数 3920~19602，医疗/生育基数 5360~26796） |

**河北省 2024 社保参考数据**：
```
养老/失业/工伤：基数下限 3920，上限 19602
医疗/生育：      基数下限 5360，上限 26796
养老 企业16%  个人8%
失业 企业0.7%  个人0.3%
工伤 企业0.2~1.9%（按行业）
医疗 企业8%    个人2%
生育 企业1%（已并入医疗，河北单独列）
```

---

### 2.2 公积金测算报错（#4）

**根因分析**：

- `social.routes.ts:557-606` — `/housing-calculate` 接口
- **核心问题在第 580-583 行**：当查不到公积金配置时，自动创建一条默认配置：
  ```ts
  config = await prisma.housingFundConfig.create({
    data: { orgId, effectiveFrom: ..., city: city || '北京', createdBy: ... },
  })
  ```
  创建的配置使用 schema 默认值（`housingOrg: 12, housingEmp: 12, baseMin: 6326, baseMax: 33891`），但 `city` 参数可能为 `undefined`
  
- **前端调用链**：`SocialInsurance.tsx:611` — `calcHousingMutate()` 调用 `POST /social/housing-calculate`，传参 `{ base, month, city }`
- **可能原因**：
  1. `city` 未正确传递（`undefined`），创建的配置城市为「北京」而非用户期望的城市
  2. 前端 `housingResult` 的 `items` 字段不存在（公积金返回的是 `housingOrg/housingEmp` 而非 `items` 数组），但前端试算结果展示复用了社保的 `r.items.map()` 逻辑，导致 `undefined.map()` 报错

- **前端结果展示 Bug**：`SocialInsurance.tsx:625-677` — 试算结果展示区同时用于社保和公积金，使用 `r.items.map()` 渲染表格。但公积金计算接口返回 `{ housingOrg, housingEmp, total }`，**没有 `items` 数组**，导致 `r.items` 为 `undefined` → `.map()` 抛出 TypeError

**修复方案**：

| 改动 | 文件 | 具体内容 |
|------|------|---------|
| 前端结果展示 | `frontend/src/pages/SocialInsurance.tsx:625-677` | 公积金试算结果单独渲染（显示企业/个人比例和金额），不复用社保的 items 表格 |
| 后端兜底优化 | `backend/src/routes/social.routes.ts:580-583` | 不自动创建默认配置，改为返回提示「该城市暂无公积金配置，请先创建」 |

---

### 2.3 专项附加扣除（#5）

**根因分析**：

- `payroll.service.ts:179` — 个税累计预扣计算：
  ```ts
  const ytdSpecialDeduction = employee.specialDeduction * Number(month.slice(5, 7))
  ```
- `Employee.specialDeduction` 是单一 Float 字段，表示每月专项附加扣除金额
- 个税计算时直接乘以月份序号作为累计扣除额
- **问题**：不支持按月不同金额（如某月子女教育扣除变更），且需手动在员工档案中录入

**修复方案**：

| 改动 | 文件 | 具体内容 |
|------|------|---------|
| 新建 Prisma 模型 | `prisma/schema.prisma` | `model SpecialDeductionRecord { id, orgId, employeeId, month, amount, type(子女教育/住房贷款/赡养老人/...), createdBy, createdAt }` |
| 个税计算适配 | `backend/src/services/payroll.service.ts:179` | 改为查询 `SpecialDeductionRecord` 按月累加，fallback 到 `employee.specialDeduction * 月份` |
| 前端录入入口 | `frontend/src/pages/roster/BasicInfo.tsx` | 在社保/公积金基数旁增加「专项附加扣除」按月录入区 |

---

### 2.4 花名册合同保存失败（#6）

**根因分析**：

- **前端调用**：`ContractInfo.tsx:19` — `api.post('/employees/contracts', { ...data, employeeId })`
- **后端路由**：`employee.routes.ts:206-209` — `router.post('/contracts', ...)` → `addContractSchema.parse(req.body)` → `addContract()`
- **Schema 校验**：`contract.schema.ts:54-64`：
  ```ts
  signDate: z.string().datetime().nullable(),   // 必须是 ISO datetime 字符串
  startDate: z.string().datetime(),              // 必须是 ISO datetime 字符串
  endDate: z.string().datetime().nullable(),
  ```
- **前端提交**：`ContractInfo.tsx` 表单中日期用 `<Input type="date">`，值为 `YYYY-MM-DD` 格式（如 `2026-07-27`），**不是 ISO datetime 格式**（`2026-07-27T00:00:00.000Z`）
- **根因**：Zod 校验 `z.string().datetime()` 要求 RFC 3339 格式，`YYYY-MM-DD` 不通过校验 → `ZodError` → 返回 400 → 前端显示「保存失败」

**修复方案**：

| 改动 | 文件 | 具体内容 |
|------|------|---------|
| Schema 日期校验放宽 | `backend/src/schemas/contract.schema.ts:56-58` | 改为 `z.string().nullable()` + 在 `addContract()` 中用 `new Date()` 解析 |
| 或前端提交时转换 | `frontend/src/pages/roster/ContractInfo.tsx` | 提交前将日期转为 ISO 格式：`new Date(form.signDate).toISOString()` |

**推荐方案**：前端转换（改动最小，且 `Contracts.tsx` 新建员工时已用 `new Date(form.signDate).toISOString()` 转换，`ContractInfo.tsx` 遗漏了同样的转换）

---

### 2.5 批量导入问题（#7, #8）

**根因分析**：

- `import.routes.ts:214-390` — 多 Sheet 导入逻辑
- **Sheet 名称精确匹配**：代码中硬编码 Sheet 名称为中文（如「员工信息」「劳动合同」「加班记录」「考勤记录」），如果用户修改了 Sheet 名或模板格式不一致，则无法匹配
- **合同匹配逻辑**：先按 `idCardHash` 匹配，再按 `name` 匹配。如果员工信息 Sheet 和合同 Sheet 中的身份证号或姓名不一致（空格、别称），则匹配失败
- **错误信息未充分展示**：后端返回 `errors` 数组，但前端可能只显示了「成功 N 条」的汇总，未展示详细错误

**修复方案**：

| 改动 | 文件 | 具体内容 |
|------|------|---------|
| 花名册增加导入按钮 | `frontend/src/pages/Roster.tsx` 或 `Contracts.tsx` | 在列表页顶部增加「批量导入」按钮，点击后弹出导入向导 |
| 导入模板下载 | `frontend` | 调用 `GET /import/template` 下载标准模板 |
| 错误详情展示 | `frontend` | 导入结果弹窗中展示 `errors[]` 数组的每条错误（行号+原因） |
| Sheet 名称容错 | `backend/src/routes/import.routes.ts` | Sheet 名称匹配改为包含关键词即可（如包含「合同」即视为劳动合同 Sheet） |

---

### 2.6 薪酬管理创建失败（#9）

**根因分析**：

- `payroll2.routes.ts:220-403` — 批次创建逻辑
- **关键链路**：`createBatchSchema.parse(req.body)` → 查询员工 → 循环 `calcBatchEntry()` → 创建 `BatchEntry`
- **`calcBatchEntry()` 可能抛异常**：`payroll.service.ts:109-127` — 查询 `socialInsuranceConfig` 和 `housingFundConfig` 时**不带 `city` 过滤**：
  ```ts
  prisma.socialInsuranceConfig.findFirst({
    where: { orgId, effectiveFrom: { lte: month }, OR: [...] },
    orderBy: { effectiveFrom: 'desc' },
  })
  ```
  如果组织有多个城市的配置，可能取到错误城市的配置；如果无配置，`socialConfig` 为 `null`，社保为 0（不报错）
- **更可能的根因**：`payroll.service.ts:329` — `Number(decrypt(emp.monthlySalary))` 如果 `monthlySalary` 加密格式异常，`decrypt` 抛出错误，虽然有 `catch` 回退到 `Number(emp.monthlySalary)`，但如果 `monthlySalary` 本身是加密后的非数字字符串，`Number()` 返回 `NaN`，后续计算 `NaN` 传播可能导致 Prisma 写入失败
- **另一个可能**：`payroll2.routes.ts:346` — `calcBatchEntry()` 内部 `prisma.payslip.findMany()` 查询历史工资条，如果数据量大可能超时

**修复方案**：

| 改动 | 文件 | 具体内容 |
|------|------|---------|
| calcBatchEntry 增加城市过滤 | `backend/src/services/payroll.service.ts:111-118` | 查询社保配置时加入 `city: employee.city` 过滤 |
| 错误处理增强 | `backend/src/routes/payroll2.routes.ts:346` | `calcBatchEntry()` 调用加 try-catch，单条失败跳过并记录，不阻塞整批 |
| 前端错误展示 | `frontend/src/pages/Money.tsx:111-120` | `onError` 时展示后端返回的具体错误信息 |

---

### 2.7 单人发薪（#10）

**根因分析**：

- **后端已有接口**：`payroll2.routes.ts:489-547` — `POST /batches/:batchId/employees` 支持向批次添加员工
- **前端已有调用**：`Money.tsx:735-739` — `addMutation` 调用 `api.post('/payroll2/batches/${batchId}/employees', { employeeIds })`
- **结论**：功能已存在，用户可能未找到入口。需检查前端 UI 是否暴露了「添加员工」按钮

**修复方案**：

- 检查 `Money.tsx` 批次详情页中是否有「添加员工」按钮
- 如果按钮存在但隐藏，调整 UI 使其更明显
- 如果按钮不存在，在批次详情页增加「添加员工」操作

---

### 2.8 工资表导入（#11）

**现状**：无工资表导入功能

**修复方案**：

| 改动 | 文件 | 具体内容 |
|------|------|---------|
| 后端导入接口 | `backend/src/routes/import.routes.ts` | 新增 `POST /import/payroll` 解析 Excel 工资表（员工姓名/身份证 + 基本工资/津贴/奖金/扣款） |
| 前端导入入口 | `frontend/src/pages/Money.tsx` | 批次详情页增加「导入工资表」按钮 |

---

### 2.9 个税计算问题（#12）

**根因分析**：

- `payroll.service.ts:160-183` — 累计预扣法个税计算逻辑完整
- **个税为 0 的正常情况**：
  - `totalPay < 5000` → `ytdTaxableIncome ≤ 0` → 个税 = 0
  - `totalPay - 社保 - 公积金 - 5000*月份 - 专项附加扣除 ≤ 0` → 个税 = 0
- **个税为 0 的异常情况**：
  - 社保配置缺失 → `socialEmp = 0`（不会导致个税为 0，反而个税应更高）
  - `specialDeduction` 为 0 → 减除费用仅 5000/月，如果工资 > 5000 应有个税
  - **真正问题**：如果 `baseSalary = 0`（使用 `blank_all` 或 `blank_employees` 模式创建批次），`totalPay = 0` → 个税 = 0
- **用户反馈场景**：用户说「导入工资后显示无个税」，说明工资数据已导入但个税仍为 0
  - 可能原因：导入工资数据后未触发 `calcBatchEntry()` 重新计算
  - 或前端显示的个税字段映射有误

**修复方案**：

| 改动 | 文件 | 具体内容 |
|------|------|---------|
| 编辑条目时重算 | `backend/src/routes/payroll2.routes.ts` | `PUT /batches/:batchId/entries/:employeeId` 已调用 `calcBatchEntry()`，确认前端编辑后是否触发重算 |
| 前端字段映射 | `frontend/src/pages/Money.tsx` | 确认 `entry.tax` 字段正确显示 |
| 导入后自动重算 | `backend/src/routes/import.routes.ts` | 如果新增工资表导入，导入后自动调用 `calcBatchEntry()` |

---

### 2.10 证据链无法查看（#13）

**根因分析**：

- **后端 API 完整**：`roster.routes.ts:240-494` — `GET /:id/evidence-chain` 返回 `{ employee, evidence[], risks[], summary }`
- **前端组件完整**：`EvidenceChain.tsx:14-136` — 使用 `useQuery` 调用 `api.get('/roster/${employeeId}/evidence-chain')`，渲染证据列表和风险提醒
- **前端引用正确**：`EmployeeProfile.tsx:96` — `{tab === 'evidence' && <EvidenceChain employeeId={employeeId} />}`
- **可能根因**：
  1. **Tab 未显示**：`EmployeeProfile.tsx` 的 Tab 列表中是否有「证据链」Tab？需检查 `TAB_GROUPS` 定义
  2. **API 路由前缀**：前端 `api.get('/roster/${employeeId}/evidence-chain')` → 实际请求路径需确认是否匹配后端路由挂载前缀
  3. **新员工无数据**：手动录入的新员工如果没有合同/工资条/考勤等关联数据，`evidence[]` 数组可能为空，前端显示「无数据」

**修复方案**：

| 改动 | 文件 | 具体内容 |
|------|------|---------|
| 检查 Tab 定义 | `frontend/src/pages/roster/shared.ts` | 确认 `TAB_GROUPS` 中包含证据链 Tab |
| 空数据提示优化 | `frontend/src/pages/roster/EvidenceChain.tsx:24` | `if (!data || data.evidence?.length === 0)` 时显示「暂无证据记录，员工产生合同/工资/考勤等数据后自动生成」 |
| API 路径验证 | `frontend/src/lib/api.ts` | 确认 baseURL + `/roster/:id/evidence-chain` 是否匹配后端挂载路径 |

---

### 2.11 加班费自定义标准（#14）

**根因分析**：

- **后端已有 OvertimeConfig 模型和 API**：
  - `schema.prisma:444-454` — `OvertimeConfig` 模型，含 `weekdayRate/weekendRate/holidayRate/monthlyDays/dailyHours`
  - `payroll.routes.ts:334-370` — `GET /overtime/config` 和 `POST /overtime/config` 接口
- **但加班费计算仍用硬编码**：`payroll.routes.ts:45-47` 和 `107-109`：
  ```ts
  const weekdayPay = hourlyWage * 1.5 * data.weekdayHours
  const weekendPay = hourlyWage * 2.0 * data.weekendHours
  const holidayPay = hourlyWage * 3.0 * data.holidayHours
  ```
  **未读取 `OvertimeConfig` 中的倍率**，直接硬编码 1.5/2.0/3.0

**修复方案**：

| 改动 | 文件 | 具体内容 |
|------|------|---------|
| 加班费计算读取配置 | `backend/src/routes/payroll.routes.ts:44-47` | 先查 `OvertimeConfig`，用配置中的倍率替代硬编码 |
| 同上 | `backend/src/routes/payroll.routes.ts:107-109` | PUT 接口同样修复 |
| 前端增加配置入口 | `frontend/src/pages/Money.tsx` 或 `Settings.tsx` | 增加加班费倍率配置 UI |

---

### 2.12 考勤企微对接（#15）

**现状**：无企微对接

**需求**：评估对接企业微信考勤数据的可行性

**方案**：后期规划，需企微 API 文档调研。企微提供考勤数据接口 `checkin/getcheckindata`，可定时拉取同步到系统

---

### 2.13 电子签对接（#16）

**现状**：合同记录有 `signMethod` 字段（PAPER/ELECTRONIC），`ContractInfo.tsx` 表单已支持选择签署方式并填写电子合同编号/链接

**需求**：评估对接电子签平台（如法大大/上上签）的可行性

**方案**：后期规划，需第三方平台 API 调研。当前可先完善手动录入电子合同信息的流程

---

### 2.14 文本模板补充（#17）

**根因分析**：

- `template.service.ts:15-249` — 硬编码模板数组 `documentTemplates`
- 已有模板：固定期限劳动合同、无固定期限劳动合同、**协商解除劳动合同协议书**（`tpl_termination_agreement`）、员工手册公示通知、规章制度讨论通知、违纪处分通知书、试用期转正通知书、合同到期不续签通知书
- **缺少**：员工主动提出离职的解除协议书模板

**修复方案**：

| 改动 | 文件 | 具体内容 |
|------|------|---------|
| 新增模板 | `backend/src/services/template.service.ts` | 在 `documentTemplates` 数组中新增 `tpl_voluntary_termination_agreement`（员工提出离职版解除协议） |

**模板内容要点**：
- 乙方主动提出离职，甲方同意
- 无经济补偿金（员工主动辞职，法定无需支付）
- 工作交接条款
- 社保公积金截止月份
- 竞业限制延续条款（如有）
- 变量：`companyName, employeeName, idCard, resignDate, lastWorkDay, socialInsEndMonth, housingFundEndMonth, resignReason`

---

## 三、实施优先级建议

### Phase 1 — 紧急修复（阻塞客户使用）

| 序号 | 任务 | 根因 | 预估工作量 |
|------|------|------|-----------|
| 1 | 社保城市选择改为可输入 | 城市下拉限制了已有城市 | 0.5 天 |
| 2 | 社保上下限拆分（三险/医保） | Schema 单一 baseMin/baseMax | 1 天 |
| 3 | 预置河北省社保政策 | 无河北数据 | 0.5 天 |
| 4 | 公积金试算结果展示修复 | 公积金返回无 items 数组，复用社保表格渲染报错 | 0.5 天 |
| 5 | 花名册合同保存修复 | 前端提交 YYYY-MM-DD 未转 ISO datetime | 0.5 天 |
| 6 | 薪酬批次创建失败修复 | calcBatchEntry 缺城市过滤 + 错误处理不足 | 0.5 天 |
| 7 | 证据链查看修复 | 需确认 Tab 定义 + 空数据提示 | 0.5 天 |
| 8 | 个税计算排查 | 确认导入后是否触发重算 | 0.5 天 |

### Phase 2 — 功能完善

| 序号 | 任务 | 预估工作量 |
|------|------|-----------|
| 9 | 批量导入 Bug 修复 + 导入按钮 | 0.5 天 |
| 10 | 单人发薪 UI 入口优化 | 0.5 天 |
| 11 | 工资表导入功能 | 1 天 |
| 12 | 大病险/长护险单独险种模块 | 1 天 |
| 13 | 专项附加扣除按月录入 | 0.5 天 |
| 14 | 加班费倍率读取配置（后端已有模型，改计算逻辑） | 0.5 天 |
| 15 | 解除协议模板补充（员工提出离职版） | 0.5 天 |

### Phase 3 — 后期规划

| 序号 | 任务 | 说明 |
|------|------|------|
| 16 | 企微考勤对接 | 需 API 调研 |
| 17 | 电子签平台对接 | 需第三方平台选型 |

---

## 四、技术要点

### 4.1 社保上下限拆分方案

```prisma
// schema.prisma — SocialInsuranceConfig 新增字段
model SocialInsuranceConfig {
  // ... 现有字段 ...
  baseMin          Float    @default(6326)  // 三险基数下限（养老/失业/工伤）
  baseMax          Float    @default(33891) // 三险基数上限
  medicalBaseMin   Float    @default(0)     // 医保基数下限（0 = fallback 到 baseMin）
  medicalBaseMax   Float    @default(0)     // 医保基数上限（0 = fallback 到 baseMax）
  extraInsurances  String?  // JSON: [{ name, type: 'fixed'|'rate', orgRate, empRate, orgAmount, empAmount }]
}
```

```ts
// payroll.service.ts — calcSocialInsurance 适配
export function calcSocialInsurance(base: number, config: any) {
  const pensionBase = Math.min(Math.max(base, config.baseMin), config.baseMax)
  const medicalBase = Math.min(
    Math.max(base, config.medicalBaseMin || config.baseMin),
    config.medicalBaseMax || config.baseMax
  )
  // 三险用 pensionBase，医保用 medicalBase
  const socialEmp = pensionBase * (config.pensionEmp + config.unemploymentEmp) / 100
    + medicalBase * (config.medicalEmp) / 100
  const socialOrg = pensionBase * (config.pensionOrg + config.unemploymentOrg + config.injuryOrg) / 100
    + medicalBase * (config.medicalOrg + config.maternityOrg) / 100
  return { actualBase: pensionBase, socialEmp, socialOrg }
}
```

### 4.2 合同日期格式修复

```ts
// ContractInfo.tsx — 提交前转换日期格式
const handleSubmit = () => {
  const data = {
    ...formData,
    signDate: form.signDate ? new Date(form.signDate).toISOString() : null,
    startDate: new Date(form.startDate).toISOString(),
    endDate: form.endDate ? new Date(form.endDate).toISOString() : null,
  }
  addContractMutation.mutate(data)
}
```

### 4.3 公积金试算结果展示修复

```tsx
// SocialInsurance.tsx — 公积金试算结果单独渲染
{isHousing && r ? (
  <div className="space-y-2">
    <div className="flex justify-between text-sm">
      <span>缴费基数</span><span className="font-medium">¥{fmt(r.actualBase)}</span>
    </div>
    <div className="flex justify-between text-sm">
      <span>企业缴纳 ({r.housingOrg ? '' : ''})</span>
      <span className="text-danger">¥{fmt(r.housingOrg)}</span>
    </div>
    <div className="flex justify-between text-sm">
      <span>个人缴纳</span>
      <span className="text-warning">¥{fmt(r.housingEmp)}</span>
    </div>
    <div className="flex justify-between text-sm border-t pt-2 font-medium">
      <span>合计</span><span className="text-primary">¥{fmt(r.total)}</span>
    </div>
  </div>
) : !isHousing && r ? (
  // 社保试算结果保持原有 items 表格渲染
  ...
) : ...}
```

### 4.4 加班费倍率读取配置

```ts
// payroll.routes.ts — 保存加班费记录时读取 OvertimeConfig
router.post('/overtime', async (req, res, next) => {
  const data = overtimeSchema.parse(req.body)
  let config = await prisma.overtimeConfig.findUnique({ where: { orgId: req.user!.orgId } })
  if (!config) config = { weekdayRate: 1.5, weekendRate: 2.0, holidayRate: 3.0, monthlyDays: 21.75, dailyHours: 8 } as any
  const hourlyWage = data.monthlyWage / config.monthlyDays / config.dailyHours
  const weekdayPay = hourlyWage * config.weekdayRate * data.weekdayHours
  const weekendPay = hourlyWage * config.weekendRate * data.weekendHours
  const holidayPay = hourlyWage * config.holidayRate * data.holidayHours
  // ...
})
```

### 4.5 个税计算链路

```
创建/编辑批次条目 → calcBatchEntry()
  → 查社保配置（orgId + month，需加 city 过滤）
  → 查公积金配置（同上）
  → 累计预扣法：
     ytdIncome = 历史工资条 totalPay 之和 + 本月 totalPay
     ytdDeductions = 5000 * 月份 + ytdSocialEmp + ytdHousingEmp + ytdSpecialDeduction
     ytdTaxableIncome = max(0, ytdIncome - ytdDeductions)
     tax = calcCumulativeTax(ytdTaxableIncome, ytdTaxDeducted)
  → 返回 { tax, netPay, socialEmp, socialOrg, housingEmp, housingOrg }
```

**个税为 0 的条件**：`ytdTaxableIncome ≤ 0`，即累计收入 ≤ 累计减除费用（5000×月份数 + 累计社保 + 累计公积金 + 累计专项附加扣除）

### 4.6 证据链 API 链路

```
前端 EvidenceChain.tsx
  → useQuery(['evidence-chain', employeeId])
  → api.get('/roster/${employeeId}/evidence-chain')
  → 后端 roster.routes.ts:240
     → prisma.employee.findFirst({ include: { contracts, payslips, overtimeRecords, ... } })
     → 组装 evidence[]（劳动关系/薪酬发放/考勤记录/违纪处理/培训签收/绩效考核/解聘记录）
     → 风险检测 risks[]（未签合同/合同到期/工资异常/无考勤记录等）
     → 返回 { employee, evidence, risks, summary: { total, signed, unsigned, riskCount } }
```

---

## 五、实施进度追踪（2026-07-27 更新）

### Phase 1 — 紧急修复（全部完成 ✅）

| 序号 | 任务 | 状态 | 修改文件 | 实施内容 |
|------|------|------|---------|---------|
| 1 | 社保城市选择改为可输入 | ✅ 已完成 | `SocialInsurance.tsx` | 城市下拉改为 `<input list>` + `<datalist>`，支持手动输入 |
| 2 | 社保上下限拆分（三险/医保） | ✅ 已完成 | `schema.prisma` `social.routes.ts` `payroll.service.ts` `SocialInsurance.tsx` | Schema 新增 `medicalBaseMin/medicalBaseMax`；`calcSocialInsurance()` 和 `calcSocialDetail()` 医保使用独立基数（为 0 时 fallback）；试算接口适配；前端新建版本表单增加医保上下限输入；配置展示区显示医保上下限 |
| 3 | 公积金试算结果展示修复 | ✅ 已完成 | `SocialInsurance.tsx` | 公积金试算结果单独渲染（企业/个人缴纳金额），不再复用社保 `items.map()` |
| 4 | 花名册合同保存修复 | ✅ 已完成 | `ContractInfo.tsx` | 提交前将日期转为 ISO 格式 `new Date(form.signDate).toISOString()` |
| 5 | 薪酬批次创建失败修复 | ✅ 已完成 | `payroll.service.ts` `payroll2.routes.ts` | `calcBatchEntry` 查社保/公积金配置加 `city` 过滤；单员工计算 try-catch 不阻塞整批；返回 `failedEmployees` 详情 |
| 6 | 证据链查看修复 | ✅ 已完成 | `shared.ts` `EmployeeProfile.tsx` `EvidenceChain.tsx` | 添加 evidence Tab 到 `TAB_GROUPS`；`EmployeeProfile` 渲染 `EvidenceChain` 组件；空数据友好提示 |
| 7 | 个税计算排查修复 | ✅ 已完成 | `payroll2.routes.ts` | `blank_employees` 模式下从员工记录获取基本工资，避免 `baseSalary=0` 导致个税为 0 |
| 8 | 加班费倍率读取配置 | ✅ 已完成 | `payroll.routes.ts` | 从 `OvertimeConfig` 读取倍率，fallback 到 1.5/2.0/3.0 |

### Phase 2 — 功能完善（全部完成 ✅）

| 序号 | 任务 | 状态 | 修改文件 | 实施内容 |
|------|------|------|---------|---------|
| 9 | 批量导入 Bug 修复 + 导入按钮 | ✅ 已完成 | `import.routes.ts` `Roster.tsx` | 加班/违纪/考勤导入添加 per-row try-catch；Roster 页面添加「批量导入」按钮入口 |
| 10 | 单人发薪 UI 入口优化 | ✅ 已完成 | `Roster.tsx` | 操作列添加「发薪」按钮（Wallet 图标），跳转薪税管理页面 |
| 11 | 解除协议模板补充 | ✅ 已完成 | `template.service.ts` | 新增 `tpl_termination_agreement_employee`（员工主动提出离职版），含离职原因/无补偿金/竞业限制等条款 |

### Phase 3 — 后期规划（部分完成）

| 序号 | 任务 | 状态 | 修改文件 | 实施内容 |
|------|------|------|---------|---------|
| 12 | 工资表导入功能 | ✅ 已完成 | `import.routes.ts` `Money.tsx` | 新增 `POST /import/payroll` 接口，解析 Excel 工资表批量更新批次条目（基本工资/加班费/津贴/扣款/奖金），自动重算税费；前端批次详情页添加「导入工资表」按钮 + 模板下载 + 结果展示 |
| 13 | 大病险/长护险单独险种模块 | ✅ 已完成 | `schema.prisma` `social.routes.ts` `payroll.service.ts` `SocialInsurance.tsx` | Schema 新增 `extraInsurances` JSON 字段；`calcSocialInsurance()` 和 `calcSocialDetail()` 支持附加险种计算（按养老基数/医保基数/固定金额三种方式）；试算接口返回附加险种明细；前端新建版本表单增加附加险种动态配置区（添加/删除险种行） |
| 14 | 专项附加扣除按月录入 | ✅ 已完成 | `schema.prisma` `social.routes.ts` `SocialInsurance.tsx` | 新建 `SpecialDeductionRecord` 模型（子女教育/赡养老人/住房/继续教育/婴幼儿照护五项分项）；后端 CRUD + 批量录入 API；前端新增「专项附加扣除」Tab，支持按月查看/编辑/新增，自动计算合计并同步员工便捷字段 |
| 15 | 预置河北省社保政策 | ✅ 已完成 | `seed.ts` | 添加河北省石家庄市社保配置（养老16/8、医疗8/2、失业0.7/0.3、工伤0.3、生育0.5，基数3920~19602）+ 大病医疗(固定5元) + 长期护理险(0.1%)；公积金配置（12%/12%） |

### 待实施

| 序号 | 任务 | 说明 |
|------|------|------|
| 16 | 企微考勤对接 | 需 API 调研 |
| 17 | 电子签平台对接 | 需第三方平台选型 |

### 技术备注

- **Prisma migration**：`medicalBaseMin`/`medicalBaseMax`、`extraInsurances`、`SpecialDeductionRecord` 已通过 `prisma db push` 同步到数据库
- **向后兼容**：医保独立上下限为 0 时自动 fallback 到 `baseMin/baseMax`；`extraInsurances` 为 null 时不影响现有计算
- **附加险种计算方式**：`baseType: 'pension'` 按养老基数 × 比例，`baseType: 'medical'` 按医保基数 × 比例，`baseType: 'fixed'` 按固定金额
- **专项附加扣除**：录入后自动同步 `employee.specialDeduction` 便捷字段，个税计算时直接使用
- **解除协议模板**：原 `tpl_termination_agreement` 描述更新为「用人单位提出」，新增 `tpl_termination_agreement_employee` 为「员工主动提出离职」版