放課後リンク 開発仕様

Appearance

開発環境構築手順 (Developer Setup Guide) ​

本ドキュメントでは、「放課後リンク」の全コンポーネントをローカル開発環境で立ち上げ、初期データを投入し、テストを実行するまでの手順を解説します。

1. 動作環境と開発ツールの前提条件 ​

開発を開始する前に、ローカル環境に以下のツールがインストールされていることを確認してください。

  • OS: Windows 11 (推奨) または macOS
  • Node.js: v20 以上 (LTS推奨)
  • .NET SDK: SDK 10.0 (global.jsonにより pins 10.0.300 が指定されています)
  • Android 開発環境:
    • Android Studio: Ladybug 以降
    • Android SDK: API 34 / 35
    • JDK: Gradle 9.x および Android Gradle Plugin (AGP) 8.13+ が Java 25 未サポートのため、必ず JDK 21（Android Studio 同梱の C:\Program Files\Android\Android Studio\jbr など）を使用してください。
  • IDE / エディタ:
    • VS Code: APIおよび各フロントエンドPWA開発用。
    • Visual Studio 2022 / JetBrains Rider: WinUI 3 (Management/Kiosk) および Avalonia (Kiosk Linux/Android) 開発用。

2. バックエンド API (Cloudflare Workers & D1) の起動 ​

API ディレクトリは app/api に配置されています。

2.1 依存関係のインストール ​

bash
cd app/api
npm install

2.2 データベース (Prisma & ローカル D1) の初期化 ​

Cloudflare D1 互換のローカル SQLite データベースをマイグレーションし、Prisma クライアントを生成します。

bash
# マイグレーションの実行
npx prisma migrate dev --name init

# Prisma クライアントの生成
npx prisma generate

2.3 ローカル開発サーバーの起動 ​

Wrangler (Cloudflare 開発ツール) を用いて、エッジランタイムをシミュレートしたローカルサーバーを起動します。

bash
npm run dev

起動に成功すると、デフォルトで http://localhost:8787 で API が待機します。

2.4 API テストの実行 ​

Vitest を使用して API の統合テストを実行できます。

bash
npm run test

3. 各種フロントエンド (PWA) の起動 ​

各種フロントエンドは app/Facility, app/Guardian, app/Staff に配置されています。 Facility は React + Vite + Capacitor のハイブリッド構成で、Guardian と Staff は React + Vite の PWA 構成です。

3.0 API とフロントエンドの一括起動 ​

リポジトリルートから、API と Provider/Guardian/Facility/Staff を別々のPowerShellウィンドウで一括起動できます。

powershell
# 通常モード: APIへ接続する
powershell -ExecutionPolicy Bypass -File .\scripts\start-local-stack.ps1

# デモモード: PWAはデモデータを使用する（APIも同時に起動）
powershell -ExecutionPolicy Bypass -File .\scripts\start-local-stack.ps1 -Demo

既定のポートは API 8787、Provider 5173、Guardian 5174、Facility 5175、Staff 5176 です。ポートを変更する場合は次のように指定します。

powershell
powershell -ExecutionPolicy Bypass -File .\scripts\start-local-stack.ps1 `
  -ApiPort 8790 -ProviderPort 5183 -GuardianPort 5184 -FacilityPort 5185 -StaffPort 5186

一部だけ起動する場合は -SkipProvider、-SkipGuardian、-SkipFacility、-SkipStaff を使用できます。実際には起動せず、生成されるコマンドだけ確認する場合は -DryRun を指定します。

3.1 施設業務用アプリ (Facility App) ​

bash
cd app/Facility
npm install
npm run dev

※デモモード（オフライン動作のシミュレーション）で起動する場合は以下を実行します：

bash
npm run demo:dev

3.2 保護者用アプリ (Guardian App) ​

bash
cd app/Guardian
npm install
npm run dev

※デモモードでの起動：

bash
npm run demo:dev

3.3 職員個人用アプリ (Staff App) ​

bash
cd app/Staff
npm install
npm run dev

本番相当の出退勤画面でGPS判定を使う場合は、ビルド時に施設の座標を設定します。 VITE_FACILITY_LATITUDE と VITE_FACILITY_LONGITUDE が未設定の非デモ版は、誤った東京固定座標で判定せず、位置情報未設定として打刻を停止します。デモ版だけは検証用の東京座標とQRシミュレーションを使用します。 ログイン画面の「自動ログイン」をOFFにした場合は、現在のブラウザタブ内だけで認証状態を保持し、タブを閉じると次回起動時に再ログインが必要です。

3.4 モバイル配布物の生成 ​

製品形態はアプリごとに固定しています。

アプリ正式な配布形態動作確認用の出力
FacilityAndroid APK（Capacitor）release/Facility/facility-*-offline-debug-demo.apk
GuardianブラウザPWArelease/PWA/guardian-*-offline-debug-demo.zip
StaffブラウザPWArelease/PWA/staff-*-offline-debug-demo.zip

Guardian と Staff は PWA 専用です。Android プロジェクト、Capacitor ラッパー、APK生成手順は存在せず、スマートフォンではブラウザの「ホーム画面に追加」または「インストール」を使用します。

動作確認用の成果物は、リポジトリルートから一括生成します。

powershell
pwsh -ExecutionPolicy Bypass -File ./scripts/build-demo-artifacts.ps1 `
  -Target facility,guardian,staff -Version 0.1.0 -VersionCode 1001 -Clean

