店長エージェント MVP 要件定義書

1. プロジェクト概要

1.1 背景

パチンコホールの店長は「数値管理」「シフト作成」「報告書作成」等の膨大な事務作業に追われ、本来注力すべき接客サービス向上や戦略立案に時間を割けていない。本プロジェクトでは、キクヤ向けに開発した「SETTING OPTIMIZER」をベースに、パチンコホール業界向けSaaSとして横展開する。

1.2 目的

• 店長の事務作業を最大77%カットするAI業務支援SaaS
• 月額サブスクリプション型の継続収益モデルの確立
• 複数ホールへのスケーラブルな提供基盤の構築

1.3 MVPスコープ

MVP（Basicプラン相当）として以下の4機能を実装する。

1.4 MVPに含めないもの（Phase 2以降）

• 島図面ヒートマップ（Proプラン）
• 複数店舗比較分析（Proプラン）
• AI営業戦略提案（Business Ownerプラン）
• 財務諸表分析（Business Ownerプラン）

2. システムアーキテクチャ

2.1 全体構成

┌─────────────┐     ┌──────────────────────┐     ┌──────────────┐
│  Frontend   │────▶│  Backend API         │────▶│  Database    │
│  React/TS   │◀────│  FastAPI (Python)    │◀────│  PostgreSQL  │
│  TailwindCSS│     │                      │     │              │
└─────────────┘     │  ┌────────────────┐  │     └──────────────┘
                    │  │ Claude API     │  │
                    │  │ (AI Analyzer)  │  │
                    │  └────────────────┘  │
                    └──────────────────────┘

2.2 既存資産の再利用方針（キクヤ SETTING OPTIMIZER）

Backend（Python / FastAPI）

Frontend（React 19 / TypeScript / Vite / TailwindCSS 4）

2.3 技術スタック

3. 機能要件

3.1 F-01: 計数管理（SETTING OPTIMIZER移植）

キクヤ向けに開発済みの台設定最適化システムをそのまま移植。ホールコンピュータからエクスポートしたCSVと粗利目標を入力し、AIが翌日の台別推奨設定を提案する。

入力

CSVカラム: date, machine_no, model_name, in_medals, out_medals, diff_medals, sales, bonus_count, utilization

処理フロー

1. データ整形: CSVの列マッピング・正規化（csv_loader.py）
2. スコアリング: 台ごとに5指標（平均稼働率30%・トレンド25%・機種人気度15%・台個別偏差15%・ボーナス率15%）を算出
3. 粗利最適化: 全台設定1→低稼働台から設定引上げ→粗利目標に収束
4. スマート最適化: 複数候補（バランス/見せ場/テコ入れ/安定運用）から最適案選定
5. AI分析: Claude APIで自然言語解説・対話Q&A

出力

画面構成

APIエンドポイント（既存）

3.2 F-02: 労務管理（シフト作成）

アルバイトスタッフのシフトを自動作成・調整。希望シフト・スキル・法定労働時間を考慮してAIが最適なシフト表を提案する。

入力

制約条件

• 法定労働時間（週40時間/日8時間）の遵守
• 連続勤務日数の制限（6日以内）
• スキル要件の充足（設定変更可能者が必ず1名以上等）
• 人件費の最適化

出力

APIエンドポイント（新規）

DBテーブル（新規）

-- スタッフマスタ
CREATE TABLE staff (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    name VARCHAR(100) NOT NULL,
    employment_type VARCHAR(20) NOT NULL,
    hourly_rate INTEGER,
    max_weekly_hours INTEGER DEFAULT 40,
    skills JSONB DEFAULT '[]',
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- 希望シフト
CREATE TABLE staff_availability (
    id UUID PRIMARY KEY,
    staff_id UUID NOT NULL REFERENCES staff(id),
    date DATE NOT NULL,
    available_from TIME,
    available_to TIME,
    preference VARCHAR(20) DEFAULT 'available',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- シフト
CREATE TABLE shifts (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    staff_id UUID NOT NULL REFERENCES staff(id),
    date DATE NOT NULL,
    shift_type VARCHAR(20) NOT NULL,
    start_time TIME NOT NULL,
    end_time TIME NOT NULL,
    break_minutes INTEGER DEFAULT 60,
    status VARCHAR(20) DEFAULT 'draft',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 営業カレンダー
CREATE TABLE business_calendar (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    date DATE NOT NULL,
    day_type VARCHAR(20) NOT NULL,
    required_staff JSONB,
    note TEXT
);

3.3 F-03: 報告書作成

日次・週次の営業報告書を、計数データ（F-01）とシフト実績（F-02）から自動生成。テンプレート対応。

処理ロジック

1. テンプレートに定義された項目を各データソースから自動収集
2. Claude APIで自然言語のサマリー文を生成
3. テンプレートに流し込んで報告書を生成

APIエンドポイント（新規）

3.4 F-04: 効果測定（ROI自動算出）

イベント・ライター来店企画等の施策のROIを自動算出。施策前後の売上比較で投資効果を可視化。

処理ロジック

1. 施策実施日の売上を取得
2. 比較基準（直近4週間の同曜日平均）を算出
3. 増分売上 = 施策日売上 - 比較基準
4. ROI = (増分売上 - 施策費用) / 施策費用 x 100
5. Claude APIで施策の評価コメントを生成

APIエンドポイント（新規）

4. マルチテナント要件

論理分離（共有DB + tenant_id）を採用。MVPフェーズでは店舗数が限定的（〜10店舗）のため、インフラコスト最小化を優先。

CREATE TABLE tenants (
    id UUID PRIMARY KEY,
    name VARCHAR(200) NOT NULL,
    slug VARCHAR(50) UNIQUE NOT NULL,
    plan VARCHAR(20) DEFAULT 'basic',
    config JSONB DEFAULT '{}',
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE users (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    name VARCHAR(100) NOT NULL,
    role VARCHAR(20) DEFAULT 'user',
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

認証・認可: JWT認証（既存拡張）、トークンにtenant_id含有、全APIでtenant_id分離強制。ロール: admin / manager / user

5. 非機能要件

5.1 性能要件

5.2 可用性・セキュリティ

5.3 インフラ構成（推奨）

6. API原価試算

7. 画面一覧

8. データモデル概要

tenants ──┬── users
          ├── daily_data (日次実績CSV)
          ├── optimization_runs (最適化実行履歴)
          ├── decisions (設定決定履歴)
          ├── staff ──── staff_availability (希望シフト)
          ├── shifts (確定シフト)
          ├── business_calendar (営業カレンダー)
          ├── reports (報告書)
          ├── report_templates (報告書テンプレート)
          ├── campaigns (施策)
          └── campaign_results (ROI結果)

9. 開発フェーズ

Phase 1（MVP）: 2ヶ月

Phase 2（Proプラン）: 1ヶ月

• 島図面ヒートマップ
• 複数店舗比較分析
• ダッシュボード強化

Phase 3（Business Ownerプラン）: 1ヶ月

• AI営業戦略提案
• 財務諸表連携
• 人的アドバイス連携フロー

10. 受入基準

10.1 機能テスト

10.2 非機能テスト

11. 納品物

12. 前提条件・制約

付録A: 用語集