feat: complete V1 phases 0-7
This commit is contained in:
@@ -0,0 +1,185 @@
|
||||
# 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` 已回写。
|
||||
Reference in New Issue
Block a user