3.3 KiB
仓库协作指南
项目结构与模块组织
本仓库是 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，因此执行前需要先检查其中的服务器相关配置。