forked from erp-dev/erp
371 lines
8.0 KiB
Markdown
371 lines
8.0 KiB
Markdown
# 创建工艺参数 API 文档
|
||
|
||
## 接口信息
|
||
|
||
**POST** `/api/v1/parameters/`
|
||
|
||
创建新的工艺参数。
|
||
|
||
**认证方式**: JWT Token (Bearer Authentication)
|
||
**权限要求**: `IsAuthenticated` - 需要登录认证
|
||
|
||
---
|
||
|
||
## 请求说明
|
||
|
||
### 请求头
|
||
```
|
||
Authorization: Bearer {your_jwt_token}
|
||
Content-Type: application/json
|
||
```
|
||
|
||
### 请求体
|
||
|
||
**完整示例：**
|
||
```json
|
||
{
|
||
"key": "weight", // 必填，唯一标识符
|
||
"value": "500g", // 可选，参数值
|
||
"description": "重量参数", // 可选，参数描述
|
||
"is_required": false, // 可选，是否必填，默认 false
|
||
"is_image_path": false // 可选，是否图片路径，默认 false
|
||
}
|
||
```
|
||
|
||
**最小请求（只需 key）：**
|
||
```json
|
||
{
|
||
"key": "simple_param"
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| `key` | string | **是** | - | 参数键，唯一标识符，最大100字符 |
|
||
| `value` | string | 否 | null | 参数值，最大200字符 |
|
||
| `description` | string | 否 | "" | 参数描述，最大200字符 |
|
||
| `is_required` | boolean | 否 | false | 标记该参数是否为必填参数 |
|
||
| `is_image_path` | boolean | 否 | false | 标记 value 字段是否为图片URL路径 |
|
||
|
||
---
|
||
|
||
## 响应说明
|
||
|
||
### 成功响应
|
||
|
||
**状态码**: `201 Created`
|
||
|
||
**响应体：**
|
||
```json
|
||
{
|
||
"id": 5,
|
||
"key": "weight",
|
||
"value": "500g",
|
||
"attachment": null,
|
||
"attachment_url": null,
|
||
"description": "重量参数",
|
||
"is_required": false,
|
||
"is_image_path": false
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
#### 1. key 重复
|
||
|
||
**状态码**: `400 Bad Request`
|
||
|
||
**响应体：**
|
||
```json
|
||
{
|
||
"key": ["具有 参数键 的 state parameter 已存在。"]
|
||
}
|
||
```
|
||
|
||
#### 2. 未认证
|
||
|
||
**状态码**: `401 Unauthorized`
|
||
|
||
**响应体：**
|
||
```json
|
||
{
|
||
"detail": "身份认证信息未提供。"
|
||
}
|
||
```
|
||
|
||
#### 3. 字段验证失败
|
||
|
||
**状态码**: `400 Bad Request`
|
||
|
||
**响应体示例：**
|
||
```json
|
||
{
|
||
"key": ["该字段是必填项。"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### JavaScript (Fetch API)
|
||
|
||
```javascript
|
||
async function createParameter(paramData) {
|
||
const response = await fetch('/api/v1/parameters/', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify({
|
||
key: paramData.key,
|
||
value: paramData.value,
|
||
description: paramData.description,
|
||
is_required: paramData.isRequired || false,
|
||
is_image_path: paramData.isImagePath || false
|
||
})
|
||
});
|
||
|
||
if (!response.ok) {
|
||
const error = await response.json();
|
||
if (error.key) {
|
||
throw new Error('参数键已存在，请使用其他名称');
|
||
}
|
||
throw new Error('创建失败');
|
||
}
|
||
|
||
return await response.json();
|
||
}
|
||
|
||
// 使用示例
|
||
try {
|
||
const newParam = await createParameter({
|
||
key: 'fabric_color',
|
||
value: '红色',
|
||
description: '面料颜色',
|
||
isRequired: true,
|
||
isImagePath: false
|
||
});
|
||
console.log('创建成功:', newParam);
|
||
} catch (error) {
|
||
console.error('创建失败:', error.message);
|
||
}
|
||
```
|
||
|
||
### JavaScript (Axios)
|
||
|
||
```javascript
|
||
import axios from 'axios';
|
||
|
||
async function createParameter(paramData) {
|
||
try {
|
||
const response = await axios.post('/api/v1/parameters/', {
|
||
key: paramData.key,
|
||
value: paramData.value,
|
||
description: paramData.description,
|
||
is_required: paramData.isRequired || false,
|
||
is_image_path: paramData.isImagePath || false
|
||
}, {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`
|
||
}
|
||
});
|
||
|
||
return response.data;
|
||
} catch (error) {
|
||
if (error.response?.data?.key) {
|
||
throw new Error('参数键已存在');
|
||
}
|
||
throw error;
|
||
}
|
||
}
|
||
```
|
||
|
||
### Python (requests)
|
||
|
||
```python
|
||
import requests
|
||
|
||
def create_parameter(token, key, value=None, description='', is_required=False, is_image_path=False):
|
||
url = 'https://your-domain.com/api/v1/parameters/'
|
||
headers = {
|
||
'Authorization': f'Bearer {token}',
|
||
'Content-Type': 'application/json'
|
||
}
|
||
data = {
|
||
'key': key,
|
||
'value': value,
|
||
'description': description,
|
||
'is_required': is_required,
|
||
'is_image_path': is_image_path
|
||
}
|
||
|
||
response = requests.post(url, json=data, headers=headers)
|
||
|
||
if response.status_code == 201:
|
||
return response.json()
|
||
elif response.status_code == 400:
|
||
error = response.json()
|
||
if 'key' in error:
|
||
raise ValueError('参数键已存在')
|
||
raise ValueError(f'创建失败: {error}')
|
||
else:
|
||
response.raise_for_status()
|
||
|
||
# 使用示例
|
||
try:
|
||
new_param = create_parameter(
|
||
token='your_jwt_token',
|
||
key='fabric_weight',
|
||
value='300g/m²',
|
||
description='面料克重',
|
||
is_required=True
|
||
)
|
||
print(f'创建成功: {new_param}')
|
||
except ValueError as e:
|
||
print(f'错误: {e}')
|
||
```
|
||
|
||
### cURL
|
||
|
||
```bash
|
||
# 基本创建
|
||
curl -X POST https://your-domain.com/api/v1/parameters/ \
|
||
-H "Authorization: Bearer your_jwt_token" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"key": "print_method",
|
||
"value": "丝网印刷",
|
||
"description": "印刷方式",
|
||
"is_required": true,
|
||
"is_image_path": false
|
||
}'
|
||
|
||
# 最小请求（只创建 key）
|
||
curl -X POST https://your-domain.com/api/v1/parameters/ \
|
||
-H "Authorization: Bearer your_jwt_token" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"key": "simple_param"}'
|
||
```
|
||
|
||
---
|
||
|
||
## 常见使用场景
|
||
|
||
### 场景1：创建普通文本参数
|
||
|
||
```javascript
|
||
const textParam = await createParameter({
|
||
key: 'fabric_type',
|
||
value: '纯棉',
|
||
description: '面料类型',
|
||
isRequired: true,
|
||
isImagePath: false
|
||
});
|
||
```
|
||
|
||
### 场景2：创建图片路径参数
|
||
|
||
```javascript
|
||
const imageParam = await createParameter({
|
||
key: 'design_preview',
|
||
value: '/uploads/designs/preview_001.jpg',
|
||
description: '设计预览图',
|
||
isRequired: false,
|
||
isImagePath: true // 标记为图片路径
|
||
});
|
||
```
|
||
|
||
### 场景3：创建必填参数（用于流程验证）
|
||
|
||
```javascript
|
||
const requiredParam = await createParameter({
|
||
key: 'customer_approval',
|
||
value: '待确认',
|
||
description: '客户审批状态',
|
||
isRequired: true, // 标记为必填
|
||
isImagePath: false
|
||
});
|
||
```
|
||
|
||
### 场景4：批量创建参数
|
||
|
||
```javascript
|
||
const paramsToCreate = [
|
||
{ key: 'color', description: '颜色' },
|
||
{ key: 'size', description: '尺寸' },
|
||
{ key: 'quantity', description: '数量' }
|
||
];
|
||
|
||
const results = await Promise.all(
|
||
paramsToCreate.map(param => createParameter(param))
|
||
);
|
||
|
||
console.log('批量创建完成:', results);
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. ⚠️ **key 必须唯一**：如果 key 已存在，会返回 400 错误，创建前可以先查询是否存在
|
||
2. 📝 **value 可为空**：value 字段是可选的，可以先创建参数，后续再更新值
|
||
3. 🔐 **必须认证**：请求头必须包含有效的 JWT Token
|
||
4. 🏷️ **is_image_path 标记**：如果 value 存储的是图片路径，建议设置 `is_image_path: true` 以便前端正确处理
|
||
5. ✅ **is_required 标记**：用于标识该参数在业务流程中是否为必填项，方便表单验证
|
||
|
||
---
|
||
|
||
## 与其他接口的配合使用
|
||
|
||
### 创建后查询详情
|
||
```javascript
|
||
// 1. 创建参数
|
||
const newParam = await createParameter({
|
||
key: 'logo_position',
|
||
description: 'Logo位置'
|
||
});
|
||
|
||
// 2. 查询详情
|
||
const detail = await fetch(`/api/v1/parameters/${newParam.id}/`, {
|
||
headers: { 'Authorization': `Bearer ${token}` }
|
||
}).then(r => r.json());
|
||
```
|
||
|
||
### 创建后立即更新
|
||
```javascript
|
||
// 1. 先创建
|
||
const param = await createParameter({
|
||
key: 'temp_param'
|
||
});
|
||
|
||
// 2. 立即更新值
|
||
const updated = await fetch(`/api/v1/parameters/${param.id}/`, {
|
||
method: 'PATCH',
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify({
|
||
value: '最终值',
|
||
description: '更新后的描述'
|
||
})
|
||
}).then(r => r.json());
|
||
```
|
||
|
||
---
|
||
|
||
## 测试状态
|
||
|
||
✅ 所有相关测试用例已通过：
|
||
- 创建普通参数
|
||
- 创建最小参数（仅 key）
|
||
- 重复 key 验证
|
||
- 字段验证
|
||
- 认证验证
|
||
|
||
接口已可用于生产环境。
|