# 仪陇表务管理系统 — 接口文档 V2.0（需求驱动）

> **仅依据** `../demand/` PRD 与 [数据库设计-V1.0.md](./数据库设计-V1.0.md)（`wssmet_*` 表）；**不参照**存量 Controller/路径实现。  
> 路由风格参考 `java6/java-ylsw-bw.md`；统一前缀示例：`/api/wm`（以网关为准）。  
> 返回体：**`ResultResponse<T>`**；分页：**`PageQuery`**（`pageNum`/`pageSize`）。

## 1. 通用约定

| 项 | 约定 |
|----|------|
| 分页 | `GET /{resource}/page` |
| 列表 | `GET /{resource}/list`（与 page 同 Query，不分页） |
| 详情 | `GET /{resource}/{id}` |
| 新增 | `POST /{resource}/` |
| 修改 | `POST /{resource}/update` |
| 删除 | `DELETE /{resource}/{id}` |
| 批量删 | `DELETE /{resource}/deleteByIds?ids=1,2,3` |
| 导出 | `GET /{resource}/export`（台账类） |
| 附件 | 请求/响应字段类型 `FileEntryList` / `FileEntry` |
| 逻辑删除 | 查询默认 `deleted=0` |

## 2. 工单中心（workflow，无本地 CRUD 表）

| 能力 | 说明 |
|------|------|
| 待办/已办/我发起/抄送 | **workflow** 标准 API；表务可选 BFF：`GET /workorder/todo/page` 等转发 |
| 办理 | `POST` workflow 审批接口；成功后同步业务表 `approve_status` |
| 工单台账 | workflow 查询 + 业务表 `work_order_code` 关联展示 |

> 业务申请 `POST` 保存后 **发起流程**，回写 `process_instance_id` / `work_order_code`（见各 `*Apply` 接口）。

## 3. 水表台账 ` /ledger`

| 资源 | 路径前缀 | 说明 |
|------|----------|------|
| 水表查询 | `/ledger/meter` | 分页/详情/生命周期 |
| 采购台账 | `/ledger/purchase` | 计划+到货汇总 |
| 检定台账 | `/ledger/verify` | 多检定类型汇总 |
| 入库台账 | `/ledger/inventoryIn` | 总仓/分仓筛选 |
| 出库台账 | `/ledger/inventoryOut` | 总仓/分仓筛选 |
| 安装台账 | `/ledger/install` | |
| 换表台账 | `/ledger/replace` | |
| 周检台账 | `/ledger/inspect` | |
| 轮换台账 | `/ledger/rotate` | |
| 报废台账 | `/ledger/scrap` | |

## 4. 采购管理 ` /manage/purchase`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/purchaseApply/` | 提交采购申请并发起 workflow |
| GET | `/purchaseApply/page` | 历史记录 |
| GET | `/purchaseApply/{id}` | 详情（含明细、工单状态） |
| POST | `/purchasePlan/` | 新建/编辑计划 |
| GET | `/purchasePlan/page` | 计划列表 |
| POST | `/purchasePlan/arrive` | 到货登记（含附件） |
| GET | `/purchasePlan/{id}` | 计划详情 |

## 5. 落地检 ` /manage/verify/landing`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/landingVerify/` | 落地检登记 |
| POST | `/returnFactory/` | 不合格返厂 |
| POST | `/landingVerify/app/sealBind` | App 铅封绑定入库 |

## 6. 领取管理 ` /manage/claim`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/claimApply/` | 领用申请+工单 |
| GET | `/claimApply/page` | |
| POST | `/claimRegister/` | 领取登记 |
| GET | `/claimRegister/pending` | 待领取清单 |
| POST | `/claimRegister/app/inbound` | App 分仓入库 |

## 7. 调拨管理 ` /manage/transfer`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/transferApply/` | 调拨申请+工单 |
| GET | `/transferApply/stock` | 各分公司库存查询 |
| POST | `/transferOut/` | 调拨出库登记 |
| POST | `/transferIn/confirm` | 调拨入库确认 |

## 8. 到期检定 ` /manage/verify/expire`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/expireReminder/page` | 到期提醒清单 |
| POST | `/expireVerifyTask/` | 创建任务 |
| GET | `/expireVerifyTask/page` | 任务列表 |
| POST | `/expireVerifyTask/dispatch` | 派单 |
| POST | `/expireVerifyExec/` | App 执行回传 |

## 9. 争议检定 ` /manage/verify/dispute`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/disputeVerifyApply/` | 申请+工单 |
| GET | `/disputeVerifyTask/page` | 任务列表 |
| POST | `/disputeVerifyExec/` | App 执行节点登记 |

## 10. 其他检定 & 检定记录

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/otherVerify/` | 其他检定登记 |
| GET | `/verifyRecord/page` | 检定记录列表 |
| POST | `/verifyRecord/link` | 手工关联业务 |
| POST | `/verifyRecord/void` | 作废 |

## 11. 入库 / 出库 ` /manage/inventory`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/inventoryIn/` | 入库存单（总仓/分仓） |
| GET | `/inventoryIn/page` | |
| POST | `/inventoryConfirm/` | 总仓入库确认 |
| POST | `/stationReturnIn/` | 营业所退库入库登记 |
| POST | `/inventoryOut/` | 出库存单 |
| GET | `/inventoryOut/page` | |

**出库类型（PRD-01）**：总仓—分配/调拨/遗失/废表/返厂；分仓—安装/换表/调拨/遗失/返回总仓。

## 12. 退库 ` /manage/return`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/returnStationApply/` | 营业所退库申请+工单 |
| POST | `/returnHqApply/` | 退回总仓申请+工单 |
| GET | `/returnHqApply/page` | |

## 13. 安装 / 换表 / 迁表 / 拆表（任务+App）

| 模块 | 路径前缀 | 关键接口 |
|------|----------|----------|
| 安装 | `/installTask` | POST `/` 派单；App POST `/record`、`/acceptance` |
| 换表 | `/replaceApply`、`/replaceTask` | 申请+任务+App `/replaceRecord` |
| 迁表 | `/relocateApply`、`/relocateTask` | 申请+App `/relocateRecord` |
| 拆表 | `/removeApply`、`/removeTask` | 申请+App `/removeRecord` |

## 14. 轮换 & 周期检查

| 模块 | 路径前缀 | 关键接口 |
|------|----------|----------|
| 轮换 | `/rotateTask` | GET `/reminder`；POST `/`；App `/rotateRecord` |
| 周期检查 | `/inspectConfig`、`/inspectTask` | 配置 CRUD；任务 CRUD；App `/inspectRecord` |

## 15. 报废 ` /manage/scrap`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/scrapApply/` | 报废申请+工单 |
| POST | `/scrapRegister/` | 报废登记/封存 |
| POST | `/scrapRegister/dispose` | 处置出库 |

## 16. 配置 ` /manage/config`

| 资源 | 路径 | 说明 |
|------|------|------|
| 仓库 | `/warehouse` | CRUD |
| 厂家 | `/brand` | CRUD |
| 型号 | `/brandModel` | CRUD |
| 周期规则 | `/cycleRule` | CRUD |
| 库存预警 | `/inventoryAlertRule` | 占位，暂不实现 |

## 17. 外部集成 ` /api`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/verify/sync` | 检定测量系统记录推送 |
| GET | `/api/bz/install` | 报装事件拉取 |
| POST | `/api/yx/meter/sync` | 营销表务状态推送 |

---

详细字段、校验规则以各 [功能设计](./功能设计/) 文档及 PRD-04 为准。