放課後リンク 開発仕様

Appearance

リリースビルド手順 (Release Build Runbook) ​

本ドキュメントでは、「放課後リンク」の各クライアントアプリケーションをビルドし、リリースまたはテスト用の配布用パッケージ（バージョン 0.1.0 以降）を作成するための手順および成果物の生成・配置ルールを解説します。

1. 運用方針（サブモジュールごとのリリース・配置ルール） ​

バージョン 0.1.0 以降、ビルド成果物およびリリース用配布パッケージは、親リポジトリ直下の build/<app>/ および release/ 配下に個別に生成・配置されます。

1.1 テスト段階におけるビルドモード ​

  • オフライン・デモ・デバッグ版 (offline demo debug): プロジェクトは現在テスト段階にあります。原則として、すべてのコンポーネントでデモビルドスクリプトを用い、オフラインデモ用の設定でビルドを実施してください。
  • インストーラー/パッケージ作成の許可: バージョン 0.1.0 のリリース登録においては、指定された形式（インストーラー、APK、ZIP）の作成およびパッケージングが明示的に許可・推奨されます。

1.2 サブモジュール別リリース成果物形式・生成ルール ​

各アプリの成果物はルート直下の release/ 配下に配置し、アプリごとにサブフォルダを分けます。生成ルールは以下の通りです。

  1. 💻 管理ポータル (app/Management - WinUI 3)
    • 形式: Windows 自己完結型バイナリフォルダ
    • 成果物: インストーラーを明示的に指定しない限り、実行ファイルと依存関係を含むフォルダを release/Management/ に配置。
  2. 🖥️ 入退室端末 (app/Kiosk - WinUI 3 & Avalonia)
    • 形式: マルチプラットフォームバイナリ & APK
    • 成果物:
      • WinUI 3 ➔ Windows版バイナリ（パッケージしたもの）
      • Avalonia (Desktop/Kiosk.Desktop.csproj) ➔ Linux版バイナリ（パッケージしたもの）
      • Avalonia (Android/Kiosk.Android.csproj) ➔ Android版 APK (.apk)
    • 上記3種類すべてを生成し、release/Kiosk/ に一括配置します。
  3. 📲 PWAアプリ (app/Guardian, app/Staff - React PWA)
    • 形式: ZIPパッケージのみ
    • 成果物:
      • app/Guardian と app/Staff の静的ファイル ➔ Viteがルートの build/Guardian / build/Staff に生成した本番ビルドをそれぞれ ZIP アーカイブ化 したもの。
      • Guardian/StaffにはAndroidプロジェクト、Capacitorラッパー、APK生成スクリプトを用意しません。モバイル確認はブラウザのPWAインストール機能で行います。
  4. 🏢 施設業務用アプリ (app/Facility - Capacitor Hybrid)
    • 形式: Android APK
    • 成果物: ビルドされた Android 用 APK (.apk) のみを release/Facility/ に配置。
  5. 🌐 API (app/api - Cloudflare Workers)
    • 形式: なし（生成不要）
    • 運用: サーバーレス環境（Cloudflare Workers）に直接デプロイされるため、配布用の物理成果物の生成や配置は一切行いません。

1.3 本番リリース候補の共通ゲート ​

テスト用デモ成果物と本番候補を混在させないため、本番候補は build-demo-artifacts.ps1 ではなく、専用の build-release-artifacts.ps1 を使用します。このスクリプトは次を満たさない限り成果物を作成せずに停止します。

  • app/Facility/.env.production、app/Guardian/.env.production、app/Staff/.env.production の実値設定。FacilityはHTTPS API・更新署名公開鍵・Firebase設定、Guardian/StaffはHTTPS API・Firebase設定とVITE_DEMO_MODE=falseを使用します。
  • Facility/Kiosk Android対象では本番keystore、alias、keystore password、key password。パスワードは環境変数で渡し、リポジトリやログに保存しない。
  • Kiosk Androidでは package ID、版数、application-debuggable なし、apksigner verify 成功。
  • 生成後の全成果物は release/release-manifest-<version>.json と SHA-256 checksum に記録する。

