# 環境構築手順 (Environment Setup)

環境の再構築・別の PC での作業開始時に使う手順．プロジェクト作成時に一度だけ行う設定は [ENV_03](ENV_03_管理者用環境構築手順.md) にまとめる．

## 前提ツール (Prerequisites)

| ツール | 用途 | 備考 |
| --- | --- | --- |
| git | バージョン管理 | 運用は `.claude/rules/git-conventions.md` |
| gh | GitHub CLI | 手元 PC のみ．PR 作成・リポジトリ設定 |
| uv | Python・依存管理 | `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`（ユーザー領域 `%USERPROFILE%\.local\bin` に入る．`winget install astral-sh.uv` でもよい） |
| Python 3.12 | 実行環境 | `uv python install 3.12`（uv が管理する．`.python-version` で固定） |
| Python 3.7 以上 ＋ bash | `.claude/hooks/` の実行 | 手元 PC のみ（研究室 PC では Claude Code を使わない）．Windows は Git for Windows 付属の bash．※ Python が見つからないとアクセス制限フックが全ツールをブロックする |
| OpenSSH | 研究室 PC の操作 | Windows 11 標準．SSH の別名 `labpc`（研究室 PC．Tailscale 経由）は SmTIAS-LightSim で構築済みのものを使う |

## 場所ごとの役割 (Roles by Location)

| 場所 | 役割 | 臨床データ |
| --- | --- | --- |
| 手元 PC | 開発．ダミーデータでのテスト | 置かない |
| 研究室 PC（`DESKTOP-1QLOO91`．SSH の別名 `labpc`） | 目録とデータ置き場を置き，CLI で登録・manifest の書き出しを行う | 原本 |
| 計算サーバ（Newton・Archimedes） | 使う側のリポジトリが学習・解析を行う．研究室 PC から manifest と作業用コピーを受け取る | 作業用コピー |

## 手元 PC のセットアップ (Local Setup)

```bash
git clone https://github.com/rintoHasegawa/TIASDataHub.git
cd TIASDataHub
uv sync
uv run pytest
```

- `uv sync` で `.venv/` に依存（実行時は pydantic のみ．開発用に pytest・ruff・Pillow）が入る
- 手元 PC には臨床データを置かない．テストはダミーデータ（テスト内で一時ディレクトリに作る）だけで動く

## 研究室 PC の操作方針 (Lab PC Operation Policy)

研究室 PC は**手元 PC から SSH（`ssh labpc`）で操作する**．研究室 PC の前で作業したり，研究室 PC で Claude Code を開いたりはしない（2026-10-02 のユーザー判断）．

- 研究室 PC は `main` を取り込んで CLI を実行するだけにし，**研究室 PC では編集・コミットしない**（変更は手元 PC で作業ブランチ → PR で `main` に入れる）
- SSH 経由の操作は非対話で行う（パスワード入力・GUI が必要な操作は SSH ではできない）
- **SSH 経由でデータの中身を表示しない**．`.claude/repo-access.json` のフックは SSH の先のファイル読み取りまでは止められないため，データの確認は CLI の集計出力（件数・ハッシュの不一致・参照切れ等．患者 ID・ファイル名を含まない）で行う．`type`・`Get-Content` 等でデータ置き場・目録・対応表を直接読まない
- データの置き場所は研究室 PC 上の設定ファイルから CLI が読む．SSH のコマンドにデータのパスを書かなくて済むようにする（仕様設計で決める）
- 研究室 PC 側で人間が必要な作業: 新しいデータを研究室 PC に置くこと（USB 等で持ち込む場合），GUI でしか動かないプログラムの操作，研究室 PC の起動と Tailscale への接続の維持

## 研究室 PC のセットアップ (Lab PC Setup)

GitHub から取得する．研究室 PC には個人のアカウントの認証情報を置かず，このリポジトリ専用の**読み取り専用のデプロイキー**（SSH の別名 `github-tiasdatahub`）で取得する（設定は [ENV_03「研究室 PC のデプロイキー」](ENV_03_管理者用環境構築手順.md)）．手元 PC から次のように実行する（uv は非対話の SSH では PATH に入らないため絶対パスで呼ぶ）．

