# Gozaresh implementation va rahnamaye release

Tarikh: 2026-09-17. Hameye ejra-ha local boodand; production deploy ya taghir dade nashode ast.

## 1. Hotfix fori admin 403

Root cause: model `User` contract-e `FilamentUser` ra implement nemikard. Filament dar environment-e gheyr-local dastresi panel ra rad mikard.

- `User::canAccessPanel()` va `canAccessAdmin()` ezafe shodand.
- Dastresi faghat baraye `is_active = true` VA role-e `admin` dar guard-e `web` ast.
- `EnsureActiveAdmin` dar request-haye panel va Livewire persistent ast; endpoint-haye admin kharej az panel ham hamoon shart ra darand.
- `APP_ENV=prod` va `APP_ENV=production` har do test shodand. Bargasht be `local` rah-e hal production nist.
- Hich user-i khodkar admin ya active nashode ast.

Baraye release-e mostaghel-e hotfix, faghat in se file lazem ast; migration nemikhahad:

1. `app/Models/User.php`
2. `app/Http/Middleware/EnsureActiveAdmin.php`
3. `app/Providers/Filament/AdminPanelProvider.php`

Bad az deploy hotfix:

```sh
php artisan optimize:clear
php artisan permission:cache-reset
php artisan config:cache
```

Role va active boodan account-e admin ra ba dastresi mojaz check konid. Baraye full release, hameye file-ha va migration-haye zir lazem-and; hotfix-e se-file-i faghat panel ra cover mikonad.

## 2. Feature-ha va tasmim-ha

### Category va wholesale

- Haman `product_categories.parent_category_id` hefz shod; URL jadid-e hierarchy tahmil nashod.
- Cycle, self-parent va parent-e namojood rad mishavand. Delete-e category ba product ya child block mishavad.
- Parent selector descendant-ha ra hazf mikonad; list admin depth ra neshan midahad va sort/active filter darad.
- Inactive category public nist. Active boodan farzand mostaghel ast; gheyrfaal kardan parent khodkar child-ha ra gheyrfaal nemikonad.
- Rule-e wholesale default OFF ast. Minimum configurable, default 5, minimum mojaz 1 ast.
- Scope faghat category-e mostaghim ast, na descendants. Product dar schema-e mojood yek category darad; variant-e joda vojood nadarad.
- Distinct product ID hesab mishavad, na quantity. Product-e inactive, deleted, out-of-stock ya ba quantity bishtar az stock qualify nemishavad.
- Har category mostaghel check mishavad. UI category/product/cart/checkout progress va link neshan midahad; AJAX progress ra refresh mikonad.
- Checkout ba lock-e user/cart/product/category, stock va rule ra dobare server-side check mikonad.

### Blog va navigation

- Model/resource/editor/media-e mojood reuse shod. Draft default ast; public shodan niaz be `is_active`, `status=published` va `published_at <= now()` darad.
- Blog category, excerpt, author, related product/category/article va SEO field-ha ezafe shodand.
- Body sanitizer HTML-e khatarnak ra hazf va H1-e dakhele matn ra be H2 tabdil mikonad. H1-e asli az title miayad.
- Delete-e author digar blog ra cascade-delete nemikonad.
- `menus` haman item-haye ghadimi ast; `navigation_menus` collection/location jadid ast. Hich table-e parallel baraye item-ha sakhte nashod.
- `/admin/navigation-builder`: entekhab menu, drag/drop, reorder ba keyboard, parent selection, save, publish/unpublish. Add/edit label/link az resource-e Menu anjam mishavad.
- Location-haye `header` va `footer` render mishavand; location-e delkhah niaz be estefade az component dar template darad.
- Save dar menu-e published foran apply mishavad; draft-version-e joda baraye menu nist. Baraye edit-e gheyr-public aval unpublish konid.
- Parent bayad dar haman menu bashad; cycle/orphan/ID-e tampered rad mishavad. URL faghat internal ya http/https ast.
- Cache structure invalid mishavad; URL target az entity-e jari resolve mishavad. Target-e deleted/inactive/publish-nashode link nemisazad.
- Ta menu publish nashode, fallback-e header/footer hefz mishavad. Nesting ba link-e vaghei va `details/summary` kar mikonad.

