162 lines
5.0 KiB
Markdown
162 lines
5.0 KiB
Markdown
# サーバー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日
|
||
作成者: システム開発チーム
|