機能仕様書

1. 文書管理情報

2. API設計

本システムのAPIはRESTfulアーキテクチャに準拠し、JSON形式でリクエスト/レスポンスを行います。 認証にはJWT（JSON Web Token）を使用し、アクセストークン（有効期限15分）とリフレッシュトークン（有効期限7日）の二重トークン方式を採用します。 一覧取得APIにはカーソルベースのページネーションを実装し、大量データの効率的な取得を可能にします。

2.1 認証 API（Auth）

2.2 リード API（Leads）

2.3 オークション API（Auctions）

2.4 案件 API（Cases）

2.5 返金 API（Refunds）

2.6 請求 API（Billing）

2.7 管理 API（Admin）

3. 状態遷移図

各エンティティのライフサイクルをステートマシンとして定義します。 不正な遷移が要求された場合は HTTP 409 Conflict を返却します。

3.1 リードステータス（Lead Status）

  [NEW]
    |
    | スコアリング完了 & オークション作成
    v
  [IN_AUCTION]
    |
    +--- 落札者確定 -----------> [SOLD]
    |
    +--- 入札なし・期限切れ ---> [UNSOLD]
    |                             |
    |                             +--- 再出品（自動/手動）---> [IN_AUCTION]
    |
    +--- 管理者による無効化 ---> [INVALID]

3.2 オークションステータス（Auction Status）

  [SCHEDULED]
    |
    | 開始時刻到達
    v
  [ACTIVE]
    |
    +--- 終了3分前に入札あり ---> [EXTENDED]（3分延長）
    |                               |
    |                               +--- 延長後に再入札 ---> [EXTENDED]（再延長）
    |                               |
    |                               +--- 延長終了 ---------> [COMPLETED]
    |
    +--- 入札あり＆時間終了 -----> [COMPLETED]
    |
    +--- 入札なし＆時間終了 -----> [NO_BID]
    |                               |
    |                               +--- 自動再出品 -------> [SCHEDULED]
    |
    +--- 管理者取消 -------------> [CANCELLED]

3.3 案件ステータス（Case Status）

  [NOT_CONTACTED]
    |
    | 初回連絡実施
    v
  [IN_PROGRESS]
    |
    +--- 連絡不通（3回以上）---> [UNREACHABLE]
    |                             |
    |                             +--- 返金申請 ---> [REFUND_REQUESTED]
    |
    +--- 面談実施 -------------> [MET]
    |                             |
    |                             +--- 成約/終了 ---> [CLOSED]
    |
    +--- 返金申請 -------------> [REFUND_REQUESTED]
    |                             |
    |                             +--- 承認 -------> [CLOSED]（返金処理）
    |                             |
    |                             +--- 却下 -------> [IN_PROGRESS]
    |
    +--- 案件完了 -------------> [CLOSED]

3.4 返金ステータス（Refund Status）

  [PENDING]
    |
    +--- 管理者承認 ---> [APPROVED]（Stripe経由で返金処理）
    |
    +--- 管理者却下 ---> [REJECTED]（理由通知）

4. スコアリングアルゴリズム詳細

LP経由で登録されたリードの品質を0〜100点で定量評価します。 スコアは3つのサブスコアの合計で算出され、オークションのエントリー価格に直接影響します。

4.1 入力完全性スコア（inputScore: 0〜40点）

フォーム入力の充実度を評価します。必須項目と任意項目の入力率、自由記述の文字数を考慮します。

4.2 温度感スコア（temperatureScore: 0〜30点）

顧客の検討緊急度と相談方法から見込み度合いを評価します。

4.3 属性スコア（attributeScore: 0〜30点）

顧客の属性情報から商談成約の見込み度を評価します。

5. 価格算出ロジック

リードのスコアと保険種別に基づき、オークションのエントリー価格・即時購入価格・入札単位を算出します。

5.1 エントリー価格（entryPrice）

5.2 カテゴリ乗数（categoryMultiplier）

5.3 即時購入価格（instantPrice）

5.4 入札単位（bidUnit）

5.5 計算例

6. WebSocket イベント仕様

リアルタイム通信にはWebSocket（Socket.IO互換）を使用します。 オークションの入札状況・終了通知・各種アラートをクライアントにプッシュ配信します。

6.1 サブスクリプション管理

7. エラーコード定義

全APIで統一されたエラーレスポンス形式を使用します。エラーレスポンスには一意のエラーコードを含め、 クライアント側での適切なエラーハンドリングを可能にします。

7.1 認証エラー（AUTH）

7.2 リードエラー（LEAD）

7.3 オークションエラー（AUCTION）

7.4 入札エラー（BID）

7.5 返金エラー（REFUND）

7.6 請求エラー（BILLING）

8. 認可マトリクス

各APIエンドポイントに対するロール別アクセス権限を定義します。 「OK (own)」は自身が関連するリソースのみアクセス可能であることを示します。