build-release-artifacts.ps1 の1回の実行が本番候補の単位です。実行開始時に、デモ成果物を残したまま、既存の *-release-real* 成果物とリリースmanifestをクリーニングします。そのため -Target management のような部分ターゲット実行でも、未選択ターゲットの旧本番候補が新しいmanifestに混在しません。前提検証またはビルドに失敗した場合はmanifestを作成しないため、成功メッセージだけを承認根拠にせず、終了コードとmanifest/hashを確認してください。

1.4 本番候補ファイル名 ​

本番候補は、接続形態・ビルド種別・運用データ種別を含むonline-release-realまたはoffline-release-realを使用します。これはビルドスクリプト、成果物検証、manifestの対象を一意に保つためです。納品先が短いファイル名を要求する場合の*-online.apk等へのリネームは、manifestとSHA-256を固定した後の配布工程に限定します。

Android署名を含む全クライアント候補の生成例（秘密値は表示しない）：

powershell
$env:ANDROID_RELEASE_KEYSTORE = 'C:\secure\amga-release.jks'
$env:ANDROID_RELEASE_KEY_ALIAS = 'amga-release'
$env:ANDROID_RELEASE_KEYSTORE_PASSWORD = '<secret-from-secret-store>'
$env:ANDROID_RELEASE_KEY_PASSWORD = '<secret-from-secret-store>'
pwsh -ExecutionPolicy Bypass -File ./scripts/build-release-artifacts.ps1 -Target all -Version 0.1.0 -VersionCode 1

署名鍵や本番環境ファイルがまだ準備できていない場合は、コードとデスクトップ配布物だけを次のように検証できます。この結果は正式リリース承認ではありません。

powershell
pwsh -ExecutionPolicy Bypass -File ./scripts/build-release-artifacts.ps1 -Target api,management,kiosk-windows,kiosk-linux -Version 0.1.0 -VersionCode 1

2. アプリ別ビルド手順 ​

2.1 施設業務用アプリ (Facility APK) ​

Capacitor を用いたハイブリッドアプリであり、Android 端末向けにビルドします。

前提環境 ​

  • Node.js & npm
  • Android SDK (Android Studio による管理を推奨)
  • JDK 21 (Gradle 9.x / Android Gradle Plugin 8.13+ が Java 25 を未サポートのため、Android Studio同梱の JDK 21 などの使用を推奨。Java 25 を標準としている環境ではビルド時にエラーとなるため注意)。

手順 ​

powershell
# 1. 前提チェックスクリプトの実行
pwsh -ExecutionPolicy Bypass -File app/Facility/scripts/check-android-prereqs.ps1

# 2. オフライン・デモ・デバッグ版APKのビルド (JDK 21を明示的に指定して実行)
$env:GRADLE_JAVA_HOME="C:\Program Files\Android\Android Studio\jbr"
pwsh -ExecutionPolicy Bypass -File app/Facility/scripts/build-apk-release.ps1 -VersionName 0.1.0 -VersionCode 1001 -DemoMode
  • 成果物出力先: release/Facility

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

WinUI 3 (.NET 10) アプリケーションです。接続モードと API 接続先は初回起動時の SetupWindow で設定し、AppStateStorage がローカルに保存します。

手順 ​

powershell
# オフライン・デモ・デバッグ用のフォルダを生成（標準手順）
pwsh -ExecutionPolicy Bypass -File ./scripts/build-demo-artifacts.ps1 -Target management -Version 0.1.0

# フォルダに加えてZIPとSHA-256チェックサムを作成する場合
pwsh -ExecutionPolicy Bypass -File ./scripts/build-offline-debug-demo-installerZ.ps1 -Version 0.1.0
  • 中間publish出力先: build/Management/management-0.1.0-offline-debug-demo
  • 配布フォルダ: release/Management/management-0.1.0-offline-debug-demo
  • 任意のZIP: release/Management/management-0.1.0-offline-debug-demo.zip
  • チェックサム: release/Management/management-0.1.0-offline-debug-demo.sha256

