Admin/fquiz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f1688ae560e013e5d5586833dc6c28269689ba31
fquiz/memory/2026-04-23.md
T
chengkai3 3fd15fbd21 前端框架修改
2026-04-24 15:50:52 +08:00

789 lines
43 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## Work Log - 日记管理按 quiz 表与逻辑重构（2026-04-23）
- 背景：按“用老工程表，参考老工程逻辑改造当前工程日记管理功能”要求，将 `fquiz` 的 `/admin/diary` 从系统日志复用页切换为独立 Diary 模块。
- 本次改动（最小闭环）：
- 后端模型与接口落地（对齐 quiz 口径）：
- `api/app/models/diary.py`
- 新增主表 `diary`，字段：
- `id/title/content/diary_date/mood/weather/archived/create_date/create_user/update_date/update_user`
- 索引：`idx_diary_create_user/idx_diary_diary_date/idx_diary_mood/idx_diary_archived`。
- `api/app/schemas/diary.py`
- 新增 `DiaryMood` 枚举：`HAPPY/CALM/SAD/ANGRY/TIRED/EXCITED`。
- 新增 `DiaryQueryRequest/DiaryCreateRequest/DiaryUpdateRequest/DiarySummary/DiaryPageResponse`。
- `api/app/services/diary_service.py`
- 新增 create/search/get/update/delete/archive 逻辑。
- 查询逻辑对齐 quiz：按 `create_user` 隔离数据，支持 `title/mood/diary_date_start/diary_date_end/archived` 过滤，排序 `diary_date DESC, create_date DESC`。
- 归档逻辑对齐 quiz：`archive` 仅修改 `archived` 状态，保留原记录。
- `api/app/api/v1/diary.py`
- 新增接口：
- `POST /api/v1/diary/search`
- `GET /api/v1/diary/get/{id}`
- `POST /api/v1/diary/create`
- `PUT /api/v1/diary/update`
- `DELETE /api/v1/diary/delete/{id}`
- `POST /api/v1/diary/{id}/archive?archived=...`
- 权限口径：
- 读：`menu.read | menu.manage`
- 写：`menu.manage`
- 路由与建表注册：
- `api/app/api/router.py` 挂载 `diary` 路由。
- `api/app/models/__init__.py`、`api/app/core/database.py` 注册 `diary` 模型，确保 `create_all` 生效。
- 前端页面改造（替换 syslog 复用）：
- `web/src/app/admin/diary/page.tsx`
- 改为独立 Diary 页面：
- 列表分页
- 条件查询（标题、心情、日期范围、归档状态）
- 新增 / 编辑 / 删除
- 归档 / 取消归档
- 详情弹窗
- API 调整到新后端接口 `/api/v1/diary/*`。
- `web/src/types/auth.ts`
- 新增 `DiaryMood/DiarySummary/DiaryListResponse` 类型。
- `web/src/app/admin/page.tsx`
- 首页卡片文案从“上帝视角”调整为“日记管理”。
- `api/app/services/seed_service.py`
- 菜单 `admin.diary` 名称更新为“日记管理”（路径保持 `/admin/diary`）。
- 验证：
- `python3 -m py_compile api/app/models/diary.py api/app/schemas/diary.py api/app/services/diary_service.py api/app/api/v1/diary.py api/app/api/router.py api/app/models/__init__.py api/app/core/database.py api/app/services/seed_service.py` -> 通过。
- `python3 -m compileall api/app` -> 通过。
- 前端 ESLint 未完成（环境依赖缺失）：
- `npm run lint` 提示 `eslint: not found`；
- 直接执行 eslint 后提示缺少 `typescript` 依赖（`Cannot find module 'typescript'`）。
- 风险与影响：
- `admin.diary` 保留 `menu.read/menu.manage` 权限体系（未引入独立 `diary.read/diary.manage`），属于兼容方案；后续若需要更细权限边界，可单独拆分权限码。
- 本次仅对齐了老工程 diary 主链路，不包含分组/tag 维度扩展（老工程该模块本身也未强依赖）。
## Work Log - 登录链路切换为 quiz 老表与老逻辑兼容（2026-04-23）
- 背景：按“改用老工程 `/root/.openclaw/workspace/quiz` 中的表，参照老工程登录逻辑改造”要求，当前轮以“登录可用 + 会话鉴权可用 + 菜单可拉取”为最小闭环。
- 本次改动（最小闭环）：
- 登录请求契约切换：
- `api/app/schemas/auth.py`
- `LoginRequest` 从 `email + password` 改为 `user_id + password`（密码最小长度放宽为 1，兼容老库短密码）。
- `web/src/components/auth-provider.tsx`
- `login(...)` 传参改为 `user_id + password`，请求体同步改为 `{ user_id, password }`。
- `web/src/app/page.tsx`
- 登录表单输入从 `Email` 改为 `User ID`，记住密码缓存字段同步改为 `userId`。
- 密码与状态兼容：
- `api/app/core/security.py`
- `verify_password` 增加 `BCrypt` 兼容分支（老工程口令），保留现有 `Argon2` 支持。
- `api/app/services/legacy_authz_service.py`（新增）
- 新增用户状态归一：`ENABLED/ACTIVE/1/TRUE -> active`，`DISABLED/... -> disabled`。
- `api/app/models/user.py`
- 用户默认状态改为 `ENABLED`；默认主键改为 `uuid4().hex`（32 位，兼容老表长度习惯）。
- 旧表角色/权限装配兼容层（核心）：
- `api/app/services/legacy_authz_service.py`（新增）
- 从老表链路读取授权信息：
- `user_role_rela -> user_role` 计算 `role_codes`
- `role_menu_rela -> menu` 映射 `permission_codes`
- 管理员识别兼容：`admin/sys_mgr/administrator` 或角色名含“管理员”，统一附加 `admin` 角色别名。
- 提供 `build_legacy_menu_tree(...)`，按老 `menu` 表生成 `/admin/me/menus` 所需菜单树。
- 后端鉴权链路接入兼容层：
- `api/app/services/auth_service.py`
- 登录改为按 `user_id` 查询。
- Access Token 的 `role_codes/permission_codes` 改为通过兼容层计算（不再依赖新 RBAC 表）。
- `api/app/core/dependencies.py`
- `get_current_user` 改为用户基础信息 + 兼容层授权计算。
- `api/app/api/v1/ws.py`
- WS 鉴权改为复用兼容层 `role_codes/permission_codes`。
- `api/app/services/jwt_generator_service.py`
- JWT 生成与用户列表角色展示改为兼容层口径，状态过滤兼容 `ENABLED`。
- `api/app/services/user_service.py`
- `serialize_user/queue_user_auth_refresh` 改为兼容层计算授权信息。
- 用户状态写入统一落库存储值 `ENABLED/DISABLED`。
- 用户角色更新改为直连老表 `user_role_rela` 写入（`rela_id + user_id + role_id`）。
- `api/app/services/admin_service.py`
- `build_menu_tree` 优先走老表菜单树构建，失败时回退现有实现。
- 验证：
- 后端编译：
- `python3 -m py_compile api/app/services/legacy_authz_service.py api/app/core/security.py api/app/schemas/auth.py api/app/schemas/user.py api/app/services/auth_service.py api/app/core/dependencies.py api/app/services/user_service.py api/app/api/v1/ws.py api/app/services/jwt_generator_service.py api/app/services/admin_service.py api/app/models/user.py` -> 通过。
- `python3 -m compileall api/app` -> 通过。
- 前端构建：
- `npm run build:web` -> 失败（既有类型问题，非本轮新增）：
- `web/src/app/admin/layout.tsx:155`，`Card` 组件 `children` 类型不匹配（`ui-antd` 兼容层类型定义问题）。
- 风险与影响：
- 本轮优先闭环“登录 + 鉴权 + 菜单树”，未对 `admin/roles`、`admin/menus` 全量 CRUD 全面切换到老表语义；这些接口仍存在新旧口径混用风险。
- 旧表无独立 `permissions` 表，当前 `permission_codes` 为“角色菜单到权限码”的兼容映射；若老库菜单编码与映射不一致，可能出现权限显隐偏差。
- 注册接口当前保留并做了缺省兜底，但老库角色初始化策略（如默认 `user` 角色）依赖目标库实际数据，需联调确认。
## Work Log - 第二轮：角色/菜单管理切换 quiz 老表口径（2026-04-23）
- 背景：按“继续做第二轮”要求，将后台角色/菜单管理从现有 RBAC ORM 表切换为 quiz 老表链路，并同步前后端 ID 类型契约。
- 本次改动（最小闭环）：
- 后端接口与服务切换：
- `api/app/services/legacy_admin_rbac_service.py`
- 完成并启用老表 CRUD：
- 角色：`user_role`、`user_role_rela`、`role_menu_rela`
- 菜单：`menu`、`role_menu_rela`
- 支持：`list/get/create/update/delete role`、`list/get/create/update/delete menu`、`list/replace role menus`、`list permissions`。
- 保护项兼容：保留受保护角色与菜单编码删除拦截。
- 修复更新边界：`menu.parent_id` 支持显式清空；角色/菜单名称做 `strip` 空值校验。
- `api/app/api/v1/admin.py`
- 角色/菜单相关路由改为调用 `legacy_admin_rbac_service`。
- 角色/菜单 path 参数改为字符串：`role_id: str`、`menu_id: str`。
- `GET /admin/roles/{role_id}/menus` 返回改为 `list[str]`。
- `api/app/schemas/admin.py`
- 角色/菜单契约改为字符串 ID：
- `RolePublic.id`、`RolePublic.menu_ids`
- `RoleCreateRequest.menu_ids`、`RoleUpdateRequest.menu_ids`
- `MenuPublic.id`、`MenuPublic.parent_id`
- `MenuCreateRequest.parent_id`、`MenuUpdateRequest.parent_id`
- `RoleMenuUpdateRequest.menu_ids`
- 鉴权菜单树 ID 口径对齐：
- `api/app/services/legacy_authz_service.py`
- `build_legacy_menu_tree` 改为直接使用老表 `menu.menu_id/parent_id` 作为菜单树 ID，不再生成临时递增 ID。
- 前端类型与页面对齐：
- `web/src/types/auth.ts`
- `RoleItem.id/menu_ids`、`MenuItem.id/parent_id` 改为字符串类型。
- `web/src/app/admin/roles/page.tsx`
- 角色编辑状态与 `menu_ids` 改为字符串口径。
- `web/src/app/admin/menus/page.tsx`
- 菜单编辑状态与 `parent_id` 改为字符串口径；
- ID 排序改为兼容字符串（纯数字优先数值比较，否则字典序）。
- `web/src/app/admin/layout.tsx`
- 菜单路径项 `id` 改为字符串。
- `web/src/app/admin/users/page.tsx`
- 角色兜底项 `id` 改为字符串（`fallback-*`）。
- 验证：
- 后端编译：
- `python3 -m py_compile api/app/schemas/admin.py api/app/api/v1/admin.py api/app/services/legacy_admin_rbac_service.py api/app/services/legacy_authz_service.py` -> 通过。
- `python3 -m compileall api/app` -> 通过。
- 前端构建：
- `npm run build:web` -> 失败，仍为既有问题：
- `web/src/app/admin/layout.tsx:155`，`Card` 组件 `children` 类型不匹配（`ui-antd` 兼容层类型定义问题，非本轮新增）。
- 风险与影响：
- 老表 `menu` 字段语义与当前前端展示字段并非一一对应（如 `component/cacheable`），当前仍为兼容映射；如需完全对齐 quiz UI 语义，后续需补充映射规则。
- `permissions` 仍是基于菜单编码映射的兼容推导；若线上老表菜单编码偏差，权限显示与鉴权可能出现边缘不一致，需要联调验证。
## Work Log - 第三轮：前端构建门禁打通（2026-04-23）
- 背景：第二轮后 `npm run build:web` 仍被前端类型问题阻断，影响发布门禁。
- 本次改动（最小闭环）：
- `antd Card` 类型兼容修复：
- `web/src/components/ui-antd.tsx`
- `Card` 包装器改用 `antd` 官方 `CardProps` 类型，不再依赖 `ComponentProps<typeof AntCard>` 推导。
- 对 `AntCard` 做显式可渲染组件收敛（`AntCardComponent`），避免 `JSX element type 'AntCard' does not have construct or call signatures`。
- 页面层统一复用兼容层 `Card`：
- `web/src/app/admin/mermaid-mgr/_components/mermaid-editor.tsx`
- `web/src/app/admin/mindmap/_components/mindmap-editor.tsx`
- 从 `antd` 直引 `Card` 改为 `@/components/ui-antd` 的 `Card`。
- 严格 TS 隐式 any 清理（与现有 strict 配置对齐）：
- `web/src/app/admin/mermaid-mgr/_components/mermaid-editor.tsx`
- `web/src/app/admin/mermaid-mgr/page.tsx`
- `web/src/app/admin/mindmap/_components/mindmap-editor.tsx`
- `web/src/app/admin/schedule/page.tsx`
- `web/src/app/admin/todos/page.tsx`
- 补全 `onChange/onClick/onFinish/showTotal/footer` 等回调参数类型标注，消除 `noImplicitAny` 阻断。
- 验证：
- `npm run build:web` -> 通过（TypeScript 检查通过 + 54 个页面静态生成完成）。
- 风险与影响：
- 本轮仅做类型与组件兼容修复，未改业务逻辑与接口契约。
- 后续若继续在 `web/src/app/admin/**` 新增 AntD 回调，仍需显式参数类型以避免 `strict` 下再次触发 `implicit any`。
## Work Log - 第四轮：类型门禁巡检与基线固化（2026-04-23）
- 背景：第三轮已打通 `build:web`，第四轮目标是做“全量巡检”防止同类问题回归。
- 本次动作：
- 代码扫描：
- `web/src` 内 `import { Card } from "antd"`（避免回到不稳定类型入口）；
- `onFinish/onChange/onClick/onPressEnter` 中常见未标注参数模式（`event/value/values/total/_`）。
- 类型基线检查：
- `npm --workspace web exec tsc --noEmit --pretty false`。
- 结果：
- 扫描未发现新的高风险命中。
- `tsc --noEmit` 全量通过，`web` 当前类型门禁基线稳定。
- 影响：
- 第四轮未新增业务逻辑改动，属于稳定性巡检与基线确认。
## Work Log - 第五轮：后端联调冒烟与运行时修复（2026-04-23）
- 背景：按“继续第五轮”要求，对登录与后台角色/菜单主链路做联调冒烟，验证第二轮老表改造在运行容器中的真实表现。
- 本次动作与发现：
- 容器代码加载校验：
- 初次冒烟发现运行中的 `api` 仍走旧登录契约（`email + password`），因此执行 `docker compose up --build -d api` 重新加载最新代码。
- 运行时阻断修复 1（启动失败）：
- 重建后 `api` 启动报错：`ModuleNotFoundError: No module named 'bcrypt'`。
- 处理：`api/requirements.txt` 新增 `bcrypt==4.2.1`，重建 `api` 后恢复健康。
- 运行时阻断修复 2（`/admin/me/menus` 500）：
- 冒烟命中 `500`，日志定位到 `legacy_authz_service.build_legacy_menu_tree` 使用了未定义变量 `node_id`。
- 处理：`api/app/services/legacy_authz_service.py` 将 `nodes[node_id]` 修正为 `nodes[legacy_id]`，重建后恢复。
- 冒烟验证（只读，不写库）：
- 登录契约校验：
- `POST /api/v1/auth/login` 传 `{user_id, password}` -> 401（凭证错误，说明契约已生效）；
- 传 `{email, password}` -> 422（缺少 `user_id`）。
- 管理后台主链路：
- `GET /api/v1/admin/roles` -> 200，`RolePublic.id/menu_ids` 为字符串；
- `GET /api/v1/admin/menus` -> 200，`MenuPublic.id/parent_id` 为字符串口径；
- `GET /api/v1/admin/me/menus` -> 200，菜单树根节点 `id` 为字符串；
- `GET /api/v1/admin/roles/sys_mgr/menus` -> 200，`menu_ids` 为字符串数组；
- `GET /api/v1/admin/permissions` -> 200。
- 相关文件：
- `api/requirements.txt`
- `api/app/services/legacy_authz_service.py`
- 风险与影响：
- 本轮未执行角色/菜单写接口（create/update/delete），避免对外部数据库产生变更；当前验证覆盖“登录契约 + 权限读取 + 菜单读取”读路径。
## Work Log - 第六轮：修复日程页 Modal.footer 类型不兼容（2026-04-23）
- 背景：`docker compose build web` 在 `web/src/app/admin/schedule/page.tsx:747` 失败，报错为 `Modal.footer` 回调签名不匹配（`OkBtn/CancelBtn` 被错误标注为 `() => ReactElement`）。
- 本次改动（最小闭环）：
- `web/src/app/admin/schedule/page.tsx`
- 补充 React 类型导入：`FC`、`ReactNode`。
- `Modal.footer` 回调类型从：
- `_origin: unknown`
- `{ OkBtn: () => ReactElement; CancelBtn: () => ReactElement }`
调整为：
- `_origin: ReactNode`
- `{ OkBtn: FC; CancelBtn: FC }`
- 保持现有按钮渲染与删除/保存逻辑不变，仅修复类型契约。
- 验证：
- `npm run build:web` -> 通过（Next.js 编译、TypeScript 检查、静态页面生成全部完成）。
- 风险与影响：
- 仅影响前端类型声明，不涉及接口契约、请求参数、业务分支和数据写入行为。
## Work Log - 第七轮：后台系统菜单改用 AntD Menu 组件（2026-04-23）
- 背景：当前后台左侧“系统菜单”是递归 `Button + Link`，移动端是 `DropdownMenu`。按要求切换为 Ant Design `Menu` 组件承载菜单树。
- 本次改动（最小闭环）：
- `web/src/app/admin/layout.tsx`
- 新增 `Menu as AntMenu` 与 `MenuProps` 引入。
- 移除递归渲染函数 `renderMenuNodes` 与移动端 `flattenMenuPaths` 下拉菜单构建逻辑。
- 新增 `buildMenuItems`：把后端返回的 `MenuTreeItem[]` 转为 `AntMenu` 的 `items` 结构（支持嵌套）。
- 新增 `collectSubmenuKeys`：收集所有带子节点菜单并展开，保持与旧实现一致的“默认全展开”体验。
- 新增 `findActiveMenuState`：基于 `pathname` 计算 `selectedKeys/openKeys`，保证当前路由高亮准确。
- 桌面端左侧“系统菜单”改为 `AntMenu mode=\"inline\"` 渲染。
- 移动端菜单入口改为在卡片内直接渲染 `AntMenu mode=\"inline\"`（不再使用下拉菜单承载）。
- 顶部“账号”菜单保持原 `DropdownMenu` 方案不变。
- 验证：
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- `npm run build:web` -> 通过（Next.js 编译、TypeScript、静态页面生成全部完成）。
- 风险与影响：
- 移动端菜单交互由“点击按钮弹出”改为“卡片内直接展示”，视觉高度会增加，但菜单可见性更高。
- 本次只调整菜单承载组件，不涉及菜单接口、权限判断和路由结构变更。
## Work Log - 第八轮：菜单导航切回左侧布局（2026-04-23）
- 背景：收到“menu 导航放到左侧”的要求，当前后台壳层为顶部横向 `Menu`，与期望不一致。
- 本次改动（最小闭环）：
- `web/src/app/admin/layout.tsx`
- 移除顶部横向 `AntMenu(mode=\"horizontal\")` 导航区。
- 新增左侧栏布局（`md` 及以上）：`AntMenu(mode=\"inline\")` 承载后台菜单树。
- 移动端菜单改为左侧 `Drawer`（`placement=\"left\"`）承载 `AntMenu`，顶部仅保留“菜单”按钮触发抽屉。
- 保留现有菜单数据来源（`/api/v1/admin/me/menus`）、路由高亮逻辑（`selectedKeys`）与账号区交互不变。
- 菜单展开状态统一为 `menuOpenKeys`，桌面侧栏与移动抽屉共用，保证一致性。
- 验证：
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- `npm run build:web` -> 通过（Next.js 编译、TypeScript、静态页面生成全部完成）。
- 风险与影响：
- 布局从“顶部导航”改为“左侧导航”，横向空间分配会变化，但仅影响后台壳层，不涉及页面业务逻辑与接口契约。
## Work Log - 第八轮：后台壳层改为顶部固定导航（2026-04-23）
- 背景：按“参考 Ant Design 文档站顶部固定导航（左侧 Logo + 主导航）”要求，重构当前后台壳层布局。
- 本次改动（最小闭环）：
- `web/src/app/admin/layout.tsx`
- 布局从“左侧固定菜单 + 内容头卡片”调整为“顶部固定导航 + 内容区”。
- 顶栏结构改为：左侧品牌 Logo（`Q + fquiz`）+ 中部主导航（`AntMenu mode=horizontal`）+ 右侧账号区。
- 保留现有菜单数据链路：继续通过 `/api/v1/admin/me/menus` 拉取并渲染树形菜单。
- 保留路由高亮逻辑，并补充 `openKeys` 计算用于移动端内嵌菜单展开。
- 新增移动端菜单折叠入口（`菜单/收起菜单`），避免小屏导航不可达。
- 保留 `menuError` 提示、登录态判断与账号退出逻辑，不改接口契约。
- 验证：
- `npm run build:web` -> 通过（Next.js 编译、TypeScript 检查、静态页面生成全部完成）。
- 风险与影响：
- 桌面端导航入口从左侧改为顶部，用户需要适应新的操作路径。
- 当顶级菜单数量较多时，水平菜单会进入 AntD 的溢出折叠（`...`）交互，属于组件默认行为。
## Work Log - 第九轮：84 库用户/角色/菜单数据导出并初始化本地库（2026-04-23）
- 背景：按“查询 84 的用户表、角色表、菜单表、菜单角色关系数据，然后初始化本地库”要求执行。
- 本次动作（最小闭环）：
- 远端 84 库（`223.109.142.84:5432/postgres`）连通与数据核验：
- 表存在：`users / user_role / menu / role_menu_rela`。
- 行数：`users=5`、`user_role=6`、`menu=64`、`role_menu_rela=123`。
- 数据导出留档：
- CSV 导出文件：
- `tmp/84-export/users_84.csv`
- `tmp/84-export/user_role_84.csv`
- `tmp/84-export/menu_84.csv`
- `tmp/84-export/role_menu_rela_84.csv`
- 初始化脚本导出：
- `tmp/84-export/legacy_auth_schema.sql`
- `tmp/84-export/legacy_auth_data.sql`
- `tmp/84-export/legacy_auth_data_wrapped.sql`
- 本地库初始化：
- 目标库：本地 `fquiz-db` 的 `postgres` 数据库（用户 `fquiz`）。
- 先 `DROP TABLE IF EXISTS public.role_menu_rela, public.menu, public.user_role, public.users CASCADE`。
- 回放 schema + data 完成建表和数据导入。
- 由于 `menu.parent_id` 自关联外键，导入数据时在同一会话启用 `session_replication_role=replica` 后回放，导入成功。
- 验证：
- 远端与本地（postgres）按表对比 `count + md5(signature)` 全量一致：
- `users`: `5` / `a50fedde66f156b0442d792b42c355b7`
- `user_role`: `6` / `7fb7d2520f44efe25e8be15762a3bd3d`
- `menu`: `64` / `094b533fe91b853868a0f9e4356da49a`
- `role_menu_rela`: `123` / `3c752bb95375e80d835b198831d44535`
- 风险与影响：
- 本次初始化目标是本地 `postgres` 库，不影响本地 `fquiz` 库现有表数据。
- `users` 表为老工程结构（`user_id/user_name/password/state...`），与新表结构不同；后续若切回新 RBAC 表需区分数据库与表口径。
## Work Log - 第十轮：数据库默认目标切换到本地并修复启动兼容（2026-04-23）
- 背景：按“现在切到本地库，不用84了”要求，将默认数据库目标从 `223.109.142.84` 切到本地 `fquiz-db`。
- 本次改动（最小闭环）：
- `docker-compose.yml`
- `db` 服务移除 `local-db` profile，改为默认启动。
- `api` 新增 `depends_on: db (service_healthy)`。
- `api` 的默认 DB 参数切到本地：
- `DB_HOST=db`
- `DB_PORT=5432`
- `DB_NAME=postgres`
- `DB_USERNAME=fquiz`
- `DB_PASSWORD=fquiz`
- `api/app/core/config.py`
- 非 Docker 默认 DB 参数改为本机本地库：
- `db_host=127.0.0.1`
- `db_port=5433`
- `db_name=postgres`
- `db_username=fquiz`
- `db_password=fquiz`
- `.env.example`
- 同步改为本机本地库默认值（不再出现 84 默认地址）。
- `api/app/services/seed_service.py`
- `_seed_initial_admin` 中初始管理员状态由 `active` 调整为 `ENABLED`，兼容老 `users.state` 约束，解决本地库启动时 `users_state_check` 报错。
- 验证：
- `python3 -m py_compile api/app/services/seed_service.py` -> 通过。
- `docker compose up -d --build api` -> 通过，`fquiz-api` 正常启动。
- `docker compose ps` -> `api/db/web` 全部 `healthy/up`。
- `GET /health` -> 200。
- `POST /api/v1/auth/login`（错误密码探测）-> 401（说明 API 可用且查询链路正常）。
- 风险与影响：
- 默认目标已改为本地库；若后续要临时连外部库，需显式设置 `DATABASE_URL` 或覆盖 `DB_HOST` 等环境变量。
## Work Log - 第十一轮：后台菜单改为左侧内嵌并支持右上角显隐（2026-04-23）
- 背景：按“改成内嵌菜单，放在页面左侧，通过右上角菜单按钮隐藏/显示”要求调整后台壳层交互。
- 本次改动（最小闭环）：
- `web/src/app/admin/layout.tsx`
- 移除移动端 `Drawer` 侧滑菜单方案，统一为页面内嵌左侧菜单。
- 新增状态 `menuVisible`，默认 `true`，控制左侧菜单区域显示/隐藏。
- 顶栏右上角“菜单”按钮改为全端可见，并切换文案：
- 菜单显示时：`隐藏菜单`
- 菜单隐藏时：`显示菜单`
- 内容区网格列根据 `menuVisible` 动态切换：
- 显示：`md:grid-cols-[280px_minmax(0,1fr)]`
- 隐藏：`md:grid-cols-1`
- 左侧菜单保留 `AntMenu inline` + `openKeys/selectedKeys` 逻辑，保持当前路由高亮与展开行为。
- 验证：
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- `next build` 多次在当前环境命中 `.next` 产物文件 `ENOENT`（非本次业务逻辑错误）：
- Turbopack 路径：`_buildManifest.js.tmp` 丢失；
- Webpack 路径：`edge-runtime-webpack.js` copyfile 丢失。
- 风险与影响：
- 本次仅改后台壳层菜单交互，不涉及 API 契约和业务数据写入。
- 当前构建环境存在 `.next` 产物落盘异常，影响 `build:web` 门禁稳定性（与菜单逻辑无直接耦合）。
## Work Log - 第十二轮：支持主题色切换并持久化（2026-04-23）
- 背景：按“支持主题色切换”要求，增加可视化主题色切换入口，并要求刷新后保持。
- 本次改动（最小闭环）：
- `web/src/components/ui-antd.tsx`
- 新增主题外观上下文 `ThemeAppearanceContext`。
- 新增 `useThemeAppearance()`，对外暴露：
- `accentColor`
- `setAccentColor(...)`
- 新增 `THEME_ACCENT_OPTIONS`（靛蓝/蓝色/青色/绿色/橙色/红色/粉色/紫色）。
- `Theme` 组件增加主题色状态与持久化：
- 启动时读取 `localStorage["fquiz:theme:accent-color"]`
- 切换后写回 localStorage
- 切换即更新 AntD `ConfigProvider` 的 `colorPrimary`，全局生效。
- `web/src/app/admin/layout.tsx`
- 顶栏右侧新增主题色选择器（`Select`），使用 `THEME_ACCENT_OPTIONS` 渲染。
- 选择器值绑定 `useThemeAppearance().accentColor`，变更时调用 `setAccentColor`。
- 验证：
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- `npm run build:web` -> 通过（Next.js 编译、TypeScript、静态页面生成全部完成）。
- 风险与影响：
- 主题色选择属于前端 UI 层改动，不影响后端接口与数据模型。
## Work Log - 登录页怪兽主视觉改为“毛怪 + 大眼仔”双角色（2026-04-23）
- 背景：按“把登录页面的怪兽换成毛怪和大眼仔”要求，保留登录/注册链路不变，仅重做首页登录视觉。
- 本次改动（最小闭环）：
- `web/src/app/page.tsx`
- 保留 `useAuth` 登录/注册/退出与表单提交流程不变。
- 将单怪兽舞台替换为双角色舞台：`sulley + mike`。
- 保留“眼睛跟随鼠标”交互，并新增大眼仔眼球偏移参数（`MIKE_GAZE_MAX_X/Y`）。
- 保留“密码输入时挪开视线”交互：毛怪转头避视、大眼仔轻微眯眼。
- 替换旧 `.monster-*` 样式为 `.duo-* / .sulley-* / .mike-*` 样式，维持响应式布局与背景动效。
- 验证：
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- `npm run build:web` -> 通过（Next.js 编译、TypeScript、静态页面生成全部完成）。
- 风险与影响：
- 本次为前端视觉层改动，不涉及 API 契约、鉴权逻辑或后端数据结构。
- 角色形象为页面内 CSS 卡通实现，不依赖外部图片资源。
## Work Log - 第九轮：按 AntD 配色收口全局变量（2026-04-23）
- 背景：当前前端虽然已切到 AntD 组件栈，但大量页面仍使用历史 `--gray-* / --accent-*` 变量与 Tailwind 类，导致视觉不完全跟随 AntD 主题色。
- 本次改动（最小闭环）：
- `web/src/components/ui-antd.tsx`
- 在 `Theme` 内新增 `ThemeCssVarsScope`，通过 `antdTheme.useToken()` 把旧语义变量映射到 AntD token。
- 覆盖变量包括：
- AntD 直连变量：`--ant-color-primary`、`--ant-color-bg-layout`、`--ant-color-border-secondary`、`--ant-color-text-secondary`、`--ant-color-text`
- 旧语义变量：`--gray-*`、`--accent-*`、`--red-*`、`--green-*`、`--orange-*`、`--indigo-*`、`--color-panel-solid`、`--border`
- 通过 `display: contents` 避免新增布局层级影响页面结构。
- `web/src/app/globals.css`
- 新增上述变量的静态兜底值，避免主题注入前变量缺失。
- `body` 背景与文字颜色改为走 AntD 变量（`--ant-color-bg-layout`、`--ant-color-text`）。
- 验证：
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- `npm run build:web` -> 通过（Next.js 编译、TypeScript、静态页面生成全部完成）。
- 风险与影响：
- 本次不改接口与业务逻辑，仅调整前端主题变量层与全局视觉基线。
- 旧页面里保留的 `var(--gray/* --accent/*)` 写法将统一跟随 AntD token，后续可按需渐进式替换为原生 AntD token class/style。
## Work Log - 第十轮：去掉前端 URL 的 `/admin` 前缀（2026-04-23）
- 背景：希望用户侧访问地址不再出现 `/admin`，但保留现有 `app/admin/**` 页面实现与权限链路。
- 本次改动（最小闭环）：
- `web/src/middleware.ts`（新增）
- 新地址（不含 `/admin`）统一 rewrite 到现有 `/admin/**` 页面路由。
- 旧地址 `/admin/**` 自动 redirect 到无前缀地址，兼容历史链接与书签。
- 根路径 `/`、`/api`、`/_next`、常见静态文件请求走 bypass，不参与改写。
- 约定：原 `/admin` 首页映射为 `/dashboard`。
- `web/src/app/admin/layout.tsx`
- 菜单数据加载后统一把 `path` 从 `/admin/**` 规范化为无前缀地址（`/admin` -> `/dashboard`）。
- 顶部 Logo 跳转从 `/admin` 改为 `/dashboard`。
- `web/src/app/page.tsx`
- 首页快捷入口改为无前缀地址：`/dashboard`、`/users`、`/requirements`。
- 验证：
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- `npm run build:web` -> 通过（含 Proxy/Middleware 生效，编译与静态生成完成）。
- 风险与影响：
- 现有硬编码 `/admin/**` 链接仍可用，但会发生一次 30x 重定向到无前缀地址。
- Next.js 16 对 `middleware` 命名提示迁移到 `proxy`，当前功能正常；后续可按官方建议改名以消除提示。
## Work Log - 第十轮：下线 8 个后台功能（2026-04-23）
- 背景：按“删除生命倒计时、密钥管理、价格监控、历史答卷、诗词本、日记管理、家庭作业、试题管理功能”要求，执行最小闭环下线。
- 本次改动（最小闭环）：
- 菜单与权限口径收敛：
- `api/app/services/seed_service.py`
- 移除默认菜单：
- `admin.life_countdown`
- `admin.password`
- `admin.token_usage`
- `admin.history`
- `admin.vocabulary`
- `admin.diary`
- `admin.homework`
- `admin.question_bank`
- `ROLE_MENU_BINDINGS["admin"]` 同步移除上述菜单。
- 移除默认权限 `life_countdown.read/manage`。
- `api/app/services/legacy_authz_service.py`
- 将上述 8 个菜单加入 `DISABLED_MENU_CODES`，保证老库已有记录也不会再出现在 `/api/v1/admin/me/menus`。
- 权限映射移除对应菜单码；补充 `admin.job_mgr -> question_bank.read/manage`，确保“作业监控”权限链路不受影响。
- `api/app/services/legacy_admin_rbac_service.py`
- 增加 `REMOVED_MENU_CODES` 过滤：菜单列表、角色菜单返回、权限推导、菜单可用性校验均排除已下线菜单。
- `api/app/services/admin_service.py`
- 受保护菜单集合同步移除上述 8 个菜单码（兼容回退路径）。
- `web/src/app/admin/menus/page.tsx`
- 前端受保护菜单集合同步移除上述 8 个菜单码。
- 后端接口下线：
- `api/app/api/router.py`
- 不再挂载 `diary_router` 与 `life_countdown_router`。
- `api/app/api/v1/admin.py`
- 删除密钥管理专用接口：
- `GET /api/v1/admin/password/models`
- `GET /api/v1/admin/password/models/{model_id}/keys`
- `POST /api/v1/admin/password/models/{model_id}/rotate-key`
- 前端页面下线：
- 删除路由页面：
- `web/src/app/admin/life-countdown/page.tsx`
- `web/src/app/admin/password/page.tsx`
- `web/src/app/admin/price-monitor/page.tsx`
- `web/src/app/admin/token-usage/page.tsx`
- `web/src/app/admin/history/page.tsx`
- `web/src/app/admin/poetry/page.tsx`
- `web/src/app/admin/diary/page.tsx`
- `web/src/app/admin/homework/page.tsx`
- `web/src/app/admin/question-bank/page.tsx`
- `web/src/app/admin/vocabulary/page.tsx`
- `web/src/app/admin/page.tsx` 移除上述功能卡片入口。
- `web/src/app/admin/vocabulary-proficiency/page.tsx` 移除“进入诗词本”跳转按钮。
- 保留“作业监控”功能：
- 将原 `question-bank` 页面实现迁移到 `web/src/app/admin/job/_components/job-question-bank-page.tsx`，
- `web/src/app/admin/job/page.tsx` 改为引用该实现。
- 验证：
- 后端语法校验：
- `python3 -m py_compile api/app/services/seed_service.py api/app/services/legacy_authz_service.py api/app/services/legacy_admin_rbac_service.py api/app/services/admin_service.py api/app/api/v1/admin.py api/app/api/router.py` -> 通过。
- `python3 -m compileall api/app` -> 通过。
- 前端构建：
- `npm run build:web` -> 通过。
- 输出路由确认已不再生成：
- `/admin/life-countdown`、`/admin/password`、`/admin/price-monitor`、`/admin/token-usage`、`/admin/history`、`/admin/poetry`、`/admin/diary`、`/admin/homework`、`/admin/question-bank`、`/admin/vocabulary`。
- 风险与影响：
- 本次下线为“菜单 + 路由 + 部分接口”闭环；`question_bank` 与 `vocabulary` 底层 API 仍保留，供“作业监控/分组管理/知识点管理/单词统计”等保留模块复用。
- 若线上老库仍有已下线菜单记录，当前会被服务层过滤，不再对外展示。
## Work Log - 下线 8 个后台功能模块（2026-04-23）
- 背景：按要求删除系统中的以下功能：
- 微信小程序（`admin.wxapp`）
- MD解析（`admin.mdresolve`）
- 数据查询（`admin.data_query`）
- 热搜（`admin.hot_search`）
- 文件识别（`admin.filedetector`）
- 百度网盘（`admin.baidu_pan`）
- 分组管理（`admin.tag`）
- 知识点管理（`admin.knowledge_point_mgr`）
- 本次改动（最小闭环）：
- 前端：删除 8 个页面路由文件（访问即 404）：
- `web/src/app/admin/wxapp/page.tsx`
- `web/src/app/admin/mdresolve/page.tsx`
- `web/src/app/admin/data-query/page.tsx`
- `web/src/app/admin/hot-search/page.tsx`
- `web/src/app/admin/filedetector/page.tsx`
- `web/src/app/admin/baidu-pan/page.tsx`
- `web/src/app/admin/group/page.tsx`
- `web/src/app/admin/knowledge/page.tsx`
- 前端：移除后台首页入口卡片：
- `web/src/app/admin/page.tsx`
- 前端：菜单管理页取消上述 8 个菜单码的“受保护菜单”限制（允许删除历史残留菜单）：
- `web/src/app/admin/menus/page.tsx`
- 后端：菜单树硬过滤（即使老库仍有菜单记录，也不会下发给前端导航）：
- `api/app/services/legacy_authz_service.py`
- 新增 `DISABLED_MENU_CODES` 并在菜单树构建、权限推导时过滤。
- `api/app/services/admin_service.py`
- 新增 `REMOVED_MENU_CODES` 并在 `list_menus/get_menu_by_id/get_menu_by_code/create_menu/build_menu_tree/_load_menus_by_ids` 过滤。
- `api/app/services/legacy_admin_rbac_service.py`
- 将 8 个菜单码加入 `REMOVED_MENU_CODES`，统一影响菜单列表、角色菜单关联、权限推导。
- 后端：停用对应接口挂载与默认种子：
- `api/app/api/router.py`
- 移除 `hot_search_router` 与 `mdresolve_router` 挂载。
- `api/app/services/topic_registry.py`
- 移除 `admin.hot_search` 与 `admin.hot_search.follow_topics` topic 规则。
- `api/app/services/seed_service.py`
- 移除 8 个菜单定义与 admin 默认菜单绑定。
- 移除 `seed_hot_search_defaults` 导入与调用。
- 验证：
- `python3 -m py_compile api/app/services/legacy_authz_service.py api/app/services/seed_service.py api/app/api/router.py api/app/services/topic_registry.py api/app/services/legacy_admin_rbac_service.py api/app/services/admin_service.py` -> 通过。
- `python3 -m compileall api/app` -> 通过。
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- `npm run build:web` -> 通过；后台静态路由从 54 个下降到 36 个，已不再包含上述 8 个页面。
- 风险与影响：
- 本次不做数据库物理删行迁移；若库内仍有历史菜单记录，将被后端过滤而不可见。
- `api/app/api/v1/hot_search.py` 与 `api/app/api/v1/mdresolve.py` 文件仍保留在仓库，但未挂载到 `api_router`，外部不可访问。
## Work Log - 下线功能补充收口（2026-04-23）
- 补充改动：
- 删除历史别名页面 `web/src/app/admin/tag/page.tsx`，彻底下线“分组管理”的旧路由入口。
- 验证补充：
- 因删除页面后 `.next` 残留类型缓存导致 `tsc` 引用旧路径，执行 `rm -rf web/.next` 后重跑：
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过
- `npm run build:web` -> 通过
- 产物路由确认不再包含 `/admin/tag` 及本轮下线的 8 个功能页面。
## Work Log - 下线 4 个后台功能模块（2026-04-23）
- 背景：按要求删除以下功能：
- 脚本管理（`admin.cron_task_mgr`）
- 待办管理（`admin.todos`）
- 作业监控（`admin.job_mgr`）
- JWT 生成器（`admin.jwt_generator`）
- 本次改动（最小闭环）：
- 前端下线：
- 删除路由页面：
- `web/src/app/admin/cron/page.tsx`
- `web/src/app/admin/todos/page.tsx`
- `web/src/app/admin/job/page.tsx`
- `web/src/app/admin/jwt-generator/page.tsx`
- 后台首页移除 4 个入口卡片：
- `web/src/app/admin/page.tsx`
- 菜单管理页移除 4 个菜单码受保护限制（允许清理历史残留）：
- `web/src/app/admin/menus/page.tsx`
- 为保留“队列管理”能力，将原待办页面实现迁移到：
- `web/src/app/admin/jobqueue/_components/jobqueue-todo-page.tsx`
- `web/src/app/admin/jobqueue/page.tsx` 改为引用新组件。
- 后端菜单/权限链路下线：
- `api/app/services/seed_service.py`
- 移除 4 个菜单定义及 admin 默认菜单绑定。
- 移除 `jwt_generator.read/jwt_generator.manage` 默认权限与 admin 角色默认绑定。
- `api/app/services/legacy_authz_service.py`
- 将 4 个菜单码加入 `DISABLED_MENU_CODES`，并移除对应菜单权限映射。
- 移除 `DEFAULT_ADMIN_PERMISSION_CODES` 中 `jwt_generator.*`。
- `api/app/services/legacy_admin_rbac_service.py`
- 将 4 个菜单码加入 `REMOVED_MENU_CODES`。
- `api/app/services/admin_service.py`
- 将 4 个菜单码加入 `REMOVED_MENU_CODES`，并从受保护删除集合中移除。
- 后端接口挂载下线：
- `api/app/api/router.py`
- 移除 `jwt_generator_router` import 与 `include_router`，JWT 生成器 API 不再对外挂载。
- 验证：
- `python3 -m py_compile api/app/services/seed_service.py api/app/services/legacy_authz_service.py api/app/services/legacy_admin_rbac_service.py api/app/services/admin_service.py api/app/api/router.py` -> 通过。
- `python3 -m compileall api/app` -> 通过。
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- `npm --workspace web exec next build --webpack` -> 通过；产物路由确认不再包含：
- `/admin/cron`
- `/admin/todos`
- `/admin/job`
- `/admin/jwt-generator`
- 风险与影响：
- `api/app/api/v1/jwt_generator.py` 文件仍保留在仓库，但已从路由汇总中移除，不可外部访问。
- 当前环境下 Next 构建偶发 `.next` 产物拷贝 `ENOENT` 警告（非本次改动引入，存在环境不稳定性）；本轮最终构建已成功产出路由清单。
## Work Log - 修复 `/users` 首屏卡在 Loading（2026-04-23）
- 背景：访问 `http://localhost:3000/users` 时，后台壳层页面一直停留在 `Loading admin workspace...`。
- 根因：
- `web/src/app/admin/layout.tsx` 的 `loadMenus` 仅处理了接口返回 `!ok` 场景；
- 当 `fetchWithAuth("/api/v1/admin/me/menus")` 发生网络异常（例如 API 未启动、连接失败）抛出异常时，没有兜底 `catch/finally`，导致 `loadingMenus` 一直为 `true`。
- 本次改动（最小闭环）：
- `web/src/app/admin/layout.tsx`
- `loadMenus` 增加 `try/catch/finally`。
- 异常场景下会：
- 清空 `menuTree`
- 设置 `menuError`（显示可见错误）
- 在 `finally` 中统一 `setLoadingMenus(false)`，避免页面卡死在 loading。
- 无用户场景补充 `setMenuError("")`，避免遗留错误文案。
- 验证：
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- 风险与影响：
- 仅涉及后台壳层菜单加载状态管理，不改接口契约与业务数据。
## Work Log - 默认 admin 视为全权限（2026-04-23）
- 背景：要求“默认 admin 有全部权限”。
- 现状定位：
- 后端接口鉴权已具备 `admin` 角色兜底（`require_permission/require_any_permission` 中 `if "admin" in role_codes: allow`）。
- 前端权限判定 `hasPermission` 仅判断 `permission_codes.includes(...)`，未对 `admin` 角色做兜底，可能导致 admin 页面按钮/入口被误隐藏。
- 本次改动（最小闭环）：
- `web/src/components/auth-provider.tsx`
- `hasPermission` 调整为：
- 若用户角色包含 `admin`，直接返回 `true`；
- 否则按原逻辑判断 `permission_codes`。
- 验证：
- 先清理 Next 类型缓存：`rm -rf web/.next`
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- 风险与影响：
- 仅影响前端可见性与交互开关判定，不改后端鉴权规则。
- 后端仍保持真实权限校验，前端放行不会绕过服务端安全边界。
## Work Log - 去掉登录后首页，直接进入后台（2026-04-23）
- 背景：要求“去掉首页，登录完成直接进入后台”。
- 本次改动（最小闭环）：
- `web/src/app/page.tsx`
- 移除已登录态的首页欢迎面板（欢迎文案 / Ping / 快捷入口）。
- 新增登录态跳转：当 `!initializing && user` 时执行 `router.replace("/dashboard")`。
- 已登录时仅短暂显示“正在进入后台...”，避免闪现旧首页内容。
- `web/src/app/admin/layout.tsx`
- 未登录访问后台时按钮文案从“返回首页”调整为“前往登录”（`/`）。
- 账号下拉中的“返回首页”调整为“后台首页”（`/dashboard`）。
- 验证：
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- 风险与影响：
- 仅涉及前端路由与文案，不改后端接口与鉴权逻辑。
## Work Log - 右上角账号入口改为 Avatar（2026-04-23）
- 背景：要求“右上角账号改成 avatar 组件”。
- 本次改动（最小闭环）：
- `web/src/app/admin/layout.tsx`
- 顶部账号下拉触发器由“账号”按钮改为 AntD `Avatar`。
- 头像文案取当前用户名首字母（大写），空值兜底 `U`。
- 保持原下拉菜单项不变（账号信息、后台首页、退出登录）。
- 验证：
- `npm --workspace web exec tsc --noEmit --pretty false` -> 通过。
- 风险与影响：
- 仅涉及前端展示与交互入口样式，不改业务逻辑与接口调用。
Reference in New Issue View Git Blame Copy Permalink