# 開発者向けガイド

:::{admonition} ゴール

haniwers のコードを理解して、測定ツールを改善・拡張しよう

:::

**このセクションは、haniwers の開発に参加したい開発者向けです。**

初めての方は、まず以下を読んでください：
- [クイックスタート](../quickstart.md) - 10分で使ってみる
- [インストールガイド](../install.md) - 開発環境の構築
- [ユーザーガイド](../user/index.md) - 基本的な使い方

## 📋 開発に参加する前に

1. リポジトリをフォークまたはクローン
2. 開発ブランチを作成
3. 小さな変更から始める
4. テストとドキュメントを併せて更新

詳細は [開発ガイド](../dev/index.md) を参照してください。

## 🚀 開発環境の構築手順

### ステップ 1: リポジトリのセットアップ

```bash
# リポジトリをクローン
git clone https://gitlab.com/qumasan/haniwers
cd haniwers

# Git worktree で開発ブランチを作成（推奨）
git worktree add ../worktrees/feature-name -b feature/feature-name

# または通常のブランチ切り替え
git branch feature/feature-name
git switch feature/feature-name
```

### ステップ 2: 依存関係のインストール

```bash
# 開発・ドキュメント依存関係を含めてインストール
poetry install --with docs,dev

# または uv を使用（最速）
uv sync --all-groups
```

### ステップ 3: 環境確認

```bash
# 依存関係ツリー確認
poetry show --tree

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

### ステップ 4: 開発環境テスト

```bash
# テストの実行
poetry run pytest

# コード品質チェック
poetry run ruff check .
poetry run ruff format .
```

## 🧪 開発・テスト方法

### コマンドの実行テスト

開発環境で haniwers コマンドが正しく動作するか確認：

```bash
# サンドボックスディレクトリで実行
cd sandbox

# ヘルプ表示
poetry run haniwers --help

# 利用可能なポート確認
poetry run haniwers ports

# バージョン確認
poetry run haniwers version

# 特定のコマンドをテスト
poetry run haniwers scan --help
poetry run haniwers daq --help
```

### ユニットテスト

```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` で擬似データ生成
- **単体テスト**: 新機能追加時はテストも併せて作成

---

## 📚 関連ドキュメント

- **[CLAUDE.md](../../CLAUDE.md)** - プロジェクト全体の開発ガイド
- **[開発ガイド](../dev/index.md)** - ブランチ戦略、MR プロセス
- **[API リファレンス](../apidocs/index.md)** - 自動生成 API ドキュメント
- **[ユーザーガイド](../user/index.md)** - ツールの使い方

## ✅ 開発時のチェックリスト

開発や改修を行う際は、以下を確認してください：

- [ ] コードが Ruff フォーマットを通す（`poetry run ruff format .`）
- [ ] テストが全て通る（`poetry run pytest`）
- [ ] pre-commit フックが通る（`poetry run pre-commit run --all-files`）
- [ ] 新機能に対応するテストを追加している
- [ ] ドキュメント（docstring）を更新している
- [ ] リリースノートに変更点を記載している（必要に応じて）

## 🤝 貢献ガイドライン

1. **小さな変更から始める** - 大きな変更は事前にイシューで相談
2. **テストとドキュメント必須** - コードだけでなく、テストと doc も
3. **Conventional Commits** - コミットメッセージ形式を遵守
4. **MR テンプレート使用** - GitLab の MR テンプレートを使用
5. **コードレビュー** - CI が通ったら、他の開発者のレビューを待つ

詳細は [開発ガイド](../dev/index.md) を参照してください。