121 lines
2.9 KiB
Markdown
121 lines
2.9 KiB
Markdown
# 项目工程规则
|
||
|
||
版本：2.0
|
||
更新时间：2026-03-25
|
||
|
||
本规则是当前项目的真实工程约束，不是泛化建议。
|
||
|
||
## 1. 基本原则
|
||
|
||
- 结论必须可验证，不能靠口头“已完成”。
|
||
- 优先真实闭环，拒绝 fake success、临时掩盖和只过局部样例。
|
||
- 任何上线结论都必须区分：
|
||
- 浏览器级真实验证
|
||
- OS 级自动化
|
||
- 外部交付治理证据
|
||
|
||
## 2. 后端规则
|
||
|
||
### 2.1 运行时安全
|
||
|
||
- 非测试代码禁止保留 `panic` 作为常规失败路径。
|
||
- 配置不合法时应在启动期失败，不要运行后再暴露风险。
|
||
- 外部依赖缺失时必须显式禁用能力或启动失败，不能返回假成功。
|
||
|
||
### 2.2 错误处理
|
||
|
||
- 必须保留真实错误语义，不能吞错。
|
||
- 优先使用显式错误分类：
|
||
- 例如 rate limit
|
||
- validation
|
||
- internal failure
|
||
- 禁止长期依赖字符串子串判断错误类型。
|
||
|
||
### 2.3 分层设计
|
||
|
||
- service 层依赖接口能力，不依赖具体 repository 类型断言。
|
||
- repository 负责持久化细节，service 负责业务编排和错误分级。
|
||
- 外部副作用必须 fail closed，并处理回滚。
|
||
|
||
### 2.4 安全与配置
|
||
|
||
- 敏感值不得硬编码到配置模板。
|
||
- release 模式必须限制：
|
||
- 占位密钥
|
||
- localhost OAuth 回调
|
||
- `*` CORS 放行
|
||
- 不安全 JWT 配置
|
||
|
||
## 3. 前端规则
|
||
|
||
### 3.1 浏览器行为
|
||
|
||
- 原生弹窗和 popup 不是“可以接受的小问题”，而是验收失败信号。
|
||
- 必须阻断并记录：
|
||
- `alert`
|
||
- `confirm`
|
||
- `prompt`
|
||
- `open`
|
||
|
||
### 3.2 主链路要求
|
||
|
||
- 登录页、后台主导航、路由守卫、认证状态恢复必须进入真实浏览器回归。
|
||
- 认证能力展示必须跟随后端 `capabilities`，不能前端硬编码。
|
||
|
||
### 3.3 smoke 边界
|
||
|
||
- `smoke` 只允许存在于测试或诊断层。
|
||
- 任何产品运行时逻辑都不得依赖 `smoke`。
|
||
|
||
## 4. 验证规则
|
||
|
||
### 4.1 后端最低门槛
|
||
|
||
```powershell
|
||
go test ./... -count=1
|
||
go vet ./...
|
||
go build ./cmd/server
|
||
```
|
||
|
||
### 4.2 前端最低门槛
|
||
|
||
```powershell
|
||
cd frontend/admin
|
||
npm.cmd run lint
|
||
npm.cmd run build
|
||
```
|
||
|
||
### 4.3 真实浏览器最低门槛
|
||
|
||
以下改动必须执行：
|
||
|
||
```powershell
|
||
cd frontend/admin
|
||
npm.cmd run e2e:full:win
|
||
```
|
||
|
||
适用改动：
|
||
|
||
- 认证
|
||
- 会话
|
||
- OAuth
|
||
- 登录页
|
||
- 路由守卫
|
||
- 主导航
|
||
- `window` 防线
|
||
- 用户主流程
|
||
|
||
## 5. 文档规则
|
||
|
||
- 真实状态变化后必须更新 `docs/status/REAL_PROJECT_STATUS.md`。
|
||
- 团队长期规则变化后必须更新本文件和 `docs/team/PRODUCTION_CHECKLIST.md`。
|
||
- 形成阶段性经验后必须沉淀到 `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`。
|
||
|
||
## 6. 禁止项
|
||
|
||
- 禁止“只跑单个用例就宣布收口”。
|
||
- 禁止“因为环境受限就把诊断脚本包装成主验收路径”。
|
||
- 禁止“为了通过测试保留运行时 mock provider”。
|
||
- 禁止“服务层通过具体仓储断言完成业务”。
|
||
- 禁止“因为终端乱码就把乱码字面量继续扩散到业务逻辑”。
|