ディレクトリ構成

ワークスペース全体

ワークスペースのルート自体は git リポジトリではなく、独立した 4 つのリポジトリと設計ドキュメント群で構成される。

design/
├── heineken-survey-design-backend/    # API サーバー (Hono + Bun + Drizzle / PostgreSQL)
├── heineken-survey-design-frontend/   # Web UI (Next.js 15 App Router)
├── Lab-web-extension/                 # Chrome 拡張 (Plasmo)
├── heineken-survey-design-docs/       # 本ドキュメント (MkDocs Material)
├── integration-tests/                 # dev 環境に対する Playwright 統合テスト
├── cs-api-logs/                       # CS 編集画面の実機 API トラフィック
└── *.md                               # 実装計画・CS との仕様差分分析

ディレクトリ	説明
`heineken-survey-design-backend/`	REST API。AWS Lambda 上でコンテナイメージとして動作する
`heineken-survey-design-frontend/`	調査設計担当者が操作する Web UI
`Lab-web-extension/`	Creative Survey への投入・取り込みを行う Chrome 拡張
`heineken-survey-design-docs/`	このドキュメントサイト
`integration-tests/`	dev 環境に対する Playwright テスト（独立ディレクトリ）
`cs-api-logs/`	CS の API 仕様解明のために採取した実機ログ

ルート直下の設計ドキュメント

ファイル	内容
`branch-logic-current-state-and-cs-diff.md`	分岐機能の現状と CS との差分整理。実機ログからの確定事項
`branch-cs-parity-implementation-plan.md`	CS 同等化の実装計画とフェーズ分け
`free-text-multi-fields-implementation-plan.md`	FA 複数回答欄の実装プラン
`text-matrix-implementation-plan.md`	テキストマトリクス設定 UI の実装プラン
`cs-api-log-collection-guide.md`	CS 実機ログの収集手順
`cs-import-test-cases.md`	CS 投入テストの観点（CP / I / R のチェックリスト）

backend

heineken-survey-design-backend/
├── src/
│   ├── index.ts                  # ローカル起動のエントリーポイント
│   ├── lambda.ts                 # AWS Lambda のエントリーポイント
│   ├── migrate-handler.ts        # マイグレーション実行 Lambda のエントリーポイント
│   ├── app.ts                    # createApp(): 認証ミドルウェアと router の登録
│   ├── routes/                   # API ルート定義とハンドラ
│   ├── repositories/             # データアクセス層 (権限判定・トランザクション)
│   ├── db/                       # Drizzle スキーマ・型・接続
│   ├── lib/                      # 認証・OpenAPI スキーマ・共通処理
│   ├── types/                    # ドメイン型
│   ├── scripts/                  # OpenAPI 書き出し・マイグレーション・シード
│   └── test/                     # テストヘルパー
├── drizzle/                      # 生成されたマイグレーション SQL
├── openapi.json                  # 書き出された OpenAPI ドキュメント
├── Dockerfile                    # API Lambda のコンテナイメージ
└── Dockerfile.migration          # マイグレーション Lambda のコンテナイメージ

ディレクトリ	説明
`src/routes/`	リソース単位のルート定義。`surveys` / `sections` / `questions` / `versions` / `permissions` / `question-library` / `users` / `imports`
`src/repositories/`	`survey-store.ts`（案件まわり全般）と `import-store.ts`（外部取り込み）。DB 操作と権限判定をここに閉じ込める
`src/db/`	`schema.ts`（DB 構造の唯一の正）・`models.ts`（推論型）・`client.ts`（接続）
`src/lib/`	`auth.ts`（ユーザー解決・管理者判定）・`openapi-schemas.ts`（Zod スキーマ集約）・`openapi.ts`・`renumber-questions.ts`（設問コード振り直しの計算。純粋関数）
`src/types/domain.ts`	API とアプリケーションで共有するドメイン型

テストは対象と同じ階層に *.test.ts として置く（例: src/app.test.ts）。

frontend

src/ を持たず、ルート直下に app/ components/ lib/ を置く構成。

heineken-survey-design-frontend/
├── app/                          # App Router
│   ├── login/                    # ログイン
│   ├── surveys/                  # 案件一覧・新規作成・詳細・セクション・プレビュー
│   ├── library/                  # 質問ライブラリ
│   └── api/auth/[...nextauth]/   # next-auth のハンドラ
├── components/
│   ├── app-shell/                # サイドバー・ヘッダを含む共通シェル
│   ├── common/                   # 汎用 UI (ボタン・バッジ・ダイアログ等)
│   ├── providers/                # 認証・TanStack Query の Provider
│   ├── surveys/                  # 案件・セクション・設問・プレビューの画面本体
│   └── library/                  # 質問ライブラリの画面本体
├── lib/
│   ├── api/                      # orval 生成の API クライアント (手編集禁止)
│   ├── orval/client.ts           # customFetch (共通ヘッダの付与)
│   ├── surveys/                  # 分岐評価・バリデーション等のドメインロジック
│   └── format/                   # 日時整形などのユーティリティ
├── styles/                       # 共通 SCSS
├── types/                        # 共有型
├── scripts/                      # OpenAPI 正規化・orval パッチ・husky セットアップ
├── _templates/                   # hygen のコンポーネント雛形
├── middleware.ts                 # /surveys/* /library/* の認証保護
└── Dockerfile                    # App Runner 用のコンテナイメージ

