4.5 KiB
4.5 KiB
仓库规范
开发阶段原则
-
开发阶段仅关注业务功能：不实现访问限制、认证、网络隔离等安全策略，安全由用户自行把控。
-
开发阶段不做数据兼容：数据库 schema 可随时破坏性重建，不编写迁移兼容、存量回填或双写代码；网关与环境数据均可删除重来。
-
保持变更小而独立可评审，并附带覆盖该变更的最小相关检查。
-
使用下方已批准的技术栈；在栈内优先复用现有代码、标准库和平台原生能力，而非新增依赖或抽象。
-
在集成边界保持幂等性和向后兼容；文档化重试与失败行为。
-
永不提交密钥、生产凭据或个人账号数据。
-
引用上游项目时，记录其来源与许可证；除非许可证明确允许复用，否则须独立实现。
已批准的技术栈
Go 后端
- 使用 Go 1.26、Fiber v3（HTTP 路由与服务生命周期）、Viper（配置）、Logrus（应用日志）、Cobra（可执行入口）。依赖版本由
go.mod和go.sum精确锁定。 - 保留成熟的标准库集成，如反向代理和 Docker HTTP 客户端，不重复造轮子。
net/httphandler 跨越 Fiber 边界时，使用 Fiber 官方适配器。 - 创建局部
viper.New()实例，只绑定支持的输入，显式应用默认值，并在产生网络、文件系统或 Docker 副作用前完成全部配置校验。未经评审的需求批准，不使用 Viper 全局单例、远程 provider 或热加载。 - 通过 Logrus 输出结构化 JSON 日志，保持
service等稳定字段。可复用代码只返回错误，并在服务边界记录一次。 - 每个服务只保留一个最小化的 Cobra 根命令。仅当存在真实的运维工作流需求时，才添加子命令、持久化 flag、代码生成器或补全。
- 未经评审的需求批准，不添加 ORM、Redis、任务框架或另一套 HTTP/配置/日志/CLI 技术栈。
React 前端
- 使用 React 19、Vite 8、
react-admin5.15.x 和 MUI 9。在web/package-lock.json中锁定精确的已安装版本。 - 初始实现只使用开源版 react-admin 和 MUI 包。Enterprise Edition 与 MUI X Pro/Premium 需单独的产品与许可证评审。
- 视觉体系由 CreatorHub 自有掌控：品牌 token 保留在项目主题中，导航/外壳保留在项目自有的 Layout、AppBar 和 Menu 组件中。Mantis Free 可作为 MIT 许可的视觉参考，但不得导入或 fork 整个模板。
- 不将 Ant Design、Arco 或其他组件体系混入 react-admin/MUI 应用。
- 将启动、停止、回收等领域动作保留为显式动作；不得为迎合 react-admin 惯例而伪装成通用 CRUD 更新。
UI 替换边界
- 未来 UI 切换仅限于项目自有的 MUI 主题、Layout/AppBar/Menu，以及 react-admin
dataProvider边界。API 调用与响应映射放在 data provider 中，不放展示组件里。 - 现阶段不构建并行设计系统、框架中立的组件层或投机性的适配器层级。仅当具体替换方案无法被现有三处缝隙（seam）容纳时，才引入新边界。
- 从 MUI 或 react-admin 切换出去前必须经用户评审。替换现有 UI 栈，而非两套组件体系并行运行。
验证与交付
- 每个非平凡行为变更附带最小的回归测试，且该测试在无此变更时会失败。在信任与集成边界覆盖成功、校验、失败和兼容路径。
- 后端变更必须通过
go test ./...、go vet ./...，并完成./cmd/control-plane和./cmd/docker-gateway双端构建；涉及并发、生命周期或共享状态的变更须运行go test -race ./...。Docker 或 Compose 变更还须通过docker compose config --quiet。 - 前端变更必须从 lockfile 安装、通过仓库的非交互式测试命令，并通过
npm --prefix web run build。主题、Layout、导航、资源动作或 data provider 的变更需要聚焦的交互覆盖，包括适用的错误与禁用状态。 - 除非 issue 明确批准契约变更，保持既有 API 与 Docker 生命周期行为不变。在 PR 中文档化任何状态码、载荷、配置、迁移、安全或重试方面的影响。
- 每个 PR 限定于单个 issue，标题、正文或分支名中包含 issue 编号，并报告确切的验证命令与结果。除非 issue 明确要求，不使用 close intent。
- 每个代码 PR 均需独立评审。P0/P1 问题必须修复并复审；P2 问题记录为后续工作。实现 agent 不得合并、部署、发布或修改生产配置；将已批准的 PR 移交指定交付角色。