Initial word table SQLite importer

HOWTO.md

@@ -0,0 +1,201 @@
+# HOWTO: Word 表格导入 SQLite 并导出字段化 CSV
+
+这份说明面向实际使用：把报备表 `.docx` 导入 SQLite，然后把自动识别出的字段内容导出成 CSV，方便用 WPS/Excel 查看。
+
+## 1. 准备文件
+
+需要两个文件：
+
+- `wordtable2sqlite`：macOS 可执行文件。
+- `要导入的 .docx`：例如重要服务事项报备表。
+
+在 Windows 上使用时，对应可执行文件是：
+
+- `wordtable2sqlite-windows-amd64.exe`
+
+## 2. 导入单个 Word 文件
+
+macOS 示例：
+
+```bash
+./bin/wordtable2sqlite -reset -db report.sqlite input.docx
+```
+
+Windows 示例：
+
+```powershell
+.\wordtable2sqlite-windows-amd64.exe -reset -db report.sqlite input.docx
+```
+
+参数含义：
+
+- `-db report.sqlite`：指定输出的 SQLite 数据库文件。
+- `-reset`：导入前删除旧数据库，适合重新生成结果。
+- `input.docx`：要导入的 Word 文件路径。
+
+执行成功后会看到类似输出：
+
+```text
+imported input.docx: 1 tables, 31 cells, 15 fields
+database: report.sqlite
+```
+
+含义是：
+
+- `tables`：识别到几张 Word 表格。
+- `cells`：保存了多少个原始单元格。
+- `fields`：自动抽取了多少个字段化内容。
+
+## 3. 批量导入多个 Word 文件
+
+把多个 `.docx` 导入到同一个数据库：
+
+```bash
+./bin/wordtable2sqlite -reset -db reports.sqlite *.docx
+```
+
+如果是后续追加导入，不想清空旧数据，就不要加 `-reset`：
+
+```bash
+./bin/wordtable2sqlite -db reports.sqlite another.docx
+```
+
+## 4. 数据库里有什么表
+
+导入后会生成 4 张主要表：
+
+- `documents`：每个导入的 Word 文件。
+- `tables`：每个 Word 文件里的表格。
+- `cells`：原始单元格内容，保留行号、列号、合并单元格信息。
+- `fields`：字段化内容，最适合业务人员查看和检索。
+
+一般看业务内容，优先看 `fields`。
+
+## 5. 查看字段化内容
+
+在 macOS/Linux 终端中：
+
+```bash
+sqlite3 report.sqlite
+```
+
+进入 SQLite 后执行：
+
+```sql
+.headers on
+.mode line
+SELECT key, value FROM fields ORDER BY id;
+```
+
+`.mode line` 适合看长文本。每条记录会显示成：
+
+```text
+  key = 事件过程
+value = ...
+```
+
+如果想看表格模式：
+
+```sql
+.headers on
+.mode box
+SELECT key, value FROM fields ORDER BY id;
+```
+
+## 6. 导出字段化内容 CSV
+
+这是最常用的导出方式：
+
+```bash
+sqlite3 -header -csv report.sqlite "SELECT key, value FROM fields ORDER BY id;" > report-fields.csv
+```
+
+生成的 `report-fields.csv` 可以直接用 WPS/Excel 打开。
+
+如果打开后中文乱码，使用 WPS/Excel 的“从文本/CSV 导入”，编码选择：
+
+```text
+UTF-8
+```
+
+## 7. 导出原始单元格 CSV
+
+如果要检查 Word 表格的原始行列结构，导出 `cells`：
+
+```bash
+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. 常用查询
+
+查所有字段名：
+
+```sql
+SELECT key FROM fields ORDER BY id;
+```
+
+查某个字段：
+
+```sql
+SELECT value FROM fields WHERE key = '工单编号';
+```
+
+按文件查看字段：
+
+```sql
+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;
+```
+
+查原始单元格：
+
+```sql
+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. 本次样例命令
+
+本次样例数据库：
+
+```bash
+/Users/zhaoyilun/Documents/Codex/2026-06-24/wo-x/outputs/sample-baiyin.sqlite
+```
+
+导出字段化 CSV：
+
+```bash
+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：
+
+```bash
+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
+```