Eden 連携システム概要

2つのシステム

📚

SYSTEM A

EdenTeacher

保護者向け表示: Eden 保護者ポータル

家庭教師Eden の基幹業務システム

⚔️

SYSTEM B

EdenQuest

小学生向けゲーミフィケーション学習アプリ

🛠️ それぞれのアプリでできること

2つのシステムを役割で分担。EdenTeacher が 裏側の運営・契約管理を、EdenQuest が 表側の学習体験を担う。

📚

SYSTEM A — 基幹業務システム

EdenTeacher（Eden 保護者ポータル）

🧑‍💼 顧客・契約管理

生徒情報・コース（12回 / 24回）の管理
残り授業回数の自動・手動増減
継続意思の確認（will_continue）と退会フロー
コース更新（renewCourse）
保護者アカウントの作成・紐付け

📝 授業運用

授業報告書（リッチエディタ Tiptap）
保護者向け公開リンク
授業スケジュール管理（xyflow可視化）
宿題セクション

💰 給与・運営

先生別給与計算・稼働報告
当日キャンセル料金処理
お知らせ配信
ユーザー管理（admin / teacher / parent）

📞 外部連携

LINE 連携（保護者通知・グループ管理）
Zoom OAuth・録画自動取得
授業要約（AI）
YouTube 自動アップロード（録画→限定公開）

↔️ EdenQuest との連携

残回数・継続意思の変更を即時 webhook 送信
保護者メアドでの契約照合 API を提供

⚔️

SYSTEM B — 学習体験アプリ

EdenQuest（小学生向け学習アプリ）

📖 学習コンテンツ

教科 → 単元 → レッスン構造（社会43+理科40単元）
ボス問題（ゲーミフィケーション化された練習問題）
アドベンチャーマップ UI（学習フロー可視化）
教材検索・推薦
カリキュラム CSV インポート

🐉 ゲーミフィケーション

ペット育成（種族 / 進化 / XP）
ペット作成エディタ（5ステップ）
レベルアップ・アーカイブ（達成記録）
オープニング演出・チュートリアル

🎯 リアルタイム / AI

ライブクイズ（教師主催・複数生徒同時）
AI 学習アドバイス（Gemini）
進捗ベースのレコメンド

👨‍👩‍👧 保護者・運営

保護者ダッシュボード（進捗閲覧）
管理者画面（コース編集・進捗確認）
トライアル発行

↔️ EdenTeacher との連携

EdenTeacher の残回数 > 0 でアクセス自動許可
保護者メアドで EdenTeacher の契約を照合・紐付け

🎯 ひとことで言うと

EdenTeacher の契約変更が、EdenQuest 側に常に同期される。

顧客情報を二重管理せず、契約状態のズレや対応漏れを構造的に減らす。「契約更新したのにアプリ側が古いまま」「気づかずアプリを使い続けられている」 — そういう手作業の取りこぼしが起きにくい仕組み。最終的なアクセス停止 / 卒業生扱いの判断は管理者が手動で行うが、判断材料は常に最新で揃った状態を作れる。

❌ もし連携してなかったら

・EdenTeacher の契約変更が EdenQuest に伝わらず、状態がズレたまま気付かない
・契約更新のたびに EdenQuest 側の残回数を 手動で書き換える必要
・二重入力でデータがズレ、対応漏れが顧客クレームに
・運営工数が顧客数に比例して増えていく

✅ 連携した結果（現状）

・残回数や継続意思の変更が 即座に EdenQuest に反映
・管理者は最新の契約状態を見て判断（停止 / 卒業生扱い等）できる
・先生は EdenTeacher だけ操作 → 両方の状態が同期される
・運営工数が 顧客数に依存しない（スケール可能）

この連携の中身（Push / Pull / Gate の3つの動き）は後ろの「連携アーキテクチャ」セクションで詳しく解説します。

連携の鍵 — メールアドレス

EdenTeacher

(Eden 保護者ポータル)

profiles.email

parent@example.com

⇄

↕

EdenQuest

profiles.email

parent@example.com

