85ba15c564
- Go + Gin + GORM + PostgreSQL backend - RESTful API for material management - Docker deployment support - Database partitioning for billion-scale data - API documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
570 lines
11 KiB
Markdown
570 lines
11 KiB
Markdown
# 材质管理系统 API 文档
|
||
|
||
## 基础信息
|
||
|
||
- **Base URL**: `http://10.99.98.248:8081/api/v1`
|
||
- **认证方式**: API Token
|
||
- **Content-Type**: `application/json`
|
||
|
||
## 认证
|
||
|
||
所有API请求需要在Header中携带Token：
|
||
|
||
```
|
||
X-API-Token: seatons3d
|
||
```
|
||
|
||
错误响应示例：
|
||
```json
|
||
{
|
||
"code": 401,
|
||
"message": "missing API token"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 通用响应格式
|
||
|
||
### 成功响应
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
### 分页响应
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"items": [...],
|
||
"total": 303,
|
||
"page": 1,
|
||
"page_size": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "error description"
|
||
}
|
||
```
|
||
|
||
### 错误码
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 201 | 创建成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未授权（Token无效） |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 材质管理接口
|
||
|
||
### 1. 获取材质列表
|
||
|
||
**GET** `/materials`
|
||
|
||
#### 请求参数（Query）
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认20，最大100 |
|
||
| name | string | 否 | 按名称模糊搜索 |
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -H "X-API-Token: seatons3d" \
|
||
"http://10.99.98.248:8081/api/v1/materials?page=1&page_size=10&name=red"
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"id": 4,
|
||
"name": "dgnColor4",
|
||
"diffuse_r": 255,
|
||
"diffuse_g": 0,
|
||
"diffuse_b": 0,
|
||
"alpha": 255,
|
||
"shininess": 20,
|
||
"specular_r": 230,
|
||
"specular_g": 230,
|
||
"specular_b": 230,
|
||
"ambient_r": 50,
|
||
"ambient_g": 50,
|
||
"ambient_b": 50,
|
||
"metallic": 0,
|
||
"roughness": 0,
|
||
"reflectance": 0,
|
||
"created_at": "2025-12-09T09:53:33.209555Z",
|
||
"updated_at": "2025-12-09T09:53:33.209555Z"
|
||
}
|
||
],
|
||
"total": 303,
|
||
"page": 1,
|
||
"page_size": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 添加材质
|
||
|
||
**POST** `/materials`
|
||
|
||
#### 请求Body
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| name | string | 是 | 材质名称 |
|
||
| diffuse_r | float | 否 | 漫反射-红 (0-255) |
|
||
| diffuse_g | float | 否 | 漫反射-绿 (0-255) |
|
||
| diffuse_b | float | 否 | 漫反射-蓝 (0-255) |
|
||
| alpha | float | 否 | 透明度 (0-255) |
|
||
| shininess | float | 否 | 光泽度 |
|
||
| specular_r | float | 否 | 高光-红 (0-255) |
|
||
| specular_g | float | 否 | 高光-绿 (0-255) |
|
||
| specular_b | float | 否 | 高光-蓝 (0-255) |
|
||
| ambient_r | float | 否 | 环境光-红 (0-255) |
|
||
| ambient_g | float | 否 | 环境光-绿 (0-255) |
|
||
| ambient_b | float | 否 | 环境光-蓝 (0-255) |
|
||
| metallic | float | 否 | 金属度 |
|
||
| roughness | float | 否 | 粗糙度 |
|
||
| reflectance | float | 否 | 反射率 |
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X POST -H "X-API-Token: seatons3d" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "红色金属",
|
||
"diffuse_r": 255,
|
||
"diffuse_g": 50,
|
||
"diffuse_b": 50,
|
||
"alpha": 255,
|
||
"metallic": 0.8,
|
||
"roughness": 0.2
|
||
}' \
|
||
"http://10.99.98.248:8081/api/v1/materials"
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "created",
|
||
"data": {
|
||
"id": 305,
|
||
"name": "红色金属",
|
||
"diffuse_r": 255,
|
||
"diffuse_g": 50,
|
||
"diffuse_b": 50,
|
||
"alpha": 255,
|
||
"shininess": 0,
|
||
"specular_r": 0,
|
||
"specular_g": 0,
|
||
"specular_b": 0,
|
||
"ambient_r": 0,
|
||
"ambient_g": 0,
|
||
"ambient_b": 0,
|
||
"metallic": 0.8,
|
||
"roughness": 0.2,
|
||
"reflectance": 0.5,
|
||
"created_at": "2025-12-09T18:02:22.846141Z",
|
||
"updated_at": "2025-12-09T18:02:22.846141Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 获取材质详情
|
||
|
||
**GET** `/materials/:id`
|
||
|
||
#### 路径参数
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 材质ID |
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -H "X-API-Token: seatons3d" \
|
||
"http://10.99.98.248:8081/api/v1/materials/4"
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 4,
|
||
"name": "dgnColor4",
|
||
"diffuse_r": 255,
|
||
"diffuse_g": 0,
|
||
"diffuse_b": 0,
|
||
"alpha": 255,
|
||
"shininess": 20,
|
||
"specular_r": 230,
|
||
"specular_g": 230,
|
||
"specular_b": 230,
|
||
"ambient_r": 50,
|
||
"ambient_g": 50,
|
||
"ambient_b": 50,
|
||
"metallic": 0,
|
||
"roughness": 0,
|
||
"reflectance": 0,
|
||
"created_at": "2025-12-09T09:53:33.209555Z",
|
||
"updated_at": "2025-12-09T09:53:33.209555Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 错误响应
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "material not found"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 编辑材质
|
||
|
||
**PUT** `/materials/:id`
|
||
|
||
#### 路径参数
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 材质ID |
|
||
|
||
#### 请求Body
|
||
同"添加材质"接口
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X PUT -H "X-API-Token: seatons3d" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "红色金属-更新版",
|
||
"diffuse_r": 200,
|
||
"diffuse_g": 100,
|
||
"diffuse_b": 50,
|
||
"alpha": 255,
|
||
"metallic": 0.9,
|
||
"roughness": 0.1
|
||
}' \
|
||
"http://10.99.98.248:8081/api/v1/materials/305"
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 305,
|
||
"name": "红色金属-更新版",
|
||
"diffuse_r": 200,
|
||
"diffuse_g": 100,
|
||
"diffuse_b": 50,
|
||
"alpha": 255,
|
||
...
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 删除材质
|
||
|
||
**DELETE** `/materials/:id`
|
||
|
||
#### 路径参数
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 材质ID |
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X DELETE -H "X-API-Token: seatons3d" \
|
||
"http://10.99.98.248:8081/api/v1/materials/305"
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 305
|
||
}
|
||
}
|
||
```
|
||
|
||
> **注意**: 删除材质会级联删除所有相关的绑定关系
|
||
|
||
---
|
||
|
||
## 绑定管理接口
|
||
|
||
### 6. 绑定材质到多个Group
|
||
|
||
**POST** `/materials/:id/bindings`
|
||
|
||
将一个材质绑定到多个叶子节点（group_id），支持幂等操作（重复绑定不会报错）。
|
||
|
||
#### 路径参数
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 材质ID |
|
||
|
||
#### 请求Body
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| group_ids | string[] | 是 | 叶子节点ID数组 |
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X POST -H "X-API-Token: seatons3d" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"group_ids": ["node_001", "node_002", "node_003"]
|
||
}' \
|
||
"http://10.99.98.248:8081/api/v1/materials/4/bindings"
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"material_id": 4,
|
||
"group_ids": ["node_001", "node_002", "node_003"]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 7. 解绑材质与Group
|
||
|
||
**DELETE** `/materials/:id/bindings`
|
||
|
||
#### 路径参数
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 材质ID |
|
||
|
||
#### 请求Body
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| group_ids | string[] | 是 | 要解绑的叶子节点ID数组 |
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X DELETE -H "X-API-Token: seatons3d" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"group_ids": ["node_001", "node_002"]
|
||
}' \
|
||
"http://10.99.98.248:8081/api/v1/materials/4/bindings"
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"material_id": 4,
|
||
"unbound": ["node_001", "node_002"]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 8. 获取材质关联的所有Group（分页）
|
||
|
||
**GET** `/materials/:id/groups`
|
||
|
||
#### 路径参数
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 材质ID |
|
||
|
||
#### 请求参数（Query）
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认20，最大100 |
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -H "X-API-Token: seatons3d" \
|
||
"http://10.99.98.248:8081/api/v1/materials/4/groups?page=1&page_size=10"
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"items": [
|
||
"20251021105717834754",
|
||
"20251021105717834758",
|
||
"20251021105717834762"
|
||
],
|
||
"total": 22,
|
||
"page": 1,
|
||
"page_size": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 9. 根据Group IDs批量查询关联材质
|
||
|
||
**POST** `/groups/materials`
|
||
|
||
根据一个或多个叶子节点ID，查询它们关联的材质详情。
|
||
|
||
#### 请求Body
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| group_ids | string[] | 是 | 叶子节点ID数组 |
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X POST -H "X-API-Token: seatons3d" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"group_ids": ["202510211057245681447", "aDsIXMkjxdm2CDUj9gTvf"]
|
||
}' \
|
||
"http://10.99.98.248:8081/api/v1/groups/materials"
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"group_id": "202510211057245681447",
|
||
"material": {
|
||
"id": 4,
|
||
"name": "dgnColor4",
|
||
"diffuse_r": 255,
|
||
"diffuse_g": 0,
|
||
"diffuse_b": 0,
|
||
"alpha": 255,
|
||
"shininess": 20,
|
||
"specular_r": 230,
|
||
"specular_g": 230,
|
||
"specular_b": 230,
|
||
"ambient_r": 50,
|
||
"ambient_g": 50,
|
||
"ambient_b": 50,
|
||
"metallic": 0,
|
||
"roughness": 0,
|
||
"reflectance": 0,
|
||
"created_at": "2025-12-09T09:53:33.209555Z",
|
||
"updated_at": "2025-12-09T09:53:33.209555Z"
|
||
}
|
||
},
|
||
{
|
||
"group_id": "aDsIXMkjxdm2CDUj9gTvf",
|
||
"material": {
|
||
"id": -1,
|
||
"name": "默认值",
|
||
"diffuse_r": 192,
|
||
"diffuse_g": 192,
|
||
"diffuse_b": 192,
|
||
...
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> **注意**: 如果某个group_id没有绑定材质，则不会出现在返回结果中
|
||
|
||
---
|
||
|
||
## 健康检查
|
||
|
||
**GET** `/health`
|
||
|
||
此接口无需认证。
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl http://10.99.98.248:8081/health
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"status": "ok"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### Material（材质）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int64 | 材质ID（主键） |
|
||
| name | string | 材质名称 |
|
||
| diffuse_r | float64 | 漫反射-红 (0-255) |
|
||
| diffuse_g | float64 | 漫反射-绿 (0-255) |
|
||
| diffuse_b | float64 | 漫反射-蓝 (0-255) |
|
||
| alpha | float64 | 透明度 (0-255) |
|
||
| shininess | float64 | 光泽度 |
|
||
| specular_r | float64 | 高光-红 (0-255) |
|
||
| specular_g | float64 | 高光-绿 (0-255) |
|
||
| specular_b | float64 | 高光-蓝 (0-255) |
|
||
| ambient_r | float64 | 环境光-红 (0-255) |
|
||
| ambient_g | float64 | 环境光-绿 (0-255) |
|
||
| ambient_b | float64 | 环境光-蓝 (0-255) |
|
||
| metallic | float64 | 金属度 |
|
||
| roughness | float64 | 粗糙度 |
|
||
| reflectance | float64 | 反射率 |
|
||
| created_at | timestamp | 创建时间 |
|
||
| updated_at | timestamp | 更新时间 |
|
||
|
||
### MaterialBinding（材质绑定）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int64 | 绑定ID（主键） |
|
||
| material_id | int64 | 材质ID（外键） |
|
||
| group_id | string | 叶子节点ID |
|
||
| created_at | timestamp | 创建时间 |
|