データモデル (Data Model)

目録（catalog.sqlite）の表の定義．スキーマは migrations/ の連番 SQL で管理し，適用済みの版を PRAGMA user_version に記録する（ENV_01）．外部キー制約を有効にする（PRAGMA foreign_keys = ON）．

全体像 (Overview)

subjects（症例）
└── captures（撮影）
    ├── assets（ファイル．舌画像・カラーチャート画像・派生データ）
    │     ▲ derivation_outputs ── derivations（由来: プログラム・版）── derivation_inputs ▶ assets
    └── annotations（所見．舌色等．撮影またはファイルに付く）

datasets ── dataset_versions ── dataset_members（ファイル）── dataset_member_annotations（所見）
                              └── deliveries（受け渡しの記録）

kinds（ファイルの種類・所見の種類の定義）

ID の書式 (Identifiers)

対象	書式	例
症例（研究用 ID）	`S` ＋ 6 桁の連番	`S000123`
撮影	`C` ＋ 6 桁の連番	`C000456`
ファイル	中身の SHA-256（16 進 64 文字．小文字）	`3f9a…`
データセット	英小文字・数字・`_`（英小文字で始まる）	`tongue_color`
データセットの版	1 から始まる整数	`1`

研究用 ID は基盤が振る．実際の患者 ID・カルテ番号は目録に入れない（対応表 identity.sqlite にだけ置く）
現在の舌色データは 1 患者 1 枚ではない（PLAN_01「現在あるデータ」）．取り込みでは研究室 PC の対応表の xlsx（画像の番号 → 患者 ID・何枚目）を読み，患者 ID ごとに症例を 1 つ，画像 1 枚ごとに撮影を 1 つ作る．患者 ID は対応表 identity.sqlite にだけ入れる
同じ患者の複数枚が同じ日の撮影か別の日の撮影かは，現在のデータからは分からないため，撮影日（captured_on）は NULL にする

表の定義 (Tables)

kinds（種類の定義）

ファイルの種類と所見の種類を 1 つの表で管理する．種類の追加はこの表への行の追加と，src/tiasdata/kinds/ への検証用の型の追加で行う．

列	型	内容
`kind`	TEXT PK	種類名（例: `tongue_crop_masked`・`tongue_color`）
`category`	TEXT	`asset`（ファイル）または `annotation`（所見）
`description`	TEXT	説明
`value_schema_version`	INTEGER	所見の値の型の版（`annotation` のみ．値の形を変えたら上げる）

最初に用意する種類:

`kind`	`category`	内容
`tongue_raw`	`asset`	撮影した舌画像（補正前）
`color_chart`	`asset`	カラーチャート画像
`tongue_crop_masked`	`asset`	色補正後の画像を舌の枠で切り出し，マスク外を黒 (0,0,0) にしたもの（DeepTIAS Image&Calib の `2-cropped` × `3-resized`．現在の舌色データ）
`tongue_mask`	`asset`	舌のマスク画像
`tongue_color`	`annotation`	舌色 5 分類＋程度．値は `{"label": <slug>, "severity": "strong" \\| "mild" \\| "normal"}`．slug は `pale`・`light_red`・`red`・`dark_red`・`purple`（TIASJudgeModel の SPEC_01「クラス定義」と同じ）．`light_red` のときだけ `normal`

subjects（症例）

列	型	内容
`subject_id`	TEXT PK	研究用 ID
`created_at`	TEXT	登録日時（ISO 8601）
`note`	TEXT	備考

captures（撮影）

列	型	内容
`capture_id`	TEXT PK	撮影 ID
`subject_id`	TEXT FK	症例
`captured_on`	TEXT NULL	撮影日（日付まで．不明なら NULL．現在のデータは不明）
`device`	TEXT NULL	撮影装置（例: `TIAS`）
`note`	TEXT	備考

assets（ファイル）

列	型	内容
`sha256`	TEXT PK	中身の SHA-256
`kind`	TEXT FK	ファイルの種類（`kinds.category = 'asset'`）
`capture_id`	TEXT FK NULL	撮影（撮影にひも付かないファイルは NULL）
`ext`	TEXT	拡張子（`png` 等．小文字）
`size_bytes`	INTEGER	サイズ
`source`	TEXT	取り込み元の名前（設定ファイルの `sources.<名前>`）
`source_name`	TEXT	取り込み元での相対パス（現在のデータのファイル名は個人をたどれる情報を含まないことを 2026-10-02 にユーザーが確認）
`registered_at`	TEXT	登録日時

ストア上のパスは store/<sha256 の先頭 2 文字>/<sha256>.<ext> で決まるため，目録には保存しない
同じ中身のファイルを 2 度取り込むと，同じ行を指す（重複登録しない）．ただし別の撮影・別の種類として登録しようとした場合は停止する

derivations・derivation_inputs・derivation_outputs（由来）

派生データを「どのファイルから，どのプログラムのどの版で」作ったかを記録する．

