表格与 Word 的读取、生成和转换

文件任务决定工具边界复制锚点链接

表格读取、样式报表生成、CSV 流式导入、Word 生成和 Word 转 HTML，处理的是不同对象。表格单元格包含值、公式和显示格式；Word 包含段落、样式、表格和资源。转成普通 JSON 或 HTML 后，原文件的一部分格式、结构或关系可能不再存在。

归档材料采用的主要路线是 ExcelJS 生成 XLSX、SheetJS 读取多种表格、PapaParse 或 csv-parse 解析 CSV、docx 生成 Word、Mammoth 读取 DOCX 的语义结构。选型比较属于具体项目条件，不能把一个文件后缀视为所有相关操作的统一接口。

XLSX 的内容与显示分开处理复制锚点链接

ExcelJS 的 workbook 包含 worksheet，行和单元格保存值及样式。按稳定的列定义生成数据，能把业务字段、表头和显示格式集中维护。以下为小型生成片段，尚未包括下载响应或持久化任务。

import ExcelJS from 'exceljs';

export async function buildRows(
  rows: Array<{ code: string; amount: number }>,
) {
  const workbook = new ExcelJS.Workbook();
  const sheet = workbook.addWorksheet('记录', {
    views: [{ state: 'frozen', ySplit: 1 }],
  });
  sheet.columns = [
    { header: '编号', key: 'code', width: 18 },
    { header: '金额', key: 'amount', width: 16 },
  ];
  rows.forEach((row) => sheet.addRow(row));
  sheet.getColumn('amount').numFmt = '0.00';
  return workbook.xlsx.writeBuffer();
}

编号保存为字符串，保留前导零。数字格式改变显示，不改变实际金额精度；精确金额需要在业务数据中选择明确表示。公式值与缓存结果要分别处理，生成文件的库不自动执行与 Excel 相同的全部计算。

大结果集可以用 ExcelJS 的 streaming writer，逐行提交后释放行对象，最后提交 workbook。已提交的行不能任意回改，图片等能力也有流式限制。实际阈值取决于列数、字符串、样式和内存，不把固定“一万行”当成通用上限。ExcelJS README

导出任务应使用唯一临时路径或直接受控流，不能让并发任务共享 orders.xlsx 一类固定文件。完成、失败及取消均释放临时文件和句柄；客户端断开不自动停止仍在查询和生成的服务端任务。

读取与导入需要明确转换复制锚点链接

SheetJS 的 Community Edition 提供多格式读取路线。官方安装文档维护自己的发布来源；锁文件应固定实际包来源和版本，不能把旧 npm 版本当成当前官方分发。SheetJS Node 安装

解析结果进入业务库之前，需要完成文件大小及资源限制、表或列识别、逐行字段转换和校验。空白单元格、零、缺失列和公式结果是不同情况。日期序号、时区、科学记数、百分比和前导零都可能改变业务含义；保留原值及行列定位有助于报告错误。

CSV 需要处理引号、逗号、换行、编码与 BOM。直接 split(',') 无法解析带引号的字段。PapaParse 可用于浏览器文件解析和 Worker 路线，csv-parse 支持 Node 流；Worker 减少主线程计算，却不免除内存、错误和消息传递成本。

导入可以先预览和确认，再提交有效行；部分成功与整批事务具有不同业务含义。文件哈希、导入批次或业务唯一键需要对应重复处理策略。解析成功仅表示文件语法被读取，字段合法、数据一致和获准写入分别检查。

不可信单元格导出到 CSV 或电子表格时还应考虑公式解释。是否把公式前缀转成文本、保留原类型或拒绝，依据目标格式和数据用途制定规则，避免用户内容在打开文件时意外成为公式。

Word 生成与读取的语义差异复制锚点链接

docx 一类生成器从段落、run、表格、图片和样式组成 OOXML 文档。内容模型中的标题级别可以映射为 Word 标题样式；列表、合并单元格、图片尺寸、页眉页脚、分页和字体分别转换。生成 Word 文件不会自动提供 PDF 渲染或网页布局一致性。

富文本节点转换到 Word 时，应给每种已启用节点和 mark 定义映射。无法表达的交互、视频嵌入、批注及模型建议要说明输出策略；静默跳过会造成信息丢失。转换器和编辑 schema 应按同一功能集维护。

Mammoth 偏向把 DOCX 的语义结构转为 HTML，而非复制每个版式细节。它明确提醒转换输出没有自动清洗；不可信文件转出的链接及 HTML 需要在呈现前处理。Mammoth README

读取 DOCX 与把文件上传到另一个服务不同。上传接口接受 .docx 只能证明文件接收范围，不能证明浏览器本地拥有转换器，或证明所有图片、公式和批注已经导入。

下载、任务与检查复制锚点链接

正式生成可以在服务端进行，也可以在受控浏览器场景生成，选择取决于数据范围、资源与任务性质。原归档中的“所有导出必须服务端生成”是所选架构的工程约定，不能推广成库的能力限制。

文件响应保留正确 MIME、文件名及权限。长任务返回任务身份，状态、文件资源和错误分别管理；只有用户获准读取的数据才能导出，下载地址的有效期与公开范围要匹配。

检查生成文件可以回读单元格、文档结构和关键文本；版式、换页、字体及目标阅读器行为需要渲染观察。流式与非流式、含图片与无图片、空文件、损坏文件和超大输入分别形成有意义的验证条件。本轮没有执行文件生成或阅读器验证。