255 lines
11 KiB
Markdown
255 lines
11 KiB
Markdown
# DAD Project - Bisca Game Platform
|
||
|
||
## Overview
|
||
|
||
The DAD project aims to develop and deploy the **Bisca Game Platform** as a web application. The platform is a distributed system that provides users with the ability to play the traditional Portuguese card game Bisca in single-player and multiplayer modes, manage their coins, and track their gaming statistics.
|
||
|
||
The web client is implemented as a **Single-Page Application (SPA)** built with **Vue.js** and hosted on the designated internal school server. The backend system includes a database, a RESTful API server, and a WebSocket server for real-time multiplayer gameplay.
|
||
|
||
## Project Architecture
|
||
|
||
### Frontend
|
||
- **Technology**: Vue.js SPA
|
||
- **Purpose**: User interface for game play, user management, coin transactions, and statistics visualization
|
||
- **Features**: Real-time game updates via WebSockets, responsive design, player profiles, leaderboards
|
||
|
||
### Backend
|
||
- **RESTful API Server**: Handles user authentication, coin transactions, game history, leaderboards, and administrative operations
|
||
- **WebSocket Server**: Manages real-time multiplayer game communication, ensuring the server acts as the authoritative source for game state
|
||
- **Database**: Persists user data, game results, transactions, and platform statistics
|
||
|
||
## Constraints
|
||
|
||
The project must adhere to the following mandatory constraints:
|
||
|
||
1. **Single-Page Application (SPA)** - The application must be implemented exclusively as an SPA
|
||
2. **Vue.js Requirement** - The client application must be built with Vue.js
|
||
3. **Payment Gateway Integration** - All external coin purchases must be processed via the provided RESTful API (Payment Gateway Service)
|
||
4. **Deployment** - The application must be deployed on the designated internal school server and be accessible via a desktop web browser
|
||
5. **Backend Technologies** - Must be open-source or available as free external services
|
||
6. **Server Compatibility** - Backend technologies must be installable on or accessible from the designated server; if not supported, compliant alternatives must be selected
|
||
7. **Database Seeding** - The deployed application's database must be seeded with realistic data in both scale and content to simulate typical usage patterns
|
||
|
||
## Core Features
|
||
|
||
### 1. User Management
|
||
- **Registration**: Users register with email, nickname, name, password (minimum 3 characters), and optional photo/avatar
|
||
- **Authentication**: Email and password-based login
|
||
- **Profile Management**: View and update profile information, change password
|
||
- **Sign Out**: Users can end their session
|
||
- **Account Deletion**: Requires explicit confirmation; permanently forfeits all coins
|
||
- **Welcome Bonus**: New users receive 10 coins upon registration
|
||
- **Admin Accounts**: Created only by existing administrators; same profile capabilities as users but cannot delete their own accounts
|
||
|
||
### 2. Coins and Transactions
|
||
- **Coin Balance**: Users can view their current coin balance
|
||
- **Coin Purchases**: External purchases via Payment Gateway Service
|
||
- **Conversion Rate**: €1 = 10 coins (purchases in €1 increments)
|
||
- **Coin Earning**: Players earn coins through gameplay and bonuses
|
||
- **Transaction History**: All coin-related transactions (bonuses, purchases, spending, earnings) are logged
|
||
- **History Access**:
|
||
- Players view only their own transaction history
|
||
- Administrators have read-only access to all players' histories
|
||
- Administrators cannot create, modify, or delete transactions
|
||
|
||
### 3. Games and Matches
|
||
|
||
#### Game Variants
|
||
- **Bisca de 3**: Three-card hands
|
||
- **Bisca de 9**: Nine-card hands
|
||
|
||
#### Game Modes
|
||
- **Single-Player**: Against a bot (available to anonymous and registered users)
|
||
- **Multiplayer**: Against human opponents (available only to registered users)
|
||
- **Match**: Best-of series (up to 4 marks/wins) with two players
|
||
|
||
#### Game Rules
|
||
- Games and matches are limited to two players
|
||
- The bot follows game rules and attempts to win when playing second; otherwise plays its lowest-value card
|
||
- Official Bisca rules apply (as defined in the "Bisca Game" documentation)
|
||
|
||
#### Multiplayer Gameplay
|
||
- **Real-Time Communication**: WebSockets for live game updates
|
||
- **Server Authority**: The server is the source of truth for:
|
||
- Card dealing
|
||
- Turn order
|
||
- Valid moves
|
||
- Trick resolution
|
||
- Drawing from stock
|
||
- Scoring
|
||
- End-of-game/match conditions
|
||
- **Move Timer**: 20-second limit per move
|
||
- **Resignation**:
|
||
- Opponent awarded all remaining cards
|
||
- Game ends immediately
|
||
- If in a match, player forfeits all remaining games
|
||
- Scores computed accordingly
|
||
- **Persistent Results**: Game and match results with metadata are persisted for user history and administrative access
|
||
|
||
### 4. Game History and Leaderboards
|
||
|
||
#### Tracking
|
||
- **Scope**: Only multiplayer games and matches are tracked
|
||
- **Metadata**: Start/end timestamps, variant, outcome (win/loss/draw/forfeit), final points, marks (capote, bandeira), duration
|
||
|
||
#### History Access
|
||
- **Players**: View only their own multiplayer history
|
||
- **Administrators**: Read-only access to all players' histories and detailed records
|
||
- **Detailed Records**: Visible only to administrators and participating players
|
||
|
||
#### Leaderboards
|
||
- **Personal Leaderboards**: Visible only to the owner; summarize totals for game wins, match wins, capotes, and bandeiras (optionally segmented by variant)
|
||
- **Global Leaderboards**: Visible to all users including anonymous visitors; highlight top players by game and match wins, may include capotes and bandeiras
|
||
- **Tie-Breaking**: Earlier achievers rank higher in case of ties
|
||
|
||
### 5. Administration
|
||
|
||
#### Administrator Capabilities
|
||
- **Profile Management**: Same as regular users, except cannot delete their own accounts
|
||
- **Account Management**: Create new administrator accounts, remove any account except their own
|
||
- **Soft Deletion**: Player accounts with prior activity must be soft-deleted
|
||
- **User Monitoring**: View all users (players and administrators), block/unblock players
|
||
- **Read-Only Access**:
|
||
- All transactions
|
||
- All multiplayer games and matches
|
||
- Platform usage summaries and statistics
|
||
|
||
#### Administrator Access Control
|
||
- Cannot play games or hold coins
|
||
- New administrator accounts can only be created by existing administrators
|
||
|
||
### 6. Statistics and Reporting
|
||
|
||
#### Anonymous Users and Players
|
||
- Access only generic, anonymized aggregates:
|
||
- Total registered players
|
||
- Games and matches played
|
||
- Recent activity summaries
|
||
|
||
#### Administrators
|
||
- Full, non-anonymized access including:
|
||
- Purchases by period and player
|
||
- Game/match volumes
|
||
- User activity breakdowns
|
||
- Time-series data
|
||
|
||
#### Visualization
|
||
- Statistics available in both visual (charts) and textual/tabular forms
|
||
- Privacy for non-admin viewers is preserved
|
||
- Exact metrics and visualizations are team-defined
|
||
|
||
## Enhancement and Innovation Opportunities
|
||
|
||
To distinguish this project, consider implementing one or more of the following:
|
||
|
||
### Custom Features (Examples)
|
||
- Support for three or more players per game (optional extension while preserving two-player mode)
|
||
- Spectator mode for multiplayer games and matches
|
||
- Full playback of past games
|
||
- Custom card sets
|
||
- Extended bot capabilities (e.g., improved AI strategies)
|
||
- Integration of bots into multiplayer games
|
||
|
||
### Architecture and Performance Enhancements (Examples)
|
||
- Queue server or worker for asynchronous, long-running operations
|
||
- Horizontal scaling of the WebSocket server
|
||
- Session recovery after WebSocket or node failures
|
||
- Cache server implementation
|
||
- NoSQL database for specific use cases
|
||
- Search engine for game history or statistics
|
||
- Asynchronous messaging broker (e.g., Kafka, RabbitMQ)
|
||
- Distributed components for improved scalability and resilience
|
||
|
||
### Implementation Quality
|
||
- Use of technologies or techniques not covered in standard coursework
|
||
- Performance optimization with empirical benchmarks
|
||
- Improved architecture and code structure
|
||
- Enhanced implementation quality and documentation
|
||
|
||
**Note**: Credit is proportional to demonstrated impact with preference given to distributed capabilities that improve architecture, scalability, or resilience.
|
||
|
||
## Technology Stack
|
||
|
||
### Frontend
|
||
- Vue.js (mandatory)
|
||
- Vite (build tool)
|
||
- ESLint (code quality)
|
||
|
||
### Backend
|
||
- **API Server**: Open-source, student-selected technology
|
||
- **WebSocket Server**: Open-source, student-selected technology
|
||
- **Database**: Open-source, student-selected technology
|
||
- All must be compatible with the designated school server
|
||
|
||
### Supported Variants
|
||
- Laravel (PHP) for REST API
|
||
- Node.js for WebSocket server
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
DADProject/
|
||
├── api/ # Laravel REST API backend
|
||
├── frontend/ # Vue.js SPA
|
||
├── websockets/ # WebSocket server
|
||
└── README.md # This file
|
||
```
|
||
|
||
## Getting Started
|
||
|
||
Refer to the individual `README.md` files in each directory for setup and deployment instructions:
|
||
|
||
- [API Documentation](./api/README.md)
|
||
- [Frontend Documentation](./frontend/README.md)
|
||
- [WebSocket Server Documentation](./websockets/README.md)
|
||
|
||
## Database Schema
|
||
|
||
The application's database includes the following primary entities:
|
||
|
||
- **Users**: Player and administrator accounts
|
||
- **Games**: Individual game records (both single-player and multiplayer)
|
||
- **Matches**: Match records (series of games)
|
||
- **Coin Transactions**: Purchase and spending history
|
||
- **Coin Transaction Types**: Transaction categorization
|
||
- **Coin Purchases**: External purchase records
|
||
- **Leaderboard Data**: Aggregated player statistics
|
||
|
||
For detailed schema information, refer to the database migrations in the `api/database/migrations/` directory.
|
||
|
||
## Key Business Rules
|
||
|
||
1. **Coin System**:
|
||
- New users receive 10 welcome coins
|
||
- Conversion rate: €1 = 10 coins
|
||
- Coin purchases are made in €1 increments
|
||
- All transactions are logged and immutable (except soft-deleted accounts)
|
||
|
||
2. **Game Rules**:
|
||
- Two-player games only (in standard mode)
|
||
- Bot cannot be played in multiplayer
|
||
- 20-second move timer in multiplayer
|
||
- Resignation forfeits remaining games in a match
|
||
|
||
3. **Account Management**:
|
||
- Administrators cannot be created via public registration
|
||
- Administrators cannot delete their own accounts
|
||
- Account deletion requires explicit confirmation
|
||
- Soft deletion preserves historical data for deleted player accounts
|
||
|
||
4. **Leaderboard Ranking**:
|
||
- Multiplayer games and matches only
|
||
- Ties resolved by earlier achievement date
|
||
|
||
## Notes for Developers
|
||
|
||
- The WebSocket server acts as the authoritative source for all game state in multiplayer games
|
||
- Ensure proper error handling and recovery for WebSocket disconnections
|
||
- All coin transactions must be atomic and immutable
|
||
- Database must be seeded with realistic, varied data
|
||
- Privacy and data protection must be maintained throughout
|
||
|
||
## License
|
||
|
||
This project is part of the EI – DAD 2025/26 course.
|