VWED_server/扩展属性管理接口文档.md

# 扩展属性管理接口文档

## 概述

扩展属性管理接口用于管理动作点（库位）的扩展属性定义。通过这些接口，您可以创建、查询和删除扩展属性配置，为库位提供灵活的自定义字段支持。

## 接口列表

### 1. 创建扩展属性

**接口地址：** `POST /api/vwed-operate-point/extended-properties`

**功能说明：** 创建新的扩展属性定义

**重要提示：** 创建扩展属性后，会自动将该属性添加到所有现有的库位层中，每个库位层的config_json会自动更新，包含新的扩展属性配置。

**请求参数：**
```json
{
  "property_name": "温度",
  "property_type": "float",
  "is_required": false,
  "is_enabled": true,
  "description": "库位温度监控",
  "placeholder": "请输入温度值",
  "default_value": "25.0",
  "options": null,
  "validation_rules": {
    "min": -50,
    "max": 100
  },
  "category": "环境监控",
  "sort_order": 10,
  "display_width": 150,
  "display_format": "{{value}}°C"
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "扩展属性创建成功",
  "data": {
    "id": "1",
    "property_name": "温度",
    "message": "扩展属性创建成功，已应用到所有库位层"
  }
}
```

### 2. 获取扩展属性列表

**接口地址：** `GET /api/vwed-operate-point/extended-properties`

**功能说明：** 获取扩展属性列表，支持多种筛选条件

**请求参数：**
- `property_name` (可选): 属性名称，支持模糊搜索
- `property_type` (可选): 属性类型
- `category` (可选): 属性分类
- `is_enabled` (可选): 是否启用
- `page` (可选): 页码，默认1
- `page_size` (可选): 每页数量，默认20

**响应示例：**
```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 5,
    "page": 1,
    "page_size": 20,
    "total_pages": 1,
    "properties": [
      {
        "id": "1",
        "property_name": "温度",
        "property_type": "float",
        "is_required": false,
        "is_enabled": true,
        "description": "库位温度监控",
        "placeholder": "请输入温度值",
        "default_value": "25.0",
        "options": null,
        "validation_rules": {
          "min": -50,
          "max": 100
        },
        "category": "环境监控",
        "sort_order": 10,
        "display_width": 150,
        "display_format": "{{value}}°C",
        "created_at": "2024-12-20T10:00:00",
        "updated_at": "2024-12-20T10:00:00"
      }
    ]
  }
}
```

### 3. 删除扩展属性

**接口地址：** `DELETE /api/vwed-operate-point/extended-properties/{property_id}`

**功能说明：** 删除指定的扩展属性（软删除）

**重要提示：** 删除扩展属性后，会自动从所有现有的库位层中移除该属性，每个库位层的config_json会自动更新，清除已删除的扩展属性配置。此操作不可逆，请谨慎使用。

**请求参数：**
- `property_id` (路径参数): 属性ID

**响应示例：**
```json
{
  "code": 200,
  "message": "扩展属性删除成功",
  "data": {
    "property_id": "1",
    "property_name": "温度",
    "message": "扩展属性删除成功，已从所有库位层移除"
  }
}
```

### 4. 获取扩展属性类型列表

**接口地址：** `GET /api/vwed-operate-point/extended-properties/types`

**功能说明：** 获取系统支持的扩展属性类型列表

**响应示例：**
```json
{
  "code": 200,
  "message": "获取扩展属性类型成功",
  "data": {
    "types": [
      {
        "value": "string",
        "description": "字符串 - 适用于短文本输入"
      },
      {
        "value": "integer",
        "description": "整数 - 适用于整数值"
      },
      {
        "value": "float",
        "description": "浮点数 - 适用于小数值"
      },
      {
        "value": "boolean",
        "description": "布尔值 - 适用于是/否选择"
      },
      {
        "value": "date",
        "description": "日期 - 适用于日期选择"
      },
      {
        "value": "datetime",
        "description": "日期时间 - 适用于日期和时间选择"
      },
      {
        "value": "text",
        "description": "长文本 - 适用于多行文本输入"
      },
      {
        "value": "select",
        "description": "下拉选择 - 适用于单选择"
      },
      {
        "value": "multiselect",
        "description": "多选 - 适用于多选择"
      }
    ],
    "count": 9
  }
}
```

## 属性类型详细说明

### 1. string（字符串）
- 适用于短文本输入
- 支持长度限制验证
- 支持正则表达式验证

### 2. integer（整数）
- 适用于整数值
- 支持最小值/最大值验证
- 支持数值范围验证

### 3. float（浮点数）
- 适用于小数值
- 支持最小值/最大值验证
- 支持精度设置

### 4. boolean（布尔值）
- 适用于是/否选择
- 显示为复选框或开关

### 5. date（日期）
- 适用于日期选择
- 格式：YYYY-MM-DD
- 支持日期范围验证

### 6. datetime（日期时间）
- 适用于日期和时间选择
- 格式：YYYY-MM-DD HH:MM:SS
- 支持日期时间范围验证

### 7. text（长文本）
- 适用于多行文本输入
- 支持最大长度限制
- 显示为文本区域

### 8. select（下拉选择）
- 适用于单选择
- 需要配置选项列表
- 选项格式：`[{"label": "选项1", "value": "value1"}, ...]`

### 9. multiselect（多选）
- 适用于多选择
- 需要配置选项列表
- 选项格式：`[{"label": "选项1", "value": "value1"}, ...]`

