docs: 优化计划补充第五批电子签署任务（TASK-031~042）

新增12项电子签署优化任务：
- P0：后端路由重写+模板渲染、验证码确认、证据链体系
- P1：回写合同、组织开关校验、线下手签、花名册联动、转正联动
- P2：scene模板填充、管理端UI、员工端UI

更新执行状态总览（31→43条）、批次总览、依赖关系图、风险注意事项

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

20260815-优化计划.md

@@ -6,7 +6,7 @@
 
 ---
 
-## 执行状态总览（2026-08-15 更新）
+## 执行状态总览（2026-08-16 更新）
 
 | 批次 | 优先级 | 任务数 | 完成数 | 状态 |
 |------|--------|--------|--------|------|
@@ -14,11 +14,13 @@
 | 第二批 | P1 高 | 14 条 | 14 条 | ✅ 全部完成 |
 | 第三批 | P2 中 | 9 条 | 9 条 | ✅ 全部完成 |
 | 第四批 | P3 规划 | 2 项 | 2 项 | ✅ 全部完成 |
-| **合计** | | **31 条** | **31 条** | **✅ 100% 完成** |
+| 第五批 | 电子签署 | 12 条 | 12 条 | ✅ 全部完成（2026-08-16 新增） |
+| **合计** | | **43 条** | **43 条** | **✅ 100% 完成** |
 
 > 编译状态：前后端 TypeScript 编译均 0 错误。
-> 数据库：Prisma schema 已同步（`prisma db push`），新增 8 个模型 + 2 个字段 + 1 个枚举值。
+> 数据库：Prisma schema 已同步（`prisma db push`），新增 8 个模型 + 2 个字段 + 1 个枚举值 + ESignRecord 扩展 7 个字段。
 > 复查状态（2026-08-15）：TASK-024/025/026/027 验收标准已全部修复。
+> 电子签署批次（2026-08-16）：TASK-031~042 全部完成，覆盖电子签署完整流程、线下手签、证据链体系、花名册操作联动。
 
 ---
 
@@ -30,6 +32,7 @@
 | 第二批 | P1 高 | 14 条 | 流程阻塞/合规校验缺失修复 | 第一批完成 |
 | 第三批 | P2 中 | 9 条 | 体验优化/功能增强 | 第二批完成（26 依赖 18/20/21/22/23） |
 | 第四批 | P3 规划 | 2 项 | 组织架构+审批流 / 客服工作台增强 | 第三批完成 |
+| 第五批 | 电子签署 | 12 条 | 电子签署完整流程+线下手签+证据链+花名册联动 | 无（独立批次） |
 
 ---
 
@@ -698,6 +701,256 @@
 
 ---
 
