ylsw-bw/business/water-meter/doc/demand/功能需求说明/仪陇表务-公共接口说明-V1.0.md

仪陇表务管理系统 — 公共接口说明 V1.0

各 PRD-04 模块专属接口见对应 功能需求说明 文档末尾 §接口设计（研发）；本文管理跨模块复用能力。

1. 通用约定

项	约定
统一前缀	/api/wm（以网关发布为准）
返回体	必须为具体泛型，如 ResultResponse<PageInfo<XxxVo>>、ResultResponse<Void>；禁止 ResultResponse<T>
分页	PageQuery：pageNum、pageSize；响应 PageInfo<T>
逻辑删除	查询默认 deleted=0
附件	请求/响应 FileEntry / FileEntryList；实体 @TableField(exist = false)，无库列
删除	禁止 DELETE /{id}；统一 DELETE /{resource}/deleteByIds?ids=1,2
入参命名	接口文档与 Java DTO/Query 驼峰（如 meterCode、applyDeptId）；库列为蛇形，仅实体 @TableField 映射
出参	各接口须写明完整泛型；对象类型须展开 data 内字段表（驼峰）；无数据时 ResultResponse<Void>

1.1 标准 CRUD 模板

接口名	接口说明	请求地址	请求类型
分页查询	分页列表	GET /{resource}/page	GET
列表查询	全量列表（同 Query）	GET /{resource}/list	GET
详情	按 id 查询	GET /{resource}/{id}	GET
新增	新增记录	POST /{resource}/	POST
修改	修改记录	POST /{resource}/update	POST
删除	逻辑删除（批量）	DELETE /{resource}/deleteByIds	DELETE

入参（分页 Query）：pageNum、pageSize + 各资源业务筛选字段（见模块文档）。

出参：各接口须写明完整泛型（如 ResultResponse<PageInfo<PurchaseApplyVo>>、ResultResponse<Long>、ResultResponse<Void>）。

1.2 台账只读模板

接口名	接口说明	请求地址	请求类型
分页查询	台账分页	GET /{resource}/page	GET
列表查询	台账列表	GET /{resource}/list	GET
详情	详情（可选）	GET /{resource}/{id}	GET
导出	导出 Excel	GET /{resource}/export	GET

1.3 ResultResponse 包装（所有接口通用）

字段	类型	说明
code	Integer	业务状态码
message	String	提示信息
data	T	业务数据；T 须为具体类型（见各接口出参下列字段表）

1.4 PageInfo 分页包装（data 为分页时）

2. 工单中心（workflow）

本模块无表务本地 CRUD 表；待办/已办/我发起/抄送/办理均调用平台 workflow API。表务可选 BFF 聚合：

字段	类型	说明
pageNum	Integer	当前页码
pageSize	Integer	每页条数
total	Long	总记录数
pages	Integer	总页数
list	List	当前页列表；list 元素字段见各接口 XxxVo 字段表

接口名	接口说明	请求地址	请求类型	入参	出参
待办分页	当前用户待办工单	GET /api/wm/workorder/todo/page	GET	PageQuery + 工单类型筛选	ResultResponse<PageInfo<WorkOrderVo>>
已办分页	已处理工单	GET /api/wm/workorder/done/page	GET	同上	同上
我发起分页	我发起的流程	GET /api/wm/workorder/started/page	GET	同上	同上
抄送分页	抄送我的工单	GET /api/wm/workorder/cc/page	GET	同上	同上
工单办理	提交审批意见	POST workflow 标准办理 URL	POST	节点 id、意见、附件等	workflow 约定
业务区只读	办理页展示业务单	各模块 GET /{apply}/{id}	GET	业务主键	各模块 Vo

审批通过后由 workflow 回调或事件同步业务表 approve_status、process_instance_id、work_order_code。

3. 平台复用接口（组织/用户/字典/文件）

接口名	接口说明	请求地址	请求类型
组织树	查询组织	平台 /api/org/tree	GET
用户列表	按组织查用户	平台 /api/user/list	GET
字典项	按目录码取字典	平台 /api/dict/items?code=	GET
文件上传	附件上传	平台文件服务	POST
文件下载	附件下载	平台文件服务	GET

字典目录码、业务枚举取值见 design/字典与枚举说明-V1.0.md。

4. 外部集成

接口名	接口说明	请求地址	请求类型	入参	出参
检定记录同步	测量系统推送检定结果	POST /api/wm/api/verify/sync	POST	检定记录 Dto（见 wssmet_verifyrecord_w）	ResultResponse<Void>
报装事件拉取	拉取报装待安装事件	GET /api/wm/api/bz/install	GET	时间范围 Query	ResultResponse<List<BzInstallEventVo>>
营销状态推送	向营销推送水表状态	POST /api/wm/api/yx/meter/sync	POST	水表状态 Dto	ResultResponse<Void>

---

与各 PRD-04 §接口设计（研发）、java6/java-ylsw-bw.md §接口文档生成 保持一致。