معماری Headless Commerce چیست؟ راهنمای انتخاب، TCO و مهاجرت

Headless Commerce چیست؟

در معماری Headless Commerce، Commerce backend—Catalog، Price، Cart، Promotion، Inventory و Order—به‌صورت مستقل از لایهٔ نمایش کار می‌کند. Storefront وب، اپ موبایل، کیوسک یا کانال دیگر از طریق API و Event با آن ارتباط می‌گیرد.

این تعریف فقط «جدا بودن Front-end» را تضمین می‌کند. ممکن است Backend همچنان یک پلتفرم یکپارچه باشد؛ ممکن است ده سرویس مستقل داشته باشید. Headless با Microservices و Composable مترادف نیست.

Headless CMS نیز فقط مدیریت محتوا را از Presentation جدا می‌کند؛ Commerce rule، Inventory یا Order را فراهم نمی‌کند مگر محصول صریحاً آن قابلیت‌ها را داشته باشد.

Headless چه چیزی را حل می‌کند و چه چیزی را نه؟

معماری ابزار کاهش یک محدودیت مشخص است؛ پروژهٔ «Headless شویم چون مدرن است» Business case ندارد.

چه زمانی Headless Commerce ارزش بررسی دارد؟

• دو یا چند کانال واقعاً فعال دارید که Catalog، Price، Cart یا Account مشترک می‌خواهند.
• Template و Release cycle پلتفرم فعلی مانع Outcome اندازه‌گیری‌شده شده است.
• Content و Commerce باید در تجربه‌ای غنی و چندبرندی ترکیب شوند.
• چند Market/Brand/Locale با Rule و Storefront مستقل دارید.
• تیم Front-end و Platform توان مالکیت CI/CD، Observability و On-call را دارد.
• حجم تغییر یا درآمد، هزینهٔ ساخت و عملیات چندسامانه‌ای را توجیه می‌کند.

نشانه‌های No-Go یا انتخاب Hybrid

• مسئله با Theme، Plugin، CDN یا بهینه‌سازی Checkout حل می‌شود.
• تنها یک کانال و فرایند استاندارد دارید.
• تیم برای API، Security، SRE و Test automation مالک مشخص ندارد.
• بودجه فقط Launch را پوشش می‌دهد، نه Run و Upgrade.
• Source of truth محصول، قیمت و موجودی بین ERP، فروشگاه و فایل دستی مبهم است.
• هدف «سریع‌تر شدن» است اما Baseline و Performance budget ندارید.

قبل از تغییر معماری، مسئلهٔ Journey را در راهنمای UX فروشگاه اینترنتی ریشه‌یابی کنید؛ اصطکاک فرم یا سیاست مرجوعی با Headless رفع نمی‌شود.

Monolith، Hybrid، Headless یا Composable؟

Hybrid اغلب نقطهٔ شروع خوب است: صفحات محتوا و Product discovery را جدا کنید، ولی Checkout را تا زمان اثبات نیاز روی مسیر بالغ پلتفرم نگه دارید.

Snapshot گزینه‌ها در اوت ۲۰۲۶

این جدول رتبه‌بندی نیست و قابلیت‌ها با Plan، Region و نسخه تغییر می‌کنند. تاریخ، API version و مسیر Upgrade را در Architecture decision record ثبت کنید.

Reference Architecture پیشنهادی

Browser / App / Kiosk
        │
 CDN / WAF / Edge
        │
Storefront SSR + BFF ─── CMS / Search / Personalization
        │
 Commerce API Gateway
        │
Catalog ─ Price ─ Cart ─ Checkout ─ Order ─ Customer
   │       │       │        │         │
 PIM     Promo  Session   Payment    OMS/ERP
   └────────── Event bus / Webhook ──────────┘
              │
      Analytics / Logs / Traces / Audit

این Diagram محصول نیست؛ مرز مسئولیت است. هر Arrow باید Contract، Authentication، Timeout، Retry، Idempotency، Observability و Owner داشته باشد.

Source of truth و Data ownership را پیش از کدنویسی تعیین کنید

در Headless، یک Product ممکن است هم‌زمان در ERP، PIM، Commerce، Search و Cache حضور داشته باشد. بدون Ownership map، Conflict در قیمت و موجودی حتمی است.

