# Loyal Aid System

A comprehensive Laravel-based loyalty program management system for Beautez Pharmacy's Loyal Aid program. This system manages member registrations, subscription plans, loyalty points, bank payment processing, and integration with Loyverse POS.

## Features

- **Member Registration**: Complete registration form based on the original JotForm
- **Member Dashboard**: Members can view their points and profile information
- **Admin Panel**: Full administrative control over:
  - Member management
  - Points management (add/deduct points)
  - User management with role-based access control
  - Role and permission management
  - Subscription plan management
  - Bank payment CSV import and processing
  - Loyverse POS integration

## System Requirements

- PHP >= 8.2
- Composer
- Node.js and NPM
- MySQL/PostgreSQL/SQLite
- Laravel 12.x

## Installation

1. **Navigate to the project directory:**
   ```bash
   cd loyal-aid-system
   ```

2. **Install PHP dependencies:**
   ```bash
   composer install
   ```

3. **Install Node dependencies:**
   ```bash
   npm install
   ```

4. **Configure environment:**
   ```bash
   cp .env.example .env
   php artisan key:generate
   ```

5. **Update `.env` file with your database credentials:**
   ```env
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=loyal_aid
   DB_USERNAME=your_username
   DB_PASSWORD=your_password
   ```

6. **Run migrations:**
   ```bash
   php artisan migrate
   ```

7. **Seed initial data:**
   ```bash
   php artisan db:seed
   ```

8. **Build frontend assets:**
   ```bash
   npm run build
   ```

9. **Start the development server:**
   ```bash
   php artisan serve
   ```

## Default Admin Credentials

After seeding, you can login with:
- **Email:** admin@loyalaid.com
- **Password:** password

**⚠️ IMPORTANT:** Change this password immediately in production!

## Database Structure

### Core Tables

- **users**: System users (admin, staff, members)
- **roles**: User roles (admin, staff, member)
- **permissions**: System permissions
- **role_permission**: Many-to-many relationship between roles and permissions
- **members**: Loyal Aid members
- **dependents**: Member dependents (up to 4)
- **subscription_plans**: Available subscription plans (M100, M200, M300, etc.)
- **points_transactions**: All points credit/debit transactions
- **bank_payments**: Imported bank payment records
- **loyverse_syncs**: Loyverse POS synchronization records

## Key Features Implementation

### 1. Member Registration

The registration form includes:
- Personal information (name, ID number, email, phone)
- Dependents (up to 4)
- Postal address
- Employment information
- Banking details (multiple banks supported)
- Subscription plan selection

**Route:** `/register`

### 2. CSV Bank Payment Import

Import bank payment CSV files to process monthly subscriptions:
- Supports Standard Bank CSV format
- Matches payments to members by account number and reference
- Processes payments and awards points based on subscription plan
- Tracks payment status (not_processed, processed, failed)

**Route:** `/admin/bank-payments/import`

### 3. Points Management

- View all points transactions
- Add points manually
- Deduct points
- Automatic points calculation based on subscription plans
- Points history tracking

**Route:** `/admin/points`

### 4. Role-Based Access Control

- Create custom roles
- Assign permissions to roles
- Manage user roles
- Granular permission system

**Routes:**
- `/admin/roles`
- `/admin/users`
- `/admin/permissions`

### 5. Loyverse POS Integration

Integration with Loyverse POS API for:
- Syncing customer data
- Syncing points earned/redeemed
- Real-time point updates

**Configuration:** Add to `.env`:
```env
LOYVERSE_ACCESS_TOKEN=your_access_token
LOYVERSE_STORE_ID=your_store_id
```

**API Documentation:** https://developer.loyverse.com/docs/

## Subscription Plans

The system includes 7 subscription plans:
- M100: M100/month - 100 points/month
- M200: M200/month - 200 points/month
- M300: M300/month - 300 points/month
- M400: M400/month - 400 points/month
- M500: M500/month - 500 points/month
- M600: M600/month - 600 points/month
- M700+: M700+/month - 700 points/month

## CSV Import Format

The bank payment CSV should have the following columns:
- Bank Name
- Choose a Date in a Month Loyalaid Payment or Subscription Contribution should take place
- Member Names
- Standards Bank Account Details
- Branch Code Standard Bank
- Your Monthly Contribution
- Reference Number (format: Loyalaid/XXXX)
- Status

## Development

### Running Tests
```bash
php artisan test
```

### Code Style
```bash
./vendor/bin/pint
```

### Building Assets
```bash
npm run dev    # Development
npm run build  # Production
```

## Project Structure

```
loyal-aid-system/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       ├── Admin/
│   │       │   ├── MemberController.php
│   │       │   ├── UserController.php
│   │       │   ├── RoleController.php
│   │       │   ├── PointsController.php
│   │       │   └── BankPaymentController.php
│   │       ├── MemberRegistrationController.php
│   │       ├── MemberDashboardController.php
│   │       └── LoyverseController.php
│   └── Models/
│       ├── User.php
│       ├── Role.php
│       ├── Permission.php
│       ├── Member.php
│       ├── Dependent.php
│       ├── SubscriptionPlan.php
│       ├── PointsTransaction.php
│       ├── BankPayment.php
│       └── LoyverseSync.php
├── database/
│   ├── migrations/
│   └── seeders/
├── resources/
│   ├── views/
│   └── js/
└── routes/
    └── web.php
```

## Next Steps

1. **Implement Controllers:** Complete the controller logic for all features
2. **Create Views:** Build Blade templates for:
   - Member registration form
   - Admin dashboard
   - Member dashboard
   - Points management
   - CSV import interface
3. **Loyverse Integration:** Implement the API client for Loyverse POS
4. **Payment Processing:** Complete the bank payment processing logic
5. **Testing:** Write unit and feature tests
6. **Security:** Implement proper validation and authorization
7. **Documentation:** Add API documentation if needed

## Support

For issues or questions, please contact the development team.

## License

Proprietary - Beautez Pharmacy
