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


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

文档版本：V1.0

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

模块序号：19

模块名称：轮换管理

## 轮换管理

本模块覆盖水表到期强制轮换提醒、轮换任务创建分派及现场执行全链路，对应《PRD-01》轮换管理能力。含 Web 菜单：到期轮换水表提醒、到期轮换任务；App 菜单：到期轮换任务执行。轮换周期依据配置管理「周期设置」中轮换周期规则（如首次检定合格起满 6 年须强制轮换）。

### **到期轮换水表提醒**

#### 功能描述

按强制轮换周期自动筛选即将到期水表并生成清单，提供到期预警查看能力，支持营业办/供水站人员提前安排轮换计划，实现到期轮换前置预警与计划提前安排。

#### 菜单权限

表务营业办/供水站管理人员；表务分公司管理人员；表务总公司管理人员；表务水表管理中心；表务系统管理员

#### 数据权限

表务营业办/供水站管理人员：可见、可操作本营业办/供水站及管辖范围内到期轮换预警数据。

表务分公司管理人员：可见、可操作本分公司及下属营业办、供水站范围内数据。

表务总公司管理人员、表务水表管理中心：可见全公司范围内到期轮换预警数据。

表务系统管理员：可见、可操作全公司范围内到期轮换预警数据。

#### 核心逻辑

系统每日依据周期设置中轮换周期及水表首次检定合格日期计算轮换到期日。

清单仅作预警与任务创建入口，不直接变更水表状态。

从清单创建的任务在「到期轮换任务」菜单管理。

#### 功能需求

##### **一级页面：到期轮换水表提醒**

#整体布局

-- 布局骨架：上下结构；上区查询条件，下区到期水表清单；上区联动下区

-- 页面右上角「批量创建轮换任务」按钮（选中水表后可用）

#查询条件

-- 所属分公司：下拉单选，总公司可选全部，分公司默认本分公司

-- 营业办/供水站：下拉单选，依赖分公司

-- 用户编号、用户名称、水表表号：文本，支持模糊搜索

-- 水表口径、水表类型：下拉单选

-- 到期状态：下拉（全部、已到期、30天内到期、90天内到期）

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

#数据列表

-- 表格标题：到期轮换水表清单

-- 表格字段：序号、用户编号、用户名称、水表表号、出厂编号、水表口径、水表类型、安装地址、首次检定日期、轮换到期日、距到期天数、所属营业办/供水站

-- 行内操作：创建任务（单只）；支持多选批量创建

-- 基础功能：分页、导出

#交互说明

-- 系统每日按轮换周期规则自动刷新清单

-- 距到期天数 ≤ 0 标红展示「已到期」

-- 选中水表后点击「批量创建轮换任务」打开「弹窗：新建到期轮换任务」并带入已选水表

-- 仅展示所属机构属于当前用户所属部门及管辖部门的水表

### **到期轮换任务**

#### 功能描述

承载到期轮换任务创建、派单与进度跟踪，提供任务明细管理及执行人指定能力，支持由到期提醒直接创建任务或管理人员直接派单，实现轮换任务规范化管理。

#### 菜单权限

表务营业办/供水站管理人员；表务分公司管理人员；表务总公司管理人员；表务水表管理中心；表务系统管理员

#### 数据权限

表务营业办/供水站管理人员：可见、可操作本营业办/供水站范围内轮换任务；可新建、派单。

表务分公司管理人员：可见、可操作本分公司及下属机构范围内轮换任务。

表务营业办/供水站职员（抄表员）：可见本机构任务进度（只读，不可新建）。

表务总公司管理人员、表务水表管理中心：可见全公司轮换任务（只读）。

表务系统管理员：可见、可操作全公司轮换任务。

#### 核心逻辑

以轮换任务为查询主体，关联轮换任务水表明细。

任务创建后直接下发 App，不经工单审批（与到期检定任务模式一致）。

现场执行在 App「到期轮换任务执行」办理；旧表退返分公司走退库管理。

#### 功能需求

##### **一级页面：到期轮换任务**

#整体布局

-- 上下结构：查询条件 + 任务列表；右上角「新建任务」

#查询条件

-- 所属分公司、营业办/供水站、任务编号、任务名称、任务状态（待执行/执行中/已完成/已关闭）

-- 执行人、创建日期范围；查询、重置

#数据列表

