> **源文件**：仪陇表务管理系统-PRD-04-功能需求说明-13-退库管理-V1.0.docx
> **导出时间**：2026-05-26 10:34


**仪陇表务管理系统
产品需求说明书
04-功能需求说明
退库管理**

文档版本：V1.0

对应 01 版本：仪陇表务管理系统-PRD-01-总体说明-V1.0

模块序号：13

模块名称：退库管理

## 退库管理

本模块覆盖营业办/供水站水表退库申请与分公司旧表退回总仓申请两类退返场景。含 Web 菜单：水表退库申请、水表退回申请-分仓。审批在工单中心办理；退库通过后由「入库管理」办理分仓入库；退回总仓通过后由「出库管理」「入库管理」衔接出库与总仓入库确认。

### **水表退库申请**

#### 功能描述

用于营业办/供水站主任提交水表退库申请工单并查看本人历史申请。适用于现场无法安装但水表健康可留存营业所，或因健康问题需退回分公司处理等场景。审核通过后驱动分仓退库入库。

#### 菜单权限

表务营业办/供水站管理人员；表务系统管理员

#### 数据权限

表务营业办/供水站管理人员：可见、可操作本营业办（或本供水站）范围内水表退库申请业务数据；「历史记录」Tab 仅展示当前登录账号作为发起人提交的退库申请工单。

表务系统管理员：可见、可操作全公司范围内水表退库申请数据。

#### 核心逻辑

以退库申请单及关联工单为业务主体，关联退库水表明细。

本菜单仅负责发起与进度查询，审核在工单中心办理，入库在「入库管理」办理。

#### 业务流程

流程概要

营业办/供水站主任发起 → 分公司分管领导审核 → 通过后抄送分公司库管员；营业所实物送至分公司仓库后，由入库管理办理退库入库，实现退库申请与资产回流闭环。

环节说明表

| 序号 | 环节名称 | 环节类型 | 责任岗位 | 须填写 / 处理内容 | 审核结果选项 | 通过后流向 | 驳回 / 其他结果流向 | 抄送 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 水表退库申请发起 | 发起 | 表务营业办/供水站管理人员 | 填报退库申请基础信息及退库水表明细（见「一级页面：水表退库申请-tab-工单发起」） | 提交 | 退库申请审核 | — | — |
| 2 | 退库申请审核 | 审核 | 表务分公司领导班子 | 核对退库原因、水表数量表号及现场情况说明；填写审核意见 | 通过；驳回 | 流程通过（系统自动处理） | 退回水表退库申请发起 | 表务分公司库管员 |
| 3 | 退库入库衔接 | 系统自动 | 系统 | 工单通过后更新申请状态，驱动分仓可办理退库入库 | — | 流程完结（待实物入库） | — | — |

审核通过后数据影响

- 生成/更新水表退库申请记录及关联工单，工单状态为「已通过」。

- 抄送表务分公司库管员待接收实物。

- 驱动「入库管理」可关联本申请办理分仓退库入库（不在本菜单办理）。

关联界面逻辑闭环

- 发起侧：「历史记录」Tab 与详情展示工单状态、当前节点；通过后展示「入库状态」（待入库/已入库）。

- 办理侧：「去处理」仅在审批中且当前用户为处理人时显示，跳转工单中心办理页。

- 入库侧：详情不提供入库办理入口（在「入库管理」办理）；入库状态与入库管理列表一致。

- 跨菜单一致：工单状态、入库状态文案与入库管理、工单中心一致。

审核界面说明

- 标准界面：复用工单中心「二级页面：工单办理」。

- 本业务差异：各审核环节只读展示申请信息及退库水表明细；无额外填报区块。

#### 功能需求

##### **一级页面：水表退库申请-tab-工单发起**

#整体布局

-- 菜单入口：Tab 页结构；Tab 列表：工单发起（本 Tab，默认选中）、历史记录（见「一级页面：水表退库申请-tab-历史记录」）

