fix:[FL-218][角色管理列表接口返回 500]

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

memory/2026-06-20.md

@@ -509,3 +509,22 @@
 
 - 风险与关注点：
   - 改动仅影响 `[data-fquiz-theme="dark"]` 下菜单管理页卡片相关 CSS，不改变亮色主题、接口、权限或页面业务逻辑。
+
+# Work Log - 角色列表接口 keyword SQL 修复（FL-218）
+
+- 背景：
+  - `/api/v1/admin/roles-with-menus` 与 `/api/v1/admin/roles` 在 PostgreSQL/psycopg 下因 `_load_role_page()` 使用 `:keyword IS NULL OR ... LIKE :keyword` 触发参数类型推断失败，角色管理页列表与搜索返回 500。
+
+- 本次处理：
+  - `legacy_admin_rbac_service._load_role_page()` 改为仅在 keyword 非空时拼接角色/菜单搜索条件，空 keyword 列表查询不再生成 `:keyword IS NULL`。
+  - `removed_menu_codes` expanding bind 仅在 keyword 搜索子查询需要菜单过滤时绑定，避免空列表查询携带无用 bind。
+  - `api/tests/test_role_pagination_contract.py` 补充 legacy/modern 两套角色源的 SQL 构造回归测试，覆盖空 keyword 与带 keyword 两种路径。
+
+- 验证：
+  - 基线：`UV_CACHE_DIR=/tmp/fquiz-uv-cache UV_PYTHON_INSTALL_DIR=/tmp/fquiz-uv-python uv run --python 3.11 --with pytest --with fastapi --with pydantic-settings --with sqlalchemy --with PyJWT --with argon2-cffi --with email-validator --with python-multipart --with psycopg[binary] --with bcrypt pytest api/tests/test_role_pagination_contract.py` 通过，2 passed。
+  - 修改后：同命令通过，4 passed。
+  - 修改后：`python3 -m py_compile api/app/services/legacy_admin_rbac_service.py api/tests/test_role_pagination_contract.py` 通过。
+  - 修改后：`git diff --check` 通过。
+
+- 风险与关注点：
+  - 改动仅影响角色列表/搜索 SQL 生成，不改变接口路径、响应字段、分页参数、角色 CRUD 或权限语义。