標準ビルドはDebug + win-x64 + self-contained + WindowsPackageType=Noneです。テスト段階ではこのオフライン・デモ・デバッグ構成を使用し、オンライン版や正式Release構成は別途リリース判定を通してから作成します。 NuGetのユーザー設定を参照できない隔離環境で、既存の復元済み資産を使う場合は各コマンドに-NoRestoreを追加してください。

2.2.1 本番Managementリリースゲート ​

本番用のManagementだけを検証する場合は、次のスクリプトを使用します。Release + self-contained + win-x64で発行し、必須ファイル、obj/bin混入、版数、SHA-256マニフェストを検証します。

powershell
pwsh -ExecutionPolicy Bypass -File ./scripts/build-release-artifacts.ps1 -Target management -Version 0.1.0

本番版は実際のオンライン接続や認証後画面の受入確認を代替しません。モバイル版を含む全体リリースでは、本番.env.production、署名鍵、外部サービス接続を別途準備してください。

Release版をデモ版と同じWindowsユーザー領域で起動した場合、既知のデモ組織・デモログイン設定は自動的に.legacy-demo-<UTC>-<GUID>へ退避され、初回セットアップ画面を表示します。設定ファイルは削除しないため、必要な場合は退避ファイルから復旧できます。オフライン設定と接続状態表示が食い違わないよう、起動モードは同じ解決規則を使用します。

Release版は既知のデモ管理者アカウントを自動生成しません。オフライン開始を利用する端末には、オンライン同期または安全なプロビジョニングで暗号化された職員アカウントを先に登録し、初期パスワードを運用手順に従って変更してください。

2.3 入退室端末 (Kiosk App) ​

Avalonia / WinUI 3 構成の端末アプリであり、Linux用およびWindows用のバイナリを生成します。

手順 ​

powershell
# Kiosk の Windows / Linux / Android オフライン・デモ・デバッグ版を生成
pwsh -ExecutionPolicy Bypass -File ./scripts/build-demo-artifacts.ps1 -Target kiosk -Version 0.1.0
  • 成果物出力先: build/Kiosk および release/Kiosk

3. デモ用一括ビルド手順 ​

プロジェクトのすべてのコンポーネントを一括してオフラインデモ用にビルドするには、ルートディレクトリにある統合スクリプトを実行します。

powershell
# 0.1.0 のオフライン・デモ・デバッグ版を全クライアント一括ビルド
pwsh -ExecutionPolicy Bypass -File ./scripts/build-demo-artifacts.ps1 -Version 0.1.0 -VersionCode 1001

3.1 実行プロセスと成果物の変換・配置 ​

このスクリプトは以下のシーケンスで実行され、成果物をルートの build/ および release/ ディレクトリに集約します。

  1. API: app/api にて npm 依存関係をインストール・ビルドし、Cloudflare Workersに直接デプロイするため成果物は配置しません。
  2. Management: app/Management 配下の C# ソリューションを publish し、Windows オフライン用自己完結フォルダとして release/Management/ に出力します。
  3. Kiosk: Windows用バイナリ、Linux用バイナリ、および Android用 APK を生成し、release/Kiosk/ 配下に配置します。
  4. Facility: VITE_DEMO_MODE=true を明示してReactをViteのデモモードでビルドし、CapacitorのデバッグAPKを配置します。Staff/Guardianは同じデモモードでPWA用ZIPのみを配置します。

4. 配布パッケージの統合整理 ​

ビルドされた各成果物を、配布用・運用チーム向けに整理するための手順です。全ての成果物は release/[submodule-name]/ の規則に従い格納されます。

powershell
# release/ 配下の各モジュール出力物を最終的な状態に整理・クリーニング
pwsh scripts/prepare-release-layout.ps1 -Version 0.1.0

配布フォルダの構造案 ​

  • release/Facility/ (施設業務用アプリ APK)
  • release/PWA/ (Guardian/Staff PWA 用 ZIPのみ)
  • release/Management/ (管理ツール実行ファイル一式フォルダ)
  • release/Kiosk/ (打刻端末用 Windows/Linuxバイナリ & Android APK)

