docview/docs/design/00-guide.md

# DocView アプリケーション設計書

設計基準版 1.0 / 2026年9月19日

## 目的と設計の要点

DocView（仮称）は、PDFを中心にHTML・HTML ZIP・EPUBを読むための、Vim風操作を備えたデスクトップ文書リーダーである。本文を主役にした静かな画面と、キーボードだけで完結する移動を提供する。

表示基盤にはQt Quick、PDF描画には独立プロセス内のPDFium、HTML・EPUB表示にはQt WebEngineを採用する設計とする。PDFは紙面を保持し、HTML・EPUBはそれぞれの構造を使って移動する。表示形式の違いを無理に「ページ番号」だけへ統一しない。

本版は実装の入力となる設計基準である。動作・性能・互換性の実測結果は含まない。性能数値は受入目標、技術選定は検証ゲート付きの設計判断として示す。プログラム、ビルド環境、試作品は成果物に含まれない。

## 文書構成

| 文書 | 主な内容 | 主な読者 |
|---|---|---|
| [01 要件・スコープ](01-requirements.md) | 要件ID、優先順位、対応範囲、受入追跡 | 企画・開発・QA |
| [02 全体アーキテクチャ](02-architecture.md) | 構成、責務、処理フロー、拡張点 | 開発 |
| [03 形式別設計](03-formats.md) | PDF、HTML、ZIP、EPUBの取込みと表示 | 開発・QA |
| [04 画面・操作設計](04-ui-navigation.md) | 画面、モード、キー、フォーカス、見出し | 企画・開発・QA |
| [05 データ・インターフェース設計](05-data-contracts.md) | モデル、位置表現、コマンド、IPC、状態遷移 | 開発 |
| [06 設定・保存設計](06-config-storage.md) | TOML、キーバインド、OS別配置、永続化 | 開発・運用 |
| [07 セキュリティ・障害設計](07-security-errors.md) | 信頼境界、入力制限、障害復旧 | 開発・QA |
| [08 性能・試験設計](08-performance-tests.md) | 目標、測定条件、互換性、受入ケース | 開発・QA |
| [09 技術判断・開発計画](09-decisions-roadmap.md) | 選定理由、代替案、検証ゲート、残課題 | 技術責任者 |
| [10 参考資料](10-references.md) | 公式仕様・API・配布資料 | 開発 |

初読は01→02→04→09の順、実装着手時は03・05・06・07・08を併読する。

## 設計の確度

| 区分 | 意味 |
|---|---|
| 確定要件 | 原要件、またはデスクトップGUIであるという補足合意 |
| 設計判断 | この版で採用する構成・振る舞い。変更は関連文書と試験を同時に更新する |
| 提案値 | 原要件に数値指定がないため設定した測定可能な初期値 |
| 検証ゲート | 実装開始後に実機・代表文書で確認し、未達なら選定を見直す条件 |

PDFの再現性、構造タグからの見出し移動、隔離環境の動作、縦書きEPUB、Qt依存物を含めた配布を最初に検証する。これらが未確認の段階で、全PDFへの完全互換や全Linux環境への対応を宣言しない。

## 用語

- 文書: 開いたPDF、単独HTML、HTML ZIP、またはEPUB。HTMLの内部リンク先も同じ許可ルート内なら同一文書セッションに属する。
- 目次: PDFアウトライン、EPUB nav/NCX、HTML見出しから構成したナビゲーションツリー。
- 見出し: 文書構造に記録された節の起点。PDFアウトラインとPDF構造タグは出典を区別する。
- ページ一覧: PDFの物理ページ、固定レイアウトEPUBのspine項目。流し込み文書では代わりに章一覧を使う。
- 論理位置: 再描画やウィンドウサイズ変更後も可能な限り再発見できる読書位置。
- 許可ルート: 文書セッションが参照できるファイル集合の境界。端末全体のファイル権限とは異なる。

## 文書管理

要件をR01〜R15、設計判断をADR、受入ケースをT、技術検証をGで識別する。要求の変更時は01の対応表から影響をたどる。補助的な機能は原要件と区別し、リリース範囲に入れる判断を記録する。外部資料は確認時点の情報であり、採用時にバージョンとライセンスを固定する。