- 外部打单平台快递接口:按账号同步平台模板、绑定快递编码、查看模板明细;打开列表只读库,仅「从平台同步数据」时拉取 - 系统管理新增自定义快递编码字典,订单改快递 / 物流下拉合并系统与自定义编码,推送奇门沿用订单上的编码 - 新增 OpenAPI deliveryorder.getwaybill:WMS 批量回取号(单次≤100、并发4、逐单结果),快递编码只取 WMS 报文,取消/作废/归档返回失败,已取号直接复用 - 新增 openapi_request_idempotency 请求级幂等:request_id 回放、报文摘要校验、30 分钟 stale 接管、7 天定时清理 - 外部打单平台订单按平台 fetch_waybill_no 下发 need_oms_waybill,推送时实时判定并回写单据 - 店铺、打单账号平台配置与「平台+编码→模板」绑定走 Redis 缓存,绑定/账号变更主动失效,避免批量推送与取号逐单查库 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
500 lines
20 KiB
JavaScript
500 lines
20 KiB
JavaScript
'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)
|
||
* @request query integer exclude_unbound 传 1 时排除含未绑定商品明细的订单(前端「查看未绑定商品订单」开关关闭时使用)
|
||
* @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;
|