./knowledge-base/docs/DEPLOYMENT.md

# Historical Research System - 完全デプロイガイド

## 概要

このガイドでは、時代考証システムの基本機能を最初から最後までデプロイする手順を説明します。

## 前提条件

### 必要なツール

- **Node.js 18以上**
- **Python 3.11**
- **AWS CLI** (設定済み)
- **AWS CDK CLI** (`npm install -g aws-cdk`)
- **Git**

### AWS環境

- アカウントID: `903877990773`
- リージョン: `ap-northeast-1`
- 既存VPC: `vpc-08d84efb87d052cf9`
- Secrets Manager: `nhk_ai_api_key_lite_llm` (設定済み)

## デプロイ手順

### Step 1: リポジトリのクローンまたはダウンロード

```bash
cd /path/to/HistorycalResearch
```

### Step 2: Lambda共通レイヤーのビルド

```bash
cd lambda/layers/common
pip install -r requirements.txt -t python/
cd ../../..
```

### Step 3: CDKプロジェクトのセットアップ

```bash
cd cdk
npm install
npm run build
```

### Step 4: CDK Bootstrap（初回のみ）

```bash
cdk bootstrap aws://903877990773/ap-northeast-1
```

### Step 5: CDKスタックのデプロイ

```bash
cdk deploy --all
```

デプロイには10〜20分かかります。完了すると以下の情報が出力されます：

```
Outputs:
HistoricalResearchStack.ImagesBucketName = historical-research-images
HistoricalResearchStack.PromptsBucketName = historical-research-prompts
HistoricalResearchStack.WebBucketName = historical-research-web
HistoricalResearchStack.OpenSearchDomainEndpoint = xxx.ap-northeast-1.es.amazonaws.com
HistoricalResearchStack.APIGatewayURL = https://xxx.execute-api.ap-northeast-1.amazonaws.com/prod/
HistoricalResearchStack.CloudFrontURL = https://xxx.cloudfront.net
```

### Step 6: プロンプトファイルのアップロード

```bash
cd ..

# プロンプトバケット名を環境変数に設定
export PROMPTS_BUCKET=historical-research-prompts

# プロンプトファイルをアップロード
aws s3 cp prompts/image-analysis/main.txt s3://${PROMPTS_BUCKET}/image-analysis/main.txt
aws s3 cp prompts/image-analysis/json-schema.json s3://${PROMPTS_BUCKET}/image-analysis/json-schema.json
aws s3 cp prompts/master/era-list.json s3://${PROMPTS_BUCKET}/master/era-list.json

# アップロード確認
aws s3 ls s3://${PROMPTS_BUCKET}/ --recursive
```

### Step 7: OpenSearchインデックスの作成

**注意**: OpenSearchはVPC内にあるため、VPC内からアクセスする必要があります。

#### 方法1: EC2インスタンスから実行

1. 同じVPC内にEC2インスタンスを作成（または既存のものを使用）
2. SSHでログイン
3. 以下のコマンドを実行：

```bash
# OpenSearchエンドポイントを取得
OPENSEARCH_ENDPOINT=$(aws cloudformation describe-stacks \
  --stack-name HistoricalResearchStack \
  --region ap-northeast-1 \
  --query "Stacks[0].Outputs[?OutputKey=='OpenSearchDomainEndpoint'].OutputValue" \
  --output text)

# インデックスを作成
curl -X PUT "https://${OPENSEARCH_ENDPOINT}/historical-research-pages" \
  -H 'Content-Type: application/json' \
  -d '{
  "settings": {
    "index": {
      "knn": true,
      "knn.algo_param.ef_search": 512,
      "number_of_shards": 2,
      "number_of_replicas": 1
    }
  },
  "mappings": {
    "properties": {
      "page_id": { "type": "keyword" },
      "document_id": { "type": "keyword" },
      "page_number": { "type": "integer" },
      "user_era": { "type": "keyword" },
      "user_genre": { "type": "keyword" },
      "user_tags": { "type": "keyword" },
      "extracted_text": { "type": "text" },
      "text_embedding": {
        "type": "knn_vector",
        "dimension": 1024,
        "method": {
          "name": "hnsw",
          "space_type": "cosinesimil",
          "engine": "nmslib"
        }
      }
    }
  }
}'

# インデックス作成確認
curl -X GET "https://${OPENSEARCH_ENDPOINT}/_cat/indices?v"
```

詳細は [docs/opensearch-setup.md](docs/opensearch-setup.md) を参照してください。

### Step 8: フロントエンドのビルドとデプロイ