5. 本番リリースゲート ​

本番Android APKを作る前に、Facility/Kioskの接続先、デモモード、更新マニフェスト署名検証、Firebase Push設定を機械的に確認します。Guardian/StaffはPWA ZIPとしてHTTPS API、デモモード、Firebase設定を検証します。.env.production.example は値の記入例であり、そのままでは合格しません。実値を .env.production に設定し、秘密情報はリポジトリへコミットしないでください。

powershell
pwsh -ExecutionPolicy Bypass -File scripts/verify-release-config.ps1 -App facility -EnvFile app/Facility/.env.production -RequireFirebase
pwsh -ExecutionPolicy Bypass -File scripts/verify-release-config.ps1 -App guardian -EnvFile app/Guardian/.env.production -RequireFirebase
pwsh -ExecutionPolicy Bypass -File scripts/verify-release-config.ps1 -App staff -EnvFile app/Staff/.env.production -RequireFirebase

APKの本番ビルドでは、Android Studio同梱JDK 21と本番署名鍵を必ず指定します。パスワードをコマンド履歴へ残さないよう、CIのSecretまたは一時的な環境変数から渡してください。

powershell
$env:GRADLE_JAVA_HOME = "C:\Program Files\Android\Android Studio\jbr"
pwsh -ExecutionPolicy Bypass -File app/Facility/scripts/build-apk-release.ps1 -VersionName 0.1.0 -VersionCode 1001 `
  -KeystorePath $env:HL_RELEASE_KEYSTORE -KeystoreAlias $env:HL_RELEASE_ALIAS `
  -KeystorePassword $env:HL_RELEASE_STORE_PASSWORD -KeyPassword $env:HL_RELEASE_KEY_PASSWORD

Guardian/StaffのPWA ZIPは release/PWA/ に置き、Facility/KioskのAPKとは別に最終検査します。デモ成果物はデバッグ用のため、本番検査では -AllowDebug を付けずに実行してください。

powershell
pwsh -ExecutionPolicy Bypass -File scripts/verify-release-artifacts.ps1 -VersionName 0.1.0 -VersionCode 1 -RequireManifest

フロントエンドの本番設定やAndroid署名鍵が未提供で、Management/Kioskだけを先に検証する場合は、検証対象を明示します。対象を省略すると、Facility/KioskのAPK・AABとGuardian/StaffのPWA ZIPも必須になります。

powershell
pwsh -ExecutionPolicy Bypass -File scripts/verify-release-artifacts.ps1 `
  -VersionName 0.1.0 -VersionCode 1 `
  -Target management,kiosk-windows,kiosk-linux -RequireManifest

テスト段階の成果物を検査する場合だけ、デバッグAPKを明示的に許可します。

powershell
pwsh -ExecutionPolicy Bypass -File scripts/verify-release-artifacts.ps1 -VersionName 0.1.0 -VersionCode 1001 -AllowDebug

verify-release-artifacts.ps1 -RequireManifest は、APKのパッケージID、versionName、versionCode、debuggableフラグ、AABのZIP構造とJAR署名、PWA ZIPの index.html / sw.js、manifestの全ファイルサイズ・SHA-256、manifest自身のSHA-256 sidecarを確認します。実機インストール、Firebase通知、実APIログイン、FacilityのCloudflare更新署名の運用確認は別のリリース承認項目です。

6. トラブルシューティング ​

6.1 フロントエンド（PWA/Capacitor）ビルド時の "@houkago-link/shared" 依存性エラー ​

Vite / Rolldown ビルド中に Rolldown failed to resolve import "@houkago-link/shared" エラーが発生してビルドが中断される場合があります。

  • 原因: 各 PWA (Guardian, Staff, Facility) がルート共有モジュールである @houkago-link/shared への依存関係を解決できていないか、シンボリックリンク（Lerna/Workspace等）が正しく張られていない可能性があります。
  • 対処法: 各プロジェクトディレクトリにおいて、npm install を再実行して package.json および tsconfig.json のワークスペース定義をリロードしてください。
    bash
    # 修正手順の例
