feat(product): 商品批量导入(12 字段,编码存在则更新)

- 后端新增 app/lib/productImport.js:模板列定义(含表头别名)、xlsx 解析、行校验、金额解析
- 新增 GET /api/products/import-template(下载仅含表头的模板)
- 新增 POST /api/products/import:同主体下商品编码已存在则更新(空单元格不覆盖原值,
  软删除的会恢复),否则新建;文件内重复编码按最后一行处理;未知列在结果中返回
- 导入结果返回 total/created/updated/restored/failed/duplicated/errors/ignored_columns,
  并写入操作日志、对更新的商品触发待审核订单明细重算
- multipart 白名单增加 .xlsx
- 前端商品页新增「批量导入」:下载模板、选择 xlsx、展示导入结果与失败明细
- .eslintrc 为 config 目录放开 no-restricted-modules(config 需要 path 等核心模块)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-03 03:57:11 +08:00
parent 2d98d5e7eb
commit 7f0651ed37
8 changed files with 576 additions and 2 deletions

View File

@ -21,6 +21,12 @@
"no-restricted-modules": "off"
}
},
{
"files": [ "config/**/*.js" ],
"rules": {
"no-restricted-modules": "off"
}
},
{
"files": [
"app/controller/exportTask.js",

View File

@ -372,6 +372,22 @@ module.exports = {
},
productPage: buildPage('productItem', '商品列表'),
productListResponse: buildListResponse('productPage'),
/** 商品批量导入结果 */
productImportResult: {
total: { type: 'integer', description: '文件中的数据行数(不含表头与空行)' },
created: { type: 'integer', description: '新增商品数' },
updated: { type: 'integer', description: '更新商品数(商品编码已存在)' },
restored: { type: 'integer', description: '其中被恢复的已删除商品数' },
failed: { type: 'integer', description: '校验或写入失败的行数' },
duplicated: { type: 'integer', description: '文件内重复商品编码的行数(按最后一行处理)' },
errors: { type: 'array', itemType: 'string', description: '失败明细:{ row, item_code, message }' },
ignored_columns: { type: 'array', itemType: 'string', description: '被忽略的未知表头' },
},
productImportResponse: {
code: { type: 'integer', description: '业务状态码,0 成功' },
message: { type: 'string', description: '提示信息' },
data: { type: 'productImportResult', description: '导入结果' },
},
createProductRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID' },
item_code: { type: 'string', required: true, description: '商品编码,主体内唯一' },

View File

@ -1,7 +1,9 @@
'use strict';
const { Controller } = require('egg');
const ExcelJS = require('exceljs');
const { parsePagination, buildPageResult } = require('../lib/pagination');
const { IMPORT_COLUMNS, parseImportFile, normalizeRow } = require('../lib/productImport');
/** 库存类型:与 product_stocks.item_type 对齐(ZC=正品 / CC=残次品) */
const STOCK_TYPE_CC = 'CC';
@ -233,6 +235,214 @@ class ProductController extends Controller {
return ctx.service.orderItemResolve.rebuildOrdersByShopProducts(shopProducts.map(row => Number(row.id)));
}
/**
* @summary 下载商品批量导入模板
* @description 生成仅含表头的 xlsx 模板(商品编码 / 商品名称 / 货物编码 / SKU规格 / 分类 / 品牌 / 条码 / 单位 / 零售价 / 成本价 / 标签价 / 备注)
* @router get /api/products/import-template
* @apikey
* @request query integer principal_id 所属主体ID(必填,需当前账号已绑定该主体)
* @response 200 baseResponse 文件二进制流(xlsx 模板,Content-Type 为 excel 类型)
*/
async importTemplate() {
const { ctx } = this;
const workbook = new ExcelJS.Workbook();
const sheet = workbook.addWorksheet('商品导入模板');
sheet.columns = IMPORT_COLUMNS.map(col => ({
header: col.label,
key: col.field,
width: col.type === 'money' ? 12 : Math.min(30, Math.max(12, col.label.length * 4)),
}));
sheet.getRow(1).font = { bold: true };
sheet.getRow(1).alignment = { vertical: 'middle' };
sheet.views = [{ state: 'frozen', ySplit: 1 }];
const buffer = await workbook.xlsx.writeBuffer();
ctx.set('Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
ctx.set('Content-Disposition', 'attachment; filename="product-import-template.xlsx"');
ctx.body = Buffer.from(buffer);
}
/**
* @summary 批量导入商品
* @description 上传 xlsx(表单字段 file,第一行为表头)。只接受 12 个字段:
* 商品编码 / 商品名称 / 货物编码 / SKU规格 / 分类 / 品牌 / 条码 / 单位 / 零售价 / 成本价 / 标签价 / 备注;
* 同一主体下商品编码已存在则更新(空单元格不覆盖原值,软删除的会恢复),否则新建
* @router post /api/products/import
* @apikey
* @request formData file *file xlsx 文件
* @request formData integer principal_id 所属主体ID(必填,需当前账号已绑定该主体)
* @response 200 productImportResponse success
*/
async importProducts() {
const { ctx } = this;
const Op = this.app.Sequelize.Op;
const principalId = ctx.state.principalId;
const files = ctx.request.files || [];
const file = files.find(item => item.field === 'file') || files[0];
if (!file) {
ctx.status = 400;
ctx.body = { code: 400, message: '未接收到上传文件(表单字段名 file)' };
return;
}
if (!/\.xlsx$/i.test(file.filename || '')) {
await ctx.cleanupRequestFiles();
ctx.status = 400;
ctx.body = { code: 400, message: '仅支持 .xlsx 文件,请使用导入模板填写' };
return;
}
let parsed;
try {
parsed = await parseImportFile(file.filepath);
} catch (err) {
await ctx.cleanupRequestFiles();
ctx.status = 400;
ctx.body = { code: 400, message: `文件解析失败:${err.message}` };
return;
}
await ctx.cleanupRequestFiles();
if (parsed.headerError) {
ctx.status = 400;
ctx.body = { code: 400, message: parsed.headerError };
return;
}
if (!parsed.rows.length) {
ctx.status = 400;
ctx.body = { code: 400, message: '文件中没有可导入的数据行' };
return;
}
// 1) 逐行校验 + 收集商品编码
const errors = [];
const validRows = [];
const seenCodes = new Set();
let duplicated = 0;
for (const { rowNumber, raw } of parsed.rows) {
const { data, errors: rowErrors } = normalizeRow(raw);
if (rowErrors.length) {
errors.push({ row: rowNumber, item_code: data.item_code || '', message: rowErrors.join(';') });
continue;
}
if (seenCodes.has(data.item_code)) {
duplicated++;
errors.push({ row: rowNumber, item_code: data.item_code, message: '文件内商品编码重复,已按最后一行处理' });
// 保留最后一行:先删掉前面的同编码行
const idx = validRows.findIndex(item => item.data.item_code === data.item_code);
if (idx >= 0) validRows.splice(idx, 1);
}
seenCodes.add(data.item_code);
validRows.push({ rowNumber, data });
}
if (!validRows.length) {
ctx.body = {
code: 0,
message: '没有可导入的有效数据',
data: { total: parsed.rows.length, created: 0, updated: 0, failed: errors.length, errors, ignored_columns: parsed.ignoredColumns, duplicated },
};
return;
}
// 2) 批量取已存在商品(含软删除,编码唯一键包含已删除行)
const codes = validRows.map(item => item.data.item_code);
const existMap = new Map();
for (let i = 0; i < codes.length; i += 500) {
const chunk = codes.slice(i, i + 500);
const rows = await ctx.model.Product.findAll({
where: { principal_id: principalId, item_code: { [Op.in]: chunk } },
paranoid: false,
});
for (const row of rows) existMap.set(row.item_code, row);
}
// 3) 逐行写入(同一事务,任一行异常回滚该行前的内容不做半途提交)
const transaction = await ctx.model.transaction();
let created = 0;
let updated = 0;
let restored = 0;
const logRows = [];
try {
for (const { rowNumber, data } of validRows) {
const exist = existMap.get(data.item_code);
try {
if (exist) {
const patch = {};
for (const [ key, value ] of Object.entries(data)) {
if (value === undefined || value === '') continue;
if (String(exist[key] ?? '') !== String(value)) patch[key] = value;
}
if (exist.deleted_at) {
await exist.restore({ transaction });
restored++;
}
if (Object.keys(patch).length) {
await exist.update(patch, { transaction });
}
updated++;
logRows.push({
targetType: 'product',
targetId: exist.id,
action: 'update',
title: `批量导入更新商品:${data.item_name || exist.item_name || ''}(${data.item_code})${Object.keys(patch).length ? `— 变更 ${Object.keys(patch).join('、')}` : ''}`,
detail: { row: rowNumber, changed: Object.keys(patch) },
});
} else {
if (!data.item_name) {
errors.push({ row: rowNumber, item_code: data.item_code, message: '商品名称不能为空(新增商品必填)' });
continue;
}
const product = await ctx.model.Product.create({
...data,
principal_id: principalId,
create_from: 'self',
}, { transaction });
created++;
logRows.push({
targetType: 'product',
targetId: product.id,
action: 'create',
title: `批量导入新增商品:${product.item_name || ''}(${product.item_code})`,
detail: { row: rowNumber },
});
}
} catch (err) {
errors.push({ row: rowNumber, item_code: data.item_code, message: err.message });
}
}
await transaction.commit();
} catch (err) {
await transaction.rollback();
ctx.status = 500;
ctx.body = { code: 500, message: `导入失败:${err.message}` };
return;
}
// 4) 操作日志 + 绑定了这些商品的待审核订单重算
await ctx.service.operationLog.recordMany(logRows, { source: 'ui' });
const touchedIds = [ ...new Set(logRows.filter(row => row.action === 'update').map(row => Number(row.targetId))) ];
for (const productId of touchedIds) {
await this.rebuildBoundOrders(productId, principalId);
}
ctx.body = {
code: 0,
message: `导入完成:新增 ${created},更新 ${updated}${restored ? `(含恢复已删除 ${restored})` : ''}${errors.length ? `,失败 ${errors.length}` : ''}`,
data: {
total: parsed.rows.length,
created,
updated,
restored,
failed: errors.length,
duplicated,
errors,
ignored_columns: parsed.ignoredColumns,
},
};
}
/**
* @summary 商品快速搜索(聚合)
* @description 按 商品编码 / 货品编码 / 条码 / 商品名称 聚合模糊匹配,仅返回启用商品,供出入库明细快速选择

View File

@ -0,0 +1,153 @@
'use strict';
const ExcelJS = require('exceljs');
const fs = require('fs');
/**
* 商品批量导入的列定义与解析工具。
*
* 只接受下面 12 个字段,表头按中文名匹配(允许少量别名);
* 未识别的列会在结果里以 ignored_columns 返回,不参与导入。
*/
const IMPORT_COLUMNS = [
{ field: 'item_code', label: '商品编码', required: true, type: 'text', max: 50 },
{ field: 'item_name', label: '商品名称', type: 'text', max: 255 },
{ field: 'goods_code', label: '货物编码', type: 'text', max: 100, aliases: [ '货品编码' ] },
{ field: 'sku_property', label: 'SKU规格', type: 'text', max: 100, aliases: [ '规格', 'SKU 规格' ] },
{ field: 'category_name', label: '分类', type: 'text', max: 100, aliases: [ '商品分类' ] },
{ field: 'brand_name', label: '品牌', type: 'text', max: 100, aliases: [ '商品品牌' ] },
{ field: 'barcode', label: '条码', type: 'text', max: 100 },
{ field: 'stock_unit', label: '单位', type: 'text', max: 20, aliases: [ '库存单位' ] },
{ field: 'retail_price', label: '零售价', type: 'money' },
{ field: 'cost_price', label: '成本价', type: 'money' },
{ field: 'tag_price', label: '标签价', type: 'money', aliases: [ '标价' ] },
{ field: 'remark', label: '备注', type: 'text', max: 255 },
];
/** 允许的表头(含别名)→ 字段定义 */
const HEADER_MAP = new Map();
for (const col of IMPORT_COLUMNS) {
HEADER_MAP.set(col.label, col);
for (const alias of col.aliases || []) HEADER_MAP.set(alias, col);
}
/**
* 单元格取值归一化(兼容富文本 / 公式 / 超链接 / 日期)
* @param {*} value 原始单元格值
* @return {string} 文本
*/
function cellText(value) {
if (value == null) return '';
if (value instanceof Date) return value.toISOString().slice(0, 10);
if (typeof value === 'object') {
if (Array.isArray(value.richText)) return value.richText.map(item => item.text || '').join('').trim();
if (value.text != null) return String(value.text).trim();
if (value.result != null) return String(value.result).trim();
if (value.hyperlink != null) return String(value.hyperlink).trim();
return '';
}
return String(value).trim();
}
/**
* 金额解析(去千分位与货币符号)
* @param {string} text 文本
* @return {{ok: boolean, value?: number, message?: string}} 解析结果
*/
function parseMoney(text) {
const cleaned = String(text || '').replace(/[¥,,\s]/g, '');
if (!cleaned) return { ok: true, value: undefined };
const num = Number(cleaned);
if (!Number.isFinite(num)) return { ok: false, message: `不是有效金额:${text}` };
if (num < 0) return { ok: false, message: '金额不能为负数' };
return { ok: true, value: Number(num.toFixed(2)) };
}
/**
* 读取 Excel 文件并解析为待导入行
* @param {string|Buffer} source 文件路径或文件内容
* @return {Promise<{rows: Array, ignoredColumns: Array<string>, headerError: string|null}>} 解析结果
*/
async function parseImportFile(source) {
const buffer = typeof source === 'string' ? fs.readFileSync(source) : source;
const workbook = new ExcelJS.Workbook();
await workbook.xlsx.load(buffer);
const sheet = workbook.worksheets[0];
if (!sheet) return { rows: [], ignoredColumns: [], headerError: '文件中没有任何工作表' };
const headerRow = sheet.getRow(1);
const columnByIndex = new Map();
const ignoredColumns = [];
headerRow.eachCell({ includeEmpty: false }, (cell, colNumber) => {
const label = cellText(cell.value);
if (!label) return;
const col = HEADER_MAP.get(label);
if (col) {
if (!columnByIndex.has(col.field)) columnByIndex.set(col.field, colNumber);
} else {
ignoredColumns.push(label);
}
});
if (!columnByIndex.has('item_code')) {
return { rows: [], ignoredColumns, headerError: '缺少「商品编码」列(第一行应为表头)' };
}
const rows = [];
const lastRow = sheet.actualRowCount || sheet.rowCount;
for (let rowNumber = 2; rowNumber <= lastRow; rowNumber++) {
const row = sheet.getRow(rowNumber);
const raw = {};
for (const col of IMPORT_COLUMNS) {
const colNumber = columnByIndex.get(col.field);
raw[col.field] = colNumber ? cellText(row.getCell(colNumber).value) : '';
}
// 整行为空则跳过
if (Object.values(raw).every(text => !text)) continue;
rows.push({ rowNumber, raw });
}
return { rows, ignoredColumns, headerError: null };
}
/**
* 校验并把一行原始文本转换为待写入的商品字段
* 只返回「填了值」的字段:空单元格不覆盖已有数据
* @param {Object} raw 原始文本(按字段名)
* @return {{data: Object, errors: Array<string>}} 结果
*/
function normalizeRow(raw) {
const data = {};
const errors = [];
for (const col of IMPORT_COLUMNS) {
const text = String(raw[col.field] == null ? '' : raw[col.field]).trim();
if (col.type === 'money') {
const parsed = parseMoney(text);
if (!parsed.ok) { errors.push(`${col.label}${parsed.message}`); continue; }
if (parsed.value !== undefined) data[col.field] = parsed.value;
continue;
}
if (!text) {
if (col.required) errors.push(`${col.label}不能为空`);
continue;
}
if (col.max && text.length > col.max) {
errors.push(`${col.label}超长(最多 ${col.max} 字符)`);
continue;
}
data[col.field] = text;
}
return { data, errors };
}
module.exports = {
IMPORT_COLUMNS,
parseImportFile,
normalizeRow,
cellText,
parseMoney,
};

View File

@ -89,6 +89,9 @@ module.exports = app => {
router.post('/api/order-status/:id/push-wms', jwtAuth, principalCheck(), controller.orderStatus.pushWms);
// 以下资源均归属某个主体,需做主体校验与数据隔离,防止跨主体操作
// 商品批量导入:模板下载与导入接口需在 resources 之前注册,避免被 /:id 误匹配
router.get('/api/products/import-template', jwtAuth, principalCheck(), controller.product.importTemplate);
router.post('/api/products/import', jwtAuth, principalCheck(), controller.product.importProducts);
router.resources('products', '/api/products', jwtAuth, principalCheck({ model: 'Product' }), controller.product);
router.resources('comboProducts', '/api/combo-products', jwtAuth, principalCheck({ model: 'ComboProduct' }), controller.comboProduct);
router.resources('menus', '/api/menus', jwtAuth, controller.menu);

View File

@ -59,7 +59,8 @@ module.exports = appInfo => {
mode: 'file',
fileSize: '20mb',
files: 10,
whitelist: [ '.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp', '.svg' ],
// .xlsx 用于商品批量导入(见 app/controller/product.js importProducts)
whitelist: [ '.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp', '.svg', '.xlsx' ],
};
// 文件资源存储:按「主体ID/年/月/日」分层,由上传时间决定(见 app/controller/file.js)

View File

@ -1,4 +1,5 @@
import { get, post, put, del } from '@/utils/request'
import request from '@/utils/request'
export interface ProductItem {
id: number
@ -117,3 +118,36 @@ export function updateProduct(id: number, data: Partial<ProductPayload>) {
export function deleteProduct(id: number) {
return del<{ id: number }>(`/products/${id}`)
}
/** 批量导入:单行失败明细 */
export interface ProductImportError {
row: number
item_code: string
message: string
}
/** 批量导入结果 */
export interface ProductImportResult {
total: number
created: number
updated: number
restored: number
failed: number
duplicated: number
errors: ProductImportError[]
ignored_columns: string[]
}
/** 下载批量导入模板(xlsx,仅表头):走鉴权拦截器,由调用方触发浏览器下载 */
export function downloadImportTemplate() {
return request.get('/products/import-template', {
responseType: 'blob',
}) as unknown as Promise<Blob>
}
/** 批量导入商品(xlsx;同一主体下商品编码已存在则更新,空单元格不覆盖原值) */
export function importProducts(file: File) {
const form = new FormData()
form.append('file', file)
return post<ProductImportResult>('/products/import', form)
}

View File

@ -1,13 +1,16 @@
<script setup lang="ts">
import { computed, onMounted, reactive, ref } from 'vue'
import { useRoute } from 'vue-router'
import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
import { ElMessage, ElMessageBox, type FormInstance, type FormRules, type UploadFile, type UploadInstance } from 'element-plus'
import {
getProducts,
createProduct,
updateProduct,
deleteProduct,
downloadImportTemplate,
importProducts,
type ProductItem,
type ProductImportResult,
} from '@/api/product'
import {
getProductCategoryOptions,
@ -371,6 +374,71 @@ const logTitle = computed(() => {
return `操作记录:${row.item_name || ''}(${row.item_code || ''})`
})
/* -------------------- 批量导入 -------------------- */
const importVisible = ref(false)
const importing = ref(false)
const importFileName = ref('')
const importFile = ref<File | null>(null)
const importResult = ref<ProductImportResult | null>(null)
const uploadRef = ref<UploadInstance>()
function openImport() {
importVisible.value = true
importResult.value = null
importFileName.value = ''
importFile.value = null
uploadRef.value?.clearFiles()
}
function onImportFileChange(file: UploadFile) {
importFileName.value = file.name
importFile.value = (file.raw as File | undefined) || null
importResult.value = null
}
function onImportFileRemove() {
importFileName.value = ''
importFile.value = null
importResult.value = null
}
async function downloadTemplate() {
try {
const blob = await downloadImportTemplate()
const url = window.URL.createObjectURL(blob)
const link = document.createElement('a')
link.href = url
link.download = 'product-import-template.xlsx'
link.click()
window.URL.revokeObjectURL(url)
} catch {
// 拦截器已提示
}
}
async function submitImport() {
const raw = importFile.value
if (!raw) {
ElMessage.warning('请先选择需要导入的 .xlsx 文件')
return
}
importing.value = true
try {
importResult.value = await importProducts(raw)
const result = importResult.value
if (result.created || result.updated) {
ElMessage.success(`导入完成:新增 ${result.created},更新 ${result.updated}`)
await fetchList()
} else {
ElMessage.warning('没有导入成功的数据,请查看失败明细')
}
} catch {
// 拦截器已提示
} finally {
importing.value = false
}
}
onMounted(async () => {
await loadAttributeOptions()
applyRouteQuery()
@ -385,6 +453,7 @@ onMounted(async () => {
<span>商品</span>
<div class="header-actions">
<el-button type="primary" @click="openCreate">新增商品</el-button>
<el-button @click="openImport">批量导入</el-button>
<ExportButton type="product" :filters="exportFilters" />
</div>
</div>
@ -527,6 +596,63 @@ onMounted(async () => {
</template>
</el-dialog>
<!-- 批量导入:上传 xlsx,按商品编码新增/更新 -->
<el-dialog v-model="importVisible" title="批量导入商品" width="min(720px, 94vw)" top="8vh" destroy-on-close>
<div class="import-body">
<el-alert type="info" :closable="false" show-icon>
<template #title>
仅识别 12 个字段:商品编码、商品名称、货物编码、SKU规格、分类、品牌、条码、单位、零售价、成本价、标签价、备注;同一主体下商品编码已存在则更新(空单元格不覆盖原值),否则新建。
</template>
</el-alert>
<div class="import-actions">
<el-button link type="primary" @click="downloadTemplate">下载导入模板</el-button>
</div>
<el-upload
ref="uploadRef"
:auto-upload="false"
:limit="1"
accept=".xlsx"
:on-change="onImportFileChange"
:on-remove="onImportFileRemove"
>
<el-button type="primary" plain>选择 .xlsx 文件</el-button>
<template #tip>
<div class="import-tip">第一行必须是表头(可用导入模板填好再上传)</div>
</template>
</el-upload>
<div v-if="importResult" class="import-result">
<div class="import-summary">
共 {{ importResult.total }} 行:新增 <b>{{ importResult.created }}</b>,更新
<b>{{ importResult.updated }}</b>
<template v-if="importResult.restored">(其中恢复已删除 {{ importResult.restored }})</template>
,失败 <b>{{ importResult.failed }}</b>
</div>
<div v-if="importResult.ignored_columns.length" class="import-ignored">
已忽略的未知列:{{ importResult.ignored_columns.join('、') }}
</div>
<DataTable
v-if="importResult.errors.length"
:data="importResult.errors"
height="220"
size="small"
>
<el-table-column prop="row" label="行号" width="80" />
<el-table-column prop="item_code" label="商品编码" width="180" />
<el-table-column prop="message" label="失败原因" min-width="240" />
</DataTable>
</div>
</div>
<template #footer>
<el-button @click="importVisible = false">关闭</el-button>
<el-button type="primary" :loading="importing" :disabled="!importFileName" @click="submitImport">
开始导入
</el-button>
</template>
</el-dialog>
<el-drawer
v-model="drawerVisible"
:title="editId == null ? '新增商品' : '编辑商品'"
@ -735,6 +861,31 @@ onMounted(async () => {
display: flex;
flex-direction: column;
}
.import-body {
display: flex;
flex-direction: column;
gap: 12px;
}
.import-actions {
display: flex;
justify-content: flex-end;
}
.import-tip {
color: var(--el-text-color-secondary);
font-size: 12px;
}
.import-result {
display: flex;
flex-direction: column;
gap: 8px;
}
.import-summary {
font-size: 13px;
}
.import-ignored {
font-size: 12px;
color: var(--el-color-warning);
}
.search-bar {
margin-bottom: 16px;
}