Files

T

chengkai3 a9a2d32fd5 [feat]:[FL-154][系统消息页面一致性优化]

Co-authored-by: multica-agent <github@multica.ai>

2026-06-20 07:00:47 +08:00

88 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（默认 5434），用于规避与宿主机已有 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 直接中断发布。
生产发布默认不再依赖 ghcr.io：工作流镜像仓库统一通过 REGISTRY / REGISTRY_NAMESPACE 控制，默认指向阿里云个人版容器仓库 crpi-u265r07n4blchcqo.cn-shanghai.personal.cr.aliyuncs.com/ck-registry；CI 与远端部署均使用 REGISTRY_USERNAME / REGISTRY_PASSWORD 登录同一仓库，避免服务器侧访问 GHCR 出现 Get "https://ghcr.io/v2/": EOF。
GitHub Actions 若继续使用 docker/setup-buildx-action 默认 docker-container 驱动，BuildKit builder 会先拉 moby/buildkit:buildx-stable-1；在当前网络条件下应显式通过 driver-opts 指向镜像站（当前口径：docker.m.daocloud.io/moby/buildkit:buildx-stable-1），避免安装 Buildx 阶段因 Docker Hub 超时直接失败。
docker compose up -d 不会重建 build 类型服务镜像；开发链路默认使用 deploy/dev-deploy/compose.yml，前端代码变更后需执行 docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml up --build -d web（必要时先 docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml build --no-cache web）。
api 构建若在拉取 docker.m.daocloud.io/library/python:3.11-slim 时出现 manifest EOF，优先重试 docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml build api；若持续失败，可在 deploy/dev-deploy/.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 基址解析逻辑。
NEXT_PUBLIC_API_BASE_URL 必须只配置“协议 + 主机 + 可选端口”，不要额外带 /api 前缀；当前前端请求路径已自行拼接 /api/v1/...，若环境变量写成 https://host/api 会落成 /api/api/v1/...。
通过 IP:3000 直接访问站点时，后端 API_CORS_ORIGINS 必须显式包含该页面 origin（例如 http://223.109.142.84:3000）；仅放行正式域名会导致浏览器在登录预检阶段返回 Disallowed CORS origin。
生产若通过公网 IP:3000 暴露前端，而公网 8000 不可直达，则应由入口反代统一承接：浏览器端对 loopback API 基址一律回落到当前站点 origin，/api/* 与 /api/v1/ws 通过部署层反代到 api:8000，避免浏览器直接访问 host:8000。

前端构建稳定性口径（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-* 变量声明字体栈；若后续引入新字体，优先走自托管或运行时回退方案。
Next.js App Router 的 web/src/app/**/page.tsx 只能导出约定字段（default、metadata 等）；不要在页面文件里额外导出可复用组件。可复用页面主体应放在同目录独立文件（如 *-content.tsx），页面文件仅做无参默认导出包装，避免 next build TypeScript 阶段报 invalid "default" export / OmitWithTag 错误。
Cesium 1.140.0 依赖链中的 @spz-loader/core@0.3.1 会把 WASM 二进制以内联模板字符串打进浏览器 chunk，并触发 Octal escape sequences are not allowed in template strings；当前项目不使用 SPZ/Gaussian splats，前端构建通过 web/next.config.ts 将 @spz-loader/core alias 到 web/src/lib/spz-loader-core-shim.ts，保留常规 Cesium Viewer/Entity 能力，禁用 SPZ 解码。

前端组件类型兼容口径（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/login/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。

Celery 监控口径（2026-05-01）

Celery 监控采用“双页面”：
- Worker监控：/admin/workers（聚焦 worker 在线状态、并发、队列、单 worker 任务快照）
- 任务监控：/admin/task-monitor（聚焦全局任务状态分布、队列积压、任务明细）
Worker 监控 API 入口：
- GET /api/v1/admin/workers/overview
- GET /api/v1/admin/workers/tasks?worker=...&recent_limit=...
两页统一复用权限码：celery.read / celery.manage。

调度与监控口径（2026-05-02）

调度链路已统一为 API 直连 Celery（不再保留独立 scheduler 服务与 SCHEDULER_API_* 配置）：
- Web 任务调用 API 业务接口后，由后端服务层直接 .delay() 入队。
- 任务执行与定时触发继续由 celery-worker / celery-beat 负责。
监控能力统一走 Flower 代理：
- 后端代理入口：
  - GET /api/v1/admin/flower/workers
  - GET /api/v1/admin/flower/worker-tasks
