@ims-view/server 1.1.0 → 1.2.1

package/README.md

@@ -33,12 +33,16 @@ npx ims-view-server
 IMS_SERVER_PORT=3010 npx ims-view-server
 ```
 
-仓库内开发：
+仓库内开发（默认热重载，改 `packages/server/src` / `packages/utils/src/excel` 会自动重启）：
 
 ```shell
 IMS_SERVER_PORT=3010 pnpm start:server
 ```
 
+不需要热重载时：`pnpm --dir packages/server start:once`
+
+请求体校验使用 Zod（`createZodBaseModel` + `ZodValidationPipe`），JSON 接口统一 `ResponseEntity`：`{ code, data, msg }`（`code === 0` 成功）。`POST /excel/export` 仍直接返回 xlsx 二进制。
+
 ## 嵌入 Nest 应用
 
 ```ts
@@ -57,9 +61,22 @@ export class AppModule {}
 | ---- | ---- | ---- |
 | `IMS_SERVER_PORT` | 服务端口（优先） | `3010` |
 | `PORT` | 兼容通用端口变量 | - |
+| `IMS_SERVER_BODY_LIMIT` | JSON body 体积上限 | `50mb` |
+| `IMS_SERVER_GZIP_THRESHOLD` | 响应 gzip 压缩阈值（字节） | `1024` |
+| `IMS_EXCEL_UPLOAD_DIR` | 上传文件目录 | `os.tmpdir()/ims-excel-uploads` |
+| `IMS_EXCEL_UPLOAD_TTL_MS` | 上传文件保留时长 | `3600000`（1h） |
+| `IMS_EXCEL_UPLOAD_CLEANUP_MS` | 定时清理间隔 | `600000`（10min） |
+| `IMS_EXCEL_CHUNK_BYTES` | 超过该体积走分块挂载（LuckyExcel 解析后切块） | `2097152`（2MB） |
+| `IMS_EXCEL_BLOCK_ROWS` | 渐进挂载每块行数（不是总行上限） | `5000` |
+| `IMS_EXCEL_MAX_ROWS` | 大文件导入行上限（`0`=不截断） | `150000` |
+| `IMS_EXCEL_PARSE_TIMEOUT_MS` | 单次解析超时 | `600000`（10min） |
 
 前端对接：`IMS_EXCHANGE_ENDPOINT=http://localhost:3010`
 
+## 导入策略
+
+- **小文件**：LuckyExcel → `{id}.snapshot.json`，前端一次 `createWorkbook`
+- **大文件（默认 >2MB）**：同一套 **LuckyExcel** 解析 → `{id}.meta.json` + blocks，前端骨架（含 styles/resources）+ 分批 `setValues`
 ## API
 
 见文档站：

package/lib/excel/excel-parse.worker.cjs

