coal/IMPLEMENTATION_CHECKLIST.md

实施前检查清单

完成日期: 性能验证完成后
目标: 确保所有准备就绪，可以启动实施

---

✅ 已完成项

分析与验证阶段

• 识别权限系统的复杂性问题
• 分析原始 Java Stream 逻辑 (50+ 行)
• 设计 SQL 视图替代方案
• 创建 v_user_resources 视图
• 创建 v_user_permissions 视图
• 针对 4 种权限类型进行验证
• 对 3 种用户类型进行测试

性能验证阶段

• 执行 EXPLAIN ANALYZE (系统管理员)
• 执行 EXPLAIN ANALYZE (组织管理员)
• 对比原始 Java 多 JOIN 逻辑
• 验证执行计划效率 (Hashed SubPlans)
• 记录响应时间基准 (0.77-70 ms)
• 评估并发可扩展性
• 分析缓存友好性

文档与代码阶段

• 创建 PERMISSION_VIEWS.sql (完整 DDL)
• 创建 PERFORMANCE_ANALYSIS.md (性能报告)
• 创建 JAVA_SERVICE_IMPLEMENTATION.md (代码指南)
• 创建 NEXT_STEPS.md (行动计划)
• 创建 WORK_SUMMARY.md (工作总结)
• 提供 PermissionCacheService 完整代码
• 提供 UserService 修改方案
• 提供 CacheInvalidationService 架构

---

⏳ 待执行项

技术准备阶段 (1 天)

• 添加 Maven 依赖 (Redis, Micrometer)
• 配置 application.yaml (Redis 连接, 缓存 TTL)
• 验证 Redis 连接可用
• 设置 Micrometer 指标采集
• 验证本地开发环境 Redis 实例

编码实施阶段 (2 天)

• 创建 PermissionCacheService 类

  • getUserPermissions(userId) 方法
  • getUserResources(userId) 方法
  • getUserPermissionsBatch(userIds) 方法
  • getUserResourcesBatch(userIds) 方法

• 修改 UserService

  • resources(id) 修改为调用 permissionCacheService
  • permissions(id) 修改为调用 permissionCacheService
  • 删除旧的 Stream 逻辑 (50+ 行)

• 创建 CacheInvalidationService 类

  • invalidateUserPermissionCache(userId) 方法
  • invalidateAllPermissionCache() 方法
  • invalidateOrgPermissionCache(orgId) 方法
  • invalidateRolePermissionCache(roleId) 方法

• 修改 PermissionService

  • 替换 clearCache() 调用为 cacheInvalidationService.invalidateAllPermissionCache()
  • 在权限创建/更新/删除时调用新服务

• 修改 RoleService

  • 在角色权限变更时调用 invalidateRolePermissionCache()

测试阶段 (2 天)

• 单元测试

  • PermissionCacheService 测试 (100% 覆盖)
  • CacheInvalidationService 测试
  • 缓存命中/未命中场景测试

• 集成测试

  • 系统管理员权限查询测试
  • 组织管理员权限查询测试
  • 普通用户权限查询测试
  • 权限变更后缓存失效测试
  • 角色权限变更后缓存失效测试

• 性能测试

  • 建立 5 个典型用户的性能基准
  • 对比原始 vs 优化方案 (同一硬件环境)
  • 验证缓存命中率 (目标 > 85%)
  • 压力测试 (50 并发用户)

• 代码审查

  • peer review (至少 2 人)
  • 安全审查 (SQL 注入、权限校验)
  • 性能审查 (N+1 查询、缓存策略)

部署准备阶段 (1 天)

• 准备灰度发布计划

  • 测试环境全量部署脚本
  • 生产环境灰度部署脚本 (10%, 50%, 100%)

• 配置监控告警

  • Prometheus 指标导出 (权限查询时间、缓存命中率)
  • Grafana 仪表板 (实时监控)
  • 告警规则 (响应时间 > 200ms, 错误率 > 1%)

• 准备回滚方案

  • 备份原始 UserService 代码
  • 准备回滚 SQL (恢复旧的缓存逻辑)
  • 文档化回滚步骤 (< 5 分钟内完成)

• 更新文档

  • API 文档 (如适用)
  • 运维手册 (缓存管理、故障排查)
  • 变更日志 (CHANGELOG)

灰度发布阶段 (3 天)

