first commit

about/user_dashboard.md

@@ -0,0 +1,430 @@
+# Spanglish Website – User Accounts & Dashboard Specification
+
+## 1. Purpose
+
+This document defines the complete user account system, authentication methods, identity management, and user dashboard features for the Spanglish platform.
+
+It ensures that all bookings are linked to user accounts while keeping the booking process frictionless.
+
+The system supports both casual users and long-term community members.
+
+---
+
+## 2. Core Principles
+
+* Every booking is linked to a user account
+* Account creation must not block booking
+* Authentication must be flexible
+* Email is the primary identifier
+* Users own their data and history
+* Financial transparency is mandatory
+* Administrative users can manage and resolve conflicts
+
+---
+
+## 3. User Account Model
+
+### 3.1 Progressive Accounts
+
+Spanglish uses a progressive account system.
+
+Users are created automatically during booking using their email address.
+
+These accounts are initially marked as unclaimed and can be activated later.
+
+This allows first-time users to book without registration.
+
+---
+
+### 3.2 User States
+
+Each user account has one of the following states:
+
+* Unclaimed: Created during booking, no login configured
+* Claimed: User has activated login
+* Suspended: Disabled by admin
+
+---
+
+### 3.3 User Identity Fields
+
+Each user record contains:
+
+* id (UUID)
+* name
+* email (unique)
+* phone
+* password_hash (nullable)
+* google_id (nullable)
+* is_claimed (boolean)
+* ruc_number (nullable)
+* created_at
+* updated_at
+
+Email is the primary identity key.
+
+---
+
+## 4. Authentication Methods
+
+### 4.1 Password Authentication
+
+Users may optionally set a password.
+
+Passwords are never required for booking.
+
+Requirements:
+
+* Minimum 10 characters
+* Argon2 hashing
+* Reset via email
+
+---
+
+### 4.2 Google Login (OAuth)
+
+Users may authenticate using Google.
+
+Behavior:
+
+* Email is verified by Google
+* Existing accounts are matched by email
+* Google ID is linked on first login
+
+---
+
+### 4.3 Email Code / Magic Link
+
+Users may log in using one-time codes or magic links.
+
+Behavior:
+
+* Code expires in 10 minutes
+* One-time use only
+* Sent to registered email
+
+---
+
+## 5. Account Claiming Flow
+
+When a user books without logging in:
+
+1. System creates unclaimed account
+2. Confirmation email includes "Claim Account" link
+3. User sets password or links Google
+4. Account becomes claimed
+
+This process is optional but encouraged.
+
+---
+
+## 6. Booking to User Linking
+
+During booking:
+
+* Email is mandatory
+* System searches for existing user
+* If found, booking is linked
+* If not found, new user is created
+
+All tickets are linked to user_id.
+
+No orphan records are allowed.
+
+---
+
+## 7. Multiple Ticket Management
+
+### 7.1 Single User, Multiple Events
+
+Users may book unlimited events.
+
+Each booking creates a separate ticket record.
+
+---
+
+### 7.2 Group Bookings
+
+Users may purchase multiple tickets per booking.
+
+Behavior:
+
+* One user_id owns all tickets
+* Guest names are optional
+* Tickets may be reassigned later
+
+---
+
+## 8. RUC & Invoice Management
+
+### 8.1 RUC Collection
+
+During booking, users may optionally provide:
+
+* Paraguayan RUC number
+* Legal name (optional)
+
+This data is stored in the user profile and booking record.
+
+---
+
+### 8.2 Invoice Generation
+
+When a booking is marked as Paid:
+
+* System generates a fiscal invoice
+* Invoice includes RUC data
+* Invoice is stored as PDF
+* Invoice is linked to payment record
+
+Invoices are immutable after generation.
+
+---
+
+### 8.3 Invoice Access
+
+From the dashboard, users may:
+
+* View invoices
+* Download PDF invoices
+* Access invoice history
+
+Only confirmed and paid bookings generate invoices.
+
+---
+
+## 9. User Dashboard
+
+### 9.1 Access
+
+Dashboard URL:
+
+/dashboard
+
+Authentication required.
+
+---
+
+### 9.2 Dashboard Sections
+
+#### 9.2.1 Welcome Panel
+
+Displays:
+
+* User name
+* Account status
+* Membership duration
+
+---
+
+#### 9.2.2 Next Event Panel
+
+Displays:
+
+* Upcoming event
+* Date and time
+* Location
+* Payment status
+
+Actions:
+
+* View ticket
+* Open map
+* Add to calendar
+
+---
+
+#### 9.2.3 My Tickets
+
+Displays all tickets:
+
+* Event name
+* Date
+* Payment method
+* Status
+* Invoice link (if available)
+
+Tickets link to detail view.
+
+---
+
+#### 9.2.4 Payments & Invoices
+
+Displays:
+
+* Payment history
+* Pending approvals
+* Downloadable invoices
+* Payment references
+
+---
+
+#### 9.2.5 Community Access
+
+Displays:
+
+* WhatsApp group link
+* Instagram link
+* Website link
+
+Links are managed by admin.
+
+---
+
+#### 9.2.6 Profile Settings
+
+Users may edit:
+
+* Name
+* Email
+* Phone
+* Preferred language
+* RUC number
+
+Email changes require verification.
+
+---
+
+#### 9.2.7 Security Settings
+
+Users may:
+
+* Set or change password
+* Link / unlink Google account
+* View active sessions
+* Logout all sessions
+
+---
+
+#### 9.2.8 Support Panel
+
+Includes:
+
+* Contact links
+* FAQ
+* Support form
+
+---
+
+## 10. Ticket Detail View
+
+Each ticket page includes:
+
+* Ticket ID
+* QR code (optional)
+* Event details
+* Payment status
+* Invoice download
+* Check-in status
+
+---
+
+## 11. Admin User Management
+
+Admins may:
+
+* View all users
+* Edit profiles
+* Reset authentication
+* Merge duplicate accounts
+* Suspend users
+* Edit RUC data
+
+All actions are logged.
+
+---
+
+## 12. Data Protection & Privacy
+
+* GDPR-style data rights
+* Data export on request
+* Account deletion support
+* Secure storage
+* Encrypted credentials
+
+---
+
+## 13. Notifications
+
+Users receive system notifications for:
+
+* Booking confirmation
+* Payment approval
+* Invoice generation
+* Account security changes
+
+Notifications are delivered via email.
+
+---
+
+## 14. Database Tables (Core)
+
+### users
+
+* id
+* name
+* email
+* phone
+* password_hash
+* google_id
+* is_claimed
+* ruc_number
+* created_at
+
+### tickets
+
+* id
+* user_id
+* event_id
+* status
+* created_at
+
+### payments
+
+* id
+* ticket_id
+* status
+* amount
+* reference
+
+### invoices
+
+* id
+* payment_id
+* pdf_url
+* ruc_number
+* created_at
+
+---
+
+## 15. Security Requirements
+
+* Argon2 password hashing
+* OAuth verification
+* Rate-limited login
+* Brute-force protection
+* Secure cookies
+* HTTPS enforced
+
+---
+
+## 16. Future Extensions
+
+Planned enhancements:
+
+* Loyalty tiers
+* Membership subscriptions
+* Family accounts
+* Corporate accounts
+* Tax reporting exports
+* Mobile app support
+
+---
+
+## 17. Summary
+
+The Spanglish user system provides frictionless onboarding, strong identity management, and full financial transparency.
+
+It supports both casual participants and professional users who require invoices and account history.
+
+All implementations must follow this specification.