ag/gymflow
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases 1 Wiki Activity

e2e tests added. Core & Authentication

Browse Source
This commit is contained in:
AG
2025-12-08 10:18:42 +02:00
parent d284563301
commit 615c3a0cb7
16 changed files with 740 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
specs/gymflow-test-plan.md
View File

@@ -302,6 +302,37 @@ Comprehensive test plan for the GymFlow web application, covering authentication
**Expected Results:**
- The 'Name' input field for new exercises correctly prompts for capitalization on mobile keyboards, enhancing user experience.
#### 2.12. B. Exercise Library - Create Unilateral Exercise
**File:** `tests/workout-management.spec.ts`
**Steps:**
1. Log in as a regular user.
2. Navigate to the 'Profile' section -> 'Exercise Manager'.
3. Click 'Create Exercise'.
4. Enter name 'One Arm Row'.
5. Select 'Strength' type.
6. Toggle the 'Unilateral' switch to ON.
7. Click 'Create'.
**Expected Results:**
- The new exercise is created.
- It is marked as unilateral in the database/UI logic (though visual indicator might differ).
#### 2.13. B. Exercise Library - Create Special Type Exercises
**File:** `tests/workout-management.spec.ts`
**Steps:**
1. Log in as a regular user.
2. Create a 'Static' exercise (e.g., 'Plank').
3. Create a 'High Jump' exercise (e.g., 'Box Jump').
4. Create a 'Long Jump' exercise (e.g., 'Broad Jump').
5. Create a 'Plyometric' exercise (e.g., 'Burpees').
**Expected Results:**
- All exercises are created successfully with their respective types.
### 3. III. Workout Tracking
**Seed:** `tests/workout-tracking.spec.ts`
@@ -497,6 +528,52 @@ Comprehensive test plan for the GymFlow web application, covering authentication
- The exercise list filters dynamically as the user types.
- The search field content is cleared on focus.
#### 3.14. C. Active Session - Log Unilateral Set
**File:** `tests/workout-tracking.spec.ts`
**Steps:**
1. Start a Free Workout (or Plan with unilateral exercise).
2. Select a Unilateral exercise (created in 2.12).
3. Enter Weight/Reps.
4. Select 'Left' from the Side selector.
5. Click 'Log Set'.
6. Repeat for 'Right' side.
**Expected Results:**
- Sets are logged with the correct 'Left'/'Right' indicators visible in the history.
#### 3.15. C. Active Session - Log Special Type Set
**File:** `tests/workout-tracking.spec.ts`
**Steps:**
1. Start a Free Workout.
2. Select a Static exercise -> Enter Duration.
3. Select a High Jump exercise -> Enter Height.
4. Select a Long Jump exercise -> Enter Distance.
5. Select a Plyometric exercise -> Enter Reps.
6. Log a set for each.
**Expected Results:**
- Each set is logged with the correct specific metric (Height, Distance, Duration, etc.).
#### 3.16. C. Active Session - Smart Plan Matching
**File:** `tests/workout-tracking.spec.ts`
**Steps:**
1. Start a Plan with 2 exercises (Ex A, Ex B).
2. Log a set for Ex A (matching plan). Verify it counts towards plan progress.
3. Manually search and select Ex B (skipping Ex A).
4. Log a set for Ex B.
**Expected Results:**
- The system detects the mismatch or allows it.
- If "Smart Matching" is strict, it might warn or just log it as an extra set.
- If "Smart Matching" is flexible, it might advance progress for Ex B (depending on spec).
- *Assumption based on Requirements*: "System attempts to match... activeExerciseId returned". Verify the UI updates focus to the relevant step if matched.
### 4. IV. Data & Progress
**Seed:** `tests/data-progress.spec.ts`

244
specs/requirements.md
View File

