Admin/fquiz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
472234035dfd5baa5ea587f2f074802f39354240
fquiz/MEMORY.md
T
chengkai3 472234035d 前端框架修改
2026-04-23 09:41:54 +08:00

29 KiB
Raw Blame History

MEMORY.md - fquiz 工程长期记忆

项目基线

  • 当前已完成 fquiz 子智能体骨架创建。
  • OpenClaw agent id：fquiz
  • Workspace：/root/.openclaw/workspace/fquiz
  • Agent dir：/root/.openclaw/agents/fquiz/agent

调度并发口径（程凯指定）

  • fquiz 默认调度并发：maxConcurrency=6。
  • 供派单技能读取时使用以下固定映射：
    • targetAgent=fquiz
    • dispatchProjectName=fquiz
    • maxConcurrency=6

约定

  • 在未明确项目技术栈、目录结构、部署方式前，避免把其他工程（如 quiz / nquiz）的具体规则直接套用到 fquiz。
  • 后续若 fquiz 绑定真实仓库或明确职责，应在此文件补充长期有效口径。
  • API 镜像构建阶段支持通过 PIP_INDEX_URL（Secrets/Variables）和 PIP_DEFAULT_TIMEOUT（Variables）调优 pip 拉包稳定性；默认索引为 https://pypi.org/simple。
  • web 目录用于 Docker 独立构建时，web/package.json 与 web/package-lock.json 必须保持同步；否则 web/Dockerfile 中的 npm ci 会因锁文件不一致直接失败（EUSAGE）。

模型管理口径（2026-04-12）

  • 模型业务引用键统一使用 code（llm_models.code），name 仅用于展示文案。
  • 模型状态机固定为：DRAFT/ENABLED/DISABLED/DEPRECATED，并遵循受限流转规则，禁止任意跳转。
  • 路由规则类型固定为：GLOBAL/CAPABILITY/BUSINESS/AGENT；其中 GLOBAL 保留 key 为 __global__。
  • 模型删除前必须做引用检查（至少检查路由规则引用）；ENABLED 状态禁止直接删除。
  • 密钥默认只保留 hash + masked + fingerprint，不通过 API 返回明文。

文件管理口径（2026-04-12）

  • 文件管理一期采用三层模型：
    • file_storage_backends（后端定义：VFS/S3）
    • file_storage_mounts（挂载点）
    • file_index_entries（目录索引快照）
  • 后台 API 入口统一在 /api/v1/admin/files 前缀，权限码为：
    • file.read：浏览挂载点和目录列表
    • file.manage：创建目录、删除路径
  • 存储驱动抽象位于 api/app/services/storage_driver.py，VFS/S3 必须通过同一工厂分发，避免业务层直接耦合具体存储 SDK。
  • VFS 默认根目录由 FILE_VFS_ROOT 控制（默认 ./data/vfs）。

启动与部署稳定性口径（2026-04-12）

  • SQLAlchemy 关联加载选项（selectinload/joinedload）避免在模块导入期以全局常量初始化，优先在函数内惰性构建，防止导入顺序导致 mapper 提前配置失败。
  • app.models 包初始化需预加载全部模型模块，确保字符串关系（如 "AuditLog"）在启动阶段可解析。
  • 部署 compose 中 DB 镜像应通过 POSTGRES_IMAGE 可配置，默认使用镜像站的 pgvector 镜像（docker.m.daocloud.io/pgvector/pgvector:pg16）。
  • 宿主机 DB 暴露端口统一走 POSTGRES_PORT（默认 5433），用于规避与宿主机已有 PostgreSQL（常见 5432）冲突；容器内连接仍保持 db:5432。
  • CORS 来源控制采用“双轨配置”：API_CORS_ORIGINS（精确列表）+ API_CORS_ORIGIN_REGEX（正则，可选）；API_CORS_ORIGINS 支持 * 和通配符域名并在后端转换为 allow_origin_regex。
  • GitHub Actions 使用 appleboy/ssh-action 部署时，慢网环境需显式设置 command_timeout（建议 45m）并为 docker compose pull 增加重试，避免出现 Run Command Timeout 直接中断发布。
  • docker compose up -d 不会重建 build 类型服务镜像；本项目 web 无源码挂载且运行 Next.js 生产构建产物，前端代码变更后需执行 docker compose up --build -d web（必要时先 docker compose build --no-cache web）。
  • api 构建若在拉取 docker.m.daocloud.io/library/python:3.11-slim 时出现 manifest EOF，优先重试 docker compose build api；若持续失败，可在 .env 覆盖 PYTHON_BASE_IMAGE=python:3.11-slim 走 Docker Hub 兜底。