### SEO

- Meta/canonical/robots/OG/Twitter server-rendered ast; priority: field-e sarihe entity, data-e entity, fallback-e site.
- Route-haye ghadimi hefz shodand. Taghir slug ya category-e product redirect 301 misazad; chain-ha flatten mishavand.
- Origin-e canonical az `APP_URL` ast. Normalization-e host/scheme/trailing slash faghat ruye public GET/HEAD-e catalog/blog/home ast, na admin/payment POST.
- Search/filter/sort noindex,follow ast. Tracking query az canonical hazf mishavad. Pagination-e unfiltered self-canonical ba `?page=N` darad.
- Category-e khali noindex ast. Missing/inactive product/category va draft/future blog 404 midahand.
- Sitemap faghat active/published/indexable/self-canonical entity-ha ra darad. `lastmod` az timestamp-e vaghei ast.
- `robots.txt` dynamic shod; file-e static `public/robots.txt` hazf shod. Local/testing `Disallow: /` darad.
- Schema: Organization/WebSite, BreadcrumbList, Product/Offer, BlogPosting. Rating faghat az review-e vaghei; brand/stock/price az data-e vaghei.
- UI gheymat toman ast; schema-e IRR va gateway az `app.price_convert_amount` estefade mikonand. Discount-null be base price fallback mikonad.
- FAQ schema/hreflang ezafe nashodand chon data/sharayet-e lazem ehraz nashod.
- Image uploader dimension-e asli ra save va resize-ha ra az clone-e asli misazad; old media bedune dimension-e sakhtegi hefz mishavad.

### Cart, coupon, review va payment

- JSON-e cart digar double-wrap nist: `products` array va `wholesale_rules` array. Cookie malformed/missing product/media handle mishavad.
- Guest merge quantity ra jam va be stock mahdood mikonad. Add/update/remove-e authenticated ba lock-e user serial mishavand.
- Quick-view, empty cart, quantity/delete dar my-cart va gheymat-e namayesh-dade-shode fix shodand.
- Shipping address bayad male user ya guest address-e sabt-shode dar haman session bashad. Retry invoice faghat baraye owner-e invoice-e pardakht-nashode ast.
- Coupon: relation-e eshtebah fix shod; percentage/fixed_amount, active/date/min/max discount va usage limits validate mishavand. Form-e admin ba schema hamahang shod.
- Coupon dar sakht-e movafagh-e order + daryaft token masraf mishavad, na callback. Token failure transaction ra rollback mikonad. Unpaid invoice discount-e khod ra hefz mikonad; retry masraf-e jadid nist. Cancel/abandon coupon ra khodkar bargardani nemikonad; siyasat-e release/recredit-e joda implement nashode ast.
- Blog review digar be service-e product ba type-e eshtebah nemiravad. Form ID-e dorost mifrestad; error be onvan success neshan dade nemishavad.
- Product review-e jadid niaz be invoice-e paid darad. Rating cache bad az save/delete invalidate mishavad. API review contact info-e user ra neshan nemidahad; label-e verified-e bedune madarak hazf shod.
- Invoice/order faghat bad az verify-e movafagh, match-e amount/terminal/reference va stock check paid mishavand. Callback-e tekrar stock ra dobare kam nemikonad.
- `verified_ref` unique faghat baraye payment-haye jadid ast. Reference-haye legacy dast-nakhorde mandand; reuse-e reference-e legacy ham rad mishavad.
- Payment/SMS dar local fake ast. Fake token faghat order-e pending misazad; fake verify hich invoice-i ra paid nemikonad.

## 3. Migration-ha

1. `2026_09_17_000001_extend_catalog_content_navigation.php`: category/wholesale, publication/blog category/pivot, SEO, navigation collection, redirect table. Duplicate blog slug ghabl az DDL check mishavad; auto-rename nadarim. Blog-e active-e ghadimi published mishavad va published_at az created_at migirad.
2. `2026_09_17_000002_unique_payment_references.php`: nullable unique `payment_transactions.verified_ref`; no delete/deduplicate-e legacy.
3. `2026_09_17_000003_preserve_content_and_image_dimensions.php`: author FK-e nullOnDelete, nullable meta_description-e blog, original image dimensions.

