wordtable2sqlite/HOWTO.md

HOWTO: Word 表格导入 SQLite 并导出字段化 CSV

这份说明面向实际使用：把报备表 .docx 导入 SQLite，然后把自动识别出的字段内容导出成 CSV，方便用 WPS/Excel 查看。

1. 准备文件

需要两个文件：

• wordtable2sqlite：macOS 可执行文件。
• 要导入的 .docx：例如重要服务事项报备表。

在 Windows 上使用时，对应可执行文件是：

• wordtable2sqlite-windows-amd64.exe

2. 导入单个 Word 文件

macOS 示例：

./bin/wordtable2sqlite -reset -db report.sqlite input.docx

Windows 示例：

.\wordtable2sqlite-windows-amd64.exe -reset -db report.sqlite input.docx

参数含义：

• -db report.sqlite：指定输出的 SQLite 数据库文件。
• -reset：导入前删除旧数据库，适合重新生成结果。
• input.docx：要导入的 Word 文件路径。

执行成功后会看到类似输出：

imported input.docx: 1 tables, 31 cells, 15 fields
database: report.sqlite

含义是：

• tables：识别到几张 Word 表格。
• cells：保存了多少个原始单元格。
• fields：自动抽取了多少个字段化内容。

3. 批量导入多个 Word 文件

把多个 .docx 导入到同一个数据库：

./bin/wordtable2sqlite -reset -db reports.sqlite *.docx

如果是后续追加导入，不想清空旧数据，就不要加 -reset：

./bin/wordtable2sqlite -db reports.sqlite another.docx

4. 数据库里有什么表

导入后会生成 4 张主要表：

• documents：每个导入的 Word 文件。
• tables：每个 Word 文件里的表格。
• cells：原始单元格内容，保留行号、列号、合并单元格信息。
• fields：字段化内容，最适合业务人员查看和检索。

一般看业务内容，优先看 fields。

5. 查看字段化内容

在 macOS/Linux 终端中：

sqlite3 report.sqlite

进入 SQLite 后执行：

.headers on
.mode line
SELECT key, value FROM fields ORDER BY id;

.mode line 适合看长文本。每条记录会显示成：

  key = 事件过程
value = ...

如果想看表格模式：

.headers on
.mode box
SELECT key, value FROM fields ORDER BY id;

6. 导出字段化内容 CSV

这是最常用的导出方式：

sqlite3 -header -csv report.sqlite "SELECT key, value FROM fields ORDER BY id;" > report-fields.csv

生成的 report-fields.csv 可以直接用 WPS/Excel 打开。

如果打开后中文乱码，使用 WPS/Excel 的“从文本/CSV 导入”，编码选择：

UTF-8

7. 导出原始单元格 CSV

如果要检查 Word 表格的原始行列结构，导出 cells：

sqlite3 -header -csv report.sqlite "SELECT table_index, row_index, cell_index, col_index, col_span, text FROM cells ORDER BY table_index, row_index, cell_index;" > report-cells.csv

字段含义：

• table_index：第几张表，从 0 开始。
• row_index：第几行，从 0 开始。
• cell_index：该行第几个单元格。
• col_index：逻辑列号。
• col_span：横向合并了几列。
• text：单元格文字。

8. 常用查询

查所有字段名：

SELECT key FROM fields ORDER BY id;

查某个字段：

SELECT value FROM fields WHERE key = '工单编号';

按文件查看字段：

SELECT d.filename, f.key, f.value
FROM fields f
JOIN documents d ON d.id = f.document_id
ORDER BY d.id, f.id;

查原始单元格：

SELECT row_index, cell_index, text
FROM cells
ORDER BY table_index, row_index, cell_index;

9. 推荐查看方式

给业务人员看：

1. 先导出 report-fields.csv。
2. 用 WPS/Excel 打开。
3. 每一行就是一个字段：key 是字段名，value 是字段内容。

给开发或调试看：

1. 打开 report.sqlite。
2. 查看 cells 判断 Word 原始表格结构。
3. 查看 fields 判断字段抽取是否符合预期。

10. 本次样例命令

本次样例数据库：

/Users/zhaoyilun/Documents/Codex/2026-06-24/wo-x/outputs/sample-baiyin.sqlite

导出字段化 CSV：

sqlite3 -header -csv /Users/zhaoyilun/Documents/Codex/2026-06-24/wo-x/outputs/sample-baiyin.sqlite "SELECT key, value FROM fields ORDER BY id;" > /Users/zhaoyilun/Documents/Codex/2026-06-24/wo-x/outputs/sample-baiyin-fields.csv

导出原始单元格 CSV：

sqlite3 -header -csv /Users/zhaoyilun/Documents/Codex/2026-06-24/wo-x/outputs/sample-baiyin.sqlite "SELECT table_index, row_index, cell_index, col_index, col_span, text FROM cells ORDER BY table_index, row_index, cell_index;" > /Users/zhaoyilun/Documents/Codex/2026-06-24/wo-x/outputs/sample-baiyin-cells.csv