lehuo/docs/08_ENGINEERING_RULES.md

08 工程开发规则

1. Monorepo

推荐 pnpm workspace。

根命令：

pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build

必须保证 CI 与本地命令一致。

---

2. 包管理

• 锁定 package manager 版本；
• 提交 lockfile；
• 不混 npm/yarn/pnpm；
• 国内开发可配置可靠 npm 镜像，但源码不得依赖私有个人镜像；
• CI 应支持官方源回退。

---

3. TypeScript

• strict: true
• 禁止大面积 any
• 禁止 @ts-ignore 掩盖错误；特殊情况写原因
• API contracts 明确类型
• 日期统一 ISO 8601

---

4. Git

分支：

• main
• develop（可选）
• feature/*
• fix/*
• chore/*

Commit 建议 Conventional Commits。

每个 PR：

• 变更摘要
• 测试结果
• 截图（UI）
• migration 说明
• 风险
• 回滚方案

---

5. 环境变量

.env.example 只能放占位符。

示例：

APP_ENV=development
DATABASE_URL=
REDIS_URL=
WECHAT_APP_ID=
WECHAT_APP_SECRET=
COS_BUCKET=
COS_REGION=
COS_SECRET_ID=
COS_SECRET_KEY=
SESSION_SECRET=
FIELD_ENCRYPTION_KEY=

真实密钥不得入 Git。

---

6. 数据库 Migration

规则：

• 每次 schema 修改一份 migration；
• migration 可审查；
• 生产不允许 ORM 自动 synchronize=true；
• 大表变更考虑锁；
• destructive migration 分阶段。

---

7. 代码质量

函数：

• 单一职责；
• 复杂度高就拆；
• 业务规则命名表达含义；
• 不写 1000 行 service；
• 不复制粘贴权限逻辑。

必须有：

• lint
• format
• typecheck
• unit test
• integration test

---

8. 错误处理

后端：

• 业务错误使用统一 Domain/Application Error；
• 未预期错误不把 stack 返回用户；
• requestId 贯穿。

前端：

• 业务错误直接友好提示；
• 网络错误可重试；
• 401 统一重新登录；
• 403 明确无权限；
• 5xx 提供 requestId。

---

9. 第三方依赖

新增依赖前：

1. 是否真有必要？
2. 是否长期维护？
3. License 是否可用？
4. 是否显著增大 bundle？
5. 是否国内网络可获取？
6. 能否用现有依赖实现？

避免“为了 10 行代码引入一个包”。

---

10. Codex 禁止行为

• 不读文档直接重构；
• 看到旧代码就全量重写；
• 为通过测试删除测试；
• 用 mock 替代真实功能后宣称完成；
• 注释掉权限；
• 关闭类型检查；
• catch {} 吞错误；
• 生产环境 hardcode；
• 把敏感值写 fixtures；
• 删除 migration 历史；
• 改 API 不更新前端和 contracts；
• 自己决定产品删减。

---

11. Definition of Done

一个任务只有同时满足以下条件才算完成：

• 功能实现；
• 正常路径测试；
• 异常路径测试；
• 权限测试；
• 数据 migration 完成；
• 文档更新；
• lint 通过；
• typecheck 通过；
• test 通过；
• build 通过；
• 无新 High/Critical 漏洞；
• 10_TASK_STATE.md 已回写。