# 開発者向けガイド

このセクションは、`haniwers` プロジェクトに貢献したい「開発者（Developer）」向けのドキュメントです。

開発環境のセットアップから、コードの理解、テストの実行、そして貢献の方法まで、開発に必要な情報を提供します。

:::{admonition} このセクションの目標
コードを理解して、測定ツールを改善し、プロジェクトに貢献できるようになる
:::

## コンテンツ

- **[貢献ガイド](./contributing.md)**: プロジェクトへの貢献方法、ブランチ戦略、コミット規約
- **[Docker Containers ガイド](./containers.md)**: Docker/Docker Composeを使った開発・テスト環境（初心者向け）
- **[アーキテクチャ](./architecture.md)**: v0/v1のデュアルアーキテクチャ、技術選定の理由
- **[データ取得（サンプリング）ガイド](./sampling.md)**: Device、RawEvent、Sampler、SamplerConfigの理解と使い方
- **[Sandbox開発ガイド](./sandbox.md)**: 隔離環境でのテスト、モックデバイス活用、CLI検証
- **[設定ガイド](./configuration.md)**: ConfigLoaderの使い方、TOML設定ファイル、環境変数オーバーライド
- **[CLI開発ガイド](./cli-development.md)**: V1 CLI拡張パターン、新規コマンド追加方法
- **[CLI Context 継承ガイド](./cli-context-inheritance.md)**: グローバルオプションの継承、Typer Contextの使い方（初心者向け）
- **[テストガイドライン](./testing.md)**: テストの種類、実行方法、TDDワークフロー
- **[TestPyPI パッケージ動作テスト](./testing-testpypi.md)**: TestPyPI公開パッケージのローカル検証方法
- **[Mockerの使い方](./mocking.md)**: デバイスなし開発のためのMocker活用ガイド
- **[よくある質問 (FAQ)](./faq.md)**: 開発時によくある質問と回答
- **[チュートリアル](./tutorial.md)**: 開発環境のセットアップから最初の貢献まで

```{toctree}
---
maxdepth: 1
hidden:
---
contributing
containers
architecture
sampling
sandbox
configuration
cli-development
cli-context-inheritance
testing
testing-testpypi
mocking
faq
tutorial
```

---

## 開発環境の構築手順

### 基本セットアップ

```bash
git clone https://gitlab.com/qumasan/haniwers
cd haniwers
poetry install --with docs,dev
```

### 開発用依存関係の確認

```bash
poetry show --tree
poetry run haniwers version --env
```

## 開発・テスト方法

### Sandboxディレクトリでの開発・テスト

`sandbox/`ディレクトリは、開発・テスト用の隔離された環境として機能します。実際のデータやハードウェアなしでコマンドテストを実行できます。

**Sandboxの役割:**
- 設定ファイルのテスト環境
- モックデバイスでの動作確認
- CLI コマンドの検証
- 新機能の動作確認

**基本的な使用方法:**

```bash
# Sandbox ディレクトリに移動
cd sandbox

# ヘルプの確認
poetry run haniwers --help
poetry run haniwers-v1 --help

# ポート確認（実際のシリアルポート表示）
poetry run haniwers ports list
poetry run haniwers ports test /dev/cu.usbserial-140

# バージョン・環境情報の確認
poetry run haniwers version
poetry run haniwers version --env
```

**設定ファイルでのテスト:**

```bash
# Sandbox内で設定ファイルを作成・テスト
cp ../examples/daq.toml ./daq.toml
cp ../examples/config.toml ./config.toml

# モックデバイスでDAQをテスト（設定ファイル使用）
poetry run haniwers-v1 daq --config daq.toml --mock

# スレッショルドスキャンのテスト
poetry run haniwers-v1 scan serial --help
```

**Mockerを使ったテスト:**

