# アーキテクチャ

このドキュメントでは、`haniwers` プロジェクトのアーキテクチャと設計の決定について説明します。

## デュアルバージョンシステム

`haniwers` は2つの並行実装を維持しています：

### v0: プロトタイプ版（will be deprecated）

**場所**: `src/haniwers/v0/`

**特徴**:

- プロダクション対応の安定版CLI
- 基本的な機能を提供
- シンプルで実証済みのアーキテクチャ

**主要コンポーネント**:

- `cli.py`: Typer ベースのメインCLIインターフェース
- `config.py`: 設定管理
- `daq.py`: データ取得ロジック
- `threshold.py`: 閾値スキャンとフィッティング
- `preprocess.py`: 生データ処理
- `postprocess.py`: データ解析ユーティリティ

### v1: 次世代版（in development）

**場所**: `src/haniwers/v1/`

**特徴**:

- モダンでモジュラーなアーキテクチャ
- より優れたテスト容易性
- 関心の分離が改善

**主要コンポーネント**:

- `cli/`: モジュラーなCLI構造
  - `main.py`: エントリーポイントとグローバルオプション
  - `config.py`: 設定管理コマンド
  - `daq.py`: データ取得コマンド
  - `scan.py`: 閾値スキャンコマンド
- `config/`: Pydantic モデルによる設定管理
- `daq/`: デバイス抽象化によるデータ取得
- `log/`: Loguru による構造化ロギング

### バージョンの選択

- **v0 (`haniwers`)**: デフォルトのメインCLI
- **v0 明示的 (`haniwers-v0`)**: 明示的なv0 CLI
- **v1 (`haniwers-v1`)**: 次世代v1 CLI
- **v1 エイリアス (`haniwers-ng`)**: 次世代版のエイリアス

## 技術スタック

### 言語とランタイム

- **Python**: 3.12+
- **パッケージ管理**: Poetry 2.0+
- **仮想環境**: `poetry run <command>` または `poetry env activate`
  - 注: `poetry shell` は非推奨

### コア依存関係

- **CLI**: Typer - コマンドラインインターフェース
- **シリアル通信**: pyserial - OSECHI検出器との通信
- **設定**: TOML - 設定ファイル形式
- **データ処理**: Pandas/Polars - データフレーム操作
- **ロギング**: Loguru (v1) - 構造化ロギング
- **バリデーション**: Pydantic (v1) - 設定モデルの検証

### 開発ツール

- **フォーマッター**: Ruff
- **リンター**: Ruff
- **テスト**: pytest
- **カバレッジ**: pytest-cov
- **コミット**: Commitizen
- **Pre-commit**: pre-commit
- **ドキュメント**: Sphinx, MyST, autodoc2

## v0 アーキテクチャ詳細

### モジュール構成

#### `haniwers/v0/cli.py`

**責務**: メインのCLIエントリーポイント

- Typerベースのコマンド定義
- サブコマンド: `daq`, `scan`, `fit`, `vth`, `ports`, `run2csv`
- ログ設定とオプション解析
- 統一されたエラー処理

#### `haniwers/v0/config.py`

**責務**: 設定管理

- `Config`, `RunData`, `UserSettings` クラス
- TOML設定ファイルの読み込み
  - `daq.toml`: データ取得設定
  - `scan.toml`: 閾値スキャン設定
- パス管理と環境固有設定

#### `haniwers/v0/daq.py`

**責務**: データ取得（DAQ）

- シリアル通信（pyserial）による測定器制御
- `RealEvent` クラスによるイベントデータ構造
- ファイル保存とタイムスタンプ管理

#### `haniwers/v0/threshold.py`

**責務**: 閾値制御

- `scan_thresholds_in_parallel`: 並列閾値測定
- `Count` データクラス: 測定結果の構造化
- フィット処理とCSV出力

#### `haniwers/v0/dataset.py`

**責務**: データ処理

- `Run` クラス: 測定データへのアクセス
- パス管理とファイル操作
- データフレーム変換

#### `haniwers/v0/preprocess.py` & `haniwers/v0/postprocess.py`

**責務**: データ処理パイプライン

- 生データの前処理とリサンプリング
- 可視化とプロット機能
- CSV形式への変換

### デザインパターン

**責務の分離**:
- CLI: コマンド定義とオプション解析
- DAQ: ハードウェア制御とデータ取得
- Config: TOML設定の管理
- Data Processing: 前処理・後処理・可視化

**設定による柔軟性**:
- 外部設定ファイル（TOML）
- 実験ラン管理（runs.csv）
- 環境変数サポート

**データフロー**:
```
生データ取得 → 前処理 → CSV保存 → 可視化・解析
```

## v1 アーキテクチャ詳細

### モジュール構成

#### `haniwers/v1/cli/`

**モジュラーなCLI構造**:
- `main.py`: エントリーポイントとグローバルオプション処理
- `config.py`: 設定管理コマンド（show, init）
- `daq.py`: データ取得コマンド
- `scan.py`: 閾値スキャンコマンド

**改善点**:
- コマンドごとにファイルを分離（保守性向上）
- テスト容易性の大幅な改善（モック戦略）
- 新規コマンド追加が容易（main.pyは2行変更のみ）
- 100%後方互換性を維持

**詳細**: [CLI開発ガイド](./cli-development.md)を参照

#### `haniwers/v1/config/`