```bash
cd frontend

# 依存パッケージのインストール
npm install

# 環境変数の設定
cp .env.example .env

# .envファイルを編集（CDKの出力からURLを取得して設定）
# VITE_API_GATEWAY_URL=https://xxx.execute-api.ap-northeast-1.amazonaws.com/prod
# VITE_CLOUDFRONT_URL=https://xxx.cloudfront.net

# ビルド
npm run build

# S3にアップロード
aws s3 sync dist/ s3://historical-research-web/

# CloudFrontキャッシュ無効化
DISTRIBUTION_ID=$(aws cloudfront list-distributions \
  --query "DistributionList.Items[?Origins.Items[0].DomainName=='historical-research-web.s3.ap-northeast-1.amazonaws.com'].Id" \
  --output text)

aws cloudfront create-invalidation \
  --distribution-id ${DISTRIBUTION_ID} \
  --paths "/*"
```

## デプロイ後の確認

### 1. API Gatewayのテスト

```bash
# API Gateway URLを取得
API_URL=$(aws cloudformation describe-stacks \
  --stack-name HistoricalResearchStack \
  --query "Stacks[0].Outputs[?OutputKey=='APIGatewayURL'].OutputValue" \
  --output text)

# ヘルスチェック（存在する場合）
curl -X GET "${API_URL}/"
```

### 2. フロントエンドへのアクセス

```bash
# CloudFront URLを取得
CLOUDFRONT_URL=$(aws cloudformation describe-stacks \
  --stack-name HistoricalResearchStack \
  --query "Stacks[0].Outputs[?OutputKey=='CloudFrontURL'].OutputValue" \
  --output text)

echo "フロントエンドURL: ${CLOUDFRONT_URL}"
```

ブラウザで上記URLにアクセスし、検索ページが表示されることを確認します。

### 3. 画像アップロードのテスト

1. フロントエンドの「アップロード」ボタンをクリック
2. テスト画像を選択
3. メタデータを入力（タイトル、時代、ジャンル、タグ）
4. アップロード実行
5. DynamoDBとOpenSearchに登録されることを確認

```bash
# DynamoDBの確認
aws dynamodb scan \
  --table-name historical-research-processing-status \
  --limit 5

# OpenSearchの確認（VPC内から）
curl -X GET "https://${OPENSEARCH_ENDPOINT}/historical-research-pages/_search?size=5&pretty"
```

## トラブルシューティング

### CDKデプロイが失敗する

- IAM権限を確認
- VPC設定を確認（既存VPCが存在するか）
- リソース制限を確認（例: Elastic IP上限）

### Lambda関数がタイムアウトする

- メモリサイズを増やす（CDKスタックで設定）
- タイムアウト時間を延長
- VPC設定を確認（NAT Gateway経由でインターネットアクセス可能か）

### OpenSearchにアクセスできない

- Security Groupを確認
- VPC内からアクセスしているか確認
- アクセスポリシーを確認

### LiteLLM APIエラー

- Secrets Managerに正しいAPIキーが設定されているか確認
- Lambda関数にSecrets Managerアクセス権限があるか確認

### フロントエンドが表示されない

- S3バケットにファイルがアップロードされているか確認
- CloudFrontのOAC設定を確認
- ブラウザのコンソールでエラーを確認

## 運用

### プロンプトの更新

```bash
# プロンプトファイルを編集
vim prompts/image-analysis/main.txt

# S3にアップロード
aws s3 cp prompts/image-analysis/main.txt s3://historical-research-prompts/image-analysis/main.txt

# 即座に反映される（Lambda関数は毎回S3から読み込む）
```

### 時代マスタの更新

```bash
# era-list.jsonを編集
vim prompts/master/era-list.json

# S3にアップロード
aws s3 cp prompts/master/era-list.json s3://historical-research-prompts/master/era-list.json

# CloudFrontキャッシュ無効化
aws cloudfront create-invalidation \
  --distribution-id ${DISTRIBUTION_ID} \
  --paths "/master/era-list.json"
```

### ログの確認

```bash
# Lambda関数のログを確認
aws logs tail /aws/lambda/historical-research-image-analyzer --follow

# DLQメッセージの確認
aws sqs receive-message \
  --queue-url https://sqs.ap-northeast-1.amazonaws.com/903877990773/historical-research-image-analysis-dlq
```

## クリーンアップ

システムをすべて削除する場合：

```bash
# CDKスタックを削除
cd cdk
cdk destroy

# S3バケットを手動で削除（バケットポリシーで保護されている場合）
aws s3 rm s3://historical-research-images --recursive
aws s3 rb s3://historical-research-images

aws s3 rm s3://historical-research-web --recursive
aws s3 rb s3://historical-research-web

aws s3 rm s3://historical-research-prompts --recursive
aws s3 rb s3://historical-research-prompts
```

## 参考資料

- [README.md](README.md) - プロジェクト概要
- [仕様書_基本機能.md](仕様書_基本機能.md) - 詳細仕様
- [docs/opensearch-setup.md](docs/opensearch-setup.md) - OpenSearchセットアップ
- [frontend/README.md](frontend/README.md) - フロントエンド開発ガイド

## サポート

技術的な質問や問題は、仕様書を参照するか、開発チームに問い合わせてください。