rogee
b875149605
- compose: 去掉 control 网络的 internal 标记（internal 网络上 Docker 会静默丢弃端口发布，导致局域网无法访问） - docker-gateway: 浏览器网络改为普通 bridge，移除 internal+禁 ICC - AGENTS.md: 新增开发阶段原则（仅业务功能、不做访问限制、安全自管），删除输入信任/风控/敏感日志约束 - docs/README: 同步移除 localhost-only 与网络隔离声明 - 端口改为 8082（8080 被 multica-backend-1 占用）
46 lines
4.3 KiB
Markdown
46 lines
4.3 KiB
Markdown
# 仓库规范
|
||
|
||
## 开发阶段原则
|
||
|
||
- 开发阶段仅关注业务功能：不实现访问限制、认证、网络隔离等安全策略，安全由用户自行把控。
|
||
|
||
- 保持变更小而独立可评审，并附带覆盖该变更的最小相关检查。
|
||
- 使用下方已批准的技术栈；在栈内优先复用现有代码、标准库和平台原生能力，而非新增依赖或抽象。
|
||
- 在集成边界保持幂等性和向后兼容；文档化重试与失败行为。
|
||
- 永不提交密钥、生产凭据或个人账号数据。
|
||
- 引用上游项目时，记录其来源与许可证；除非许可证明确允许复用，否则须独立实现。
|
||
|
||
## 已批准的技术栈
|
||
|
||
### Go 后端
|
||
|
||
- 使用 Go 1.26、Fiber v3（HTTP 路由与服务生命周期）、Viper（配置）、Logrus（应用日志）、Cobra（可执行入口）。依赖版本由 `go.mod` 和 `go.sum` 精确锁定。
|
||
- 保留成熟的标准库集成，如反向代理和 Docker HTTP 客户端，不重复造轮子。`net/http` handler 跨越 Fiber 边界时，使用 Fiber 官方适配器。
|
||
- 创建局部 `viper.New()` 实例，只绑定支持的输入，显式应用默认值，并在产生网络、文件系统或 Docker 副作用前完成全部配置校验。未经评审的需求批准，不使用 Viper 全局单例、远程 provider 或热加载。
|
||
- 通过 Logrus 输出结构化 JSON 日志，保持 `service` 等稳定字段。可复用代码只返回错误，并在服务边界记录一次。
|
||
- 每个服务只保留一个最小化的 Cobra 根命令。仅当存在真实的运维工作流需求时，才添加子命令、持久化 flag、代码生成器或补全。
|
||
- 未经评审的需求批准，不添加 ORM、Redis、任务框架或另一套 HTTP/配置/日志/CLI 技术栈。
|
||
|
||
### React 前端
|
||
|
||
- 使用 React 19、Vite 8、`react-admin` 5.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 移交指定交付角色。
|