OCS_service/CLAUDE.md

CLAUDE.md

项目定位

本项目是基于 Nuxt 4 / Nitro 的 OCS AI 答题服务，兼容 OCS AnswererWrapper 的题库接口，同时提供网页登录、答题工作台、Dashboard、个人 API 配置和 superadmin 系统配置后台。

核心技术栈：

• Nuxt 4、Vue 3、Pinia、VueUse、Tailwind CSS v4、shadcn-vue / reka-ui、lucide-vue-next。
• Better Auth 邮箱密码登录，Prisma 7 + @prisma/adapter-mariadb 连接 MySQL/MariaDB。
• OpenAI 兼容 Chat Completions 流式调用；对 OCS 客户端仍返回普通 JSON。
• pnpm 10.33.0，Node 22 Alpine 用于 Docker 镜像。

核心原则

• 默认最小改动，优先复用现有目录结构、工具函数、共享类型、store 和 service。
• 前端不接触数据库连接串、session 细节、完整 API Key、token、cookie 或上游响应体。
• API 返回给前端或 OCS 的 msg 必须是本地业务表达，不暴露 OpenAI、Better Auth、Prisma、token、key、连接串或调试细节。
• 内部异常统一返回“服务器内部错误”；具体异常只能进入服务端安全日志。
• 日志记录 requestId、阶段、用户/记录标识、分页、耗时、状态等排查信息；不得记录密码、cookie、完整 key、token、完整 prompt、图片二进制、base64、完整请求体或响应体。
• 不写可能阻塞整个进程的代码；流、DB、外部请求都要有明确边界或错误出口。
• 不为未来不确定需求预建兼容路由、抽象层、配置项或多套入口。

目录结构约定

• app/：前端应用代码。
  • app/pages/：页面路由，当前包括首页答题、Dashboard、登录、注册。
  • app/components/：业务组件；app/components/ui/ 是 shadcn-vue 组件，尽量不要手改生成件。
  • app/services/：前端 API 封装，组件不要直接写 $fetch 调业务接口。
  • app/stores/：Pinia 状态与动作；组件通过 store 消费状态和发起业务操作。
  • app/interfaces/：前端类型出口，主要重导出 shared/types。
  • app/utils/：前端工具，例如 Better Auth client、错误文案、剪贴板等。
• server/：Nitro 服务端代码。
  • server/api/：JSON API 与 Better Auth 路由。
  • server/middleware/：服务端中间件，当前包含 API 统一鉴权和注册开关守卫。
  • server/plugins/：Nitro 启动插件，当前用于补全默认系统配置。
  • server/utils/：服务端业务工具、DB、鉴权、OpenAI、日志、配置、答题逻辑。
• shared/：前后端共享类型和纯函数。新增或修改接口契约时优先更新这里。
• prisma/schema.prisma：数据库结构唯一来源；Prisma Client 输出到 prisma/generated，不要改回 app/generated。
• public/：静态公开文件，不经过构建处理。

认证与权限