前端视觉口径（2026-04-12）

  • 后台视觉基线采用 Slate + Indigo（浅色）风格，优先使用 web/src/app/globals.css 中统一样式类：
    • surface-card / surface-card-muted
    • notice + notice-error / notice-success
    • btn-primary / btn-secondary / btn-danger
    • control
    • table-modern / table-head / table-body
  • 字体基线：
    • 标题：Space Grotesk
    • 正文：Manrope
    • 等宽：JetBrains Mono

前端联调口径（2026-04-12）

  • NEXT_PUBLIC_API_BASE_URL 若误配为 loopback（127.0.0.1/localhost），前端运行时会在浏览器端自动改写为“当前页面主机 + 同端口（默认 8000）”，避免公网页面触发 PNA（Private Network Access）阻断。
  • 认证请求与 WebSocket 连接均统一复用该运行时 API 基址解析逻辑。

前端构建稳定性口径（2026-04-13）

  • web 在 Docker/受限网络环境构建时，避免使用 next/font/google（编译期需访问 fonts.googleapis.com，网络受限会导致 npm run build 失败）。
  • 字体基线应优先采用本地可用字体或仓库内自托管字体（next/font/local），并通过 CSS 变量维持 --font-heading / --font-body / --font-mono 约定，减少样式层连锁改动。
  • web/src/app/layout.tsx 应保持无 next/font/google 依赖，仅通过 web/src/app/globals.css 的 --font-* 变量声明字体栈；若后续引入新字体，优先走自托管或运行时回退方案。

前端组件类型兼容口径（2026-04-13）

  • 当前依赖组合下，@heroui/react 在仓库内会出现 Button/Input 等组件导出类型与常见属性（如 id/className/onPress）不一致的问题，可能导致 next build 的 TypeScript 阶段失败。
  • web/src/components/ui.tsx 已改为原生语义封装（button/input/checkbox）并保留现有样式类约定（btn-*、control）作为稳定兜底；同时 ListBox/Modal/Table 使用 HeroUI 运行时组件 + 宽松类型包装，避免 children 等声明缺口阻断构建。
  • @heroui/react 的 Table 在当前版本是分层组合组件：Table 仅作为外层容器，Table.Header/Body/Row/Column/Cell 必须置于 Table.Content 内部，否则运行时会触发 cannot be rendered outside a collection.。
  • 后续若要恢复 HeroUI 组件能力，先验证依赖版本和类型声明兼容性，再逐页替换，避免再次阻断 Docker 构建。

