CSV出力・APIドキュメント・
クローズドベータ実用化

1. CSV Export API -- データを手元に

店舗オーナーが最も求める機能のひとつは「データを手元に持ち出す」こと。ダッシュボードで見るだけでなく、Excel で加工したり、他のツールに取り込みたい。CSV出力はそのニーズに直接応える。

エンドポイント設計

実装コード

/// GET /api/v1/stores/me/export/csv
pub async fn export_csv(
    State(state): State<AppState>,
    AuthUser(user_id): AuthUser,
    Query(params): Query<CsvExportParams>,
) -> Result<impl IntoResponse, ApiError> {
    let store = get_store_by_owner(&state.pool, &user_id).await?;
    let tier = store.tier.as_deref().unwrap_or("free");

    // Plan guard: csv_export は Pro/Enterprise のみ
    if !tier_has_feature(tier, "csv_export") {
        return Err(ApiError::Forbidden(
            "CSV出力はProプラン以上で利用できます".into()
        ));
    }

    let rows = fetch_visitor_data(
        &state.pool,
        &store.id,
        params.from,
        params.to,
    ).await?;

    // CSV生成 (標準ライブラリのみ)
    let mut csv = String::from("日付,時間,カメラ名,来客数\n");
    for row in &rows {
        csv.push_str(&format!(
            "{},{},{},{}\n",
            row.date, row.time, row.camera_name, row.count
        ));
    }

    let filename = format!(
        "miseban_{}_{}_{}.csv",
        store.name, params.from, params.to
    );

    Ok((
        [
            (header::CONTENT_TYPE, "text/csv; charset=utf-8"),
            (
                header::CONTENT_DISPOSITION,
                &format!("attachment; filename=\"{}\"", filename),
            ),
        ],
        csv,
    ))
}

plan_guard の tier_has_feature(tier, "csv_export") が最初の関門。Free/Starter ユーザーがこのエンドポイントを叩くと、403でアップグレードを促す。Pro/Enterprise ならCSVデータを生成し、Content-Disposition: attachment ヘッダーでブラウザにファイルダウンロードさせる。

Query パラメータ

#[derive(Deserialize)]
pub struct CsvExportParams {
    /// 開始日 (YYYY-MM-DD)
    pub from: NaiveDate,
    /// 終了日 (YYYY-MM-DD)
    pub to: NaiveDate,
}

from と to を必須パラメータにすることで、無制限のデータ取得を防ぐ。日付バリデーションは NaiveDate の Deserialize に任せている。不正な形式なら 400 Bad Request が自動で返る。

2. API Documentation Page -- docs.html

APIドキュメントがないプロダクトは信用されない。ベータユーザーに「APIがある」と言っても、仕様書がなければ使いようがない。Cycle 7 では全18エンドポイントを体系的にドキュメント化した。

認証方式

# Supabase Auth でJWTトークンを取得
curl -X POST https://xxx.supabase.co/auth/v1/token?grant_type=password \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"***"}'

# APIリクエスト (Bearer token)
curl https://misebanai.com/api/v1/stores/me \
  -H "Authorization: Bearer eyJhbG..."

エンドポイント一覧 (抜粋)

レスポンス例

// GET /api/v1/stores/me/usage
{
  "tier": "pro",
  "cameras_used": 3,
  "cameras_max": 16,
  "retention_days": 90,
  "features": [
    ["basic_count", true],
    ["demographics", true],
    ["heatmaps", true],
    ["alerts", true],
    ["line_alerts", true],
    ["csv_export", true],
    ["api_access", true],
    ["custom_models", false]
  ]
}

// GET /api/v1/stores/me/export/csv
// Content-Type: text/csv; charset=utf-8
// Content-Disposition: attachment; filename="miseban_cafe_2026-02-01_2026-02-23.csv"

日付,時間,カメラ名,来客数
2026-02-01,09:00,入口カメラ,12
2026-02-01,10:00,入口カメラ,28
2026-02-01,11:00,入口カメラ,45
...

全エンドポイントに対して curl コマンド + 期待されるレスポンスJSON を記載。ベータユーザーがドキュメントだけで API 連携を実装できる状態を目指した。

3. カスタム 404 エラーページ

些細に見えるが、404ページの品質はプロダクトの信頼感に直結する。ブラウザのデフォルトエラー画面が表示されると「このサービスは雑に作られている」という印象を与える。カスタム404ページは、迷子になったユーザーを正しい場所へ誘導するナビゲーションの役割を果たす。

4. Before / After 比較

Cycle 6 まで残っていた「データ出力」と「API仕様書」の2項目が埋まり、クローズドベータに必要な全8項目が完了した。ダッシュボード、API、決済、法務、オンボーディング、データ出力、ドキュメント、エラーハンドリング。プロダクトとして公開するために必要な要素が揃った。

ベータチェックリスト 8/8: 認証、API、決済、プランガード、法務、オンボーディング、CSV出力、APIドキュメント -- 全項目 DONE。

5. 技術的判断

6. 成果と数字

作成・更新したファイル

1. crates/api/src/csv_export.rs -- CSV出力モジュール (新規、約80行)
2. crates/api/src/main.rs -- mod csv_export 宣言、GET /api/v1/stores/me/export/csv ルート追加 (+15行)
3. web/landing/docs.html -- APIドキュメントページ (新規、約350行)
4. web/landing/404.html -- カスタム404ページ (新規、約60行)

「動くプロダクト」と「使えるプロダクト」は違う。データが出力でき、仕様書があり、迷子にならない。この3つが揃って初めて、ベータユーザーに「使ってください」と言えるプロダクトになる。

7. ロードマップ

7サイクルを経て、ミセバンAIはパブリックベータに耐えうる完成度に到達した。Cycle 8 ではいよいよ実店舗にデプロイし、実データでの動作検証とフィードバック収集に入る。ここからが本番だ。

7サイクル、7週間。ダッシュボードから始まって、API、決済、法務、そしてデータ出力とドキュメントまで。Building in Public で走り続けた結果、ベータに出せるプロダクトが出来上がった。次はユーザーの声を聞く番だ。