# 开发规范

## Git 工作流

### 分支策略

| 分支 | 说明 |
|------|------|
| `main` / `master` | 生产分支，保护分支 |
| `dev` | 开发集成分支 |
| `feature/*` | 功能分支 |
| `fix/*` | 修复分支 |
| `hotfix/*` | 紧急修复 |

### 提交规范

```
<type>: <description>

- 变更点 1
- 变更点 2
```

Type 列表：
- `feat`: 新功能
- `fix`: Bug 修复
- `refactor`: 重构
- `docs`: 文档
- `style`: 样式
- `test`: 测试
- `chore`: 构建/工具

示例：
```
feat: 添加服务器批量导入功能

- 支持 Excel 导入
- 支持云平台同步
```

## 后端规范（Go）

### 目录职责

| 目录 | 职责 |
|------|------|
| `main.go` / `embed.go` | 应用入口 + 前端嵌入 |
| `controller/` | HTTP 请求处理（参数校验、响应） |
| `model/` | 数据模型定义 |
| `config/` | 配置管理 (Viper) |
| `middleware/` | JWT / 日志 / CORS 中间件 |
| `router/` | 路由注册 |
| `service/` / `repository/` | 业务逻辑 / 数据访问 |
| `pkg/database/` | 数据库连接 + AutoMigrate |
| `pkg/logger/` | 日志工具 |
| `static/` | 前端 embed 静态资源 |

### 命名规范

- 文件名：`snake_case.go`
- 类型/方法：`PascalCase`
- 变量：`camelCase`
- 常量：`PascalCase` 或 `ALL_CAPS`

### 统一响应格式

```go
// 成功响应
c.JSON(http.StatusOK, models.Response{
    Code:    200,
    Message: "success",
    Data:    result,
})

// 分页响应
c.JSON(http.StatusOK, models.Response{
    Code:    200,
    Message: "success",
    Data: models.ListResponse{
        List:  items,
        Total: total,
    },
})

// 错误响应
c.JSON(http.StatusBadRequest, models.Response{
    Code:    400,
    Message: "参数错误: " + err.Error(),
})
```

### Handler 模板

```go
func (h *ServerHandler) CreateServer(c *gin.Context) {
    // 1. 参数绑定
    var req models.ServerRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, models.Response{Code: 400, Message: err.Error()})
        return
    }

    // 2. 业务逻辑
    server := models.Server{
        Name: req.Name,
        IP:   req.IP,
    }
    if err := h.db.Create(&server).Error; err != nil {
        c.JSON(http.StatusInternalServerError, models.Response{Code: 500, Message: "创建失败"})
        return
    }

    // 3. 返回结果
    c.JSON(http.StatusOK, models.Response{Code: 200, Message: "创建成功", Data: server})
}
```

### 注意事项

- GORM `First()` 连续查询会带上次 ID，用 `Take()` 代替
- Go 编译前设置 `GOPROXY=https://goproxy.cn,direct`
- SQLite 需要 `CGO_ENABLED=1`
- JWT 使用 `golang-jwt/jwt/v5`，`jwt.TimeFunc()` 已移除，用 `time.Now()`

## 前端规范（React + TypeScript）

### 目录职责

| 目录 | 职责 |
|------|------|
| `src/components/*/` | 业务组件 |
| `src/components/ui/` | shadcn/ui 基础组件 |
| `src/hooks/` | 自定义 Hooks |
| `src/lib/` | 工具函数 |
| `src/services/` | API 封装 |
| `src/store/` | Zustand 状态管理 |
| `src/types/` | TypeScript 类型 |
| `src/mocks/` | Mock 数据 |

### 命名规范

- 组件文件：`PascalCase.tsx`（如 `ServerManager.tsx`）
- 工具文件：`camelCase.ts`（如 `formatDate.ts`）
- 组件名：`PascalCase`

### UI 设计原则

- 能去掉的装饰都去掉（无边框、无多余分隔线）
- 选中态用 `bg-surface-active`，不用彩色高亮
- 页面打开即用，不需要额外的"新建"按钮跳转
- 操作成功不弹 toast，仅在失败时提示

### API 调用

前端通过 Vite 代理访问后端 API：

```typescript
// 开发环境请求会被代理到 http://localhost:8080
fetch('/api/v1/servers')
```

## 测试

### 后端测试

```bash
cd backend
go test -v ./...
```

### 前端构建测试

```bash
cd frontend
npm run build
npx tsc --noEmit   # 类型检查（提交前零错误）
```

### 独立二进制构建

```bash
./run.sh build tag v1.5.0
./aiops version
```

## 日志

| 级别 | 使用场景 |
|------|---------|
| Info | 服务启动、正常操作 |
| Warn | 配置缺失、降级处理 |
| Error | 操作失败、异常 |
| Fatal | 启动失败、不可恢复 |

```go
log.Info("server started", zap.String("port", cfg.Port))
log.Error("database error", zap.Error(err))
```