@@ -0,0 +1,279 @@
+/**
+ * Worker 入口（纯 CJS）：ExcelJS 分块写盘，不依赖 tsx。
+ * 由 excel.service 用 worker_threads 拉起。
+ */
+const { parentPort, workerData } = require('worker_threads');
+const { readFile, writeFile } = require('fs/promises');
+const path = require('path');
+const { createRequire } = require('module');
+
+const requireFromHere = createRequire(__filename);
+
+const resolveExcelJS = () => {
+  const candidates = [
+    () => requireFromHere.resolve('exceljs'),
+    () =>
+      requireFromHere.resolve('exceljs', {
+        paths: [path.resolve(__dirname, '../../../utils')],
+      }),
+    () =>
+      requireFromHere.resolve('exceljs', {
+        paths: [path.resolve(__dirname, '../../../../node_modules')],
+      }),
+  ];
+  for (const tryResolve of candidates) {
+    try {
+      // eslint-disable-next-line import/no-dynamic-require
+      return require(tryResolve());
+    } catch {
+      // continue
+    }
+  }
+  throw new Error('无法解析 exceljs，请确认 monorepo 依赖已安装');
+};
+
+const ExcelJS = resolveExcelJS();
+
+const CellValueType = {
+  STRING: 1,
+  NUMBER: 2,
+  BOOLEAN: 3,
+};
+
+const argbToRgb = (argb) => {
+  if (!argb || typeof argb !== 'string') return undefined;
+  const hex = argb.replace(/^#/, '');
+  if (hex.length === 8) return `#${hex.slice(2)}`;
+  if (hex.length === 6) return `#${hex}`;
+  return undefined;
+};
+
+const excelColorToRgb = (color) => {
+  if (!color) return undefined;
+  if (color.argb) return argbToRgb(color.argb);
+  return undefined;
+};
+
+const cellFromExcelJs = (cell) => {
+  const value = cell.value;
+  if (value == null || value === '') return null;
+
+  let mapped = null;
+
+  if (typeof value === 'object' && value !== null && 'formula' in value) {
+    const formula = String(value.formula || '').replace(/^=/, '');
+    const result = value.result;
+    mapped = {
+      f: `=${formula}`,
+      v: result,
+      t:
+        typeof result === 'number'
+          ? CellValueType.NUMBER
+          : typeof result === 'boolean'
+            ? CellValueType.BOOLEAN
+            : CellValueType.STRING,
+    };
+  } else if (typeof value === 'object' && value !== null && 'richText' in value) {
+    const text = (value.richText || []).map((part) => part.text || '').join('');
+    if (!text) return null;
+    mapped = { v: text, t: CellValueType.STRING };
+  } else if (typeof value === 'object' && value !== null && 'text' in value && 'hyperlink' in value) {
+    mapped = { v: String(value.text || ''), t: CellValueType.STRING };
+  } else if (typeof value === 'object' && value !== null && 'error' in value) {
+    mapped = { v: String(value.error), t: CellValueType.STRING };
+  } else if (value instanceof Date) {
+    mapped = { v: value.toISOString(), t: CellValueType.STRING };
+  } else if (typeof value === 'number') {
+    mapped = { v: value, t: CellValueType.NUMBER };
+  } else if (typeof value === 'boolean') {
+    mapped = { v: value, t: CellValueType.BOOLEAN };
+  } else {
+    const text = String(value);
+    if (!text) return null;
+    mapped = { v: text, t: CellValueType.STRING };
+  }
+
+  const style = {};
+  const font = cell.font;
+  if (font) {
+    if (font.bold) style.bl = 1;
+    if (font.italic) style.it = 1;
+    if (font.size) style.fs = font.size;
+    if (font.name) style.ff = font.name;
+    const fc = excelColorToRgb(font.color);
+    if (fc) style.cl = { rgb: fc };
+  }
+  const fill = cell.fill;
+  if (fill && fill.type === 'pattern' && fill.fgColor) {
+    const bg = excelColorToRgb(fill.fgColor);
+    if (bg) style.bg = { rgb: bg };
+  }
+  if (Object.keys(style).length) mapped.s = style;
+  return mapped;
+};
+
+const collectMerges = (worksheet, maxRowExclusive) => {
+  const merges = [];
+  const raw = worksheet.model && worksheet.model.merges;
+  if (!Array.isArray(raw)) return merges;
+  raw.forEach((ref) => {
+    try {
+      const [start, end] = String(ref).split(':');
+      if (!start) return;
+      const startCell = worksheet.getCell(start);
+      const endCell = worksheet.getCell(end || start);
+      const top = Number(startCell.row) - 1;
+      const left = Number(startCell.col) - 1;
+      const bottom = Number(endCell.row) - 1;
+      const right = Number(endCell.col) - 1;
+      if (top >= maxRowExclusive) return;
+      merges.push({
+        startRow: top,
+        startColumn: left,
+        endRow: Math.min(bottom, maxRowExclusive - 1),
+        endColumn: right,
+      });
+    } catch {
+      // ignore
+    }
+  });
+  return merges;
+};
+
+const post = (msg) => {
+  if (parentPort) parentPort.postMessage(msg);
+};
+
+const main = async () => {
+  const data = workerData || {};
+  const {
+    id,
+    xlsxPath,
+    uploadDir,
+    fileName = 'workbook.xlsx',
+    blockRowSize = 2000,
+    maxRows = 100000,
+  } = data;
+
+  if (!id || !xlsxPath || !uploadDir) {
+    throw new Error('workerData 缺少 id / xlsxPath / uploadDir');
+  }
+
+  const effectiveMaxRows = maxRows === 0 ? Number.POSITIVE_INFINITY : maxRows;
+  const buffer = await readFile(xlsxPath);
+
+  post({ type: 'progress', percent: 5, parsedBlocks: 0, totalBlocks: 0 });
+
+  const workbook = new ExcelJS.Workbook();
+  await workbook.xlsx.load(buffer);
+
+  post({ type: 'progress', percent: 20, parsedBlocks: 0, totalBlocks: 0 });
+
+  const sheetsMeta = [];
+  const sheetOrder = [];
+  let truncated = false;
+  let emittedBlocks = 0;
+
+  const sheetInfos = workbook.worksheets.map((worksheet, sheetIndex) => {
+    const sheetId = `sheet-${sheetIndex}`;
+    const actualRowCount = worksheet.rowCount || 0;
+    const cappedRows = Math.min(actualRowCount, effectiveMaxRows);
+    if (actualRowCount > effectiveMaxRows) truncated = true;
+    const blockCount = Math.max(1, Math.ceil(Math.max(cappedRows, 1) / blockRowSize));
+    return { worksheet, sheetIndex, sheetId, cappedRows, blockCount };
+  });
+
+  const totalBlocks = sheetInfos.reduce((sum, info) => sum + info.blockCount, 0) || 1;
+
+  for (const info of sheetInfos) {
+    const { worksheet, sheetIndex, sheetId, cappedRows, blockCount } = info;
+    sheetOrder.push(sheetId);
+
+    let maxCol = 0;
+    const mergeData = collectMerges(worksheet, cappedRows);
+
+    for (let blockIndex = 0; blockIndex < blockCount; blockIndex += 1) {
+      const startRow = blockIndex * blockRowSize;
+      const endRow = Math.min(cappedRows, startRow + blockRowSize) - 1;
+      const cellData = {};
+
+      if (cappedRows > 0 && endRow >= startRow) {
+        for (let excelRow = startRow + 1; excelRow <= endRow + 1; excelRow += 1) {
+          const row = worksheet.getRow(excelRow);
+          row.eachCell({ includeEmpty: false }, (cell, colNumber) => {
+            const mapped = cellFromExcelJs(cell);
+            if (!mapped) return;
+            const r = excelRow - 1;
+            const c = colNumber - 1;
+            if (!cellData[r]) cellData[r] = {};
+            cellData[r][c] = mapped;
+            maxCol = Math.max(maxCol, colNumber);
+          });
+        }
+      }
+
+      const blockName = `${id}.block.${sheetIndex}.${blockIndex}.json`;
+      await writeFile(
+        path.join(uploadDir, blockName),
+        JSON.stringify({
+          sheetId,
+          sheetIndex,
+          blockIndex,
+          startRow: Math.max(0, startRow),
+          endRow: Math.max(0, endRow),
+          cellData,
+        }),
+        'utf8',
+      );
+
+      emittedBlocks += 1;
+      const percent = Math.min(95, 20 + Math.round((emittedBlocks / totalBlocks) * 75));
+      post({
+        type: 'progress',
+        percent,
+        parsedBlocks: emittedBlocks,
+        totalBlocks,
+      });
+    }
+
+    sheetsMeta.push({
+      id: sheetId,
+      name: worksheet.name || `Sheet${sheetIndex + 1}`,
+      rowCount: Math.max(cappedRows, 1),
+      columnCount: Math.max(maxCol, 1),
+      blockCount,
+      mergeData: mergeData.length ? mergeData : undefined,
+    });
+  }
+
+  const meta = {
+    parseEngine: 'exceljs',
+    fileName,
+    name: String(fileName).replace(/\.xlsx$/i, '') || 'workbook',
+    sheetOrder,
+    sheets: sheetsMeta,
+    blockRowSize,
+    truncated: truncated || undefined,
+    maxRows: Number.isFinite(effectiveMaxRows) ? effectiveMaxRows : undefined,
+  };
+
+  const metaFileName = `${id}.meta.json`;
+  await writeFile(path.join(uploadDir, metaFileName), JSON.stringify(meta), 'utf8');
+
+  post({
+    type: 'done',
+    metaPath: metaFileName,
+    metaFileName,
+    parsedBlocks: emittedBlocks,
+    totalBlocks,
+    truncated: meta.truncated,
+  });
+};
+
+main().catch((error) => {
+  post({
+    type: 'error',
+    message: error instanceof Error ? error.message : String(error),
+  });
+  process.exitCode = 1;
+});

package/lib/server/src/app.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.module.js","sourceRoot":"","sources":["../../../src/app.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAwC;AACxC,uDAAmD;AAK5C,IAAM,SAAS,GAAf,MAAM,SAAS;CAAG,CAAA;AAAZ,8BAAS;oBAAT,SAAS;IAHrB,IAAA,eAAM,EAAC;QACN,OAAO,EAAE,CAAC,0BAAW,CAAC;KACvB,CAAC;GACW,SAAS,CAAG"}

package/lib/server/src/config/env.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export declare const serverEnvSchema: z.ZodObject<{
+    IMS_SERVER_PORT: z.ZodDefault<z.ZodNumber>;
+    PORT: z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>, number | undefined, string | number | undefined>;
+    IMS_SERVER_BODY_LIMIT: z.ZodDefault<z.ZodString>;
+    IMS_SERVER_GZIP_THRESHOLD: z.ZodDefault<z.ZodNumber>;
+    IMS_EXCEL_UPLOAD_DIR: z.ZodOptional<z.ZodString>;
+    IMS_EXCEL_UPLOAD_TTL_MS: z.ZodDefault<z.ZodNumber>;
+    IMS_EXCEL_UPLOAD_CLEANUP_MS: z.ZodDefault<z.ZodNumber>;
+    IMS_EXCEL_CHUNK_BYTES: z.ZodDefault<z.ZodNumber>;
+    IMS_EXCEL_BLOCK_ROWS: z.ZodDefault<z.ZodNumber>;
+    IMS_EXCEL_MAX_ROWS: z.ZodDefault<z.ZodNumber>;
+    IMS_EXCEL_PARSE_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    IMS_EXCEL_UPLOAD_TTL_MS: number;
+    IMS_EXCEL_UPLOAD_CLEANUP_MS: number;
+    IMS_EXCEL_CHUNK_BYTES: number;
+    IMS_EXCEL_PARSE_TIMEOUT_MS: number;
+    IMS_EXCEL_BLOCK_ROWS: number;
+    IMS_EXCEL_MAX_ROWS: number;
+    IMS_SERVER_PORT: number;
+    IMS_SERVER_BODY_LIMIT: string;
+    IMS_SERVER_GZIP_THRESHOLD: number;
+    IMS_EXCEL_UPLOAD_DIR?: string | undefined;
+    PORT?: number | undefined;
+}, {
+    IMS_EXCEL_UPLOAD_DIR?: string | undefined;
+    IMS_EXCEL_UPLOAD_TTL_MS?: number | undefined;
+    IMS_EXCEL_UPLOAD_CLEANUP_MS?: number | undefined;
+    IMS_EXCEL_CHUNK_BYTES?: number | undefined;
+    IMS_EXCEL_PARSE_TIMEOUT_MS?: number | undefined;
+    IMS_EXCEL_BLOCK_ROWS?: number | undefined;
+    IMS_EXCEL_MAX_ROWS?: number | undefined;
+    IMS_SERVER_PORT?: number | undefined;
+    PORT?: string | number | undefined;
+    IMS_SERVER_BODY_LIMIT?: string | undefined;
+    IMS_SERVER_GZIP_THRESHOLD?: number | undefined;
+}>;
+export type ServerEnv = z.infer<typeof serverEnvSchema>;
+export declare const loadServerEnv: (env?: NodeJS.ProcessEnv) => ServerEnv;

package/lib/server/src/config/env.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadServerEnv = exports.serverEnvSchema = void 0;
+const zod_1 = require("zod");
+exports.serverEnvSchema = zod_1.z.object({
+    IMS_SERVER_PORT: zod_1.z.coerce.number().int().positive().default(3010),
+    PORT: zod_1.z
+        .union([zod_1.z.string(), zod_1.z.number()])
+        .optional()
+        .transform((value) => {
+        if (value === undefined || value === '')
+            return undefined;
+        const num = typeof value === 'number' ? value : Number(value);
+        return Number.isFinite(num) && num > 0 ? num : undefined;
+    }),
+    IMS_SERVER_BODY_LIMIT: zod_1.z.string().default('50mb'),
+    IMS_SERVER_GZIP_THRESHOLD: zod_1.z.coerce.number().int().nonnegative().default(1024),
+    IMS_EXCEL_UPLOAD_DIR: zod_1.z.string().optional(),
+    IMS_EXCEL_UPLOAD_TTL_MS: zod_1.z.coerce.number().int().positive().default(60 * 60 * 1000),
+    IMS_EXCEL_UPLOAD_CLEANUP_MS: zod_1.z.coerce.number().int().positive().default(10 * 60 * 1000),
+    IMS_EXCEL_CHUNK_BYTES: zod_1.z.coerce.number().int().positive().default(2 * 1024 * 1024),
+    IMS_EXCEL_BLOCK_ROWS: zod_1.z.coerce.number().int().min(100).default(5_000),
+    IMS_EXCEL_MAX_ROWS: zod_1.z.coerce.number().int().nonnegative().default(150_000),
+    IMS_EXCEL_PARSE_TIMEOUT_MS: zod_1.z.coerce.number().int().positive().default(10 * 60 * 1000),
+});
+const loadServerEnv = (env = process.env) => {
+    const result = exports.serverEnvSchema.safeParse(env);
+    if (!result.success) {
+        const message = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+        throw new Error(`[@ims-view/server] 环境变量校验失败: ${message}`);
+    }
+    return result.data;
+};
+exports.loadServerEnv = loadServerEnv;
+//# sourceMappingURL=env.js.map

package/lib/server/src/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../../src/config/env.ts"],"names":[],"mappings":"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"}

package/lib/server/src/excel/dto/excel-task-id.dto.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export declare const excelTaskIdSchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+declare const ExcelTaskIdDto_base: import("../../shared/create-zod-base-model").ZodBaseModel<z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>>;
+export declare class ExcelTaskIdDto extends ExcelTaskIdDto_base {
+}
+export type ExcelTaskIdPlain = z.infer<typeof excelTaskIdSchema>;
+export {};

package/lib/server/src/excel/dto/excel-task-id.dto.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExcelTaskIdDto = exports.excelTaskIdSchema = void 0;
+const zod_1 = require("zod");
+const create_zod_base_model_1 = require("../../shared/create-zod-base-model");
+exports.excelTaskIdSchema = zod_1.z.object({
+    id: zod_1.z
+        .string()
+        .trim()
+        .min(1, '任务 id 不能为空')
+        .regex(/^[a-zA-Z0-9_-]+$/, '任务 id 格式无效')
+        .describe('解析任务 id'),
+});
+class ExcelTaskIdDto extends (0, create_zod_base_model_1.createZodBaseModel)(exports.excelTaskIdSchema) {
+}
+exports.ExcelTaskIdDto = ExcelTaskIdDto;
+//# sourceMappingURL=excel-task-id.dto.js.map

package/lib/server/src/excel/dto/excel-task-id.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel-task-id.dto.js","sourceRoot":"","sources":["../../../../../src/excel/dto/excel-task-id.dto.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,8EAAwE;AAE3D,QAAA,iBAAiB,GAAG,OAAC,CAAC,MAAM,CAAC;IACxC,EAAE,EAAE,OAAC;SACF,MAAM,EAAE;SACR,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC;SACpB,KAAK,CAAC,kBAAkB,EAAE,YAAY,CAAC;SACvC,QAAQ,CAAC,SAAS,CAAC;CACvB,CAAC,CAAC;AAEH,MAAa,cAAe,SAAQ,IAAA,0CAAkB,EAAC,yBAAiB,CAAC;CAAG;AAA5E,wCAA4E"}

package/lib/server/src/excel/dto/export-excel.dto.d.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+export declare const exportExcelSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    data: z.ZodOptional<z.ZodAny>;
+    fileName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    data?: any;
+    fileName?: string | undefined;
+}, {
+    data?: any;
+    fileName?: string | undefined;
+}>, {
+    data?: any;
+    fileName?: string | undefined;
+}, {
+    data?: any;
+    fileName?: string | undefined;
+}>, {
+    fileName: string | undefined;
+    data: z.objectOutputType<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        appVersion: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+        sheetOrder: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        sheets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        styles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        resources: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    }, z.ZodTypeAny, "passthrough">;
+}, {
+    data?: any;
+    fileName?: string | undefined;
+}>;
+declare const ExportExcelDto_base: import("../../shared/create-zod-base-model").ZodBaseModel<z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    data: z.ZodOptional<z.ZodAny>;
+    fileName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    data?: any;
+    fileName?: string | undefined;
+}, {
+    data?: any;
+    fileName?: string | undefined;
+}>, {
+    data?: any;
+    fileName?: string | undefined;
+}, {
+    data?: any;
+    fileName?: string | undefined;
+}>, {
+    fileName: string | undefined;
+    data: z.objectOutputType<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        appVersion: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+        sheetOrder: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        sheets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        styles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        resources: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    }, z.ZodTypeAny, "passthrough">;
+}, {
+    data?: any;
+    fileName?: string | undefined;
+}>>;
+export declare class ExportExcelDto extends ExportExcelDto_base {
+}
+export type ExportExcelPlain = z.infer<typeof exportExcelSchema>;
+export {};

