feat(rest): native server-side xlsx parsing in /import

Accept format:'xlsx' with a base64-encoded workbook (xlsxBase64) and an
optional sheet selector. The server flattens ExcelJS cells to their
human-visible text (formula results, hyperlink text, rich-text runs,
dates -> ISO) so a parsed xlsx yields the same cells a CSV export would,
then feeds them through the existing coercion + upsert pipeline.

- spec: extend ImportRequestSchema format enum with 'xlsx'; add
  xlsxBase64 + sheet fields.
- rest: xlsxCellToString + parseXlsxToRows helpers (dynamic exceljs
  import so csv/json imports don't pay for it); wire the xlsx branch
  into the /import body parser; 400 on malformed workbooks.
- tests: 3 integration cases (coercion parity with csv, named-sheet
  selection + format inference, malformed-payload 400).

Author: baozhoutao

packages/rest/src/import-integration.test.ts

@@ -237,4 +237,49 @@ describe('import route — real engine + protocol integration', () => {
     expect(res._status).toBe(400);
     expect(res._json.code).toBe('INVALID_REQUEST');
   });
+
+  it('parses a native xlsx workbook server-side and coerces cells like csv', async () => {
+    const ExcelJS: any = (await import('exceljs')).default ?? (await import('exceljs'));
+    const wb = new ExcelJS.Workbook();
+    const ws = wb.addWorksheet('Sheet1');
+    ws.addRow(['ID', '标题', '完成', '优先级', '分数', '截止', '负责人']);
+    ws.addRow(['1', '写代码', '是', '高', 1200, new Date('2026-06-30T00:00:00Z'), '张三']);
+    ws.addRow(['2', '测试', '否', '低', 3, '2026/07/01', '李四']);
+    const buf = await wb.xlsx.writeBuffer();
+    const xlsxBase64 = Buffer.from(buf).toString('base64');
+
+    const res = await call(route, {
+      format: 'xlsx', xlsxBase64,
+      mapping: { ID: 'id', 标题: 'title', 完成: 'done', 优先级: 'priority', 分数: 'score', 截止: 'due', 负责人: 'owner' },
+    });
+    expect(res._json).toMatchObject({ total: 2, ok: 2, errors: 0, created: 2 });
+    const one = await engine.findOne('task', { where: { id: '1' } });
+    expect(one).toMatchObject({ title: '写代码', done: true, priority: 'high', score: 1200, owner: 'u1' });
+    expect(String(one.due)).toContain('2026-06-30');
+    const two = await engine.findOne('task', { where: { id: '2' } });
+    expect(two).toMatchObject({ title: '测试', done: false, priority: 'low', score: 3, owner: 'u2' });
+  });
+
+  it('reads xlsxBase64 without an explicit format and honors the sheet selector', async () => {
+    const ExcelJS: any = (await import('exceljs')).default ?? (await import('exceljs'));
+    const wb = new ExcelJS.Workbook();
+    wb.addWorksheet('Empty'); // decoy first sheet
+    const ws = wb.addWorksheet('Data');
+    ws.addRow(['id', 'title', 'score']);
+    ws.addRow(['x1', 'from-named-sheet', 7]);
+    const buf = await wb.xlsx.writeBuffer();
+    const xlsxBase64 = Buffer.from(buf).toString('base64');
+
+    const res = await call(route, { xlsxBase64, sheet: 'Data' });
+    expect(res._json).toMatchObject({ total: 1, ok: 1, created: 1 });
+    const row = await engine.findOne('task', { where: { id: 'x1' } });
+    expect(row).toMatchObject({ title: 'from-named-sheet', score: 7 });
+  });
+
+  it('rejects a malformed xlsx payload with 400', async () => {
+    const res = await call(route, { format: 'xlsx', xlsxBase64: Buffer.from('not a workbook').toString('base64') });
+    expect(res._status).toBe(400);
+    expect(res._json.code).toBe('INVALID_REQUEST');
+    expect(String(res._json.error)).toMatch(/xlsx/i);
+  });
 });

packages/rest/src/rest-server.ts

@@ -382,6 +382,75 @@ function parseCsvToRows(csv: string, mapping: Record<string, string> = {}): Arra
     return out;
 }
 
