# 扩展属性管理接口文档 ## 概述 扩展属性管理接口用于管理动作点（库位）的扩展属性定义。通过这些接口，您可以创建、查询和删除扩展属性配置，为库位提供灵活的自定义字段支持。 ## 接口列表 ### 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` 表及相关索引。