-- 本 Tab 内容：申请表单区 + 业务明细表格（如有）；底部常驻「提交」「重置」

#信息展示

-- 申请基础信息区

-- 申请部门：只读，默认当前用户所属部门

-- 申请人：只读，默认当前登录用户

-- 申请日期：只读，默认当前日期

-- 退库原因：必填，下拉单选（无法现场安装可留存、健康原因退回分公司、其他）

-- 项目名称：选填，文本，最多 100 字

-- 备注：选填，多行文本，最多 500 字

-- 退库水表明细区：表格，支持扫码/手工录入，至少 1 行

-- 水表编号：必填；须校验水表状态可退库

-- 水表口径、水表类型：必填，下拉

-- 数量：必填，正整数，默认 1

-- 明细备注：选填

#底部按钮

-- 提交：校验必填项及明细规则后提交，进入审批流程

-- 重置：清空表单；有已填内容时二次确认

#交互说明

-- 提交成功后提示「提交成功」，自动切换至 Tab「历史记录」并刷新列表

-- Tab 切换时保留未提交内容；刷新页面后未提交内容不保留

##### **一级页面：水表退库申请-tab-历史记录**

#整体布局

-- 菜单入口 Tab「历史记录」；上下结构：查询条件区 + 历史工单列表

-- 数据范围：仅当前登录账号作为发起人提交的水表退库申请工单

#查询条件

-- 工单编号：文本，支持模糊搜索

-- 申请单号：文本，支持模糊搜索

-- 工单状态：下拉单选（全部、审批中、已通过、已驳回、已撤销）

-- 申请日期：日期范围选择

-- 功能按钮：查询、重置

#数据列表

-- 表格标题：我的水表退库申请

-- 表格字段：工单编号、申请单号、申请日期、退、库、原、因、、、明、细、数、量、当前节点、工单状态、提交时间

-- 行内操作：详情

#交互说明

-- 点击工单编号、行内「详情」或列表行，打开「弹窗：水表退库申请工单详情」

-- 列表按提交时间倒序，支持分页

##### **弹窗：水表退库申请工单详情**

#弹窗类型

-- 抽屉弹窗（右侧滑出）；遮罩：有；主页面：不可操作

#整体布局

-- 宽度约 960px；全高；内部分 Tab：申请信息 / 退库明细

#弹窗标题

-- 水表退库申请详情 - {工单编号}

#标题栏操作

-- 关闭（×）：关闭抽屉，返回当前 Tab 列表

#信息展示

-- Tab·申请信息：只读展示对应申请及业务信息

-- Tab·退库明细：只读展示对应申请及业务信息

-- Tab·审批记录：审批时间轴（环节、处理人、审核结果、审核意见、处理时间）

#底部按钮

-- 关闭：关闭抽屉

-- 去处理：仅审批中且当前用户为当前节点处理人时显示，跳转工单中心「二级页面：工单办理」

-- 已通过时展示关联入库单号、入库状态（只读）

#交互说明

-- 本功能为只读查看 / 跟踪，非审核办理页

### **水表退回申请-分仓**

#### 功能描述

用于分公司仓库管理员将需放回总仓的水表发起退回申请。支持按业务标签筛选水表一键纳入明细。审批通过后驱动分仓出库及总仓入库确认。

#### 菜单权限

表务分公司库管员；表务分公司管理人员；表务系统管理员

#### 数据权限

表务分公司库管员：可见、可操作本分公司及下属仓库范围内退回申请业务数据；「历史记录」Tab 仅展示当前登录账号作为发起人提交的退回申请工单。

表务分公司管理人员、表务系统管理员：可见全公司退回申请工单（管理人员只读不可发起时按角色配置）；库管员可发起、办理本分公司数据。

#### 核心逻辑

以退回申请单及关联工单为查询主体，明细关联待退回总仓水表。

支持按标签（如换表旧表、检定待返等）筛选后批量生成明细。

