# 要件定義書 (Requirements)

## プロジェクトの目的 (Purpose)

舌診研究のデータ（舌画像・ラベル・派生データ等）を研究室 PC でまとめて管理する**共有のデータ基盤**を作る．

舌診研究のデータを使うリポジトリは今後も増える．各リポジトリが個別に研究室 PC のフォルダを読む形をやめ，本リポジトリを**共通の入口**にする．各リポジトリは「データセット名」を指定してデータを取り出す．

- 現在あるデータは舌色の画像とラベル（5 分類＋程度）だけだが，今後ほかの種類のデータを増やす．**データの種類が増えても骨組みを作り直さずに済む**構造にする
- 置き場所・データ集合の版・派生データの由来を基盤側で管理し，各リポジトリの実験の**再現性**と**由来の追跡**を支える

## 対象ユーザー (Target Users)

| 区分 | 対象 |
| --- | --- |
| 直接 | 開発者本人（hasegawa）のみ |
| 使う側のリポジトリ | TIASJudgeModel（舌色分類モデルの学習），TIASjudge（舌色診断アプリ），DeepTIAS（舌画像の解析．C# WinForms），今後増えるもの |

- 研究室の他メンバーが使う予定は無い．**複数人での利用（同時編集・利用者ごとの権限管理等）は考慮しない**

## スコープ (Scope)

### やること (In Scope)

- **データの目録（カタログ）**: 症例・撮影・画像ファイル・ラベル・派生データと，それらの関係を記録する
- **データセットの定義と版**: 「データセット名」で取り出せるデータ集合を定義し，データを追加した後も過去と同じ集合を取り出せるようにする
- **由来（プロビナンス）の記録**: 派生データを「どの元データから，どのプログラムのどの版で」作ったかを記録する
- **アクセス用ライブラリ（Python）**: 使う側の Python プロジェクトが import して，データセット名から一覧・パスを取り出す
- **CLI**: データの登録・データセットの定義・manifest（CSV 等）の書き出し．Python 以外のプロジェクトや，目録に直接触れない計算サーバには書き出したファイルを渡す
- **置き場所の管理**: データの実際の置き場所は設定または目録で管理し，コードに書かない
- **ダミーデータ**: 臨床データの無い環境（手元 PC・CI）で，ライブラリ・CLI を同じコードパスで動かすための合成データ
- **手順書**: 研究室 PC での運用・データ登録・計算サーバへの受け渡しの手順

### やらないこと (Out of Scope)

- データ本体・実際の患者 ID と研究用 ID の対応表を本リポジトリに入れること（GitHub・研究室の GitBucket のどちらにも入れない）
- 機械学習の学習・評価（TIASJudgeModel 等，使う側の仕事）
- 画像処理そのもの（色補正・セグメンテーション・特徴量の計算．DeepTIAS 等の仕事．基盤はその**結果と由来を記録する**だけ）
- 臨床データを手元 PC に置くこと
- 研究室の外から目録・データに直接アクセスする仕組み（Web API・クラウドストレージ等）

## データ (Data)

### 現在あるデータ (Current Data)

