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

サーバー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: ゼッケン番号

レスポンス:

{
  "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/ パラメータ:

{
  "event_code": "EVENT2025",
  "zekken_number": "001",
  "is_in_rog": true,
  "rogaining_counted": false,
  "ready_for_goal": false,
  "is_at_goal": false
}

レスポンス:

{
  "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）
• 開始時刻の記録
• レスポンスで更新後の競技状態を返す

レスポンス拡張:

{
  "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: チェックポイント番号

レスポンス:

{
  "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日 作成者: システム開発チーム