zhuiguang-ai/.trae/specs/modules/17-rules.md

开发规则模块

概述

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

• 文件: .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同步规则	🟡

关键规则速查

代码提交前必检

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/测试/性能/安全/无障碍全面增强