ファイルが開かない:まず情報取得、次に修復、そして推測をやめる
PDF が開かないときは、Get Info でプリフライトし、Repair で構造を再建する。それは xref の復旧であり、デスクトップの Recovery Toolbox のクローンではない。

開かない PDF は通常、構造の問題だ(壊れた相互参照表、途中で切れたダウンロード、不正なオブジェクト)。手で描き直せる欠けたページ画像ではない。ファイルがパースできるようになるまで、OCR や圧縮や変換で当て推量しても時間の無駄だ。
まず情報取得
情報取得(POST /api/v1/security/get-info-on-pdf)は JSON のレポートを返す。FileSize、PageCount、Encrypted、存在すれば Info 辞書のフィールド(title、author、subject、creator、producer)、PDF の Version、簡単な Pages のリスト、そして文書ルートが見つかったかどうかだ。プリフライトとして使う。
- Encrypted: true は、大半の編集の前に正当な パスワードの解除 が必要だという意味だ。修復だけではパスワードを割らない。
- PageCount/FileSize は妥当に見えるのにデスクトップのビューアが失敗するなら、次に構造の 修復 を試す。
- 呼び出し自体がバイトを読み込めないなら、きれいな Info を通せないほど壊れている可能性がある。それでも複製に対して修復を試す。
情報取得は PDF を書き換えない。パーサに見えるものを教えるだけであり、すべての失敗を「OCR が要る」「圧縮が要る」と扱うのをやめさせてくれる。
次に修復(qpdf による構造の再建)
PDF の修復(POST /api/v1/misc/repair)は qpdf でファイルを書き換え、十分なオブジェクトが残っていればビューアが再び開けるようにする。うまくいけば、意図したページ内容は保たれる。仕事はファイルの地図(xref やオブジェクトストリーム)であって、削除された下書きをフォレンジックに復元することではない。
修復は次ではない。
- OCR/スキャンの整形(ファイルは開くがテキストが画像にしかなっていない):OCR を使う。ここでは Markdown テキストを返し、検索可能な PDF 層ではない
- パスワードの除去:パスワードの解除 を使う
- フォントの修復や「再び編集可能にする」こと
- Windows 製品「Recovery Toolbox for PDF」のクローン
ブランドと経路の区別(オンラインの構造修復と、デスクトップの「recovery toolbox」検索)は オンライン PDF 修復と Recovery Toolbox 検索 にある。
推測をやめるための判断手順
- ビューアがファイルを開けない:情報取得、それから 修復。
- 開くがスキャン上で選択・検索ができない:Markdown テキスト向けに OCR。サイズが残った問題なら、任意で複製を 圧縮(スキャン束:OCR してから圧縮)。
- 開くが表のエクスポートが 204:列が検出されていない。空の表エクスポート(204) を参照。
- スクリプトやエージェントから同じ修復:開発者向け 経由で
POST /api/v1/misc/repair。クライアントがアップロードを再試行するならIdempotency-Keyを送る(Idempotency-Key)。
「修復済み」でも直らないもの
修復が成功したことは、ビューアがファイルを再び開けるという意味だ。次を意味しない。
- すべてのページ画像が無から再建された(欠けたオブジェクトは欠けたまま)
- スキャン上でテキストが選択可能になった(ここでは OCR → Markdown)
- 暗号化が消えた(既知のパスワードで解除する)
- 表がエクスポートされるようになった(列状のテキストは依然必要で、204 は未検出を意味する)
修復後の情報取得が妥当なページ数を示すのにページが空白なら、構造は復旧しても、そのページの内容は元のバイトで空か途中で切れている可能性がある。
壊れた原本を残す
修復した派生物の隣に、壊れた原本を残す。修復が十分な構造を復旧できなければ、正直な結果は「バイトは失われた」であり、カタログの別のツールに当たることではない。まだパースできないファイルを圧縮や変換しても、欠けたオブジェクトは発明されない。
ツールを「recovery toolbox」ブランドの検索から見つけたなら、経路の意図(オンラインの構造修復と、デスクトップの「recovery toolbox」ブランド検索)の対比は オンライン PDF 修復と Recovery Toolbox 検索 にある。カタログツールのブラウザ経路にアカウントは不要だ。