diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..be9f0ea --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,6 @@ +{ + "recommendations": [ + "Dart-Code.flutter", + "Dart-Code.dart-code" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..7aa9fdb --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,8 @@ +{ + "editor.formatOnSave": true, + "dart.flutterSdkPath": null, + "[dart]": { + "editor.defaultFormatter": "Dart-Code.dart-code", + "editor.rulers": [80] + } +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f432105 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,51 @@ +# プロジェクト名 + + + +## 開発進捗 + +現在の進捗: GUIDE_01 に従いプロジェクト立ち上げ中 +※ ステップ完了時にここを更新すること． + +## 必須ルール（コード実装時） + + + +### Git 運用（GUIDE_04 準拠） + +- ブランチ名: `feature/`/`fix/`/`docs/`/`chore/` + 英単語 2〜4 語（kebab-case） +- コミットメッセージ: `[add]`/`[update]`/`[fix]`/`[remove]`/`[clean]` + 日本語 +- コミット・push 後は `gh pr create` で PR を作成する + +### 手動確認が必要な作業（自分で完了させないこと） + +以下は実装完了後にユーザーへ報告し，確認・実施を依頼すること． + +- 外部サービスの設定（コンソール操作，セキュリティルール変更等） +- 実機・ブラウザでの動作確認 +- ストアへのアップロード・リリース作業 + +## ドキュメント + +設計・規約に関する情報は docs/ にある． +コードを書く前に関連するファイルを読むこと． + +### 01_GUIDE（規約・ルール） + +- プロジェクト立ち上げフロー: docs/01_GUIDE/GUIDE_01_プロジェクト立ち上げフロー.md +- ドキュメント作成規約: docs/01_GUIDE/GUIDE_02_ドキュメント作成ガイド.md +- ファイル命名規則: docs/01_GUIDE/GUIDE_03_ファイル命名規則.md +- Git 運用ルール: docs/01_GUIDE/GUIDE_04_Git運用ルール.md +- ※ コーディング規約，テスト方針等はプロジェクト立ち上げ時に作成する（GUIDE_01 参照） + +### 02_ENV（環境） + + + +### 03_PLAN（計画） + + + +### 04_SPEC（仕様・設計） + + diff --git a/DSC_0066.JPG b/DSC_0066.JPG new file mode 100644 index 0000000..d8a9c19 --- /dev/null +++ b/DSC_0066.JPG Binary files differ diff --git "a/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" new file mode 100644 index 0000000..f9aa80e --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" @@ -0,0 +1,113 @@ +# プロジェクト立ち上げフロー (Project Setup Flow) + +新規プロジェクトを AI と協働で立ち上げる際の手順を定義する． +各フェーズを順番に進め，成果物を確定させてから次のフェーズに移ること． + +## フェーズ一覧 (Phase Overview) + +| フェーズ | やること | 成果物 | +| -------- | ---------------------------------------------- | ---------------------------------------------------------- | +| 方針決定 | プロジェクトの目的・スコープを決める | `PLAN_01_要件定義書.md` | +| 技術選定 | 言語・フレームワーク・インフラを決める | `ENV_01_技術スタック.md` | +| 環境構築 | 開発環境のセットアップ手順を整備する | `ENV_02_環境構築手順.md`，`ENV_03_管理者用環境構築手順.md` | +| 仕様設計 | アーキテクチャ・データモデル・画面設計を決める | `SPEC_01_*.md` | +| 規約整備 | 技術スタックに応じたコーディング規約を作る | `GUIDE_*_*.md` | +| 開発計画 | ステップを分割し，開発順序を決める | `PLAN_02_開発ステップ.md` | +| 実装開始 | 開発計画に沿って実装を進める | ソースコード | + +## 方針決定 (Direction) + +プロジェクトの全体像を明確にする． + +- **人間が決めること**: プロジェクトの目的，対象ユーザー，スコープ（やること・やらないこと） +- **AI に依頼できること**: 要件の整理・構造化，類似プロジェクトの調査，要件定義書のドラフト作成 +- **成果物**: `PLAN_01_要件定義書.md` + +## 技術選定 (Tech Stack) + +要件に基づいて技術スタックを決定する． + +- **人間が決めること**: 最終的な技術選定の判断，チームのスキルセットとの適合性 +- **AI に依頼できること**: 要件に適した技術の候補提案，各候補のメリット・デメリット比較 +- **成果物**: `ENV_01_技術スタック.md` + +## 環境構築 (Environment Setup) + +開発環境を構築し，手順をドキュメント化する．初回のみの管理者作業と，メンバーが繰り返し行う構築手順を分けて整備する． + +- **前提条件**: 以下のツールは全プロジェクト共通で導入する． + - `git` — バージョン管理（[GUIDE_04](GUIDE_04_Git運用ルール.md) で運用ルールを定義） + - `gh` — GitHub CLI（PR 作成・マージ等に使用） +- **基本方針**: 環境の再現性を重視し，手順書だけに頼らず構築を自動化・コード化できる方法を優先する（例: Docker，Dev Containers，Windows Sandbox，IaC ツール等）． +- **人間が決めること**: 開発マシンの選定，クラウドサービスのアカウント作成，環境構築方法の選択 +- **AI に依頼できること**: 環境構築手順書の作成，設定ファイルの生成，`.gitignore` の作成，Dockerfile や devcontainer.json 等の構築用ファイルの作成 +- **成果物**: + - `ENV_02_環境構築手順.md` — メンバーの参加時や環境の再構築時に使う手順 + - `ENV_03_管理者用環境構築手順.md` — プロジェクト作成時に一度だけ行う初期設定（リポジトリ作成，外部サービスの設定等） + +## 仕様設計 (Specification) + +アプリケーションの設計を行う． + +- **人間が決めること**: ユーザー体験の方針，ビジネスロジックの最終判断 +- **AI に依頼できること**: アーキテクチャ設計のドラフト，データモデル定義，画面遷移図の整理 +- **成果物**: `SPEC_01_*.md`（プロジェクトの規模に応じて複数ファイルに分割） + +## 規約整備 (Coding Standards) + +技術スタックに応じたコーディング規約やプロジェクト固有のガイドを作成する． +汎用ガイド（GUIDE_01〜04）は本テンプレートに含まれている．ここではプロジェクト固有の規約を追加する． + +- **基本方針**: 言語・フレームワークの公式ガイドラインや広く採用されている標準規約に則る（例: Effective Dart，PEP 8，Google Style Guide 等）．プロジェクト固有のルールは標準と異なる部分のみ定義する． +- **人間が決めること**: 標準規約でカバーされない判断（アーキテクチャパターンの選択等） +- **AI に依頼できること**: 標準規約を踏まえた規約のドラフト作成，参照元ガイドラインの調査 +- **作成すべきガイド**: + - コーディング規約 — 命名規則，フォーマット，import 順序，型の使い方，コメントの書き方，コード内ドキュメントの規則 + - ディレクトリ構造規則 — プロジェクトのディレクトリ構成とファイル配置ルール + - テスト方針 — テストの種類，粒度，実行タイミング，カバレッジ基準 + - エラーハンドリング方針 — エラーの分類，処理方法，ログ出力の方針 + - リファクタリング方針 — リファクタリングの判断基準，実施タイミング + - 機能実装完了フロー — コミット前のチェックリスト（フォーマット，静的解析，テスト，レビュー等） + +## 開発計画 (Development Plan) + +実装の順序とステップを決定する． + +- **人間が決めること**: 優先度，リリース計画，マイルストーン +- **AI に依頼できること**: 仕様を元にしたステップ分割の提案，依存関係の整理 +- **成果物**: `PLAN_02_開発ステップ.md` + +## 実装開始 (Implementation) + +開発計画に沿って AI と協働で実装を進める． + +- 各ステップの完了時に [GUIDE_02_ドキュメント作成ガイド](GUIDE_02_ドキュメント作成ガイド.md) と [GUIDE_04_Git運用ルール](GUIDE_04_Git運用ルール.md) に従ってコミット・PR を作成する． +- 仕様変更が発生した場合は，先にドキュメントを更新してから実装に反映する． + +### ドキュメントの書き方 + +- コード内ドキュメント（JSDoc・コメント）と docs/ ドキュメントの書き方は [GUIDE_05_コーディング規約](GUIDE_05_コーディング規約.md) の「ドキュメント」セクションを参照 +- 仕様・設計の変更がある場合は `docs/` を先に更新してから実装に反映する + +## CLAUDE.md の管理 (CLAUDE.md Management) + +`CLAUDE.md` は AI が会話開始時に最初に読むファイルであり，プロジェクトの引継ぎ情報を一元管理する． +AI は毎回新しい会話で始まるため，このファイルが唯一の継続的な文脈となる． + +### 記載すべき内容 + +- **プロジェクト概要**: プロジェクト名，目的，技術スタックの要約 +- **開発進捗**: 現在のステップ，次にやること +- **必須ルール**: AI が実装時に必ず守るべきルール（コーディング規約，コミット前チェック等の要点） +- **ドキュメント一覧**: docs/ 内のファイルへの参照パス + +### 更新タイミング + +- ステップの完了時に開発進捗を更新する +- ドキュメントの追加・削除・リネーム時に参照パスを更新する +- 必須ルールに変更があった場合に反映する + +### 運用上の注意 + +- CLAUDE.md は AI が毎回読み込むため，簡潔に保つ．詳細は docs/ のドキュメントに委ね，CLAUDE.md には要点と参照先のみ記載する． +- プロジェクト固有のルールが増えたら，docs/ に独立ファイルとして切り出し，CLAUDE.md からはリンクで参照する． diff --git "a/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.md" "b/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.md" new file mode 100644 index 0000000..ed91906 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.md" @@ -0,0 +1,114 @@ +# ドキュメント作成ガイドライン (Documentation Style Guide) + +本ガイドはプロジェクト内のマークダウンドキュメントの書式を統一するためのルールを定める． +基本方針として [Google Markdown Style Guide](https://google.github.io/styleguide/docguide/style.html) および [markdownlint](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) のルールに準拠し，本ガイドで上書きする項目のみ以下に記載する． + +## 基本フォーマット (Basic Format) + +- 文字コード: UTF-8 +- 改行コード: LF（推奨）または CRLF +- ファイル拡張子: `.md` +- ファイル末尾: 空行を 1 行入れて終了する（MD047） + +## 句読点・約物 (Punctuation) + +- 句読点: 「，」（全角カンマ）と「．」（全角ピリオド）を使用する． + - 「、」「。」は使用しない． +- コロン: 半角コロン＋半角スペース「: 」を使用する． + - NG: 全角コロン「：」，スペースなし「:」 +- 括弧: 原則として半角 `( )` を使用する．強調や補足には全角 `（ ）` や `「 」` も許容する． +- 注釈: 補足には「※」（全角米印）＋半角スペースを使用する． + - 例: ※ shared は client/server 両方から import して使用する． + +## 見出し (Headings) + +ATX スタイル（`#`）を使用する．Setext スタイル（`===` / `---` の下線）は使用しない． + +- `#` の後に半角スペースを 1 つ入れる（MD018） +- 見出しの前後に空行を 1 行入れる（MD022） +- 見出しレベルは飛ばさない（MD001） + - NG: `#` の直下に `###` +- ドキュメント内の `#`（H1）は 1 つだけにする（MD025） +- 見出しには番号を付けない．マークダウンの見出し構造で階層を表現する． +- 見出しの書式: `タイトル (English Title)` + - 例: `## 基本設計 (Basic Design)` + +### 見出しレベルの対応表 + +| レベル | 記法 | 用途 | +| --- | --- | --- | +| H1 | `#` | ドキュメントタイトル（ファイルに 1 つ） | +| H2 | `##` | 大見出し（セクション） | +| H3 | `###` | 中見出し（サブセクション） | +| H4 | `####` | 小見出し（トピック） | + +## リスト (Lists) + +- 箇条書きには `- `（半角ハイフン＋半角スペース）を使用する（MD004） + - `*` `+` `・` は使用しない． +- ネストは 2 スペースでインデントする（MD007） +- 順序付きリストは `1.` の連番で記述する． +- リストの前後に空行を 1 行入れる（MD032） + +## 強調 (Emphasis) + +- 太字: `**テキスト**` を使用する．`__テキスト__` は使用しない（MD050） +- 斜体: `*テキスト*` を使用する．`_テキスト_` は使用しない（MD049） +- 太字斜体: `***テキスト***` を使用する． + +## コードブロック・インラインコード (Code) + +- コードブロックにはフェンス（` ``` `）を使用し，言語名を明記する（MD040） + + ````markdown + ```dart + final name = 'DxNavi'; + ``` + ```` + +- インラインコードにはバッククォート `` ` `` を使用する． + - 例: `build_runner` コマンドを実行する． +- コマンド例にはシェル言語を指定する． + + ````markdown + ```bash + dart run build_runner build --delete-conflicting-outputs + ``` + ```` + +## リンク・画像 (Links & Images) + +- リンク: `[テキスト](URL)` 形式を使用する． +- 画像: `![代替テキスト](パス)` 形式を使用し，代替テキストを必ず記述する（MD045） +- プロジェクト内リンクは相対パスを使用する． + +## テーブル (Tables) + +- ヘッダー行とセパレータ行を必ず含める． +- セル内は簡潔に記述し，長い場合はリンクや脚注で補足する． + +```markdown +| 項目 | 説明 | +| --- | --- | +| 名前 | 値 | +``` + +## 空行・余白 (Spacing) + +- 連続する空行は最大 1 行までとする（MD012） +- 見出し・リスト・コードブロックの前後に空行を 1 行入れる（MD022, MD031, MD032） +- 行末の不要な空白は削除する（MD009） + +## その他 (Miscellaneous) + +- HTML タグは原則使用しない．マークダウン記法で表現できない場合のみ許容する． +- 1 行の長さに厳密な上限は設けないが，可読性のために適度に改行する． +- ディレクトリ構造の表現にはコードブロック内でツリー記号（`├──`，`│`，`└──`）を使用する． + +```text +project/ +├── lib/ +│ ├── core/ +│ └── features/ +└── test/ +``` diff --git "a/docs/01_GUIDE/GUIDE_03_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.md" "b/docs/01_GUIDE/GUIDE_03_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.md" new file mode 100644 index 0000000..f9d43d2 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_03_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.md" @@ -0,0 +1,31 @@ +# ドキュメント管理・ファイル命名規則 (File Naming Conventions) + +## 命名の基本方針 (Basic Policy) + +プロジェクトの規模拡大に伴うファイルの散乱を防ぎ，開発メンバーおよび AI がファイルの内容・文脈を即座に特定できるようにするため，以下の規則を適用する． + +### 基本フォーマット + +`[カテゴリ]_[連番]_[ファイル名].md` + +- 区切り文字: アンダースコア `_` を使用する． +- 連番: 01 から始まる 2 桁の数字とする． +- 拡張子: マークダウン `.md` とする． + +## カテゴリ定義 (Category Definitions) + +ファイル名の先頭に付与するプレフィックス（接頭辞）定義． + +| カテゴリ | ディレクトリ | 内容 | 対象例 | +| --- | --- | --- | --- | +| `GUIDE_` | `01_GUIDE/` | ルール，規約，運用フロー | スタイルガイド，命名規則，Git 運用ルール | +| `ENV_` | `02_ENV/` | 開発環境，プロジェクトの土台 | 環境構築手順，技術スタック一覧，パッケージ構成図 | +| `PLAN_` | `03_PLAN/` | 進行計画，スケジュール，要件定義 | WBS，ロードマップ，要件定義書，タスク一覧 | +| `SPEC_` | `04_SPEC/` | ユーザーから見える仕様 | 企画書，画面遷移図，パラメータ設定 | +| `TECH_` | `05_TECH/` | エンジニア向けの技術設計 | 通信プロトコル仕様，データベース設計，クラス設計 | +| `TEST_` | `06_TEST/` | テスト計画，品質保証 | 単体テスト仕様書，シナリオテスト計画，品質基準 | + +## 運用ルール (Operational Rules) + +- 1 ファイル 1 テーマ: ファイルサイズが肥大化しすぎないよう，トピックごとにファイルを分割することを推奨する．これにより，AI へのコンテキスト入力精度が向上する． +- スタイルの継承: 新規作成するファイルも，必ず [GUIDE_02_ドキュメント作成ガイド](GUIDE_02_ドキュメント作成ガイド.md) に記載された書式に従うこと． diff --git "a/docs/01_GUIDE/GUIDE_04_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_04_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" new file mode 100644 index 0000000..3b79351 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_04_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" @@ -0,0 +1,181 @@ +# Git 運用ルール (Git Operation Rules) + +## 基本方針 (Basic Policy) + +チーム開発におけるコードの整合性を保ち，手戻りを防ぐために以下の運用フローを徹底する． + +- **メインブランチ (main)**: + - 本番環境または常に動作可能な状態を維持するブランチ． + - 直接のコミット（直プッシュ）は禁止する．必ずプルリクエスト（PR）経由でマージする． +- **作業ブランチ (Feature Branch)**: + - 機能追加やバグ修正ごとに `main` から派生させて作成する． + - 作業完了後，`main` へマージし，原則として削除する． +- **`.gitignore`**: + - リポジトリ作成時に必ず整備する． + - ビルド成果物，依存パッケージ（`node_modules/` 等），環境変数ファイル（`.env` 等）は必ず除外する． + - `git add .` を安全に使うための前提条件であるため，メンバー追加時にも確認する． + +## ブランチ命名規則 (Branch Naming) + +### プレフィックス (Prefix) + +作業の種類を一目で判別するために，以下のプレフィックスを使用する． + +| プレフィックス | 用途 | +| --- | --- | +| `feature/` | 新機能の実装，仕様変更 | +| `fix/` | バグ修正 | +| `refactor/` | コードの整理（挙動は変えない） | +| `docs/` | ドキュメントの追記・修正 | +| `chore/` | ビルド設定やツール導入など，雑多な作業 | + +### 書式 (Format) + +- 書式: `[プレフィックス][概要]` +- 区切り: スラッシュ `/` を使用する．概要内の単語区切りはハイフン `-` を使用する． +- 概要: 作業内容を端的に表す英単語 2〜4 語程度（小文字）とする． +- 例: + - `feature/player-jump` + - `fix/collision-bug` + - `docs/guide-update` + +## 開発フロー (Development Workflow) + +作業を開始してからマージされるまでの手順． + +### ローカルの最新化 + +作業開始前は必ず `main` ブランチに切り替え，リモートの最新状態を取り込む． + +```bash +git checkout main +git pull origin main +``` + +### 作業ブランチの作成 + +最新の `main` から新しいブランチを作成して移動する． + +```bash +git checkout -b feature/new-function +``` + +### 実装とコミット + +- 作業単位（意味のあるまとまり）ごとにコミットする． +- 巨大なコミットは避け，レビューしやすい粒度を心がける． +- AI によるコミットメッセージの生成機能を利用してもよい．ただし，生成されたメッセージは必ず「コミットメッセージ」セクションの書式ルールに合わせて修正すること． + +```bash +git add . +git commit -m "[add] 新機能を実装" +``` + +### リモートへのプッシュ + +作業ブランチをリモートリポジトリへ送信する． + +```bash +git push origin feature/new-function +``` + +### プルリクエスト (PR) の作成 + +GitHub CLI (`gh`) を使用して PR を作成する． + +```bash +gh pr create --title "[add] 新機能を実装" --body "概要" +``` + +- `--title` はコミットメッセージと同じ書式（`[タグ] 内容`）とする． +- 必要に応じて `--reviewer` でレビュワーを指定する． + +### レビューと修正の対応 + +- レビュワーのコメントを確認し，修正が必要な場合はローカルで修正・コミット・プッシュを繰り返す． +- 全ての指摘に対応し，レビュワーから Approve をもらう． + +### マージの実行 + +- マージ方式は「Create a merge commit」を使用する（作業ブランチの全コミット履歴が `main` に残る）． + - 「Squash and merge」「Rebase and merge」は使用しない． + +```bash +gh pr merge --merge --delete-branch +``` + +### ローカル環境のクリーンアップ + +マージ完了後はローカル環境も最新状態に戻し，古いブランチを削除する． + +```bash +git checkout main +git pull origin main +git branch -d feature/new-function +``` + +## コミットメッセージ (Commit Messages) + +### 書式 + +- 書式: `[タグ] 内容` +- 言語: 日本語 +- 句読点: 末尾に句点は不要 + +### タグ一覧 + +| タグ | 用途 | +| --- | --- | +| `[add]` | ファイルや機能の追加 | +| `[update]` | 機能やデータの更新・修正 | +| `[fix]` | バグ修正 | +| `[remove]` | 削除 | +| `[clean]` | 整理，リファクタリング | + +## トラブルシューティング (Troubleshooting) + +### コンフリクトが発生した場合 + +他メンバーの変更と競合した場合の対処手順． + +**main の取り込み** + +作業ブランチに `main` の最新内容をリベースして競合箇所を洗い出す．`merge` ではなく `rebase` を使うことで，履歴が線形に保たれレビューしやすくなる． + +```bash +git checkout main +git pull origin main +git checkout feature/new-function +git rebase main +``` + +**競合の解消** + +エディタ上で `<<<<<<<`，`=======`，`>>>>>>>` で囲まれた箇所を手動で修正する．修正後，以下のコマンドでリベースを続行する． + +```bash +git add [修正したファイル] +git rebase --continue +``` + +全ての競合が解消されたらプッシュする．リベース後は履歴が書き換わるため `-f` オプションが必要になる． + +```bash +git push -f origin feature/new-function +``` + +### 間違えて main にコミットしてしまった場合 + +**まだプッシュしていない場合** + +コミットを取り消し，変更内容を保持したまま新しいブランチへ移動する． + +```bash +git reset --soft HEAD^ +git checkout -b feature/new-function +git commit -m "[add] ..." +``` + +**すでにプッシュしてしまった場合** + +`main` への force push はチーム全員の履歴を壊す危険があるため，自分では対処しない．直ちにチームメンバーに報告し，全員で対応方針を決める． diff --git "a/docs/02_ENV/ENV_01_\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.md" "b/docs/02_ENV/ENV_01_\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.md" new file mode 100644 index 0000000..b8fffdc --- /dev/null +++ "b/docs/02_ENV/ENV_01_\346\212\200\350\241\223\343\202\271\343\202\277\343\203\203\343\202\257.md" @@ -0,0 +1,106 @@ +# 技術スタック (Tech Stack) + +## 概要 (Overview) + +MiniTIAS は Flutter を用いたクロスプラットフォームモバイルアプリケーションである．初期段階では Android のみを対象とし，将来的に iOS 等への展開を視野に入れる． + +## 試験端末 (Test Device) + +| 項目 | 値 | +| --- | --- | +| 端末名 | AQUOS sense3（SH-02M） | +| OS | Android 9 Pie（Android 10 にアップデート可能） | +| インカメラ | 800 万画素 | +| RAM / ROM | 4GB / 64GB | + +## フレームワーク・言語 (Framework & Language) + +| 要素 | 選定 | 理由 | +| --- | --- | --- | +| フレームワーク | Flutter（最新 stable） | 将来的なクロスプラットフォーム対応のため | +| 言語 | Dart | Flutter の標準言語 | +| 対象 OS | Android | 試験端末が Android のため．初期は Android のみ | +| minSdkVersion | 21（Android 5.0） | Flutter のデフォルト．AQUOS sense3（API 28）で問題なし | + +## 主要パッケージ (Key Packages) + +| パッケージ | 用途 | 備考 | +| --- | --- | --- | +| `camera` | インカメラのライブプレビュー・撮影 | Flutter 公式プラグイン | +| `image` | 撮影画像の PNG エンコード | JPEG → PNG 変換に使用 | +| `path_provider` | アプリ内ファイルパスの取得 | 保存先ディレクトリの参照に使用 | +| `permission_handler` | カメラ・ストレージの権限管理 | Android の実行時権限リクエスト | +| `provider` | 状態管理 | Flutter 公式推奨．シンプルかつ拡張しやすい | + +※ パッケージバージョンは環境構築時に最新 stable を採用し，`pubspec.yaml` で管理する． + +### 共有ストレージ保存 (Shared Storage) + +画像の保存先は `Pictures/MiniTIAS/`（Android 共有ストレージ）とする．Android 10 以降の Scoped Storage 制約により，`path_provider` では共有ストレージに直接書き込めない．保存方法は以下のいずれかを環境構築時に検証・確定する． + +- `saver_gallery` 等の既存パッケージを利用 +- Platform Channels で Android の MediaStore API を直接呼び出し + +### 状態管理 (State Management) + +`provider` パッケージを使用する．画面数が少なくシンプルな構成のため，大規模な状態管理ライブラリは導入しない． + +### 静的解析 (Static Analysis) + +Dart 標準のリンター（`analysis_options.yaml`）を使用する．Flutter プロジェクト作成時に生成されるデフォルト設定をベースとし，プロジェクト固有のルール追加は規約整備フェーズで定義する． + +## 役割分担 (Role Distribution) + +| 処理 | 実行場所 | 備考 | +| --- | --- | --- | +| 撮影・ライブプレビュー | スマホ（Flutter アプリ） | インカメラ使用 | +| 画像保存（PNG） | スマホ（Flutter アプリ） | 共有ストレージに保存 | +| データ転送 | USB 接続 | PC からフォルダを直接参照 | +| キャリブレーション | PC | カラーバーを用いた色補正 | +| 色変換・解析 | PC | L\*a\*b\* 変換，色差計算等 | + +## 開発環境 (Development Environment) + +| 要素 | 選定 | 備考 | +| --- | --- | --- | +| IDE | VS Code | Flutter / Dart 拡張機能を使用 | +| Flutter SDK | 最新 stable | Dart SDK 同梱 | +| Android SDK | Android Studio 経由で導入 | ビルドツール・エミュレータを含む | +| JDK | Flutter 推奨バージョン | Android ビルドに必要 | +| ADB | Android SDK 同梱 | USB 経由の実機デバッグに使用 | +| バージョン管理 | Git + GitHub | `gh` CLI で PR 管理 | +| CI/CD | 初期段階では導入しない | — | + +### VS Code 拡張機能 (VS Code Extensions) + +| 拡張機能 | 用途 | +| --- | --- | +| Flutter | Flutter 開発統合（ビルド，デバッグ，ホットリロード等） | +| Dart | Dart 言語サポート（補完，解析，フォーマット等） | + +### 環境の再現性 (Environment Reproducibility) + +別の PC への移行を容易にするため，以下の方針で環境をコード化する． + +**リポジトリで Git 管理するもの:** + +| ファイル | 役割 | +| --- | --- | +| `pubspec.yaml` | Dart パッケージとバージョンの管理 | +| `.vscode/extensions.json` | 推奨 VS Code 拡張機能の定義 | +| `.vscode/settings.json` | プロジェクト固有の VS Code 設定 | + +**SDK のインストール自動化:** + +- Windows パッケージマネージャー（Scoop）を使用し，セットアップスクリプトで SDK 類を一括インストールする +- 対象: Flutter SDK，Android Studio，Git，GitHub CLI 等 +- スクリプトはリポジトリに含め，`ENV_02_環境構築手順.md` で手順を説明する + +**環境セットアップの流れ:** + +1. `git clone` でリポジトリを取得 +2. セットアップスクリプトを実行（SDK 一括インストール） +3. `flutter doctor` で環境の過不足を確認 +4. VS Code が推奨拡張機能のインストールを提案 + +※ 詳細な環境構築手順は `ENV_02_環境構築手順.md` に記載する． diff --git "a/docs/02_ENV/ENV_02_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" "b/docs/02_ENV/ENV_02_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" new file mode 100644 index 0000000..edaa94c --- /dev/null +++ "b/docs/02_ENV/ENV_02_\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" @@ -0,0 +1,156 @@ +# 環境構築手順 (Environment Setup Guide) + +新しい PC で開発環境を構築する際の手順．メンバーの参加時や環境の再構築時に使用する． + +## 前提条件 (Prerequisites) + +- OS: Windows 10 以降 +- インターネット接続 +- GitHub アカウント（リポジトリへのアクセス権があること） + +## 手順 (Steps) + +### Scoop のインストール (Install Scoop) + +PowerShell を開き，以下を実行する． + +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser +Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression +``` + +インストール後，ターミナルを再起動して以下で確認する． + +```bash +scoop --version +``` + +### リポジトリの取得 (Clone Repository) + +```bash +git clone https://github.com//MiniTIAS.git +cd MiniTIAS +``` + +※ Git が未インストールの場合は `scoop install git` を先に実行する． +※ リポジトリの URL は管理者に確認すること． + +### セットアップスクリプトの実行 (Run Setup Script) + +リポジトリに含まれるセットアップスクリプトを実行し，必要なツールを一括インストールする． + +```powershell +.\scripts\setup.ps1 +``` + +以下が自動的にインストールされる． + +- Flutter SDK（Dart SDK 同梱） +- Android Studio +- GitHub CLI（`gh`） + +### Android Studio の初期設定 (Android Studio Initial Setup) + +Android Studio を一度起動し，セットアップウィザードを完了させる．以下が自動的にインストールされる． + +- Android SDK +- Android SDK Command-line Tools +- Android SDK Build-Tools +- JDK（Android Studio に同梱） + +**手順:** + +1. Android Studio を起動する +2. セットアップウィザードで「Standard」を選択する +3. ライセンスに同意し，ダウンロードを完了させる +4. セットアップ完了後，Android Studio は閉じてよい（エディタとしては VS Code を使用する） + +### Flutter の設定 (Configure Flutter) + +Flutter が Android SDK を認識できるように設定する． + +```bash +flutter doctor --android-licenses +``` + +表示されるライセンスにすべて同意する（`y` を入力）． + +### 環境の確認 (Verify Environment) + +以下のコマンドで環境の過不足を確認する． + +```bash +flutter doctor +``` + +すべての項目にチェック（✓）が付いていれば OK．問題がある項目は表示されるガイドに従って対処する． + +### GitHub CLI の認証 (Authenticate GitHub CLI) + +```bash +gh auth login +``` + +対話形式で GitHub アカウントにログインする．PR の作成・管理に使用する． + +### VS Code のセットアップ (VS Code Setup) + +1. VS Code でプロジェクトフォルダを開く +2. 推奨拡張機能のインストール通知が表示されるので，すべてインストールする + - Flutter + - Dart + +※ 推奨拡張機能は `.vscode/extensions.json` で定義されている． + +### 実機デバッグの準備 (USB Debugging Setup) + +AQUOS sense3（または他の Android 端末）を USB デバッグできるようにする． + +**スマートフォン側の設定:** + +1. 「設定」→「デバイス情報」を開く +2. 「ビルド番号」を 7 回タップする → 「開発者になりました」と表示される +3. 「設定」→「開発者向けオプション」を開く +4. 「USB デバッグ」を ON にする + +**PC との接続:** + +1. USB ケーブルでスマートフォンと PC を接続する +2. スマートフォンに「USB デバッグを許可しますか？」と表示されたら「許可」をタップする +3. 以下のコマンドで接続を確認する + +```bash +flutter devices +``` + +接続した端末名が表示されれば OK． + +### アプリの実行確認 (Run App) + +```bash +flutter run +``` + +実機にアプリがインストールされ，起動すれば環境構築は完了． + +## トラブルシューティング (Troubleshooting) + +### `flutter doctor` で Android SDK が見つからない場合 + +Android SDK のパスを手動で設定する． + +```bash +flutter config --android-sdk +``` + +Scoop 経由でインストールした場合，Android SDK は通常以下にある． + +```text +%LOCALAPPDATA%\Android\Sdk +``` + +### ADB で端末が認識されない場合 + +- USB ケーブルが「データ転送対応」であることを確認する（充電専用ケーブルでは認識されない） +- スマートフォンの USB 接続モードが「ファイル転送（MTP）」になっていることを確認する +- 端末のメーカー固有の USB ドライバが必要な場合がある（AQUOS の場合は SHARP 公式サイトからダウンロード） diff --git "a/docs/02_ENV/ENV_03_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" "b/docs/02_ENV/ENV_03_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" new file mode 100644 index 0000000..8c952f4 --- /dev/null +++ "b/docs/02_ENV/ENV_03_\347\256\241\347\220\206\350\200\205\347\224\250\347\222\260\345\242\203\346\247\213\347\257\211\346\211\213\351\240\206.md" @@ -0,0 +1,126 @@ +# 管理者用環境構築手順 (Admin Setup Guide) + +プロジェクト作成時に一度だけ行う初期設定．管理者が実施する． + +## GitHub リポジトリの作成 (Create GitHub Repository) + +```bash +gh repo create MiniTIAS --private +``` + +※ GitHub CLI（`gh`）が未認証の場合は `gh auth login` を先に実行する． + +## セットアップスクリプトの作成 (Create Setup Script) + +メンバーが環境を構築する際に使用するスクリプトを作成し，リポジトリに含める． + +### ディレクトリ構成 + +```text +MiniTIAS/ +├── scripts/ +│ └── setup.ps1 +``` + +### `scripts/setup.ps1` の内容 + +```powershell +# MiniTIAS 開発環境セットアップスクリプト +# 使用方法: .\scripts\setup.ps1 + +Write-Host "=== MiniTIAS Setup ===" -ForegroundColor Cyan + +# Scoop の確認 +if (-not (Get-Command scoop -ErrorAction SilentlyContinue)) { + Write-Host "[ERROR] Scoop がインストールされていません．" -ForegroundColor Red + Write-Host "以下を実行してください:" -ForegroundColor Yellow + Write-Host " Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser" + Write-Host " Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression" + exit 1 +} + +# extras バケットの追加 +Write-Host "[1/4] Scoop extras バケットを追加..." -ForegroundColor Green +scoop bucket add extras 2>$null + +# Flutter SDK +Write-Host "[2/4] Flutter SDK をインストール..." -ForegroundColor Green +scoop install flutter + +# Android Studio +Write-Host "[3/4] Android Studio をインストール..." -ForegroundColor Green +scoop install extras/android-studio + +# GitHub CLI +Write-Host "[4/4] GitHub CLI をインストール..." -ForegroundColor Green +scoop install gh + +Write-Host "" +Write-Host "=== インストール完了 ===" -ForegroundColor Cyan +Write-Host "" +Write-Host "次の手順:" -ForegroundColor Yellow +Write-Host " 1. Android Studio を起動してセットアップウィザードを完了する" +Write-Host " 2. flutter doctor --android-licenses を実行する" +Write-Host " 3. flutter doctor で環境を確認する" +Write-Host " 4. gh auth login で GitHub にログインする" +Write-Host "" +Write-Host "詳細は docs/02_ENV/ENV_02_環境構築手順.md を参照してください．" +``` + +## VS Code 設定ファイルの作成 (Create VS Code Config) + +### `.vscode/extensions.json` + +推奨拡張機能を定義する． + +```json +{ + "recommendations": [ + "Dart-Code.flutter", + "Dart-Code.dart-code" + ] +} +``` + +### `.vscode/settings.json` + +プロジェクト固有の設定を定義する． + +```json +{ + "editor.formatOnSave": true, + "dart.flutterSdkPath": null, + "[dart]": { + "editor.defaultFormatter": "Dart-Code.dart-code", + "editor.rulers": [80] + } +} +``` + +## `.gitignore` の作成 (Create .gitignore) + +Flutter プロジェクト作成時（`flutter create`）に自動生成されるが，必要に応じて以下を追加する． + +- `.env` — 環境変数（機密情報） +- `*.jks` — Android 署名キー + +## Flutter プロジェクトの作成 (Create Flutter Project) + +```bash +flutter create --org com.example mini_tias +``` + +※ パッケージ名・組織名は正式に決定してから実行する． + +## チェックリスト (Checklist) + +管理者は以下をすべて完了させてからメンバーに展開する． + +- [ ] GitHub リポジトリの作成（private） +- [ ] `scripts/setup.ps1` の作成・動作確認 +- [ ] `.vscode/extensions.json` の作成 +- [ ] `.vscode/settings.json` の作成 +- [ ] `.gitignore` の確認 +- [ ] Flutter プロジェクトの作成（`flutter create`） +- [ ] 初回コミット・プッシュ +- [ ] メンバーにリポジトリへのアクセス権を付与 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..eff0204 --- /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,108 @@ +# 要件定義書 (Requirements Definition) + +## プロジェクト概要 (Project Overview) + +### プロジェクト名 + +MiniTIAS（ミニティアス） + +### 背景 (Background) + +千葉大学フロンティア医工学センター 中口俊哉教授の研究グループでは，舌画像撮影・解析システム TIAS（Tongue Image Analyzing System）を用いた舌診の客観化研究を行っている．既存の TIAS は積分球を用いた大型装置であり，社会への広い普及が困難である． + +### 目的 (Objective) + +TIAS のスマートフォン版（MiniTIAS）を開発し，舌画像撮影の小型化・簡便化を実現する．研究の初期段階として，既存 TIAS と MiniTIAS で同一対象を撮影し，画像品質の差を定量的に検証する．その結果をもとに差を埋める改善を行う． + +### 対象ユーザー (Target Users) + +研究メンバー（初期段階） + +### 位置づけ (Positioning) + +研究をスムーズに進めるための援助用ソフトウェア．画像の解析・キャリブレーションは PC 側で行い，スマホアプリは撮影・保存に特化する． + +## スコープ (Scope) + +### やること (In Scope) + +- スマートフォンのインカメラを用いた舌画像の撮影 +- 撮影画像の PNG（非圧縮）保存 +- 撮影済み画像の一覧表示・確認・削除 +- USB 経由で PC へのデータ転送を前提としたファイル管理 + +### やらないこと (Out of Scope) + +- 画像のキャリブレーション（PC 側で実施） +- 色変換・解析（L\*a\*b\* 変換等，PC 側で実施） +- AR マーカー検出（将来対応） +- サーバー連携・クラウドストレージ +- 一般ユーザー向け UI/UX + +## 撮影システム構成 (System Configuration) + +### ハードウェア + +| 要素 | 内容 | +| --- | --- | +| スマートフォン | AQUOS sense3（試験端末） | +| カメラ | インカメラ（フロントカメラ） | +| アタッチメント | 専用小型ケース（SmTIAS） | +| 照明 | LED ライト | +| キャリブレーション | 4 つの AR マーカー + カラーバー（PC 側で処理） | + +### 撮影方法 + +- スマートフォンを**逆さ**にしてアタッチメントの上に置く +- インカメラが下を向き，アタッチメント内の対象物（舌模型・白板等）を撮影する +- 画面が上を向くため，撮影者はプレビューを見ながら操作できる + +### 初期検証の対象物 + +- **白板** — 照明の均一性を評価するため +- **舌模型** — 色再現性を評価するため + +※ 被験者の舌ではなく，模型と白板を使って既存 TIAS との比較検証を行う． + +## ソフトウェア要件 (Software Requirements) + +### 技術スタック + +| 要素 | 選定 | +| --- | --- | +| フレームワーク | Flutter | +| 対象 OS | Android | +| 開発言語 | Dart | + +※ 将来的には端末に依存しないクロスプラットフォーム対応を目指す． + +### 画面構成 (Screen Layout) + +#### 撮影画面 (Capture Screen) + +- インカメラの**ライブプレビュー**を表示する +- 画面の向きを固定し，**UI を上下反転表示**する（スマホを逆さに置いた状態で撮影者から正しく見えるようにする） +- シャッターボタンをタップして撮影する +- 撮影後はライブプレビューに戻り，**連続撮影が可能**（確認画面への遷移なし） + +#### 一覧画面 (Gallery Screen) + +- 撮影済み画像を**サムネイル一覧**で表示する +- 画像を選択して**拡大確認**できる +- 不要な画像を**削除**できる + +### ファイル管理 (File Management) + +| 項目 | 仕様 | +| --- | --- | +| 保存形式 | PNG（非圧縮） | +| 保存先 | `Pictures/MiniTIAS/` （共有ストレージ） | +| ファイル名形式 | `MiniTIAS_YYYYMMDD_HHmmss.png` | +| 同秒重複時 | `MiniTIAS_YYYYMMDD_HHmmss_1.png`，`_2.png` ... と連番を付与 | +| データ転送 | USB 接続で PC からフォルダを直接参照・コピー | + +### 将来的な拡張 (Future Enhancements) + +- タイマー撮影機能 +- AR マーカー検出（撮影時のリアルタイムバリデーション） +- 端末非依存のクロスプラットフォーム対応 diff --git a/scripts/setup.ps1 b/scripts/setup.ps1 new file mode 100644 index 0000000..5516a28 --- /dev/null +++ b/scripts/setup.ps1 @@ -0,0 +1,40 @@ +# MiniTIAS Development Environment Setup Script +# Usage: .\scripts\setup.ps1 + +Write-Host "=== MiniTIAS Setup ===" -ForegroundColor Cyan + +# Check Scoop +if (-not (Get-Command scoop -ErrorAction SilentlyContinue)) { + Write-Host "[ERROR] Scoop is not installed." -ForegroundColor Red + Write-Host "Run the following commands:" -ForegroundColor Yellow + Write-Host " Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser" + Write-Host " Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression" + exit 1 +} + +# Add extras bucket +Write-Host "[1/4] Adding Scoop extras bucket..." -ForegroundColor Green +scoop bucket add extras 2>$null + +# Flutter SDK +Write-Host "[2/4] Installing Flutter SDK..." -ForegroundColor Green +scoop install flutter + +# Android Studio +Write-Host "[3/4] Installing Android Studio..." -ForegroundColor Green +scoop install extras/android-studio + +# GitHub CLI +Write-Host "[4/4] Installing GitHub CLI..." -ForegroundColor Green +scoop install gh + +Write-Host "" +Write-Host "=== Setup Complete ===" -ForegroundColor Cyan +Write-Host "" +Write-Host "Next steps:" -ForegroundColor Yellow +Write-Host " 1. Launch Android Studio and complete the setup wizard" +Write-Host " 2. Run: flutter doctor --android-licenses" +Write-Host " 3. Run: flutter doctor" +Write-Host " 4. Run: gh auth login" +Write-Host "" +Write-Host "See docs/02_ENV/ENV_02 for details."