Fix some APIs

2025-09-02 23:14:14 +09:00
parent 9f27357a3b
commit 8ffedc177f
11 changed files with 974 additions and 287 deletions
--- a/外部システムAPI仕様書.md
+++ b/外部システムAPI仕様書.md
@ -9,6 +9,23 @@
 - **データ形式**: JSON
 - **文字エンコーディング**: UTF-8

+## 重要な注意事項
+APIへのアクセスには以下の点にご注意ください：
+
+### URL構成
+- **管理画面・認証系**: `/api/` プレフィックスが必要
+- **ロゲイニング競技系**: `/api/` プレフィックスが必要
+- **例**: `POST /api/start_from_rogapp`, `GET /api/getCheckinList`
+
+### 未実装API
+以下のAPIは仕様書に記載されていますが、現在未実装です：
+- `/api/get_checkpoints` - チェックポイント一覧取得
+- `/api/current_ranking` - 現在ランキング
+- `/api/get_teams` - チーム一覧取得
+
+### 一時的に無効化されているAPI
+- `/api/getRoute` - ルート情報取得（データベース構造変更により一時的に無効）
+
 ## 認証について
 APIへのアクセスには認証トークンが必要です。ログイン後に取得したトークンをHTTPヘッダーに含めてリクエストしてください。

@ -312,7 +329,7 @@ Content-Type: application/json
 ### 4.1 スタート処理
 ロゲイニングのスタート処理を行います。

-**エンドポイント**: `POST /start_from_rogapp`
+**エンドポイント**: `POST /api/start_from_rogapp`

 **リクエストパラメータ**:
 ```json
@ -348,7 +365,7 @@ Content-Type: application/json
 ### 5.1 チェックイン登録
 チェックポイント通過時のチェックイン処理を行います。

-**エンドポイント**: `POST /checkin_from_rogapp`
+**エンドポイント**: `POST /api/checkin_from_rogapp`

 **リクエストパラメータ**:
 ```json
@ -386,7 +403,7 @@ Content-Type: application/json
 ### 5.2 チェックイン削除
 誤って登録したチェックインを削除します。

-**エンドポイント**: `POST /remove_checkin_from_rogapp`
+**エンドポイント**: `POST /api/remove_checkin_from_rogapp`

 **リクエストパラメータ**:
 ```json
@ -406,6 +423,14 @@ Content-Type: application/json
 }
 ```

+**レスポンス（エラー時）**:
+```json
+{
+  "status": "ERROR",
+  "message": "指定されたチェックポイント記録が見つかりません"
+}
+```
+
 ---

 ## 6. 買い物ポイント・QRコード登録API
@ -413,7 +438,7 @@ Content-Type: application/json
 ### 6.1 買い物ポイント写真登録
 買い物ポイントでのレシート写真を登録します。

-**エンドポイント**: `POST /checkin_from_rogapp`
+**エンドポイント**: `POST /api/checkin_from_rogapp`

 **リクエストパラメータ**:
 ```json
@ -442,7 +467,7 @@ Content-Type: application/json
 ### 6.2 QRコード登録
 QRコードを使用したチェックイン登録を行います。

-**エンドポイント**: `POST /input_cp`
+**エンドポイント**: `POST /api/input_cp`

 **リクエストパラメータ**:
 ```json
@ -473,7 +498,7 @@ QRコードを使用したチェックイン登録を行います。
 ### 7.1 ゴール処理
 ゴール時の処理を行い、通過証明書を生成します。

-**エンドポイント**: `POST /goal_from_rogapp`
+**エンドポイント**: `POST /api/goal_from_rogapp`

 **リクエストパラメータ**:
 ```json
@ -573,7 +598,7 @@ zekken_number=101&event_code=岐阜ロゲイニング2025
 ### 9.1 イベントコード確認
 イベントコードの有効性を確認します。

-**エンドポイント**: `POST /check_event_code`
+**エンドポイント**: `POST /api/check_event_code`

 **リクエストパラメータ**:
 ```json
@ -596,31 +621,260 @@ zekken_number=101&event_code=岐阜ロゲイニング2025
 ### 9.2 チェックインリスト取得
 チームのチェックイン履歴を取得します。

