# v1.3.0 (2025-10-27)

このリリースは、複数チャネルの閾値スキャニングを並列実行する新しい高速化機能を実装した重要なアップデートです。
すべてのチャネルが同時に閾値段階をステップするパラレル方式により、シリアルスキャンと比べて**3倍の高速化**を実現しました。

## ✨ v1.3.0 での改善点

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

- **パラレル閾値スキャニング**: すべてのチャネルが同時にステップ（3倍高速化）
- **配置検証機能**: チャネル設定の不一致を事前検出し、無駄なスキャンを防止
- **エラー回復機構**: ハードウェア障害時も`スキップして続行`戦略で最大限のデータ収集を実現
- **完全な後方互換性**: シリアルスキャン機能は一切変更なし、既存テストすべてが引き続き成功

## 🎯 User Story 1 - 基本的なパラレル閾値スキャン

### 新機能: 全チャネル同時ステップ

- **`threshold parallel --mock`**: パラレルモードでの閾値スキャンが可能に
  ```bash
  haniwers-v1 threshold parallel \
    --thresholds "1:200;2:300;3:250" \
    --nsteps 8 \
    --step 5 \
    --duration 5 \
    --mock
  ```
  - すべてのチャネルが同じタイミングで閾値段階をステップ
  - 測定は 1 回のデータ収集で全チャネルのデータを同時取得
  - チャネルごとに独立した CSV ファイルを出力

### パラレルステップのメカニズム

- **シリアルスキャン** (従来): 1 チャネル → 次チャネル → 次チャネル
  - 3 チャネル × 20 段階 = 60 回の測定（5 秒×60 = 300 秒）

- **パラレルスキャン** (新方式): 全チャネル同時にステップ
  - 20 段階 = 20 回の測定（5 秒×20 = 100 秒）
  - **3 倍の高速化** を実現！

### CSV 出力と出力管理

- **チャネルごとの CSV ファイル**: `scan_results_ch1.csv`, `scan_results_ch2.csv`, `scan_results_ch3.csv`
- **追記モード**: 複数回スキャンを実行しても履歴データが保持される
- **監査ログ**: `threshold_operations.csv` にすべての閾値操作を記録

## 🎯 User Story 2 - 配置検証機能

### 設定エラーの早期検出

- **チャネル設定の同期確認**: すべてのチャネルが同じ段階数（nsteps）を持つことを確認
  ```bash
  haniwers-v1 threshold parallel --config config_invalid.toml --mock
  # エラー: Parallel scanning requires all channels to have same number of steps.
  # Got: {1: 21, 2: 19}
  ```

- **フェイルファスト設計**: スキャン開始前に設定エラーを検出
  - 無駄な時間を消費しない
  - ユーザーに明確なエラーメッセージを表示
  - 設定の修正方法をガイド

### 検証ロジック

- `validate_threshold_ranges()` 関数で設定チェック
- CLI レイヤーとビジネスロジックレイヤーの両方で検証
- 既存の汎用バリデーターを再利用（DRY 原則遵守）

## 🎯 User Story 3 - エラー回復と堅牢性

### スキップして続行戦略

- **段階ごとのエラーハンドリング**: 1 チャネルが失敗したら全チャネルの該当段階をスキップ
  ```
  Step 0: ✅ Success (all channels)
  Step 1: ✅ Success (all channels)
  Step 2: ⚠️ Channel 1 write failed → Step 2 を全チャネルでスキップ
  Step 3: ✅ Success (all channels)
  ...
  ```

- **リトライメカニズム**: 一時的なハードウェア障害に対応
  - 最大 3 回まで自動リトライ
  - 各試行をログに記録
  - すべてリトライ失敗後は段階をスキップ

- **エラー集約**: すべてのエラーをスキャン結果に集約
  - 部分的な成功を許容
  - スキャンは中断せず続行
  - ユーザーはエラーサマリーで問題を把握可能

### 実装例

```python
# パラレルスキャン実行
result = run_parallel_threshold_scan(config, device, max_retry=3)

# 結果確認
print(f"Success: {result.success}")
print(f"Scanned channels: {result.scanned_channels}")
print(f"Skipped steps: {result.skipped_steps}")  # [2, 5] など
print(f"Errors: {result.errors}")  # エラーメッセージリスト
```

## 🧪 テスト強化

### 新規ユニットテスト（19 件）

**検証テスト（4 件）**:
- チャネル段階数の一致確認
- 不一致時の明確なエラーメッセージ
- シリアルモードでは検証をスキップ
- バリデーター関数の単体テスト

