# 🚀 Almondo PoC Template

このリポジトリは、PoCプロジェクトのための包括的なテンプレートです。本READMEでは、プロジェクトのセットアップから開発プロセス、ディレクトリ構造まで、詳細かつ分かりやすく説明します。

## 📑 目次

- [🚀 Almondo PoC Template](#-almondo-poc-template)
  - [📑 目次](#-目次)
  - [🛠 セットアップ](#-セットアップ)
      - [前提条件](#前提条件)
      - [セットアップ手順](#セットアップ手順)
    - [Dockerの基本操作](#dockerの基本操作)
    - [パッケージの管理](#パッケージの管理)
  - [🔄 開発の手順](#-開発の手順)
    - [開発フロー](#開発フロー)
  - [📂 ディレクトリ構造](#-ディレクトリ構造)
    - [主要ディレクトリの説明](#主要ディレクトリの説明)
      - [`work/`](#work)
      - [`data/`](#data)
    - [`work/` ディレクトリ](#work-ディレクトリ)
      - [`example/`](#example)
      - [`experiments/`](#experiments)
      - [`src/`](#src)
      - [`tests/`](#tests)
    - [`data/` ディレクトリ](#data-ディレクトリ)
      - [`models/`](#models)
      - [`preprocessed/`](#preprocessed)
      - [`raw/`](#raw)
      - [`results/`](#results)
  - [VSCode上での作業(Dev container)](#vscode上での作業dev-container)
    - [前提条件](#前提条件-1)
    - [🔧 セットアップ手順](#-セットアップ手順)
      - [1️⃣ 拡張機能のインストール](#1️⃣-拡張機能のインストール)
      - [2️⃣ プロジェクトを開く](#2️⃣-プロジェクトを開く)
      - [3️⃣ Dev Containerの設定](#3️⃣-dev-containerの設定)
      - [4️⃣ Dev Container内でプロジェクトを再オープン](#4️⃣-dev-container内でプロジェクトを再オープン)
      - [5️⃣ 開発開始](#5️⃣-開発開始)


## 🛠 セットアップ

#### 前提条件

- git,dockerのインストール

#### セットアップ手順

1. **リポジトリのクローン**
   ```bash
   git clone [リポジトリのurl]
   cd [ディレクトリ名]
   ```

2. **デフォルトブランチの確認**
   ```bash
   git branch
   ```
   > 💡 `develop`ブランチがアクティブであることを確認してください。
   ```
   * develop
     main
   ```

3. **環境設定ファイルの作成**
   ```bash
   cp .env.dev.template .env.dev
   ```
   > ⚠️ `.env.dev`ファイルを編集し、必要な環境変数を設定してください。

4. **Dockerコンテナの起動**
   ```bash
   docker-compose run development bash
   ```
   > 🔔 初回実行時はイメージのビルドが行われるため、時間がかかる場合があります。

5. **パッケージのインストール**
   ```bash
   poetry install
   ```
   > 📘 これにより、`pyproject.toml`に定義された全ての依存パッケージがインストールされます。

### Dockerの基本操作

| コマンド | 説明 |
|---------|------|
| `docker ps` | 実行中のコンテナ一覧を表示 |
| `docker exec -it [container_id] bash` | 実行中のコンテナに接続 |
| `docker-compose down` | コンテナを停止し削除 |

### パッケージの管理

Poetryを使用してパッケージを管理します。

- **パッケージの追加**:
  ```bash
  poetry add [パッケージ名]
  ```
  特定のバージョンを指定する場合:
  ```bash
  poetry add [パッケージ名]=[バージョン]
  ```

- **パッケージの削除**:
  ```bash
  poetry remove [パッケージ名]
  ```

> 📝 パッケージの追加や削除を行った後は、必ず変更をコミットしてください。

## 🔄 開発の手順

本プロジェクトでは、効率的かつ体系的な開発を行うため、Issue driven開発手法を採用しています。

> 📚 詳細は[Issue driven運用のドキュメント](https://www.notion.so/Issue-driven-5378336f66c243f7933b52a15ce15ee7?p=9b275fa3a5e841eea11133f900a80499&pm=s)をご参照ください。

### 開発フロー

1. **Issueの作成** 
   - リポジトリの「Issues」タブから新規Issueを作成
   - タスクの詳細、目的、期待される結果を明確に記述

2. **ブランチの作成** 
   作成したIssueからGUI上でbranchを作成してください
   - 命名規則:
     - 新機能追加: `feature/[機能名]`
     - バグ修正/改善: `fix/[修正内容]`

3. **開発作業** 
   GUI上で作成したbranchをローカルにfetchします
   ```bash
   git fetch origin
   git checkout [branch名]
   ```
   - コードの実装
   - ユニットテストの作成・実行

4. **変更内容のコミットとプッシュ** 
   ```bash
   git add .
   git commit -m "commit message"
   git push origin [branch名]
   ```

5. **プルリクエスト(PR)の作成** 
   - GitHub上で「Compare & pull request」ボタンをクリック
   - PRの説明を記入する

6. **コードレビュー** 
   - PjMがコードをチェック
   - フィードバックがある場合は修正を行い、再度プッシュ

7. **マージと後処理** 
   - レビュー承認後、GUI上で`develop`ブランチにマージ
   - GUI上で作業ブランチの削除

> 💡 **Tip**: 常に`develop`ブランチの最新状態を維持するよう心がけましょう。作業開始前に以下のコマンドを実行することをおすすめします：
> ```bash
> git checkout develop
> git pull origin develop
> git switch [branch名]
> git merge —no-ff develop
> ```

## 📂 ディレクトリ構造

```
root/
├── .github/
│   └── workflows/           # CI/CDワークフロー定義
│       └── pysen-python-app.yaml
├── data/                    # データ関連ファイル (Gitで管理されません)
│   ├── models/              # 学習済みモデル (.pth等)
│   ├── preprocessed/        # 前処理済みデータ (CSV等)
│   ├── raw/                 # 生データ (提供されたExcel等)
│   └── results/             # 解析結果
├── work/                    # プロジェクトのメインコード
│   ├── example/             # デモやサンプルコード
│   ├── experiments/         # 実験用コード
│   ├── src/                 # 共通ライブラリやユーティリティ
│   └── tests/               # テストコード
├── .env.dev.template        # 開発環境変数テンプレート
├── .gitignore               # Git除外設定
├── Dockerfile               # Dockerイメージ定義
├── README.md                # プロジェクト説明 (本ファイル)
├── docker-compose.yml       # Docker Compose設定
├── entrypoint.sh            # Dockerエントリーポイントスクリプト
├── poetry.lock              # 依存関係ロックファイル
├── pyproject.toml           # Poetryプロジェクト設定
└── LICENSE                  # ライセンス情報
```

### 主要ディレクトリの説明

#### `work/`
- **example/**: クリーンなデモ用コード、Spaces用スクリプトなど
- **experiments/**: 実験的コードや一時的なスクリプト
- **src/**: プロジェクト共通の基本クラスやユーティリティ
- **tests/**: 単体テストコード

#### `data/`
- **models/**: 学習済みモデル（.pthファイルなど）
- **preprocessed/**: 前処理済みデータ（CSVやテキストファイル）
- **raw/**: 元データ（提供されたExcelファイルなど）
- **results/**: 各タスクの出力結果



### `work/` ディレクトリ

`work/` ディレクトリは、プロジェクトの主要なコードベースを含みます。各サブディレクトリの詳細は以下の通りです：

#### `example/`
- **目的**: デモンストレーションやサンプルコードの保管
- **内容**:
  - クリーンで理解しやすいコード例
  - Hugging Face Spacesのデモスクリプト
  - クライアントへの提示用コードサンプル

#### `experiments/`
- **目的**: 実験的なコードや一時的なスクリプトの保管
- **内容**:
  - 新しいアルゴリズムの試験実装
  - パラメータチューニングスクリプト
  - プロジェクト固有のプロンプトやコンフィグ

#### `src/`
- **目的**: 再利用可能な共通コンポーネントの保管
- **内容**:
  - プロジェクト間で共有できる基本クラス
  - ユーティリティ関数
  - データ処理パイプライン

#### `tests/`
- **目的**: 単体テストとその関連ファイルの保管
- **内容**:
  - 各モジュールの単体テスト

### `data/` ディレクトリ

`data/` ディレクトリは、プロジェクトで使用する様々なデータを保管します。
#### `models/`
- **目的**: 学習済みモデルの保存
- **内容**:
  - PyTorchモデル（.pthファイル）
  - TensorFlowモデル（.h5ファイル）
  - その他の機械学習モデル

#### `preprocessed/`
- **目的**: 前処理済みデータの保存
- **内容**:
  - クリーニング済みCSVファイル
  - トークン化されたテキストファイル
  - 正規化された数値データ

#### `raw/`
- **目的**: 元データの保管
- **内容**:
  - クライアントから提供された元のExcelファイル
  - ウェブスクレイピングで取得した生データ
  - 未処理のログファイル

#### `results/`
- **目的**: 分析結果や出力データの保存
- **内容**:
  - モデルの予測結果
  - 統計分析のレポート
  - 生成されたグラフや図表

> ⚠️ 注意: `data/`ディレクトリの内容はGitで管理されません。重要なデータは別途バックアップを取ってください。


## VSCode上での作業(Dev container)
vscode上でdocker環境で作業する方法に[Dev container]という拡張機能があるのでご紹介します

### 前提条件

以下のツールがインストールされていることを確認してください：

- ✅ [Visual Studio Code](https://code.visualstudio.com/)
- ✅ [Docker Desktop](https://www.docker.com/products/docker-desktop) (起動済みであること)

### 🔧 セットアップ手順

#### 1️⃣ 拡張機能のインストール

<details>
<summary>詳細手順を表示</summary>

1. VSCodeを開く
2. 左サイドバーの拡張機能アイコン（🧩）をクリック（または `Ctrl+Shift+X` / `Cmd+Shift+X`）
3. 検索バーに "Remote Development" と入力
4. 表示された拡張機能をインストール

</details>

#### 2️⃣ プロジェクトを開く

<details>
<summary>詳細手順を表示</summary>

1. VSCodeで開発したいプロジェクトのフォルダを開く（`File > Open Folder`）

</details>

#### 3️⃣ Dev Containerの設定

<details>
<summary>詳細手順を表示</summary>

1. コマンドパレットを開く（`Ctrl+Shift+P` または `Cmd+Shift+P`）
2. "Dev containers:Add Dev Containers Configuration Files..." と入力し選択
3. プロジェクトに適したテンプレートを選択（例：Python, Node.js など）

</details>

#### 4️⃣ Dev Container内でプロジェクトを再オープン

<details>
<summary>詳細手順を表示</summary>

1. コマンドパレットを再度開く
2. "Dev-Containers: Reopen in Container" を選択
3. VSCodeがコンテナをビルドし、プロジェクトを開くのを待つ

</details>

#### 5️⃣ 開発開始

- 🎉 コンテナ内でVSCodeが起動したら、開発を開始できます
- 💻 ターミナルも自動的にコンテナ内で動作します


🔗 詳細情報は[公式VSCode Dev Containersドキュメント](https://code.visualstudio.com/docs/remote/containers)をご覧ください。