表	列	内容
`derivations`	`derivation_id` INTEGER PK	—
	`tool`	プログラム名（例: `DeepTIAS`）
	`tool_version`	プログラムの版（例: `2021-12-exe`・`2.7.1`・git のコミット）．不明なら `unknown`
	`mode`	実行モード・設定（例: `Image&Calib`．JSON で詳細を持ってよい）
	`performed_at`	実行日時（不明なら NULL）
	`note`	備考
`derivation_inputs`	`derivation_id`・`sha256`・`role`	入力ファイルと役割（例: `tongue`・`chart`）
`derivation_outputs`	`derivation_id`・`sha256`・`role`	出力ファイルと役割（例: `cropped`・`mask`・`analysis`）

同じ入力から版の違うプログラムで作った出力は，別の derivations 行になる（DeepTIAS の旧 exe と現行ソースの結果を区別できる）
現在の舌色データ（tongue_crop_masked）は元の撮影画像が基盤に無いため，入力なし・tool = 'DeepTIAS'・tool_version = 'unknown'・mode = 'Image&Calib' の由来を付けて登録する（TIASJudgeModel の SPEC_04 の確認結果を note に書く）

annotations（所見）

列	型	内容
`annotation_id`	INTEGER PK	—
`kind`	TEXT FK	所見の種類（`kinds.category = 'annotation'`）
`capture_id`	TEXT FK NULL	撮影に付く所見の場合
`sha256`	TEXT FK NULL	ファイルに付く所見の場合（`capture_id` とどちらか一方だけ）
`value`	TEXT	値（JSON．`kinds/` の型で検証してから保存する）
`annotator`	TEXT NULL	評価者（研究用の記号．個人名は入れない）
`source`	TEXT	由来（例: `tiasjudgemodel_folder`＝フォルダ名から読み取った）
`created_at`	TEXT	登録日時
`superseded_by`	INTEGER NULL	訂正したときの新しい行

所見の行は書き換えない．訂正は新しい行を追加し，古い行の superseded_by を埋める（過去の版が古い行を参照し続けられるようにするため）
現在の舌色ラベルは撮影に付ける（医師が撮影を見て付けたラベルのため）

datasets・dataset_versions・dataset_members・dataset_member_annotations（データセット）

表	列	内容
`datasets`	`name` TEXT PK・`description`・`created_at`	—
`dataset_versions`	`name`・`version`（PK は 2 列）	—
	`definition`	版を作ったときのデータセットの定義（TOML の内容をそのまま保存）
	`hub_commit`	版を作ったときの本リポジトリのコミット
	`manifest_sha256`	この版の `manifest.csv` の SHA-256（指紋）
	`created_at`・`note`	—
`dataset_members`	`name`・`version`・`sha256`	版に含まれるファイル
`dataset_member_annotations`	`name`・`version`・`sha256`・`annotation_id`	版を作った時点で採用した所見

版の行と，その版の構成の行は書き換え・削除しない（凍結）
版の作り方・manifest の形は SPEC_03

deliveries（受け渡しの記録）

計算サーバにコピーした作業用データと，データセットの版との対応を記録する．

列	内容
`delivery_id` INTEGER PK	—
`name`・`version`	渡したデータセットの版
`server`	受け渡し先（設定ファイルの `servers.<名前>`）
`path`	受け渡し先のパス（例: `~/data/tiasdata/tongue_color/v1`）
`delivered_at`	日時
`verified`	受け渡し先でハッシュを照合できたか

対応表 (Identity Map)

identity.sqlite（目録とは別のファイル・別のフォルダ）．実際の患者 ID が分かるデータを取り込むときに使う（現在の舌色データも対象）．

列	内容
`patient_key` TEXT PK	実際の患者 ID（取り込み元が持つもの）
`subject_id` TEXT	研究用 ID
`created_at`	—

同じ患者の別の撮影を取り込むと，同じ研究用 ID にひも付く（複数枚・経時的な撮影に対応する）
CLI は対応表の中身を表示しない．対応表を開くのは取り込みのときだけ
匿名化の方法・対応表の保管ルールは倫理審査の保管ルールを確認して確定する（PLAN_01「人間が確認すること」）

拡張の例 (Extension Examples)

追加したいもの	やること
苔の色・厚さ等の所見	`kinds` に行を追加し，`kinds/` に値の型を足す．マイグレーションは種類の行の追加だけ
問診・体質	撮影または症例に付く所見として同様に追加する（症例に付く所見が必要になったら `annotations` に `subject_id` 列を足す）
経時的な撮影	同じ症例に撮影を追加する（対応表で同じ研究用 ID にひも付ける）
別の撮影装置	`captures.device` に記録する．装置固有の情報が必要なら所見として持つ
DeepTIAS の解析結果	出力ファイルの種類（`tongue_mask`・`analysis_csv` 等）を足し，`derivations` で入力の撮影画像とひも付ける