◀ Previous: Data Flow & Sync | 返回目錄

This chapter documents the API contract between the Fugu-developed mobile app and the SolidFocus backend, based on the client's backend specification v3.0.

⚠️ IMPORTANT CLARIFICATION (Updated 2025-12-24):

What the Client (SolidFocus) Provided:

• ✅ Endpoint paths and HTTP methods
• ✅ High-level descriptions (in Chinese)
• ✅ Database schema (SQLModel classes)
• ✅ Architecture concepts (Offline-First, JSONB usage)
• ✅ Sequence diagrams showing sync flows

What the Client Did NOT Provide:

• ❌ Request/response body structures
• ❌ HTTP status codes and error responses
• ❌ Authentication details (JWT format, token expiration)
• ❌ Field-level validation rules
• ❌ Pagination formats

Current Status: This document has been cleaned up to clearly separate:

1. Client-defined requirements (from their Notion spec)
2. Fugu's design proposals (marked clearly, needs client approval)

Key Architecture Principles (from client spec):

• Offline-First (離線優先): APP is source of truth for workout data
• Store-and-Forward (儲存後轉發): Local storage first, sync when online
• Device-Agnostic (異質數據標準化): JSONB for heterogeneous device data (bike, rower, treadmill)
• Batch Upload: Efficient session synchronization
• APP Wins: Force-sync pattern for UserStats conflict resolution

📚 本章節文件結構¶

04.1 API Specification ⭐¶

• ✅ Client-defined endpoints: Paths and descriptions from SolidFocus spec
• ⚠️ Request/Response formats: NOT defined by client - needs discussion
• ⚠️ Error handling: NOT defined by client - needs discussion
• From client spec: Batch upload concept, offline-first architecture
• Status: Cleaned up to show only client-provided info vs Fugu's proposals

04.2 Data Models¶

• Database Schema (v3.0)
• Entity Relationship Diagrams (ERD)
• Field descriptions and constraints
• UPDATED: Aligned with client's SQLModel specification
• BREAKING: Field renames (e.g., workout_total_duration → total_duration_seconds)

🔄 v3.0 Major Changes Summary¶

1. Offline-First Architecture: APP-centric design
2. Batch Upload: New POST /sessions/batch_upload endpoint
3. No Device Binding: Removed User.bound_device_id
4. Force-Sync Stats: PATCH /users/me/stats for APP to override
5. Unified SSO: Single POST /auth/sso/{provider} endpoint
6. Meta APIs: Schema discovery and app version checks
7. Field Renames: Aligned with client specification

📖 Reference Materials¶

• API Design Best Practices
• RESTful API Design Guidelines
• JWT Authentication Best Practices

Next: See 04.1 API Specification for detailed API definitions.

◀ 返回目錄