コンテンツにスキップ

セットアップ

前提条件

ツール バージョン
Bun v1.x 以上
Docker / Docker Compose Postgres コンテナ起動に必要
Node.js v20 以上（フロントエンドの型定義用）
Google Cloud プロジェクト OAuth クライアント ID / シークレットの発行に必要

リポジトリ構成

このプロジェクトは独立した 2 つのリポジトリからなる。作業ディレクトリ直下に両方を並べて配置する運用を想定している。

arrange/
├── heineken-interview-arrange-backend/
├── heineken-interview-arrange-frontend/
└── heineken-interview-arrange-docs/

backend の手順

1. リポジトリのクローン

git clone <backend-repository-url> heineken-interview-arrange-backend
cd heineken-interview-arrange-backend

2. 一括セットアップ

.env の作成、Postgres の起動、依存関係のインストール、スキーマ反映をまとめて実行する。

bun run setup

内部で以下を順に行う。

  1. .env.example から .env を作成（既にあればスキップ）
  2. Docker の起動確認
  3. docker compose up -d postgres（PostgreSQL 17）
  4. pg_isready で起動待ち
  5. bun install
  6. bun run db:push

個別に実行する場合は以下。

cp .env.example .env
bun run docker:up
bun install
bun run db:push

3. 環境変数の設定

.env のうち、Google OAuth の 3 項目は必ず自分の値に置き換える。

変数名 必須 説明 例
NODE_ENV - 実行モード development
PORT - 待ち受けポート（既定 8080） 8080
HOST - 待ち受けホスト（既定 0.0.0.0） 0.0.0.0
APP_BASE_URL ◯ バックエンド自身の URL http://localhost:8080
FRONTEND_URL - フロントエンドの URL（既定 http://localhost:3000） http://localhost:3000
ALLOWED_ORIGINS ◯ CORS 許可オリジン（カンマ区切り） http://localhost:3000
DATABASE_URL ◯ DB 接続文字列 postgresql://user:password@localhost:5432/interview_arrangement
GOOGLE_CLIENT_ID ◯ OAuth クライアント ID xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET ◯ OAuth クライアントシークレット -
GOOGLE_REDIRECT_URI ◯ OAuth コールバック URL http://localhost:8080/api/v1/auth/google/callback
ALLOWED_EMAIL_DOMAINS ◯ ログインを許可するメールドメイン（カンマ区切り） 4digit.jp
ALLOWED_SURVEY_IDS - 連携する調査を限定する（カンマ区切り）。未設定なら制限なし 389867
GOOGLE_SERVICE_ACCOUNT_EMAIL - Calendar 操作用サービスアカウント -
GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY - 同秘密鍵 "-----BEGIN PRIVATE KEY-----\n...\n"
GMAIL_SENDER_EMAIL - 送信元アドレス noreply@example.com
EMAIL_ENABLED - 実メール送信の可否（既定 false） true
JWT_SECRET ◯ JWT 署名鍵（32 文字以上） -
JWT_EXPIRES_IN - アクセストークン有効期限（既定 1h） 1h
JWT_REFRESH_EXPIRES_IN - リフレッシュトークン有効期限（既定 7d） 7d
PROTOTYPE_MODE - 外部副作用の無効化（既定 true） true
LOG_LEVEL - ログレベル（既定 info） debug
LOG_SQL_QUERIES - SQL ログ出力（既定 false） false
SCHEDULING_TOKEN_TTL_DAYS - 調整トークン有効日数（既定 14） 14
DATABRICKS_HOST - ワークスペース URL https://dbc-xxxx.cloud.databricks.com
DATABRICKS_WAREHOUSE_ID - SQL Warehouse の ID -
DATABRICKS_CLIENT_ID - サービスプリンシパルの Application ID -
DATABRICKS_CLIENT_SECRET - サービスプリンシパルの OAuth secret -
DATABRICKS_TOKEN - ローカル用。CLI のトークンで代替する場合に指定 -
DATABRICKS_CATALOG - 既定 cs cs
DATABRICKS_SCHEMA_DM - 調査別テーブルのスキーマ。既定 cs_dm cs_dm
DATABRICKS_SCHEMA_DWH - メタ集計用スキーマ。既定 cs_dwh cs_dwh

