sync: 同步 v1.0.4 并脱敏配置与镜像

docs/agent-role-template.md

@@ -1,15 +1,38 @@
-# 代理角色模板
+# 代理角色模板与机构权限上限
 
-使用现有 sys_config、sys_role、sys_role_menu、sys_dept、sys_user_role 表，不新增字段、索引或任务表。
+## 业务规则
 
-平台参数：tenant_id=000000，config_key=agent.role.template.role_id，config_value 为本平台企业的模板角色 ID。开发环境使用 82。模板在企业管理的角色管理维护，正常启用、is_pass=1、数据范围为本机构及下级（4），按钮不允许全部或自定义数据范围。每个企业只能有一个下发模板。
+使用现有 sys_config、sys_role、sys_role_menu、sys_dept、sys_user_role 表，不新增表、字段或前端“角色用途”。
 
-模板修改提交后直接同步直属企业，按 sys_dept.parent_id 定位直属客户、dept_role 定位该企业实际默认角色。通过 created_dept 和上下级关系识别下发角色，不依赖 source_role_id 或 source_dept_id。平台模板切换限定同一企业，旧任务读取当前配置。下级企业维护自己的客户模板，不直接继承平台对孙级的新增授权。
+平台在默认租户的系统参数 agent.role.template.role_id 中指定模板角色 ID。模板身份由参数决定，不再依赖隐藏的 is_pass=1。角色必须启用、属于有效机构、不是上级继承角色，角色数据范围为本机构及下级（4），按钮不能配置全部或自定义数据范围。
 
-同步保留角色 ID 和账号绑定，每家企业独立事务。单家失败不阻塞其他企业，接口报告同步失败，日志记录失败企业。保存成功和同步成功分开处理；失败时模板可能已保存，修复角色关联后重新保存可幂等重试。不会凭空修复账号绑定。
+## 创建代理与维护普通角色
 
-接口鉴权读取当前权限并与上级企业和平台模板取交集，不依赖长期用户权限缓存。没有有效角色或模板参数无效时拒绝授权。业务角色授权记录不会主动删除，模板恢复权限后仍保留授权的角色可能重新获得权限。前端按钮更新需刷新，后端执行当前鉴权。
+- 平台创建一级代理时，从参数模板复制权限，为新机构创建独立默认角色和管理员绑定，不共用平台角色 ID。
+- 各级代理创建下级时，从本机构有效默认角色复制权限，与上级链和平台模板取交集，不要求本机构再创建一个下发模板。
+- 各级机构可新增多个普通角色。保存不再强制 is_pass=1，也不强制覆盖普通角色数据范围。
+- 普通角色授权必须同时在本机构有效权限上限和当前操作账号有效角色的菜单范围内。停用角色不能提供授权依据。
+- 参数模板、机构默认继承角色、普通角色分别承担平台权限来源、机构权限上限、人员实际授权，不混用。
+- 未配置平台参数时，保留原有本级唯一 is_pass=1 角色的下发流程；配置平台参数后，历史本地下发标记不再触发权限覆盖。
 
-采用提交后直接同步，不保证模板保存和全体客户同步原子完成。进程在提交后、同步完成前退出时，需要重新保存触发补偿；没有数据库持久化任务，不承诺自动恢复丢失任务。原有角色同步队列保留兼容重试和旧消息处理，不新增队列配置或定时任务。
+## 多级异步同步
 
-正式上线前验证三级企业、参数切换、权限收回、旧登录账号、单家无效角色、重复同步和真实并发请求。同步随直属企业数量增加会延长请求耗时，需结合实际规模验证 API 超时与数据库负载。
+后端保存成功提交后，通过 RabbitMQ 发布任务，由独立 Worker 执行。平台模板变更按父先子后的顺序遍历各级企业，仅更新 sys_dept.dept_role 指定、归属本机构且来源为直属上级的有效继承角色。角色 ID、人员绑定和下级自建角色勾选保持不变。
+
+新增权限扩展各级继承默认角色的权限范围；普通角色需下级自己勾选。绑定默认继承角色的管理员随默认角色取得新增权限，需要与普通角色区分。
+
+撤销权限时，运行时逐级交集立即限制有效权限，不等待 Worker；Worker 随后更新继承角色记录。普通角色的历史勾选不主动删除，平台未来重新开放权限后，仍保留勾选的普通角色可能恢复该权限。这是现有授权记录保留语义，不表示“新权限自动勾选”。
+
+每机构独立事务。父机构失败时，该分支下级计入失败而不越过父级放权；其他分支继续。重试只处理失败机构及被阻断的下级，失去当前模板从属关系的重试目标明确失败。旧模板任务和历史本地下发任务不能覆盖当前参数模板的继承链。
+
+## 安全边界及历史数据
+
+平台有效超级管理员的登录权限加载不依赖代理模板是否有效，普通账号仍严格校验模板与机构权限。不能只凭旧令牌中的管理员标记绕过检查。
+
+默认角色缺失、停用、归属错误明确返回可处理错误，不再静默变成空菜单 404。角色列表查询不会自动建角色、绑定当前访问者或为历史账号扩权。历史 dept_role=0 数据需要平台管理员核实后修复，代码不会猜测哪个角色应是管理员。
+
+## 可靠性限制
+
+本分支不使用数据库任务表。保存与 MQ 发布不是原子操作；入队失败会明确提示“角色已保存”，需修复消息队列后重新保存补偿。进程若在数据库提交后、发布前退出，也需重新保存。消费者有限重试后进入死信队列，不承诺永不丢任务或 exactly-once。
+
+后台与 Worker 必须成套更新。仅重启后台不会加载新的 Worker 多级同步逻辑。

