# Claude Code Instructions — Highgrove Sync

> **SELF-IMPROVEMENT DIRECTIVE**: When you make changes to logic, flow, architecture, models, jobs, services, constants, or conventions in this project, you MUST update ALL of the following:
> 1. **This file (CLAUDE.md)** — Update patterns, registries, field indices
> 2. **`.github/copilot-instructions.md`** — Mirror any architectural/convention changes
> 3. **`docs/retailers/{slug}.md`** — Update the affected retailer's user guide (written for END USERS, not developers — see guide rules below)
> 4. **`docs/user-guide.md`** — Update if the change affects the overview (new retailer, new sync type, etc.)
> 5. **`.claude/commands/highgrove-sync.md`** — Update the Retailer Registry table and Override Fields Quick Reference if affected
> 6. **`memory/decisions.md`** — Log the architectural decision so future sessions stay aligned
> 7. **`MEMORY.md`** — Update if the change affects cross-session patterns
>
> **Process flow changes are ALWAYS a trigger.** If a retailer's sync type, product sync capability, inventory sync pattern, overridable fields, or any step in its sync flow changes (enabled, disabled, reordered, added, removed), update ALL files above — no exceptions.
>
> Delete outdated sections, add new patterns, and keep everything accurate. These files are your persistent memory — if they're wrong, you'll write wrong code in future sessions.

---

## MANDATORY: Read Context Files Before Working

Before starting ANY sync service, retailer, or architectural work:

1. **Read `memory/decisions.md`** — Contains past architectural decisions. Follow them unless the user explicitly changes direction.
2. **Read the relevant `docs/retailers/{slug}.md`** — Understand current documented behavior before modifying it.
3. **Read the relevant sync service** — Understand current implementation before changing it.
4. **Never re-decide something already decided** — If a decision is documented, follow it.

---

## MANDATORY: Retailer Guide Writing Rules

Retailer guides in `docs/retailers/` are for **END USERS** (business users, product managers), NOT developers. When updating them:

- **No code**, no class names, no method names, no file paths
- **No technical jargon** — say "the system" not "the service", "scheduled batch" not "cron job", "saved to the database" not "persisted to the DB"
- **Explain what happens from the user's perspective** — "Your products are exported to a CSV file every hour" not "RetailerSyncJob dispatches FreedomFeedExport"
- **Use plain language for quantities** — "Stock Quantity (negative values are treated as zero)" not "max(StockOnHandQty, 0)"
- **Include "Good to Know" section** with practical tips and gotchas
- **Include "What Can Go Wrong" section** with scenarios and what the user should expect
- **Follow the format convention** documented in `.claude/commands/highgrove-sync.md` section E

---

## MANDATORY: Run Unit Tests After Every Code Change

After ANY code modification (sync services, constants, exports, imports, models, jobs, etc.), you MUST run:

```bash
export PATH="/c/laragon/bin/php/php-8.1.34-Win32-vs16-x64:$PATH" && cd /c/laragon/www/highgrove-sync && php artisan test --testsuite=Unit
```

- All tests MUST pass before considering work complete
- If a test fails, fix the code or update the test (with justification)
- When modifying sync services (`app/Services/Sync/Retailer/*SyncService.php`), update the corresponding unit test in `tests/Unit/Services/Sync/{RetailerName}SyncServiceTest.php`

---

## Project Overview

Laravel application synchronizing product and inventory data from eSuite (ERP) to 10 retail platforms: Shopify, Amazon, Fieldfolio, Freedom, Temple & Webster, Fantastic Furniture, Kitchen Warehouse, Living Styles, KG Group, and generic feed receivers.

---

## Sync Service Architecture & Conventions

### Core Pattern: Strategy + Factory

- **Contract**: `SyncServiceInterface` (`app/Services/Sync/Contracts/`) defines 3 methods:
  - `syncProduct(int $esuiteId, array $product): void`
  - `syncInventory(int $esuiteId, array $product): void`
  - `syncFulfillmentOrder(int $esuiteId, array $fulfillmentOrderData): void`
- **Factory**: `SyncServiceFactory::make(string $retailer_slug)` (`app/Services/Sync/Factory/`) resolves via PHP `match` expression. Direct instantiation (`new`), NOT DI container.
- **Base class**: All sync services `extend BaseService implements SyncServiceInterface`.

### Sync Service Registry

