feat: 新增运单退回登记模块(returnWaybill)并同步接口文档

- 复用 wms_return_query_log 表,提供货主+运单号退回登记增删查改(create/update/list/detail/delete)
- create 幂等(同仓库+货主+运单号返回已有);货主合约校验;update 冲突 409
- 权限固定 ID 551-555 + 角色授权迁移
- 同步 methods/system.json 退回拆包/运单退回登记模块与 changes 变更记录
This commit is contained in:
liufumingren 2026-08-13 21:40:57 +08:00
parent 38b29be776
commit 2d1b9e98fa
5 changed files with 2024 additions and 92 deletions

View File

@ -0,0 +1,132 @@
'use strict';
const MainService = require('../main');
/**
* 系统方法层:returnWaybill(运单退回登记模块接口包装层)。
* 主要职责:统一包装系统方法接口,处理权限、where 解析等公共逻辑,
* 将具体业务逻辑下沉到 systems.return_waybill 中。
*/
class ReturnWaybillMethodService extends MainService {
constructor(ctx) {
super(ctx);
// 免登录方法列表:空(全部需要登录)
const _noNeedLogin = '';
// 免权限方法列表:detail 复用列表权限(仅登录 + 仓库隔离校验),其余走 API 权限校验
const _noNeedRight = 'detail';
// 免日志方法列表:空(全部记录日志)
const _noNeedLog = '';
// 免鉴权(仓库有效期检查)方法列表:空(全部检查有效期)
const _noNeedAuth = '';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
/**
* 统一调用运单退回登记业务服务,并捕获业务错误码。
*
* @param {Function} fn 业务调用函数。
* @param {string} fallbackMessage 兜底错误文案。
* @return {Promise<Object>} 统一 success/fail 包装。
*/
async _call(fn, fallbackMessage) {
try {
const result = await fn();
return this.success('ok', result);
} catch (error) {
const code = Number(error && error.code);
if (Number.isInteger(code) && code >= 400 && code < 600) {
return this.fail(error.message || fallbackMessage, {}, code);
}
this.ctx.logger.error(`[returnWaybill] ${fallbackMessage}: ${error && error.message ? error.message : error}`);
return this.fail('服务器内部错误', {}, 500);
}
}
/**
* 运单退回登记(增)。
*
* @param {Object} data 请求体。
* @param {string} data.waybill_code 运单号。
* @param {number} data.store_id 货主ID。
* @param {string} [data.remark] 备注。
* @return {Promise<Object>} 统一 success 包装。
*/
async create(data = {}) {
const { waybill_code, store_id, remark } = data;
return this._call(
() => this.service.systems.returnWaybill.create({ waybill_code, store_id, remark }),
'登记失败'
);
}
/**
* 修改登记(改)。
*
* @param {Object} data 请求体。
* @param {number} data.id 登记记录ID。
* @param {string} [data.waybill_code] 运单号。
* @param {number} [data.store_id] 货主ID。
* @param {string} [data.remark] 备注。
* @return {Promise<Object>} 统一 success 包装。
*/
async update(data = {}) {
const { id, waybill_code, store_id, remark } = data;
return this._call(
() => this.service.systems.returnWaybill.update({ id, waybill_code, store_id, remark }),
'修改登记失败'
);
}
/**
* 分页查询登记列表(查,仓库隔离自动注入)。
*
* @param {Object} data 请求体。
* @param {Object} [data.pagination] 分页参数。
* @param {Object} [data.where] 筛选条件。
* @param {Object} [data.sort] 排序参数。
* @return {Promise<Object>} 统一 success 包装。
*/
async list(data = {}) {
const { service } = this;
const { pagination, sort } = data;
const { where } = this.prepareWhereContext(data, {});
// 仓库隔离:由服务端从当前上下文自动注入,禁止前端传入
const warehouseId = Number(this.ctx.user && this.ctx.user.store_id || 0);
const enforcedWhere = { ...where };
if (warehouseId > 0) {
enforcedWhere.warehouse_id = { operator: 'eq', value: warehouseId };
}
return this._call(
() => service.systems.returnWaybill.list(enforcedWhere, pagination, sort),
'查询列表失败'
);
}
/**
* 查询单条登记详情(查)。
*
* @param {Object} data 请求体。
* @param {number} data.id 登记记录ID。
* @return {Promise<Object>} 统一 success 包装。
*/
async detail(data = {}) {
const { id } = data;
return this._call(() => this.service.systems.returnWaybill.detail(Number(id)), '查询详情失败');
}
/**
* 删除单条登记(删)。
*
* @param {Object} data 请求体。
* @param {number} data.id 登记记录ID。
* @return {Promise<Object>} 统一 success 包装。
*/
async delete(data = {}) {
const { id } = data;
return this._call(() => this.service.systems.returnWaybill.delete(Number(id)), '删除失败');
}
}
module.exports = ReturnWaybillMethodService;

View File

@ -0,0 +1,371 @@
'use strict';
const Service = require('egg').Service;
/**
* 运单退回登记模块业务逻辑层。
* 复用 wms_return_query_log 表,提供「货主 + 运单号」退回登记的增删查改。
* 所有数据库交互集中在此层,供 systemMethods/returnWaybill.js 调用。
*/
class ReturnWaybillService extends Service {
/**
* 创建带业务错误码的异常对象。
*
* @param {string} message 错误信息。
* @param {number} [code=400] 业务错误码。
* @return {Error} 包含 code 的异常对象。
*/
createBusinessError(message, code = 400) {
const error = new Error(`${message}`);
error.code = code;
return error;
}
/**
* 运单退回登记(增)。入参:运单号 + 货主ID。
* 同 warehouse_id + store_id + waybill_code 已存在时返回已有记录(幂等)。
*
* @param {Object} params 登记参数。
* @param {string} params.waybill_code 运单号(必填)。
* @param {number} params.store_id 货主ID(必填)。
* @param {string} [params.remark] 备注。
* @return {Promise<Object>} { record, duplicated }。
*/
async create({ waybill_code, store_id, remark }) {
const { ctx } = this;
const waybillCode = String(waybill_code || '').trim();
if (!waybillCode) {
throw this.createBusinessError('waybill_code 不能为空', 400);
}
const storeId = Number(store_id || 0);
if (!Number.isFinite(storeId) || storeId <= 0) {
throw this.createBusinessError('store_id 必填且必须为正整数', 400);
}
const warehouseId = Number(ctx.user && ctx.user.store_id || 0);
if (!Number.isFinite(warehouseId) || warehouseId <= 0) {
throw this.createBusinessError('缺少仓库上下文', 400);
}
// 货主合约校验:wms_store_warehouse 存在 store_id + warehouse_id 合约
await this._assertStoreContract(storeId, warehouseId);
// 幂等:同仓库+货主+运单号已存在 → 返回已有记录
const existing = await ctx.model.ReturnQueryLog.findOne({
where: {
warehouse_id: warehouseId,
store_id: storeId,
waybill_code: waybillCode,
},
order: [[ 'id', 'ASC' ]],
raw: true,
});
if (existing) {
return { record: this._formatRow(existing), duplicated: true };
}
const created = await ctx.model.ReturnQueryLog.create({
warehouse_id: warehouseId,
store_id: storeId,
waybill_code: waybillCode,
remark: remark ? String(remark).slice(0, 500) : null,
is_notified: 0,
is_back: 0,
});
const createdRow = created && typeof created.toJSON === 'function' ? created.toJSON() : created;
return { record: this._formatRow(createdRow), duplicated: false };
}
/**
* 修改登记(改)。入参:id + 可改运单号/货主ID/备注。
*
* @param {Object} params 修改参数。
* @param {number} params.id 登记记录ID(必填)。
* @param {string} [params.waybill_code] 运单号。
* @param {number} [params.store_id] 货主ID。
* @param {string} [params.remark] 备注。
* @return {Promise<Object>} { record }。
*/
async update({ id, waybill_code, store_id, remark }) {
const { ctx } = this;
const { Op } = ctx.app.Sequelize;
const record = await this._findByIdChecked(id);
const updateFields = {};
const nextWaybillCode = waybill_code !== undefined && waybill_code !== null
? String(waybill_code).trim()
: record.waybill_code;
if (!nextWaybillCode) {
throw this.createBusinessError('waybill_code 不能为空', 400);
}
const nextStoreId = store_id !== undefined && store_id !== null
? Number(store_id)
: Number(record.store_id);
if (!Number.isFinite(nextStoreId) || nextStoreId <= 0) {
throw this.createBusinessError('store_id 必填且必须为正整数', 400);
}
if (waybill_code !== undefined && waybill_code !== null) {
updateFields.waybill_code = nextWaybillCode;
}
if (store_id !== undefined && store_id !== null && Number(store_id) !== Number(record.store_id)) {
// 货主变更时校验新货主合约
await this._assertStoreContract(nextStoreId, record.warehouse_id);
updateFields.store_id = nextStoreId;
}
if (remark !== undefined && remark !== null) {
updateFields.remark = String(remark).slice(0, 500);
}
// 冲突防护:改后与另一条同仓库+货主+运单号冲突则拒绝
const changed = Object.keys(updateFields).length > 0;
if (changed) {
const conflict = await ctx.model.ReturnQueryLog.findOne({
where: {
warehouse_id: record.warehouse_id,
store_id: nextStoreId,
waybill_code: nextWaybillCode,
id: { [Op.ne]: record.id },
},
attributes: [ 'id' ],
raw: true,
});
if (conflict) {
throw this.createBusinessError('已存在相同货主 + 运单号的登记记录', 409);
}
await ctx.model.ReturnQueryLog.update(updateFields, {
where: { id: record.id },
});
}
const updated = await ctx.model.ReturnQueryLog.findOne({
where: { id: record.id },
raw: true,
});
return { record: this._formatRow(updated) };
}
/**
* 分页查询登记列表(仓库隔离由方法层注入 warehouse_id)。
*
* @param {Object} where 标准化 where 条件对象。
* @param {Object} [pagination] 分页参数。
* @param {Object} [sort] 排序参数。
* @return {Promise<Object>} { list, pagination }。
*/
async list(where = {}, pagination = {}, sort = {}) {
const { ctx, app } = this;
const { Op } = app.Sequelize;
const page = Math.max(1, parseInt(pagination.page) || 1);
const pageSize = Math.min(500, Math.max(1, parseInt(pagination.pageSize) || 20));
const queryWhere = this._buildListWhere(where, Op);
const order = this._buildListOrder(sort);
const { count, rows } = await ctx.model.ReturnQueryLog.findAndCountAll({
where: queryWhere,
order,
offset: (page - 1) * pageSize,
limit: pageSize,
raw: true,
});
return {
list: rows.map(row => this._formatRow(row)),
pagination: {
page,
pageSize,
total: count,
totalPages: Math.ceil(count / pageSize),
hasPrevious: page > 1,
hasNext: page * pageSize < count,
},
};
}
/**
* 查询单条登记详情。
*
* @param {number} id 登记记录ID。
* @return {Promise<Object>} { record }。
*/
async detail(id) {
const record = await this._findByIdChecked(id);
return { record: this._formatRow(record) };
}
/**
* 删除单条登记(物理删除)。
*
* @param {number} id 登记记录ID。
* @return {Promise<Object>} 删除结果,含被删除记录 id。
*/
async delete(id) {
const { ctx } = this;
const record = await this._findByIdChecked(id);
await ctx.model.ReturnQueryLog.destroy({ where: { id: record.id } });
return { id: record.id };
}
// ===========================
// 辅助方法
// ===========================
/**
* 按主键查询登记记录,并校验仓库隔离。
*
* @param {number} id 登记记录ID。
* @return {Promise<Object>} 登记记录原始数据。
*/
async _findByIdChecked(id) {
const { ctx } = this;
const normalizedId = Number(id || 0);
if (!Number.isFinite(normalizedId) || normalizedId <= 0) {
throw this.createBusinessError('id 必填且必须为正整数', 400);
}
const record = await ctx.model.ReturnQueryLog.findOne({
where: { id: normalizedId },
raw: true,
});
if (!record) {
throw this.createBusinessError('登记记录不存在', 404);
}
const warehouseId = Number(ctx.user && ctx.user.store_id || 0);
if (warehouseId > 0 && Number(record.warehouse_id) !== warehouseId) {
throw this.createBusinessError('无权访问该登记记录', 403);
}
return record;
}
/**
* 货主合约校验:wms_store_warehouse 必须存在 store_id + warehouse_id 合约。
*
* @param {number} storeId 货主ID。
* @param {number} warehouseId 仓库ID。
* @return {Promise<void>} 校验失败抛业务异常。
*/
async _assertStoreContract(storeId, warehouseId) {
const { ctx } = this;
const contract = await ctx.model.StoreWarehouse.findOne({
where: { store_id: storeId, warehouse_id: warehouseId },
attributes: [ 'id' ],
raw: true,
});
if (!contract) {
throw this.createBusinessError('货主在当前仓库无合约关系,无法登记', 400);
}
}
/**
* 格式化登记记录(时间字段本地化)。
*
* @param {Object} row 登记记录原始数据。
* @return {Object} 格式化后的记录。
*/
_formatRow(row) {
const { app } = this;
const record = { ...row };
record.created_at = record.created_at ? app.formatDate(record.created_at) : null;
record.updated_at = record.updated_at ? app.formatDate(record.updated_at) : null;
return record;
}
/**
* 根据标准化 where 条件构建 Sequelize 查询条件。
*
* @param {Object} where 标准化 where 条件对象。
* @param {Object} Op Sequelize Op 对象。
* @return {Object} Sequelize where 条件。
*/
_buildListWhere(where = {}, Op) {
const queryWhere = {};
const fields = [
'warehouse_id', 'store_id', 'waybill_code',
'is_notified', 'is_back', 'created_at', 'updated_at',
];
for (const field of fields) {
if (where[field] !== undefined && where[field] !== null) {
queryWhere[field] = this._resolveConditionValue(where[field], Op);
}
}
return queryWhere;
}
/**
* 解析标准化条件值为 Sequelize 可用的条件对象。
*
* @param {*} condition 标准化条件(可能是 {operator, value} 或直接值)。
* @param {Object} Op Sequelize Op 对象。
* @return {*} Sequelize 条件。
*/
_resolveConditionValue(condition, Op) {
if (condition && typeof condition === 'object' && !Array.isArray(condition)) {
const operator = condition.operator;
const value = condition.value;
if (!operator) {
return value;
}
switch (operator) {
case 'eq':
return value;
case 'ne':
return { [Op.ne]: value };
case 'in':
return { [Op.in]: Array.isArray(value) ? value : [ value ] };
case 'notin':
return { [Op.notIn]: Array.isArray(value) ? value : [ value ] };
case 'like':
return { [Op.like]: `%${value}%` };
case 'gt':
return { [Op.gt]: value };
case 'gte':
return { [Op.gte]: value };
case 'lt':
return { [Op.lt]: value };
case 'lte':
return { [Op.lte]: value };
case 'between':
return { [Op.between]: Array.isArray(value) ? value : [ value ] };
default:
return value;
}
}
return condition;
}
/**
* 根据 sort 参数构建 Sequelize 排序数组。
*
* @param {Object} sort 排序参数。
* @return {Array<Array<string>>} Sequelize order 数组。
*/
_buildListOrder(sort = {}) {
const sortField = sort.sortField || sort.sort_field || 'created_at';
const sortOrderRaw = (sort.sortOrder || sort.sort_order || 'desc').toLowerCase();
const sortOrder = sortOrderRaw === 'asc' ? 'ASC' : 'DESC';
const allowedSortFields = new Set([ 'id', 'created_at', 'updated_at', 'waybill_code' ]);
const safeSortField = allowedSortFields.has(sortField) ? sortField : 'created_at';
return [[ safeSortField, sortOrder ]];
}
}
module.exports = ReturnWaybillService;

View File

@ -0,0 +1,104 @@
'use strict';
/**
* 运单退回登记模块权限记录 + 角色授权迁移。
*
* 权限明细(固定 ID 551-555,550 预留):
* 551 — returnWaybill.create API:运单退回登记
* 552 — returnWaybill.update API:运单退回登记修改
* 553 — returnWaybill.list API:运单退回登记列表
* 554 — returnWaybill.detail API:运单退回登记详情
* 555 — returnWaybill.delete API:运单退回登记删除
*
* 角色授权(系统预设角色,不含通配符角色):
* 作业类(551-552)→ 仓库组-员工(27) → 仓库组-主管(26)(仓库员工及以上)
* 查询/删除类(553-555)→ 客服组-员工(30) → 客服组-主管(28)(客服员工及以上)
* 经理(8)/仓库管理员(2)/超级管理员(7) 已持有 * 通配符,自动拥有所有权限,无需处理
*
* 幂等:INSERT IGNORE 创建权限记录;角色权限数组追加后去重排序,已存在跳过。
*/
const TABLE = 'wms_permission';
const ROLE_TABLE = 'wms_role';
const COLUMNS = 'id, path, component, name, redirect, meta_title, meta_icon, hidden, always_show, parent_id, type, sort, status, created_at, update_at';
/** 权限ID → 授权角色ID列表(不含通配符角色) */
const PERMISSION_ROLES = {
551: [ 27, 26 ],
552: [ 27, 26 ],
553: [ 30, 28 ],
554: [ 30, 28 ],
555: [ 30, 28 ],
};
module.exports = {
// eslint-disable-next-line no-unused-vars
async up(queryInterface, Sequelize) {
// ── 1. 创建 API 权限记录(固定 ID)──
const apis = [
[ 551, 'returnWaybill.create', 'API:运单退回登记' ],
[ 552, 'returnWaybill.update', 'API:运单退回登记修改' ],
[ 553, 'returnWaybill.list', 'API:运单退回登记列表' ],
[ 554, 'returnWaybill.detail', 'API:运单退回登记详情' ],
[ 555, 'returnWaybill.delete', 'API:运单退回登记删除' ],
];
for (const [ id, path, metaTitle ] of apis) {
await queryInterface.sequelize.query(
`INSERT IGNORE INTO \`${TABLE}\` (${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NOW(), NOW())`,
{ replacements: [ id, path, null, path, null, metaTitle, null, 0, 0, null, 'api', 0, 1 ] }
);
}
// ── 2. 角色授权注入 ──
for (const permId of Object.keys(PERMISSION_ROLES).map(Number)) {
for (const roleId of PERMISSION_ROLES[permId]) {
const rows = await queryInterface.sequelize.query(
`SELECT id, permissions FROM \`${ROLE_TABLE}\` WHERE id = ?`,
{ replacements: [ roleId ], type: queryInterface.sequelize.QueryTypes.SELECT }
);
const record = Array.isArray(rows) ? rows[0] : null;
if (!record) {
continue;
}
// 通配符角色跳过
if (record.permissions === '*') {
continue;
}
let perms;
try {
perms = JSON.parse(record.permissions || '[]');
} catch (err) {
continue;
}
if (!Array.isArray(perms)) {
continue;
}
if (perms.includes(permId)) {
continue;
}
perms.push(permId);
perms.sort((a, b) => a - b);
await queryInterface.sequelize.query(
`UPDATE \`${ROLE_TABLE}\` SET permissions = ? WHERE id = ?`,
{ replacements: [ JSON.stringify(perms), roleId ] }
);
}
}
},
// eslint-disable-next-line no-unused-vars
async down(queryInterface, Sequelize) {
const ids = [ 551, 552, 553, 554, 555 ];
const placeholders = ids.map(() => '?').join(', ');
await queryInterface.sequelize.query(
`DELETE FROM \`${TABLE}\` WHERE id IN (${placeholders})`,
{ replacements: ids }
);
},
};

View File

@ -1,4 +1,21 @@
[
{
"version": "2026.08.13-stockQueryWhere",
"date": "2026-08-13",
"type": "added",
"summary": "storage.receiving.getReceivingList / getStoreReceivingList 新增 stock_query_where 参数:按商品条码/商品编码/商品ID 搜索,经收货明细关联过滤收货单列表(仓库侧与货主侧同步支持)",
"methods": [
"storage.receiving.getReceivingList",
"storage.receiving.getStoreReceivingList"
],
"notes": [
"新增 stock_query_where 入参(string|string[], optional, body,前端通常传数组),搜索范围:wms_stock_barcodes.barcode + wms_stock_warehouse.item_code + wms_stock_warehouse.id(纯数字时精确匹配)",
"解析链路:stock_query_where → wms_stock_warehouse.id 集合 → wms_receiving_detail.system_product_id IN 集合 → receiving_id 列表",
"与 filterDepleted、entry_order_id 可组合使用(多组过滤取交集,仓库侧),无匹配结果时返回空列表",
"代码变更:systems/storage/receiving.js 新增 _resolveStockQueryReceivingIds 并对两个列表方法注入过滤;systemMethods/storage/receiving.js 两个列表方法均透传 stock_query_where;methods/system.json 两个接口均新增参数文档"
],
"module": "storage"
},
{
"version": "2026.08.12-confirmIntercept-doc",
"date": "2026-08-12",
@ -5775,5 +5792,129 @@
"代码变更:app/model/return_received.js、app/service/systems/return_received.js、app/service/systemMethods/returnReceived.js、database/migrations/20260812160000-create-wms-return-received.js、20260813100000-create-return-received-permissions.js"
],
"module": "returnReceived"
},
{
"version": "2026.08.13-shops-GetAuthorizeSessionKey-doc-sync",
"date": "2026-08-13",
"type": "updated",
"summary": "同步 shops.GetAuthorizeSessionKey 文档:实现已切换为调用授权服务 saveShop 换取授权会话,旧的 PDD/CAINIAO 预占码方案已下线。",
"methods": [
"shops.GetAuthorizeSessionKey"
],
"notes": [
"实现:按店铺 platform_code 取 wms_print_platform.get_auth_platform_name 作为 platName,POST 授权服务 saveShop,携带 RedirectCodeUrl/shopName;京东平台附 VenderID,视频号平台改传 appId/toUserName 且不带 RedirectCodeUrl",
"成功后更新店铺 access_token=sessionKey、status=1,返回 data.message='获取授权成功';上游 code≠0 或未返回 sessionKey 时抛 500",
"文档更新:移除旧 data.session_key/authorize_url/state 返回结构与 501 未实现错误,补充 appId/toUserName 入参及 shop_id/callbackurl/platform_code 校验错误码",
"仅文档同步,不修改业务代码"
],
"module": "shops"
},
{
"version": "2026.08.13-interceptScan-non-intercept-guard",
"date": "2026-08-13",
"type": "updated",
"summary": "order.recheckOrder.interceptScan 增加非拦截订单前置校验:运单不存在或未发起系统拦截时直接拒绝并提示「非拦截订单」,移除原先自动创建运单补充记录的逻辑。",
"methods": [
"order.recheckOrder.interceptScan"
],
"notes": [
"校验规则:运单记录不存在即拒绝;运单 is_intercept≠'Y' 时回查关联订单,intercept_status 不在 requested/intercepting 也拒绝,提示「非拦截订单」",
"校验通过后原逻辑不变:标记 is_back='Y'/is_intercept='Y'、处理未完结售后工单、订单级更新 intercepted_at_warehouse 并释放储位分配与订单锁",
"移除运单不存在时自动创建补充记录的分支(未发起拦截的运单不再被静默置为拦截)",
"同步更新 JSDoc 与 methods/system.json 文档,错误码新增 400 非拦截订单"
],
"module": "order.recheckOrder"
},
{
"version": "2026.08.13-returnUnpack",
"date": "2026-08-13",
"type": "added",
"summary": "新增退回拆包模块(returnUnpack):开拆包单、录明细、更新明细、移除明细、取消、提交确认、分页列表、明细列表、详情、删除十个接口。开单反查原运单判定原单退回并回填货主,未命中原单时按 warehouse_id+waybill_code 从退回查询记录反查货主;拆包单号 RP+YYYYMMDD+6位序号;状态机 unpacking/completed/cancelled;明细识别状态 none_recognized/partial_recognized/all_recognized;全接口仓库隔离(服务端注入 warehouse_id)。配套权限 540-549(作业类→仓库员工及以上,查询/删除类→客服员工及以上,detail 免权限复用列表权限)",
"methods": [
"returnUnpack.create",
"returnUnpack.addDetail",
"returnUnpack.updateDetail",
"returnUnpack.removeDetail",
"returnUnpack.cancel",
"returnUnpack.submit",
"returnUnpack.list",
"returnUnpack.detailList",
"returnUnpack.detail",
"returnUnpack.delete"
],
"notes": [
"新增表 wms_return_unpack(主表)/ wms_return_unpack_detail(明细)/ wms_return_unpack_video(视频,paranoid 软删)/ wms_return_query_log(退回查询记录)",
"returnUnpack.create:waybill_code 必填;反查 wms_order_express.waybill_code 命中则回填 order_express_id/order_id/store_id 并返回原订单详情(复用 afterSale._resolveOrderDetail);未命中再从 wms_return_query_log 按 warehouse_id+waybill_code 反查货主(限最近 3 个月内登记);返回 id/record/is_original_return/store_remark/order",
"returnUnpack.addDetail:主单非终态校验;stock_id 有值 → 查 wms_stock_warehouse 校验货主归属(不一致 403)+ 回填 is_recognized=1 与快照;主表 store_id 为空时以首个识别商品回填货主;写明细后重算 total_items/total_quantity/detail_status",
"returnUnpack.updateDetail:白名单仅 quantity/remark;仅 quantity 变更时重算主表汇总",
"returnUnpack.removeDetail:明细表 paranoid:false 硬删除 + 重算主表汇总",
"returnUnpack.cancel:仅 unpacking 状态;事务内硬删主表+明细,软删视频",
"returnUnpack.submit:仅 unpacking;status=completed + 回写 end_time,并同步更新 wms_return_query_log.is_back=1(失败不阻断主流程)",
"returnUnpack.list:主表分页,仓库隔离服务端注入 warehouse_id;where 支持 unpack_no/waybill_code 模糊、unpack_date/start_time/end_time 范围、status/detail_status/unpacker_id/return_received_id/store_id/order_express_id/order_id 等值",
"returnUnpack.detailList:明细分页 + stockWarehouse 关联(命中时);where 支持 unpack_id/stock_id/barcode/is_recognized/product_status",
"returnUnpack.detail:主表 + details(stockWarehouse) + videos(camera) + returnReceived;原单退回时返回 related.order;免权限仅登录 + 仓库隔离",
"returnUnpack.delete:后台删除不限状态;事务物理删主表+明细,软删视频",
"仓库隔离:全部接口禁止前端传入 warehouse_id,由服务端注入 ctx.user.store_id;拆包单号规则 RP+YYYYMMDD+6位序号(仓库维度序号)",
"权限:540 returnUnpack.create、541 addDetail、542 updateDetail、543 removeDetail、544 cancel、545 submit(仓库员工及以上);546 list、547 detailList、548 detail、549 delete(客服员工及以上);detail 免权限(复用列表权限)",
"代码变更:app/model/return_unpack.js、return_unpack_detail.js、return_unpack_video.js、return_query_log.js;app/service/systems/return_unpack.js;app/service/systemMethods/returnUnpack.js;database/migrations/20260813120000-20260813120300 建表、20260813130000 权限"
],
"module": "returnUnpack"
},
{
"version": "2026.08.13-returnReceived.createResponse",
"date": "2026-08-13",
"type": "updated",
"summary": "returnReceived.create 出参结构调整:由平铺返回登记字段改为包装结构 { record, is_original_return, store_remark, duplicated },record 含登记记录完整字段与派生字段 is_original_return/store_remark,与代码实现(app/service/systems/return_received.js)及设计文档对齐",
"methods": [
"returnReceived.create"
],
"notes": [
"原出参平铺 id/waybill_code/scan_date/scanner_id/scanner_name/order_express_id/order_id/store_id/remark/is_original_return/store_remark/duplicated,现改为四个顶层字段:record(object,必填)、is_original_return(boolean,必填)、store_remark(string,必填)、duplicated(boolean,必填)",
"record 内字段:id、waybill_code、scan_date、scanner_id、scanner_name、order_express_id、order_id、store_id、remark、created_at、updated_at(时间为格式化字符串)+ 派生字段 is_original_return、store_remark",
"顶层 is_original_return / store_remark / duplicated 为 record 之外独立返回字段,与 record 内同名字段取值一致",
"仅文档变更,代码实现已对齐(create 返回 { record, is_original_return, store_remark, duplicated },30日幂等命中与新建分支结构一致)"
],
"module": "returnReceived"
},
{
"version": "2026.08.13-returnWaybill",
"date": "2026-08-13",
"type": "added",
"summary": "新增运单退回登记模块(returnWaybill):复用 wms_return_query_log 表实现「货主 + 运单号」退回关系的增删查改五个接口(create/update/list/detail/delete)。create 校验货主合约并幂等返回已有记录;update 支持改运单号/货主/备注,改后冲突 409 拒绝;list 分页筛选(运单号模糊/货主/是否已通知/是否退回/登记时间范围);detail 免权限仅登录+仓库隔离;delete 物理删除。全接口仓库隔离(warehouse_id 服务端注入)。配套权限 551-555(作业类 create/update→仓库员工及以上,查询/删除类 list/detail/delete→客服员工及以上,detail 免权限复用列表权限)",
"methods": [
"returnWaybill.create",
"returnWaybill.update",
"returnWaybill.list",
"returnWaybill.detail",
"returnWaybill.delete"
],
"notes": [
"复用表 wms_return_query_log(20260813120300 迁移已落地):warehouse_id/store_id/waybill_code/remark/is_notified/is_back/created_at/updated_at;登记接口不维护 is_notified/is_back(由定时任务与拆包联动维护)",
"returnWaybill.create:waybill_code/store_id 必填;货主合约校验(wms_store_warehouse 存在 store_id+warehouse_id,无合约 400 拒绝);同仓库+货主+运单号已存在时幂等返回已有记录 duplicated=true;写入 is_notified=0/is_back=0",
"returnWaybill.update:id 必填;仓库隔离校验;waybill_code/store_id/remark 可选更新;store_id 变更时校验新货主合约;改后与另一条同仓库+货主+运单号冲突则 409 拒绝",
"returnWaybill.list:pagination(pageSize 上限 500 默认 20)+ where(waybill_code 模糊、store_id、is_notified、is_back、created_at 起止)+ sort(id/created_at/updated_at/waybill_code,默认 created_at desc)",
"returnWaybill.detail:免权限(复用列表权限),仅登录 + 仓库隔离校验",
"returnWaybill.delete:物理删除(表 paranoid:false),返回被删除记录 id",
"仓库隔离:所有接口 warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入",
"权限:551 create、552 update(仓库员工及以上);553 list、554 detail、555 delete(客服员工及以上);detail 免权限复用 list 权限",
"代码变更:app/service/systems/return_waybill.js、app/service/systemMethods/returnWaybill.js、database/migrations/20260813160000-create-return-waybill-permissions.js"
],
"module": "returnWaybill"
},
{
"version": "2026.08.13-returnUnpack.detailAuth",
"date": "2026-08-13",
"type": "updated",
"summary": "returnUnpack.detail 鉴权配置变更:不再免权限(原 _noNeedRight='detail'),改为走 API 权限校验(固定权限 ID 548,客服员工及以上),与 app/service/systemMethods/returnUnpack.js 实现对齐。",
"methods": [
"returnUnpack.detail"
],
"notes": [
"isNeedAuth:false → true;description 同步说明「需 548 权限(客服员工及以上)」",
"代码对齐:returnUnpack.js _noNeedRight 改为空字符串,detail 与其他接口一致走 API 权限校验",
"权限 548 为客服员工及以上(与原「查询类→客服员工及以上」设计一致)",
"仅文档同步,其余接口与模块不动"
],
"module": "returnUnpack"
}
]

File diff suppressed because it is too large Load Diff