# CLAUDE.md

## 目标

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

## 核心原则

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

## API 路由规范

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

## 上游请求规范

- 调用上游 NewAPI 必须使用 server/utils/fetch.ts 中的 newApiFetch。
- 上游基地址只在 fetch.ts 的 BASE_URL 维护一次。
- 禁止在各个 handler 内重复写 baseURL。
- 当前策略是硬编码基地址，按项目要求保持简单直接。

## 请求体处理规范

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

## 响应与错误处理规范

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

## 类型规范

- 用户相关请求/响应类型放在 shared/types/user.ts。
- 公共响应类型放在 shared/types/index.ts。
- 新增接口必须先补类型，再写 handler。
- 每个类型字段都要有中文注释，说明字段含义与可选性。

## 注释规范

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

## 代码风格规范

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

## AI 执行清单

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

1. 在 shared/types 中定义请求与响应类型，并写字段注释。
2. 在 server/api/auth 新建对应 handler。
3. 在 handler 中完成请求体校验和白名单过滤。
4. 使用 newApiFetch 调用上游接口。
5. 用统一响应工具返回成功与错误结果。
6. 自检 TypeScript 报错后再结束。

## 非目标

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