基本設計書

SMART EC School（会員制ECスクール会員サイト）

現ブランド名：SMART EC LINK　／　運営：株式会社スマートネクサス

文書バージョン	1.1
作成日	2026-07-27
作成者	RERISE JAPAN開発チーム
対象システム	会員サイト（frontend / backend / DB）＋関連システム（AI説明会・稼働チェックツール）
参照要件定義書	docs/requirements.md（v7.15）／docs/requirements-activity-checker.md

承認

区分	役職・氏名	承認日	押印
承認者			印
確認者			印
作成者	RERISE JAPAN開発チーム	2026-07-27	印

改訂履歴

版数	改訂日	改訂者	改訂内容
1.0	2026-07-03	RERISE JAPAN開発チーム	初版作成。docs/requirements.md（v7.13）、docs/SCOPE_PROGRESS.md、frontend/src/types/index.ts、frontend/src/routes/index.tsx、backend/src/models・routers 実装コードを基に、現行実装の実態を反映した基本設計書として作成。
1.1	2026-07-27	RERISE JAPAN開発チーム	docs/requirements.md（v7.15）反映＋実装コード再検証による更新。 (1) TEMU保証金制度（1アカウント20万円／2アカウント以上30万円・敷金型・契約終了時全額返金、運営支援契約第6条の2）を追加。 (2) 既存会員向けTEMU追加申込導線 `/temu-apply`（U-015）とAPI `/api/contracts/temu-addition` を追加。 (3) 顧客管理シートの店舗審査ステータス列（新設）と整合cron `/api/cron/review-status-reconcile` を追加。 (4) 融資関連書類の売上算出基準を「入金額（confirmed_sales）」から「販売額グロス（gross_sales・発生ベース）優先」へ是正した実装（`loan_support.py`）を反映。 (5) 融資申請3点セット・資料③生成API `/api/admin/loan-documents/keikakusho` をAPI仕様に追加。 (6) 本体と独立した関連システムとして「8. 関連システム」を新設し、AI説明会システム（temu-ai-meeting／Cloud Run別サービス・招待キー制・スライド+TTS音声+Realtime質疑・/admin観戦ダッシュボード・/agency-contract代理店契約Web同意フォーム）と稼働チェックツール（TikTok Shop売上活動モニタリング・AIコントローラー型・UIなし）を追記。

目次
システム概要
システム構成
画面一覧・画面遷移
データベース設計
API仕様
外部インターフェース
非機能要件
関連システム（本体と独立）

1. システム概要

1.1 システムの目的

SMART EC School（現ブランド名：SMART EC LINK）は、EC物販スクール事業および運営代行事業を提供する会員制サイトである。学習コンテンツ（動画・テキスト・アーカイブ）の提供、契約管理（電子契約・決済確認）、会員間の売上・利益レポート閲覧、運営者向けの議事録管理・AIタスク抽出、CRM連携による既存契約者統合など、会員の学習から契約・成果管理までを一気通貫で支える。

複数のECプラットフォーム（TEMU / TikTok Shop / メルカリShops）に対応するコンテンツ・アクセス制御を持ち、新規プラットフォーム追加時にはDB・メタデータの追加のみで対応できるアーキテクチャを採用している。

1.2 対象ユーザー・ロール体系

ロールはSupabase Authの app_metadata.role に保持され、DB/APIの内部値は変更せず表示名のみ日本語化している。

内部値	表示名	権限概要
`owner`	オーナー	全機能＋管理画面フルアクセス（Google認証可、2FA必須）
`operator`	管理者	会員管理（閲覧）＋レポート管理（2FA必須）
`school_plus`	スクール+	学習コンテンツ＋売上・利益レポート（自分のみ）
`school`	スクール	学習コンテンツのみ
`agency`	代理店	代理店ページ（紹介コード確認）・設定のみ。学習コンテンツ／レポート等は非対象

1.3 プラットフォーム体系

会員は User.platforms（配列）で複数プラットフォームへの契約を保持できる（例: ['temu','tiktokshop']）。

内部値	表示名	状態
`temu`	TEMU	提供中
`tiktokshop`	TikTok Shop	提供中
`mercarishops`	メルカリShops	準備中（全ロール共通でアクセス不可）

1.4 コンテンツ階層構造

courses（コース）

└─>

chapters（章）

└─>

lessons（レッスン：動画/テキスト/アーカイブ）

各階層に sort_order による並び替え、is_published による下書き/公開切替を持つ。chapters.is_opening_guide は契約前でも公開できる「開店準備マニュアル」章を識別するフラグ。

1.5 主要な利用者フロー（業務フロー概要）

公開LP / 申込フォーム

→

契約書電子署名

→

決済スクリーンショット提出

→

運営承認

→

全コンテンツ解放

→

学習・レポート確認

契約締結前は「開店準備マニュアル」のみ閲覧可能。契約締結後にプラットフォーム別の全学習コンテンツが解放される（§3.1参照）。

2. システム構成

2.1 全体構成図

利用者（ブラウザ／スマートフォン）

↓

HTTPS

