Newer
Older
TIASDataHub / .claude / rules / project-structure.md

paths: ["src/", "tests/", "datasets/**"]

プロジェクト構成ルール (Project Structure)

ソース・テスト・マイグレーション・データセットの定義を追加・移動するときは本ルールに従うこと.設計の背景は SPEC_01 アーキテクチャ設計を参照する(本ルールは配置規則のみを定める).

ディレクトリ構成 (Layout)

src/tiasdata/
├── __init__.py            # 公開 API(load・open_bundle・Bundle・Catalog)を再 export する
├── config.py              # 設定ファイルの読み込み・検証
├── catalog/               # 目録(SQLite)の接続・マイグレーションの適用・各表の操作(SQL はここだけ)
│   └── migrations/        # スキーマ変更(catalog/・identity/ の 2 系列.NNNN_<内容>.sql)
├── store.py               # ストア(ハッシュ・コピー・照合)
├── kinds/                 # ファイルの種類・所見の種類の値の型
├── importers/             # 取り込み元の形ごとの読み取り(1 つの形 = 1 モジュール)
├── datasets.py            # データセットの定義の評価・版の作成
├── bundle.py              # バンドルの書き出し・読み込み・検証
├── deliver.py             # 計算サーバへの受け渡し(scp・ssh)
└── cli.py                 # CLI エントリポイント

datasets/                  # データセットの定義(<名前>.toml)
tests/                     # src/tiasdata/ の構造をミラーする

配置ルール (Placement Rules)

  • 1 モジュール 1 責務: 新しい機能は責務に合うモジュールに置く.大きくなったらサブパッケージに分ける(既存モジュールを肥大化させない)
  • 依存方向: cli → datasets・bundle・deliver・importers → catalog・store・kinds・config の一方向を保つ.下位から上位を import しない
  • バンドルの読み込みは目録に依存しない: bundle.py の読み込み側(load・open_bundle)は catalog・store・config を import しない(目録の無い計算サーバで使うため.書き出し側は別関数に分ける)
  • 公開 API は __init__.py で export したものだけ: 使う側は tiasdata.<名前> で使う.内部モジュールを直接 import させない
  • 取り込み元を増やすとき: importers/ にモジュールを追加し,設定ファイルの importer の名前から選べるようにする.既存の importer に分岐を足さない
  • 種類を増やすとき: src/tiasdata/catalog/migrations/catalog/ に kinds の行を追加する SQL と,kinds/ に値の型を追加する(SPEC_02「拡張の例」)
  • 副作用は縁に寄せる: ファイルのコピー・SSH・DB への書き込みは store・deliver・catalog に閉じ込め,定義の評価・manifest の行の組み立て・照合の判定は入力 → 出力の純関数として書く(テスト容易性のため)
  • データを置かない: 臨床データ・目録・対応表・バンドルをリポジトリの配下に置かない(.gitignore は保険.ENV_02「臨床データの取り扱い」)
  • テストの配置: tests/ は src/tiasdata/ の構造をミラーする(詳細は .claude/rules/testing.md)