# 工单助手(App)接口联调方案 ## 涉及页面 - App 工作台「工单助手」分组 - App 工单上报(新增 / 编辑售后工单) - App 工单受理(售后工单列表) - App 售后工单详情(进度、签到、转派、升级、处理记录) - App 工单分析(统计看板) ## 业务流程与数据带入 1. 工单上报 → 工单受理:上报后工单状态为「处理中」,自动写入一条 `CREATE` 进度记录。 2. 工单受理 → 售后工单详情:列表点入详情,按 `ticketId` 拉取进度记录、回访记录与附件。 3. 详情 → 现场签到:App 取当前定位(经度 / 纬度)并填写现场地址,首次签到回写工单 `signInTime` / `signInAddress`。 4. 详情 → 转派 / 升级 / 处理记录:均写入 `after_sale_ticket_log`,进度时间线实时刷新。 5. 详情 → 完结 → 回访:回访登记成功后写 `VISIT` 记录;不满意或复发会退回「处理中」。 6. 工单分析:按数据权限场景(我负责的 / 我参与的 / 下属负责的 / 全部)汇总工单状态、问题类型、处理人工作量。 ## API | 方法 | 路径 | 说明 | |------|------|------| | POST | /aftersales/ticket/sign-in | 现场签到 | | POST | /aftersales/ticket/transfer | 转派工单 | | POST | /aftersales/ticket/escalate | 升级工单 | | POST | /aftersales/ticket/handle | 新增处理记录 | | GET | /aftersales/ticket/log-list | 工单操作 / 进度记录列表 | | GET | /aftersales/ticket/statistics | 工单助手统计 | 权限码:签到、转派、升级、处理记录统一使用 `aftersales:ticket:update`;进度记录与统计使用登录态,无额外按钮权限。 **请求参数:** 签到 `POST /aftersales/ticket/sign-in` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | id | Long | 是 | 工单编号 | | longitude | BigDecimal | 否 | 经度,App 定位失败时允许为空 | | latitude | BigDecimal | 否 | 纬度 | | address | String | 否 | 现场地址(建议客户端必填,便于追溯) | | content | String | 否 | 签到说明 | 转派 `POST /aftersales/ticket/transfer` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | id | Long | 是 | 工单编号 | | handlerUserId | Long | 是 | 新处理人,不能与当前处理人相同 | | reason | String | 否 | 转派原因 | 升级 `POST /aftersales/ticket/escalate` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | id | Long | 是 | 工单编号 | | severityLevel | Integer | 否 | 升级后的严重程度(0 轻微 / 1 一般 / 2 严重 / 3 致命),不传则自动 +1,最高 3 | | reason | String | 否 | 升级原因 | 处理记录 `POST /aftersales/ticket/handle` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | id | Long | 是 | 工单编号 | | content | String | 是 | 处理动作与结果 | 进度记录 `GET /aftersales/ticket/log-list?ticketId=1` 统计 `GET /aftersales/ticket/statistics?sceneType=4` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | sceneType | Integer | 否 | 1 我负责的 / 2 我参与的 / 3 下属负责的 / 4 全部,默认 4 | **响应字段:** 进度记录项: | 字段 | 类型 | 说明 | |------|------|------| | actionType | Integer | 1 上报 / 2 派单 / 3 签到 / 4 问题判定 / 5 转派 / 6 升级 / 7 处理记录 / 8 完结 / 9 回访 / 10 归档 / 11 取消 | | actionName | String | 操作名称(后端已翻译) | | content | String | 操作内容 | | operatorUserName | String | 操作人昵称 | | longitude / latitude | BigDecimal | 签到坐标 | | address | String | 签到地址 | | createTime | LocalDateTime | 操作时间 | 统计响应: | 字段 | 类型 | 说明 | |------|------|------| | totalCount / processingCount / waitingReturnCount / waitingRefundCount | Long | 总量与各阶段数量 | | completedCount / closedCount / canceledCount | Long | 已完结 / 已关闭 / 已取消 | | todayCreateCount / todayResolveCount | Long | 今日上报 / 今日完结 | | signInCount / escalatedCount | Long | 签到次数 / 升级过的工单数 | | avgResolveHours | BigDecimal | 平均处理时长(小时) | | satisfactionRate | BigDecimal | 回访满意度(%) | | statusCounts | Array | `{ status, statusName, count }` | | issueTypeCounts | Array | `{ issueType, issueTypeName, count }` | | handlerWorkloads | Array | `{ handlerUserId, handlerUserName, processingCount, totalCount }` | ## 字段展示规则 | 字段 | 展示位置 | 说明 | |------|----------|------| | signInTime / signInAddress | 工单详情 | 显示「未签到」时提供一个现场签到按钮 | | 进度记录 | 工单详情「处理进度」 | 按时间正序展示,签到记录附带定位 | | actionName | 进度时间线标题 | 直接使用后端返回值,不在前端重复维护枚举 | | 统计看板 | 工单分析 | 卡片刻度 + 横向占比条,处理人工作量按处理中 / 累计展示 | ## 业务规则说明 | 场景 | 规则 | |------|------| | 现场签到 | 仅「处理中」工单可签到;首次签到回写工单,后续签到仅追加记录 | | 转派 | 仅「处理中」可转派;新处理人与当前处理人相同会返回明确错误 | | 升级 | 仅「处理中」工单可升级;严重程度只升不降 | | 处理记录 | 处理中、待退货、待退款状态可追加 | | 离线上报 | 无网络时工单暂存本地,进入工单列表且有网时自动补传;业务校验失败的离线单会被跳过 | ## 注意事项 - 签到定位失败不阻断签到:地址仍建议必填,便于追溯。 - 进度记录依赖登录用户,操作人由后端从上下文获取,前端不要传 `operatorUserId`。 - 统计接口按数据权限场景过滤,`sceneType` 与工单列表保持一致。 - 离线队列补传使用创建时的 token;token 失效时需用户重新登录后再补传。