環境変数は src/config/env.ts の Zod スキーマが起動時に検証する。変数を追加するときは src/config/env.ts と .env.example の両方を更新すること。

ALLOWED_EMAIL_DOMAINS は必須

未設定だと起動時に失敗する。任意にすると設定漏れで誰でもログインできる穴が残るため、意図的に fail-closed にしている。

Databricks 変数は process.env を直読みする

lib/databricks-client.ts は getEnvConfig() を通さない。バッチがアプリ用の必須変数なしで動くため。env.ts の定義は API 側の検証用。ローカルでは DATABRICKS_TOKEN=$(databricks auth token -p <profile> | jq -r .access_token) で資格情報を省略できる。

PROTOTYPE_MODE

PROTOTYPE_MODE=true（既定）の間は メール送信と Google Calendar への書き込みが無効化される。コードから判定するときは env を直接読まず isEmailEnabled() / isCalendarEnabled() / isPrototypeMode() を使う。dev は既定のまま、stg は false にして実際に送信・書き込みを行う。

ALLOWED_SURVEY_IDS は空文字を許さない

未設定なら制限なし（ローカルと dev）。一方、設定されているのに空の場合は起動時エラーにしている。限定が必須の環境で値が抜けたときに、全調査が見える状態へ黙って戻らないようにするため。判定は isSurveyAllowed() / getAllowedSurveyIds() を使う。

効くのは services/survey.ts の一覧・詳細（対象外の ID は 404）と、batch/databricks-meta-sync.ts のキャッシュ対象（WHERE survey_id IN (...) で絞るのでメタ集計自体も速くなる）。

4. 起動

bun run dev
URL 内容
http://localhost:8080/health ヘルスチェック
http://localhost:8080/docs Swagger UI
http://localhost:8080/openapi.json OpenAPI 定義（Orval の入力）

frontend の手順

1. 依存関係のインストール

cd heineken-interview-arrange-frontend
bun install

2. 環境変数の設定

変数名 説明 例
NEXT_PUBLIC_API_URL バックエンドのベース URL。未設定時は http://localhost:8080 http://localhost:8080

3. API クライアントの生成

backend を起動した状態で実行する。停止していると Orval は失敗する。

bun run generate-api

http://localhost:8080/openapi.json から src/api/**（React Query フックと型）が再生成される。生成物は手で編集しない。

4. 起動

bun run dev

http://localhost:3000 にアクセスして確認する。

API を変更したときの手順

graph LR
  A[backend でルート/スキーマを修正] --> B[bun run dev で backend 起動]
  B --> C[frontend で bun run generate-api]
  C --> D[画面側のコードを修正]

よくあるエラー

Invalid environment variables:

原因: src/config/env.ts の Zod 検証に失敗している。必須変数の欠落か、形式違反（JWT_SECRET が 32 文字未満、URL 形式でないなど）。

解決策: エラーメッセージに列挙された変数を .env で修正する。

cp .env.example .env

Orval の生成が失敗する

原因: backend が起動していない、または /openapi.json が返らない。

解決策:

# 別ターミナルで backend を起動
cd ../heineken-interview-arrange-backend && bun run dev

# 疎通を確認してから再実行
curl http://localhost:8080/openapi.json | head

docker compose で Postgres が起動しない

原因: ポート 5432 が既存の PostgreSQL に使われている。

解決策:

lsof -i :5432
bun run docker:down && bun run docker:up

スキーマ変更が DB に反映されない

原因: 開発時のスキーマ反映は db:push が主。マイグレーションファイル生成（db:generate）だけでは DB は変わらない。

解決策:

bun run db:push
bun run db:studio   # Drizzle Studio で確認