cd app/Guardian
npm install
npx cap sync

6.2 Android SDK / Java バージョン不一致エラー ​

Gradle ビルド実行時に Unsupported class file major version や SDK パスが見つからない旨のエラーが出る場合があります。

  • 対処法:
    • local.properties に正しい SDK パス（例: sdk.dir=C:\\Users\\[ユーザー名]\\AppData\\Local\\Android\\Sdk）が設定されているか確認します。
    • GRADLE_JAVA_HOME を Android Studio 同梱の JDK 21（C:\Program Files\Android\Android Studio\jbr）に設定してください。Java 25は使用しません。

関連ドキュメント ​

7. 明示的な高負荷検証用・ローカル開発版ビルド手順 ​

本セクションは、テスト段階の標準（オフライン・デモ・デバッグ版）とは異なる構成を明示的に検証する場合だけ使用します。大規模データまたはオンライン・ローカル版を必要としない通常の動作確認は、3章の build-demo-artifacts.ps1 を使用してください。

7.1 API（ローカル高負荷版の起動） ​

APIサーバーで高負荷テスト用の大規模シードデータを投入し、ローカルで起動する手順です。

powershell
# 1. API ディレクトリに移動し、大規模なシードデータを流し込んでDBを初期化
cd app/api
npm.cmd run db:demo:local:large

# 2. API サーバーをローカルで起動 (localhost:8787 で稼働)
npm.cmd run dev

7.2 管理ポータル (app/Management) ​

オフライン高負荷版とオンラインローカル版は同じ Management.csproj から publish します。モードと API 接続先は初回起動時の SetupWindow で選び、AppStateStorage が暗号化してローカルに保存します。

7.2.1 オフライン 高負荷版 ​

  1. 以下のコマンドで publish フォルダを生成します：
powershell
dotnet publish app/Management/Management.csproj -c Release -r win-x64 -p:Platform=x64 -p:SelfContained=true -p:PublishSelfContained=true -p:UseAppHost=true -o release/Management/management-1.0.0-offline-release-large --self-contained true

7.2.2 オンライン運用版 ​

Managementはオンライン専用・オフライン専用に分かれた別バイナリではなく、同じ自己完結Windows x64バイナリを初回セットアップで切り替えて使用します。オンライン運用の配布物は、自己完結設定・版数・manifest検証を含む正規の本番発行スクリプトで生成してください。

powershell
pwsh -ExecutionPolicy Bypass -File ./scripts/build-release-artifacts.ps1 -Target management -Version 0.1.0

生成された release/Management/management-0.1.0-offline-release-real を起動し、初回セットアップで次を設定します。

  1. 「起動時にオフラインモードで開始する」をオフにする。
  2. APIベースURLに /v1 まで含めた本番HTTPS URL（例: https://api.example.com/v1）を入力する。
  3. 保存後、ログイン画面の接続状態が「オンライン・同期中」になることを確認する。

旧来の dotnet publish 直接実行は、Release資産の状態によってFramework-dependent成果物を作る可能性があるため、オンライン配布には使用しません。実API認証、認証後画面、権限別操作の受入確認は本番アカウントと接続先を用いた別ゲートです。

7.3 施設業務用アプリ (app/Facility) ​

ビルドスクリプトの -DemoMode スイッチの有無でビルドを切り替えます。

7.3.1 オフライン 高負荷版 APK ​

powershell
& pwsh -File app/Facility/scripts/build-apk-release.ps1 -DemoMode -VersionName "1.0.0-offline-release-large" -VersionCode 1001

7.3.2 オンライン ローカル版 APK ​

※事前に必要に応じて接続先 API_URL を .env や localStorage にてローカルAPIに設定してください。

powershell
& pwsh -File app/Facility/scripts/build-apk-release.ps1 -VersionName "1.0.0-online-debug-demo" -VersionCode 1002

7.4 職員アプリ ＆ 保護者アプリ (app/Staff, app/Guardian) ​