```bash
# ランダムイベント生成でDAQテスト
poetry run haniwers-v1 daq --mock --mock-speed 10.0

# 既存CSVファイル再生でテスト
poetry run haniwers-v1 daq --mock --mock-file sample.csv
```

**Sandboxディレクトリの構成:**

```
sandbox/
├── config.toml           # グローバル設定
├── daq.toml             # DAQ設定
├── scan.toml            # スレッショルドスキャン設定
├── data/                # 処理済みデータ
├── logs/                # ログファイル
└── .env.haniwers        # 環境変数（オプション）
```

### ユニットテスト

```bash
# 基本テスト実行
poetry run pytest

# カバレッジ付きテスト
poetry run pytest --cov=haniwers --cov-report=html

# 特定のテストモジュール実行
poetry run pytest tests/test_config.py -v
```

### コード品質チェック

```bash
# フォーマット
poetry run ruff format .

# 静的解析
poetry run ruff check .

# 型チェック（mypy設定がある場合）
# poetry run mypy haniwers/

# pre-commitフック実行
poetry run pre-commit run --all-files
```

## 現在のモジュール構成（v0.23.1）

### `haniwers/cli.py`

メインのCLIエントリーポイント：
- Typerベースのコマンド定義
- `daq`, `scan`, `fit`, `vth`, `ports`等のサブコマンド
- ログ設定とオプション解析

### `haniwers/config.py`

設定管理：
- `Config`, `RunData`, `UserSettings`クラス
- TOML設定ファイル（`daq.toml`, `scan.toml`）の読み込み
- パス管理と環境固有設定

### `haniwers/daq.py`

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

### `haniwers/threshold.py`

スレッショルド制御：
- `scan_thresholds_in_parallel`: 並列スレッショルド測定
- `Count`データクラス: 測定結果の構造化
- フィット処理とCSV出力

### `haniwers/dataset.py`

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

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

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

## 現在の設計方針

### アーキテクチャ

- **モジュールごとの責務分離**
  - CLI: コマンド定義とオプション解析（`cli.py`）
  - DAQ: ハードウェア制御とデータ取得（`daq.py`）
  - 設定: TOML設定の管理（`config.py`）
  - データ処理: 前処理・後処理・可視化（`preprocess.py`, `postprocess.py`）

- **CLIはTyperベース**
  - `haniwers COMMAND [OPTIONS]` 形式
  - サブコマンド: `daq`, `scan`, `fit`, `vth`, `ports`, `run2csv`
  - 統一されたログ出力とエラー処理

- **設定ファイルによる柔軟性**
  - `daq.toml`: データ取得設定
  - `scan.toml`: スレッショルドスキャン設定
  - `runs.csv`: 実験ラン管理

- **データフロー**
  - 生データ取得 → 前処理 → CSV保存 → 可視化・解析
  - タイムスタンプベースのファイル管理
  - Pandas/Polarsによる効率的なデータ処理

## 開発のベストプラクティス

### コーディング規約

- **Conventional Commits**: コミットメッセージ規約の遵守
- **Ruff**: フォーマットと静的解析
- **型ヒント**: 可能な限りtype hintsを使用
- **Docstring**: 公開関数には説明を記載

### リリース手順

```bash
# 1. 機能開発・バグ修正
git commit -m "feat: add new feature"

# 2. バージョン管理
poetry run cz bump --dry-run  # 確認
poetry run cz bump -cc -ch    # 実行

# 3. パッケージ公開
poetry build
poetry publish --repository testpypi  # テスト
poetry publish                        # 本番

# 4. タグプッシュ
git push origin main --tags
```

### デバッグとテスト

- **ログレベル**: `--log-level DEBUG`でデバッグ情報表示
- **モック**: `haniwers/mimic.py`で擬似データ生成
- **単体テスト**: 新機能追加時はテストも併せて作成

---

開発や改修を行う際は、以下も併せてお願いします：
- 対応するテストの追加・更新
- ドキュメントの更新
- リリースノートへの変更点記載