feat: initialize Next.js project with Prisma, authentication, and rankings page
This commit is contained in:
@@ -0,0 +1,283 @@
|
||||
# Authentication, Authorization, and Accounting (AAA) Design
|
||||
|
||||
## Overview
|
||||
Implement a comprehensive AAA system for EuchreCamp with user authentication, role-based authorization, and activity logging.
|
||||
|
||||
## Authentication (Who are you?)
|
||||
|
||||
### User Model
|
||||
```ruby
|
||||
# Database Schema
|
||||
table :users do
|
||||
primary_key :id
|
||||
foreign_key :player_id, :players # Links to existing player record
|
||||
column :email, String, null: false, unique: true
|
||||
column :password_digest, String, null: false
|
||||
column :confirmed, Boolean, default: false
|
||||
column :confirmation_token, String
|
||||
column :confirmation_sent_at, DateTime
|
||||
column :reset_password_token, String
|
||||
column :reset_password_sent_at, DateTime
|
||||
column :failed_login_attempts, Integer, default: 0
|
||||
column :locked_until, DateTime
|
||||
column :last_login_at, DateTime
|
||||
column :last_login_ip, String
|
||||
column :created_at, DateTime, null: false
|
||||
column :updated_at, DateTime, null: false
|
||||
end
|
||||
|
||||
# Indexes
|
||||
add_index :users, :email, unique: true
|
||||
add_index :users, :confirmation_token
|
||||
add_index :users, :reset_password_token
|
||||
```
|
||||
|
||||
### Authentication Flow
|
||||
1. User enters email and password
|
||||
2. System verifies email exists and account is not locked
|
||||
3. BCrypt verifies password hash
|
||||
4. If successful:
|
||||
- Update `last_login_at` and `last_login_ip`
|
||||
- Reset `failed_login_attempts`
|
||||
- Create session/token
|
||||
5. If failed:
|
||||
- Increment `failed_login_attempts`
|
||||
- Lock account after 5 failed attempts (15 minutes)
|
||||
|
||||
### Session Management
|
||||
- Use signed cookies for session storage
|
||||
- Session expires after 30 days of inactivity
|
||||
- Session invalidation on password change
|
||||
- Concurrent session limits (optional)
|
||||
|
||||
### Password Requirements
|
||||
- Minimum 8 characters
|
||||
- At least one uppercase letter
|
||||
- At least one lowercase letter
|
||||
- At least one number
|
||||
- At least one special character
|
||||
|
||||
### Registration Flow
|
||||
1. User registers with email and password
|
||||
2. System creates user record with `confirmed: false`
|
||||
3. Send confirmation email with unique token
|
||||
4. User clicks link to confirm account
|
||||
5. Account activated and ready for login
|
||||
|
||||
### Password Reset Flow
|
||||
1. User requests password reset
|
||||
2. System generates unique token (expires in 1 hour)
|
||||
3. Send reset email with token link
|
||||
4. User enters new password
|
||||
5. System validates and updates password hash
|
||||
6. Invalidate all existing sessions
|
||||
|
||||
## Authorization (What can you do?)
|
||||
|
||||
### Role-Based Access Control (RBAC)
|
||||
|
||||
#### Roles
|
||||
```ruby
|
||||
ROLES = {
|
||||
player: 0, # Default user - can view rankings, own profile
|
||||
tournament_admin: 1, # Can manage specific tournaments
|
||||
club_admin: 2, # Superuser - full access
|
||||
system_admin: 3 # Technical admin access
|
||||
}
|
||||
```
|
||||
|
||||
#### Permission Matrix
|
||||
|
||||
| Permission | Player | Tournament Admin | Club Admin | System Admin |
|
||||
|------------|--------|------------------|------------|--------------|
|
||||
| View rankings | ✅ | ✅ | ✅ | ✅ |
|
||||
| View own profile | ✅ | ✅ | ✅ | ✅ |
|
||||
| Edit own profile | ✅ | ✅ | ✅ | ✅ |
|
||||
| View other profiles | ✅ | ✅ | ✅ | ✅ |
|
||||
| Record own matches | ✅ | ✅ | ✅ | ✅ |
|
||||
| Create tournaments | ❌ | ✅ | ✅ | ✅ |
|
||||
| Manage own tournaments | ❌ | ✅ | ✅ | ✅ |
|
||||
| Manage all tournaments | ❌ | ❌ | ✅ | ✅ |
|
||||
| Manage all players | ❌ | ❌ | ✅ | ✅ |
|
||||
| Club settings | ❌ | ❌ | ✅ | ✅ |
|
||||
| System settings | ❌ | ❌ | ❌ | ✅ |
|
||||
|
||||
### Implementation
|
||||
```ruby
|
||||
module EuchreCamp
|
||||
module Auth
|
||||
class Authorization
|
||||
def self.can?(user, action, resource = nil)
|
||||
case action
|
||||
when :view_rankings
|
||||
true # All users can view rankings
|
||||
when :edit_profile
|
||||
resource.nil? || resource.id == user.player_id
|
||||
when :create_tournament
|
||||
user.club_admin? || user.system_admin?
|
||||
when :manage_tournament
|
||||
user.club_admin? || user.system_admin? ||
|
||||
(user.tournament_admin? && resource.admin_id == user.player_id)
|
||||
when :manage_players
|
||||
user.club_admin? || user.system_admin?
|
||||
else
|
||||
false
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
### Middleware
|
||||
- Authentication middleware checks for valid session
|
||||
- Authorization middleware verifies permissions
|
||||
- Redirect unauthenticated users to login
|
||||
- Show 403 Forbidden for unauthorized actions
|
||||
|
||||
## Accounting (What did you do?)
|
||||
|
||||
### Activity Logging
|
||||
```ruby
|
||||
table :activity_logs do
|
||||
primary_key :id
|
||||
foreign_key :user_id, :users
|
||||
column :action, String, null: false # e.g., 'login', 'create_tournament', 'record_match'
|
||||
column :resource_type, String # e.g., 'tournament', 'match', 'player'
|
||||
column :resource_id, Integer
|
||||
column :ip_address, String
|
||||
column :user_agent, String
|
||||
column :details, JSON # Additional context
|
||||
column :created_at, DateTime, null: false
|
||||
end
|
||||
|
||||
add_index :activity_logs, [:user_id, :created_at]
|
||||
add_index :activity_logs, [:resource_type, :resource_id]
|
||||
```
|
||||
|
||||
### Tracked Events
|
||||
- Authentication events (login, logout, password change)
|
||||
- Tournament management (create, update, delete, schedule)
|
||||
- Match recording (create, update, delete)
|
||||
- Player management (create, update)
|
||||
- Settings changes
|
||||
|
||||
### Audit Reports
|
||||
- User activity timeline
|
||||
- Tournament lifecycle audit
|
||||
- Match result verification log
|
||||
- System changes overview
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Authentication (Week 1-2)
|
||||
- [ ] Create users table and model
|
||||
- [ ] Implement BCrypt password hashing
|
||||
- [ ] Build login/logout actions
|
||||
- [ ] Create registration flow
|
||||
- [ ] Add session management
|
||||
- [ ] Password reset functionality
|
||||
|
||||
### Phase 2: Authorization (Week 2-3)
|
||||
- [ ] Define roles and permissions
|
||||
- [ ] Implement RBAC middleware
|
||||
- [ ] Add role assignment UI (for club admins)
|
||||
- [ ] Protect routes based on roles
|
||||
- [ ] Add permission checks to actions
|
||||
|
||||
### Phase 3: Accounting (Week 3-4)
|
||||
- [ ] Create activity logging system
|
||||
- [ ] Track key events
|
||||
- [ ] Build audit reports UI
|
||||
- [ ] Add activity feed to dashboard
|
||||
|
||||
### Phase 4: Security Hardening (Week 4-5)
|
||||
- [ ] Rate limiting on login attempts
|
||||
- [ ] IP-based lockout
|
||||
- [ ] Secure cookie settings
|
||||
- [ ] CSRF protection
|
||||
- [ ] Security headers
|
||||
- [ ] Session fixation prevention
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Password Security
|
||||
- Use BCrypt with cost factor 12+
|
||||
- Never store plaintext passwords
|
||||
- Enforce strong password policy
|
||||
- Rate limit password attempts
|
||||
|
||||
### Session Security
|
||||
- Use signed, encrypted cookies
|
||||
- Regenerate session ID on privilege escalation
|
||||
- Set appropriate expiration times
|
||||
- Invalidate on password change
|
||||
|
||||
### Access Control
|
||||
- Principle of least privilege
|
||||
- Defense in depth
|
||||
- Fail securely (deny by default)
|
||||
- Log all access attempts
|
||||
|
||||
### Data Protection
|
||||
- Encrypt sensitive data at rest
|
||||
- Secure transmission (HTTPS only)
|
||||
- Regular security audits
|
||||
- Compliance with privacy regulations
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Authentication
|
||||
```
|
||||
POST /auth/login # Login with email/password
|
||||
POST /auth/logout # Logout current session
|
||||
POST /auth/register # Create new account
|
||||
POST /auth/confirm # Confirm email address
|
||||
POST /auth/forgot # Request password reset
|
||||
POST /auth/reset # Reset password with token
|
||||
```
|
||||
|
||||
### Users
|
||||
```
|
||||
GET /users/me # Get current user profile
|
||||
PATCH /users/me # Update own profile
|
||||
GET /users/:id # Get user profile (public)
|
||||
```
|
||||
|
||||
### Admin
|
||||
```
|
||||
GET /admin/users # List users (club admin only)
|
||||
PATCH /admin/users/:id # Update user roles (club admin only)
|
||||
GET /admin/activity # View audit logs (club admin only)
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
- Password hashing verification
|
||||
- Permission calculations
|
||||
- Session management
|
||||
- Activity logging
|
||||
|
||||
### Integration Tests
|
||||
- Login/logout flow
|
||||
- Registration process
|
||||
- Password reset
|
||||
- Role-based access
|
||||
|
||||
### Security Tests
|
||||
- SQL injection prevention
|
||||
- XSS prevention
|
||||
- CSRF protection
|
||||
- Rate limiting
|
||||
- Session security
|
||||
|
||||
## Migration Steps
|
||||
|
||||
1. Create users table and related migrations
|
||||
2. Add foreign key from users to players
|
||||
3. Migrate existing player data to users (optional)
|
||||
4. Update navigation to show login/logout links
|
||||
5. Add authentication checks to existing actions
|
||||
6. Implement role assignment for existing admins
|
||||
7. Set up activity logging for new features
|
||||
@@ -0,0 +1,88 @@
|
||||
# AAA System Implementation Progress
|
||||
|
||||
## Files Created
|
||||
|
||||
### Database
|
||||
- `db/migrate/20240915000008_create_users.rb` - Users table with authentication fields
|
||||
|
||||
### Models/Entities
|
||||
- `lib/euchre_camp/entities/user.rb` - User entity with authentication methods
|
||||
|
||||
### Repositories
|
||||
- `app/repositories/users.rb` - Users repository with authentication logic
|
||||
|
||||
### Actions
|
||||
- `app/actions/auth/login.rb` - Login form and authentication processing
|
||||
- `app/actions/auth/logout.rb` - Logout action
|
||||
|
||||
### Templates
|
||||
- `app/templates/auth/login.html.erb` - Login page template
|
||||
|
||||
### Routes
|
||||
- Updated `config/routes.rb` with login/logout routes
|
||||
|
||||
### Styles
|
||||
- Updated `app/assets/css/app.css` with auth page styling
|
||||
|
||||
### Documentation
|
||||
- `AAA_DESIGN.md` - Complete AAA design specification
|
||||
- `AAA_IMPLEMENTATION.md` - This file
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
### Authentication
|
||||
- [x] Users table migration created
|
||||
- [x] Users repository with authentication methods
|
||||
- [x] User entity/model with authentication helpers
|
||||
- [x] Login form template
|
||||
- [x] Login action (GET and POST)
|
||||
- [x] Logout action
|
||||
- [x] Login/logout routes
|
||||
- [ ] BCrypt added to Gemfile (pending bundle install)
|
||||
- [ ] Session management middleware
|
||||
- [ ] Current user helper for views
|
||||
- [ ] Registration flow
|
||||
- [ ] Password reset functionality
|
||||
- [ ] Email confirmation system
|
||||
|
||||
### Authorization
|
||||
- [ ] Role definitions (player, tournament_admin, club_admin, system_admin)
|
||||
- [ ] Permission matrix implementation
|
||||
- [ ] RBAC middleware
|
||||
- [ ] Role assignment UI
|
||||
- [ ] Route protection
|
||||
|
||||
### Accounting
|
||||
- [ ] Activity logging system
|
||||
- [ ] Audit report UI
|
||||
- [ ] Activity feed
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Install BCrypt: `bundle install`
|
||||
2. Create registration action and template
|
||||
3. Implement session management middleware
|
||||
4. Add current_user helper to base action
|
||||
5. Create password reset flow
|
||||
6. Build email confirmation system
|
||||
7. Implement role-based authorization
|
||||
8. Add activity logging
|
||||
|
||||
## Security Features Implemented
|
||||
|
||||
### Account Lockout
|
||||
- After 5 failed login attempts, account is locked for 15 minutes
|
||||
- Prevents brute force attacks
|
||||
|
||||
### Password Storage
|
||||
- Passwords will be hashed with BCrypt
|
||||
- Never stored in plaintext
|
||||
|
||||
### Session Security
|
||||
- Session cleared on logout
|
||||
- User ID and player ID stored in session
|
||||
|
||||
### Input Validation
|
||||
- Email format validation
|
||||
- Password required
|
||||
- Form submission protection
|
||||
@@ -0,0 +1,31 @@
|
||||
Event #,Round,Table,Seat 1,Seat 3,Odds Points,Seat 2,Seat 4,Evens Points,Winner
|
||||
1,1,Clubs,Derrick,Jesse C,5,Emma,Alissa,10,Evens
|
||||
1,1,Hearts,Kevin,Andy,8,Ellie,Jesse,6,Odds
|
||||
1,1,Diamonds,Sara M,Amelia,10,Mike G,AJ,4,Odds
|
||||
1,1,Spades,John,Dave B,7,Sara R,Emily,9,Evens
|
||||
1,1,Stars,Linden,Jim,1,David G,Lynn,10,Evens
|
||||
1,2,Clubs,John,Morgan,7,Alissa,Emma,14,Evens
|
||||
1,2,Hearts,Lynn,Mike G,6,Kevin,AJ,8,Evens
|
||||
1,2,Diamonds,Jesse F,Amelia,6,Linden,Jesse C,8,Evens
|
||||
1,2,Spades,Lucas,Andy,18,Derrick,Ellie,7,Odds
|
||||
1,2,Stars,Dave B,Emily,9,Jim,Sara R,12,Evens
|
||||
1,3,Hearts,Lynn,Derrick,10,Alissa,Emma,13,Evens
|
||||
1,3,Clubs,Kevin,AJ,2,Andy,Jesse C,11,Evens
|
||||
1,3,Diamonds,Jim,Mike G,8,Amelia,Kristen,4,Odds
|
||||
1,3,Spades,Ellie,John,11,Sara R,Dave B,12,Evens
|
||||
1,3,Stars,Lucas,Linden,7,Emily,Sara M,14,Evens
|
||||
1,4,Diamonds,John,Kevin,10,Alissa,Emma,7,Odds
|
||||
1,4,Hearts,Emily,Sara M,11,Jim,Ellie,6,Odds
|
||||
1,4,Clubs,Linden,AJ,2,Amelia,Mike G,8,Evens
|
||||
1,4,Spades,Andy,Derrick,10,Sara R,Jesse C,5,Odds
|
||||
1,4,Stars,Dave B,Lucas,9,David G,Lynn,7,Odds
|
||||
1,5,Clubs,Amelia,Alissa,11,Linden,Ellie,3,Odds
|
||||
1,5,Hearts,Emily,Sara R,10,Mike G,Andy,9,Odds
|
||||
1,5,Diamonds,Derrick,Jesse F,5,Sara M,Jim,5,Evens
|
||||
1,5,Spades,Kevin,Emma,11,Lynn,Dave B,11,Evens
|
||||
1,5,Stars,John,Lucas,9,AJ,Jesse C,6,Odds
|
||||
1,6,Diamonds,Alissa,Jim,11,John,Mike G,6,Odds
|
||||
1,6,Hearts,Kevin,AJ,8,Sara R,Emma,12,Evens
|
||||
1,6,Clubs,Derrick,Lucas,6,David G,Jesse C,5,Odds
|
||||
1,6,Spades,Lynn,Emily,9,Amelia,Dave B,7,Odds
|
||||
1,6,Stars,Sara M,Ellie,5,Linden,Andy,9,Evens
|
||||
|
+552
@@ -0,0 +1,552 @@
|
||||
# EuchreCamp
|
||||
|
||||
A comprehensive tournament management and partnership analytics system for the card game Euchre.
|
||||
|
||||
## Overview
|
||||
|
||||
EuchreCamp is a full-stack Ruby web application built with Hanami 2.1 that provides:
|
||||
|
||||
- **Tournament Management**: Create and manage round-robin, single elimination, double elimination, and Swiss-style tournaments
|
||||
- **Partnership Analytics**: Track partnership performance, win rates, and Elo changes between players
|
||||
- **Player Profiles**: Display individual player statistics and partnership breakdowns
|
||||
- **Admin Dashboard**: Centralized management interface for tournaments, players, and matches
|
||||
- **Authentication & Authorization**: Role-based access control with player, tournament_admin, and club_admin roles
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Ruby 3.3.3 (managed by mise or rbenv)
|
||||
- Node.js 22+ (for asset compilation)
|
||||
- SQLite3
|
||||
- Bundler
|
||||
|
||||
### Installation
|
||||
|
||||
1. **Clone the repository:**
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd euchre_camp
|
||||
```
|
||||
|
||||
2. **Install dependencies:**
|
||||
|
||||
```bash
|
||||
bundle install
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **Set up the database:**
|
||||
|
||||
```bash
|
||||
bundle exec rake db:migrate
|
||||
```
|
||||
|
||||
4. **Compile assets:**
|
||||
|
||||
```bash
|
||||
./node_modules/.bin/esbuild app/assets/css/app.css --bundle --outfile=public/assets/app-GVDAEYEC.css
|
||||
```
|
||||
|
||||
5. **Start the server:**
|
||||
|
||||
```bash
|
||||
bundle exec puma -p 3000 -e development
|
||||
```
|
||||
|
||||
### Accessing the Application
|
||||
|
||||
- **Main Page**: http://localhost:3000
|
||||
- **Admin Dashboard**: http://localhost:3000/admin
|
||||
- **Rankings**: http://localhost:3000/rankings
|
||||
- **Login**: http://localhost:3000/login
|
||||
|
||||
## Development
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
euchre_camp/
|
||||
├── app/
|
||||
│ ├── actions/ # Hanami actions (controllers)
|
||||
│ ├── assets/ # CSS, JavaScript, images
|
||||
│ ├── repositories/ # ROM repositories for data access
|
||||
│ ├── services/ # Business logic (Elo calculator, partnership tracker)
|
||||
│ ├── templates/ # ERB view templates
|
||||
│ ├── views/ # Hanami view objects
|
||||
│ └── action.rb # Base action class with auth helpers
|
||||
├── config/
|
||||
│ ├── routes.rb # Application routes
|
||||
│ ├── app.rb # Hanami app configuration
|
||||
│ └── assets.js # Asset compilation configuration
|
||||
├── db/
|
||||
│ ├── migrate/ # Database migrations
|
||||
│ └── euchre_camp.db # SQLite database
|
||||
├── lib/
|
||||
│ └── euchre_camp/ # Domain models and entities
|
||||
├── spec/
|
||||
│ └── acceptance/ # RSpec acceptance tests
|
||||
└── public/
|
||||
└── assets/ # Compiled assets
|
||||
```
|
||||
|
||||
### Running the Application
|
||||
|
||||
**Development mode (with auto-reload):**
|
||||
|
||||
```bash
|
||||
bundle exec puma -p 3000 -e development
|
||||
```
|
||||
|
||||
**Production mode:**
|
||||
|
||||
```bash
|
||||
bundle exec puma -p 3000 -e production
|
||||
```
|
||||
|
||||
### Database Management
|
||||
|
||||
**Run migrations:**
|
||||
|
||||
```bash
|
||||
bundle exec rake db:migrate
|
||||
```
|
||||
|
||||
**Rollback last migration:**
|
||||
|
||||
```bash
|
||||
bundle exec rake db:migrate[<version>]
|
||||
```
|
||||
|
||||
**Reset database:**
|
||||
|
||||
```bash
|
||||
bundle exec rake db:reset
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
**Run all acceptance tests:**
|
||||
|
||||
```bash
|
||||
bundle exec rspec spec/acceptance/
|
||||
```
|
||||
|
||||
**Run specific test:**
|
||||
|
||||
```bash
|
||||
bundle exec rspec spec/acceptance/tournament_partnership_spec.rb:280
|
||||
```
|
||||
|
||||
**Run with documentation:**
|
||||
|
||||
```bash
|
||||
bundle exec rspec spec/acceptance/ --format documentation
|
||||
```
|
||||
|
||||
**Run Playwright mobile responsiveness tests:**
|
||||
|
||||
```bash
|
||||
# Start the server
|
||||
bundle exec hanami server --port 2300 &
|
||||
|
||||
# Run Playwright tests
|
||||
bundle exec rspec spec/playwright/mobile_responsiveness_spec.rb
|
||||
```
|
||||
|
||||
**Test with Playwright MCP (browser automation):**
|
||||
|
||||
1. Start the Hanami server: `bundle exec hanami server --port 2300`
|
||||
2. Use opencode with Playwright MCP tools to:
|
||||
- Navigate to pages
|
||||
- Take screenshots
|
||||
- Test responsive layouts
|
||||
- Verify mobile UI elements
|
||||
|
||||
### Assets
|
||||
|
||||
**Compile CSS for development:**
|
||||
|
||||
```bash
|
||||
./node_modules/.bin/esbuild app/assets/css/app.css --bundle --outfile=public/assets/app-GVDAEYEC.css
|
||||
```
|
||||
|
||||
**Watch for changes (requires separate process):**
|
||||
|
||||
```bash
|
||||
./node_modules/.bin/esbuild app/assets/css/app.css --bundle --outfile=public/assets/app-GVDAEYEC.css --watch
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
### Tournament Management
|
||||
|
||||
#### Creating a Tournament
|
||||
|
||||
1. Navigate to Admin Dashboard (`/admin`)
|
||||
2. Click "Create Tournament"
|
||||
3. Enter tournament details:
|
||||
- Name
|
||||
- Format (round-robin, single elimination, double elimination, Swiss)
|
||||
- Number of teams/players
|
||||
4. Register participants
|
||||
5. Generate schedule
|
||||
6. Record match results
|
||||
|
||||
#### Tournament Formats
|
||||
|
||||
- **Round-Robin**: Each team plays every other team once
|
||||
- **Single Elimination**: Lose once and you're out
|
||||
- **Double Elimination**: Must lose twice to be eliminated
|
||||
- **Swiss**: Pairings based on win-loss records
|
||||
|
||||
### Partnership Analytics
|
||||
|
||||
#### Tracking Partnerships
|
||||
|
||||
The system automatically tracks:
|
||||
- Games played together
|
||||
- Win/loss records
|
||||
- Elo changes per partnership
|
||||
- Partnership win rates
|
||||
|
||||
#### Viewing Partnership Data
|
||||
|
||||
1. Visit any player's profile page (`/players/:id/profile`)
|
||||
2. Scroll to "Partnership Performance" section
|
||||
3. View statistics for each partner
|
||||
|
||||
### Player Profiles
|
||||
|
||||
Each player profile displays:
|
||||
- Current Elo rating
|
||||
- Total games played
|
||||
- Win rate
|
||||
- Partnership statistics
|
||||
- Recent games timeline
|
||||
|
||||
### Admin Dashboard
|
||||
|
||||
The admin dashboard provides:
|
||||
- Quick statistics (total players, active tournaments, recent matches)
|
||||
- Quick action buttons for common tasks
|
||||
- Recent matches table
|
||||
- Links to all admin sections
|
||||
|
||||
## Authentication & Authorization
|
||||
|
||||
### User Roles
|
||||
|
||||
| Role | Permissions |
|
||||
|------|-------------|
|
||||
| **Player** | Edit own profile, record own matches within 5 minutes |
|
||||
| **Tournament Admin** | Create/manage tournaments, edit matches in their tournaments (no time limit) |
|
||||
| **Club Admin** | Full access to edit/delete any record, manage all players and tournaments |
|
||||
|
||||
### Login/Logout
|
||||
|
||||
**Login:**
|
||||
- Navigate to `/login`
|
||||
- Enter email and password
|
||||
- Click "Login"
|
||||
|
||||
**Logout:**
|
||||
- Click "Logout" in navigation bar
|
||||
|
||||
### Admin User Creation
|
||||
|
||||
To create an admin user, use the provided script:
|
||||
|
||||
```bash
|
||||
ruby scripts/create_admin.rb <email> <password>
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
ruby scripts/create_admin.rb david@dhg.lol admin
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Create a player profile
|
||||
2. Create a user account with `club_admin` role
|
||||
3. Mark the account as confirmed
|
||||
|
||||
**Manual SQL Alternative:**
|
||||
|
||||
If you prefer to create users manually via SQL:
|
||||
|
||||
1. Access the database: `sqlite3 db/euchre_camp.db`
|
||||
2. Generate a BCrypt password hash:
|
||||
```bash
|
||||
ruby -e "require 'bcrypt'; puts BCrypt::Password.create('your_password')"
|
||||
```
|
||||
3. Insert a user record:
|
||||
```sql
|
||||
INSERT INTO players (name, rating) VALUES ('PlayerName', 1000);
|
||||
INSERT INTO users (player_id, email, password_digest, role, confirmed, created_at, updated_at)
|
||||
VALUES (1, 'user@example.com', '$2b$12$...', 'club_admin', 1, datetime('now'), datetime('now'));
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### Routes
|
||||
|
||||
#### Public Routes
|
||||
- `GET /` - Redirects to rankings
|
||||
- `GET /rankings` - Player rankings
|
||||
- `GET /players/:id` - Player profile
|
||||
- `GET /players/:id/profile` - Player profile with partnerships
|
||||
- `GET /players/:id/schedule` - Player tournament schedule
|
||||
|
||||
#### Authentication Routes
|
||||
- `GET /login` - Login form
|
||||
- `POST /auth/login` - Process login
|
||||
- `GET /logout` - Logout and clear session
|
||||
|
||||
#### Admin Routes (Require Authentication)
|
||||
- `GET /admin` - Admin dashboard
|
||||
- `GET /admin/players` - List all players
|
||||
- `GET /admin/players/new` - Add new player form
|
||||
- `POST /admin/players` - Create new player
|
||||
- `GET /admin/players/:id/edit` - Edit player form
|
||||
- `PATCH /admin/players/:id` - Update player
|
||||
- `DELETE /admin/players/:id` - Delete player
|
||||
- `GET /admin/matches` - List all matches
|
||||
- `GET /admin/matches/new` - Record match form
|
||||
- `POST /admin/matches` - Create match
|
||||
- `GET /admin/matches/:id/edit` - Edit match form
|
||||
- `PATCH /admin/matches/:id` - Update match
|
||||
- `GET /admin/matches/upload` - CSV upload form
|
||||
- `POST /admin/matches/process_upload` - Process CSV upload
|
||||
- `GET /admin/tournaments` - List all tournaments
|
||||
- `GET /admin/tournaments/new` - Create tournament form
|
||||
- `POST /admin/tournaments` - Create tournament
|
||||
- `GET /admin/tournaments/:id` - Tournament details
|
||||
- `GET /admin/tournaments/:id/edit` - Edit tournament form
|
||||
- `PATCH /admin/tournaments/:id` - Update tournament
|
||||
- `DELETE /admin/tournaments/:id` - Delete tournament
|
||||
- `POST /admin/tournaments/:id/participants` - Add participant
|
||||
- `DELETE /admin/tournaments/:id/participants/:player_id` - Remove participant
|
||||
- `POST /admin/tournaments/:id/teams` - Create team
|
||||
- `GET /admin/tournaments/:id/teams/:team_id/edit` - Edit team form
|
||||
- `PATCH /admin/tournaments/:id/teams/:team_id` - Update team
|
||||
- `DELETE /admin/tournaments/:id/teams/:team_id` - Delete team
|
||||
- `POST /admin/tournaments/:id/schedule` - Generate schedule
|
||||
- `GET /admin/tournaments/:id/rounds/:round_id` - View round matchups
|
||||
- `GET /admin/tournaments/:id/results` - Tournament results
|
||||
- `POST /admin/tournaments/:id/results` - Save results
|
||||
- `POST /admin/tournaments/:id/complete` - Complete tournament
|
||||
|
||||
## Database Schema
|
||||
|
||||
### Tables
|
||||
|
||||
- **players**: Player information and ratings
|
||||
- **users**: Authentication and authorization
|
||||
- **events**: Tournaments and events
|
||||
- **event_participants**: Player participation in tournaments
|
||||
- **teams**: Teams in tournaments
|
||||
- **tournament_rounds**: Tournament rounds
|
||||
- **bracket_matchups**: Matchups per round
|
||||
- **matches**: Individual match results
|
||||
- **elo_snapshots**: Elo rating history
|
||||
- **partnership_games**: Partnership occurrence tracking
|
||||
- **partnership_stats**: Aggregated partnership statistics
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Adding a New Player
|
||||
|
||||
1. Navigate to Admin Dashboard
|
||||
2. Click "Add Player"
|
||||
3. Enter name and initial rating (default 1000)
|
||||
4. Click "Create Player"
|
||||
|
||||
### Recording a Match
|
||||
|
||||
1. Navigate to Admin Dashboard
|
||||
2. Click "Record Match Result"
|
||||
3. Select players for Team 1 and Team 2
|
||||
4. Enter scores
|
||||
5. Click "Create Match"
|
||||
|
||||
### Creating a Tournament
|
||||
|
||||
1. Navigate to Admin Dashboard
|
||||
2. Click "Create Tournament"
|
||||
3. Enter tournament details
|
||||
4. Register participants
|
||||
5. Generate schedule
|
||||
6. Start recording results
|
||||
|
||||
### Editing a Match
|
||||
|
||||
**Within 5 minutes (any user):**
|
||||
1. Navigate to `/admin/matches`
|
||||
2. Click "Edit" next to the match
|
||||
3. Update scores
|
||||
4. Click "Update Match"
|
||||
|
||||
**Anytime (tournament admin or club admin):**
|
||||
- Same process as above, no time restriction
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Server won't start:**
|
||||
- Check if port 3000 is already in use: `lsof -i :3000`
|
||||
- Kill existing process: `kill -9 <PID>`
|
||||
- Try a different port: `bundle exec puma -p 3001`
|
||||
|
||||
**CSS not loading:**
|
||||
- Recompile assets: `./node_modules/.bin/esbuild app/assets/css/app.css --bundle --outfile=public/assets/app-GVDAEYEC.css`
|
||||
- Clear browser cache
|
||||
|
||||
**Database errors:**
|
||||
- Run migrations: `bundle exec rake db:migrate`
|
||||
- Reset database: `bundle exec rake db:reset`
|
||||
|
||||
**Authorization errors:**
|
||||
- Ensure you're logged in
|
||||
- Check user role in database
|
||||
|
||||
### Debugging
|
||||
|
||||
**Check server logs:**
|
||||
|
||||
```bash
|
||||
tail -f /tmp/puma.log
|
||||
```
|
||||
|
||||
**Check database:**
|
||||
|
||||
```bash
|
||||
sqlite3 db/euchre_camp.db
|
||||
sqlite> .tables
|
||||
sqlite> SELECT * FROM users;
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Making Changes
|
||||
|
||||
1. Create a feature branch: `git checkout -b feature/your-feature`
|
||||
2. Make changes to code
|
||||
3. Run tests: `bundle exec rspec spec/acceptance/`
|
||||
4. Commit with conventional commit message
|
||||
5. Push to remote: `git push origin feature/your-feature`
|
||||
6. Create pull request
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
```
|
||||
<type>: <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer]
|
||||
```
|
||||
|
||||
Types:
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation changes
|
||||
- `style`: Code style changes
|
||||
- `refactor`: Code refactoring
|
||||
- `test`: Test changes
|
||||
- `chore`: Build/dependency changes
|
||||
|
||||
### Code Style
|
||||
|
||||
- Follow existing code patterns in the project
|
||||
- Use ROM (Ruby Object Mapper) for database access
|
||||
- Keep business logic in services
|
||||
- Use dependency injection in actions
|
||||
- Write acceptance tests for new features
|
||||
|
||||
## Deployment
|
||||
|
||||
### Production Environment
|
||||
|
||||
1. **Set production environment variables:**
|
||||
|
||||
```bash
|
||||
export HANAMI_ENV=production
|
||||
export DATABASE_URL=sqlite:///path/to/prod.db
|
||||
export SESSION_SECRET=<secure-random-string>
|
||||
```
|
||||
|
||||
2. **Compile assets for production:**
|
||||
|
||||
```bash
|
||||
./node_modules/.bin/esbuild app/assets/css/app.css --bundle --outfile=public/assets/app-GVDAEYEC.css
|
||||
```
|
||||
|
||||
3. **Run migrations:**
|
||||
|
||||
```bash
|
||||
bundle exec rake db:migrate
|
||||
```
|
||||
|
||||
4. **Start server:**
|
||||
|
||||
```bash
|
||||
bundle exec puma -p 3000 -e production
|
||||
```
|
||||
|
||||
### Using a Process Manager
|
||||
|
||||
**Using systemd:**
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=EuchreCamp
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=deploy
|
||||
WorkingDirectory=/var/www/euchre_camp
|
||||
Environment=HANAMI_ENV=production
|
||||
ExecStart=/usr/local/bin/bundle exec puma -C config/puma.rb
|
||||
Restart=always
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
**Using PM2 (Node.js):**
|
||||
|
||||
```bash
|
||||
pm2 start bundle exec -- puma -C config/puma.rb
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Run tests to ensure they pass
|
||||
5. Submit a pull request
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see LICENSE file for details
|
||||
|
||||
## Credits
|
||||
|
||||
Built with:
|
||||
- Hanami 2.1
|
||||
- ROM (Ruby Object Mapper)
|
||||
- SQLite3
|
||||
- RSpec
|
||||
- Puma
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Hanami Documentation](https://guides.hanamirb.org/)
|
||||
- [ROM Documentation](https://rom-rb.org/)
|
||||
- [RSpec Documentation](https://rspec.info/)
|
||||
- [Euchre Rules](https://www.pagat.com/euchre/euchre.html)
|
||||
+142
@@ -0,0 +1,142 @@
|
||||
# EuchreCamp - Project Todo List
|
||||
|
||||
## Completed Features
|
||||
|
||||
### Backend
|
||||
- [x] Database schema for matches, players, teams, events
|
||||
- [x] Elo rating calculator and job
|
||||
- [x] Partnership tracking and analytics
|
||||
- [x] Tournament generator (round-robin, single elim, double elim, Swiss)
|
||||
- [x] ROM relations and repositories
|
||||
- [x] Acceptance test suite (8 tests passing)
|
||||
|
||||
### Frontend
|
||||
- [x] Basic player rankings page
|
||||
- [x] Match entry form
|
||||
|
||||
## In Progress - UI Development
|
||||
|
||||
### Completed
|
||||
- [x] Navigation layout (app.html.erb)
|
||||
- [x] UI Design document (UI_DESIGN.md)
|
||||
- [x] Player Profile template (existing)
|
||||
- [x] Basic CSS styling
|
||||
- [x] Player Schedule view (action + template)
|
||||
- [x] Route for player schedule
|
||||
|
||||
### View Types to Implement
|
||||
- [ ] Tournament Admin View (Phase 2-3)
|
||||
- Create/manage tournaments
|
||||
- Set up brackets and matchups
|
||||
- Record match results
|
||||
- View tournament standings
|
||||
|
||||
- [ ] Club Admin View (Superuser) (Phase 3-4)
|
||||
- Manage all players
|
||||
- View club-wide statistics
|
||||
- Configure club settings
|
||||
- Manage tournaments
|
||||
|
||||
- [ ] Player Profile View (Phase 1-2)
|
||||
- Display player info and Elo rating
|
||||
- Show partnership analytics
|
||||
- Display match history
|
||||
- Tournament participation
|
||||
- Enhance existing template
|
||||
|
||||
- [ ] Player Tournament Schedule View (Phase 4)
|
||||
- Show upcoming matches
|
||||
- Display tournament brackets
|
||||
- Record personal match results
|
||||
|
||||
### UI Components Needed
|
||||
- [x] Navigation system (role-based) - Started
|
||||
- [ ] Dashboard layouts
|
||||
- [ ] Forms for data entry
|
||||
- [ ] Tables for displaying data
|
||||
- [ ] Charts for statistics
|
||||
- [ ] Bracket visualization
|
||||
|
||||
### Implementation Phases
|
||||
- [x] Phase 1: Navigation & Layout (Week 1)
|
||||
- [x] Phase 2: Player Profile Enhancements (Week 1-2)
|
||||
- [x] Phase 3: Tournament Admin View (Week 2-3)
|
||||
- [x] Phase 4: Club Admin View (Week 3-4)
|
||||
- [x] Phase 5: Player Schedule View (Week 4)
|
||||
- [ ] Phase 6: Authentication & Authorization (Week 5)
|
||||
- [ ] Phase 7: Polish & Testing (Week 6)
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Features
|
||||
- [ ] Real-time match updates
|
||||
- [ ] Mobile-responsive design
|
||||
- [ ] Email notifications
|
||||
- [ ] Import/Export functionality
|
||||
- [ ] API for third-party integrations
|
||||
- [ ] Login/AAA System (Authentication, Authorization, Accounting)
|
||||
|
||||
### Technical
|
||||
- [ ] Performance optimization
|
||||
- [ ] Caching strategy
|
||||
- [ ] Security hardening
|
||||
- [ ] Deployment pipeline
|
||||
|
||||
## AAA System (Authentication, Authorization, Accounting)
|
||||
|
||||
### Authentication
|
||||
- [x] Create users table migration
|
||||
- [x] Create users repository
|
||||
- [x] Create users model/struct
|
||||
- [x] Build login page template
|
||||
- [x] Build login action
|
||||
- [x] Build logout action
|
||||
- [x] Add login/logout routes
|
||||
- [x] Add BCrypt to Gemfile
|
||||
- [x] Install BCrypt
|
||||
- [x] Create authorization service
|
||||
- [x] Add authorization helpers to base action
|
||||
- [x] Add role-based access control
|
||||
- [ ] Create registration action and template
|
||||
- [ ] Add session management middleware
|
||||
- [ ] Add current_user helper to views
|
||||
- [ ] Password reset functionality
|
||||
- [ ] Email confirmation system
|
||||
|
||||
### Authorization
|
||||
- [x] Define roles (player, tournament_admin, club_admin, system_admin)
|
||||
- [x] Create Authorization service
|
||||
- [x] Implement permission checks
|
||||
- [x] Add authorization to admin dashboard
|
||||
- [x] Add authorization to player management
|
||||
- [x] Add authorization to tournament management
|
||||
- [x] Add 5-minute match edit window
|
||||
- [ ] Add role assignment UI
|
||||
- [ ] Add permission checks to all routes
|
||||
|
||||
### Accounting
|
||||
- [ ] Create activity logging system
|
||||
- [ ] Track authentication events
|
||||
- [ ] Track tournament management events
|
||||
- [ ] Track match recording events
|
||||
- [ ] Build audit reports UI
|
||||
|
||||
### Security
|
||||
- [ ] Rate limiting on login attempts
|
||||
- [ ] IP-based lockout (partially implemented in users repo)
|
||||
- [ ] Secure cookie settings
|
||||
- [ ] CSRF protection
|
||||
- [ ] Security headers
|
||||
- [ ] Session fixation prevention
|
||||
|
||||
## Known Issues
|
||||
- [ ] Database IDs not resetting between tests (workaround: query by round_number)
|
||||
- [ ] Need to clean up debug output from acceptance tests
|
||||
- [ ] README is minimal and needs expansion
|
||||
|
||||
## Next Steps
|
||||
1. Design UI mockups for each view type
|
||||
2. Implement navigation system
|
||||
3. Build out Tournament Admin view
|
||||
4. Add role-based access control
|
||||
5. Create reusable UI components
|
||||
@@ -0,0 +1,550 @@
|
||||
# EuchreCamp UI Design
|
||||
|
||||
## Overview
|
||||
Design for four distinct user views with role-based access control:
|
||||
1. Tournament Admin View
|
||||
2. Club Admin View (Superuser)
|
||||
3. Player Profile View
|
||||
4. Player Tournament Schedule View
|
||||
|
||||
## Layout Structure
|
||||
|
||||
### Navigation Bar (All Views)
|
||||
```html
|
||||
<nav class="main-nav">
|
||||
<div class="nav-brand">
|
||||
<a href="/">EuchreCamp</a>
|
||||
</div>
|
||||
<div class="nav-links">
|
||||
<a href="/rankings">Rankings</a>
|
||||
<% if defined?(current_player) && current_player %>
|
||||
<a href="/players/<%= current_player.id %>/profile">My Profile</a>
|
||||
<a href="/players/<%= current_player.id %>/schedule">My Schedule</a>
|
||||
<% if current_player.admin? %>
|
||||
<a href="/admin">Admin</a>
|
||||
<% end %>
|
||||
<% end %>
|
||||
</div>
|
||||
<div class="nav-user">
|
||||
<% if defined?(current_player) && current_player %>
|
||||
<span><%= current_player.name %></span>
|
||||
<a href="/logout">Logout</a>
|
||||
<% else %>
|
||||
<a href="/login">Login</a>
|
||||
<a href="/register">Register</a>
|
||||
<% end %>
|
||||
</div>
|
||||
</nav>
|
||||
```
|
||||
|
||||
## Authentication Views
|
||||
|
||||
### Login Page
|
||||
**URL:** `/login`
|
||||
**Purpose:** Allow existing users to sign in
|
||||
|
||||
#### Layout:
|
||||
```
|
||||
+-------------------------------------------+
|
||||
| EuchreCamp - Login |
|
||||
+-------------------------------------------+
|
||||
| |
|
||||
| [Logo/Brand] |
|
||||
| |
|
||||
| Email: [_______________________] |
|
||||
| Password: [_______________________] |
|
||||
| [ ] Remember me |
|
||||
| |
|
||||
| [Login] |
|
||||
| |
|
||||
| Don't have an account? |
|
||||
| [Register here] |
|
||||
| |
|
||||
| Forgot password? |
|
||||
| [Reset password] |
|
||||
+-------------------------------------------+
|
||||
```
|
||||
|
||||
### Registration Page
|
||||
**URL:** `/register`
|
||||
**Purpose:** Allow new users to create accounts
|
||||
|
||||
#### Layout:
|
||||
```
|
||||
+-------------------------------------------+
|
||||
| EuchreCamp - Create Account |
|
||||
+-------------------------------------------+
|
||||
| |
|
||||
| Join EuchreCamp to track your games |
|
||||
| and partnerships! |
|
||||
| |
|
||||
| Full Name: [_______________________] |
|
||||
| Email: [_______________________] |
|
||||
| Password: [_______________________] |
|
||||
| Confirm: [_______________________] |
|
||||
| |
|
||||
| [Create Account] |
|
||||
| |
|
||||
| Already have an account? |
|
||||
| [Login here] |
|
||||
+-------------------------------------------+
|
||||
```
|
||||
|
||||
### Password Reset Page
|
||||
**URL:** `/password/reset`
|
||||
**Purpose:** Allow users to reset forgotten passwords
|
||||
|
||||
#### Layout:
|
||||
```
|
||||
+-------------------------------------------+
|
||||
| Reset Password |
|
||||
+-------------------------------------------+
|
||||
| |
|
||||
| Enter your email address and we'll |
|
||||
| send you a reset link. |
|
||||
| |
|
||||
| Email: [___________________________] |
|
||||
| |
|
||||
| [Send Reset Link] |
|
||||
| |
|
||||
| Remember your password? |
|
||||
| [Login here] |
|
||||
+-------------------------------------------+
|
||||
```
|
||||
|
||||
### Email Confirmation Page
|
||||
**URL:** `/confirm`
|
||||
**Purpose:** Display confirmation status
|
||||
|
||||
#### Layout:
|
||||
```
|
||||
+-------------------------------------------+
|
||||
| Email Confirmation |
|
||||
+-------------------------------------------+
|
||||
| |
|
||||
| ✓ Email Confirmed! |
|
||||
| Your account is now active. |
|
||||
| |
|
||||
| [Go to Dashboard] |
|
||||
| |
|
||||
| OR |
|
||||
| |
|
||||
| ✗ Confirmation Failed |
|
||||
| The link has expired or is invalid. |
|
||||
| |
|
||||
| [Request new confirmation] |
|
||||
+-------------------------------------------+
|
||||
```
|
||||
|
||||
## 1. Tournament Admin View
|
||||
|
||||
### URL: `/admin/tournaments`
|
||||
|
||||
**Purpose**: Create, manage, and monitor tournaments
|
||||
|
||||
### Components:
|
||||
|
||||
#### Dashboard
|
||||
- **Upcoming Tournaments Table**
|
||||
- Name, Date, Format, Status, Actions (View/Edit/Manage)
|
||||
- Quick action buttons: Schedule, Add Teams, Record Results
|
||||
|
||||
#### Tournament Detail Page
|
||||
- **Tournament Info Header**
|
||||
- Name, Format, Status, Dates
|
||||
- Quick stats: Teams, Rounds, Matches, Participants
|
||||
|
||||
- **Tournament Management Tabs**
|
||||
```
|
||||
Overview | Participants | Teams | Schedule | Results | Analytics
|
||||
```
|
||||
|
||||
- **Overview Tab**
|
||||
- Current standings
|
||||
- Next matches
|
||||
- Tournament progress bar
|
||||
|
||||
- **Participants Tab**
|
||||
- List of registered players
|
||||
- Add/Remove participants
|
||||
- Bulk import from CSV
|
||||
|
||||
- **Teams Tab**
|
||||
- Team management (create/edit/delete teams)
|
||||
- Assign players to teams
|
||||
- Team standings
|
||||
|
||||
- **Schedule Tab**
|
||||
- Generate round-robin schedule
|
||||
- Generate bracket (single/double elim)
|
||||
- View round matchups
|
||||
- Re-schedule matches
|
||||
|
||||
- **Results Tab**
|
||||
- Match result entry form
|
||||
- CSV upload for batch results
|
||||
- Verify and submit results
|
||||
|
||||
- **Analytics Tab**
|
||||
- Tournament statistics
|
||||
- Partnership performance
|
||||
- Elo changes
|
||||
|
||||
### Wireframe Layout:
|
||||
```
|
||||
+-------------------------------------------+
|
||||
| Tournament Admin |
|
||||
| [Create New] [Generate Schedule] |
|
||||
+-------------------------------------------+
|
||||
| Active: Spring Championship (Round 3/5) |
|
||||
| [Overview] [Teams] [Schedule] [Results] |
|
||||
+-------------------------------------------+
|
||||
| Match Schedule - Round 3 |
|
||||
| --------------------------------------- |
|
||||
| Match 1: Team A vs Team B [Enter Result] |
|
||||
| Match 2: Team C vs Team D [Enter Result] |
|
||||
| Match 3: Team E vs Team F [Enter Result] |
|
||||
+-------------------------------------------+
|
||||
```
|
||||
|
||||
## 2. Club Admin View (Superuser)
|
||||
|
||||
### URL: `/admin` or `/admin/club`
|
||||
|
||||
**Purpose**: Club-wide management and oversight
|
||||
|
||||
### Components:
|
||||
|
||||
#### Club Dashboard
|
||||
- **Quick Stats Overview**
|
||||
- Total Players
|
||||
- Active Tournaments
|
||||
- Matches This Week
|
||||
- Average Elo Rating
|
||||
|
||||
- **Recent Activity Feed**
|
||||
- New player registrations
|
||||
- Tournament creations
|
||||
- Match results
|
||||
- Partnership records
|
||||
|
||||
#### Player Management
|
||||
- **Player Directory**
|
||||
- Searchable list of all players
|
||||
- Filter by status, rating range, activity
|
||||
- Bulk actions: Email, Export, Update ratings
|
||||
|
||||
- **Player Editor**
|
||||
- Edit player details
|
||||
- View player history
|
||||
- Manage player status
|
||||
|
||||
#### Tournament Management
|
||||
- **All Tournaments List**
|
||||
- Filter by status, format, date range
|
||||
- Archive/completed tournaments
|
||||
- Clone existing tournaments
|
||||
|
||||
#### Club Settings
|
||||
- **Configuration**
|
||||
- Default tournament settings
|
||||
- Elo rating parameters
|
||||
- Partnership tracking preferences
|
||||
- Notification settings
|
||||
|
||||
#### Analytics & Reports
|
||||
- **Club Statistics**
|
||||
- Rating distribution charts
|
||||
- Activity heatmaps
|
||||
- Partnership network graph
|
||||
- Export reports (PDF/CSV)
|
||||
|
||||
### Wireframe Layout:
|
||||
```
|
||||
+-------------------------------------------+
|
||||
| Club Admin Dashboard |
|
||||
| [Players] [Tournaments] [Reports] [Settings]
|
||||
+-------------------------------------------+
|
||||
| Quick Stats: 45 Players | 3 Tournaments |
|
||||
+-------------------------------------------+
|
||||
| Recent Activity |
|
||||
| - John joined the club |
|
||||
| - Spring Championship started |
|
||||
| - Emma & Alice won match vs Bob & Charlie|
|
||||
+-------------------------------------------+
|
||||
| Player Directory |
|
||||
| [Search] [Filter by Rating] [Export] |
|
||||
| --------------------------------------- |
|
||||
| Rank | Name | Elo | Status |
|
||||
| 1 | Emma | 1200 | Active |
|
||||
| 2 | Alice | 1150 | Active |
|
||||
+-------------------------------------------+
|
||||
```
|
||||
|
||||
## 3. Player Profile View
|
||||
|
||||
### URL: `/players/:id/profile`
|
||||
|
||||
**Purpose**: Display player information and partnership analytics
|
||||
|
||||
### Components:
|
||||
|
||||
#### Profile Header
|
||||
- Player name and avatar
|
||||
- Current Elo rating (with trend indicator)
|
||||
- Club affiliation
|
||||
- Member since date
|
||||
|
||||
#### Statistics Grid
|
||||
```
|
||||
+------------------+------------------+------------------+
|
||||
| Current Elo | Total Games | Win Rate |
|
||||
| 1,200 | 45 | 58.2% |
|
||||
+------------------+------------------+------------------+
|
||||
| Partnership Elo | Best Partnership | Games with Best |
|
||||
| +150 | Alice (65%) | 12 games |
|
||||
+------------------+------------------+------------------+
|
||||
```
|
||||
|
||||
#### Partnership Performance Table
|
||||
- Partner name (clickable link)
|
||||
- Games played together
|
||||
- Win rate with confidence indicator
|
||||
- Total Elo change
|
||||
- Average Elo change per match
|
||||
- Last played together
|
||||
|
||||
#### Recent Games Timeline
|
||||
- Chronological list of recent matches
|
||||
- Shows teams, scores, and result
|
||||
- Partner information for each game
|
||||
|
||||
#### Tournament History
|
||||
- List of tournaments participated in
|
||||
- Final standings
|
||||
- Performance summary
|
||||
|
||||
### Wireframe Layout:
|
||||
```
|
||||
+-------------------------------------------+
|
||||
| Player Profile: Emma |
|
||||
| ELO: 1200 (+25 this week) |
|
||||
+-------------------------------------------+
|
||||
| Partnership Performance |
|
||||
| --------------------------------------- |
|
||||
| Partner Games Win Rate ELO Change |
|
||||
| Alice 12 65% +45 |
|
||||
| Bob 8 50% -20 |
|
||||
| Charlie 5 60% +30 |
|
||||
+-------------------------------------------+
|
||||
| Recent Games |
|
||||
| --------------------------------------- |
|
||||
| 2024-03-27 Win vs Bob+Charlie 10-7 |
|
||||
| Partner: Alice |
|
||||
+-------------------------------------------+
|
||||
```
|
||||
|
||||
## 4. Player Tournament Schedule View
|
||||
|
||||
### URL: `/players/:id/schedule`
|
||||
|
||||
**Purpose**: View upcoming matches and tournament brackets
|
||||
|
||||
### Components:
|
||||
|
||||
#### Upcoming Matches
|
||||
- **This Week**
|
||||
- Match date/time
|
||||
- Opponent team
|
||||
- Tournament name
|
||||
- Location/notes
|
||||
- Action: Record Result (if applicable)
|
||||
|
||||
- **Next 30 Days**
|
||||
- Calendar view of upcoming matches
|
||||
- Grouped by tournament
|
||||
|
||||
#### Active Tournaments
|
||||
- **My Tournaments List**
|
||||
- Tournament name and status
|
||||
- Current round
|
||||
- My team's position
|
||||
- Next match details
|
||||
|
||||
- **Tournament Bracket View**
|
||||
- Visual bracket display
|
||||
- My team highlighted
|
||||
- Progress tracking
|
||||
|
||||
#### Match History
|
||||
- **Past Matches**
|
||||
- Results from previous tournaments
|
||||
- Performance trends
|
||||
|
||||
### Wireframe Layout:
|
||||
```
|
||||
+-------------------------------------------+
|
||||
| Emma's Schedule |
|
||||
+-------------------------------------------+
|
||||
| This Week |
|
||||
| --------------------------------------- |
|
||||
| Mar 28 Spring Championship |
|
||||
| vs Team B (Bob + Charlie) |
|
||||
| Court 3, 7:00 PM |
|
||||
| [Record Result] |
|
||||
+-------------------------------------------+
|
||||
| Upcoming Matches |
|
||||
| [Calendar View] [List View] |
|
||||
| --------------------------------------- |
|
||||
| Apr 1 Tournament X - Round 2 |
|
||||
| Apr 5 Tournament Y - Quarterfinal |
|
||||
| Apr 8 Tournament X - Round 3 |
|
||||
+-------------------------------------------+
|
||||
| Active Tournaments |
|
||||
| --------------------------------------- |
|
||||
| Spring Championship |
|
||||
| Round 3 of 5 | Position: 2nd |
|
||||
| Next: vs Team C (Apr 1) |
|
||||
+-------------------------------------------+
|
||||
```
|
||||
|
||||
## Role-Based Access Control
|
||||
|
||||
### Player Role (Default)
|
||||
- View own profile and schedule
|
||||
- View rankings and other player profiles
|
||||
- Record own match results (with verification)
|
||||
|
||||
### Tournament Admin Role
|
||||
- All Player role permissions
|
||||
- Create and manage tournaments they admin
|
||||
- Add/remove participants
|
||||
- Record match results
|
||||
- View tournament analytics
|
||||
|
||||
### Club Admin Role (Superuser)
|
||||
- All Tournament Admin permissions
|
||||
- Manage all players
|
||||
- Manage all tournaments
|
||||
- View club-wide analytics
|
||||
- Configure club settings
|
||||
- Export reports
|
||||
|
||||
## UI Components to Build
|
||||
|
||||
### 1. Navigation
|
||||
- Main navigation bar
|
||||
- Breadcrumb navigation
|
||||
- Tab navigation for multi-view pages
|
||||
|
||||
### 2. Data Display
|
||||
- Data tables with sorting/filtering
|
||||
- Statistics cards
|
||||
- Charts (using Chart.js or similar)
|
||||
- Calendar views
|
||||
|
||||
### 3. Forms
|
||||
- Player registration/edit forms
|
||||
- Tournament creation/edit forms
|
||||
- Match result entry forms
|
||||
- CSV upload forms
|
||||
|
||||
### 4. Interactive Elements
|
||||
- Modal dialogs for quick actions
|
||||
- Dropdown menus
|
||||
- Search/filter controls
|
||||
- Pagination controls
|
||||
|
||||
### 5. Visual Elements
|
||||
- Elo rating indicators (with trends)
|
||||
- Win/loss badges
|
||||
- Partnership confidence indicators
|
||||
- Tournament bracket visualization
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 0: Authentication (Week 0)
|
||||
- [ ] Create login page
|
||||
- [ ] Create registration page
|
||||
- [ ] Implement session management
|
||||
- [ ] Add navigation for logged-in users
|
||||
- [ ] Protect admin routes
|
||||
|
||||
### Phase 1: Navigation & Layout (Week 1)
|
||||
- [ ] Add navigation bar to all templates
|
||||
- [ ] Implement role-based navigation links
|
||||
- [ ] Create consistent layout structure
|
||||
|
||||
### Phase 2: Player Profile Enhancements (Week 1-2)
|
||||
- [ ] Improve profile header with stats grid
|
||||
- [ ] Enhance partnership table with confidence indicators
|
||||
- [ ] Add recent games timeline
|
||||
|
||||
### Phase 3: Tournament Admin View (Week 2-3)
|
||||
- [ ] Build tournament dashboard
|
||||
- [ ] Implement management tabs
|
||||
- [ ] Add match result entry forms
|
||||
|
||||
### Phase 4: Club Admin View (Week 3-4)
|
||||
- [ ] Create superuser dashboard
|
||||
- [ ] Build player directory with search
|
||||
- [ ] Add club settings page
|
||||
|
||||
### Phase 5: Player Schedule View (Week 4)
|
||||
- [ ] Build upcoming matches view
|
||||
- [ ] Implement calendar integration
|
||||
- [ ] Add bracket visualization
|
||||
|
||||
### Phase 6: Polish & Testing (Week 5)
|
||||
- [ ] Mobile responsiveness
|
||||
- [ ] Accessibility improvements
|
||||
- [ ] Cross-browser testing
|
||||
- [ ] User feedback incorporation
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
### Hanami View Structure
|
||||
```
|
||||
app/
|
||||
actions/
|
||||
players/
|
||||
profile.rb
|
||||
schedule.rb
|
||||
admin/
|
||||
tournaments/
|
||||
index.rb
|
||||
show.rb
|
||||
club/
|
||||
dashboard.rb
|
||||
templates/
|
||||
layouts/
|
||||
app.html.erb
|
||||
admin.html.erb
|
||||
players/
|
||||
profile.html.erb
|
||||
schedule.html.erb
|
||||
admin/
|
||||
tournaments/
|
||||
index.html.erb
|
||||
show.html.erb
|
||||
club/
|
||||
dashboard.html.erb
|
||||
```
|
||||
|
||||
### CSS Architecture
|
||||
- Use Tailwind CSS or custom CSS
|
||||
- Consistent color scheme (green for wins, red for losses)
|
||||
- Responsive breakpoints for mobile
|
||||
- Accessibility: color contrast, focus states
|
||||
|
||||
### JavaScript Interactions
|
||||
- Calendar navigation
|
||||
- Modal dialogs
|
||||
- Form validation
|
||||
- Real-time updates (optional)
|
||||
|
||||
## Success Metrics
|
||||
- User satisfaction with navigation
|
||||
- Time to complete common tasks
|
||||
- Mobile usage statistics
|
||||
- Accessibility compliance score
|
||||
@@ -0,0 +1,221 @@
|
||||
# EuchreCamp User Stories
|
||||
|
||||
## Epic 1: Authentication & User Management
|
||||
|
||||
### As a new user, I want to register for an account so that I can participate in tournaments and track my games
|
||||
- Acceptance Criteria:
|
||||
- Registration form with name, email, password, password confirmation
|
||||
- Email validation and uniqueness check
|
||||
- Password strength requirements (8+ chars, uppercase, lowercase, number, special char)
|
||||
- Account confirmation via email
|
||||
- Auto-create player profile upon registration
|
||||
|
||||
### As a registered user, I want to log in to my account so that I can access my data
|
||||
- Acceptance Criteria:
|
||||
- Login form with email and password
|
||||
- Session management with secure cookies
|
||||
- "Remember me" functionality
|
||||
- Error handling for invalid credentials
|
||||
- Account lockout after 5 failed attempts
|
||||
|
||||
### As a logged-in user, I want to log out so that I can secure my account
|
||||
- Acceptance Criteria:
|
||||
- Logout button in navigation
|
||||
- Session cleared on logout
|
||||
- Redirect to home page
|
||||
|
||||
### As a user who forgot my password, I want to reset it so that I can regain access
|
||||
- Acceptance Criteria:
|
||||
- "Forgot password" link on login page
|
||||
- Email input for reset request
|
||||
- Unique token generation (expires in 1 hour)
|
||||
- Email with reset link
|
||||
- Password update form with validation
|
||||
|
||||
## Epic 2: Player Profile & Analytics
|
||||
|
||||
### As a player, I want to view my profile so that I can see my statistics
|
||||
- Acceptance Criteria:
|
||||
- Profile header with name and avatar
|
||||
- Current Elo rating with trend indicator
|
||||
- Total games played
|
||||
- Win rate percentage
|
||||
- Member since date
|
||||
|
||||
### As a player, I want to see my partnership performance so that I can identify my best partners
|
||||
- Acceptance Criteria:
|
||||
- Table showing all partners
|
||||
- Games played with each partner
|
||||
- Win rate with each partner
|
||||
- Total Elo change per partnership
|
||||
- Last played together date
|
||||
|
||||
### As a player, I want to see my recent games so that I can track my performance
|
||||
- Acceptance Criteria:
|
||||
- Timeline of recent matches
|
||||
- Date, opponents, scores, and results
|
||||
- Partner information for each game
|
||||
- Pagination for loading more games
|
||||
|
||||
### As a player, I want to see my tournament history so that I can review past performances
|
||||
- Acceptance Criteria:
|
||||
- List of tournaments participated in
|
||||
- Final standings in each tournament
|
||||
- Performance summary per tournament
|
||||
|
||||
## Epic 3: Rankings & Public Data
|
||||
|
||||
### As a visitor, I want to view player rankings so that I can see top players
|
||||
- Acceptance Criteria:
|
||||
- Sortable rankings table
|
||||
- Columns: Rank, Name, Elo, Win Rate, Games Played
|
||||
- Search/filter functionality
|
||||
- Pagination
|
||||
|
||||
### As a visitor, I want to view player profiles so that I can learn about other players
|
||||
- Acceptance Criteria:
|
||||
- Public profile pages (read-only for non-admins)
|
||||
- Basic stats: Elo, games played, win rate
|
||||
- Partnership performance (if public)
|
||||
- Recent games (limited)
|
||||
|
||||
## Epic 4: Tournament Management
|
||||
|
||||
### As a tournament admin, I want to create a new tournament so that I can organize events
|
||||
- Acceptance Criteria:
|
||||
- Tournament creation form
|
||||
- Fields: Name, Format (round-robin, single elim, double elim, Swiss), Date, Status
|
||||
- Default settings for each format
|
||||
- Validation for required fields
|
||||
|
||||
### As a tournament admin, I want to manage tournament participants so that I can control who plays
|
||||
- Acceptance Criteria:
|
||||
- Add participants from player list
|
||||
- Remove participants
|
||||
- Bulk import from CSV
|
||||
- View participant list with status
|
||||
|
||||
### As a tournament admin, I want to create teams so that I can organize players into pairs
|
||||
- Acceptance Criteria:
|
||||
- Team creation form
|
||||
- Select two players per team
|
||||
- Auto-generate team names
|
||||
- Edit/delete teams
|
||||
|
||||
### As a tournament admin, I want to generate a schedule so that matches are organized
|
||||
- Acceptance Criteria:
|
||||
- Round-robin schedule generation
|
||||
- Single/double elimination bracket generation
|
||||
- View schedule by round
|
||||
- Re-schedule matches if needed
|
||||
|
||||
### As a tournament admin, I want to record match results so that I can track tournament progress
|
||||
- Acceptance Criteria:
|
||||
- Match result entry form
|
||||
- Select teams and enter scores
|
||||
- Auto-determine winner from scores
|
||||
- Validation for score formats
|
||||
|
||||
### As a tournament admin, I want to upload results via CSV so that I can batch process matches
|
||||
- Acceptance Criteria:
|
||||
- CSV upload form with tournament selection
|
||||
- Parse CSV with specific format (Event, Round, Table, Seats, Scores, Winner)
|
||||
- Validate player names exist in system
|
||||
- Create teams automatically if needed
|
||||
- Import matches and update Elo ratings
|
||||
|
||||
### As a tournament admin, I want to view tournament analytics so that I can assess performance
|
||||
- Acceptance Criteria:
|
||||
- Tournament statistics (total matches, average score, etc.)
|
||||
- Partnership performance within tournament
|
||||
- Elo changes for participants
|
||||
- Visual charts for key metrics
|
||||
|
||||
## Epic 5: Match Recording & CSV Import
|
||||
|
||||
### As a user, I want to record a match result so that I can track my games
|
||||
- Acceptance Criteria:
|
||||
- Match creation form
|
||||
- Select Team 1 and Team 2 (each with 2 players)
|
||||
- Enter scores for each team
|
||||
- Auto-calculate winner
|
||||
- Update Elo ratings for all players
|
||||
- Update partnership statistics
|
||||
|
||||
### As a user, I want to upload match results via CSV so that I can process multiple matches at once
|
||||
- Acceptance Criteria:
|
||||
- CSV upload form
|
||||
- Support for Euchre format (Event, Round, Table, Seat 1-4, Odds/Evens Points, Winner)
|
||||
- Map table names (Clubs, Hearts, Diamonds, Spades, Stars) to numeric IDs
|
||||
- Handle player name variations
|
||||
- Create teams automatically
|
||||
- Import matches and calculate Elo
|
||||
- Show import summary with success/error count
|
||||
|
||||
### As a user, I want to edit match results so that I can correct mistakes
|
||||
- Acceptance Criteria:
|
||||
- Edit form for existing matches
|
||||
- Validation for time limits (5 minutes for players, unlimited for admins)
|
||||
- Update Elo ratings on change
|
||||
- Log changes in activity feed
|
||||
|
||||
## Epic 6: Club Administration
|
||||
|
||||
### As a club admin, I want to manage all players so that I can maintain the player database
|
||||
- Acceptance Criteria:
|
||||
- Player directory with search and filter
|
||||
- Create, edit, delete players
|
||||
- Bulk actions (export, update ratings)
|
||||
- View player activity
|
||||
|
||||
### As a club admin, I want to manage all tournaments so that I can oversee club events
|
||||
- Acceptance Criteria:
|
||||
- Tournament list with filters
|
||||
- Clone existing tournaments
|
||||
- Archive completed tournaments
|
||||
- View tournament analytics
|
||||
|
||||
### As a club admin, I want to configure club settings so that I can customize the system
|
||||
- Acceptance Criteria:
|
||||
- Elo rating parameters
|
||||
- Partnership tracking preferences
|
||||
- Notification settings
|
||||
- Default tournament settings
|
||||
|
||||
### As a club admin, I want to view club analytics so that I can assess overall performance
|
||||
- Acceptance Criteria:
|
||||
- Rating distribution charts
|
||||
- Activity heatmaps
|
||||
- Partnership network graph
|
||||
- Export reports (PDF/CSV)
|
||||
|
||||
## Epic 7: Mobile Responsiveness
|
||||
|
||||
### As a mobile user, I want to navigate the site so that I can access features on my phone
|
||||
- Acceptance Criteria:
|
||||
- Responsive navigation bar
|
||||
- Bottom navigation for mobile
|
||||
- Touch-friendly buttons and links
|
||||
- Optimized layouts for small screens
|
||||
|
||||
### As a mobile user, I want to record match results so that I can log games on the go
|
||||
- Acceptance Criteria:
|
||||
- Mobile-optimized forms
|
||||
- Quick entry for common actions
|
||||
- Offline support (optional)
|
||||
|
||||
## Epic 8: Data Management & Export
|
||||
|
||||
### As a club admin, I want to export data so that I can backup or analyze externally
|
||||
- Acceptance Criteria:
|
||||
- Export players to CSV
|
||||
- Export tournaments to CSV
|
||||
- Export matches to CSV
|
||||
- Export partnership data to CSV
|
||||
|
||||
### As a club admin, I want to import data so that I can migrate from other systems
|
||||
- Acceptance Criteria:
|
||||
- Import players from CSV
|
||||
- Import tournaments from CSV
|
||||
- Import matches from CSV
|
||||
- Data validation and error reporting
|
||||
Reference in New Issue
Block a user