update APIs

2025-09-04 19:25:14 +09:00
parent 32f860af41
commit e0543e2b4e
8 changed files with 759 additions and 64 deletions
--- a/サーバーAPI変更要求書20250904.md
+++ b/サーバーAPI変更要求書20250904.md
@ -0,0 +1,161 @@
+# サーバー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日
+作成者: システム開発チーム