# 项目工程规则

版本：3.0  
更新时间：2026-04-02

本规则是当前项目的真实工程约束，不是泛化建议。

## 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` 防线
- 用户主流程

### 4.4 测试覆盖要求

- 新增代码必须有对应测试。
- 修复 bug 必须有回归测试。
- 安全敏感代码必须有边界条件测试。
- 每个函数/方法必须有对应的单元测试。
- 跨模块交互必须有集成测试。
- 用户主流程必须有真实浏览器 E2E 测试。

### 4.5 防虚假测试规则

- 禁止使用 mock 响应替代真实 API 调用进行 E2E 验证。
- 禁止在测试中硬编码预期结果而不走真实业务链路。
- 禁止跳过认证、权限校验等安全环节直接断言页面状态。
- 禁止在测试中使用 `context.Background()` 绕过上下文治理。
- 禁止在测试中注入假数据后直接断言页面显示而不验证后端存储。
- 禁止用 `smoke` 脚本的结果替代主验收路径。

### 4.6 E2E 测试架构要求

- E2E 测试必须：
  - 启动真实后端进程（隔离测试数据库）
  - 启动真实前端开发服务器
  - 通过真实浏览器（CDP 协议）执行用户操作
  - 验证真实 API 响应（非 mock）
  - 验证真实数据库状态变化
- 当前项目的真实 E2E 路径：
  - Playwright CDP E2E：`cd frontend/admin && npm.cmd run e2e:full:win`
  - 覆盖场景：管理员引导、注册、邮箱激活、登录、认证工作流、响应式布局、桌面/移动端导航
- E2E 测试架构组件：
  - Playwright CDP 协议连接真实浏览器
  - 隔离测试数据库（临时 SQLite 文件）
  - 本地 SMTP 捕获服务（验证邮件发送）
  - 信号收集器（console errors、dialogs、popups、request failures、401 responses）
  - 多视口验证（desktop 1440x960、tablet 820x1180、mobile 390x844）
- 未来增强方向：
  - 引入 `agent-browser`（bb browse）等浏览器自动化工具，补充 Playwright 未覆盖的交互场景
  - 增加复杂业务流程的端到端验证（如设备信任、批量操作、系统设置等）

## 5. 方案对比机制

### 5.1 何时需要方案对比

- 新增核心功能或架构变更时。
- 存在多种可行实现路径时。
- 性能优化涉及重大权衡时。

### 5.2 对比维度

- 实现复杂度（人天/智能体时）
- 性能影响
- 可维护性
- 与现有架构的兼容性
- 测试难度

### 5.3 决策记录

- 选定的方案必须记录决策原因。
- 被否决的方案必须记录否决原因。
- 决策记录写入 PR 描述或 `docs/decisions/` 目录。

## 6. 文档规则

- 真实状态变化后必须更新 `docs/status/REAL_PROJECT_STATUS.md`。
- 团队长期规则变化后必须更新本文件和 `docs/team/PRODUCTION_CHECKLIST.md`。
- 形成阶段性经验后必须沉淀到 `docs/team/PROJECT_EXPERIENCE_SUMMARY.md`。
- 新增架构决策时，写入 `docs/decisions/` 目录。

## 7. Gitea 协作规则

### 7.1 分支策略

- `main` 分支：始终可构建、可测试通过，是唯一的发布基线。
- `feature/<简短描述>`：功能分支，每个独立功能一个分支。
- `fix/<简短描述>`：修复分支，每个独立修复一个分支。
- 禁止直接推送到 `main`，所有变更必须通过 PR 合并。

### 7.2 PR 规范

- 每个 PR 只包含一个逻辑变更。
- PR 描述必须包含：
  - 变更目的（1-2 句）
  - 验证命令及结果
  - 影响范围（后端/前端/文档）
- PR 合并前必须通过最低验证矩阵。

### 7.3 提交规范

- 提交信息格式：`类型: 简短描述`
  - 类型：`feat`、`fix`、`test`、`docs`、`refactor`、`chore`
- 每次提交应该是可独立验证的最小单元。

## 8. 多智能体并行工作流

### 8.1 任务拆分原则

- 每个任务必须是独立的、可并行执行的单元。
- 任务之间如果有依赖，必须明确标注依赖关系和执行顺序。
- 前后端分离的任务优先并行执行。

### 8.2 并行执行模式

- **方案对比阶段**：多个智能体并行输出不同方案，由决策者选择最优解。
- **实现阶段**：无依赖的任务并行执行，有依赖的任务按拓扑序执行。
- **验证阶段**：后端测试、前端 lint/build、E2E 测试并行执行。

### 8.3 智能体分工

- **规划智能体**：负责任务拆分、依赖分析、方案对比。
- **实现智能体**：负责编码，每个智能体负责一个独立任务。
- **验证智能体**：负责测试执行、结果验证、报告生成。
- **审查智能体**：负责代码审查、安全审查、性能审查。

### 8.4 冲突解决

