# サーバーAPI変更要求書20250904.md

## 概要
アプリの状態管理において、競技開始状態とゴール状態の保存・復元に関する問題を解決するため、以下のサーバーAPI修正・追加が必要です。

## 問題点の分析

### 1. 競技状態管理の不足
現在のアプリでは以下4つの重要な状態を管理していますが、サーバー側で対応する状態管理機能が不足している可能性があります：

- `isInRog` (ロゲイニング中=スタートしたらTrue)
- `rogainingCounted` (ロゲイニングチェックイン履歴あり=一度でもスタート・ゴール以外でチェックインしたら True)
- `ready_for_goal` (ゴール準備完了=スタートから遠くに移動した際にTrueになる)
- `isAtGoal` (ゴール状態=ゴールしたらTrue)

### 2. チェックイン状態の不整合
チェックポイント詳細画面でスタート処理完了後も「未」のまま表示される問題が発生しています。

## 必要なAPI修正・追加要求

### 1. 競技状態取得API
**エンドポイント**: `GET /api/competition_status/`
**パラメータ**: 
- `event_code`: イベントコード
- `zekken_number`: ゼッケン番号

**レスポンス**:
```json
{
  "status": "OK",
  "data": {
    "is_in_rog": true,
    "rogaining_counted": false,
    "ready_for_goal": false,
    "is_at_goal": false,
    "start_time": "2025-09-04T09:00:00+09:00",
    "goal_time": null,
    "last_checkin_time": "2025-09-04T09:30:00+09:00"
  }
}
```

### 2. 競技状態更新API
**エンドポイント**: `POST /api/competition_status/update/`
**パラメータ**:
```json
{
  "event_code": "EVENT2025",
  "zekken_number": "001",
  "is_in_rog": true,
  "rogaining_counted": false,
  "ready_for_goal": false,
  "is_at_goal": false
}
```

**レスポンス**:
```json
{
  "status": "OK",
  "message": "Competition status updated successfully",
  "updated_at": "2025-09-04T10:00:00+09:00"
}
```

### 3. スタート処理API拡張
**エンドポイント**: `POST /api/start_rogaining/`
**既存機能に以下を追加**:
- 競技状態の確実な更新（is_in_rog = true）
- 開始時刻の記録
- レスポンスで更新後の競技状態を返す

**レスポンス拡張**:
```json
{
  "status": "OK",
  "message": "Rogaining started successfully",
  "competition_status": {
    "is_in_rog": true,
    "rogaining_counted": false,
    "ready_for_goal": false,
    "is_at_goal": false,
    "start_time": "2025-09-04T09:00:00+09:00"
  },
  "checkin_record": {
    "id": 123,
    "cp_number": -2,
    "checkin_time": "2025-09-04T09:00:00+09:00"
  }
}
```

### 4. ゴール処理API拡張
**エンドポイント**: `POST /api/goal_rogaining/`
**既存機能に以下を追加**:
- 競技状態の確実な更新（is_at_goal = true）
- ゴール時刻の記録
- 最終得点の計算

### 5. チェックイン処理API拡張
**エンドポイント**: `POST /api/checkin/`
**既存機能に以下を追加**:
- スタート・ゴール以外のチェックイン時に rogaining_counted = true に設定
- ready_for_goal フラグの管理（GPS位置情報に基づく）

### 6. チェックポイント状態取得API
**エンドポイント**: `GET /api/checkpoint_status/`
**パラメータ**:
- `event_code`: イベントコード
- `zekken_number`: ゼッケン番号
- `cp_number`: チェックポイント番号

**レスポンス**:
```json
{
  "status": "OK",
  "data": {
    "cp_number": -2,
    "is_checked_in": true,
    "checkin_time": "2025-09-04T09:00:00+09:00",
    "status": "競技中",  // "未", "競技中", "競技終了"
    "points_earned": 0
  }
}
```

## 実装上の注意点

### 1. 状態の整合性保証
- 競技状態の変更は必ずトランザクション内で実行
- 状態変更時は必ず関連する全てのテーブルを更新

### 2. エラーハンドリング
- ネットワーク切断時でも状態が失われないような設計
- 重複チェックイン防止機能の実装

### 3. パフォーマンス考慮
- 状態取得APIは高頻度でアクセスされるため、適切なキャッシュ機能を実装
- レスポンス時間は500ms以内を目標

### 4. ログ記録
- 競技状態の変更履歴を詳細にログ記録
- デバッグ用のタイムスタンプ情報を含める

## タイムライン
- **緊急度**: 高
- **実装期限**: 2025年9月10日
- **テスト期間**: 2025年9月11日〜13日
- **本番適用**: 2025年9月14日

## 備考
これらの修正により、アプリ側で以下の問題が解決されます：

1. ✅ 競技中にアプリを終了・再開しても正しい状態が復元される
2. ✅ スタート処理完了後、チェックポイント詳細画面で「競技中」と表示される
3. ✅ 4つの重要な状態（isInRog, rogainingCounted, ready_for_goal, isAtGoal）が確実に保存・復元される
4. ✅ サーバー・クライアント間の状態整合性が保たれる

---
作成日: 2025年9月4日
作成者: システム開発チーム