CastBox ダッシュボード 仕様書

1. 概要

MNP獲得実績を可視化する自社ダッシュボード。Tableauの代替として、Google Sheetsの入力フォーム（成果報告・出発報告）を5分ごとに取得・集計し、FastAPI + Chart.js で表示する。

2. システム構成

[ Google Sheets (入力フォーム) ]
        │ gspread (Service Account認証, readonly)
        ▼
[ core/pipeline.py ] 取得・名寄せ・結合・集計
        │
        ▼
[ api/cache.py ] インメモリ DataFrame + SQLite永続化 + 5分バッチ更新
        │
        ▼
[ api/auth.py ] Firebase Auth ミドルウェア（JWT検証）
        │
        ▼
[ api/main.py ] FastAPI REST + StaticFiles（ui/ をルートにマウント）
        │
        ▼
[ ui/ ] vanilla JS + Chart.js（外部CSS/JS分割済 T-19）
  index.html ← スプラッシュ + ダッシュボード + マイページオーバーレイ
  login.html ← Firebase Auth ログイン画面
  account.html ← アカウント設定（スタンドアロン）

2.1 実行環境

• コンテナ: python:3.12-slim / Cloud Run
• 公開ポート: 8080
• 起動コマンド: uvicorn api.main:app --host 0.0.0.0 --port 8080
• 認証: Service Account（Sheets APIのみ読み取り）
• 認証鍵: secrets/castboard-data-reader-81f1ba38fac7.json U-02 移行予定

2.2 依存ライブラリ

3. データソース

3.1 シート一覧

3.2 集計ロジック

件数パース（_parse_count）

• "3件" / "3" → 数値
• 空文字・テスト|test|見込み|練習|確認 を含む値 → 除外

稼働場所算出（_calc_location）

1. 候補列（H〜N）のいずれかに この中に当てはまるものがない が入っていれば列N（自由記入）を採用
2. そうでなければ H〜M の最初の非空値
3. すべて空なら N

キャリア名寄せ

結合

• 出発報告は (email, dep_date) で dedup（最小タイムスタンプ採用）
• 成果報告 × 出発報告（dedup済）を (email, date) LEFT JOIN
• 氏名解決優先順位: ユーザー登録_V1 → 氏名マスタ → 出発報告の氏名 → emailローカル部

3.3 キャリア列マッピング（成果報告_V3）

4. キャッシュ設計

5. API仕様

5.1 エンドポイント一覧

5.2 共通クエリパラメータ

5.3 レスポンス例

GET /api/summary

{
  "total_count": 309,
  "total_working": 268,
  "avg_per_work": 1.15,
  "by_location": [{"name": "渋谷店", "件数": 42, "稼働数": 28}, ...],
  "by_person":   [{"name": "山田太郎", "件数": 15, "稼働数": 10}, ...],
  "daily":       [{"date": "2026-04-01", "件数": 12, "稼働数": 5}, ...],
  "comments":    [{"date": "2026-04-21", "name": "山田太郎", "comment": "..."}],
  "updated_at":  "2026-04-21T06:00:00+00:00"
}

GET /api/by_carrier

{
  "carriers": {"SB": 80, "YM": 12, "docomo": 60, "au": 50, "ahamo": 8,
               "POVO": 5, "UQ": 10, "楽天": 4, "その他": 2},
  "updated_at": "2026-04-21T06:00:00+00:00"
}

GET /api/filters

{
  "names":     ["山田太郎", "佐藤花子", ...],
  "locations": ["渋谷店", "新宿店", ...],
  "months":    ["2026-04", "2026-03", ...],
  "careers":   ["Softbank", "docomo", "KDDI"]
}

• names は month / career 適用後の 稼働数（出勤日数）降順
• 同数時は氏名昇順で安定ソート

6. フロントエンド仕様

6.1 技術スタック

• vanilla JS（フレームワーク不使用）ES Module形式
• Chart.js 4.4.1 / chartjs-plugin-datalabels 2.2.0 / chartjs-chart-sankey 0.12.1 / html2canvas 1.4.1
• Firebase JS SDK v10（CDN / モジュール形式）: Auth + Firestore
• Material Symbols Outlined
• Comfortaa Variable Font（ロゴ文字専用）/ BIZ UDPGothic（本文フォールバック）

6.2 外部化ファイル構成（T-19 / 2026-04-23）

6.3 主要画面構成

• ヘッダー（static ロゴ・フィルタトグル・ハンバーガーメニュー）
• フィルタバー（クライアント / 対象月 / 氏名 / 稼働場所 / 更新・Download）
• KPI 3枚（件数 / 総稼働数 / 生産）
• カレンダー（件数・生産切替） + 稼働場所ランキング + Sankey（獲得経路）
• 人別ランキング（Lv.バッジ・稼働比例バー・稼働/件数/生産切替）+ ドーナツ（件/% 切替）
• コメント一覧
• マイページオーバーレイ（ハンバーガー押下で固定表示 / ダッシュボード上に重なる）

6.4 マイページ（account overlay）

• Firestore users/{uid}: displayName / companyName / email / updatedAt
• Firestore users/{uid}/login_history: signinTime / device（直近10件）
• Google連携/解除（linkWithPopup / unlinkProvider）
• account.js は IS_OVERLAY フラグで index.html / account.html 両モードを兼用
• データは dashboard 初回ロード時に先行取得 → オーバーレイ開時は即表示

6.3 Splash演出

• 初回ロードと更新ボタン押下時のみ runSplashSequence() 経由で発火
• phase-loading → phase-settle → phase-exit の3段
• 最低表示時間 5秒保証
• フォント: Comfortaa Variable（ui/assets/fonts/Comfortaa-VariableFont_wght.ttf）

6.4 禁止事項（先祖返り防止）

6.5 モバイル対応

• Pull-to-refresh（最上部で下フリック → manualRefresh / オーバーレイ開時は無効）
• フィルターバー開閉アニメ + 欄外タップで閉じる + 遮光
• タップハイライト無効化
• PWA対応: apple-touch-icon 180px / manifest.webmanifest / theme-color #37359A（T-23）
• ヘッダー高さ変数 --header-h: デスクトップ52px / モバイル60px+safe-area

7. デプロイ

gcloud run deploy castbox-dashboard \
  --source . \
  --region asia-northeast1 \
  --allow-unauthenticated \
  --set-secrets "GOOGLE_SA_KEY_JSON=castbox-sa-key:latest" \
  --quiet

• --allow-unauthenticated: 認証なし公開（Firebase Auth はフロント側で実施）
• SA鍵は castbox-sa-key（Secret Manager）経由で注入。Dockerイメージには含まれない（T-21完了）
• UI変更も本コマンドのみで反映（firebase deploy 不要）

8. セキュリティ

8.1 SA鍵管理（T-21完了 2026-04-24）

• SA鍵は castbox-sa-key（Secret Manager）に登録済み
• secrets/ は .dockerignore 除外済み → Dockerイメージには含まれない
• ローカル開発は secrets/ 配下の鍵ファイルをフォールバックで使用

8.2 Firebase認証

• フロント: Firebase SDK v10 / ID トークンを castbox_id_token (localStorage) に保存
• バックエンド: api/auth.py が firebase-admin でトークン検証
• DEV: DEV_SKIP_AUTH=1 環境変数でバイパス（本番未設定）
• Firestore規則: users/{uid}/{document=**} → 本人のみ読み書き可

8.3 グローバル運用規則

• .env / .env.local は読み取り禁止・内容出力禁止
• 本番DBへの直接操作禁止
• git push --force 禁止

9. タスク状況

完了

バックログ