# 实施计划与验收

> 巴青平台密码改造分期计划、任务分解与验收标准。

---

## 1. 总体里程碑

| 阶段 | 周期（建议） | 目标 |
| --- | --- | --- |
| 一期 | 3～4 周 | 身份鉴别（UKey + 短信双因子）+ 密码模块骨架 + 密码机联调 |
| 二期 | 4～5 周 | 平台核心表（用户、权限、日志）SM3/SM4 改造 |
| 三期 | 6～8 周 | 业务表按映射表改造 + 存量迁移 |
| 四期 | 2～3 周 | 巡检告警、密钥轮换、等保测评配合 |

---

## 2. 一期：身份鉴别与密码框架

> **进度说明（互联网管理端）**：后端短信双因子、`ruoyi-crypto` Stub、阿里云短信 SDK、`login.auth-mode` 切换已落地；UKey 证书登录与前端改造仍待实施。

### 2.1 任务清单

| 序号 | 任务 | 产出 | 状态 |
| --- | --- | --- | --- |
| 1.1 | 采购/部署密码机、验签服务器联调环境 | 联调报告 | ⏳ |
| 1.2 | 新建 `ruoyi-crypto` 模块，`CryptoService` 封装 SM3/SM4 | 代码 + 单元测试（Stub） | ✅ |
| 1.3 | 对接签名验签服务器，`/login/cert` 接口 | 证书登录可用 | ⏳ |
| 1.4 | 短信双因子登录（互联网） | `/login/sms/send`、登录校验 | ✅ 后端 |
| 1.4a | 阿里云短信 SDK 集成 | `AliyunSmsGatewayClient` + `dry-run` | ✅ |
| 1.4b | 若依默认登录一键切换 | `login.auth-mode: ruoyi` | ✅ |
| 1.5 | `sys_user` 增加 `cert_sn`、`login_policy` 等字段 | `sql/crypto_phase1.sql` | ✅ 脚本已提供 |
| 1.6 | `sys_login_policy` 配置与文档 | 策略可配置 | ✅ |
| 1.7 | 安全审计：短信失败记 `sys_logininfor` | 日志可查 | ✅ |
| 1.8 | 前端：登录页短信双因子、`api/login.js` | 待前端改造（后端可先 API 联调） |

### 2.2 验收标准

- [ ] 内网管理员可使用国密 UKey 登录管理后台（待 1.3）
- [x] 互联网环境管理员须口令 + 短信验证码方可登录（后端，`auth-mode=sms-2fa`）
- [x] 验证码错误有明确提示且不泄露内部信息
- [x] 可通过 `login.auth-mode: ruoyi` 恢复若依默认登录
- [ ] 密码机 SM3/SM4 单次调用成功率 ≥ 99.9%（生产 HSM 联调后压测）
- [x] `ruoyi-crypto` Stub 无硬编码主密钥

---

## 3. 二期：平台核心数据保护

### 3.1 任务清单

| 序号 | 任务 | 产出 |
| --- | --- | --- |
| 2.1 | 执行用户/权限/日志表 DDL 扩展 | `sql/crypto_migration.sql` |
| 2.2 | 初始化 `sys_crypto_field_config` | 平台表配置数据 |
| 2.3 | MyBatis 加解密拦截器上线 | 用户手机、邮箱 SM4 |
| 2.4 | `sys_user` / `sys_role` / `sys_user_role` / `sys_role_menu` 行级 HMAC | 写后生成、读时校验 |
| 2.5 | `sys_oper_log` / `sys_logininfor` 写入后异步 HMAC | 防篡改 |
| 2.6 | `sys_security_alert` + 告警通知 | 篡改可感知 |
| 2.7 | 口令存储方案定稿并实施 | 与测评口径一致 |
| 2.8 | 前端：`request.js` 完整性错误处理；用户管理证书绑定 | 待前端改造 |

### 3.2 验收标准

- [ ] 库中 `phonenumber` 等为密文，应用层展示正常
- [ ] 手工篡改 `sys_user_role` 后，用户登录或权限加载触发告警并阻断
- [ ] 手工篡改 `sys_oper_log.integrity_hmac` 后，读日志触发告警
- [ ] 个人信息、权限、日志类数据 HMAC 覆盖率 100%（映射表范围内）
- [ ] 密码机调用有 `sys_crypto_audit_log` 记录

---

## 4. 三期：业务数据与存量迁移

### 4.1 任务清单

| 序号 | 任务 | 产出 |
| --- | --- | --- |
| 3.1 | 扫描全部 `biz_*` 表，补全映射表 | 更新映射表文档 |
| 3.2 | 分期改造：医疗资源、交易、养殖等 | 各模块 DDL + 配置 |
| 3.3 | 存量数据迁移 Job（分批、可暂停） | `CryptoMigrationJob` |
| 3.4 | 双写/校验期（明文列与密文列比对） | 迁移报告 |
| 3.5 | 下线明文列（验收后） | 变更记录 |