フロントエンドCloudflare Pages（smart-ec-link.pages.dev）
React 19 + TypeScript + Vite 7

↓

HTTPS REST API（JWT Bearer認証）

バックエンドAPIGoogle Cloud Run（smart-ec-academy-api）
Python 3.12 + FastAPI + SQLAlchemy 2.0

↓

SupabasePostgreSQL + Auth（JWT/RLS/TOTP）

Gemini 2.5 Flashgoogle-genai SDK
議事録要約・タスク抽出

Cloudflare R2 + Workers動画配信（署名付きURL）

外部連携Chatwork API
Zoom API/Webhook
Google Sheets/Drive API

図2-1: システム全体構成図

2.2 技術スタック一覧

区分	技術要素
フロントエンド	React 19 / TypeScript 5 / shadcn/ui / Tailwind CSS / Vite 7 / Framer Motion
バックエンド	Python 3.12+ / FastAPI / SQLAlchemy 2.0 / Alembic
データベース	PostgreSQL（Supabase Free）
認証	Supabase Auth（JWT + RLS + TOTP 2要素認証）
AI	Gemini 2.5 Flash（google-genai SDK）
フロントエンド配信	Cloudflare Pages（プロジェクト名: smart-ec-link）
バックエンド実行環境	Google Cloud Run（asia-northeast1／サービス名: smart-ec-academy-api）
動画配信	Cloudflare R2 + Workers（署名付きURL方式）
外部連携	Chatwork API / Zoom API・Webhook / Google Sheets・Drive API / YouTube Data API v3 / PayPal・ファーストペイメント・UnivaPay（決済）

3. 画面一覧・画面遷移

3.1 権限マトリクス

凡例: ○=アクセス可 / 🔒=画面は見えるが機能不可（追加契約案内を表示）/ ×=非表示・アクセス不可

機能／画面グループ	スクール	スクール+	管理者	オーナー	代理店
プラットフォーム選択・ホーム・設定・契約管理	○	○	○	○	○（設定・紹介コードのみ）
学習コンテンツ・アーカイブ（契約済PF）	○	○	○	○	×
学習コンテンツ・アーカイブ（未契約PF）	🔒	🔒	○	○	×
Q&A・お知らせ・カレンダー・会員ディレクトリ・融資サポート	○	○	○	○	×
レポート（売上・利益）	×	○（自分のみ）	○	○	×
管理：会員管理・契約承認・エンゲージメント・契約担当者管理(CRM)・運営オペレーションハブ・シミュレーション・資料ライブラリ・申込管理・代理店会員管理	×	×	○	○	×
管理：コンテンツ管理・お知らせ管理・営業戦略ガイド・融資申込管理・議事録管理	×	×	×	○	×

3.2 公開ページ一覧（認証不要）

ID	画面名	ルート	概要
G-001	公開LP	`/lp`, `/top`	集客用ランディングページ（LandingGuard）。プラットフォーム・訴求パターン別に複数バリエーションあり
G-002	申込フォーム（TEMU）	`/apply/temu`	9ステップウィザード形式の申込フロー
G-003	申込フォーム（TikTok Shop）	`/apply/tiktok`	同上
G-004	代理店申込	`/apply/agency`	代理店契約の申込フォーム
G-005	法務確認プレビュー	`/legal-review/temu`, `/legal-review/tiktok`	契約書・特商法表記の弁護士確認用プレビュー画面
G-006	公開学習コンテンツ	`/learn/public`	開店準備マニュアル等、契約前でも閲覧可能な章の公開ページ
G-007	契約電子署名	`/contracts/sign/:token`	顧客側の電子署名（双方署名フローのカウンターサイン）
G-008	オーナー契約承認	`/contracts/owner-approve/:token`	双方署名フローにおけるオーナー側の最終承認
G-009	招待登録	`/invite/:token`	CRM統合済み契約担当者向けの招待経由アカウント作成（v7.5）
G-010	ログイン／セルフ登録／パスワード再設定	`/login`, `/register`, `/reset-password`, `/update-password`	Supabase Authベースの認証画面群

3.3 会員ページ一覧（要ログイン）

