運用保守ドキュメント

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

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

文書バージョン	1.0
発行日	2026-07-27
作成者	RERISE JAPAN開発チーム
対象システム	会員サイト（frontend / backend / DB）
参照文書	docs/client-docs/basic-design.html（基本設計書）／ docs/requirements.md

承認

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

改訂履歴

版数	改訂日	改訂者	改訂内容
1.0	2026-07-27	RERISE JAPAN開発チーム	初版作成。CLAUDE.md（デプロイ手順・環境変数運用ルール）、docs/SCOPE_PROGRESS.md、deploy-frontend.sh／deploy-backend.sh、backend/src/routers 実装、docs/requirements.md を基に現行運用の実態を反映した運用保守ドキュメントとして作成。

目次
システム構成概要
日常運用手順
デプロイ手順
障害対応手順
バックアップ・データ管理
よくある質問（FAQ）
連絡体制

1. システム構成概要

1.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

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

1.2 コンポーネント一覧

区分	内容
フロントエンド	React 19 / TypeScript 5 / shadcn/ui / Tailwind CSS / Vite 7 / Framer Motion。配信基盤: Cloudflare Pages（プロジェクト名 `smart-ec-link`）
バックエンド	Python 3.12+ / FastAPI / SQLAlchemy 2.0 / Alembic。実行基盤: Google Cloud Run（リージョン asia-northeast1／サービス名 `smart-ec-academy-api`）
データベース	PostgreSQL（Supabase Free プラン）。スキーマ変更はAlembicマイグレーションで管理
認証	Supabase Auth（JWT + RLS + TOTP 2要素認証）
AI	Gemini 2.5 Flash（google-genai SDK）。議事録の要約生成・タスク抽出・前回タスク照合に利用（無料枠 250 RPD）
動画配信	Cloudflare R2 + Workers（署名付きURL方式）
外部連携	Chatwork API（通知）／ Zoom API・Webhook（議事録取込）／ Google Sheets・Drive API（議事録・デポジット・契約管理シート連携）

1.3 ポート番号（開発環境）

対象	ポート
フロントエンド（開発サーバー）	3847
バックエンド（開発サーバー）	7795

開発サーバーは1プロジェクトにつき1つのみ維持する。別ポートでの重複起動は行わない。

1.4 サービスURL・GCPプロジェクト

項目	内容
バックエンドAPI URL	`https://smart-ec-academy-api-786237390070.asia-northeast1.run.app`
フロントエンドURL	`https://smart-ec-link.pages.dev`（独自ドメイン運用時はそちらを正とする）
GCPプロジェクト	`gen-lang-client-0630810646`（2026-04-14 移行完了。当プロジェクトには `smart-ec-academy-api` のみが存在し、他サービスとは同居していない）
Cloud Runサービス名	`smart-ec-academy-api`

⚠️ 他プロジェクトとの混同注意

旧GCPプロジェクト roulette-jelly-ec 上の smart-ec-academy-api は2026-04-14に削除済み。roulette-jelly-ec / ai-agent-biz-2026 / crevio-platform / tiktokshop-research / amazon-catalog-tool 等、他事業のGCPプロジェクトに対して本システムのコマンドを実行しないこと。Cloudflare Pagesも smart-ec-link（本番）と smart-ec-academy（旧・テスト用）を混同しないこと。

2. 日常運用手順

2.1 会員管理

管理画面（オーナー／管理者権限）の会員管理ページから、会員の登録状況・契約プラットフォーム（platforms 配列）・ロールを確認する。

管理画面にログインし、会員管理ページを開く
会員一覧から対象会員を検索（氏名・メールアドレス）
契約状況（プラットフォーム別）・ロール（オーナー／管理者／スクール+／スクール）を確認
変更が必要な場合は該当項目を編集し保存する

会員登録自体はバックエンドAdmin APIによる一括処理（/api/contracts/register）で行われ、登録時にスプレッドシート追記・Chatwork通知が自動実行される。

2.2 Q&A承認

会員からの質問はQ&Aページに投稿され、AIアシスタント（伊藤遥）がドラフト回答を生成する。本番掲載は平部の承認のみで公開可能とする運用であり、松田承認のチェックは不要（平部が別途松田に確認する運用のため）。