| Slug | Class | Product Sync | Inventory Sync | Pattern |
|------|-------|:---:|:---:|---|
| `shopify` | `ShopifySyncService` | Full CRUD | Real-time API | Individual, GraphQL, multi-location, color/size group linking |
| `amazon` | `AmazonSyncService` | Inventory passthrough | Real-time API + Batch API | Individual + Batch, SP-API (Vendor Direct Fulfillment), order pull |
| `fieldfolio` | `FieldfolioSyncService` | Full CRUD | Real-time API | Individual, multi-catalog, auto-publish, order pull |
| `kitchen_warehouse` | `KitchenWarehouseSyncService` | Inventory passthrough | Real-time API | Individual, Ordoro (product CRUD disabled), order pull |
| `fantastic` | `FantasticFurnitureSyncService` | Inventory passthrough | Real-time API | Individual, inventory + overridable product name, order pull (Dsco API) |
| `freedom` | `FreedomSyncService` | Inventory passthrough | Local DB | Batch CSV upload, order pull |
| `temple_webster` | `TempleWebsterSyncService` | Inventory passthrough | Local DB | FTP CSV batch, order pull (Supplier API) |
| `living_styles` | `LivingStylesSyncService` | Inventory passthrough | FTP XLSX batch | FTP, XLSX, order pull (FTP CSV) |
| `kg_group` | `KgGroupSyncService` | Inventory passthrough | SFTP CSV batch | SFTP, CSV |
| `generic_feed` | `GenericFeedSyncService` | Inventory passthrough | Local only | Feed-based |

### Sync Cadences

1. **Individual** (`sync_type='individual'`): Real-time per-product via queued `SyncRetailerProductJob` / `SyncRetailerInventoryJob`.
2. **Batch** (`sync_type='batch'`): `PrepareRetailerSyncJob` fetches modified stocks from eSuite once, passes `modifiedStockNos` to each retailer's `syncBatchProduct()`/`syncBatchInventory()`. Freedom uses CSV export→API upload. Amazon batches items into chunks of 50 (`AMAZON_BATCH_CHUNK_SIZE`) and submits via `submitInventoryUpdate()`.
3. **FTP** (`sync_type='ftp'`): `PrepareRetailerSyncJob` fetches modified stocks from eSuite once, passes `modifiedStockNos` to `syncFtpInventory()`. Temple & Webster (CSV), Living Styles (XLSX), KG Group (CSV via SFTP). Full export at EOD + hourly incremental.
4. **Feed-only**: Only write inventory to DB; external systems pull via authenticated feed downloads.

> **`ftp_export_type` setting** (in retailer `extra_configs`): Controls incremental vs full export. `'full'` (default) exports all enabled products regardless of `modifiedStockNos`. `'incremental'` exports only products whose stock_no is in `modifiedStockNos`, or skips entirely if the list is empty.

> **Order pulling**: `OrderPullCommand` dispatches `OrderPullJob` for each enabled retailer in `ORDER_PULL_RETAILERS` (kitchen_warehouse, freedom, fieldfolio, temple_webster, fantastic, amazon). Living Styles pulls CSV order files from FTP. Each sync service implements `pullOrders()` to fetch orders from the retailer's API, normalize them, and sync to eSuite. Freedom uses Mirakl OR11 API with `order_state_codes=WAITING_ACCEPTANCE,SHIPPING` (two-step flow: creates order at WAITING_ACCEPTANCE without address, updates with shipping address at SHIPPING), paginated with `max`/`offset`, and filters by `last_successful_order_sync` timestamp. Temple & Webster uses a two-step flow: `list_purchase_orders` (unshipped POs) then `get_purchase_order` (details per PO), with staging/production mode controlled by `extra_configs.order_api_mode`. Amazon uses the Vendor Direct Fulfillment Orders API v1 with single-step fetch (`includeDetails=true`), `status=NEW`, and cursor pagination via `nextToken`. Fantastic Furniture uses Dsco API v3 (`api/v3/order/page`) with `lifecycle=received` filter, `scrollId` pagination, and customer-based account resolution via `OrderSyncService::syncOrderCustomer()` (same pattern as Shopify/Fieldfolio — no static `account_ref`). Living Styles pulls CSV order files from FTP (`ftp_ls` disk, `order_ftp_path` default `'orders'`), groups rows by Order Number, and moves processed files to a `processed/` subdirectory.

> **Inventory passthrough**: Non-individual retailers (cron/ftp/feed) have `syncProduct()` implemented as "inventory passthrough" — it loads the product from DB and calls `syncInventory()`. This means `ProductSyncService` dispatches `SyncRetailerProductJob` for ALL retailers, and inventory is synced during product sync. The separate EOD inventory sync is optional for these retailers.

### Fulfillment Order Sync (Shopify)