```bash
ssh -n labpc "cd C:\Users\Papin\source && git clone git@github-tiasdatahub:rintoHasegawa/TIASDataHub.git"
ssh -n labpc "cd C:\Users\Papin\source\TIASDataHub && C:\Users\Papin\.local\bin\uv.exe sync --no-dev --extra import"
```

更新するとき（`init` は新しいマイグレーションがあれば適用する．無ければ何もしない）:

```bash
ssh -n labpc "cd C:\Users\Papin\source\TIASDataHub && git pull && C:\Users\Papin\.local\bin\uv.exe sync --no-dev --extra import && C:\Users\Papin\.local\bin\uv.exe run --no-dev --extra import tiasdata init"
```

- ※ clone・`uv sync` は未検証（立ち上げの成果物を `main` に取り込んだ後に実行する）．デプロイキーでの接続（`git ls-remote`）は 2026-10-02 に確認済み
- 研究室 PC からは取得しかできない（デプロイキーは読み取り専用）．研究室 PC では編集・push しない（上記「操作方針」）
- 置き場所は `C:\Users\Papin\source\`（OneDrive の同期対象外）．**ドキュメント・デスクトップ配下には置かない**（研究室 PC ではドキュメントフォルダが OneDrive にリダイレクトされている）
- 目録・ストア・対応表は `E:\clinical-data\tiasdata\`・`tiasdata-identity\` に置き，場所は設定ファイル `C:\Users\Papin\.config\tiasdata\config.toml` に書く（配置と設定のキーは [SPEC_01「配置」「設定ファイル」](../04_SPEC/SPEC_01_アーキテクチャ設計.md)）．設定ファイルの作成と `tiasdata init` は実装後に行う ※ 未検証

## 使う側のリポジトリへの組み込み (Using from Other Repositories)

Python のプロジェクトでは，本リポジトリを git サブモジュールとして置き，編集可能なパッケージとして読み込む．

```bash
git submodule add https://github.com/rintoHasegawa/TIASDataHub.git external/TIASDataHub
```

```toml
# 使う側の pyproject.toml
[project]
dependencies = ["tiasdata"]

[tool.uv.sources]
tiasdata = { path = "external/TIASDataHub", editable = true }
```

- サブモジュールは**本リポジトリの `main` にマージ済みのコミット**を指す．使う側の作業中に基盤を直した場合は，サブモジュールの中で作業ブランチを切って本リポジトリに PR を出し，マージ後にサブモジュールの参照を更新する
- ※ 未検証（使う側への組み込みは実装フェーズで行う）

## 臨床データの取り扱い (Clinical Data Handling)

**手順ではなく，守るべき制約である．**

- データ本体と，実際の患者 ID ↔ 研究用 ID の対応表はリポジトリに入れない．`.gitignore` で `/data/`・`*.sqlite`・`*.db`・`/exports/` 等を除外しているが，そもそもリポジトリの配下に置かない
- 手元 PC に臨床データを置かない
- Claude にデータの中身を読ませない．`.claude/repo-access.json` の `deny_read` に研究室 PC のデータフォルダ（`E:/clinical-data`）とリポジトリ内の `data/`・`exports/` を入れている．データ置き場・DB の場所を追加・変更したら，このリストも更新する

## 環境再現性のルール (Reproducibility Rules)

- 依存の追加は `uv add`（開発用は `uv add --dev`）．`uv.lock` はコミットする
- 実行時の依存は最小限にする（使う側に入るため．[ENV_01](ENV_01_技術スタック.md)）
- データの置き場所をコードに書かない（設定ファイル・環境変数で渡す）

## トラブルシューティング (Troubleshooting)

| 症状 | 原因 | 対処 |
| --- | --- | --- |
| `python --version` が `Python` とだけ出る | Microsoft Store の案内用スタブ（`WindowsApps\python.exe`）が呼ばれている | `uv python install 3.12` で入れた Python を使う．プロジェクト内では `uv run` を使えば uv が管理する Python が使われる |
| SSH で `uv` が見つからない | 非対話の SSH セッションに PATH の変更が反映されていない | `C:\Users\Papin\.local\bin\uv.exe` を絶対パスで呼ぶ |
| SSH の出力が文字化けする | 研究室 PC の出力が CP932 | 手元で `iconv -f cp932 -t utf-8` を通す |
| ファイル操作系のツールが全てブロックされる | フック用の Python が見つからない | `python3` / `python` / `py` のいずれかが起動できるようにする |