@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/core/import.js

@@ -0,0 +1,753 @@
+// `bitable table --import` 的客户端解析：CSV/XLSX → 类型推断 → 分批 → 取值转换。
+//
+// 这是"业务计算在客户端"的第一个落点（契约 §6.2）：平台只存结果，
+// 解析、推断、分批、幂等键全在本地做完。
+//
+// 推断规则（**可解释、可覆盖**）：
+//
+// | 判定 | 依据 | 落到哪个字段类型 |
+// |---|---|---|
+// | 布尔 | 全部取值 ∈ {true,false,yes,no,是,否,...} | `boolean` |
+// | 日期 | 全部匹配 `YYYY-MM-DD` / `YYYY/M/D` / `YYYY.M.D` / `YYYYMMDD`（且是真实日历日） | `date` |
+// | 金额 | 出现 `￥$¥€`、千分位（`1,234.00`）、会计负数（`(123.45)`） | `currency` |
+// | 数值 | 全部是整数/小数（可带 `%` 或正负号） | `number` |
+// | 文本 | 其余 | `text` |
+//
+// 判定顺序是刻意的：**日期先于数值**（`20260301` 既是数字也是日期，
+// 但在单据里它是日期），**金额先于数值**（千分位小数是金额的语言）。
+// 想推翻推断就 `--type 列名=类型`，它以最高优先级生效。
+//
+// 一条硬约束：列的 `semantic_key` 必须匹配服务端的 `^[a-z][a-z0-9_]{0,63}$`。
+// 中文列名做不了机器名，所以中文列自动得到 `col_3` 这样的键，
+// **显示名仍是原列名** —— `values` 两种写法都接受（semantic_key 或 field_id），
+// 导入结果里会把对应关系逐列返回，后续读写照着用即可。
+//
+// 本模块是 `cli/crates/xinhe-oa-cli/src/import.rs` 的逐函数移植（含全部单测口径）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+import { CliError } from './error.js';
+import { rustIoErrorText } from './util.js';
+import { readXlsx } from './xlsx.js';
+
+/**
+ * 单批记录数上限，**与服务端 `/me` 公布的 `rate_limits.row_ops_batch_max` 同值**。
+ *
+ * 2026-09-29 之前这里是 200，而服务端一直是 500 —— 客户端自己把批切得更小，
+ * 每批都要付一次固定开销（认证、幂等查重、事务提交）。2 万行按 200 切是 106 批，
+ * 按 500 切是 43 批：省下的正是这 63 次的固定开销。
+ *
+ * 服务端会**真的**按这个数收口（超了报 `request.invalid`），所以它是契约而不是建议。
+ */
+export const MAX_BATCH = 500;
+
+/** 客户端支持推断出的字段类型（与服务端 `FIELD_TYPES` 同一份名单）。 */
+export const FIELD_TYPES = [
+  'text',
+  'number',
+  'currency',
+  'date',
+  'single_select',
+  'multi_select',
+  'boolean',
+  'person',
+  'attachment_ref',
+  'relation',
+];
+
+/** 列的类型。 */
+export const ColumnType = Object.freeze({
+  Text: 'text',
+  Number: 'number',
+  Currency: 'currency',
+  Date: 'date',
+  Boolean: 'boolean',
+});
+
+/** 为什么这么推断（写进结果，让人能复核，而不是"机器说它是金额"）。 */
+export function typeReason(type) {
+  switch (type) {
+    case ColumnType.Text:
+      return '有非数值/非日期的取值';
+    case ColumnType.Number:
+      return '全部取值都是数值（含百分比）';
+    case ColumnType.Currency:
+      return '出现币种符号/千分位/会计负数';
+    case ColumnType.Date:
+      return '全部取值都是日期';
+    default:
+      return '全部取值都是布尔字面量';
+  }
+}
+
+/**
+ * 服务端字段类型 → 列类型。
+ *
+ * `--append` 追加到已有表时用：写记录要按**表里那个字段的类型**来转值，
+ * 而不是按这次文件推断出来的类型（推断只是给新建字段用的建议）。
+ * `single_select` / `multi_select` / `person` / `attachment_ref` / `relation`
+ * 没有值级推断，返回 `null` —— 调用方按文本原样写，让服务端校验。
+ */
+export function columnTypeFromServer(raw) {
+  switch (String(raw ?? '').trim().toLowerCase()) {
+    case 'text':
+      return ColumnType.Text;
+    case 'number':
+      return ColumnType.Number;
+    case 'currency':
+      return ColumnType.Currency;
+    case 'date':
+      return ColumnType.Date;
+    case 'boolean':
+      return ColumnType.Boolean;
+    default:
+      return null;
+  }
+}
+
+/** `--type 列名=类型` 的右侧：只认能推断出来的那几种（`bool` 是别名）。 */
+export function parseColumnType(raw) {
+  switch (String(raw ?? '').trim().toLowerCase()) {
+    case 'text':
+      return ColumnType.Text;
+    case 'number':
+      return ColumnType.Number;
+    case 'currency':
+      return ColumnType.Currency;
+    case 'date':
+      return ColumnType.Date;
+    case 'boolean':
+    case 'bool':
+      return ColumnType.Boolean;
+    default:
+      throw CliError.usage(
+        `列类型只能是 ${FIELD_TYPES.join(' / ')}（收到 ${JSON.stringify(
+          String(raw ?? '').trim().toLowerCase(),
+        )}）`,
+      ).withHint('`--type` 只覆盖类型；person / relation / 选项类字段请建表后用 bitable field --create');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 值级推断
+// ---------------------------------------------------------------------------
+export function isBlank(raw) {
+  const trimmed = String(raw ?? '').trim();
+  return (
+    trimmed.length === 0 ||
+    trimmed === '-' ||
+    trimmed === '—' ||
+    trimmed.toLowerCase() === 'null'
+  );
+}
+
+/** 布尔字面量（与服务端 `_coerce_boolean` 接受的一致，再加中文）。 */
+export function asBool(raw) {
+  switch (String(raw ?? '').trim().toLowerCase()) {
+    case 'true':
+    case '1':
+    case 't':
+    case 'yes':
+    case 'y':
+    case '是':
+    case '有':
+      return true;
+    case 'false':
+    case '0':
+    case 'f':
+    case 'no':
+    case 'n':
+    case '否':
+    case '无':
+      return false;
+    default:
+      return null;
+  }
+}
+
+const CURRENCY_SYMBOLS = ['￥', '¥', '$', '€', '£', '元', 'RMB', 'rmb', 'CNY', 'cny'];
+
+/**
+ * 去掉币种符号与千分位；会计负数 `(123.45)` → `-123.45`。
+ *
+ * @returns {{value: string, money: boolean, scale: number}|null}
+ *   `money` = "这看起来像金额"：千分位、币种符号、会计负数都是金额的语言；
+ *   **百分比不是**（`12%` 是比率，不是钱）。
+ */
+export function normalizeNumber(raw) {
+  let text = String(raw ?? '').trim();
+  if (text.length === 0) return null;
+  // 会计负数：`(123.45)` 是财务报表里"负数"的写法，也是**金额**的信号。
+  let negative = false;
+  let parenNegative = false;
+  if (text.startsWith('(') && text.endsWith(')')) {
+    negative = true;
+    parenNegative = true;
+    text = text.slice(1, -1).trim();
+  }
+  let hasSymbol = false;
+  for (const symbol of CURRENCY_SYMBOLS) {
+    if (text.includes(symbol)) {
+      hasSymbol = true;
+      text = text.split(symbol).join('');
+    }
+  }
+  if (text.startsWith('-')) {
+    negative = !negative;
+    text = text.slice(1).trim();
+  } else if (text.startsWith('+')) {
+    text = text.slice(1).trim();
+  }
+  // 百分比：识别并**剥掉**，值仍是数值（`12%` → 12）
+  if (text.endsWith('%')) text = text.slice(0, -1).trim();
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return null;
+  const hasThousands = trimmed.includes(',');
+  const cleaned = trimmed.split(',').join('');
+  const dot = cleaned.indexOf('.');
+  const integer = dot >= 0 ? cleaned.slice(0, dot) : cleaned;
+  const fraction = dot >= 0 ? cleaned.slice(dot + 1) : '';
+  if (integer.length === 0 && fraction.length === 0) return null;
+  if (!/^[0-9]*$/.test(integer) || !/^[0-9]*$/.test(fraction)) return null;
+  const scale = fraction.length;
+  return {
+    value: negative ? `-${cleaned}` : cleaned,
+    money: hasThousands || hasSymbol || parenNegative,
+    scale,
+  };
+}
+
+/** 日期：只接受无歧义的写法（年月日的顺序在中文单据里几乎恒为 Y-M-D）。 */
+export function asDate(raw) {
+  const text = String(raw ?? '').trim();
+  if (text.length === 0) return null;
+  const normalized = text
+    .split('年')
+    .join('-')
+    .split('月')
+    .join('-')
+    .split('日')
+    .join('')
+    .split('/')
+    .join('-')
+    .split('.')
+    .join('-')
+    .split('．')
+    .join('-')
+    .trim();
+  const parts = normalized.split('-').filter((part) => part.length > 0);
+  let year;
+  let month;
+  let day;
+  if (parts.length === 3) {
+    if (!/^[+-]?[0-9]+$/.test(parts[0]) || !/^[+-]?[0-9]+$/.test(parts[1]) || !/^[+-]?[0-9]+$/.test(parts[2])) {
+      return null;
+    }
+    year = Number.parseInt(parts[0], 10);
+    month = Number.parseInt(parts[1], 10);
+    day = Number.parseInt(parts[2], 10);
+  } else if (parts.length === 1 && /^[0-9]{8}$/.test(parts[0])) {
+    // `YYYYMMDD` 的紧凑写法（纯 8 位数字）。
+    //
+    // **必须先确认它真的是 8 个 ASCII 数字，再切** —— Rust 那边踩过一个 panic：
+    // 只判字符串**字节**长度时，`81滞留`（2 + 3 + 3 = 8 字节、3 个字符）也进得来，
+    // 随后按字节切直接崩，整张表一条都导不进去。这类值在收费明细里真实存在
+    // （诊断编码 `84中龋`、渠道名 `美团3M`、姓名 `崔允xi`），不是理论边界。
+    // JS 的 `length` 是字符数、正则又钉死 ASCII 数字，天然不会犯这个错。
+    const digits = parts[0];
+    year = Number.parseInt(digits.slice(0, 4), 10);
+    month = Number.parseInt(digits.slice(4, 6), 10);
+    day = Number.parseInt(digits.slice(6, 8), 10);
+  } else {
+    return null;
+  }
+  if (year < 1900 || year > 2999 || month < 1 || month > 12 || day < 1 || day > 31) return null;
+  const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+  const maxDay =
+    month === 2 ? (leap ? 29 : 28) : [4, 6, 9, 11].includes(month) ? 30 : 31;
+  if (day > maxDay) return null;
+  return `${String(year).padStart(4, '0')}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+}
+
+/** 采样推断一列的类型（`samples` 里空白值不参与）。 */
+export function inferColumn(samples) {
+  const values = samples.filter((value) => !isBlank(value));
+  if (values.length === 0) return { type: ColumnType.Text, scale: 0 };
+  const total = values.length;
+  let bools = 0;
+  let dates = 0;
+  let numbers = 0;
+  let money = 0;
+  let maxScale = 0;
+  for (const value of values) {
+    if (asBool(value) !== null) bools += 1;
+    if (asDate(value) !== null) dates += 1;
+    const number = normalizeNumber(value);
+    if (number !== null) {
+      numbers += 1;
+      maxScale = Math.max(maxScale, number.scale);
+      if (number.money) money += 1;
+    }
+  }
+  if (bools === total) return { type: ColumnType.Boolean, scale: 0 };
+  if (dates === total) return { type: ColumnType.Date, scale: 0 };
+  if (numbers === total) {
+    return money > 0
+      ? { type: ColumnType.Currency, scale: maxScale }
+      : { type: ColumnType.Number, scale: maxScale };
+  }
+  return { type: ColumnType.Text, scale: maxScale };
+}
+
+/**
+ * 列名看起来是不是**标识符**（流水号 / 手机号 / 门诊号 / ID …）。
+ *
+ * 为什么需要它（真实现场问题）：结算流水号、手机号、门诊号、票据号**全是纯数字**，
+ * 采样推断必然把它们判成 `number`；而数字落库会掉前导零、丢精度，也没法当字符串比较。
+ * 现场的代价是"每一列都得手写 `--type 结算流水号=text`，漏一列就建错类型"——
+ * 而**类型建后不可改**（服务端语义：改类型 = 新建字段 + 回填），只能归档重导。
+ *
+ * 判据刻意保守：**宁可把数字判成文本，也不要把标识符判成数字**。
+ * 数字存成文本仍然可读、可排序、可导出；而标识符存成数字会**静默损坏**
+ * （`007` → `7`），且不可逆。
+ */
+export function looksLikeIdentifier(name) {
+  const markers = ['号', '编号', '流水', 'ID', 'Id', 'id', '证件', '手机', '电话', '邮编'];
+  return markers.some((marker) => String(name ?? '').includes(marker));
+}
+
+/**
+ * 带列名的推断：先按取值推断，再把"像标识符的纯数字列"降级成文本。
+ *
+ * `noInfer = true`（`--no-infer`）时**一律文本**，只有 `--type` 能改写。
+ * 只降级 `Number`：`Currency` 有自己的金额标记（千分位/￥/会计负数），
+ * 那些标记本身就说明"这是钱"，不该被列名里的一个"号"字推翻。
+ */
+export function inferColumnNamed(name, samples, noInfer) {
+  const inferred = inferColumn(samples);
+  if (noInfer) return { type: ColumnType.Text, scale: inferred.scale, downgraded: false };
+  if (inferred.type === ColumnType.Number && looksLikeIdentifier(name)) {
+    return { type: ColumnType.Text, scale: inferred.scale, downgraded: true };
+  }
+  return { ...inferred, downgraded: false };
+}
+
+/** 中文列名做不了机器名 → 给一个稳定的 ASCII 键（`^[a-z][a-z0-9_]{0,63}$`）。 */
+export function semanticKeyOf(name, index, taken) {
+  let ascii = '';
+  for (const ch of String(name ?? '')) {
+    if (/[A-Za-z0-9]/.test(ch)) ascii += ch.toLowerCase();
+    else if (ch.charCodeAt(0) < 128) ascii += '_';
+    // 非 ASCII（中文等）整段丢掉：它在机器名里没有合法的表示
+  }
+  while (ascii.includes('__')) ascii = ascii.split('__').join('_');
+  ascii = ascii.replace(/^_+/, '').replace(/_+$/, '');
+  if (ascii.length > 48) ascii = ascii.slice(0, 48);
+  let candidate =
+    ascii.length === 0 || !/^[a-z]/.test(ascii) ? `col_${index + 1}` : ascii;
+  // 重名去冲突：**逐字照抄 Rust 的那两行**（先按"去掉结尾数字"的基名加后缀，
+  // 再把这个后缀拼一次）—— 结果形如 `amount_2_2`。看着别扭，但机器名是
+  // 跨实现可比的契约：两边生成不同的键，同一份文件在两种实现下会建出不同字段。
+  let suffix = 2;
+  while (taken.includes(candidate)) {
+    const base = candidate.replace(/[0-9]+$/, '');
+    candidate = `${base}_${suffix}`;
+    candidate = `${candidate}_${suffix}`;
+    suffix += 1;
+  }
+  taken.push(candidate);
+  return candidate;
+}
+
+// ---------------------------------------------------------------------------
+// 解析：CSV / XLSX
+// ---------------------------------------------------------------------------
+/**
+ * 解析输入文件（按扩展名分派）。返回 `ParsedTable`：
+ * `{sourceFormat, sheetName, columns, rows, skippedEmptyRows}`。
+ */
+export /** OLE 复合文档（老式 `.xls`）的 8 字节签名。 */
+const OLE_MAGIC = Buffer.from([0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]);
+
+/** 读文件头的 8 个字节；读不了就返回 null（后面交给正常的解析报错）。 */
+function readMagicRaw(filePath) {
+  try {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      const head = Buffer.alloc(8);
+      const read = fs.readSync(fd, head, 0, 8, 0);
+      return read === 8 ? head : null;
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+
+export function parseFile(file, sheet, overrides, noInfer) {
+  const extension = path.extname(String(file ?? '')).replace(/^\./, '').toLowerCase();
+  let grid;
+  let sourceFormat;
+  let sheetName = null;
+  if (extension === 'csv' || extension === 'txt') {
+    grid = parseCsv(file);
+    sourceFormat = 'csv';
+  } else if (extension === 'xlsx' || extension === 'xlsm' || extension === 'xls') {
+    // **老式 `.xls`（BIFF，OLE 复合文档）读不了**：Rust 版靠 calamine 支持它，
+    // Node 版只实现了 OOXML（.xlsx 就是一个 zip）。这里**先看魔术字节**再决定报什么错 ——
+    // 直接交给 zip 解析器会得到"这不是一个 zip：找不到中央目录"，用户完全不知道
+    // 该怎么办。`.xls` 的签名是 `D0 CF 11 E0 A1 B1 1A E1`。
+    if (readMagicRaw(file) !== null && readMagicRaw(file).equals(OLE_MAGIC)) {
+      throw CliError.usage(
+        '这是老式 .xls（Excel 97-2003 二进制格式），当前客户端读不了',
+      ).withHint('在 Excel / WPS 里「另存为 → .xlsx」或「另存为 → CSV UTF-8（逗号分隔）」再导入');
+    }
+    const read = readXlsx(file, sheet ?? null, { formatFloat, serialToDate: excelSerialToDate });
+    grid = read.grid;
+    sourceFormat = 'xlsx';
+    sheetName = read.sheetName;
+  } else {
+    throw CliError.usage(`不认识的扩展名 ${JSON.stringify(extension)}（支持 .csv / .xlsx）`).withHint(
+      'Excel 另存为 CSV，或直接用 .xlsx',
+    );
+  }
+  if (grid.length === 0) {
+    throw CliError.usage(`${file} 里没有数据`).withHint('确认文件不是空的、sheet 选对了');
+  }
+
+  const header = grid.shift();
+  const columns = [];
+  const taken = [];
+  const headerSeen = [];
+  header.forEach((rawName, index) => {
+    let name = String(rawName ?? '').trim();
+    if (name.length === 0) name = `列${index + 1}`;
+    // 重名列：加序号（服务端的字段显示名不要求唯一，但列名是我们识别"同一列"的键）
+    if (headerSeen.includes(name)) {
+      let suffix = 2;
+      let candidate = `${name}_${suffix}`;
+      while (headerSeen.includes(candidate)) {
+        suffix += 1;
+        candidate = `${name}_${suffix}`;
+      }
+      name = candidate;
+    }
+    headerSeen.push(name);
+    columns.push({
+      name,
+      semanticKey: semanticKeyOf(name, index, taken),
+      columnType: ColumnType.Text,
+      reason: '',
+      maxScale: 0,
+      overridden: false,
+    });
+  });
+
+  // 行长不足的行补空（Excel 里尾列全空是常事），超长的截断并记数。
+  const rows = [];
+  let skippedEmptyRows = 0;
+  for (const row of grid) {
+    const padded = row.slice(0, columns.length);
+    while (padded.length < columns.length) padded.push('');
+    if (padded.every((cell) => isBlank(cell))) {
+      skippedEmptyRows += 1;
+      continue;
+    }
+    rows.push(padded);
+  }
+  if (rows.length === 0) throw CliError.usage(`${file} 里只有表头、没有数据行`);
+
+  // 逐列采样推断（最多看 500 行，够稳且不必为 10 万行文件重复解析）。
+  const sampleSize = Math.min(rows.length, 500);
+  columns.forEach((column, index) => {
+    const samples = rows.slice(0, sampleSize).map((row) => row[index]);
+    const inferred = inferColumnNamed(column.name, samples, noInfer);
+    const plain = inferColumn(samples);
+    let finalType;
+    let reason;
+    if (Object.prototype.hasOwnProperty.call(overrides, column.name)) {
+      finalType = overrides[column.name];
+      reason = '由 --type 指定';
+    } else if (noInfer) {
+      finalType = inferred.type;
+      reason = '由 --no-infer 指定（全部按文本导入）';
+    } else if (inferred.type !== plain.type) {
+      finalType = inferred.type;
+      reason = '列名像标识符（号/编号/流水/ID…）且取值全是数字 ⇒ 按文本，避免掉前导零';
+    } else {
+      finalType = inferred.type;
+      reason = typeReason(inferred.type);
+    }
+    column.overridden = Object.prototype.hasOwnProperty.call(overrides, column.name);
+    column.columnType = finalType;
+    column.reason = reason;
+    column.maxScale =
+      finalType === ColumnType.Currency
+        ? // 金额超过两位小数：默认 precision=18/scale=2 会拒收 → 抬 scale（最多 6）。
+          Math.min(Math.max(inferred.scale, 2), 6)
+        : Math.min(inferred.scale, 10);
+  });
+
+  // `--type` 里点名但文件里没有的列：当场报错，别让人以为生效了。
+  for (const name of Object.keys(overrides)) {
+    if (!columns.some((column) => column.name === name)) {
+      throw CliError.usage(`--type 里的列 ${JSON.stringify(name)} 不在文件的表头里`).withDetails({
+        available_columns: columns.map((column) => column.name),
+      });
+    }
+  }
+
+  return { sourceFormat, sheetName, columns, rows, skippedEmptyRows, file };
+}
+
+/** 解析 `--type 列名=类型`（键是显示名，值是列类型）。 */
+export function parseTypeOverrides(items) {
+  const out = {};
+  for (const item of items) {
+    const index = String(item).indexOf('=');
+    if (index < 0) {
+      throw CliError.usage(`--type 的写法是 \`列名=类型\`，收到 ${JSON.stringify(item)}`).withHint(
+        '例：--type 金额=currency',
+      );
+    }
+    const name = String(item).slice(0, index).trim();
+    if (name.length === 0) {
+      throw CliError.usage(`--type 里的列名不能为空（${JSON.stringify(item)}）`);
+    }
+    out[name] = parseColumnType(String(item).slice(index + 1));
+  }
+  return out;
+}
+
+/** 猜测分隔符（企业里导出的 CSV 有逗号、分号、制表符、竖线四种）。 */
+export function sniffDelimiter(firstLine) {
+  const candidates = [',', ';', '\t', '|'];
+  let best = ',';
+  let bestCount = 0;
+  for (const candidate of candidates) {
+    const count = String(firstLine ?? '').split(candidate).length - 1;
+    if (count > bestCount) {
+      best = candidate;
+      bestCount = count;
+    }
+  }
+  return best;
+}
+
+/** RFC4180 风格的 CSV 解析（引号内的分隔符/换行不算分隔）。 */
+export function parseCsvText(text, delimiter) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuotes = false;
+  let index = 0;
+  while (index < text.length) {
+    const ch = text[index];
+    if (inQuotes) {
+      if (ch === '"') {
+        if (text[index + 1] === '"') {
+          field += '"';
+          index += 2;
+          continue;
+        }
+        inQuotes = false;
+        index += 1;
+        continue;
+      }
+      field += ch;
+      index += 1;
+      continue;
+    }
+    if (ch === '"' && field.length === 0) {
+      inQuotes = true;
+      index += 1;
+      continue;
+    }
+    if (ch === delimiter) {
+      row.push(field);
+      field = '';
+      index += 1;
+      continue;
+    }
+    if (ch === '\r' || ch === '\n') {
+      if (ch === '\r' && text[index + 1] === '\n') index += 1;
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = '';
+      index += 1;
+      continue;
+    }
+    field += ch;
+    index += 1;
+  }
+  if (field.length > 0 || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows;
+}
+
+/** 读 CSV：**非 UTF-8 当场拒**（Excel 默认导出的 GBK 不许静默按 UTF-8 解）。 */
+export function parseCsv(file) {
+  let bytes;
+  try {
+    bytes = fs.readFileSync(file);
+  } catch (err) {
+    throw CliError.usage(`读不了 ${file}：${rustIoErrorText(err)}`);
+  }
+  let text;
+  try {
+    // `fatal: true`：遇到非法 UTF-8 序列直接抛。静默按 UTF-8 解会把中文变成乱码入库，
+    // 而"表里全是问号"是客户最难自己查出来的故障。
+    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    throw CliError.usage(`${file} 不是 UTF-8 编码（Excel 默认导出常是 GBK）`).withHint(
+      '在 Excel 里「另存为 → CSV UTF-8（逗号分隔）」，或直接传 .xlsx',
+    );
+  }
+  if (text.startsWith('\uFEFF')) text = text.slice(1);
+  const firstLine = text.split('\n')[0] ?? '';
+  return parseCsvText(text, sniffDelimiter(firstLine));
+}
+
+/**
+ * Excel 日期序列号 → `YYYY-MM-DD`。
+ *
+ * 自己算而不是依赖某个库：我们只需要"年月日"，
+ * 序列号 1 = 1900-01-01、0 = 1899-12-30 这条定义足够。
+ * Excel 把 1900 当闰年（历史 bug），所以序列号 60 = 1900-02-29（假日期），
+ * 我们跳过它：`>= 60` 时减 1（于是 61 = 1900-03-01）。
+ */
+export function excelSerialToDate(serial) {
+  if (!Number.isFinite(serial) || serial < 1.0 || serial > 2958465.0) return null;
+  const daysRaw = Math.trunc(serial);
+  const days = daysRaw >= 60 ? daysRaw - 1 : daysRaw;
+  const epoch = Date.UTC(1899, 11, 31); // epoch 是 1899-12-31
+  const date = new Date(epoch + days * 86400000);
+  if (Number.isNaN(date.getTime())) return null;
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(date.getUTCDate()).padStart(2, '0');
+  return `${String(year).padStart(4, '0')}-${month}-${day}`;
+}
+
+/** `1200.0` → `1200`；`1234.56` → `1234.56`（数字要**去掉浮点尾巴**）。 */
+export function formatFloat(number) {
+  if (!Number.isFinite(number)) return '';
+  if (Number.isInteger(number)) {
+    if (Math.abs(number) < 1e15) return String(number);
+    if (Math.abs(number) < 1e21) return BigInt(number).toString();
+  }
+  return String(number);
+}
+
+// ---------------------------------------------------------------------------
+// 取值 → API 值
+// ---------------------------------------------------------------------------
+/**
+ * 把一列的值按列类型转成 API 能收的 JSON 值。
+ *
+ * 数值一律回**字符串**（服务端 `_parse_decimal` 收字符串，
+ * 而 JSON 的 number 是 float64 —— 金额过一遍就会丢精度）。
+ */
+export function coerceValue(column, raw) {
+  if (isBlank(raw)) return null;
+  switch (column.columnType) {
+    case ColumnType.Boolean: {
+      const flag = asBool(raw);
+      return flag === null ? String(raw).trim() : flag;
+    }
+    case ColumnType.Date: {
+      const date = asDate(raw);
+      return date === null ? String(raw).trim() : date;
+    }
+    case ColumnType.Number:
+    case ColumnType.Currency: {
+      const number = normalizeNumber(raw);
+      return number === null ? String(raw).trim() : number.value;
+    }
+    default:
+      return String(raw);
+  }
+}
+
+/** 按批切分（每批 ≤ `MAX_BATCH`）。返回 `[[start, end], ...]`。 */
+export function batchIndices(total, batchSize) {
+  const size = Math.min(Math.max(Math.trunc(batchSize) || 1, 1), MAX_BATCH);
+  const out = [];
+  let start = 0;
+  while (start < total) {
+    const end = Math.min(start + size, total);
+    out.push([start, end]);
+    start = end;
+  }
+  return out;
+}
+
+/** 字段定义（`POST /tables/{id}/fields` 的请求体）。 */
+export function fieldPayload(column, sortOrder) {
+  const payload = {
+    semantic_key: column.semanticKey,
+    name: column.name,
+    type: column.columnType,
+    sort_order: sortOrder,
+  };
+  if (column.columnType === ColumnType.Currency) {
+    payload.property = {
+      precision: 18,
+      scale: Math.max(column.maxScale, 2),
+      currency: 'CNY',
+    };
+  } else if (column.columnType === ColumnType.Number) {
+    if (column.maxScale > 0) {
+      payload.property = { precision: 38, scale: Math.min(column.maxScale, 10) };
+    }
+  } else if (column.columnType === ColumnType.Text) {
+    // 长文本（备注、单据说明）容易顶到默认 4000。
+    payload.property = { max_length: 4000 };
+  }
+  return payload;
+}
+
+/**
+ * 文件指纹：**内容**决定（列名 + 类型 + 每一行）—— SHA-256 取前 16 位十六进制。
+ *
+ * 为什么不是"路径 + 首尾行"：`--append` 的幂等键由它算出来，而
+ * "每月把同一份导出文件更新后追加到同一张表"正是最常见的用法 ——
+ * 只哈希路径与首尾行时，中间若干行变了而指纹不变，服务端会把新数据
+ * 当重放**静默丢掉**（数据看起来"导进去了"，其实一条没写）。
+ *
+ * 内容决定指纹的代价：同一份内容重复追加会被当成重放（这正是幂等的本义）。
+ */
+export function fileFingerprint(parsed) {
+  const hash = createHash('sha256');
+  for (const column of parsed.columns) {
+    hash.update(Buffer.from(column.name, 'utf8'));
+    hash.update(Buffer.from([0x1f]));
+    hash.update(Buffer.from(column.columnType, 'utf8'));
+    hash.update(Buffer.from([0x1e]));
+  }
+  for (const row of parsed.rows) {
+    for (const cell of row) {
+      hash.update(Buffer.from(String(cell), 'utf8'));
+      hash.update(Buffer.from([0x1f]));
+    }
+    hash.update(Buffer.from([0x1e]));
+  }
+  return hash.digest('hex').slice(0, 16);
+}
+
+/** 一行记录的 `values`（空值不进 values —— 服务端把 null 当"删掉这个 cell"）。 */
+export function rowValues(columns, row) {
+  const values = {};
+  columns.forEach((item, index) => {
+    const raw = row[index] === undefined ? '' : row[index];
+    const value = coerceValue(item.column, raw);
+    if (value !== null) values[item.writeKey] = value;
+  });
+  return values;
+}