## 验证规则配置

验证规则使用JSON格式配置，支持以下规则：

```json
{
  "min": 0,                    // 最小值（数字类型）
  "max": 100,                  // 最大值（数字类型）
  "minLength": 1,              // 最小长度（字符串类型）
  "maxLength": 255,            // 最大长度（字符串类型）
  "pattern": "^[a-zA-Z0-9]+$", // 正则表达式（字符串类型）
  "required": true,            // 是否必填
  "decimal": 2                 // 小数位数（浮点数类型）
}
```

## 选项配置示例

对于select和multiselect类型，选项配置示例：

```json
[
  {
    "label": "选项1",
    "value": "option1",
    "description": "选项1的描述"
  },
  {
    "label": "选项2",
    "value": "option2",
    "description": "选项2的描述"
  }
]
```

## 使用示例

### 创建温度监控属性

```bash
curl -X POST "http://localhost:8000/api/vwed-operate-point/extended-properties" \
  -H "Content-Type: application/json" \
  -d '{
    "property_name": "温度",
    "property_type": "float",
    "description": "库位温度监控",
    "validation_rules": {
      "min": -50,
      "max": 100,
      "decimal": 1
    },
    "category": "环境监控",
    "display_format": "{{value}}°C"
  }'
```

### 创建库位状态选择属性

```bash
curl -X POST "http://localhost:8000/api/vwed-operate-point/extended-properties" \
  -H "Content-Type: application/json" \
  -d '{
    "property_name": "维护状态",
    "property_type": "select",
    "is_required": true,
    "options": [
      {"label": "正常", "value": "normal"},
      {"label": "维护中", "value": "maintenance"},
      {"label": "故障", "value": "fault"}
    ],
    "category": "设备管理"
  }'
```

## 扩展属性在库位层中的存储

### config_json结构

每个库位层的扩展属性值存储在 `config_json` 字段中，结构如下：

```json
{
  "extended_fields": {
    "温度": {
      "value": "25.0",
      "type": "float",
      "is_required": false,
      "updated_at": "2024-12-20T10:00:00"
    },
    "维护状态": {
      "value": "normal",
      "type": "select",
      "is_required": true,
      "updated_at": "2024-12-20T10:00:00"
    }
  }
}
```

### 自动同步机制

1. **创建扩展属性时：** 自动为所有现有库位层添加该属性，使用默认值进行初始化
2. **删除扩展属性时：** 自动从所有库位层中移除该属性的配置和数据
3. **新建库位层时：** 自动同步所有已启用的扩展属性到新库位层
4. **地图推送时：** 推送地图数据创建新库位层时，自动为每个新层同步扩展属性

### 数据完整性保证

- 扩展属性定义与库位层数据保持同步
- 删除扩展属性会清理所有相关数据
- 支持批量操作，确保数据一致性

## 与地图推送的集成

### 地图推送时的自动同步

当通过地图推送接口 `POST /api/vwed-map-data/push` 创建新的地图数据时：

1. **自动检测扩展属性：** 系统会查询所有已启用的扩展属性
2. **同步到新库位层：** 为每个新创建的库位层自动添加扩展属性配置
3. **使用默认值：** 新库位层的扩展属性会使用定义时的默认值进行初始化
4. **错误处理：** 即使扩展属性同步失败，地图推送也能正常完成

### 推荐工作流程

1. **先配置扩展属性：** 在推送地图前，先创建所需的扩展属性定义
2. **推送地图数据：** 地图推送时会自动为新库位层同步扩展属性
3. **验证结果：** 通过库位列表接口查看扩展属性是否正确同步

### 示例场景

```bash
# 1. 创建温度监控属性
curl -X POST "http://localhost:8000/api/vwed-operate-point/extended-properties" \
  -H "Content-Type: application/json" \
  -d '{
    "property_name": "温度",
    "property_type": "float",
    "default_value": "25.0"
  }'

# 2. 推送地图数据
curl -X POST "http://localhost:8000/api/vwed-map-data/push" \
  -H "Content-Type: application/json" \
  -d '{
    "scene_id": "scene_001",
    "storage_areas": [...],
    "operate_points": [...]
  }'

# 3. 查看库位列表（新库位层会自动包含温度属性）
curl "http://localhost:8000/api/vwed-operate-point/list?include_extended_fields=true"
```

## 注意事项

1. **属性名称唯一性：** `property_name` 必须在系统中唯一
2. **软删除：** 删除操作是软删除，不会真正删除数据
3. **数据类型验证：** 创建时会验证数据类型和格式
4. **选项配置：** select和multiselect类型需要配置选项列表
5. **验证规则：** 验证规则必须符合JSON格式且类型匹配
6. **自动同步：** 扩展属性的创建和删除会自动影响所有库位层的配置
7. **地图推送集成：** 新推送的地图数据会自动包含已定义的扩展属性
8. **操作顺序：** 建议先创建扩展属性，再进行地图推送，以确保新库位层包含完整的属性配置
9. **性能考虑：** 扩展属性数量较多时，地图推送可能需要更多时间来同步属性

## 错误码说明

- `200`: 操作成功
- `400`: 请求参数错误
- `404`: 资源不存在
- `500`: 服务器内部错误

## 数据库迁移

在使用这些接口前，请确保已执行数据库迁移：

```bash
# 执行迁移
python scripts/run_migration.py
```

迁移将创建 `extended_properties` 表及相关索引。