BJ_FS / urbanops

  # 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 流程定义文档