前端组件栈口径（2026-04-17）

  • 前端组件库基线已从 @heroui/react 切换到 shadcn/ui 风格封装 + Radix UI primitives。
  • 当前基础组件位于 web/src/components/ui/，统一通过 web/src/components/ui.tsx 对外导出（保留 @/components/ui 入口）。
  • todos 页面已完成首批迁移：筛选/表单选择器使用 Radix Select，弹窗使用 Radix Dialog，表格使用 shadcn 风格 Table 语义封装。
  • web 依赖口径：新增 @radix-ui/react-dialog、@radix-ui/react-select、class-variance-authority、clsx、tailwind-merge；移除 @heroui/react。
  • 后续页面迁移保持“业务逻辑不动，仅替换 UI 组件 API”的最小改动策略，并以 npm run build:web 为最终验收门禁。
  • 阶段 B（表单控件统一）已覆盖：/admin/requirements、/admin/requirements/new、/admin/requirements/[id]、/admin/menus、/admin/models、/admin/users；上述页面不再使用原生 select/textarea 与 control 样式输入，统一走 @/components/ui 的 Input/Select/TextArea 组件。
  • 阶段 B 收尾已完成：/admin/chat 的消息输入框已统一为 TextArea；当前 web/src/app/admin/** 已无原生 select/textarea 与 control 直连输入写法。
  • 阶段 C（弹窗统一）已完成：/admin/models 与 /admin/roles 的手写遮罩弹窗（fixed inset-0）已统一迁移为 @/components/ui 的 Dialog，并保留原有新建/编辑/关闭与提交行为。
  • 在当前 @radix-ui/themes + TS 配置下，TextField.Root / TextArea 的 onChange 处理函数应显式标注 ChangeEvent<HTMLInputElement | HTMLTextAreaElement>；否则 next build 的 TypeScript 阶段可能出现 Parameter implicitly has an 'any' type，且输入/文本域混用时会触发事件类型不兼容。

前端主题口径（2026-04-17）

  • 后台主题基线已切换到 Radix Themes：web/src/app/layout.tsx 必须注入 @radix-ui/themes/styles.css 与 <Theme ...> 根包裹。
  • 当前默认主强调色为 indigo（accentColor=\"indigo\"）；如需换肤优先调整 Theme 的 accentColor，并同步清理页面中的硬编码色值类。
  • web/src/app/globals.css 的语义类（surface-card / btn-* / control / table-*）统一基于 Radix token（--gray-* / --accent-* 等）实现；后续新增样式优先复用这些语义类，不再回退硬编码 slate/cyan 色值。
  • web/src/components/ui/* 的样式应优先通过语义类（如 dialog-content、select-content、checkbox-control）承接主题，确保后续仅改 token 即可全局换肤。
  • web Docker 构建基于 node:alpine 时，web/package-lock.json 必须保留 musl 可选依赖条目（至少 lightningcss-linux-x64-musl、@tailwindcss/oxide-linux-x64-musl）；缺失会在 next build 阶段触发 Cannot find module ...musl.node。

登录页与品牌文案口径（2026-04-18）

  • 站点品牌标题统一使用 Quiz：至少保持 web/src/app/layout.tsx 的 metadata.title 与首页主标题一致。
  • 登录页默认不展示 API Base URL，仅保留 getApiBaseUrl() 在请求链路中的能力（不影响鉴权与 API 调用逻辑）。

登录页动效口径（2026-04-22）

  • 登录页主视觉允许使用装饰性动效（如浮动背景与角色动画），但必须保持登录/注册接口调用链路与鉴权行为不变。
  • 首页怪兽交互基线：眼睛跟随鼠标，密码输入框聚焦时主动挪开视线（避免“盯着密码输入”观感）。
  • 当前实现位于 web/src/app/page.tsx；若后续继续扩展动效，优先抽离样式与展示组件，避免登录业务与视觉代码耦合过深。

AI 聊天口径（2026-04-13）

  • 一期聊天入口固定为后台路由 /admin/chat，权限码为 chat.use。
  • 聊天模型选择规则固定为：CAPABILITY: chat.default 优先，未命中时回退 GLOBAL: __global__。
  • 仅允许 ENABLED 且具备激活密钥记录的模型参与路由命中；若不满足，接口返回 400。
  • 运行时真实 Provider Key 不从数据库反解，统一从环境变量 LLM_PROVIDER_API_KEYS 注入（支持 openai=sk-... 或 JSON 字典字符串）。
  • 一期模型调用采用非流式 OpenAI-compatible POST /chat/completions，后续如需流式再扩展 SSE/WS。

前端 Radix 全量化口径（2026-04-18）

  • web/src/app/** 已完成“去语义类 + 组件全量 Radix 化”：不再依赖 surface-card / btn-* / control / table-* / notice* / text-muted 等自定义语义类。
  • 页面组件基线统一为 @radix-ui/themes：
    • 交互：Button / Checkbox
    • 输入：TextField.Root / TextArea / Select.Root
    • 表格：Table.Root + Header/Body/Row/ColumnHeaderCell/Cell
  • 工程约束更新：web/src/app 下默认不再引入原生 button/input/select/textarea/table 作为业务 UI（除非有明确无替代场景并单独说明）。
  • web/src/app/globals.css 仅保留基础排版与 Radix token 基线，不再承载语义组件样式层。

前端上传控件类型口径（2026-04-18）

  • 在当前 @radix-ui/themes 类型定义下，TextField.Root 的 type 联合不包含 file。
  • 文件上传场景应使用原生 <input type="file">（可配合主题 token 做样式），避免在 next build 的 TypeScript 阶段触发类型错误。

前台组件选型优先级（程凯指定，2026-04-18）

  • 前台页面组件默认优先使用 Radix UI（含 @radix-ui/themes 与 Radix primitives）。
  • 仅当 Radix 体系内没有合适组件时，才使用其他组件方案。
  • 引入非 Radix 组件时，优先最小依赖与最小改动，并保持现有主题与交互风格一致。

菜单迁移口径（2026-04-18）

  • 日程管理 菜单已升级为独立日程模块：保留菜单 admin.schedule（/admin/schedule，权限 todo.read），前端由 web/src/app/admin/schedule/page.tsx 承载年/月/周视图、编辑、完成、AI 生成交互，不再复用 todos 页面。
  • admin.schedule 已加入后端与前端受保护菜单集合，避免在菜单管理中被误删。
  • 家庭作业 菜单迁移采用最小改动策略：新增菜单 admin.homework（/admin/homework，权限 question_bank.read），并直接复用 question-bank 页面能力作为家庭作业承载。
  • admin.homework 已加入后端与前端受保护菜单集合，避免在菜单管理中被误删。
  • 作业监控 菜单迁移采用最小改动策略：新增菜单 admin.job_mgr（/admin/job，权限 question_bank.read），并由 web/src/app/admin/job/page.tsx 复用 question-bank 页面能力承载作业监控交互。
  • admin.job_mgr 已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口，避免在菜单管理中被误删。
  • 题库统计 菜单迁移采用最小改动策略：新增菜单 admin.mindmap（/admin/mindmap，权限 question_bank.read），并复用现有题库统计承载页面能力。
  • admin.mindmap 已加入后端默认菜单绑定与前端后台首页入口，确保菜单可见且可直达。
  • 诗词本 菜单迁移沿用词条能力：保留菜单编码 admin.vocabulary 与权限 vocabulary.read，菜单文案统一为“诗词本”，默认路由为 /admin/poetry，并由 web/src/app/admin/poetry/page.tsx 复用 vocabulary 页面实现。
  • 价格监控 菜单迁移沿用 Token 统计能力：保留菜单编码 admin.token_usage 与权限 model.read，菜单文案统一为“价格监控”，默认路由为 /admin/price-monitor，并由 web/src/app/admin/price-monitor/page.tsx 复用 token-usage 页面实现。
  • API测试 菜单迁移沿用模型测试能力：新增菜单编码 admin.api_tester（/admin/api-tester，权限 model.read），由 web/src/app/admin/api-tester/page.tsx 复用 models 页面承载“冒烟测试/对话测试/测试记录”能力；并已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口。
  • 模型管理 菜单迁移沿用既有模型能力：保留菜单编码 admin.models（/admin/models，权限 model.read/model.manage），继续由 web/src/app/admin/models/page.tsx 承载模型台账、状态流转、路由规则、密钥轮换、健康检查与测试能力；并已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口。
  • 流程图 菜单已切回独立 Mermaid 管理能力：菜单编码 admin.mermaid_mgr（/admin/mermaid-mgr，权限 question_bank.read），前端由 web/src/app/admin/mermaid-mgr/page.tsx 承载列表/分组/新建编辑删除，编辑页为 web/src/app/admin/mermaid-mgr/[id]/page.tsx（AI 流式改图 + 预览 + 保存）；后端接口对齐 quiz 路径：/api/v1/mermaids/diagrams/*，并兼容 /api/mermaids/diagrams/* legacy 前缀。
  • 上帝视角 菜单迁移沿用系统日志能力：新增菜单编码 admin.diary（/admin/diary，权限 menu.read），由 web/src/app/admin/diary/page.tsx 复用 syslog 页面承载审计日志查询能力；并已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口。
  • 待办管理 菜单迁移采用最小改动策略：保留菜单编码 admin.todos（/admin/todos，权限 todo.read），并沿用现有 todos 页面能力承载待办管理完整交互（筛选、创建、状态流转、删除）。
  • 队列管理 菜单迁移采用最小改动策略：新增菜单编码 admin.queue_mgr（/admin/jobqueue，权限 todo.read），并由 web/src/app/admin/jobqueue/page.tsx 复用 todos 页面能力承接队列任务清单管理；已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口。
  • 试题管理 菜单迁移采用最小改动策略：保留菜单编码 admin.question_bank（/admin/question-bank，权限 question_bank.read），菜单文案统一为“试题管理”；前端后台首页入口文案同步为“试题管理”，并继续复用现有题库题目管理页面能力（列表、筛选、编辑、状态流转、标签管理）。
  • 分组管理 菜单迁移沿用标签能力：保留菜单编码 admin.tag 与权限 question_bank.read，菜单文案统一为“分组管理”，默认路由迁移为 /admin/group，并由 web/src/app/admin/group/page.tsx 复用 tag 页面承载分组检索、重命名与解除关联能力。
  • 知识点管理 菜单迁移沿用标签能力：新增菜单编码 admin.knowledge_point_mgr（/admin/knowledge，权限 question_bank.read），并由 web/src/app/admin/knowledge/page.tsx 复用 tag 页面承载知识点检索、重命名与解除关联能力；已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口。
  • MCP管理 菜单迁移沿用模型编排能力：新增菜单编码 admin.mcp_server（/admin/mcp-server，权限 model.read），并由 web/src/app/admin/mcp-server/page.tsx 复用 models 页面承载模型/路由规则管理能力；已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口。
  • 菜单管理 菜单迁移沿用现有后台菜单能力：保留菜单编码 admin.menus（/admin/menus）、权限 menu.read/menu.manage 与前后端 CRUD/树形查询接口（/api/v1/admin/menus*）不变，继续由 web/src/app/admin/menus/page.tsx 承载菜单筛选、新建、编辑、删除与受保护菜单拦截能力。
  • 微信小程序 菜单迁移采用最小改动策略：新增菜单编码 admin.wxapp（/admin/wxapp，权限 system_param.read），并由 web/src/app/admin/wxapp/page.tsx 复用 system-params 页面能力承载微信小程序配置项维护。
  • admin.wxapp 已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口，确保可见、可达且不被误删。
  • 单词统计 菜单迁移采用最小改动策略：保留菜单编码 admin.knowledge_mastery（/admin/vocabulary-proficiency，权限 vocabulary.read），并由 web/src/app/admin/vocabulary-proficiency/page.tsx 承载词条总量、状态分布、缺失字段与最近更新趋势统计能力；已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口。
  • 队列管理 菜单迁移采用最小改动策略：新增菜单编码 admin.queue_mgr（/admin/jobqueue，权限 todo.read），并由 web/src/app/admin/jobqueue/page.tsx 复用 todos 页面承载队列任务清单能力；已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口。
  • 提示词管理 菜单迁移沿用系统消息能力：保留菜单编码 admin.system_message 与权限 system_message.read/system_message.manage，菜单文案统一为“提示词管理”，默认路由迁移为 /admin/prompt，并由 web/src/app/admin/prompt/page.tsx 复用 system-message 页面承载提示词内容、等级、有效期与发布状态维护能力。
  • 历史答卷 菜单迁移采用最小改动策略：保留菜单编码 admin.history（/admin/history，权限 question_bank.read），并由 web/src/app/admin/history/page.tsx 复用 question-bank 页面承载历史答卷查询与管理能力；已加入后端与前端受保护菜单集合与后台首页入口。
  • 脚本管理 菜单迁移采用最小改动策略：保留菜单编码 admin.cron_task_mgr（/admin/cron，权限 todo.read），菜单文案统一为“脚本管理”，并继续由 web/src/app/admin/cron/page.tsx 复用 todos 页面承载脚本任务清单能力。
  • 百度网盘 菜单迁移采用最小改动策略：新增菜单编码 admin.baidu_pan（/admin/baidu-pan，权限 file.read），并由 web/src/app/admin/baidu-pan/page.tsx 复用 files 页面承载目录浏览、上传、重命名、移动、删除与下载能力；已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口。
  • 文件识别 菜单迁移采用最小改动策略：新增菜单编码 admin.filedetector（/admin/filedetector，权限 file.read），并由 web/src/app/admin/filedetector/page.tsx 复用 files 页面承载目录浏览、上传、重命名、移动、删除与下载能力；已加入后端与前端受保护菜单集合、admin 默认菜单绑定与后台首页入口。
  • 热搜 菜单迁移采用最小改动策略：新增菜单编码 admin.hot_search（/admin/hot-search，权限 menu.read），并由 web/src/app/admin/hot-search/page.tsx 复用 data-query 页面承接热搜入口；后端同步提供 /api/v1/admin/hot-search 记录检索与关注主题能力（api/app/api/v1/hot_search.py + api/app/services/hot_search_service.py + api/app/models/hot_search.py）作为后续独立热搜交互能力底座。

前端主题纯化口径（2026-04-18）

  • web/src/app/globals.css 保持最小化：仅保留 Tailwind 导入与基础全局规则，不再承载字体栈覆盖、Radix token 二次映射、装饰性渐变背景。
  • web/src/app/layout.tsx 只负责注入 @radix-ui/themes/styles.css 与 Theme Provider，不再通过根容器类叠加自定义主题视觉。
  • web/src/app/admin/layout.tsx 使用 Radix Themes 组件（Card/Flex/Text/Heading/Button/Callout）组织后台壳层，避免硬编码品牌色光斑与渐变块。
  • web/src/app/** 中 Button 视觉优先通过 variant / color / size 控制；不再使用长 Tailwind 颜色类拼接按钮主题。

前端菜单交互口径（2026-04-19）

  • 后台壳层（web/src/app/admin/layout.tsx）已采用 @radix-ui/themes 的 DropdownMenu 承接菜单交互：
    • 移动端（md 以下）菜单入口统一为“菜单”下拉，不再直接渲染左侧长列表；
    • 顶部账号区“返回首页/退出登录”统一收口到“账号”下拉。
  • 后台表格行内“操作”入口推荐统一为下拉菜单形态，优先复用 web/src/components/row-action-menu.tsx，避免页面内重复堆叠小按钮并降低操作列宽度波动。
  • Phase B 样板页已落地：/admin/users、/admin/requirements、/admin/menus；后续页面迁移默认保持“业务逻辑不动，仅替换操作入口承载组件”的最小改动策略。

数据库连接口径（2026-04-22）

  • API 默认数据库连接改为外部 PostgreSQL：优先读取 DATABASE_URL；若未设置则由 DB_HOST/DB_PORT/DB_NAME/DB_USERNAME/DB_PASSWORD 组装。
  • DB_SCHEMA 通过 PostgreSQL search_path 注入，语义等价 JDBC 的 currentSchema。
  • docker compose 中本地 db 服务改为 local-db profile（默认不启动）；仅在需要本地库时显式 docker compose --profile local-db up -d。
  • API 启动初始化口径：seed_defaults 仅对本地数据库目标执行（db/localhost/127.0.0.1/::1 或 DATABASE_URL 指向本地）；非本地目标跳过默认数据写入，避免对外部库做不兼容初始化。
  • 用户表兼容口径：用户主键列对齐旧库 users.user_id，与用户关联的外键统一引用 users.user_id（不再引用 users.id）。

前端组件栈口径（2026-04-22）

  • 组件库基线从 Radix UI 切换为 Ant Design，web 依赖已移除 @radix-ui/themes / @radix-ui/react-dialog / @radix-ui/react-select，新增 antd。
  • 为控制迁移范围，新增兼容层 web/src/components/ui-antd.tsx：对外保持 Button/Card/Flex/Text/Heading/TextField/TextArea/Select/Dialog/DropdownMenu/Callout/Table/Checkbox/Theme API 形态，内部使用 AntD 实现。
  • web/src/app/layout.tsx 统一注入 antd/dist/reset.css，并通过兼容层 Theme 提供全局主题 token。
  • 工程约束更新：
    • 页面/组件禁止继续新增 @radix-ui/themes 导入；
    • 优先从 @/components/ui-antd 引入 UI 组件；
    • 新增页面如需 AntD 高级能力，可直接引入 antd，但需保持与现有主题和交互风格一致。
  • 兼容说明：web/src/types/antd.d.ts 仅保留 antd/dist/reset.css 声明，禁止再写 declare module "antd"；否则会覆盖官方类型并导致 Form.useForm<T> 等泛型调用在 next build 的 TypeScript 阶段失败。
  • web/src/components/ui-antd.tsx 作为兼容层时，若自定义 type/variant/size/checked 等语义，必须先 Omit 掉对应 AntD 原生同名字段再重定义，否则会触发联合类型冲突并阻断 Docker 构建。

需求管理兼容口径（2026-04-22）

  • 需求管理底层表结构已切换为老工程口径：
    • 主表：project_requirement
    • 生命周期表：project_requirement_log
  • fquiz 需求模块保持“双接口并行”策略：
    • 现有前端接口：/api/v1/requirements*
    • 老工程兼容接口：/api/project/requirement/*（search/get/status/analyze/review/lifecycle/history-options/pending）

思维导图兼容口径（2026-04-22）

  • 思维导图已从“题库统计复用页”切回独立模块，后端主表固定为老工程口径 mind_map。
  • API 入口统一采用老工程风格路径（挂在 /api/v1 下）：
    • 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
  • Todo 分析链路已恢复老逻辑：POST /api/v1/todos/{todo_id}/init-mindmap 会真实创建/复用 mind_map(id=todo_id) 并返回导图信息，前端跳转到 /admin/mindmap/edit/{id}。
  • 当前前端编辑器基线为“JSON 编辑 + 树预览 + AI 流式生成 + JSON/Markdown 导出”；如需老工程 mind-elixir 的可视化拖拽编辑，需单独引入并适配 AntD/Next 页面栈。
  • 状态机口径对齐老工程：PENDING_ANALYSIS -> PENDING_REVIEW/PENDING_REVISION/OPEN -> IN_PROGRESS -> COMPLETED/CLOSED；并兼容映射 CANCELLED -> CLOSED。
  • 优先级口径对齐老工程存储：数据库落库使用大写 LOW/MEDIUM/HIGH；API 层兼容小写输入并向前端返回小写展示值。
  • 旧表不包含 assignee/reviewer/due_at 等字段，/api/v1/requirements 中这些字段当前作为兼容占位返回，后续如需恢复需补扩展表或业务映射策略。
  • 老工程兼容接口补充 POST /api/project/requirement/{id}/design，用于需求设计阶段回写（PENDING_ANALYSIS 内部闭环）。

待办管理兼容口径（2026-04-22）

  • 待办模块已切换到 quiz 表口径：api/app/models/todo.py 使用 todo 表（非 todos），字段为 title/descr/status/priority/start_time/due_date/expire_time/calendar_event_id/create_date/create_user/update_date/update_user。
  • 状态机与优先级固定为：
    • 状态：SCHEDULED/IN_PROGRESS/COMPLETED/CANCELLED/EXPIRED
    • 优先级：LOW/MEDIUM/HIGH
  • /api/v1/todos 查询口径对齐 quiz：默认按当前登录用户 create_user 过滤，仅返回本人待办；支持 title/status/priority/page_num/page_size。
  • 待办扩展接口口径：
    • POST /api/v1/todos/{todo_id}/complete：完成待办（置 COMPLETED）
    • POST /api/v1/todos/{todo_id}/init-mindmap：创建或复用 mind_map(id=todo_id) 并返回导图详情
  • 前端 web/src/app/admin/todos/page.tsx 已按 quiz 交互重构：默认状态筛选 SCHEDULED、分页列表、新增/编辑/详情、分析、完成、删除；jobqueue/cron 继续复用该页面。

日程管理兼容口径（2026-04-22）

  • 日程模块已切换到 quiz 表口径：api/app/models/calendar_event.py 使用 calendar_event 表，字段为 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 固定为：
    • 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
  • 日程与待办保持双向同步：
    • 日程创建/更新/删除/完成会同步到 todo
  • 待办创建/更新/删除/状态流转会同步到 calendar_event
  • 通过 is_sync/syncing 标记防止递归回环。

日记管理兼容口径（2026-04-23）

  • admin.diary 已从系统日志复用页切换为独立 Diary 模块，后端主表固定为老工程口径 diary。
  • Diary 表字段口径：id/title/content/diary_date/mood/weather/archived/create_date/create_user/update_date/update_user，并保留 create_user 维度隔离查询。
  • API 入口统一采用老工程风格路径（挂在 /api/v1 下）：
    • 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=...
  • 查询逻辑对齐老工程：支持 title/mood/diary_date_start/diary_date_end/archived 过滤，排序 diary_date DESC, create_date DESC。
  • 当前权限沿用兼容口径：
    • 读：menu.read | menu.manage
    • 写：menu.manage 后续若需细粒度可拆分 diary.read/diary.manage。
Reference in New Issue View Git Blame Copy Permalink