jzw/VWED_server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
VWED_server/VWED任务模块接口文档/库位管理接口文档.md
靳中伟 de82ddf7cd 修改部分接口
2025-07-17 15:47:56 +08:00

33 KiB
Raw Permalink Blame History

库位管理接口文档

概述

库位管理接口提供了对库位（基于动作点分层）的全面管理功能，包括库位查询、状态更新、扩展属性管理、操作记录查询等。每个动作点可以包含多个层，每一层对应一个库位。

重要说明：

  • 所有接口现在使用 layer_name（库位名称）作为库位的主要标识符
  • 路径参数和查询参数均使用 layer_name 而不是 storage_location_id
  • 这样设计使得接口更加直观和易于使用

接口更新历史

2024年最新更新：

  • 将 GET /api/vwed-operate-point/{layer_name}/status 接口的路径参数改为 layer_name
  • 将 GET /api/vwed-operate-point/{layer_name} 接口的路径参数改为 layer_name
  • 将 PUT /api/vwed-operate-point/{layer_name} 接口的路径参数改为 layer_name
  • 将 GET /api/vwed-operate-point/operation-logs 接口的查询参数改为 layer_name
  • 统一使用库位名称作为主要标识符，提升接口的一致性和易用性

接口列表

1. 获取库位列表 (GET /api/vwed-operate-point/list)

获取库位列表，支持多种筛选条件和分页查询。

请求参数

参数名 类型 必填 描述
scene_id string 否 场景ID
storage_area_id string 否 库区ID
station_name string 否 站点名称（支持模糊搜索）
layer_name string 否 层名称（支持模糊搜索）
is_disabled boolean 否 是否禁用
is_occupied boolean 否 是否占用
is_locked boolean 否 是否锁定
is_empty_tray boolean 否 是否空托盘
include_operate_point_info boolean 否 是否包含动作点信息（默认true）
include_extended_fields boolean 否 是否包含扩展字段（默认true）
page integer 否 页码（默认1）
page_size integer 否 每页数量（默认20，最大100）

响应格式

{
  "code": 200,
    "message": "查询成功",
  "data": {
        "total": 7,
        "page": 1,
        "page_size": 20,
        "total_pages": 1,
        "storage_locations": [
            {
                "id": "45ecea40-032d-47e1-8637-50882fd722f1",
                "layer_index": 3,
                "layer_name": "4-3",
                "is_occupied": false,
                "is_locked": false,
                "is_disabled": false,
                "is_empty_tray": false,
                "locked_by": null,
                "goods_content": "",
                "goods_weight": null,
                "goods_volume": null,
                "goods_stored_at": null,
                "goods_retrieved_at": null,
                "last_access_at": null,
                "max_weight": null,
                "max_volume": null,
                "layer_height": null,
                "tags": null,
                "description": null,
                "created_at": "2025-07-15T13:27:05.994536",
                "updated_at": "2025-07-15T13:28:17.825850",
                "extended_fields": {
                    "真实名字": null,
                    "test": null
                },
                "operate_point_id": "637defff-4670-4574-a73e-033bc94941a5",
                "station_name": "STATION-B-004",
                "scene_id": "1936411520272753371",
                "storage_area_id": "df28bb5a-f88f-4825-93e6-a1dae7c34bb1",
                "storage_area_type": "general",
                "area_name": "一般存储区C",
                "max_layers": 3,
                "current_layers": 0,
                "position_x": null,
                "position_y": null,
                "position_z": null,
                "operate_point_description": null
            },
            
        ]
  }
}

返回字段说明

分页信息
字段名 类型 说明
total integer 总记录数
page integer 当前页码
page_size integer 每页记录数
total_pages integer 总页数
库位层信息 (storage_locations)
字段名 类型 说明
id string 库位ID（唯一标识）
layer_index integer 层索引（从1开始）
layer_name string 库位名称
is_occupied boolean 是否占用
is_locked boolean 是否锁定
is_disabled boolean 是否禁用
is_empty_tray boolean 是否空托盘
locked_by string 锁定者
goods_content string 货物内容
goods_weight integer 货物重量（克）
goods_volume integer 货物体积（立方厘米）
goods_stored_at string 货物存放时间
goods_retrieved_at string 货物取出时间
last_access_at string 最后访问时间
max_weight integer 最大承重（克）
max_volume integer 最大体积（立方厘米）
layer_height integer 层高（毫米）
tags string 层标签
description string 层描述
created_at string 创建时间
updated_at string 更新时间
extended_fields object 扩展字段（键值对形式）
动作点信息 (operate_point_info)
字段名 类型 说明
operate_point_id string 动作点ID
station_name string 站点名称
scene_id string 场景ID
storage_area_id string 库区ID
storage_area_type string 库区类型
area_name string 库区名称
max_layers integer 最大层数
current_layers integer 当前层数
position_x float X坐标
position_y float Y坐标
position_z float Z坐标
operate_point_description string 动作点描述