• Better Auth 实例在 server/utils/auth.ts，使用 Prisma MySQL/MariaDB 适配器，只启用邮箱密码登录。
• 注册用户时通过 Better Auth databaseHooks 自动生成 32 位 hex apiToken。
• apiToken 供 OCS 油猴脚本跨域调用 /api/search 使用；客户端不能自行写入，刷新走 POST /api/user/refresh-token。
• server/middleware/api-auth.ts 默认保护所有 /api/* 路由；只有 publicApiRoutes 中声明的公开路由放行。
• 当前公开路由：
  • /api/auth/**：Better Auth 登录、注册、退出、get-session 等。
  • GET /api/health：健康检查，不含敏感信息。
  • /api/search：有自己的 session/apiToken 双通道鉴权。
• OPTIONS 预检请求在中间件中直接返回 204。
• superadmin 接口必须在 handler 内二次校验 role === "superadmin"，不能只依赖通用 middleware。
• 注册开关由 allow_registration 系统配置控制，server/middleware/registration-guard.ts 拦截 POST /api/auth/sign-up/email。

API 规范

• 新增接口默认需要登录；只有确实公开的接口才能加入 server/utils/api-auth-rules.ts。
• Handler 只负责入参校验、鉴权/权限边界、调用业务函数和统一响应；复用逻辑放到 server/utils。
• 非 OCS 接口使用 server/utils/response.ts：
  • 成功：apiOk(data)，结构为 { code: 0, data, msg: "请求成功" }。
  • 失败：apiErr(code, msg)，data 固定为 null。
• /api/search 是 OCS 兼容接口，不使用 apiOk/apiErr：
  • 成功固定 { code: 1, question, answer }。
  • 失败固定 { code: 0, msg }。
• 所有 JSON body 先校验为普通对象或 null；数组、字符串等无效 body 返回 400。
• 对客户端传入字段必须白名单过滤，只接受当前接口声明的字段和正确类型。
• 新增或修改接口时，同步维护 shared/types、服务端实现、前端 service、Pinia store 和组件消费。
• API 响应只返回前端需要的字段，不透出内部响应体、数据库异常、第三方错误详情或完整调试对象。

答题流程与缓存

• /api/search 兼容 GET、JSON POST、urlencoded POST、multipart/form-data。
• 鉴权顺序：优先读取网页登录 session；没有 session 时使用请求中的 token 查 User.apiToken。
• title/type/options 会标准化为 SearchParams，只把题目长度、题型和是否有选项写日志。
• 缓存不再是进程内内存缓存；答案记录写入 qa_record，按 userId + md5(title|type|options) 查询最近答案。
• 清缓存不删除历史记录，而是更新 User.cacheClearedAt；缓存查询只命中该时间之后的记录。
• 调 OpenAI 前必须通过 getUserEffectiveApiConfig(userId) 取得生效配置，保证系统 key 不会发往用户自定义 endpoint。
• 多选题继续使用 # 分隔；server/utils/answer.ts 中的 OCS 响应格式不可随意改动。

配置模型

• OpenAI 运行配置以数据库 system_config 为准，不再依赖 OPENAI_API_KEY 等旧环境变量。
• server/plugins/initConfig.ts 启动时补全缺失的默认系统配置；不覆盖已有值。
• server/utils/sysConfig.ts 对系统配置做 60 秒 TTL 内存缓存；superadmin 更新配置后必须调用 invalidateSysConfigCache()。
• 系统配置接口：
  • GET /api/admin/system-config：仅 superadmin，可读，API Key 只返回遮蔽预览。
  • PUT /api/admin/system-config：仅 superadmin，可写，openAiApiKey 为空字符串表示不修改已有 key。
• 用户自定义配置保存在 user_config.value JSON 中：
  • GET /api/user/settings：只返回遮蔽后的 key 预览。
  • POST|PUT /api/user/settings：白名单字段，空字符串 key 表示不修改旧 key。
• 用户启用自定义配置时，只有 customApiBase 和 customApiKey 同时非空，才使用用户 endpoint + key；否则 base 和 key 完全回退系统配置。
• DATABASE_URL、BETTER_AUTH_SECRET、BETTER_AUTH_URL 仍来自环境变量；.env.example 只放这些运行必需项。

数据库与 Prisma

• Prisma schema 位于 prisma/schema.prisma，实际数据库结构以 Prisma 为准。
• 当前使用 Prisma 7 + @prisma/adapter-mariadb，Prisma Client 从 server/utils/db.ts 创建和复用。
• 业务代码不要直接 new PrismaClient()，不要在前端读取或间接获取数据库连接信息。
• DATABASE_URL 只允许服务端读取；日志和响应都不能输出完整连接串。
• prisma.config.ts 在 Prisma 命令加载时需要 DATABASE_URL；Docker build 使用占位值，运行时由容器环境变量覆盖。
• 修改数据库结构的标准流程：
  1. 先阅读 prisma/schema.prisma、相关 handler、server/utils 和共享类型。
  2. 修改 schema。
  3. 优先新增 Prisma migration；若当前开发库确认可接受 prisma db push，必须说明原因。
  4. 运行 .\node_modules\.bin\prisma.CMD generate 重新生成客户端。
  5. 对实际数据库执行同步命令，并确认 schema 已落库。
  6. 运行类型检查；涉及服务启动或构建行为时再运行构建。
• 如果 migration 状态和数据库实际结构不一致，先停下来检查原因，不要直接强行部署或 resolve。
• 数据库不要保存大体积二进制、base64 或敏感明文；API Key 如需保存，只能服务端读取，前端只看遮蔽预览。

前端约定

• 组件只负责 UI 渲染和交互，通过 useXxxStore() 和 storeToRefs() 消费状态，通过 store action 发起操作。
• 接口调用放在 app/services/；业务状态、loading、错误文案和 toast 放在 Pinia store。
• Store 内部通用常量作为具名导出，供组件引用，不在组件中重复定义。
• 认证状态由 app/plugins/auth.ts 做 SSR/client 共用初始化，避免首屏水合不一致。
• /dashboard 由 app/middleware/auth.ts 保护，未登录跳 /login。
• 深色模式通过 useCookie("color-mode") 持久化，避免 localStorage 导致 SSR 水合不匹配。
• 页面与组件不得展示内部服务名、第三方错误、token、key、连接串或原始异常信息。
• shadcn-vue 配置见 components.json；新增 UI 优先使用现有 app/components/ui、lucide 图标和 Tailwind token。

代码风格

• TypeScript 严格类型优先，避免 any 扩散；确需使用时收敛在边界处。
• 新增或大改 server/ 文件时，文件顶部写一行中文用途说明，格式建议为 // server/... - 用途说明。
• 复杂 defineEventHandler 上方写清楚流程、鉴权边界、数据是否入库、哪些信息不会返回前端。
• 注释使用中文，描述意图、边界和排查信息，不写机械解释。
• 不删除已有有价值注释；重写文件时保留或迁移原注释表达的信息。
• import 排序受 eslint-plugin-simple-import-sort 约束。
• app/components/ui/** 在 ESLint 中忽略，通常视为生成代码，不做无关手改。

常用命令

• 安装依赖：pnpm install
• 开发启动：pnpm dev
• 构建：pnpm build
• 预览构建产物：pnpm preview
• Nuxt 静态生成：pnpm generate
• Prisma generate：.\node_modules\.bin\prisma.CMD generate
• 类型检查：.\node_modules\.bin\nuxi.CMD typecheck
• ESLint：.\node_modules\.bin\eslint.CMD .

执行说明：

• 涉及 Prisma schema 时必须运行 Prisma generate。
• 涉及 API、共享类型、store、组件联动时至少运行类型检查。
• 涉及构建、Nitro 插件、Nuxt 配置、Docker 行为时再运行构建。
• 当前仓库未声明专门的 test 脚本，不要假设存在单元测试命令。

Docker 与部署

• Dockerfile.base 基于 node:22-alpine，启用 corepack 并激活 pnpm 10.33.0。
• Dockerfile 从 ocs-base:latest 构建应用，复制源码、安装依赖、执行 pnpm build，最终用 node .output/server/index.mjs 启动。
• .dockerignore 排除 node_modules/、.nuxt/、.output/、prisma/generated/、本地 env 和日志。
• 容器默认 PORT=3000，TZ=Asia/Shanghai。
• 构建阶段的 DATABASE_URL 是占位值；运行时必须提供真实数据库连接和 Better Auth 环境变量。

可用 Skills

本项目本地 .agents/skills 包含以下 Better Auth 相关 skills，遇到对应任务时优先查阅：

• better-auth-best-practices：Better Auth 服务端/客户端、数据库适配、session、插件和环境变量。
• create-auth-skill：为 TypeScript/JavaScript 项目脚手架或扩展认证流程。
• email-and-password-best-practices：邮箱密码、邮箱验证、密码重置和密码策略。
• better-auth-security-best-practices：速率限制、secret、CSRF、trusted origins、cookie/session 安全和审计。
• organization-best-practices：组织、多租户、成员、邀请、团队和 RBAC。
• two-factor-authentication-best-practices：TOTP、OTP、备份码、可信设备和 2FA 登录流。

当前会话还可用的通用 skills / 插件能力：

• frontend-design：构建或美化前端页面、组件、应用体验。
• openai-docs：查询 OpenAI 官方文档和最新 API/模型建议。
• imagegen、hatch-pet：生成位图视觉素材或 Codex pet。
• documents:documents、presentations:Presentations、spreadsheets:Spreadsheets：处理 Word、PPT、表格文件。
• GitHub 插件 skills：github:github、github:gh-address-comments、github:gh-fix-ci、github:yeet。
• skill-creator、skill-installer、plugin-creator：创建/安装 Codex skills 或插件。

使用 skills 时先读对应 SKILL.md，只加载与当前任务直接相关的引用文件，不要为了普通代码改动批量读取全部资料。

AI 执行清单

当新增或调整 API、数据结构、认证、配置或核心业务逻辑时，按以下顺序执行：

1. 阅读真实实现：handler、middleware、server/utils、shared/types、Pinia store、Prisma schema。
2. 明确鉴权边界：公开路由、session、apiToken、superadmin 二次校验。
3. 更新共享类型，再更新服务端、前端 service、store 和组件。
4. 对请求体做普通对象校验和字段白名单过滤。
5. 确认响应 msg、data 不包含内部或第三方细节。
6. 确认敏感信息不进入前端响应、日志或不该保存的数据库字段。
7. 涉及数据库时同步 schema、migration 或 db push、Prisma generate 和实际数据库。
8. 运行类型检查；涉及 Prisma schema 时必须 Prisma generate；涉及服务启动或构建行为时再构建。

非目标

• 不恢复旧的 ACCESS_TOKEN 单全局令牌模式。
• 不恢复旧的 OpenAI 环境变量配置作为主配置来源。
• 不为同一能力创建多个本地别名路由。
• 不新增长期保留的临时排查接口，例如数据库健康检查类接口。
• 不引入与当前需求无关的抽象层、兼容层或配置项。
• 不在多个地方维护同一配置值。
• 不保存大体积 base64、敏感明文或上游完整响应体。
• 不把服务端密钥、session、token、cookie、数据库连接信息或内部错误暴露给前端。