package/lib/server/src/excel/dto/export-excel.dto.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExportExcelDto = exports.exportExcelSchema = void 0;
+const zod_1 = require("zod");
+const create_zod_base_model_1 = require("../../shared/create-zod-base-model");
+const workbookDataSchema = zod_1.z
+    .object({
+    id: zod_1.z.string().optional(),
+    name: zod_1.z.string().optional(),
+    appVersion: zod_1.z.string().optional(),
+    locale: zod_1.z.string().optional(),
+    sheetOrder: zod_1.z.array(zod_1.z.string()).optional(),
+    sheets: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
+    styles: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
+    resources: zod_1.z.array(zod_1.z.any()).optional(),
+})
+    .passthrough();
+exports.exportExcelSchema = zod_1.z
+    .object({
+    data: zod_1.z.any().optional().describe('工作簿 snapshot'),
+    fileName: zod_1.z.string().trim().min(1, '文件名不能为空').optional().describe('导出文件名'),
+})
+    .superRefine((value, ctx) => {
+    if (value.data == null || typeof value.data !== 'object' || Array.isArray(value.data)) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['data'],
+            message: '缺少工作簿数据 data',
+        });
+        return;
+    }
+    const parsed = workbookDataSchema.safeParse(value.data);
+    if (!parsed.success) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['data'],
+            message: parsed.error.issues[0]?.message || 'data 格式无效',
+        });
+    }
+})
+    .transform((value) => ({
+    fileName: value.fileName,
+    data: workbookDataSchema.parse(value.data),
+}));
+class ExportExcelDto extends (0, create_zod_base_model_1.createZodBaseModel)(exports.exportExcelSchema) {
+}
+exports.ExportExcelDto = ExportExcelDto;
+//# sourceMappingURL=export-excel.dto.js.map