-**エンドポイント**: `GET /checkins/{zekken_number}/{event_code}/`
+**エンドポイント**: `GET /getCheckinList`
+
+**リクエストパラメータ**:
+```
+zekken=<ゼッケン番号>&event=<イベントコード>
+```

 **レスポンス（成功時）**:
 ```json
 {
-  "team_name": "チーム名",
-  "zekken_number": "101",
-  "checkins": [
+  "status": "OK",
+  "team_info": {
+    "zekken_number": "001",
+    "team_name": "チーム名",
+    "event_code": "岐阜ロゲイニング2025"
+  },
+  "checkpoints": [
    {
-      "cp_number": 1,
-      "checkin_time": "2025-09-15T11:30:00Z",
-      "point_value": 10,
-      "image_url": "https://example.com/photos/checkpoint1.jpg"
-    },
-    {
-      "cp_number": 5,
-      "checkin_time": "2025-09-15T12:15:00Z",
-      "point_value": 15,
-      "image_url": "https://example.com/photos/checkpoint5.jpg"
+      "id": 123,
+      "cp_number": "1",
+      "checkin_time": "2025-09-15 11:30:00",
+      "image_url": "https://example.com/photos/checkpoint1.jpg",
+      "is_service_checked": false,
+      "cp_point": 10,
+      "cp_name": "市役所"
    }
  ],
-  "total_score": 25
+  "start_info": {
+    "start_time": "2025-09-15 10:00:00"
+  },
+  "goal_info": {
+    "goal_time": "2025-09-15 13:45:00",
+    "score": 150,
+    "scoreboard_url": "https://example.com/scoreboards/team_001.pdf"
+  }
 }
 ```

