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 多级同步逻辑。