Fincs

横断/運用基盤 / PWA

横断/運用基盤 / PWA

本ページは 2 段構成。上段が biz/CS 向け（ユーザー提示可）、下段（## 🔧 実装詳細 以降）が dev 向け。biz/CS がユーザーへ提示・転用してよいのは上段のみ。

概要

fincs サービスを PWA（Progressive Web App）として提供するための基盤レイヤ。Web ブラウザから fincs を「アプリのように」ホーム画面に追加して使えるようにし、起動高速化・オフライン対応の一部・通知受信などのアプリ的体験を提供する。

主な構成要素:

  • PWA インストール対応: ホーム画面追加用のメタ情報（マニフェスト）・アイコン提供
  • Service Worker: 静的アセットの事前キャッシュ・通知受信・OS バッジ更新を担当
  • PWA 起動時の自動遷移: ログイン済みユーザーが PWA を起動した際、最後に訪問していた講座ページへ直接遷移する仕組み
  • 配信キャッシュの無効化: リリース時に CDN（CloudFront）のキャッシュを全パス無効化し、最新版を即座に配信
  • 更新検知 + リロード促進: 新バージョンがリリースされたタイミングで内部的に検知し、必要に応じて画面リロードを促す
  • ストレージ容量管理: ブラウザの localStorage が満杯にならないよう、自動で不要なキャッシュ痕跡を削除する仕組み

主な利用想定は、スマートフォン・タブレットでアプリ的な体験で fincs を使う、iOS で通知機能を使うために PWA 化する、デプロイ後にユーザーが最新版を即座に受け取る、など。

iOS は PWA 化が前提: iOS Safari は標準では通知機能を使えない。ホーム画面追加で PWA として動作させた状態でのみ通知を受け取れる仕様。CS で「iOS で通知が来ない」相談時は PWA 化を案内する運用。

PWA 機能トグル: PWA 機能は内部の機能トグルで有効化/無効化可能。各環境で個別に制御している。

CloudFront キャッシュ無効化のコスト: リリース毎に全パスを無効化する仕組みのため、リリース頻度に応じて配信コストが発生する。配信頻度・コストのバランスは運用で判断。

iPhone PWA での画面更新の特殊事情: iPhone PWA では画面の自動更新処理が一部不安定であるため、内部的に通常の URL 履歴更新 + ページリロードを使う代替手段で対応している。

