feat(shop): cart and checkout shipping flow

Guest/user cart (carts table) with add/update/remove, header count badge,
and merge of the guest cart into the account on login. Product buy box
mirrors the cart per variety. Checkout shipping step picks an address (or
adds one inline) and a per-destination shipping method, seeded in admin
ShippingSeeder. Persian validation messages for the address form.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: bahman026

admin/database/seeders/DatabaseSeeder.php

@@ -21,6 +21,7 @@ public function run(): void
             AncestorSeeder::class,
             AttributeSeeder::class,
             AttributeGroupCategorySeeder::class,
+            ShippingSeeder::class,
             SettingSeeder::class,
         ]);
     }

admin/database/seeders/ShippingSeeder.php

@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Database\Seeders;
+
+use App\Models\Province;
+use App\Models\ShippingCity;
+use App\Models\ShippingLine;
+use App\Models\ShippingMethod;
+use Illuminate\Database\Seeder;
+
+class ShippingSeeder extends Seeder
+{
+    /**
+     * Seed the three storefront shipping methods. Costs are placeholder demo
+     * values; descriptions and delivery windows match the storefront design.
+     */
+    public function run(): void
+    {
+        ShippingCity::query()->delete();
+        ShippingMethod::query()->delete();
+        ShippingLine::query()->delete();
+
+        $tehran = Province::query()->where('name', 'تهران')->value('id');
+
+        // پیک ویژه تهران: same-day style courier, Tehran only.
+        $courier = ShippingLine::query()->create([
+            'name' => 'پیک ویژه تهران',
+            'cost' => 50000,
+        ]);
+        $courierMethod = ShippingMethod::query()->create([
+            'shipping_line_id' => $courier->id,
+            'name' => 'پیک ویژه تهران',
+            'type' => 'پیک',
+            'status' => true,
+        ]);
+        ShippingCity::query()->create([
+            'shipping_method_id' => $courierMethod->id,
+            'province_id' => $tehran,
+            'amount' => 50000,
+            'sending_days' => '۲۴ ساعت کاری',
+            'description' => 'تحویل ۲۴ ساعت کاری پس از ثبت سفارش (روزهای تعطیل جزو زمان آماده‌سازی و ارسال محاسبه نمی‌شوند). سفارش‌هایی که در روزهای تعطیل رسمی ثبت شوند، در اولین روز کاری بعد پردازش و روز کاری پس از آن ارسال خواهند شد.',
+            'status' => true,
+        ]);
+
+        // پست پیشتاز: nationwide.
+        $post = ShippingLine::query()->create([
+            'name' => 'پست',
+            'cost' => 45000,
+        ]);
+        $postMethod = ShippingMethod::query()->create([
+            'shipping_line_id' => $post->id,
+            'name' => 'پست پیشتاز',
+            'type' => 'پست',
+            'status' => true,
+        ]);
+        ShippingCity::query()->create([
+            'shipping_method_id' => $postMethod->id,
+            'amount' => 45000,
+            'sending_days' => '۲ تا ۴ روز کاری',
+            'description' => 'ارسال از طریق پست پیشتاز (۲ تا ۴ روز کاری).',
+            'status' => true,
+        ]);
+
+        // تحویل حضوری از فروشگاه: nationwide, postpaid (pay on delivery).
+        $pickup = ShippingLine::query()->create([
+            'name' => 'تحویل حضوری از فروشگاه',
+            'cost' => 0,
+        ]);
+        $pickupMethod = ShippingMethod::query()->create([
+            'shipping_line_id' => $pickup->id,
+            'name' => 'تحویل حضوری از فروشگاه',
+            'type' => 'حضوری',
+            'status' => true,
+        ]);
+        ShippingCity::query()->create([
+            'shipping_method_id' => $pickupMethod->id,
+            'pay_on_delivery' => true,
+            'amount' => null,
+            'description' => 'تحویل حضوری (شنبه تا چهارشنبه، به‌جز روزهای تعطیل) — بعد از آماده‌سازی، زمان تحویل با شما از طرف فروشگاه هماهنگ می‌شود. هزینه ارسال به صورت پس‌کرایه می‌باشد.',
+            'status' => true,
+        ]);
+    }
+}

