# TeamWorks 宛 共有文書の PDF 生成

TeamWorks へ送る共有文書は、**Markdown の原稿から reportlab で PDF を生成**しています。
このディレクトリにその生成スクリプトと自己点検スクリプトを置いています。

**PDF そのものはコミットしません**（`.gitignore` で `docs/handoff/pdf/*.pdf` を除外）。
**原稿とスクリプトがあれば同じものが再生成できる**ため、バイナリを持ちません。

> **2026-09-03**: 第1回のスクリプト・原稿は一時ディレクトリにしか存在せず、
> 消えると復元できない状態でした（引き継ぎ文書の「踏んだ地雷」参照）。
> 第2回の作成時にまとめてリポジトリへ移しています。

## 対応関係

| 回 | 原稿 | 生成 | 点検 | 出力ファイル名 |
|---|---|---|---|---|
| 第1回 | `docs/handoff/TeamWorks実DDL照合結果_第1回_20260903.md` | `make_ddl_review_pdf.py` | `check_ddl_review_pdf.py` | `D-Watch_実DDL照合結果_20260903.pdf` |
| 第2回 | `docs/handoff/TeamWorks確認事項_第2回_20260903.md` | `make_teamworks_qa2_pdf.py` | `check_teamworks_qa2_pdf.py` | `DWatch_確認事項_第2回_20260903.pdf` |
| 第3回 | `docs/handoff/TeamWorks確認事項_第3回_20260903.md` | `make_teamworks_qa3_pdf.py` | `check_teamworks_qa3_pdf.py` | `DWatch_確認事項_第3回_20260903.pdf` |
| 第4回 | `docs/handoff/TeamWorks確認事項_第4回_20260907.md` | `make_teamworks_qa4_pdf.py` | `check_teamworks_qa4_pdf.py` | `DWatch_確認事項_第4回_20260907.pdf` |
| 第5回 | `docs/handoff/TeamWorks確認事項_第5回_20260907.md` | `make_teamworks_qa5_pdf.py` | `check_teamworks_qa5_pdf.py` | `DWatch_確認事項_第5回_20260907.pdf` |
| 第13回 | `docs/handoff/TeamWorks確認事項_第13回_20261019_送付版.md` | `make_teamworks_qa13_pdf.py` | `check_teamworks_qa13_pdf.py` | `DWatch_確認事項_第13回_20261019.pdf` |

## 使い方

```bash
# 生成（既定の出力先はこのディレクトリ）
python docs/handoff/pdf/make_teamworks_qa2_pdf.py

# 自己点検（原稿の文言が全部入っているか / フォントが日本語フォントか）
python docs/handoff/pdf/check_teamworks_qa2_pdf.py

# 送付用に Downloads へ出す
DWATCH_PDF_OUT=C:/Users/daich/Downloads python docs/handoff/pdf/make_teamworks_qa2_pdf.py
```

点検スクリプトは PDF のパスを第1引数で受け取れます。終了コードは OK なら 0、NG なら 1。

必要なもの: `reportlab`（生成）/ `pypdf`（点検）。

## ★体裁の決まりごと（次回も必ず守ること）★

### フォント — 日本語フォントを使う

```python
pdfmetrics.registerFont(TTFont("JP",   "C:/Windows/Fonts/BIZ-UDGothicR.ttc", subfontIndex=0))
pdfmetrics.registerFont(TTFont("JP-B", "C:/Windows/Fonts/BIZ-UDGothicB.ttc", subfontIndex=0))
```

**中国語向けフォント（SimSun / Microsoft YaHei / Noto Sans SC 等）は使わないこと。
フォールバックにも混ぜないこと。** 漢字の字形が異なり、日本語文書として不自然になります
（`CLAUDE.md` §0-3）。点検スクリプトがこの混入を検査します。

BIZ UDGothic は等幅（半角は 0.5em 固定）なので、**SQL やコードの枠にも同じフォントを使います。**
コードブロック内の空白は ` ` に置換して桁を保ちます（`code()` が行います）。

### レイアウト

| 項目 | 値 |
|---|---|
| 用紙 | A4 縦 |
| 余白 | 左右上 18mm / 下 20mm |
| フッター | 左「D-Watch / DFA Robotics」・右ページ番号・上に 0.4pt の罫線（`on_page()`） |

### 配色（第1回から共通）

| 用途 | 色 |
|---|---|
| 本文 | `#1e293b` |
| 補足・表見出しの文字 | `#475569` |
| フッター・引用の罫線 | `#94a3b8` |
| 罫線 | `#cbd5e1` |
| 表の見出し行の背景 | `#f1f5f9` |
| コード枠の背景 | `#f8fafc` |

### 文字サイズ

表題 17pt / 節見出し 12.5pt / 小見出し 10.5pt / 本文 9.5pt / 補足 9pt /
表のセル 8.8pt / コード 8.2pt / 表の見出し 8.4pt。すべて `st()` で定義しています。

