forked from erp-dev/erp
feat: product quick api and param create api
This commit is contained in:
370
api_v1/views/param_create.md
Normal file
370
api_v1/views/param_create.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# 创建工艺参数 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 验证
|
||||
- 字段验证
|
||||
- 认证验证
|
||||
|
||||
接口已可用于生产环境。
|
||||
Reference in New Issue
Block a user