121 lines
6.4 KiB
Markdown
121 lines
6.4 KiB
Markdown
# Data Model: Fitbit-Garmin Local Sync
|
|
|
|
## Overview
|
|
This document defines the data models for the Fitbit-Garmin Local Sync application based on the key entities identified in the feature specification.
|
|
|
|
## Entity: Configuration
|
|
**Description**: Application settings including API credentials, sync settings, and database connection parameters
|
|
**Fields**:
|
|
- `id` (Integer): Unique identifier for the configuration record
|
|
- `fitbit_client_id` (String): Fitbit API client ID
|
|
- `fitbit_client_secret` (String): Fitbit API client secret (encrypted)
|
|
- `garmin_username` (String): Garmin Connect username
|
|
- `garmin_password` (String): Garmin Connect password (encrypted)
|
|
- `sync_settings` (JSON): Sync preferences and settings
|
|
- `created_at` (DateTime): Timestamp of creation
|
|
- `updated_at` (DateTime): Timestamp of last update
|
|
|
|
## Entity: Weight Record
|
|
**Description**: Individual weight entries with timestamps, values, and sync status with unique identifiers to prevent duplicate processing
|
|
**Fields**:
|
|
- `id` (Integer): Unique identifier for the weight record
|
|
- `fitbit_id` (String): Original Fitbit ID for the weight entry
|
|
- `weight` (Float): Weight value in user's preferred units
|
|
- `unit` (String): Weight unit (e.g., 'kg', 'lbs')
|
|
- `date` (Date): Date of the weight measurement
|
|
- `timestamp` (DateTime): Exact timestamp of the measurement
|
|
- `sync_status` (String): Sync status ('unsynced', 'synced', 'failed')
|
|
- `garmin_id` (String, nullable): ID of the record if synced to Garmin
|
|
- `created_at` (DateTime): Timestamp of record creation
|
|
- `updated_at` (DateTime): Timestamp of last update
|
|
|
|
## Entity: Activity Metadata
|
|
**Description**: Information about Garmin activities including download status, file content stored in database, and activity details
|
|
**Fields**:
|
|
- `id` (Integer): Unique identifier for the activity record
|
|
- `garmin_activity_id` (String): Original Garmin ID for the activity
|
|
- `activity_name` (String): Name of the activity
|
|
- `activity_type` (String): Type of activity (e.g., 'running', 'cycling')
|
|
- `start_time` (DateTime): Start time of the activity
|
|
- `duration` (Integer): Duration in seconds
|
|
- `file_content` (LargeBinary, nullable): Activity file content stored in database (base64 encoded)
|
|
- `file_type` (String): File type (.fit, .gpx, .tcx, etc.)
|
|
- `download_status` (String): Download status ('pending', 'downloaded', 'failed')
|
|
- `downloaded_at` (DateTime, nullable): Timestamp when downloaded
|
|
- `created_at` (DateTime): Timestamp of record creation
|
|
- `updated_at` (DateTime): Timestamp of last update
|
|
|
|
## Entity: Health Metric
|
|
**Description**: Comprehensive health data including type, timestamp, values across categories (steps, calories, heart rate, sleep, etc.)
|
|
**Fields**:
|
|
- `id` (Integer): Unique identifier for the health metric record
|
|
- `metric_type` (String): Type of metric (e.g., 'steps', 'heart_rate', 'sleep', 'calories')
|
|
- `metric_value` (Float): Value of the metric
|
|
- `unit` (String): Unit of measurement
|
|
- `timestamp` (DateTime): When the metric was recorded
|
|
- `date` (Date): Date of the metric
|
|
- `source` (String): Source of the metric ('garmin')
|
|
- `detailed_data` (JSON, nullable): Additional details specific to the metric type
|
|
- `created_at` (DateTime): Timestamp of record creation
|
|
- `updated_at` (DateTime): Timestamp of last update
|
|
|
|
## Entity: Sync Log
|
|
**Description**: Operation logs with timestamps, status, and results for monitoring and troubleshooting
|
|
**Fields**:
|
|
- `id` (Integer): Unique identifier for the sync log entry
|
|
- `operation` (String): Type of sync operation ('weight_sync', 'activity_archive', 'metrics_download')
|
|
- `status` (String): Status of the operation ('started', 'in_progress', 'completed', 'failed')
|
|
- `message` (String): Status message or error details
|
|
- `start_time` (DateTime): When the operation started
|
|
- `end_time` (DateTime, nullable): When the operation completed
|
|
- `records_processed` (Integer): Number of records processed
|
|
- `records_failed` (Integer): Number of records that failed
|
|
- `user_id` (Integer, nullable): Reference to user (if applicable)
|
|
|
|
## Entity: API Token
|
|
**Description**: OAuth tokens for Fitbit and Garmin with expiration tracking and refresh mechanisms
|
|
**Fields**:
|
|
- `id` (Integer): Unique identifier for the token record
|
|
- `token_type` (String): Type of token ('fitbit', 'garmin')
|
|
- `access_token` (String): Access token (encrypted)
|
|
- `refresh_token` (String): Refresh token (encrypted)
|
|
- `expires_at` (DateTime): When the token expires
|
|
- `scopes` (String): OAuth scopes granted
|
|
- `last_used` (DateTime): When the token was last used
|
|
- `created_at` (DateTime): Timestamp of record creation
|
|
- `updated_at` (DateTime): Timestamp of last update
|
|
- `garth_oauth1_token` (String, nullable): Garmin OAuth1 token (encrypted)
|
|
- `garth_oauth2_token` (String, nullable): Garmin OAuth2 token (encrypted)
|
|
- `mfa_state` (String, nullable): MFA state information for Garmin authentication
|
|
- `mfa_expires_at` (DateTime, nullable): When MFA state expires
|
|
|
|
## Entity: Auth Status
|
|
**Description**: Current authentication state for both Fitbit and Garmin, including token expiration times and last login information
|
|
**Fields**:
|
|
- `id` (Integer): Unique identifier for the auth status record
|
|
- `service_type` (String): Type of service ('fitbit', 'garmin')
|
|
- `username` (String): Username for the service (masked for security display)
|
|
- `authenticated` (Boolean): Whether currently authenticated
|
|
- `token_expires_at` (DateTime): When the current token expires
|
|
- `last_login` (DateTime): When the last successful login occurred
|
|
- `is_china` (Boolean): Whether using garmin.cn domain (Garmin only)
|
|
- `last_check` (DateTime): When status was last checked
|
|
- `created_at` (DateTime): Timestamp of record creation
|
|
- `updated_at` (DateTime): Timestamp of last update
|
|
|
|
## Relationships
|
|
- Configuration has many API Tokens
|
|
- Authentication Status references API Tokens
|
|
- Sync Logs reference Configuration
|
|
- Weight Records may reference API Tokens for sync operations
|
|
- Activity Metadata may reference API Tokens for download operations
|
|
- Health Metrics may reference API Tokens for retrieval operations
|
|
|
|
## Validation Rules
|
|
- Configuration records must have valid API credentials before sync operations
|
|
- Weight Records must have unique fitbit_id to prevent duplicates
|
|
- Activity Metadata records must have unique garmin_activity_id
|
|
- Health Metric records must have valid metric_type from allowed list
|
|
- Sync Log records must have valid operation and status values
|
|
- API Token records must be refreshed before expiration
|
|
- Authentication status must be updated when tokens are refreshed |