# v1.4.0 (2025-10-29)

このリリースは、Spec 021（Threshold Scan Sampler）の大規模リファクタリングを完了した重要なアップデートです。
パラレル・シリアルスキャンの統合、CSV監査ログの強化、ロギング機能の改善により、より堅牢で保守性の高いシステムを実現しました。

## ✨ v1.4.0 での改善点

このマイルストーンは、以下を実現します。

- **Threshold Scan Sampler 統合**: `serial()` と `parallel()` の共通インターフェース化によるコード統一
- **CSV監査ログ強化**: `attempts` フィールド追加により詳細な実行履歴を記録
- **ロギング機能拡張**: モジュール・関数・行番号の位置情報を含むデバッグログ
- **エラーハンドリング向上**: 割り込み処理対応とエラーマネジメントの強化
- **CLI 最適化**: 非推奨オプション削除と SamplerOptions への統一
- **アーキテクチャ整理**: 不要な Scanner モジュール削除と API 整理

## 🎯 User Story 1 - Threshold Writer の強化

### 新機能: 包括的なデバッグログと位置情報

- **ロガー設定の拡張**: ログフォーマットにモジュール、関数、行番号を追加
  ```python
  # 従来:
  # INFO: Threshold write succeeded

  # v1.4.0:
  # INFO [haniwers.v1.threshold.writer:write_threshold:142]: Threshold write succeeded
  ```

- **Debug ログの充実**: Threshold Writer に包括的なロギングを実装
  - 段階前後のステータス確認
  - リトライ試行の詳細ログ
  - チャネル別の成功/失敗情報

- **割り込み処理対応**: Ctrl+C でスキャン実行中に安全に中断可能
  - スキャン途中の中断を適切にハンドル
  - 部分的な結果を CSVに保存
  - エラーサマリーを表示

### CSV 監査ログの詳細化

- **`attempts` フィールド追加**: 各閾値操作の試行回数を記録
  ```csv
  timestamp,channel,threshold,status,attempts,notes
  2025-10-29T10:00:00+00:00,1,280,success,1,"Write successful on first attempt"
  2025-10-29T10:00:05+00:00,2,320,success,3,"Required 3 attempts due to communication error"
  ```

- **履歴追跡機能**: 何度スキャンを実行しても履歴が保持される
  - マルチラン対応で長期的な実験をサポート
  - 各実行の詳細を CSV で分析可能

## 🎯 User Story 2 - ThresholdScanResult モデルと Sampler 統合

### 統合された結果モデル

- **`ThresholdScanResult` モデル**: スキャン結果を統一形式で管理
  ```python
  from haniwers.v1.threshold.model import ThresholdScanResult

  # スキャン実行
  result = run_parallel_threshold_scan(config, device)

  # 統一されたインターフェース
  print(f"Success: {result.success}")
  print(f"Channels: {result.scanned_channels}")
  print(f"Attempts: {result.total_attempts}")
  print(f"CSV files: {result.files}")
  ```

- **モデル整理**: `ThresholdResult` → `ThresholdWriteResult` に名前変更
  - 書き込み結果と スキャン結果の区別を明確化
  - API の意図をより正確に表現

- **Sampler との連携**: `serial()` と `parallel()` が `ThresholdScanResult` を返却
  - 共通インターフェースで統一的な処理が可能
  - スキャン実行後の結果処理が簡潔に

## 🎯 User Story 3 - CLI コマンドの整理と最適化

### SamplingOptions への統一

- **非推奨オプション削除**: `SamplingOptions` と `SamplerModeOptions` を廃止

- **SamplerOptions への統一**: 単一の統一されたオプションクラスを使用
  - ConfigLoader 統合で TOML ベースの設定が可能に
  - CLI オプションの冗長性を排除

- **SamplerConfig の対称性**: 不足していたオプションを追加
  - v1.0 以来の設定パラメータの不均衡を解決
  - スキャンと測定の両方で同じ設定項目を使用可能に

### serial() コマンドの簡素化

```bash
# v1.4.0 の改善後
haniwers-v1 threshold serial \
  --thresholds "1:200;2:300;3:250" \
  --config config.toml \
  --duration 5 \
  --nsteps 10
```

- **測定ループの再構成**: per-sensor scanning を Sampler.run() で実装
  - チャネルごとの独立した測定制御
  - より柔軟なスキャンロジック

## 🧪 テスト強化

### リファクタリング後の検証

| テストスイート | 状態 | 詳細 |
|---------------|------|------|
| v1 ユニットテスト全体 | ✅ パス | Scanner モジュール削除後も回帰なし |
| コード品質 | ✅ Pass | ruff format, pre-commit OK |
| テストカバレッジ | ✅ 80%+ | CSV、ロギング、エラーハンドリング対応 |

