# camelCase Migration Summary

## 🎯 目标

将项目从 snake_case JSON 迁移到 camelCase JSON，符合 REST API 最佳实践和 Google JSON Style Guide。

## ✅ 实施方案 A：全面 camelCase

### 架构设计

```
Backend Go
├─ struct fields: PascalCase (Go 规范)
└─ json tags: camelCase → JSON: camelCase
     ↓
OpenAPI
├─ schemas: PascalCase
└─ properties: camelCase
     ↓ Orval
Frontend TypeScript
├─ interfaces: PascalCase (TS 规范)
├─ properties: camelCase (TS 规范)
└─ JSON: camelCase (REST 标准)
```

## 📝 修改清单

### 1. Backend Go - JSON Tags (✅ 完成)

修改所有 DTO 文件的 JSON tags 从 snake_case → camelCase：

- ✅ `backend/internal/adapter/input/http/dto/cluster_dto.go`
  - `ca_data` → `caData`
  - `cert_data` → `certData`
  - `key_data` → `keyData`
  - `has_ca_data` → `hasCaData`
  - `created_at` → `createdAt`
  - `updated_at` → `updatedAt`

- ✅ `backend/internal/adapter/input/http/dto/auth_dto.go`
  - `refresh_token` → `refreshToken`
  - `access_token` → `accessToken`
  - `user_id` → `userId`

- ✅ `backend/internal/adapter/input/http/dto/registry_dto.go`
  - `has_password` → `hasPassword`
  - `created_at` → `createdAt`
  - `updated_at` → `updatedAt`

- ✅ `backend/internal/adapter/input/http/dto/instance_dto.go`
  - `registry_id` → `registryId`
  - `cluster_id` → `clusterId`
  - `values_yaml` → `valuesYaml`
  - `keep_history` → `keepHistory`

- ✅ `backend/internal/adapter/input/http/dto/artifact_dto.go`
  - `registry_id` → `registryId`
  - `registry_url` → `registryUrl`
  - `repository_name` → `repositoryName`
  - `catalog_supported` → `catalogSupported`
  - `media_type` → `mediaType`

- ✅ `backend/internal/adapter/input/http/dto/monitoring_dto.go`
  - All monitoring metrics fields converted to camelCase

### 2. OpenAPI Specification (✅ 完成)

- ✅ 创建转换脚本: `backend/scripts/convert-openapi-to-camelcase.cjs`
- ✅ 转换 `backend/docs/openapi.yaml` 所有属性为 camelCase
- ✅ 备份原文件: `backend/docs/openapi.yaml.backup`

### 3. Frontend Setup (✅ 完成)

#### 安装 Orval
- ✅ 添加 `orval@7.3.0` 到 `package.json`
- ✅ 运行 `npm install`

#### 配置 Orval
- ✅ 创建 `frontend/orval.config.ts`
- ✅ 配置生成器指向 OpenAPI 文件
- ✅ 配置 Axios mutator

#### 创建 Axios Mutator
- ✅ 创建 `frontend/src/api/axios-mutator.ts`
- ✅ 配置 Axios 实例和拦截器

#### 更新脚本
- ✅ 修改 `package.json` 的 `openapi-gen` 脚本使用 Orval
- ✅ 修改 `Makefile` 的 `openapi-gen-frontend` 使用 Orval

#### 创建文档和示例
- ✅ 创建 `frontend/src/api/README.md`
- ✅ 创建 `frontend/src/api/example.ts`
- ✅ 更新 `frontend/src/api/index.ts`

### 4. 工具文件 (✅ 保留备用)

- ✅ `frontend/src/api/case-converter.ts` - 保留作为工具函数
- ✅ `frontend/scripts/post-process-openapi.cjs` - 保留作为备用方案

## 🚀 使用方法

### 重新生成 API 代码

```bash
# 从项目根目录
make openapi-gen-frontend

# 或从 frontend 目录
cd frontend
npm run openapi-gen
```

### 前端使用示例

```typescript
import { createCluster, setAuthToken } from '@/api';

// 设置 token
setAuthToken('your-jwt-token');

// 创建集群 - 全部使用 camelCase ✅
const cluster = await createCluster({
  name: 'my-cluster',
  host: 'https://k8s.example.com',
  caData: 'base64...',      // ✅ camelCase
  certData: 'base64...',    // ✅ camelCase
  keyData: 'base64...',     // ✅ camelCase
});
```

## 📊 变更统计

- **后端 Go 文件**: 6 个 DTO 文件修改
- **JSON Tags 转换**: ~50+ 字段
- **OpenAPI 属性**: ~50+ 属性转换
- **新增文件**: 7 个
  - `orval.config.ts`
  - `axios-mutator.ts`
  - `case-converter.ts`
  - `api/README.md`
  - `api/example.ts`
  - `convert-openapi-to-camelcase.cjs`
  - `CAMELCASE-MIGRATION.md`

## ✨ 优势

1. **符合标准**: 遵循 REST API 和 JSON 最佳实践
2. **类型安全**: 完整的 TypeScript 类型支持
3. **IDE 友好**: 自动补全和类型检查
4. **无性能损耗**: 无需运行时转换
5. **维护简单**: OpenAPI 驱动，自动生成
6. **前后端一致**: 统一的命名规范

## 🔍 验证

### 检查生成的类型

```bash
grep -A 5 "export interface CreateClusterRequest" \
  frontend/src/api/generated-orval/api.schemas.ts
```

应该看到:
```typescript
export interface CreateClusterRequest {
  caData?: string;        // ✅ camelCase
  certData?: string;      // ✅ camelCase
  keyData?: string;       // ✅ camelCase
  ...
}
```

### 测试 API 调用

```bash
# 启动后端
cd backend && make run-mock

# 启动前端
cd frontend && npm run dev

# 测试 API
curl -X POST http://localhost:8080/api/v1/clusters \
  -H "Content-Type: application/json" \
  -d '{"name":"test","host":"https://k8s.example.com","caData":"..."}'
```

## 📚 参考文档

- `frontend/src/api/README.md` - API 使用文档
- `frontend/src/api/example.ts` - 代码示例
- [Orval Documentation](https://orval.dev/)
- [Google JSON Style Guide](https://google.github.io/styleguide/jsoncstyleguide.xml)

## 🎉 完成状态

✅ **方案 A 已全面实施完成！**

所有代码已修改为使用 camelCase：
- ✅ 后端 Go JSON tags
- ✅ OpenAPI 规范
- ✅ 前端 TypeScript 类型
- ✅ JSON 传输格式

项目现在符合现代 REST API 最佳实践！