# 开发规则模块

## 概述
项目开发规则体系，定义代码质量、安全、性能、无障碍、SEO、部署等全生命周期的强制/推荐规范。

- **文件**: [.trae/rules/project_rules.md](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)
- **严重级别**: 🔴 必须遵守 | 🟡 强烈推荐 | 🟢 建议

## 章节目录（22章）

| 章节 | 内容 | 严重度 |
|------|------|--------|
| **零、代码质量基础** | TypeScript类型安全、构建检查、Git工作流、文件组织 | 🔴 |
| **一、数据获取策略** | ISR、API缓存、缓存失效、N+1优化、并行查询 | 🔴 |
| **二、导航与链接规范** | Link组件优先、a标签限制、中间件路由保护 | 🔴 |
| **三、图片优化规范** | LazyImage强制使用、LCP优先加载、远程图片配置 | 🔴 |
| **四、无障碍规范** | Skip Link、语义化HTML、ARIA/键盘交互、焦点对比度 | 🔴 |
| **五、结构化数据与SEO** | JSON-LD、metadata、Canonical URL、Robots策略 | 🔴 |
| **六、性能规范** | 组件懒加载、虚拟滚动、字体优化、Suspense、Bundle体积 | 🔴 |
| **七、安全规范** | CSP、XSS防护、Zod输入验证、认证授权、敏感信息、Bot防护 | 🔴 |
| **八、定时任务规范** | Crontab管理、任务日志、备份脚本、错误处理、幂等性、Entrypoint规范、日志规范 | 🔴 |
| **九、测试规范** | Vitest框架、80%覆盖率、三类测试、禁止skip | 🟡 |
| **十、设计系统速查** | 颜色/圆角/阴影/动画Token | 🟡 |
| **十一、API约定速查** | 前缀/分页/返回格式 | 🟡 |
| **十二、踩坑记录** | Next.js/Prisma/Docker/Chart.js等实际问题与解决 | — |
| **十三、Shell脚本规范** | 脚本结构、set -e、结构化输出、资源预检、禁止操作 | 🟡 |
| **十四、Docker容器规范** | 容器清单、管理命令、host网络、健康检查 | 🟡 |
| **十五、部署规范** | 部署前自检、构建流程、部署后六项验证、回滚策略 | 🔴 |
| **十六、数据模型与迁移规范** | Prisma命名约定、连接单例、Schema变更流程、数据库隔离 | 🔴 |
| **十七、API设计规范** | 路由骨架、错误处理、响应格式、状态码、缓存控制、认证分层 | 🔴 |
| **十八、AI/Bot系统规范** | Bot角色定义、12张Bot表、活动脚本约定、AI API隔离、提示词管理 | 🔴 |
| **十九、环境变量管理规范** | 变量分级、安全规则、脚本侧加载 | 🔴 |
| **二十、依赖管理规范** | 添加/删除/版本管理 | 🟡 |
| **二十一、代码审查清单** | 12项提交前自检+Knowledge Graph同步规则 | 🟡 |

## 关键规则速查

### 代码提交前必检
```bash
npx tsc --noEmit    # TypeScript 零错误
npx vitest run      # 所有测试通过
```

### 核心禁止事项
- 禁止 `any` 类型 / `as` 强制断言
- 禁止 N+1 查询 / 串行 await
- 禁止 `<img>` 标签（必须用 LazyImage）
- 禁止 `<button onClick={router.push}>`（必须用 Link）
- 禁止硬编码 API Key / 密码
- 禁止 `dangerouslySetInnerHTML`（除非消毒）
- 禁止 DROP / TRUNCATE / 裸 rm -rf

### 新增任务同步四方
1. `scripts/task-xxx.mjs` — 创建脚本
2. `crontab.txt` — 添加 supercronic 条目
3. `seed-task-configs.mjs` — 注册 TaskConfig
4. `health-check.mjs` — 添加监控 key

### 部署后六项验证
- `docker ps --filter name=zhuiguang-ai` — 两个容器 healthy
- `curl -I https://www.zhuig.com` — 200 / < 3s
- `ss -tlnp | grep :8301` — 端口为 Docker
- `docker logs --tail 20 zhuiguang-ai-app` — 无 FATAL/ERROR
- `docker logs --tail 20 zhuiguang-ai-cron` — "Container ready"
- 其他项目容器仍在运行

## 版本历史
- 2026-06-23: 第三轮优化 — 新增6章（数据模型/API设计/Bot系统/环境变量/依赖/审查清单）
- 2026-06-22: 第二轮优化 — 新增3章（Shell/Docker/部署）+ Entrypoint/日志子章节
- 2026-06-22: 第一轮优化 — 8章→12章，TypeScript/Git/测试/性能/安全/无障碍全面增强