- 前端 Worker监控 与 任务监控 页面都通过后端代理读取 Flower 数据，不直接连 Flower。
Worker 自动注册机制：
- Celery worker 启停/心跳通过 signals 写入 worker_registry 表。
- Beat 定时任务 app.tasks.worker_registry_tasks.sweep_worker_registry_offline 负责离线兜底标记。
Flower 代理鉴权一致性：
- api 服务必须显式注入 FLOWER_BASIC_AUTH（与 flower 服务保持同一来源），避免 /api/v1/admin/flower/* 代理调用因 Basic Auth 不一致返回 401 并在前端表现为 502。
Flower worker 详情查询兼容：
- 当前 Flower 版本下，/api/workers?...&workername=... 可能返回 404 Unknown worker（即使 worker 在线且 /api/tasks?workername=... 可用）。
- 后端代理查询 worker 明细时应避免依赖该过滤接口，优先读取 workers 全量快照后本地匹配 worker，避免误映射为 502。

Legacy 鉴权兼容口径（2026-05-03）

鉴权服务在访问 legacy 表（user_role_rela / role_menu_rela / menu / user_role）前应先做 to_regclass 存在性判断。
当 legacy 表缺失（modern-only 数据库）时，直接返回空并走 modern 回退逻辑，避免持续 relation does not exist 日志与事务回滚。

前端 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 默认菜单绑定与后台首页入口。
提示词管理 菜单能力已于 2026-04-26 下线：/admin/prompt、/admin/system-message、system_message.read/system_message.manage 与 /api/v1/admin/system-messages* 均不再作为有效功能入口；历史数据库表不主动删除。admin.system_message 已恢复为“系统消息”菜单权限码，当前有效路由为 /admin/system-messages，接口入口为 /api/v1/system-messages*。
系统消息个人列表 GET /api/v1/system-messages/me 支持可选 message_type=info|warning|error|success 筛选；响应 total 跟随当前筛选条件，unread_count 保持当前用户全局未读数，用于顶部未读徽标。
收件箱、代码评审、Git管理 功能已于 2026-04-26 下线：admin.inbox、admin.code_review、admin.git_desktop 仅保留在 removed/disabled 过滤集合中，用于屏蔽存量菜单；前端路由 /admin/inbox、/admin/code-review、/admin/git-desktop 不再提供页面。
历史答卷 菜单迁移采用最小改动策略：保留菜单编码 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-25）

主页面与系统页面滚动条样式统一收敛到 web/src/app/globals.css 的全局基线：
- * 统一声明 scrollbar-width 与 scrollbar-color（覆盖 Firefox 等非 WebKit 浏览器的所有滚动容器）。
- *::-webkit-scrollbar* 统一声明轨道/滑块样式（覆盖 Chromium/WebKit）。
.scrollbar-antd 仅保留 scrollbar-gutter: stable，不再重复定义颜色与尺寸，避免局部样式与全局基线漂移。

Wine 执行器口径（2026-04-25）

Windows EXE 调用能力统一由后端 /api/v1/wine/* 承接，权限码为 wine.read / wine.manage。
Wine 运行参数通过环境变量控制：
- WINE_BINARY_PATH：Wine 可执行文件路径或命令名，默认 wine。
- WINE_ALLOWED_ROOT：允许执行/工作目录根路径，默认 ./data/wine。
- WINE_DEFAULT_TIMEOUT_SECONDS / WINE_MAX_TIMEOUT_SECONDS：默认与最大执行超时。
后端执行必须使用 asyncio.create_subprocess_exec 参数数组，不走 shell；EXE 路径与工作目录必须限制在 WINE_ALLOWED_ROOT 下。
实时日志通过 StreamingResponse + SSE 事件输出；前端使用 fetchWithAuth 读取 ReadableStream，避免原生 EventSource 无法携带现有 Bearer Token 的鉴权问题。
api/Dockerfile 构建出的共享后端镜像已内置 wine + wine32:i386；api/celery-worker/celery-beat/flower 当前都复用该镜像，若需切换二进制仍可通过 WINE_BINARY_PATH 覆盖。
Wine / ATP 的状态探测口径中，若 wine --version 输出包含 wine32 is missing，必须标记为不可用，避免前端把半可用环境误显示为“可用”。

前端菜单交互口径（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-06-08）

全局瞬时成功/失败反馈统一使用 Ant Design message，展示在页面右上角，并在短时间后自动消失。
Alert 仅保留给需要常驻占位的状态：权限不足、列表加载失败、解析警告、空态说明等；不要再把普通 CRUD 成功/失败提示固定渲染在页面顶部。
后台页面首屏加载态统一使用居中 Spin，优先复用 web/src/components/admin-page-loading.tsx；不要再用左上角纯文本或文本卡片作为页面级初始加载占位。

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

API 默认数据库连接切换为本地 PostgreSQL：优先读取 DATABASE_URL；若未设置则由 DB_HOST/DB_PORT/DB_NAME/DB_USERNAME/DB_PASSWORD 组装。
默认参数口径：
- Docker 内：DB_HOST=db、DB_PORT=5432、DB_NAME=postgres、DB_USERNAME=fquiz、DB_PASSWORD=fquiz。
- 本机直连（非 Docker）：DB_HOST=127.0.0.1、DB_PORT=5434、DB_NAME=postgres、DB_USERNAME=fquiz、DB_PASSWORD=fquiz。
docker compose 的 db 服务已取消 local-db profile，默认 up 即启动本地库；api 增加 depends_on: db (healthy)。
DB_SCHEMA 通过 PostgreSQL search_path 注入，语义等价 JDBC 的 currentSchema。
API 启动初始化口径：seed_defaults 对本地目标执行；为兼容老表状态约束，初始管理员状态写入值统一为 ENABLED（不使用 active）。
用户表兼容口径：用户主键列对齐旧库 users.user_id，与用户关联的外键统一引用 users.user_id（不再引用 users.id）。

高程数据管理口径（2026-05-01）

高程管理一期采用“文件 + 元数据 + 异步回填”三层：
- 文件层：高程源数据文件由现有文件管理模块承载（mount_code + file_path）。
- 元数据层：elevation_dataset 记录数据集来源、分辨率、样本统计、覆盖 bbox、状态。
- 任务层：elevation_apply_job 记录线路高程回填任务状态与统计。
线路渲染继续复用 power_line_tower.altitude_m 作为高度来源；回填后在 raw_extra_json.elevation 写入溯源信息（dataset/sample_distance/sampled_at）。
一期采样策略为 CSV 点集最近邻（非栅格插值），用于先打通管理与回填闭环；默认推荐回填模式 fill_null_only，避免覆盖人工高程。
高频通知 topic 为 admin.elevation，线路联动通知沿用 admin.power-lines。
高程数据文件格式已扩展为：csv/img/tif/tiff。

DEM 地形瓦片口径（2026-06-09）

高程数据集在“分析成功”后会自动尝试派发 DEM 地形瓦片构建任务；管理端同时保留手动 POST /api/v1/elevation/datasets/{id}/terrain/build 触发入口，用于重试或重建。
地形瓦片产物采用 Cesium heightmap-1.0 规范，落盘到数据集目录下的 terrain/：
- terrain/layer.json
- terrain/{z}/{x}/{y}.terrain
当前服务口径：
- GET /api/v1/elevation/datasets/{id}/terrain/layer.json
- GET /api/v1/elevation/datasets/{id}/terrain/{z}/{x}/{y}.terrain
前端加载 Cesium DEM 时，必须通过 Cesium.Resource 显式附带 Authorization: Bearer <token>；不能假设仅靠 refresh cookie 即可访问地形接口。
前端地形地址生成统一复用 web/src/lib/elevation-terrain.ts：
- getElevationTerrainRenderState()
- getElevationTerrainLayerUrl()
/admin/elevation 负责展示地形状态、手动触发构建和预览地图加载真实地形；/admin/power-lines 负责选择已接入的 DEM 数据集和垂直夸张倍数，不在页面层重复实现地形地址或状态判断逻辑。
- csv：继续使用点集最近邻采样。
- img/tif/tiff：使用栅格像元采样（按杆塔经纬度取值，必要时自动做 CRS 转换）。
栅格实现口径：
- 运行依赖 rasterio（随 api 依赖安装）。
- 分析阶段 sample_count 使用 width * height（超大栅格上限截断为 2_147_483_647），bbox 直接取源栅格 bounds。
- 非 WGS84 CRS 会返回告警说明，提醒边界坐标单位可能不是经纬度。
用户名列口径：历史环境存在 users.username 与 users.user_name 双形态；运行时通过 USER_USERNAME_COLUMN（username/user_name）与目标库对齐，避免启动阶段关系预加载触发 UndefinedColumn。
密码列口径：历史环境存在 users.password 与 users.password_hash 双形态；运行时通过 USER_PASSWORD_COLUMN（password/password_hash）与目标库对齐，避免启动阶段关系预加载触发 UndefinedColumn。

发布验收口径（2026-04-26）

发布链路默认执行（开发链路）：
- docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml build
- docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml up -d
最小运行态验收：
- docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml ps（关键服务 api/web/celery-worker/celery-beat/db/redis/minio 为 Up，关键依赖健康）。
- curl -fsS http://127.0.0.1:8000/health 返回 API 健康 JSON。
- curl -I -fsS http://127.0.0.1:3000/ 返回 HTTP/1.1 200 OK。
- 结合 docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml logs --tail 抽样检查 api/web/celery-worker/celery-beat 启动日志是否正常。

前端组件栈口径（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。

登录鉴权兼容口径（2026-04-23）

登录请求口径对齐 quiz 老工程：/api/v1/auth/login 使用 user_id + password，不再使用 email + password。
密码校验采用双栈兼容：
- 优先兼容老库 BCrypt 哈希；
- 继续兼容现有 Argon2 哈希。
用户状态采用兼容归一：
- ENABLED/ACTIVE/1/TRUE 视为可登录（active）；
- DISABLED/INACTIVE/0/FALSE 视为禁用（disabled）。
角色/权限读取优先走老表链路：
- user_role_rela -> user_role 计算 role_codes
- role_menu_rela -> menu 映射 permission_codes
管理员角色兼容别名：
- 命中 admin/sys_mgr/administrator 或角色名含“管理员”时，统一附加 admin 角色码，用于现有 require_permission 放行逻辑。
菜单树读取优先走老 menu 表构建（用于 /api/v1/admin/me/menus）；读取失败时回退现有实现。

角色菜单管理兼容口径（2026-04-23）

后台角色/菜单管理（/api/v1/admin/roles*、/api/v1/admin/menus*）已切换为老表链路：
- 角色主表：user_role
- 用户角色关系：user_role_rela
- 角色菜单关系：role_menu_rela
- 菜单主表：menu
角色/菜单 ID 口径统一为字符串（含前后端契约）：
- 后端 api/app/schemas/admin.py 的 RolePublic/MenuPublic 及其请求体均使用字符串 ID；
- 前端 web/src/types/auth.ts 的 RoleItem/MenuItem/MenuTreeItem 同步使用字符串 ID。
菜单树（/api/v1/admin/me/menus）ID 口径已对齐老表：
- 直接返回 menu.menu_id/parent_id，不再生成临时递增 ID。
旧库无独立 permissions 表，/api/v1/admin/permissions 与角色权限展示继续采用“菜单编码 -> 权限码”兼容映射策略。

前端构建类型口径（2026-04-23）

web 在 strict 配置下，web/src/app/admin/** 中事件/回调参数（如 onChange/onClick/onFinish/showTotal/footer）需显式标注类型，避免 noImplicitAny 在 next build 阶段阻断。
antd 的 Card 在当前仓库类型环境下不稳定，页面层默认优先使用 @/components/ui-antd 的 Card 兼容包装；兼容层内部通过显式类型收敛渲染 AntCard，避免 JSX 构造签名缺失报错。
前端类型巡检推荐命令：npm --workspace web exec tsc --noEmit --pretty false；用于在完整 next build 前快速发现 strict 类型门禁问题。
antd 的 Modal.footer 自定义回调中，extra.OkBtn/CancelBtn 必须按组件类型标注为 FC（或由上下文推断），不要写成 () => ReactElement；否则在 next build 的 TS 阶段会出现签名不兼容报错（Target signature provides too few arguments）。

后台菜单组件口径（2026-04-23）

后台壳层菜单（web/src/app/admin/layout.tsx）统一使用 Ant Design Menu（mode="inline"）承载菜单树，不再使用递归 Button + Link 手工渲染。
菜单数据仍来自 /api/v1/admin/me/menus，并通过 pathname 计算 selectedKeys，保证当前路由高亮。
菜单默认全展开（openKeys 覆盖全部带子节点菜单），与历史交互保持一致，避免层级菜单在首次进入时不可见。
顶部账号操作入口继续使用 DropdownMenu 兼容层，不在本口径范围内。
后台导航布局基线为“左侧导航”：
- 桌面端（md 及以上）在左侧栏显示 Menu；
- 移动端通过左侧 Drawer 展示同一套菜单树；
- 不再使用顶部横向 Menu 作为主导航承载。

后端运行时口径（2026-04-23）

登录兼容新增了 bcrypt 校验分支后，api/requirements.txt 必须包含 bcrypt；否则 Docker 重建后 api 会在启动阶段报 ModuleNotFoundError: No module named 'bcrypt'。
老菜单树构建（build_legacy_menu_tree）在字符串 ID 口径下，节点字典键必须使用 legacy_id（即 menu_id）；避免残留旧变量名导致 /api/v1/admin/me/menus 500。

后台壳层布局口径（2026-04-23）

web/src/app/admin/layout.tsx 当前基线为“顶部固定头 + 左侧内嵌菜单 + 主内容区”：
- 右上角提供菜单按钮，支持左侧菜单隐藏/显示；
- 左侧菜单承载组件统一为 AntMenu (inline)，不再使用 Drawer 作为主菜单容器。
后台菜单数据口径不变：继续读取 /api/v1/admin/me/menus，按 pathname 计算选中项和展开项。
后续后台页面改造默认遵循“左侧内嵌菜单可折叠（显隐）”交互，除非有明确业务理由变更。

本地数据库初始化口径（2026-04-23）

当需要把 84 库老工程鉴权链路数据落到本地时，目标应优先选本地 fquiz-db 的 postgres 数据库（非 fquiz），避免覆盖新结构表。
本地初始化范围（本轮基线）：
- public.users
- public.user_role
- public.menu
- public.role_menu_rela
标准流程：
1. 从 223.109.142.84:5432/postgres 导出上述表 schema + data；
2. 本地 postgres 库执行 DROP ... CASCADE 后回放；
3. 导入数据阶段用同一会话临时 SET session_replication_role=replica，规避 menu.parent_id 自关联外键顺序问题；
4. 用 count + md5(signature) 对比远端与本地一致性。

登录页双角色视觉口径（2026-04-23）

登录页主视觉已从单怪兽升级为“双角色怪兽”（毛怪 + 大眼仔）构图，当前登录页实现位于 web/src/app/login/page.tsx。
交互基线保持：眼睛跟随鼠标；密码输入时执行避视动作（毛怪转头，大眼仔轻微眯眼）。
视觉实现采用纯前端结构与 CSS 动效，不引入外部图片资源，不影响登录/注册链路。

前端配色口径（2026-04-23）

前端主题基线统一以 AntD token 为主，不再依赖历史 Radix 变量作为真实配色来源。
web/src/components/ui-antd.tsx 的 Theme 内置 ThemeCssVarsScope：
- 使用 antdTheme.useToken() 将历史变量（--gray-*、--accent-*、--red-*、--green-*、--orange-*、--indigo-*、--color-panel-solid、--border）映射到 AntD token。
- 同步注入 --ant-color-primary/bg-layout/border-secondary/text-secondary/text，供页面直接使用。
web/src/app/globals.css 保留上述变量的静态 fallback；运行时以 ThemeCssVarsScope 注入值为准。
后续页面改造优先级：
1. 新页面优先直接使用 AntD 组件与 token（含 --ant-color-*）；
2. 存量页面可保留历史变量写法，由映射层兜底，不做一次性大迁移。
主题色切换口径：
- 全局主题色由 ThemeAppearanceContext 管理；
- 通过 useThemeAppearance() 读写当前 accentColor；
- 已在后台顶栏提供选择入口（web/src/app/admin/layout.tsx）；
- 用户选择持久化到 localStorage 键 fquiz:theme:accent-color，刷新后保持。

前端路由展示口径（2026-04-23）

用户可见后台地址默认不再带 /admin 前缀（例如 /users、/requirements）。
兼容策略：
- 无前缀地址通过前端中间层 rewrite 到现有 app/admin/** 页面实现；
- 历史 /admin/** 地址继续可访问，并自动重定向到无前缀地址。
后台首页映射口径：/admin 对外统一为 /users。
菜单路径展示口径：前端渲染菜单时将后端返回的 /admin/** 路径规范化为无前缀地址，避免导航条继续暴露 /admin。

后台功能下线口径（2026-04-23）

已下线菜单编码：
- admin.life_countdown
- admin.password
- admin.token_usage
- admin.history
- admin.vocabulary
- admin.diary
- admin.homework
- admin.question_bank
下线策略：
- 种子菜单与 admin 默认菜单绑定中移除上述编码；
- 旧库授权链路通过 legacy_authz_service.DISABLED_MENU_CODES 过滤，确保历史菜单记录不再出现在 /api/v1/admin/me/menus；
- 前端删除对应路由页面与首页卡片入口，直链不可达。
保留能力说明：
- admin.job_mgr（作业监控）继续复用 question_bank API；
- question_bank 与 vocabulary 相关底层 API 保留，用于已保留模块（如分组管理/知识点管理/单词统计）。

功能下线口径（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）
下线语义为“三重约束”：
1. 前端页面路由删除；
2. 后端菜单树与权限推导过滤上述菜单码；
3. 种子菜单与默认角色绑定中移除上述菜单码。
兼容口径：即使旧数据库仍有历史菜单记录，也会被后端过滤，不再下发到 /api/v1/admin/me/menus。
补充口径：历史别名页面 /admin/tag 已一并删除，避免“分组管理”通过旧路由绕过下线策略。

功能下线口径补充（2026-04-23）

以下后台功能已进一步下线：
- 脚本管理（admin.cron_task_mgr）
- 待办管理（admin.todos）
- 作业监控（admin.job_mgr）
- JWT 生成器（admin.jwt_generator）
下线语义：
1. 前端页面路由删除（/admin/cron、/admin/todos、/admin/job、/admin/jwt-generator）；
2. 后端菜单树和权限推导过滤上述菜单码；
3. 种子菜单与 admin 默认菜单绑定移除上述菜单码；
4. JWT 生成器路由从 api_router 取消挂载。
兼容口径：待办底层 API 继续保留给其他模块复用；菜单/页面是否暴露以后续下线口径为准。

功能下线口径补充（2026-04-24）

以下后台功能已进一步下线：
- 单词统计（admin.knowledge_mastery）
- 队列管理（admin.queue_mgr）
下线语义：
1. 前端页面路由删除（/admin/vocabulary-proficiency、/admin/knowledge-mastery、/admin/jobqueue）；
2. 后台首页入口卡片移除；
3. 后端菜单种子与 admin 默认菜单绑定移除上述菜单码；
4. 旧库菜单下发过滤集合新增上述菜单码，确保历史菜单残留不再透出。

管理员权限口径（2026-04-23）

默认将 admin 角色视为“全权限角色”。
后端口径：
- api/app/core/dependencies.py 的 require_permission/require_any_permission 对 admin 角色直接放行。
前端口径：
- web/src/components/auth-provider.tsx 的 hasPermission 对 admin 角色直接返回 true，避免因 permission_codes 枚举不全导致入口误隐藏。
安全边界：
- 前端仅负责显隐与交互；最终权限判定以后端依赖校验为准。

首页与登录口径（2026-05-16）

/login 作为规范登录入口；在当前部署 NEXT_PUBLIC_APP_BASE_PATH=/fl 下，对外地址为 /fl/login。
/ 不再直接承载登录表单，仅用于重定向到 /login。
登录态（含刷新会话恢复）进入 /login 或 / 时，前端立即跳转 /users，实现“登录后直达后台”。
后台壳层文案对齐：
- 未登录访问后台时提示“前往登录”（/login）；
- 账号菜单提供“用户管理”（/users）作为默认后台入口。
退出登录口径：统一跳转到登录页 /login（不保留在当前后台路由）。
宿主机 Nginx 的 location = /fl 不要再重定向到 /fl/；在 basePath=/fl 下，这会和 Next 的路径归一逻辑相互打架。当前口径是把 /fl 直接导向 /fl/login，并在改完 quiz.conf 后立即 nginx -t && nginx -s reload。

站点标题口径（2026-04-24）

全局浏览器 Tab 标题统一为“需求管理”。
入口配置位于 web/src/app/layout.tsx 的 metadata.title。

登录页视觉口径（2026-04-24）

登录页采用“双栏工作台”视觉基线：
- 左侧为品牌与机器人主题视觉区；
- 右侧为白色登录卡片（品牌头、表单、主操作按钮、辅助链接）。
交互口径保持：
- 登录态进入 /login 或 / 仍自动跳转 /users；
- 登录/注册逻辑不变，视觉改造不改变鉴权接口契约。

后台账号入口口径（2026-04-23）

后台右上角账号入口采用 AntD Avatar 作为下拉触发器，不再使用“账号”文字按钮。
Avatar 文案默认使用用户名首字母（大写），空值兜底 U。
下拉内容口径保持不变：账号信息 + 默认后台入口 + 退出登录。

后台左侧导航口径（2026-04-24）

后台壳层左侧导航采用“AntD 文档站点式”固定侧栏布局（参考 https://ant.design/components/avatar-cn）：
- 桌面端（md 及以上）常驻显示；
- 位于顶部栏下方（top: 64px），高度 calc(100vh - 64px)；
- 菜单区可独立滚动，侧栏与主内容通过右边框分隔。
右上角不再提供“隐藏菜单”按钮；主布局不再依赖菜单显隐状态切换。

授权兼容口径（2026-04-24）

legacy_authz_service 在读取 legacy 关系表失败时，必须对会话做安全回滚，再执行 modern 兜底查询，避免事务错误污染导致角色/权限误判为空。
legacy_authz_service._load_modern_roles 需显式预热 Role mapper 后再解析 User.roles，避免首轮 mapper 解析异常被吞掉后出现“空权限”。
对 user_id in {admin, administrator, root, sysadmin} 且无角色映射的账号，授权链路提供内置 admin 兜底，确保本地/迁移期管理员账户可用。
当本地兼容库缺少 user_role_rela 且用户无显式角色映射时，授权链路可回退到 user 角色（前提是 user 角色存在），防止 /api/v1/admin/me/menus 返回空数组导致后台左侧菜单空白。

后台主题切换口径（2026-04-24）

后台右上角主题入口统一采用 Ant Design 文档站（avatar-cn）的“主题图标 + Dropdown 菜单”交互，不再使用简单 Select 模式切换。
主题文案口径固定为：跟随系统 / 浅色主题 / 暗黑主题 / 紧凑主题 / 快乐工作特效 / AI 生成主题 / 主题编辑器。
主题状态模型固定为“主模式 + 开关项”：
- 主模式：auto/light/dark（互斥）
- 开关项：compact、happy-work（独立开关）
持久化键口径：
- fquiz:theme:primary-mode
- fquiz:theme:compact
- fquiz:theme:happy-work
- 兼容保留：fquiz:theme:mode（legacy 四态映射）
AI 生成主题 当前为交互与文案对齐态，未内置站内 AI 主题生成流程；“主题编辑器”默认跳转官方编辑器页。

登录页文案口径（2026-05-16）

登录页（web/src/app/login/page.tsx）默认展示文案统一为中文，不再保留英文提示文案。

前端编译口径（2026-04-24）

在当前栈（Next.js 16 + React 19 + Ant Design 5）下，页面层直接使用 antd 的 Card / Image 容易触发 JSX 类型不兼容报错（TS2604/TS2786）。
项目口径：页面层优先使用 @/components/ui-antd 提供的 Card 封装；Mermaid 预览改用原生 <img>。
当前 web/tsconfig.json 已显式设置 noImplicitAny=false 以保证存量页面可编译；若后续要恢复更严格类型检查，需要分批补齐事件/回调参数类型。

菜单删除兼容口径（2026-04-24）

legacy_admin_rbac_service 中涉及 legacy 关系表 user_role_rela 的查询（如 _get_users_with_menu_access、_get_role_user_ids）必须按“缺表可降级”策略实现：
- 捕获 SQLAlchemyError；
- 执行 db.rollback() 清理失败事务；
- 返回空集合兜底，避免向上冒泡为 500。
背景约束：当前本地兼容库可能不存在 user_role_rela（仅保留 user_role / role_menu_rela），菜单删除链路需在该条件下可用。

认证时效口径（2026-04-24）

API access token 默认有效期已调整为 8 小时（ACCESS_TOKEN_EXPIRE_MINUTES=480）。
refresh token（Refresh Session）默认有效期保持 30 天（REFRESH_TOKEN_EXPIRE_DAYS=30）不变。

发布执行口径（2026-04-25）

本项目本地发布更新容器的标准链路保持为：
- docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml build
- docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml up -d
发布后至少执行以下验收：
- docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml ps（容器状态/健康）
- curl -fsS http://127.0.0.1:8000/health（API 健康）
- curl -I -fsS http://127.0.0.1:3000/（前端可达）
2026-04-25 二次重发验证通过：按上述链路重跑后，api/web/db 均可正常拉起并通过健康检查。

前端 API 基址解析口径（2026-04-25）

当 NEXT_PUBLIC_API_BASE_URL 指向 loopback（localhost/127.0.0.1/::1）时，前端运行时应保证 API host 与当前页面 host 对齐。
只要“配置 host 是 loopback 且与 window.location.hostname 不一致”，就自动重写为当前页面 host，并保留配置端口（默认 8000）。
目的：避免 localhost 与 127.0.0.1 混用导致 refresh cookie 跨站语义，从而在后台路由硬刷新时误判未登录。

仪表盘下线口径（2026-05-02）

后台“仪表盘”页面已下线，不再作为可访问菜单和默认首页。
前端路由口径：
- /admin、/dashboard 统一重定向到 /users；
- 登录态进入 /login 或 / 默认跳转到 /users；
- web/src/app/admin/page.tsx 改为重定向页，不再渲染卡片工作台。
后端菜单口径：
- seed_service.DEFAULT_MENUS 删除 dashboard；

前端菜单路由兼容口径（2026-05-16）

前端公开菜单路由的规范地址统一使用真实页面路径，例如 /users、/roles、/menus、/system-params、/power-lines。
历史别名路径（如 /user、/role、/menu、/system-param、/power-line、/worker、/tower-model、/file）由前端路由层自动规范到对应正式地址，避免旧菜单数据或手输地址直接落到 404。
后台菜单渲染与菜单管理页默认展示规范化后的 path，减少“菜单能点但高亮错位”或“列表里还是旧地址”的前后不一致。
- ROLE_MENU_BINDINGS 删除 admin/user 对 dashboard 的绑定；
- legacy_authz_service、legacy_admin_rbac_service、admin_service 对 dashboard 统一加入下线过滤集合，屏蔽历史库残留菜单记录。

后台顶部滚动口径（2026-04-25）

固定对象是“最顶部导航栏”（包含主题切换与用户 Avatar 下拉），而非主内容区标题栏。
实现基线（web/src/app/admin/layout.tsx）：
- 顶部导航栏使用 sticky top-0 z-50，随页面滚动始终保持可见；
- 主内容区“后台管理标题 + 用户邮箱”保持普通流布局，不做 sticky 固定。

后台外层边距口径（2026-04-25）

左侧导航需贴近页面左边界；后台主栅格外层容器在 md 及以上不保留左侧 padding（pl-0）。
右侧留白继续保持响应式（pr-3 sm:pr-4 xl:pr-6），避免内容区贴右边导致拥挤。

后台页面头信息口径（2026-04-25）

web/src/app/admin/layout.tsx 不再渲染主内容区通用头块（“后台管理”标题 + 当前用户名/邮箱）。
用户信息与主题切换仅保留在最顶部导航栏（Avatar 下拉 + 主题按钮），避免每个页面重复展示相同信息。

前端鉴权刷新并发口径（2026-04-25）

web/src/components/auth-provider.tsx 中 refreshAccessToken() 必须做并发去重（single-flight）；同一时刻只能存在一个 /api/v1/auth/refresh 请求。
原因：后端 refresh 采用“旋转 refresh token”策略，并发刷新会导致后发请求命中旧 token 并把前面成功状态覆盖为未登录，表现为“刷新页面后被踢回登录提示”。
约束：后续任何调用链（bootstrap、fetchWithAuth 401 重试、页面并发请求）都必须复用同一个 in-flight refresh Promise，避免重复发起 refresh。

线路与杆塔管理口径（2026-04-25）

输电线路管理模块采用两张主表：
- power_line（线路）
- power_line_tower（杆塔，line_id 外键关联线路）
关系口径：Line 1:N LineTower，并约束：
- uq_power_line_tower_line_seq（同线路内序号唯一）
- uq_power_line_tower_line_tower_no（同线路内塔号唯一）
导入口径：
- 使用 POST /api/v1/lines/{line_id}/towers/import 导入 CSV；
- 兼容 UTF-8/UTF-8-SIG/GBK；
- 对源数据 -1 作为无效值归一化为 NULL；
- 超出表头的额外列写入 raw_extra_json，避免导入因列漂移失败。
导出口径：
- 使用 GET /api/v1/lines/{line_id}/towers/export 导出 CSV；
- 导出包含线路基础信息、杆塔核心字段与 JSON 扩展字段。
权限口径：
- 新增 line.read / line.manage / tower.read / tower.manage；
- admin 默认授予上述权限。
菜单口径：
- 新增菜单 admin.power_lines，路由 /admin/power-lines；
- 一级菜单默认排序中，admin.power_lines 使用最小 sort_order，应展示在后台菜单最前面；
- 后台默认菜单集合补齐 admin.fl_analysis、admin.fault_recurrence、admin.basic_data、admin.system_monitor、admin.system；其中后 3 项为无路由目录菜单，用于保留现存菜单树全量可见性。
- 页面由 web/src/app/admin/power-lines/page.tsx 承载线路与杆塔管理闭环。

线路地图展示口径（2026-04-25）

线路地图（含 Cesium）可直接复用现有杆塔数据底座：
- power_line_tower 的 longitude/latitude/altitude_m + seq_no 作为线路几何主数据；
- 几何拼接顺序与展示顺序统一按 seq_no ASC。
若线路杆塔数量可能超过 500，前端地图加载不得复用当前页面固定 limit=500 的请求口径；需要补全分页拉取或增加专用几何接口。
坐标系必须显式约定并在导入/展示链路保持一致（建议默认 WGS84）；未标注坐标系的数据源不应直接进入生产地图渲染。

线路 Cesium MVP 口径（2026-04-25）

前端线路管理页（/admin/power-lines）已支持“表格/地图”双视图切换，地图视图使用 Cesium 渲染：
- 杆塔点位：longitude/latitude/altitude_m
- 线路折线：按 seq_no ASC 连线
Cesium 静态资源采用构建前同步策略：
- web/scripts/sync-cesium-assets.mjs 在 postinstall 与 prebuild 执行；
- 同步目录固定为 web/public/cesium/{Assets,ThirdParty,Workers,Widgets}。
工程约束：
- web/public/cesium 属于构建生成资产，不纳入 Git 版本管理（由 .gitignore 忽略）。

线路走向图专题口径（2026-04-26）

线路管理 页面地图视图已升级为“走向图”专题视图（保留表格/走向图双视图切换）。
走向图默认关闭通用底图能力（Cesium baseLayer: false），仅突出线路业务语义：
- 按杆塔 seq_no 连线展示线路走向；
- 展示杆塔点位、起点/终点标识；
- 支持按风险着色、塔号显隐、居中重置。
走向图统计信息固定包含：有效坐标、缺失坐标、断点段数、线路估算长度（Haversine）。
对序号断档采用分段折线渲染，避免缺失坐标导致的跨段误连线。
当前部署默认启用 NEXT_PUBLIC_APP_BASE_PATH=/fl；Cesium 组件初始化时，window.CESIUM_BASE_URL 必须通过 withBasePath("/cesium") 生成，禁止硬编码根路径 "/cesium"，否则子路径部署下会因静态资源 404 导致 Viewer 初始化失败、页面空白。

雷电流数据管理口径（2026-04-25）

雷电流模块一期后端入口统一在 /api/v1/lightning-currents，权限码为：
- lightning.read：查看事件、采样与统计。
- lightning.manage：导入、更新、删除事件。
一期数据模型采用“双表”结构：
- lightning_current_event：事件元数据 + 特征参数（峰值、T1/T2、陡度、I²t、波形分类、极性、多回击统计）。
- lightning_current_sample：采样时序点（seq_no/time_us/current_ka）。
原始序列导入支持单列电流或双列 time,current，并在导入时自动提取特征。
峰值超越概率（P 曲线）通过 /api/v1/lightning-currents/stats/exceedance 提供，便于地区雷电流分布统计。
前端后台入口固定为 /admin/lightning-currents，菜单编码 admin.lightning_currents。
雷电流后台模块对外展示名称已调整为“雷电幅值统计”；保留现有路由 /admin/lightning-currents 与菜单编码 admin.lightning_currents 不变（2026-04-25）。

文件管理下线口径（2026-04-25）

文件管理能力已下线：
- 前端不再提供 /admin/files 与 /admin/knowledge-set 页面；
- 后端不再暴露 /api/v1/admin/files* 相关接口；
- 默认权限中不再包含 file.read / file.manage；
- 默认菜单与 admin 角色菜单绑定中不再包含 admin.files。
为避免对存量数据库做破坏性变更，本次仅下线功能入口与执行链路，不主动删除既有 file_storage_* 表结构。

文件管理迁移口径（2026-04-25）

口径更新：同日已按“参考 modo-next 文件管理能力”重新迁移并恢复本项目文件管理功能，当前状态以本节为准。
后端入口：
- 文件管理 API 恢复到 /api/v1/admin/files*；
- 保留 VFS/S3 存储抽象（storage_driver）与挂载点机制（file_storage_backends / file_storage_mounts / file_index_entries）。
权限与菜单：
- 默认权限恢复 file.read / file.manage；
- 默认菜单与 admin 绑定恢复 admin.files（/admin/knowledge-set）。
迁移增强：
- 新增目录打包下载接口 GET /api/v1/admin/files/download-zip，支持按目录递归生成 zip 下载。

前端 chunk 失配容错口径（2026-04-25）

Next.js 前端需内置 chunk load 失配恢复能力：当出现 Loading chunk ... failed / ChunkLoadError / 动态 import 失败时，自动执行“一次性刷新”尝试恢复。
实现基线：
- web/src/lib/chunk-error.ts：统一错误识别与单次刷新标记。
- web/src/components/chunk-load-recovery.tsx：全局监听 window error 与 unhandledrejection。
- web/src/app/error.tsx 与 web/src/app/global-error.tsx：提供可见兜底与手动恢复入口。
组件级异步加载（例如 import("cesium")）若在局部 try/catch 中吞掉异常，需在 catch 内显式调用 reloadOnceOnChunkError(error)，否则全局监听无法感知并触发恢复。
刷新标记口径：
- 不在应用挂载时主动清理标记；
- 采用带时间戳的冷却窗口（当前 2 分钟）限制自动刷新频率，避免 chunk 持续不可用时陷入无限刷新。
目标：降低发布后或本地重编译后因旧缓存 chunk 引发的白屏概率，避免用户停留在不可恢复状态。

不要在 body（或其祖先）上使用 filter/transform/perspective 做全局动效；这会改变 position: fixed 的定位参照，导致 AntD Modal 在页面滚动后出现顶部遮挡或错位。
快乐工作特效 已调整为背景色轻微脉冲（background-color 动画），避免影响弹窗定位。

雷电分布统计口径（2026-04-25）

雷电分布数据导入入口：
- POST /api/v1/lightning-currents/import-distribution
- 输入：TXT/CSV（纬度、经度、电流幅值）
- 清洗规则：非法行/非法坐标跳过；按批次写入 lightning_current_event。
空间统计主接口：
- GET /api/v1/lightning-currents/stats/distribution
- 输出：
  - 网格化地闪密度 Ng（次/km²·年）
  - 网格 Imax/Iavg
  - 极性占比
  - 散点数据（地图展示）
  - P 曲线阈值超越点
资产关联接口：
- GET /api/v1/lightning-currents/stats/tower-buffer
- 输入：tower_id 或中心坐标 + radius_km + design_current_ka
- 输出：缓冲区雷击统计、超设计阈值次数、风险等级（LOW/MEDIUM/HIGH）与建议文本。
合成对比接口：
- GET /api/v1/lightning-currents/stats/compare-synthetic
- 输出：实测/合成统计与网格余弦相似度（用于验证合成分布接近度）。
周期报表接口：
- GET /api/v1/lightning-currents/reports/distribution?period=week|month
- 输出：近 7/30 天雷击次数、Imax/Iavg、Ng、最严重事件。
前端页面口径：
- 独立菜单入口为 admin.lightning_distribution -> /admin/lightning-distribution，对外展示名“雷电分布统计”。
- /admin/lightning-distribution 复用雷电工作台底座，但只展示分布统计相关能力：筛选、导入、网格热力、散点地图、杆塔缓冲区、实测/合成对比与周/月报。
- /admin/lightning-currents 保留为“雷电幅值统计”，用于原始雷电流序列导入、事件列表、特征参数与采样预览。
- 地图组件：web/src/components/lightning-distribution-map.tsx（Cesium）。

文件管理 MinIO 接入口径（2026-04-25）

deploy/dev-deploy/compose.yml 与 deploy/pro-deploy/compose.yml 均包含 minio 与 minio-init 服务：
- minio 提供 S3 兼容对象存储（9000 API，9001 Console）。
- minio-init 使用 minio/mc 自动创建 MINIO_BUCKET，避免首用报 NoSuchBucket。
api 服务通过环境变量接入 MinIO：
- MINIO_ENABLED
- MINIO_ENDPOINT
- MINIO_ACCESS_KEY
- MINIO_SECRET_KEY
- MINIO_BUCKET
- MINIO_REGION
文件存储 seed 口径更新：
- MINIO_ENABLED=true 时，默认后端切换到 files.s3.default，并将 main 挂载绑定到 S3。
- MINIO_ENABLED=false 时，默认回退到 files.vfs.default。
- 对已存在的默认后端记录执行幂等更新（status/is_default/config_json），确保切换配置重启即可生效。

用户管理新增表单交互口径（2026-04-25）

web/src/app/admin/users/page.tsx 的“新增用户”交互基线为 Modal 弹窗表单，不再采用页面内联大表单。
表单字段与校验规则保持不变（user_id/email/username/password），仅变更承载方式。
创建成功后默认行为：
- 关闭新增用户弹窗；
- 重置表单；
- 刷新用户/角色列表。

后台 Ant Design 规范化口径（2026-04-25）

后台 UI 以 Ant Design 规范为优先口径，不再追求“贴边/全直角”的扁平化视觉。
根主题基线：
- web/src/components/ui-antd.tsx 的 Theme 使用 ConfigProvider + App，并接入 zh_CN locale。
- 默认强调色为 AntD 蓝色体系（blue/#1677ff）。
- 默认圆角采用 AntD 常规 token：medium=6、large=8。
- 主题样式优先走 AntD global token / component token，再通过项目自有 CSS 变量桥接给历史页面；禁止新增宽泛 .ant-* 全局覆盖。
后台布局基线：
- web/src/app/admin/layout.tsx 使用 AntD Layout/Header/Sider/Content。
- Header 高度固定 64px；桌面端使用可折叠 Sider；移动端使用 Drawer 菜单。
- 内容区恢复 AntD 工作台留白：桌面 24px，移动 16px。
- 页面顶部统一展示 Breadcrumb + 页面标题 + 描述，作为后台页面信息架构入口。
核心页面交互基线：
- 工作台使用 AntD Statistic + Row/Col/Card/Tag/Avatar 的模块入口模式。
- 角色管理使用 AntD Card/Table/Form/Modal/Select/Input，权限点和菜单绑定使用 Select mode="multiple"。
- 行内操作优先使用 web/src/components/row-action-menu.tsx，内部已切换为 AntD Dropdown + Button。
验证口径：
- UI 改造至少跑 npm --workspace web exec tsc --noEmit --pretty false 与 npm run build:web。
- 全量 npm --workspace web run lint 当前会被 web/public/cesium 生成资产和历史页面问题阻断；改动文件需至少跑 targeted eslint。

角色管理搜索口径（2026-04-25）

web/src/app/admin/roles/page.tsx 已支持前端本地搜索，匹配字段为：角色编码、角色名称、权限编码、菜单名称/编码。
当前实现不依赖后端关键词参数；若后续角色规模显著增长，再评估升级为接口级搜索。

后端 Celery 调度口径（2026-04-25）

后端调度基线采用 Redis + Celery worker + Celery Beat：
- Redis broker：默认 redis://redis:6379/0。
- Redis result backend：默认 redis://redis:6379/1。
- Worker 服务：celery-worker。
- Beat 服务：celery-beat。
Celery 应保持独立进程运行，FastAPI api 进程只承载 HTTP/WebSocket，不在 lifespan 内启动调度循环。
当前首个周期任务为 app.tasks.schedule_tasks.expire_overdue_schedule_items，由 Beat 按 SCHEDULER_EXPIRE_INTERVAL_SECONDS（默认 60 秒）投递，用于过期 calendar_event 与 todo。
新增周期任务优先放在 api/app/tasks/，业务逻辑继续沉淀到 api/app/services/，避免 Celery task 直接堆业务细节。

任务监控口径（2026-04-25）

任务监控统一入口：/admin/task-monitor（菜单码：admin.task_monitor）。
后端聚合接口：GET /api/v1/admin/task-monitor/overview（/api/v1/admin/task-monitor 前缀）。
监控口径：
- 需求：统计状态/优先级分布，输出高优先级与滞留需求（按 update_date + 阈值小时判定）。
- 待办：统计状态/优先级分布，输出超期待办（due_date/expire_time 触发）。
权限分层：接口按 requirement.* 与 todo.* 权限分别返回对应数据块，避免越权暴露。
菜单保护：admin.task_monitor 已纳入前后端受保护菜单集合，避免在菜单管理中误删。

文件管理单挂载 UI 口径（2026-04-26）

web/src/app/admin/files/page.tsx 默认按“单挂载”交互：不再展示左侧挂载点列表，不提供前端挂载点切换。
当前挂载上下文统一以接口返回的 current_mount 为准；文件操作仍透传 mount_code，保持与后端接口契约一致。
后端仍保留多挂载点模型能力（file_storage_mounts），本次仅收敛前端交互层。

文件管理删除交互口径（2026-05-03）

web/src/app/admin/files/page.tsx 删除确认弹窗统一使用 App.useApp().modal.confirm，避免 Modal.confirm 静态方法在 React 19 + Antd 5 组合下出现“点击删除无响应”问题。

任务监控口径更新（2026-04-26）

/admin/task-monitor 与 GET /api/v1/admin/task-monitor/overview 已收口为 Celery 运行态监控，不再承载需求/待办风险聚合。
接口查询参数：
- task_limit：返回任务明细上限。
- history_limit：历史任务扫描上限（Redis result backend）。
数据来源口径：
- 队列积压（pending_count）在 Redis broker 下按队列 LLEN 读取，非 Redis broker 回退为 0。
- 历史任务状态（SUCCESS/FAILURE/RETRY/REVOKED）在 Redis result backend 下通过 SCAN celery-task-meta-* 采样聚合。
接口与页面权限统一为：celery.read 或 celery.manage。
前端展示结构固定为三块：
- Worker 概览（在线状态、并发、预取、活跃/预留/定时任务数）
- Queue 概览（pending、consumer、active/reserved/scheduled）
- Task 明细（状态、队列、worker、ETA/开始/完成、错误摘要）

后台页面顶部信息口径（2026-04-26）

后台壳层 web/src/app/admin/layout.tsx 不再渲染内容区顶部公共信息块（Breadcrumb + 页面标题 + 页面描述）。
后台页面默认直接进入业务内容区，避免在每个页面重复展示“模块标题 + 描述文案”。

ATP 模型管理口径（2026-04-26）

ATP 功能一期定位为“ATPDraw 产物版本管理 + ATP 引擎调用”：
- 模型台账：atp_model
- 版本管理：atp_model_version
- 运行记录：atp_simulation_run
后端 API 统一前缀：/api/v1/atp/models，包含：
- 引擎状态：GET /engine/status
- 模型 CRUD：GET/POST/PATCH/DELETE /
- 版本管理：GET/POST/PATCH /{model_id}/versions* + POST /activate
- 运行管理：GET/POST /{model_id}/runs*
权限口径：
- atp.read：查看模型/版本/运行
- atp.manage：维护模型与版本、激活版本
- atp.run：执行仿真
菜单口径：
- 新增 admin.atp_models，路由 /admin/power-lines/atp-viewer，默认绑定 admin 角色。
推送订阅口径：
- 主题 admin.atp-models（权限 atp.read/atp.run/atp.manage）。
配置口径：
- atp_engine_mode：wine|native
- atp_engine_executable
- atp_storage_root
- atp_engine_workdir
- atp_engine_default_timeout_seconds
- atp_engine_max_timeout_seconds

功能下线口径（2026-04-26）

以下后台功能已下线，不再作为有效入口、默认菜单、默认权限或公开 API 提供：
- AI 聊天：/admin/chat、/api/v1/chat*、chat.use
- 编排管理：/admin/orchestration
- MCP管理：/admin/mcp-server
- 模型管理/API测试：/admin/models、/admin/api-tester、/api/v1/admin/models*、/api/v1/admin/model-routes*、model.read/model.manage
- 知识集/文件管理：/admin/knowledge-set、/admin/files、/api/v1/admin/files*、file.read/file.manage
- 流程图：/admin/mermaid-mgr、/api/v1/mermaids*、legacy /api/mermaids*
- 思维导图：/admin/mindmap、/api/v1/mindmap*
- 需求管理：/admin/requirements、/api/v1/requirements*、/api/project/requirement*、requirement.*
- 日程管理：/admin/schedule、/api/v1/calendar*、/api/v1/todos*、todo.*
admin.agent/admin.mcp_server/admin.files/admin.requirements/admin.schedule/admin.mindmap/admin.mermaid_mgr/admin.chat/admin.api_tester/admin.models/admin.orchestration 仅保留在 removed/disabled 过滤集合中，用于屏蔽历史菜单数据。
本次不执行数据库 drop；历史表若已存在，作为历史数据保留。模型注册表/路由表仍保留给内部 LLM 网关和寿命倒计时等内部能力使用，但无后台管理页面/API。
/admin/task-monitor 已独立为 Celery Worker/Queue/Task 监控，不再读取需求/待办数据。

文件管理恢复口径（2026-04-26）

文件管理模块恢复路径：
- 前端页面：/admin/files（后台首页卡片入口 /files）。
- 后端接口：/api/v1/admin/files 及其 directories/delete/rename/move/upload/download/download-zip 子接口。
权限口径：file.read（读）与 file.manage（写操作）。
订阅口径：admin.files topic 已恢复，文件操作后触发前端刷新。
模型与 seed：file_storage_backends / file_storage_mounts / file_index_entries 已恢复注册；默认 seed 会创建 files.vfs.default、files.s3.default 与 main 挂载。
交互口径：页面保持“单挂载点”模式，不展示左侧挂载点切换面板。

ATP 查看器口径（2026-04-26，2026-05-04 更新）

ATP 文本查看能力已落地在线路模块子路由：/power-lines/atp-viewer（内部路由 web/src/app/admin/power-lines/atp-viewer/page.tsx）。
技术栈固定为“前端本地解析 + 前端只读渲染”：
- 解析：web/src/lib/atp/parse-atp-text.ts
- 渲染：@antv/x6 + web/src/components/atp-x6-viewer.tsx
- 电气元件符号：组件内置 SVG data-uri 映射（R/L/C/SW/SRC/XFMR/LINE/CTRL/MISC）。
当前目标是“查看保真优先”，明确不包含仿真内核调用。
解析覆盖常见元件行格式，复杂 ATP 控制卡/模型卡默认容错跳过并输出 warnings，不阻断基础图形查看。

雷电地形倾角口径（2026-04-26）

地面倾角计算接口固定为：
- POST /api/v1/lightning-currents/stats/tower-terrain
入参口径：
- dem_grid_m 必须为 3x3 高程矩阵（中心点 + 邻域 8 点）。
- cell_size_m 为 DEM 栅格间距（米）。
- dem_resolution_m 可单独传入用于质量评分（不传时默认等于 cell_size_m）。
算法口径：
- 梯度：Horn 3x3（algorithm_version=horn_3x3.v1）。
- 输出：slope_deg、aspect_deg、slope_mean/p95/max、slope_along/cross_line_deg、relief_m_50、terrain_exposure_index、quality_score/level。
- 坡向定义为“顺坡向（下坡方向）方位角”，0-360°，顺时针（0=北，90=东）。
持久化口径：
- persist=true 时要求 tower_id，且调用方需具备 tower.manage 或 lightning.manage（admin 放行）。
- 持久化位置：power_line_tower.raw_extra_json.terrain_metrics，并同步更新 slope_1/slope_2（纵坡/横坡绝对值）。
缓冲区分析联动：
- GET /api/v1/lightning-currents/stats/tower-buffer 返回 terrain_metrics（若杆塔已有地形指标）。
- 风险分级引入地形暴露权重：ng_for_risk = ng * (1 + 0.25 * exposure)，但原始返回字段 ng_per_km2_year 保持未加权值。

users 主键兼容口径（2026-05-01）

用户主键列工程约定仍为 users.user_id。
为兼容历史库（残留 users.id）并避免启动 seed 阶段出现 UndefinedColumn: users.user_id，init_db() 在 PostgreSQL 下新增启动期兼容逻辑：
- 若检测到 users 表存在且仅有 id、缺少 user_id，自动执行 ALTER TABLE users RENAME COLUMN id TO user_id，再继续 create_all/seed。
对已对齐 users.user_id 的库，该逻辑不产生任何改动。

users 审计列兼容口径（2026-05-01）

用户审计字段工程约定为 users.create_user、users.update_user。
为兼容历史库并避免启动 seed 阶段出现 UndefinedColumn: users.create_user/update_user，init_db() 在 PostgreSQL 下新增启动期兼容逻辑：
- 若存在 create_by/created_by，自动重命名为 create_user。
- 若存在 update_by/updated_by，自动重命名为 update_user。
- 若目标列仍缺失，自动补齐 nullable 列：create_user VARCHAR(64)、update_user VARCHAR(64)。
对已对齐审计字段的库，该逻辑不产生任何改动。

GitHub Actions 发布分支口径（2026-05-01）

.github/workflows/main.yml 的自动发布触发分支已切换为 dev：
- on.push.branches: [dev]
- deploy.if: github.ref == 'refs/heads/dev'
main 分支默认不再触发该部署 workflow。

legacy 角色查询兼容口径（2026-05-01）

/api/v1/admin/roles 当前入口仍走 legacy_admin_rbac_service，但数据库形态可能是 legacy（user_role/role_menu_rela/menu）或 modern（roles/role_menus/menus）。
角色读取链路兼容策略：
- 当 public.user_role 存在：继续走 legacy 表链路。
- 当 public.user_role 缺失：自动回退到 modern 表链路，并补齐 role_permissions + permissions 权限码。
该兼容仅针对角色读取相关接口（list_roles/get_role_by_id/list_role_menu_ids）；角色写入链路暂仍以 legacy 表为准。

用户管理检索与分页口径（2026-05-01）

用户管理列表接口 GET /api/v1/users 支持查询参数：
- limit / offset：分页
- keyword：按 user_id/email/username 模糊检索
- status：状态过滤（active|enabled|disabled）
后端统计口径要求：total 必须与当前检索/过滤条件一致（不是全量总数）。
前端 /admin/users 采用“检索条件 + 分页状态”驱动请求，不再固定拉取 limit=200 全量列表。

用户管理编辑口径（2026-05-01）

用户信息更新接口 PATCH /api/v1/users/{user_id} 当前支持：
- email
- username
- status
更新规则：
- email 入库前统一 trim + lower，且做唯一性校验；
- username 入库前统一 trim，且做唯一性校验；
- 空字符串视为非法更新（返回失败）。

线路管理塔杆分页口径（2026-05-01）

web/src/app/admin/power-lines/page.tsx 的“塔杆列表”默认启用服务端分页：
- 默认每页 20 条；
- 请求参数按 limit/offset 驱动；
- 总数以接口返回 total 为准。
筛选条件（关键词/塔型/风险等级）或线路切换时，分页需自动回到第 1 页，避免落在无数据页。
地图视图保留大页查询（当前 500 条）用于展示线路点位，不与表格分页参数共用同一页码。

线路管理电压等级口径（2026-05-03）

/admin/power-lines 的“新建/编辑线路”中，电压等级输入已统一为下拉选择（不再允许自由数值输入）。
下拉选项对齐旧 fl 工程 FormCreateXianLu 的 14 个预设文案（含直流/交流与四回路文案）。
后端契约保持不变：仍提交并存储 voltage_kv（整数），不新增交流/直流或回路数单独字段。
由于仅存储数值，部分文案在持久化后会折叠为同一电压值（例如 直流500kV 与 交流500kV），编辑回显采用固定默认映射。
FL-10 起，新建线路弹窗不再展示“线路编码将由系统自动生成”提示；“电压等级”在前端表单层改为必填，并禁止手动清空下拉值。

角色/菜单配置口径（2026-05-01）

角色管理页面（/admin/roles）当前仅提供角色基础信息与“可见菜单”配置，不再提供权限点（permission_codes）配置入口。
菜单管理页面（/admin/menus）当前不再提供菜单权限码（permission_code）配置入口与列表展示。
后端权限字段与接口兼容能力保留，作为历史数据与鉴权映射兜底；前端交互层默认不暴露该配置。

文件管理上传进度口径（2026-05-02）

文件管理页（/admin/files）上传链路已从 fetch 切换为 XMLHttpRequest，用于获取浏览器原生上传进度事件并展示百分比。
上传进度展示基线：
- 上传进行中显示文件名、百分比数值与进度条；
- 上传成功后清空进度状态；
- 上传失败时进度归零并沿用现有错误提示通道。
鉴权口径：
- XHR 上传沿用 withCredentials + Authorization: Bearer <token>；
- 401 时触发一次 refreshAccessToken 并重试上传，保持与现有鉴权刷新机制一致。
AuthContext 对外新增 getAccessToken()，用于在异步重试场景读取最新 token，避免闭包持有旧值。

Redis 持久化容错口径（2026-05-03）

deploy/dev-deploy/compose.yml 与 deploy/pro-deploy/compose.yml 的 redis 统一采用：
- appendonly yes
- save ""
- stop-writes-on-bgsave-error no
目的：规避 RDB 快照失败触发 MISCONF 后 Redis 全局拒写，保障 Celery broker/result backend 可持续写入。

故障复现工具口径（2026-06-07）

新增独立能力入口 /admin/fault-recurrence，定位为源端 FuXian 的无状态迁移版工具，不挂靠现有 /admin/fl-analysis 任务模型。
后端接口统一走 POST /api/v1/fault-recurrence/analyze，输入为 multipart/form-data：
- file
- curve_no
- stroke_mode
- withstand_level_ka
输入文件兼容两类口径：
- 源端 <TGanTa>/<XianLu> 分段文本
- 含 波头时间/μs、波尾时间/μs、反击耐雷水平kA、绕击耐雷水平kA 列的普通 CSV/TXT
计算逻辑保持源端 FuXian.LeiDianFuXian2()：
- 先按 2.6/50 基准点判断是否 No need!
- 再按同波头分组做线性插值与概率密度比较，输出最可能的波头/波尾组合
菜单编码为 admin.fault_recurrence，默认绑定 line.read 口径，并加入 modern seed 与 legacy synthetic menu 双轨兼容。

88 KiB Raw Blame History Unescape Escape

MEMORY.md - fquiz 工程长期记忆

项目基线

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

约定

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

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

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

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

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

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

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

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

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

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

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

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

Celery 监控口径（2026-05-01）

调度与监控口径（2026-05-02）

Legacy 鉴权兼容口径（2026-05-03）

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

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

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

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

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

滚动条样式口径（2026-04-25）

Wine 执行器口径（2026-04-25）

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

前端提示反馈口径（2026-06-08）

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

高程数据管理口径（2026-05-01）

DEM 地形瓦片口径（2026-06-09）

发布验收口径（2026-04-26）

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

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

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

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

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

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

登录鉴权兼容口径（2026-04-23）

角色菜单管理兼容口径（2026-04-23）

前端构建类型口径（2026-04-23）

后台菜单组件口径（2026-04-23）

后端运行时口径（2026-04-23）

后台壳层布局口径（2026-04-23）

本地数据库初始化口径（2026-04-23）

登录页双角色视觉口径（2026-04-23）

前端配色口径（2026-04-23）

前端路由展示口径（2026-04-23）

后台功能下线口径（2026-04-23）

功能下线口径（2026-04-23）

功能下线口径补充（2026-04-23）

功能下线口径补充（2026-04-24）

管理员权限口径（2026-04-23）

首页与登录口径（2026-05-16）

站点标题口径（2026-04-24）

登录页视觉口径（2026-04-24）

后台账号入口口径（2026-04-23）

后台左侧导航口径（2026-04-24）

授权兼容口径（2026-04-24）

后台主题切换口径（2026-04-24）

登录页文案口径（2026-05-16）

前端编译口径（2026-04-24）

菜单删除兼容口径（2026-04-24）

认证时效口径（2026-04-24）

发布执行口径（2026-04-25）

前端 API 基址解析口径（2026-04-25）

仪表盘下线口径（2026-05-02）

前端菜单路由兼容口径（2026-05-16）

后台顶部滚动口径（2026-04-25）

后台外层边距口径（2026-04-25）

后台页面头信息口径（2026-04-25）

前端鉴权刷新并发口径（2026-04-25）

线路与杆塔管理口径（2026-04-25）

线路地图展示口径（2026-04-25）

线路 Cesium MVP 口径（2026-04-25）

线路走向图专题口径（2026-04-26）

雷电流数据管理口径（2026-04-25）

文件管理下线口径（2026-04-25）

文件管理迁移口径（2026-04-25）

88 KiB

Raw Blame History