本番候補はこの手順ではなく、実値の環境設定と署名鍵を要求する scripts/build-release-artifacts.ps1 を使用してください。成果物形式の詳細は release-build-runbook.md を参照します。

4. デスクトップアプリのビルド (.NET 10) ​

デスクトップアプリはソリューションファイル houkago-link.sln を介して管理されています。

4.1 管理ポータル (Management App) ​

WinUI 3 アプリケーションです。現行プロジェクトは app/Management/Management.csproj です。

bash
# ビルドの実行 (デバッグビルド)
dotnet build app/Management/Management.csproj -c Debug

ビルド完了後、実行ファイルは app/Management/bin/Debug/net10.0-windows10.0.19041.0/ などの出力ディレクトリに生成されます。

4.2 打刻端末 (Kiosk App) ​

Windows版は WinUI 3、Linux/Android版は Avalonia で構成されており、それぞれ対応するプラットフォームで動作可能です。

bash
# Windows 版 WinUI 3
dotnet build app/Kiosk/Windows/Kiosk.Windows.csproj -c Debug

# Linux 向け Avalonia Desktop
dotnet build app/Kiosk/Desktop/Kiosk.Desktop.csproj -c Debug

4.2.1 Kiosk 端末ハードウェア設定 (PaSoRi) ​

FeliCa 等を用いた IC カード打刻機能を検証する場合、以下の設定が必要です。

  • ICカードリーダー: SONY PaSoRi RC-S380 / RC-S300 等を PC に接続します。
  • ドライバ設定: FeliCa ポートソフトウェアを導入し、自己診断ツールで認識されることを確認します。
  • サービス設定: Windows の Smart Card サービスを自動起動に設定してください。

5. 初期データ（シードデータ）の投入手順 ​

開発およびデモ、またはパフォーマンステストのために、初期データの投入が必要な場合は、以下の手順を行います。 パフォーマンスとハッシュ最適化（$demo$ プレフィックスによる遅延ハッシュ生成）の観点から、npx prisma db seed は使用せず、必ず以下の専用コマンドを使用してください。

API のリッチデモシード (POST /v1/demo/seed) は破壊的操作のため、実行前にローカルAPIの環境へトークンを設定してください。トークン未設定または不一致の場合、シード処理は実行されません。

powershell
$env:DEMO_SEED_TOKEN = "ローカル専用の十分に長いランダム値"

npm run db:setup を使う場合も、同じシェルで DEMO_SEED_TOKEN を設定してから実行します。

児童名などの暗号化フィールドを含むSQLシードは、APIと同じENCRYPTION_KEYを使用します。seed_sql.tsは、環境変数、app/api/.dev.vars、開発用デフォルト値の順に読み込みます。本番・共有環境では暗号鍵をリポジトリへ保存せず、必ず環境変数またはSecretsで指定してください。

5.1 通常データ・実環境本番想定版（標準サイズ） ​

5施設・各30児童のデータ群（合計150児童）をシードします。実環境想定の動作確認に適しています。

bash
cd app/api
npm run db:demo:local

5.2 大規模データ・高負荷検証版（ラージサイズ） ​

15施設・各300児童のデータ群（合計4500児童）をシードします。高負荷検証や限界性能テストに適しています。

bash
cd app/api
npm run db:demo:local:large

5.3 ログイン確認用デフォルトアカウント ​

シードデータの投入完了後、以下のデフォルトアカウントでログイン可能です：

  • 施設管理者:
    • 新形式の例: SD3MA2AAAB / 初期パスワード: Demo123!
    • ※デモデータはパフォーマンス向上のため、初回ログイン時に $demo$loginId から $v2$ のPBKDF2ハッシュへ自動再ハッシュされます。
  • 保護者:
    • 組織コード: ログインIDに含まれるため入力不要（標準: D3M / 大規模: H3G）
    • 新形式の例: PD3MA2AAAB / 初期パスワード: Demo123!

6. 便利な開発ツールとTips ​

6.1 Prisma Studio によるデータ閲覧 ​

開発中にローカル SQLite 内のデータを GUI で確認・編集したい場合、以下のコマンドを API ディレクトリで実行することでブラウザ上で直接閲覧できます。

bash
cd app/api
npx prisma studio

ブラウザで http://localhost:5555 が開き、直感的にテーブル操作が行えます。

6.2 Wrangler CLI を用いたローカル/リモート D1 の操作 ​

ローカルまたはリモート（Cloudflare本番）の D1 に対し、直接 SQL を実行することができます。

bash
# ローカルD1へのSQL実行 (例: ユーザー一覧の取得)
npx wrangler d1 execute houkago_link_d1 --local --command "SELECT * FROM User;"

# リモート(本番)D1へのSQL実行
npx wrangler d1 execute houkago_link_d1_prod --remote --command "SELECT id, name FROM Facility;"

6.3 ローカルでのデモ用ビルド検証 ​

プロジェクト全体をデモモードでビルドし、最終的な成果物（インストーラー、Guardian/StaffのPWA ZIP、Facility/KioskのAPK等）を生成・検証するには、PowerShell スクリプトを実行します。

powershell
./scripts/build-demo-artifacts.ps1

生成された成果物は、ルート直下の release/<app>/ ディレクトリおよび release/ 直下の個別成果物に出力されます。

関連ドキュメント ​

放課後リンク 開発プロジェクト

Copyright © 2026 NGS / takao-dev. All Rights Reserved.