fquiz/memory/2026-04-22.md

## Work Log - 外部 PostgreSQL 连接切换（2026-04-22）

- 背景：按“改成连外部 PG 库”要求，将 API 默认数据库连接从 compose 内 `db` 服务切换为外部 PostgreSQL，并保留本地 `db` 容器为可选能力。

- 本次改动（最小闭环）：
  - `api/app/core/config.py`
    - 新增 `DB_HOST/DB_PORT/DB_NAME/DB_SCHEMA/DB_USERNAME/DB_PASSWORD` 配置项。
    - `DATABASE_URL` 改为可选覆盖项；未设置时自动由 `DB_*` 组装 PostgreSQL DSN。
  - `api/app/core/database.py`
    - 统一使用 `settings.resolved_database_url` 建连。
    - PostgreSQL 场景注入 `options=-csearch_path=<DB_SCHEMA>`，对齐 `currentSchema` 语义。
  - `docker-compose.yml`
    - `api` 移除对 `db` 的强依赖（不再 `depends_on db`）。
    - `api` 注入 `DB_*` 外部库环境变量，`DATABASE_URL` 作为可选覆盖。
    - `db` 服务改为 `profiles: [local-db]`，默认不启动。
  - `.env.example`
    - 数据库示例变量切换为外部库口径（含 `DB_*`）。
  - `README.md`
    - 更新 compose 启动说明：默认外部库；本地 DB 需显式 `--profile local-db`。

- 验证：
  - `python3 -m py_compile api/app/core/config.py api/app/core/database.py` -> `py_compile_ok`
  - `docker compose config` -> `compose_config_ok`，解析结果含 `DB_HOST/DB_PORT/DB_NAME/DB_SCHEMA/DB_USERNAME` 且 `DATABASE_URL` 允许为空覆盖。

- 风险与影响：
  - 默认 `docker compose up --build -d` 不再自动启动本地 DB；需要本地库时必须显式启用 `local-db` profile。
  - 若外部库网络不通或凭据错误，API 启动后会因数据库不可达报错；可通过设置 `DATABASE_URL` 快速回退到其他连接串。

## Work Log - 登录页动效改造（2026-04-22）

- 背景：用户要求登录页增强动效，增加“动态小怪兽 + 眼睛跟随鼠标 + 输入密码时挪开视线”的交互。

- 本次改动（最小闭环，仅改前台首页）：
  - `web/src/app/page.tsx`
    - 保留既有登录/注册提交链路（`login/register`）、记住密码逻辑与错误处理，不改接口契约。
    - 新增怪兽视线状态：`gaze` + `monsterRef` + `pointermove` 监听，实现眼球跟随鼠标。
    - 新增密码聚焦状态：`passwordFocused`；密码输入框 `onFocus/onBlur` 驱动怪兽“挪开视线”（瞳孔偏移 + 眼睑下落 + 身体倾斜）。
    - 重做未登录页视觉：浮动渐变背景、怪兽悬浮动画、阴影脉冲动画，并保持桌面/移动端自适应布局。

- 验证：
  - `cd web && npx eslint src/app/page.tsx` -> 通过（0 error）。
  - `npm run lint:web` -> 失败（仓库已有历史问题，集中在 `admin/hot-search`、`admin/jwt-generator`、`admin/life-countdown`，与本次登录页改动无关）。

- 风险与影响：
  - 本次改动将动画样式内联在 `web/src/app/page.tsx` 的 `style jsx` 中，后续若首页风格继续扩展，建议再抽离到独立样式模块以降低单文件复杂度。

## Work Log - 前端组件库从 Radix UI 迁移到 Ant Design（2026-04-22）

- 背景：按“弃用 Radix UI，改成 Ant Design”要求，前端在不改业务逻辑前提下完成组件层迁移。