调用示例

GET /api/vwed-operate-point/list?scene_id=scene-001&is_occupied=false&page=1&page_size=20

2. 更新库位状态 (PUT /api/vwed-operate-point/status)

更新单个库位的状态。

请求参数

{
  "layer_name": "layer-001",
  "action": "occupy",
  "locked_by": "user123",
  "reason": "放置货物A"
}
参数名 类型 必填 描述
layer_name string 是 库位名称
action string 是 操作类型（见支持的操作类型）
locked_by string 否 锁定者（锁定操作时必填）
reason string 否 操作原因

支持的操作类型

操作类型 描述
occupy 占用库位
release 释放库位
lock 锁定库位
unlock 解锁库位
enable 启用库位
disable 禁用库位
set_empty_tray 设置为空托盘
clear_empty_tray 清除空托盘状态

响应格式

{
  "code": 200,
  "message": "状态更新完成",
  "data": {
    "layer_name": "layer-001",
    "action": "occupy",
    "success": true,
    "message": "库位占用成功",
    "new_status": {
      "is_occupied": true,
      "is_locked": false,
      "is_disabled": false,
      "is_empty_tray": false,
      "locked_by": null,
      "updated_at": "2024-01-01T12:00:00"
    }
  }
}

返回字段说明

字段名 类型 说明
layer_name string 库位名称
action string 执行的操作类型
success boolean 操作是否成功
message string 操作结果消息
new_status object 更新后的状态信息
状态信息 (new_status)
字段名 类型 说明
is_occupied boolean 是否占用
is_locked boolean 是否锁定
is_disabled boolean 是否禁用
is_empty_tray boolean 是否空托盘
locked_by string 锁定者
updated_at string 更新时间

3. 批量更新库位状态 (PUT /api/vwed-operate-point/batch-status)

批量更新多个库位的状态。

请求参数

{
  "layer_names": ["layer-001", "layer-002", "layer-003"],
  "action": "lock",
  "locked_by": "user123",
  "reason": "批量锁定操作"
}
参数名 类型 必填 描述
layer_names string[] 是 库位名称列表（最多100个）
action string 是 操作类型（见支持的操作类型）
locked_by string 否 锁定者（锁定操作时必填）
reason string 否 操作原因

响应格式

{
  "code": 200,
  "message": "批量状态更新完成：成功操作 2 个库位，失败操作 1 个库位",
  "data": {
    "total_count": 3,
    "success_count": 2,
    "failed_count": 1,
    "results": [
      {
        "layer_name": "layer-001",
        "action": "lock",
  "success": true,
        "message": "库位锁定成功",
        "new_status": {
          "is_locked": true,
          "locked_by": "user123"
        }
      },
      {
        "layer_name": "layer-002",
        "action": "lock",
  "success": false,
        "message": "库位已被其他用户锁定",
        "new_status": {}
      }
    ]
  }
}

返回字段说明

字段名 类型 说明
total_count integer 总操作数量
success_count integer 成功操作数量
failed_count integer 失败操作数量
results array 每个库位的操作结果详情
操作结果详情 (results[])
字段名 类型 说明
layer_name string 库位名称
action string 执行的操作类型
success boolean 操作是否成功
message string 操作结果消息
new_status object 更新后的状态信息（成功时返回）

4. 获取支持的操作类型 (GET /api/vwed-operate-point/actions)

获取系统支持的所有库位操作类型。

响应格式

{
  "code": 200,
  "message": "获取支持的操作类型成功",
  "data": {
    "actions": [
      {
        "value": "occupy",
        "description": "占用库位"
      },
      {
        "value": "release",
        "description": "释放库位"
      },
      {
        "value": "lock",
        "description": "锁定库位（需要提供锁定者）"
      }
    ],
    "count": 8
  }
}

返回字段说明

字段名 类型 说明
actions array 支持的操作类型列表
count integer 操作类型数量
操作类型信息 (actions[])
字段名 类型 说明
value string 操作类型值
description string 操作类型描述