ID	画面名	ルート	権限	概要
U-001	プラットフォーム選択	`/select-platform`	全ロール	契約済PFカード一覧のハブ画面。未契約PFは🔒表示、準備中PFは「準備中」バッジ
U-002	ホーム	`/home`	全ロール	displayName表示＋選択中PFに応じた学習進捗・統計ダッシュボード
U-003	設定	`/settings`	全ロール	displayName（ニックネーム）編集、2FA設定、公開プロフィール設定
U-004	代理店	`/referral`	全ロール（主に代理店）	紹介コード確認・紹介実績
U-005	サービス紹介	`/service`	全ロール	契約前の会員に向けたサービス説明ページ
U-006	契約管理	`/contracts`	全ロール	契約一覧・電子契約UI・決済スクリーンショットアップロード
U-007	学習コンテンツ	`/learn/:courseId?/:lessonId?`	owner/operator/school_plus/school	選択中PFのコースのみ表示。動画・テキスト・スライドビューアー対応
U-008	アーカイブ	`/archives`	owner/operator/school_plus/school	選択中PFのライブ配信アーカイブ動画一覧
U-009	Q&A	`/qa`	owner/operator/school_plus/school	質問投稿・回答閲覧。AIドラフト回答（伊藤遥）の承認後公開
U-010	レポート	`/reports`	owner/operator/school_plus/school	月次売上・利益レポート閲覧（school_plus以上は自社分、複数企業切替対応）
U-011	お知らせ	`/notices`	owner/operator/school_plus/school	カテゴリ別お知らせ一覧・既読管理
U-012	カレンダー	`/calendar`	owner/operator/school_plus/school	セミナー・勉強会等のイベント一覧
U-013	会員ディレクトリ	`/directory`	owner/operator/school_plus/school	会員間の公開プロフィール・ビジネス紹介ネットワーク
U-014	融資サポート	`/loan-support`	owner/operator/school_plus/school	公庫融資申込の事前ヒアリング・申請補助
U-015	TEMU追加申込	`/temu-apply`	全ロール（要ログイン）	既存会員がTEMUアカウントの追加参加を申し込む導線。契約は自動作成せず、申込内容を `application_logs` に永続化のうえSEL運営本部Chatworkへ通知し個別案内につなげる（新規申込フォームは既存登録メールを409で弾くため、その受け皿として案内）

3.4 管理者ページ一覧

ID	画面名	ルート	権限	概要
A-001	契約承認待ち一覧	`/admin/contracts/pending`	owner/operator	申込直後・署名待ち・決済確認待ちの契約を横断表示
A-002	契約マスタ管理	`/admin/contracts`	owner/operator	全契約の一覧・送付・締結状況管理
A-003	会員管理	`/admin/members`	owner/operator（招待・編集はowner限定）	会員一覧・招待・platforms/ロール編集・BAN/UNBAN
A-004	エンゲージメント分析	`/admin/engagement`	owner/operator	会員の学習進捗・活動状況モニタリング
A-005	コンテンツ管理	`/admin/content`	owner限定	コース・章・レッスン・アーカイブのCRUD、YouTube動画承認タブ
A-006	レポート管理	`/admin/reports`	owner/operator	全会員レポートの閲覧・CRM同期実行・同期ログ確認
A-007	契約担当者管理（CRM統合）	`/admin/contracted-persons`	owner/operator	CRM同期済み契約担当者・企業の一覧、招待発行、売上分析（v7.5）
A-008	お知らせ管理	`/admin/notices`	owner限定	お知らせの作成・公開・AI生成支援
A-009	営業戦略ガイド	`/admin/strategy`	owner限定	営業戦略・トークスクリプトの社内向けガイド
A-010	融資申込管理	`/admin/loan-application`	owner限定	会員からの融資サポート申込の審査・ステータス管理
A-011	議事録管理	`/admin/minutes`	owner限定	議事録一覧・検索・タスク一覧・Chatwork転送
A-012	議事録ドラフト編集	`/admin/minutes/drafts/:id`	owner限定	Zoom→Gemini解析済みドラフトの確認・修正・承認確定
A-013	運営オペレーションハブ	`/admin/ops`	owner/operator	Q&A候補管理・FAQ承認・トピック編集等の運営タスク集約画面
A-014	売上シミュレーション	`/admin/simulation`	owner/operator	営業提案用の売上・利益シミュレーションツール
A-015	説明資料・LPライブラリ	`/admin/materials`	owner/operator	営業資料・LPパターンの一覧・ダウンロード導線
A-016	申込管理	`/admin/apply`	owner/operator	申込フォーム経由の新規申込データの管理
A-017	代理店会員管理	`/admin/agency`	owner/operator	代理店ロール会員の管理・報酬集計連携

画面ID・権限は frontend/src/routes/index.tsx のルーティング定義（AuthGuard の allowedRoles）を実装の正とし記載。

3.5 画面遷移（代表フロー）

ログイン後の初回導線

G-010 ログイン

→

U-001 プラットフォーム選択

→

U-002 ホーム

→

U-007 学習コンテンツ／U-008 アーカイブ

新規契約フロー

G-002/003 申込フォーム

→

G-007 電子署名

→

G-008 オーナー承認

→

U-006 契約管理（決済スクショ提出）

→

A-001 承認待ち一覧（運営確認）

→

コンテンツ全解放

議事録自動化フロー（運営者向け）

Zoom会議終了

→

Webhook受信

→

Gemini解析

→

A-012 ドラフト編集

→

承認確定

→

A-011 議事録一覧／Chatwork通知

4. データベース設計

バックエンド backend/src/models/（SQLAlchemy 2.0モデル）および要件定義書§11・§13の生成SQLを正として記載。主要テーブルの要点のみを示し、全カラムは網羅しない。全テーブルは PostgreSQL（Supabase）上に存在し、ユーザーの認証・認可情報自体は Supabase Auth の auth.users（app_metadata に role / platforms / plan / two_factor を保持）で管理する。

4.1 学習コンテンツ系