@@ -1,143 +1,133 @@
# Application Requirements
# GymFlow Application Requirements Specification
This document outlines the functional requirements of the GymFlow application, derived from an analysis of its React components and backend services.
## 1. Introduction
This document serves as the authoritative source of truth for the GymFlow application functionality. It is derived from a deep analysis of the production codebase (React frontend + Node.js/Prisma backend). These requirements are intended to guide future development and serve as the basis for automated test generation (Playwright).
## I. Core & Authentication
## 2. System Actors
* **Guest**: An unauthenticated user (restricted to Login/Register).
* **User**: A standard authenticated user with access to tracking, plans, and capabilities.
* **Admin**: A super-user with additional privileges to manage other users (block, delete, reset passwords).
### A. Login (`Login.tsx`)
- **User Authentication:** Users must be able to log in using their email and password.
- **First-Time Password Change:** On their initial login, users are required to change their temporary password.
- **Language Selection:** The interface language can be toggled between English and Russian directly on the login screen.
---
### B. Navigation (`Navbar.tsx`)
- **Primary Navigation:** A persistent navigation bar (bottom on mobile, side rail on desktop) allows access to the main sections of the application:
- Tracker
- Plans
- History
- Stats
- AI Coach
- Profile
## 3. Functional Requirements
## II. Workout Management
### 3.1. Authentication & Integrity
The system relies on JWT-based authentication.
### A. Workout Plans (`Plans.tsx`)
- **CRUD Operations:** Users can create, view, update, and delete their workout plans.
- **Plan Composition:** A plan consists of a name, a descriptive text (for preparation/instructions), and an ordered list of exercises.
- **Exercises List Reordering:** Exercises within a plan can be reordered via a drag-and-drop interface.
- **Starting a Session:** Users can initiate a workout session from a selected plan in the list.
* **3.1.1 Login**
* **Input**: Email, Password.
* **Logic**:
* Must validate email existence.
* Must validate password matches hash.
* **Block Check**: Must prevent login if `User.isBlocked` is true, returning a 403 error.
* **UI**:
* Show "Invalid credentials" on failure.
* Redirect to Tracker upon success.
* **Language Toggle**: User must be able to switch between English (EN) and Russian (RU) before logging in.
* **3.1.2 Registration**
* **Input**: Email, Password.
* **Logic**:
* Email must be unique.
* Creates a `UserProfile` with default values (e.g., default weight 70kg) upon account creation.
* Sets `isFirstLogin` to true.
* **3.1.3 First-Time Setup (Password Change)**
* **Trigger**: If `User.isFirstLogin` is true.
* **Requirement**: User must be forced to change password immediately after initial login.
* **Effect**: Updates `User.password` and sets `isFirstLogin` to false.
* **3.1.4 Profile Management**
* **Fields**: Weight, Height, Gender, Birth Date.
* **Logic**:
* Updates to `UserProfile` table.
* Dates are handled as ISO strings or timestamps.
### B. Exercise Library (`Plans.tsx`, `Profile.tsx`)
- **Custom Exercise Creation:** Users can define new exercises, specifying:
- Name: The input field should suggest capitalizing each word for mobile users.
- Type (e.g., Strength, Bodyweight, Cardio)
- For bodyweight exercises, a percentage of body weight to be used in calculations.
- **Exercise Management:** From the profile section, users can view all their created exercises, edit their names, and archive or unarchive them.
### 3.2. Workout Management (Plans)
Users can structure their training via Plans.
## III. Workout Tracking
* **3.2.1 Plan Creation/Editing**
* **Data**: Name (required), Description (optional).
* **Exercises**:
* User selects exercises from the global/personal library.
* **Ordering**: Exercises must be ordered (0-indexed).
* **Weighted Flag**: specific exercises in a plan can be marked as `isWeighted` (visual indicator).
* **Logic**: Supports reordering capabilities via drag-and-drop in UI.
* **3.2.2 Plan Deletion**
* Standard soft or hard delete (Cascades to PlanExercises).
### A. Tracker Hub (`Tracker/index.tsx`)
- **Central Control:** This component orchestrates the tracking experience, displaying the appropriate view based on the current state (idle, in-session, or sporadic logging).
### 3.3. Exercise Library
* **3.3.1 Exercise Types**
The system supports distinct exercise types which dictate valid data entry fields:
* `STRENGTH`: Requires **Weight (kg)** and **Reps**.
* `BODYWEIGHT`: Requires **Reps** (and optional added Weight).
* `CARDIO`: Requires **Duration (s)** and **Distance (m)**.
* `STATIC`: Requires **Duration (s)**.
* `HIGH_JUMP`: Requires **Height (cm)**.
* `LONG_JUMP`: Requires **Distance (m)**.
* `PLYOMETRIC`: Requires **Reps**.
* **3.3.2 Custom Exercises**
* User can create new exercises.
* **Unilateral Flag**: Boolean flag `isUnilateral`. If true, sets recorded for this exercise can specify a `side` (LEFT/RIGHT).
* **Bodyweight %**: For bodyweight-based calculations.
### B. Idle State (`Tracker/IdleView.tsx`)
- **Session Initiation:** From the idle screen, users can:
- Start a "Free Workout" without a predefined plan.
- Begin a "Quick Log" session for sporadic, one-off sets.
- Select and start a workout from their list of saved plans.
- **Session Body Weight Entry:** Users can input their current body weight before starting a session; the default value comes from user profile; this weight is associated with the active session for accurate calculations.
- **Plan Preview:** If a plan includes a description, it is displayed to the user for review before the session begins.
### 3.4. Workout Tracking (The "Tracker")
The core feature. States: **Idle**, **Active Session**, **Sporadic Mode**.
### C. Active Session (`Tracker/ActiveSessionView.tsx`)
- **Real-Time Timer:** A running timer displays the elapsed time for the current workout.
- **Exercise Selection:** Users can search for and select the exercise they are performing. The search field filters available exercises as the user types and clears its content automatically when focused. New exercises can be created on-the-fly.
- **Set Logging:** Users can log completed sets, with input fields dynamically adjusting based on the selected exercise's type (e.g., weight/reps for strength, duration/distance for cardio).
- **Session Body Weight:** The body weight entered before the session is displayed and used for calculations within the active session.
- **Session History:** A chronological list of sets logged during the current session is displayed.
- **Set Management:** Logged sets can be edited to correct data or deleted entirely.
- **Plan Progression:** When following a plan, the interface highlights the current exercise. Users can view the full plan and jump to different steps if needed.
- **Session Control:** Users can finish the session (saving the data) or quit without saving.
* **3.4.1 Active Session (Standard)**
* **Initiation**:
* Can start "Free Workout" (no plan).
* Can start from a "Plan".
* **Input**: User confirms current Body Weight before starting.
* **Constraint**: User cannot have more than one active standard session (where `endTime` is null). API returns 400 if one exists.
* **The "Active" State**:
* **Persistence**: Session remains active in DB if browser is closed. `GET /sessions/active` restores state.
* **Timer**: Client-side logic calculates `now - startTime`.
* **Logging Sets**:
* **Input**: Exercise, Metrics (Weight/Reps/etc. based on Type), Side (if unilateral).
* **Smart Matching**: If a Plan is active, the system attempts to match the logged set to the current step in the plan based on the exercise ID and the number of sets already performed vs. planned.
* **Response**: Returns the created set and the `activeExerciseId` (for UI to auto-advance focus in plan).
* **Session Termination**:
* **Finish**: Updates `endTime` to now.
* **Profile Sync**: If the session had a `userBodyWeight` set, it updates the `UserProfile.weight`.
* **Quit (No Save)**:
* **Destructive Action**: Hard deletes the `WorkoutSession` and all associated `WorkoutSets` from the DB.
* **3.4.2 Active Session (Quick Log)**
* **Concept**: A special session type (`QUICK_LOG`) that aggregates all sporadic sets for a single day.
* **Logic**:
* `GET /sessions/quick-log`: Finds strictly one session for the current calendar day (00:00-23:59 local server time) of type `QUICK_LOG`.
* `POST /sessions/quick-log/set`:
* Finds OR Creates the daily Quick Log session.
* Appends the set.
* **UI**: Separate "Sporadic Mode" view specialized for fast, one-off entries without a timer or plan context.
### D. Sporadic Logging (`Tracker/SporadicView.tsx`)
- **Ad-Hoc Tracking:** Enables logging of individual sets outside of a structured workout session.
- **Quick Access:** Optimized for quickly selecting an exercise, entering metrics, and logging the set. The exercise selection field filters available exercises as the user types and clears its content automatically when focused.
- **Daily History:** Displays a list of all sporadic sets logged on the current day.
### 3.5. History & Analysis
* **3.5.1 Session History**
* Displays all finished sessions.
* Groups by Date.
* **Quick Logs**: Displayed alongside standard workouts, identifiable by type.
* **3.5.2 Statistics**
* Visualizes progress over time.
* **Key Metrics**: Volume (Weight * Reps), Frequency, Body Weight trends.
## IV. Data & Progress
### 3.6. User Interface Logic
* **3.6.1 Navigation**
* **Mobile**: Bottom navigation bar.
* **Desktop**: Side rail navigation.
* **Responsiveness**: Main layout container adapts padding/margins based on viewport breakpoint.
* **3.6.2 Input Behavior**
* **Search**: Exercise selectors must support text search filtering.
* **Auto-Clear**: Search inputs should clear/select text on focus for rapid entry.
### A. Session History (`History.tsx`)
- **Workout Review:** Provides a comprehensive list of all past workout sessions and sporadic sets, grouped by day.
- **Detailed View:** Users can inspect the details of each session, including all sets performed.
- **Data Correction:** Past sessions and their individual sets can be edited or deleted.
### 3.7. Admin Capabilities
Accessible only if `User.role === 'ADMIN'`.
### B. Performance Statistics (`Stats.tsx`)
- **Visualizations:** The application generates and displays charts to track progress over time, including:
- **Total Volume:** The total weight lifted in each session.
- **Set Count:** The number of sets performed per session.
- **Body Weight:** A line graph of the user's body weight over time.
* **User List**: View all registered users (showing Block status, First Login status).
* **Actions**:
* **Toggle Block**: Ban/Unban access.
* **Delete User**: Permanent removal.
* **Reset Password**: Admin can manually trigger password reset flows.
## V. User & System Management
### A. User Profile (`Profile.tsx`)
- **Personal Information:** Users can view and update their personal data, including weight, height, birth date, and gender.
- **Dedicated Daily Weight Logging:** Users can log their body weight daily, and view a history of these records.
- **Account Management:** Users can change their password and (if not an admin) delete their own account.
- **Language Preference:** The application language can be changed.
### B. AI Coach (`AICoach.tsx`)
- **Conversational AI:** Provides an interactive chat interface with an AI fitness expert.
- **Contextual Awareness:** The AI is primed with the user's workout history, plans, and profile data to provide personalized advice and analysis.
### C. Admin Panel (within `Profile.tsx`)
- **User Administration:** Admin-level users have access to a special panel to manage the user base.
- **User CRUD:** Admins can create new users, view a list of all users, block/unblock, and delete users.
- **Password Resets:** Admins can reset the passwords for non-admin users.
## VI. User Interface & Experience
### A. Adaptive GUI
- **Responsive Navigation:**
- On mobile devices, the application displays a bottom navigation bar.
- On desktop devices, a vertical navigation rail is displayed on the left side.
- **Fluid Layout:** The application's content layout adapts to different screen sizes, ensuring usability across a wide range of devices.
- **Responsive Charts:** Data visualizations in the statistics section are responsive and scale to fit the available screen space.
## VII. Backend API Endpoints
The frontend components interact with a backend service through the following conceptual endpoints:
- **Authentication:**
- `POST /auth/login`
- `POST /auth/change-password`
- `GET /auth/me`
- **Users (Admin):**
- `GET /users`
- `POST /users/create`
- `DELETE /users/:id`
- `PUT /users/toggle-block/:id`
- `POST /users/admin-reset-password`
- **User Profile:**
- `PUT /users/profile/:id`
- **Workout Plans:**
- `GET /plans`
- `POST /plans`
- `DELETE /plans/:id`
- **Exercises:**
- `GET /exercises`
- `POST /exercises`
- **Workout Sessions:**
- `GET /sessions`
- `POST /sessions/start`
- `POST /sessions/end`
- `POST /sessions/quit`
- `POST /sessions/active/log-set`
- `PUT /sessions/:id`
- `DELETE /sessions/:id`
- **Sporadic Sets:**
- `GET /sporadic-sets`
- `POST /sporadic-sets`
- `PUT /sporadic-sets/:id`
- `DELETE /sporadic-sets/:id`
- **Weight Logging:**
- `GET /weight`
- `POST /weight`
- **AI Service:**
- `POST /ai/chat`
## 4. Technical Constants & Constraints
* **Database**: SQLite (via Prisma).
* **API Schema**: REST-like (JSON).
* **Timezones**: Dates stored as UTC in DB, displayed in Local Time on client.
* **Offline Mode**: Currently NOT supported (requires active connection for mutations).