diff --git a/docs/architecture/backend/Backend-Platform-API-Spec.md b/docs/architecture/backend/Backend-Platform-API-Spec.md new file mode 100644 index 0000000..ba3acb9 --- /dev/null +++ b/docs/architecture/backend/Backend-Platform-API-Spec.md @@ -0,0 +1,451 @@ +# Backend Platform API Specification + +Status: Draft for implementation handoff +Date: 2026-07-03 +Scope: Marketplace Platform (Website + Builder + Backoffice) + +## 1. Tenant Resolution + +### Mechanism +- Backend resolves tenant from HTTP Host header. +- Frontend never sends tenant id or project key. +- Tenant resolution occurs before authorization and route handling. + +### Resolution Rules +1. Exact host match in tenant registry. +2. Alias host fallback. +3. Unknown host returns 404 tenant_not_found. + +### Validation +- Host must be present. +- Host must map to active tenant. +- Suspended tenant returns 403 tenant_suspended. + +## 2. Bootstrap API + +### Endpoint +- Method: GET +- Path: /bootstrap + +### Purpose +- Return complete tenant runtime configuration for frontend bootstrap. + +### Authorization +- Public for website runtime. +- Optional authenticated extensions for builder/backoffice context may be included via claims. + +### Request +- Headers: Host (required) +- Query: locale (optional) + +### Response +- 200 with BootstrapConfig payload. + +### Validation +- Schema version required. +- Required segments: tenant, branding, theme, featureFlags, navigation, pages. + +### Example Response +```json +{ + "schemaVersion": "1.0.0", + "generatedAt": "2026-07-03T00:00:00Z", + "tenant": { "id": "tenant-default-001", "slug": "default", "host": "default.local" }, + "branding": { "brandName": "Marketplace Platform Demo", "logoUrl": "/assets/images/dexar-logo.svg", "faviconUrl": "/favicon.ico" }, + "theme": { "themeId": "default-light", "mode": "light", "palette": { "primary": "#497671" }, "typography": { "primaryFontFamily": "DM Sans, sans-serif", "baseFontSize": 16 }, "spacing": { "unit": 4, "scale": [0,4,8] }, "borderRadiusScale": { "md": "12px" }, "shadows": { "md": "0 4px 12px rgba(0,0,0,0.15)" }, "iconSet": "default" }, + "featureFlags": { "wishlist": true, "reviews": true }, + "navigation": { "header": [], "footer": [] }, + "pages": [] +} +``` + +## 3. Configuration API + +### Endpoint +- Method: GET +- Path: /configuration + +### Purpose +- Return complete editable configuration model for Builder. + +### Authorization +- Required: builder.read + +### Request +- Headers: Authorization bearer token + +### Response +- 200 configuration aggregate for tenant. + +### Validation +- Caller must belong to tenant context. +- Caller role must include builder permissions. + +### Example Response +```json +{ + "tenantId": "tenant-default-001", + "branding": { "brandName": "Marketplace Platform Demo" }, + "theme": { "themeId": "default-light" }, + "navigation": { "header": [], "footer": [] }, + "pages": [] +} +``` + +## 4. Website API + +### Endpoint +- Method: GET +- Path: /website/pages/{pageKey} + +### Purpose +- Return website page composition for runtime rendering. + +### Authorization +- Public. + +### Request +- Path: pageKey required + +### Response +- 200 PageConfig with sections/widgets. + +### Validation +- pageKey must exist for tenant. +- hidden pages return 404. + +### Example Response +```json +{ + "id": "page-home", + "key": "home", + "layout": "default-public", + "sections": [ + { + "id": "section-hero", + "type": "hero", + "order": 1, + "widgets": [ + { "id": "widget-hero-main", "type": "hero", "version": "1.0.0", "props": { "title": "Welcome" } } + ] + } + ] +} +``` + +## 5. Builder API + +### Endpoint +- Method: PUT +- Path: /builder/configuration + +### Purpose +- Save tenant configuration from Builder Sandbox. + +### Authorization +- Required: builder.write + +### Request +- Body: full or partial configuration document. + +### Response +- 200 updated configuration metadata. + +### Validation +- JSON schema validation. +- Widget types must be registered and supported. +- Route/path uniqueness checks. + +### Example Request +```json +{ + "branding": { "brandName": "Updated Brand" }, + "featureFlags": { "chat": true }, + "pages": [] +} +``` + +### Example Response +```json +{ + "version": 42, + "updatedAt": "2026-07-03T12:00:00Z", + "updatedBy": "user-100" +} +``` + +## 6. Backoffice API + +### Endpoint +- Method: GET +- Path: /backoffice/dashboard + +### Purpose +- Return dashboard aggregates for backoffice operations. + +### Authorization +- Required: backoffice.read + +### Request +- Optional query filters by date range. + +### Response +- KPIs and entity counts. + +### Validation +- Caller must belong to tenant. + +### Example Response +```json +{ + "ordersToday": 14, + "openOrders": 38, + "products": 1024, + "customers": 5600, + "inventoryAlerts": 12 +} +``` + +## 7. Products API + +### Endpoint +- GET /products +- GET /products/{id} +- POST /products +- PUT /products/{id} +- DELETE /products/{id} + +### Purpose +- Product catalog management for backoffice. + +### Authorization +- Read: backoffice.products.read +- Write: backoffice.products.write + +### Request +- Supports paging/filter/sort on GET /products. + +### Response +- Product entities aligned to UI contracts. + +### Validation +- SKU unique per tenant. +- Price and currency required. +- Visibility and status must be valid enum values. + +### Example Product +```json +{ + "id": "prod-001", + "sku": "SKU-001", + "title": "Demo Product", + "price": { "amount": 149990, "currency": "RUB" }, + "stockStatus": "in_stock", + "visible": true +} +``` + +## 8. Categories API + +### Endpoint +- GET /categories +- POST /categories +- PUT /categories/{id} +- DELETE /categories/{id} + +### Purpose +- Category tree management. + +### Authorization +- Read: backoffice.categories.read +- Write: backoffice.categories.write + +### Validation +- Category id unique. +- Parent relation must not create cycles. + +### Example Category +```json +{ + "id": "cat-001", + "title": "Electronics", + "parentId": null, + "itemsCount": 120, + "visible": true +} +``` + +## 9. Orders API + +### Endpoint +- GET /orders +- GET /orders/{id} +- PATCH /orders/{id}/status + +### Purpose +- Order lifecycle tracking and updates. + +### Authorization +- Read: backoffice.orders.read +- Write: backoffice.orders.write + +### Validation +- Status transition must be legal according to state machine. + +### Example Response +```json +{ + "id": "ord-1001", + "status": "processing", + "total": { "amount": 9900, "currency": "RUB" }, + "createdAt": "2026-07-03T10:20:00Z" +} +``` + +## 10. Media API + +### Endpoint +- POST /media/upload +- GET /media/{id} +- DELETE /media/{id} + +### Purpose +- Media asset management for products/widgets/pages. + +### Authorization +- Required: backoffice.media.write for upload/delete. + +### Validation +- File size/type constraints. +- Malware scan required before publish. + +### Example Response +```json +{ + "id": "media-001", + "url": "https://cdn.example.com/tenant-default/media-001.jpg", + "mimeType": "image/jpeg" +} +``` + +## 11. Localization API + +### Endpoint +- GET /localization/dictionaries/{locale} +- PUT /localization/dictionaries/{locale} + +### Purpose +- Localization dictionary retrieval and updates. + +### Authorization +- Read: builder.localization.read +- Write: builder.localization.write + +### Validation +- Locale must be supported by tenant. +- Keys must be unique. + +### Example Response +```json +{ + "locale": "ru", + "version": "1.0.3", + "entries": { + "nav.home": "Главная", + "nav.cart": "Корзина" + } +} +``` + +## 12. Permissions API + +### Endpoint +- GET /permissions +- GET /roles +- PUT /roles/{role} + +### Purpose +- Permission definitions and role bindings. + +### Authorization +- Required: security.admin + +### Validation +- Role names unique. +- Permission keys must exist in definitions. + +### Example Response +```json +{ + "definitions": [ + { "key": "builder.pages.edit" }, + { "key": "backoffice.products.read" } + ], + "roles": [ + { "role": "builder_admin", "permissions": ["builder.pages.edit"] } + ] +} +``` + +## 13. Feature Flags API + +### Endpoint +- GET /feature-flags +- PUT /feature-flags + +### Purpose +- Tenant capability toggles for optional modules. + +### Authorization +- Read: builder.features.read +- Write: builder.features.write + +### Validation +- Flag keys must be from allowed registry. +- Non-boolean values rejected. + +### Example Response +```json +{ + "wishlist": true, + "compare": true, + "reviews": true, + "blog": false, + "chat": false, + "analytics": true, + "notifications": true, + "coupons": true, + "loyalty": false, + "giftCards": false, + "invoices": true +} +``` + +## Error Model (Common) + +### Structure +```json +{ + "code": "validation_error", + "message": "Validation failed", + "details": [ + { "field": "pages[0].route.path", "message": "Path already exists" } + ], + "traceId": "trc-123" +} +``` + +### Common Codes +- tenant_not_found +- tenant_suspended +- unauthorized +- forbidden +- validation_error +- conflict +- not_found +- internal_error + +## Contract Compatibility Note + +Authentication, payment, and authorization behavior and contracts in the current system are preserved as-is. +This document defines platform APIs around those stable integrations without changing their existing payload contracts.