This commit is contained in:
sdarbinyan
@@ -1,451 +0,0 @@
|
||||
# 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", "logoUrl": "/icons/icon-192x192.png", "faviconUrl": "/icons/icon-192x192.png" },
|
||||
"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" },
|
||||
"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": "Wireless Headphones",
|
||||
"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.
|
||||
@@ -1,36 +1,11 @@
|
||||
# ADR-004: Configuration Bootstrap and Provider Abstraction
|
||||
|
||||
Status: Accepted
|
||||
Status: Superseded
|
||||
Date: 2026-07-03
|
||||
Superseded by: `docs/backend/BACKEND-INTEGRATION.md` §4 (Bootstrap) and §14 (Backend replacement pattern)
|
||||
|
||||
## Context
|
||||
## Original decision (preserved for history)
|
||||
|
||||
Configuration must initially come from mock JSON and later from backend API without changing consumers.
|
||||
Configuration must initially come from mock JSON and later from backend API without changing consumers. `ConfigService` is the only configuration entrypoint; consumers depend on typed selectors only; provider implementation is swappable (`MockBootstrapProvider` / `ApiBootstrapProvider`); the frontend calls `GET /bootstrap` when the API provider is enabled and never passes a tenant id.
|
||||
|
||||
## Decision
|
||||
|
||||
Introduce configuration provider abstraction behind ConfigService.
|
||||
|
||||
- ConfigService is the only configuration entrypoint.
|
||||
- Consumers depend on typed ConfigService selectors only.
|
||||
- Provider implementation is swappable:
|
||||
- MockBootstrapProvider
|
||||
- ApiBootstrapProvider
|
||||
- Frontend calls GET /bootstrap when API provider is enabled.
|
||||
- Frontend does not pass tenant id.
|
||||
|
||||
## Consequences
|
||||
|
||||
Positive:
|
||||
|
||||
- Source-agnostic configuration usage.
|
||||
- Mock-to-backend transition with minimal change surface.
|
||||
|
||||
Negative:
|
||||
|
||||
- Requires strict prohibition of direct JSON imports in components/services.
|
||||
|
||||
## Compliance Requirements
|
||||
|
||||
- No code outside ConfigService may load bootstrap JSON.
|
||||
- No page/widget/component may access configuration files directly.
|
||||
This decision remains in effect. The full, verified contract — endpoint, caching, field-by-field DTO reference, and the generalized mock↔API provider-swap pattern this ADR introduced (now used by every admin domain, not just bootstrap) — lives in `docs/backend/BACKEND-INTEGRATION.md`. Read that document for current, code-verified detail; this file is kept only so ADR-numbered references in `docs/architecture/foundation/README.md` continue to resolve.
|
||||
|
||||
@@ -1,35 +1,11 @@
|
||||
# ADR-010: Backward Compatibility for Authentication, Payment, and Authorization
|
||||
|
||||
Status: Accepted
|
||||
Status: Superseded
|
||||
Date: 2026-07-03
|
||||
Superseded by: `docs/backend/BACKEND-INTEGRATION.md` §2 (Authentication), §2.8 (Payments), §2.5 (admin authorization gap)
|
||||
|
||||
## Context
|
||||
## Original decision (preserved for history)
|
||||
|
||||
Authentication and payment flows are proven and contract-sensitive. Platform refactoring must not break existing integrations.
|
||||
Authentication and payment flows are proven and contract-sensitive. Platform refactoring must not break existing integrations. Freeze behavior and contracts for authentication flow, payment API interactions, and authorization logic. Allow only encapsulation and integration-layer isolation, not contract redesign.
|
||||
|
||||
## Decision
|
||||
|
||||
Freeze behavior and contracts for:
|
||||
|
||||
- Authentication flow.
|
||||
- Payment API interactions.
|
||||
- Authorization logic.
|
||||
|
||||
Allow only encapsulation and integration-layer isolation, not contract redesign.
|
||||
|
||||
## Consequences
|
||||
|
||||
Positive:
|
||||
|
||||
- Prevents regressions in critical commerce and access flows.
|
||||
- Enables architecture modernization around stable core behavior.
|
||||
|
||||
Negative:
|
||||
|
||||
- Some suboptimal legacy internals may remain until controlled replacement strategy is approved.
|
||||
|
||||
## Compliance Requirements
|
||||
|
||||
- Existing auth/payment request/response contracts remain unchanged.
|
||||
- Behavior-equivalent wrappers/adapters are allowed.
|
||||
- Any change requires explicit ADR and compatibility test evidence.
|
||||
This decision remains in effect. The full, verified contract — the Telegram QR/session flow, cookie policy, the frozen payment endpoint shapes, and the still-unresolved admin-authorization gap this ADR's constraint interacts with — lives in `docs/backend/BACKEND-INTEGRATION.md` §2 and §2.5–§2.8. Read that document for current, code-verified detail; this file is kept only so ADR-numbered references in `docs/architecture/foundation/README.md` continue to resolve.
|
||||
|
||||
Reference in New Issue
Block a user