開発者向けマニュアル

本ページは PLATEAU-SNAP-CMS の開発者向けドキュメントです。 本ページでは、大きく分けて以下について説明します。

Note

CMS の使い方（画面操作）は「利用者向けマニュアル」を参照してください。

Note

本ページには、SNAP Appに掲載しているようなコントリビューター向け情報は含まれていません。 SNAP Appでは、コードから仕様ドキュメントを自動生成する仕組みを採用しているため、 一定の記述ルールや設計方針を開発者向けに明示しています。 一方、本CMS／Serverはそのような仕組みを前提としていないため、 特定の記述ルールを共有する必要がなく、コントリビューター向け情報は設けていません。

必要なデバイス・環境

環境として、CMSを利用するためのPCとCMSを動作させるためのサーバが必要です。 下記に動作確認済みの環境を示します。

目的 デバイス 機種名 その他 備考
CMSにアクセス PC MacBook Pro Sonoma 14.7 ローカルサーバとしても確認
CMSを動作 サーバ AWS(ECS/Fargate) Linux/X86_64/.5 vCPU/2 GiB -

前提

システム構成

PLATEAU SNAP は以下の 3 つのコンポーネントで構成されます。

コンポーネント 役割
App モバイルアプリ（画像撮影・アップロード）
Server バックエンド（データ蓄積、画像処理、モデル生成）
CMS 操作用フロントエンド（処理指示、結果確認、エクスポート）

本リポジトリ（CMS）は Server が提供する API を呼び出す側です。Server がなければ CMS 単体では動作しません。そのため、Serverの構築を先に実施してください。

※ 利用技術やフォルダ構成は README を参照してください。

通信の流れ

