Immutable. This exact content is served forever at /api/v1/blob/3094bd3f6f09a493.
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Build & Development Commands
### Backend (Go)
```bash
cd server
go mod tidy # 安装依赖
go run main.go # 运行服务
go build -o vega-backend # 构建
go test ./... # 运行所有测试
go test -v ./logics/catalog/... # 运行单个包的测试
go vet ./... # 静态检查
```
### Frontend (React)
```bash
cd frontend
npm install # 安装依赖
npm run dev # 开发服务器
npm run build # 生产构建
npm run lint # ESLint 检查
npm run preview # 预览构建结果
```
### Configuration
服务配置文件: `./config/vega-backend-config.yaml`
## Architecture
VEGA Manager 采用六边形架构 (Hexagonal Architecture / Ports & Adapters):
```
server/
├── interfaces/ # 端口定义 (Ports) - 服务和数据访问接口
├── logics/ # 核心业务逻辑 - 服务实现
│ ├── catalog/ # Catalog 服务
│ ├── resource/ # Resource 服务
│ └── connectors/ # 数据源连接器 (Factory 模式)
├── driveradapters/ # 主适配器 (Primary Adapters) - HTTP REST 处理器
└── drivenadapters/ # 次适配器 (Secondary Adapters) - 数据库访问、外部服务
├── catalog/ # Catalog 数据访问
├── resource/ # Resource 数据访问
└── opensearch/ # OpenSearch 客户端
```
### 核心概念
**Catalog (数据目录)**: 数据源连接，可以是物理数据源(MySQL, S3, Kafka等)或逻辑目录(虚拟视图)
**Resource (数据资源)**: 数据资源实体，支持9种类型:
- 物理: table, file, fileset, api, metric, topic, index
- 逻辑: logicview, dataset
**Connectors**: 可插拔的数据源连接器，按类型组织在 `logics/connectors/`:
- table/ (MySQL, PostgreSQL, 达梦, Oracle, ClickHouse)
- index/ (OpenSearch, Elasticsearch)
- 计划中: fileset/, topic/, metric/, api/
### REST API
基础路径: `/api/vega-backend/v1`
| 资源 | 端点 |
|------|------|
| Catalog | GET/POST `/catalogs`, GET/PUT/DELETE `/catalogs/:id` |
| Catalog 状态 | GET `/catalogs/:id/status`, POST `/catalogs/:id/test-connection` |
| Resource | GET/POST `/resources`, GET/PUT/DELETE `/resources/:id` |
| Resource 操作 | GET `/resources/:id/schema`, POST `/resources/:id/enable\|disable\|sync` |
| 健康检查 | GET `/health` |
#### 端点设计规则
**禁止新增"嵌套列表"端点**：不要为"列出某个父资源下的子资源"再开 `GET /{parent}/{parent_id}/{children}` 这种端点。
- 正确做法：在 `/{children}` 列表端点上加 query 过滤，如 `GET /build-tasks?resource_id={id}` 而不是 `GET /resources/{id}/build-tasks`。
- 理由：(1) 子资源的列表语义已由 `/{children}` 承载，嵌套形态会让同一查询暴露在两个端点，OpenAPI / SDK 表达分裂；(2) 父资源的存在性校验属于"过滤参数指向不存在实体"——这种情况 list 端点应当返回空列表，而不是 404；如果真要做存在性校验，那它是动作类语义而非列表，应另设端点。
- 例外：动作端点保留嵌套形态（`POST /catalogs/:id/discover`、`POST /build-tasks/:id/start`），因为它们对父资源做操作，不是单纯的列表视图。
**列表端点的过滤参数命名**：`?{singular_parent}_id=` 或 `?{filter}_id=`，单值。要支持多值过滤时使用 `?{singular_parent}_ids=a,b,c`（逗号分隔）或 query 重复 `?id=a&id=b`，不要走 path。
**批量删除走 path**：`DELETE /{resource}/{ids}`（逗号分隔，单条即长度 1 的退化），与 `/catalogs/:ids`、`/resources/:ids` 对齐；不要用 `?ids=` query 形态。语义：整体事务，任一预校验失败整批不删。可选 `?ignore_missing=true` 放宽不存在性检查；状态类拦截（如 running task）不可绕过。
## Database
MariaDB/MySQL 8.0+，主要表:
- `t_catalog` - 目录/数据源配置
- `t_resource` - 数据资源定义，含 schema (JSON)
- `t_resource_schema_history` - Schema 变更历史
迁移脚本: `migrations/mariadb/`
### Schema 字段类型系统
VEGA 统一类型: `integer`, `unsigned_integer`, `float`, `decimal`, `string`, `text`, `date`, `datetime`, `time`, `boolean`, `binary`, `json`, `vector`
字段特征 (Features): `keyword`, `fulltext`, `vector`
## Frontend
React 19 + Vite + Tailwind CSS + React Router
路由:
- `/` - Dashboard
- `/catalogs` - 目录管理
- `/resources` - 资源列表
- `/resources/:id` - 资源详情
- `/query` - 查询工作台
## Development Conventions
- 所有代码注释使用中文
- 依赖注入通过构造函数，接口定义在 `interfaces/`
- 错误码定义在 `errors/`，国际化在 `locale/`
- 新增连接器类型需在 `logics/connectors/factory/` 注册