FastAPIで構築された授業アンケート分析システムのバックエンドサービス。CSVアップロード、LLMによるコメント分析、集計・可視化機能を提供。
# 環境変数設定
cp .env.example .env
# Docker Composeで全環境を起動
docker compose up --build
# マイグレーションを適用
docker compose exec api alembic upgrade head
# ブラウザでSwagger UIにアクセス
open http://localhost:8000/docs- CSVアップロード: 授業アンケートCSVを受け取り、データベースに正規化
- LLM分析: 自由記述コメントを感情分析、カテゴリ分類、重要度評価
- 集計処理: NPS、平均スコア、スコア分布、コメント分類の自動集計
- RESTful API: フロントエンドへのデータ提供
- FastAPI - Webフレームワーク
- SQLAlchemy - ORM (7テーブルのリレーショナルモデル)
- Alembic - データベースマイグレーション管理
- Celery + Redis - 非同期バックグラウンドタスク処理
- LLM API - コメント分析 (OpenAI / Azure OpenAI / Generic HTTP)
- Storage - ローカル/S3対応の抽象化ストレージレイヤー
.
├── app/ # FastAPIアプリケーション
│ ├── main.py # アプリケーションファクトリ
│ ├── api/ # APIエンドポイント (10モジュール)
│ ├── core/ # 設定管理
│ ├── db/ # データベースモデル・セッション
│ ├── schemas/ # Pydanticスキーマ
│ ├── services/ # ビジネスロジック
│ ├── workers/ # Celeryワーカー
│ └── analysis/ # LLM分析パイプライン
├── tests/ # ユニット・統合テスト
├── alembic/ # データベースマイグレーション
├── docs/ # ドキュメント
│ ├── database.md # データベーススキーマ詳細
│ ├── api-specification.md # APIエンドポイント詳細
│ ├── dataflow.md # データフロー詳細
│ └── development.md # 開発ガイド
├── Dockerfile # コンテナイメージ定義
├── docker-compose.yml # ローカル開発環境
└── requirements.txt # 依存パッケージ
詳細なドキュメントは docs/ ディレクトリを参照してください：
- データベーススキーマ - 7テーブルの詳細定義、ER図、命名規則
- API エンドポイント - 全エンドポイントのリクエスト/レスポンス仕様
- データフロー - システムアーキテクチャと処理フロー詳細
- 開発ガイド - ローカル環境セットアップ、テスト、マイグレーション
主要なAPIエンドポイント：
| メソッド | エンドポイント | 説明 |
|---|---|---|
| POST | /api/v1/surveys/upload |
アンケートデータアップロード |
| GET | /api/v1/courses |
講座一覧取得 |
| GET | /api/v1/courses/trends |
講座全体の傾向データ取得 |
| GET | /api/v1/courses/compare |
年度比較データ取得 |
| GET | /api/v1/lectures/{lecture_id}/analysis |
講義回別分析データ取得 |
| GET | /api/v1/jobs/{job_id} |
ジョブ状態確認 |
詳細は docs/api-specification.md および Swagger UI (http://localhost:8000/docs) を参照してください。
7つのテーブルで構成されたデータベース：
- lectures - 講義マスタ
- survey_batches - アンケートバッチ
- survey_responses - 個別回答（12種類のスコア）
- response_comments - コメント + LLM分析結果
- survey_summaries - 集計サマリー（NPS、平均スコア）
- score_distributions - スコア分布
- comment_summaries - コメント分類集計
詳細は docs/database.md を参照してください。
# 依存パッケージインストール（仮想環境の作成も自動）
uv sync
# 環境変数設定
cp .env.example .env
# .envを編集してLLM APIキーなどを設定
# マイグレーション実行（Alembic）
# DBスキーマの変更を反映させるには以下のコマンドを実行する必要があります
# 注意：Docker環境の場合は `docker compose exec api ...` のようにコンテナ内で実行してください
uv run alembic upgrade head
# 新しいマイグレーションを作成する場合
# uv run alembic revision --autogenerate -m "変更内容のコメント"
# 開発サーバー起動
uv run uvicorn app.main:app --reload
# 本番相当での起動（アクセスログ二重化防止のため --no-access-log 推奨）
# 例: uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --no-access-log# 全テスト実行
uv run pytest
# カバレッジ付き
uv run pytest --cov=app --cov-report=html詳細な開発手順は docs/development.md を参照してください。
GitHub Actions で以下のワークフローが設定されています：
| ワークフロー | トリガー | 内容 |
|---|---|---|
| tests | push / PR | ユニットテスト (pytest --cov) + 統合スモークテスト (PostgreSQL + Redis) |
| ruff-check | push (main) / PR | Ruff による lint (ruff check) とフォーマット検証 (ruff format --check) |
| deploy | push (main) / 手動 | ECR へイメージ push → Alembic マイグレーション → ECS (API + Celery) デプロイ |
プロジェクトでは Ruff を lint・フォーマッタとして使用しています。設定は pyproject.toml に記載。
# lint 実行
uv run ruff check .
# lint 自動修正
uv run ruff check --fix .
# フォーマット実行
uv run ruff format .
# フォーマット差分確認のみ
uv run ruff format --check .main ブランチへの push で自動デプロイが実行されます。手順：
- Docker イメージをビルドし Amazon ECR へ push
- ECS タスク定義を新イメージで更新・登録
- Fargate 上で
alembic upgrade headを実行（マイグレーション） - マイグレーション成功後、API サービスと Celery ワーカーサービスを更新
- 両サービスの安定化を待機
（ライセンス情報を追加してください）