aiartstudio/CLAUDE.md

CLAUDE.md

目标

本文件用于约束 AI 在本项目内的实现方式，确保代码简洁、可维护、不过度设计。

核心原则

• 只做当前需要的功能，不做无意义兼容层。
• 保持单一入口和单一职责，避免重复路径和重复逻辑。
• 默认最小改动，优先复用已有工具函数和类型。
• 注释和文档要清晰，特别是接口字段与错误处理语义。

API 路由规范

• 认证相关接口统一放在 server/api/auth。
• 当前仅保留以下入口：
  • POST /api/auth/register
  • POST /api/auth/login
  • GET /api/auth/me
  • GET /api/auth/logout
  • GET /api/auth/ready
• 不再创建 server/api/user 的本地别名路由。
• 对外路径由前端统一调用 auth 前缀，不允许同一业务暴露两套路由。

登录状态与环境准备规范

• 登录成功后，后端从 NewAPI Set-Cookie 中提取 session，并写入本项目 httpOnly cookie。
• 前端不得读取、保存或透传 NewAPI session、完整 API Key 等敏感信息。
• 前端通过 /api/auth/me 恢复登录状态，通过 /api/auth/logout 清理登录状态。
• /api/auth/ready 只负责检查当前账号运行环境是否就绪：存在 name 为 AIArtStudio、status 为 1、未删除的 Token 即视为就绪。
• ready 检查不到可用 Token 时，由后端使用固定参数创建 AIArtStudio Token。
• /api/auth/ready 不返回完整 key，也不调用完整 key 获取接口；返回文案使用“环境已准备 / 环境初始化完成”等业务表达，不向前端暴露 API Key 细节。

上游请求规范

• 调用上游 NewAPI 必须使用 server/utils/fetch.ts 中的统一入口。
• 普通未登录请求使用 newApiFetch。
• 需要读取上游响应头的请求使用 newApiFetchRaw，目前主要用于登录时提取 Set-Cookie。
• 需要 NewAPI 登录态的请求使用 newApiAuthedFetch，由服务端从 httpOnly cookie 中读取 session 和 userId 后补齐 Cookie 与 New-Api-User。
• 上游基地址只在 fetch.ts 的 BASE_URL 维护一次。
• 禁止在各个 handler 内重复写 baseURL。
• 当前策略是硬编码基地址，按项目要求保持简单直接。

Token 处理规范

• NewAPI Token 相关通用逻辑放在 server/utils/newApiTokens.ts。
• handler 不直接拼装 Token 列表、创建参数或 ready 判定逻辑。
• Token 列表接口返回的脱敏 key 只用于后端判断，不透出给前端。
• 完整 key 获取接口必须单独设计服务端流程，默认不要在登录或 ready 阶段调用。
• 上游 Token 内部结构类型优先留在 server/utils 内；只有前后端共享的返回契约才放入 shared/types。

请求体处理规范

• 所有接口先校验请求体：只接受 JSON 对象或 null。
• 对上游透传字段必须使用白名单数组过滤。
• 仅透传类型正确且文档声明的字段，忽略多余字段。
• 不做隐式字段转换，不做猜测性补全。

响应与错误处理规范

• 统一使用 createSuccessResponse 和 createErrorResponse 返回结构。
• 上游异常统一通过 createUpstreamErrorResponse 处理。
• 错误处理策略：尽量保留上游状态码与原始错误数据，只补统一响应外壳。
• 避免在每个 handler 内复制复杂的错误解析代码。

类型规范

• 用户相关请求/响应类型放在 shared/types/user.ts。
• 公共响应类型放在 shared/types/index.ts。
• OpenAI 调用基础类型放在 shared/types/openai.ts。
• 新增接口必须先补类型，再写 handler。
• 每个类型字段都要有中文注释，说明字段含义与可选性。
• 仅前端需要感知的接口契约放入 shared/types；服务端内部上游适配类型不要扩散到 shared。

注释规范

• 注释用中文，描述意图与边界，不写无意义废话。
• 关键位置必须有注释：
  • 字段白名单目的
  • 请求体校验原因
  • 上游转发意图
  • 错误处理策略

代码风格规范

• TypeScript 严格类型优先，避免 any 扩散。
• 修改优先小步快改，不重构无关代码。
• 保持现有目录结构和命名风格。
• 新增通用逻辑优先抽到 server/utils，避免在 handler 重复实现。

AI 执行清单

当 AI 新增一个 API 时，按以下顺序执行：

1. 在 shared/types 中定义请求与响应类型，并写字段注释。
2. 在 server/api/auth 新建对应 handler。
3. 在 handler 中完成请求体校验和白名单过滤。
4. 按请求场景选择 newApiFetch、newApiFetchRaw 或 newApiAuthedFetch 调用上游接口。
5. 可复用的业务逻辑优先抽到 server/utils，handler 只负责入参、调用和统一响应。
6. 用统一响应工具返回成功与错误结果。
7. 自检 TypeScript 报错后再结束。

非目标

• 不为未来不确定需求预建兼容路由。
• 不引入与当前需求无关的抽象层。
• 不在多个地方维护同一配置值。