# 库位处理接口文档

## 批量设置库位 (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
}
```