./README.md

# 📚 HistoricalAccuracy

**時代考証アシストシステム** のモノリポジトリです。

---

## 🗂️ ディレクトリ構成

```
HistoricalAccuracy/
│
├── 📁 .github/workflows/
│   ├── deploy-infrastructure.yml  ← CDK / Lambda の自動デプロイ
│   └── deploy-frontend.yml        ← フロントエンドの自動デプロイ
│
├── 📁 research-ai/                ← AI アシスト機能（App Runner）
│   ├── src/
│   ├── front/
│   ├── Dockerfile
│   └── ...
│
└── 📁 knowledge-base/             ← 知識ベース・検索基盤（CDK + Lambda + フロントエンド）
    ├── cdk/                         インフラ定義（AWS CDK / TypeScript）
    ├── lambda/                      Lambda 関数（Python）
    ├── frontend/                    フロントエンド（React / Vite）
    ├── prompts/                     AI プロンプトファイル（S3 管理）
    └── docs/                        ドキュメント
```

> 💡 **モジュールは独立しています**
> `research-ai/` と `knowledge-base/` は同じリポジトリに共存していますが、
> CI/CD は **変更されたモジュールだけ** を自動デプロイします。
> 片方を触っても、もう片方は再デプロイされません。

---

## 🚀 初回セットアップ（このリポジトリを初めて使う人へ）

### 1️⃣ リポジトリをクローンする

```bash
git clone git@github.com:nhk-ds/HistoricalAccuracy.git
cd HistoricalAccuracy
```

> ⚠️ SSH キーを GitHub に登録していない場合は、
> GitHub の「Settings → SSH and GPG keys」からキーを追加してください。

### 2️⃣ 依存パッケージをインストールする

作業するモジュールに応じて、以下を実行してください。

**📦 knowledge-base の CDK（インフラ定義）を触る場合:**

```bash
cd knowledge-base/cdk
npm install
```

**📦 knowledge-base のフロントエンドを触る場合:**

```bash
cd knowledge-base/frontend
npm install
```

**📦 research-ai を触る場合:**

```bash
cd research-ai
# uv がインストールされていない場合: pip install uv
uv sync
```

### 3️⃣ フロントエンドのローカル動作確認（任意）

```bash
cd knowledge-base/frontend
npm run dev
# → ブラウザで http://localhost:3000 を開く
```

---

## 🔄 開発フロー

このプロジェクトは **コードを `main` ブランチに追加するとAWSへ自動デプロイ** される仕組みになっています。
開発スタイルは状況に応じて以下の3パターンから選べます。

---

### 📌 パターン早見表

| パターン          | ブランチ              | PR                         | 向いている場面                 |
| ----------------- | --------------------- | -------------------------- | ------------------------------ |
| **A（最速）**     | 作らない（main 直接） | しない                     | 一人作業・小さな修正・PoC      |
| **B（バランス）** | 作る                  | しない（ローカルでマージ） | 実験的な変更・試行錯誤         |
| **C（標準）**     | 作る                  | する                       | 複数人・レビュー必要・本番運用 |

---

### 🅰️ パターンA：最速（main に直接プッシュ）

小さな修正や一人作業のときに使える、最もシンプルな方法です。

```
① 最新コードを取得
② コードを修正
③ コミット
④ main に直接プッシュ
        ↓
⑤ GitHub Actions が自動デプロイ 🎉
```

```bash
# ① 最新コードを取得
git checkout main
git pull origin main

# ② コードを修正（エディタで編集）

# ③ コミット
git add .
git commit -m "fix: 検索のバグを修正"

# ④ main に直接プッシュ → 自動デプロイ開始
git push origin main
```

---

### 🅱️ パターンB：ブランチを作ってローカルでマージ

「実験的なコードを書いてみたい」「失敗しても main を汚したくない」ときに使います。
GitHub を経由せず、自分の PC 上でブランチを作り→作業→main にマージします。

```
① 最新コードを取得
② ブランチを作成
③ コードを修正・コミット（何度でも）
④ main に戻ってローカルでマージ
⑤ main にプッシュ
        ↓
⑥ GitHub Actions が自動デプロイ 🎉
```

```bash
# ① 最新コードを取得
git checkout main
git pull origin main

# ② 作業ブランチを作成
git checkout -b feature/add-era-filter

# ③ コードを修正 → コミット（何度繰り返してもOK）
git add .
git commit -m "feat: 時代フィルターを追加"

# ④ main に戻ってローカルでマージ
git checkout main
git merge feature/add-era-filter

# ⑤ プッシュ → 自動デプロイ開始
git push origin main

# 作業ブランチを削除（任意）
git branch -d feature/add-era-filter
```

---

### 🅲️ パターンC：PR（プルリクエスト）経由でマージ

複数人で開発したり、レビューを経てからデプロイしたいときの標準的なフローです。

```
① 最新コードを取得
② ブランチを作成
③ コードを修正・コミット
④ GitHub にプッシュ
⑤ GitHub 上でプルリクエスト（PR）を作成
⑥ レビュー → 承認
⑦ Merge pull request をクリック
        ↓
⑧ GitHub Actions が自動デプロイ 🎉
```

```bash
# ① 最新コードを取得
git checkout main
git pull origin main

# ② 作業ブランチを作成
git checkout -b fix/search-lambda-timeout

# ③ コードを修正 → コミット
git add knowledge-base/lambda/search-api/handler.py
git commit -m "fix: サーチAPIのタイムアウトを30秒に延長"

# ④ GitHub にプッシュ
git push origin fix/search-lambda-timeout
```

