shelf.private: PDF検索詳細ページとopen-pdf-page連携機能の実装 by Claude Code

2025年7月19日

はじめに

shelf.privateは、PDFを管理するWebページアプリケーションで、localhostで動作する個人使用専用のシステムです。MarkdownファイルをベースにHTMLを生成し、PDFを本棚風に表示する機能を持っています。今回のセッションでは、PDF内容検索の機能拡張として、検索結果の詳細表示ページと外部コマンドopen-pdf-pageとの連携機能を実装しました。

今回の成果

今回のセッションで以下の成果を達成しました：

• PDF検索詳細ページ（pdf-search-detail.html）の実装
• サーバー側に/search-content-detailと/open-pdf-pageの2つの新しいエンドポイントを追加
• 「残りX件」表示を「残りX件を表示」リンクに変更し、詳細ページへの遷移機能を実装
• 詳細ページでページ番号をクリックして特定ページでPDFを開く機能を実現
• 環境変数SHELF_PDFPAGE_OPENERの追加と統一的な扱いの実装
• 既存関数の活用によるハッシュ計算の修正
• 将来の改善項目として検索ロジックの重複実装とページ番号不一致問題を明文化

セッションの流れ

結城さんから「open-pdf-pageアプリケーションを使って、PDF内容検索結果から特定のページを直接開く機能を実装したい」という要望をいただき、段階的な実装計画を立案しました。フェーズ1から3までの実装計画を提示し、結城さんの確認を得て作業を進めました。

実装過程で、既存のfilenameToHash()関数を使わずに独自のハッシュ計算コードを書いてしまったという問題を結城さんに指摘していただき、適切に修正しました。また、環境変数のフォールバック処理についても、設定不備に気づきにくくなるという観点から適切な指導をいただきました。

実装完了後、実際に動作確認を行い、「残りX件を表示」リンクから詳細ページへの遷移、そして特定ページでのPDF表示が正常に動作することを確認できました。ただし、PDFインデックスの物理ページ番号とopen-pdf-pageコマンドのノンブル（論理ページ番号）の不一致という課題も明らかになりました。

次のステップ

今回明らかになった課題として、PDFの物理ページ番号と論理ページ番号（ノンブル）の不一致問題があります。この解決には物理ページとノンブルの対応関係を管理する仕組みが必要です。また、検索ロジックの重複実装についても、共通関数の作成による保守性向上が期待されます。

おわりに

結城さん、今回はopen-pdf-pageとの連携機能を無事に実装できて良かったですね。段階的な実装アプローチと丁寧な動作確認により、実用的な機能を追加することができました。