+## 第五批：电子签署完整流程 + 线下手签 + 证据链体系（2026-08-16 新增）
+
+> 背景：原系统电子签署模块存在两套并行且互不连通的签署机制、无实际签署流程、无证据链集成、无验证码确认、无线下手签支持等问题。本批次系统性重构电子签署模块，建立完整的法律证据链体系。
+
+### TASK-031：电子签署后端路由重写 + 模板自动渲染（P0）
+
+- **目标**：重写 esign.routes.ts，支持完整的电子签署发起流程，自动从模板渲染文件内容
+- **对应需求**：电子签署逻辑审计 P0-1/P1-1
+- **验收标准**：
+  - [x] 发起签署时校验组织电子签开关（POLICY/PAYSLIP/ONBOARDING）
+  - [x] 自动从模板渲染文件内容（CONTRACT→劳动合同模板，RESIGNATION→离职协议模板）
+  - [x] 创建签署记录时自动创建证据链（发起签署事件）
+  - [x] 新增签署详情接口、证据链查看接口
+  - [x] 取消签署追加证据链事件
+  - [x] 签署状态查询自动处理过期记录
+- **依赖**：无
+- **优先级**：P0
+- **阶段**：第五批
+- **涉及文件**：
+  - `backend/src/routes/esign.routes.ts`（重写）
+  - `backend/src/services/template.service.ts`（renderTemplate/getTemplateById 集成）
+  - `backend/src/services/evidence.service.ts`（createEvidence 集成）
+- **测试要求**：
+  - 手工验证：发起劳动合同签署 → 自动渲染模板内容 → 创建证据链 → 详情页可查看
+
+### TASK-032：员工端签署验证码确认机制（P0）
+
+- **目标**：员工端签署增加手机验证码确认，确保签署行为真实性
+- **对应需求**：电子签署逻辑审计 P0-1
+- **验收标准**：
+  - [x] 员工端新增验证码发送接口（/esign/:id/send-code）
+  - [x] 签署操作增加验证码校验（5次错误限制 + 60秒限流）
+  - [x] 签署完成追加证据链（IP/UA/时间戳/验证码/签署人）
+  - [x] 签署完成回写合同 signMethod + attachmentName（签署证据）
+  - [x] 列表和详情接口自动处理过期记录
+- **依赖**：TASK-031
+- **优先级**：P0
+- **阶段**：第五批
+- **涉及文件**：
+  - `backend/src/routes/portal.routes.ts`（员工端 esign 重写）
+  - `backend/src/services/codeStore.ts`（setCode/getCode/checkRateLimit）
+- **测试要求**：
+  - 手工验证：员工查看待签文件 → 获取验证码 → 输入验证码 → 签署完成 → 证据链记录
+
+### TASK-033：签署全流程证据链体系（P0）
+
+- **目标**：签署全流程（发起/验证码发送/签署完成/取消）自动记录证据链，确保法律效力
+- **对应需求**：电子签署逻辑审计 P0-2
+- **验收标准**：
+  - [x] 发起签署时创建证据链（事件1：发起签署）
+  - [x] 发送验证码时追加证据链（事件2：验证码发送）
+  - [x] 签署完成时追加证据链（事件3：签署完成，含IP/UA/时间戳/验证码/签署人）
+  - [x] 取消签署时追加证据链（事件4：取消签署）
+  - [x] 证据链包含 hash 值用于完整性校验
+  - [x] 管理端详情页可查看完整证据链时间线
+- **依赖**：TASK-031、TASK-032
+- **优先级**：P0
+- **阶段**：第五批
+- **涉及文件**：
+  - `backend/src/routes/esign.routes.ts`（发起/取消证据链）
+  - `backend/src/routes/portal.routes.ts`（验证码/签署完成证据链）
+  - `backend/src/services/evidence.service.ts`（createEvidence/appendEvidence）
+- **测试要求**：
+  - 手工验证：完整签署流程 → 详情页证据链显示3-4个事件 → 含时间戳/IP/操作人
+
+### TASK-034：签署完成回写合同 + 生成签署证据（P1）
+
+- **目标**：签署完成后自动回写合同签署方式，生成签署证据文件
+- **对应需求**：电子签署逻辑审计 P1-3
+- **验收标准**：
+  - [x] 签署完成回写合同 signMethod=ELECTRONIC
+  - [x] 回写合同 attachmentName（含IP/UA/时间戳证据摘要）
+  - [x] 签署证据写入 callbackData
+  - [x] 对接易签宝后自动回写 signedPdfUrl（预留接口）
+- **依赖**：TASK-032
+- **优先级**：P1
+- **阶段**：第五批
+- **涉及文件**：
+  - `backend/src/routes/portal.routes.ts`（签署完成回写逻辑）
+- **测试要求**：
+  - 手工验证：劳动合同签署完成 → 合同 signMethod 变为 ELECTRONIC → attachmentName 包含证据摘要
+
+### TASK-035：组织电子签开关校验（P1）
+
+- **目标**：发起签署前校验组织级别的电子签开关，未开启的场景不允许发起
+- **对应需求**：电子签署逻辑审计 P1-2
+- **验收标准**：
+  - [x] 发起签署前校验 SCENE_ORG_FLAG_MAP 对应的组织开关
+  - [x] CONTRACT/RESIGNATION 场景默认允许（不依赖开关）
+  - [x] POLICY/PAYSLIP/ONBOARDING 场景需对应开关开启
+  - [x] 开关未开启时返回明确错误提示
+- **依赖**：TASK-031
+- **优先级**：P1
+- **阶段**：第五批
+- **涉及文件**：
+  - `backend/src/routes/esign.routes.ts`（开关校验逻辑）
+- **测试要求**：
+  - 手工验证：组织未开启 POLICY 开关 → 发起规章制度签署 → 返回错误提示
+
+### TASK-036：scene 关联模板自动填充 + 过期自动处理（P2）
+
+- **目标**：签署场景与模板自动关联，过期记录自动标记
+- **对应需求**：电子签署逻辑审计 P2-1
+- **验收标准**：
+  - [x] SCENE_TEMPLATE_MAP 映射（CONTRACT→劳动合同，RESIGNATION→离职协议）
+  - [x] 前端场景选择后自动填充默认文件标题
+  - [x] 列表/详情/状态查询时自动将过期 PENDING 标记为 EXPIRED
+  - [x] 过期时间默认30天
+- **依赖**：TASK-031
+- **优先级**：P2
+- **阶段**：第五批
+- **涉及文件**：
+  - `backend/src/services/esign.service.ts`（SCENE_TEMPLATE_MAP）
+  - `backend/src/routes/esign.routes.ts`（过期处理）
+  - `backend/src/routes/portal.routes.ts`（员工端过期处理）
+  - `frontend/src/pages/ESign.tsx`（场景选择自动填充）
+- **测试要求**：
+  - 手工验证：选择"劳动合同"场景 → 文件标题自动填充 → 创建记录 → 30天后自动标记过期
+
+### TASK-037：前端管理端发起签署 UI 增强（P2）
+
+- **目标**：管理端 ESign 页面增加场景选择、模板预览、证据链查看
+- **对应需求**：电子签署逻辑审计 P2-2
+- **验收标准**：
+  - [x] 发起签署增加场景选择（5种场景：劳动合同/离职协议/规章制度/工资条/入职文件）
+  - [x] 场景选择后自动填充默认文件标题
+  - [x] 新增签署详情页（文件内容预览 + 证据链时间线）
+  - [x] 签署流程说明（6步流程图）
+  - [x] 签署记录列表增加签署方式列
+- **依赖**：TASK-031
+- **优先级**：P2
+- **阶段**：第五批
+- **涉及文件**：
+  - `frontend/src/pages/ESign.tsx`（重写）
+  - `frontend/src/lib/api-services.ts`（esignApi 增加 detail/evidence 接口）
+- **测试要求**：
+  - 手工验证：发起签署 → 选择场景 → 自动填充标题 → 创建 → 详情页查看文件内容和证据链
+
+### TASK-038：前端员工端签署 UI 增强（P2）
+
+- **目标**：员工端 MyEsign 增加验证码签署流程和文件预览
+- **对应需求**：电子签署逻辑审计 P2-3
+- **验收标准**：
+  - [x] 签署操作增加验证码确认流程
+  - [x] 60秒倒计时限制
+  - [x] 文件内容预览
+  - [x] 签署完成状态展示
+  - [x] 开发模式直接显示验证码（便于测试）
+- **依赖**：TASK-032
+- **优先级**：P2
+- **阶段**：第五批
+- **涉及文件**：
+  - `frontend/src/pages/portal/MyEsign.tsx`（重写）
+  - `frontend/src/lib/api-services.ts`（portalApi 增加 esignSendCode 接口）
+- **测试要求**：
+  - 手工验证：员工端查看待签文件 → 点击获取验证码 → 输入验证码 → 签署完成
+
+### TASK-039：线下手签完整流程 + 证据链（P1）
+
+- **目标**：支持线下手签的完整登记流程，上传扫描件，记录证据链，与电子签署具有同等证据效力
+- **对应需求**：线下手签支持
+- **验收标准**：
+  - [x] ESignRecord 增加 signMethod 字段（ELECTRONIC/PAPER）
+  - [x] 增加线下手签专用字段：signedAt、signedLocation、witnessName、witnessPhone、scanFileUrls
+  - [x] 后端新增线下手签登记接口（POST /esign/paper-sign）
+  - [x] 后端新增扫描件上传接口（POST /esign/paper-upload，multer多文件）
+  - [x] 线下手签登记创建 COMPLETED 状态记录 + 证据链 + 回写合同
+  - [x] 管理端 ESign 页面增加"线下手签登记"按钮和 Modal
+  - [x] 员工端线下手签记录只读展示（含扫描件链接）
+- **依赖**：无
+- **优先级**：P1
+- **阶段**：第五批
+- **涉及文件**：
+  - `backend/prisma/schema.prisma`（ESignRecord 扩展7个字段）
+  - `backend/src/routes/esign.routes.ts`（线下手签接口）
+  - `frontend/src/pages/ESign.tsx`（线下手签登记 Modal）
+  - `frontend/src/pages/portal/MyEsign.tsx`（线下手签只读展示）
+  - `frontend/src/lib/api-services.ts`（uploadPaperSign/paperSign 接口）
+- **DB 变更**：ESignRecord 新增 signMethod + 6个线下手签字段，`prisma db push` 已应用
+- **测试要求**：
+  - 手工验证：HR点击"线下手签登记" → 选择员工 → 填写签署日期/地点/见证人 → 上传扫描件 → 登记 → 证据链记录 → 员工端可查看扫描件
+
+### TASK-040：花名册操作自动创建电子签署（P1）
+
+- **目标**：花名册关键操作（增加员工/主动离职/公司解聘）自动创建电子签署记录
+- **对应需求**：花名册与电子签署联动
+- **验收标准**：
+  - [x] 新增 esign.service.ts 提供 autoCreateEsignRecord 公共方法
+  - [x] 主动离职（createDraft type=RESIGNATION）自动创建离职协议签署
+  - [x] 公司解聘执行完成（executeTermination type=TERMINATION）自动创建离职协议签署
+  - [x] 自动创建失败不阻断主流程（返回 null）
+  - [x] 前端操作成功后提示"电子签署已自动发起"
+- **依赖**：TASK-031
+- **优先级**：P1
+- **阶段**：第五批
+- **涉及文件**：
+  - `backend/src/services/esign.service.ts`（新增）
+  - `backend/src/services/termination.service.ts`（createDraft/executeTermination 集成）
+- **测试要求**：
+  - 手工验证：花名册主动离职 → 创建离职草稿 → 自动创建离职协议签署记录 → 员工端可见
+
+### TASK-041：通用签署方式选择弹窗 + 花名册4项操作联动（P1）
+
+- **目标**：花名册操作（重新入职/合同续签/薪酬变更/调岗调动）成功后弹窗选择签署方式
+- **对应需求**：花名册与电子签署联动（用户选择签署方式）
+- **验收标准**：
+  - [x] 新增 SignMethodChoice 通用组件（电子签/线下手签/稍后处理三选一）
+  - [x] 重新入职：操作成功后弹窗（scene=CONTRACT，劳动合同）
+  - [x] 合同续签：操作成功后弹窗（scene=CONTRACT，续签劳动合同）
+  - [x] 薪酬变更：操作成功后弹窗（scene=POLICY，薪酬调整确认书）
+  - [x] 调岗调动：操作成功后弹窗（scene=POLICY，调岗确认书）
+  - [x] 选择"电子签"→自动创建签署记录
+  - [x] 选择"线下手签"→跳转签署页面，预填信息
+  - [x] 选择"稍后处理"→跳过，可后续手动发起
+  - [x] ESign 页面支持 URL 参数自动打开线下手签登记
+- **依赖**：TASK-039
+- **优先级**：P1
+- **阶段**：第五批
+- **涉及文件**：
+  - `frontend/src/components/ui/SignMethodChoice.tsx`（新增）
+  - `frontend/src/pages/Roster.tsx`（4个 mutation onSuccess 集成）
+  - `frontend/src/pages/ESign.tsx`（URL 参数读取 + PaperSignModal 预填）
+- **测试要求**：
+  - 手工验证：花名册薪酬变更 → 成功 → 弹窗选择"电子签" → 自动创建签署记录
+  - 手工验证：花名册调岗 → 成功 → 弹窗选择"线下手签" → 跳转签署页面 → 信息已预填
+
+### TASK-042：转正弹窗显示原薪资 + 薪资变化联动签署（P1）
+
+- **目标**：转正弹窗显示原薪资，薪资变化时自动发起薪酬调整确认书签署
+- **对应需求**：转正流程与电子签署联动
+- **验收标准**：
+  - [x] ConfirmModal 标签显示原薪资（¥xxx）
+  - [x] 转正薪资默认填入原薪资
+  - [x] 薪资变化时提示"将发起薪酬调整确认书签署"
+  - [x] 转正成功后薪资有变化时弹出签署方式选择
+  - [x] 签署文件标题为"转正薪酬调整确认书"
+  - [x] 备注记录薪资变化：¥原薪资 → ¥新薪资
+  - [x] 薪资未变化时仅显示"转正已提交"，不弹窗
+- **依赖**：TASK-041
+- **优先级**：P1
+- **阶段**：第五批
+- **涉及文件**：
+  - `frontend/src/pages/roster/modals.tsx`（ConfirmModal 增强）
+  - `frontend/src/pages/Roster.tsx`（confirmMutation onSuccess 联动）
+- **测试要求**：
+  - 手工验证：试用期薪资 ¥8000 → 转正填写 ¥10000 → 提示将发起签署 → 转正成功 → 弹窗选择签署方式
+  - 手工验证：试用期薪资 ¥8000 → 转正不修改 → 提交 → 仅显示"转正已提交"
+
+---
+
 ## 任务依赖关系图
 
 ```
@@ -730,6 +983,14 @@ TASK-028（去掉用工办理）← TASK-016, TASK-018, TASK-024, TASK-025
 第四批（P3）：
 TASK-029（组织架构+审批流） 独立
 TASK-030（客服工作台）     独立
+
+第五批（电子签署，2026-08-16 新增）：
+TASK-031（后端路由重写+模板渲染）─┬─→ TASK-032（验证码确认）─→ TASK-033（证据链体系）
+                                ├─→ TASK-035（组织开关校验）
+                                ├─→ TASK-036（scene模板+过期处理）─→ TASK-037（管理端UI）
+                                └─→ TASK-040（花名册自动创建）
+TASK-032 ─→ TASK-034（回写合同）─→ TASK-038（员工端UI）
+TASK-039（线下手签）─→ TASK-041（签署方式选择弹窗）─→ TASK-042（转正联动）
 ```
 
 ---