Shopify orders sync via `fulfillment_orders/order_routing_complete` webhook. Each fulfillment order (one per location) syncs to eSuite as a separate transaction.

**Flow**: Webhook → `ShopifyWebhookService::handleFulfillmentOrder()` (filters `open` status) → `SyncFulfillmentOrderJob` → `ShopifySyncService::syncFulfillmentOrder()` → fetch FO details from Shopify REST → save/find parent order (cache lock) → resolve customer → build eSuite payload → `createOrUpdateEsuiteTransaction()`

**Tables**: `orders` (parent, reference only), `fulfillment_orders` (per FO, sync status tracked here), `fulfillment_order_payloads` (raw/eSuite JSON)

**Resync**: Single (Show page), bulk (Index page checkboxes), auto-retry cron (`ResyncFailedOrdersCommand` for `sync_status=0`). Resyncs re-fetch from Shopify API and proceed regardless of FO status — no `open` check on resync.

**eSuite payload**: `T_Trans` (BatchType=SWO, TransIncGST=True, CostCentreCode=W, LocationNo=10, TransUserStr2=SOR), `T_TrnDet` (LineIncGST=True, LineDlvMode=SOR, freight line), `T_TrnDlv` (delivery address), `T_Pay` (gateway mapping: shopify_payments→WEB, zip→ZIP), `T_Acc` (inline account when no accountRef).

**Key fields**: `trans_comment` = `"[Order Sync - {order_name}]"`, `trans_your_ref` = `"{order_name} -> {fo_id}"`.

> **Old order sync removed**: `syncOrder()`, `SyncRetailerOrderJob`, order import flow, order resync, Myer/Mirakl detection, `buildShopifyTransComment()` — all deleted. Order UI is read-only (view only, no resync).

### BaseService Shared Methods (`app/Services/BaseService.php`)

- `commonSyncInventory()` — Generic local inventory sync. Calculates `stock_quantity = max(StockOnHandQty, 0)`. Creates/updates `RetailerInventory` records.
- `setProductPricePerRetailer()` — Multi-step pricing: price band matching → fallback to PriceBand "I" → campaign discounts (P=fixed, D=discount, %=percentage). Returns `['price', 'compare_at', 'gst_type']`.
- `getEsuiteValue()` — **Static**. Extract value from raw eSuite data (`'attribute'`, `'text'`, or `'field'` type).
- `getArrivalDateFromEsuite()` — **Static**. Parses `ArrivalDate` attribute + 14 days buffer. Returns `Y-m-d` or null.

### Adding a New Retailer

1. Create `app/Services/Sync/Retailer/{Name}SyncService.php` extending `BaseService implements SyncServiceInterface`
2. Add constructor calling `setRetailerDetails()`
3. Add entry to `SyncServiceFactory::make()` match expression
4. If API-based: create `app/Services/API/{Name}/{Name}ApiService.php` + `app/Libraries/Lib{Name}.php`
5. Add product field schema to `RetailerConstants::PRODUCT_FIELDS` and settings to `RETAILER_SETTINGS`
6. Add unit test in `tests/Unit/Services/Sync/{Name}SyncServiceTest.php`

---

## Data Model & JSON Column Patterns

### Entity Relationships

```
Esuite ──hasMany──▸ Product ──hasMany──▸ RetailerProduct ──hasMany──▸ RetailerInventory
                      │                     │   │
                      │hasMany              │   │belongsTo
                      ▼                     │   ▼
                 ProductImage               │  RetailerCategory
                      │hasMany              │
                      ▼                     │hasMany
             RetailerProductImage ◂─────────┘

RetailerIntegration ──hasMany──▸ RetailerProduct, RetailerInventory,
                                 RetailerCategory, EsuiteCategoryMapping,
                                 LookUp, SyncLog, Customer, Order, FulfillmentOrder

Order ──hasMany──▸ FulfillmentOrder ──hasOne──▸ FulfillmentOrderPayload

EsuiteCategoryMapping ──belongsTo──▸ RetailerIntegration, RetailerCategory
```

### JSON Column Conventions

- **`platform_configs`** (RetailerProduct): User-editable fields. Schema defined by `RetailerConstants::PRODUCT_FIELDS`.
- **`extra_configs`** (RetailerProduct): System-managed data. NOT user-editable.
- **`credentials`** (RetailerIntegration): API keys/tokens. NOT in config files.
- **`esuite_data`** (Product): Raw eSuite stock data snapshot. Use `scopeWithoutEsuiteData` for list views.

### Model Conventions