终审通过后在出库管理、入库管理办理，不在本菜单办理实物出入库。

#### 业务流程

流程概要

分公司库管员发起 → 分公司综合办主任一级审核 → 分公司分管领导二级审核 → 水表管理中心主任/副主任终审 → 抄送总公司库管员；通过后办理分仓出库及总仓入库确认。

环节说明表

| 序号 | 环节名称 | 环节类型 | 责任岗位 | 须填写 / 处理内容 | 审核结果选项 | 通过后流向 | 驳回 / 其他结果流向 | 抄送 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 水表退回申请发起 | 发起 | 表务分公司库管员 | 填报退回申请及待退回总仓水表明细（见「一级页面：水表退回申请-分仓-tab-工单发起」）；支持按标签筛选批量纳入明细 | 提交 | 退回申请一级审核 | — | — |
| 2 | 退回申请一级审核 | 审核 | 表务分公司管理人员（综合办） | 核对退回水表数量、表号、标签及退回事由；填写审核意见 | 通过；驳回 | 退回申请二级审核 | 退回水表退回申请发起 | — |
| 3 | 退回申请二级审核 | 审核 | 表务分公司领导班子 | 复核旧表退回整体业务及移送方案；填写审核意见 | 通过；驳回 | 退回申请终审 | 退回退回申请一级审核 | — |
| 4 | 退回申请终审 | 审核 | 表务水表管理中心 | 最终审定退回申请及明细；填写审核意见 | 通过；驳回 | 流程通过（系统自动处理） | 退回退回申请二级审核 | 表务水表管理中心；表务总公司库管员（知会） |
| 5 | 出库与总仓入库衔接 | 系统自动 | 系统 | 驱动分仓出库登记及总仓入库待确认 | — | 流程完结 | — | — |

审核通过后数据影响

- 生成/更新水表退回申请记录及关联工单，工单状态为「已通过」。

- 驱动「出库管理」可办理关联退回单的出库；驱动总仓「入库管理」待入库确认。

- 旧表实物移送检定中心等后续环节按《PRD-03》旧表流转规则，在入库/检定模块衔接。

关联界面逻辑闭环

- 发起侧：历史 Tab/详情展示工单状态、出库状态、总仓入库状态。

- 办理侧：「去处理」条件与工单中心一致。

- 出库/入库侧：详情只读展示下游状态，办理入口在出库管理、入库管理。

- 跨菜单：出库状态、入库状态与各模块列表文案一致。

审核界面说明

- 标准界面：复用工单中心「二级页面：工单办理」。

- 本业务差异：审核环节只读展示完整退回明细；终审通过后详情展示出库/入库衔接状态。

#### 功能需求

##### **一级页面：水表退回申请-分仓-tab-工单发起**

#整体布局

-- 菜单入口：Tab 页结构；Tab 列表：工单发起（本 Tab，默认选中）、历史记录（见「一级页面：水表退回申请-分仓-tab-历史记录」）

-- 本 Tab 内容：申请表单区 + 业务明细表格（如有）；底部常驻「提交」「重置」

#信息展示

-- 申请基础信息区

-- 申请部门：只读，默认当前用户所属部门

-- 申请人：只读，默认当前登录用户

-- 申请日期：只读，默认当前日期

-- 退回标签筛选：选填，下拉/多选（按系统配置的标签类型筛选待退回水表）

-- 退回事由：必填，下拉单选

-- 备注：选填，多行文本

-- 退回水表明细区：表格，支持从标签筛选结果批量加入、手工增删行

-- 水表编号、水表口径、水表类型、数量：同退库明细规则

#底部按钮

-- 提交：校验必填项及明细规则后提交，进入审批流程

-- 重置：清空表单；有已填内容时二次确认

#交互说明

-- 提交成功后提示「提交成功」，自动切换至 Tab「历史记录」并刷新列表

-- Tab 切换时保留未提交内容；刷新页面后未提交内容不保留