-- 表格标题：到期轮换任务列表

-- 表格字段：任务编号、任务名称、所属营业办/供水站、轮换水表数、已完成数、执行人、任务状态、创建人、创建时间

-- 行内操作：详情；编辑（待执行）；分配人员；关闭

#交互说明

-- 可从「到期轮换水表提醒」带入水表创建任务，亦可本菜单直接新建

-- 任务执行流程：抄表员领用新表 → 现场拆旧装新 → 旧表返回营业办/供水站

-- 旧表需返回分公司时，由营业办/供水站通过「退库管理」提交退库工单（见原始 PRD 备注）

-- 点击「详情」打开「弹窗：到期轮换任务详情」

##### **弹窗：新建到期轮换任务**

#弹窗类型

-- 居中模态弹窗，宽度约 960px；遮罩：有

#信息展示

-- 任务名称：必填，文本

-- 所属营业办/供水站：必填，下拉

-- 执行人：必填，下拉（本机构抄表员）

-- 计划完成日期：必填，日期

-- 轮换水表明细：表格，至少 1 行（用户编号、水表表号、口径、类型）；可从提醒清单带入

-- 任务说明：选填

#底部按钮

-- 保存并下发：状态「待执行」，同步 App；取消

#交互说明

-- 保存后记录创建人、分派人、分派时间

##### **弹窗：到期轮换任务详情**

#弹窗类型

-- 抽屉弹窗（右侧），宽度约 1100px

#信息展示

-- 任务摘要：任务编号、名称、机构、执行人、状态、完成率

-- Tab·轮换明细：水表列表及每只表轮换状态（待执行/已完成）

-- Tab·操作日志：创建、下发、分配、关闭记录

#底部按钮

-- 分配人员；关闭任务；导出明细；关闭

#交互说明

-- App 完成单只表轮换后明细状态及完成率自动更新

### **到期轮换任务执行（App）**

#### 功能描述

面向抄表员移动端作业，提供轮换任务接收、现场拆表换表及执行状态登记能力，支持外勤完成到期轮换现场作业，实现轮换执行移动化与数据回传。

#### 菜单权限

表务营业办/供水站职员

#### 数据权限

表务营业办/供水站职员：仅可查看及操作执行人为本人的轮换任务及现场填报数据。

#### 核心逻辑

App 提交驱动单只水表轮换完成及任务进度回写；衔接新表安装与旧表退返。

#### 功能需求

##### **一级页面：到期轮换任务列表（App）**

#整体布局

-- 任务卡片列表；下拉刷新

#页面标题

-- 标题文案：轮换任务

#查询条件

-- 任务状态：全部 / 待执行 / 执行中 / 已完成

#信息展示

-- 卡片：任务编号、任务名称、轮换水表数、已完成数、计划完成日期、任务状态

#交互说明

-- 仅执行人为本人的任务；点击进入「二级页面：轮换任务详情（App）」

##### **二级页面：轮换任务详情（App）**

#页面标题

-- 标题文案：任务详情

#信息展示

-- 任务名称、计划完成日期、轮换水表明细列表（水表表号、用户名称、轮换状态）

#交互说明

-- 点击待轮换水表进入「三级页面：现场轮换填报（App）」

##### **三级页面：现场轮换填报（App）**

#信息展示

-- 旧水表表号：只读，支持扫码

-- 旧表拆除止码：必填

-- 新水表表号：必填，支持扫码（须为已领用出库状态）

-- 新表安装读数：必填

-- 旧表归集状态：必填，下拉（已归集营业办/供水站）

-- 现场照片：必填，至少 1 张

-- GPS：自动采集

-- 备注：选填

#底部按钮

-- 暂存；提交

#交互说明

-- 提交后该只水表轮换状态「已完成」；全部完成后任务「已完成」

-- 更新水表档案及轮换台账；旧表触发退库流转

-- 支持离线暂存

---

## 详细设计（研发）

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

### 仪陇表务-功能设计-19-轮换管理-V1.0

# 仪陇表务 — 功能设计 19 轮换管理 V1.0

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

## 1. 模块概述

| 项 | 说明 |
|----|------|
| 模块序号 | 19 |
| 模块名称 | 轮换管理 |
| 后端包（建议） | `com.tofly.wm.manage.rotate` |
| 业务模式 | 任务直办 |
| 工单 | 无 |

