user-system/docs/team/QUALITY_STANDARD.md

项目工程规则

版本：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 后端最低门槛

go test ./... -count=1
go vet ./...
go build ./cmd/server

4.2 前端最低门槛

cd frontend/admin
npm.cmd run lint
npm.cmd run build

4.3 真实浏览器最低门槛

以下改动必须执行：

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