- Almost ALL models use `$guarded = []`. Exceptions: `EsuiteFieldMapping` and `UserSyncStatus` use `$fillable`.
- Most models use `SoftDeletes`. Exceptions: `SyncLog`, `LookUp`, `Esuite`, `Customer`, `Order`, `User`, `FulfillmentOrder`, `FulfillmentOrderPayload`.

---

## Job Dispatch & Orchestration

### Product Sync Chain

```
ProductSyncCommand (artisan)
  └─▸ PaginateProductSyncJob
        ├─▸ SyncProductsJob → ProductSyncService::processTargetProducts()
        │     ├─ saveProductToDb()
        │     ├─ Creates SyncRetailerProductJob per product×retailer (ALL sync types)
        │     ├─ For sync_type='batch': also marks products via ProductSyncFlagService
        │     └─ Bus::batch([...jobs])->finally(CompleteSyncStatusJob → next page)
        └─ On final page (no products): triggers PrepareRetailerSyncJob('inventory_ftp')
           for TW/LS/KG full FTP upload (full daily sync only)
```

### Batch/FTP Sync Chain

```
RetailerBatchSyncCommand / RetailerFtpInventorySyncCommand / RetailerBatchInventorySyncCommand
  └─▸ PrepareRetailerSyncJob(syncType, esuiteId)
        ├─ fetchModifiedStockNos(QtyModified|InfoModified) — single eSuite call, 60-min window
        └─▸ RetailerSyncJob(syncType, esuiteId, retailer, modifiedStockNos) per enabled retailer
              └─▸ SyncServiceFactory::make(slug)->syncBatchProduct|syncBatchInventory|syncFtpInventory
```

### Disabled Product Scan

```
DisabledProductScanCommand (every 6 hours)
  ├─ Read last-run timestamp from GlobalMeta ('disabled_product_scan_last_run')
  ├─ Call EsuiteApiService::getDisabledProducts(lastRun) → _HGV_WebDisabledDiscontinued SP
  ├─ For each returned product:
  │     ├─ Find local Product by SKU + esuite_id
  │     └─ Set enabled=0 on all enabled RetailerProduct records
  │           └─ RetailerProduct model observer dispatches DisableRetailerProductJob (Shopify)
  └─ Update GlobalMeta last-run timestamp
```

### Inventory Sync Chain (Modified/Delta Only)

```
InventorySyncCommand --date_modified (every 5 min)
  └─▸ PaginateInventorySyncJob
        └─▸ SyncInventoriesJob → InventorySyncService::processTargetProducts()
              ├─ Fetches fresh stock from eSuite API per product
              ├─ Creates SyncRetailerInventoryJob per product×retailer
              └─ Bus::batch([...jobs])->then(next page)
```

> **Note**: The EOD full inventory sync (`inventories:sync --sync_all=1`) has been removed.
> Product sync now runs inventory passthrough for all retailers and triggers FTP upload on completion.

### Fulfillment Order Sync Chain (Shopify)

```
Shopify Webhook: fulfillment_orders/order_routing_complete
  └─▸ ShopifyWebhookService::handleFulfillmentOrder()
        ├─ Filters: status must be 'open', sync not disabled
        └─▸ SyncFulfillmentOrderJob (queue: orders)
              └─▸ ShopifySyncService::syncFulfillmentOrder()
                    ├─ Fetch FO details from Shopify REST API
                    ├─ Save/find parent Order (cache lock for race safety)
                    ├─ Resolve customer via OrderSyncService
                    ├─ Save FulfillmentOrder + FulfillmentOrderPayload
                    ├─ Build eSuite payload (T_Trans, T_TrnDet, T_TrnDlv, T_Pay, T_Acc)
                    └─ createOrUpdateEsuiteTransaction()

ResyncFailedOrdersCommand (cron — auto-retry)
  └─ Queries FulfillmentOrder where sync_status='0', limit 50
     └─▸ SyncFulfillmentOrderJob per failed FO
```

### Job Properties

- Tries: 15 (accommodates rate limiter releases)
- MaxExceptions: 2 (only real failures count)
- Timeout: 600s, Backoff: 30s
- Middleware: `RateLimitedRetailer`, `WithoutOverlapping`

---

## RetailerConstants & Product Field Schemas

`app/Constants/RetailerConstants.php` — Defines per-retailer configurable product fields.

### Key Field Properties

- `read_only`: Field is system-managed, skipped in exports/imports
- `overridable`: When `true`, field gets inline override checkbox. Override ON = push local value; OFF = pull from platform.
- `override_key`: Custom key name for the override flag (defaults to `'override_' + field`)
- `field_type`: `string`, `enum`, `boolean`, `date`, `number`, `textarea`, `multiselect`, `checkbox`, `password`