## 2. 功能范围

- 到期轮换提醒
- 轮换任务
- App 执行

## 3. 数据模型

### 3.1 涉及表

- `wssmet_rotatetask_w`
- `wssmet_rotatetaskmeter_w`
- `wssmet_rotaterec_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. 核心业务规则

- FIRST_VERIFY_DATE 为周期基准

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

| 方法 | 路径（示例前缀） | 说明 |
|------|------------------|------|
| — | `/rotateTask/` | 见 PRD 界面 |
| — | `/rotateReminder/list` | 见 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/rotate`；各接口 **出参** 须为具体泛型（见下文，**禁止** `T`/`Vo` 占位）；公共约定见 [仪陇表务-公共接口说明-V1.0.md](./仪陇表务-公共接口说明-V1.0.md)。

#### 到期轮换任务-分页查询

| 项 | 内容 |
|----|------|
| 接口说明 | 分页查询到期轮换任务 |
| 请求地址 | `GET /api/wm/manage/rotate/rotateTask/page` |
| 请求类型 | GET |

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

| 字段 | 类型 | 说明 |
|------|------|------|
| taskCode | String | 任务编号 |
| taskName | String | 任务 |
| planFinishDate | Date | 计划完成日期 |
| meterQty | Integer | 水表数量 |
| finishedQty | Integer | 数量 |
| taskStatusCode | String（枚举 code） | 任务状态 |
| taskDesc | String | 任务 |
| creatorName | String | 创建人 |
| dispatchTime | DateTime | 分派时间 |

**出参**

- ResultResponse<PageInfo<RotateTaskVo>>

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

**data（PageInfo）字段**

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

**`RotateTaskVo` 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |
| taskCode | String | 任务 |
| taskName | String | 任务 |
| orgId | Long | 组织ID，关联tf_org表的id字段 |
| executorId | Long | 执行人ID，关联tf_user表的id字段 |
| planFinishDate | Date | 计划完成日期 |
| meterQty | Integer | 水表数量 |
| finishedQty | Integer | 数量 |
| taskStatusCode | String（枚举 code） | 任务状态 |
| taskDesc | String | 任务 |
| creatorId | Long | 创建人ID，关联tf_user表的id字段 |
| creatorName | String | 创建人 |
| dispatchTime | DateTime | 分派时间 |
#### 到期轮换任务-列表查询

| 项 | 内容 |
|----|------|
| 接口说明 | 列表查询到期轮换任务 |
| 请求地址 | `GET /api/wm/manage/rotate/rotateTask/list` |
| 请求类型 | GET |

**入参（Query）**

| 字段 | 类型 | 说明 |
|------|------|------|
| taskCode | String | 任务编号 |
| taskName | String | 任务 |
| planFinishDate | Date | 计划完成日期 |
| meterQty | Integer | 水表数量 |
| finishedQty | Integer | 数量 |
| taskStatusCode | String（枚举 code） | 任务状态 |
| taskDesc | String | 任务 |
| creatorName | String | 创建人 |
| dispatchTime | DateTime | 分派时间 |

**出参**

- ResultResponse<List<RotateTaskVo>>

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

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

**`RotateTaskVo` 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |
| taskCode | String | 任务 |
| taskName | String | 任务 |
| orgId | Long | 组织ID，关联tf_org表的id字段 |
| executorId | Long | 执行人ID，关联tf_user表的id字段 |
| planFinishDate | Date | 计划完成日期 |
| meterQty | Integer | 水表数量 |
| finishedQty | Integer | 数量 |
| taskStatusCode | String（枚举 code） | 任务状态 |
| taskDesc | String | 任务 |
| creatorId | Long | 创建人ID，关联tf_user表的id字段 |
| creatorName | String | 创建人 |
| dispatchTime | DateTime | 分派时间 |
#### 到期轮换任务-详情

| 项 | 内容 |
|----|------|
| 接口说明 | 查询到期轮换任务详情 |
| 请求地址 | `GET /api/wm/manage/rotate/rotateTask/{id}` |
| 请求类型 | GET |

**入参（Path: id）**

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

**出参**

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

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

**data（RotateTaskVo）字段**