+**レスポンス（エラー時）**:
+```json
+{
+  "status": "ERROR",
+  "message": "指定されたゼッケン番号のチームが見つかりません"
+}
+```
+
+### 9.3 通過履歴承認
+ユーザーが自分のチームの通過履歴を確認し、承認確定する処理を行います。
+
+**エンドポイント**: `POST /api/approve_checkin_history`
+
+**認証**: 必須（Token認証）
+
+**リクエストパラメータ**:
+```json
+{
+  "event_code": "岐阜ロゲイニング2025",
+  "zekken_number": "001",
+  "checkin_ids": [123, 124, 125],
+  "approval_comment": "通過履歴を確認し、すべて正確です"
+}
+```
+
+**パラメータ説明**:
+- `event_code`: イベントコード（必須）
+- `zekken_number`: ゼッケン番号（必須）
+- `checkin_ids`: 承認するチェックインIDのリスト（必須）
+- `approval_comment`: 承認コメント（任意）
+
+**レスポンス（成功時）**:
+```json
+{
+  "status": "OK",
+  "message": "通過履歴の承認が完了しました",
+  "approved_count": 3,
+  "approved_checkins": [
+    {
+      "checkin_id": 123,
+      "cp_number": "1",
+      "approved_at": "2025-09-02 15:30:00"
+    },
+    {
+      "checkin_id": 124,
+      "cp_number": "5",
+      "approved_at": "2025-09-02 15:30:00"
+    },
+    {
+      "checkin_id": 125,
+      "cp_number": "8",
+      "approved_at": "2025-09-02 15:30:00"
+    }
+  ],
+  "team_info": {
+    "team_name": "チーム名",
+    "zekken_number": "001",
+    "event_code": "岐阜ロゲイニング2025"
+  }
+}
+```
+
+**レスポンス（エラー時）**:
+```json
+{
+  "status": "ERROR",
+  "message": "指定されたチェックイン記録が見つかりません",
+  "error_details": {
+    "invalid_checkin_ids": [126, 127],
+    "valid_checkin_ids": [123, 124, 125]
+  }
+}
+```
+
+**レスポンス（権限エラー時）**:
+```json
+{
+  "status": "ERROR",
+  "message": "このチームの通過履歴を承認する権限がありません"
+}
+```
+
+### 9.4 写真一括アップロード・通過履歴校正
+スマホアルバムから複数の写真を一括アップロードし、EXIF情報から自動的に通過履歴を生成・校正する処理を行います。
+
+**エンドポイント**: `POST /api/bulk_upload_checkin_photos/`
+
+**認証**: 必須（Token認証）
+
+**Content-Type**: `multipart/form-data`
+
+**リクエストパラメータ**:
+```
+event_code: 岐阜ロゲイニング2025 (必須)
+zekken_number: 001 (必須) 
+photos: [file1.jpg, file2.jpg, file3.jpg, ...] (必須・最大50ファイル)
+auto_process: true (任意・デフォルト: true)
+```
+
+**パラメータ説明**:
+- `event_code`: イベントコード（必須）
+- `zekken_number`: ゼッケン番号（必須）
+- `photos`: アップロードする写真ファイルのリスト（必須・最大50ファイル）
+- `auto_process`: EXIF情報から自動処理を行うかどうか（任意・デフォルト: true）
+
+**対応ファイル形式**: JPG, JPEG, PNG, HEIC
+**ファイルサイズ制限**: 1ファイルあたり最大10MB
+
+**レスポンス（成功時）**:
+```json
+{
+  "status": "OK",
+  "message": "写真の一括アップロードが完了しました",
+  "upload_summary": {
+    "total_files": 15,
+    "successful_uploads": 12,
+    "failed_uploads": 3,
+    "upload_time": "2025-09-02 16:30:00"
+  },
+  "team_info": {
+    "team_name": "チーム名",
+    "zekken_number": "001",
+    "event_code": "岐阜ロゲイニング2025"
+  },
+  "processed_files": [
+    {
+      "filename": "photo001.jpg",
+      "file_index": 1,
+      "file_size": 2048576,
+      "status": "uploaded",
+      "saved_path": "bulk_checkin_photos/岐阜ロゲイニング2025/001/20250902_163000_001_photo001.jpg",
+      "file_url": "/media/bulk_checkin_photos/岐阜ロゲイニング2025/001/20250902_163000_001_photo001.jpg",
+      "upload_time": "2025-09-02 16:30:00",
+      "auto_process_status": "pending",
+      "auto_process_message": "EXIF解析機能は今後実装予定です"
+    },
+    {
+      "filename": "photo002.jpg",
+      "file_index": 2,
+      "status": "failed",
+      "error": "サポートされていないファイル形式: .bmp"
+    }
+  ],
+  "auto_process_enabled": true,
+  "next_steps": [
+    "アップロードされた写真のEXIF情報解析",
+    "GPS座標からチェックポイント自動判定",
+    "通過履歴の自動生成と校正",
+    "ユーザーによる確認と承認"
+  ]
+}
+```
+
+**レスポンス（エラー時）**:
+```json
+{
+  "status": "ERROR",
+  "message": "一度にアップロードできる写真は最大50枚です"
+}
+```
+
+**レスポンス（権限エラー時）**:
+```json
+{
+  "status": "ERROR",
+  "message": "このチームの写真をアップロードする権限がありません"
+}
+```
+
+### 9.5 一括アップロード状況取得
+写真一括アップロードの処理状況を取得します。
+
+**エンドポイント**: `GET /api/get_bulk_upload_status/`
+
+**認証**: 必須（Token認証）
+
+**リクエストパラメータ**:
+```
+event_code=岐阜ロゲイニング2025&zekken_number=001
+```
+
+**レスポンス（成功時）**:
+```json
+{
+  "status": "OK",
+  "team_info": {
+    "team_name": "チーム名",
+    "zekken_number": "001",
+    "event_code": "岐阜ロゲイニング2025"
+  },
+  "upload_status": {
+    "total_uploaded_files": 15,
+    "processed_files": 12,
+    "pending_files": 3,
+    "auto_checkins_generated": 8,
+    "manual_review_required": 4
+  },
+  "implementation_status": "基本機能実装完了、詳細処理は今後実装予定"
+}
+```
+
+**処理フロー**:
+1. **写真アップロード**: 複数の写真ファイルを安全にサーバーに保存
+2. **EXIF情報解析**: GPS座標、撮影時刻などのメタデータを抽出（今後実装）
+3. **自動チェックイン判定**: GPS座標から最寄りのチェックポイントを特定（今後実装）
+4. **通過履歴生成**: 撮影時刻順にソートして通過履歴を自動生成（今後実装）
+5. **ユーザー確認**: 生成された履歴をユーザーが確認・修正（今後実装）
+6. **履歴確定**: 承認されたチェックイン記録をデータベースに保存（今後実装）
+
+**今後の実装予定機能**:
+- EXIF情報からのGPS座標・撮影時刻自動抽出
+- チェックポイント自動判定アルゴリズム
+- 時系列自動ソート機能
+- 重複チェック・エラー検出機能
+- ユーザーによる手動校正インターフェース
+
 ---

 ## 10. エントリー管理API