管理画面「Q&A管理」（旧・運営本部ハブ、現在は/admin/opsにQ&A管理として集約）を開く
AIドラフト回答の内容を確認・必要に応じて編集
「平部承認」を実行すると status='published' に遷移し、Q&Aページに即時反映される

⚠️ 承認運用の注意

承認のないQ&Aを勝手に公開掲載しない。会員が閲覧する情報の信頼性に直結するため、承認は必ず平部本人が実行する。

2.3 議事録運用

運営者ミーティング（松田氏×平部、週3回）の議事録は、Zoom Webhookからの自動取込パイプラインで処理される。

Zoom会議終了

→

Webhook（transcript_completed）

→

VTT取得

→

Gemini分析（要約・タスク抽出）

→

下書き保存

→

管理画面で確認・確定

Zoom AI要約（日付・数値をハルシネーションする性質があるため）は使用せず、必ずVTT（transcript）を情報源とする。VTT自動取得が使えない場合は、genspark等で作成した議事録の共有URL／テキストを管理画面から貼り付ける手動フォールバックが利用できる（レガシー扱い）。

⚠️ 議事録の承認・公開は管理画面ボタンでは実行しない

管理画面の「承認してスプシ＋HTML公開」ボタンは、公開先ディレクトリがローカルリポジトリ前提の実装になっているため、Cloud Run上では正しく動作しない（公開URLが生成されず、承認済みドラフトのみ削除される事故につながる）。議事録の承認・公開は必ずローカル環境で実行する手順とし、承認後はスプレッドシート（環境変数 MINUTES_SHEET_ID で指定・松田氏と共有）へ本体行・タスク・論点を書き込み、DB上の下書き（meeting_minute_drafts）は削除する。確定議事録の単一真実源はスプレッドシートであり、DBには確定議事録を残さない。

議事録データ・タスク一覧はオーナー権限のみアクセス可能。タスク担当者は平部／松田のみ。

2.4 デポジット週次運用

TEMU顧客のデポジット残高不足の催促は、会員サイトの管理画面ではなくChatwork上で運用する（/admin/deposits画面は廃止済み）。

毎週月曜朝、算定ロジックにより顧客ごとの残高・目標額・不足額・推奨入金額を算出
不足額が最小入金単位（¥20,000）未満の顧客は催促対象から除外
平部個人のChatworkルームに、伊藤bot名義で承認URL付きの催促候補メッセージが1顧客1件投稿される
平部が承認URLをタップ→確認画面で内容確認→送信実行ボタンで顧客ルームへ催促メッセージが投稿される

承認URLはHMAC署名付き・有効期限7日。直近5日以内に張さん（スマート社担当）が催促済みの顧客ルームは自動除外される。

2.5 Chatwork通知運用

通知内容	トリガー
コンテンツ追加・レポート更新・お知らせ公開	各機能の管理画面操作時に自動投稿
議事録タスクのリマインド	未完了タスクを次回ミーティング前日に通知
Q&A回答ドラフト	AIボット（伊藤遥）が生成し承認後に公開
申込フォーム（Google Forms経由）の受信	SEL運営本部Chatwork（room_id 434842968）へ即時通知。取りこぼし防止のため会員アカウントは自動作成しない
決済スクリーンショットのアップロード失敗	SEL運営本部Chatworkへ即時アラート＋Google Formハイブリッド予備経路の案内

3. デプロイ手順

⚠️ デプロイの大原則

デプロイはユーザー（平部）の明示的な承認を得てから実行する。承認を得ずにデプロイコマンドを実行しない。

3.1 フロントエンドデプロイ

フロントエンドはCloudflare Pages（プロジェクト名 smart-ec-link）で配信している。Git連携は行っておらず、git pushでは自動デプロイされない。必ず以下のスクリプトを実行する。

./deploy-frontend.sh

スクリプトの内容: cd frontend → npm run build → npx wrangler pages deploy dist --project-name smart-ec-link --branch main --commit-dirty=true

⚠️ mainとdevelop両方へのデプロイ

フロントエンドデプロイはmainブランチ・developブランチの両方に同時実行する運用とする。developのみの単独デプロイは行わない。