shop/AGENTS.md

@@ -190,6 +190,9 @@ This is `shop/`, the customer-facing storefront (Laravel 13 + Inertia). The Fila
 - **Auth is mobile-first** (`AuthController`, routes under `/login`). OTP is the primary path (and registers on first login); password login is an alternative. Codes live in cache via `SendOtpCode`/`VerifyOtpCode` and are "sent" by a logged stub - replace with a real SMS provider later. The shared `users` table has NOT NULL `email`/`password` and a non-unique `mobile`, so OTP sign-ups seed placeholders (`User::placeholderEmail`) and a random password. `auth.user` + auth `flash` are shared in `HandleInertiaRequests`.
 - **Account area** lives under `/account` (auth middleware, `AccountController`). `AccountLayout.vue` is the shared shell (sidebar nav + user card + logout) wrapping `AppLayout`; account pages are `noindex`. Built: dashboard (`Account/Dashboard.vue`) and profile edit (`Account/Profile.vue`, edits name/email; mobile read-only; placeholder email hidden via `User::hasPlaceholderEmail`). Not-yet-built sidebar links render `Account/ComingSoon.vue`. Profile saves flash a generic `status` message (shared in `HandleInertiaRequests`); `UserDTO` shapes the user payload.
 - **Addresses** (`AddressController`, `/account/addresses`) are immutable history: editing creates a NEW row (`UpdateUserAddress`) that inherits `prime` and soft-deletes the old one (kept for order history, hidden from the active list). First address auto-primary; one primary per user via the model `saved` hook; any address can be promoted from the list (`setPrimary`, `PUT /account/addresses/{address}/primary`); delete is soft-only (`destroy`, `DELETE /account/addresses/{address}`) to preserve order history, and deleting the default promotes the newest remaining address. The shared table has no plate/unit columns, so those round-trip through `description` as JSON (`App\Support\AddressDescription`); recipient name uses the account name (no per-address column). Province/city are cascading (`/account/addresses-cities`). **Neshan maps**: the location (lat/long) is a section separate from the province/city selects. Two key types. Picking a point on either map sets lat/long and auto-fills the address via reverse geocoding (`ReverseGeocode`, `/account/addresses-reverse`, service key). With a `web.` map key (`services.neshan.map_key`, `NESHAN_MAP_KEY`, shared per-page) the form shows the interactive `NeshanMap.vue` (draggable marker, client-side tiles, fast). Without a `web.` key the form falls back to `MapPicker.vue`: a draggable Neshan static map (proxied `StaticMap` -> `/account/addresses-static`, service key) with a fixed center pin (the selected point is always the map center), drag-to-pan (pixel delta -> lat/long via Web Mercator) and zoom buttons; the proxy caches images (30 days) and fails gracefully on timeout (the static plan is slow, so the web key is preferred). All Neshan calls use the server-side `service.` key (`NESHAN_SERVICE_KEY`); only the `web.` key ever reaches the browser. Note: `service.` keys are IP-scoped in the Neshan panel, the server's (public) egress IP must be allowed. The nullable `latitude`/`longitude` columns live on the admin-owned `addresses` table (in the `create_addresses_table` migration).