- 本次改动（最小闭环）：
  - 依赖迁移：
    - `web/package.json` 移除 `@radix-ui/themes`、`@radix-ui/react-dialog`、`@radix-ui/react-select`。
    - 新增 `antd` 依赖；根 `package-lock.json` 同步更新。
  - 兼容层落地：
    - 新增 `web/src/components/ui-antd.tsx`，提供 `Button/Card/Flex/Text/Heading/TextField/TextArea/Select/Dialog/DropdownMenu/Callout/Table/Checkbox/Theme` 兼容导出，底层改由 Ant Design 承接。
    - 新增 `web/src/types/antd.d.ts`（当前安装源下 `antd` 包不含 `.d.ts` 时的类型声明兜底）。
  - 批量替换：
    - `web/src/app/**` 与 `web/src/components/row-action-menu.tsx` 的 `@radix-ui/themes` 导入统一替换为 `@/components/ui-antd`。
    - `web/src/app/layout.tsx` 移除 `@radix-ui/themes/styles.css`，改为 `antd/dist/reset.css`，`Theme` 改由兼容层提供。

- 验证：
  - `npm run build:web` -> 通过（Next.js build + TypeScript + 静态页面生成全部成功）。

- 风险与影响：
  - 兼容层采用“Radix API 形态 + AntD 实现”策略，短期可稳定过渡；后续若需发挥 AntD 原生能力（如 Table 高级功能、Form 生态），建议分阶段把页面改为直接使用 AntD 原生 API，逐步下线兼容层。

## Work Log - 前端依赖残留清理（2026-04-22）

- 背景：用户要求“清理”组件库迁移后的残留依赖。

- 本次处理：
  - 清理校验范围统一为源码导入 + `web/package.json` + 根/子锁文件。
  - `web/package-lock.json` 已重新对齐 `web/package.json`，移除 `@radix-ui/*` 残留并保留 `antd` 依赖树。
  - 根 `package-lock.json` 未检出 `@radix-ui/*` 残留。
  - 已删除本地 `node_modules` 与 `web/node_modules`，避免此前安装异常产生的脏依赖目录影响后续排查。

- 验证：
  - `rg -n "@radix-ui/..." web/src web/package.json web/package-lock.json package-lock.json` 无命中。

- 说明：
  - 当前环境下多次 `npm install` 出现 `TAR_ENTRY_ERROR ENOENT`（Next 解包阶段），属于本地依赖安装层异常，不影响仓库内代码与锁文件的残留清理结论。

## Work Log - 需求管理兼容老工程表与逻辑（2026-04-22）

- 背景：按“用老工程 `quiz` 的需求表结构与流程逻辑改造 `fquiz`”要求，目标是在保留现有 `/api/v1/requirements` 可用的前提下，切换底层到老表并补齐老接口兼容。

- 本次改动（最小闭环）：
  - ORM 表结构改造（对齐老工程）：
    - `api/app/models/requirement.py`
      - `Requirement` 主表由 `requirements` 切换为 `project_requirement`。
      - 字段改为老口径：`title/project_name/git_url/branch/descr/result_msg/progress_percent/status/priority/create_date/create_user/update_date/update_user`。
      - 生命周期事件表切到 `project_requirement_log`（`RequirementEvent`）。
      - 保留 `requirement_comments` 作为现有 API 注释能力的兼容扩展，外键改指向 `project_requirement.id`。
  - 服务层逻辑改造（参考老工程）：
    - `api/app/services/requirement_service.py`
      - 状态集改为老口径：`PENDING_ANALYSIS/PENDING_REVIEW/PENDING_REVISION/OPEN/IN_PROGRESS/COMPLETED/CLOSED`。
      - 兼容映射：`CANCELLED -> CLOSED`。
      - 进度规则对齐老逻辑：`COMPLETED=100`；`PENDING_ANALYSIS/PENDING_REVIEW/PENDING_REVISION/OPEN=0`；其余区间归一化到 `0-100`。
      - `/api/v1/requirements` 仍可用：序列化层将老表字段映射回现有前端字段（`description<-descr`、`source<-git_url`、`module_name<-branch` 等）。
      - 事件列表改读 `project_requirement_log`，并将 `before_descr/after_descr/remark` 投影为 `payload_json`。
      - 新增 legacy 业务函数：`search/get/pending/update_status/analyze/review/lifecycle/history-options`。
  - 旧接口兼容层新增：
    - 新增 `api/app/api/project_requirement.py`，提供：
      - `POST /api/project/requirement/search`
      - `GET /api/project/requirement/get/{id}`
      - `GET /api/project/requirement/pending`
      - `POST /api/project/requirement/{id}/status`
      - `POST /api/project/requirement/{id}/analyze`
      - `POST /api/project/requirement/{id}/review`
      - `GET /api/project/requirement/{id}/lifecycle`
      - `GET /api/project/requirement/history-options`
    - `api/app/api/router.py` 改为组合路由：保留 `/api/v1/*`，并额外挂载 `/api/project/requirement/*`。
  - 前端类型与状态枚举兼容：
    - `web/src/types/auth.ts`：`RequirementStatus` 新增 `PENDING_REVIEW/CLOSED`；`RequirementEvent.id` 改为 `string`；`RequirementSummary` 补充 `result_msg/progress_percent/git_url/branch`。
    - `web/src/app/admin/requirements/page.tsx`
    - `web/src/app/admin/requirements/new/page.tsx`
    - `web/src/app/admin/requirements/[id]/page.tsx`
      - 状态文案/选项新增 `PENDING_REVIEW`、`CLOSED`；详情页状态流转映射同步老逻辑。

