# 创建工艺参数 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 验证
- 字段验证
- 认证验证

接口已可用于生产环境。
