# Import System Implementation Playbook

Use this file as the default implementation contract for adding CSV import support to any new module/model.

## Trigger Format

When the user says only a module or model name, treat it as:

- "Implement full import system for <ModelName>"

Example inputs:

- ProductBrand
- ProductCategory
- Customer
- Supplier

## Required Outcome

For the requested model, implement a working import flow that matches existing project patterns (like Product import), including:

1. Import list page route (GET)
2. Import upload/dispatch route (POST)
3. Controller methods for both GET and POST
4. Import strategy registration in central config
5. Model-specific import strategy class
6. Import UI payload fields and sample data
7. Index page Import button/link wired to import route
8. Validation and duplicate handling behavior aligned with model constraints
9. Tenant compatibility (must work under tenant context)
10. Verification commands and result summary

## Implementation Checklist

### 1) Discover Existing Pattern

- Find a working module import flow (prefer Product).
- Compare routes, controller, strategy, config, and UI wiring.
- Reuse existing generic import page/component when available.

### 2) Routes

Add tenant routes (or equivalent module routes):

- GET `<resource>/import` -> `<Controller>@import` (named `<resource-singular>.import`)
- POST `<resource>/import` -> `<Controller>@<resource>Import` (named `<resourceplural>.import`)

Keep route names consistent with existing module naming conventions.

### 3) Controller

Inject and use:

- `App\Services\Import\ImportService`
- `App\Services\Import\ImportFieldResolver`
- `App\Http\Resources\ImportResource`

Implement GET import method:

- derive query params via `paginateParams`
- force/infer `model_type` when missing
- load import history via `ImportService::all`
- load summary via `ImportService::summary`
- resolve fields and sample rows via `ImportFieldResolver`
- return JSON when `wantsJson`
- otherwise render `Import/Index`

Implement POST import method:

- validate file (`csv,txt`) and `column_mapping`
- store file with `storeToLocal`
- ensure local availability with `ensureOnLocal`
- create pending import with model type
- dispatch import job
- return JSON success payload with `ImportResource`

### 4) Import Config

Update central import config:

- Add strategy map entry for `<ModelName>`
- Add `ui_payload_fields.<ModelName>`
- Add `ui_sample_data.<ModelName>`

Field keys must match the strategy transform inputs.

### 5) Strategy Class

Create `app/Services/Import/Strategies/<ModelName>ImportStrategy.php` implementing:

- `ImportStrategyInterface`
- `SkippableImportStrategyInterface`

Must include:

- `validate(array $row): array`
- `transform(array $row): array`
- `persist(array $row): bool`
- `wasSkipped(): bool`

Recommended rules:

- Required-field validation for model essentials
- Type coercion helpers (int/bool/float)
- Parent/relation resolver by ID first, then name/slug
- Duplicate policy based on unique constraints (usually slug and/or name)
- If duplicate, set skipped flag and return true
- If persist fails, return false and log exception

### 6) Frontend Wiring

In module index page:

- Add/keep Import action that navigates to import page route
- Prefer Inertia `Link` pattern used by Product module

Do not leave import button pointing to placeholder endpoint.

### 7) Tenant Safety

- Ensure queries and import records run in tenant context when tenant is initialized.
- Verify route and import execution in tenant mode.

### 8) Verify After Implementation

Run at least:

- route verification (GET+POST import routes exist)
- static error check on changed files
- one real import test on tenant with small CSV
- inspect resulting import record (`success_count`, `failure_count`, `error_log`)

## Default Duplicate Policy

Unless user asks otherwise, use this default:

- Skip duplicates (do not update existing rows)
- Log skipped rows in import error log as `type = skipped`

If user requests another behavior, switch to one of:

- slug-only duplicate detection
- upsert (update existing by unique key)
- fail-on-duplicate

## Delivery Format

After implementation, provide:

1. What was added (routes, controller, strategy, config, frontend)
2. Verification results
3. Any behavior notes (duplicate handling, parent resolution)
4. Optional next step options (sample CSV, upsert mode, stricter validation)

## One-Line Shortcut Instruction

When user says only a model name, execute this playbook immediately for that model.