- 验证：
  - `python3 -m compileall api/app/services/requirement_service.py api/app/api/project_requirement.py api/app/models/requirement.py api/app/schemas/requirement.py api/app/api/router.py` -> 通过。
  - `npm --workspace web exec -- eslint src/app/admin/requirements/page.tsx src/app/admin/requirements/new/page.tsx src/app/admin/requirements/[id]/page.tsx src/types/auth.ts` -> 通过。
  - `npm run -s lint:web` -> 失败（仓库既有问题：`hot-search/jwt-generator/life-countdown` 等页面，非本次改造引入）。
  - 运行态接口自检未执行：当前环境缺少 `fastapi` 运行依赖（`ModuleNotFoundError: fastapi`），因此未做本地启动路由验证。

- 风险与影响：
  - 该改造面向“老表兼容”，若数据库中同时存在新旧两套需求表，后续数据归一需额外迁移策略。
  - 由于老表无显式 `assignee/reviewer/due_at` 字段，`/api/v1/requirements` 中对应字段目前为兼容占位（多数返回 `null`）。
  - `project_requirement_log` 在历史库中若字段口径有差异（例如时间列名或类型差异），需按实际库结构微调 ORM 映射。
- 增补兼容接口：`POST /api/project/requirement/{id}/design`（对应老工程 DESIGN 流程，保持 `PENDING_ANALYSIS` 并写入生命周期日志）。

## Work Log - 待办管理按 quiz 表与页面重构（2026-04-22）

- 背景：按“改用 quiz 的表，照抄 quiz 逻辑和页面”要求，对 `fquiz` 待办模块做整链路重构（后端表结构/状态机/API + 前端页面交互）。

- 本次改动（最小闭环）：
  - 后端表结构与字段口径对齐 `quiz`：
    - `api/app/models/todo.py`
      - 表名由 `todos` 改为 `todo`。
      - 主键改为 32 位 hex 字符串（`uuid4().hex`）。
      - 字段切换为 `title/descr/status/priority/start_time/due_date/expire_time/calendar_event_id/create_date/create_user/update_date/update_user`。
      - 索引对齐：`idx_todo_status/idx_todo_priority/idx_todo_due_date/idx_todo_expire_time`。
  - 后端 schema 与服务逻辑重构：
    - `api/app/schemas/todo.py`
      - 状态改为 `SCHEDULED/IN_PROGRESS/COMPLETED/CANCELLED/EXPIRED`。
      - 优先级改为 `LOW/MEDIUM/HIGH`。
      - 请求/响应字段改为 quiz 风格（`descr/start_time/due_date/expire_time`）。
      - 新增 `TodoMindMapInitResponse`。
    - `api/app/services/todo_service.py`
      - 列表查询改为 quiz 逻辑：按当前登录用户名过滤 `create_user`，支持 `title/status/priority`，并支持分页参数 `page_num/page_size`。
      - 新增 owner 校验（非创建人不可读写删改）。
      - 新增 `complete_todo` 与 `init_todo_mindmap`。
      - 保留/兼容 `transition_todo`，状态流转规则切换到新状态机。
  - 后端路由补齐：
    - `api/app/api/v1/todos.py`
      - 列表接口支持 `title/status/priority/page_num/page_size`（兼容 `keyword`）。
      - 新增 `POST /api/v1/todos/{todo_id}/complete`。
      - 新增 `POST /api/v1/todos/{todo_id}/init-mindmap`。
  - 前端类型与页面重构：
    - `web/src/types/auth.ts`
      - `TodoStatus/TodoPriority/TodoSummary` 改为 quiz 字段与状态口径。
    - `web/src/app/admin/todos/page.tsx`
      - 页面按 quiz 交互重写：默认筛选 `SCHEDULED`、查询/重置、分页、新增、编辑、详情、完成、删除、分析（init-mindmap）。
      - 状态与优先级中文标签、完成态/过期态禁用“完成”按钮，行为与 quiz 页面一致。