Migration az MySQL khali, upgrade-e snapshot va rollback/re-apply-e se migration jadid dar DB-e disposable pass shod. Clean SQLite dar suite ham pass mishavad.

DB-haye local baraye validation: `ecom_seo_validation_20260917` (clone-e snapshot) va `ecom_seo_clean_20260917` (clean MySQL). Se migration ruye DB-e asli local ham ejra shodand. Production taghir nakarde ast.

Moghayese-e count-e DB-e local ba clone: products 121/121, categories 8/8, blogs 2/2, orders 9/9, invoices 32/32, payment_transactions 15/15.

Backup-e local ghabl az migration: `/tmp/ecom-before-seo-20260917.sql`, permission 600. File hamele data-e snapshot ast; nabayad commit ya public share shavad. Clone-ha khodkar delete nashodand.

## 4. Route-ha va compatibility

- Jadid: GET `/blogs/category/{blogCategory}` (`site.blog.category`), GET `/robots.txt` (`robots`), page-e Filament `/admin/navigation-builder`, resource `/admin/blog-categories`.
- GET `/products/{product}/reviews` ghabl az route-e generic va faghat baraye ID-e adadi resolve mishavad.
- `/import-cat` va `/import-product` faghat POST-e authenticated active-admin hastand; GET 405 midahad. Client-e import bayad CSRF token befrestad.
- `/checkout/old-invoice/{invoice}` auth/ownership check darad.
- Review route-name-e blog be `reviews.blog.store` tashih shod; URL-e POST `/reviews/blog` hefz shod.
- Public URL-haye `/products/{category}/{slug}`, `/products/{category}`, `/blogs`, `/blogs/{slug}` hefz shodand.

## 5. Local setup-e safe

`.env` va DB dump ra dar git nagozarid. Credential-haye production ra baraye local reuse nakonid.

```dotenv
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost
PAYMENT_FAKE=true
SMS_FAKE=true
MAIL_MAILER=log
QUEUE_CONNECTION=database
SESSION_DRIVER=database
CACHE_STORE=database
TELESCOPE_ENABLED=false
```

- Docker: DB_HOST=mysql, DB_PORT=3306 va database/user/password-e LOCAL. Host CLI az connection-e local-e monaseb estefade konad.
- `docker compose up -d`, `composer install`, `npm ci`, `npm run build`. Dependencies-e jadid baraye feature-ha ezafe nashode ast.
- Dump ra faghat dar database-e local-e jadid import konid. DEFINER-e routine/trigger-e production ra ba user-e local-e mojaz adapt konid; be user-e app SUPER nadahid.
- Ghabl az `migrate`, `migrate:status` ra check konid. Migration-e tarikhche-e `2025_10_03_062102_update_products_prices` destructive ast; nabayad ruye snapshot dobare replay shavad.
- Files-e media bayad dar `storage/app/public` copy shavand. `public/storage` dar Docker be in directory link ast. App az ghabl override-e `path.public` be root darad; `storage:link` ra bedune check-e document-root va config ejra nakonid.
- Local mail dar service provider ham `log` mishavad. Worker-e production ya queue-e imported ra dar local run nakonid. Agar background QA lazem ast, faghat queue-e khali va joda ba fake-ha run shavad.
- Scheduled publication query-based ast va cron jadid nemikhahad. `routes/console.php` schedule-e business-e jadidi nadarad.
- Dar local ba `APP_ENV=prod` ham fake-ha ra sarihan true negah darid. Dar production `APP_DEBUG=false`, PAYMENT_FAKE=false, SMS_FAKE=false va APP_URL-e HTTPS-e dorost zaroori ast.

## 6. Backfill

```sh
php artisan site:backfill-content
php artisan site:backfill-content --apply
```