package/lib/server/src/excel/dto/export-excel.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-excel.dto.js","sourceRoot":"","sources":["../../../../../src/excel/dto/export-excel.dto.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,8EAAwE;AAExE,MAAM,kBAAkB,GAAG,OAAC;KACzB,MAAM,CAAC;IACN,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACzB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,UAAU,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC1C,MAAM,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE;IAChD,MAAM,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE;IAChD,SAAS,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvC,CAAC;KACD,WAAW,EAAE,CAAC;AAGJ,QAAA,iBAAiB,GAAG,OAAC;KAC/B,MAAM,CAAC;IACN,IAAI,EAAE,OAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;IACjD,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;CAC3E,CAAC;KACD,WAAW,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;IAC1B,IAAI,KAAK,CAAC,IAAI,IAAI,IAAI,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACtF,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,OAAC,CAAC,YAAY,CAAC,MAAM;YAC3B,IAAI,EAAE,CAAC,MAAM,CAAC;YACd,OAAO,EAAE,cAAc;SACxB,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,OAAC,CAAC,YAAY,CAAC,MAAM;YAC3B,IAAI,EAAE,CAAC,MAAM,CAAC;YACd,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,WAAW;SACxD,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC;KACD,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,QAAQ;IACxB,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;CAC3C,CAAC,CAAC,CAAC;AAEN,MAAa,cAAe,SAAQ,IAAA,0CAAkB,EAAC,yBAAiB,CAAC;CAAG;AAA5E,wCAA4E"}