テーブル	主要カラム	説明
`courses`	id, name, description, platform, sort_order, is_published	コース（例: TEMU基礎 / TikTok Shop基礎）
`chapters`	id, course_id(FK), name, sort_order, is_published, is_opening_guide	章。`is_opening_guide`=trueは契約前公開対象
`lessons`	id, chapter_id(FK), title, type, video_key, content, duration_seconds, sort_order, is_published, resources(JSONB)	レッスン（動画/テキスト/アーカイブ）。`video_key`はR2オブジェクトキー
`content_sources`	id, course_id(FK), name, source_type, content, split_rule, last_synced_at	スライド原本からレッスンを自動生成するマスタソース
`archives`	id, title, description, platform, video_key, thumbnail_key, duration_seconds, streamed_at, is_published	ライブ勉強会アーカイブ動画
`user_progress`	id, user_id, lesson_id(FK), completed, completed_at, last_position（unique: user_id+lesson_id）	レッスン視聴進捗
`lesson_views`	id, user_id, lesson_id, course_id, chapter_id, started_at, duration_seconds, completed	視聴ログ（エンゲージメント分析用）

4.2 Q&A・お知らせ系

テーブル	主要カラム	説明
`questions`	id, user_id, title, body, category, image_urls, is_resolved	会員からの質問
`answers`	id, question_id(FK), user_id, body, ai_draft, is_approved	回答。`ai_draft`はAI下書き、運営承認後`body`に反映
`notices`	id, title, body, category, target_roles(配列), is_published, published_at	お知らせ
`notice_reads`	id, notice_id(FK), user_id, read_at（unique: notice_id+user_id）	既読管理

4.3 レポート・契約・決済系

テーブル	主要カラム	説明
`reports`	id, user_id, year_month, platform, gross_sales, confirmed_sales, product_cost, logistics_cost, platform_fee, refund_cost, other_cost, target_profit, smart_share, rerise_share, customer_share, shop_count, contracted_company_id(FK)	月次売上・利益レポート。CRM同期データは`contracted_company_id`必須。`gross_sales`（販売額・発生ベース）を売上の正データとし、`confirmed_sales`（入金額）は未同期の旧データのみのフォールバックとして扱う（融資関連書類生成に適用、§5.6参照）
`contracts`	id, user_id, contract_type, platform, status, template_version, confirmation_items(JSONB), signed_at/ip/user_agent/hash, pdf_url, sign_token, owner_sign_token, owner_signed_at	契約レコード。status: pending→sent→signed_by_user→active。TEMU運営支援契約（第6条の2）は保証金条項（1アカウント200,000円／2アカウント以上300,000円・無利息・契約終了時全額返金）を含み、`confirmation_items`に保証金理解チェック項目を保持。保証金の入金案内自体はChatworkでの個別運用（システム未組込）
`coupons`	id, code, coupon_type, issued_to_user_id/email/company, used_by_user_id, is_used, max_accounts, source_platform, source_account_count	TikTok Shop無料運用権等のクーポン
`payment_confirmations`	id, user_id, platform, payment_type, image_url, status, admin_note, reviewed_by, reviewed_at	決済スクリーンショット承認レコード。status: pending→approved/rejected
`loan_applications`	id, user_id(unique), pre_screening_data(JSONB), hearing_data(JSONB), status, admin_note	融資サポート申込

4.4 議事録管理系

テーブル	主要カラム	説明
`meeting_minutes`	id, title, meeting_date, participants(配列), summary, full_text, source_url, status	確定済み議事録
`meeting_minute_tasks`	id, minute_id(FK), assignee, description, due_date, is_completed, completed_at, mentioned_in_next	議事録から抽出されたタスク（担当者は平部／松田のみ）
`meeting_minute_drafts`	id, zoom_uuid(unique), zoom_start_time, zoom_duration_min, zoom_topic, classification, analysis(JSONB), vtt_excerpt, transcript_url, instruction_history(JSONB), status	Zoom→Gemini解析済みの承認待ちドラフト

4.5 CRM統合・招待系（v7.5）

テーブル	主要カラム	説明
`contracted_persons`	id, crm_person_id(unique), name, email, phone, chatwork_room_id, status(synced/invited/claimed), user_id, synced_at, invited_at, claimed_at	CRM側の契約担当者マスタ
`contracted_companies`	id, crm_company_id(unique), contracted_person_id(FK), company_name, platforms(配列), plan, contract_plan, chatwork_room_id_temu/tiktok, is_primary, analysis_status	契約企業。担当者と1:N
`invitations`	id, contracted_person_id(FK, unique), token_hash(unique), chatwork_room_id, is_active, expires_at(発行から30日), posted_to_chatwork_at, claimed_at	人単位で1本発行される招待リンク。トークンはSHA-256ハッシュのみ保存
`registration_logs`	id, invitation_id, contracted_person_id, user_id, ip_address, user_agent, status, error_message	招待経由登録の監査ログ

4.6 デポジット管理系（v7.7）