##### **一级页面：水表退回申请-分仓-tab-历史记录**

#整体布局

-- 菜单入口 Tab「历史记录」；上下结构：查询条件区 + 历史工单列表

-- 数据范围：仅当前登录账号作为发起人提交的水表退回申请-分仓工单

#查询条件

-- 工单编号：文本，支持模糊搜索

-- 申请单号：文本，支持模糊搜索

-- 工单状态：下拉单选（全部、审批中、已通过、已驳回、已撤销）

-- 申请日期：日期范围选择

-- 功能按钮：查询、重置

#数据列表

-- 表格标题：我的水表退回申请-分仓

-- 表格字段：工单编号、申请单号、申请日期、退、回、事、由、、、明、细、数、量、当前节点、工单状态、提交时间

-- 行内操作：详情

#交互说明

-- 点击工单编号、行内「详情」或列表行，打开「弹窗：水表退回申请-分仓工单详情」

-- 列表按提交时间倒序，支持分页

##### **弹窗：水表退回申请-分仓工单详情**

#弹窗类型

-- 抽屉弹窗（右侧滑出）；遮罩：有；主页面：不可操作

#整体布局

-- 宽度约 960px；全高；内部分 Tab：申请信息 / 退回明细

#弹窗标题

-- 水表退回申请-分仓详情 - {工单编号}

#标题栏操作

-- 关闭（×）：关闭抽屉，返回当前 Tab 列表

#信息展示

-- Tab·申请信息：只读展示对应申请及业务信息

-- Tab·退回明细：只读展示对应申请及业务信息

-- Tab·审批记录：审批时间轴（环节、处理人、审核结果、审核意见、处理时间）

#底部按钮

-- 关闭：关闭抽屉

-- 去处理：仅审批中且当前用户为当前节点处理人时显示，跳转工单中心「二级页面：工单办理」

-- 已通过时展示关联出库单号、总仓入库状态（只读）

#交互说明

-- 本功能为只读查看 / 跟踪，非审核办理页

---

## 详细设计（研发）

> 以下内容合并自 `design/功能设计/`，与 PRD 需求章节配套使用。数据模型详见 `design/数据库设计-V1.0.md`。

### 仪陇表务-功能设计-13-退库管理-V1.0

# 仪陇表务 — 功能设计 13 退库管理 V1.0

> 需求来源：`../demand/功能需求说明/仪陇表务管理系统-PRD-04-功能需求说明-13-*.md`  
> 数据模型：见 [数据库设计-V1.0.md](../数据库设计-V1.0.md)  
> 接口约定：见本文 **§接口设计（研发）**、[仪陇表务-公共接口说明-V1.0.md](./仪陇表务-公共接口说明-V1.0.md)、[00-总体框架设计-V1.0.md](../../design/00-总体框架设计-V1.0.md)

## 1. 模块概述

| 项 | 说明 |
|----|------|
| 模块序号 | 13 |
| 模块名称 | 退库管理 |
| 后端包（建议） | `com.tofly.wm.manage.return` |
| 业务模式 | 申请工单 |
| 工单 | RETURN_STATION_APPLY / RETURN_HQ_APPLY |

## 2. 功能范围

- 水表退库申请
- 退回总仓申请

## 3. 数据模型

### 3.1 涉及表

- `wssmet_retstnapply_w`
- `wssmet_retstnapplymeter_w`
- `wssmet_rethqapply_w`
- `wssmet_rethqapplymeter_w`

### 3.2 实体约定

- 所有实体 `extends BaseEntity`；逻辑删除 `Boolean deleted` ↔ `deleted`。
- 字典 `DictEntry` + `@DictDirectory(MeterConstant.*)` ↔ 库列 `VARCHAR2`；组织/用户 `OrganizationEntry`/`UserNameEntry` ↔ 库列 `NUMBER(19)`；附件 `FileEntryList`/`FileEntry` 用 `@TableField(exist = false)`，**无库列**。
- 申请类主表含 `process_instance_id / work_order_code / approve_status`；工单反查 `（无本地表，见 workflow）.TABLE_NAME` + `TABLE_ID`。

