SyntaxSquad/DADProject
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 3 Releases Wiki Activity

Added database structure and components

Browse Source
This commit is contained in:
KZix
2025-11-13 21:27:45 +00:00
parent 3f1c69c15b
commit 98a2ca4611
182 changed files with 3847 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+253 -1
View File
@@ -1,2 +1,254 @@
# DADProject
# 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.