- 验证：
  - `python3 -m py_compile api/app/models/todo.py api/app/schemas/todo.py api/app/services/todo_service.py api/app/api/v1/todos.py` -> 通过。
  - `cd web && npx eslint src/app/admin/todos/page.tsx src/types/auth.ts` -> 通过。

- 风险与影响：
  - 表名从 `todos` 切到 `todo`，若现网已落 `todos` 数据，需做数据迁移或并行兼容策略；当前实现按“以 quiz 表为准”直接切换。
  - `init-mindmap` 当前仅返回初始化结构（fquiz 目前无独立 mindmap 存储与编辑链路），页面侧做成功反馈，不做跳转编辑。

## Work Log - 思维导图按 quiz 表与逻辑落地（2026-04-22）

- 背景：按“用老工程表，参考老工程逻辑改造当前工程思维导图功能”要求，将 `fquiz` 的 `/admin/mindmap` 从题库统计复用页切回独立思维导图模块。

- 本次改动（最小闭环）：
  - 后端模型与路由新增：
    - `api/app/models/mind_map.py`
      - 新增老工程口径主表 `mind_map`（字段：`id/map_name/descr/map_data/create_date/create_user/update_date/update_user`）。
      - 索引对齐：`idx_mind_map_name`、`idx_mind_map_create_date`。
    - `api/app/schemas/mind_map.py`
      - 新增 `MindMapQueryRequest/MindMapCreateRequest/MindMapBasicInfoUpdateRequest/MindMapDataUpdateRequest`。
      - 新增 `MindMapSummary/MindMapPageResponse`。
    - `api/app/services/mind_map_service.py`
      - 新增 search/get/create/update-basic-info/update-data/delete 业务逻辑。
      - 新增 AI 流式生成：`stream_generate_mind_map`，输出 `[PARSE_RESULT]` + `[MINDMAP]{json}` 标记。
      - 新增初始化模板构造：`build_initial_mind_map_data(title)`。
    - `api/app/api/v1/mind_map.py`
      - 新增接口：
        - `POST /api/v1/mindmap/search`
        - `GET /api/v1/mindmap/get/{id}`
        - `POST /api/v1/mindmap/create`
        - `PUT /api/v1/mindmap/update-basic-info`
        - `PUT /api/v1/mindmap/update-data`
        - `DELETE /api/v1/mindmap/delete/{id}`
        - `GET /api/v1/mindmap/generate/stream`
      - 读接口权限：`question_bank.read | question_bank.manage`；
      - 写接口权限：`question_bank.manage`。
    - `api/app/api/router.py`、`api/app/core/database.py`、`api/app/models/__init__.py`
      - 注册 `mind_map` 模块与路由，确保启动建表与路由生效。

  - Todo 联动改造：
    - `api/app/services/todo_service.py`
      - `init_todo_mindmap` 从“仅返回初始化 JSON”改为“真实落库到 `mind_map`”：
        - 若同 `todo.id` 的导图存在则直接返回；
        - 不存在则按老逻辑以 `todo.id` 创建导图并返回。
    - `web/src/app/admin/todos/page.tsx`
      - `分析` 后改为跳转 `/admin/mindmap/edit/{id}`，与老工程链路一致。

  - 前端页面切换为独立思维导图：
    - `web/src/app/admin/question-bank/page.tsx`
      - 固化为原题库页面实现（不再从 `../mindmap/page` 复用导出）。
    - `web/src/app/admin/mindmap/page.tsx`
      - 改为思维导图列表页：查询、分页、新建、编辑基础信息、删除、进入绘图页。
    - `web/src/app/admin/mindmap/_components/mindmap-editor.tsx`
      - 新增编辑器：基础信息编辑、JSON 编辑、树预览、保存、导出 JSON/Markdown、AI 流式生成。
    - `web/src/app/admin/mindmap/edit/page.tsx`
    - `web/src/app/admin/mindmap/edit/[id]/page.tsx`
      - 新增新建/编辑路由承载页。
    - `web/src/types/auth.ts`
      - 新增 `MindMapSummary/MindMapListResponse` 类型。

  - 菜单与入口文案对齐：
    - `api/app/services/seed_service.py`
      - `admin.mindmap` 菜单名从“题库统计”改为“思维导图”。
    - `web/src/app/admin/page.tsx`
      - 后台首页入口文案改为“思维导图”。

