# 仓库协作指南

## 项目结构与模块组织

本仓库是 MemeMind 的 NestJS 后端服务。应用代码位于 `src/`。通用守卫、过滤器、装饰器和基础 DTO 位于 `src/common/`。运行时配置和 TypeORM 配置位于 `src/config/` 与 `src/database/`。业务代码按领域划分在 `src/modules/` 下，包括 `auth/`、`level/`、`share/`、`user/` 和 `game-config/`。新增代码应放入对应模块，并遵循 Nest 的常规结构：`*.controller.ts`、`*.service.ts`、`*.module.ts`，以及按需补充 `dto/`、`entities/`、`repositories/`。单元测试与源码相邻，命名为 `*.spec.ts`；端到端测试位于 `test/`。

## 构建、测试与开发命令

使用 `pnpm`，仓库已包含 `pnpm-lock.yaml`。

- `pnpm install`：安装依赖。
- `pnpm run start:dev`：以 watch 模式启动本地开发服务。
- `pnpm run build`：将 TypeScript 编译到 `dist/`。
- `pnpm run start:prod`：从 `dist/main` 启动生产构建。
- `pnpm run lint`：运行 ESLint 并自动修复可修复问题。
- `pnpm run format`：使用 Prettier 格式化 `src/` 与 `test/`。
- `pnpm run test`、`pnpm run test:cov`、`pnpm run test:e2e`：运行单测、覆盖率测试和 e2e 测试。

## 编码风格与命名规范

使用严格类型的 TypeScript；除非处于明确的边界场景，否则避免新增 `any`。Prettier 约束为单引号和尾随逗号。遵循现有的 2 空格缩进和 NestJS 命名习惯：类使用 `PascalCase`，方法与变量使用 `camelCase`，目录使用 kebab-case，DTO 文件名要具备明确语义，例如 `wx-login.dto.ts` 或 `share-response.dto.ts`。

## 测试规范

单元测试和 e2e 测试均使用 Jest。单元测试文件命名为 `*.spec.ts`，并与被测源码放在一起。只要 controller 契约、service 逻辑、repository 行为或鉴权流程发生变化，就需要新增或更新测试。提交 PR 前应运行 `pnpm run test:cov`，覆盖率结果输出到 `coverage/`。

## 接口文档规范

只要接口发生改动，必须同步更新 `docs/api/` 目录中的对应文档，确保客户端可以直接使用该目录下的文档进行联调。

- 新增接口：在对应模块文档中新增接口章节，并补充请求参数、响应结构、示例和调用场景。
- 修改接口：同步更新字段、鉴权方式、错误码、业务规则和示例。
- 删除或废弃接口：在文档中明确标记，并说明客户端迁移方式。
- 如果一次改动涉及多个模块接口，相关文档都要一并更新，不能只改代码不改文档。

## 提交与合并请求规范

最近的提交历史使用 Conventional Commit 前缀，例如 `feat:`、`perf:`、`refactor:`，也包含带作用域的形式，例如 `feat(share): ...`。请保持提交聚焦，并沿用同样格式。PR 需要说明行为变更、配置或迁移影响、关联的 issue（如果有），并在请求或响应结构发生变化时附上 API 示例。

## 配置与部署说明

环境变量在 `src/config/env.validation.ts` 中做校验。敏感信息应保存在 `.env.local` 或部署环境专用配置中，不能写入源码。无论本地还是生产环境，API 统一暴露在 `/api` 下，Swagger 暴露在 `/api/docs`。`pnpm run deploy` 会调用 `deploy.sh`、`rsync` 和 PM2，因此执行前需要先检查其中的服务器相关配置。