+- **Cart** (`carts`, admin-owned: one row per variety line) works for guests and users. `ResolveCartOwner` keys the cart by `user_id` when logged in, else the guest `session_id`; on login `MergeGuestCart` (called from `AuthController@login` with the pre-regeneration session id) folds the guest lines onto the account, combining and clamping to inventory. `CartController` (`/cart`) + `Cart/` actions (`AddToCart`, `GetCartLines`, `BuildCartSummary`) drive add/update/remove; quantity is always clamped to the variety `inventory` server-side. The cart is inventory-neutral (never touches `varieties.inventory`; see `ORDER.md`). Pricing per line is the variety `sale_price ?? price` via `CalculatePricing`; `CartSummaryDTO` totals items, savings and payable. `Cart/Index.vue` renders the checkout stepper (`CheckoutSteps.vue`), `CartLine.vue` rows and `CartSummary.vue`. Add-to-cart is wired in the product `BuyBox` (requires a selected variety). The header badge reads the shared `cart.count` prop (`HandleInertiaRequests`, guarded by `rescue`).
+- **Checkout** (`/checkout`, auth) is being built. Step 2 is shipping (`CheckoutController@shipping` + `Checkout/Shipping.vue`): pick a saved address (or add one inline when none exist, reusing `AddressFormModal`) and a shipping method; an empty cart redirects back to `/cart`. Shipping methods are resolved per destination by `GetShippingMethods` over the admin-owned `shipping_lines → shipping_methods → shipping_cities` hierarchy (most specific scope wins: exact city > province > nationwide null/null); cost `null` + `pay_on_delivery` means postpaid ("پس‌کرایه"), `0` means free. Changing the address refreshes the list via `/checkout/methods` (JSON, like the cities endpoint). The selected `address_id` + `shipping_method_id` are validated (method must be available for the address) and stored in the session; the cost is added to the summary payable (`CartSummary` `showShipping`/`shipping` props). Seed data is in admin `ShippingSeeder` (پیک ویژه تهران Tehran-only، پست پیشتاز nationwide، تحویل حضوری از فروشگاه pay-on-delivery). The payment step (`Checkout/Payment.vue`) is a placeholder until the gateway/receipt flow (Phase 4); order creation and coupons are not built yet. Shop has read-only models `ShippingLine`/`ShippingMethod`/`ShippingCity` for these shared tables.
+- **PWA / install** is wired via `public/manifest.webmanifest` + `public/icons/*` + Apple meta tags in `app.blade.php`. `InstallPrompt.vue` (mounted in `AppLayout`) is an iOS-Safari-only guided "Add to Home Screen" bottom-sheet (iOS has no native prompt); it skips standalone mode and snoozes 7 days after dismissal (`localStorage`). Android/desktop Chrome rely on the native manifest install prompt.
 
 ## Frontend (Inertia + Vue)
 

shop/app/Actions/Cart/AddToCart.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions\Cart;
+
+use App\Models\Cart;
+use App\Models\Variety;
+
+class AddToCart
+{
+    /**
+     * Add (or increase) a variety line for the given owner. Quantity is clamped
+     * to the variety's available inventory; never touches inventory itself.
+     *
+     * @param  array{user_id: int}|array{session_id: string}  $owner
+     */
+    public function __invoke(array $owner, Variety $variety, int $count): Cart
+    {
+        $line = Cart::query()
+            ->where($owner)
+            ->where('variety_id', $variety->id)
+            ->first();
+
+        $current = $line === null ? 0 : $line->count;
+        $desired = $current + max(1, $count);
+        $clamped = max(1, min($desired, $variety->inventory));
+
+        if ($line === null) {
+            return Cart::query()->create([
+                ...$owner,
+                'variety_id' => $variety->id,
+                'count' => $clamped,
+            ]);
+        }
+
+        $line->update(['count' => $clamped]);
+
+        return $line;
+    }
+}

shop/app/Actions/Cart/BuildCartSummary.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions\Cart;
+
+use App\DTOs\CartLineDTO;
+use App\DTOs\CartSummaryDTO;
+use Illuminate\Support\Collection;
+
+class BuildCartSummary
+{
+    /**
+     * Totals for a set of cart lines. Discount is the saving from variety sale
+     * prices; coupons are not applied here.
+     *
+     * @param  Collection<int, CartLineDTO>  $lines
+     */
+    public function __invoke(Collection $lines): CartSummaryDTO
+    {
+        $itemsTotal = (int) $lines->sum(fn (CartLineDTO $line): int => $line->lineOriginalTotal());
+        $payable = (int) $lines->sum(fn (CartLineDTO $line): int => $line->lineTotal());
+
+        return new CartSummaryDTO(
+            count: (int) $lines->sum(fn (CartLineDTO $line): int => $line->count),
+            itemsTotal: $itemsTotal,
+            discount: $itemsTotal - $payable,
+            payable: $payable,
+        );
+    }
+}

shop/app/Actions/Cart/GetCartLines.php

