# 项目工程规则

版本：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”。
- 禁止“服务层通过具体仓储断言完成业务”。
- 禁止“因为终端乱码就把乱码字面量继续扩散到业务逻辑”。