fquiz/memory/2026-06-20.md

# Work Log - 菜单管理页面一致性优化（FL-151）

- 背景：
  - 菜单管理页需要继续对齐用户管理页的消息反馈、筛选表单、空态与表格滚动配置规范。

- 本次处理：
  - 移除菜单管理页对 `App.useApp()` 的依赖，创建、编辑、删除结果统一走 `error` / `success` state + `useToastFeedback`。
  - 桌面筛选表单项由 Tailwind `min-w-*` 改为与用户管理页一致的 `style={{ width: ... }}`。
  - 表格空态 `Empty` 属性顺序调整为 `image` 在前、`description` 在后。
  - 移除菜单表格 `scroll.x`，仅保留纵向滚动配置，与用户管理页保持一致。

- 验证：
  - 基线：`npm --workspace web exec eslint src/app/admin/menus/page.tsx` 通过。
  - 基线：`npm --workspace web exec tsc --noEmit` 通过。
  - 修改后：`npm --workspace web exec eslint src/app/admin/menus/page.tsx` 通过。
  - 修改后：`npm --workspace web exec tsc --noEmit` 通过。

- 风险与关注点：
  - 改动仅影响菜单管理页前端展示与提示机制，不改变菜单接口、字段结构或权限语义。

## Follow-up - 菜单管理页 React Query 架构对齐（FL-151）

- 背景：
  - 评审继续指出菜单管理页仍使用手动 `useState` + `loadMenus` 数据管理，与用户管理页 React Query 架构不一致。

- 本次处理：
  - 菜单列表查询改为 `useQuery`，由 `menusQuery` 承接 loading、error、数据与 total。
  - 创建、编辑、删除、启用/禁用改为 `useMutation`，并通过 `queryClient.refetchQueries` 刷新菜单数据。
  - `activeKeyword` 统一命名为 `searchKeyword`，移除手动 `loading` / `saving` / `menus` / `menuTotal` state。
  - 实时订阅改为 `queryClient.invalidateQueries({ queryKey: ["admin.menus"] })`。
  - 错误反馈改为组合本地错误与 `menusQuery.error` 后交给 `useToastFeedback`。

- 验证：
  - 基线：`npm --workspace web exec eslint src/app/admin/menus/page.tsx` 通过。
  - 基线：`npm --workspace web exec tsc --noEmit` 通过。
  - 修改后：`npm --workspace web exec eslint src/app/admin/menus/page.tsx` 通过。
  - 修改后：`npm --workspace web exec tsc --noEmit` 通过。

- 风险与关注点：
  - 改动仅迁移菜单管理页前端数据管理架构，不改变 `/api/v1/admin/menus*` 接口路径、请求字段或权限语义。

# Work Log - 角色管理页对齐用户管理页规范（FL-152）

- 背景：
  - 角色管理页需对齐用户管理页的后台列表页布局、移动卡片、操作区换行和反馈规范。

- 本次处理：
  - 角色表格操作区改为与用户管理页一致的 `Space wrap`，避免小屏或窄列下按钮挤压。
  - 角色移动卡片标题改为名称 + 编码横向信息结构，并补齐“角色编码 / 角色名称 / 菜单”字段网格，视觉和信息密度对齐用户移动卡片。
  - 角色菜单多选保留现有接口与字段结构，不改动后端 RBAC 合约。

- 验证：
  - 基线：`npm --workspace web exec eslint src/app/admin/users/page.tsx src/app/admin/roles/page.tsx` 通过，仅用户页存在 1 条既有 unused eslint-disable warning。
  - 修改后：`npm --workspace web exec eslint src/app/admin/roles/page.tsx --max-warnings=0` 通过。
  - 修改后：`npm --workspace web exec eslint src/app/admin/users/page.tsx src/app/admin/roles/page.tsx` 通过，仍仅用户页 1 条既有 warning。
  - 修改后：`npm --workspace web exec tsc --noEmit` 通过。

- 风险与关注点：
  - 改动仅影响角色管理页前端展示与交互排布，不改变接口路径、请求/响应字段、权限判断或角色 CRUD 语义。

## Follow-up - 角色管理页细节一致性补齐（FL-152）

- 背景：
  - 评审继续指出角色管理页在搜索文案、角色编码校验、移动端操作丰富度等方面仍与用户管理页存在细节差异。

- 本次处理：
  - 搜索占位文案统一为“按角色编码/名称/菜单搜索”，对齐用户管理页“按...搜索”的表达方式。
  - 新建角色表单新增角色编码格式校验、500ms 防抖重复检查和提交前重复检查，复用现有 `/api/v1/admin/roles` 列表接口做精确 code 命中判断。
  - 角色移动卡片更多菜单补齐“编辑”和“查看菜单”，删除仍使用 `Modal.confirm`，保持与用户卡片的操作入口组织方式一致。
  - 确认角色 schema 仅包含 `code/name/permission_codes/menu_ids`，无 `status` 字段，因此未新增状态筛选器，避免引入未支持的数据模型语义。

- 验证：
  - 基线：`npm --workspace web exec eslint src/app/admin/users/page.tsx src/app/admin/roles/page.tsx` 通过，仅用户页存在 1 条既有 unused eslint-disable warning。
  - 修改后：`npm --workspace web exec eslint src/app/admin/roles/page.tsx --max-warnings=0` 通过。
  - 修改后：`npm --workspace web exec tsc --noEmit` 通过。
  - 修改后：`npm --workspace web exec eslint src/app/admin/users/page.tsx src/app/admin/roles/page.tsx` 通过，仍仅用户页 1 条既有 warning。