※ 同じメールアドレスでないと連携できません。 新規アカウント作成時、両システムで同じメアドを使うよう案内文を表示しています。

連携アーキテクチャ

基幹システム（EdenTeacher）と学習アプリ（EdenQuest）の状態を、メールアドレスを共通キーに 双方向連携。手動の二重入力・確認作業を排除し、運営工数とミスのリスクを削減する。

🗺️ 全体像

flowchart LR
  subgraph T["📚 EdenTeacher（Eden 保護者ポータル）"]
    direction TB
    T_user["👨‍🏫 先生・👩‍💼 管理者・👨‍👩‍👧 保護者"]
    T_data[("📊 契約・残回数・授業報告")]
    T_user --> T_data
  end

  subgraph Q["⚔️ EdenQuest（学習アプリ）"]
    direction TB
    Q_user["🧒 生徒・👨‍👩‍👧 保護者・👨‍🏫 先生"]
    Q_gate{"🚪 アクセス判定"}
    Q_data[("📱 学習状態 / 紐付契約")]
    Q_user --> Q_gate
    Q_gate --> Q_data
  end

  T_data ==>|"📨 Push: 状態変更を自動連携"| Q_data
  Q_user -.->|"🔍 Pull: メールで契約を照合"| T_data
  Q_data ==>|"✅ 残回数 > 0 → アクセス許可"| Q_gate

  classDef teacher fill:#fef3c7,stroke:#f59e0b,color:#78350f,stroke-width:2px
  classDef quest fill:#ede9fe,stroke:#8b5cf6,color:#4c1d95,stroke-width:2px
  class T teacher
  class Q quest

Push: 状態変更時に自動連携。先生の操作1つで両システムが同期する。

Pull: 共通キー（メアド）で契約を照合。新規保護者の紐付けに利用。

Gate: 残回数を条件にアクセス自動許可。手動付与不要。

📚

EdenTeacher

(Eden 保護者ポータル)

👨‍🏫 先生

👩‍💼 管理者

👨‍👩‍👧 保護者

契約・残回数・授業報告書を管理

🔗

同じメアドで紐づく

📧 parent@example.com

⇄

自動で同期

⚔️

EdenQuest

(学習アプリ)

🧒 生徒

👨‍👩‍👧 保護者(進捗)

👨‍🏫 先生

学習・クエスト・ペット育成

📨 Use Case 1 — Push

授業実施から学習アプリ反映まで、追加操作ゼロで完結

先生の単一オペレーションで両システムの状態を整合。二重入力・反映漏れによる問い合わせを排除する。

📝

① 授業報告書を提出

先生が EdenTeacher に入力

📉

② 残回数を減算

契約データを更新（10回 → 9回）

📡

③ 状態変更を自動連携

EdenTeacher が EdenQuest に通知（署名付き）

🔄

④ 学習アプリ側を更新

EdenQuest 側の残回数も同期

📱

⑤ 利用者に正確な状態を提示

残回数を踏まえた表示・導線

業務効果: 先生は基幹システム1つに集中。学習アプリ側のメンテは発生しない。データの食い違いに起因する保護者問い合わせを構造的に減らす。

🔍 Use Case 2 — Pull

新規保護者と既存契約の紐付けを最短で完了

メールアドレスを共通キーとして契約照合。手動でのID対応表メンテナンスや人為ミスを排除する。

👤

① 保護者が EdenQuest に登録

入力例: parent@example.com

🔎

② メールで契約を照会

EdenQuest 管理画面 → EdenTeacher にAPI問合せ

📋

③ 契約候補を返却

残回数・コース等を一覧表示

🔗

④ 紐付けを確定

以降は Push 同期の対象になる

前提条件: 両システムで同一メールアドレスが登録されていること。新規アカウント作成画面に注意書きを表示し、登録時点での不一致を未然に防いでいる（後述）。

🚪 Use Case 3 — Gate

家庭教師契約者には学習アプリへのアクセス権を自動付与

権限管理を残回数に従属させ、運用上の権限付与・剥奪コストをゼロにする。

📲

生徒が EdenQuest にアクセス

