## 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=`，对齐 `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 相关范围内追加改造，未触及其余模块。