その後 GitHub 上で：

1. [https://github.com/nhk-ds/HistoricalAccuracy](https://github.com/nhk-ds/HistoricalAccuracy) を開く
2. 画面上部に表示される「**Compare & pull request**」ボタンをクリック
3. 変更内容を説明して PR を作成
4. レビュアーを指定し、承認されたら「**Merge pull request**」をクリック

> 💡 コミット前に `git status`（変更ファイル一覧）や `git diff`（差分）で内容を確認するのがおすすめです。
> 初回プッシュ時に `--set-upstream` を求められることがありますが、`git push origin ブランチ名` で自動的に設定されます。

---

### ⬇️ 他の人の変更を自分の PC に取り込む方法

誰かが `main` にコードを追加したあと、自分の作業を始める前に必ず実行してください。

```bash
git checkout main
git pull origin main
```

> 💡 これを忘れると「コンフリクト（同じ行を別々に変更した状態）」が発生しやすくなります。
> 作業前の `git pull` を習慣にしましょう。

---

### 🔍 デプロイの進行状況を確認する

`main` にプッシュ・マージしたあと、デプロイが正常に動いているか確認できます：

➡️ **[GitHub Actions タブを開く](https://github.com/nhk-ds/HistoricalAccuracy/actions)**

- ✅ 緑のチェック = 成功
- ❌ 赤の × = 失敗（クリックしてログを確認）

---

## ⚙️ CI/CD の仕組み

**GitHub Actions** とは「GitHub 上で自動的にコマンドを実行する仕組み」です。
`main` ブランチに変更が入ったとき、**変更されたフォルダに応じて** 対応するデプロイだけが自動実行されます。

### どのフォルダを変えると何がデプロイされるか

| 変更したフォルダ             | 動くワークフロー                              | デプロイ内容                                           |
| ---------------------------- | --------------------------------------------- | ------------------------------------------------------ |
| `knowledge-base/cdk/**`      | `deploy-infrastructure.yml`                   | CDK deploy（Lambda / API Gateway / WAF 等）            |
| `knowledge-base/lambda/**`   | `deploy-infrastructure.yml`                   | 同上（Lambda コードも CDK 経由で更新）                 |
| `knowledge-base/prompts/**`  | `deploy-infrastructure.yml`                   | 同上                                                   |
| `knowledge-base/frontend/**` | `deploy-frontend.yml`                         | フロントエンドを S3 に配置 + CloudFront キャッシュ削除 |
| `research-ai/**`             | **動かない**（research-ai 側の CI/CD は別途） | —                                                      |

> **例：** Lambda の `handler.py` だけ変えた場合
> → フロントエンドは再デプロイされない。時間もコストも無駄にならない。

---

### 🏗️ インフラデプロイ（deploy-infrastructure）の流れ

```
main にコード追加
  ↓
GitHub Actions が起動（GitHub のサーバーで実行）
  ↓
① AWS に OIDC 認証でログイン（パスワード不要・IAM ロールを一時的に使用）
  ↓
② knowledge-base/cdk/ の TypeScript をコンパイル
  ↓
③ cdk deploy --all を実行
   └─ WafStack（us-east-1）
   └─ HistoricalResearchStack（ap-northeast-1）
      ├─ 変更のある Lambda 関数だけ更新
      ├─ API Gateway 設定の差分だけ適用
      └─ 変更がなければ何もしない（スキップ）
```

---

### 🖥️ フロントエンドデプロイ（deploy-frontend）の流れ

```
main にコード追加（frontend/ 以下に変更があった場合のみ）
  ↓
GitHub Actions が起動
  ↓
① AWS に OIDC 認証でログイン
  ↓
② npm run build（React アプリを静的 HTML/CSS/JS にビルド）
  ↓
③ aws s3 sync で S3 バケット（historical-research-web）に差分のみアップロード
  ↓
④ CloudFront のキャッシュを削除（古いファイルが配信されなくなる）
```

---

### 🔐 AWS への認証方法（OIDC）

GitHub Actions が AWS にアクセスするとき、**アクセスキーなどの長期的な秘密情報は一切使いません**。
代わりに「GitHub が発行した一時的な証明書」を AWS IAM が検証する **OIDC 方式** を採用しています。

- **IAM ロール名:** `github-actions-knowledge-base`
- **許可範囲（最小権限）:** CDK deploy ロールの権限借用 + S3 書き込み + CloudFront キャッシュ削除のみ

---

## 🛠️ 手動デプロイが必要な場合

通常は `main` へのプッシュ・マージで自動デプロイされますが、緊急時や手動で再実行したい場合：

1. **[Actions タブ](https://github.com/nhk-ds/HistoricalAccuracy/actions)** を開く
2. 実行したいワークフロー（`Deploy Infrastructure` または `Deploy Frontend`）をクリック
3. 右側の「**Run workflow**」ボタン → `main` を選択して実行

---

## 📖 各モジュールの詳細ドキュメント

| モジュール                    | ドキュメント                                                 |
| ----------------------------- | ------------------------------------------------------------ |
| 🗄️ knowledge-base（開発手順） | [knowledge-base/開発引継ぎ.md](knowledge-base/開発引継ぎ.md) |
| 🗄️ knowledge-base（仕様）     | [knowledge-base/仕様書.md](knowledge-base/仕様書.md)         |
| 🤖 research-ai                | [research-ai/README.md](research-ai/README.md)               |