# APP 端 — 园林工单创建接口

> **接口路径**：`POST /app-api/bpm/garden/workorder/create`
>
> **版本**：v1.0
>
> **最后更新**：2026-06-07

---

## 1. 接口概述

| 属性 | 说明 |
|------|------|
| **接口名称** | APP 端创建园林工单 |
| **请求方式** | `POST` |
| **完整路径** | `/app-api/bpm/garden/workorder/create` |
| **认证方式** | Token 认证（`Authorization: Bearer {token}`） |
| **权限控制** | 无独立权限注解（由登录用户角色决定） |
| **请求格式** | `application/json` |
| **响应格式** | `application/json` |
| **幂等性** | 无（同一请求多次调用会创建多个工单） |

### 业务说明

该接口用于 APP 移动端创建智慧园林养护工单。提交后系统自动完成：

1. 校验道路信息存在性
2. 根据道路养护级别自动赋值养护等级
3. 自动生成工单编号（前缀 `GWO`）
4. 保存问题附件图片（如有）
5. 自动发起 Flowable BPM 工作流（流程定义 Key：`workorder_common_prod`）
6. 根据业务线自动匹配对应班组长角色作为流程审批人

---

## 2. 请求参数

### 2.1 Header 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `Authorization` | String | **是** | Bearer Token，格式：`Bearer {token}` |
| `Content-Type` | String | **是** | `application/json` |
| `tenant-id` | Long | 否 | 租户 ID（多租户场景） |

### 2.2 Body 参数（JSON）