**エラーハンドリングテスト（6 件）**:
- リトライロジックの動作確認
- エラー集約機能の検証
- スキップされた段階の追跡
- チャネル障害シミュレーション
- デバイス失敗時の回復確認
- エラーメッセージの詳細度

**ステップアルゴリズムテスト（3 件）**:
- 閾値計算の正確性（center + step×size）
- 値のクリッピング [1, 1023] 範囲
- すべてのチャネルの同期ステップ確認

**結果ファイルテスト（3 件）**:
- チャネルごとの CSV ファイル作成
- 追記モード（ヘッダは 1 度だけ書込）
- 監査ログの自動生成

**統合テスト（3 件）**:
- Mock デバイスでのエンドツーエンドテスト
- デバイス障害シミュレーション
- 出力ファイルの整合性確認

### テスト成功率

| テストスイート | 結果 | 詳細 |
|---------------|------|------|
| パラレルスキャンテスト | ✅ 19/19 | 検証 + エラー処理 + ステップ + ファイル + 統合 |
| v1 ユニットテスト全体 | ✅ 428/428 | 後方互換性確認済み |
| コード品質 | ✅ Pass | ruff format, pre-commit OK |
| テストカバレッジ | ✅ 90%+ | ビジネスロジック parallel.py |

## 🔧 内部実装の改善

### アーキテクチャ: パラレルスキャン実行エンジン

```python
# パラレルスキャン実行
from haniwers.v1.threshold.parallel import run_parallel_threshold_scan

config = HaniwersConfig.from_file("config.toml")
device = create_device(config, use_mock=True)

# 実行（配置検証も含む）
result = run_parallel_threshold_scan(
    config,
    device,
    max_retry=3  # リトライ回数
)

# 結果処理
if result.success:
    print(f"✅ Scanned {len(result.scanned_channels)} channels")
    print(f"📊 Output files: {result.files}")
else:
    print(f"⚠️ Partial success: {len(result.errors)} errors occurred")
    for error in result.errors:
        print(f"  - {error}")
```

### 設計の特徴

- **Sequential 実装**: async なし、シンプル設計を優先（YAGNI 原則）
  - シリアル通信がボトルネック → 複雑な並列化は不要

- **バリデーター再利用**: `validate_threshold_ranges()` を統合
  - 既存コードの活用でコード重複を回避
  - CLI と ビジネスロジックの両レイヤーで検証

- **All-or-Nothing** ステップ: チャネル単位の部分的成功ではなく、段階単位で成功/失敗を判定
  - CSV ファイルの整合性を保証
  - データ分析時の混乱を防止

- **エラー集約**: 最後に全エラーをまとめて報告
  - スキャン途中で中断しない
  - ユーザーが最大限のデータを取得可能

### 後方互換性保証

- ✅ パラレルスキャンは完全に新規機能（serial 機能は変更なし）
- ✅ 既存シリアルスキャンのテスト（95 件）すべて継続成功
- ✅ 設定スキーマ変更なし
- ✅ CLI は新規サブコマンド `parallel` を追加

## 📋 今後の拡張（v1.4+）

### 非同期実行の検討

```bash
# 将来的な計画
haniwers-v1 threshold parallel --async  # 非同期実行モード
```

### 統計分析機能

- チャネル間の相関分析
- 失敗率の統計計算
- パフォーマンス最適化提案

### 進捗表示とモニタリング

- リアルタイムプログレスバー
- スキャン速度の表示
- ETA (推定完了時間)の計算

## 📦 インストール

```bash
pip install haniwers==1.3.0
```

または最新版：

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

## 🔗 関連リンク

- [完全な変更ログ](../../CHANGELOG.md#130-2025-10-27)
- [仕様書](../../specs/019-parallel-threshold-scan/)
- [アーキテクチャ決定記録 (ADR-020)](../../docs/adr/020-parallel-threshold-scanning.md)
- [実装ドキュメント](../../docs/progress/entries/2025-10-27-parallel-threshold-scan-completion.md)
- [ドキュメント](https://qumasan.gitlab.io/haniwers/docs/)
- [Issues](https://gitlab.com/qumasan/haniwers/-/issues)
- [リリースタグ](https://gitlab.com/qumasan/haniwers/-/tags/1.3.0)

---

**リリース担当**: shotakaha
**リリース日**: 2025-10-27
**MR**: [!101 - feat: complete parallel threshold scanning implementation (019)](https://gitlab.com/qumasan/haniwers/-/merge_requests/101)