# よくある質問（開発者向け）

開発時によくある質問と回答をまとめています。

## 環境セットアップ

### Q: `poetry shell` が非推奨と聞きましたが、どうすればいいですか？

**A:** Poetry 2.0+ では `poetry shell` の代わりに以下を使用してください：

```bash
# コマンドを直接実行
poetry run <command>

# または仮想環境をアクティベート
poetry env activate
```

`poetry shell` は将来のバージョンで削除される予定です。

### Q: Poetry のインストールに失敗します

**A:** `pipx` または `uv` を使用してインストールしてください：

```bash
# pipx を使用（推奨）
pipx install poetry

# または uv を使用
pipx install uv
uv tool install poetry
```

システムのPythonに直接インストールするのは避けてください。

### Q: 依存関係のインストール中にエラーが発生します

**A:** 以下を試してください：

```bash
# キャッシュをクリア
poetry cache clear pypi --all

# 依存関係を再インストール
poetry install --with docs,dev
```

それでも解決しない場合は、`poetry.lock` を削除して再生成してください：

```bash
rm poetry.lock
poetry install --with docs,dev
```

## テスト

### Q: テストを実行するとエラーが出ます

**A:** 以下を確認してください：

1. **依存関係のインストール**:
   ```bash
   poetry install --with dev
   ```

2. **正しいディレクトリで実行**:
   ```bash
   # プロジェクトルートで実行
   poetry run pytest
   ```

3. **特定のバージョンのみテスト**:
   ```bash
   # v1のみ
   poetry run pytest tests/v1

   # v0をスキップ
   poetry run pytest -m "not v0"
   ```

### Q: カバレッジレポートを生成するには？

**A:** 以下のコマンドを使用してください：

```bash
# ターミナルに表示
poetry run pytest --cov=haniwers.v0 --cov=haniwers.v1 --cov-report=term

# HTMLレポートを生成
poetry run pytest --cov=haniwers.v0 --cov=haniwers.v1 --cov-report=html

# ブラウザで htmlcov/index.html を開く
```

### Q: テストが遅すぎます。速くする方法は？

**A:** 並列実行を使用してください：

```bash
# pytest-xdist を使用
poetry run pytest -n auto

# 特定のマーカーのみ実行
poetry run pytest -m "not slow"
```

## コミットとマージリクエスト

### Q: Conventional Commits の形式がよくわかりません

**A:** Commitizen を使用すれば対話的に作成できます：

```bash
git add <files>
cz c
```

または、以下の形式に従ってください：

```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

**タイプ**:

- `feat`: 新機能
- `fix`: バグ修正
- `docs`: ドキュメント
- `test`: テスト
- `refactor`: リファクタリング

**例**:

```
feat(daq): add parallel threshold scanning
fix(config): handle missing TOML sections
docs(readme): update installation instructions
```

### Q: pre-commit フックに失敗します

**A:** フックを手動で実行して問題を確認してください：

```bash
# すべてのファイルをチェック
poetry run pre-commit run --all-files

# 特定のフックのみ実行
poetry run pre-commit run ruff --all-files
```

自動修正されるものもあるので、再度 `git add` してコミットしてください。

### Q: MR を作成したいのですが、どうすればいいですか？

**A:** `glab` CLI を使用するのが最も簡単です：

```bash
# glab をインストール（初回のみ）
# macOS: brew install glab
# Linux: https://gitlab.com/gitlab-org/cli

# MR を作成
glab mr create --target-branch main --template draft
```

または、`git push` 後にターミナルに表示されるリンクをクリックしてください。

### Q: rebase でコンフリクトが発生しました

**A:** 以下の手順で解決してください：

1. **コンフリクトファイルを確認**:
   ```bash
   git status
   ```

2. **ファイルを編集して修正**:
   エディタで `<<<<<<<`, `=======`, `>>>>>>>` の区切りを探して修正

3. **ステージングしてrebaseを続行**:
   ```bash
   git add <fixed-files>
   git rebase --continue
   ```

4. **中断したい場合**:
   ```bash
   git rebase --abort
   ```

## デバッグ

### Q: デバッグ情報を表示するには？

**A:** ログレベルを DEBUG に設定してください：

```bash
haniwers --log-level DEBUG <command>