برای هر Field، Owner، Schema، ID، Version، Freshness، Conflict rule و Retention را در Data contract ثبت کنید.

چرا BFF در Storefront مهم است؟

Backend for Frontend بین Browser و سرویس‌ها قرار می‌گیرد تا Token خصوصی در Client افشا نشود، چند API را ترکیب کند، Policy و Timeout یکسان بدهد و Waterfall را کم کند. BFF نباید Monolith جدیدی شود که همهٔ Business ruleها در آن کپی شده‌اند.

• Public و Private API را جدا و Allowlist کنید.
• Payload را به حداقل Field لازم برای همان Route محدود کنید.
• Timeout و Budget کلی Request را بین Dependencyها تقسیم کنید.
• Trace ID را از Edge تا Commerce/Payment عبور دهید.
• Error را به State قابل فهم Storefront نگاشت کنید، نه Stack trace.
• Fallback فقط برای داده‌ای باشد که Stale بودن آن بی‌خطر است.

برای انتخاب GraphQL یا REST و کنترل N+۱، Complexity و Versioning، راهنمای GraphQL و REST را ببینید.

Contract و Versioning؛ استقلال تیم بدون قرارداد توهم است

«تیم‌ها مستقل Deploy می‌کنند» فقط وقتی درست است که Dependency و Contract failure از قبل دیده و Rollback مستقل ممکن باشد.

Cache؛ قیمت و موجودی را مثل تصویر Cache نکنید

Catalog content خواندنی و Asset نسخه‌دار Cacheپذیرند؛ Price، Promotion، Inventory، Cart و Account به Market/User/Time وابسته‌اند. یک Policy واحد برای همهٔ داده‌ها خطرناک است.

Cache key باید Locale، Currency، Market، Customer group و Permission لازم را لحاظ کند؛ در غیر این صورت نشت داده یا قیمت رخ می‌دهد.

Cart و Session؛ State را کجا نگه داریم؟

Local storage برای UX optimistic مفید است، اما Cart معتبر باید Server-side قابل بازیابی و Reconcile باشد. Anonymous cart، login merge، چند دستگاه، Expiry، coupon و price change را طراحی کنید.

1. Storefront Cart ID/Token opaque می‌گیرد و آن را امن نگه می‌دارد.
2. Mutation با Idempotency و Version مورد انتظار ارسال می‌شود.
3. Server Product/Price/Inventory را دوباره اعتبارسنجی می‌کند.
4. پاسخ State کامل یا Delta versioned می‌دهد.
5. در Conflict، UI به‌جای overwrite کور، تغییر قیمت/موجودی را توضیح می‌دهد.

در WooCommerce Store API، Endpointهای نوشتن Cart و Checkout به Nonce یا Cart token نیاز دارند؛ غیرفعال‌کردن کنترل Nonce که برای Development مستند شده، راه‌حل Production نیست.

Checkout را یک State machine ببینید

هر Transition باید Command، Event، Actor، Timestamp و Audit trail داشته باشد. UI نباید «بازگشت موفق از درگاه» را به‌تنهایی پرداخت قطعی بداند.

درگاه پرداخت ایرانی در Headless

Payment initiation و Verification باید Server-to-server انجام شوند. Secret در Browser قرار نمی‌گیرد و مبلغ از Cart معتبر Server محاسبه می‌شود.

1. Server Order draft و شناسهٔ یکتا می‌سازد.
2. مبلغ نهایی با واحد قراردادی—ریال یا تومان—Normalize و Freeze می‌شود.
3. درخواست درگاه با Idempotency داخلی ثبت می‌شود.
4. کاربر Redirect می‌شود؛ State/nonce و Return URL کنترل می‌شوند.
5. پس از بازگشت، Server تراکنش را از درگاه Verify می‌کند.
6. Transition Paid فقط یک‌بار و داخل Transaction/Lock مناسب انجام می‌شود.
7. Callback تکراری همان نتیجه را برمی‌گرداند؛ Order تکراری ساخته نمی‌شود.
8. Job reconciliation تراکنش‌های Pending/Unknown را تطبیق می‌دهد.