5. 获取库位详情 (GET /api/vwed-operate-point/{layer_name})

获取指定库位的详细信息。

请求参数

参数名 类型 必填 描述
layer_name string 是 库位名称（路径参数）

响应格式

{
  "code": 200,
  "message": "获取库位详情成功",
  "data": {
    "storage_location": {
      "id": "layer-001",
      "layer_index": 1,
      "layer_name": "第一层",
      "is_occupied": false,
      "is_locked": false,
      "is_disabled": false,
      "is_empty_tray": false,
      "locked_by": null,
      "goods_content": "",
      "goods_weight": null,
      "goods_volume": null,
      "max_weight": 5000,
      "max_volume": 1000,
      "layer_height": 300,
      "tags": "高架库,密集存储",
      "description": "密集存储区第一层",
      "created_at": "2024-01-01T00:00:00",
      "updated_at": "2024-01-01T00:00:00",
      "extended_fields": {
        "产品类别": "电子产品",
        "存储温度": "常温"
      }
    },
    "operate_point_info": {
      "id": "point-001",
      "station_name": "存储站点A",
      "scene_id": "scene-001",
      "area_name": "密集存储区"
    },
    "extended_fields_definitions": [
      {
        "id": "ext-001",
        "property_name": "产品类别",
        "property_type": "select",
        "is_required": true,
        "is_enabled": true,
        "description": "产品分类"
      }
    ],
    "status_history": []
  }
}

返回字段说明

库位信息 (storage_location)
字段名 类型 说明
id string 层ID（唯一标识）
layer_index integer 层索引（从1开始）
layer_name string 层名称
is_occupied boolean 是否占用
is_locked boolean 是否锁定
is_disabled boolean 是否禁用
is_empty_tray boolean 是否空托盘
locked_by string 锁定者
goods_content string 货物内容
goods_weight integer 货物重量（克）
goods_volume integer 货物体积（立方厘米）
max_weight integer 最大承重（克）
max_volume integer 最大体积（立方厘米）
layer_height integer 层高（毫米）
tags string 层标签
description string 层描述
created_at string 创建时间
updated_at string 更新时间
extended_fields object 扩展字段值（键值对形式）
动作点信息 (operate_point_info)
字段名 类型 说明
id string 动作点ID
station_name string 站点名称
scene_id string 场景ID
area_name string 库区名称
扩展字段定义 (extended_fields_definitions[])
字段名 类型 说明
id string 扩展属性ID
property_name string 属性名称
property_type string 属性类型
is_required boolean 是否必填
is_enabled boolean 是否启用
description string 属性描述
状态历史 (status_history[])
字段名 类型 说明
operation_time string 操作时间
operation_type string 操作类型
operator string 操作人员
description string 操作描述

6. 编辑库位信息 (PUT /api/vwed-operate-point/{layer_name})

编辑库位的各种属性信息。

请求参数

参数名 类型 必填 描述
layer_name string 是 库位名称（路径参数）

请求体

{
  "goods_content": "电子产品A",
  "goods_weight": 500,
  "goods_volume": 200,
  "max_weight": 6000,
  "is_locked": false,
  "is_disabled": false,
  "is_empty_tray": true,
  "tags": "高架库,密集存储,已更新",
  "description": "密集存储区第一层 - 已更新",
  "extended_fields": {
    "产品类别": "机械配件",
    "存储温度": "常温",
    "保质期": "12个月"
  }
}

响应格式

{
  "code": 200,
  "message": "库位信息编辑成功",
  "data": {
    "layer_name": "layer-001",
    "success": true,
    "message": "库位信息更新成功，共更新 8 个字段",
    "updated_fields": [
      "goods_content",
      "goods_weight",
      "goods_volume",
      "max_weight",
      "is_locked",
      "is_disabled",
      "is_empty_tray",
      "tags",
      "description",
      "extended_fields.产品类别"
    ],
    "updated_storage_location": {
      "id": "layer-001",
      "layer_name": "第一层",
      "goods_content": "电子产品A",
      "goods_weight": 500,
      "updated_at": "2024-01-02T10:30:00"
    }
  }
}

返回字段说明

字段名 类型 说明
layer_name string 库位名称
success boolean 操作是否成功
message string 操作结果消息
updated_fields array 更新的字段列表
updated_storage_location object 更新后的库位信息摘要
更新后的库位信息 (updated_storage_location)
字段名 类型 说明
id string 层ID
layer_name string 层名称
goods_content string 货物内容
goods_weight integer 货物重量（克）
updated_at string 更新时间