# 例
haniwers --log-level DEBUG daq --port /dev/ttyUSB0
```

### Q: シリアルポートが見つかりません

**A:** 利用可能なポートを確認してください：

```bash
# ポート一覧を表示
haniwers ports

# Linux/macOS の場合
ls /dev/tty*

# 権限を確認（Linux）
sudo usermod -a -G dialout $USER
# ログアウト・ログインが必要
```

### Q: ハードウェアなしでテストできますか？

**A:** はい、モックDAQを使用できます：

```bash
# v0: mimic モジュールを使用
# v1: mocker デバイスを使用

# コード例
from haniwers.v1.daq.mocker import MockDevice
device = MockDevice()
```

## アーキテクチャ

### Q: v0 と v1 の違いは何ですか？

**A:**

**v0**:
- シンプルで実証済み
- プロダクション対応
- すべての基本機能を提供

**v1**:
- モダンなアーキテクチャ
- より良いテスト容易性
- Pydantic による設定検証
- Loguru による構造化ロギング

詳細は[アーキテクチャドキュメント](./architecture.md)を参照してください。

### Q: どちらのバージョンを使うべきですか？

**A:**

**新機能を追加する場合**:
- v1 に追加（推奨）
- v1 はモダンで拡張しやすい

**バグ修正の場合**:
- 該当するバージョンを修正
- 必要に応じて両方を修正

**新規ユーザー**:
- v0 を使用（デフォルト、`haniwers` コマンド）
- 安定性が高い

### Q: v1 はいつメインになりますか？

**A:** v1 が十分に成熟し、v0 のすべての機能を提供できるようになったら、メインになります。現在は段階的に機能を追加中です。

## ドキュメント

### Q: ドキュメントをローカルでプレビューするには？

**A:**

```bash
# ライブリロード付きプレビュー
task livehtml

# または
cd docs
poetry run make livehtml

# ブラウザで http://localhost:8000 を開く
```

### Q: API ドキュメントが自動生成されません

**A:** autodoc2 の設定を確認してください：

```bash
# Sphinx ビルドを実行
cd docs
poetry run sphinx-build -b html . _build/html

# エラーメッセージを確認
```

`conf.py` の `autodoc2_packages` が正しく設定されているか確認してください。

### Q: ドキュメントのビルドに警告が出ます

**A:**

```bash
# 警告を詳細表示
cd docs
poetry run sphinx-build -W -b html . _build/html

# -W: 警告をエラーとして扱う
```

リンク切れや構文エラーを修正してください。

## その他

### Q: バージョンをバンプするには？

**A:** Commitizen を使用してください：

```bash
# 確認（dry-run）
poetry run cz bump --dry-run

# 実行
poetry run cz bump --changelog --check-consistency

# タグをプッシュ
git push origin --tags
```

### Q: PyPI にパッケージを公開するには？

**A:**

```bash
# ビルド
poetry build

# TestPyPI でテスト
poetry publish --repository testpypi

# 本番
poetry publish
```

API トークンが必要です。プロジェクトメンテナーに連絡してください。

### Q: git worktree のメリットは？

**A:**

- **ブランチ間の切り替えが高速**: ディレクトリを変更するだけ
- **並行開発が容易**: 複数のブランチで同時作業
- **git stash 不要**: 作業内容が隔離されている
- **クリーンな環境**: ブランチごとに独立

詳細は[貢献ガイド](./contributing.md#4-git-worktree-で作業スペースを作成する推奨)を参照してください。

---

**他に質問がありますか？**

[GitLab Issues](https://gitlab.com/qumasan/haniwers/-/issues) で質問するか、プロジェクトメンバーに連絡してください。