431 lines
6.3 KiB
Markdown
431 lines
6.3 KiB
Markdown
# 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.
|