7. 获取库位状态 (GET /api/vwed-operate-point/{layer_name}/status)

获取单个库位的状态信息。

请求参数

参数名 类型 必填 描述
layer_name string 是 库位名称（路径参数）

响应格式

{
  "code": 200,
  "message": "查询成功",
  "data": {
      "is_occupied": false,
      "is_locked": false,
      "is_disabled": false,
      "is_empty_tray": false,
      "locked_by": null,
    "goods_content": "",
    "last_access_at": "2024-01-01T12:00:00",
    "updated_at": "2024-01-01T12:00:00"
  }
}

返回字段说明

字段名 类型 说明
is_occupied boolean 是否占用
is_locked boolean 是否锁定
is_disabled boolean 是否禁用
is_empty_tray boolean 是否空托盘
locked_by string 锁定者
goods_content string 货物内容
last_access_at string 最后访问时间
updated_at string 更新时间

8. 创建扩展属性 (POST /api/vwed-operate-point/extended-properties)

创建新的扩展属性定义。

请求参数

{
  "property_key": "storage_temperature",
  "property_name": "存储温度",
  "property_type": "string",
  "is_required": false,
  "is_enabled": true,
  "default_value": "常温",
  "description": "库位存储温度要求",
  "category": "环境参数",
  "display_width": 120,
  "display_format": "",
  "validation_rules": "",
  "options": []
}

响应格式

{
  "code": 200,
  "message": "扩展属性创建成功",
  "data": {
    "property_id": "ext-001",
    "property_key": "storage_temperature",
    "property_name": "存储温度",
    "success": true,
    "message": "扩展属性创建成功，已同步到 150 个库位层",
    "affected_layers_count": 150
  }
}

返回字段说明

字段名 类型 说明
property_id string 扩展属性ID
property_key string 属性键名
property_name string 属性名称
success boolean 操作是否成功
message string 操作结果消息
affected_layers_count integer 影响的库位层数量

9. 获取扩展属性列表 (GET /api/vwed-operate-point/extended-properties)

获取扩展属性定义列表。

请求参数

参数名 类型 必填 描述
property_name string 否 属性名称（支持模糊搜索）
property_type string 否 属性类型
category string 否 属性分类
is_enabled boolean 否 是否启用
page integer 否 页码（默认1）
page_size integer 否 每页数量（默认20，最大100）

响应格式

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 10,
    "page": 1,
    "page_size": 20,
    "total_pages": 1,
    "properties": [
      {
        "id": "ext-001",
        "property_key": "storage_temperature",
        "property_name": "存储温度",
        "property_type": "string",
        "is_required": false,
        "is_enabled": true,
        "default_value": "常温",
        "description": "库位存储温度要求",
        "category": "环境参数",
        "created_at": "2024-01-01T00:00:00",
        "updated_at": "2024-01-01T00:00:00"
      }
    ]
  }
}

返回字段说明

分页信息
字段名 类型 说明
total integer 总记录数
page integer 当前页码
page_size integer 每页记录数
total_pages integer 总页数
扩展属性信息 (properties[])
字段名 类型 说明
id string 扩展属性ID
property_key string 属性键名
property_name string 属性名称
property_type string 属性类型
is_required boolean 是否必填
is_enabled boolean 是否启用
default_value string 默认值
description string 属性描述
category string 属性分类
created_at string 创建时间
updated_at string 更新时间

10. 删除扩展属性 (DELETE /api/vwed-operate-point/extended-properties/{property_id})

删除指定的扩展属性。

请求参数

参数名 类型 必填 描述
property_id string 是 属性ID

响应格式

{
  "code": 200,
  "message": "扩展属性删除成功",
  "data": {
    "property_id": "ext-001",
    "success": true,
    "message": "扩展属性删除成功，已从 150 个库位层中清除",
    "affected_layers_count": 150
  }
}

返回字段说明

字段名 类型 说明
property_id string 扩展属性ID
success boolean 操作是否成功
message string 操作结果消息
affected_layers_count integer 影响的库位层数量

11. 创建扩展属性

接口地址： 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": "扩展属性创建成功，已应用到所有库位层"
  }
}

12. 获取库位操作记录 (GET /api/vwed-operate-point/operation-logs)

获取库位操作记录列表。

请求参数

