From 0c2b0626582c7981ca57dd4b183092fd77f20daf Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sun, 9 Aug 2026 16:21:04 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E7=A7=BB=E9=99=A4=E5=94=AE=E5=90=8E?= =?UTF-8?q?=E5=B7=A5=E5=8D=95=E6=A8=A1=E5=9D=97=20(after=5Fsale=5Fwork=5Fo?= =?UTF-8?q?rder)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除 model: after_sale_work_order.js, after_sale_work_order_step.js - 删除旧迁移: 20260728120000, 20260728130000 - 删除设计文档: after-sale-work-order-design.md, after-sale-api-design.md - 新增 DROP TABLE 迁移: 20260809120000 - 开发/生产环境均已执行 DROP 迁移,两表已删除 --- app/model/after_sale_work_order.js | 267 -------- app/model/after_sale_work_order_step.js | 99 --- database/designs/after-sale-api-design.md | 644 ------------------ .../designs/after-sale-work-order-design.md | 440 ------------ ...0-create-wms-after-sale-work-order-step.js | 115 ---- ...9120000-drop-wms-after-sale-work-order.js} | 167 +++-- 6 files changed, 104 insertions(+), 1628 deletions(-) delete mode 100644 app/model/after_sale_work_order.js delete mode 100644 app/model/after_sale_work_order_step.js delete mode 100644 database/designs/after-sale-api-design.md delete mode 100644 database/designs/after-sale-work-order-design.md delete mode 100644 database/migrations/20260728130000-create-wms-after-sale-work-order-step.js rename database/migrations/{20260728120000-create-wms-after-sale-work-order.js => 20260809120000-drop-wms-after-sale-work-order.js} (50%) diff --git a/app/model/after_sale_work_order.js b/app/model/after_sale_work_order.js deleted file mode 100644 index 90e0c89..0000000 --- a/app/model/after_sale_work_order.js +++ /dev/null @@ -1,267 +0,0 @@ -'use strict'; - -module.exports = app => { - const { STRING, BIGINT, INTEGER, TINYINT, TEXT, DATE, DECIMAL } = app.Sequelize; - - /** - * 售后工单业务类型定义 - * 外部可通过 require('./app/model/after_sale_work_order').BUSINESS_TYPES 访问 - * 增删业务类型或子类型只需修改此常量,无需 ALTER TABLE - */ - const BUSINESS_TYPES = { - 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: '发货延迟', - }, - }, - entry_order: { - label: '入库单', - table: 'wms_entry_order', - subtypes: { - shortage: '少货', - damage: '破损', - wrong_sku: '错品', - quality_issue: '质量问题', - }, - }, - order_stockout: { - label: '出库单/退货出库单', - table: 'wms_order_stockout', - subtypes: { - return_issue: '退货异常', - wrong_outbound: '错发', - shortage: '少发', - }, - }, - receiving: { - label: '收货单', - table: 'wms_receiving', - subtypes: { - shortage: '少货', - damage: '破损', - quality_issue: '质量问题', - }, - }, - other: { - label: '其他', - table: null, - subtypes: { - general: '通用', - }, - }, - }; - - /** - * 根据 business_type 获取关联表名 - * @param {string} businessType 业务类型 - * @return {string|null} 关联表名 - */ - function getBusinessTable(businessType) { - return BUSINESS_TYPES[businessType]?.table || null; - } - - /** - * 校验 business_type + business_sub_type 组合是否合法 - * @param {string} businessType 业务类型 - * @param {string} businessSubType 业务子类型 - * @return {boolean} 是否合法 - */ - function isValidSubType(businessType, businessSubType) { - const def = BUSINESS_TYPES[businessType]; - return def && Object.prototype.hasOwnProperty.call(def.subtypes, businessSubType); - } - - const AfterSaleWorkOrder = app.model.define('after_sale_work_order', { - id: { - type: BIGINT(20).UNSIGNED, - primaryKey: true, - autoIncrement: true, - comment: '主键ID', - }, - warehouse_id: { - type: BIGINT(20).UNSIGNED, - allowNull: false, - comment: '仓库ID', - }, - store_id: { - type: BIGINT(20).UNSIGNED, - allowNull: false, - comment: '货主ID', - }, - work_order_no: { - type: STRING(50), - allowNull: false, - comment: '售后工单号,唯一', - }, - business_type: { - type: STRING(50), - allowNull: false, - comment: '关联业务类型', - }, - business_sub_type: { - type: STRING(50), - allowNull: false, - comment: '关联业务子类型', - }, - business_id: { - type: BIGINT(20).UNSIGNED, - allowNull: false, - comment: '关联业务单据主键ID(多态关联)', - }, - business_no: { - type: STRING(100), - allowNull: true, - comment: '关联业务单据号(冗余)', - }, - direction: { - type: TINYINT.UNSIGNED, - allowNull: false, - defaultValue: 0, - comment: '记账方向:0=未确定 1=入库 2=出库', - }, - status: { - type: TINYINT.UNSIGNED, - allowNull: false, - defaultValue: 0, - comment: '工单状态:0=待处理 1=处理中 2=已完成 3=已关闭 9=已取消', - }, - priority: { - type: TINYINT.UNSIGNED, - allowNull: false, - defaultValue: 50, - comment: '优先级:1~100,数字越大优先级越高', - }, - title: { - type: STRING(200), - allowNull: false, - comment: '工单标题/摘要', - }, - description: { - type: TEXT, - allowNull: true, - comment: '问题描述', - }, - creator_id: { - type: BIGINT(20).UNSIGNED, - allowNull: false, - comment: '创建人ID,关联 account.id;0 表示 AI 自动接待', - }, - creator_snapshot: { - type: TEXT, - allowNull: true, - comment: '创建人信息快照(JSON格式);AI创建时记录模型/会话信息', - }, - assignee_id: { - type: BIGINT(20).UNSIGNED, - allowNull: true, - comment: '当前处理人ID,关联 account.id', - }, - parent_work_order_id: { - type: BIGINT(20).UNSIGNED, - allowNull: true, - comment: '父工单ID,自关联本表;非空时表示子工单', - }, - current_step: { - type: TINYINT.UNSIGNED, - allowNull: false, - defaultValue: 1, - comment: '当前进度,值为当前正在处理的 step_order 序号', - }, - claim_needed: { - type: TINYINT.UNSIGNED, - allowNull: false, - defaultValue: 0, - comment: '是否需要理赔:0=不需要 1=需要', - }, - claim_amount: { - type: DECIMAL(12, 2), - allowNull: true, - defaultValue: 0.00, - comment: '理赔金额(元)', - }, - claim_status: { - type: TINYINT.UNSIGNED, - allowNull: false, - defaultValue: 0, - comment: '理赔状态:0=未理赔 1=已理赔(单笔结清) 2=月结', - }, - resolution: { - type: TEXT, - allowNull: true, - comment: '处理结果说明', - }, - resolved_at: { - type: DATE, - allowNull: true, - comment: '解决时间', - }, - created_at: { - type: DATE, - allowNull: false, - comment: '创建时间', - }, - updated_at: { - type: DATE, - allowNull: false, - comment: '更新时间', - }, - deleted_at: { - type: DATE, - allowNull: true, - comment: '软删除时间', - }, - }, { - tableName: 'wms_after_sale_work_order', - timestamps: true, - createdAt: 'created_at', - updatedAt: 'updated_at', - paranoid: true, - deletedAt: 'deleted_at', - comment: '售后工单主表', - }); - - AfterSaleWorkOrder.associate = () => { - // 自关联:父工单 → 子工单 - AfterSaleWorkOrder.hasMany(app.model.AfterSaleWorkOrder, { - foreignKey: 'parent_work_order_id', - sourceKey: 'id', - as: 'children', - }); - AfterSaleWorkOrder.belongsTo(app.model.AfterSaleWorkOrder, { - foreignKey: 'parent_work_order_id', - targetKey: 'id', - as: 'parent', - }); - - // 关联进度步骤表 - AfterSaleWorkOrder.hasMany(app.model.AfterSaleWorkOrderStep, { - foreignKey: 'work_order_id', - sourceKey: 'id', - as: 'steps', - }); - }; - - // 挂载业务类型常量及辅助函数到 Model - AfterSaleWorkOrder.BUSINESS_TYPES = BUSINESS_TYPES; - AfterSaleWorkOrder.getBusinessTable = getBusinessTable; - AfterSaleWorkOrder.isValidSubType = isValidSubType; - - return AfterSaleWorkOrder; -}; diff --git a/app/model/after_sale_work_order_step.js b/app/model/after_sale_work_order_step.js deleted file mode 100644 index dc66ba4..0000000 --- a/app/model/after_sale_work_order_step.js +++ /dev/null @@ -1,99 +0,0 @@ -'use strict'; - -module.exports = app => { - const { STRING, BIGINT, TINYINT, TEXT, DATE } = app.Sequelize; - - const AfterSaleWorkOrderStep = app.model.define('after_sale_work_order_step', { - id: { - type: BIGINT(20).UNSIGNED, - primaryKey: true, - autoIncrement: true, - comment: '主键ID', - }, - work_order_id: { - type: BIGINT(20).UNSIGNED, - allowNull: false, - comment: '工单ID,关联 wms_after_sale_work_order.id', - }, - step_order: { - type: TINYINT.UNSIGNED, - allowNull: false, - defaultValue: 1, - comment: '步骤序号(从1开始递增)', - }, - step_name: { - type: STRING(100), - allowNull: false, - comment: '步骤名称', - }, - step_status: { - type: TINYINT.UNSIGNED, - allowNull: false, - defaultValue: 0, - comment: '步骤状态:0=待开始 1=进行中 2=已完成 3=已跳过', - }, - operator_id: { - type: BIGINT(20).UNSIGNED, - allowNull: true, - comment: '操作员工ID,关联 account.id', - }, - operator_snapshot: { - type: TEXT, - allowNull: true, - comment: '操作人信息快照(JSON格式)', - }, - action: { - type: STRING(100), - allowNull: true, - comment: '操作动作描述', - }, - remark: { - type: TEXT, - allowNull: true, - comment: '处理备注', - }, - started_at: { - type: DATE, - allowNull: true, - comment: '步骤开始时间', - }, - completed_at: { - type: DATE, - allowNull: true, - comment: '步骤完成时间', - }, - created_at: { - type: DATE, - allowNull: false, - comment: '创建时间', - }, - updated_at: { - type: DATE, - allowNull: false, - comment: '更新时间', - }, - deleted_at: { - type: DATE, - allowNull: true, - comment: '软删除时间', - }, - }, { - tableName: 'wms_after_sale_work_order_step', - timestamps: true, - createdAt: 'created_at', - updatedAt: 'updated_at', - paranoid: true, - deletedAt: 'deleted_at', - comment: '售后工单进度步骤表', - }); - - AfterSaleWorkOrderStep.associate = () => { - AfterSaleWorkOrderStep.belongsTo(app.model.AfterSaleWorkOrder, { - foreignKey: 'work_order_id', - targetKey: 'id', - as: 'workOrder', - }); - }; - - return AfterSaleWorkOrderStep; -}; diff --git a/database/designs/after-sale-api-design.md b/database/designs/after-sale-api-design.md deleted file mode 100644 index b4a4bd3..0000000 --- a/database/designs/after-sale-api-design.md +++ /dev/null @@ -1,644 +0,0 @@ -# 售后工单 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` 记录关键状态变更? diff --git a/database/designs/after-sale-work-order-design.md b/database/designs/after-sale-work-order-design.md deleted file mode 100644 index 13d2914..0000000 --- a/database/designs/after-sale-work-order-design.md +++ /dev/null @@ -1,440 +0,0 @@ -# 售后工单表设计方案 - -> **状态**: ✅ 已落库(开发环境) -> **设计日期**: 2026-07-28(v4 定稿:新增 parent_work_order_id 支持主子工单) -> **设计人**: wms-db-agent -> **说明**: 本文档仅输出设计方案,不执行落库。审阅通过后再生成迁移文件。 - ---- - -## 一、需求概述 - -1. **主表**:售后工单单表,支持灵活绑定多种业务单据(运单、订单、入库单、退货单等),通过 `business_type` + `business_sub_type` + `business_id` 三级多态关联 -2. **副表**:进度步骤处理表,记录每一步的操作员工、动作、备注(步骤不预设模板,由业务逻辑动态创建) -3. **状态流转**:工单整体状态 + 主表 `current_step` 进度 + 步骤级状态三层次 -4. **简单记账**:记录是"进"还是"出" -5. **理赔追踪**:是否需要理赔、理赔金额、理赔结算状态 -6. **附件关联**:通过现有 `wms_file_reference` 表关联附件/图片 - ---- - -## 二、表结构设计 - -### 2.1 主表:`wms_after_sale_work_order`(售后工单主表) - -| # | 字段名 | 类型 | 必填 | 默认值 | 说明 | -|---|--------|------|------|--------|------| -| 1 | `id` | `BIGINT(20) UNSIGNED` | Y | AUTO | 主键ID | -| 2 | `warehouse_id` | `BIGINT(20) UNSIGNED` | Y | — | 仓库ID | -| 3 | `store_id` | `BIGINT(20) UNSIGNED` | Y | — | 货主ID | -| 4 | `work_order_no` | `VARCHAR(50)` | Y | — | 售后工单号,唯一,格式 `AS` + 时间戳(如 AS202607280001) | -| 5 | `business_type` | `VARCHAR(50)` | Y | — | 关联业务类型,见 §3.1 枚举及 §五 Model 内置定义 | -| 6 | `business_sub_type` | `VARCHAR(50)` | Y | — | 关联业务子类型,如运单下的 `intercept`(拦截)、订单下的 `mis_shipment`(错发),见 §五 | -| 7 | `business_id` | `BIGINT(20) UNSIGNED` | Y | — | 关联业务单据主键ID(多态关联) | -| 8 | `business_no` | `VARCHAR(100)` | N | — | 关联业务单据号(冗余,方便列表展示) | -| 9 | `direction` | `TINYINT UNSIGNED` | Y | 0 | 记账方向:`1`=入库(退货入库/换货入库),`2`=出库(补发/换货出库),`0`=未确定 | -| 10 | `status` | `TINYINT UNSIGNED` | Y | 0 | 工单状态,见 §3.4 状态机 | -| 11 | `priority` | `TINYINT UNSIGNED` | Y | 50 | 优先级:`1`~`100`,数字越大优先级越高,由客服接待或AI自动识别填入 | -| 12 | `title` | `VARCHAR(200)` | Y | — | 工单标题/摘要 | -| 13 | `description` | `TEXT` | N | — | 问题描述 | -| 14 | `creator_id` | `BIGINT(20) UNSIGNED` | Y | — | 创建人ID,关联 `account.id`;`0` 表示 AI 自动接待 | -| 15 | `creator_snapshot` | `TEXT` | N | — | 创建人信息快照(JSON格式);AI创建时记录模型/会话信息 | -| 16 | `assignee_id` | `BIGINT(20) UNSIGNED` | N | — | 当前处理人ID,关联 `account.id` | -| 17 | `parent_work_order_id` | `BIGINT(20) UNSIGNED` | N | — | 父工单ID,自关联 `wms_after_sale_work_order.id`;非空时表示当前工单为子工单 | -| 18 | `current_step` | `TINYINT UNSIGNED` | Y | 1 | **当前进度**(位于主表),值为当前正在处理的 `step_order` 序号 | -| 19 | `claim_needed` | `TINYINT UNSIGNED` | Y | 0 | 是否需要理赔:`0`=不需要,`1`=需要 | -| 20 | `claim_amount` | `DECIMAL(12,2)` | N | 0.00 | 理赔金额(元),精度2位小数 | -| 21 | `claim_status` | `TINYINT UNSIGNED` | Y | 0 | 理赔状态:`0`=未理赔,`1`=已理赔(单笔结清),`2`=月结 | -| 22 | `resolution` | `TEXT` | N | — | 处理结果说明 | -| 23 | `resolved_at` | `DATETIME` | N | — | 解决时间 | -| 24 | `created_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP` | 创建时间 | -| 25 | `updated_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP ON UPDATE` | 更新时间 | -| 26 | `deleted_at` | `DATETIME` | N | — | 软删除时间 | - -**索引设计**: - -| 索引名 | 字段 | 类型 | 说明 | -|--------|------|------|------| -| `PRIMARY` | `id` | 主键 | — | -| `uk_work_order_no` | `work_order_no` | 唯一 | 工单号唯一 | -| `idx_warehouse_id` | `warehouse_id` | 普通 | 按仓库查询 | -| `idx_store_id` | `store_id` | 普通 | 按货主查询 | -| `idx_business_type_subtype_id` | `business_type, business_sub_type, business_id` | 普通 | 按业务类型+子类型+单据ID反查工单 | -| `idx_status` | `status` | 普通 | 按状态筛选 | -| `idx_assignee_id` | `assignee_id` | 普通 | 按处理人查询 | -| `idx_parent_work_order_id` | `parent_work_order_id` | 普通 | 按父工单查所有子工单 | -| `idx_priority` | `priority` | 普通 | 按优先级排序 | -| `idx_claim_status` | `claim_status` | 普通 | 按理赔状态筛选 | -| `idx_created_at` | `created_at` | 普通 | 按时间排序 | -| `idx_deleted_at` | `deleted_at` | 普通 | 软删除查询 | - ---- - -### 2.2 副表:`wms_after_sale_work_order_step`(售后工单进度步骤表) - -| # | 字段名 | 类型 | 必填 | 默认值 | 说明 | -|---|--------|------|------|--------|------| -| 1 | `id` | `BIGINT(20) UNSIGNED` | Y | AUTO | 主键ID | -| 2 | `work_order_id` | `BIGINT(20) UNSIGNED` | Y | — | 工单ID,关联 `wms_after_sale_work_order.id` | -| 3 | `step_order` | `TINYINT UNSIGNED` | Y | 1 | 步骤序号(从1开始递增) | -| 4 | `step_name` | `VARCHAR(100)` | Y | — | 步骤名称 | -| 5 | `step_status` | `TINYINT UNSIGNED` | Y | 0 | 步骤状态:`0`=待开始,`1`=进行中,`2`=已完成,`3`=已跳过 | -| 6 | `operator_id` | `BIGINT(20) UNSIGNED` | N | — | 操作员工ID,关联 `account.id` | -| 7 | `operator_snapshot` | `TEXT` | N | — | 操作人信息快照(JSON格式) | -| 8 | `action` | `VARCHAR(100)` | N | — | 操作动作描述(如"核实问题属实,安排退货入库") | -| 9 | `remark` | `TEXT` | N | — | 处理备注 | -| 10 | `started_at` | `DATETIME` | N | — | 步骤开始时间 | -| 11 | `completed_at` | `DATETIME` | N | — | 步骤完成时间 | -| 12 | `created_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP` | 创建时间 | -| 13 | `updated_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP ON UPDATE` | 更新时间 | -| 14 | `deleted_at` | `DATETIME` | N | — | 软删除时间 | - -**索引设计**: - -| 索引名 | 字段 | 类型 | 说明 | -|--------|------|------|------| -| `PRIMARY` | `id` | 主键 | — | -| `idx_work_order_id` | `work_order_id` | 普通 | 按工单查所有步骤 | -| `idx_operator_id` | `operator_id` | 普通 | 按操作人反查 | -| `idx_deleted_at` | `deleted_at` | 普通 | 软删除查询 | -| `uk_work_order_step` | `work_order_id, step_order, deleted_at` | 唯一 | 同一工单下步骤序号唯一(含软删除) | - ---- - -## 三、枚举定义 - -### 3.1 `business_type` 与 `business_sub_type`(业务类型及子类型) - -业务类型和子类型由 Model 文件 `app/model/after_sale_work_order.js` 中的 `BUSINESS_TYPES` 常量统一定义。数据库层面使用 `VARCHAR(50)` 存储,方便扩展。 - -#### 内置业务类型总览 - -| business_type | 业务名称 | 关联表 | 子类型 (business_sub_type) | -|---------------|---------|--------|---------------------------| -| `waybill` | 运单 | `wms_order_express` | `intercept`(拦截)、`urge`(催件)、`damage`(破损)、`lost`(丢件)、`wrong_info`(信息错误) | -| `order_delivery` | 发货订单 | `wms_order_delivery` | `mis_shipment`(错发)、`missing_item`(少发)、`wrong_sku`(错品)、`quality_issue`(质量问题)、`delivery_delay`(发货延迟) | -| `entry_order` | 入库单 | `wms_entry_order` | `shortage`(少货)、`damage`(破损)、`wrong_sku`(错品)、`quality_issue`(质量问题) | -| `order_stockout` | 出库单/退货出库单 | `wms_order_stockout` | `return_issue`(退货异常)、`wrong_outbound`(错发)、`shortage`(少发) | -| `receiving` | 收货单 | `wms_receiving` | `shortage`(少货)、`damage`(破损)、`quality_issue`(质量问题) | -| `other` | 其他 | — | `general`(通用) | - -> **扩展方式**:在 Model 的 `BUSINESS_TYPES` 常量中增删条目即可,无需 ALTER TABLE。外部代码通过 `require` Model 文件读取。 - -### 3.2 `priority`(优先级) - -``` -1 ~ 100 的整数,数字越大优先级越高。 -由客服接待手动填入,或由 AI 根据问题描述自动识别并填入。 -默认值 50(中等优先级)。 -``` - -### 3.3 `direction`(记账方向) - -``` -0 — 未确定 -1 — 入库(IN):退货入库 / 换货入库 / 赔付补货入库 -2 — 出库(OUT):补发出库 / 换货出库 / 退款退货出库 -``` - -> 与 `stock_transaction.transaction_type`(`INBOUND`/`OUTBOUND`)语义对齐。 - -### 3.4 `status`(工单状态) - -``` -0 — 待处理 (工单刚创建,尚未分配) -1 — 处理中 (已分配处理人,正在推进) -2 — 已完成 (问题已解决,全部步骤完成) -3 — 已关闭 (问题关闭,不再跟进) -9 — 已取消 (工单作废) -``` - -### 3.5 `claim_status`(理赔状态) - -``` -0 — 未理赔 (不需要理赔,或尚未发起理赔) -1 — 已理赔 (单笔已结清,理赔款项已到账) -2 — 月结 (纳入月度结算,按月统一对账打款) -``` - -### 3.6 `step_status`(步骤状态) - -``` -0 — 待开始 (步骤尚未激活) -1 — 进行中 (当前正在处理的步骤) -2 — 已完成 (步骤已处理完毕) -3 — 已跳过 (该步骤被跳过,不适用) -``` - -### 3.7 `creator_id` 特殊值 - -``` -0 — AI 自动接待(非员工账号创建) -> 0 — 对应 account.id,人工客服/员工创建 -``` - -> 当 `creator_id = 0` 时,`creator_snapshot` 可记录 AI 模型标识及会话 ID 等元信息。 - ---- - -## 四、状态流转设计 - -### 4.1 工单级别状态机 - -``` - ┌──────────────────────────────────┐ - │ │ - ┌───┴──────┐ ┌───┴──────┐ - 创建工单 ───→ │ 待处理(0) │ ──── 分配处理人 ───→ │ 处理中(1) │ - └───┬──────┘ └───┬──────┘ - │ │ - │ 取消 │ 全部步骤完成 - ↓ ↓ - ┌───┴──────┐ ┌───┴──────┐ - │ 已取消(9) │ │ 已完成(2) │ - └──────────┘ └───┬──────┘ - │ - │ 关闭 - ↓ - ┌───┴──────┐ - │ 已关闭(3) │ - └──────────┘ -``` - -**流转规则**: - -| 当前状态 | 允许流转到 | 触发条件 | -|----------|-----------|----------| -| `0-待处理` | `1-处理中` | 分配处理人 | -| `0-待处理` | `9-已取消` | 主动取消 | -| `1-处理中` | `2-已完成` | 所有步骤均标记为已完成 | -| `1-处理中` | `9-已取消` | 主动取消 | -| `2-已完成` | `3-已关闭` | 确认关闭 | -| `3-已关闭` | — | 终态,不可流转 | - -### 4.2 步骤级别状态机 - -``` - ┌──────────────────────────────────┐ - │ │ - ┌───┴──────┐ ┌───┴──────┐ - 步骤创建 ───→ │ 待开始(0) │ ──── 开始处理 ───→ │ 进行中(1) │ - └───┬──────┘ └───┬──────┘ - │ │ - │ 跳过 │ 完成 - ↓ ↓ - ┌───┴──────┐ ┌───┴──────┐ - │ 已跳过(3) │ │ 已完成(2) │ - └──────────┘ └──────────┘ -``` - -**约束**: -- 同一工单下,同一时刻最多只有 1 个步骤处于 `进行中(1)` -- 步骤按 `step_order` 顺序流转,但允许跳过中间步骤 -- 工单进度由主表 `current_step` 字段追踪,指向当前正在处理的 `step_order` -- 所有步骤标记为 `已完成(2)` 或 `已跳过(3)` 后,`current_step` 置为最终步骤号,工单状态可流转至 `已完成(2)` - ---- - -## 五、Model 内置业务类型定义 - -> **步骤不预设模板**:`wms_after_sale_work_order_step` 表的步骤由业务逻辑在运行时动态创建,不在数据库或 Model 中硬编码步骤模板。 - -### 5.1 `BUSINESS_TYPES` 常量(定义在 `app/model/after_sale_work_order.js`) - -```javascript -/** - * 售后工单业务类型定义 - * 外部可通过 require('./app/model/after_sale_work_order').BUSINESS_TYPES 访问 - * 增删业务类型或子类型只需修改此常量,无需 ALTER TABLE - */ -const BUSINESS_TYPES = { - 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: '发货延迟', - }, - }, - entry_order: { - label: '入库单', - table: 'wms_entry_order', - subtypes: { - shortage: '少货', - damage: '破损', - wrong_sku: '错品', - quality_issue: '质量问题', - }, - }, - order_stockout: { - label: '出库单/退货出库单', - table: 'wms_order_stockout', - subtypes: { - return_issue: '退货异常', - wrong_outbound: '错发', - shortage: '少发', - }, - }, - receiving: { - label: '收货单', - table: 'wms_receiving', - subtypes: { - shortage: '少货', - damage: '破损', - quality_issue: '质量问题', - }, - }, - other: { - label: '其他', - table: null, - subtypes: { - general: '通用', - }, - }, -}; - -// 辅助函数:根据 business_type 获取关联表名 -function getBusinessTable(businessType) { - return BUSINESS_TYPES[businessType]?.table || null; -} - -// 辅助函数:校验 business_type + business_sub_type 组合是否合法 -function isValidSubType(businessType, businessSubType) { - const def = BUSINESS_TYPES[businessType]; - return def && Object.prototype.hasOwnProperty.call(def.subtypes, businessSubType); -} - -module.exports = { BUSINESS_TYPES, getBusinessTable, isValidSubType }; -``` - -### 5.2 使用示例 - -```javascript -// 外部读取 -const { BUSINESS_TYPES, getBusinessTable, isValidSubType } = require('./app/model/after_sale_work_order'); - -// 获取所有业务类型列表 -Object.keys(BUSINESS_TYPES); // ['waybill', 'order_delivery', 'entry_order', ...] - -// 获取运单下的子类型 -BUSINESS_TYPES.waybill.subtypes; // { intercept: '拦截', urge: '催件', ... } - -// 获取关联表 -const table = getBusinessTable('waybill'); // 'wms_order_express' - -// 校验合法性 -isValidSubType('waybill', 'intercept'); // true -isValidSubType('waybill', 'mis_shipment'); // false -``` - ---- - -## 六、与现有系统的关联 - -### 6.1 与业务单据的多态关联(三级定位) - -``` -wms_after_sale_work_order - .business_type = 'waybill' - .business_sub_type = 'intercept' ← 子类型(Model 常量定义) - .business_id = 12345 ← wms_order_express.id - .business_no = 'YD202607280001' ← 冗余单号 - -实际关联链路: - business_type → BUSINESS_TYPES[type].table → 确定关联表 - business_id → 关联表主键 - business_sub_type → 细分工单类别(如拦截/催件/破损) - -示例: - ├── 'waybill' / 'intercept' → wms_order_express.id - ├── 'waybill' / 'urge' → wms_order_express.id - ├── 'waybill' / 'damage' → wms_order_express.id - ├── 'order_delivery' / 'mis_shipment' → wms_order_delivery.id - ├── 'order_delivery' / 'missing_item' → wms_order_delivery.id - ├── 'entry_order' / 'shortage' → wms_entry_order.id - ├── 'order_stockout' / 'return_issue' → wms_order_stockout.id - ├── 'receiving' / 'damage' → wms_receiving.id - └── 'other' / 'general' → 自定义 -``` - -### 6.2 与库存交易的对账 - -``` -售后工单.direction = 1 (入库) - → stock_transaction.transaction_type = 'INBOUND' - → stock_transaction.order_type = 'AFTER_SALE' (需同步在 stock_transaction 中新增此类型) - -售后工单.direction = 2 (出库) - → stock_transaction.transaction_type = 'OUTBOUND' - → stock_transaction.order_type = 'AFTER_SALE' -``` - -### 6.4 与附件的关联 - -售后工单不新增附件字段,复用现有 `wms_file_reference` 表做多态附件关联: - -``` -wms_file_reference - .reference_type = 'after_sale_work_order' ← 固定标识 - .reference_id = 工单 id ← wms_after_sale_work_order.id - .file_id = 文件 id ← wms_file.id - -示例:一张工单可关联多张图片/多个附件(如破损照片、快递面单照片等)。 -``` - -> `file_reference` 表已支持多态关联(`reference_type` + `reference_id`),无需新建表或字段。 - -### 6.5 与员工的关联 - -``` -wms_after_sale_work_order.creator_id → account.id(创建人) -wms_after_sale_work_order.assignee_id → account.id(当前处理人) -wms_after_sale_work_order_step.operator_id → account.id(步骤操作人) -``` - ---- - -## 七、待确认事项(审阅清单) - -请审阅时重点关注以下设计决策: - -- [x] **1. `business_type` 枚举值**:`order_delivery` / `entry_order` / `order_stockout` / `waybill` / `receiving` / `other` — ✅ 已确认,暂不增加 `return_order` 独立类型(退货场景通过 `order_stockout` 覆盖) -- [x] **2. `direction` 记账方向**:`1`=入库 / `2`=出库 / `0`=未确定 — ✅ 已确认,细粒度区分由关联的实际出入库单承载 -- [x] **3. 工单状态值**:`0-待处理/1-处理中/2-已完成/3-已关闭/9-已取消` — ✅ 已确认,当前中间态足够,无需增加"驳回/退回" -- [x] **4. 预设步骤模板**:不再预设步骤模板,步骤由业务逻辑动态创建 ✅ -- [x] **5. `business_id` 多态关联**:采用 `business_type` + `business_sub_type` + `business_id` 三级多态关联,子类型由 Model 常量定义 ✅ -- [x] **6. 理赔信息**:已新增 `claim_needed` / `claim_amount` / `claim_status` 三个字段 ✅ -- [x] **7. 进度追踪**:进度由主表 `current_step` 字段承载(不再仅依赖副表步骤状态) ✅ -- [x] **8. 优先级**:改为 `TINYINT UNSIGNED` 取值范围 `1-100`,由客服或 AI 自动识别填入,默认值 `50` ✅ -- [x] **9. AI 创建支持**:`creator_id = 0` 表示 AI 自动接待,`creator_snapshot` 记录模型/会话信息 ✅ -- [x] **10. 附件/图片**:复用现有 `wms_file_reference` 表做多态关联,不新增字段 ✅ -- [x] **11. 预计完成时间**:暂不增加,后续通过 `created_at` + `priority` 做超时告警替代;SLA 配置表留待后续迭代 ✅ -- [x] **12. 关联工单**:已确认新增 `parent_work_order_id` 字段,支持主子工单拆分 ✅ -- [x] **13. 表名**:`wms_after_sale_work_order` 和 `wms_after_sale_work_order_step` — ✅ 已确认 -- [x] **14. 权限**:API 接口设计阶段再补录 `wms_permission` 记录,不阻塞表落库 ✅ - ---- - -## 八、后续落库计划(审阅通过后执行) - -1. 创建迁移文件 `database/migrations/20260728XXXXXX-create-wms-after-sale-work-order.js` -2. 创建迁移文件 `database/migrations/20260728XXXXXX-create-wms-after-sale-work-order-step.js` -3. 创建 Model 文件 `app/model/after_sale_work_order.js` -4. 创建 Model 文件 `app/model/after_sale_work_order_step.js` -5. 在 `methods/system.json` 中新增接口路由 -6. 如需,在 `stock_transaction.order_type` 中新增 `AFTER_SALE` 枚举值(独立迁移) -7. 如需,新增 `wms_permission` 权限记录 diff --git a/database/migrations/20260728130000-create-wms-after-sale-work-order-step.js b/database/migrations/20260728130000-create-wms-after-sale-work-order-step.js deleted file mode 100644 index 77e2b6f..0000000 --- a/database/migrations/20260728130000-create-wms-after-sale-work-order-step.js +++ /dev/null @@ -1,115 +0,0 @@ -'use strict'; - -const TABLE_NAME = 'wms_after_sale_work_order_step'; - -module.exports = { - up: async (queryInterface, Sequelize) => { - const tables = await queryInterface.showAllTables(); - const exists = tables.some(t => (typeof t === 'string' ? t : t.tableName) === TABLE_NAME); - if (exists) return; - - await queryInterface.createTable(TABLE_NAME, { - id: { - type: Sequelize.BIGINT(20).UNSIGNED, - primaryKey: true, - autoIncrement: true, - allowNull: false, - comment: '主键ID', - }, - work_order_id: { - type: Sequelize.BIGINT(20).UNSIGNED, - allowNull: false, - comment: '工单ID,关联 wms_after_sale_work_order.id', - }, - step_order: { - type: Sequelize.TINYINT.UNSIGNED, - allowNull: false, - defaultValue: 1, - comment: '步骤序号(从1开始递增)', - }, - step_name: { - type: Sequelize.STRING(100), - allowNull: false, - comment: '步骤名称', - }, - step_status: { - type: Sequelize.TINYINT.UNSIGNED, - allowNull: false, - defaultValue: 0, - comment: '步骤状态:0=待开始 1=进行中 2=已完成 3=已跳过', - }, - operator_id: { - type: Sequelize.BIGINT(20).UNSIGNED, - allowNull: true, - comment: '操作员工ID,关联 account.id', - }, - operator_snapshot: { - type: Sequelize.TEXT, - allowNull: true, - comment: '操作人信息快照(JSON格式)', - }, - action: { - type: Sequelize.STRING(100), - allowNull: true, - comment: '操作动作描述', - }, - remark: { - type: Sequelize.TEXT, - allowNull: true, - comment: '处理备注', - }, - started_at: { - type: Sequelize.DATE, - allowNull: true, - comment: '步骤开始时间', - }, - completed_at: { - type: Sequelize.DATE, - allowNull: true, - comment: '步骤完成时间', - }, - created_at: { - type: Sequelize.DATE, - allowNull: false, - defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'), - comment: '创建时间', - }, - updated_at: { - type: Sequelize.DATE, - allowNull: false, - defaultValue: Sequelize.literal('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'), - comment: '更新时间', - }, - deleted_at: { - type: Sequelize.DATE, - allowNull: true, - comment: '软删除时间', - }, - }); - - // 按工单查所有步骤 - await queryInterface.addIndex(TABLE_NAME, [ 'work_order_id' ], { - name: 'idx_work_order_id', - }); - - // 按操作人反查 - await queryInterface.addIndex(TABLE_NAME, [ 'operator_id' ], { - name: 'idx_operator_id', - }); - - // 软删除查询优化 - await queryInterface.addIndex(TABLE_NAME, [ 'deleted_at' ], { - name: 'idx_deleted_at', - }); - - // 同一工单下步骤序号唯一(含软删除) - await queryInterface.addIndex(TABLE_NAME, [ 'work_order_id', 'step_order', 'deleted_at' ], { - unique: true, - name: 'uk_work_order_step', - }); - }, - - down: async queryInterface => { - await queryInterface.dropTable(TABLE_NAME); - }, -}; diff --git a/database/migrations/20260728120000-create-wms-after-sale-work-order.js b/database/migrations/20260809120000-drop-wms-after-sale-work-order.js similarity index 50% rename from database/migrations/20260728120000-create-wms-after-sale-work-order.js rename to database/migrations/20260809120000-drop-wms-after-sale-work-order.js index c6c6ab1..ec379c2 100644 --- a/database/migrations/20260728120000-create-wms-after-sale-work-order.js +++ b/database/migrations/20260809120000-drop-wms-after-sale-work-order.js @@ -1,14 +1,18 @@ -'use strict'; +'use strict'; -const TABLE_NAME = 'wms_after_sale_work_order'; +const TABLE_MAIN = 'wms_after_sale_work_order'; +const TABLE_STEP = 'wms_after_sale_work_order_step'; module.exports = { up: async (queryInterface, Sequelize) => { - const tables = await queryInterface.showAllTables(); - const exists = tables.some(t => (typeof t === 'string' ? t : t.tableName) === TABLE_NAME); - if (exists) return; + // 先删子表(步骤表),再删主表(工单表) + await queryInterface.dropTable(TABLE_STEP); + await queryInterface.dropTable(TABLE_MAIN); + }, - await queryInterface.createTable(TABLE_NAME, { + down: async (queryInterface, Sequelize) => { + // ========== 1. 重建主表:wms_after_sale_work_order ========== + await queryInterface.createTable(TABLE_MAIN, { id: { type: Sequelize.BIGINT(20).UNSIGNED, primaryKey: true, @@ -152,64 +156,101 @@ module.exports = { }, }); - // 工单号唯一 - await queryInterface.addIndex(TABLE_NAME, [ 'work_order_no' ], { - unique: true, - name: 'uk_work_order_no', + await queryInterface.addIndex(TABLE_MAIN, ['work_order_no'], { unique: true, name: 'uk_work_order_no' }); + await queryInterface.addIndex(TABLE_MAIN, ['warehouse_id'], { name: 'idx_warehouse_id' }); + await queryInterface.addIndex(TABLE_MAIN, ['store_id'], { name: 'idx_store_id' }); + await queryInterface.addIndex(TABLE_MAIN, ['business_type', 'business_sub_type', 'business_id'], { name: 'idx_business_type_subtype_id' }); + await queryInterface.addIndex(TABLE_MAIN, ['status'], { name: 'idx_status' }); + await queryInterface.addIndex(TABLE_MAIN, ['assignee_id'], { name: 'idx_assignee_id' }); + await queryInterface.addIndex(TABLE_MAIN, ['parent_work_order_id'], { name: 'idx_parent_work_order_id' }); + await queryInterface.addIndex(TABLE_MAIN, ['priority'], { name: 'idx_priority' }); + await queryInterface.addIndex(TABLE_MAIN, ['claim_status'], { name: 'idx_claim_status' }); + await queryInterface.addIndex(TABLE_MAIN, ['created_at'], { name: 'idx_created_at' }); + await queryInterface.addIndex(TABLE_MAIN, ['deleted_at'], { name: 'idx_deleted_at' }); + + // ========== 2. 重建子表:wms_after_sale_work_order_step ========== + await queryInterface.createTable(TABLE_STEP, { + id: { + type: Sequelize.BIGINT(20).UNSIGNED, + primaryKey: true, + autoIncrement: true, + allowNull: false, + comment: '主键ID', + }, + work_order_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: false, + comment: '工单ID,关联 wms_after_sale_work_order.id', + }, + step_order: { + type: Sequelize.TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 1, + comment: '步骤序号(从1开始递增)', + }, + step_name: { + type: Sequelize.STRING(100), + allowNull: false, + comment: '步骤名称', + }, + step_status: { + type: Sequelize.TINYINT.UNSIGNED, + allowNull: false, + defaultValue: 0, + comment: '步骤状态:0=待开始 1=进行中 2=已完成 3=已跳过', + }, + operator_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: true, + comment: '操作员工ID,关联 account.id', + }, + operator_snapshot: { + type: Sequelize.TEXT, + allowNull: true, + comment: '操作人信息快照(JSON格式)', + }, + action: { + type: Sequelize.STRING(100), + allowNull: true, + comment: '操作动作描述', + }, + remark: { + type: Sequelize.TEXT, + allowNull: true, + comment: '处理备注', + }, + started_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '步骤开始时间', + }, + completed_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '步骤完成时间', + }, + created_at: { + type: Sequelize.DATE, + allowNull: false, + defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'), + comment: '创建时间', + }, + updated_at: { + type: Sequelize.DATE, + allowNull: false, + defaultValue: Sequelize.literal('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'), + comment: '更新时间', + }, + deleted_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '软删除时间', + }, }); - // 仓库隔离查询 - await queryInterface.addIndex(TABLE_NAME, [ 'warehouse_id' ], { - name: 'idx_warehouse_id', - }); - - // 货主隔离查询 - await queryInterface.addIndex(TABLE_NAME, [ 'store_id' ], { - name: 'idx_store_id', - }); - - // 按业务类型+子类型+单据ID反查工单 - await queryInterface.addIndex(TABLE_NAME, [ 'business_type', 'business_sub_type', 'business_id' ], { - name: 'idx_business_type_subtype_id', - }); - - // 按状态筛选 - await queryInterface.addIndex(TABLE_NAME, [ 'status' ], { - name: 'idx_status', - }); - - // 按处理人查询 - await queryInterface.addIndex(TABLE_NAME, [ 'assignee_id' ], { - name: 'idx_assignee_id', - }); - - // 按父工单查子工单 - await queryInterface.addIndex(TABLE_NAME, [ 'parent_work_order_id' ], { - name: 'idx_parent_work_order_id', - }); - - // 按优先级排序 - await queryInterface.addIndex(TABLE_NAME, [ 'priority' ], { - name: 'idx_priority', - }); - - // 按理赔状态筛选 - await queryInterface.addIndex(TABLE_NAME, [ 'claim_status' ], { - name: 'idx_claim_status', - }); - - // 按时间排序 - await queryInterface.addIndex(TABLE_NAME, [ 'created_at' ], { - name: 'idx_created_at', - }); - - // 软删除查询优化 - await queryInterface.addIndex(TABLE_NAME, [ 'deleted_at' ], { - name: 'idx_deleted_at', - }); - }, - - down: async queryInterface => { - await queryInterface.dropTable(TABLE_NAME); + await queryInterface.addIndex(TABLE_STEP, ['work_order_id'], { name: 'idx_work_order_id' }); + await queryInterface.addIndex(TABLE_STEP, ['operator_id'], { name: 'idx_operator_id' }); + await queryInterface.addIndex(TABLE_STEP, ['deleted_at'], { name: 'idx_deleted_at' }); + await queryInterface.addIndex(TABLE_STEP, ['work_order_id', 'step_order', 'deleted_at'], { unique: true, name: 'uk_work_order_step' }); }, };