From 7f0651ed37e76b4705a1cfe84bb478eb1e0b4917 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Tue, 3 Nov 2026 03:57:11 +0800 Subject: [PATCH] =?UTF-8?q?feat(product):=20=E5=95=86=E5=93=81=E6=89=B9?= =?UTF-8?q?=E9=87=8F=E5=AF=BC=E5=85=A5=EF=BC=8812=20=E5=AD=97=E6=AE=B5?= =?UTF-8?q?=EF=BC=8C=E7=BC=96=E7=A0=81=E5=AD=98=E5=9C=A8=E5=88=99=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 后端新增 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> --- backend/.eslintrc | 6 + backend/app/contract/index.js | 16 ++ backend/app/controller/product.js | 210 +++++++++++++++++++++++++++ backend/app/lib/productImport.js | 153 +++++++++++++++++++ backend/app/router.js | 3 + backend/config/config.default.js | 3 +- frontend/src/api/product.ts | 34 +++++ frontend/src/views/Product/Index.vue | 153 ++++++++++++++++++- 8 files changed, 576 insertions(+), 2 deletions(-) create mode 100644 backend/app/lib/productImport.js diff --git a/backend/.eslintrc b/backend/.eslintrc index d5c1009..da59f4a 100644 --- a/backend/.eslintrc +++ b/backend/.eslintrc @@ -21,6 +21,12 @@ "no-restricted-modules": "off" } }, + { + "files": [ "config/**/*.js" ], + "rules": { + "no-restricted-modules": "off" + } + }, { "files": [ "app/controller/exportTask.js", diff --git a/backend/app/contract/index.js b/backend/app/contract/index.js index 1a301e5..7ee0897 100644 --- a/backend/app/contract/index.js +++ b/backend/app/contract/index.js @@ -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: '商品编码,主体内唯一' }, diff --git a/backend/app/controller/product.js b/backend/app/controller/product.js index 3291297..58db34b 100644 --- a/backend/app/controller/product.js +++ b/backend/app/controller/product.js @@ -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 按 商品编码 / 货品编码 / 条码 / 商品名称 聚合模糊匹配,仅返回启用商品,供出入库明细快速选择 diff --git a/backend/app/lib/productImport.js b/backend/app/lib/productImport.js new file mode 100644 index 0000000..c2611d0 --- /dev/null +++ b/backend/app/lib/productImport.js @@ -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, 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}} 结果 + */ +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, +}; diff --git a/backend/app/router.js b/backend/app/router.js index 24e0ffb..a504b92 100644 --- a/backend/app/router.js +++ b/backend/app/router.js @@ -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); diff --git a/backend/config/config.default.js b/backend/config/config.default.js index 89d9432..78c5016 100644 --- a/backend/config/config.default.js +++ b/backend/config/config.default.js @@ -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) diff --git a/frontend/src/api/product.ts b/frontend/src/api/product.ts index fc4a563..d7fa5c1 100644 --- a/frontend/src/api/product.ts +++ b/frontend/src/api/product.ts @@ -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) { 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 +} + +/** 批量导入商品(xlsx;同一主体下商品编码已存在则更新,空单元格不覆盖原值) */ +export function importProducts(file: File) { + const form = new FormData() + form.append('file', file) + return post('/products/import', form) +} diff --git a/frontend/src/views/Product/Index.vue b/frontend/src/views/Product/Index.vue index 8d33522..cf89bf2 100644 --- a/frontend/src/views/Product/Index.vue +++ b/frontend/src/views/Product/Index.vue @@ -1,13 +1,16 @@