参数名 类型 必填 描述
layer_name string 否 库位名称
operator string 否 操作人（支持模糊搜索）
operation_type string 否 操作类型
start_time string 否 开始时间（格式：YYYY-MM-DD HH:MM:SS）
end_time string 否 结束时间（格式：YYYY-MM-DD HH:MM:SS）
page integer 否 页码（默认1）
page_size integer 否 每页数量（默认20，最大100）

响应格式

{
  "code": 200,
  "message": "查询操作记录成功",
  "data": {
    "total": 25,
    "page": 1,
    "page_size": 10,
    "total_pages": 3,
    "logs": [
      {
        "id": "log-001",
        "operation_time": "2024-01-02T10:30:00",
        "operator": "admin",
        "operation_type": "编辑库位",
        "affected_storage_locations": ["layer-001"],
        "description": "编辑库位信息，更新字段: goods_content, goods_weight, is_locked",
        "created_at": "2024-01-02T10:30:00"
      },
      {
        "id": "log-002",
        "operation_time": "2024-01-02T09:15:00",
        "operator": "系统",
        "operation_type": "occupy",
        "affected_storage_locations": ["layer-001"],
        "description": "占用库位操作",
        "created_at": "2024-01-02T09:15:00"
      }
    ]
  }
}

返回字段说明

分页信息
字段名 类型 说明
total integer 总记录数
page integer 当前页码
page_size integer 每页记录数
total_pages integer 总页数
操作记录信息 (logs[])
字段名 类型 说明
id string 操作记录ID
operation_time string 操作时间
operator string 操作人员
operation_type string 操作类型
affected_storage_locations array 受影响的库位名称列表
description string 操作描述
created_at string 记录创建时间

调用示例

GET /api/vwed-operate-point/operation-logs?layer_name=layer-001&start_time=2024-01-01 00:00:00&end_time=2024-01-02 23:59:59&page=1&page_size=10

错误处理

常见错误码

错误码 描述 示例
400 请求参数错误 缺少必填参数、参数格式错误
404 资源不存在 库位不存在、扩展属性不存在
409 资源冲突 库位已被锁定、扩展属性名称已存在
500 服务器内部错误 数据库连接失败、系统异常

错误响应格式

{
  "code": 400,
  "message": "请求参数错误：layer_name 不能为空",
  "data": null
}

注意事项

  1. 认证要求：所有接口都需要有效的认证token
  2. 参数验证：请确保传入的参数类型和格式正确
  3. 分页限制：列表接口的每页最多返回100条记录
  4. 批量操作限制：批量状态更新最多支持100个库位
  5. 扩展属性：创建或删除扩展属性会影响所有现有的库位层
  6. 时间格式：所有时间参数使用格式 YYYY-MM-DD HH:MM:SS
  7. 库位标识：所有接口统一使用 layer_name（库位名称）作为库位的主要标识符
  8. 事务处理：所有修改操作都在事务中进行，确保数据一致性
  9. 操作记录：所有状态更新和编辑操作都会自动记录到操作日志中
  10. 软删除：扩展属性删除使用软删除机制，不会物理删除数据
  11. 接口统一性：无论是路径参数还是查询参数，都使用 layer_name 确保接口的一致性

使用示例

查询空闲库位

GET /api/vwed-operate-point/list?is_occupied=false&is_locked=false&is_disabled=false&page=1&page_size=20

批量占用库位

PUT /api/vwed-operate-point/batch-status
Content-Type: application/json

{
  "layer_names": ["layer-001", "layer-002"],
  "action": "occupy",
  "reason": "批量放置货物"
}

获取特定库位状态

GET /api/vwed-operate-point/layer-001/status

获取库位详情

GET /api/vwed-operate-point/layer-001

创建产品类别扩展属性

POST /api/vwed-operate-point/extended-properties
Content-Type: application/json

{
  "property_key": "product_category",
  "property_name": "产品类别",
  "property_type": "select",
  "is_required": true,
  "options": [
    {"value": "electronics", "label": "电子产品"},
    {"value": "machinery", "label": "机械配件"}
  ]
}

编辑库位信息

PUT /api/vwed-operate-point/layer-001
Content-Type: application/json

{
  "goods_content": "iPhone 手机",
  "goods_weight": 200,
  "extended_fields": {
    "产品类别": "电子产品",
    "存储温度": "常温"
  }
}

查询库位操作记录

GET /api/vwed-operate-point/operation-logs?layer_name=layer-001&start_time=2024-01-01 00:00:00&end_time=2024-01-02 23:59:59

这些接口提供了对库位的全面管理功能，支持状态管理、信息编辑、扩展属性管理和操作记录查询等核心功能。