项目开发规范 (Project SPEC)
版本：v1.0 | 生效日期：2026-03-06
技术栈
| 层级 | 技术 |
|---|---|
| 后端语言 | Go |
| 前端语言 | Vue |
| 后端框架 | Gin + MySQL + Redis |
| 项目架构 | Linux + Nginx + MySQL + Go + Vue |
代码架构
- 前后端严格分离
- 后端接口通过 Nginx 反向代理，路径前缀：
/api/v1/ - 后端框架仓库：
https://git.clawzone.ai/framework/go - 前端框架仓库：
https://git.clawzone.ai/framework/vue
文档规范
文档存放于后端仓库，目录结构：
doc/
design/ # 设计文档（PRD / 原型 / 数据库设计）
api/ # API 定义（Swagger 格式，RESTful 规范）
schedule/ # 排期计划
deployment/ # 部署文档（环境要求、部署步骤、回滚方案）
migrations/ # 数据库变更 SQL
CHANGELOG.md # 版本变更日志
版本管理
- 起始版本：
0.0.1 - 版本规则：
major.minor.patch- major：重大变更 / 不兼容
- minor：新功能
- patch：bug 修复
- 版本标记：Git Tag +
CHANGELOG.md - 每个需求在独立分支开发，完成后提交 Merge Request
- 合并方式：rebase
登录认证
- 认证方式：Google SSO（OAuth）
- 登录态：JWT，前端存于
localStorage - 后端 Token 存入 Redis，有效期 4 小时，每次请求自动续期
- 过期用户直接踢出
- 登出时：删除 Redis Token Key + 前端清除 localStorage
错误码规范
错误响应格式：
{"code": -10001, "message": "用户不存在", "data": null}
错误码分段：
| 区间 | 用途 |
|---|---|
| [-20000, -10000) | 通用 |
| [-30000, -20000) | 用户认证 |
| [-40000, -30000) | 权限 |
成功响应规范
{"code": 0, "message": "ok", "data": {...}}
日志 & 监控
| 项目 | 规范 |
|---|---|
| 链路追踪 | OpenTelemetry + Jaeger，覆盖所有 DB 操作 |
| TraceID | Gin 中间件统一生成 UUID |
| 日志与 TraceID 打通 | 是 |
| 存储方式 | 文件，路径：/opt/weblogs/{项目名称} |
| 日志格式 | JSON（兼容 ELK） |
| 日志级别 | debug / info / warn / error |
| 日志轮转 | 按天切割 |
| 保留期限 | 生产 30 天 / 测试 7 天（手动脚本） |
| 日志分类 | 请求日志 vs 业务日志分开存 |
| 告警 | error 级别通过 Telegram 通知 |
测试规范
- 开发模式：TDD
- 单元测试：
testify - 集成测试：
httptest - CI 测试门禁：
- 整体覆盖率 ≥ 70%
- 核心业务覆盖率 ≥ 90%
数据库变更规范
- 工具：Archery
- 变更文件存放：
migrations/ - 命名规则：
V001__create_user_table.sql（按版本顺序） - 禁止修改已执行的文件
配置管理
- 使用
.env文件管理配置 - 禁止硬编码 DB / Redis / 密钥等敏感配置
国际化（i18n）
| 层 | 实现 |
|---|---|
| 前端 | vue-i18n，通过请求头 Accept-Language 识别 |
| 后端 | error message 存 MySQL，支持多语言，启动时加载内存缓存 |
| 热更新 | 支持管理后台热更新（无需重启） |
| 当前支持语言 | 中文 / 英文 |
部署说明
| 项目 | 规范 |
|---|---|
| 部署方式 | 纯手动部署 |
| HTTPS | 强制 HTTP → HTTPS 跳转 |
| 数据库备份 | GCP 工具每天定时备份，保留 30 天 |
| 数据库变更 | Archery |