+/**
+ * Flatten one ExcelJS cell value to the raw string the coercion layer expects.
+ * ExcelJS hands back rich objects for formulas / hyperlinks / rich text / dates;
+ * we reduce each to the human-visible text so a server-parsed xlsx yields the
+ * same cells a CSV export would (dates → ISO, so parseDateCell can re-read them).
+ */
+function xlsxCellToString(value: any): string {
+    if (value === null || value === undefined) return '';
+    if (typeof value === 'string') return value;
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') return String(value);
+    if (value instanceof Date) return value.toISOString();
+    if (typeof value === 'object') {
+        // Formula cell → prefer its computed result.
+        if ('result' in value && value.result !== undefined && value.result !== null) return xlsxCellToString(value.result);
+        // Hyperlink cell → the visible text, not the target.
+        if ('text' in value && typeof value.text === 'string') return value.text;
+        if ('hyperlink' in value && typeof value.hyperlink === 'string') return value.hyperlink;
+        // Rich text → concatenate runs.
+        if (Array.isArray(value.richText)) return value.richText.map((r: any) => r?.text ?? '').join('');
+        if ('error' in value && value.error) return String(value.error);
+    }
+    try { return String(value); } catch { return ''; }
+}
+
+/**
+ * Parse an .xlsx workbook (raw bytes) into row objects, mirroring
+ * {@link parseCsvToRows}: first non-empty row is the header, each subsequent row
+ * becomes `{ header→cell }` with the optional `mapping` renaming columns. Reads
+ * the named/indexed `sheet` when given, else the first worksheet. Dynamically
+ * imports ExcelJS (already a dependency of the export path) so CSV/JSON imports
+ * don't pay for it.
+ */
+async function parseXlsxToRows(
+    buffer: Buffer | ArrayBuffer,
+    mapping: Record<string, string> = {},
+    sheet?: string | number,
+): Promise<Array<Record<string, any>>> {
+    const ExcelJS: any = (await import('exceljs')).default ?? (await import('exceljs'));
+    const wb = new ExcelJS.Workbook();
+    await wb.xlsx.load(buffer);
+    const ws = sheet !== undefined ? wb.getWorksheet(sheet as any) : wb.worksheets[0];
+    if (!ws) return [];
+
+    const cells: string[][] = [];
+    ws.eachRow({ includeEmpty: false }, (row: any) => {
+        const values = row.values as any[]; // 1-based; index 0 is unused
+        const line: string[] = [];
+        for (let c = 1; c < values.length; c++) line.push(xlsxCellToString(values[c]));
+        cells.push(line);
+    });
+    while (cells.length > 0 && cells[cells.length - 1].every(c => c === '')) cells.pop();
+    if (cells.length < 2) return [];
+
+    const header = cells[0].map(h => h.trim());
+    const fields = header.map(h => mapping[h] ?? h);
+    const out: Array<Record<string, any>> = [];
+    for (let r = 1; r < cells.length; r++) {
+        const line = cells[r];
+        const obj: Record<string, any> = {};
+        for (let c = 0; c < fields.length; c++) {
+            const key = fields[c];
+            if (!key) continue;
+            obj[key] = line[c] ?? '';
+        }
+        out.push(obj);
+    }
+    return out;
+}
+
 /**
  * Escape a single value into an RFC-4180 CSV cell. Values containing
  * commas, quotes, CR, or LF are wrapped in double-quotes with embedded
@@ -3259,19 +3328,32 @@ export class RestServer {
                         return out;
                     };
 
-                    // Build rows[] from either explicit JSON array or CSV text.
+                    // Build rows[] from JSON array, CSV text, or a base64 xlsx.
                     let rows: Array<Record<string, any>> = [];
                     if (body.format === 'json' && Array.isArray(body.rows)) {
                         rows = (body.rows as Array<Record<string, any>>).map(applyMapping);
                     } else if ((body.format === 'csv' || typeof body.csv === 'string') && typeof body.csv === 'string') {
                         rows = parseCsvToRows(body.csv, mapping);
+                    } else if ((body.format === 'xlsx' || typeof body.xlsxBase64 === 'string') && typeof body.xlsxBase64 === 'string') {
+                        // Native server-side xlsx parse — the client uploads raw
+                        // workbook bytes (base64) instead of pre-flattening to CSV.
+                        try {
+                            const buf = Buffer.from(body.xlsxBase64, 'base64');
+                            rows = await parseXlsxToRows(buf, mapping, body.sheet);
+                        } catch (e: any) {
+                            res.status(400).json({
+                                code: 'INVALID_REQUEST',
+                                error: `Failed to parse xlsx: ${e?.message ?? String(e)}`,
+                            });
+                            return;
+                        }
                     } else if (Array.isArray(body)) {
                         // Permissive: a bare JSON array at the top level.
                         rows = (body as Array<Record<string, any>>).map(applyMapping);
                     } else {
                         res.status(400).json({
                             code: 'INVALID_REQUEST',
-                            error: 'Provide either format:"csv" with csv text or format:"json" with rows[]',
+                            error: 'Provide format:"csv" with csv text, format:"json" with rows[], or format:"xlsx" with xlsxBase64',
                         });
                         return;
                     }

packages/spec/src/api/export.zod.ts

@@ -300,11 +300,15 @@ export type ImportMapping = z.infer<typeof ImportMappingSchema>;
  * }
  */
 export const ImportRequestSchema = lazySchema(() => z.object({
-  format: z.enum(['csv', 'json']).optional()
-    .describe('Payload shape: csv text or a rows[] array (inferred when omitted)'),
+  format: z.enum(['csv', 'json', 'xlsx']).optional()
+    .describe('Payload shape: csv text, a rows[] array, or a base64 xlsx (inferred when omitted)'),
   csv: z.string().optional().describe('CSV text (when format = csv)'),
   rows: z.array(z.record(z.string(), z.unknown())).optional()
     .describe('Row objects (when format = json)'),
+  xlsxBase64: z.string().optional()
+    .describe('Base64-encoded .xlsx workbook bytes (when format = xlsx); parsed server-side'),
+  sheet: z.union([z.string(), z.number().int()]).optional()
+    .describe('Worksheet name or 1-based index to read (xlsx; defaults to the first sheet)'),
   mapping: ImportMappingSchema.optional()
     .describe('Source column → target field mapping'),
   dryRun: z.boolean().default(false)