メインコンテンツへスキップ
見出し画像

Material Viewer——英語教材のための「閲覧・添削・録音」統合ビューア

    何を作ったか

    英語学習サービス GOSAPO の受講生・講師・管理者が、ひとつの画面で教材の閲覧・添削・音声録音までを完結できる Web アプリケーション「Material Viewer(教材ビューア)」を開発した。

    主な機能は次のとおり。

    • 日英並列表示のマークダウンビューア — 教材本文を Markdown で管理し、ReactMarkdown + remark-gfm + rehype-raw でレンダリング。インラインコメントのハイライト、折りたたみ式の解答セクション、チェックボックス付き問題表示に対応する。

    • 音声再生・録音 — Supabase Storage に格納した発音教材音声を AudioPlayer で再生し、AudioRecorder でブラウザ上からの録音・提出を可能にした。RecordingReview / RecordingSubmission で講師側のレビューフローも組み込んだ。

    • コメント・添削(リアルタイム更新) — テキスト選択ベースのインラインコメント機能。Supabase Realtime を使い、講師がコメントを書くと受講生の画面に即時反映される。CommentSidebar / CommentPopup / CommentDetailModal の 3 層構成。

    • 3 ロール制御(Student / Instructor / Admin) — Zustand + persist による認証状態管理。ProtectedRoute コンポーネントで allowedRoles を宣言的に指定し、ロールごとにルーティングを分岐させる。

    • 教材ライブラリ — ライブラリ → チャプター → レッスンの 3 階層で教材原本を管理。バスケット方式のマルチライブラリインポート、クラス単位の一括共有、Markdown ファイルからの直接インポートに対応。

    • AI 教材生成 — 6 ステップの対話型ウィザード(AICreateModal)と一括編集(AIBatchEditModal)で教材を自動生成。3 段階の言語設定、AI 画像生成、バックグラウンドジョブ実行(JobProgressToast / JobResultModal)を統合。

    • PWA 対応 — vite-plugin-pwa による Service Worker 登録。教材データは NetworkFirst、音声ファイルは CacheFirst で 7 日間キャッシュし、オフラインでも直近の教材を閲覧できる。

    • 共有リンク — 認証不要の公開共有ページ(PublicSharedPage)。個別共有・クラス一括共有・カスタムグループ共有の 3 パターンを用意した。

    • その他 — ブックマーク、学習進捗バー、キーボードショートカット、検索モーダル、印刷ビュー、差分ビューア(DiffViewer)、AI ヘルプチャット、PDF ビューア、多言語対応(i18next、日本語/英語)。

    なぜ作ったか

    GOSAPO は法人向けオンライン英語研修を提供しており、講師が受講生ごとにカスタマイズした教材を Google Docs で共有していた。運用上、次の課題が顕在化していた。

    1. 教材の散在 — Google Docs、Zoho WorkDrive、紙資料が混在し、受講生がどこに何があるか分からない。

    2. 音声教材の運用コスト — 発音練習の音声ファイルは WorkDrive に置いていたが、受講生がダウンロードして別アプリで再生する手間があった。録音提出に至っては LINE で送るなど非構造的だった。

    3. 添削のやり取りが非同期 — Google Docs のコメント機能では、どの部分にどのフィードバックがあるか、受講生には見づらい。リアルタイム性もない。

    4. 受講生ごとの進捗把握が困難 — どのレッスンまで完了したか、講師が手動で追跡していた。

    Material Viewer はこれらを「教材の閲覧」「音声の再生・録音」「添削コメント」「進捗管理」の 4 軸で 1 つのアプリに統合し、受講生にはスマホで開くだけの体験を、講師には管理画面から一元操作できる体験を提供するために作った。

    どう作ったか

    技術スタック

    層 技術 フロントエンド React 19 + TypeScript 5.9, Vite 7 状態管理 Zustand(認証状態の永続化) バックエンド Supabase(PostgreSQL + Realtime + Storage + RLS) 多言語 i18next + react-i18next(ja/en) PWA vite-plugin-pwa + Workbox E2E テスト Playwright デプロイ Docker → Google Cloud Run(asia-northeast1)、GitHub Actions による自動デプロイ

    アーキテクチャ

    src/
      App.tsx              ... BrowserRouter + ProtectedRoute によるロール分岐
      stores/authStore.ts  ... Zustand persist(GOSAPO ID 認証)
      pages/               ... 7 ページ(Login / Student / Instructor / Admin / Library / Manual / SharedPage)
      components/
        common/            ... MarkdownViewer, Header, Modal, ResizablePanel, HelpChat, DiffViewer 他 16 コンポーネント
        audio/             ... AudioPlayer, AudioRecorder, RecordingReview, RecordingSubmission
        ai/                ... AICreateModal, AIBatchEditModal, AIEditModal, AIImageModal, JobProgressToast, JobResultModal
        admin/             ... AudioManagerModal, MaterialAssignmentModal, LessonStructureEditor, ContextLibraryManager 他
        comment/           ... CommentSidebar, CommentPopup, CommentDetailModal
        share/             ... ShareLinkModal, BatchShareLinkModal, ClassShareLinkModal
        bookmark/          ... BookmarkSidebar
        progress/          ... LessonProgressBar
        search/            ... SearchModal
        export/            ... PrintView
        materials/         ... MarkdownImportModal
      hooks/               ... 18 カスタムフック(useMaterials, useComments, useRecordings, useBookmarks, useAIEdit 他)
      services/            ... 14 サービス(audioService, aiEditService, materialLibraryService 他)
      i18n/locales/        ... ja.json, en.json
    

    ソースコードは TypeScript/TSX/CSS 合わせて約 100 ファイル、51,000 行。

    データベース設計

    Supabase 上に lessonmaterials_ プレフィックスのテーブル群を構築した。マイグレーションファイルは 30 本。主要テーブルは以下。

    • lessonmaterials_users / lessonmaterials_user_roles — ユーザーとロール

    • lessonmaterials_materials — 教材コンテンツ(Markdown 本文、カテゴリ、レッスン番号)

    • lessonmaterials_comments — インラインコメント(Realtime 有効、selected_text + selection_start でテキスト位置を特定)

    • lessonmaterials_bookmarks — ブックマーク

    • lessonmaterials_recordings — 録音メタデータ(実体は Storage)

    • lessonmaterials_instructor_notes — 講師メモ(添付ファイル対応)

    • lessonmaterials_share_links — 共有リンク(個別/クラス/ライブラリ)

    Storage バケットは pronunciation-materials(Public、音声教材)と lessonmaterials_note_attachments(Private、講師メモ添付)の 2 つ。

    Playwright E2E テスト

    tests/ ディレクトリに 7 つのスペックファイルを配置。

    • student.spec.ts — 受講生画面のレンダリング、レッスン選択、タブ切り替え(FB / 表現集 / 宿題 / 指示)

    • instructor.spec.ts — 講師画面の操作

    • admin.spec.ts — 管理者画面

    • material-library-check.spec.ts — ライブラリ表示の整合性

    • prompt-management.spec.ts / prompt-page-layout.spec.ts — プロンプト管理画面

    • check-layout.spec.ts — レイアウト崩れの検出

    各テストはログインフローを beforeEach で実行し、ロール別にページ遷移後のアサーションを行う。Chromium ヘッドレスモードで実行し、CI では retries: 2 を設定。

    開発の流れ

    開発は 2025 年 12 月 30 日の最初のコミット(Cloud Run デプロイ設定)から始まり、2026 年 3 月 7 日時点で 46 コミット。Claude Code との対話セッションは material-viewer-react プロジェクトで 4 セッション、GOSAPO Material Viewer プロジェクトで 60 以上のセッションを重ねた。主な開発フェーズは以下。

    1. Phase 1(2025/12/30〜2026/01/01) — Cloud Run デプロイ、モバイル対応、GOSAPO ID 認証、Supabase 統合、教材割り当て機能

    2. Phase 2(2026/01/01〜01/11) — 教材ライブラリ構築、バスケット方式インポート、AI 教材生成(6 ステップ対話型)、コンテキストライブラリ

    3. Phase 3(2026/01/11〜01/30) — AI 画像生成、バックグラウンドジョブ、クラス共有、マニュアルページ、カウンセリング診断機能

    4. Phase 4(2026/02/26〜03/07) — マークダウンインポート、URL ベースタブルーティング、カスタムグループ、AI ヘルプチャット

    現在の状態

    • 本番環境: Google Cloud Run(開発環境)で稼働中。URL: https://app-materialviewer-mock-dev-qtyazlt7la-an.a.run.app/

    • 認証: GOSAPO ID による認証。Supabase の RLS(Row Level Security)でデータアクセスを制御。

    • 教材データ: TOEIC L&R 対策教材(Part 1〜4)と、法人受講生向けカスタム教材(タイ赴任向けビジネス英語 10 ユニット)が投入済み。

    • デプロイ: app/material-viewer-react/** への変更を main ブランチに push すると GitHub Actions が自動で Cloud Run にデプロイ。

    • テスト: Playwright E2E テストは 7 スペック。手動実行ベース(npm test)。

    見えてきたこと

    Markdown は教材フォーマットとして想像以上に強力だった。 Google Docs からの移行時は表現力の低下を懸念したが、rehype-raw で HTML を直接埋め込めるため、折りたたみセクション(<details>)、チェックボックス、引用ブロックによる問題囲み、インライン音声プレーヤーまで実現できた。教材作成者が Markdown を書けさえすれば、従来の Google Docs より構造化された教材が作れる。

    Supabase Realtime の「コメント即時反映」は講師の体験を変えた。 従来、添削結果は次のレッスンまで受講生に届かなかった。リアルタイムのインラインコメントにより、レッスン中に講師がコメントを入れると受講生の画面にハイライトが現れるという体験が生まれた。ただし、Realtime のコネクション管理(再接続、チャネル多重化)は、まだ ConnectionStatus コンポーネントで可視化しているだけで、堅牢性には課題がある。

    PWA のオフラインキャッシュは「スマホで開くだけ」の体験に不可欠だった。 受講生の多くはレッスン前にスマホで教材を確認する。NetworkFirst で教材を、CacheFirst で音声をキャッシュする設計により、地下鉄の中でも直近の教材と音声を再生できる。これは Google Docs では不可能だった体験。

    AI 教材生成は「対話型」と「一括」の両方が必要だった。 最初は 6 ステップの対話型ウィザードだけを作ったが、講師が 10 レッスン分を一気に生成したいケースが出てきて、一括生成モード(AIBatchEditModal)を追加した。さらに生成時間が長いためバックグラウンドジョブ化し、JobProgressToast でリアルタイムに進捗を表示する設計に至った。教材生成は「一発で完璧な出力」ではなく「素案を高速に出し、人が直す」ワークフローに落ち着いている。

    51,000 行のコードベースのほぼ全てが Claude Code との対話で生成された。 約 2 ヶ月半、60 以上の対話セッションを通じて、要件定義からコンポーネント設計、テスト作成、バグ修正までを対話ドリブンで進めた。「Prompt is too long」でコンテキストが溢れるたびにセッションを分割し、会話履歴を検索して前のコンテキストを復元するという運用が定着した。AI コード生成の実用的な限界は「一度に扱えるコンテキスト量」であり、それはプロジェクトが大きくなるほど顕在化する。

     
     
    様々な事象が構造を浸食していく現場からの論考。ビジネス・社会・教育の地殻変動を描く。

    あなたへのおすすめ