- 风险与关注点：
  - 角色编码重复检查依赖现有角色列表 keyword 查询做前端预检查；服务端创建接口和数据库唯一约束仍是最终一致性保护。
  - 改动仅影响角色管理页前端，不改变后端接口、schema 或权限语义。

# Work Log - 系统参数管理页一致性优化（FL-153）

- 背景：
  - 系统参数管理页需要对齐用户管理页的列表布局、权限呈现、移动卡片、反馈校验与分页交互规范。

- 本次处理：
  - 系统参数页新建入口改为仅 `system_param.manage` 权限可见，保持只读权限下的页面呈现与实际操作权限一致。
  - 表格配置对齐用户管理页：`tableLayout="fixed"`、仅纵向滚动、空态属性顺序、加载态和分页最小 total 处理保持一致。
  - 移动卡片状态 Tag 文案与颜色对齐用户管理页，并补齐 card view 数据累积的 `requestAnimationFrame` 时序处理。
  - 新建/编辑弹窗补齐 `autoComplete="off"`、字段长度规则、参数键防抖重复检查和提交前重复检查。
  - 后端系统参数列表接口补齐 `limit/offset` 查询参数并在 service 层实际分页，修复前端分页参数此前未生效的问题。
  - 新增 `api/tests/test_system_param_service.py` 覆盖系统参数列表分页与筛选后分页行为。

- 验证：
  - 基线：`npm --workspace web exec eslint src/app/admin/users/page.tsx src/app/admin/system-params/page.tsx` 通过，仅用户页存在 1 条既有 unused eslint-disable warning。
  - 基线：`npm --workspace web exec tsc --noEmit` 通过。
  - 修改后：`npm --workspace web exec eslint src/app/admin/system-params/page.tsx --max-warnings=0` 通过。
  - 修改后：`npm --workspace web exec tsc --noEmit` 通过。
  - 修改后：`python3 -m py_compile api/app/api/v1/system_params.py api/app/services/system_param_service.py api/tests/test_system_param_service.py` 通过。
  - 修改后：`UV_PYTHON_INSTALL_DIR=/tmp/fquiz-uv-python uv run --cache-dir /tmp/fquiz-uv-cache --python 3.11 --with fastapi --with pydantic-settings --with sqlalchemy --with PyJWT --with argon2-cffi --with email-validator --with bcrypt -m unittest api.tests.test_system_param_service` 通过。

- 风险与关注点：
  - 改动涉及系统参数列表接口分页契约，但不改变请求/响应字段结构、权限码或 CRUD 语义。
  - 当前本机 `python3` 为 3.7.9，不满足 `api/pyproject.toml` 的 `requires-python >=3.10`；后端单测使用 `uv` 管理的 Python 3.11 环境验证。

# Work Log - 系统消息页面一致性优化（FL-154）

- 背景：
  - 系统消息页面需对齐用户管理页的后台列表页布局、动态表格高度、移动卡片视图和无限滚动交互。

- 本次处理：
  - 系统消息页补齐表格 body 最小高度 CSS 钩子，动态 `scroll.y` 对应的 CSS 变量现已生效。
  - 移动端卡片视图改为与用户管理页一致的容器、空态、卡片视觉和字段网格样式，移除卡片字段内散落的内联间距。
  - 移动卡片累积列表改为 `requestAnimationFrame` 内更新，避免 React hooks lint 的同步 effect 更新错误；筛选切换直接重置卡片分页和累积数据。
  - 系统消息列表 API 增加可选 `message_type` 查询参数，服务端按类型/未读状态返回匹配 `items` 与 `total`，保证移动端无限滚动的 total 与当前筛选一致；`unread_count` 仍保持用户全局未读数。
  - 补充系统消息服务层测试覆盖类型筛选后的 total 行为。

- 验证：
  - 基线：`npm --workspace web exec eslint src/app/admin/users/page.tsx src/app/admin/system-messages/page.tsx` 失败，系统消息页存在 2 个 `react-hooks/set-state-in-effect` 既有错误；用户页存在 1 条既有 unused eslint-disable warning。
  - 基线：`npm --workspace web exec tsc --noEmit` 通过。
  - 基线：`python -m pytest api/tests/test_system_message_service.py api/tests/test_system_message_schema.py` 因系统 `python` 缺少 pytest 无法执行。
  - 修改后：`npm --workspace web exec eslint src/app/admin/system-messages/page.tsx --max-warnings=0` 通过。
  - 修改后：`npm --workspace web exec eslint src/app/admin/users/page.tsx src/app/admin/system-messages/page.tsx` 通过，仍仅用户页 1 条既有 warning。
  - 修改后：`npm --workspace web exec tsc --noEmit` 通过。
  - 修改后：`UV_CACHE_DIR=/tmp/fquiz-uv-cache UV_PYTHON_INSTALL_DIR=/tmp/fquiz-uv-python /home/jenkins/.local/bin/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] pytest api/tests/test_system_message_service.py api/tests/test_system_message_schema.py` 通过，4 passed，存在 1 条既有 SQLAlchemy relationship warning。

- 风险与关注点：
  - `/api/v1/system-messages/me` 新增可选 `message_type` 参数，未传参时保持原列表语义；前端不再做本地类型过滤，分页 total 与服务端过滤结果一致。
  - 改动影响系统消息列表展示与筛选，不改变创建、删除、标记已读接口字段。