Game Account Shop - MVP

A beginner-friendly game account marketplace built with Spring Boot 3.5.0 and Java 17. Sellers can list game accounts, buyers can browse and purchase, and admins manage the platform.

🎯 Project Overview

Game Account Shop is a Vietnamese marketplace platform where:

• Sellers list game accounts (Liên Minh Huyền Thoại, Valorant, etc.)
• Buyers browse listings, search/filter, and purchase via PayOS payment gateway
• Admins approve listings, verify payments, and deliver credentials via email

Target Audience: Newbie developers learning Spring Boot

Technology Stack:

• Backend: Java 17, Spring Boot 3.5.0, Spring Data JPA, Spring Security, MySQL 8.0
• Frontend: Thymeleaf, Bootstrap 5.3, HTML5/CSS3/JavaScript
• Database: MySQL 8.0 with Flyway migrations
• Build: Maven 3.x

---

📋 Prerequisites

Before running this project, ensure you have:

Tool	Version	Command to Check
Java JDK	17+	java -version
Maven	3.8+	mvn -version
MySQL	8.0+	mysql --version
Git	Latest	git --version

---

🚀 Quick Start

1. Clone the Repository

git clone <repository-url>
cd fcode-challenge-3

2. Database Setup

This section guides you through setting up MySQL 8.0 for the Game Account Shop project.

Step 2.1: Verify MySQL is Installed

Check if MySQL is installed:

# Windows
mysql --version

# Linux/Mac
mysql --version

Expected output:

mysql  Ver 8.0.xx for Win64 on x86_64

If MySQL is NOT installed:

Windows:

