# PROJECT GUIDELINES - Art Gallery Ecommerce

## 🧾 System Overview
A production-ready ecommerce backend for an Art Gallery selling unique (one-of-a-kind) artworks.
- **Backend**: Laravel 12.x
- **Admin Panel**: Filament 3
- **API**: REST API (v1) for Flutter mobile app
- **Currency**: MXN
- **Architecture**: Domain-based modular architecture

## 🧱 Domain Architecture
The project follows a modular structure located in `app/Domains/`.

### Domains:
- **Art**: Artist, Category, Technique, Artwork, Collection.
- **Sales**: Cart, Order.
- **Users**: User Management.
- **Payments**: Payment Intent, Transactions, Webhooks.
- **Shipping**: Shipment tracking.
- **Settings**: Site configurations (Singleton).

### Standard Domain Folder Structure:
```
app/Domains/{DomainName}/
    Models/
    Services/
    Actions/
    DTOs/
    Enums/
    Policies/
```

## 🗃️ Core Data Model & Schema

### Art Domain
- **artists**: `id, name, bio, photo, website, social_links`
- **categories**: `id, name, slug` (e.g., Painting, Sculpture)
- **techniques**: `id, name, slug`
- **artworks**: `id, artist_id, category_id, title, description, price, dimensions, year, status (available, reserved, sold), images`
- **collections**: `id, name, description, cover_image`
- **artwork_technique**: `artwork_id, technique_id` (Pivot)
- **collection_artwork**: `collection_id, artwork_id` (Pivot)

### Sales Domain
- **carts**: `id, user_id, session_id`
- **cart_items**: `id, cart_id, artwork_id`
- **orders**: `id, user_id, total_amount, status (pending, paid, preparing, shipped, delivered, cancelled), shipping_address`
- **order_items**: `id, order_id, artwork_id, price`

### Payments Domain
- **payments**: `id, order_id, provider (mercadopago, paypal), provider_payment_id, amount, currency (MXN), status, idempotency_key (UUID), payload`

### Shipping Domain
- **shipments**: `id, order_id, carrier, tracking_number, shipped_at, delivered_at`

### Settings Domain
- **site_settings**: `id, key, value` (Handled via Filament Spatie Settings or custom singleton)

## 💳 Payment Flow & Idempotency

### Checkout Strategy:
1. Validate artwork availability.
2. **Reserve** artwork (status = `reserved`) for 15 minutes.
3. Create **Order** (status = `pending`).
4. Generate **Idempotency Key** (UUID).
5. Create **Payment Intent** in `payments` table.
6. Redirect user to provider (MercadoPago/PayPal).

### Duplicate Charge Prevention:
- **Idempotency Key**: Sent to payment providers and stored locally.
- **Order Lock**: If `order.payment_status == paid`, reject any new payment attempts.
- **Reservation System**: Artworks are locked during checkout to prevent double-selling.

## 🔄 Webhook Processing
Endpoint: `POST /api/v1/payments/webhook/{provider}`
- **Signature Validation**: Required for all providers.
- **Idempotency Check**: Verify if the payment has already been processed.
- **Actions**:
    - Update `payment.status`.
    - Update `order.status` to `paid`.
    - Mark `artwork.status` to `sold`.

## 📦 Shipping Management
Manual process handled via Filament:
- Admin enters `carrier` and `tracking_number`.
- Updates `shipped_at` and `delivered_at` timestamps.

## 🌐 API Structure
Base Path: `/api/v1`
Authentication: Laravel Sanctum
Format: JSON, Stateless.

### Endpoints:
- `GET /catalog/artists`
- `GET /catalog/categories`
- `GET /catalog/techniques`
- `GET /catalog/artworks`
- `GET /catalog/collections`
- `POST /ecommerce/cart`
- `POST /ecommerce/checkout`
- `GET /ecommerce/orders`
- `POST /payments/create`

## 🖥️ Filament Admin Structure
Resources organized by Domain:
- **Art**: ArtistResource, ArtworkResource, CategoryResource, TechniqueResource, CollectionResource.
- **Sales**: OrderResource, PaymentResource.
- **Shipping**: ShipmentResource.
- **Settings**: SiteSettings (Custom Page).

### Filament Admin Forms Implementation
- **Artist**: Includes general info (name, bio as Rich Text), media (photo), and online presence (website, social links).
- **Artwork**: Uses Tabs for Basic Info, Pricing & Status, Media (Multiple images), and Categorization (Techniques/Collections).
- **Category & Technique**: Simple forms with auto-slug generation on creation. Table lists show name and slug.
- **Collection**: General info and cover image.
- **Order**: Summary (readonly user/total) and editable status and shipping address.
- **Payment**: Detailed breakdown with provider info (mostly readonly in edit mode).
- **Shipment**: Manual entry for carrier, tracking number, and timestamps.
- **SiteSettings**: Centralized page for site name, contact info, branding (logo/favicon/colors), and specific Payment Gateway configurations for Mercado Pago and PayPal.

## 🌐 Localization
- **Primary Locale**: Spanish (Mexico) `es_MX`
- **Fallback**: English `en`
- **Filament Resources**: All labels, plural labels, and navigation labels are translated to Spanish.
- **Icons**: Customized Heroicons for better visual representation.

## 📏 Naming Conventions & Coding Standards
- **Models**: PascalCase, Singular.
- **Controllers**: PascalCase, Suffix `Controller`.
- **Enums**: PascalCase, located in `app/Domains/{Domain}/Enums`.
- **Services/Actions**: Standard Laravel patterns.
- **API Responses**: Always wrap in a standard JSON structure.

## 🧬 Enum Definitions
- **ArtworkStatus**: `available`, `reserved`, `sold`.
- **OrderStatus**: `pending`, `paid`, `preparing`, `shipped`, `delivered`, `cancelled`.
- **PaymentStatus**: `pending`, `authorized`, `captured`, `failed`, `refunded`.

## 📅 Event Flow
1. `OrderCreated`: Triggers reservation timer.
2. `PaymentReceived`: Triggers `OrderPaid` event.
3. `OrderPaid`: Marks artwork as sold, notifies artist/admin.
4. `OrderShipped`: Notifies customer with tracking info.

## 📱 Future Mobile Considerations
- Use UUIDs for public-facing IDs.
- Optimized image thumbnails.
- Push notification placeholders for order updates.