CMS は、画面（ブラウザ）から直接バックエンドにアクセスするのではなく、基本的に CMS 側の /api/*（Remix の API ルート）を経由して Server と通信します。

ブラウザ → CMS /api/* → CMS（サーバ側）→ Server（バックエンド）

この構成により、API キーなどの機密情報を ブラウザに配らずに運用できます。

通信レイヤーの概要

レイヤー 主なファイル 役割
React Query フック app/hooks/useApi.ts データ取得・キャッシュ・リトライ制御
内部 API ルート app/routes/api/*.ts ブラウザからのリクエストを受ける
Loader / Action app/loaders/, app/actions/ サーバー側処理の実装
サービス層 app/services/api.ts Server API の呼び出しラッパー
API クライアント app/generated/Api.ts Swagger から自動生成された型付きクライアント
HTTP 通信 app/services/axios.config.ts Axios 設定（baseURL, API Key 注入）

Serverとの連携方法

CMS が Server（バックエンド）と通信するために、接続先と認証情報を環境変数で設定します。

設定する環境変数

変数 必須 役割 例
API_URL ✅ Server のベース URL http://localhost:5000
API_KEY ✅ API 認証キー（X-API-KEY ヘッダに設定される） your-secret-key

設定方法

設定方法は環境に応じて選択してください。

方法 用途 例
コマンド直接指定 ローカル開発 API_URL="..." API_KEY="..." npm run dev
シェルで export ローカル開発 export API_URL="..." → npm run dev
.env ファイル ローカル開発 プロジェクトルートに .env を作成
Docker 環境変数 本番運用 docker-compose.yml の environment: で指定

具体的な手順は 3. ローカルでのセットアップ および 4. サーバ上でのセットアップ を参照してください。

Important

注意事項

  • .env や API キーは絶対にコミットしない（.gitignore で除外済み）
  • VITE_API_URL / VITE_API_KEY はフォールバック用ですが、本番では使用しないでください（ビルド成果物に埋め込まれ、ブラウザに露出する可能性があるため）

ローカルでのセットアップ

依存関係のインストール

npm ci

※ package-lock.json を更新する必要がある場合のみ npm install を使用してください。

起動方法

起動時に環境変数（API_URL, API_KEY）を渡す必要があります。以下の A / B / C いずれかの方法で起動してください。

方法 A: コマンドに直接指定（推奨）

API_URL="http://<server-host>:<server-port>" API_KEY="<your-api-key>" npm run dev

方法 B: 事前に export してから起動

export API_URL="http://<server-host>:<server-port>"
export API_KEY="<your-api-key>"
npm run dev

方法 C: .env ファイルに記述してから起動

# .env ファイルを作成（プロジェクトルート）
echo 'API_URL=http://<server-host>:<server-port>' >> .env
echo 'API_KEY=<your-api-key>' >> .env

# 起動
npm run dev

起動後、http://localhost:5173 にアクセスします。

Important

.env や API キーは 絶対にコミットしないでください（.gitignore で除外済み）。

サーバ上でのセットアップ（本番相当）

運用形態は固定しません（このリポジトリで可能な方法を示します）。

Node 直起動（ビルド → 起動）

  1. ビルド:
npm ci
npm run build
  1. 環境変数を設定して起動:
export API_URL="http://<server-host>:<server-port>"
export API_KEY="<your-api-key>"
npm run start

補足:

  • 待受ポートは PORT で変更できます（例: export PORT=3000）
  • 逆プロキシ（nginx 等）配下で動かす場合は、プロキシ側の設定も合わせて調整してください

Docker（compose を使う場合）

本リポジトリには docker-compose.yml が含まれています（nginx + remix 構成）。

# Docker Compose V2 の場合
docker compose up --build

# Docker Compose V1 の場合
docker-compose up --build

補足:

  • nginx 側で Basic 認証を有効化しています。認証情報は docker/nginx/.htpasswd を差し替えてください
  • Server 連携（API_URL / API_KEY）は、運用に合わせて注入してください

例（docker-compose.yml のイメージ）:

services:
  remix:
    environment:
      API_URL: "http://<server-host>:<server-port>"
      API_KEY: "<your-api-key>"

API クライアント生成

Server の API 仕様（Swagger/OpenAPI）から TypeScript の API クライアントを生成できます。

npm run api:generate

生成されたコードは app/generated/ に出力されます。

Important

app/generated/ 配下のファイルは自動生成されるため、手動で編集しないでください。

品質を維持するためのチェック

テスト

本プロジェクトでは Vitest を使用してテストを行います。

テストコマンド一覧

テストは ~/generated/apiService をモックしているため、Server を起動せずに実行できます。

コマンド 用途
npm run test テスト実行
npm run test:watch ファイル変更を監視して自動実行
npm run test:coverage カバレッジレポート付きで実行
npm run test:ui ブラウザ UI でテスト実行

関連ファイル

テストは app/test/ ディレクトリに集約されています。

app/test/
├── setup.ts              # グローバルセットアップ
└── integration/          # 統合テスト
    ├── actions/          # アクションテスト
    ├── component/        # コンポーネントテスト
    │   ├── common/       # 共通コンポーネント
    │   └── features/     # 機能コンポーネント
    ├── hook/             # カスタムフックテスト
    ├── loaders/          # ローダーテスト
    ├── services/         # サービステスト
    └── utils/            # ユーティリティテスト

テストを作成する際の命名規則

種別 ファイル名
コンポーネント ComponentName.test.tsx
フック useHookName.test.ts
ユーティリティ utilityName.test.ts
サービス serviceName.test.ts
ローダー / アクション loaderName.test.ts

コード品質チェック

Linting（ESLint）

# チェックのみ
npm run lint:check

# 自動修正
npm run lint

型チェック（TypeScript）

npm run typecheck

スペルチェック

# チェックのみ
npm run spellcheck

# 自動修正
npm run spellcheck:fix

コードフォーマット（Prettier）

# フォーマット実行
npm run format

# フォーマットチェックのみ
npm run format:check

コミット前のチェック

以下のコマンドで一括チェックを実行できます。

npm run pre-commit

これは lint:check → typecheck → spellcheck → test を順に実行します。

設定ファイル

各ツールの設定ファイルは以下の通りです。

ファイル ツール 主な設定内容
.eslintrc.cjs ESLint TypeScript 対応、React ベストプラクティス、import 順序、アクセシビリティルール
.prettierrc Prettier コードフォーマット（80文字幅、2スペースインデント、trailing comma）
.cspell.json cspell スペルチェック（プロジェクト固有の単語、技術用語のホワイトリスト）
vitest.config.ts Vitest テスト環境（JSDOM、カバレッジ、パスエイリアス）