1. Go to https://dev.mysql.com/downloads/mysql/
2. Download "MySQL Community Server" 8.0
3. Run the installer
4. Use default settings (or set root password to something you'll remember)
5. Finish installation

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install mysql-server
sudo systemctl start mysql
sudo systemctl enable mysql

Mac (using Homebrew):

brew install mysql
brew services start mysql

---

Step 2.2: Start MySQL Server

Windows:

• Open "Services" (press Win + R, type services.msc)
• Find "MySQL80" or "MySQL"
• Right-click → "Start"

Or using command line:

net start MySQL80

Linux:

sudo systemctl start mysql

Mac:

brew services start mysql

---

Step 2.3: Create the Database

Option A: Let the application create it automatically (Easiest)

The application is configured to create the database automatically if it doesn't exist. You don't need to do anything!

Option B: Create manually using MySQL Command Line

1. Open MySQL Command Line:

Windows:

• Open Command Prompt
• Type: mysql -u root -p
• Enter your MySQL root password (press Enter if no password set)

Linux/Mac:

mysql -u root -p

2. Create the database:

CREATE DATABASE gameaccountshop
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

3. Verify database was created:

SHOW DATABASES;

You should see gameaccountshop in the list.

4. Exit MySQL:

EXIT;

---

Step 2.4: Verify Database Connection (Optional)

Test that you can connect to the database:

mysql -u root -p gameaccountshop

If successful, you'll see:

Server version: 8.0.xx MySQL Community Server
...
mysql>

Type EXIT; to leave.

---

Step 2.5: Configure Database Credentials

The application uses these default credentials (already configured):

# In: game-account-shop/src/main/resources/application.yml
spring:
  datasource:
    username: root
    password: password

If your MySQL root password is different:

1. Open game-account-shop/src/main/resources/application.yml in a text editor
2. Find the datasource section
3. Change password: password to password: YOUR_MYSQL_PASSWORD

Example:

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/gameaccountshop
    username: root
    password: MySecretPassword123  # Change this!

---

Step 2.6: Common MySQL Issues for Newbies

Issue: "Access denied for user 'root'@'localhost'"

Solution: Reset MySQL root password

Windows:

1. Stop MySQL service
2. Create a text file with: ALTER USER 'root'@'localhost' IDENTIFIED BY 'NewPassword123';
3. Save as reset.sql
4. Run: mysqld --init-file=C:\\path\\to\\reset.sql
5. Start MySQL service

Linux:

sudo mysql
ALTER USER 'root'@'localhost' IDENTIFIED BY 'NewPassword123';
FLUSH PRIVILEGES;
EXIT;

**Issue: "Can't connect to MySQL server on 'localhost'"

Solution: MySQL server is not running

Windows:

net start MySQL80

Linux:

sudo systemctl start mysql

**Issue: "Unknown database 'gameaccountshop'"

Solution: Database doesn't exist yet. The app will create it automatically, or you can create manually (see Step 2.3).

---

Step 2.7: Flyway Database Migrations (Automatic)

This project uses Flyway to manage database schema automatically.

What happens on first run:

1. Application starts
2. Flyway checks if migrations table exists
3. If not, it creates flyway_schema_history table
4. Runs migration script: V1__Create_Database_Tables.sql
5. Creates 4 tables: users, game_accounts, transactions, reviews

You don't need to manually create tables! Flyway handles everything.

View migration script:

# Location: game-account-shop/src/main/resources/db/migration/
cat V1__Create_Database_Tables.sql

---

Step 2.8: Verify Database is Ready

After first application run, verify tables were created:

mysql -u root -p gameaccountshop

SHOW TABLES;

Expected output:

+---------------------------+
| Tables_in_gameaccountshop |
+---------------------------+
| flyway_schema_history      |
| game_accounts             |
| reviews                    |
| transactions               |
| users                      |
+---------------------------+

Check default admin user was created:

SELECT id, username, role FROM users;

Expected output:

+----+----------+--------+
| id | username | role   |
+----+----------+--------+
|  1 | admin    | ADMIN  |
+----+----------+--------+

---

Summary:

1. ✅ Install MySQL 8.0 (if not installed)
2. ✅ Start MySQL server
3. ✅ Database will be created automatically (optional manual creation)
4. ✅ Configure password in application.yml if different from password
5. ✅ Flyway will create tables automatically on first run
6. ✅ Default admin account created automatically

3. Configure Application Settings

Step 3.1: Copy the example configuration file

# Navigate to the resources directory
cd game-account-shop/src/main/resources

# Copy the example configuration
cp application.yml.example application.yml

Step 3.2: Edit application.yml with your settings

Open game-account-shop/src/main/resources/application.yml in a text editor and configure:

spring:
  datasource:
    username: root
    password: YOUR_MYSQL_PASSWORD  # Change to your MySQL root password

# Email configuration (required for listing approval notifications)
  mail:
    username: your-email@gmail.com  # CHANGE THIS: Your Gmail address
    password: xxxx xxxx xxxx xxxx   # CHANGE THIS: Your 16-character App Password

# ImgBB Image Upload API (optional - for image upload feature)
imgbb:
  api-key: YOUR_IMGBB_API_KEY  # Get free key from https://api.imgbb.com/

# PayOS Payment Configuration (required - for payment processing)
payos:
  client-id: YOUR_PAYOS_CLIENT_ID      # Your PayOS Client ID from my.payos.vn
  api-key: YOUR_PAYOS_API_KEY          # Your PayOS API Key
  checksum-key: YOUR_PAYOS_CHECKSUM_KEY # Your PayOS Checksum Key

Configuration Options:

Setting	Description	Default
spring.datasource.password	MySQL root password	YOUR_MYSQL_PASSWORD
spring.mail.username	Gmail address for sending emails	your-email@gmail.com
spring.mail.password	Gmail App Password (see below)	xxxx xxxx xxxx xxxx
imgbb.api-key	ImgBB API key for image upload	YOUR_IMGBB_API_KEY

Setting up Gmail for Email Notifications (Required):

The application sends email notifications to sellers when their listings are approved or rejected. To enable this:

1. Enable 2-Step Verification on your Google Account:

   • Go to https://myaccount.google.com/security
   • Find "2-Step Verification" and enable it

2. Create an App Password:

   • Go to https://myaccount.google.com/apppasswords
   • Select "Mail" and "Other (Custom name)"
   • Enter a name like "GameShop"
   • Click "Generate"
   • Copy the 16-character password (e.g., abcd efgh ijkl mnop)

3. Configure in application.yml:

   spring:
     mail:
       username: your-email@gmail.com  # Your Gmail address
       password: uinkjxbccstgvtzv     # Paste the 16-character App Password WITHOUT spaces

   Important: Remove all spaces from the App Password when pasting into application.yml. For example, if Google gives you abcd efgh ijkl mnop, enter it as abcdefghijklmnop.

Note: If you don't configure email, listing approval/rejection notifications will fail silently in the background.

Getting an ImgBB API Key (optional):

1. Go to https://imgbb.com/
2. Sign up for a free account
3. Go to API Settings
4. Copy your API key
5. Paste it in application.yml

Note: If you don't configure the ImgBB API key, the image upload feature will not work. You can add it later if needed.

Setting up PayOS for Payment Processing (Required):

The application uses PayOS as the payment gateway for processing purchases. To enable payments:

1. Create a PayOS Account:

   • Go to https://my.payos.vn
   • Sign up for a new account
   • Verify your email address

2. Create a Payment Channel:

   • Navigate to the "Payment Channels" section
   • Click "Create New Channel"
   • Select your bank and enter your bank account details
   • Complete the verification process

3. Get Your API Credentials:

   • From the Payment Channels section, copy:
     • Client ID - Used for API authentication
     • API Key - Used for API authentication
     • Checksum Key - Used for HMAC SHA256 signature verification

4. Configure in application.yml:

   payos:
     client-id: your_actual_client_id_here
     api-key: your_actual_api_key_here
     checksum-key: your_actual_checksum_key_here
     base-url: https://api-merchant.payos.vn

5. Security Best Practices:

   • NEVER commit actual API keys to git
   • Use environment variables in production:

     export PAYOS_CLIENT_ID=your_actual_client_id
     export PAYOS_API_KEY=your_actual_api_key
     export PAYOS_CHECKSUM_KEY=your_actual_checksum_key

   • Add .env to .gitignore
   • Use different credentials for development and production

6. Environment Variable Setup (Production):

   Linux/Mac:

   export PAYOS_CLIENT_ID=your_actual_client_id
   export PAYOS_API_KEY=your_actual_api_key
   export PAYOS_CHECKSUM_KEY=your_actual_checksum_key

   Windows (Command Prompt):

   set PAYOS_CLIENT_ID=your_actual_client_id
   set PAYOS_API_KEY=your_actual_api_key
   set PAYOS_CHECKSUM_KEY=your_actual_checksum_key

   Windows (PowerShell):

   $env:PAYOS_CLIENT_ID="your_actual_client_id"
   $env:PAYOS_API_KEY="your_actual_api_key"
   $env:PAYOS_CHECKSUM_KEY="your_actual_checksum_key"

7. Test Configuration:

   • After configuring, start the application
   • Try to purchase a listing
   • Verify that QR code is generated with PayOS branding
   • Check the payment page displays correctly

Note: If you don't configure PayOS credentials, the payment feature will fail with an error message. You can add it later, but payment processing will not work without it.

For more details: See docs/payos-integration.md for complete PayOS API documentation.

4. Build and Run

Navigate to project directory first:

cd game-account-shop

Then run using Maven wrapper:

# Windows
mvnw.cmd spring-boot:run

# Linux/Mac
./mvnw spring-boot:run

Or using installed Maven (if you have Maven installed globally):

mvn spring-boot:run

5. Verify Startup

Look for this log message:

=================================================================
DEFAULT ADMIN ACCOUNT CREATED
Username: admin
Password: admin123
=================================================================

6. Access the Application

Open your browser: http://localhost:8080

---

🔑 Default Admin Account

Field	Value
Username	admin
Password	admin123
Role	ADMIN

⚠️ IMPORTANT: Change the default admin password after first login!

---

📁 Project Structure

game-account-shop/
├── src/
│   ├── main/
│   │   ├── java/com/gameaccountshop/
│   │   │   ├── GameAccountShopApplication.java    # Main entry point
│   │   │   ├── config/                            # Configuration classes
│   │   │   │   ├── SecurityConfig.java            # Security + BCrypt
│   │   │   │   └── DataInitializer.java           # Creates default admin
│   │   │   ├── controller/                        # Web controllers
│   │   │   ├── service/                           # Business logic
│   │   │   ├── repository/                        # Data access (JPA)
│   │   │   ├── entity/                            # Database entities
│   │   │   │   └── User.java
│   │   │   ├── enums/                             # Enumerations
│   │   │   │   └── Role.java                      # USER, ADMIN
│   │   │   └── dto/                               # Data Transfer Objects
│   │   └── resources/
│   │       ├── application.yml                    # Application config
│   │       ├── db/migration/                      # Flyway migrations
│   │       │   └── V1__Create_Database_Tables.sql
│   │       ├── templates/                         # Thymeleaf templates
│   │       └── static/                            # CSS, JS, images
│   └── test/                                      # Unit tests
├── pom.xml                                        # Maven dependencies
├── mvnw, mvnw.cmd                                 # Maven wrapper scripts
└── .mvn/                                          # Wrapper files

---

🗄️ Database Schema

Tables

Table	Description
users	User accounts (buyers, sellers, admins)
game_accounts	Game account listings (column account_rank for rank level)
transactions	Purchase transactions
reviews	Seller ratings and reviews

Note: The game_accounts table uses account_rank instead of rank to avoid MySQL reserved keyword conflicts.

Status Flows

Game Account Status:

PENDING → APPROVED → SOLD
    ↓
  REJECTED

Transaction Status:

PENDING → VERIFIED

User Roles:

USER (can be seller or buyer)
ADMIN

---

📚 Documentation

Document	Location	Description
Database Schema	docs/database-schema.md	Complete database design
PayOS Integration	docs/payos-integration.md	Payment gateway setup and API documentation
Project Context	_bmad-output/planning-artifacts/project-context.md	Coding standards & rules
Architecture	_bmad-output/planning-artifacts/architecture.md	System architecture decisions
Epics & Stories	_bmad-output/planning-artifacts/epics.md	Feature breakdown (18 stories)
Sprint Status	_bmad-output/implementation-artifacts/sprint-status.yaml	Development progress

---

🛠️ Development Guidelines

Coding Standards

Follow the project-context.md rules:

1. Naming Conventions:

   • Classes: PascalCase → UserService
   • Methods: camelCase → getUserById
   • Database: snake_case → created_at, seller_id

2. Architecture Pattern (Strict Layered):

   Browser → Controller → Service → Repository → Database
   

3. Security:

   • BCryptPasswordEncoder with 10 rounds minimum
   • Never store plaintext passwords
   • Session timeout: 30 minutes

4. Error Messages:

   • All user-facing messages in Vietnamese
   • Example: "Tên đăng nhập hoặc mật khẩu không đúng"

Creating a New Story

# Use the BMAD workflow
/bmad:bmm:workflows:create-story

Running Development Workflow

# Execute a story
/bmad:bmm:workflows:dev-story

# Code review
/bmad:bmm:workflows:code-review

---

🧪 Testing

Run tests:

mvn test

Run with coverage:

mvn clean test jacoco:report

---

🐛 Troubleshooting

Port 8080 Already in Use

Edit game-account-shop/src/main/resources/application.yml:

server:
  port: 8081  # Change to available port

Database Connection Failed

1. Verify MySQL is running: mysql --version
2. Check credentials in game-account-shop/src/main/resources/application.yml
3. Ensure database exists: CREATE DATABASE gameaccountshop;

Flyway Migration Failed

Drop and recreate database:

DROP DATABASE gameaccountshop;
CREATE DATABASE gameaccountshop CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Project Won't Compile

cd game-account-shop
./mvnw clean compile

Maven Wrapper Not Found

Make sure you're in the game-account-shop directory:

# Check current directory
pwd

# Should show: .../fcode-challenge-3
cd game-account-shop

# Now run
mvnw.cmd spring-boot:run

---

📝 Current Status

Epic	Status	Stories Done
Epic 1: Basic Authentication	Completed	3/3 (✅Initialize, ✅DB Setup, ✅Auth Logic)
Epic 2: Listings & Ratings	Backlog	0/5
Epic 3: Simple Buying	Backlog	0/3
Epic 4: Dashboard & Profiles	Backlog	0/3

✅ Backend Status: Running successfully on http://localhost:8080

• Database connected and migrated (Flyway V1 applied)
• Default admin account created (admin/admin123)
• User Registration & Login implemented (Spring Security + Thymeleaf)

---

🤝 Contributing

This is a learning project for newbie developers. To contribute:

1. Check sprint-status.yaml for available stories
2. Pick a story from backlog
3. Run /bmad:bmm:workflows:dev-story to implement
4. Run /bmad:bmm:workflows:code-review for review
5. Update sprint status when complete

---

📞 Support

For questions or issues:

• Review docs/database-schema.md for data model questions
• Check project-context.md for coding standards
• Refer to epics.md for feature specifications

---

📄 License

This project is for educational purposes.

---

Built with ❤️ for newbie developers learning Spring Boot