**モジュラーな設定管理**:
- `model.py`: Pydantic モデルによる設定の定義と検証
- `loader.py`: 設定ファイルの読み込みロジック
- `generator.py`: 設定ファイルのテンプレート生成

**改善点**:
- 型安全な設定
- 自動バリデーション
- より良いエラーメッセージ

#### `haniwers/v1/daq/`

**デバイス抽象化**:
- `device.py`: デバイス抽象化層
- `mocker.py`: テスト用モックデバイス
- `sampler.py`: サンプリングロジック
- `model.py`: データモデル定義

**改善点**:
- テスト容易性の向上（モック機能）
- より明確な抽象化
- デバイスの交換が容易

#### `haniwers/v1/log/`

**構造化ロギング**:
- `logger.py`: Loguru ベースのロガー設定

**改善点**:
- JSON形式の構造化ログ
- より良いデバッグ情報
- ログレベルの柔軟な制御

### デザインパターン

**モジュラリティ**:
- 小さく、焦点を絞ったモジュール
- 明確なモジュール境界
- 再利用可能なコンポーネント

**テスト容易性**:
- 依存性注入
- モック可能なインターフェース
- 単体テストフレンドリーな設計

## データフロー

### 測定ワークフロー

```
1. 閾値スキャン (scan)
   ↓
2. 閾値フィッティング (fit)
   ↓
3. 閾値設定 (vth)
   ↓
4. データ取得 (daq)
   ↓
5. 生データ変換 (raw2tmp)
   ↓
6. CSV変換 (run2csv)
```

### ファイル管理

**タイムスタンプベースの命名**:
- 生データ: `YYYYMMDD_HHMMSS_raw.dat`
- 処理済み: `YYYYMMDD_HHMMSS_run.csv`

**ディレクトリ構造**:
```
data/
├── YYYYMMDD_HHMMSS_run.csv
├── runs.csv
sandbox/
├── YYYYMMDD_HHMMSS_raw.dat
├── YYYYMMDD_HHMMSS_tmp.csv
```

## 設計原則

### 1. CLI第一

- すべての機能はCLIから利用可能
- スクリプト化とオートメーションが容易
- 対話的とバッチ実行の両方をサポート

### 2. 設定ファイルによる制御

- ハードコードされた値を避ける
- 環境固有の設定を外部化
- バージョン管理可能な設定

### 3. モジュール性と再利用性

- 小さく、焦点を絞った関数とクラス
- 明確な責務の分離
- 再利用可能なコンポーネント

### 4. データの完全性

- タイムスタンプによる追跡可能性
- 生データの保存
- 再現可能な処理パイプライン

### 5. 段階的な複雑化

- シンプルなv0から開始
- 段階的にv1で機能を追加
- 両バージョンの互換性を維持

## 依存関係管理

### Poetry を使用する理由

- **決定論的なビルド**: `poetry.lock` による再現可能なインストール
- **依存関係の分離**: 開発、ドキュメント、テスト用の分離された依存関係
- **パッケージ公開**: PyPI への公開が簡単

### 依存関係グループ

```toml
[tool.poetry.dependencies]
python = "^3.12"
typer = "^0.9"
# ... コア依存関係

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
ruff = "^0.6"
# ... 開発用依存関係

[tool.poetry.group.docs.dependencies]
sphinx = "^8.0"
# ... ドキュメント用依存関係
```

## テスト戦略

### テストの種類

- **Unit Tests**: 個別コンポーネントのテスト（`tests/{version}/unit/`）
- **Integration Tests**: マルチモジュール相互作用（`tests/{version}/integrations/`）
- **Contract Tests**: APIインターフェース
- **Manual Validation**: quickstart.md のシナリオ経由

### カバレッジ目標

- **目標**: 80%以上のカバレッジ
- **対象**: プロダクションコード（v0, v1モジュール）

詳細は[テストガイドライン](./testing-guidelines.md)を参照してください。

## ドキュメント構造

### Sphinx + MyST

- **フォーマット**: Markdown（MyST）
- **ビルダー**: Sphinx
- **テーマ**: sphinx_book_theme
- **API ドキュメント**: autodoc2

### ドキュメントの種類

- **ユーザー向け** (`docs/users/`): データ取得ワークフロー
- **協力者向け** (`docs/collaborators/`): データ解析ワークフロー
- **開発者向け** (`docs/developers/`): 開発ワークフロー
- **共有** (`docs/_shared/`): 用語集、コマンドリファレンス

## 継続的インテグレーション

### GitLab CI/CD

- **テスト**: すべてのコミットでpytestを実行
- **リンター**: Ruffによる静的解析
- **カバレッジ**: カバレッジレポート生成
- **ドキュメント**: Sphinxビルド検証

## 将来の方向性

### v1 への移行

- v1の機能を段階的に拡張
- v0との互換性を維持
- 最終的にv1をデフォルトに

### 計画されている改善

- よりよいエラーハンドリング
- パフォーマンス最適化
- 追加のデータ形式サポート
- リアルタイムデータ可視化

---

## アーキテクチャ判断レコード (ADR)

詳細なアーキテクチャ判断と設計決定については、[Architecture Decision Records (ADR)](../adr/)を参照してください。ADRsは、プロジェクトの進化過程で下されたキー決定と、その理由を文書化しています。

---

アーキテクチャに関する質問や提案は、[GitLab Issues](https://gitlab.com/qumasan/haniwers/-/issues)で歓迎します。