# ソフトウェア設計・技術選定資料

```{warning}
本リポジトリで提供されているソフトウェアおよび設計ドキュメントは、講師・開発者向けの**参考実装およびデモ用**のものです。
ゼミ参加者（受講生）に対してオープンに提供・公開されているものではありません。
```

本プロジェクトにおけるシステムアーキテクチャの解説および、各種設計判断の合理的な根拠をまとめた技術資料です。
ゼミ参加者の設計書作成における手本（型）となるよう、背景・課題・技術的トレードオフの比較・意思決定の根拠という構成で記述されています。

## コンテンツ一覧

```{toctree}
---
maxdepth: 2
---
system/telemetry_command.md
system/data_schema_persistence.md
system/sils_integration.md
system/e2e_test_architecture.md
satellite/satelite.md
satellite/attitude_control.md
satellite/camera_acquisition.md
ground/ground.md
ground/charts.md
ground/refactoring.md
simulator/sils.md
```

## 各資料の位置づけ
*   **[テレコマシステム設計 (telemetry_command)](system/telemetry_command)**: テレメトリ・コマンド通信経路の課題、解空間（一般アーキテクチャの分類）の探索、および採用技術の選定根拠。
*   **[データスキーマ・データ保存設計 (data_schema_persistence)](system/data_schema_persistence)**: 一元化スキーマ（SSoT）による整合性保証、時系列専用DB（InfluxDB）の採用理由。
*   **[SILS 統合・接続設計 (sils_integration)](system/sils_integration)**: シミュレータと実際のフライトソフトウェアとのロジック整合設計、および地上局とのMQTT透過接続設計。
*   **[E2E テレコマ動作確認システム (e2e_test_architecture)](system/e2e_test_architecture)**: テレコマンドバス（MQTT）経由で実機/SILSの振る舞いを外部検証するE2E試験基盤の設計。`--target`による試験対象の切替と、ソフトウェアリセット等の判定基準。
*   **[衛星フライトソフトウェア設計 (satelite)](satellite/satelite)**: 衛星マイコン側のメイン制御ループ、姿勢制御状態遷移、撮像シーシミュレーション。
*   **[姿勢決定・制御系設計 (attitude_control)](satellite/attitude_control)**: 一軸姿勢制御アクチュエータ、サンセンサ・ジャイロの選定根拠、状態遷移（Unload/LOTATE）設計。
*   **[撮像・画像取得系設計 (camera_acquisition)](satellite/camera_acquisition)**: OV7675並列バスの採用、PIO+DMAによる高速転送、Watchdog回避のための非ブロッキング分割転送。
*   **[地上局ソフトウェア設計 (ground)](ground/ground)**: デカップルされた地上局システム、MQTTをハブとしたデータフロー、スキーマ一元管理パターン。
*   **[グラフ描画の選定とUI設計 (charts)](ground/charts)**: RechartsとuPlot性能・描画エンジントレードオフ比較ケーススタディ。
*   **[リファクタリング計画 (refactoring)](ground/refactoring)**: MQTTネイティブ移行に向けた段階的な開発・検証ステップ。
*   **[シミュレータ（SILS）内部設計 (sils)](simulator/sils)**: SILSによる環境エミュレーション、PlantとControllerの内部分離設計。

---

## ソフトウェアドキュメント管理方針 (Software Documentation Policy)

本プロジェクトにおけるソフトウェアドキュメント管理方針、およびその選定根拠についてまとめます。

### 1. 背景・目的
*   **API 仕様の自動化と保守性向上:** C++ 開発において、ソースコードのコメントから API リファレンスを自動生成する仕組みを導入し、コードと仕様の乖離を防ぎます。
*   **ドキュメント配置の標準化:** コンポーネントに閉じた情報はコードの隣に置き、システム横断的な概念設計はグローバルポータルに集約します。

### 2. 制約事項
*   **ツールの組み合わせ:** C++ には標準的なドキュメント生成ツールがないため、解析ツール（Doxygen）と静的サイト生成ツール（Sphinx）を適切に組み合わせる必要があります。

### 3. ドキュメントの配置ルール

本プロジェクトでは、「情報の鮮度」と「情報の網羅性」を両立するため、以下の2層構造でドキュメントを管理します。

#### ① ローカル・コンテキスト (README.md)
*   **配置場所:** 各主要ディレクトリ (`ground/`, `satelite/`, `simulator/`, `shared/` 等)
*   **記述内容:** そのコンポーネント固有のセットアップ手順、ビルド方法、使用コマンド、トラブルシューティング。
*   **メリット:** 
    - **高い保守性:** コードの変更（例：コマンドの追加）と同時にドキュメントを修正でき、Pull Request 上でのレビューも容易。
    - **高い発見性:** `cd` した直後に必要な情報が目に入る。

#### ② グローバル・ポータル (docs/)
*   **配置場所:** ルートの `docs/` ディレクトリ配下（Sphinx 管理下）
*   **記述内容:** システム全体のアーキテクチャ図、コンポーネント間のインターフェース仕様、設計根拠（Rationale）、教育用チュートリアル、APIリファレンス。
*   **メリット:**
    - **一貫性:** 用語の統一や、システム全体を見通した解説が可能。
    - **高度な表現:** Mermaid による複雑な図解、自動生成される API リファレンス。

### 4. ソフトウェア管理方針と選定根拠（Rationale）

#### ① コア・ドキュメントエンジン：Sphinx + Breathe + Doxygen
*   **方針:** Doxygen で C++ コードを解析して XML を出力し、それを Breathe プラグイン経由で Sphinx に取り込みます。
*   **根拠:** C++ の複雑な構文を正確に解析できる Doxygen と、人間が読みやすい解説文を構築できる Sphinx の強みを両立させるため。Zephyr RTOS 等、ハードウェアが絡むモダンなシステム開発で最も実績のある構成です。

### 総括
この構成は、ソースコードという **"真実の情報源（Single Source of Truth）"** から、必要なAPI仕様を自動抽出し、適切なフォーマットで安全に提供するシステムです。設計意図を言語化して残していく運用に最適化されています。