Day 1: 测试环境全量验证

• 部署到测试环境
• 执行全套集成测试
  • 权限查询正确性 (100% 通过)
  • 缓存命中率 (> 80%)
  • 压力测试 (100 并发, 无错误)
• 检查监控指标
  • 响应时间: 0.77-70 ms ✓
  • 缓存命中率: > 80% ✓
  • 错误率: 0% ✓
• 签名确认: 可进入灰度

Day 2: 灰度 10% (生产环境)

• 部署到 10% 生产实例
• 启动实时监控 (刷新频率 < 5 分钟)
• 监控关键指标
  • 缓存命中率
  • p95 响应时间
  • 错误率
  • 用户反馈
• 持续 4 小时无异常后，升级到 50%
• 若有异常，立即回滚 (预计 < 5 分钟)

Day 3: 灰度 50% → 100%

• 升级到 50% 实例
• 继续监控 4 小时
• 无异常后升级到 100%
• 最终验证
  • 全部实例已部署
  • 所有指标正常
  • 用户反馈积极

---

📊 关键指标验证

性能指标 (必须满足)

指标	目标值	验证方法
p50 响应时间	< 70 ms	应用日志
p95 响应时间	< 100 ms	Prometheus
p99 响应时间	< 200 ms	Prometheus
缓存命中率	> 85%	Redis INFO
错误率	< 0.1%	应用日志

功能指标 (必须满足)

指标	目标值	验证方法
系统管理员权限	412 条	SQL 查询
组织管理员权限	369 条	SQL 查询
权限查询正确性	100%	单元测试
缓存失效准确性	100%	集成测试

资源指标 (监控)

指标	告警阈值	说明
数据库连接	> 20	权限查询并发连接
Redis 内存	> 500 MB	缓存容量检查
CPU 使用率	> 80%	数据库服务器
应用内存	> 1 GB	JVM 堆内存

---

🚨 风险控制

已识别的高风险项

• 权限逻辑错误 → 单元测试 + 集成测试覆盖
• 缓存不一致 → 完整的失效流程 + 监控告警
• 性能回退 → 基准对比 + 灰度验证

未来可能的风险

• Redis 不可用 → 需添加回源逻辑 (备用方案)
• 新权限类型支持 → 更新视图 + 添加测试
• 高并发场景 → 考虑物化视图或权限预加载

---

📋 部门协调

需要协调的部门

部门	事项	截止日期
基础设施	Redis 环境准备、Prometheus 配置	实施前 1 天
QA	测试用例评审、测试环境准备	实施前 1 天
运维	灰度部署脚本、监控告警配置	实施前 1 天
产品	灰度发布计划评审、用户沟通	实施前 3 天

---

✍️ 签字确认

技术负责人

• 确认设计方案合理
• 确认代码质量达标
• 确认性能验证通过
• 签名: _____________ 日期: _________

测试负责人

• 确认测试覆盖完整
• 确认所有测试用例通过
• 确认灰度测试计划可行
• 签名: _____________ 日期: _________

运维负责人

• 确认部署脚本可用
• 确认监控告警配置
• 确认回滚方案有效
• 签名: _____________ 日期: _________

项目经理

• 确认时间计划可行
• 确认风险评估完整
• 确认所有准备就绪
• 签名: _____________ 日期: _________

---

🎯 启动条件

所有以下条件满足时，可启动实施:

1. ✅ 所有技术准备完成 (Redis, Maven 依赖)
2. ✅ 所有涉及部门确认就绪
3. ✅ 性能基准已建立 (0.77-70 ms)
4. ✅ 灰度计划已评审
5. ✅ 回滚方案已准备
6. ✅ 监控告警已配置
7. ✅ 所有人员已签字确认

满足上述条件后，可以进入「实施周」

---

📞 应急联系

在灰度或部署过程中如遇问题，请联系:

• 技术顾问: [Name] - 权限逻辑、SQL 视图
• 数据库管理员: [Name] - 数据库性能、视图管理
• 运维团队: [Name] - 部署、回滚、监控

应急回滚 (如发现严重问题):

1. 停止灰度部署 (停止新实例更新)
2. 联系运维执行回滚脚本
3. 恢复原始 UserService 代码
4. 预计时间: < 5 分钟
5. 事后分析根本原因

---

准备就绪？🚀 启动实施吧！