### 削除されたレガシーテスト

- **Old Scanner test 削除** (~568 LOC):
  - `test_serial_threshold_scan.py` (parallel mode テスト)
  - `test_parallel_threshold_scan.py` (serial mode テスト)
  - 非推奨の `collect_events()` API に依存するテスト

- **理由**: Sampler による統一化により不要になったレガシーテスト
  - 新しい Sampler ベースのテストで十分カバー

## 🔧 内部実装の改善

### API の削除と整理

- **削除された関数**:
  - `load_thresholds_from_csv()`: 非推奨 API
  - `run_serial_threshold_scan()`: serial.py モジュール削除に伴う廃止
  - 複数の legacy scan 実行関数

- **削除されたモジュール**:
  - `src/haniwers/v1/threshold/serial.py`: Sampler に統合
  - `src/haniwers/v1/threshold/parallel.py`: Sampler に統合
  - `src/haniwers/v1/helpers/scan_result.py`: ScanResultWriter に統合

- **削除された CLI**:
  - `scan` サブコマンドモジュール: write / serial コマンドに統合

### コード改善

- **Magic Numbers の廃止**: プロトコル定数とタイミング定数への置き換え
  ```python
  # 従来 (threshold/writer.py):
  val1 = 0b10000 + (vth >> 6)  # ヘッダビット + 上位3ビット
  val2 = (vth << 2) & 0xFF      # 下位8ビット
  time.sleep(0.1)               # デバイス安定化待ち
  time.sleep(0.5)               # リトライ間隔

  # v1.4.0:
  PROTOCOL_HEADER_BIT = 0b10000
  THRESHOLD_UPPER_BITS_SHIFT = 6
  THRESHOLD_LOWER_BITS_SHIFT = 2
  BYTE_MASK = 0xFF
  DEVICE_STABILIZATION_DELAY = 0.1
  RETRY_INTERVAL = 0.5

  val1 = PROTOCOL_HEADER_BIT + (vth >> THRESHOLD_UPPER_BITS_SHIFT)
  val2 = (vth << THRESHOLD_LOWER_BITS_SHIFT) & BYTE_MASK
  time.sleep(DEVICE_STABILIZATION_DELAY)
  time.sleep(RETRY_INTERVAL)
  ```

- **ログレベルの整理**: 過度なデバッグログを削除
  - パフォーマンス向上
  - ログ出力の可読性向上
  - 本当に必要な情報に焦点

- **関数名の明確化**:
  - `log_threshold_operation()` → `write_threshold_to_csv()`
  - より正確な関数名で意図を表現

### Sampler 統合の成果

```python
# v1.3.0:
from haniwers.v1.threshold.serial import run_serial_threshold_scan
from haniwers.v1.threshold.parallel import run_parallel_threshold_scan

# v1.4.0: 統一されたインターフェース
from haniwers.v1.threshold.scanner.serial import run_serial_threshold_scan
from haniwers.v1.threshold.scanner.parallel import run_parallel_threshold_scan
# どちらも同じ ThresholdScanResult を返却
```

## 📊 Spec 021 実装完了サマリー

### Phase 1-5 の達成

1. **Phase 1** (計画): Threshold Scan Sampler 設計完了
2. **Phase 2** (実装): device.read_events() から Sampler への置き換え完了
3. **Phase 3** (統合): serial / parallel / write の統一インターフェース化完了
4. **Phase 4** (強化): CSV エクスポート、デバッグログ、エラー処理向上
5. **Phase 5** (最適化): CLI 整理、レガシー API 削除、SamplerOptions 統一

### 主要な統計

- **削除コード**: ~1200 LOC (legacy scanner module)
- **追加テスト**: ~200 LOC (Sampler 統合テスト)
- **実装期間**: 2025-08-25 ～ 2025-10-29 (約 2 ヶ月)
- **コミット数**: 71 commits

## 📦 インストール

```bash
pip install haniwers==1.4.0
```

または最新版：

```bash
pip install --upgrade haniwers
```

## 🔗 関連リンク

- [完全な変更ログ](../../CHANGELOG.md#140-2025-10-29)
- [仕様書](../../specs/021-threshold-scan-sampler/)
- [実装進行状況](../../.specify/progress/021/)
- [ドキュメント](https://qumasan.gitlab.io/haniwers/docs/)
- [Issues](https://gitlab.com/qumasan/haniwers/-/issues)
- [リリースタグ](https://gitlab.com/qumasan/haniwers/-/tags/1.4.0)

---

**リリース担当**: shotakaha
**リリース日**: 2025-10-29
**MR**: [!106 - feat(threshold): complete Sampler integration and API cleanup (021)](https://gitlab.com/qumasan/haniwers/-/merge_requests/106)