1017 lines
34 KiB
Markdown
1017 lines
34 KiB
Markdown
# 库位管理接口文档
|
||
|
||
## 概述
|
||
|
||
库位管理接口提供了对库位（基于动作点分层）的全面管理功能，包括库位查询、状态更新、扩展属性管理、操作记录查询等。每个动作点可以包含多个层，每一层对应一个库位。
|
||
|
||
**重要说明：**
|
||
- 所有接口现在使用 `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)
|
||
|
||
获取库位列表，支持多种筛选条件、排序功能和分页查询。
|
||
|
||
**排序功能说明：**
|
||
- `layer_name_sort`：支持按层名称排序，如 GSD_1_1_1 格式，先按数字部分排序，然后按字母部分排序
|
||
- `station_name_sort`：支持按站点名称排序，如 AP1 格式，先按数字部分排序，然后按字母部分排序
|
||
- 排序规则：首先按数字排序，如果数字都一样的话，按照字母排序
|
||
- 可以同时使用两种排序，优先按 layer_name_sort 排序，然后按 station_name_sort 排序
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
| --------------------------- | ------- | ---- | --------------------------- |
|
||
| 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） |
|
||
| layer_name_sort | boolean | 否 | 层名称排序：true（升序，默认）、false（降序） |
|
||
| station_name_sort | boolean | 否 | 站点名称排序：true（升序，默认）、false（降序） |
|
||
| page | integer | 否 | 页码（默认1） |
|
||
| page_size | integer | 否 | 每页数量（默认20，最大100） |
|
||
|
||
#### 响应格式
|
||
|
||
```json
|
||
{
|
||
"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 | 动作点描述 |
|
||
|
||
#### 调用示例
|
||
|
||
**基本查询：**
|
||
```bash
|
||
GET /api/vwed-operate-point/list?scene_id=scene-001&is_occupied=false&page=1&page_size=20
|
||
```
|
||
|
||
**带排序的查询：**
|
||
```bash
|
||
# 按层名称升序排序
|
||
GET /api/vwed-operate-point/list?layer_name_sort=true&page=1&page_size=20
|
||
|
||
# 按站点名称降序排序
|
||
GET /api/vwed-operate-point/list?station_name_sort=false&page=1&page_size=20
|
||
|
||
# 组合排序：先按层名称升序，再按站点名称降序
|
||
GET /api/vwed-operate-point/list?layer_name_sort=true&station_name_sort=false&page=1&page_size=20
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 更新库位状态 (PUT /api/vwed-operate-point/status)
|
||
|
||
更新单个库位的状态。
|
||
|
||
#### 请求参数
|
||
|
||
```json
|
||
{
|
||
"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 | 清除空托盘状态 |
|
||
|
||
#### 响应格式
|
||
|
||
```json
|
||
{
|
||
"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)
|
||
|
||
批量更新多个库位的状态。
|
||
|
||
#### 请求参数
|
||
|
||
```json
|
||
{
|
||
"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 | 否 | 操作原因 |
|
||
|
||
#### 响应格式
|
||
|
||
```json
|
||
{
|
||
"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)
|
||
|
||
获取系统支持的所有库位操作类型。
|
||
|
||
#### 响应格式
|
||
|
||
```json
|
||
{
|
||
"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 | 是 | 库位名称（路径参数） |
|
||
|
||
#### 响应格式
|
||
|
||
```json
|
||
{
|
||
"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 | 是 | 库位名称（路径参数） |
|
||
|
||
#### 请求体
|
||
|
||
```json
|
||
{
|
||
"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个月"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 响应格式
|
||
|
||
```json
|
||
{
|
||
"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 | 是 | 库位名称（路径参数） |
|
||
|
||
#### 响应格式
|
||
|
||
```json
|
||
{
|
||
"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)
|
||
|
||
创建新的扩展属性定义。
|
||
|
||
#### 请求参数
|
||
|
||
```json
|
||
{
|
||
"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": []
|
||
}
|
||
```
|
||
|
||
#### 响应格式
|
||
|
||
```json
|
||
{
|
||
"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） |
|
||
|
||
#### 响应格式
|
||
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
#### 响应格式
|
||
|
||
```json
|
||
{
|
||
"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会自动更新，包含新的扩展属性配置。
|
||
|
||
**请求参数：**
|
||
```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": "扩展属性创建成功，已应用到所有库位层"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 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） |
|
||
|
||
#### 响应格式
|
||
|
||
```json
|
||
{
|
||
"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 | 记录创建时间 |
|
||
|
||
#### 调用示例
|
||
|
||
```bash
|
||
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 | 服务器内部错误 | 数据库连接失败、系统异常 |
|
||
|
||
### 错误响应格式
|
||
|
||
```json
|
||
{
|
||
"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` 确保接口的一致性
|
||
|
||
## 使用示例
|
||
|
||
### 查询空闲库位
|
||
|
||
```bash
|
||
GET /api/vwed-operate-point/list?is_occupied=false&is_locked=false&is_disabled=false&page=1&page_size=20
|
||
```
|
||
|
||
### 批量占用库位
|
||
|
||
```bash
|
||
PUT /api/vwed-operate-point/batch-status
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"layer_names": ["layer-001", "layer-002"],
|
||
"action": "occupy",
|
||
"reason": "批量放置货物"
|
||
}
|
||
```
|
||
|
||
### 获取特定库位状态
|
||
|
||
```bash
|
||
GET /api/vwed-operate-point/layer-001/status
|
||
```
|
||
|
||
### 获取库位详情
|
||
|
||
```bash
|
||
GET /api/vwed-operate-point/layer-001
|
||
```
|
||
|
||
### 创建产品类别扩展属性
|
||
|
||
```bash
|
||
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": "机械配件"}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 编辑库位信息
|
||
|
||
```bash
|
||
PUT /api/vwed-operate-point/layer-001
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"goods_content": "iPhone 手机",
|
||
"goods_weight": 200,
|
||
"extended_fields": {
|
||
"产品类别": "电子产品",
|
||
"存储温度": "常温"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 查询库位操作记录
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
这些接口提供了对库位的全面管理功能，支持状态管理、信息编辑、扩展属性管理和操作记录查询等核心功能。 |