## 4. 业务流程

营业所退库→分仓入库；分仓退总仓→出库+总仓确认入库。

## 5. 核心业务规则

- 多级审批
- 标签筛选(退回总仓)

## 6. 接口设计（概要）

| 方法 | 路径（示例前缀） | 说明 |
|------|------------------|------|
| — | `/returnStationApply/` | 见 PRD 界面 |
| — | `/returnHqApply/` | 见 PRD 界面 |

- 标准 CRUD 另含：`GET /page`、`GET /list`、`POST /update`、`DELETE /{id}`、`DELETE /deleteByIds`。
- 返回体：须为带**具体**泛型的 `ResultResponse<...>`，见下文 §接口设计（研发）各接口出参（**禁止** `T`/`Vo` 占位）。

## 7. 权限与数据范围

遵循 PRD-02：菜单角色 + 组织数据权限 + 工单岗位权限；具体角色见 PRD-04 各功能「菜单权限」「数据权限」章节。

## 8. 上下游依赖

| 上游 | 下游 |
|------|------|
| 见 PRD-03 流程说明 | 见 PRD-01 总体主流程 |

---

*本设计仅依据 `../demand/` PRD 与 [数据库设计-V1.0.md](../数据库设计-V1.0.md)；实现时遵循 `java6/java-ylsw-bw.md` 与 `database-design.mdc`（`wssmet_*` 表名），**不参照**存量业务表与接口。*



---

## 接口设计（研发）

> 统一前缀：`/api/wm/manage/return`；各接口 **出参** 须为具体泛型（见下文，**禁止** `T`/`Vo` 占位）；公共约定见 [仪陇表务-公共接口说明-V1.0.md](./仪陇表务-公共接口说明-V1.0.md)。

#### 营业所退库申请-分页查询

| 项 | 内容 |
|----|------|
| 接口说明 | 分页查询营业所退库申请 |
| 请求地址 | `GET /api/wm/manage/return/returnStationApply/page` |
| 请求类型 | GET |

**入参（Query（PageQuery））**

| 字段 | 类型 | 说明 |
|------|------|------|
| applyCode | String | 申请编号 |
| returnReasonCode | String（字典 code） | 退回原因编号 |
| projectName | String | 项目 |
| inboundStatusCode | String（枚举 code） | 入库状态 |
| remark | String | 备注 |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |

**出参**

- ResultResponse<PageInfo<ReturnStationApplyVo>>

> 外层包装 ResultResponse 含 code、message、data，见 [公共接口说明](./仪陇表务-公共接口说明-V1.0.md) §1.3。

**data（PageInfo）字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| pageNum | Integer | 当前页码 |
| pageSize | Integer | 每页条数 |
| total | Long | 总记录数 |
| pages | Integer | 总页数 |
| list | List<ReturnStationApplyVo> | 当前页数据列表 |

**`ReturnStationApplyVo` 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |
| applyCode | String | 申请 |
| returnReasonCode | String（字典 code） | 退回原因 |
| projectName | String | 项目 |
| inboundStatusCode | String（枚举 code） | 入库状态 |
| inboundId | Long | 入库主单ID，关联wssmet_invin_w表的id字段 |
| remark | String | 备注 |
| processInstanceId | Long | workflow 流程实例ID（工单中心外挂，不落本地工单表） |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |
#### 营业所退库申请-列表查询

| 项 | 内容 |
|----|------|
| 接口说明 | 列表查询营业所退库申请 |
| 请求地址 | `GET /api/wm/manage/return/returnStationApply/list` |
| 请求类型 | GET |

**入参（Query）**

| 字段 | 类型 | 说明 |
|------|------|------|
| applyCode | String | 申请编号 |
| returnReasonCode | String（字典 code） | 退回原因编号 |
| projectName | String | 项目 |
| inboundStatusCode | String（枚举 code） | 入库状态 |
| remark | String | 备注 |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |

