# 创建工艺参数 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 验证 - 字段验证 - 认证验证 接口已可用于生产环境。