| データ | 内容 | 原本の置き場所（研究室 PC） |
| --- | --- | --- |
| 舌色データセット | 舌領域を切り出した舌画像（PNG）．舌色 5 分類＋程度のラベルごとに 9 フォルダ・1085 枚．**1 患者 1 枚ではない**（約 450 人．2 枚以上の患者がいる．下記） | `E:\clinical-data\TIASJudgeModel\` |
| セグメンテーション用データ | ResUNet の開発時の画像と正解マスク | `E:\clinical-data\TongueSegmentation\` |
| 舌色データセットの DeepTIAS 出力 | 舌色データセットの各画像の元になった DeepTIAS の全工程の出力（`1-detection`〜`4-featureExtraction`．`analysis.csv` を含む）．番号ごとのフォルダ・1085 個．フォルダ名は番号だけで患者 ID を含まない | `E:\clinical-data\DeepTIAS_TIASJudgeModel\<番号>\` |

- 舌色データセットは DeepTIAS 2.7 の Image&Calib モードの出力（色補正後の画像を枠で切り出し，マスク外を黒にしたもの）から作られている（TIASJudgeModel の `SPEC_04`）
- ラベルは現在フォルダ名で表現されている．基盤に登録するときは，フォルダ名から読み取ったラベルを目録の項目として記録する
- 画像の番号（ファイル名）と，DeepTIAS の出力側の患者 ID・何枚目の画像かの対応は，研究室 PC の対応表（`E:\clinical-data\DeepTIAS後_ID_番号.xlsx`）にある．2026-10-03 に件数だけを照合し，1085 枚が約 450 人分（2 枚以上の患者が 239 人・874 枚）であることが分かった（TIASJudgeModel の「1 患者 1 枚」の前提は誤りで，ユーザーも確認済み）．患者単位で扱うには，この対応表を取り込みに使う必要がある
- DeepTIAS の出力（元は患者 ID のフォルダ `DeepTIAS後＿亥鼻＿村上_2025.08修正`）は，2026-10-03 に舌色データセットで使った画像の分だけを番号ごとのフォルダへ移し，残り（使わない出力 約 8GB）を削除した（元のデータは研究室のサーバにある）．各番号の画像は `2-cropped` × `3-resized`（127 超）で作り直したものと画素で一致する（完全一致 1073・違う画素 1% 未満 12）．経緯は `docs/PROGRESS.md`
- 舌色データセットには**同じ写真の重複**が 5 組ある（2026-10-03 確認）．ファイルが同一で対応表の患者 ID が違う 2 組（122/184・548/566．ラベルは同じ），ほぼ同じ画像（違う画素約 0.7%）が連番で 2 回登録された 3 組（381/382・508/509・515/516．うち 381/382 は程度，515/516 は舌色のラベルが違う）．382・509・516 のフォルダの DeepTIAS 出力は，それぞれ 381・508・515 の出力のコピー（元の出力は見つからなかった）．扱いは，確かめられるまで 9 枚を保留にする（2026-10-06．`holds/tiasjudgemodel.toml`・PLAN_02）

### 表せるようにする関係 (Relationships)

```text
症例（患者．研究用 ID）
└── 撮影（1 回の撮影．日時・撮影装置）
    ├── 舌画像
    ├── カラーチャート画像
    ├── ラベル（舌色・程度．将来は別の所見も）
    └── 派生データ（色補正後の画像・マスク・特徴量 analysis.csv 等）
         └── 由来: 元データ・プログラム名・プログラムの版・作成日時
