docs

docs/backend-platform/business-apis.md

@@ -0,0 +1,118 @@
+# Business APIs
+
+## 1. Scope
+Business APIs provide transactional and catalog capabilities.
+They must remain tenant-aware and must not return UI/layout/theme/widget configuration.
+
+## 2. Immutable Rule
+These APIs MUST NOT return:
+- page composition
+- layout mode
+- widget metadata
+- theme/footer/static page config
+
+That data belongs to CONFIG DOMAIN (`/bootstrap`, `/pages/:slug`).
+
+## 3. API Catalog
+
+## /auth
+Purpose:
+- session creation/validation
+- login/logout flows
+- token refresh where applicable
+
+High-level response shape:
+- session/token metadata
+- user identity claims
+- permission scopes
+
+Tenant rule:
+- auth sessions are tenant-scoped by request context.
+
+Must not change:
+- authentication contract and downstream payment/auth integrations.
+
+## /items
+Purpose:
+- list/fetch product items
+- search/filter/sort
+- item details and availability
+
+High-level response shape:
+- item arrays / item objects
+- pagination metadata
+- stock/price fields
+
+Tenant rule:
+- only items visible to tenant catalog policy.
+
+Must not change:
+- item identifiers/price semantics relied on frontend checkout/cart logic.
+
+## /categories
+Purpose:
+- category tree retrieval
+- category filtering metadata
+
+High-level response shape:
+- hierarchical or flat category collections
+- visibility and ordering metadata
+
+Tenant rule:
+- category graph resolved per tenant catalog configuration.
+
+Must not change:
+- category IDs and parent linkage semantics consumed by frontend domain mapping.
+
+## /orders
+Purpose:
+- create and track orders
+- lifecycle state transitions
+
+High-level response shape:
+- order id
+- status
+- totals and line-items
+
+Tenant rule:
+- order creation/query restricted to tenant context.
+
+Must not change:
+- order status lifecycle contract integrated with payment and notification flows.
+
+## /cart
+Purpose:
+- cart synchronization and server-side cart state where applicable
+
+High-level response shape:
+- cart items
+- totals
+- selected delivery/payment metadata
+
+Tenant rule:
+- cart state must be isolated by tenant + session/user.
+
+Must not change:
+- cart schema expected by checkout and payment request builders.
+
+## /payments
+Purpose:
+- payment intent/QR/card flow initiation
+- payment status querying
+
+High-level response shape:
+- payment id/reference
+- redirect/QR links
+- status fields
+
+Tenant rule:
+- payment credentials/routes resolved per tenant context on backend.
+
+Must not change:
+- existing payment provider contracts and callback/status semantics.
+
+## 4. Governance for All Business APIs
+- tenant derived from request context only
+- strict repository-level tenant filtering
+- no UI config payloads
+- backward compatibility for existing frontend business flows