mirror of
https://github.com/sstent/FitTrack_ReportGenerator.git
synced 2026-02-01 03:52:00 +00:00
feat: Initial implementation of FitTrack Report Generator
This commit introduces the initial version of the FitTrack Report Generator, a FastAPI application for analyzing workout files. Key features include: - Parsing of FIT, TCX, and GPX workout files. - Analysis of power, heart rate, speed, and elevation data. - Generation of summary reports and charts. - REST API for single and batch workout analysis. The project structure has been set up with a `src` directory for core logic, an `api` directory for the FastAPI application, and a `tests` directory for unit, integration, and contract tests. The development workflow is configured to use Docker and modern Python tooling.
This commit is contained in:
238
specs/001-create-a-new/contracts/openapi.yaml
Normal file
238
specs/001-create-a-new/contracts/openapi.yaml
Normal file
@@ -0,0 +1,238 @@
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: FitTrack Report Generator API
|
||||
version: 1.0.0
|
||||
description: API for analyzing workout files and generating reports.
|
||||
|
||||
servers:
|
||||
- url: /api
|
||||
description: Base API path
|
||||
|
||||
paths:
|
||||
/analyze/workout:
|
||||
post:
|
||||
summary: Analyze a single workout file
|
||||
description: Uploads a single workout file (FIT, TCX, or GPX) for comprehensive analysis.
|
||||
operationId: analyzeSingleWorkout
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
file:
|
||||
type: string
|
||||
format: binary
|
||||
description: The workout file (FIT, TCX, or GPX) to analyze.
|
||||
user_id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Optional user ID to associate the analysis with.
|
||||
ftp_value:
|
||||
type: number
|
||||
format: float
|
||||
description: Optional Functional Threshold Power (FTP) value for calculations. Overrides user's default if provided.
|
||||
required:
|
||||
- file
|
||||
responses:
|
||||
'200':
|
||||
description: Analysis successful. Returns a summary of the analysis.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/WorkoutAnalysisSummary'
|
||||
'400':
|
||||
description: Invalid input or file format.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'500':
|
||||
description: Internal server error.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/analyze/batch:
|
||||
post:
|
||||
summary: Analyze multiple workout files in a batch
|
||||
description: Uploads a directory (as a zip file) of workout files for batch analysis and generates a summary report.
|
||||
operationId: analyzeBatchWorkouts
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
zip_file:
|
||||
type: string
|
||||
format: binary
|
||||
description: A zip file containing multiple workout files (FIT, TCX, or GPX).
|
||||
user_id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Optional user ID to associate the analysis with.
|
||||
ftp_value:
|
||||
type: number
|
||||
format: float
|
||||
description: Optional Functional Threshold Power (FTP) value for calculations. Overrides user's default if provided.
|
||||
required:
|
||||
- zip_file
|
||||
responses:
|
||||
'200':
|
||||
description: Batch analysis initiated. Returns a summary of the batch process.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
batch_id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Unique ID for the batch analysis.
|
||||
status:
|
||||
type: string
|
||||
description: Status of the batch analysis (e.g., 'processing', 'completed').
|
||||
total_files:
|
||||
type: integer
|
||||
description: Total number of files submitted in the batch.
|
||||
'400':
|
||||
description: Invalid input or file format.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'500':
|
||||
description: Internal server error.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/analysis/{analysis_id}/charts:
|
||||
get:
|
||||
summary: Retrieve generated charts for a specific analysis
|
||||
description: Returns a PNG image of the requested chart for a previously analyzed workout.
|
||||
operationId: getAnalysisCharts
|
||||
parameters:
|
||||
- name: analysis_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
description: The ID of the workout analysis.
|
||||
- name: chart_type
|
||||
in: query
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
enum: [power_curve, elevation_profile, zone_distribution_power, zone_distribution_hr, zone_distribution_speed]
|
||||
description: The type of chart to retrieve.
|
||||
responses:
|
||||
'200':
|
||||
description: Chart image successfully retrieved.
|
||||
content:
|
||||
image/png:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
'404':
|
||||
description: Analysis or chart not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'500':
|
||||
description: Internal server error.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
/analysis/{analysis_id}/summary:
|
||||
get:
|
||||
summary: Retrieve a summary of a specific analysis
|
||||
description: Returns a detailed summary of a previously analyzed workout.
|
||||
operationId: getAnalysisSummary
|
||||
parameters:
|
||||
- name: analysis_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
description: The ID of the workout analysis.
|
||||
responses:
|
||||
'200':
|
||||
description: Analysis summary successfully retrieved.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/WorkoutAnalysisSummary'
|
||||
'404':
|
||||
description: Analysis not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
'500':
|
||||
description: Internal server error.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
|
||||
components:
|
||||
schemas:
|
||||
WorkoutAnalysisSummary:
|
||||
type: object
|
||||
properties:
|
||||
analysis_id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Unique ID of the analysis.
|
||||
user_id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: User ID associated with the analysis.
|
||||
file_name:
|
||||
type: string
|
||||
description: Original name of the analyzed file.
|
||||
analysis_date:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Timestamp of the analysis.
|
||||
status:
|
||||
type: string
|
||||
description: Status of the analysis (e.g., 'completed', 'failed').
|
||||
metrics:
|
||||
type: object
|
||||
description: Key metrics from the workout analysis (e.g., duration, distance, NP, IF, TSS).
|
||||
additionalProperties: true
|
||||
report_url:
|
||||
type: string
|
||||
format: url
|
||||
description: URL to the generated report.
|
||||
chart_urls:
|
||||
type: object
|
||||
description: URLs to generated charts.
|
||||
additionalProperties:
|
||||
type: string
|
||||
format: url
|
||||
ErrorResponse:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
description: A unique error code.
|
||||
message:
|
||||
type: string
|
||||
description: A human-readable error message.
|
||||
details:
|
||||
type: object
|
||||
description: Optional additional error details.
|
||||
additionalProperties: true
|
||||
Reference in New Issue
Block a user