ディレクトリ	説明
`app/`	ルーティング。`page.tsx`（サーバー）と `page-client.tsx`（クライアント）を対で置く
`components/`	1 コンポーネント 1 ディレクトリ。`index.tsx` + `index.module.scss`
`lib/surveys/`	UI に依存しないドメインロジック。分岐評価・バリデーション・カスタムフック
`lib/api/`	orval の生成物。手編集禁止

画面パスと対応ディレクトリ

画面	パス	実装
ログイン	`/login`	`components/auth/login-page-client/`
案件一覧	`/surveys`	`components/surveys/surveys-page-client/`
新規作成	`/surveys/new`	`components/surveys/new-survey-client/`, `survey-theme-form/`
案件詳細	`/surveys/[id]`	`components/surveys/survey-detail-client/`, `survey-permission-panel/`, `survey-version-panel/`
セクション一覧	`/surveys/[id]/sections`	`components/surveys/section-list-client/`
セクション詳細	`/surveys/[id]/sections/[sectionId]`	`components/surveys/section-detail-client/`
プレビュー	`/surveys/[id]/preview`	`components/surveys/survey-preview/`
質問ライブラリ	`/library`	`components/library/question-library-page-client/`

Chrome 拡張

Lab-web-extension/
├── src/
│   ├── background.ts                       # バックグラウンドスクリプト
│   ├── popup/                              # 拡張のポップアップ UI
│   ├── contents/
│   │   ├── creative-survey-overlay.tsx     # CS 画面に重ねる操作パネル
│   │   └── cs-api-logger.ts                # CS の API トラフィック記録
│   ├── components/creative-survey/         # 投入 UI・API ログパネル
│   ├── providers/                          # Theme / SurveyUploader の Provider
│   ├── types/                              # CS API・設計ツール JSON の型定義
│   └── utils/creative-survey/
│       ├── api.ts                          # CS API クライアント
│       ├── constants.ts                    # answer_type / API URL
│       ├── plan/build-import-plan.ts       # 出力 JSON → CS 投入プラン (純粋関数)
│       ├── execute-import-plan.ts           # プランに沿って CS API を呼び出す
│       └── reset-survey.ts                 # CS 側の調査票をリセットする
└── cs-import-test-cases.md                 # CS 投入テストの観点

CS への投入は「変換（プランの組み立て）」と「実行（API 呼び出し）」を分離している。変換が純粋関数なので、CS の API を呼ばずに Vitest で網羅的にテストできる。

flowchart LR
    Json[調査票 JSON] --> Build[build-import-plan.ts<br/>純粋関数]
    Build --> Plan[投入プラン]
    Plan --> Exec[execute-import-plan.ts]
    Exec --> CS[(Creative Survey API)]

integration-tests

integration-tests/
├── config.ts                     # dev の URL と API 用アカウント
├── playwright.config.ts          # Playwright 設定 (workers: 1, headless: false)
├── tests/
│   ├── 00-smoke.spec.ts          # dev への疎通確認
│   ├── 01-build-survey.spec.ts   # サーベイ構築 (CP1〜CP13)
│   └── 02-preview-run.spec.ts    # プレビュー走行 (R1〜R28)
├── pages/                        # 画面操作 (設問エディタ / 分岐 / 表示ロジック / プレビュー)
├── lib/                          # dev API 直叩き・走行ロジック・待機ヘルパー
├── fixtures/scenario.ts          # 設問表 (Q1〜Q13) の定義
└── scripts/                      # 認証状態の保存・後片付け・CS ログ照合

docs（本サイト）

heineken-survey-design-docs/
├── mkdocs.yml                    # サイト設定・ナビゲーション・i18n
├── pyproject.toml                # MkDocs の依存定義 (uv 管理)
└── docs/
    ├── home.{ja,en}.md
    ├── link.{ja,en}.md
    ├── business-domain/          # プロダクト・登場人物・機能・データモデル
    └── development/              # セットアップ・API・DB・インフラ・規約

日本語版は *.ja.md、英語版は *.en.md として同じディレクトリに置く（mkdocs-static-i18n の suffix 方式）。

新ファイルを追加するとき

追加するもの	置き場所
API のエンドポイント	backend `src/routes/<リソース>.ts`（新規リソースなら `src/app.ts` に登録を追加）
DB 操作	backend `src/repositories/survey-store.ts`（外部取り込みは `import-store.ts`）
テーブル定義	backend `src/db/schema.ts` → `bun run db:generate`
リクエスト / レスポンススキーマ	backend `src/lib/openapi-schemas.ts`
ドメイン型	backend `src/types/domain.ts`
画面	frontend `app/<パス>/page.tsx` + `page-client.tsx`、本体は `components/<ドメイン>/`
汎用 UI コンポーネント	frontend `components/common/`（`bun run new:common` で雛形生成）
画面固有のコンポーネント	frontend `components/<ドメイン>/`（`bun run new:component`）
UI に依存しないロジック	frontend `lib/surveys/` に純粋関数として置き、Vitest でテストする
CS 変換ロジック	拡張 `src/utils/creative-survey/plan/build-import-plan.ts` + 同名の `.test.ts`
統合テストのシナリオ	`integration-tests/tests/` と `fixtures/scenario.ts`