Skip to content

Add root README.md #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add root README.md #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 88 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Flet Multiplatform Project Hub

## 概要

このリポジトリは、Fletフレームワークを使用したマルチプラットフォーム対応アプリケーションの開発基盤を提供するプロジェクトハブです。単一のコードベースからデスクトップ、ウェブ、モバイルアプリケーションを効率的に構築し、強力なPythonバックエンドAPI（FastAPIを利用）と連携させることを目的としています。

このプロジェクトは、開発者が迅速に高品質なマルチプラットフォームアプリケーションを立ち上げ、保守・拡張していく上での共通的な課題（開発環境の統一、UIとバックエンドの連携、CI/CDの整備など）を解決するためのテンプレート、ツール、ガイドラインを提供します。

## 主な特徴

- **マルチプラットフォームGUI**: [Flet](https://flet.dev/) を使用し、Pythonのみでインタラクティブなフロントエンドを構築。Windows, macOS, Linux, Web, (将来的にはiOS/Android) に対応。
- **強力なバックエンドAPI**: [FastAPI](https://fastapi.tiangolo.com/) を採用し、高性能でモダンな非同期APIを提供。
- **開発支援ツール**: コーディング、テスト、デプロイメントを支援する各種ツールを同梱。
- **CI/CDパイプライン**: GitHub Actionsを使用した継続的インテグレーションとデプロイメントのワークフローを定義済み。

## プロジェクト構造

このリポジトリは、複数のコンポーネントとドキュメントから構成されています。

- `flet-multiplatform-app/`:
主要なFlet GUIアプリケーションとFastAPIバックエンドAPIのソースコード、詳細なドキュメントが含まれています。このアプリケーションのセットアップ、開発、テストに関する詳細は、`flet-multiplatform-app/README.md` を参照してください。
- `tools/`:
開発効率を向上させるための各種スクリプトや補助ツール群が格納されています。詳細は `tools/README.md` を参照してください。
Comment on lines +22 to +23
Copy link
Preview

Copilot AI May 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The root README references a tools/ directory, but the repository doesn’t include it. Either add that directory or update the README to reflect the actual structure.

Suggested change
- `tools/`:
開発効率を向上させるための各種スクリプトや補助ツール群が格納されています。詳細は `tools/README.md` を参照してください。
<!-- The `tools/` directory reference has been removed as it is not part of the repository. -->

Copilot uses AI. Check for mistakes.

- `.github/workflows/`:
CI (継続的インテグレーション) および CD (継続的デプロイメント) のためのGitHub Actionsワークフロー定義ファイルが格納されています。
- 各種 `.md` ガイドファイル (ルートディレクトリ):
リポジトリ全体に関わる横断的なガイドや、特定のプラットフォームへのデプロイメント手順などを記載したマークダウンファイル群です。

## 技術スタック

本プロジェクトで主に使用されている技術は以下の通りです。

- **プログラミング言語**: Python 3.13+
- **GUIフレームワーク**: Flet
- **バックエンドAPIフレームワーク**: FastAPI
- **非同期処理**: Uvicorn (ASGIサーバー), asyncio
- **データベース (バックエンドAPI)**: SQLAlchemy (ORM), Alembic (マイグレーション) - (主に `flet-multiplatform-app` 内で使用)
- **型チェック**: Pydantic (データバリデーションと設定管理)
- **テスト**: Pytest, Pytest-Cov
- **コードフォーマット・リンター**: Black, isort, Flake8, MyPy

(依存関係の詳細は各サブプロジェクトの `pyproject.toml` や `requirements.txt` を参照してください。)

## はじめに (Getting Started)

1. **リポジトリのクローン:**
```bash
git clone https://github.com/your-username/your-repository-name.git
cd your-repository-name
```
(上記URLは実際のリポジトリURLに置き換えてください)

2. **メインアプリケーションのセットアップと起動:**
主要なFletアプリケーション (`flet-multiplatform-app`) のセットアップ方法、開発環境の構築、アプリケーションの起動手順については、以下のドキュメントを参照してください。
* `flet-multiplatform-app/README.md`
* `flet-multiplatform-app/docs/getting_started.md` (日本語版は `GETTING_STARTED_JA.md`)

## ドキュメンテーション

このプロジェクトには、開発と運用を支援するための複数のドキュメントが用意されています。

- **アプリケーション開発ドキュメント (`flet-multiplatform-app/docs/`)**:
* `DEVELOPER_GUIDE.md`: 開発環境のセットアップ、コーディング規約、コントリビューション方法など。
* `API_REFERENCE.md`: バックエンドAPIのエンドポイント仕様。
* `DESIGN_GUIDELINES.md`: UI/UXデザインに関する指針。
* `TUTORIAL.md`: アプリケーション機能開発のチュートリアル。
- **デプロイメントガイド**:
* `android-flet-deployment-guide.md`: AndroidプラットフォームへのFletアプリケーションデプロイガイド。
* `ios-flet-deployment-guide.md`: iOSプラットフォームへのFletアプリケーションデプロイガイド。
* `web-flet-deployment-guide.md`: WebプラットフォームへのFletアプリケーションデプロイガイド。
- **CI/CD & リリース**:
* `cicd-release-guide.md`: CI/CDパイプラインの概要とリリース手順。
- **その他主要ガイド**:
* `architecture-design-guide.md`: プロジェクト全体のアーキテクチャ設計思想。
* `security-checklist.md`: セキュリティに関するチェックリスト。
* `testing-qa-guide.md`: テスト戦略と品質保証に関するガイド。

各ドキュメントは、それぞれの `.md` ファイルを参照してください。

## 貢献方法 (Contributing)

このプロジェクトへの貢献に興味がある方は、`flet-multiplatform-app/docs/DEVELOPER_GUIDE.md` に記載されている開発ワークフロー、コーディング規約、プルリクエストの手順などを参照してください。

バグ報告や機能提案は、GitHubのIssuesを通じて行うことを推奨します。

## ライセンス

このプロジェクトは MIT License の下で公開されています。詳細については、リポジトリ内の `LICENSE` ファイルを参照してください。もし `LICENSE` ファイルが存在しない場合は、プロジェクトオーナーにライセンス情報を確認してください。
238 changes: 114 additions & 124 deletions flet-multiplatform-app/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,51 +9,105 @@

```text
flet-multiplatform-app
├── src/ # アプリケーションのソースコード
│ ├── backend/ # バックエンド
├── pyproject.toml # Pythonプロジェクト定義、依存関係 (PEP 621)
├── pytest.ini # Pytest設定
├── src/ # ソースコード
│ ├── __init__.py
│ ├── app.py # Flet UIの構造やカスタムコントロールを定義
│ ├── flet_app.py # Flet UIアプリケーションのメインエントリーポイント
│ ├── main.py # FastAPIアプリケーションのエントリーポイント (src.backend.mainとは別)
│ ├── assets/ # 画像、フォントなどの静的アセット
│ ├── backend/ # バックエンドAPI (FastAPI)
│ │ ├── __init__.py
│ │ ├── main.py # アプリケーションのエントリーポイント
│ │ ├── app.py # FastAPIアプリケーション
│ │ ├── api/ # APIルーター
│ │ ├── core/ # コア機能
│ │ ├── models/ # データベースモデル
│ │ ├── schemas/ # Pydanticスキーマ
│ │ ├── services/ # ビジネスロジック
│ │ ├── tests/ # バックエンドテスト
│ │ ├── utils/ # ユーティリティ
│ │ └── config/ # 設定ファイル
│ └── frontend/ # フロントエンド
│ ├── main.py # フロントエンドのエントリーポイント
│ ├── components/ # UIコンポーネント
│ ├── pages/ # ページコンポーネント
│ └── utils/ # ユーティリティ
├── scripts/ # スクリプト
│ │ ├── app.py # FastAPIアプリケーションインスタンスの定義
│ │ ├── main.py # バックエンドAPIの起動スクリプト
│ │ ├── alembic/ # Alembicデータベースマイグレーション用ディレクトリ
│ │ │ ├── versions/ # マイグレーションスクリプト
│ │ │ └── env.py # Alembic実行環境設定
│ │ ├── alembic.ini # Alembic設定ファイル (こちらが主に使われる)
│ │ ├── api/ # APIルーター定義
│ │ ├── core/ # 設定読み込み、共通ロジックなど
│ │ ├── db/ # データベースセッション、エンジン設定
│ │ ├── models/ # SQLAlchemyデータベースモデル
│ │ ├── schemas/ # Pydanticデータスキーマ
│ │ └── tests/ # バックエンド固有のテスト
│ ├── components/ # Flet UIコンポーネント (共通部品など)
│ ├── config/ # アプリケーション全体の設定
│ ├── services/ # ビジネスロジック層
│ └── utils/ # 汎用ユーティリティ関数
├── scripts/ # 各種スクリプト (テスト実行用など)
│ ├── test.sh # テスト実行スクリプト (Linux/macOS)
│ └── test.bat # テスト実行スクリプト (Windows)
├── tests/ # 統合テスト
│ ├── __init__.py
│ ├── conftest.py
│ └── test_*.py
├── .env # 環境変数
├── .gitignore
├── pyproject.toml # 依存関係とプロジェクト設定
├── pytest.ini # pytest設定
└── README.md
├── tests/ # プロジェクト全体のテスト (統合テストなど)
│ ├── conftest.py # Pytest設定ファイル
│ └── ...
└── ... # .gitignore, .env.example などその他の設定ファイル
```
(上記は主要なファイルとディレクトリの構造です。詳細なファイルは省略されている場合があります。)

## 必要システム構成
- Python 3.13 以上
- Git

## セットアップ

1. **リポジトリのクローン:**
```bash
git clone <your-repository-url>
cd flet-multiplatform-app
```

2. **仮想環境の作成と有効化:**
```bash
python -m venv .venv
# Windows: .\.venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
```

3. **依存関係のインストール:**
開発に必要な全ての依存関係（本体、テストツール、リンター等）をインストールするには、プロジェクトルート (`flet-multiplatform-app`) で以下を実行します:
```bash
pip install -e .[dev]
```
アプリケーションの実行のみに必要な基本的な依存関係をインストールする場合は、以下を実行します:
```bash
pip install .
```

4. **環境変数の設定:**
`.env.example` ファイルを参考に `.env` ファイルを作成し、必要な環境変数を設定してください。

## アプリケーションの起動

開発時には、Flet UIアプリケーションとバックエンドAPIサーバーを個別に起動します。

1. **Flet UIアプリケーション:**
(`flet-multiplatform-app` ディレクトリから実行)
```bash
flet run src/flet_app.py
```

2. **バックエンドAPIサーバー:**
(`flet-multiplatform-app` ディレクトリから実行)
```bash
python -m uvicorn src.backend.main:app --reload --port 8001
```
(APIサーバーのポートはFletアプリと衝突しないように8001などを推奨)

## ドキュメンテーション

### オンラインドキュメント

プロジェクトのドキュメントは [MkDocs](https://www.mkdocs.org/) を使用してビルド・公開できます。
ドキュメント関連の依存関係は `pyproject.toml` の `[project.optional-dependencies.docs]` (仮の名称、必要に応じて追加) に定義するか、専用の `requirements-docs.txt` を使用します。

#### ドキュメントのビルド
#### ドキュメントのビルド (例: `requirements-docs.txt` を使用する場合)

1. ドキュメント用の依存関係をインストールします：

```bash
pip install -r requirements-docs.txt
```
```bash
pip install -r requirements-docs.txt
```
(または `pip install .[docs]` もし `pyproject.toml` に `docs` グループが定義されていれば)

2. ドキュメントをビルドします：

Expand Down Expand Up @@ -81,15 +135,26 @@ mkdocs serve

### テストの実行方法

1. テストに必要な依存関係をインストールします：

```bash
pip install -r requirements-test.txt
```
1. テストに必要な依存関係をインストールします（開発セットアップ `pip install -e .[dev]` に含まれています）：
```bash
# pip install -e .[dev] を実行していれば、通常は追加のインストールは不要です。
# requirements-test.txt は pyproject.toml の [dev] グループと内容を確認し、統一を検討してください。
# もし requirements-test.txt が独自の依存関係を持つ場合:
# pip install -r requirements-test.txt
```

2. テストを実行します：

**Windows の場合:**
**pytestコマンドを直接使用する場合 (推奨):**
`pyproject.toml` で `pytest` の設定が定義されています。プロジェクトルートで以下を実行します:
```bash
pytest
```
詳細なオプション (カバレッジレポート生成など) は `pyproject.toml` の `tool.pytest.ini_options.addopts` を参照してください。

**スクリプトを使用する場合:**

**Windows の場合:**

```batch
scripts\test.bat
Expand All @@ -109,105 +174,30 @@ chmod +x scripts/test.sh

#### カバレッジレポートの生成

pytestの実行時にHTMLカバレッジレポートが `htmlcov/` ディレクトリに自動生成されます (`pyproject.toml` の設定による)。
```bash
# テストを実行してカバレッジレポートを生成
pytest --cov=src --cov-report=term-missing --cov-report=html

# カバレッジレポートを表示（ブラウザで開く）
start htmlcov/index.html # Windows
open htmlcov/index.html # macOS
# pytest 実行後
# Windows: start htmlcov/index.html
# macOS/Linux: open htmlcov/index.html
```
ターミナルでのサマリーも表示されます。

#### カバレッジの目標

このプロジェクトでは、以下のカバレッジ目標を設定しています：

- **最小要件**: 70%以上（CIで強制）
- **推奨**: 80%以上
- **理想**: 90%以上

これらの目標は、コードの品質と保守性を確保するために設定されています。テストカバレッジは継続的インテグレーション（CI）プロセスで自動的に計測されます。
カバレッジを改善するには、テストされていないコード行を特定し（`htmlcov`レポートで詳細を確認できます）、それらに対するテストケースを追加してください。

#### カバレッジを改善するには
## その他のドキュメント

1. テストされていないファイルを特定:
```bash
coverage report --show-missing
```

2. 特定のファイルのカバレッジを確認:
```bash
coverage html --include="path/to/file.py"
```
- **[開発者ガイド](./docs/DEVELOPER_GUIDE.md)**: より詳細な開発環境のセットアップ、コーディング規約、コントリビューション方法など。
- **[デザインガイドライン](./docs/design_guidelines.md)**: UI/UX デザインに関するガイドライン。
- **[Swagger UI (API Docs)]**: バックエンドAPIサーバー起動後、`/docs` エンドポイント (例: `http://localhost:8001/docs`) にてAPIドキュメントが利用可能です。
- **[Redoc (API Docs)]**: バックエンドAPIサーバー起動後、`/redoc` エンドPOINT (例: `http://localhost:8001/redoc`) にて代替のAPIドキュメントが利用可能です。

3. カバレッジが低いファイルに対してテストを追加してください。

## ドキュメント

- [開発者ガイド](./docs/DEVELOPER_GUIDE.md) - 開発環境のセットアップやコントリビューション方法など
- [デザインガイドライン](./docs/design_guidelines.md) - UI/UX デザインのガイドライン

## プロジェクト構成

```
flet-multiplatform-app
├── src/ # アプリケーションのソースコード
│ ├── backend/ # バックエンド
│ │ ├── __init__.py
│ │ ├── main.py # アプリケーションのエントリーポイント
│ │ ├── app.py # FastAPIアプリケーション
│ │ ├── api/ # APIルーター
│ │ ├── core/ # コア機能
│ │ ├── models/ # データベースモデル
│ │ ├── schemas/ # Pydanticスキーマ
│ │ ├── services/ # ビジネスロジック
│ │ ├── tests/ # バックエンドテスト
│ │ ├── utils/ # ユーティリティ
│ │ └── config/ # 設定ファイル
│ └── frontend/ # フロントエンド
│ ├── main.py # フロントエンドのエントリーポイント
│ ├── components/ # UIコンポーネント
│ ├── pages/ # ページコンポーネント
│ └── utils/ # ユーティリティ
├── scripts/ # スクリプト
│ ├── test.sh # テスト実行スクリプト (Linux/macOS)
│ └── test.bat # テスト実行スクリプト (Windows)
├── tests/ # 統合テスト
│ ├── __init__.py
│ ├── conftest.py
│ └── test_*.py
├── .env # 環境変数
├── .gitignore
├── pyproject.toml # 依存関係とプロジェクト設定
├── pytest.ini # pytest設定
└── README.md
├── docs # ドキュメント
│ ├── DEVELOPER_GUIDE.md # 開発者向けガイド
│ └── design_guidelines.md # デザインガイドライン
├── requirements.txt # 依存関係
├── pyproject.toml # プロジェクト設定
└── README.md # プロジェクトの概要
```

## 使用方法

1. **依存関係のインストール**
プロジェクトのルートディレクトリで以下のコマンドを実行して、必要なパッケージをインストールします。
```
pip install -r requirements.txt
```

2. **アプリケーションの起動**
`src/main.py`を実行してアプリケーションを起動します。
```
python src/main.py
```

3. **テストの実行**
テストを実行するには、以下のコマンドを使用します。
```
pytest tests/
```

## 貢献

Expand Down
Loading
Loading