**出参**

- ResultResponse<List<ReturnStationApplyVo>>

> 外层包装 ResultResponse 含 code、message、data，见 [公共接口说明](./仪陇表务-公共接口说明-V1.0.md) §1.3。

**data（List<ReturnStationApplyVo>）元素字段**

**`ReturnStationApplyVo` 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |
| applyCode | String | 申请 |
| returnReasonCode | String（字典 code） | 退回原因 |
| projectName | String | 项目 |
| inboundStatusCode | String（枚举 code） | 入库状态 |
| inboundId | Long | 入库主单ID，关联wssmet_invin_w表的id字段 |
| remark | String | 备注 |
| processInstanceId | Long | workflow 流程实例ID（工单中心外挂，不落本地工单表） |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |
#### 营业所退库申请-详情

| 项 | 内容 |
|----|------|
| 接口说明 | 查询营业所退库申请详情 |
| 请求地址 | `GET /api/wm/manage/return/returnStationApply/{id}` |
| 请求类型 | GET |

**入参（Path: id）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |

**出参**

- ResultResponse<ReturnStationApplyVo>（含明细 list 若适用）

> 外层包装 ResultResponse 含 code、message、data，见 [公共接口说明](./仪陇表务-公共接口说明-V1.0.md) §1.3。

**data（ReturnStationApplyVo）字段**

**`ReturnStationApplyVo` 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |
| applyCode | String | 申请 |
| returnReasonCode | String（字典 code） | 退回原因 |
| projectName | String | 项目 |
| inboundStatusCode | String（枚举 code） | 入库状态 |
| inboundId | Long | 入库主单ID，关联wssmet_invin_w表的id字段 |
| remark | String | 备注 |
| processInstanceId | Long | workflow 流程实例ID（工单中心外挂，不落本地工单表） |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |

#### 营业所退库申请-新增

| 项 | 内容 |
|----|------|
| 接口说明 | 新增营业所退库申请；提交时同步发起 workflow，回写 process_instance_id / work_order_code / approve_status |
| 请求地址 | `POST /api/wm/manage/return/returnStationApply/` |
| 请求类型 | POST |

**入参（Body: Dto）**

| 字段 | 类型 | 说明 |
|------|------|------|
| applyCode | String | 申请编号 |
| returnReasonCode | String（字典 code） | 退回原因编号 |
| projectName | String | 项目 |
| inboundStatusCode | String（枚举 code） | 入库状态 |
| inboundId | Long | 入库主单ID，关联wssmet_invin_w表的id字段 |
| remark | String | 备注 |
| processInstanceId | Long | workflow 流程实例ID（工单中心外挂，不落本地工单表） |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |

**出参**

- ResultResponse<Long>

**data 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 新增记录主键 |
#### 营业所退库申请-修改

| 项 | 内容 |
|----|------|
| 接口说明 | 修改营业所退库申请 |
| 请求地址 | `POST /api/wm/manage/return/returnStationApply/update` |
| 请求类型 | POST |

**入参（Body: Dto（含 id））**

| 字段 | 类型 | 说明 |
|------|------|------|
| applyCode | String | 申请编号 |
| returnReasonCode | String（字典 code） | 退回原因编号 |
| projectName | String | 项目 |
| inboundStatusCode | String（枚举 code） | 入库状态 |
| inboundId | Long | 入库主单ID，关联wssmet_invin_w表的id字段 |
| remark | String | 备注 |
| processInstanceId | Long | workflow 流程实例ID（工单中心外挂，不落本地工单表） |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |

**出参**

- ResultResponse<Void>

**data** 无业务字段（null）。
#### 营业所退库申请-删除

