jzw/VWED_server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
VWED_server/VWED任务模块接口文档/库位处理接口文档.md

1170 lines
39 KiB
Markdown
Raw Normal View History

init project
2025-04-30 16:57:46 +08:00
# 库位处理接口文档
## 批量设置库位 (BatchSettingSiteBp)
本接口用于批量设置库位的占用状态和内容。当库位 IDs 和库区集同时提供时，会对这些库位进行批量设置操作。
### 描述
本块在需要批量设置库位内容和占用状态时使用，可同时设置多个库位或多个库区的库位的占用状态。当库位 Ids 和库区集参数均填入时，则表示可同时对满足这两个参数的库位进行设置。
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| ---------- | -------- | -------- | ------------ | ------------------------ |
| siteIds | 库位IDs | 非必填 | String[] | 多个库位 id 的集合 |
| groupNames | 库区集 | 非必填 | String[] | 多个库区的集合 |
| filled | 占用 | 必填 | Boolean | 库位是否占用状态，选择 true 或 false |
| content | 货物 | 非必填 | String | 填写库位中具体的货物 |
| type | 是否物理库位 | 非必填 | Boolean | 勾选设置的库位是否是物理库位或是逻辑库位。物理库位指地图上实际存在的库位，逻辑库位指因业务逻辑创建的虚拟库位，不实际存在于地图中。 |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| --------- | -------- | ------- | ------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息 |
| code | 返回代码 | Number | 操作结果代码 |
### 调用示例
```json
// 输入参数示例
{
"siteIds": ["site001", "site002", "site003"],
"groupNames": [],
"filled": true,
"content": "产品A",
"type": "physical"
}
// 成功响应示例
{
"success": true,
"message": "批量设置库位成功，共设置 3 个库位",
"code": 200
}
// 失败响应示例
{
"success": false,
"message": "批量设置库位失败: 库位ID不存在",
"code": 404
}
```
## 获取密集库位 (GetIdleCrowdedSiteBp)
本接口用于获取密集库位，支持根据库区、占用状态等条件查找适合的库位。
### 描述
本块用于在一组密集库位中获取符合条件的空闲库位，支持重试机制。
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| ---------- | -------- | -------- | ------------ | ------------------------ |
| groupName | 库区集 | 必填 | String[] | 库区数组 |
| filled | 取/放 | 必填 | Boolean | 选出库位用来取货还是放货 |
| content | 货物(取) | 非必填 | String | 取货库位的货物内容，在放货此字段忽略 |
| lock | 获取库位后是否锁定 | 非必填 | Boolean | 选出库位后是否立即锁定 |
| retry | 是否重试 | 必填 | Boolean | 是否启用重试 |
| retryPeriod | 重试时间间隔(ms) | 非必填 | Long | 重试周期（毫秒） |
| retryNum | 重试次数 | 非必填 | Long | 重试次数 |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| --------- | -------- | ------- | ------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息 |
| code | 返回代码 | Number | 操作结果代码 |
| data | 数据 | Object | 返回数据对象 |
| data.siteId | 选出的库位 | String | 获取到的库位ID |
### 调用示例
```json
// 输入参数示例
{
"groupName": ["density_area_1", "density_area_2"],
"filled": false,
"content": "",
"lock": true,
"retry": true,
"retryPeriod": 1000,
"retryNum": 3
}
// 成功响应示例
{
"success": true,
"message": "获取密集库位成功，库位ID: site001",
"code": 200,
"data": {
"siteId": "site001"
}
}
// 失败响应示例
{
"success": false,
"message": "获取密集库位失败: 未找到合适的库位",
"code": 404
}
```
## 获取库位 (GetIdleSiteBp)
本接口用于获取符合条件的库位，支持按多种条件过滤和查询。
### 描述
本块用于获取符合特定条件的库位，可以指定多种查询参数，并支持自动无限重试机制直到找到合适的库位。
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| ------------ | -------- | -------- | ------------- | ------------------------- |
| siteId | 库位ID | 非必填 | String | 库位ID |
| content | 货物 | 非必填 | String | 获取该货物名称的库位 |
| filled | 是否有货物 | 非必填 | Boolean | true: 获取有货物的库位; false: 获取无货物的库位 |
| locked | 是否已锁定 | 必填 | Boolean | true: 获取已锁定的库位; false: 获取未锁定的库位 |
| type | 是否物理库位 | 非必填 | Boolean | 是否是物理库位 |
| groupName | 库区名 | 非必填 | String | 库区名称 |
| lock | 获取库位后是否锁定 | 非必填 | Boolean | 选出库位后是否立即锁定 |
| retryPeriod | 重试时间间隔(ms) | 非必填 | Long | 重试间隔时间（毫秒），默认为1000毫秒。系统会不断重试直到获取到库位。 |
| ifFair | 是否为公平锁 | 非必填 | Boolean | 任务先尝试加锁库位，优先这个任务加锁此库位 |
| orderDesc | 是否为降序 | 非必填 | Boolean | true: 优先获取库位id大的; false: 优先获取库位id小的; 默认true |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| --------- | -------- | ------- | ------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息，包含重试次数信息 |
| code | 返回代码 | Number | 操作结果代码 |
| data | 数据 | Object | 返回数据对象 |
| data.siteId | 选出的库位 | String | 获取到的库位ID |
### 调用示例
```json
// 输入参数示例
{
"locked": false,
"filled": false,
"groupName": "storage_area_A",
"lock": true,
"retryPeriod": 2000,
"ifFair": true,
"orderDesc": true
}
// 成功响应示例
{
"success": true,
"message": "获取库位成功，库位ID: site123",
"code": 200,
"data": {
"siteId": "site123"
}
}
// 重试成功响应示例
{
"success": true,
"message": "第3次重试获取库位成功，库位ID: site123",
"code": 200,
"data": {
"siteId": "site123"
}
}
```
### 注意事项
1. 该接口实现了无限重试机制，会一直尝试获取库位直到成功
2. 每次重试之间会等待retryPeriod指定的时间（毫秒）
3. 如果长时间无法获取到库位，建议检查查询条件是否合理
## 根据任务实例ID获取所有枷锁库位 (GetLockedSitesByTaskRecordIdBp)
本接口用于获取某个任务实例已锁定的所有库位。
### 描述
本块用于查询指定任务实例ID锁定的所有库位，方便后续对这些库位进行操作。
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| ------------- | ---------- | -------- | ------------- | -------------- |
| taskRecordId | 任务实例ID | 必填 | String | 任务实例ID |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| ---------------- | -------------- | --------- | ----------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息 |
| code | 返回代码 | Number | 操作结果代码 |
| data | 数据 | Object | 返回数据对象 |
| lockedSiteIdList | 已锁定库位列表 | String[] | 已锁定的库位ID列表 |
### 调用示例
```json
// 输入参数示例
{
"taskRecordId": "task123456"
}
// 成功响应示例
{
"success": true,
"message": "获取任务锁定库位成功，共 3 个库位",
"code": 200,
"data": {
"lockedSiteIdList": ["site001", "site002", "site003"]
}
}
// 失败响应示例
{
"success": false,
"message": "获取任务锁定库位失败: 任务实例不存在",
"code": 404
}
```
## 获取库位扩展属性 (GetSiteAttrBp)
本接口用于获取库位的扩展属性值。
### 描述
本块用于获取指定库位ID的特定扩展属性值，支持获取自定义属性。
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| --------- | -------- | -------- | ------------- | -------------- |
| siteId | 库位ID | 必填 | String | 指定的库位 Id |
| attrName | 属性名称 | 必填 | String | 指定的库位扩展属性名称|
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| ---------- | -------- | ------- | ------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息 |
| code | 返回代码 | Number | 操作结果代码 |
| data | 数据 | Object | 返回数据对象 |
| attrValue | 属性值 | Any | 属性值 |
### 调用示例
```json
// 输入参数示例
{
"siteId": "site001",
"attrName": "temperature"
}
// 成功响应示例
{
"success": true,
"message": "获取库位属性值成功，temperature: 25",
"code": 200,
"data": {
"attrValue": "25"
}
}
// 失败响应示例
{
"success": false,
"message": "获取库位属性值失败: 属性不存在",
"code": 404
}
```
## 查询库位 (QueryIdleSiteBp)
本接口用于查询符合条件的库位详细信息。
### 描述
本块用于根据指定条件查询库位的详细信息，与获取库位接口不同，此接口会返回库位的完整信息，而不会锁定库位。
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| ------------ | -------- | -------- | ------------- | ------------------------- |
| siteId | 库位ID | 非必填 | String | 库位ID |
| content | 货物 | 非必填 | String | 获取该货物名称的库位 |
| filled | 是否有货物 | 非必填 | Boolean | true: 获取有货物的库位; false: 获取无货物的库位 |
| locked | 是否已锁定 | 非必填 | Boolean | true: 获取已锁定的库位; false: 获取未锁定的库位 |
| type | 是否物理库位 | 非必填 | Boolean | 勾选 True 或者 False |
| groupName | 库区名 | 非必填 | String | 填入库区名称 |
| orderDesc | 是否为降序 | 非必填 | Boolean | true: 优先获取库位id大的; false: 优先获取库位id小的; 默认为false |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| --------- | -------- | ------- | ------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息 |
| code | 返回代码 | Number | 操作结果代码 |
| data | 数据 | Object | 返回数据对象 |
| site | 库位信息 | Object | 库位详细信息对象 |
### 库位对象属性（不确定）
| 属性名 | 中文名称 | 类型 | 描述 |
| ----------- | -------- | --------- | ------------------- |
| id | 库位ID | String | 库位ID |
| groupName | 库区名称 | String | 库区名称 |
| type | 类型 | Number | 库位类型 |
| filled | 占用 | Boolean | 是否已占用 |
| locked | 锁定 | Boolean | 是否已锁定 |
| content | 货物内容 | String | 库位内容 |
### 调用示例
```json
// 输入参数示例
{
"siteId": "site001",
"filled": false,
"locked": false
}
// 成功响应示例
{
"success": true,
"message": "查询库位成功，库位ID: site001",
"code": 200,
"data": {
"site": {
"id": "site001",
"groupName": "storage_area_A",
"type": 0,
"filled": false,
"locked": false,
"content": ""
}
}
}
// 失败响应示例
{
"success": false,
"message": "查询库位失败: 未找到符合条件的库位",
"code": 404
}
```
## 设置库位扩展属性 (SetSiteAttrBp)
本接口用于设置库位的扩展属性值。
### 描述
本块用于设置指定库位ID的特定扩展属性值，支持设置自定义属性。
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| ---------- | -------- | -------- | ------------- | ------------- |
| siteId | 库位ID | 必填 | String | 库位ID |
| attrName | 属性名称 | 必填 | String | 指定的库位扩展属性名称|
| attrValue | 属性值 | 非必填 | Any | 属性值 |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| --------- | -------- | ------- | ------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息 |
| code | 返回代码 | Number | 操作结果代码 |
### 调用示例
```json
// 输入参数示例
{
"siteId": "site001",
"attrName": "temperature",
"attrValue": 25
}
// 成功响应示例
{
"success": true,
"message": "设置库位属性值成功，site001.temperature = 25",
"code": 200
}
// 失败响应示例
{
"success": false,
"message": "设置库位属性值失败: 库位不存在",
"code": 404
}
```
## 设置库位货物 (SetSiteContentBp)
本接口用于设置库位的货物内容。
### 描述
本块用于设置指定库位ID的货物内容，通常用于标记库位中存放的具体物品。
### 输入参数
| 参数名 | 是否必填 | 类型 | 描述 |
| --------- | -------- | ------------- | ------------- |
| siteId | 必填 | String | 库位ID |
| content | 必填 | String | 货物内容 |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| --------- | -------- | ------- | ------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息 |
| code | 返回代码 | Number | 操作结果代码 |
### 调用示例
```json
// 输入参数示例
{
"siteId": "site001",
"content": "产品A-批次123"
}
// 成功响应示例
{
"success": true,
"message": "设置库位货物成功，site001 货物: 产品A-批次123",
"code": 200
}
// 失败响应示例
{
"success": false,
"message": "设置库位货物失败: 库位不存在",
"code": 404
}
```
## 设置库位为空 (SetSiteEmptyBp)
本接口用于将库位设置为空闲状态。
### 描述
该块可以将指定库位设置为未占用状态，同时清空货物字段。
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| --------- | -------- | -------- | ------------- | ------------- |
| siteId | 库位ID | 必填 | String | 库位ID |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| --------- | -------- | ------- | ------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息 |
| code | 返回代码 | Number | 操作结果代码 |
### 调用示例
```json
// 输入参数示例
{
"siteId": "site001"
}
// 成功响应示例
{
"success": true,
"message": "设置库位为空成功，库位ID: site001",
"code": 200
}
// 失败响应示例
{
"success": false,
"message": "设置库位为空失败: 库位不存在",
"code": 404
}
```
## 设置库位为占用 (SetSiteFilledBp)
本接口用于将库位设置为占用状态。
### 描述
该块可以将指定库位设置为占用状态，但不操作货物字符串。
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| --------- | -------- | -------- | ------------- | ------------- |
| siteId | 库位ID | 必填 | String | 库位ID |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| --------- | -------- | ------- | ------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息 |
| code | 返回代码 | Number | 操作结果代码 |
### 调用示例
```json
// 输入参数示例
{
"siteId": "site001"
}
// 成功响应示例
{
"success": true,
"message": "设置库位为占用成功，库位ID: site001",
"code": 200
}
// 失败响应示例
{
"success": false,
"message": "设置库位为占用失败: 库位不存在",
"code": 404
}
```
## 锁定库位 (SetSiteLockedBp)
本接口用于锁定库位，防止其他任务操作该库位。
### 描述
该块可以将指定定的库位锁定，前提是该库位位已经在库存中设置或者在当前节点任务实例中被当前节点加锁。如果不满足条件，这个块将阻塞，直到该库位可交为解锁状态，然后进行锁定。
### 输入参数
| 参数名 | 是否必填 | 类型 | 描述 |
| ---------- | -------- | ------------ | ------------------------ |
| 库位 Id | 必填 | String | 指定的库位 Id |
| 是否为公平锁 | 非必填 | boolean | 任务先发出加锁库位，优先这个任务加锁此库位 |
| 加锁者 | 非必填 | String | 指定加锁该库位的加锁者，默认为当前任务实例id |
| 重试次数 | 非必填 | Integer | 重试次数 |
### 调用示例
```json
// 输入参数示例
{
"siteId": "site001",
"ifFair": true,
"locker": "task123456",
"retryNum": 3
}
// 成功响应示例
{
"success": true,
"message": "锁定库位成功，库位ID: site001",
"code": 200,
"data": {
"success": true
}
}
// 失败响应示例
{
"success": false,
"message": "锁定库位失败，库位ID: site001，可能已被其他任务锁定",
"code": 409,
"data": {
"success": false
}
}
```
## 解锁库位 (SetSiteUnlockedBp)
本接口用于解锁库位，允许其他任务操作该库位。
### 描述
本块用于解锁特定的库位ID，解除其与特定任务的关联，允许其他任务操作该库位。
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| ---------- | -------- | -------- | ------------- | --------------------- |
| siteId | 库位ID | 必填 | String | 指定的库位ID |
| unLockedId | 解锁者 | 非必填 | String | 指定解锁该库位的解锁者，默认为当前任务实例id |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| --------- | --------- | ------- | ------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息 |
| code | 返回代码 | Number | 操作结果代码 |
### 调用示例
```json
// 输入参数示例
{
"siteId": "site001",
"unLockedId": "task123456"
}
// 成功响应示例
{
"success": true,
"message": "解锁库位成功，库位ID: site001",
"code": 200
}
// 失败响应示例
{
"success": false,
"message": "解锁库位失败: 库位不存在",
"code": 404
}
```
## 设置库位标签 (SetSiteTagsBp)
本接口用于设置库位的标签信息。
### 描述
本块用于为指定库位设置标签，可用于标记库位的特殊属性或分类，便于后续查询和管理。
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| --------- | -------- | -------- | ------------- | ------------- |
| siteId | 库位ID | 必填 | String | 指定的库位ID |
| tags | 标签 | 非必填 | String | 库位标签，多个标签可用逗号分隔 |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| --------- | -------- | ------- | ------------------- |
| success | 成功标志 | Boolean | 操作是否成功 |
| message | 消息 | String | 操作结果消息 |
| code | 返回代码 | Number | 操作结果代码 |
### 调用示例
```json
// 输入参数示例
{
"siteId": "site001",
"tags": "临时存储,高优先级,易碎品"
}
// 成功响应示例
{
"success": true,
"message": "设置库位标签成功，库位ID: site001，标签: 临时存储,高优先级,易碎品",
"code": 200
}
// 失败响应示例
{
"success": false,
"message": "设置库位标签失败: 库位不存在",
"code": 404
}
add api
2025-07-14 10:29:37 +08:00
```
## 获取库位详情 (GetStorageLocationDetail)
本接口用于获取指定库位的详细信息。
### 描述
本接口用于获取指定库位的完整详情信息，包括库位基本信息、动作点信息、扩展字段定义和值、状态变更历史等。适用于需要全面了解库位信息的场景。
### 接口信息
- **URL**: `/api/vwed-operate-point/{storage_location_id}`
- **方法**: GET
- **认证**: 需要
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| ------------------ | -------- | -------- | ------ | ------------------------------ |
| storage_location_id | 库位ID | 必填 | String | 要获取详情的库位ID |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| -------------------------- | --------------- | ------- | ------------------------------ |
| code | 返回代码 | Number | 操作结果代码 |
| message | 消息 | String | 操作结果消息 |
| data | 数据 | Object | 返回数据对象 |
| data.storage_location | 库位信息 | Object | 库位基本信息 |
| data.operate_point_info | 动作点信息 | Object | 所属动作点的详细信息 |
| data.extended_fields_definitions | 扩展字段定义 | Array | 扩展字段的定义信息 |
| data.status_history | 状态变更历史 | Array | 库位状态变更历史记录 |
### 调用示例
```json
// 请求URL
GET /api/vwed-operate-point/layer-001
// 成功响应示例
{
"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,
"goods_stored_at": null,
"goods_retrieved_at": null,
"last_access_at": 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_id": "point-001",
"station_name": "存储站点A",
"storage_location_name": "A1库位",
"scene_id": "scene-001",
"storage_area_id": "area-001"
},
"operate_point_info": {
"id": "point-001",
"station_name": "存储站点A",
"storage_location_name": "A1库位",
"scene_id": "scene-001",
"storage_area_id": "area-001",
"storage_area_type": "dense",
"area_name": "密集存储区",
"max_layers": 10,
"current_layers": 5,
"position_x": 100,
"position_y": 200,
"position_z": 0,
"description": "密集存储区的动作点",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00",
"is_deleted": false
},
"extended_fields_definitions": [
{
"id": "ext-001",
"property_name": "产品类别",
"property_type": "select",
"is_required": true,
"is_enabled": true,
"description": "产品分类",
"options": [
{"value": "电子产品", "label": "电子产品"},
{"value": "机械配件", "label": "机械配件"}
]
},
{
"id": "ext-002",
"property_name": "存储温度",
"property_type": "string",
"is_required": false,
"is_enabled": true,
"description": "存储温度要求"
}
],
"status_history": []
}
}
// 失败响应示例
{
"code": 404,
"message": "库位 layer-001 不存在",
"data": null
}
```
## 编辑库位信息 (EditStorageLocation)
本接口用于编辑和更新库位的各种属性信息。
### 描述
本接口用于编辑库位的各种属性，包括货物信息、库位规格、状态字段、扩展字段等。支持部分更新，只有传入的字段且值发生变化时才会被更新。扩展字段必须在系统中已定义且已启用。
### 接口信息
- **URL**: `/api/vwed-operate-point/{storage_location_id}`
- **方法**: PUT
- **认证**: 需要
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| ------------------ | ------------ | -------- | ------- | ------------------------------ |
| storage_location_id | 库位ID | 必填 | String | 要编辑的库位ID |
| goods_content | 货物内容 | 非必填 | String | 货物内容描述 |
| goods_weight | 货物重量 | 非必填 | Integer | 货物重量（克） |
| goods_volume | 货物体积 | 非必填 | Integer | 货物体积（立方厘米） |
| max_weight | 最大承重 | 非必填 | Integer | 最大承重（克） |
| max_volume | 最大体积 | 非必填 | Integer | 最大体积（立方厘米） |
| layer_height | 层高 | 非必填 | Integer | 层高（毫米） |
| is_locked | 是否锁定 | 非必填 | Boolean | 库位是否锁定 |
| is_disabled | 是否禁用 | 非必填 | Boolean | 库位是否禁用 |
| is_empty_tray | 是否空托盘 | 非必填 | Boolean | 库位是否为空托盘状态 |
| tags | 标签 | 非必填 | String | 库位标签 |
| description | 描述 | 非必填 | String | 库位描述 |
| extended_fields | 扩展字段 | 非必填 | Object | 扩展字段的键值对 |
### 输出参数
| 参数名 | 中文名称 | 类型 | 描述 |
| -------------------------- | --------------- | ------- | ------------------------------ |
| code | 返回代码 | Number | 操作结果代码 |
| message | 消息 | String | 操作结果消息 |
| data | 数据 | Object | 返回数据对象 |
| data.storage_location_id | 库位ID | String | 被编辑的库位ID |
| data.success | 成功标志 | Boolean | 编辑是否成功 |
| data.message | 操作消息 | String | 详细的操作结果消息 |
| data.updated_fields | 更新字段列表 | Array | 已更新的字段名称列表 |
| data.updated_storage_location | 更新后库位信息 | Object | 更新后的库位完整信息 |
### 调用示例
```json
// 请求URL
PUT /api/vwed-operate-point/layer-001
// 请求体示例
{
"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": {
"storage_location_id": "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.产品类别",
"extended_fields.存储温度",
"extended_fields.保质期",
"updated_at"
],
"updated_storage_location": {
"id": "layer-001",
"layer_index": 1,
"layer_name": "第一层",
"is_occupied": false,
"is_locked": false,
"is_disabled": false,
"is_empty_tray": true,
"locked_by": null,
"goods_content": "电子产品A",
"goods_weight": 500,
"goods_volume": 200,
"goods_stored_at": null,
"goods_retrieved_at": null,
"last_access_at": null,
"max_weight": 6000,
"max_volume": 1000,
"layer_height": 300,
"tags": "高架库,密集存储,已更新",
"description": "密集存储区第一层 - 已更新",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-02T10:30:00",
"extended_fields": {
"产品类别": "机械配件",
"存储温度": "常温",
"保质期": "12个月"
},
"operate_point_id": "point-001",
"station_name": "存储站点A",
"storage_location_name": "A1库位",
"scene_id": "scene-001",
"storage_area_id": "area-001"
}
}
}
// 失败响应示例
{
"code": 404,
"message": "库位 layer-001 不存在",
"data": null
}
// 没有字段变化的响应示例
{
"code": 200,
"message": "库位信息编辑成功",
"data": {
"storage_location_id": "layer-001",
"success": true,
"message": "没有字段发生变化，数据保持不变",
"updated_fields": [],
"updated_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": "电子产品A",
"goods_weight": 500,
"goods_volume": 200,
"goods_stored_at": null,
"goods_retrieved_at": null,
"last_access_at": null,
"max_weight": 6000,
"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_id": "point-001",
"station_name": "存储站点A",
"storage_location_name": "A1库位",
"scene_id": "scene-001",
"storage_area_id": "area-001"
}
}
}
// 部分字段更新失败示例
{
"code": 400,
"message": "更新扩展字段失败: 扩展字段 未定义字段 不存在或已禁用",
"data": null
}
```
### 注意事项
1. **部分更新**: 只有传入的字段且值发生变化时才会被更新，未传入的字段保持原值
2. **层名称限制**: 层名称（layer_name）不能通过此接口修改，请使用其他方式
3. **状态字段支持**: 支持修改 `is_locked`、`is_disabled`、`is_empty_tray` 三个状态字段
4. **扩展字段验证**: 扩展字段必须在系统中已定义且已启用，否则会跳过更新
5. **数据变更校验**: 如果所有字段都没有发生变化，会返回相应提示信息
6. **字段验证**: 数值类型字段会进行范围验证，字符串类型字段会进行长度验证
7. **事务处理**: 所有更新操作在同一个事务中进行，确保数据一致性
## 获取库位操作记录 (GetStorageLocationOperationLogs)
本接口用于获取库位相关的操作记录，支持多种筛选条件和分页查询。
### 描述
本接口用于查询库位相关的操作记录，包括状态更新操作、信息编辑操作等。所有对库位的操作都会自动记录到操作日志中，方便后续审计和追踪。
### 接口信息
- **URL**: `/api/vwed-operate-point/operation-logs`
- **方法**: GET
- **认证**: 需要
### 输入参数
| 参数名 | 中文名称 | 是否必填 | 类型 | 描述 |
| ------------------ | ------------ | -------- | ------- | ------------------------------ |
| storage_location_id | 库位ID | 非必填 | String | 查询特定库位的操作记录 |
| operator | 操作人 | 非必填 | String | 操作人姓名（支持模糊搜索） |
| operation_type | 操作类型 | 非必填 | String | 操作类型（如：occupy、release等）|
| 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 | 返回代码 | Number | 操作结果代码 |
| message | 消息 | String | 操作结果消息 |
| data | 数据 | Object | 返回数据对象 |
| data.total | 总数量 | Number | 符合条件的记录总数 |
| data.page | 当前页码 | Number | 当前页码 |
| data.page_size | 每页数量 | Number | 每页数量 |
| data.total_pages | 总页数 | Number | 总页数 |
| data.logs | 操作记录列表 | Array | 操作记录数组 |
| data.logs[].id | 记录ID | String | 操作记录的唯一标识 |
| data.logs[].operation_time | 操作时间 | String | 操作发生的时间 |
| data.logs[].operator | 操作人 | String | 执行操作的人员 |
| data.logs[].operation_type | 操作类型 | String | 操作类型 |
| data.logs[].affected_storage_locations | 影响的库位列表 | Array | 受影响的库位ID列表 |
| data.logs[].description | 操作描述 | String | 操作的详细描述 |
| data.logs[].created_at | 创建时间 | String | 记录创建时间 |
### 支持的操作类型
| 操作类型 | 中文名称 | 描述 |
| ------------ | ----------- | ------------------------------ |
| occupy | 占用库位 | 将库位设置为占用状态 |
| release | 释放库位 | 将库位设置为空闲状态 |
| lock | 锁定库位 | 锁定库位防止其他操作 |
| unlock | 解锁库位 | 解锁库位允许其他操作 |
| enable | 启用库位 | 启用库位使其可用 |
| disable | 禁用库位 | 禁用库位使其不可用 |
| set_empty_tray | 设置空托盘 | 将库位设置为空托盘状态 |
| clear_empty_tray | 清除空托盘 | 清除库位的空托盘状态 |
| 编辑库位 | 编辑库位 | 编辑库位的信息 |
### 调用示例
```json
// 请求URL示例
GET /api/vwed-operate-point/operation-logs?storage_location_id=layer-001&page=1&page_size=10
// 带时间范围的请求示例
GET /api/vwed-operate-point/operation-logs?start_time=2024-01-01 00:00:00&end_time=2024-01-02 23:59:59&operator=admin&page=1&page_size=20
// 成功响应示例
{
"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"
},
{
"id": "log-003",
"operation_time": "2024-01-02T08:45:00",
"operator": "user001",
"operation_type": "lock",
"affected_storage_locations": ["layer-001", "layer-002"],
"description": "锁定库位操作",
"created_at": "2024-01-02T08:45:00"
}
]
}
}
// 空结果响应示例
{
"code": 200,
"message": "查询操作记录成功",
"data": {
"total": 0,
"page": 1,
"page_size": 10,
"total_pages": 0,
"logs": []
}
}
// 时间格式错误示例
{
"code": 400,
"message": "开始时间格式错误，请使用格式：YYYY-MM-DD HH:MM:SS",
"data": null
}
// 参数错误示例
{
"code": 400,
"message": "开始时间不能大于结束时间",
"data": null
}
```
### 注意事项
1. **时间格式**: 时间参数必须使用格式 `YYYY-MM-DD HH:MM:SS`，例如 `2024-01-01 12:00:00`
2. **时间范围**: 如果同时提供开始时间和结束时间，开始时间不能大于结束时间
3. **模糊搜索**: 操作人字段支持模糊搜索，会匹配包含关键词的记录
4. **排序方式**: 操作记录按操作时间倒序排列，最新的操作记录在前面
5. **自动记录**: 所有对库位的操作都会自动记录，无需手动创建记录
6. **分页限制**: 每页最多返回100条记录
7. **数据完整性**: 操作记录一旦创建就不能修改或删除，确保审计追踪的完整性
Reference in New Issue Copy Permalink