feat: 补充注释

CLAUDE.md

@@ -9,6 +9,7 @@
 - 默认最小改动，优先复用现有工具函数、类型和目录结构。
 - 保持单一入口和单一职责，避免同一业务暴露多套路由或重复实现。
 - 前端不接触 NewAPI session、完整 API Key、Lsky token 等敏感信息。
+- 所有返回给前端的 `msg` 必须使用本地业务表达，不提及“上游”“NewAPI”“Lsky”“供应商”“token”“key”等内部来源；内部异常统一返回“服务器内部错误”。
 - 注释和日志要解释意图、边界和排查信息，不输出密码、cookie、完整 key、token、图片二进制或完整 prompt。
 - 已存在的说明性注释不要随意删除，尤其是 `server/utils/openai.ts` 里的模型调用、视觉输入、流式解析等上下文注释。
 
@@ -60,7 +61,7 @@
 
 - `POST /api/images/generate` 当前同步等待生图完成后返回，不向前端透传流式进度。
 - 生图成功后返回：
-  - `imageUrl`：NewAPI 上游返回的图片 URL，前端当前优先展示。
+  - `imageUrl`：生成图片访问地址，前端当前优先展示。
   - `hostedImageUrl`：Lsky 图床归档后的 URL，归档失败时为 `null`。
   - `revisedPrompt`：流式 chat completions 当前没有等价字段，通常为空。
 - Lsky 归档逻辑集中在 `server/utils/lsky.ts`：
@@ -68,9 +69,9 @@
   - 上传时先下载上游图片，再用 `multipart/form-data` 调 Lsky `/upload`。
   - 文件名格式为 `userId_username_timestamp_recordId.ext`。
   - tags 固定包含 `AIArtStudio`、`user:{userId}`、`record:{recordId}`、`model:gpt-image-2`。
-- 图床上传失败不影响本次生图成功：接口仍返回上游 `imageUrl`，数据库记录归档失败提示。
+- 图床上传失败不影响本次生图成功：接口仍返回 `imageUrl`，数据库记录归档失败提示；前端可见文案只能说“图片归档失败”等本地描述。
 - 数据库不保存图片 base64；不要恢复 `image_base64` 或类似大文本存图方案。
-- 历史列表不返回大体积数据；详情可返回完整上游响应和 Lsky 上传响应。
+- 历史列表和详情都不向前端返回完整上游响应、图床响应或内部错误详情；这些内容可以入库供服务端排查，但 API 响应应固定隐藏或置空。
 
 ## 数据库与 Prisma
 
@@ -92,6 +93,7 @@
 
 - API handler 使用 `server/utils/logging.ts` 的 `createApiLogger` 和 `toSafeLogError`。
 - 日志必须包含足够排查信息，例如 `requestId`、阶段、`userId`、`recordId`、分页、耗时、状态。
+- 上游错误、内部响应、图床响应、数据库异常等细节只允许写入服务端日志或数据库排查字段，不允许通过接口 `msg`、`data`、历史详情等返回给前端。
 - 生图日志阶段建议保持清晰：
   - `read_body`
   - `read_user_id`
@@ -108,7 +110,10 @@
 - 所有 JSON 接口先校验请求体：只接受 JSON 对象或 `null`，数组、字符串等无效 body 直接返回 400。
 - 对上游透传字段必须使用白名单数组过滤，只透传类型正确且文档声明的字段。
 - 统一使用 `createSuccessResponse`、`createErrorResponse` 返回结构。
-- 上游异常统一通过 `createUpstreamErrorResponse` 转换。
+- `createSuccessResponse` 的 `msg` 只写本地业务结果，例如“登录成功”“生图完成”“环境已准备”。
+- `createErrorResponse` 的 `msg` 只写本地业务错误，例如“未登录”“请求体必须是 JSON 对象”“生图记录不存在”。
+- 上游或内部异常统一通过 `createUpstreamErrorResponse` 转换，并固定对前端返回“服务器内部错误”；具体异常必须在调用前写入服务端日志。
+- 不把上游 `message`、`statusMessage`、响应体、错误 data、完整响应对象、图床错误信息、数据库错误信息透出给前端。
 - 401 或登录态失效时统一清理本地 auth cookie。
 - 不在 handler 内重复实现复杂错误解析，通用判断放到 `server/utils`。
 
@@ -133,6 +138,8 @@
 - TypeScript 严格类型优先，避免 `any` 扩散。
 - 新增通用逻辑优先抽到 `server/utils`，handler 只负责入参校验、调用和统一响应。
 - 修改优先小步快改，不重构无关代码。
+- `server/` 下每个文件顶部必须有 `// server/... - 用途说明` 注释。
+- 复杂 `defineEventHandler` 上方必须写清楚接口流程、鉴权边界、数据是否入库、哪些信息不会返回前端。
 - 注释使用中文，描述意图与边界，不写机械解释。
 - 不删除已有有价值注释；确需重写文件时，要保留或迁移原注释表达的信息。
 
@@ -145,8 +152,9 @@
 3. 在 handler 中完成请求体校验、白名单过滤、鉴权和日志。
 4. 将可复用业务逻辑抽到 `server/utils`。
 5. 涉及数据库时同步修改 Prisma schema、migration、`create_tables.sql`。
-6. 确认敏感信息不进入前端响应、日志或数据库不该保存的字段。
-7. 运行 `pnpm typecheck`；涉及 Prisma schema 时运行 `prisma generate`，必要时同步数据库。
+6. 确认前端响应中的 `msg`、`data`、历史详情不包含上游/internal 细节；内部错误统一显示“服务器内部错误”。
+7. 确认敏感信息不进入前端响应、日志或数据库不该保存的字段。
+8. 运行 `pnpm typecheck`；涉及 Prisma schema 时运行 `prisma generate`，必要时同步数据库。
 
 ## 非目标