📝 レビュー観点:

  • 目的: ホーム画面追加でアプリ風利用、オフライン対応の precache、デプロイ時のキャッシュ無効化
  • 誰が使うか: 全ユーザー
  • どこで使うか: 全画面、特に PWA インストール後のスタンドアロン起動
  • 隣接機能との関係: 通知（./notification.md）、SEO（./seo.md）、解析（./analytics.md）
  • CS 問い合わせで頻発する論点: 「ホーム画面追加できない」「アプリが起動しない」「再ログインを求められる」「最終訪問講座に直行したい」「iOS で通知が出ない」
  • [本機能特有] PWA は ENABLE_PWA トグルで制御: 環境変数で無効化可能
  • [本機能特有] iOS PWA 化必須で通知機能利用: PWA 未化の Safari は通知不可
  • [本機能特有] CloudFront キャッシュ無効化はリリース毎: GitHub Actions で /* 無効化
  • [本機能特有] localStorage 3MiB 閾値: Firestore キャッシュ痕跡の自動削除
  • [本機能特有] inject-manifest 戦略: Workbox + 自作 sw.ts

利用シナリオ

シナリオ 1: ホーム画面追加してアプリ風に利用

ユーザーがブラウザのメニューから「ホーム画面に追加」を選び、fincs を PWA としてインストール。インストール後はホーム画面アイコンから起動でき、ブラウザバー無しのアプリ風 UI（スタンドアロン表示）で利用できる。

シナリオ 2: PWA 起動時に最終訪問講座へ自動遷移

ログイン済みのユーザーが PWA を起動すると、トップ画面ではなく最後に訪問していた講座ページへ自動的に遷移する。継続学習の利用導線として、毎回トップから探し直す手間を減らす。

シナリオ 3: 新バージョンリリース後の最新版受信

運営側がリリースを行うと、配信キャッシュが全パス無効化され、ユーザー側では次回読み込み時に最新版が配信される。さらに、内部的にバージョンを定期確認し、新バージョンが出たことを検知するとユーザーに更新を促す動作も走る。

シナリオ 4: iOS で PWA 化して通知を受け取る

iOS ユーザーがホーム画面追加で PWA 化することで、通知機能の利用が可能になる。PWA 化していない iOS Safari では通知を受け取れない。

よくある失敗ケース

  • PWA 未対応ブラウザでのインストール: 古いブラウザや一部の環境ではホーム画面追加機能自体が提供されていない。代替案内が必要
  • localStorage 容量超過: ブラウザの localStorage が容量上限に達すると一部機能が動作不能になるケース。内部的に閾値到達時の自動削除で回避
  • 更新検知後のリロード忘れ: 新バージョン検知後にリロードされないままだと古いバージョンを使い続けるケース。内部の促進処理で対応
  • iOS 未 PWA 化での通知未受信: PWA 化していないと iOS では通知が届かない

権限別仕様

権限定義は ../user-roles.md 参照。

PWA は基盤機能のため、ユーザー権限軸での直接の操作は無い。全ユーザーが対象。

機能詳細（ふるまい）

PWA インストール

  • ブラウザのメニュー「ホーム画面に追加」からインストール可能
  • インストール用のメタ情報（マニフェスト）を提供
  • アイコンは複数サイズ（64 / 192 / 512px）+ マスク対応の 192px を提供
  • インストール後はスタンドアロン表示（ブラウザバー無し）で起動

Service Worker

  • 静的アセットの事前キャッシュ（precache）でアプリ起動を高速化
  • ナビゲーション（ページ遷移）の段階的キャッシュ
  • フォントの長期キャッシュ
  • 通知受信処理 + OS バッジ更新
  • 事前キャッシュの対象サイズ上限あり（大容量メディアは対象外）

PWA 起動時の最終訪問講座への自動遷移

  • ログイン済みかつトップ画面 / ログイン画面にいる場合、最後に訪問した講座ページへ自動遷移
  • セッション内で初回起動時のみ実行（後続のページ遷移は通常通り）
  • 機能トグルでの有効化制御

配信キャッシュ無効化（リリース時）

  • リリース実行時に CDN（CloudFront）のキャッシュを全パス無効化
  • ユーザーは次回読み込み時に最新版を取得できる
  • 配信メタ情報の更新検知用ファイルには no-cache メタ情報を付与し、常に最新を取得する仕組み

更新検知 + リロード促進

  • 内部的に定期的にバージョン情報を確認
  • 新バージョンが検知された場合、ユーザーに更新を促し、必要に応じて画面リロードを実行

ストレージ容量管理

  • ブラウザの localStorage 上限（5MiB）を超えると一部機能が動作不能になるリスクへの対応
  • 容量が一定の閾値（3MiB）を超えた場合、内部キャッシュの痕跡を自動削除して空き容量を確保

iOS PWA の制約事項

  • iOS Safari では PWA 化しないと通知機能を使えない
  • PWA 起動状態でも、iOS 特有の動作制約に応じた個別対応が走る（通知の挙動・画面更新方法等）
  • PWA 未化の iOS ユーザー向けには互換層経路（PushQuay）で通知を提供（./notification.md 参照）

📝 レビュー観点:

  • 入力 → 処理 → 出力: PWA インストール → 起動 → SW 登録 → push 受信 → 通知表示
  • エッジケース: 通知許可 denied、リダイレクト前後のセッション切れ、Service Worker 更新タイミング
  • エラー表示: Service Worker 登録失敗時はサイレント
  • [本機能特有] iPhone PWA で reloadNuxtApp 不安定: history.replaceState + window.location.reload で代替

admin 操作

該当なし / 実装されていない

  • PWA 関連の運営アドミン操作経路: 無し（全 FE 設定）
  • CloudFront 手動 invalidate: GitHub Actions の手動起動（環境別 wrapper）

📝 レビュー観点:

  • 緊急時の手動 invalidate 経路の運用ガイド

品質 / 約束事項

  • 応答性: PWA インストール即時、Service Worker 更新は次回起動時
  • 信頼性: precache + ナビゲーション fallback で網羅、CloudFront invalidate でリリース反映
  • 制限値:
    • Service Worker precache 上限: 6 MB（maximumFileSizeToCacheInBytes）
    • フォントキャッシュ: 30 件上限 + 1 年期限
    • localStorage 閾値: 3 MiB（5 MiB 上限の安全マージン）
    • Firestore IndexedDB キャッシュ: 40 MB
    • Firestore キャッシュ再初期化周期: 24 時間
  • データ保持: PWA 設定は端末ローカル

📝 レビュー観点:

  • [本機能特有] CloudFront 無効化のコスト: リリース毎の /* 無効化

変更履歴（リリースノート候補）

v2.29.2: 2026-05-04（PSD 初版）

  • [PSD 追加] 本ドキュメント初版作成。v2.29.2 時点の実装を起こし。機能追加・変更は含まない

📝 レビュー観点:

  • 過去の主要変更（@vite-pwa/nuxt 導入 / inject-manifest 戦略移行 / 起動リダイレクト追加 等）

関連ドキュメント

このページの内容を AI に質問しますか？
関連 spec を自動抽出して ChatGPT / Claude などに渡せます。
AI Prompt で開く →