iotlcm/docs/角色权限任务切换.md

角色权限任务切换

管理后端仅保存角色并事务记录 sys_role_sync_task，Worker 接管执行。任务数据格式和迁移脚本与管理后端一致。

启用顺序

1. 备份并执行 resource/migrations/20261014_role_sync_outbox.sql；已执行时无需重复迁移。
2. 停止全部旧管理后端执行实例，更新后端。不要与旧消费者混跑。
3. 核对 Worker 和管理后端使用同环境数据库、RabbitMQ vhost；数据库账号须有角色、菜单、机构、任务及权限版本表的相应读写权限。
4. 配置 roleSync.enabled: true，更新 Worker；确认 role sync Worker started 日志及 iotlcm-worker-agent-role-sync 消费者。
5. 核对旧主队列、retry、dlq 积压。完整来源的旧消息转为确定性 ID 的数据库任务；不完整消息拒绝处理，不能盲目清空队列。
6. 保存成功仅表示来源权限和任务已提交；通过管理后端任务查询与重试接口观察结果。

验收

使用隔离环境验证正常同步、断开 RabbitMQ、消费者断线重连、Worker 重启、重复消息、部分失败、模板切换、多实例撤权和租约丢失。监控 pending/retry 积压、最老任务时间和终态失败。SQLite 测试不能代替 MySQL 行锁及真实消息队列验收。

回滚

关闭 Worker 的 roleSync.enabled 前先记录未完成任务；恢复旧后端消费者与停止新消费者要协调，禁止长期双执行。保留任务表和权限版本表，不删除真实角色绑定。未启用执行器期间任务保留 pending，恢复后处理。

检查补充

无效 JSON 和缺少来源信息的旧消息先确认发布到 iotlcm.agent.role.sync.dlq，再确认原消息；隔离发布失败时原消息重新入队。消息引用不存在的任务只记警告，不无限重投；有效任务载荷必须与任务表的租户及来源字段一致。缺失默认角色直接失败，不自动生成孤立角色，修复绑定须业务确认。权限相关数据库查询使用主库，避免从库延迟将旧权限缓存到新版本。