Command-e aval dry-run ast. Dovomi Home/Blog/category tree ra faghat agar header item nadashte bashad misazad. Menu unpublished mimanad. Existing items replace nemishavand; rerun idempotent ast. Tree-e invalid command ra motevaghef mikonad.

`--apply` faghat ruye clone-e validation ejra shode, na DB-e asli local ya production. Bad az review dar builder publish konid. Wholesale rule-ha ra ba entekhab-e admin enable konid; hich category khodkar wholesale nashode ast.

## 7. Test va QA

Suite-haye jadid: `AdminAccessTest`, `CatalogContentSeoTest`, `NavigationTest`, `WholesaleCheckoutTest`, `CouponCheckoutTest`, `ReviewFlowTest`, `PaymentSafetyTest`.

Natije-e nahayi: **51 test, 421 assertion pass**. PHP lint ruye 87 file pass shod; build-e Mix va `git diff --check` pass shodand. Route cache dar file-e temporary-e joda sakhte shod va pass shod. Warning-e build faghat database-e Browserslist-e ghadimi bood; dependency update-e namertabet anjam nashod.

```sh
vendor/bin/phpunit --do-not-cache-result
npm run build
git diff --check
```

PHPUnit DB ra sarihan be SQLite `:memory:` force mikonad; HTTP-e bedoone fake block ast; mail/notification fake hastand. Test-haye price import/export-e ghadimi hefz shodand va path-e fixture-ha ba move-e ghabli-e specs hamahang shod.

| Check | Natije |
| --- | --- |
| Admin local/testing/prod/production + login-e vaghei Livewire | Pass; active-admin mojaz, client/inactive rad |
| Category tree/cycle/move/delete, slug 301 va Persian slug | Automated coverage |
| Draft/scheduled/public blog, HTML/H1, meta/canonical/sitemap/schema | Automated coverage |
| Menu order/nest/cache/target invalidation/invalid payload | Automated coverage |
| Wholesale 1/4/5, duplicate quantity, multiple categories, stale stock | Automated coverage |
| Guest merge, authenticated add/update/delete, ownership/bypass | Automated coverage |
| Coupon limits/calculation/rollback va review flows | Automated coverage |
| Verify failure/mismatch/replay/stock once | Mocked HTTP tests; bank-e vaghei test nashode |
| MySQL clean + snapshot upgrade + new migrations rollback/re-apply | Pass |
| Browser 1440px va 390px: home/catalog/blog/checkout/admin login/product/category | 200, JSON-LD parse, canonical/H1 check; pageerror nadarad |
| Browser 1440px va 390px: quick-view + guest add/update/delete | Pass; mobile close-button ham fix shod |
| Laravel log | Khataye jadid-e unexpected az browser nist; negative payment test log-e entezari misazad |
| Images-e snapshot | Pending: storage-e production dar local kamel nist; request-haye image 403 darand |

## 8. Release gate va mavared-e baghimande

- Full release hanooz production-certified nist. SEP faghat ba response-e mocked test shode; payload-e vaghei-e `VerifyTransaction` (Success/ResultCode/TransactionDetail/OrginalAmount/TerminalNumber/RefNum va ResNum agar mojood bashad) bayad ba fixture-e mojaz ya sandbox-e bank tatbigh dade shavad. Hich bank/SMS-e vaghei dar in QA seda zade nashod.
- Snapshot 5 approved transaction ba yek ref_num-e tekrar darad. Code legacy ra taghir nadade; reconciliation-e mali-e mostaghel lazem ast. Tamamiyat-e data-e legacy az test-ha natije nemishavad.
- Inventory dar token issuance reserve nemishavad; dar verify lock va decrement mishavad. Agar stock ta callback tamam shode bashad, invoice paid nemishavad va reconciliation/refund-e operatouri lazem ast. Automatic bank reversal implement nashode ast.
- File-haye asli media bayad local copy shavand; visual QA-e kamel, image sizing/quality va Rich Results/live crawl bad az an tekrar shavand. Baraye penhan kardan in moshkel file-e fake sakhte nashod.
- Stress-test-e multi-process MySQL baraye contention, QA-e browser-e authenticated checkout ba account-e test, va flow-e vaghei-e OTP/password reset/file upload/queue hanooz manual gate hastand; unit/feature test jaygozin in-ha nist.
- Fallback-e shipping-e mojood 0 hefz shod; tarif-e shipping ya variant system-e jadid sakhte nashod. Business bayad in siyasat va coupon reservation-e order-time ra ghabl az full release taeed konad.
- Old media dimensions backfill nashode chon file-ha local vojood nadarand. FAQ schema, hreflang, tags va inherited wholesale amdan implement nashodand.