## 実績

| 回 | ページ数 | 検査項目 | 目視で直したもの |
|---|---|---|---|
| 第5回 | 6ページ / 181KB | 156項目（欠落0） | サマリ表の「区分」列を 44mm → 50mm（「確認」が2行に割れていた） |
| 第13回 | 4ページ / 115KB | 全項目 OK（設問6 / 表6・24行 / 本文73行・欠落0）。目視は未実施 | （目視前） |

**第5回で確認したこと**: 識別子の語中改行は0件。
`clean_watch_20260907.sql` / `control_error_histories` / `facility_error_summaries` /
`"10001:HandleUp"` / `Common Open Interface Error Codes` はいずれも無傷でした。

## 次回（第6回）を作るとき

1. 原稿の Markdown を `docs/handoff/` に作る（`TeamWorks..._第N回_YYYYMMDD.md`）
2. `make_teamworks_qa5_pdf.py` をコピーして、**表データと `build()` の本文だけ差し替える**。
   `st()` / `table()` / `code()` / `quote()` / `on_page()` / 配色 / フォントは**触らない**
   （第3回以降はすべて共通部をそのまま流用して作った。同じやり方でよい）
3. `check_teamworks_qa5_pdf.py` をコピーし、`must` を新しい原稿の文言に差し替える。
   ★**ページを跨ぐ語は `must` に入れないこと**★ — 抽出テキストにフッター
   （`D-Watch / DFA Robotics` とページ番号）が挟まり、空白を詰めても一致しない。
   第3回で `bigint auto_increment` が実際にこれで引っかかった（PDFは正常、検査側の都合）
4. 生成 → 点検 → **全ページを目視確認**する

**目視確認は省かないこと。** 点検スクリプトは文言の有無しか見ないため、
**表の列幅が足りずに識別子が語の途中で折り返る**（`control_error_histories.occurred_` / `at` のような）
崩れは検出できません。第2回でも実際にこれが5箇所発生し、列幅の調整で直しています。
`wordWrap="CJK"` は ASCII の語中でも改行するため、**識別子が入る列は幅を実測して決めること**
（BIZ UDGothic は半角 0.5em なので、`8.2pt × 文字数 ÷ 2 + 左右パディング 12pt` が必要幅）。

## 社内向け: ソースコード地図（`docs/code-map.md`）

TeamWorks 宛ではなく**社内で読むための PDF** です。作法（フォント・配色・余白・点検）は上と同じです。

| 原稿 | 生成 | 点検 | 出力ファイル名 |
|---|---|---|---|
| `docs/code-map.md` | `make_code_map_pdf.py` | `check_code_map_pdf.py` | `DWatch_ソースコード地図_20261005.pdf` |

```bash
python docs/handoff/pdf/make_code_map_pdf.py
python docs/handoff/pdf/check_code_map_pdf.py
```

★**原稿を直したら、スクリプトは触らずに再実行すればよい**★（原稿の .md を読んで組む。第10回以降と同じ作り）。

第11回のスクリプトから足した対応（詳細は各スクリプトの冒頭）:

- 見出しは `#` 表題 / `##` 章 / `###` 節 / `####` 小見出し。★改ページは番号の付いた章（「0.」〜「14.」「5-B.」「付録」）だけ★
- ★PDF のしおり★（`##` と `###`）と、★クリックできる章内リンク★（`[…](#…)`。宛先が無ければ例外で止まる）
- ファイルへのリンク `[…](パス)` は文字だけを出す。入れ子の箇条書きは3段まで。8列までの表（6列以上はセルの文字を小さく）
- Mermaid の図は★記法のままコードの枠に入れ★、「図（Mermaid 記法）」と注記する（図としては描かない）
- ★BIZ UDGothic に字形が無い記号（✅ ❌ ⚠ 📋 📅 など19種）だけを Segoe UI Symbol で描く★。
  置き換え・削除はしない。Segoe UI Symbol は漢字を持たないので中国語の字形は混ざらない（`CLAUDE.md` §0-3）。
  目に見えない U+FE0F だけは取り除く
- ★点検は「漢字・かなを描いているのが BIZ UDGothic だけであること」も検査する★（補助フォントを入れたため）

| 版 | ページ数 | 点検 | 目視で直したもの |
|---|---|---|---|
| 第4版（D-157） | 161ページ / 1,044KB | 全項目 OK（見出し232 / 本文2,218行 / コード37 / しおり160 / 章内リンク56） | 冒頭の短い節まで改ページして1〜2ページ目がほぼ白紙だった → 章だけ改ページに |

★原稿側の不備も PDF にすると見つかります★。第4版では、見出しが5列で本文が6列の表（GitHub では6列目が黙って消える）と、
★の閉じ忘れ5箇所を、生成時の警告から見つけて原稿を直しました。