# 08 工程开发规则

## 1. Monorepo

推荐 pnpm workspace。

根命令：

```bash
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` 只能放占位符。

示例：

```env
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` 已回写。