### Current Non-Read-Only Field Indices (for ProductsSheet export)

After 7 base columns + 20 image columns = index 27 onwards. Overridable fields have an "Override [Label]" column immediately after the value column.

**Shopify** (3 overridable, tags now read_only): metafield_product_icons(27), override_product_icons(28), metafield_features(29), override_features(30)

**Fieldfolio** (4 overridable in platform_configs, label NOT overridable, custom_tags now read_only): esuite_catalogue(27), category_enum(28), override_category(29), product_name(30), override_product_name(31), brand(32), override_brand(33), label(34), brand_values(35), override_brand_values(36), then per-catalog positions: Position(J.Elliot Home)(37), Override Position(J.Elliot Home)(38), Position(Highgrove Special Buys)(39), Override Position(Highgrove Special Buys)(40), Position(Test catalogue)(41), Override Position(Test catalogue)(42)

**Freedom** (1 overridable): category_enum(27), override_category(28), warranty_period(read_only, skipped), base_colour(29), assembly_type(30)

**Fantastic Furniture** (1 overridable): product_name[label: Inventory Name](27), override_product_name(28)

**Kitchen Warehouse**: product_name(27) — no overridable fields

**Living Styles**: no non-read-only fields (eta is read_only)

**Temple & Webster**: item_description(27), item_next_availability_date(read_only, skipped), item_discontinued(read_only, skipped) — no overridable fields

**KG Group**: no non-read-only fields (empty PRODUCT_FIELDS)

> **IMPORTANT**: When modifying PRODUCT_FIELDS (adding/removing/reordering fields, changing read_only or overridable), update the field index comments above AND fix any affected tests in `tests/Unit/Exports/Product/ProductExportTest.php`.

---

## API Service & Library HTTP Pattern

### Two-Layer Architecture

```
SyncService → ApiService → Library (Lib*.php) → HTTP (Guzzle)
```

### Standard Response Format

```php
['code' => int, 'status' => bool, 'response' => array]
// On exception: ['code' => 500, 'status' => false, 'response' => []]
```

---

## Shopify-Specific