docs/普通角色与模板校验边界.md

@@ -0,0 +1,12 @@
+# 普通角色维护与代理模板校验边界
+
+- 平台模板由系统参数 agent.role.template.role_id 指定，与普通角色的隐藏 is_pass 标记分离。
+- 普通角色可以创建多个，保存不再强制变成下发角色。配置模板后，历史下发标记不限制普通角色数量、不触发继承链覆盖。
+- 普通角色的编辑、菜单、删除和数据权限维护只识别目标是否为配置模板；无关模板失效不应锁死平台超级管理员。
+- 模板停用、归属异常或记录缺失时仍保留身份及删除保护；仅平台超级管理员可修改模板，模板按钮不能授予全部或自定义数据范围。
+- 非超级管理员授予菜单时，同时核对机构及平台上限与操作员当前有效角色；禁止用已停用角色、旧管理员声明扩大授权。
+- 有效平台超级管理员的登录权限加载先核对数据库角色，跳过无关模板有效性校验；普通账号继续严格校验。
+- 缺失默认角色返回明确错误，不隐式创建角色或把访问角色列表的用户绑定成管理员。历史数据修复需核实后显式操作。
+- 多级同步仅更新默认继承角色，普通角色不自动勾选；完整流程与可靠性限制见 agent-role-template.md 和角色权限异步同步.md。
+
+验证使用 SQLite 隔离数据库，密码修改测试固定使用独立内存库和合成用户，不使用实际配置的数据库。未执行真实账号登录及真实消息队列端到端验证时，不以接口公开健康检查代替登录或同步成功。

docs/角色权限异步同步.md

@@ -0,0 +1,30 @@
+# 角色权限异步同步
+
+当前 v1.0.4 实现采用现有 RabbitMQ 队列 iotlcm.agent.role.sync，不新增任务表或权限版本表。业务规则以《代理角色模板与机构权限上限》为准。
+
+## 保存与消费
+
+1. 后台在数据库事务中保存角色及菜单，事务内禁止发布消息。
+2. 提交后识别系统参数指定模板；模板不要求 is_pass=1。配置模板时，非模板角色不发布覆盖下级权限的任务。
+3. 消息含任务标识、来源角色、来源机构、租户、操作者及模板标记，不携带菜单旧快照。
+4. 后台使用发布确认；发布失败返回明确的“角色已保存、下发失败”错误，重新保存可补偿。
+   提交后的入队使用保留身份上下文但不继承请求取消的独立超时，最长十五秒，发布确认仍最多等待十秒；错误附带任务 ID，便于排查。此处理不等同于事务发件箱，进程退出仍可能造成提交与发布之间的消息丢失。
+5. 独立 Worker 消费时读取当前模板、菜单和机构关系。配置已切换的模板任务，以及配置模板后的历史本地下发任务标记为 superseded，不按普通角色继续传播。
+6. 平台模板按父先子后同步整棵企业下级树；每家企业独立事务，锁定目标机构、默认角色、模板参数及模板角色并再次校验。
+7. 只更新有效的默认继承角色；不改用户角色绑定，不替下级普通角色增加勾选，不自动补齐缺失默认角色。
+
+## 失败与重试
+
+单家失败不阻塞其他分支；失败父机构的下级也计入失败，不能绕过父级。消息保存失败机构 ID 和统计，重试只处理失败目标。目标离开模板机构树后不能被静默算作成功。
+
+消费者失败后延迟重试，最多重试五次，之后发布死信。重试或死信发布失败不能确认原消息。无效 JSON 和无效来源消息隔离到死信队列，隔离发布失败则原消息不能确认。
+
+幂等同步保留角色 ID，重复消息读取当前配置，不恢复旧快照。但没有数据库任务表、事务发件箱或分布式租约，不能保证提交与发布原子性，也不保证任务持久化查询及人工重试页面。需要通过日志、消息队列与重新保存进行排查补偿。
+
+## 本地验证
+
+后台回归使用 SQLite 隔离数据库，覆盖模板异常与管理员登录、普通角色保存、操作员授权边界、默认角色异常、各级代理创建权限来源及提交后入队。
+
+Worker 回归覆盖多层新增、撤权、模板切换、普通角色和账号绑定保留、失败父子分支重试、跨租户隔离、机构循环及重试目标迁出。
+
+不应直接运行连接实际数据库的写入测试。密码修改回归已改为独立 SQLite 内存数据库及合成用户，不使用全局默认数据库、不读写真实账号，也不再提供环境变量开启真实库写入的入口。此前被修改账号的密码仍须管理员主动重置，测试隔离不能恢复原密码。