Timeout به معنی شکست قطعی نیست. وضعیت Unknown باید قابل بازیابی باشد. جزئیات کامل در راهنمای اتصال امن درگاه پرداخت و UX خطا/بازگشت در راهنمای بهینه‌سازی Checkout آمده است.

موجودی؛ نمایش، Promise و Reservation را جدا کنید

عدد موجودی در Product page معمولاً Read model است؛ تضمین فروش نیست. Available-to-promise باید سفارش‌های Pending، Reservation، کانال حضوری، مرجوعی و زمان Sync را در نظر بگیرد.

برای Flash sale، Bot، Oversell و Hot SKU، Atomicity و Queue/partition strategy را PoC کنید؛ اضافه‌کردن Cache بدون Reservation مشکل را پنهان می‌کند.

قیمت، تخفیف و واحد پول؛ Server authoritative

قیمت نمایش می‌تواند Estimate باشد، اما Cart و Checkout باید Rule را Server-side با Context کامل اجرا کنند: Market، Customer group، Coupon، Quantity، Shipping، Tax و زمان.

• واحد Minor/Major و تفاوت ریال/تومان را در Contract صریح کنید.
• از Float برای پول استفاده نکنید؛ Integer minor unit یا Decimal مناسب.
• Rounding و ترتیب Discount/Tax/Shipping را تست جدولی کنید.
• Promotion stacking و Exclusivity باید Rule واحد داشته باشد.
• قیمت Schema، Feed، Product page و Checkout با Source/Refresh مشترک همگام شود.
• در تغییر قیمت، Cart کاربر با پیام روشن Reprice شود؛ Silent change اعتماد را می‌شکند.

Omnichannel با API به‌تنهایی ساخته نمی‌شود

یک API مشترک، کانال‌ها را متصل می‌کند؛ تجربهٔ Omnichannel به Identity، Order history، Inventory، Pricing، Loyalty، Consent و Service policy مشترک نیاز دارد.

پیش از اضافه‌کردن «بی‌نهایت Head»، سه Journey واقعی و Source of truth آن‌ها را End-to-end اجرا کنید.

CMS، Preview و استقلال تیم محتوا

Headless ممکن است Preview و WYSIWYG را از تیم محتوا بگیرد، مگر از ابتدا طراحی شود. Content model باید Component slot، Validation، Locale، Schedule، Reference و Workflow را پوشش دهد.

• Preview با Draft token کوتاه‌عمر و محیط غیرقابل Index بسازید.
• Component و Content schema را version کنید.
• ویرایشگر نباید HTML/Script دلخواه را بدون Policy وارد کند.
• Fallback locale، Slug، Redirect و Archive را تعریف کنید.
• Release محتوا و Code باید قابل هماهنگی و Rollback باشند.

استقلال Marketing زمانی واقعی است که تغییر کم‌ریسک بدون Ticket مهندسی، با Preview و Guardrail منتشر شود.

SEO در Headless Commerce؛ کنترل بیش‌تر، مسئولیت بیش‌تر

Headless ذاتاً برای SEO بهتر یا بدتر نیست. معماری Rendering، URL و Sync داده تعیین‌کننده‌اند. راهنمای Merchant listing گوگل توصیه می‌کند Product structured data برای بهترین نتیجه در HTML اولیه باشد؛ دادهٔ JavaScript برای قیمت و موجودی سریع‌التغییر می‌تواند Crawl shopping را کم‌دفعات‌تر و کم‌اتکاتر کند.

Faceted navigation، Infinite scroll، Locale و Cache stale را روی خروجی عمومی تست کنید. برای Render و Index، راهنمای سئو PWA و JavaScript را اجرا کنید.

Performance؛ Headless می‌تواند سریع‌تر یا کندتر باشد

SSR و Edge cache فرصت‌اند، نه نتیجه. چند API، Hydration، Client SDK، Personalization و Tagها می‌توانند TTFB و INP را خراب کنند. Performance budget را بر اساس Route و State تعریف کنید.

RUM را بر اساس Route، Device، ISP، Cache state، Release و Conversion segment کنید. روش کامل در راهنمای Core Web Vitals و RUM آمده است.

