erpnew/api_v1/views/param_create.md

创建工艺参数 API 文档

接口信息

POST /api/v1/parameters/

创建新的工艺参数。

认证方式: JWT Token (Bearer Authentication)
权限要求: IsAuthenticated - 需要登录认证

---

请求说明

请求头

Authorization: Bearer {your_jwt_token}
Content-Type: application/json

请求体

完整示例：

{
  "key": "weight",           // 必填，唯一标识符
  "value": "500g",           // 可选，参数值
  "description": "重量参数",  // 可选，参数描述
  "is_required": false,      // 可选，是否必填，默认 false
  "is_image_path": false     // 可选，是否图片路径，默认 false
}

最小请求（只需 key）：

{
  "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

响应体：

{
  "id": 5,
  "key": "weight",
  "value": "500g",
  "attachment": null,
  "attachment_url": null,
  "description": "重量参数",
  "is_required": false,
  "is_image_path": false
}

错误响应

1. key 重复

状态码: 400 Bad Request

响应体：

{
  "key": ["具有 参数键 的 state parameter 已存在。"]
}

2. 未认证

状态码: 401 Unauthorized

响应体：

{
  "detail": "身份认证信息未提供。"
}

3. 字段验证失败

状态码: 400 Bad Request

响应体示例：

{
  "key": ["该字段是必填项。"]
}

---

使用示例

JavaScript (Fetch API)

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)

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)

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

# 基本创建
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：创建普通文本参数

const textParam = await createParameter({
  key: 'fabric_type',
  value: '纯棉',
  description: '面料类型',
  isRequired: true,
  isImagePath: false
});

场景2：创建图片路径参数

const imageParam = await createParameter({
  key: 'design_preview',
  value: '/uploads/designs/preview_001.jpg',
  description: '设计预览图',
  isRequired: false,
  isImagePath: true  // 标记为图片路径
});

场景3：创建必填参数（用于流程验证）

const requiredParam = await createParameter({
  key: 'customer_approval',
  value: '待确认',
  description: '客户审批状态',
  isRequired: true,  // 标记为必填
  isImagePath: false
});

场景4：批量创建参数

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 标记：用于标识该参数在业务流程中是否为必填项，方便表单验证

---

与其他接口的配合使用

创建后查询详情

// 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());

创建后立即更新

// 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 验证
• 字段验证
• 认证验证

接口已可用于生产环境。