- 多个智能体修改同一文件时，必须在任务拆分阶段识别并协调。
- 如果发生合并冲突，优先保留功能完整的版本，手动合并差异。

## 9. 快速迭代规则

### 9.1 迭代节奏

- 小步快跑：每个迭代周期不超过 2 小时。
- 持续验证：每个迭代完成后立即执行验证矩阵。
- 快速回滚：如果验证失败，立即回滚到上一个可用状态。

### 9.2 阻塞处理

- 遇到阻塞时，立即记录阻塞原因和影响范围。
- 优先寻找替代方案，而不是等待阻塞解除。
- 阻塞超过 30 分钟必须上报并寻求协助。

### 9.3 知识沉淀

- 每次解决的问题必须记录解决方案。
- 每次踩过的坑必须记录避免方法。
- 每次验证通过的命令必须记录执行结果。

## 10. 禁止项

- 禁止"只跑单个用例就宣布收口"。
- 禁止"因为环境受限就把诊断脚本包装成主验收路径"。
- 禁止"为了通过测试保留运行时 mock provider"。
- 禁止"服务层通过具体仓储断言完成业务"。
- 禁止"因为终端乱码就把乱码字面量继续扩散到业务逻辑"。
- 禁止"用 mock 响应替代真实 API 调用进行 E2E 验证"。
- 禁止"在测试中硬编码预期结果而不走真实业务链路"。
- 禁止"跳过认证、权限校验等安全环节直接断言页面状态"。

## 11. 2026-04-10 多轮 Review 新增质量规则

### 11.1 stub 转 live 的复核门槛

- 任何从 stub、mock、`not implemented` 切换为 live 的接口，都必须重新做权限边界审查，不能沿用“之前只是占位实现”的风险判断。
- 这类改动至少补齐：正向用例、负向权限用例、边界条件用例、失败回滚用例。
- 若 live 化后暴露新治理风险，结论应以新风险为准，禁止因为“功能终于通了”而降低审查标准。

### 11.2 RBAC / 管理员治理规则

- `GetUserRoles`、`AssignRoles`、`CreateAdmin`、`DeleteAdmin` 这类能力必须有显式权限控制，不能默认任何已登录用户可读写他人角色数据。
- 管理员治理必须包含 `self-action` 与 `last-admin` 防护：禁止自删管理员、禁止删除最后一个管理员、禁止把系统带入无管理员状态。
- 角色赋权、管理员创建、管理员删除这类多步写操作必须具备事务性；若底层不支持事务，必须提供显式回滚并有对应测试。
- 禁止在已有可靠角色解析或引导链路之外，再引入硬编码角色 ID 作为生产逻辑捷径。

### 11.3 干净通过的定义

- `go test ./... -count=1` 与 `cd frontend/admin && npm.cmd run e2e:full:win` 是当前项目的真实发布门槛；局部命令绿灯、单步 build 绿灯、`-short` 绿灯都不能替代。
- 文档支持的主入口命令本身必须可复现；脚本包装器、临时缓存路径、工作目录切换等任一层失败，都应按真实失败处理。
- 测试完成后若仍输出 `window.alert`、`window.confirm`、`window.prompt`、`window.open` 或对应的 jsdom `Not implemented` 噪声，不算干净通过，必须继续治理。

### 11.4 文档同步要求

- review 结论改变后，必须同步更新状态文档、门槛文档、技术指引和经验文档，禁止让旧结论继续充当协作依据。
- 文档中的”已闭环””可上线””已收口”表述，必须对应实际执行过的命令结果和当前支持的主验收入口。

### 11.5 Swagger 注解完整性要求

- **每个 handler 方法必须有完整的 swagger 注解**，包括 `@Summary`、`@Description`、`@Tags`、`@Param`、`@Success`、`@Router`。
- 验证方法：每个新增方法必须通过 `grep -E “^func \(h \*[A-Za-z]+.*\) [A-Z]” <handler>.go | wc -l` 与 `grep -c “@Summary” <handler>.go` 比对。
- 禁止：只给部分方法添加注解就声称”已完成 swagger 文档”。

### 11.6 响应格式统一性要求

- **所有 API 必须使用统一响应格式**：`gin.H{“code”: 0, “message”: “success”, “data”: ...}`
- **白名单例外**（RFC 标准要求直接返回）：
  - OAuth Token 端点（`/oauth/token`）
  - OpenID Connect UserInfo 端点
- **禁止**：在声称”已统一响应格式”后，仍有 handler 直接返回自定义结构体。
- 验证方法：`grep -rn “c.JSON.*TokenResponse\|c.JSON.*IntrospectResponse” internal/api/handler/`

### 11.7 测试基础设施完整性要求

- 所有测试引用的类型必须在代码库中定义。
- 验证方法：`grep -r “type IntegrationRedisSuite” internal/repository/` 必须返回定义位置。
- 禁止：测试文件引用未定义的类型，即使该测试有 `//go:build integration` 标签。