186 lines
2.9 KiB
Markdown
186 lines
2.9 KiB
Markdown
# 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` 已回写。
|