- Uses **GraphQL API** for product CRUD, **REST** for images/webhooks/inventory
- `retryShopify()` — exponential backoff for HTTP 429
- **Metafield sync**: Delete-then-set pattern. Overridable metafields skipped when override OFF.
- **Tags**: Sourced from eSuite `StockInfoStr4`. Sent on create and update when value exists. Not pulled from Shopify. No override flag.
- **Product Status Rules**: Based on eSuite `WebEnabled` flag only. `WebEnabled=false` → ARCHIVED, `WebEnabled=true` (or unset) → ACTIVE.
- **Category Tags**: Category names from eSuite StockLinks (`LinkType='C'`) + `StockBrandDesc` are sent as Shopify **tags** via GraphQL (replaces old collection sync). `buildCategoryTags()` extracts tag names from `esuite_category_mappings`, `saveCategoryTagsToConfig()` saves to `platform_configs['tags']` for UI display. On create: tags sent directly. On update: tags **merged** with existing Shopify tags (append-only, never removes existing tags).
- **CategorySyncCommand** (`php artisan categories:sync`): Fetches eSuite `CategoryTree`, flattens, stores in `esuite_category_mappings`. Auto-maps by fuzzy name match. Admin UI at `/products/category-mappings`.
- **EsuiteCategoryMapping** model: `esuite_category_id`, `esuite_category_name`, `esuite_parent_id`, `full_path`, `retailer_integration_id` (FK), `retailer_category_id` (FK, nullable).
- **Associated Products (Color/Size Groups)**: Inline per-product sibling linking during `createUpdateProduct()`. `syncSiblingMetafields()` resolves sibling Shopify GIDs from `color_group` and `size_group` columns, pushes `custom.associated_products` (color) and `custom.product_size_options` (size) metafields (both `list.product_reference`), and **backfills** each sibling's metafield to include the current product. When product A syncs, siblings B and C also get updated metafields including A. Read-only — sourced from product groupings, not in `PRODUCT_FIELDS`. Self-correcting: siblings not yet on Shopify are omitted, included when they sync later.
- **PDF Attachments**: `syncPdfsAndLog()` filters `esuite_data.StockImage` for `FileExt === 'pdf'`, fetches binary via `EsuiteApiService::getFile(fileName)`, stores on `public` disk at `product_pdfs/{sku}/{fileName}`, pushes as `json` metafield (`custom.product_documents`) with `[{"file_name":"Tech Spec","file_url":"https://..."}]`. Always sent (even empty `[]`) to clear stale data. `PDF_NAME_MAP` constant maps `ImageNo` (1–5) to human-readable names. Read-only `product_documents` field in `PRODUCT_FIELDS['shopify']` shows document names in admin UI.
- **Multi-Location Inventory**: Supports multiple Shopify locations with per-location stock from eSuite.
  - **LocationSyncCommand** (`php artisan locations:sync`): Three-step process: (1) Fetches Shopify locations via REST API, creates/updates `SHOPIFY_LOCATION` rows in `look_ups` table. (2) Fetches eSuite companies via `/company` endpoint, creates/updates `ESUITE_COMPANY` rows in `look_ups` (from=CompanyNo, to=CompanyCode, to_description=CompanyName). (3) Auto-maps Shopify locations to eSuite companies by matching location name against CompanyCode (case-insensitive), setting the `SHOPIFY_LOCATION` row's `from` field to the matched CompanyNo (= LedgerCompanyNo).
  - **LookUp fields**: `SHOPIFY_LOCATION` rows: `from` = eSuite CompanyNo (auto-mapped or manually set), `from_description` = `'esuite_location'`, `to` = Shopify location ID, `to_description` = location name. `ESUITE_COMPANY` rows: `from` = CompanyNo, `from_description` = `'esuite_company'`, `to` = CompanyCode, `to_description` = CompanyName.
  - **Single location** (≤1 `SHOPIFY_LOCATION` row): Uses aggregate `StockOnHandQty` — backward compatible, no extra API call.
  - **Multiple locations** (2+ rows): Calls `EsuiteApiService::getStockByLocations(sku)` → `W_HGV_GetStockAvail_Stores` SP, returns per-`LedgerCompanyNo` stock. Stock calculated via `BaseService::calculateLocationStock()` matching old Magento StockService consolidation logic.
  - **Stock calculation** (`BaseService::calculateLocationStock()`): Uses `DCCompanyNo` field to distinguish primary vs affiliate locations. Primary (`DCCompanyNo=''`): `max(DCAvailQty, 0) + max(StoreAvailQty, 0) + sum of all affiliates' max(StoreAvailQty, 0)`. Affiliate (`DCCompanyNo` = parent's CompanyNo): `max(StoreAvailQty, 0)` only (DC stock skipped to avoid double-counting). `AffiliateAvailQty` is deliberately excluded (matches old Magento sync behavior).
  - **Batch chunking**: `getBulkStockByLocations()` called with chunks of 10 stock codes to limit eSuite response size.
  - **`lookUpFields()`** (plural): Returns all matching `look_ups` rows. `lookUpField()` (singular) unchanged.
  - Per-location `RetailerInventory` records use `retailer_ref_location_id` (finally populated).
  - Log description includes per-location breakdown: "Stock sent to N locations: Location A: X units, Location B: Y units."

### Product Group Linking (Color & Size)

Products in the same group (e.g., same design in different colors or sizes) are linked via metafields, NOT combined as Shopify variants:

- **Data source**: `_HGV_Swatches` eSuite stored procedure returns group→children mappings (`brandcode` → comma-separated `StockCodes`, plus `Finishes`/`FinishCodes` and `Colours`/`ColourCodes`)
- **ProductGroupingService** (`app/Services/Sync/ProductGroupingService.php`): Parses grouping data, determines group type (color vs size based on `Finishes` field). `splitGroupIntoSubGroups()` uses `FinishCodes` to detect groups with both color AND size variations — splits by matching SKU suffix (after last hyphen) against FinishCodes. Products sharing the same base = color siblings (same size, different finish). Products sharing the same suffix = size siblings (same finish, different size). `fetchAndParse()` returns `{ groupSku => ['children' => [...], 'group_type' => 'color'|'size'|'both', 'color_sub_groups' => [...], 'size_sub_groups' => [...]] }`
- **ProductGroupingSyncCommand** (`php artisan products:sync-groupings`): Fetches groupings, assigns `color_group` and/or `size_group` on each product. Three code paths: (1) `both` — assigns both columns using sub-group keys `{groupSku}__{base}` for color and `{groupSku}__{suffix}` for size, (2) `color` — assigns `color_group` only, nulls `size_group`, (3) `size` — assigns `size_group` only, nulls `color_group`. Clears stale values for products no longer in any group.
- **Product model**: `color_group` and `size_group` (nullable strings, indexed). Products with the same value in either column are siblings. A product can have BOTH columns populated when it belongs to a group with both color and size variations.
- **Inline sibling linking**: `syncSiblingMetafields()` in `ShopifySyncService` runs during `createUpdateProduct()` (both create and update paths). For each group (color/size), resolves sibling GIDs via `resolveSiblingGids()`, pushes current product's metafield, and **backfills** each sibling's metafield to include the current product. No batch job — linking happens per-product during sync.

**Migration**: Adds `color_group`/`size_group` columns, backfills from old parent-child relationships, archives parent products on Shopify, drops `parent_id`/`is_parent`/`retailer_ref_variant_id` columns. Fully automated — no manual commands needed.

---

## Fieldfolio Multi-Catalog Pattern

- Catalog IDs from eSuite `StockInfoStr3` (comma-separated)
- Per-catalog data stored in `extra_configs.fieldfolio_catalogs`
- Catalog priority: `FIELDFOLIO_CATALOG_PRIORITY` in `RetailerConstants`
- Position/override_position are per-catalog (in `extra_configs`, NOT `platform_configs`)
- Draft vs Published: Always store/search draft IDs. Self-healing on published version errors.
- Badge auto-determination: StockStatus 'D'→Discontinued, qty≤0+ETA→Upcoming, qty≤0+'E'→Discontinued, qty≤0+'A'→Sold Out, campaign→Special, else blank.
- **Custom Tags**: Sourced from eSuite `StockInfoStr4`. Sent on create and update when value exists. Not pulled from Fieldfolio. No override flag. "Ending Stock" auto-appended for ending stock.

---

## Sync Log UI & Descriptions

- **createLog signature**: 9 args. 8th is `$apiMode` ('production'|'sandbox'), 9th is `$description` (plain-language summary).
- **Every sync service** builds `$description` via a private `buildXSyncDescription()` helper. Content rules: first sentence states success/failure; stock calculation in form `"Stock sent: {qty} (eSuite stock {esuite}, clamped to 0 minimum)."`; override ON/OFF state for overridable fields; image sync counts; failure error fallback chain `response.error → response.message → error → "HTTP {code}"`.
- **Show.vue** (`resources/js/Pages/SyncLog/Show.vue`):
  - Always renders a **Product** identity card at the top of the Summary with exactly 4 rows in order: **Stock No → Product Name → SKU → Barcode**. Missing values show `N/A`.
  - `SyncLogService::show()` enriches the Inertia payload with `product` resolved via `reference_id`/`reference_table` (supports `products` and `retailer_products`).
  - New logs (description present): description rendered as bullets (split regex `/(?<=\.)\s+(?=[A-Z0-9"])|(?<=\.)$/`); normalized "What was sent"/"What happened" tables hidden.
  - Legacy logs (no description): normalized tables shown.
  - Identity fields NOT duplicated in `payloadSummary`.

---

## Unit Testing Convention

### Test Infrastructure

- **Trait**: `Tests\Unit\Traits\CreatesSyncServiceWithoutConstructor` — creates service instances without constructor, injects mocks via reflection.
- **SyncLog**: Uses real SQLite in-memory `sync_logs` table. Call `$this->ensureSyncLogTable()` in `setUp()`.
- **Mocking**: Mockery for external dependencies. Access private methods via `ReflectionMethod`.
- **PHP executable**: `/c/laragon/bin/php/php-8.1.34-Win32-vs16-x64/php.exe`

### Coverage Requirements

Every sync service test must cover:
1. `syncProduct()` entry point: product not found, no retailer product, disabled product, success
2. `createUpdateProduct()`: create new, link existing, create failure, update existing, update failure
3. Pricing: compare_at when available, regular price fallback
4. `syncInventory()` entry point: with/without existing inventory
5. `syncInventoryDetails()`: API success/failure, missing config, negative qty clamped to 0

### Test Files

| Test File | Covers |
|-----------|--------|
| `BaseServiceTest.php` | Pricing engine (price bands, campaigns, edge cases) |
| `SyncServiceFactoryTest.php` | Factory match expression |
| `ShopifySyncServiceTest.php` | Shopify sync (product status, reactivation, CRUD, inventory, images, auto-category assignment) |
| `CategorySyncTest.php` | eSuite category tree parsing, auto-mapping, mapping model |
| `ProductGroupingServiceTest.php` | Product grouping parsing, color/size group detection, reverse lookup |
| `FieldfolioSyncServiceTest.php` | Badge auto-determination, catalog management, image sync |
| `AmazonSyncServiceTest.php` | SP-API product sync, inventory, image patch |
| `FreedomSyncServiceTest.php` | Batch product/inventory CSV export |
| `FantasticFurnitureSyncServiceTest.php` | Inventory-only sync, warehouse code, pricing, product name override, order pull (Dsco API) |
| `KitchenWarehouseSyncServiceTest.php` | Ordoro inventory sync, barcode-as-SKU (product CRUD disabled) |
| `TempleWebsterSyncServiceTest.php` | FTP inventory export |
| `LivingStylesSyncServiceTest.php` | FTP XLSX inventory export, modified sync, FTP CSV order pull |
| `KgGroupSyncServiceTest.php` | SFTP CSV inventory export, modified sync |
| `FeedSyncServicesTest.php` | GenericFeed no-op product sync |
| `DisabledProductScanCommandTest.php` | Disabled product scan: eSuite SP response handling, retailer product disabling, GlobalMeta timestamp |
| `FulfillmentOrderSyncTest.php` | Fulfillment order sync: helper methods, GID parsing, API failure handling, resync flow |
| `ProductImportTest.php` | Bulk import validation |
| `ProductExportTest.php` | Export data mapping, field indices |
| `AdminApiTest.php` (Feature) | Admin API auth, redaction, filters, endpoints, token command |

---

## Admin API (Read-Only Investigation)

Bearer-token-authenticated, read-only API for investigating production data. All endpoints are GET only.

### Infrastructure

- **Auth**: Sanctum bearer token + `admin-api` gate (role `super_admin`/`admin` + `admin:read` ability)
- **Middleware**: `ForceJsonResponse` in `api` group ensures 401 JSON (not 302 redirect)
- **Sanctum config**: `guard => []` (token-only, no session fallback)
- **Token command**: `php artisan admin-api:token {email}` creates token for super_admin users

### Endpoint Registry

| Route | Method | Purpose |
|-------|--------|---------|
| `GET /api/admin/v1/retailers` | `retailers` | List retailers with health status |
| `GET /api/admin/v1/retailers/{id}` | `retailerShow` | Single retailer with look_ups |
| `GET /api/admin/v1/products` | `products` | Product search (SKU, stock_no, barcode, name) |
| `GET /api/admin/v1/products/{id}` | `productShow` | Product detail with retailer products and inventories |
| `GET /api/admin/v1/sync-logs` | `syncLogs` | Sync log search (retailer, type, status, date) |
| `GET /api/admin/v1/sync-logs/{id}` | `syncLogShow` | Sync log detail with payload and description |
| `GET /api/admin/v1/inventory/discrepancies` | `inventoryDiscrepancies` | Find qty mismatches between DB and retailer |
| `GET /api/admin/v1/orders` | `orders` | Order search (name, status, retailer, date) |
| `GET /api/admin/v1/orders/{id}` | `orderShow` | Order detail with payload |
| `GET /api/admin/v1/system/health` | `systemHealth` | Error counts, retailer status, global meta |
| `GET /api/admin/v1/look-ups` | `lookUps` | List reference mappings (locations, companies, GST) |
| `GET /api/admin/v1/category-mappings` | `categoryMappings` | eSuite category mappings (requires retailer_integration_id) |
| `GET /api/admin/v1/system/global-meta` | `globalMeta` | All GlobalMeta entries (timestamps, flags) |
| `GET /api/admin/v1/activity-logs` | `activityLogs` | User activity audit trail (who changed what) |

### Safety Rules

- **Credentials**: Always redacted (`[REDACTED]`) on RetailerIntegration responses. `credentials_present` (bool) indicates if credentials exist.
- **esuite_data**: Always excluded from product list/show responses (large JSON).
- **Appends suppressed**: `setAppends([])` on Product (`inventory_quantity`), RetailerProduct (`category_name`), RetailerIntegration (`platform_schema`, `has_retailer_settings`).
- **Payload truncation**: Sync log and order payloads truncated at 50KB with `_truncated: true` flag.
- **withTrashed**: Used on products, retailers, and orders (investigations need soft-deleted records).

### MCP Server

Local Node.js MCP server at `tools/highgrove-mcp/index.js`. Wraps all 14 API endpoints + a lesson reader as Claude Code tools.

- **Env vars**: `HIGHGROVE_API_URL`, `HIGHGROVE_ADMIN_TOKEN`
- **Config**: `.mcp.json` (gitignored), `.mcp.json.example` (committed)
- **Register**: `claude mcp add --scope project highgrove -e HIGHGROVE_API_URL=... -e HIGHGROVE_ADMIN_TOKEN=... -- node tools/highgrove-mcp/index.js`

### Investigation Lessons

`docs/lessons/` directory contains playbooks for known data traps. Read `docs/lessons/README.md` before investigating any issue. Create a new lesson after resolving a new issue type.