@ -821,31 +1075,83 @@ curl -X PUT "/entry/123/update-status/" \

 9. **スタート**
   ```bash
-   curl -X POST "/start_from_rogapp" -d '{"event_code":"岐阜ロゲイニング2025","team_name":"サンプルチーム"}'
+   curl -X POST "/api/start_from_rogapp" -d '{"event_code":"岐阜ロゲイニング2025","team_name":"サンプルチーム"}'
   ```

 10. **チェックイン**
    ```bash
-    curl -X POST "/checkin_from_rogapp" -d '{"event_code":"岐阜ロゲイニング2025","team_name":"サンプルチーム","cp_number":1,"image":"https://example.com/photo1.jpg"}'
+    curl -X POST "/api/checkin_from_rogapp" -d '{"event_code":"岐阜ロゲイニング2025","team_name":"サンプルチーム","cp_number":1,"image":"https://example.com/photo1.jpg"}'
    ```

 11. **ゴール**
    ```bash
-    curl -X POST "/goal_from_rogapp" -d '{"event_code":"岐阜ロゲイニング2025","team_name":"サンプルチーム","image":"https://example.com/goal.jpg"}'
+    curl -X POST "/api/goal_from_rogapp" -d '{"event_code":"岐阜ロゲイニング2025","team_name":"サンプルチーム","image":"https://example.com/goal.jpg"}'
    ```

-12. **ゴール後ステータス更新**
+12. **通過履歴承認**
+    ```bash
+    curl -X POST "/api/approve_checkin_history" -H "Authorization: Token <token>" -d '{"event_code":"岐阜ロゲイニング2025","zekken_number":"001","checkin_ids":[123,124,125],"approval_comment":"通過履歴確認完了"}'
+    ```
+
+13. **写真一括アップロード（アルバムから通過履歴校正）**
+    ```bash
+    curl -X POST "/api/bulk_upload_checkin_photos/" -H "Authorization: Token <token>" -F "event_code=岐阜ロゲイニング2025" -F "zekken_number=001" -F "auto_process=true" -F "photos=@photo1.jpg" -F "photos=@photo2.jpg" -F "photos=@photo3.jpg"
+    ```
+
+14. **一括アップロード状況確認**
+    ```bash
+    curl -X GET "/api/get_bulk_upload_status/?event_code=岐阜ロゲイニング2025&zekken_number=001" -H "Authorization: Token <token>"
+    ```
+
+15. **ゴール後ステータス更新**
    ```bash
    curl -X PUT "/entry/123/update-status/" -H "Authorization: Token <token>" -d '{"hasParticipated": true, "hasGoaled": true}'
    ```

-13. **証明書取得**
+16. **証明書取得**
    ```bash
-    curl "/download_scoreboard?zekken_number=101&event_code=岐阜ロゲイニング2025"
+    curl "/api/download_scoreboard?zekken_number=101&event_code=岐阜ロゲイニング2025"
    ```

 ---

+## 更新履歴
+
+### 2025年9月2日 - APIテスト結果による仕様書修正
+
+#### 修正内容
+1. **エンドポイントURL修正**
+   - 全ての競技系APIに `/api/` プレフィックスを追加
+   - 実際のエンドポイント名に合わせて修正
+
+2. **未実装API情報の追加**
+   - `/api/get_checkpoints` - チェックポイント一覧取得（未実装）
+   - `/api/current_ranking` - 現在ランキング（未実装）
+   - `/api/get_teams` - チーム一覧取得（未実装）
+
+3. **一時的に無効化されているAPI**
+   - `/api/getRoute` - データベース構造変更により一時的に無効
+
+4. **レスポンス形式の修正**
+   - `getCheckinList` APIのレスポンス構造を実際の仕様に合わせて修正
+   - エラーレスポンスの実際の形式を追記
+
+5. **動作確認済みAPI**
+   - `start_from_rogapp` - スタート処理
+   - `checkin_from_rogapp` - チェックイン処理
+   - `goal_from_rogapp` - ゴール処理
+   - `input_cp` - QRコードチェックイン
+   - `remove_checkin_from_rogapp` - チェックイン削除
+   - `get_waypoint_datas_from_rogapp` - ウェイポイントデータ収集
+   - `getCheckinList` - チェックイン履歴取得
+
+#### 注意事項の追加
+- URL構成についての説明を追加
+- 未実装APIの明記
+- 一時的に無効化されているAPIの説明
+
+---
+
 ## 自動証明書生成について

 ゴール処理（`goal_from_rogapp`）が完了すると、システムは自動的に以下を実行します：