# Ready Templates Module (متجر النماذج الجاهزة)

## Overview
Complete e-commerce module for selling ready-made PDF templates with a separate category system.

## Features
- ✅ Separate category system for templates (independent from ads categories)
- ✅ Full CRUD for template categories
- ✅ Full CRUD for ready templates
- ✅ Multi-language support (Arabic/English)
- ✅ Media attachments (Cover image + PDF file)
- ✅ Template properties:
  - Title & Description (translated)
  - Price
  - Pages Count
  - Is Fillable (قابل للتعبئة)
  - Cover Image
  - PDF File
  - Downloads Counter
  - Active/Inactive Status
  - Display Order
- ✅ Automatic media attachment handling via observers
- ✅ Proper validation with translated attributes
- ✅ Clean API resources
- ✅ Permission-based access control

## Database Structure

### Tables Created
1. **template_categories**
   - id, is_active, order, timestamps

2. **template_category_translations**
   - id, template_category_id, locale, name

3. **ready_templates**
   - id, template_category_id, price, pages_count, is_fillable, is_active, order, downloads_count, timestamps

4. **ready_template_translations**
   - id, ready_template_id, locale, title, description

### Migrations
- `2026_08_13_000001_create_template_categories_table.php`
- `2026_08_13_000002_create_ready_templates_table.php`

## API Endpoints

### Template Categories
```
GET    /api/admin/ready-templates/categories/list          # Select list (active only)
GET    /api/admin/ready-templates/categories               # List all categories
POST   /api/admin/ready-templates/categories               # Create category
GET    /api/admin/ready-templates/categories/{id}          # Show category
PUT    /api/admin/ready-templates/categories/{id}          # Update category
DELETE /api/admin/ready-templates/categories/{id}          # Delete category
PATCH  /api/admin/ready-templates/categories/{id}/status   # Toggle status
```

### Ready Templates
```
GET    /api/admin/ready-templates                          # List all templates
POST   /api/admin/ready-templates                          # Create template
GET    /api/admin/ready-templates/{id}                     # Show template
PUT    /api/admin/ready-templates/{id}                     # Update template
DELETE /api/admin/ready-templates/{id}                     # Delete template
PATCH  /api/admin/ready-templates/{id}/status              # Toggle status
```

## Request Payloads

### Create/Update Template Category
```json
{
  "ar": {
    "name": "عقود"
  },
  "en": {
    "name": "Contracts"
  },
  "is_active": true,
  "order": 1
}
```

### Create/Update Ready Template
```json
{
  "template_category_id": 1,
  "price": 149.00,
  "pages_count": 6,
  "is_fillable": true,
  "is_active": true,
  "order": 1,
  "cover": 123,  // Media ID (pre-uploaded)
  "pdf": 124,    // Media ID (pre-uploaded)
  "ar": {
    "title": "عقد إيجار سكني",
    "description": "نموذج عقد إيجار سكني معتمد ومتوافق مع نظام الإيجار السكني..."
  },
  "en": {
    "title": "Residential Lease Agreement",
    "description": "Approved residential lease agreement template..."
  }
}
```

## Models & Relationships

### TemplateCategory
- Has many `ReadyTemplate`
- Translatable (name)
- Scopes: `active()`, `ordered()`

### ReadyTemplate
- Belongs to `TemplateCategory`
- Translatable (title, description)
- Has Media: cover (image), pdf (file)
- Scopes: `active()`, `ordered()`
- Methods: `incrementDownloads()`

## Media Handling

Media attachments are handled automatically through the `HasMedia` trait and `GeneralObserver`:

1. **Upload media** first via the general attachment endpoint
2. **Get media ID** from the response
3. **Pass media ID** in create/update requests as `cover` and `pdf` fields
4. **Observer automatically** attaches the media to the model

## Permissions Required

```
template-categories.index
template-categories.store
template-categories.show
template-categories.update
template-categories.destroy

ready-templates.index
ready-templates.store
ready-templates.show
ready-templates.update
ready-templates.destroy
```

## Seeder

Run the seeder to create initial template categories:
```bash
php artisan db:seed --class=TemplateCategorySeeder
```

Creates 5 default categories:
- نماذج قضائية (Legal Templates)
- عقود (Contracts)
- اتفاقيات (Agreements)
- نماذج أعمال (Business Templates)
- خطابات رسمية (Official Letters)

## Files Created

### Models
- `app/Models/TemplateCategory.php`
- `app/Models/TemplateCategoryTranslation.php`
- `app/Models/ReadyTemplate.php`
- `app/Models/ReadyTemplateTranslation.php`

### Controllers
- `app/Http/Controllers/Api/Dashboard/Admin/ReadyTemplates/TemplateCategoryController.php`
- `app/Http/Controllers/Api/Dashboard/Admin/ReadyTemplates/ReadyTemplateController.php`

### Services
- `app/Services/Dashboard/ReadyTemplates/TemplateCategoryService.php`
- `app/Services/Dashboard/ReadyTemplates/ReadyTemplateService.php`

### Requests
- `app/Http/Requests/Api/Dashboard/Admin/ReadyTemplates/TemplateCategoryRequest.php`
- `app/Http/Requests/Api/Dashboard/Admin/ReadyTemplates/ReadyTemplateRequest.php`

### Resources
- `app/Http/Resources/Api/Dashboard/Admin/ReadyTemplates/TemplateCategory/SimpleTemplateCategoryResource.php`
- `app/Http/Resources/Api/Dashboard/Admin/ReadyTemplates/TemplateCategory/TemplateCategoryIndexResource.php`
- `app/Http/Resources/Api/Dashboard/Admin/ReadyTemplates/TemplateCategory/TemplateCategoryShowResource.php`
- `app/Http/Resources/Api/Dashboard/Admin/ReadyTemplates/ReadyTemplate/ReadyTemplateIndexResource.php`
- `app/Http/Resources/Api/Dashboard/Admin/ReadyTemplates/ReadyTemplate/ReadyTemplateShowResource.php`

### Migrations
- `database/migrations/2026_08_13_000001_create_template_categories_table.php`
- `database/migrations/2026_08_13_000002_create_ready_templates_table.php`

### Seeders
- `database/seeders/TemplateCategorySeeder.php`

### Routes
- Updated: `routes/api/dashboard/admin.php`

### Translations
- Updated: `lang/ar/validation.php` (added template-related attributes)
- Updated: `lang/en/validation.php` (added template-related attributes)

## Next Steps

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

2. **Run seeder:**
   ```bash
   php artisan db:seed --class=TemplateCategorySeeder
   ```

3. **Add permissions** to the database for the roles that need access

4. **Test the endpoints** using your API client

## Notes

- Media (cover & PDF) must be uploaded separately via the attachment endpoint first
- The `downloads_count` field is incremented automatically when a template is downloaded
- All text fields support Arabic and English translations
- Categories and templates have independent ordering via the `order` field
- The module follows the same patterns as other modules in the codebase for consistency