# 技术验证 S1–S4（一次性代码）

架构文档 `docs/architecture/architecture.md` §10 的技术验证。结论见 `docs/architecture/tech-validation.md`。

- 这里的代码只为回答验证问题，**不进生产**；正式实现按架构文档重写。
- 样本是不可信输入：脚本都用 `python -I` 运行，转换在 Gotenberg 容器里做。
- 所有由样本派生的产物（PDF、文本、图片、JSON）都在各子目录的 `out/` 里，**不进 git**（样本不转载，见 `samples/tenders/README.md`）。
- S4 的模型配置放在 `s4-llm/.env`（`LLM_BASE_URL` / `LLM_API_KEY` / `LLM_MODEL`），不进 git。

## 环境

```bash
cd spikes
uv venv .venv && uv pip install -p .venv/bin/python pypdfium2 pdfplumber python-docx olefile httpx pillow fonttools
docker pull gotenberg/gotenberg:8          # arm64 / amd64 都有
```

## 复现步骤

```bash
# S1：真值、预处理、四种字体配置
.venv/bin/python -I s1-convert/truth.py
docker run -d --name bd-gotenberg-a -p 3101:3000 gotenberg/gotenberg:8
.venv/bin/python -I s1-convert/convert.py A-default http://localhost:3101          # 原样转换
# 旧版 DOC 先在容器里转 DOCX（soffice --convert-to docx），再修正字体字符集：
.venv/bin/python -I s1-convert/fix_charset.py in.docx out/fixed-docx/SXX.docx
# 克隆字体（行高 1.0em）+ 字体替换规则
docker cp bd-gotenberg-a:/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc s1-convert/out/fonts-src/   # 另外三个同理
.venv/bin/python -I s1-convert/make_fonts.py s1-convert/out/fonts-src s1-convert/out/fonts-C10 1.0
docker run -d --name bd-gotenberg-c10 -p 3103:3000 \
  -v "$PWD/s1-convert/out/fonts-C10:/usr/local/share/fonts/bd:ro" \
  -v "$PWD/s1-convert/fonts-C.conf:/etc/fonts/conf.d/99-bd.conf:ro" gotenberg/gotenberg:8
.venv/bin/python -I s1-convert/convert.py C10-fixed http://localhost:3103 s1-convert/out/fixed-docx
.venv/bin/python -I s1-convert/toc_truth.py

# S2：格式识别（银标准来自 DOCX）+ Docling 对比
.venv/bin/python -I s2-format/format_check.py s1-convert/out/C10-fixed s1-convert/out/fixed-docx S06 S08 S09 S03
docker run -d --name bd-docling -p 5101:5001 ghcr.io/docling-project/docling-serve-cpu:latest
.venv/bin/python -I s2-format/docling_check.py http://localhost:5101 s1-convert/out/fixed-docx/S06.docx s1-convert/out/C10-fixed/S06.pdf s2-format/out/S06-docx-iu.json

# S3：切句、quads、校验、高亮图
.venv/bin/python -I s3-citation/sentences.py s1-convert/out/C10-fixed s1-convert/out/fixed-docx 50 8
.venv/bin/python -I s3-citation/sentences.py s1-convert/out/C10-fixed s1-convert/out/fixed-docx 300 0 7   # 扩大样本
.venv/bin/python -I s3-citation/classify.py s1-convert/out/C10-fixed validation.json

# S4：准备输入 → 假模型跑通 → 小样本 → 全量
.venv/bin/python -I s4-llm/prep.py s1-convert/out/C10-fixed S01 S02 S03 S04 S05 S06 S07 S08 S09 S10
.venv/bin/python -I s4-llm/run.py --model fake --docs S06 S08 --tag fake --basis-gate
.venv/bin/python -I s4-llm/run.py --model env --docs S08 S03 --max-chunks 2 --tag smoke
.venv/bin/python -I s4-llm/run.py --model env --docs S01 S02 S03 S04 S05 S06 S07 S08 S09 S10 --prompt v2 --basis-gate --tag full-v2
.venv/bin/python -I s4-llm/aggregate.py full-v2
```

## 目录

| 目录 | 内容 |
|---|---|
| `common.py` | 样本定位、按文件头识别格式 |
| `s1-convert/` | 页数真值、Gotenberg 转换、字体字符集修正、克隆字体、目录页码比对 |
| `s2-format/` | 斜体 / 下划线 / 加粗识别与 DOCX 交叉校验；Docling 对比 |
| `s3-citation/` | 切句、句子编号、quads、几何回读、文本保真、高亮渲染 |
| `s4-llm/` | 输入准备与银标准、提示词（`prompts/`）、调用与三道校验、评估、汇总 |