**`RotateTaskVo` 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 主键 |
| taskCode | String | 任务 |
| taskName | String | 任务 |
| orgId | Long | 组织ID，关联tf_org表的id字段 |
| executorId | Long | 执行人ID，关联tf_user表的id字段 |
| planFinishDate | Date | 计划完成日期 |
| meterQty | Integer | 水表数量 |
| finishedQty | Integer | 数量 |
| taskStatusCode | String（枚举 code） | 任务状态 |
| taskDesc | String | 任务 |
| creatorId | Long | 创建人ID，关联tf_user表的id字段 |
| creatorName | String | 创建人 |
| dispatchTime | DateTime | 分派时间 |

#### 到期轮换任务-新增

| 项 | 内容 |
|----|------|
| 接口说明 | 新增到期轮换任务 |
| 请求地址 | `POST /api/wm/manage/rotate/rotateTask/` |
| 请求类型 | POST |

**入参（Body: Dto）**

| 字段 | 类型 | 说明 |
|------|------|------|
| taskCode | String | 任务编号 |
| taskName | String | 任务 |
| orgId | Long | 组织ID，关联tf_org表的id字段 |
| executorId | Long | 执行人ID，关联tf_user表的id字段 |
| planFinishDate | Date | 计划完成日期 |
| meterQty | Integer | 水表数量 |
| finishedQty | Integer | 数量 |
| taskStatusCode | String（枚举 code） | 任务状态 |
| taskDesc | String | 任务 |
| creatorId | Long | 创建人ID，关联tf_user表的id字段 |
| creatorName | String | 创建人 |
| dispatchTime | DateTime | 分派时间 |

**出参**

- ResultResponse<Long>

**data 字段**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 新增记录主键 |
#### 到期轮换任务-修改

| 项 | 内容 |
|----|------|
| 接口说明 | 修改到期轮换任务 |
| 请求地址 | `POST /api/wm/manage/rotate/rotateTask/update` |
| 请求类型 | POST |

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

| 字段 | 类型 | 说明 |
|------|------|------|
| taskCode | String | 任务编号 |
| taskName | String | 任务 |
| orgId | Long | 组织ID，关联tf_org表的id字段 |
| executorId | Long | 执行人ID，关联tf_user表的id字段 |
| planFinishDate | Date | 计划完成日期 |
| meterQty | Integer | 水表数量 |
| finishedQty | Integer | 数量 |
| taskStatusCode | String（枚举 code） | 任务状态 |
| taskDesc | String | 任务 |
| creatorId | Long | 创建人ID，关联tf_user表的id字段 |
| creatorName | String | 创建人 |
| dispatchTime | DateTime | 分派时间 |

**出参**

- ResultResponse<Void>

**data** 无业务字段（null）。
#### 到期轮换任务-删除

| 项 | 内容 |
|----|------|
| 接口说明 | 逻辑删除到期轮换任务（支持批量） |
| 请求地址 | `DELETE /api/wm/manage/rotate/rotateTask/deleteByIds?ids=1,2` |
| 请求类型 | DELETE |

**入参（Query: ids）**

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

**出参**

- ResultResponse<Void>

**data** 无业务字段（null）。
#### 到期轮换提醒

| 项 | 内容 |
|----|------|
| 接口说明 | 分页到期轮换提醒 |
| 请求地址 | `GET /api/wm/manage/rotate/rotateTask/reminder` |
| 请求类型 | GET |

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

| 字段 | 类型 | 说明 |
|------|------|------|
| rotateDueDate | Date | 轮换到期日 |

**出参**

- ResultResponse<Void>

**data** 无业务字段（null）。
#### 轮换现场记录

| 项 | 内容 |
|----|------|
| 接口说明 | App 轮换执行登记 |
| 请求地址 | `POST /api/wm/manage/rotate/rotateRecord/` |
| 请求类型 | POST |

**入参（Body: Dto）**

| 字段 | 类型 | 说明 |
|------|------|------|
| taskMeterId | Long | 轮换任务水表明细ID，关联wssmet_rotatetaskmeter_w表的id字段 |
| oldMeterCode | String | 旧水表编号 |
| oldFinalReading | String | 旧最终读数 |
| newMeterCode | String | 新水表编号 |
| newInstallReading | String | 新安装读数 |
| oldCollectStatusCode | String（枚举 code） | 旧归集状态 |
| gpsLat | String | GPS纬度 |
| gpsLng | String | GPS经度 |
| remark | String | 备注 |

**出参**

- ResultResponse<Void>

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