テーブル	主要カラム	説明
`platform_deposits`	id, user_id(nullable), platform, store_count, current_balance, initial_deposit, is_active, chatwork_room_id	プラットフォーム別デポジット残高
`weekly_consumption`	id, deposit_id(FK), week_start, week_end, consumed_amount（unique: deposit_id+week_start）	週次消費額
`deposit_transactions`	id, deposit_id(FK), type(deposit/consumption/refund), amount, source, screenshot_url, approved_by, approved_at	入出金トランザクション
`reminder_candidates`	id, deposit_id(FK), generated_at, target_balance, current_balance, recommended_amount, status(pending/approved/sent/skipped/expired), approval_token, token_expires_at, approved_at, approval_ip	入金催促候補。HMAC署名付きURLで平部がブラウザ承認

4.7 運用ログ

テーブル	主要カラム	説明
`notification_logs`	id, channel, trigger_type, room_id, message, success, error_detail, retry_count	Chatwork等の通知送信ログ

4.8 テーブル関連図（概略）

courses

1:N→

chapters

1:N→

lessons

1:N→

user_progress / lesson_views

contracted_persons

1:N→

contracted_companies

1:N→

reports

contracted_persons

1:1→

invitations

1:N→

registration_logs

meeting_minutes

1:N→

meeting_minute_tasks

platform_deposits

1:N→

weekly_consumption / deposit_transactions / reminder_candidates

5. API仕様

バックエンド backend/src/routers/（39ファイル・約193エンドポイント）を実装の正として、主要エンドポイントを機能グループ別に抜粋して記載する。全エンドポイントは Authorization: Bearer <Supabase JWTアクセストークン> による認証を前提とし（公開API・cron専用APIを除く）、権限は require_role() 依存関係で制御する。

5.1 学習コンテンツ・進捗

メソッド	パス	概要	権限
GET	`/api/courses`	選択中PFのコース一覧取得（公開コースのみ）	全ロール
GET	`/api/courses/{course_id}`	コース詳細（章・レッスン含む）	全ロール
GET	`/api/courses/public/opening-guide`	契約前公開の開店準備マニュアル取得	認証不要
GET	`/api/archives`	アーカイブ動画一覧	全ロール
POST	`/api/archives/{archive_id}/view`	視聴ログ記録	全ロール
GET / PUT	`/api/progress`, `/api/progress/{lesson_id}`	視聴進捗取得・更新	全ロール
POST	`/api/progress/view`	視聴ログ登録	全ロール
GET / POST / PATCH / DELETE	`/api/admin/content/courses\|chapters\|lessons\|archives`	コンテンツCRUD	owner
GET / POST / PATCH / DELETE	`/api/admin/library/sources`	スライド原本管理・自動同期	owner
GET	`/api/youtube/videos`	YouTubeチャンネル動画一覧（登録済フラグ付き）	owner
POST	`/api/youtube/approve`	動画承認（レッスン/アーカイブへ登録＋Chatwork通知）	owner

5.2 Q&A・お知らせ

メソッド	パス	概要	権限
GET / POST	`/api/questions`	質問一覧取得・投稿	全ロール
POST	`/api/questions/{id}/answers`	回答投稿	owner/operator
GET / POST	`/api/questions/{id}/draft`, `/draft/refine`, `/draft/approve`	AI回答ドラフト生成・修正・承認公開	owner
GET	`/api/faq/published`	公開済みFAQ一覧	全ロール
GET / POST / PATCH / DELETE	`/api/admin/faq-candidates`	FAQ候補管理・AIリライト・承認	owner/operator
GET	`/api/notices`	お知らせ一覧（ロール別フィルタ）	全ロール
POST	`/api/notices/{id}/read`	既読登録	全ロール
GET / POST / PATCH / DELETE	`/api/admin/notices`	お知らせCRUD	owner
POST	`/api/admin/ai-notices/generate`, `/publish`	AIお知らせ文生成・公開	owner

5.3 レポート・CRM連携

メソッド	パス	概要	権限
GET	`/api/reports`	自分の月次レポート取得	school_plus以上
GET	`/api/admin/reports`, `/all`	全会員レポート取得	owner/operator
POST	`/api/admin/reports/sync`, `/sync-crm`	スプレッドシート・CRMからのレポート同期実行	owner/operator
GET	`/api/admin/reports/sync-status`, `/sync-logs`	同期状況・ログ確認	owner/operator
GET	`/api/admin/contracted-persons`	契約担当者一覧（CRM同期済）	owner/operator
GET	`/api/admin/contracted-persons/companies/{id}/sales-analysis`, `/monthly-review`	企業別売上分析・月次レビュー	owner/operator
POST	`/api/admin/contracted-persons/{id}/invite`	個別招待発行	owner/operator
POST	`/api/admin/contracted-persons/bulk-invite`	一括招待発行（dry-run対応）	owner/operator
POST	`/api/admin/contracted-persons/sync-crm`	CRMからのマスタ同期実行	owner/operator
GET	`/api/invitations/verify-token`	招待トークン検証（公開API）	認証不要

5.4 契約管理・決済確認