| 参数名 | 类型 | 必填 | 校验规则 | 说明 | 示例 |
|--------|------|------|----------|------|------|
| `orderName` | String | 否 | max 100 | 工单名称 | `"树木倒伏紧急处理"` |
| `orderCode` | String | 否 | max 50 | 三级编码 | `"YL001"` |
| `busiType` | String | 否 | max 50 | 业务类型 | `"TREE_MAINTENANCE"` |
| `orderType` | String | 否 | max 1 | 工单类型：`C`=普通工单，`O`=其他工单。**不能传 `Q`**（快速工单有独立接口 `/createQuick`） | `"C"` |
| `rootCauseBy` | String | 否 | max 50 | 工单溯源号，`"0"` 表示无溯源 | `"0"` |
| `busiLine` | String | 否 | max 10 | 业务线：`yl`=园林，`wy`=物业，`sz`=市政。不传则取登录用户所属业务线 | `"yl"` |
| `roadId` | Long | **是** | `@NotNull` | 道路 ID（系统中已存在的道路） | `21128` |
| `roadName` | String | 否 | max 100 | 道路名称（辅助字段，实际以 roadId 查到的为准） | `"西长安街"` |
| `sourceId` | Integer | 否 | — | 来源 ID，不传默认 `1`（巡查）。见 [工单来源枚举](#51-工单来源枚举) | `1` |
| `sourceName` | String | 否 | max 50 | 来源名称，不传默认为"巡查" | `"巡查"` |
| `pressingType` | Integer | **是** | `@NotNull` | 紧急程度：`1`=特急，`2`=紧急，`3`=一般 | `2` |
| `latLonType` | Integer | 否 | — | 坐标系类型：`1`=WGS-84，`2`=BD-09，`3`=GCJ-02，`4`=腾讯 | `3` |
| `lat` | BigDecimal | **是** | `@NotNull` | 经度 | `116.397428` |
| `lon` | BigDecimal | **是** | `@NotNull` | 纬度 | `39.909204` |
| `lonLatAddress` | String | **是** | `@NotEmpty`，max 200 | 经纬度对应的地址描述 | `"北京市西城区西长安街5号"` |
| `thirdWorkNo` | String | 否 | max 50 | 第三方系统工单编号（对接外部系统时使用） | `"EXT20250607001"` |
| `remark` | String | **是** | `@NotEmpty`，max 500 | 工单描述 / 现场情况说明 | `"巡查发现行道树倾斜，存在倒伏风险"` |
| `handleResult` | String | 否 | max 500 | 工单完成结果描述（创建时可留空） | `""` |
| `expectedFinishDate` | String | 否 | ISO 8601 | 期望完成时间 | `"2025-12-07T18:00:00"` |
| `problemsImgs` | String[] | 否 | — | 问题现场拍照图片 URL 列表 | `["https://img.example.com/p1.jpg"]` |
| `endImgs` | String[] | 否 | — | 完成拍照图片 URL 列表（普通工单创建时一般不需要） | `[]` |

### 2.3 请求示例（完整）

```json
{
  "orderName": "树木倒伏紧急处理",
  "orderCode": "YL001",
  "busiType": "TREE_MAINTENANCE",
  "orderType": "C",
  "rootCauseBy": "0",
  "busiLine": "yl",
  "roadId": 21128,
  "roadName": "西长安街",
  "sourceId": 1,
  "sourceName": "巡查",
  "pressingType": 2,
  "latLonType": 3,
  "lat": 116.397428,
  "lon": 39.909204,
  "lonLatAddress": "北京市西城区西长安街5号",
  "thirdWorkNo": "",
  "remark": "巡查发现行道树倾斜约30度，存在倒伏风险，需要紧急处理",
  "handleResult": "",
  "expectedFinishDate": "2025-12-07T18:00:00",
  "problemsImgs": [
    "https://img.example.com/problem1.jpg",
    "https://img.example.com/problem2.jpg"
  ],
  "endImgs": []
}
```

### 2.4 请求示例（最小）

```json
{
  "roadId": 21128,
  "pressingType": 2,
  "lat": 116.397428,
  "lon": 39.909204,
  "lonLatAddress": "北京市西城区西长安街5号",
  "remark": "巡查发现树木倾斜，需要处理"
}
```

---

## 3. 响应参数

### 3.1 成功响应

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | 状态码，成功为 `0` |
| `msg` | String | 提示消息 |
| `data` | Long | 创建成功的工单 ID |

```json
{
  "code": 0,
  "msg": "成功",
  "data": 1024
}
```

> `data` 返回工单主键 ID（`workorder_main_info.id`），可用于后续查询工单详情。

### 3.2 失败响应

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | 错误码（非 0） |
| `msg` | String | 错误描述信息 |
| `data` | null | — |

```json
{
  "code": 1900001003,
  "msg": "养护班组长人员不存在",
  "data": null
}
```

---

## 4. 错误码参考

| 错误码 | 错误消息 | 触发场景 |
|--------|----------|----------|
| `1900001003` | 养护班组长人员不存在 | 根据道路 ID 和业务线找不到对应班组长角色的人员 |
| `1900002000` | 养护级别编码错误，不存在 | 道路关联的养护级别在字典中不存在 |
| `1900002001` | 该人员未分配角色 | 登录用户未分配任何角色 |
| `1900002002` | 工单类型错误，快速工单无法走此流程 | 传入了 `orderType="Q"` |
| `1900004002` | 道路信息不存在 | 传入的 `roadId` 在系统中查询不到 |
| `系统级` | 未登录 / Token 已过期 | 未传 Authorization 或 Token 无效 |
| `系统级` | 参数校验失败 | 必填字段缺失或格式不合法 |

---

## 5. 数据字典

### 5.1 工单来源枚举

| code | 描述 |
|------|------|
| `1` | 巡查 |
| `2` | 游客居民 |
| `3` | 12345 |
| `4` | 网格 |
| `5` | 大区经理 |
| `6` | AI |

### 5.2 业务线

| 值 | 描述 | 对应班组长角色 |
|----|------|----------------|
| `yl` | 园林 | `team_leader_yl` |
| `wy` | 物业 | `team_leader_wy` |
| `sz` | 市政 | `team_leader_sz` |
| `zx` | 秩序管理 | `team_leader_zxgl` |
| `hj` | 环境卫生 | `team_leader_hjws` |

### 5.3 工单类型

| 值 | 描述 | 说明 |
|----|------|------|
| `C` | 普通工单 | 走标准 BPM 审批流程 |
| `Q` | 快速工单 | **本接口不支持**，请使用 `/createQuick` 接口 |
| `O` | 其他工单 | 特殊类型 |

### 5.4 紧急程度

| 值 | 描述 |
|----|------|
| `1` | 特急 |
| `2` | 紧急 |
| `3` | 一般 |

### 5.5 坐标系类型

| 值 | 描述 |
|----|------|
| `1` | 国标（WGS-84） |
| `2` | 百度坐标系（BD-09） |
| `3` | 高德坐标系（GCJ-02） |
| `4` | 腾讯坐标系 |

---

## 6. 业务处理流程

```
 1. 参数校验（@Valid）
    ├── roadId、pressingType、lat、lon、lonLatAddress、remark 必填校验
    └── 长度/格式校验

 2. 道路信息校验
    ├── 根据 roadId 查询道路信息（roadApi.getRoadInfoById）
    ├── 赋值 workerCompanyId、streetId、streetName
    └── 道路不存在 → 抛出 APP_WORK_ROAD_NOT_EXISTS

 3. 工单类型处理
    ├── orderType 为空 → 默认 "C"
    ├── orderType = "Q" → 抛出 APP_WORK_ORADER_ERROR
    └── orderType = "C"/"O" → 正常

 4. 养护级别赋值
    ├── 根据道路 levelId 查询字典 "conserve_level"
    └── 字典值不存在 → 抛出 APP_WORKER_LEVEL_ID_NOT_EXISTS

 5. 登录用户信息赋值
    ├── companyId、deptId ← SecurityFrameworkUtils
    ├── userId、userName ← 当前登录用户
    ├── 角色列表 ← roleApi（不能为空）
    └── 角色为空 → 抛出 APP_USER_ROLE_NOT_EXISTS

 6. 来源处理（默认值）
    ├── sourceId 为空 → EventSourceEnum.PATROL(1)
    └── sourceName 为空 → "巡查"

 7. 业务线处理
    └── busiLine 为空 → 取登录用户所属业务线

 8. 工单编号生成
    └── workOrderApi.generateWONum("GWO")

 9. 工单保存
    └── workOrderMapper.insert → workorder_main_info 表

10. 附件保存（条件）
    └── problemsImgs 非空 → 写入 attachment 表

11. 发起 BPM 流程
    ├── 流程 Key: workorder_common_prod
    ├── 变量: roadId、applyUserId、isNeed
    ├── 审批人: 按 busiLine -> roleCode -> roadId 查找班组长
    └── 人员为空 → 抛出 TEAM_LEADER_YL_NOT_EXISTS

12. 回写流程实例 ID
    └── processInstanceId 更新到工单记录

13. 返回工单 ID
```

---

## 7. 写入数据表

### 7.1 `workorder_main_info`（工单主表）

| 字段 | 来源 | 说明 |
|------|------|------|
| `order_no` | 自动生成（GWO 前缀） | 工单编号 |
| `status` | `1`（RUNNING） | 审批中 |
| `buz_status` | `"000"` | 业务初始化状态 |
| `order_type` | 请求参数/默认 `"C"` | 工单类型 |
| `busi_line` | 请求参数/登录用户 | 业务线 |
| `road_id` | 请求参数 | 道路 ID |
| `worker_company_id` | 道路查询结果 | 道路负责部门 |
| `street_id` / `street_name` | 道路查询结果 | 街道信息 |
| `curing_level_id` / `curing_level_name` | 字典查询 | 养护级别 |
| `company_id` | 登录用户 | 提交人部门 |
| `dept_id` | 登录用户 | 部门 ID |
| `user_id` / `user_name` | 登录用户 | 提交人 |
| `source_id` / `source_name` | 请求/默认值 | 工单来源 |
| `wo_source_id` / `wo_source_name` | 角色信息 | 来源编码 |
| `commit_date` | `LocalDateTime.now()` | 提交时间 |
| `process_instance_id` | BPM 流程实例 ID | 工作流编号 |

### 7.2 `attachment`（附件表，条件写入）

仅当 `problemsImgs` 不为空时写入，`busiType = "01"`。

---

## 8. 对接注意事项

### 8.1 调用前准备

1. **获取 Token**：先调用登录接口获取有效的 Bearer Token
2. **确认道路 ID**：`roadId` 必须是系统中已配置的道路
3. **确认人员配置**：对应道路 + 业务线必须有班组长角色人员

### 8.2 限制与约束

| 约束 | 说明 |
|------|------|
| 不支持快速工单 | `orderType="Q"` 会报错，请用 `/createQuick` |
| 无幂等保证 | 同一请求重复调用会创建多个工单 |
| 默认工单类型 | 不传 `orderType` 默认为 `"C"`（普通工单） |
| 默认来源 | 不传 `sourceId` 默认为"巡查" |
| 事务保证 | 工单保存与流程发起在同一事务中，失败整体回滚 |
| 图片不校验 | `problemsImgs` 仅保存 URL，不校验有效性 |

### 8.3 创建成功后可用接口

| 操作 | 接口 |
|------|------|
| 查询工单详情 | `GET /app-api/bpm/garden/workorder/get?id={id}` |
| 工单分页查询 | `GET /app-api/bpm/garden/workorder/page` |
| 查询待办任务 | `GET /app-api/bpm/garden/workorder/todoPage` |
| 审批通过 | `PUT /app-api/bpm/garden/workorder/approve` |
| 退回任务 | `PUT /app-api/bpm/garden/workorder/return` |
| 撤回任务 | `PUT /app-api/bpm/garden/workorder/withdraw?taskId={taskId}` |

---

## 9. 变更记录

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| v1.0 | 2025-12-06 | 初始版本 | yanhuiqing |
| v1.1 | 2026-06-07 | 完善对外接口文档 | — |

---

> **测试环境地址**：`https://test.jichengshanshui.com.cn:28302/app-api/bpm/garden/workorder/create`
>
> **相关文档**：CLAUDE.md（项目全局约束）、BPM 流程定义文档