# データスキーマ・データ保存設計根拠 (Data Schema & Persistence Rationale)

> [!NOTE]
> **ドキュメントのスコープ**
> 本資料は、衛星と地上局間で通信されるテレメトリ（状態データ）およびコマンド（制御指令）の「フォーマット定義（スキーマ管理方式）」、および地上で高頻度データを記録・集約する「データ保存（データベース）の技術選定」における意思決定の根拠を記述したものです。回路設計やフライトマイコン側のローカルフラッシュ保存は対象外とします。

---

## 1. 一般論・基本原理の提示 (解空間の起源)

### ① スキーマ駆動開発と Single Source of Truth (SSoT)
分散システム（マイコン C++、バックエンド Python、フロントエンド TypeScript）開発において、インターフェース不整合による通信バグ（データのパースエラー、キー名のズレなど）は最も頻発する最悪ケース（障害）の一つです。これに対し、ソフトウェア工学ではデータ定義を一箇所で管理する **Single Source of Truth (SSoT: 真実の情報源)** の原理を適用します。

### ② 時系列データの処理特性
衛星運用データは本質的に「タイムスタンプが付随した不変の数値列（時系列データ）」です。一般的な業務アプリケーションで用いられる更新（Update/Delete）主体のトランザクションモデルとは異なり、高頻度な追加（Append-Only）および時間範囲での大量抽出（集約クエリ）がシステム負荷のボトルネックとなります。

---

## 2. 候補の列挙とトレードオフ分析

### 【スキーマ整合性管理】候補の比較
*   **候補A（個別定義方式）**: 衛星側の文字列出力、Python側の文字列スライス、React側の変数定義を手動でそれぞれハードコードする。
*   **候補B（SSoT スキーマ駆動方式）**: 単一の `telemetry_schema.json` をマスターとし、プログラムが動的ロードまたはコード自動生成により定義を同期する。

| 評価項目 | 候補A (個別ハードコーディング) | 候補B (SSoT スキーマ駆動) [採用] |
| :--- | :--- | :--- |
| **開発スピード（初期）** | **高** (スキーマ記述のオーバーヘッドがない) | 低 (共通スキーマファイルの設計が必要) |
| **変更時のバグ発生率** | **極めて高** (1箇所の更新忘れで表示データが化ける) | **極めて低** (定義変更が全レイヤーに自動反映) |
| **インターフェース整合性**| 低 (人間関係と手動更新に依存) | **高 (スキーマファイルによる強制担保)** |
| **学生学習用モデルとしての価値**| 低 (その場しのぎの開発スタイル) | **高 (実業界のスキーマ駆動開発の「型」を習得)** |

---

### 【データ保存 DB】候補の比較
*   **候補A（カスタム CSV 方式）**: 受信データをそのままコンマ区切りのテキストファイルとして追記保存する。
*   **候補B（汎用リレーショナル DB 方式）**: SQLite や PostgreSQL などのテーブル型 RDB にインサートする。
*   **候補C（時系列専用 DB 方式）**: InfluxDB などの時系列データベース（TSDB）に格納する。

| 比較項目 | 候補A (CSVファイル) | 候補B (RDB) | 候補C (時系列DB) [採用] |
| :--- | :--- | :--- | :--- |
| **書き込みスループット**| 中 (ロック競合なし、I/Oのみ) | 低 (B-Tree インデックス更新のオーバーヘッド) | **極めて高 (LSM-Treeベースの追記最適化)** |
| **時間範囲クエリの応答速度**| **極めて低** (全ファイル読み込み・パース) | 中 (データ増大に伴うインデックス肥大化) | **極めて高 (時間インデックスおよびデータ圧縮)** |
| **データロギングの堅牢性**| **低** (書き込み中クラッシュでファイル破損) | 高 (トランザクション整合性あり) | **高 (WALおよび時系列パーティショニング)** |
| **リアルタイム描画集約** | 不可 (カスタム計算ロジックが必要) | 低 (SQLでの日付丸め処理が低速) | **高 (秒単位の自動集約クエリ機能を標準装備)** |

---

## 3. 意思決定と選定根拠 (Justifications)

### ① SSoT によるインターフェース不整合バグの「防御的回避」
*   **根拠**: 合宿等の限られた時間内で、センサ追加に伴う「データ表示が隣のグラフにずれる」といった不名誉な通信バグに時間を奪われるのを防ぐため、SSoT スキーマ駆動（候補B）を採用しました。開発フローを「まずスキーマを変更する」という手順に統一することで、バグを発生プロセスそのものから排除します。

### ② 高頻度描画を支える時系列クエリの超高速化
*   **根拠**: 衛星姿勢制御データ（10Hz〜100Hz）を長時間記録し、フロントエンドに遅延なく描画するためには、過去データの「集約クエリ（Downsampling）」が不可欠です。RDBでは1万点を超えるとUIスレッドをブロックするほどクエリが遅延しますが、InfluxDB（候補C）を用いることで、ミリ秒単位で「10秒平均」などに集約したデータをロードでき、検証性を高めるための「スムーズなグラフ再生」が可能になります。

---

## 4. 合理的なブラックボックス化 (Rational Black-Boxing)

### ① データベースエンジン内部構造のブラックボックス化
*   時系列データの「時間差分圧縮アルゴリズム（Double-delta encoding）」や「ディスクパーティショニングのフラッシュロジック」について、本プロジェクトでは内部を深追いせず、InfluxDBを完全なブラックボックスとして信頼し活用します。
*   **割り切りの根拠**: これらの低レイヤーなデータ構造自作に学習コストを費やすのは非合理的であり、それよりも「得られた姿勢データの解析」や「制御状態遷移アルゴリズムの最適化」という模擬衛星のコアミッション開発に学生が開発資源を集中できるようにするための合理的割り切りです。

### ② スキーマパーサーのライブラリ依存
*   Python での JSON 読み込みおよび動的フィールド検証は、標準ライブラリの `json` モジュールおよび `shared/telemetry_def.py` の静的なスキーマパース処理に任せ、パーサーのパフォーマンスチューニングは行いません。