oms/backend/app/controller/orderStatus.js
liufumingren 9a944be886 feat(order): 订单列表展示电商平台,支持按电商平台筛选与平台单号批量查询
- 列表新增「电商平台」列(优先用落库的平台名称,缺失时按编码映射中文名),详情面板同口径展示
- 筛选新增电商平台多选(platform_codes)与平台单号批量精确匹配(platform_order_nos,最多 200 个)
- 平台单号批量查询复用 MultiValueFilter:收起时英文逗号拼接、展开后一行一个,与店铺商品的商家编码一致
- 订单导出同步支持这两个筛选,并新增「电商平台」导出列

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-07 00:28:42 +08:00

505 lines
21 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

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

'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 platform_codes 电商平台编码,多选用逗号分隔(PDD / DYXD / SPH…,见系统预设平台编码)
* @request query string platform_order_nos 平台单号,多个精确匹配用逗号分隔(最多 200 个)
* @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)
* @request query integer exclude_unbound 传 1 时排除含未绑定商品明细的订单(前端「查看未绑定商品订单」开关关闭时使用)
* @request query string external_send_status 同步外部发货状态筛选(0待同步 1已同步 2待重试 3异常;多选用逗号分隔,仅配送视图有意义)
* @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 仅待审核订单可修改;支持系统快递公司或自定义快递编码(启用项),
* 并同步更新 logistics_code / logistics_name 快照(推送奇门时原样下发)。
* @router post /api/order-status/change-logistics
* @apikey
* @request body changeOrderStatusLogisticsRequest
* @response 200 orderStatusChangeLogisticsResponse success
*/
async changeLogistics() {
const { ctx } = this;
const body = ctx.request.body || {};
try {
const data = await ctx.service.orderStatus.changeLogistics({
ids: this._pickIds(),
logistics_code: body.logistics_code,
});
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;