chore: organize documentation files into docs directory

2025-12-05 11:49:46 +02:00
parent 60e1716730
commit 54bd98c5de
2 changed files with 297 additions and 0 deletions
--- a/docs/TEST_MEMBERSHIP_LINKING.md
+++ b/docs/TEST_MEMBERSHIP_LINKING.md
@@ -0,0 +1,249 @@
+# Membership Linking Feature - Test & Verification Checklist
+
+## Feature Overview
+This document outlines the membership linking feature that allows multiple users (e.g., married couples, family members) to share a single membership account.
+
+## Database Schema
+
+### Tables Created
+1. **membership_links** - Tracks relationships between primary and secondary users
+   - link_id (auto-increment)
+   - primary_user_id - User who owns/manages the membership
+   - secondary_user_id - User gaining access to membership
+   - status (ACTIVE/INACTIVE)
+   - created_date
+   - expires_date (optional)
+
+2. **membership_permissions** - Granular permission control
+   - permission_id (auto-increment)
+   - link_id - Foreign key to membership_links
+   - permission_name (e.g., access_member_areas, member_pricing, etc.)
+   - granted_date
+
+## Core Functions (in src/config/functions.php)
+
+### New Functions Added
+1. **linkSecondaryUserToMembership($primary_user_id, $secondary_user_id, $permissions = [])**
+   - Creates link and assigns default permissions
+   - Validates primary user has active membership
+   - Validates secondary user exists and doesn't already link
+   - Returns success/error response
+
+2. **getUserMembershipLink($user_id)**
+   - Checks if user is linked as secondary to another membership
+   - Returns link details if active
+   - Returns false if no active link
+
+3. **getLinkedSecondaryUsers($primary_user_id)**
+   - Returns array of all secondary users linked to primary
+   - Includes link creation date and status
+   - Used for UI display on membership_details page
+
+4. **unlinkSecondaryUser($primary_user_id, $secondary_user_id)**
+   - Removes link and associated permissions
+   - Returns success/error response
+
+### Modified Functions
+1. **getUserMemberStatus($user_id)**
+   - NOW checks linked memberships at ALL failure points:
+     * If user has no application → check if linked to active membership
+     * If user hasn't accepted indemnity → check if linked
+     * If user has no payment record → check if linked
+     * If user's direct membership expired → check if linked
+   - Returns true for linked members even if direct membership check fails
+
+## API Endpoints
+
+### POST /src/processors/link_membership_user.php
+- **Purpose**: AJAX endpoint for creating membership links
+- **Parameters**:
+  - csrf_token (validated)
+  - secondary_user_email (validated)
+- **Returns**: JSON response with success/error
+- **Security**: CSRF token validation, database injection prevention
+
+### POST /src/processors/unlink_membership_user.php
+- **Purpose**: AJAX endpoint for removing membership links
+- **Parameters**:
+  - csrf_token (validated)
+  - secondary_user_id (validated)
+- **Returns**: JSON response with success/error
+- **Security**: CSRF token validation, only primary user can unlink
+
+## UI Implementation
+
+### Membership Details Page (src/pages/membership_details.php)
+- Added "Linked Accounts" section OUTSIDE main info form
+- Displays list of currently linked secondary users
+- Form to add new linked user by email
+- Unlink buttons for each linked user
+- IMPORTANT FIX: Form moved outside infoForm to prevent form submission conflicts
+
+### Header Navigation (src/pages/header.php)
+- "Members Area" dropdown shown for users with direct OR linked membership
+- Uses getUserMemberStatus() to determine visibility
+- Shows: Campsites & Gallery links
+
+## Booking Pages & Pricing
+
+### Protected Member Pages
+- `src/pages/bookings/campsites.php` - Redirects non-members
+- `src/pages/gallery/gallery.php` - Redirects non-members  
+- `src/pages/gallery/view_album.php` - Redirects non-members
+- `src/pages/gallery/create_album.php` - Redirects non-members
+
+### Open Booking Pages (All Users Welcome)
+1. **Trip Details** (`src/pages/bookings/trip-details.php`)
+   - Shows member & non-member rates
+   - Linked members get member pricing
+   - Correct calculateTotal() logic with adults/children/pensioners
+
+2. **Driver Training** (`src/pages/bookings/driver_training.php`)
+   - Pricing: Members vs Non-members
+   - Form fields adjusted for non-members
+   - FIXED: calculateTotal() now correctly:
+     * Members: (self + additional_members at member rate) + additional_nonmembers
+     * Non-members: (self + additional participants at non-member rate)
+
+3. **Bush Mechanics** (`src/pages/other/bush_mechanics.php`)
+   - FIXED: calculateTotal() pricing logic corrected
+   - Members: (self at member rate) + additional members + additional non-members
+   - Non-members: (self + additional participants at non-member rate)
+
+4. **Rescue & Recovery** (`src/pages/other/rescue_recovery.php`)
+   - FIXED: calculateTotal() pricing logic corrected
+   - Members: (self at member rate) + additional members + additional non-members
+   - Non-members: (self + additional participants at non-member rate)
+
+5. **Course Details** (`src/pages/bookings/course_details.php`)
+   - Shows member & non-member rates
+   - Open to all users (members and non-members)
+
+6. **Campsite Booking** (`src/pages/bookings/campsite_booking.php`)
+   - Pricing: Members stay FREE, Non-members R200/night
+   - Calculates based on getUserMemberStatus()
+
+### Booking Processors
+1. **process_trip_booking.php** - ✅ Allows non-members, applies pricing correctly
+2. **process_course_booking.php** - ✅ Allows non-members, applies pricing correctly  
+3. **process_camp_booking.php** - ✅ Allows non-members, applies pricing correctly
+
+## Testing Checklist
+
+### Unit Tests
+- [ ] Link secondary user to primary user membership
+- [ ] Verify linked user appears in getLinkedSecondaryUsers()
+- [ ] Verify linked user gets member pricing on bookings
+- [ ] Verify linked user can access member-only areas
+- [ ] Unlink secondary user from primary membership
+- [ ] Verify unlinked user loses member benefits
+- [ ] Test with invalid secondary user email
+- [ ] Test with secondary user who already has direct membership
+
+### Integration Tests
+- [ ] Member books trip - should use member pricing
+- [ ] Member books course - should use member pricing
+- [ ] Member books campsite - should stay FREE
+- [ ] Linked member books trip - should use member pricing
+- [ ] Linked member books course - should use member pricing
+- [ ] Linked member books campsite - should stay FREE
+- [ ] Non-member books trip - should use non-member pricing
+- [ ] Non-member books course - should use non-member pricing
+- [ ] Non-member books campsite - should pay R200/night
+- [ ] Linked member can view members gallery
+- [ ] Non-member cannot access members gallery
+- [ ] Linked member dropdown link shows in header
+- [ ] Payment processing for non-member bookings
+
+### UI/UX Tests
+- [ ] Linking form displays properly on membership details
+- [ ] Unlink buttons work correctly
+- [ ] "You will be added at non-member rate" message shows for non-members
+- [ ] Pricing calculations update correctly as form fields change
+- [ ] Member/Non-member rate display is clear
+
+## Known Issues & Fixes Applied
+
+### Issue 1: Form Submission Conflicts
+- **Problem**: linkUserForm nested inside infoForm - submit triggered parent
+- **Fix**: Moved linkUserForm outside infoForm closes
+- **Commit**: c5112e1c
+
+### Issue 2: Linked Members Not Recognized
+- **Problem**: getUserMemberStatus() only checked linked if no application existed
+- **Fix**: Added linked checks at all failure points in function
+- **Commit**: e63bd806
+
+### Issue 3: JavaScript Pricing Calculations Wrong
+- **Problem**: calculateTotal() in driver_training, bush_mechanics, rescue_recovery incorrectly calculated non-member totals
+- **Fix**: Corrected variable names and logic to properly handle:
+  - Members: count themselves + additional members/non-members
+  - Non-members: count themselves only + additional participants
+- **Commits**: 
+  - driver_training: inline with member label UI improvement
+  - bush_mechanics & rescue_recovery: 646a3ecb
+
+## Performance Considerations
+
+### Database Queries
+- getUserMembershipLink() - Single query with index on secondary_user_id
+- getLinkedSecondaryUsers() - Single join query with index on primary_user_id
+- getUserMemberStatus() - Multiple queries but cached in session after first call
+
+### Recommended Indexes
+- membership_links(secondary_user_id)
+- membership_links(primary_user_id)
+- membership_links(status)
+
+## Security Considerations
+
+### Access Control
+- Only primary user can link/unlink accounts
+- Secondary user cannot manage their own link (primary must unlink)
+- CSRF tokens validated on all membership operations
+
+### Input Validation
+- User emails validated before linking
+- User IDs validated as integers
+- Links can only be created between valid users
+
+### Audit Trail
+- All linking operations logged via auditLog()
+- Timestamps recorded for all changes
+
+## Future Enhancements
+
+1. **Secondary user control**
+   - Allow secondary users to decline/accept links
+   - Option for secondary user to self-unlink
+
+2. **Permissions system**
+   - Granular control over which permissions secondary users receive
+   - Ability to revoke specific permissions without unlinking
+
+3. **Multiple primary accounts**
+   - Allow one user to be secondary to multiple primaries
+   - Flexible family/group structure support
+
+4. **Member linking UI**
+   - Search for existing members to link
+   - Batch link multiple users
+   - Link management dashboard
+
+5. **Expiration dates**
+   - Time-limited links (e.g., seasonal guests)
+   - Auto-renewal options
+   - Expiration notifications
+
+## Rollback Plan
+
+If issues arise, revert to previous commit:
+```bash
+git revert <commit-hash>
+```
+
+Key commits to know:
+- 646a3ecb - Latest fixes (pricing calculations)
+- e63bd806 - Improved getUserMemberStatus
+- c5112e1c - Fixed form nesting issue
+- bd20fc0f - Initial feature implementation