メソッド	パス	概要	権限
GET	`/api/contracts/me`	自分の契約一覧	全ロール
GET	`/api/contracts/document/{contract_type}`	契約書全文取得（HTML）	全ロール
POST	`/api/contracts/sign`	電子同意（IP・UserAgent・チェック項目記録＋PDF生成）	全ロール
POST	`/api/contracts/apply`	公開申込フォームからの新規申込受付	認証不要（レート制限あり）
POST	`/api/contracts/register`	会員登録一括処理（アカウント作成＋契約書送付＋Chatwork通知＋スプシ追記）	owner/operator
POST	`/api/contracts/webhook/forms-notify`	Google Forms送信を運営本部Chatworkへ即時通知（放置防止）	secret認証
GET	`/api/contracts/verify/{token}`	署名リンクのトークン検証	認証不要
POST	`/api/contracts/countersign/{token}`	顧客側カウンターサイン実行	トークン認証
POST	`/api/contracts/owner-approve/{token}`	オーナー側最終承認	トークン認証
GET / POST	`/api/admin/contracts`, `/admin/send`	契約一覧取得・送付	owner/operator
POST	`/api/contracts/add-support`	運営支援契約の追加	全ロール
POST	`/api/contracts/temu-addition`	既存会員のTEMU追加参加申込（契約は自動作成せず運営本部Chatworkへ通知）	全ロール（要ログイン）
POST	`/api/payment-confirmations/upload`	決済スクリーンショットアップロード	全ロール
POST	`/api/payment-confirmations/finalize`	決済確認の最終登録	全ロール
GET / POST	`/api/admin/payment-confirmations`	決済確認一覧・承認/却下	owner/operator

5.5 デポジット管理

メソッド	パス	概要	権限
GET	`/api/deposits/balances`, `/alerts`	自分のデポジット残高・アラート確認	全ロール
GET / POST / PATCH	`/api/admin/deposits/balances`	残高一覧・登録・調整	owner/operator
POST	`/api/admin/deposits/transactions`	入出金トランザクション登録	owner/operator
GET / POST	`/api/admin/deposits/reminders`, `/reminders/generate`	催促候補一覧・生成	owner/operator
POST	`/api/admin/deposits/reminders/{id}/approve`, `/skip`	催促候補の承認・スキップ	owner/operator
GET / POST	`/r/{candidate_id}`, `/r/{candidate_id}/execute`	HMAC署名付きURLによるブラウザ一発承認（Chatwork運用フロー）	署名トークン認証
POST	`/api/cron/deposit-generate-candidates`	催促候補の定期自動生成	Cron Secret認証

5.6 議事録管理・その他管理機能

メソッド	パス	概要	権限
GET	`/api/admin/minutes`, `/{id}`	議事録一覧・詳細（検索・日付フィルタ対応）	owner
POST	`/api/admin/minutes/import`, `/import-text`	genspark共有URL／テキストからの手動取込	owner
POST	`/api/admin/minutes/{id}/confirm`	下書き→確定（確定後Chatwork本通知）	owner
PATCH	`/api/admin/minutes/tasks/{id}`	タスク完了/未完了切替	owner
GET	`/api/admin/minutes/tasks/pending`	未完了タスク横断一覧	owner
POST	`/api/admin/minute-drafts/sync`	Zoom録画からのドラフト同期	owner
GET / PATCH	`/api/admin/minute-drafts`, `/{id}`	ドラフト一覧・詳細・編集	owner
POST	`/api/admin/minute-drafts/{id}/approve`, `/reject`, `/restore`	ドラフトの承認・却下・復元	owner
GET / POST / PATCH / DELETE	`/api/admin/members`	会員一覧・招待・編集・BAN	owner/operator（招待・編集はowner）
GET	`/api/admin/engagement`, `/{target_user_id}`	会員エンゲージメント一覧・詳細	owner/operator
GET / PATCH	`/api/admin/loan-applications`	融資申込一覧・ステータス更新	owner
GET / POST	`/api/loan/pre-screening`, `/me`, `/apply`	融資サポート事前診断・申込。売上判定は`gross_sales`（販売額）優先・未同期時のみ`confirmed_sales`で代用	全ロール
POST	`/api/admin/loan-documents/keikakusho`	融資申請3点セット・資料③創業計画書（公庫正式様式xlsx）の自動記入生成	owner
POST	`/api/cron/review-status-reconcile`	顧客管理シートの店舗審査ステータス列を整合チェック。3社間締結済み→未記入なら「審査中」を自動記入、店舗運営開始日の記入があれば「審査完了」に更新。審査中のまま14日超の滞留はSEL運営本部へChatworkアラート（週1想定・手動実行可）	Cron Secret認証
GET	`/api/calendar/events`	イベント一覧取得	全ロール
GET	`/api/customer-profile/directory`	会員ディレクトリ一覧	全ロール

5.7 認証・基盤・cron