@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions\Cart;
+
+use App\Actions\Catalog\CalculatePricing;
+use App\Actions\Catalog\TransformImage;
+use App\Actions\Product\VarietyAttributes;
+use App\DTOs\CartLineDTO;
+use App\Models\Attribute;
+use App\Models\Cart;
+use App\Models\Variety;
+use Illuminate\Support\Collection;
+
+class GetCartLines
+{
+    public function __construct(
+        private CalculatePricing $pricing,
+        private TransformImage $transformImage,
+        private VarietyAttributes $varietyAttributes,
+    ) {}
+
+    /**
+     * The cart lines for an owner, newest first, shaped for the storefront.
+     *
+     * @param  array{user_id: int}|array{session_id: string}  $owner
+     * @return Collection<int, CartLineDTO>
+     */
+    public function __invoke(array $owner): Collection
+    {
+        return Cart::query()
+            ->where($owner)
+            ->with([
+                'variety.product.featuredImage',
+                'variety.image',
+                'variety.attribute.attributeGroup',
+                'variety.attributes.attributeGroup',
+            ])
+            ->latest()
+            ->get()
+            ->map(fn (Cart $line): CartLineDTO => $this->line($line))
+            ->values();
+    }
+
+    private function line(Cart $line): CartLineDTO
+    {
+        $variety = $line->variety;
+        $product = $variety->product;
+        $pricing = $this->pricing->forVariety($variety);
+
+        $image = $this->transformImage->__invoke(
+            $variety->image ?? $product->featuredImage,
+        );
+
+        return new CartLineDTO(
+            id: $line->id,
+            varietyId: $variety->id,
+            heading: $product->heading,
+            url: '/products/'.$product->slug,
+            image: $image,
+            color: $variety->color,
+            attributes: $this->attributes($variety),
+            unitPrice: $pricing['salePrice'] ?? $pricing['price'],
+            originalPrice: $pricing['price'],
+            discountPercent: $pricing['discountPercent'],
+            count: $line->count,
+            inventory: $variety->inventory,
+            inStock: $variety->has_stock && $variety->inventory > 0,
+        );
+    }
+
+    /**
+     * @return array<int, array{group: string|null, value: string}>
+     */
+    private function attributes(Variety $variety): array
+    {
+        return collect($this->varietyAttributes->__invoke($variety))
+            ->map(fn (Attribute $attribute): array => [
+                'group' => $attribute->attributeGroup?->name,
+                'value' => $attribute->value,
+            ])
+            ->all();
+    }
+}

shop/app/Actions/Cart/MergeGuestCart.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions\Cart;
+
+use App\Models\Cart;
+use App\Models\User;
+
+class MergeGuestCart
+{
+    /**
+     * Move a guest session's cart lines onto the user after login. When the
+     * same variety already exists for the user, quantities are combined and
+     * clamped to the variety's inventory.
+     */
+    public function __invoke(User $user, ?string $sessionId): void
+    {
+        if ($sessionId === null || $sessionId === '') {
+            return;
+        }
+
+        $guestLines = Cart::query()
+            ->where('session_id', $sessionId)
+            ->whereNull('user_id')
+            ->with('variety')
+            ->get();
+
+        foreach ($guestLines as $guestLine) {
+            $existing = Cart::query()
+                ->where('user_id', $user->id)
+                ->where('variety_id', $guestLine->variety_id)
+                ->first();
+
+            if ($existing === null) {
+                $guestLine->update([
+                    'user_id' => $user->id,
+                    'session_id' => null,
+                ]);
+
+                continue;
+            }
+
+            $cap = $guestLine->variety->inventory;
+            $existing->update([
+                'count' => max(1, min($existing->count + $guestLine->count, $cap)),
+            ]);
+            $guestLine->delete();
+        }
+    }
+}

shop/app/Actions/Cart/ResolveCartOwner.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions\Cart;
+
+use App\Models\User;
+use Illuminate\Http\Request;
+
+class ResolveCartOwner
+{
+    /**
+     * The column/value pair that identifies the current cart: the user id when
+     * logged in, otherwise the guest session id.
+     *
+     * @return array{user_id: int}|array{session_id: string}
+     */
+    public function __invoke(Request $request): array
+    {
+        $user = $request->user();
+
+        if ($user instanceof User) {
+            return ['user_id' => $user->id];
+        }
+
+        return ['session_id' => $request->session()->getId()];
+    }
+}