'use strict'; const { Controller } = require('egg'); const { parsePagination, buildPageResult } = require('../lib/pagination'); /** * @controller OrderStatusController 订单(状态分表) * * 订单按状态分表存储,页面按「待审核 / 待推送 / 异常 / 委外中 / 配送 / 已作废 / 已取消 / 历史」八个视图管理: * - 数据模型:order_index(索引表,订单 ID 全局唯一 + current_table/current_status) * + order_status_pending / queued / exception / outsourcing / delivery / void / canceled(7 张同构状态表) * + order_status_history; * - 状态流转由业务事务推动(审核 / 推送仓库 / 标记推送结果 / 驳回 / 取消 / 作废 / 恢复 / 归档),不提供直接改状态的接口; * 审核 → 待推送 → 推送成功 → 委外中 → 仓库回传确认 → 配送;推送失败 → 异常; * - 列表按 status 定位状态表(历史表另含归档时间/转入时间),筛选条件由 filters 接口提供下拉数据源; * - 数据按主体隔离(principal_id 由 principalCheck 中间件校验后写入 ctx.state.principalId)。 * * 权限点(建议,当前仅菜单可见性用 order:list,操作权限点待产品确认): * order:list 查看 / order:audit 审核 / order:push 推送外部 / order:return 转回待审核 / order:archive 归档 */ class OrderStatusController extends Controller { /** * 统一把服务层异常(err.status)转成业务响应,避免 500 直接抛给前端 * @param {Object} ctx koa 上下文 * @param {Error} err 异常(可带 status) * @param {String} fallbackMessage 兜底提示 * @return {void} 无 */ _fail(ctx, err, fallbackMessage) { const status = Number(err && err.status) || 500; ctx.status = status; ctx.body = { code: status, message: (err && err.message) || fallbackMessage }; if (status >= 500) ctx.logger.error('[order] %s', (err && err.message) || fallbackMessage, err); } /** * 取并校验 ids(订单ID数组) * @return {Array} 订单ID数组 */ _pickIds() { const ids = (this.ctx.request.body || {}).ids; if (!Array.isArray(ids) || !ids.length) { const err = new Error('ids(订单ID数组)为必填项:请至少勾选一条订单'); err.status = 400; throw err; } return ids; } /** * @summary 订单列表 * @description 按 status 定位状态表分页查询(pending 待审核 / queued 待推送 / exception 异常 / * outsourcing 委外中 / delivery 配送 / void 已作废 / canceled 已取消 / history 历史)。 * 支持订单号、来源订单号、店铺、收货人、收货地址、备注(异常原因)、关键词与创建时间区间过滤; * 历史视图另支持归档时间区间。返回行附状态中文、店铺名称与商品明细摘要。 * @router get /api/order-status/list * @apikey * @request query string status 状态(=所在表):pending 待审核(默认)/ queued 待推送 / exception 异常 / outsourcing 委外中 / delivery 配送 / void 已作废 / canceled 已取消 / history 历史 * @request query integer page 页码,默认 1 * @request query integer pageSize 每页条数,默认 20 * @request query string order_no 订单号,模糊匹配 * @request query string parent_order_no 来源订单号,模糊匹配 * @request query integer shop_id 店铺ID * @request query string receiver 收货人,模糊匹配 * @request query string address 收货地址,模糊匹配 * @request query string remark 备注 / 异常原因,模糊匹配 * @request query string keyword 关键词:订单号 / 来源订单号 / 收货人 / 收货地址 * @request query string created_from 创建时间起(YYYY-MM-DD) * @request query string created_to 创建时间止(YYYY-MM-DD) * @request query string archived_from 归档时间起(仅 status=history) * @request query string archived_to 归档时间止(仅 status=history) * @response 200 orderStatusListResponse success */ async index() { const { ctx } = this; const { page, pageSize, offset, limit } = parsePagination(ctx.query); try { const { list, total } = await ctx.service.orderStatus.list({ ...ctx.query, offset, limit }); ctx.body = { code: 0, message: 'success', data: buildPageResult(list, total, { page, pageSize }) }; } catch (err) { this._fail(ctx, err, '查询订单列表失败'); } } /** * @summary 订单筛选项 * @description 返回状态枚举(含中文)、当前主体下的店铺下拉、归档阈值(月)与索引表名, * 供筛选区/表单使用,避免前后端枚举漂移。 * @router get /api/order-status/filters * @apikey * @response 200 orderStatusFiltersResponse success */ async filters() { const { ctx } = this; try { const data = await ctx.service.orderStatus.filters(); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '查询筛选条件失败'); } } /** * @summary 新建订单 * @description 写入索引表(取全局唯一 id)与待审核表,状态为「待审核」。 * 订单号缺省按「来源订单号-序号」生成(序号取索引表中该来源订单号已有订单数 +1)。 * @router post /api/order-status * @apikey * @request body createOrderStatusRequest * @response 200 orderStatusCreateResponse success */ async create() { const { ctx } = this; try { const data = await ctx.service.orderStatus.create(ctx.request.body || {}); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '新建订单失败'); } } /** * @summary 批量审核(待审核 / 异常 → 待推送) * @description 审核即校验明细与店铺并**锁定库存**,通过后进入「待推送」等待推送仓库; * 异常订单可直接审核进入待推送。两个场景按索引表记录的当前所在表自动分流,无需前端区分。 * @router post /api/order-status/audit * @apikey * @request body orderStatusIdsRequest * @response 200 orderStatusTransitionResponse success */ async audit() { const { ctx } = this; try { const data = await ctx.service.orderStatus.audit({ ids: this._pickIds() }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '批量审核失败'); } } /** * @summary 手工标记推送结果(待推送 → 委外中 / 异常) * @description 正常推送走「推送仓库」接口(真实递交 WMS),本接口用于无外部仓库时的手工流转, * 或修正外部实际结果:outcome=success 表示已推送成功(→ 委外中), * outcome=failed 表示推送失败(→ 异常,remark 记录失败原因并释放锁定库存)。 * @router post /api/order-status/push * @apikey * @request body pushOrderStatusRequest * @response 200 orderStatusTransitionResponse success */ async push() { const { ctx } = this; const body = ctx.request.body || {}; try { const data = await ctx.service.orderStatus.push({ ids: this._pickIds(), outcome: body.outcome, remark: body.remark, }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '批量推送外部失败'); } } /** * @summary 批量转回待审核(异常 → 待审核) * @description 异常为侧路状态,可批量回流转正到待审核,重新走审核流程。 * @router post /api/order-status/return-to-pending * @apikey * @request body orderStatusIdsRequest * @response 200 orderStatusTransitionResponse success */ async returnToPending() { const { ctx } = this; try { const data = await ctx.service.orderStatus.returnToPending({ ids: this._pickIds() }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '批量转回待审核失败'); } } /** * @summary 订单详情(单据头 + 商品明细) * @description 按索引表定位订单当前所在状态表并返回单据头,附商品明细、状态中文、店铺/仓库名称。 * @router get /api/order-status/{id} * @apikey * @request path integer *id 订单ID * @response 200 orderStatusDetailResponse success */ async show() { const { ctx } = this; try { const data = await ctx.service.orderStatus.detail({ id: ctx.params.id }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '查询订单详情失败'); } } /** * @summary 编辑订单(仅待审核 / 异常) * @description 未传入字段保持原值;仓库/店铺变更会同步刷新 warehouse_code / shop_nick 快照; * 收件人按「现值 + 本次变更」合并校验(姓名/省/市/区/镇必填,电话与手机至少一个)。 * @router put /api/order-status/{id} * @apikey * @request path integer *id 订单ID * @request body updateOrderStatusRequest * @response 200 orderStatusUpdateResponse success */ async update() { const { ctx } = this; try { const data = await ctx.service.orderStatus.update({ ...(ctx.request.body || {}), id: ctx.params.id }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '编辑订单失败'); } } /** * @summary 删除订单(仅待审核 / 异常 / 已取消) * @description 已审核及之后的订单禁止删除(可改为作废 / 取消);已锁定库存的订单会先释放锁定,避免锁定泄漏。 * @router delete /api/order-status/{id} * @apikey * @request path integer *id 订单ID * @response 200 orderStatusTransitionResponse success */ async destroy() { const { ctx } = this; try { const data = await ctx.service.orderStatus.remove({ ids: [ ctx.params.id ] }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '删除订单失败'); } } /** * @summary 商品明细(按订单ID) * @description 返回该订单的全部商品明细(行号升序),供详情抽屉与明细编辑弹窗使用。 * @router get /api/order-status/items * @apikey * @request query integer order_id 订单ID(必填) * @response 200 orderStatusItemListResponse success */ async items() { const { ctx } = this; try { const data = await ctx.service.orderStatus.listItems({ order_id: ctx.query.order_id }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '查询商品明细失败'); } } /** * @summary 保存商品明细(整体替换,仅待审核 / 异常) * @description 明细整体覆盖写入并重算 item_total(数量合计)/ item_kind(种类数); * 校验口径与老发货单一致:plan_qty > 0、actual_price 必填、item_id/item_code 至少一个、行号不重复。 * @router post /api/order-status/items * @apikey * @request body saveOrderStatusItemsRequest * @response 200 orderStatusItemListResponse success */ async saveItems() { const { ctx } = this; const body = ctx.request.body || {}; try { const data = await ctx.service.orderStatus.saveItems({ order_id: body.order_id, items: body.items }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '保存商品明细失败'); } } /** * @summary 驳回(待推送 → 待审核) * @description 与老发货单一致:驳回即换号(X → X_1 → X_2,避免重推被 WMS 判「单号已存在」), * 释放审核锁定库存并清空审核 / 推送痕迹(重试计数归零); * 已推送成功的(委外中)不支持驳回,请用「取消」(会同步取消外部单据)。 * @router post /api/order-status/reject * @apikey * @request body orderStatusIdsRequest * @response 200 orderStatusSingleFlowResponse success */ async reject() { const { ctx } = this; try { const data = await ctx.service.orderStatus.reject({ ids: this._pickIds() }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '驳回订单失败'); } } /** * @summary 取消(待审核 / 异常 / 待推送 / 委外中 → 已取消) * @description 已推送成功(委外中)的在途订单会先调用 WMS order.cancel 取消外部单据,成功后释放锁定库存再流转; * 已配送 / 已作废 / 已取消不可取消。 * @router post /api/order-status/cancel * @apikey * @request body cancelOrderStatusRequest * @response 200 orderStatusTransitionResponse success */ async cancel() { const { ctx } = this; const body = ctx.request.body || {}; try { const ids = this._pickIds(); const data = await ctx.service.orderStatus.cancel({ ids, remark: body.remark }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '取消订单失败'); } } /** * @summary 作废(待审核 / 异常 / 待推送 → 已作废) * @description 记录作废人 / 作废时间 / 作废原因,并释放审核锁定库存;作废不可恢复也禁止删除; * 已推送成功的(委外中)请用「取消」。 * @router post /api/order-status/void * @apikey * @request body voidOrderStatusRequest * @response 200 orderStatusTransitionResponse success */ async voidOrder() { const { ctx } = this; const body = ctx.request.body || {}; try { const data = await ctx.service.orderStatus.voidOrder({ ids: this._pickIds(), void_reason: body.void_reason, remark: body.remark, }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '作废订单失败'); } } /** * @summary 恢复(已取消 / 已作废 → 待审核) * @description 曾推送过的订单恢复时换号(WMS 侧单号唯一,取消/作废后原号仍被占用), * 并清空审核 / 推送痕迹与作废原因。 * @router post /api/order-status/restore * @apikey * @request body orderStatusIdsRequest * @response 200 orderStatusSingleFlowResponse success */ async restore() { const { ctx } = this; try { const data = await ctx.service.orderStatus.restore({ ids: this._pickIds() }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '恢复订单失败'); } } /** * @summary 推送仓库(WMS deliveryorder.create) * @description 待推送订单立即递交一次到 WMS:成功流转「委外中」并写 wms_status/wms_order_no(等仓库回传确认进入配送); * 对方明确失败或连续 3 次无响应则转「异常」并释放锁定库存。 * @router post /api/order-status/{id}/push-wms * @apikey * @request path integer *id 订单ID * @response 200 orderStatusPushWmsResponse success */ async pushWms() { const { ctx } = this; try { const result = await ctx.service.orderWms.pushOne(ctx.params.id, { source: 'manual' }); if (!result.ok) { ctx.status = result.skipped ? 400 : 502; ctx.body = { code: ctx.status, message: result.message }; return; } ctx.body = { code: 0, message: 'success', data: { id: Number(ctx.params.id), attempts: result.attempts, wms_response: result.response }, }; } catch (err) { this._fail(ctx, err, '推送仓库失败'); } } /** * @summary 批量推送仓库 * @description 对选中的待推送订单顺序限流推送(每次最多 50 条,其余由定时任务继续),返回逐单结果。 * @router post /api/order-status/push-wms * @apikey * @request body orderStatusIdsRequest * @response 200 orderStatusPushWmsBatchResponse success */ async pushWmsBatch() { const { ctx } = this; try { const ids = this._pickIds().map(id => Number(id)); const data = await ctx.service.orderWms.pushMany(ids); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '批量推送仓库失败'); } } /** * @summary 批量切换仓库 * @description 待审核 / 异常 / 待推送的订单可切换仓库(同步刷新 warehouse_code 快照); * 已推送仓库后不再变更(仓库编码已递交 WMS)。 * @router post /api/order-status/change-warehouse * @apikey * @request body changeOrderStatusWarehouseRequest * @response 200 orderStatusChangeOwnerResponse success */ async changeWarehouse() { const { ctx } = this; const body = ctx.request.body || {}; try { const data = await ctx.service.orderStatus.changeWarehouse({ ids: this._pickIds(), warehouse_id: body.warehouse_id }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '切换仓库失败'); } } /** * @summary 批量设置所属店铺 * @description 店铺只影响推送时的快递策略匹配(shopNick)与 OMS 记录、不回写 WMS, * 因此委外中也允许修正(同步刷新 shop_nick 快照)。 * @router post /api/order-status/change-shop * @apikey * @request body changeOrderStatusShopRequest * @response 200 orderStatusChangeOwnerResponse success */ async changeShop() { const { ctx } = this; const body = ctx.request.body || {}; try { const data = await ctx.service.orderStatus.changeShop({ ids: this._pickIds(), shop_id: body.shop_id }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '设置所属店铺失败'); } } /** * @summary 智能识别收件人文本 * @description 把「姓名 电话 地址」等自由文本解析为收件人字段,供新增/编辑表单一键填充。 * @router post /api/order-status/parse-receiver * @apikey * @request body parseReceiverRequest *body * @response 200 baseResponse success */ async parseReceiver() { const { ctx } = this; const text = String((ctx.request.body || {}).text || '').trim(); if (!text) { ctx.status = 400; ctx.body = { code: 400, message: 'text(待识别的文本)为必填项' }; return; } try { const data = await ctx.service.ai.parseReceiver(text); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '智能识别失败,请稍后重试'); } } /** * @summary 归档到历史(写入归档时间 / 转入时间) * @description 传 ids 时归档指定订单;不传 ids 时归档当前主体下创建时间超过 months(默认 3)个月的订单。 * 归档为物理迁移:状态表删除 + 历史表插入,并写入 archived_at / transferred_at。 * 定时任务(app/schedule/orderArchive.js)同样走本逻辑,但跨主体处理。 * @router post /api/order-status/archive * @apikey * @request body archiveOrderStatusRequest * @response 200 orderStatusArchiveResponse success */ async archive() { const { ctx } = this; const body = ctx.request.body || {}; try { const data = await ctx.service.orderStatus.archive({ ids: body.ids, months: body.months }); ctx.body = { code: 0, message: 'success', data }; } catch (err) { this._fail(ctx, err, '归档到历史失败'); } } } module.exports = OrderStatusController;