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 环境验证。