🛡️

アクセス判定（自動）

紐付契約の残回数 > 0 → 許可

🎯

学習機能を提供

手動の権限付与は不要

運用方針: 残回数を起点にアクセス可否を決定するため、運営側で個別にフラグを立てる必要がない。契約終了後の取り扱い（アクセス停止 / 卒業生扱いへの移行）は、誤切断リスクを避けるため管理者の手動判断とする。

📋 3つの連携動作 — 一覧

動作	方向	トリガー	業務上の効果
📨 Push	EdenTeacher → EdenQuest	残回数・継続意思の変更時（自動）	二重入力ゼロ・反映漏れ排除
🔍 Pull	EdenQuest → EdenTeacher	管理者の検索操作（手動）	新規保護者を即時で契約に紐付け
🚪 Gate	EdenQuest 内（自動）	アクセスのたび	権限付与・剥奪の運用コストをゼロ化

Push: 状態変更を即時通知

EdenTeacher（Eden 保護者ポータル）側で customers の以下が変わると、その場で EdenQuest に webhook を送る。

トリガー操作	変更カラム	webhook event
レポート提出（残回数消費）	remaining_sessions	customer.remaining_sessions_changed
コース更新（管理者手動）	total_sessions	customer.renewed
継続意思の確認	will_continue, continuation_confirmed	customer.continuation_changed
残回数の手動修正	remaining_sessions	customer.remaining_sessions_changed

・HMAC-SHA256 署名 (x-edenteacher-signature) を付けて POST
・fire-and-forget: 失敗してもメイン処理は止めない
・成否は edenquest_webhook_logs に記録（admin SELECT のみ）

Pull: 手動同期 / 検索

EdenQuest admin が「保護者メアドで EdenTeacher の顧客情報を検索」する時に使う。

GET /api/external/customers-by-parent-email?email=xxx

parent_user_id 経由で customers 候補を最大10件返す

GET /api/external/customers/:id

単体取得 (再同期用)

両方とも Bearer 認証 (EDENQUEST_API_KEY)。RLS バイパスのため service_role で実行。

重要な原則

EdenTeacher（Eden 保護者ポータル）側

「状態を変えるだけ」

残回数や継続意思を変更し、変更を通知するだけ。EdenQuest 側のアクセス権限は触らない。

EdenQuest 側

「自動で gate 判定」

middleware が edenteacher_remaining_sessions > 0 を見て、自動でアクセスを許可する。

退会意思の扱い

自動でアクセス停止しない

will_continue=false を受け取っても、EdenQuest は自動でアクセスを止めない。最終判断は EdenQuest admin が手動で行う。

新規アカウント作成時の運用

メアドを揃えてもらうため、両システムの新規登録画面に注意書きを表示。

EdenTeacher（保護者には Eden 保護者ポータルと表示）

/dashboard/users（新規ユーザー作成）/ /dashboard/students/new（インライン保護者作成）

※ EdenQuest（学習アプリ）と連携します。 保護者がEdenQuestで使用しているのと同じメールアドレスを入力してください（メールアドレスが一致しないと連携できません）。

EdenQuest

/register/student（保護者メアド欄）/ /register/teacher

※ Eden 保護者ポータルと連携します。 Eden 保護者ポータルに登録されているのと同じメールアドレスを入力してください（メールアドレスが一致しないと連携できません）。

技術メモ — 環境変数の対応

用途	EdenTeacher 側	EdenQuest 側
Pull API 認証 Bearer	EDENQUEST_API_KEY	EDENTEACHER_API_KEY
Webhook 送信先	EDENQUEST_WEBHOOK_URL	(受信エンドポイント)
Webhook HMAC 署名	EDENQUEST_WEBHOOK_SECRET	EDENTEACHER_WEBHOOK_SECRET

対応するキーは両プロジェクトで同じ値を共有する。

残課題

□ cron 日次 fullsync（webhook 取りこぼしの救済）
□ webhook 失敗自動リトライ（edenquest_webhook_logs.success=false を再送）
□ webhook 送信エラー多発時の admin 通知