# 售后工单 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` 记录关键状态变更?