GuardianとStaffはPWA専用です。Android/CapacitorプロジェクトやAPK生成手順は存在しません。

7.4.1 職員アプリ (app/Staff) ​

  • オフライン デモ PWA:
    powershell
    pwsh -ExecutionPolicy Bypass -File ./scripts/build-demo-artifacts.ps1 -Target staff -Version 0.1.0
  • オンライン ローカル PWA:
    powershell
    cd app/Staff
npm.cmd run build
Compress-Archive -Path ../../build/Staff/* -DestinationPath ../../release/PWA/staff-1.0.0-online-debug-demo.zip -Force
cd ../..

7.4.2 保護者アプリ (app/Guardian) ​

  • オフライン デモ PWA:
    powershell
    pwsh -ExecutionPolicy Bypass -File ./scripts/build-demo-artifacts.ps1 -Target guardian -Version 0.1.0
  • オンライン ローカル PWA:
    powershell
    cd app/Guardian
npm.cmd run build
Compress-Archive -Path ../../build/Guardian/* -DestinationPath ../../release/PWA/guardian-1.0.0-online-debug-demo.zip -Force
cd ../..

7.5 入退室端末 (app/Kiosk) ​

ソースコードを手動編集せず、MSBuild プロパティ /p:KioskDemoMode=true|false でモードを指定して Windows、Linux、Android (APK) を生成します。

7.5.1 Staff オフライン 高負荷版 ​

  1. 以下のコマンドを実行します：
powershell
# Windows WinUI 3 バイナリ
dotnet publish app/Kiosk/Windows/Kiosk.Windows.csproj -c Release -r win-x64 -o release/Kiosk/kiosk-1.0.0-offline-release-large-win --self-contained true /p:PublishSingleFile=false /p:KioskDemoMode=true /p:UsedAvaloniaProducts=

# Linux シングルバイナリ
dotnet publish app/Kiosk/Desktop/Kiosk.Desktop.csproj -c Release -r linux-x64 -o release/Kiosk/kiosk-1.0.0-offline-release-large-linux --self-contained true /p:PublishSingleFile=true /p:KioskDemoMode=true /p:UsedAvaloniaProducts=

# Android APK
dotnet publish app/Kiosk/Android/Kiosk.Android.csproj -c Release -f net10.0-android -r android-arm64 -o release/Kiosk/kiosk-1.0.0-offline-release-large /p:AndroidPackageFormat=apk /p:KioskDemoMode=true /p:UsedAvaloniaProducts=

6.5.2 Staff オンライン ローカル版 ​

  1. 以下のコマンドを実行します：
powershell
# Windows WinUI 3 バイナリ
dotnet publish app/Kiosk/Windows/Kiosk.Windows.csproj -c Release -r win-x64 -o release/Kiosk/kiosk-1.0.0-online-release-demo-win --self-contained true /p:PublishSingleFile=false /p:KioskDemoMode=false /p:UsedAvaloniaProducts=

# Linux シングルバイナリ
dotnet publish app/Kiosk/Desktop/Kiosk.Desktop.csproj -c Release -r linux-x64 -o release/Kiosk/kiosk-1.0.0-online-release-demo-linux --self-contained true /p:PublishSingleFile=true /p:KioskDemoMode=false /p:UsedAvaloniaProducts=

# Android APK
dotnet publish app/Kiosk/Android/Kiosk.Android.csproj -c Release -f net10.0-android -r android-arm64 -o build/Kiosk.Android-Online /p:AndroidPackageFormat=apk /p:KioskDemoMode=false /p:UsedAvaloniaProducts=

7. 全構成の明示的ビルド ​

旧手順との互換性のため build-all-suites.ps1 は残していますが、現在は標準のオフライン・デモ・デバッグ版を build-demo-artifacts.ps1 に委譲します。高負荷版やオンライン・ローカル版は、この節の明示的な個別コマンドを使用してください。

powershell
pwsh -ExecutionPolicy Bypass -File ./scripts/build-all-suites.ps1

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

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