RTL و Accessibility را در Design system قفل کنید

Front-end سفارشی یعنی مسئولیت کامل Componentها با شماست. Cart drawer، Variant selector، Autocomplete، Modal، Toast و Checkout را با Keyboard، Screen reader، Zoom، Error summary و RTL واقعی تست کنید.

• Tokenهای Direction-aware برای spacing و icon بسازید.
• عدد، واحد پول، کد کالا و متن انگلیسی را در Bidirectional layout آزمایش کنید.
• Focus پس از Mutation و Error قابل پیش‌بینی باشد.
• Loading/Skeleton تغییر Layout یا مخفی‌شدن Label ایجاد نکند.
• عملکرد بحرانی بدون Hover و Gesture پیچیده در دسترس باشد.

امنیت API در Headless Commerce

Storefront عمومی سطح حملهٔ API را آشکارتر می‌کند. OWASP API Security ریسک‌هایی مانند Broken object authorization، مصرف نامحدود منابع، Business flow abuse، Inventory ناقص API و مصرف ناامن API ثالث را برجسته می‌کند.

Controlهای جامع REST/GraphQL/Webhook و OAuth/JWT در راهنمای امنیت API آمده‌اند.

Resilience؛ Dependency failure را طراحی کنید

در Composable، Availability کل Journey از زنجیرهٔ Dependencyها اثر می‌گیرد. Retry کور می‌تواند Retry storm بسازد و Checkout را بدتر کند.

Timeout budget، Circuit breaker، Bulkhead، Queue، Dead-letter، Replay و Manual recovery را برای هر مسیر مشخص کنید.

Observability؛ Order ID باید از کلیک تا ERP دیده شود

• Trace ID و Cart/Order correlation ID را در BFF، Commerce، Payment و OMS عبور دهید.
• Log ساخت‌یافته بدون Token، PII یا اطلاعات پرداخت بنویسید.
• Metric فنی را به Funnel وصل کنید: Add-to-cart، Checkout start، Payment verified، Order committed.
• SLI را برای Availability، Latency، Freshness و Correctness تعریف کنید.
• Deployment annotation و Feature flag را در Dashboard نشان دهید.
• Synthetic journey جدا از Health endpoint اجرا کنید.

Analytics و Attribution؛ Event را دوبار نشمارید

SSR، Client hydration، Retry و چند کانال می‌توانند Purchase event تکراری بسازند. Event contract شامل نام، Trigger، ID، Timestamp، Amount، Currency، Consent، Producer و Deduplication key باشد.

• Purchase را از Order committed یا Payment verified با تعریف واحد تولید کنید.
• Client event را برای UX نگه دارید، نه Source of truth درآمد.
• Order ID و Event ID برای Deduplication بفرستید.
• Refund/Cancel را در Revenue attribution لحاظ کنید.
• Server-side tracking هم Consent و Data minimization می‌خواهد.

TCO معماری Headless Commerce

هزینهٔ Commerce license فقط یک جزء است:

TCO = Commerce + Storefront + BFF + Hosting/CDN + CMS/PIM/Search + Integration + Observability + Security/QA + Content ops + On-call + Upgrade + Migration/Exit

مثال فرضی سه‌ساله با واحد هزینه

این عددها Quote بازار نیستند؛ ساختار مقایسه‌اند. منفعت باید از Incremental contribution، Cycle time یا هزینهٔ اجتناب‌شده با شواهد بیاید. «Headless Conversion را بالا می‌برد» بدون Experiment، Benefit قطعی نیست.

Scorecard تصمیم معماری

امتیاز ۱ تا ۵ را در وزن ضرب کنید، ولی Kill criterion را با میانگین پنهان نکنید.

PoC شش‌هفته‌ای Headless

هفته ۱: Baseline و Contract

یک Category، Product پیچیده، Promotion، درگاه Sandbox و Inventory flow انتخاب کنید. KPI و Guardrail فعلی، API schema، Source of truth و Failure case را ثبت کنید.

هفته ۲ و ۳: Vertical slice

