# Mobile Unlock Service Platform - Setup Guide

## Project Overview

This is a fully online mobile unlock service platform where:
- **Shop Users** can register, submit unlock orders, and track their status & payments
- **Admin** manages all orders, processes payments, tracks analytics

## Key Features

### Shop User Features
- Register with shop name, phone, password
- Create unlock orders (FRP, iCloud, Network, MDM)
- Track order status (Pending → In Progress → Done)
- View balance and payment history
- Dashboard with order statistics

### Admin Features
- View all orders from all shops
- Update order status and add notes
- Manage shop users and their details
- Record payments from shops
- Analytics dashboard with service breakdown
- Real-time income tracking

## Database Structure

### Tables
- `shop_users` - Shop owner accounts
- `unlock_orders` - Customer unlock requests
- `shop_payments` - Payment records from shops

### Key Fields

**shop_users**
- shop_name
- phone_number (unique)
- password (hashed)

**unlock_orders**
- shop_user_id (FK)
- customer_name
- phone_number
- device_model
- imei_number
- service_type: frp, icloud, network, mdm
- status: pending, in_progress, done
- service_price
- note (optional)
- date

**shop_payments**
- shop_user_id (FK)
- amount
- status: pending, completed, failed
- payment_method: cash, esewa, khalti
- reference (optional)
- date

## Installation

### 1. Database Migrations

```bash
# Run all migrations (includes new tables)
php artisan migrate

# Or run fresh install
php artisan migrate:fresh
```

### 2. Seeding Demo Data

```bash
# Seed the unlock service with demo shops, orders, and payments
php artisan db:seed --class=UnlockServiceSeeder
```

This creates:
- 5 demo shop users
- 15-25 demo orders
- 5-10 demo payments

### 3. Authentication Guards

Two separate authentication guards are configured:
- `web` - for standard LMS users
- `shop` - for mobile shop owners

Configuration is in `config/auth.php`

## Routes

### Shop User Routes (Public - No Auth)

```
GET  /shop/register               - Shop registration form
POST /shop/register               - Submit registration
GET  /shop/login                  - Shop login form
POST /shop/login                  - Submit login
```

### Shop User Routes (Protected - Auth:shop)

```
GET  /shop/dashboard              - Dashboard with stats
GET  /shop/orders                 - List all shop orders
GET  /shop/orders/create          - Order creation form
POST /shop/orders                 - Submit new order
POST /shop/logout                 - Logout
```

### Admin Routes (Protected - Admin Auth)

```
# Unlock Service Dashboard
GET /admin/unlock-service/dashboard           - Analytics dashboard
GET /admin/unlock-service/orders              - All orders list
GET /admin/unlock-service/orders/{id}         - Order details
PUT /admin/unlock-service/orders/{id}/status  - Update status
PUT /admin/unlock-service/orders/{id}/note    - Add note

# Shop Users
GET /admin/unlock-service/users               - Shop users list
GET /admin/unlock-service/users/{id}          - User details

# Payments
GET /admin/unlock-service/payments            - Payments list
GET /admin/unlock-service/payments/create     - Payment form
POST /admin/unlock-service/payments           - Record payment
PUT /admin/unlock-service/payments/{id}/approve - Approve payment
```

## File Structure

```
app/
  ├─ Models/
  │  ├─ ShopUser.php            - Shop user model
  │  ├─ UnlockOrder.php         - Unlock order model
  │  ├─ ShopPayment.php         - Payment model
  ├─ Http/Controllers/
  │  ├─ ShopAuthController.php           - Shop login/register
  │  ├─ ShopOrderController.php          - Shop order management
  │  ├─ ShopDashboardController.php      - Shop dashboard
  │  ├─ Admin/
  │  │  ├─ AdminOrderController.php      - Admin order management
  │  │  ├─ AdminPaymentController.php    - Admin payment management
  │  │  ├─ AdminShopUserController.php   - Admin shop user management
  │  │  └─ UnlockServiceDashboardController.php - Admin analytics

database/
  ├─ migrations/
  │  ├─ 2026_04_15_000001_create_shop_users_table.php
  │  ├─ 2026_04_15_000002_create_unlock_orders_table.php
  │  ├─ 2026_04_15_000003_create_shop_payments_table.php
  ├─ factories/
  │  ├─ ShopUserFactory.php
  │  ├─ UnlockOrderFactory.php
  │  ├─ ShopPaymentFactory.php
  ├─ seeders/
  │  └─ UnlockServiceSeeder.php

resources/js/Pages/
  ├─ Shop/
  │  ├─ Auth/
  │  │  ├─ Login.vue
  │  │  └─ Register.vue
  │  ├─ Dashboard.vue
  │  └─ Orders/
  │     ├─ Index.vue
  │     └─ Create.vue
  ├─ Admin/Pages/
  │  ├─ UnlockService/
  │  │  └─ Dashboard.vue
  │  └─ UnlockOrders/
  │     └─ Index.vue

routes/
  ├─ web.php                - Shop user routes
  └─ admin.php              - Admin routes
```

## Authentication Flow

### Shop User Registration & Login

1. User visits `/shop/register`
2. Enters shop name, phone, password
3. System validates and creates account
4. User is auto-logged in via `auth:shop` guard
5. Redirects to shop dashboard

### Admin Management

1. Admin logs in via existing admin panel
2. Accesses "Unlock Service Platform" section
3. Can view/manage all orders, users, payments
4. Updates reflected in real-time to shop users

## Key Models & Relationships

### ShopUser
```php
hasMany UnlockOrder
hasMany ShopPayment
getBalance() // Returns: charged_amount - paid_amount
```

### UnlockOrder
```php
belongsTo ShopUser
service_type: enum [frp, icloud, network, mdm]
status: enum [pending, in_progress, done]
```

### ShopPayment
```php
belongsTo ShopUser
status: enum [pending, completed, failed]
payment_method: [cash, esewa, khalti]
```

## Features Implemented

✅ Shop user registration/login
✅ Unlock order submission
✅ Order status tracking (3 statuses)
✅ Admin dashboard with analytics
✅ Order management (view, update status, add notes)
✅ Shop user management
✅ Payment recording
✅ Balance calculation
✅ Service breakdown analytics
✅ Demo data seeding

## Testing Workflow

### As Shop User:
1. Register shop account
2. Create unlock order
3. View order in "My Orders"
4. Check dashboard stats
5. Wait for admin to update status

### As Admin:
1. Login to admin panel
2. Go to "Unlock Service Platform"
3. View all orders
4. Click order to view details
5. Update status (pending → in_progress → done)
6. Add notes for shop user
7. Record payment from shop
8. View analytics on dashboard

## Future Enhancements

- SMS notifications when order status changes
- Email notifications
- API for auto unlock integration
- Wallet system with prepaid balance
- Invoice generation
- Dispute resolution system
- Shop ratings and reviews

## Support

For issues or questions, check the models and controllers for detailed implementation.
