xudan/webapp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
webapp/库位管理接口文档.md

1017 lines
34 KiB
Markdown
Raw Normal View History

feat: 添加库位管理功能，创建库位列表和批量操作界面，支持库位状态查询和更新
2025-07-25 16:18:50 +08:00
# 库位管理接口文档
## 概述
库位管理接口提供了对库位（基于动作点分层）的全面管理功能，包括库位查询、状态更新、扩展属性管理、操作记录查询等。每个动作点可以包含多个层，每一层对应一个库位。
**重要说明：**
- 所有接口现在使用 `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
```
这些接口提供了对库位的全面管理功能，支持状态管理、信息编辑、扩展属性管理和操作记录查询等核心功能。
Reference in New Issue Copy Permalink