- 验证：
  - `python3 -m py_compile api/app/models/mind_map.py api/app/schemas/mind_map.py api/app/services/mind_map_service.py api/app/api/v1/mind_map.py api/app/services/todo_service.py api/app/api/router.py api/app/core/database.py api/app/models/__init__.py` -> 通过。
  - `python3 -m compileall api/app` -> 通过。
  - 前端 lint/build 未完成：
    - `npx eslint ...` 受当前环境 npm 依赖解析影响失败（`Cannot find module 'next/dist/compiled/babel-packages'`）；
    - `npm run build:web` 受当前环境缺失 `next` 可执行文件影响失败（`next: not found`）。

- 风险与影响：
  - 当前编辑页采用 JSON 编辑 + 树预览实现，未引入老工程 `mind-elixir` 可视化拖拽编辑能力；若后续需要“节点拖拽/工具栏”体验，需单独引入前端图库并做适配。
  - 思维导图分组/标签/向量同步链路（老工程中的 group/tag/vector）本次未迁入，当前闭环聚焦 `mind_map` 主表与 Todo 联动。

## Work Log - Mermaid 按 quiz 表与页面重构（2026-04-22）

- 背景：按“改用 quiz 的表，照抄 guiz/quiz 逻辑和页面，重新改造 mermaid 功能”要求，将 `fquiz` 的 Mermaid 模块从“菜单复用 mdresolve”升级为独立 Mermaid 管理与编辑链路。

- 本次改动（最小闭环）：
  - 后端 Mermaid 接口落地（对齐 quiz 路径语义）
    - 新增 `api/app/api/v1/mermaids.py`：
      - `POST /api/v1/mermaids/diagrams/search`
      - `GET /api/v1/mermaids/diagrams/groups`
      - `GET /api/v1/mermaids/diagrams/get/{id}`
      - `POST /api/v1/mermaids/diagrams/create`
      - `PUT /api/v1/mermaids/diagrams/update`
      - `DELETE /api/v1/mermaids/diagrams/delete/{id}`
      - `PATCH /api/v1/mermaids/diagrams/{id}/data`
      - `GET /api/v1/mermaids/diagrams/generate/stream`
      - `POST /api/v1/mermaids/diagrams/chat/stream`
    - `api/app/api/router.py` 挂载 `mermaids_router` 到 `/api/v1`，并新增 legacy 兼容前缀 `/api/mermaids/diagrams/*`（对齐老页面直连习惯）。
  - Mermaid schema 兼容 quiz 请求字段
    - `api/app/schemas/mermaid.py`：为请求 DTO 增加 `validation_alias`，兼容 `camelCase` 与 `snake_case`（如 `diagramName/diagram_name`、`pageNum/page_num`、`diagramData/diagram_data`、`modelName/model_name`）。
  - Mermaid service 修正与增强
    - `api/app/services/mermaid_service.py`
      - 新增 `get_mermaid_diagram_summary`，统一单条详情序列化。
      - `create/update/patch-data` 统一复用 summary 返回。
      - 修复流式聊天系统提示组装缺陷（历史版本曾出现重复关键字问题）。
  - 前端页面重构（按 quiz 交互拆分管理页 + 编辑页）
    - `web/src/app/admin/mermaid-mgr/page.tsx`
      - 从 `mdresolve` 复用页改为独立 Mermaid 管理页。
      - 支持关键字/分组筛选、分页、新建、编辑、删除、详情预览、进入绘图。
    - `web/src/app/admin/mermaid-mgr/[id]/page.tsx`
      - 新增 Mermaid 编辑路由。
    - `web/src/app/admin/mermaid-mgr/_components/mermaid-editor.tsx`
      - 左侧 AI 对话流式改图，右侧预览，抽屉源码编辑，保存回写 `PATCH /{id}/data`。
    - `web/src/components/mermaid-viewer.tsx`
      - 新增 Mermaid 预览组件（通过 `mermaid.ink` SVG 渲染，避免本地依赖安装阻塞）。
  - 前端类型补齐
    - `web/src/types/auth.ts` 新增 Mermaid 相关类型：分组、图表摘要、分页响应、聊天消息。

