diff --git a/CLAUDE.md b/CLAUDE.md index 4030e65..3d2fada 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -75,6 +75,8 @@ ### 03_PLAN（計画） +- 要件定義書: docs/03_PLAN/PLAN_01_要件定義書.md + ### 04_SPEC（仕様・設計） diff --git "a/docs/03_PLAN/PLAN_01_\350\246\201\344\273\266\345\256\232\347\276\251\346\233\270.md" "b/docs/03_PLAN/PLAN_01_\350\246\201\344\273\266\345\256\232\347\276\251\346\233\270.md" new file mode 100644 index 0000000..d939fe0 --- /dev/null +++ "b/docs/03_PLAN/PLAN_01_\350\246\201\344\273\266\345\256\232\347\276\251\346\233\270.md" @@ -0,0 +1,145 @@ +# 要件定義書 (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 枚（2026-09-27 確認） | `C:\Users\Papin\clinical-data\TIASJudgeModel\` | +| セグメンテーション用データ | ResUNet の開発時の画像と正解マスク | `C:\Users\Papin\clinical-data\TongueSegmentation\` | + +- 舌色データセットは DeepTIAS 2.7 の Image&Calib モードの出力（色補正後の画像を枠で切り出し，マスク外を黒にしたもの）から作られている（TIASJudgeModel の `SPEC_04`） +- ラベルは現在フォルダ名で表現されている．基盤に登録するときは，フォルダ名から読み取ったラベルを目録の項目として記録する + +### 表せるようにする関係 (Relationships) + +```text +症例（患者．研究用 ID） +└── 撮影（1 回の撮影．日時・撮影装置） + ├── 舌画像 + ├── カラーチャート画像 + ├── ラベル（舌色・程度．将来は別の所見も） + └── 派生データ（色補正後の画像・マスク・特徴量 analysis.csv 等） + └── 由来: 元データ・プログラム名・プログラムの版・作成日時 +``` + +- 現在は「1 患者 1 枚」だが，**同じ患者の複数回の撮影・複数枚**に対応する（経時的な撮影を含む） +- ラベルは 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 の `C:\Users\Papin\clinical-data\` 配下に置く．研究室 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（コピー．`main` にマージしたら `git push nakaguchi main` で反映する） + +## 成功基準 (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 の派生データも含めるか） | 開発計画 | + +### 人間が確認すること + +- 倫理審査で定められた臨床データの保管ルール（保管場所・アクセスできる人の範囲・保管期間・計算サーバへのコピーの可否）