docs

2026-07-05 04:23:47 +04:00
parent c901ec1e49
commit 10251f2fc6
24 changed files with 2424 additions and 0 deletions
--- a/docs/backend-platform/bootstrap-api-spec.md
+++ b/docs/backend-platform/bootstrap-api-spec.md
@@ -0,0 +1,151 @@
+# Bootstrap API Specification
+
+## 1. Endpoint
+- Method: `GET`
+- Path: `/bootstrap`
+- Auth: public (or optional lightweight token), tenant-scoped by domain
+
+## 2. Domain-Based Request Flow
+1. Receive request with host.
+2. Resolve tenant by host.
+3. Load tenant config aggregate from CONFIG DOMAIN.
+4. Build versioned bootstrap payload.
+5. Return public config JSON.
+
+Failure responses:
+- `404` unknown tenant domain
+- `403` tenant inactive/suspended
+- `500` config assembly failure
+
+## 3. Production-Like Sample Response
+```json
+{
+  "schemaVersion": "2.1.0",
+  "generatedAt": "2026-07-05T10:30:00Z",
+  "tenant": {
+    "id": "a95c2f1b-58c1-4d8b-b35b-82e5bdf14321",
+    "slug": "alpha-market",
+    "code": "ALPHA",
+    "host": "shop.alpha.example.com",
+    "name": "Alpha Marketplace",
+    "defaultLocale": "en",
+    "supportedLocales": ["en", "ru", "hy"],
+    "defaultCurrency": "USD",
+    "supportedCurrencies": ["USD", "EUR", "AMD"],
+    "timezone": "UTC"
+  },
+  "theme": {
+    "themeId": "alpha-light",
+    "mode": "light",
+    "palette": {
+      "primary": "#2F6F6D",
+      "secondary": "#9FB8B6",
+      "accent": "#B5D7D4",
+      "textPrimary": "#1E3C38",
+      "textSecondary": "#5E7471",
+      "backgroundPrimary": "#FFFFFF",
+      "backgroundSecondary": "#F6F8F8",
+      "border": "#D7E0DF"
+    }
+  },
+  "layout": {
+    "type": "sidebar-left",
+    "options": {
+      "sidebarSticky": true,
+      "heroEnabled": true
+    }
+  },
+  "widgetRegistry": {
+    "manifestUrl": "/config/widgets/manifest.json"
+  },
+  "pages": [
+    {
+      "id": "page-home",
+      "key": "home",
+      "route": { "path": "/", "exact": true },
+      "layout": { "type": "carousel-home" },
+      "sections": [
+        {
+          "id": "sec-hero",
+          "type": "hero",
+          "order": 1,
+          "widgets": [
+            {
+              "id": "w-hero-main",
+              "type": "hero",
+              "version": "1.0.0",
+              "order": 1,
+              "padding": "0.5rem 0",
+              "visibility": { "desktop": true, "tablet": true, "mobile": true },
+              "props": { "title": "Welcome", "subtitle": "B2B Catalog" }
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "footer": {
+    "paymentIcons": [
+      { "src": "/assets/payments/visa.svg", "alt": "Visa", "width": 40, "height": 28 },
+      { "src": "/assets/payments/mastercard.svg", "alt": "Mastercard", "width": 40, "height": 28 }
+    ],
+    "copyrightText": {
+      "en": "© 2026 Alpha Marketplace. All rights reserved.",
+      "ru": "© 2026 Alpha Marketplace. Все права защищены.",
+      "hy": "© 2026 Alpha Marketplace. Բոլոր իրավունքները պաշտպանված են:"
+    },
+    "legalPageKeys": ["about-us", "privacy-policy", "terms-of-service"]
+  },
+  "localization": {
+    "defaultLocale": "en",
+    "supportedLocales": ["en", "ru", "hy"],
+    "currencyByLocale": {
+      "en": "USD",
+      "ru": "USD",
+      "hy": "AMD"
+    }
+  },
+  "apiEndpoints": {
+    "bootstrap": { "path": "/bootstrap", "method": "GET", "timeoutMs": 5000 },
+    "website": {
+      "items": { "path": "/items", "method": "GET" },
+      "categories": { "path": "/categories", "method": "GET" },
+      "cart": { "path": "/cart", "method": "GET" },
+      "orders": { "path": "/orders", "method": "POST" },
+      "payments": { "path": "/payments", "method": "POST" }
+    }
+  }
+}
+```
+
+## 4. Field-by-Field Meaning
+- `schemaVersion`: bootstrap contract version used by frontend parser.
+- `generatedAt`: payload generation timestamp.
+- `tenant`: public tenant identity and locale/currency defaults.
+- `theme`: UI tokens; no business logic.
+- `layout.type`: global layout mode. Supported: `default`, `sidebar-left`, `carousel-home`, `minimal`.
+- `widgetRegistry.manifestUrl`: source for widget definitions/components mapping metadata.
+- `pages`: route-driven composition graph.
+- `footer`: footer links/icons/legal references.
+- `localization`: supported locales and currency mapping.
+- `apiEndpoints`: public endpoint mapping for frontend clients.
+
+## 5. Versioning Strategy
+Use semantic versioning in `schemaVersion`:
+- Patch (`2.1.1`): non-breaking metadata additions.
+- Minor (`2.2.0`): additive fields/sections with backward compatibility.
+- Major (`3.0.0`): breaking structural changes.
+
+Operational rules:
+- Keep old parser compatibility for at least one minor line.
+- Publish migration notes for any major bump.
+- Validate payload against schema before release.
+
+## 6. Security Rules
+Never include in bootstrap:
+- private keys
+- internal credentials
+- admin secrets
+- payment signing material
+
+Bootstrap is strictly public runtime configuration.