long-agent
4193b46b5f
Changes: - Add FALSE_COMPLETION_PREVENTION.md documenting false completion patterns - Add integrity check script (scripts/check-integrity.sh) for automated verification - Fix swagger annotation gaps in 3 handlers (+10 annotations): - password_reset_handler.go: +4 annotations - totp_handler.go: +4 annotations - log_handler.go: +2 annotations - Define IntegrationRedisSuite type for Redis integration tests - Update QUALITY_STANDARD.md with swagger completeness and response format requirements - Update PROJECT_EXPERIENCE_SUMMARY.md with new learnings on false completion Integrity check now validates: - Swagger annotation completeness per handler - Response format uniformity (with OAuth whitelist) - Test infrastructure type definitions - Repository test coverage
305 lines
11 KiB
Markdown
305 lines
11 KiB
Markdown
# 项目工程规则
|
||
|
||
版本：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` 标签。
|
||
|