メソッド	パス	概要	権限
GET / PATCH	`/api/users/me`	自分のプロフィール取得・更新	全ロール
GET / PUT	`/api/users/me/notifications`	通知設定取得・更新	全ロール
GET	`/api/platforms`	利用可能PF一覧取得	全ロール
GET	`/api/videos/signed-url/{object_key}`	R2動画の署名付き再生URL発行	全ロール
POST	`/api/videos/upload-url`	R2動画アップロード用署名付きURL発行	owner
GET	`/health`, `/health/db`, `/health/db-size`	ヘルスチェック・DB状態確認	認証不要
POST	`/api/cron/chatwork-join-check`, `/monthly-reviews`, `/first-sales-check` 等	定期バッチ処理（Cloud Scheduler経由）	Cron Secret認証

6. 外部インターフェース

6.1 Chatwork連携

会員登録・コンテンツ追加・レポート更新・お知らせ公開・議事録確定時に自動通知
デポジット残高監視: 週次消費実績から催促候補を自動生成し、平部がChatworkまたは承認URL経由でブラウザ承認後に送信
店舗審査ステータス滞留監視: 顧客管理シートの店舗審査ステータスが「審査中」のまま14日を超えて滞留している場合にSEL運営本部へアラート（/api/cron/review-status-reconcile）
議事録タスクリマインド: 未完了タスクを次回ミーティング前日に通知
AIボット「伊藤遥」: Q&A回答ドラフトを生成し、運営承認後に会員向けへ公開
送信ログは notification_logs テーブルに保存し、失敗時の再送・監査に利用

6.2 Zoom連携

Webhookイベント: recording.transcript_completed
会議終了後にvtt（文字起こし）ファイルを自動取得。Zoom AI要約は使用せず、必ずvtt/transcriptを情報源とする
Playwrightによりgenspark（テキスト生成エージェント）を自動操作して議事録の一次生成を行う手動フォールバックあり

6.3 Gemini 2.5 Flash（AI）

項目	内容
SDK	google-genai（旧google-generativeaiは廃止済み）
用途	議事録の要約生成・タスク抽出・前回タスク照合、Q&A回答ドラフト生成、お知らせ文生成
temperature	0.3（安定した出力のため低め）
response_mime_type	application/json
無料枠	250 RPD／機密情報を含む場合は有料プラン（$0.30/1Mトークン）へ移行検討

6.4 Google Sheets / Drive連携

会員登録時に契約情報をスプレッドシートへ自動追記（スマート社の既存運用シートとの整合）
CRM同期スクリプトが顧客管理シート・買付シートと連携し、契約担当者・企業・レポートをDBへ同期
読み取り用途は GOOGLE_SHEETS_API_KEY を使用

6.5 決済連携

決済手段	用途
PayPal（サブスクリプション・単発決済）	月額利用料・デポジット入金の主要手段
ファーストペイメント（運営: 株式会社ファーストディグリー）	クレジットカード一括・分割決済。高額役務プラン向け
UnivaPay	一部プランの決済代行
銀行振込	デポジット入金の併用オプション

会員は決済後にスクリーンショットをアップロードし（/api/payment-confirmations/upload）、運営が管理画面（A-001／A-002）で承認することでコンテンツが解放される。

6.6 動画配信（Cloudflare R2 + Workers）

学習動画・アーカイブ動画はCloudflare R2にオブジェクトとして保存し、Workers経由で署名付きURLを発行して配信する。再生ごとに /api/videos/signed-url/{object_key} でURLを取得し、直リンクによる無断共有を防止する。

6.7 YouTube連携

YouTube Data API v3（OAuth）でチャンネル動画一覧・メタデータを取得し、管理画面（A-005）で承認した動画のみをレッスン・アーカイブとして登録する。無料枠は10,000クォータ/日。

7. 非機能要件

7.1 認証・認可

認証基盤: Supabase Auth（JWT）。APIは Authorization: Bearer <token> をSupabase Auth APIで検証
認可情報（role / platforms / plan）は app_metadata のみを信頼する。ユーザー自身が書き換え可能な user_metadata は権限判定に使用しない（権限昇格防止）
行レベルセキュリティ（RLS）をSupabase PostgreSQL上で併用
owner／operatorはTOTPによる2要素認証必須
ロールベースアクセス制御: require_role() 依存関係でエンドポイント単位に許可ロールを明示
cron専用エンドポイントは CRON_SECRET によるBearer認証（ロールチェックを介さない）

7.2 性能要件

API応答時間: 通常操作で3秒以内
動画配信は署名付きURL方式によりオリジンサーバー負荷を分離
フロントエンドは各ページを遅延読み込み（lazy import）し、初期バンドルサイズを最小化

7.3 セキュリティ要件

通信は全てHTTPS
招待トークン・署名トークンはハッシュ化して保存し、平文はDBに残さない（例: invitations.token_hash）
電子契約はIPアドレス・UserAgent・署名ハッシュを記録し、証跡として保持
公開申込API（/api/contracts/apply）にはIP単位のレート制限（5回/分）を実装
Gemini APIへの送信データに個人情報を含めない（議事録テキストのみ）
議事録データは管理者（オーナー）のみアクセス可能
デポジット催促の承認URLはHMAC署名付き・有効期限7日・承認IPを記録

7.4 UI/UX基準

