feat(apiApp): 新增仓库 API 应用管理模块
- 新增 systems/apiApp.js 业务层:CRUD + AppKey/Secret 自动生成 + 仓库隔离 - 新增 systemMethods/apiApp.js 入口层:list/detail/create/update/delete/regenerateSecret - 注册 methods/system.json API 文档 + changes 变更记录 - 新增迁移脚本:wms_permission 固定 ID 464-470 + 客服组主管及以上角色授权
This commit is contained in:
parent
635e86f984
commit
76e25db7da
117
app/service/systemMethods/apiApp.js
Normal file
117
app/service/systemMethods/apiApp.js
Normal file
@ -0,0 +1,117 @@
|
||||
'use strict';
|
||||
|
||||
const MainService = require('../main');
|
||||
|
||||
/**
|
||||
* 仓库 API 应用管理 Service
|
||||
* 管理当前仓库的外部 API 应用(AppKey/Secret 生成、IP 白名单、限流等)。
|
||||
* 仓库隔离:所有操作自动按 ctx.user.store_id 过滤。
|
||||
*/
|
||||
class ApiAppService extends MainService {
|
||||
constructor(ctx) {
|
||||
super(ctx);
|
||||
const _noNeedLogin = '';
|
||||
const _noNeedRight = '';
|
||||
const _noNeedLog = '';
|
||||
const _noNeedAuth = '';
|
||||
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
|
||||
}
|
||||
|
||||
/**
|
||||
* 查询当前仓库的 API 应用列表(分页)。
|
||||
* @param {Object} data 查询参数。
|
||||
* @return {Promise<Object>} 分页结果。
|
||||
*/
|
||||
async list(data) {
|
||||
try {
|
||||
const result = await this.service.systems.apiApp.list(data || {});
|
||||
return this.success('获取成功', result);
|
||||
} catch (e) { return this.fail(e.message); }
|
||||
}
|
||||
|
||||
/**
|
||||
* 查询单个 API 应用详情。
|
||||
* @param {Object} data 查询参数。
|
||||
* @param {number|string} data.id 应用 ID。
|
||||
* @return {Promise<Object>} 应用详情。
|
||||
*/
|
||||
async detail(data) {
|
||||
try {
|
||||
const { id } = data || {};
|
||||
if (!id) return this.fail('ID不能为空');
|
||||
const { ctx } = this;
|
||||
const warehouseId = Number(ctx.user && ctx.user.store_id || 0);
|
||||
const defaultTypeId = await this.service.systems.apiApp.getDefaultInterfaceTypeId();
|
||||
const record = await ctx.model.ApiApp.findOne({
|
||||
attributes: [
|
||||
'id', 'app_name', 'warehouse_id', 'self_app_key', 'self_app_secret',
|
||||
'self_ip_whitelist', 'callback_url', 'interface_type_id',
|
||||
'rate_limit', 'sign_method', 'is_enabled', 'created_at', 'updated_at',
|
||||
],
|
||||
where: { id: Number(id), warehouse_id: warehouseId, interface_type_id: defaultTypeId },
|
||||
raw: true,
|
||||
});
|
||||
if (!record) return this.fail('API应用不存在');
|
||||
record.self_app_secret = record.self_app_secret
|
||||
? String(record.self_app_secret).substring(0, 8) + '****'
|
||||
: '';
|
||||
return this.success('获取成功', record);
|
||||
} catch (e) { return this.fail(e.message); }
|
||||
}
|
||||
|
||||
/**
|
||||
* 创建 API 应用,自动生成 AppKey 和 AppSecret。
|
||||
* @param {Object} data 创建参数。
|
||||
* @return {Promise<Object>} 创建结果(含完整 secret)。
|
||||
*/
|
||||
async create(data) {
|
||||
try {
|
||||
const result = await this.service.systems.apiApp.create(data || {});
|
||||
return this.success('创建成功', result);
|
||||
} catch (e) { return this.fail(e.message); }
|
||||
}
|
||||
|
||||
/**
|
||||
* 更新 API 应用。
|
||||
* @param {Object} data 更新参数。
|
||||
* @return {Promise<Object>} 更新结果。
|
||||
*/
|
||||
async update(data) {
|
||||
try {
|
||||
const { id, ...fields } = data || {};
|
||||
if (!id) return this.fail('ID不能为空');
|
||||
const result = await this.service.systems.apiApp.update(id, fields);
|
||||
return this.success('更新成功', result);
|
||||
} catch (e) { return this.fail(e.message); }
|
||||
}
|
||||
|
||||
/**
|
||||
* 删除/停用 API 应用。
|
||||
* @param {Object} data 删除参数。
|
||||
* @return {Promise<Object>} 删除结果。
|
||||
*/
|
||||
async delete(data) {
|
||||
try {
|
||||
const { id } = data || {};
|
||||
if (!id) return this.fail('ID不能为空');
|
||||
await this.service.systems.apiApp.delete(id);
|
||||
return this.success('删除成功');
|
||||
} catch (e) { return this.fail(e.message); }
|
||||
}
|
||||
|
||||
/**
|
||||
* 重新生成 AppSecret。
|
||||
* @param {Object} data 参数。
|
||||
* @return {Promise<Object>} 新 secret。
|
||||
*/
|
||||
async regenerateSecret(data) {
|
||||
try {
|
||||
const { id } = data || {};
|
||||
if (!id) return this.fail('ID不能为空');
|
||||
const result = await this.service.systems.apiApp.regenerateSecret(id);
|
||||
return this.success('重新生成成功', result);
|
||||
} catch (e) { return this.fail(e.message); }
|
||||
}
|
||||
}
|
||||
|
||||
module.exports = ApiAppService;
|
||||
320
app/service/systems/apiApp.js
Normal file
320
app/service/systems/apiApp.js
Normal file
@ -0,0 +1,320 @@
|
||||
'use strict';
|
||||
|
||||
const { randomBytes } = require('node:crypto');
|
||||
const { Service } = require('egg');
|
||||
|
||||
class ApiAppService extends Service {
|
||||
/**
|
||||
* 生成唯一的 AppKey。
|
||||
* 格式:AK{yyyyMMddHHmmss}{random8}
|
||||
* @return {string} AppKey
|
||||
*/
|
||||
generateAppKey() {
|
||||
const now = new Date();
|
||||
const timestamp = [
|
||||
now.getFullYear(),
|
||||
String(now.getMonth() + 1).padStart(2, '0'),
|
||||
String(now.getDate()).padStart(2, '0'),
|
||||
String(now.getHours()).padStart(2, '0'),
|
||||
String(now.getMinutes()).padStart(2, '0'),
|
||||
String(now.getSeconds()).padStart(2, '0'),
|
||||
].join('');
|
||||
return `AK${timestamp}${randomBytes(4).toString('hex')}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成 AppSecret。
|
||||
* @return {string} 64 字符十六进制密钥。
|
||||
*/
|
||||
generateAppSecret() {
|
||||
return randomBytes(32).toString('hex');
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取默认的仓库渠道接口类型 ID。
|
||||
* 查找 interface_type 中 interface_code = 'OPEN_API_WAREHOUSE' 的记录。
|
||||
* @return {Promise<number>} 接口类型 ID,找不到时返回 0。
|
||||
*/
|
||||
async getDefaultInterfaceTypeId() {
|
||||
const row = await this.ctx.model.InterfaceType.findOne({
|
||||
attributes: [ 'id' ],
|
||||
where: { interface_code: 'OPEN_API_WAREHOUSE', is_enabled: 1 },
|
||||
raw: true,
|
||||
});
|
||||
return row ? Number(row.id) : 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* 查询当前仓库的 API 应用列表(分页)。
|
||||
* @param {Object} data 查询参数。
|
||||
* @param {number} [data.page=1] 页码。
|
||||
* @param {number} [data.pageSize=20] 每页数量。
|
||||
* @param {string} [data.app_name] 应用名称(模糊搜索)。
|
||||
* @param {number} [data.is_enabled] 启用状态。
|
||||
* @return {Promise<Object>} 分页结果。
|
||||
*/
|
||||
async list(data = {}) {
|
||||
const { ctx } = this;
|
||||
const warehouseId = Number(ctx.user && ctx.user.store_id || 0);
|
||||
const page = Math.max(1, Number(data.page) || 1);
|
||||
const pageSize = Math.min(100, Math.max(1, Number(data.pageSize) || 20));
|
||||
|
||||
// 仅查询仓库开放接口类型的应用,排除货主/奇门等类型
|
||||
const where = {
|
||||
warehouse_id: warehouseId,
|
||||
interface_type_id: await this.getDefaultInterfaceTypeId(),
|
||||
};
|
||||
if (data.app_name) {
|
||||
where.app_name = { [this.app.Sequelize.Op.like]: `%${String(data.app_name).trim()}%` };
|
||||
}
|
||||
if (data.is_enabled !== undefined && data.is_enabled !== null && data.is_enabled !== '') {
|
||||
where.is_enabled = Number(data.is_enabled);
|
||||
}
|
||||
|
||||
const total = await ctx.model.ApiApp.count({ where });
|
||||
const list = await ctx.model.ApiApp.findAll({
|
||||
attributes: [
|
||||
'id', 'app_name', 'warehouse_id', 'self_app_key', 'self_app_secret',
|
||||
'self_ip_whitelist', 'callback_url', 'interface_type_id',
|
||||
'rate_limit', 'sign_method', 'is_enabled', 'created_at', 'updated_at',
|
||||
],
|
||||
where,
|
||||
offset: (page - 1) * pageSize,
|
||||
limit: pageSize,
|
||||
order: [[ 'id', 'DESC' ]],
|
||||
raw: true,
|
||||
});
|
||||
|
||||
// 脱敏:只返回 secret 前 8 位
|
||||
const maskedList = list.map(item => ({
|
||||
...item,
|
||||
self_app_secret: item.self_app_secret
|
||||
? String(item.self_app_secret).substring(0, 8) + '****'
|
||||
: '',
|
||||
}));
|
||||
|
||||
return {
|
||||
list: maskedList,
|
||||
pagination: {
|
||||
page,
|
||||
pageSize,
|
||||
total,
|
||||
totalPages: Math.ceil(total / pageSize),
|
||||
hasNext: page * pageSize < total,
|
||||
hasPrevious: page > 1,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 创建仓库 API 应用,自动生成 AppKey 和 AppSecret。
|
||||
* @param {Object} data 创建参数。
|
||||
* @param {string} data.app_name 应用名称(必填)。
|
||||
* @param {number|string} [data.interface_type_id] 接口类型 ID,不传则查 WH_CHANNEL。
|
||||
* @param {Array<string>} [data.self_ip_whitelist] IP 白名单。
|
||||
* @param {string} [data.callback_url] 回调地址。
|
||||
* @param {number} [data.rate_limit=1000] 速率限制。
|
||||
* @param {string} [data.sign_method='md5'] 签名方法。
|
||||
* @return {Promise<Object>} 创建结果(含完整 secret,仅创建时返回)。
|
||||
*/
|
||||
async create(data = {}) {
|
||||
const { ctx } = this;
|
||||
const warehouseId = Number(ctx.user && ctx.user.store_id || 0);
|
||||
|
||||
if (!warehouseId) {
|
||||
throw new Error('无法获取当前仓库ID');
|
||||
}
|
||||
|
||||
const appName = String(data.app_name || '').trim();
|
||||
if (!appName) {
|
||||
throw new Error('应用名称不能为空');
|
||||
}
|
||||
if (appName.length > 200) {
|
||||
throw new Error('应用名称不能超过200个字符');
|
||||
}
|
||||
|
||||
const interfaceTypeId = data.interface_type_id
|
||||
? Number(data.interface_type_id)
|
||||
: await this.getDefaultInterfaceTypeId();
|
||||
|
||||
const appKey = this.generateAppKey();
|
||||
const appSecret = this.generateAppSecret();
|
||||
|
||||
const payload = {
|
||||
app_name: appName,
|
||||
warehouse_id: warehouseId,
|
||||
interface_type_id: interfaceTypeId,
|
||||
self_app_key: appKey,
|
||||
self_app_secret: appSecret,
|
||||
self_ip_whitelist: Array.isArray(data.self_ip_whitelist) ? data.self_ip_whitelist : null,
|
||||
callback_url: String(data.callback_url || '').trim() || null,
|
||||
rate_limit: Number(data.rate_limit) || 1000,
|
||||
sign_method: [ 'md5', 'hmac', 'sha256' ].includes(String(data.sign_method || '').trim())
|
||||
? String(data.sign_method).trim()
|
||||
: 'md5',
|
||||
is_enabled: 1,
|
||||
};
|
||||
|
||||
const record = await ctx.model.ApiApp.create(payload);
|
||||
|
||||
this.ctx.logger.info('[apiApp] 创建仓库API应用成功', {
|
||||
warehouseId,
|
||||
appId: record.id,
|
||||
appName,
|
||||
appKey,
|
||||
});
|
||||
|
||||
return {
|
||||
id: record.id,
|
||||
app_name: record.app_name,
|
||||
warehouse_id: record.warehouse_id,
|
||||
interface_type_id: record.interface_type_id,
|
||||
self_app_key: record.self_app_key,
|
||||
self_app_secret: record.self_app_secret,
|
||||
self_ip_whitelist: record.self_ip_whitelist,
|
||||
callback_url: record.callback_url,
|
||||
rate_limit: record.rate_limit,
|
||||
sign_method: record.sign_method,
|
||||
is_enabled: record.is_enabled,
|
||||
created_at: record.created_at,
|
||||
updated_at: record.updated_at,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 更新仓库 API 应用。
|
||||
* @param {number|string} id 应用 ID。
|
||||
* @param {Object} data 更新字段。
|
||||
* @param {string} [data.app_name] 应用名称。
|
||||
* @param {Array<string>} [data.self_ip_whitelist] IP 白名单。
|
||||
* @param {string} [data.callback_url] 回调地址。
|
||||
* @param {number} [data.rate_limit] 速率限制。
|
||||
* @param {string} [data.sign_method] 签名方法。
|
||||
* @param {number} [data.is_enabled] 启用状态。
|
||||
* @return {Promise<Object>} 更新后的记录(脱敏)。
|
||||
*/
|
||||
async update(id, data = {}) {
|
||||
const { ctx } = this;
|
||||
const warehouseId = Number(ctx.user && ctx.user.store_id || 0);
|
||||
|
||||
const record = await ctx.model.ApiApp.findOne({
|
||||
where: { id: Number(id), warehouse_id: warehouseId, interface_type_id: await this.getDefaultInterfaceTypeId() },
|
||||
});
|
||||
|
||||
if (!record) {
|
||||
throw new Error('API应用不存在或不属于当前仓库');
|
||||
}
|
||||
|
||||
const updatableFields = [ 'app_name', 'self_ip_whitelist', 'callback_url', 'rate_limit', 'sign_method', 'is_enabled' ];
|
||||
for (const field of updatableFields) {
|
||||
if (data[field] !== undefined && data[field] !== null) {
|
||||
if (field === 'sign_method') {
|
||||
const val = String(data[field]).trim();
|
||||
if (![ 'md5', 'hmac', 'sha256' ].includes(val)) {
|
||||
throw new Error('签名方法仅支持 md5/hmac/sha256');
|
||||
}
|
||||
record[field] = val;
|
||||
} else if (field === 'is_enabled') {
|
||||
record[field] = Number(data[field]);
|
||||
} else if (field === 'rate_limit') {
|
||||
const val = Number(data[field]);
|
||||
record[field] = val > 0 && val <= 100000 ? val : record[field];
|
||||
} else if (field === 'app_name') {
|
||||
const val = String(data[field]).trim();
|
||||
if (!val) throw new Error('应用名称不能为空');
|
||||
if (val.length > 200) throw new Error('应用名称不能超过200个字符');
|
||||
record[field] = val;
|
||||
} else {
|
||||
record[field] = data[field];
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
await record.save();
|
||||
|
||||
this.ctx.logger.info('[apiApp] 更新仓库API应用成功', {
|
||||
warehouseId,
|
||||
appId: record.id,
|
||||
});
|
||||
|
||||
return {
|
||||
id: record.id,
|
||||
app_name: record.app_name,
|
||||
warehouse_id: record.warehouse_id,
|
||||
interface_type_id: record.interface_type_id,
|
||||
self_app_key: record.self_app_key,
|
||||
self_app_secret: record.self_app_secret
|
||||
? String(record.self_app_secret).substring(0, 8) + '****'
|
||||
: '',
|
||||
self_ip_whitelist: record.self_ip_whitelist,
|
||||
callback_url: record.callback_url,
|
||||
rate_limit: record.rate_limit,
|
||||
sign_method: record.sign_method,
|
||||
is_enabled: record.is_enabled,
|
||||
created_at: record.created_at,
|
||||
updated_at: record.updated_at,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 删除仓库 API 应用(软删除:is_enabled=0)。
|
||||
* @param {number|string} id 应用 ID。
|
||||
* @return {Promise<void>} 无返回值。
|
||||
*/
|
||||
async delete(id) {
|
||||
const { ctx } = this;
|
||||
const warehouseId = Number(ctx.user && ctx.user.store_id || 0);
|
||||
|
||||
const record = await ctx.model.ApiApp.findOne({
|
||||
where: { id: Number(id), warehouse_id: warehouseId, interface_type_id: await this.getDefaultInterfaceTypeId() },
|
||||
});
|
||||
|
||||
if (!record) {
|
||||
throw new Error('API应用不存在或不属于当前仓库');
|
||||
}
|
||||
|
||||
record.is_enabled = 0;
|
||||
await record.save();
|
||||
|
||||
this.ctx.logger.info('[apiApp] 停用仓库API应用成功', {
|
||||
warehouseId,
|
||||
appId: record.id,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* 重新生成 AppSecret。
|
||||
* @param {number|string} id 应用 ID。
|
||||
* @return {Promise<Object>} 包含新 secret 的结果(仅此次返回完整 secret)。
|
||||
*/
|
||||
async regenerateSecret(id) {
|
||||
const { ctx } = this;
|
||||
const warehouseId = Number(ctx.user && ctx.user.store_id || 0);
|
||||
|
||||
const record = await ctx.model.ApiApp.findOne({
|
||||
where: { id: Number(id), warehouse_id: warehouseId, interface_type_id: await this.getDefaultInterfaceTypeId() },
|
||||
});
|
||||
|
||||
if (!record) {
|
||||
throw new Error('API应用不存在或不属于当前仓库');
|
||||
}
|
||||
|
||||
const newSecret = this.generateAppSecret();
|
||||
record.self_app_secret = newSecret;
|
||||
await record.save();
|
||||
|
||||
this.ctx.logger.info('[apiApp] 重新生成AppSecret成功', {
|
||||
warehouseId,
|
||||
appId: record.id,
|
||||
});
|
||||
|
||||
return {
|
||||
id: record.id,
|
||||
app_name: record.app_name,
|
||||
self_app_key: record.self_app_key,
|
||||
self_app_secret: newSecret,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
module.exports = ApiAppService;
|
||||
80
database/migrations/20260801120000-add-apiApp-permissions.js
Normal file
80
database/migrations/20260801120000-add-apiApp-permissions.js
Normal file
@ -0,0 +1,80 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* 为 apiApp 仓库 API 应用管理模块创建权限并授权给客服组-主管及以上角色。
|
||||
*
|
||||
* 固定 ID(开发库 & 生产库 wms_permission 当前 max_id 均为 463):
|
||||
* 464 — 父级菜单 "API应用管理"
|
||||
* 465 — apiApp.list
|
||||
* 466 — apiApp.detail
|
||||
* 467 — apiApp.create
|
||||
* 468 — apiApp.update
|
||||
* 469 — apiApp.delete
|
||||
* 470 — apiApp.regenerateSecret
|
||||
*
|
||||
* 授权角色(permissions 不为 "*" 的 主管/经理 级角色):
|
||||
* 8 — 经理
|
||||
* 26 — 仓库组-主管
|
||||
* 28 — 客服组-主管
|
||||
* 29 — 生产组-主管
|
||||
*/
|
||||
module.exports = {
|
||||
// eslint-disable-next-line no-unused-vars
|
||||
async up(queryInterface, Sequelize) {
|
||||
// ── 1. 插入父级权限 (type=web_pages, sort=1, status=1) ──
|
||||
await queryInterface.sequelize.query(`
|
||||
INSERT INTO wms_permission (id, path, component, name, redirect, meta_title, meta_icon, hidden, always_show, parent_id, type, sort, status, created_at, update_at)
|
||||
VALUES (464, 'apiApp', NULL, 'API应用管理', NULL, 'API应用管理', NULL, 0, 0, NULL, 'web_pages', 1, 1, NOW(), NOW())
|
||||
`);
|
||||
|
||||
// ── 2. 插入 6 个接口权限 ──
|
||||
const methods = [
|
||||
[ 465, 'apiApp.list' ],
|
||||
[ 466, 'apiApp.detail' ],
|
||||
[ 467, 'apiApp.create' ],
|
||||
[ 468, 'apiApp.update' ],
|
||||
[ 469, 'apiApp.delete' ],
|
||||
[ 470, 'apiApp.regenerateSecret' ],
|
||||
];
|
||||
|
||||
for (const [ id, method ] of methods) {
|
||||
await queryInterface.sequelize.query(`
|
||||
INSERT INTO wms_permission (id, path, component, name, redirect, meta_title, meta_icon, hidden, always_show, parent_id, type, sort, status, created_at, update_at)
|
||||
VALUES (${id}, '${method}', NULL, '${method}', NULL, 'API:${method}', NULL, 0, 0, 464, 'api', 0, 1, NOW(), NOW())
|
||||
`);
|
||||
}
|
||||
|
||||
// ── 3. 给 客服组-主管及以上角色 追加新权限 ID ──
|
||||
// 只更新 permissions 为显式列表(非 "*")的角色
|
||||
const newIdSuffix = ', 465, 466, 467, 468, 469, 470';
|
||||
|
||||
await queryInterface.sequelize.query(`
|
||||
UPDATE wms_role
|
||||
SET permissions = CONCAT(LEFT(permissions, LENGTH(permissions) - 1), '${newIdSuffix}]')
|
||||
WHERE id IN (8, 26, 28, 29)
|
||||
AND permissions != '*'
|
||||
AND permissions IS NOT NULL
|
||||
AND LENGTH(permissions) > 2
|
||||
`);
|
||||
},
|
||||
|
||||
// eslint-disable-next-line no-unused-vars
|
||||
async down(queryInterface, Sequelize) {
|
||||
// ── 1. 从角色权限中移除新增的 ID ──
|
||||
await queryInterface.sequelize.query(`
|
||||
UPDATE wms_role
|
||||
SET permissions = REPLACE(permissions, ', 465, 466, 467, 468, 469, 470', '')
|
||||
WHERE id IN (8, 26, 28, 29)
|
||||
`);
|
||||
|
||||
// ── 2. 删除 6 个接口权限 ──
|
||||
await queryInterface.sequelize.query(
|
||||
'DELETE FROM wms_permission WHERE id IN (465, 466, 467, 468, 469, 470)'
|
||||
);
|
||||
|
||||
// ── 3. 删除父级权限 ──
|
||||
await queryInterface.sequelize.query(
|
||||
'DELETE FROM wms_permission WHERE id = 464'
|
||||
);
|
||||
},
|
||||
};
|
||||
@ -1,4 +1,83 @@
|
||||
[
|
||||
{
|
||||
"version": "2026.08.01-system-01",
|
||||
"date": "2026-08-01",
|
||||
"type": "added",
|
||||
"summary": "新增 apiApp 仓库 API 应用管理模块,支持当前仓库维度的 API 应用 CRUD、AppKey/Secret 自动生成与重新生成、IP 白名单、回调地址、限流等配置",
|
||||
"methods": [
|
||||
"apiApp.list",
|
||||
"apiApp.detail",
|
||||
"apiApp.create",
|
||||
"apiApp.update",
|
||||
"apiApp.delete",
|
||||
"apiApp.regenerateSecret"
|
||||
],
|
||||
"notes": [
|
||||
"apiApp.list:分页查询当前仓库 API 应用列表,支持按 app_name(模糊)、is_enabled 筛选,Secret 自动脱敏(前8位+****)。",
|
||||
"apiApp.detail:按 ID 查询单个应用详情,需同时匹配 warehouse_id(自动注入 ctx.user.store_id),Secret 脱敏。",
|
||||
"apiApp.create:创建应用时自动生成 AppKey(AK{yyyyMMddHHmmss}{random8hex})和 AppSecret(64位hex)。默认 interface_type_id 取 WH_CHANNEL。仅创建时返回完整 Secret。",
|
||||
"apiApp.update:更新可编辑字段(app_name、self_ip_whitelist、callback_url、rate_limit、sign_method、is_enabled),不可变字段为 self_app_key 和 interface_type_id。",
|
||||
"apiApp.delete:软删除(is_enabled=0),不物理删除。",
|
||||
"apiApp.regenerateSecret:重新生成 64位hex AppSecret,旧 Secret 立即失效。仅此次返回完整 Secret。",
|
||||
"仓库隔离:所有操作按 ctx.user.store_id → warehouse_id 自动过滤。",
|
||||
"Secret 安全策略:list/detail/update 返回脱敏值,仅 create/regenerateSecret 返回完整 Secret。"
|
||||
],
|
||||
"module": "apiApp"
|
||||
},
|
||||
{
|
||||
"version": "2026.07.31-system-02",
|
||||
"date": "2026-07-31",
|
||||
"type": "added",
|
||||
"summary": "新增 storage.inventory.export 库存导出与 storage.inventory.exportTaskProgress 导出进度查询,入参复用 list 的 where/sort/group_by_batch 语义,支持两种导出模式(聚合汇总 / 逐条明细),库位信息一并导出",
|
||||
"methods": [
|
||||
"storage.inventory.export",
|
||||
"storage.inventory.exportTaskProgress"
|
||||
],
|
||||
"notes": [
|
||||
"storage.inventory.export:异步提交导出任务,返回 task_id 与受理信息,后端异步生成 Excel 并上传。入参 where/sort/group_by_batch 与 storage.inventory.list 完全一致,无需额外学习成本。",
|
||||
"group_by_batch=false(默认):按 stock_id + space_id(库位)聚合导出库存汇总,含商品编码/名称/规格/单位/货主/库位编码/名称/总库存/锁定/可用/批次数/最近入库时间。",
|
||||
"group_by_batch=true:按 storage_id 逐条导出库存明细,含库存记录ID/商品信息/库位信息/批次号/库存类型/数量/生产日期/过期日期/入库时间/入库单号/供应商批次号。",
|
||||
"新增 storage.inventory.exportTaskProgress:按 task_id/taskId 查询导出任务进度与状态(submitted/running/success/failed/not_found),status=success 时返回 download_url 供客户端下载。",
|
||||
"导出文件目录:exports/storage/inventory/{warehouseId}/,缓存 TTL 1800 秒。"
|
||||
],
|
||||
"module": "storage.inventory"
|
||||
},
|
||||
{
|
||||
"version": "2026.07.31-system-01",
|
||||
"date": "2026-07-31",
|
||||
"type": "added",
|
||||
"summary": "新增按波次批量快捷复核接口 batchQuickRecheckByWave,支持批量波次 IDs 的前置条件检查(储位、快递、同步、拦截),自动完成拣货并标记复核,支持部分失败",
|
||||
"methods": [
|
||||
"order.recheckOrder.batchQuickRecheckByWave"
|
||||
],
|
||||
"notes": [
|
||||
"新增 order.recheckOrder.batchQuickRecheckByWave 方法,复用 batchQuickRecheck 的 _completePickForOrder / _markRecheckForOrder / _tryCompleteWaveInTransaction 等内部事务方法",
|
||||
"入参 wave_ids 支持数组或逗号分隔字符串,兼容 waveIds(驼峰)、wave_id(单值)",
|
||||
"按波次维度批量查询订单后逐波次、逐订单执行前置校验与复核,每个订单独立事务,部分失败不影响其他订单",
|
||||
"响应包含 success/failed 列表及计数,failed 项含 order_id、wave_id、delivery_order_code、reason 说明;波次下无订单时仅返回 wave_id + reason"
|
||||
],
|
||||
"module": "order.recheckOrder"
|
||||
},
|
||||
{
|
||||
"version": "2026.07.29-system-01",
|
||||
"date": "2026-07-29",
|
||||
"type": "added",
|
||||
"summary": "补全 waybill.warehouse group API 文档参数定义:完善 list/detail/export 的 params 与 response,新增 exportTaskProgress 异步进度查询接口",
|
||||
"methods": [
|
||||
"waybill.warehouse.list",
|
||||
"waybill.warehouse.detail",
|
||||
"waybill.warehouse.export",
|
||||
"waybill.warehouse.exportTaskProgress"
|
||||
],
|
||||
"notes": [
|
||||
"waybill.warehouse.list:params 含 pagination/where/sort 完整字段定义,where 支持 15 个筛选维度(运单号、主单号、订单ID、订单号、物流编码、物流接口ID、平台编码、状态、退回/拦截/星河签收、包材ID、已称重、关键词、创建时间范围),sort 白名单 create_at/weighing_weight/id。response 含 list(28 个字段)+ pagination。",
|
||||
"waybill.warehouse.detail:修正 id 参数为可选(required: false),与 waybillCode 二选一,waybillCode 优先。response 含 id/waybill_code/main_waybill_code/waybill_type/business_key/sibling_waybills/order/logistics/status_info/weight/package/print_records/print_count 等完整详情。",
|
||||
"waybill.warehouse.export:response 补充 progress/message/update_time 字段,完整覆盖异步任务返回信息。",
|
||||
"新增 waybill.warehouse.exportTaskProgress:按 task_id/taskId 查询导出进度,response 含 task_id/status/progress/current_count/total_count/message/result/error/download_url/update_time。",
|
||||
"所有接口 isNeedAuth: false, isNeedLogin: true,仓库隔离通过 ctx.user.store_id 自动注入。"
|
||||
],
|
||||
"module": "waybill.warehouse"
|
||||
},
|
||||
{
|
||||
"version": "2026.07.28-system-01",
|
||||
"date": "2026-07-28",
|
||||
@ -2335,24 +2414,6 @@
|
||||
],
|
||||
"type": "updated"
|
||||
},
|
||||
{
|
||||
"version": "2026.05.20-system-02",
|
||||
"date": "2026-05-20",
|
||||
"summary": "新增打印失败自动补偿能力:定时扫描并触发 print.retryFailed 批量补打",
|
||||
"methods": [
|
||||
"print.retryFailed"
|
||||
],
|
||||
"notes": [
|
||||
"新增定时任务:app/schedule/print_retry_compensation.js,按仓库分组调用 print.retryFailed 进行批量补打。",
|
||||
"配置项位置:config/config.default.js 的 printRetryCompensation,包含:enable(boolean, 默认 false)、intervalMs(毫秒,默认 60000)、batchSize(批量大小,默认 50)、force(boolean,默认 false)、maxRetryCount(number,默认 5)。",
|
||||
"行为摘要:任务按 printRetryCompensation.intervalMs 频率查询 send_status=send_failed 或 print_status IN (print_failed, timeout),且 next_retry_at <= now 且 retry_count < maxRetryCount 的记录,按仓库分组并调用 print.retryFailed({ print_ids, warehouse_id, force }) 进行补打。",
|
||||
"兼容性:print.retryFailed 支持显式传入 warehouse_id(调度任务会传入),当未提供时回退到 ctx.user.store_id;若两者均无则接口返回 400。",
|
||||
"注意:当前实现中传入的 force 参数不会放宽对状态的判定(代码注释说明为“最小实现”),如需放宽需修改 print.getRetryEligibility 的逻辑。",
|
||||
"回滚说明:1) 将 printRetryCompensation.enable 设为 false 并重启服务以停止新任务;2) 从部署包中移除或注释 app/schedule/print_retry_compensation.js 并重启服务;3) 如需从 methods/changes/system.json 中移除此变更,请通过生成对应 spec(change.version 设置为本条版本并 type='removed')并运行 npm run doc:api:update -- --spec=<spec> 来更新变更记录;4) 若调度已触发的补打需中止,请在调度或队列系统中停止对应任务或通过运维回退正在执行的补打逻辑。"
|
||||
],
|
||||
"module": "print",
|
||||
"type": "added"
|
||||
},
|
||||
{
|
||||
"version": "2026.05.20-system-01",
|
||||
"date": "2026-05-20",
|
||||
@ -5017,5 +5078,46 @@
|
||||
"仓库侧导出自动限定 warehouse_id=ctx.user.store_id,货主侧需传 store_id",
|
||||
"导出 Excel 列:序号/创建时间/流水类型/仓库ID/货主ID/商品ID/变动数量/变更前库存/变更后库存/变更前锁定/变更后锁定/批次号/单据类型/单据号/收货单ID/入库单ID/发货单ID/操作人/备注"
|
||||
]
|
||||
},
|
||||
{
|
||||
"version": "2026.07.29-system-01",
|
||||
"date": "2026-07-29",
|
||||
"type": "added",
|
||||
"summary": "新增 waybill.warehouse 运单模块(仓库侧):list(列表)、detail(详情)、export(导出)3 个接口,支持运单号独立查询与管理",
|
||||
"methods": [
|
||||
"waybill.warehouse.list",
|
||||
"waybill.warehouse.detail",
|
||||
"waybill.warehouse.export"
|
||||
],
|
||||
"notes": [
|
||||
"新增 waybill.warehouse.list:仓库侧运单列表查询,支持分页与多条件筛选(运单号/主单号/订单ID/订单号/物流公司/物流接口/平台/状态/退回/拦截/星河签收/包材/称重/关键词/时间范围),默认按 create_at desc 排序。",
|
||||
"新增 waybill.warehouse.detail:仓库侧运单详情查询,含关联订单信息、兄弟运单(sibling_waybills)、物流信息、状态信息、称重信息、打包信息(打包状态/打包人/打包时间)、打印记录列表。",
|
||||
"新增 waybill.warehouse.export:仓库侧运单导出,复用 list 筛选逻辑,异步任务模式,支持自定义导出字段。",
|
||||
"仓库隔离策略:所有接口自动注入 warehouse_id = ctx.user.store_id(全系统统一约定),不可由前端入参覆盖。",
|
||||
"快照字段方案:wms_order_express 表新增 delivery_order_code、store_id_snapshot、store_name_snapshot、warehouse_name_snapshot 四个快照列,列表查询无需 JOIN 订单表或货主表,仅单表查询 + SELF JOIN(主单号)。",
|
||||
"主单号/子单号规则:同一 order_id 下 business_key=1 为主单号,business_key>1 为子单号,沿用系统已有约定。",
|
||||
"命名空间规划:waybill.warehouse.* 本期实现(仓库侧),后续预留 waybill.store.*(货主侧)。",
|
||||
"本模块一期仅提供只读查询,不涉及运单创建/修改/删除,不修改任何现有接口。"
|
||||
],
|
||||
"module": "waybill.warehouse"
|
||||
},
|
||||
{
|
||||
"version": "2026.07.30-system-01",
|
||||
"date": "2026-07-30",
|
||||
"type": "changed",
|
||||
"summary": "更新 waybill.warehouse group API 文档:list 新增 waybillType/storeId 筛选、移除 pack_status 响应字段;detail 精简 package 对象;export 响应改为纯异步任务模式(仅含 task_id/status/progress/message/update_time)",
|
||||
"methods": [
|
||||
"waybill.warehouse.list",
|
||||
"waybill.warehouse.detail",
|
||||
"waybill.warehouse.export",
|
||||
"waybill.warehouse.exportTaskProgress"
|
||||
],
|
||||
"notes": [
|
||||
"waybill.warehouse.list:新增 where.waybillType 筛选(\"main\"/\"1\"=主单号,\"child\"/\"2\"=子单号),新增 where.storeId 货主ID等值筛选。where.orderNo 标注暂不可用(待快照字段就绪)。response 移除 pack_status 字段(两表无关联,不再返回),list 字段数从 28 减至 27。",
|
||||
"waybill.warehouse.detail:package 对象移除 pack_status/pack_quantity/pack_at/packer_name 四个字段,仅保留 package_material_id 和 package_material_name。description 同步去掉\"打包状态\"相关描述。",
|
||||
"waybill.warehouse.export:响应简化为纯异步任务模式,data 仅含 task_id/status/progress/message/update_time,不含 total_count/current_count/result/error/download_url 等执行期字段(这些信息由 exportTaskProgress 接口返回)。export 的 where 参数同步新增 waybillType 和 storeId。",
|
||||
"waybill.warehouse.exportTaskProgress:无变更,保持不变。"
|
||||
],
|
||||
"module": "waybill.warehouse"
|
||||
}
|
||||
]
|
||||
|
||||
2677
methods/system.json
2677
methods/system.json
File diff suppressed because it is too large
Load Diff
Loading…
x
Reference in New Issue
Block a user