PLP→PDP→Cart→Checkout→Payment verify→Order/ERP را End-to-end بسازید. دادهٔ واقعی Sanitized، فارسی/RTL و Mobile را استفاده کنید؛ Prototype فقط Product card کافی نیست.

هفته ۴: Quality و Failure

SEO HTML، RUM/Lab، Keyboard، Contract، Load، Bot، AuthZ، Timeout، Callback تکراری، Inventory conflict و Restore را تست کنید.

هفته ۵: Operations و Content

Preview، Release، Rollback، Alert، Trace، On-call و یک تغییر Schema/API را تمرین کنید.

هفته ۶: TCO و تصمیم

زمان ساخت/Review/Incident، Cost و Risk را با Baseline مقایسه کنید. خروجی Go، Go Hybrid، Extend یا No-Go است.

مهاجرت با الگوی Strangler، نه Big Bang

1. Baseline و freeze URL: Inventory Route، SEO، Event، Integration و KPI.
2. Edge routing: Reverse proxy/route map برای انتقال بخش‌به‌بخش.
3. Read-only discovery: ابتدا Content/Category/Product با Commerce core فعلی.
4. Cart bridge: Session و Cart transfer با Contract و fallback.
5. Checkout: آخرین مرحله، پس از Payment/Inventory/reconciliation test.
6. Canary: درصد محدود Traffic، Feature flag و Rollback سریع.
7. Decommission: فقط پس از Window، Log/Redirect/Data retention و Owner removal.

مثال فرضی فروشگاه ایرانی

فروشگاهی با وب و اپ، ۴۰هزار SKU، ERP داخلی، سه انبار و کمپین‌های پرترافیک از محدودیت Theme شکایت دارد. به‌جای بازنویسی کامل:

1. مشخص می‌کند مشکل اصلی Release کند Landing و Search ضعیف است، نه Commerce core.
2. Storefront وب و CMS را جدا می‌کند؛ Checkout موجود را در Wave اول نگه می‌دارد.
3. BFF برای Catalog/Search می‌سازد، ولی Price/Promotion را در Cart دوباره محاسبه می‌کند.
4. Inventory read model با Lag نمایش می‌دهد و Reservation در Server باقی می‌ماند.
5. درگاه با Order draft، Verify و reconciliation فعلی حفظ می‌شود.
6. پس از سه ماه داده، دربارهٔ مهاجرت Cart/Checkout تصمیم می‌گیرد.

این Hybrid می‌تواند ۷۰٪ آزادی تجربه را بدون انتقال فوری پرریسک‌ترین Stateها بدهد. عدد ۷۰٪ فرضی است؛ هر تیم باید Scope و Outcome خودش را بسنجد.

برنامه ۳۰/۶۰/۹۰روزه تصمیم Headless

چک‌لیست نهایی Headless Commerce

• محدودیت فعلی و Outcome مالی/کاربری اندازه‌گیری شده است.
• Monolith، Hybrid، Headless، Composable و Microservices خلط نشده‌اند.
• Source of truth محصول، قیمت، موجودی، مشتری و سفارش روشن است.
• Storefront به قیمت/موجودی/پرداخت قطعی اعتماد نمی‌شود.
• BFF، Secret، Token و Session policy تعریف شده‌اند.
• API/Event contract، Version، Deprecation و Owner دارند.
• Idempotency و Concurrency برای Cart، Order و Payment آزموده شده‌اند.
• Cache بر اساس Market/User/Freshness تفکیک و Invalidation تست شده است.
• Checkout به State machine با Unknown/Recovery تبدیل شده است.
• درگاه با Verify Server-side و reconciliation کار می‌کند.
• Oversell، Reservation و آخرین کالا در Load/Concurrency تست شده‌اند.
• RTL، Keyboard، Error و Mobile در Componentها پاس شده‌اند.
• HTML اولیه، URL، Status، Canonical، Schema و Sitemap صحیح‌اند.
• RUM و Trace مسیر Order را End-to-end پوشش می‌دهند.
• Fallback دادهٔ stale فقط برای Domain کم‌خطر مجاز است.
• TCO سه‌ساله شامل Run، Upgrade، On-call و Exit است.
• Migration موجی، Canary و Rollback زیر RTO تمرین شده‌اند.