```

- 現在のデータにも**同じ患者の複数枚**がある．複数回の撮影・経時的な撮影にも対応する
- ラベルは 1 つの撮影に複数付きうる（所見の種類が増える，評価者が複数いる等）

### 今後増やす候補 (Future Data Candidates)

いずれも**現時点では作り込まず**，追加時に骨組みを変えずに足せることだけを要件とする．

- 舌色以外の所見（苔の色・厚さ等）
- 問診・体質の情報
- 同じ患者の経時的な撮影
- 別の撮影装置で撮った画像
- DeepTIAS の解析結果（色補正後の画像・マスク・特徴量 `analysis.csv`）

## 基本方針 (Principles)

1. **置き場所をコードに書かない**: データの置き場所は設定または目録で管理し，使う側はデータセット名で指定する．置き場所を変えても 1 か所の変更で済む
2. **再現性**: データセットは版（スナップショット）を持ち，実験が「どのデータセットのどの版」を使ったかを記録・再取得できる．データを追加しても過去の版の中身は変わらない
3. **由来の記録**: 派生データには作成したプログラムとその版を必ず記録する．DeepTIAS は旧 exe（2021 年 12 月版）と現行ソースで解析結果がずれることが分かっているため，同じ元データの派生データを版ごとに区別して保持できるようにする
4. **個人情報をリポジトリに入れない**: リポジトリに置くのはスキーマ・ライブラリ・CLI・手順書・ダミーデータのみ
5. **拡張しやすさ**: データの種類（所見・派生データの種類）の追加は，目録の項目の追加で済み，既存のテーブル構造・コードの作り直しを要しない

## 使う側との連携 (Integration with Consumers)

| 使う側 | 連携の方法 |
| --- | --- |
| Python のプロジェクト（TIASJudgeModel・TIASjudge 等） | 本リポジトリを **git サブモジュール**（例: `external/TIASDataHub`）として置き，`[tool.uv.sources]` で**編集可能なパッケージ**として読み込む（例: `tiasdata = { path = "external/TIASDataHub", editable = true }`） |
| Python 以外（DeepTIAS 等） | CLI で書き出した manifest 等のファイルを読む |
| 目録に直接触れない場所（計算サーバ Newton・Archimedes） | 研究室 PC で CLI が書き出した manifest と，コピーしたデータを使う |

- 使う側の作業中に基盤側もその場で直せるよう，サブモジュールは編集可能な形で使う
- 複数のリポジトリから編集するため，基盤の変更は**本リポジトリの作業ブランチ → PR で `main` に入れる**．使う側のサブモジュールは**マージ済みのコミット**を指す
- 使う側から見たライブラリの API・manifest の列は**互換性を保つ**（変える場合は使う側への影響を手順書に書く）

## 制約 (Constraints)

### 個人情報・臨床データの扱い（必須）

- **データ本体と，実際の患者 ID ↔ 研究用 ID の対応表は本リポジトリに入れない**（GitHub・研究室の GitBucket のどちらにも）
- 原本は研究室 PC の `E:\clinical-data\` 配下に置く（内蔵 SSD．2026-10-06 に C ドライブから移した）．研究室 PC のドキュメントフォルダは OneDrive に同期されるため，その配下には置かない（目録の DB ファイルも同様）
- 学習は研究室の計算サーバ（Newton・Archimedes）で行い，**臨床データを手元 PC に置かない**．手元 PC ではダミーデータで開発する
- **Claude にデータの中身を読ませない**．データフォルダは `.claude/repo-access.json` の `deny_read` に入れる
- エラーメッセージ・ログ・CLI の出力に，実際の患者 ID・個人を特定できる情報を出さない
- 倫理審査で定められた保管ルールに合わせる（詳細は要確認．下記「未確定事項」）

### 運用環境 (Environment)

| 場所 | 役割 | 臨床データ |
| --- | --- | --- |
| 研究室 PC | 原本と目録を置く．登録・manifest の書き出しを行う | あり（原本） |
| 計算サーバ（Newton・Archimedes） | 学習・解析．研究室 PC から作業用コピーを受け取る | あり（作業用コピー） |
| 手元 PC | 開発．ダミーデータのみ | なし |

- リモート: `origin` = GitHub（`rintoHasegawa/TIASDataHub`，Private．メイン），`nakaguchi` = 研究室の GitBucket（コピー）

## 成功基準 (Success Criteria)

1. 現在の舌色データセット（1085 枚）が目録に登録され，データセット名で取り出せる
2. TIASJudgeModel が，研究室 PC の固定パスを書かずに本基盤経由で同じデータ集合（manifest）を得られる
3. データを追加した後も，過去の版のデータセットを同じ中身で取り出せる
4. 派生データに由来（元データ・プログラム・版）が記録され，同じ元データでも版の違う派生データを区別できる
5. 新しい種類の所見を 1 つ追加するとき，既存のスキーマ・コードを作り直さずに済む（ダミーデータで確認する）
6. 手元 PC ではダミーデータだけでライブラリ・CLI のテストが通る
7. リポジトリに個人情報・データ本体が含まれていない

## 前提・未確定事項 (Assumptions & Open Questions)

### 後のフェーズで一緒に決めること

| 事項 | 決めるフェーズ |
| --- | --- |
| データベースの形（SQLite ＋画像ファイル置き場，等） | 技術選定 |
| 研究用 ID の付け方（匿名化の方法）と，対応表の置き場所・管理方法 | 仕様設計 |
| データセットの版の表し方（スナップショットの単位・識別子） | 仕様設計 |
| 計算サーバにコピーした作業用データと原本・データセットの版の対応の管理方法 | 仕様設計 |
| manifest の形式・列（TIASJudgeModel の現行 manifest との互換） | 仕様設計 |
| 最初に対応するデータの種類（舌色のみか，セグメンテーション用データ・DeepTIAS の派生データも含めるか） | 開発計画 |

### 人間が確認すること

- 倫理審査で定められた臨床データの保管ルール（保管場所・アクセスできる人の範囲・保管期間・計算サーバへのコピーの可否）