ocdp v1

2025-11-13 02:54:06 +00:00
commit c5e51ed069
254 changed files with 54901 additions and 0 deletions
--- a/docs/archive/root-cleanup/CAMELCASE-MIGRATION.md
+++ b/docs/archive/root-cleanup/CAMELCASE-MIGRATION.md
@ -0,0 +1,207 @@
+# 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 最佳实践！
+