补充角色接口兼容修复记忆记录

Co-authored-by: multica-agent <github@multica.ai>

MEMORY.md

@@ -964,3 +964,11 @@
   - `on.push.branches: [dev]`
   - `deploy.if: github.ref == 'refs/heads/dev'`
 - `main` 分支默认不再触发该部署 workflow。
+
+## legacy 角色查询兼容口径（2026-05-01）
+
+- `/api/v1/admin/roles` 当前入口仍走 `legacy_admin_rbac_service`，但数据库形态可能是 legacy（`user_role/role_menu_rela/menu`）或 modern（`roles/role_menus/menus`）。
+- 角色读取链路兼容策略：
+  - 当 `public.user_role` 存在：继续走 legacy 表链路。
+  - 当 `public.user_role` 缺失：自动回退到 modern 表链路，并补齐 `role_permissions + permissions` 权限码。
+- 该兼容仅针对角色读取相关接口（`list_roles/get_role_by_id/list_role_menu_ids`）；角色写入链路暂仍以 legacy 表为准。

memory/2026-05-01.md

@@ -178,3 +178,31 @@
 - 风险与影响：
   - 影响面限定在 PostgreSQL 的 `users` 表审计字段兼容处理。
   - 该兼容动作为启动期一次性 DDL，可能短暂持有 `users` 表 DDL 锁；对已有规范列名的库无行为变化。
+
+## Work Log - 修复 /api/v1/admin/roles 在缺失 user_role 表时返回 500（2026-05-01）
+
+- 背景：
+  - 复现路径：登录后调用 `GET /api/v1/admin/roles`，接口返回 `500`。
+  - 根因：`legacy_admin_rbac_service.list_roles` 固定查询 legacy 表 `user_role`，当库仅存在 modern RBAC 表（`roles/user_roles/role_menus`）时触发 `psycopg.errors.UndefinedTable`。
+
+- 本次改动（最小闭环）：
+  - 文件：`api/app/services/legacy_admin_rbac_service.py`
+    - 新增 `user_role` 存在性探测：`_legacy_role_table_exists()`。
+    - `list_roles` 增加双链路读取：
+      - legacy 存在时保持原有 `user_role + role_menu_rela + menu` 查询；
+      - legacy 缺失时自动回退 `roles + role_menus + menus + role_permissions + permissions`。
+    - `get_role_by_id` 与 `list_role_menu_ids` 同步支持 modern 回退（兼容按 `id` 或 `code` 查角色）。
+    - 新增辅助函数：
+      - `_load_role_rows(..., role_source=...)`
+      - `_load_role_permission_codes_map(..., role_source=...)`
+    - 扩展辅助函数以支持 modern 回退：
+      - `_load_role_menu_ids_map(..., role_source=...)`
+      - `_load_menus_map(..., role_source=...)`
+
+- 验证：
+  - `python3 -m py_compile api/app/services/legacy_admin_rbac_service.py` -> 通过。
+  - `git push origin HEAD:dev` -> 成功（提交 `2c3ad31`）。
+
+- 风险与影响：
+  - 影响范围限定在后台角色读取接口（`/api/v1/admin/roles*`）查询链路。
+  - 对 legacy 表完整的数据库行为保持不变；仅在 `user_role` 缺失时触发 modern 回退逻辑。