package/lib/server/src/excel/excel-storage.service.d.ts

@@ -0,0 +1,54 @@
+import { OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+export declare const getExcelUploadDir: () => string;
+export declare const EXCEL_STATIC_PREFIX = "/excel/static";
+export declare const preserveUploadFileName: (raw?: string) => string;
+export type StoredExcelFile = {
+    id: string;
+    fileName: string;
+    path: string;
+    size: number;
+    expiresAt: number;
+};
+export type ExcelParseTaskStatus = 'pending' | 'done' | 'error';
+export type ExcelParseMode = 'snapshot' | 'chunked';
+export type ExcelParseTask = {
+    id: string;
+    status: ExcelParseTaskStatus;
+    mode?: ExcelParseMode;
+    fileName: string;
+    xlsxPath: string;
+    snapshotPath?: string;
+    metaPath?: string;
+    progress?: number;
+    parsedBlocks?: number;
+    totalBlocks?: number;
+    truncated?: boolean;
+    error?: string;
+    startedAt: number;
+    finishedAt?: number;
+};
+export declare class ExcelStorageService implements OnModuleInit, OnModuleDestroy {
+    private readonly logger;
+    private readonly uploadDir;
+    private cleanupTimer;
+    private readonly tasks;
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): void;
+    getUploadDir(): string;
+    getTask(id: string): ExcelParseTask | undefined;
+    getXlsxFullPath(id: string): string;
+    saveXlsx(buffer: Buffer, originalName: string): Promise<StoredExcelFile>;
+    setTaskMode(id: string, mode: ExcelParseMode): void;
+    updateTaskProgress(id: string, progress: number, parsedBlocks?: number, totalBlocks?: number): void;
+    saveSnapshot(id: string, workbookData: unknown): Promise<string>;
+    markTaskChunkedDone(id: string, metaFileName: string, extras?: {
+        parsedBlocks?: number;
+        totalBlocks?: number;
+        truncated?: boolean;
+    }): string;
+    markTaskError(id: string, error: string): void;
+    readSnapshot(id: string): Promise<unknown | null>;
+    private isManagedFile;
+    private idFromFileName;
+    cleanupExpired(): Promise<number>;
+}