| 项 | 内容 |
|----|------|
| 接口说明 | 逻辑删除营业所退库申请（支持批量） |
| 请求地址 | `DELETE /api/wm/manage/return/returnStationApply/deleteByIds?ids=1,2` |
| 请求类型 | DELETE |

**入参（Query: ids）**

| 字段 | 类型 | 说明 |
|------|------|------|
| ids | String | 主键，逗号分隔 |

**出参**

- ResultResponse<Void>

**data** 无业务字段（null）。
#### 退回总仓申请-分页查询

| 项 | 内容 |
|----|------|
| 接口说明 | 分页查询退回总仓申请 |
| 请求地址 | `GET /api/wm/manage/return/returnHqApply/page` |
| 请求类型 | GET |

**入参（Query（PageQuery））**

| 字段 | 类型 | 说明 |
|------|------|------|
| applyCode | String | 申请编号 |
| tagFilter | String | 标签筛选 |
| returnReasonCode | String（字典 code） | 退回原因编号 |
| outStatusCode | String（枚举 code） | 出库状态 |
| hqInStatusCode | String（枚举 code） | 总仓入库状态 |
| remark | String | 备注 |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |

**出参**

- ResultResponse<PageInfo<ReturnHqApplyVo>>

> 外层包装 ResultResponse 含 code、message、data，见 [公共接口说明](./仪陇表务-公共接口说明-V1.0.md) §1.3。

**data（PageInfo）字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| pageNum | Integer | 当前页码 |
| pageSize | Integer | 每页条数 |
| total | Long | 总记录数 |
| pages | Integer | 总页数 |
| list | List<ReturnHqApplyVo> | 当前页数据列表 |

**`ReturnHqApplyVo` 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |
| applyCode | String | 申请 |
| tagFilter | String | 标签筛选 |
| returnReasonCode | String（字典 code） | 退回原因 |
| outStatusCode | String（枚举 code） | 出库状态 |
| hqInStatusCode | String（枚举 code） | 总仓入库状态 |
| outId | Long | 出库主单ID，关联wssmet_invout_w表的id字段 |
| confirmId | Long | 总仓入库确认ID，关联wssmet_invconfirm_w表的id字段 |
| remark | String | 备注 |
| processInstanceId | Long | workflow 流程实例ID（工单中心外挂，不落本地工单表） |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |
#### 退回总仓申请-列表查询

| 项 | 内容 |
|----|------|
| 接口说明 | 列表查询退回总仓申请 |
| 请求地址 | `GET /api/wm/manage/return/returnHqApply/list` |
| 请求类型 | GET |

**入参（Query）**

| 字段 | 类型 | 说明 |
|------|------|------|
| applyCode | String | 申请编号 |
| tagFilter | String | 标签筛选 |
| returnReasonCode | String（字典 code） | 退回原因编号 |
| outStatusCode | String（枚举 code） | 出库状态 |
| hqInStatusCode | String（枚举 code） | 总仓入库状态 |
| remark | String | 备注 |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |

**出参**

- ResultResponse<List<ReturnHqApplyVo>>

> 外层包装 ResultResponse 含 code、message、data，见 [公共接口说明](./仪陇表务-公共接口说明-V1.0.md) §1.3。

**data（List<ReturnHqApplyVo>）元素字段**

**`ReturnHqApplyVo` 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |
| applyCode | String | 申请 |
| tagFilter | String | 标签筛选 |
| returnReasonCode | String（字典 code） | 退回原因 |
| outStatusCode | String（枚举 code） | 出库状态 |
| hqInStatusCode | String（枚举 code） | 总仓入库状态 |
| outId | Long | 出库主单ID，关联wssmet_invout_w表的id字段 |
| confirmId | Long | 总仓入库确认ID，关联wssmet_invconfirm_w表的id字段 |
| remark | String | 备注 |
| processInstanceId | Long | workflow 流程实例ID（工单中心外挂，不落本地工单表） |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |
#### 退回总仓申请-详情