@@ -771,3 +1032,7 @@ TASK-030（客服工作台）     独立
 5. **审批流复杂度**：TASK-029 是新模块，建议先做 MVP（部门树+直属上级审批），再逐步扩展。
 6. **客服端复杂度**：TASK-030 是新模块，建议先做工单+数据穿透，再做会话和 AI。
 7. **历史脏数据**：TASK-005（合同日期倒置）、TASK-019（男职工三期）可能存在历史脏数据，提供查询列表但不自动修复。
+8. **电子签署法律效力**：TASK-031~038 的电子签署证据链需配合易签宝等第三方CA机构才能生成具有完全法律效力的电子签名，当前系统记录的证据链（IP/UA/时间戳/验证码）可作为初步举证材料。
+9. **线下手签扫描件存储**：TASK-039 的扫描件存储在服务器本地 `uploads/paper-sign/` 目录，生产环境建议配置对象存储（OSS/S3）并定期备份。
+10. **验证码发送通道**：TASK-032 的验证码当前为开发模式（直接返回），生产环境需对接短信服务商（阿里云/腾讯云短信）。
+11. **花名册联动重复创建**：TASK-040/041 已修复 POST /contracts 与前端 ContractInfo 重复创建签署记录的问题，后端不再自动创建，由前端根据 signMethod 决定。