jzw/VWED_server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
VWED_server/扩展属性管理接口文档.md
靳中伟 2899453300 add api
2025-07-14 10:29:37 +08:00

11 KiB
Raw Blame History

扩展属性管理接口文档

概述

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

接口列表

1. 创建扩展属性

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

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

重要提示： 创建扩展属性后，会自动将该属性添加到所有现有的库位层中，每个库位层的config_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"
}

响应示例：

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

响应示例：

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

响应示例：

{
  "code": 200,
  "message": "扩展属性删除成功",
  "data": {
    "property_id": "1",
    "property_name": "温度",
    "message": "扩展属性删除成功，已从所有库位层移除"
  }
}

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

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

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

响应示例：

{
  "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格式配置，支持以下规则：

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

选项配置示例

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

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

使用示例

创建温度监控属性

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"
  }'

创建库位状态选择属性

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 字段中，结构如下：

{
  "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. 验证结果： 通过库位列表接口查看扩展属性是否正确同步

示例场景

# 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: 服务器内部错误

数据库迁移

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

# 执行迁移
python scripts/run_migration.py

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