## 9. Manual QA checklist

- [ ] Active admin ba APP_ENV=production login konad; client/inactive dar panel va media/invoice endpoint 403 begirad.
- [ ] Category root/child/grandchild besazid; move, self/cycle rejection, search/sort/active va safe delete ra check konid.
- [ ] Draft/published/future blog, author, upload/inline image, related links va duplicate slug ra dar admin test konid.
- [ ] Header/footer ra unpublish/edit/nest/reorder/publish konid; desktop/mobile/keyboard va fallback ra check konid.
- [ ] Rule-e wholesale 4 ya 5 ra enable konid; quantity-e yek product nabayad distinct count ra ziad konad. Har do category bayad pass shavand.
- [ ] Guest cart -> login merge, my-cart quantity/remove, missing/inactive/low-stock product va address-e gheyr ra test konid.
- [ ] Coupon valid/expired/used/capped/fixed va token failure/retry ra check konid; unpaid invoice retry nabayad discount ra dobare masraf konad.
- [ ] Payment-e staging: success/failure/cancel/duplicate/mismatch/stock shortage; amount, order status, stock va receipt ra reconcile konid.
- [ ] Persian URL/301, canonical HTTPS/www, page=2/filter noindex, empty category, draft 404, robots va sitemap ra crawl konid.
- [ ] Behind reverse proxy, scheme/host-e Laravel bayad dorost bashad; trust-e proxy ra faghat baraye proxy-haye mojaz set konid ta redirect loop ijad nashavad.
- [ ] Console/log/image 403/404 va structured data ra bad az copy-e media va build-e release dobare check konid.

## 10. Full deployment va rollback

1. Aval release gate-ha ra pass konid; agar faalan faghat 403 blocker ast, hotfix-e mostaghel ra deploy konid.
2. Backup-e DB/files va release-e ghabli; maintenance window va barresi payment-haye dar hale anjam. Deploy ra ruye snapshot rehearsal konid.
3. Env: APP_ENV=production (prod ham supported), APP_DEBUG=false, APP_URL-e asli HTTPS, credential-haye khod-e production, PAYMENT_FAKE=false, SMS_FAKE=false. APP_KEY-e production ra regenerate nakonid.
4. Artifact-e build-shode ba dependency-haye lock-shode ra deploy konid. Physical robots.txt-e ghadimi nabayad route-e dynamic ra shadow konad.

```sh
php artisan down
composer install --no-dev --prefer-dist --optimize-autoloader
php artisan optimize:clear
php artisan migrate:status
php artisan migrate --force
php artisan permission:cache-reset
php artisan site:backfill-content
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:restart
php artisan up
```

5. Backfill-e `--apply` optional ast va ba review-e admin; publish/wholesale enable ra jadagane anjam dahid. Smoke-test-e login/admin/catalog/cart/checkout/robots/sitemap va log monitoring zaroori ast.
6. Rollback-e tarjihi: code/artifact-e ghabli ba schema-e additive-e hefz-shode, va clear/rebuild cache. Changes-e payment/order ra ba backup raastazmaei konid; DB-e live ra bedoone reconciliation restore nakonid.
7. `migrate:rollback` ra blindly ruye production ejra nakonid: new metadata/relations/menu settings/redirect history hazf mishavand, verified_ref protection bardashte mishavad va migration 3 author-delete behavior ra be cascade barmigardanad. Nullable meta_description dar down amdan nullable mimanad ta matn-e jadid az dast naravad.

Liste file-haye taghiryafte dar `CHANGED-FILES.md` ast. Move-haye ghabli-e specs va fixture-ha male user hastand va revert nashodand.