# 仪陇表务管理系统 — 接口文档 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.1 标准 CRUD/台账模板路径，**不因 PRD 未写或业务暂未实现而省略**（见 `java6` §接口文档生成）。

## 1. 通用约定

| 项 | 约定 |
|----|------|
| 分页 | `GET /{resource}/page` |
| 列表 | `GET /{resource}/list`（与 page 同 Query，不分页） |
| 详情 | `GET /{resource}/{id}` |
| 新增 | `POST /{resource}/` |
| 修改 | `POST /{resource}/update` |
| 删除 | `DELETE /{resource}/deleteByIds?ids=1,2,3`（**禁止** `DELETE /{resource}/{id}`） |
| 导出 | `GET /{resource}/export`（台账类） |
| 附件 | 请求/响应 `FileEntryList`/`FileEntry`；Entity **`@TableField(exist = false)`**，无库列 |
| 逻辑删除 | 查询默认 `deleted=0` |

## 1.1 标准接口模板（文档须全量列出）

### 标准 CRUD 资源（`manage` 主数据 / 可写业务表）

每个标准 CRUD 资源在模块章节中 **至少** 包含下表全部行（业务扩展接口另行列出）：

| 方法 | 路径 | 说明 |
|------|------|------| 
| GET | `/{resource}/page` | 分页查询 |
| GET | `/{resource}/list` | 列表查询（与 page 同 Query） |
| GET | `/{resource}/{id}` | 详情 |
| POST | `/{resource}/` | 新增 |
| POST | `/{resource}/update` | 修改 |
| DELETE | `/{resource}/deleteByIds` | 删除（逗号分隔主键；单条传 `ids=1`） |

### 台账只读资源（`ledger`）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/{resource}/page` | 分页 |
| GET | `/{resource}/list` | 列表（若适用） |
| GET | `/{resource}/{id}` | 详情（若适用） |
| GET | `/{resource}/export` | 导出 |

> 台账类 **不提供** `POST`/`update`/`deleteByIds` 时，在模块说明中标注「台账只读」即可，但仍须列出上表只读模板行。

## 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`

> 下列资源均为 **台账只读**，各资源须全量列出 §1.1「台账只读资源」模板行（`page`/`list`/`export` 等）；下表仅列路径前缀，接口明细按模板展开。

| 资源 | 路径前缀 | 模板接口（须全量列出） |
|------|----------|------------------------|
| 水表查询 | `/ledger/meter` | `GET /page`、`GET /list`、`GET /{id}`、`GET /export` |
| 采购台账 | `/ledger/purchase` | `GET /page`、`GET /export` |
| 检定台账 | `/ledger/verify` | `GET /page`、`GET /export` |
| 入库台账 | `/ledger/inventoryIn` | `GET /page`、`GET /export` |
| 出库台账 | `/ledger/inventoryOut` | `GET /page`、`GET /export` |
| 安装台账 | `/ledger/install` | `GET /page`、`GET /export` |
| 换表台账 | `/ledger/replace` | `GET /page`、`GET /export` |
| 周检台账 | `/ledger/inspect` | `GET /page`、`GET /export` |
| 轮换台账 | `/ledger/rotate` | `GET /page`、`GET /export` |
| 报废台账 | `/ledger/scrap` | `GET /page`、`GET /export` |

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

### 采购申请 `/purchaseApply`（标准 CRUD + 工单）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/purchaseApply/page` | 分页 |
| GET | `/purchaseApply/list` | 列表 |
| GET | `/purchaseApply/{id}` | 详情（含明细、工单状态） |
| POST | `/purchaseApply/` | 新增；提交并发起 workflow |
| POST | `/purchaseApply/update` | 修改 |
| DELETE | `/purchaseApply/deleteByIds` | 删除 |

### 采购计划 `/purchasePlan`（标准 CRUD + 业务）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/purchasePlan/page` | 分页 |
| GET | `/purchasePlan/list` | 列表 |
| GET | `/purchasePlan/{id}` | 计划详情 |
| POST | `/purchasePlan/` | 新建/编辑计划 |
| POST | `/purchasePlan/update` | 修改 |
| DELETE | `/purchasePlan/deleteByIds` | 删除 |
| POST | `/purchasePlan/arrive` | 到货登记（含附件，业务扩展） |

## 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`

以下资源均为 **标准 CRUD**，各资源须 **全量列出** §1.1 模板接口（路径前缀见「路径前缀」列）。

### 仓库 `/warehouse`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/warehouse/page` | 分页 |
| GET | `/warehouse/list` | 列表 |
| GET | `/warehouse/{id}` | 详情 |
| POST | `/warehouse/` | 新增 |
| POST | `/warehouse/update` | 修改 |
| DELETE | `/warehouse/deleteByIds` | 删除 |

### 厂家 `/brand`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/brand/page` | 分页 |
| GET | `/brand/list` | 列表 |
| GET | `/brand/{id}` | 详情 |
| POST | `/brand/` | 新增 |
| POST | `/brand/update` | 修改 |
| DELETE | `/brand/deleteByIds` | 删除 |

### 型号 `/brandModel`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/brandModel/page` | 分页 |
| GET | `/brandModel/list` | 列表 |
| GET | `/brandModel/{id}` | 详情 |
| POST | `/brandModel/` | 新增 |
| POST | `/brandModel/update` | 修改 |
| DELETE | `/brandModel/deleteByIds` | 删除 |

### 周期规则 `/cycleRule`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/cycleRule/page` | 分页 |
| GET | `/cycleRule/list` | 列表 |
| GET | `/cycleRule/{id}` | 详情 |
| POST | `/cycleRule/` | 新增 |
| POST | `/cycleRule/update` | 修改 |
| DELETE | `/cycleRule/deleteByIds` | 删除 |

### 库存预警 `/inventoryAlertRule`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/inventoryAlertRule/page` | 分页（占位，暂不实现） |
| GET | `/inventoryAlertRule/list` | 列表（占位） |
| GET | `/inventoryAlertRule/{id}` | 详情（占位） |
| POST | `/inventoryAlertRule/` | 新增（占位） |
| POST | `/inventoryAlertRule/update` | 修改（占位） |
| DELETE | `/inventoryAlertRule/deleteByIds` | 删除（占位） |

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

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

---

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