3.2 バックエンドデプロイ

バックエンドはGoogle Cloud Run（サービス名 smart-ec-academy-api）で稼働している。デプロイは以下のスクリプトのみを使用し、生の gcloud コマンドを直接叩かない。

./deploy-backend.sh

スクリプトは以下の3ステップを自動実行する。

致命バグ検査（flake8 --select=F821,F822,F823,E9：未定義名・構文エラーの検出）
コンパイル検査（python -m compileall）
Cloud Runデプロイ（gcloud run deploy --source . --region asia-northeast1 --project gen-lang-client-0630810646）

致命バグ検査を必須化しているのは、2026-06-04〜07-08に発生した owner_approve 関数のNameError（未定義名によるクラッシュ）が本番に流出した事故の再発防止のため。

3.3 環境変数の扱い

項目	内容
真実源	`backend/.env.local`。Cloud Runの環境変数と常に同期させる
禁止コマンド	`gcloud run services update --set-env-vars`（全環境変数が上書きされる事故の原因となるため禁止）
正しいコマンド	`--update-env-vars` のみを使用する。複数変数を指定する場合は区切り文字 `###` を使う

⚠️ 区切り文字のデリミタ宣言忘れに注意

--update-env-vars で ### 区切りを使う場合、先頭に ^###^ のデリミタ宣言が必須。これを怠ると複数の値が1つの環境変数に連結されてしまい、Sheets API等の外部連携が404エラーになる事故につながる。単一の環境変数のみ変更する場合は KEY=value 単体で渡す方が安全。

環境変数はfrontend/backendとも .env.local のみを使用する（.env、.env.test、.env.development、.env.example は作成しない）。frontendは VITE_* プレフィックス必須。ハードコード禁止（process.env / import.meta.env は設定モジュール経由のみ）。

4. 障害対応手順

4.1 環境変数エラー

エラーメッセージから対象の環境変数名を特定する
backend/.env.local（またはfrontendの .env.local）に該当キーが設定されているか確認する
Cloud Run側の環境変数と値が一致しているか確認する（3.3節参照）
試行錯誤は行わず、原因が環境変数であると判明した時点で作業を停止し、平部へ即報告する

4.2 DB接続エラー

まずSupabase Dashboardでプロジェクトの稼働状況を確認する（一時停止・容量超過等がないか）
DATABASE_URL の値が正しいか、接続文字列の形式に誤りがないかを確認する
SQLAlchemyのスキーマ不整合エラーが出ている場合は alembic upgrade head を実行する
1回だけ再試行し、解消しない場合はDB接続エラーとして即報告する
同一エラーが3回続く場合はWeb検索で最新情報を収集してよい

4.3 Supabase Dashboard確認手順

DB関連の異常が疑われる場合、まずSupabase Dashboardで以下を確認する。

プロジェクトのステータス（稼働中／一時停止）
テーブルスキーマとAlembicマイグレーション履歴の整合性
Auth（Supabase Auth）のユーザー一覧・ロール（app_metadata.role）
APIログ・エラーログ

4.4 過去障害事例

事例: JSONカウンタファイルの破損による503エラー（2026-07-24〜07-26発生）

利用状況を記録するJSONカウンタファイルが空ファイル化する事象が発生し、そのファイルを読み取る関数が例外を送出したことで、当該機能への全リクエストが503エラーとなる障害が2日間継続した。

恒久対応: カウンタファイルの読み取り処理を、JSONパースに失敗しても例外を送出せず空データとして継続処理する「破損耐性のある読み取り」に修正した。破損したファイル自体もクラウドストレージ上で空オブジェクト（{}）に修復した。

教訓: キャッシュ・カウンタ用途の補助ファイルであっても、読み取り失敗時に全リクエストを落とす実装にしない。読み取り関数は「壊れたデータは初期値として扱い処理を継続する」フェイルセーフな設計とすること。

事例: 甲承認クラッシュ（owner_approve NameError、2026-06-04〜07-08流出）

契約の甲側承認処理（owner_approve）内で未定義の変数（phase_types）を参照しており、本番環境でNameErrorによるクラッシュが発生していた。

