APP-园林工单创建接口文档.md 11.8 KB

Edit Raw Blame History Permalink


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 移动端创建智慧园林养护工单。提交后系统自动完成：


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


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（巡查）。见 工单来源枚举
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 请求示例（完整）
{
  "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 请求示例（最小）
{
  "roadId": 21128,
  "pressingType": 2,
  "lat": 116.397428,
  "lon": 39.909204,
  "lonLatAddress": "北京市西城区西长安街5号",
  "remark": "巡查发现树木倾斜，需要处理"
}


3. 响应参数
3.1 成功响应


字段
类型
说明


code
Integer
状态码，成功为 0


msg
String
提示消息


data
Long
创建成功的工单 ID


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


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

3.2 失败响应


字段
类型
说明


code
Integer
错误码（非 0）


msg
String
错误描述信息


data
null
—


{
  "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 调用前准备

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

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