データモデル (Data Model)

目録（catalog.sqlite）の表の定義．スキーマはパッケージ内の src/tiasdata/catalog/migrations/catalog/ の連番 SQL で管理し，適用済みの版を PRAGMA user_version に記録する（ENV_01）．対応表（identity.sqlite）は別の系列 migrations/identity/ で同様に管理する．外部キー制約を有効にする（PRAGMA foreign_keys = ON）．

スキーマで強制する規則 (Enforced by Schema)

以下は SQL の制約（CHECK・トリガ）で強制し，コードの誤りでも破れないようにする（2026-10-06 の判断）．

書式: 研究用 ID（S・C ＋ 6 桁），SHA-256（小文字 64 桁），拡張子，種類名・データセット名（英小文字で始まる snake_case），日時は UTC の YYYY-MM-DDTHH:MM:SSZ（秒まで．小数秒は拒否），撮影日は YYYY-MM-DD
主キー: ID・名前の主キーは NULL を許さない（SQLite は INTEGER 以外の主キーに NULL を入れられるため NOT NULL を明示する）
種類の整合: assets.kind はファイルの種類，annotations.kind は所見の種類だけを指せる．所見の種類は value_schema_version（1 以上）を必ず持ち，ファイルの種類は持たない
所見は書き換えない: annotations は UPDATE・DELETE を拒否する．例外は訂正のときに superseded_by を NULL から一度だけ埋めること（自分より後の行だけを指せる）．値は JSON として正しいこと
凍結した版は書き換えない: dataset_versions・dataset_members・dataset_member_annotations は UPDATE・DELETE を拒否する．そのため版の行は，manifest.csv の SHA-256 を計算してから INSERT する
対応表: 1 つの研究用 ID は 1 人の患者にだけ対応する（identity_map.subject_id は一意）

全体像 (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 にする
研究用 ID は番号順に振る．症例 S は目録と対応表の両方の最大番号 + 1 から，撮影 C は目録の最大番号 + 1 から（一度振った ID は変えない）
患者 ID は数字の値を先頭の 0 をそろえた文字列にする（123・123.0・"0123" は同じ患者．Excel の数値のセルは先頭の 0 がもともと落ちるため）
対応表 xlsx の読み方（2026-10-06 のユーザー判断）: シートは 1 枚に限る．1 行目は見出し．番号（1 列目）が整数でない行（空行を除く）は使わず，件数を報告する．使う番号について，対応表に無い・同じ番号の行が複数ある（患者 ID が同じでも）・患者 ID が数字でない場合は停止する．撮影にひも付けない番号（同じ中身ですべて要確認の番号）はこれらの確認の対象外．撮影にひも付く要確認の番号は対象
撮影の device は TIAS．所見の source は tiasjudgemodel_folder．由来は画像 1 枚につき 1 行で，出力の role は cropped

表の定義 (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` だけ，それ以外の 4 つは `strong` か `mild`（元のデータでも淡紅は「淡紅（正常）」だけ）．未知のキー・値は拒否する
`review`	`annotation`	要確認の印（2026-10-08．catalog/0002）．値は `{"reason": str, "resolve": str, "since": "YYYY-MM-DD", "numbers": [int, ...]}`（numbers は取り込み元での番号．1 個以上・昇順・重複なし）．source は `review_list`．撮影またはファイルに付く（SPEC_03「要確認リスト」）

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 度取り込むと，同じ行を指す（重複登録しない）．ただし別の撮影・別の種類・別の拡張子として登録しようとした場合は停止する（ストアでは拡張子が違うと別のファイルになるが，assets は SHA-256 で 1 行のため）
取り込み元で同じ中身が複数の番号にあり，すべて要確認の場合は，capture_id を NULL にしてファイルだけを登録し，所見はファイル（annotations.sha256）に付ける（患者が確定していないため．SPEC_03「要確認リスト」）

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（目録とは別のファイル・別のフォルダ）の identity_map 表．実際の患者 ID が分かるデータを取り込むときに使う（現在の舌色データも対象）．

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

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

拡張の例 (Extension Examples)

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