# AGENTS.md - 智能编码助手指南 ## 偏好设置 - 使用中文回答问题 - 代码变更前先阅读相关文件 - 遵循项目现有架构和模式 --- ## 命令速查 ### 基础命令 ```bash pnpm install # 安装依赖 pnpm build # 构建应用 pnpm start:dev # 开发服务器（热重载） pnpm lint # 代码检查（自动修复） pnpm format # 代码格式化 ``` ### 测试命令 ```bash pnpm test # 所有测试 pnpm test:watch # 监听模式 pnpm test:cov # 覆盖率报告 pnpm test -- path/to/testFile.spec.ts # 单个测试文件 pnpm test -- -t "pattern" # 匹配名称的测试 pnpm test:e2e # E2E 测试 ``` ### 数据库 ```bash pnpm prisma generate # 生成 Prisma Client pnpm prisma migrate dev # 开发环境迁移 pnpm prisma:deploy # 生产环境迁移 pnpm prisma:seed # 运行种子数据 ``` ### 部署运维 ```bash pnpm run verify # 验证环境配置 pnpm run deploy # 生产环境一键部署 pnpm run deploy:dev # 开发环境部署 pnpm run health # 健康检查 pnpm run init:status # 检查初始化状态（需 token） pnpm run backup # 备份数据库 pnpm run logs:api # 查看 API 日志 pnpm run shell # 进入 API 容器 ``` --- ## 代码规范 ### TypeScript - 严格模式已启用（`strict: true`） - 关键选项：`noImplicitAny`、`strictNullChecks` - 目标：ES2023，模块：NodeNext，装饰器已启用 ### 导入顺序 1. Node 内置模块 2. 第三方库 3. 内部模块（相对路径） ### 文件结构（NestJS 模块） ``` src/modules// ├── .module.ts ├── .service.ts ├── .controller.ts ├── dto/ │ ├── .dto.ts │ └── ... └── guards/、decorators/、processors/（可选） ``` ### 命名约定 - **文件**：kebab-case（如 `admin-comments.controller.ts`） - **类**：PascalCase（如 `ArticlesService`） - **方法/变量**：camelCase - **枚举**：PascalCase 名称，UPPER_SNAKE 值 - **常量**：UPPER_SNAKE - **接口**：PascalCase ### DTO 与验证 - 必须使用 `class-validator` 装饰器 - 必填字段必填，可选字段加 `@IsOptional()` - 使用 `@IsString()`、`@IsInt()`、`@IsEnum()`、`@IsEmail()` 等 - 添加限制：`@Length()`、`@Min()`、`@Max()` - Create DTO：必填字段；Update DTO：所有字段可选 ### 服务层 - `@Injectable()`，通过构造函数注入依赖 - 异步操作使用 `async/await` - 记录日志但不吞噬异常 - 返回 Plain Objects，避免循环引用 ### 控制器层 - 使用 NestJS 装饰器：`@Controller()`、`@Get()`、`@Post()`、`@Put()`、`@Delete()` - 验证输入：`@Body()`、`@Query()`、`@Param()` 配合 DTO - 访问请求：`@Req()` 获取 session、用户、IP 等 - 应用守卫：`@UseGuards(RequireSessionUser)`、`@RequireRole('admin')` - 错误处理：未找到用 `HttpStatus.NOT_FOUND`，禁止访问用 `HttpStatus.FORBIDDEN` ### 守卫与装饰器 - `RequireSessionUser`：从 session 加载用户到 `req.user` - `RequireRole`：RBAC 角色验证，配合 `RequireRoleGuard` 使用 - `@Throttler()`：对 `/login` 和 `/oauth2/token` 限流 ### 错误处理 - 使用 `HttpException` 配合适当的 HTTP 状态码 - 服务层用 `Logger.error()` 记录异常 - 外部 API 调用必须用 try-catch 包裹，提供降级行为 - 不暴露内部错误详情给客户端 ### 日志规范 - 使用 `Logger` from `@nestjs/common` - 实例化：`new Logger(ClassName.name)` - 日志级别：`log`、`debug`、`warn`、`error` - 禁止记录敏感数据，记录操作审计 ### 数据库（Prisma） - Schema：`prisma/schema.prisma` - 通过 `PrismaService` 访问，生产用真实客户端，开发用内存 mock - Mock 必须实现完整 Prisma API：`findUnique`、`findMany`、`create`、`update`、`delete`、`count`、`aggregate` - `findMany` 支持：`where`、`include`、`orderBy`、`skip`、`take` - `update` 支持嵌套操作：`{ viewCount: { increment: 1 } }` ### AI 内容审核（OpenRouter） - 使用 OpenAI 兼容的 chat completions 端点 - 配置：`AI_REVIEW_PROMPT_TEMPLATE` 环境变量 - 响应必须是 JSON：`{ decision: 'approved'|'rejected'|'suspicious', reason, score: 0-1 }` - API 错误时降级到基于规则的审核 ### 邮件服务（Nodemailer + BullMQ） - 仅使用 HTML 模板（可选纯文本备用），内联 CSS - 邮件任务通过 BullMQ 队列 `email` 排队 - `EmailProcessor` 处理 `send-email` 任务 - 所有邮件记录到 `EmailMessage` 表（状态：pending、sent、failed） - 重试机制：3 次尝试，指数退避 ### 安全规范 - Helmet 中间件已启用（安全头） - CORS：生产环境仅允许 `APP_BASE_URL` - Session Cookie：生产环境 `SESSION_COOKIE_SECURE=true`、`HttpOnly=true` - 限流：`@Throttler()` 应用于 `/login` 和 `/oauth2/token` - 全局验证管道：自动转换、白名单、开发环境拒绝额外属性 - 绝不记录敏感数据，所有凭据通过环境变量管理 ### 管理后台 API - 所有 `/admin/*` 路由需要 `@RequireRole('admin')` - 参考 `AdminCommentsController` 模式 - 分页：查询参数 `page`、`limit`，响应包含 `{ items, total, page, limit, totalPages }` ### Swagger 文档 - 非生产环境可访问 `/api-docs` - 使用 `@nestjs/swagger` 装饰器：`@ApiProperty()`、`@ApiBody()`、`@ApiParam()`、`@ApiQuery()`、`@ApiBearerAuth()` - 保持 DTO 简单，示例避免复杂嵌套对象 ### Docker 与部署 - 镜像使用 Bun 运行时（`oven/bun:1.1`） - 多阶段构建：`builder` + `runner` - Docker Compose 服务：`postgres`、`redis`、`api` - 健康检查端点验证数据库和 Redis 连接 - 启动时自动运行：`prisma migrate deploy` 和 `prisma db seed` ### 环境变量 必需配置（见 `.env.example`）： ```env DATABASE_URL # PostgreSQL 连接 SESSION_COOKIE_SECRET # Session 签名密钥（至少 32 位） AI_API_KEY # AI 服务 API Key SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASS # 邮件服务 REDIS_HOST # Redis 地址 OAUTH2_TOKEN_SIGNING_PRIVATE_KEY、OAUTH2_TOKEN_SIGNING_PUBLIC_KEY # RSA 密钥对（生产必填） ``` ### 测试策略 - **单元测试**：隔离测试服务层，mock PrismaService - **E2E 测试**：使用 `supertest` 测试 HTTP 端点 - **文件命名**：`*.spec.ts` 或 `*.test.ts` - **位置**：与源文件并列或 `test/` 目录 - **运行**：`pnpm test`、`pnpm test:watch`、`pnpm test:cov` ### Git 与提交 - 无强制提交规范，但请写清晰的提交信息 - 禁止提交密钥和 `.env` 文件 - 提交前运行 `pnpm lint` 和 `pnpm test` ### 已知模式 - 基于 session 的 Web 认证 + OAuth2 API 客户端 - 评论审核：规则优先，可疑内容走 AI 异步审核 - 文章查看数：`{ viewCount: { increment: 1 } }` - RBAC 角色：`admin`、`moderator`、`user` - PrismaService mock：确保所有模型实现完整 CRUD 方法 --- ## Cursor / Copilot 说明 本项目无特殊的 Cursor 或 Copilot 配置，请遵循上述指南。所有编码助手应： 1. 遵守 TypeScript 严格模式 2. 遵循 NestJS 最佳实践 3. 使用 DTO 进行输入验证 4. 正确使用 PrismaService 5. 记录日志但不泄露敏感信息