恒久対応: バグを修正した上で、デプロイスクリプト（deploy-backend.sh）に flake8 --select=F821,F822,F823,E9 による致命バグ検査を必須化し、未定義名・構文エラーを含むコードが本番にデプロイされることを構造的に防止した。

5. バックアップ・データ管理

5.1 スキーマ変更・マイグレーション

SQLAlchemyモデル（backend/app/models/__init__.py）を変更する
alembic revision --autogenerate でマイグレーションファイルを生成する
生成内容を確認後、alembic upgrade head を実行してDBに反映する

起動時にはスキーマ自動補完（ALTER TABLE IF NOT EXISTS）も併用しているが、正式なスキーマ管理はAlembicマイグレーションを正とする。

5.2 単一真実源（データ・ドキュメントの正）一覧

対象	真実源
型定義	`frontend/src/types/index.ts`（変更時はフロントエンド→バックエンドの順で同期）
SQLAlchemyモデル（DB定義）	`backend/app/models/__init__.py`
要件定義	`docs/requirements.md`
実装進捗・計画	`docs/SCOPE_PROGRESS.md`
デプロイ情報	`docs/DEPLOYMENT.md`
環境変数	`backend/.env.local`（Cloud Run環境変数と同期）
確定議事録	Googleスプレッドシート（`MINUTES_SHEET_ID`で指定・松田氏と共有）。DBの下書きテーブルは承認後に削除

5.3 データ管理上の注意

Supabase Storageのキーは非ASCII文字を扱えないため、日本語ファイル名はアップロード前に無害化処理を行う。失敗時は運営本部Chatworkへ即アラートする
顧客管理スプレッドシートの列構成はスマート社側で変更される可能性があるため、列定義を参照するコードは実ヘッダーとの同期を都度確認する
本番の実顧客データ・実ユーザーIDをテストに使用する場合は、必ず事前に平部の承認を得る

6. よくある質問（FAQ）

Q. サーバーがすでに起動している場合、再起動してよいか

A. サーバーは1つのみ維持する運用のため、既存プロセスがある場合は再起動せずそのまま利用する。環境変数を変更した場合のみ再起動が必要。

Q. フロントエンドの変更をgit pushしたのに本番に反映されない

A. 想定通りの挙動。フロントエンドはCloudflare Pagesとのgit連携を行っていないため、./deploy-frontend.sh を実行しない限り反映されない。

Q. バックエンドのコードを直接 `gcloud run deploy` でデプロイしてよいか

A. 不可。必ず ./deploy-backend.sh を使用する。生のgcloudコマンドは致命バグ検査（flake8/compileall）を経由しないため、過去のNameError本番流出事故の再発リスクがある。

Q. デポジットの入金催促を会員サイトの管理画面から行えるか

A. 行えない。/admin/deposits画面は廃止済みで、デポジット催促はChatwork上の週次運用スキームで実施する（2.4節参照）。

Q. 議事録の承認・公開ボタンを管理画面で押してよいか

A. 押さない。ボタンの実装はローカルリポジトリの存在を前提としており、Cloud Run上では公開URLが生成されずドラフトのみ消失する事故につながる。承認・公開作業は必ずローカル環境で行う（2.3節参照）。

Q. Q&A回答の公開に松田さんの承認も必要か

A. 不要。平部の承認のみで公開できる運用（平部が別途松田に確認するため、二重承認は行わない）。

7. 連絡体制

7.1 Chatwork運営体制

ルーム	用途
SEL運営本部Chatworkグループ	承認・アラートの集約先。申込フォーム受信通知、決済スクリーンショットアップロード失敗アラート等を集約
平部個人Chatworkルーム	デポジット週次催促の承認URL送信、システム開発関連のアラート通知先

7.2 承認フローの原則

本番DB操作・外部への投稿（Chatwork送信・メール送信等）は、必ず平部の明示的な承認（「OK」「実行して」等）を得てから実行する
Q&A公開・デポジット催促送信・議事録公開はいずれも平部単独の承認で実行可能とし、複数承認による多重フローは設けない
デプロイ（フロントエンド・バックエンドとも）は、平部の明示的な承認を得てから実行する

承認