### 4.2 验收标准

- [ ] 映射表内业务敏感字段 SM4 存储
- [ ] 主要业务数据 HMAC 覆盖率 100%（映射表范围内）
- [ ] 存量数据迁移完成率 100%，抽样解密与原文一致
- [ ] 迁移过程业务可用（只读窗口有公告与回滚方案）

---

## 5. 四期：运营与测评

### 5.1 任务清单

| 序号 | 任务 | 产出 |
| --- | --- | --- |
| 4.1 | 定时完整性巡检 `CryptoIntegrityJob` | 巡检报告 |
| 4.2 | 安全告警处置流程（若依菜单 + 权限） | 运维手册 |
| 4.2a | 前端：安全告警管理页 `monitor/securityAlert` | 待前端改造 |
| 4.3 | 密钥轮换演练（`key_ver` 升级） | 演练记录 |
| 4.4 | 等保测评配合：演示 UKey、篡改告警 | 测评材料 |
| 4.5 | 性能优化（连接池、批量 HMAC） | 压测报告 |

### 5.2 验收标准

- [ ] 每日巡检执行成功，结果可查
- [ ] 密钥轮换后旧数据仍可校验（或已完成重算）
- [ ] 核心接口 P99 延迟增加 ≤ 50ms（相对改造前，视密码机性能调整）
- [ ] 等保相关检查项有文档与演示路径

---

## 6. 角色与分工（建议）

| 角色 | 职责 |
| --- | --- |
| 项目经理 | 里程碑、测评对接 |
| 安全架构 | 方案评审、密钥策略 |
| 后端开发 | ruoyi-crypto、登录、拦截器、迁移 Job |
| 前端开发 | 证书控件集成、短信登录 UI |
| 运维 | 密码机/验签服务器部署、监控 |
| 测试 | 功能、安全、性能、篡改用例 |

---

## 7. 测试用例要点

### 7.1 身份鉴别

| 用例 | 预期 |
| --- | --- |
| 有效 UKey 验签登录 | 成功获取 Token（待实施） |
| 过期/错误证书 | 401，记登录失败（待实施） |
| 互联网登录无短信码 | 拒绝登录（`auth-mode=sms-2fa` 时） |
| 错误短信码 | 拒绝登录，OTP 有效期内可重试 |
| `auth-mode=ruoyi` | 仅需账号+密码+图形验证码，与改造前一致 |
| `sms.aliyun.dry-run=true` | 验证码出现在日志 `【短信Stub】`，不调阿里云 |

### 7.2 完整性

| 用例 | 预期 |
| --- | --- |
| 正常读取用户手机 | 解密正确，校验通过 |
| DB 直接改 `phonenumber_cipher` | 读时告警，阻断或只读降级 |
| DB 直接改 `sys_role.role_key` | 权限加载告警 |
| 更新用户前旧 HMAC 被破坏 | 拒绝更新 |

### 7.3 密码机异常

| 用例 | 预期 |
| --- | --- |
| 密码机不可用 | 明确错误提示，不返回明文兜底（生产） |
| 主备切换 | 自动 failover，业务恢复 |

---

## 8. 风险与回滚

| 风险 | 缓解 |
| --- | --- |
| 密码机单点故障 | 双机 + 健康检查 |
| 迁移数据错误 | 双写期 + 抽样校验 + 保留明文列 |
| 性能下降 | 连接池、批量、热点缓存（慎用以安全评审为准） |
| 测评口径变更 | 一期前书面确认口令存储方案 |

**回滚**：`crypto.enabled=false` 仅允许在迁移双写期由运维开关；生产篡改保护开启后不建议关闭。

---

## 9. 交付物清单

| 交付物 | 路径/形式 | 状态 |
| --- | --- | --- |
| 技术方案 | `doc/密码改造/应用密码改造技术方案.md` | ✅ |
| 字段映射表 | `doc/密码改造/数据分类与字段加密映射表.md` | ✅ |
| DDL 草案 | `doc/密码改造/数据库改造DDL.md` | ✅ |
| 一期 DDL | `sql/crypto_phase1.sql` | ✅ |
| 配置与接口 | `doc/密码改造/配置与接口说明.md` | ✅ |
| 实施与验收 | 本文档 | ✅ |
| 代码模块 | `ruoyi-crypto`、`LoginSmsService` 等 | ✅ 一期后端 |
| 全量迁移 SQL | `sql/crypto_migration.sql` | ⏳ 二期 |