# 售后工单表设计方案 > **状态**: ✅ 已落库(开发环境) > **设计日期**: 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` 权限记录