# 仪陇表务管理系统 — 公共接口说明 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 为分页时）

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

## 2. 工单中心（workflow）

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

| 接口名 | 接口说明 | 请求地址 | 请求类型 | 入参 | 出参 |
|--------|----------|----------|----------|------|------|
| 待办分页 | 当前用户待办工单 | `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` §接口文档生成 保持一致。*