デザイン品質目標: Linear／Notion／Stripe Dashboard級
視認性優先: 本文16px以上、見出し24px以上。WCAG AAA相当の高コントラスト
ボタン最小サイズ: 44px×44px。ボーダー半径: 12〜16px
アニメーション: Framer Motionによる意味のあるマイクロインタラクションのみ
PC操作に不慣れな利用者にも配慮した大きなクリック領域・迷わないナビゲーション

7.5 運用・デプロイ

対象	内容
フロントエンド	Cloudflare Pages（プロジェクト名: smart-ec-link）。Git連携なし。`deploy-frontend.sh` によるビルド＋`wrangler pages deploy`
バックエンド	Google Cloud Run（asia-northeast1／サービス名: smart-ec-academy-api）。`gcloud run deploy --source .` でデプロイ
DBマイグレーション	Alembicで管理。起動時スキーマ自動補完（ALTER TABLE IF NOT EXISTS）も併用
環境変数管理	backend/.env.local を正とし、Cloud Run環境変数と同期。上書き事故防止のため `--update-env-vars` のみ使用
バックアップ	DB日次バックアップ（Cloud Scheduler経由の `/api/cron/backup`）
CI	GitHub Actions（PR時）: TypeScript型検査／ESLint／ビルド／flake8／black

8. 関連システム（本体と独立）

本章の2システムは、いずれも会員サイト本体（frontend / backend / DB）とはコード・実行環境・データベースを共有しない独立したシステムである。参照の便宜のため本書に概要を記載するが、詳細設計は各システムの実装・要件を正とする。

8.1 AI説明会システム（temu-ai-meeting）

TEMU運営支援サービスへの見込み客（個人・代理店経由の紹介先）向けに、オンラインでの音声説明会を提供するシステム。会員サイト本体のSupabase Auth／PostgreSQLとは独立した単一のPythonサーバー（backend/scripts/temu_voice_agent_demo.py）として実装され、 Google Cloud Run上に別サービス（サービス名: temu-ai-meeting／asia-northeast1）としてデプロイされている。

項目	内容
アクセス制御	招待キー制。全エンドポイントでキー必須（課金入口封鎖）。代理店ごとにキーを発行し、日次上限・紹介元名を常時表示。キー管理は `manage_agency_keys.py`（CLI）で行う
説明会本編（`/meeting`）	スライド＋TTS音声ナレーションによる自動説明＋OpenAI Realtime API（音声）によるリアルタイム質疑応答。難しい質問はツール経由でClaude（Anthropic API）が裏側で回答を生成し音声に反映
観戦ダッシュボード（`/admin`）	平部専用（マスターキー限定）。視聴中セッションのライブ観戦（3秒更新・現在スライド位置）、代理店別サマリー、会話タイムラインを表示
代理店契約Web同意フォーム（`/agency-contract`）	契約書全文14条＋必須5項目の同意チェックを行うWebフォーム。IP・UserAgent付きで同意記録を保存し、Chatworkへ通知。同意後は控え画面を表示。同意済み一覧は `/admin` から確認可能
面談連携	面談希望が出た場合は記録の上、SEL運営本部Chatworkへ通知（TimeRex予約リンクを提示）
ログ・不正対策	全発話・操作ログをJSONL形式で保存（Cloud RunはGCSマウントで永続化）。同一IPの複数キー使用・同日多セッション等の不審パターンを検知し管理画面に表示。端末別15分/日・IP別/token発行6回/日・キー別質疑5回/日の上限を設定
顧客向け表記	「AI」を前面に出さず「オンライン説明会」と案内（アシスタント自身のAI名乗りは維持）

8.2 稼働チェックツール（TikTok Shop 売上活動モニタリング）

TikTok Shop会員各社の買付・売上管理シートをAIコントローラー（Claude Code）が手動トリガーで自動巡回し、買付（商品仕入れ）の発生有無から稼働・停滞・未稼働を判定し、要対応社を抽出した一覧レポートを平部に提示する内部運用ツール。 UIを持たず、cron等の定期実行も採用しない（サイレント失敗を避けるため手動トリガー方式）。詳細は docs/requirements-activity-checker.md を正とする。

項目	内容
対象範囲	TikTok Shop全社（TEMUは対象外）。顧客管理シートに登録された全社が対象
判定基準	最終買付日からの経過日数で判定: 7日未満=稼働🟢／7〜14日未満=要注意⚠️／14日以上=要対応🔴／買付記録ゼロ=未稼働⬜（別枠）
整合チェック	「運営状況=未払い」表示と買付シートのデポジット入金実態を突き合わせ、入金済みなのに未払い表示のままの社を検出。顧客管理シートのリンク欄欠落（Chatwork概要欄との齟齬）も検出
AI利用範囲	稼働判定そのものにはLLMを使用しない（誤読・捏造が実証されたため禁止）。注文日の表記ゆれ正規化の補助にのみ利用し、決定的ロジックで検算する
セキュリティ	本番シートは読み取り専用。認証情報列は読み取らない。レポートは平部のセッション内表示のみで外部送信・自動投稿は行わない