| 项 | 内容 |
|----|------|
| 接口说明 | 查询退回总仓申请详情 |
| 请求地址 | `GET /api/wm/manage/return/returnHqApply/{id}` |
| 请求类型 | GET |

**入参（Path: id）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |

**出参**

- ResultResponse<ReturnHqApplyVo>（含明细 list 若适用）

> 外层包装 ResultResponse 含 code、message、data，见 [公共接口说明](./仪陇表务-公共接口说明-V1.0.md) §1.3。

**data（ReturnHqApplyVo）字段**

**`ReturnHqApplyVo` 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |
| applyCode | String | 申请 |
| tagFilter | String | 标签筛选 |
| returnReasonCode | String（字典 code） | 退回原因 |
| outStatusCode | String（枚举 code） | 出库状态 |
| hqInStatusCode | String（枚举 code） | 总仓入库状态 |
| outId | Long | 出库主单ID，关联wssmet_invout_w表的id字段 |
| confirmId | Long | 总仓入库确认ID，关联wssmet_invconfirm_w表的id字段 |
| remark | String | 备注 |
| processInstanceId | Long | workflow 流程实例ID（工单中心外挂，不落本地工单表） |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |

#### 退回总仓申请-新增

| 项 | 内容 |
|----|------|
| 接口说明 | 新增退回总仓申请；提交时同步发起 workflow，回写 process_instance_id / work_order_code / approve_status |
| 请求地址 | `POST /api/wm/manage/return/returnHqApply/` |
| 请求类型 | POST |

**入参（Body: Dto）**

| 字段 | 类型 | 说明 |
|------|------|------|
| applyCode | String | 申请编号 |
| tagFilter | String | 标签筛选 |
| returnReasonCode | String（字典 code） | 退回原因编号 |
| outStatusCode | String（枚举 code） | 出库状态 |
| hqInStatusCode | String（枚举 code） | 总仓入库状态 |
| outId | Long | 出库主单ID，关联wssmet_invout_w表的id字段 |
| confirmId | Long | 总仓入库确认ID，关联wssmet_invconfirm_w表的id字段 |
| remark | String | 备注 |
| processInstanceId | Long | workflow 流程实例ID（工单中心外挂，不落本地工单表） |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |

**出参**

- ResultResponse<Long>

**data 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 新增记录主键 |
#### 退回总仓申请-修改

| 项 | 内容 |
|----|------|
| 接口说明 | 修改退回总仓申请 |
| 请求地址 | `POST /api/wm/manage/return/returnHqApply/update` |
| 请求类型 | POST |

**入参（Body: Dto（含 id））**

| 字段 | 类型 | 说明 |
|------|------|------|
| applyCode | String | 申请编号 |
| tagFilter | String | 标签筛选 |
| returnReasonCode | String（字典 code） | 退回原因编号 |
| outStatusCode | String（枚举 code） | 出库状态 |
| hqInStatusCode | String（枚举 code） | 总仓入库状态 |
| outId | Long | 出库主单ID，关联wssmet_invout_w表的id字段 |
| confirmId | Long | 总仓入库确认ID，关联wssmet_invconfirm_w表的id字段 |
| remark | String | 备注 |
| processInstanceId | Long | workflow 流程实例ID（工单中心外挂，不落本地工单表） |
| workOrderCode | String | 工单编号（展示/台账查询） |
| approveStatus | String（枚举 code） | 审批状态 |

**出参**

- ResultResponse<Void>

**data** 无业务字段（null）。
#### 退回总仓申请-删除

| 项 | 内容 |
|----|------|
| 接口说明 | 逻辑删除退回总仓申请（支持批量） |
| 请求地址 | `DELETE /api/wm/manage/return/returnHqApply/deleteByIds?ids=1,2` |
| 请求类型 | DELETE |

**入参（Query: ids）**

| 字段 | 类型 | 说明 |
|------|------|------|
| ids | String | 主键，逗号分隔 |

**出参**

- ResultResponse<Void>

**data** 无业务字段（null）。