- 验证：
  - `python3 -m py_compile api/app/schemas/mermaid.py api/app/models/mermaid_diagram.py api/app/models/object_group.py api/app/services/mermaid_service.py api/app/api/v1/mermaids.py api/app/api/router.py` -> 通过。
  - 前端 ESLint 未执行成功：当前环境 `eslint` 二进制缺失（`sh: 1: eslint: not found`），且 `npm --workspace web install` 过程中出现大量 tarball 校验重试，未形成可用依赖环境。

- 风险与影响：
  - Mermaid 预览当前走 `mermaid.ink` 在线渲染；若运行环境外网受限，预览图可能加载失败，但源码编辑与保存链路不受影响。
  - 当前工作区存在大量历史未提交改动；本次仅在 Mermaid 相关文件范围内追加改造，未处理既有脏改动。

## Work Log - 日程管理按 quiz 表与页面重构（2026-04-22）

- 背景：按“改用 quiz 的表结构，照抄 quiz 的逻辑和页面”要求，把 `fquiz` 的日程管理从“菜单复用 todo 页面”升级为独立日程模块。

- 本次改动（最小闭环）：
  - 后端表结构与接口落地：
    - 新增 `api/app/models/calendar_event.py`，表名 `calendar_event`，字段对齐 quiz：`title/descr/status/priority/start_time/end_time/expire_time/all_day/completed_at/todo_id/create_date/create_user/update_date/update_user`。
    - 新增 `api/app/schemas/calendar_event.py`（查询/创建/更新/分页响应 DTO）。
    - 新增 `api/app/services/calendar_event_service.py`（查询、增改删、完成、AI 流式生成、过期自动置 `EXPIRED`、与 todo 双向同步）。
    - 新增 `api/app/api/v1/calendar.py`，提供：
      - `POST /api/v1/calendar/search`
      - `GET /api/v1/calendar/get/{id}`
      - `POST /api/v1/calendar/create`
      - `PUT /api/v1/calendar/update`
      - `DELETE /api/v1/calendar/delete/{id}`
      - `POST /api/v1/calendar/{id}/complete`
      - `GET /api/v1/calendar/generate/stream`
    - `api/app/api/router.py` 挂载 `calendar_router`；`api/app/models/__init__.py` 与 `api/app/core/database.py` 增加 `calendar_event` 模型注册。
  - Todo 双向同步补齐：
    - `api/app/schemas/todo.py` 为 `TodoUpdateRequest/TodoTransitionRequest` 增加 `is_sync` 标记。
    - `api/app/services/todo_service.py` 的 `create/update/transition/complete/delete` 增加 `syncing` 参数并接入 `calendar_event_service` 同步函数，防止 schedule<->todo 循环调用。
  - 前端页面改造：
    - `web/src/app/admin/schedule/page.tsx` 从复用导出改为独立页面，实现 quiz 风格年/月/周视图、创建/编辑/删除/完成、AI 流式生成并回填表单。

- 验证：
  - `python3 -m compileall api/app/models/calendar_event.py api/app/schemas/calendar_event.py api/app/services/calendar_event_service.py api/app/api/v1/calendar.py api/app/services/todo_service.py api/app/schemas/todo.py api/app/api/v1/todos.py` -> 通过。
  - 前端 lint/build 未完全通过环境验证：
    - `cd web && npx eslint src/app/admin/schedule/page.tsx src/types/auth.ts` -> 失败（`eslint: not found`）。
    - `npm --workspace web install` 持续出现 `next` 解包 `TAR_ENTRY_ERROR ENOENT`，依赖环境未恢复，暂无法给出有效前端构建结论。

- 风险与影响：
  - 依赖环境异常会阻断前端 lint/build 验证，但不影响本次后端与页面代码改造落地。
  - 当前工作区存在大量历史脏改动；本次仅在日程与 todo 相关范围内追加改造，未触及其余模块。