工程规范总述
技术栈、分支与提交、测试、发布的统一约定
技术栈
全项目只用两套技术栈：Go 和 TypeScript/React。
| 服务 | 后端 | 前端 | 数据库 |
|---|---|---|---|
oceanway-platform | Go（new-api 的 Gin + GORM） | React（Console、Admin） | PostgreSQL + Redis |
oceanway-studio（Studio、Drama、Commerce） | Next.js 全栈 | Next.js / React | PostgreSQL |
oceanway-site | 小型 Node 服务 | React + Vite，静态预渲染 | 无 |
oceanway-media-gateway | Go | React（供应管理后台） | PostgreSQL + Redis |
uumi（oceanway-text-gateway） | new-api，跟随上游 | new-api 自带 | 按 uumi 现有部署 |
新代码一律使用 TypeScript，不新增 JavaScript 文件；Drama 前端迁入时逐步转为 TypeScript。
分支与提交
main是现行版本。 每个仓库的main应该能代表当前最新的可用代码。- 短期分支开发。 功能分支从
main拉出，完成后合并回main并删除。分支名用feat/、fix/、docs/、chore/前缀。 - 每天推送。 本地提交当天推送到远端，不长期保留未推送的分支或未提交的改动。
- 快照分支不删除。
archive/2026-10-01-snapshot是架构重建前的完整快照，保留在远端。 - 提交信息。 使用
类型(范围): 说明的格式，例如feat(console): add usage filter by product。
2026-10-01 时多个仓库还停在快照分支或旧功能分支上，整理计划见仓库清单。
测试
- 涉及积分、扣费、充值的代码必须有自动化测试，覆盖重复提交、失败退回、余额不足等情况。
- 接入平台的代码（登录、模型调用、扣费）在每个子站都要有端到端的验证。
- 测试不调用付费的真实模型；需要真实调用时单独授权并记录。
发布
- 每次发布记录版本号和提交号，能回退到上一个版本。
- 生产密钥不进 Git，通过环境变量或密钥文件注入。
- 先在测试环境验证，再发布到生产。
具体环境见运维。