ylsw-bw/business/water-meter/doc/design/接口文档-V1.0.md

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

仅依据 ../demand/ PRD 与 数据库设计-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 为准。