WMS_MAIN/database/designs/after-sale-api-design.md

645 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 售后工单 API 接口设计方案
> **状态**: ⏳ 等待人工审阅
> **设计日期**: 2026-07-29
> **设计人**: wms-db-agent
> **说明**: 本文档仅输出 API 接口设计方案,不直接修改程序代码。审阅通过后再执行实现。
---
## 一、模块概览
| 项目 | 说明 |
|------|------|
| 模块名 | `afterSale` |
| 接口路径 | `POST /system`,body 中 `method` 字段为 `afterSale.{方法名}` |
| 请求方式 | 全部 `POST`,参数放在 `body` 内 |
| 鉴权 | 除 `businessTypes` 外均需登录;写操作需鉴权 |
### 文件规划
```
app/service/systemMethods/afterSale.js ← 入口层(鉴权、参数校验、委托)
app/service/systems/afterSale.js ← 业务层(数据库操作、状态机)
methods/system.json ← API 文档(追加 afterSale group)
```
### 调用链路
```
POST /system { method: "afterSale.list", ... }
→ app/router.js
→ app/service/system.js
→ app/service/systemMethods/afterSale.js ← 鉴权 + 参数校验
→ app/service/systems/afterSale.js ← 业务逻辑 + DB操作
→ app/model/after_sale_work_order.js ← Sequelize Model
→ app/model/after_sale_work_order_step.js
```
---
## 二、接口清单(共 13 个)
| # | method | 描述 | 需登录 | 需鉴权 |
|---|--------|------|--------|--------|
| 1 | `afterSale.businessTypes` | 获取内置业务类型及子类型枚举 | ✗ | ✗ |
| 2 | `afterSale.list` | 工单列表(分页+筛选) | ✓ | ✗ |
| 3 | `afterSale.detail` | 工单详情(含步骤列表) | ✓ | ✗ |
| 4 | `afterSale.create` | 创建工单 | ✓ | ✓ |
| 5 | `afterSale.update` | 更新工单基本信息 | ✓ | ✓ |
| 6 | `afterSale.delete` | 删除工单(软删除) | ✓ | ✓ |
| 7 | `afterSale.assign` | 分配处理人 | ✓ | ✓ |
| 8 | `afterSale.complete` | 完成工单 | ✓ | ✓ |
| 9 | `afterSale.close` | 关闭工单 | ✓ | ✓ |
| 10 | `afterSale.cancel` | 取消工单 | ✓ | ✓ |
| 11 | `afterSale.stepStart` | 开始某个步骤 | ✓ | ✓ |
| 12 | `afterSale.stepComplete` | 完成某个步骤 | ✓ | ✓ |
| 13 | `afterSale.stepSkip` | 跳过某个步骤 | ✓ | ✓ |
---
## 三、接口详细设计
### 3.1 `afterSale.businessTypes` — 获取业务类型枚举
```json
{
"method": "afterSale.businessTypes",
"description": "获取售后工单内置业务类型及子类型枚举,供前端下拉选择使用。数据来源:app/model/after_sale_work_order.js 中的 BUSINESS_TYPES 常量。",
"isNeedAuth": false,
"isNeedLogin": false,
"params": [],
"response": [
{
"name": "data",
"type": "object",
"description": "业务类型枚举,key 为 business_type,value 含 label、table、subtypes",
"example": {
"waybill": {
"label": "运单",
"table": "wms_order_express",
"subtypes": {
"intercept": "拦截",
"urge": "催件",
"damage": "破损",
"lost": "丢件",
"wrong_info": "信息错误"
}
},
"order_delivery": {
"label": "发货订单",
"table": "wms_order_delivery",
"subtypes": {
"mis_shipment": "错发",
"missing_item": "少发",
"wrong_sku": "错品",
"quality_issue": "质量问题",
"delivery_delay": "发货延迟"
}
}
}
}
]
}
```
---
### 3.2 `afterSale.list` — 工单列表
```json
{
"method": "afterSale.list",
"description": "查询售后工单列表,支持分页与多条件筛选。仓库隔离(自动注入 warehouse_id)。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数 { page, pageSize },默认 page=1 pageSize=20"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "筛选条件,所有字段均为可选",
"children": [
{ "name": "workOrderNo", "type": "string", "description": "工单号(模糊搜索)" },
{ "name": "businessType", "type": "string", "description": "业务类型(等值),如 waybill" },
{ "name": "businessSubType","type": "string", "description": "业务子类型(等值),如 intercept" },
{ "name": "businessNo", "type": "string", "description": "关联业务单据号(模糊)" },
{ "name": "status", "type": "number", "description": "工单状态(等值):0/1/2/3/9" },
{ "name": "priorityMin", "type": "number", "description": "优先级下限(>=)" },
{ "name": "priorityMax", "type": "number", "description": "优先级上限(<=)" },
{ "name": "claimStatus", "type": "number", "description": "理赔状态(等值):0/1/2" },
{ "name": "assigneeId", "type": "number", "description": "处理人ID(等值)" },
{ "name": "creatorId", "type": "number", "description": "创建人ID(等值)" },
{ "name": "keyword", "type": "string", "description": "关键词:匹配工单号/标题/业务单据号" },
{ "name": "createdAtStart", "type": "string", "description": "创建时间起始(YYYY-MM-DD)" },
{ "name": "createdAtEnd", "type": "string", "description": "创建时间截止(YYYY-MM-DD)" }
]
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序 { field: 'priority'|'created_at'|'status', order: 'asc'|'desc' },默认 priority desc"
}
],
"response": [
{
"name": "list",
"type": "array",
"description": "工单列表(不含 description/resolution 长文本,减少传输量)",
"children": [
{ "name": "id", "type": "number", "description": "工单ID" },
{ "name": "work_order_no", "type": "string", "description": "工单号" },
{ "name": "warehouse_id", "type": "number", "description": "仓库ID" },
{ "name": "store_id", "type": "number", "description": "货主ID" },
{ "name": "business_type", "type": "string", "description": "业务类型" },
{ "name": "business_sub_type","type": "string", "description": "业务子类型" },
{ "name": "business_id", "type": "number", "description": "关联单据ID" },
{ "name": "business_no", "type": "string", "description": "关联单据号" },
{ "name": "direction", "type": "number", "description": "记账方向:0/1/2" },
{ "name": "status", "type": "number", "description": "工单状态:0/1/2/3/9" },
{ "name": "priority", "type": "number", "description": "优先级:1-100" },
{ "name": "title", "type": "string", "description": "工单标题" },
{ "name": "creator_id", "type": "number", "description": "创建人ID" },
{ "name": "creator_name", "type": "string", "description": "创建人姓名(JOIN account)" },
{ "name": "assignee_id", "type": "number", "description": "当前处理人ID" },
{ "name": "assignee_name", "type": "string", "description": "当前处理人姓名(JOIN account)" },
{ "name": "parent_work_order_id","type":"number","description": "父工单ID" },
{ "name": "current_step", "type": "number", "description": "当前进度步骤序号" },
{ "name": "claim_needed", "type": "number", "description": "是否理赔" },
{ "name": "claim_amount", "type": "number", "description": "理赔金额" },
{ "name": "claim_status", "type": "number", "description": "理赔状态" },
{ "name": "resolved_at", "type": "string", "description": "解决时间" },
{ "name": "created_at", "type": "string", "description": "创建时间" },
{ "name": "updated_at", "type": "string", "description": "更新时间" }
]
},
{ "name": "pagination", "type": "object", "description": "分页信息 { page, pageSize, total, totalPages }" }
]
}
```
---
### 3.3 `afterSale.detail` — 工单详情
```json
{
"method": "afterSale.detail",
"description": "查询单个工单详情,含完整字段 + 步骤列表。仓库隔离。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "工单ID(必填)"
}
],
"response": [
{
"name": "data",
"type": "object",
"description": "工单完整信息",
"children": [
{ "name": "id", "type": "number", "description": "工单ID" },
{ "name": "...", "type": "", "description": "同 list 接口所有字段" },
{ "name": "description", "type": "string", "description": "问题描述(详情接口返回)" },
{ "name": "resolution", "type": "string", "description": "处理结果说明(详情接口返回)" },
{ "name": "creator_snapshot", "type": "string", "description": "创建人信息快照" },
{ "name": "steps", "type": "array", "description": "步骤列表",
"children": [
{ "name": "id", "type": "number", "description": "步骤ID" },
{ "name": "step_order", "type": "number", "description": "步骤序号" },
{ "name": "step_name", "type": "string", "description": "步骤名称" },
{ "name": "step_status", "type": "number", "description": "步骤状态:0/1/2/3" },
{ "name": "operator_id", "type": "number", "description": "操作人ID" },
{ "name": "operator_name", "type": "string", "description": "操作人姓名" },
{ "name": "operator_snapshot","type": "string", "description": "操作人快照" },
{ "name": "action", "type": "string", "description": "操作动作" },
{ "name": "remark", "type": "string", "description": "处理备注" },
{ "name": "started_at", "type": "string", "description": "开始时间" },
{ "name": "completed_at", "type": "string", "description": "完成时间" },
{ "name": "created_at", "type": "string", "description": "创建时间" }
]
},
{ "name": "children", "type": "array", "description": "子工单列表(如有)" },
{ "name": "parent", "type": "object", "description": "父工单简要信息(如有)" }
]
}
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "404", "description": "工单不存在或无权访问" }
]
}
```
---
### 3.4 `afterSale.create` — 创建工单
```json
{
"method": "afterSale.create",
"description": "创建售后工单。自动生成工单号(AS+时间戳),自动设置 creator_id 和 warehouse_id。创建成功后返回工单详情。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{
"name": "business_type",
"type": "string",
"required": true,
"source": "body",
"description": "业务类型(必填),如 waybill、order_delivery"
},
{
"name": "business_sub_type",
"type": "string",
"required": true,
"source": "body",
"description": "业务子类型(必填),如 intercept、mis_shipment。需与 business_type 匹配(由 BUSINESS_TYPES 校验)"
},
{
"name": "business_id",
"type": "number",
"required": true,
"source": "body",
"description": "关联业务单据主键ID(必填)"
},
{
"name": "business_no",
"type": "string",
"required": false,
"source": "body",
"description": "关联业务单据号(可选,建议传入方便列表展示)"
},
{
"name": "direction",
"type": "number",
"required": false,
"source": "body",
"description": "记账方向:1=入库 2=出库,默认 0(未确定)"
},
{
"name": "priority",
"type": "number",
"required": false,
"source": "body",
"description": "优先级:1~100,默认 50。AI 创建时自动填入"
},
{
"name": "title",
"type": "string",
"required": true,
"source": "body",
"description": "工单标题(必填)"
},
{
"name": "description",
"type": "string",
"required": false,
"source": "body",
"description": "问题描述"
},
{
"name": "claim_needed",
"type": "number",
"required": false,
"source": "body",
"description": "是否需要理赔:0=否 1=是,默认 0"
},
{
"name": "claim_amount",
"type": "number",
"required": false,
"source": "body",
"description": "理赔金额,默认 0.00"
},
{
"name": "parent_work_order_id",
"type": "number",
"required": false,
"source": "body",
"description": "父工单ID(子工单场景),不传则为根工单"
}
],
"response": [
{
"name": "data",
"type": "object",
"description": "创建成功的工单详情(同 detail 接口返回结构)"
}
],
"errors": [
{ "code": "400", "description": "工单标题不能为空" },
{ "code": "400", "description": "业务类型或子类型不合法" },
{ "code": "400", "description": "父工单不存在" }
]
}
```
---
### 3.5 `afterSale.update` — 更新工单基本信息
```json
{
"method": "afterSale.update",
"description": "更新工单基本信息(标题、描述、优先级、记账方向、理赔信息)。不可修改 business_type/business_sub_type/business_id。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" },
{ "name": "title", "type": "string", "required": false, "source": "body", "description": "工单标题" },
{ "name": "description", "type": "string", "required": false, "source": "body", "description": "问题描述" },
{ "name": "priority", "type": "number", "required": false, "source": "body", "description": "优先级" },
{ "name": "direction", "type": "number", "required": false, "source": "body", "description": "记账方向" },
{ "name": "claim_needed", "type": "number", "required": false, "source": "body", "description": "是否需要理赔" },
{ "name": "claim_amount", "type": "number", "required": false, "source": "body", "description": "理赔金额" },
{ "name": "claim_status", "type": "number", "required": false, "source": "body", "description": "理赔状态" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的工单详情" }
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "404", "description": "工单不存在或无权操作" }
]
}
```
---
### 3.6 `afterSale.delete` — 删除工单
```json
{
"method": "afterSale.delete",
"description": "软删除工单及其所有步骤。仅待处理(0)和已取消(9)状态的工单可删除。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" }
],
"response": [],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "400", "description": "处理中的工单不可删除" },
{ "code": "404", "description": "工单不存在或无权操作" }
]
}
```
---
### 3.7 `afterSale.assign` — 分配处理人
```json
{
"method": "afterSale.assign",
"description": "将工单分配给指定处理人。仅待处理(0)状态的工单可分配。分配后自动流转至处理中(1)。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" },
{ "name": "assignee_id", "type": "number", "required": true, "source": "body", "description": "处理人ID(必填)" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "分配备注" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的工单详情" }
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "400", "description": "处理人ID不能为空" },
{ "code": "400", "description": "当前状态不可分配(非待处理状态)" }
]
}
```
---
### 3.8 `afterSale.complete` — 完成工单
```json
{
"method": "afterSale.complete",
"description": "完成工单。仅处理中(1)状态且所有步骤已完成/跳过的工单可完成。完成后自动设置 resolved_at。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" },
{ "name": "resolution", "type": "string", "required": false, "source": "body", "description": "处理结果说明" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的工单详情" }
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "400", "description": "当前状态不可完成(非处理中状态)" },
{ "code": "400", "description": "仍有步骤未完成,请先完成所有步骤" }
]
}
```
---
### 3.9 `afterSale.close` — 关闭工单
```json
{
"method": "afterSale.close",
"description": "关闭工单。仅已完成(2)状态的工单可关闭。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "关闭备注" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的工单详情" }
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "400", "description": "当前状态不可关闭(非已完成状态)" }
]
}
```
---
### 3.10 `afterSale.cancel` — 取消工单
```json
{
"method": "afterSale.cancel",
"description": "取消工单。仅待处理(0)和处理中(1)状态的工单可取消。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "取消原因" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的工单详情" }
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "400", "description": "当前状态不可取消" }
]
}
```
---
### 3.11 `afterSale.stepStart` — 开始步骤
```json
{
"method": "afterSale.stepStart",
"description": "开始处理某个步骤。将步骤状态设为进行中(1),同时更新主表 current_step。同一时刻只允许一个步骤处于进行中。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "step_id", "type": "number", "required": true, "source": "body", "description": "步骤ID(必填,wms_after_sale_work_order_step.id)" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的步骤信息" }
],
"errors": [
{ "code": "400", "description": "步骤ID不能为空" },
{ "code": "400", "description": "已有其他步骤正在进行中" },
{ "code": "400", "description": "步骤当前状态不可开始" }
]
}
```
---
### 3.12 `afterSale.stepComplete` — 完成步骤
```json
{
"method": "afterSale.stepComplete",
"description": "完成某个步骤。将步骤状态设为已完成(2),记录操作人和完成时间。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "step_id", "type": "number", "required": true, "source": "body", "description": "步骤ID(必填)" },
{ "name": "action", "type": "string", "required": false, "source": "body", "description": "操作动作描述" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "处理备注" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的步骤信息" }
],
"errors": [
{ "code": "400", "description": "步骤ID不能为空" },
{ "code": "400", "description": "步骤当前状态不可完成(非进行中状态)" }
]
}
```
---
### 3.13 `afterSale.stepSkip` — 跳过步骤
```json
{
"method": "afterSale.stepSkip",
"description": "跳过某个步骤。将步骤状态设为已跳过(3)。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "step_id", "type": "number", "required": true, "source": "body", "description": "步骤ID(必填)" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "跳过原因" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的步骤信息" }
],
"errors": [
{ "code": "400", "description": "步骤ID不能为空" },
{ "code": "400", "description": "步骤当前状态不可跳过" }
]
}
```
---
## 四、状态机约束(服务端校验规则)
| 操作 | 允许的当前状态 | 目标状态 |
|------|-------------|---------|
| `create` | — | `status=0`, `current_step=1` |
| `assign` | `status=0` | `status=1` |
| `delete` | `status=0` 或 `status=9` | 软删除 |
| `complete` | `status=1` + 所有步骤已完成/跳过 | `status=2`, `resolved_at=NOW()` |
| `close` | `status=2` | `status=3` |
| `cancel` | `status=0` 或 `status=1` | `status=9` |
| `stepStart` | `step_status=0` + 无其他进行中步骤 | `step_status=1`, `current_step=该step_order` |
| `stepComplete` | `step_status=1` | `step_status=2` |
| `stepSkip` | `step_status=0` | `step_status=3` |
---
## 五、methods/system.json 追加格式
在 `methods.system.json` 的 `methods.groups` 数组末尾追加:
```json
{
"groupName": "售后工单模块",
"module": "afterSale",
"list": [
{ "method": "afterSale.businessTypes", ... },
{ "method": "afterSale.list", ... },
{ "method": "afterSale.detail", ... },
{ "method": "afterSale.create", ... },
{ "method": "afterSale.update", ... },
{ "method": "afterSale.delete", ... },
{ "method": "afterSale.assign", ... },
{ "method": "afterSale.complete", ... },
{ "method": "afterSale.close", ... },
{ "method": "afterSale.cancel", ... },
{ "method": "afterSale.stepStart", ... },
{ "method": "afterSale.stepComplete", ... },
{ "method": "afterSale.stepSkip", ... }
]
}
```
(完整 JSON 定义见第三节各接口)
---
## 六、后续实现计划(审阅通过后执行)
| 步骤 | 文件 | 说明 |
|------|------|------|
| 1 | `app/service/systems/afterSale.js` | 业务层:数据库操作、状态机、工单号生成 |
| 2 | `app/service/systemMethods/afterSale.js` | 入口层:鉴权配置、参数校验、委托调用 |
| 3 | `methods/system.json` | 追加 `afterSale` group 的 13 个 method 文档 |
| 4 | `methods/changes/afterSale-20260729.json` | 接口变更记录 |
---
## 七、待确认事项
- [ ] **1. 模块名**:`afterSale` 是否合适?备选 `asWorkOrder`、`afterSaleWorkOrder`
- [ ] **2. 步骤操作是否需要独立接口**:`stepStart/stepComplete/stepSkip` 三个独立接口 vs 合并为一个 `stepUpdate`(传 status 参数)
- [ ] **3. `businessTypes` 接口免登录**:是否允许未登录用户获取业务类型枚举?
- [ ] **4. 步骤创建时机**:步骤是创建工单时自动初始化一组,还是由前端手动逐条添加?
- [ ] **5. 是否需要批量操作**:批量分配、批量关闭?
- [ ] **6. 是否需要操作日志**:是否复用 `operation_log` 记录关键状态变更?