merge: B2B into main
Some checks failed
Architecture Governance / architecture (push) Has been cancelled
Some checks failed
Architecture Governance / architecture (push) Has been cancelled
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
sdarbinyan
456
BACKEND-API-REFERENCE.md
Normal file
456
BACKEND-API-REFERENCE.md
Normal file
@@ -0,0 +1,456 @@
|
|||||||
|
# Backend API Reference
|
||||||
|
|
||||||
|
One document, everyone reads it: product, backend, frontend, QA. It answers three questions for every domain — **what does the frontend already call**, **what shape does it send/expect**, and **is it real or mocked today**. Generated from the actual Angular frontend source (this repo has no backend code — it is a pure client consuming an external API), cross-checked against the frontend's own tolerant adapters, not aspirational.
|
||||||
|
|
||||||
|
Maturity tags used throughout:
|
||||||
|
|
||||||
|
| Tag | Meaning |
|
||||||
|
|---|---|
|
||||||
|
| **LIVE** | Real `HttpClient` call exists in code today, hits a real endpoint. |
|
||||||
|
| **MOCK-SWAPPABLE** | Interface + DI token exist; a real implementation can be dropped in without touching UI. May or may not have a real impl yet. |
|
||||||
|
| **MOCK-ONLY (no seam)** | A mock/local implementation exists but the facade injects the concrete mock class directly — no DI token. A backend needs a token introduced first before it can be wired in. |
|
||||||
|
| **LOCAL-ONLY** | Never talks to a backend by design — localStorage / in-memory / derived from bootstrap. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Core principles
|
||||||
|
|
||||||
|
1. **No response envelope.** There is no `{ success, data, error }` wrapper anywhere. Every call is typed to the bare payload — `HttpClient.get<Item>(...)`, `get<Category[]>(...)`, `get<BootstrapConfig>(...)`. Success = the raw resource (object, array, or `{ items, total }` for lists). Do not wrap new endpoints in an envelope unless it's a deliberate, coordinated breaking change.
|
||||||
|
2. **No API versioning.** No `/v1/` segment, no `Accept-Version` header, anywhere. The only version field in the whole contract is `BootstrapConfig.schemaVersion`, and it's checked for presence only, not semantically enforced.
|
||||||
|
3. **No WebSocket / SSE.** Every "live" feeling feature (QR login polling, payment status) is plain `setInterval`/RxJS polling against a normal request/response endpoint.
|
||||||
|
4. **Tenant resolution is 100% by hostname, not by header or path.** `TenantResolverService` reads the first DNS label (skipping `www`) and uses it to pick a base URL. No `X-Tenant` header, no `/tenant/{id}/...` prefix, ever. Auth requests carry no tenant identifier either — origin is the only signal.
|
||||||
|
5. **Two independent API bases exist**, plus a third for auth:
|
||||||
|
- Marketplace/tenant API — `ApiConfigService.getBaseUrl()` — default `https://api.dexarmarket.ru:445` (or per-tenant subdomain), `/api` on localhost.
|
||||||
|
- Payment/QR API — `environment.qrApiUrl` = `https://qr.vitanova.network/api`.
|
||||||
|
- Session auth API — `environment.authApiUrl` (currently same host as the marketplace API).
|
||||||
|
6. **Two independent mock mechanisms coexist — don't conflate them.** (a) `mock-data.interceptor.ts` globally short-circuits a hardcoded URL list (`/ping`, `/users/sessions*`, `/category`, `/items/*`, `/searchitems`, `/cart`, `/qr*`, `/websession/*`) when `environment.useMockData=true` — off in both shipped environments today. (b) Per-domain DI-token factories (`CONFIG_PROVIDER`, `CATEGORY_REPOSITORY`, `PRODUCT_DATA_PROVIDER`, `BACKOFFICE_DATA_PROVIDER`, `ADMIN_CATEGORIES_GATEWAY`) pick a mock vs. real class per `RuntimeProviderStrategyService`. **`PRODUCT_DATA_PROVIDER` and `CATEGORY_REPOSITORY` always resolve to the real API implementation regardless of mode** — their mock branch is dead code (`product-data-provider.token.ts:12-18`, `category-repository.token.ts:12-19`). `ADMIN_DASHBOARD_METRICS_GATEWAY` always resolves to the local/mock class the other direction — no real implementation is bound yet even though the token exists.
|
||||||
|
7. **GET retries:** `ApiService`/`ApiCategoryRepository` wrap reads in a shared `retry({ count: 2, delay: exponential from 500ms })` — expect up to 3 attempts per read before a caller sees a failure.
|
||||||
|
8. **Dead scaffolding, not missing files:** `src/app/core/error-handling/`, `src/app/core/guards/`, `src/app/core/interceptors/` each contain only a `.gitkeep` — reserved directory structure for a centralized error-handling layer that was never built. Every error today is handled ad hoc at the call site.
|
||||||
|
9. **Backend engineers should not "clean up" the tolerant adapters.** `ApiService.normalizeItem()`/`normalizeCategory()` and `TelegramSessionApiService.normalizeWebSession()` accept multiple historical field-name casings/aliases on purpose (see §7 Products). A payload landing anywhere inside that tolerance envelope works; a stricter renamed shape breaks the client.
|
||||||
|
10. **Nullable fields:** the frontend treats `null`, `undefined`, and an omitted key as the same "absent" signal everywhere except a handful of fields explicitly typed `T | null` (e.g. `AuthSession.userId`) where `null` specifically means "known to be absent." Omit or send `null` interchangeably elsewhere.
|
||||||
|
11. **Do not invent endpoints, fields, or business rules beyond what a real frontend call already implies.** Every open question below is flagged `Requires backend decision` with a recommended default — apply the default and move on unless it's flagged as a business/security decision.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Authentication
|
||||||
|
|
||||||
|
Two **independent, coexisting** mechanisms. Neither is a stand-in for the other; they authenticate different populations today.
|
||||||
|
|
||||||
|
### 2a. Telegram QR / session login — customer AND admin (LIVE)
|
||||||
|
|
||||||
|
Single mechanism for both; only client-side storage differs (separate cookie/signals per surface). Source: `src/app/services/telegram-session-api.service.ts`.
|
||||||
|
|
||||||
|
| Endpoint | Method | Auth | Body / Headers | Response |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| `/users/sessions` | POST | none | body `{ webSessionID }` (client-generated GUID) + header `WebSessionID: <same guid>` | `{ webSessionID, url }` — `url` is a `https://t.me/{bot}?start={id}` deep link |
|
||||||
|
| `/users/sessions/{id}` | GET | none | — | Session object, field-tolerant, normalized to `AuthSession` |
|
||||||
|
| `/users/sessions/{id}` | DELETE | none | header `WebSessionID: <id>` | ignored — client clears local state regardless of response |
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST https://api.dexarmarket.ru:445/users/sessions
|
||||||
|
WebSessionID: 3f1c2a0e-4e21-4d3a-9e77-1e8f6a2d9c11
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{ "webSessionID": "3f1c2a0e-4e21-4d3a-9e77-1e8f6a2d9c11" }
|
||||||
|
```
|
||||||
|
```json
|
||||||
|
{ "webSessionID": "3f1c2a0e-4e21-4d3a-9e77-1e8f6a2d9c11", "url": "https://t.me/myAMLKYCBOT?start=3f1c2a0e-4e21-4d3a-9e77-1e8f6a2d9c11" }
|
||||||
|
```
|
||||||
|
|
||||||
|
Poll response (field-tolerant — send real field names, the client accepts many aliases):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"webSessionID": "3f1c2a0e-4e21-4d3a-9e77-1e8f6a2d9c11",
|
||||||
|
"status": "active",
|
||||||
|
"user": { "id": 8823771, "username": "buyer_ivan", "firstName": "Ivan", "lastName": "P" },
|
||||||
|
"expiresAt": "2026-07-26T05:00:00Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Send a real `expiresAt`/`expires` — if absent, the client fabricates `now + 3600s`.
|
||||||
|
|
||||||
|
Client-side model (`src/app/models/auth.model.ts`):
|
||||||
|
```ts
|
||||||
|
interface AuthSession { sessionId: string; userId: number | null; username: string | null; displayName: string; active: boolean; expires: string; }
|
||||||
|
interface WebSessionStart { webSessionID: string; url: string; }
|
||||||
|
```
|
||||||
|
|
||||||
|
Expiry handling: `expires` drives a client timer that re-polls `GET /users/sessions/{id}` shortly before expiry; if the backend reports inactive, local state clears. There is no reactive 401 handling for this mechanism — expiry is only discovered on the next explicit poll.
|
||||||
|
|
||||||
|
### 2b. Ed25519 challenge/response admin auth (wired client-side, backend not implemented — calls 404 today)
|
||||||
|
|
||||||
|
Source: `src/app/core/auth/services/auth-api.service.ts`. Base `{authApiUrl}/api/admin/auth`.
|
||||||
|
|
||||||
|
| Endpoint | Method | Request | Response |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `/challenge` | GET | — | `AuthChallenge { nonce, issuedAt, expiresAt }` |
|
||||||
|
| `/verify` | POST | `VerifySignatureRequest { publicKey, signature, nonce }` | `AuthTokenPair { token, refreshToken }` |
|
||||||
|
| `/refresh` | POST | `RefreshTokenRequest { refreshToken }` | `AuthTokenPair` |
|
||||||
|
| `/logout` | POST | `{ refreshToken }` | void |
|
||||||
|
|
||||||
|
JWT claims (`JwtClaims`, decode-only client-side — the frontend never verifies the signature, that's the backend's job on every request):
|
||||||
|
```ts
|
||||||
|
interface JwtClaims { sub: string; role: AdminRole; iat: number; exp: number; publicKey: string; }
|
||||||
|
type AdminRole = 'Owner' | 'Administrator' | 'Editor' | 'Support' | 'ReadOnly';
|
||||||
|
```
|
||||||
|
|
||||||
|
Storage: `localStorage['ed25519AdminToken']` (access), `localStorage['ed25519AdminRefreshToken']` (refresh, opaque, never decoded client-side).
|
||||||
|
|
||||||
|
**Header:** intended as standard `Authorization: Bearer <token>`, but the interceptor that would auto-attach it (`authInterceptor`) is **not registered** in `app.config.ts` today — no request currently attaches the bearer token automatically. `adminAuthHeadersInterceptor` sets it *if* a token happens to be in storage, but nothing populates one in the live flow yet.
|
||||||
|
|
||||||
|
**Refresh:** client proactively refreshes ~60s before `exp` via a scheduled timer, and (once `authInterceptor` is registered) would reactively refresh once on any 401 before giving up. Every `/refresh` response is expected to return a **new** `refreshToken` (rotation) — the backend should invalidate the one just used.
|
||||||
|
|
||||||
|
**Role → permission table** (`ROLE_PERMISSIONS`, coarse, enforced client-side only for UX — backend must independently authorize every mutation):
|
||||||
|
|
||||||
|
| Role | Permissions |
|
||||||
|
|---|---|
|
||||||
|
| `Owner` | `backoffice.read`, `backoffice.write`, `builder.read`, `builder.write`, `users.manage`, `settings.manage` |
|
||||||
|
| `Administrator` | `backoffice.read`, `backoffice.write`, `builder.read`, `builder.write`, `users.manage` |
|
||||||
|
| `Editor` | `backoffice.read`, `backoffice.write`, `builder.read`, `builder.write` |
|
||||||
|
| `Support` | `backoffice.read` |
|
||||||
|
| `ReadOnly` | `backoffice.read`, `builder.read` |
|
||||||
|
|
||||||
|
**Known naming collision:** `AdminRole` is defined twice — the string union above (`core/auth/models/permission.model.ts`, the real JWT/auth contract) and an unrelated interface in `features/admin/users/models/admin-user.model.ts` (display-only labels in the Users admin page, not connected to auth). Treat the string union as the authoritative role for auth purposes; the interface needs a rename (e.g. `AdminUserRoleRecord`) — this is flagged, not yet fixed.
|
||||||
|
|
||||||
|
**Route guards:** `adminAuthGuard` (live, checks only "is there an active Telegram session," no role check) gates `/edit`, `/edit/:section`, `/backoffice`. `ed25519AuthGuard` and `permissionGuard(permission)` exist and are fully built but attached to **no route today** — dormant until Mechanism B cuts over. Every guard is a client-side UX gate only; the backend must independently verify authorization on every admin mutation regardless of what a guard decided.
|
||||||
|
|
||||||
|
**Open decision (business, not technical — ask a human):** whether Mechanism A is retired outright in favor of Mechanism B at cutover, or both run in parallel gated by role/tenant config.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Bootstrap — the runtime config document
|
||||||
|
|
||||||
|
The single payload that drives the entire multi-tenant storefront/builder/backoffice. Fetched once at app startup, held in memory; nearly every feature reads from it instead of a dedicated endpoint.
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---|---|
|
||||||
|
| Method / Route | `GET /bootstrap` (relative, rewritten onto the tenant base) |
|
||||||
|
| Auth | **None** — must be publicly cacheable per tenant, fetched before any login |
|
||||||
|
| Query / body | none |
|
||||||
|
|
||||||
|
```ts
|
||||||
|
interface BootstrapConfig {
|
||||||
|
schemaVersion: string; generatedAt: string;
|
||||||
|
tenant: TenantConfig; branding: BrandingConfig; theme: ThemeConfig; company: CompanyConfig;
|
||||||
|
featureFlags: FeatureFlagsConfig; features?: MarketplaceFeaturesConfig;
|
||||||
|
apiEndpoints: ApiEndpointsConfig; localization: LocalizationConfig; seo: SeoConfig;
|
||||||
|
permissions: PermissionsConfig; header?: HeaderConfig; catalog?: CatalogConfig;
|
||||||
|
layout?: PlatformLayoutConfig; navigation: NavigationConfig; footer?: FooterConfig;
|
||||||
|
productPage?: ProductPageConfig; userExperience?: UserExperienceConfig;
|
||||||
|
pages: PageConfig[]; staticPages?: StaticPagesConfig; widgetRegistry?: WidgetRegistryConfig;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Required top-level keys (must always be emitted): `schemaVersion, generatedAt, tenant, branding, theme, company, featureFlags, apiEndpoints, localization, seo, permissions, navigation, pages`. Everything marked `?` may be omitted — the client applies defaults.
|
||||||
|
|
||||||
|
`apiEndpoints.{website,builder,backoffice}` is where a tenant is meant to declare its per-surface endpoint paths at runtime (`Record<string, { path, method, timeoutMs? }>`) — **these are empty `{}` in the mock today; no builder/backoffice CRUD path exists as a hardcoded literal anywhere in the client.** Any concrete admin CRUD path in this document is a proposal, not a verified literal, until populated here.
|
||||||
|
|
||||||
|
Abridged real example (from `src/assets/mock/bootstrap/bootstrap.json`):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schemaVersion": "1.0.0",
|
||||||
|
"generatedAt": "2026-07-03T00:00:00Z",
|
||||||
|
"tenant": {
|
||||||
|
"id": "tenant-default-001", "slug": "default", "code": "DEFAULT", "host": "default.local",
|
||||||
|
"name": "Marketplace", "websiteBaseUrl": "https://marketplace.local",
|
||||||
|
"builderBaseUrl": "https://builder.marketplace.local", "backofficeBaseUrl": "https://backoffice.marketplace.local",
|
||||||
|
"defaultLocale": "ru", "supportedLocales": ["ru", "en", "hy"],
|
||||||
|
"defaultCurrency": "RUB", "supportedCurrencies": ["RUB", "USD", "EUR", "AMD"],
|
||||||
|
"timezone": "Europe/Moscow", "documentationUrl": "https://docs.marketplace.local"
|
||||||
|
},
|
||||||
|
"branding": { "brandName": "Marketplace", "logoUrl": "/icons/icon-192x192.png", "faviconUrl": "/favicon.ico", "supportEmail": "support@marketplace.local" },
|
||||||
|
"theme": {
|
||||||
|
"themeId": "default-light", "mode": "light",
|
||||||
|
"palette": { "primary": "#497671", "secondary": "#a1b4b5", "success": "#10b981", "warning": "#f59e0b", "danger": "#ef4444", "textPrimary": "#1e3c38", "backgroundPrimary": "#ffffff", "border": "#d3dad9" },
|
||||||
|
"typography": { "primaryFontFamily": "DM Sans, sans-serif", "baseFontSize": 16 },
|
||||||
|
"spacing": { "unit": 4, "scale": [0, 4, 8, 12, 16, 24, 32, 48] }
|
||||||
|
},
|
||||||
|
"featureFlags": { "wishlist": true, "compare": true, "reviews": true, "blog": false, "chat": false, "coupons": true },
|
||||||
|
"apiEndpoints": { "bootstrap": { "path": "/bootstrap", "method": "GET", "timeoutMs": 10000 }, "website": {}, "builder": {}, "backoffice": {} },
|
||||||
|
"localization": { "defaultLocale": "ru", "supportedLocales": ["ru", "en", "hy"], "currencyByLocale": { "ru": "RUB", "en": "USD", "hy": "AMD" } },
|
||||||
|
"catalog": { "layout": "grid", "defaultSort": "relevance", "availableSorts": ["relevance", "latest", "price_asc", "price_desc", "rating", "popular", "discount"] },
|
||||||
|
"navigation": { "header": [{ "id": "nav-home", "labelKey": "nav.home", "route": "/", "order": 1 }], "footer": [{ "id": "footer-about", "labelKey": "nav.about", "route": "/about-us", "order": 1 }] },
|
||||||
|
"widgetRegistry": { "manifestUrl": "/assets/mock/bootstrap/widget-manifest.json" },
|
||||||
|
"pages": [{
|
||||||
|
"id": "page-home", "key": "home", "title": "Home", "route": { "path": "/", "exact": true }, "visible": true,
|
||||||
|
"sections": [{ "id": "section-hero", "type": "hero", "order": 1, "layout": { "strategy": "hero", "columns": 1 }, "widgets": [{ "id": "widget-hero-main", "type": "hero", "version": "1.0.0", "order": 1, "props": { "title": { "ru": "Добро пожаловать", "en": "Welcome" } } }] }]
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Which provider fires:** mock (`GET /assets/mock/bootstrap/bootstrap.json`) when `useMockData=true`, or when `useMockBootstrapOnLocal=true` and host is localhost; otherwise real `GET /bootstrap`.
|
||||||
|
|
||||||
|
**No write path exists.** Publishing a marketplace (builder "Publish") only promotes an in-memory/localStorage draft signal today — nothing reaches a backend. See §8 Builder.
|
||||||
|
|
||||||
|
**Requires backend decision:** `X-Language`/`Accept-Language` pre-selection on this call (today the client always gets and holds the full multi-locale document); whether `schemaVersion` is ever semantically enforced (today presence-only); ETag/conditional-request caching (none exists); the entire draft→publish write path.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Pagination, sorting, filtering, search — conventions
|
||||||
|
|
||||||
|
**Two pagination styles coexist — support both, they are not interchangeable:**
|
||||||
|
|
||||||
|
- **Offset/count** (marketplace storefront reads) — query params `count` (page size, default 50) and `skip` (offset, default 0). `searchItems` returns `{ items, total }`; other list reads (`getCategoryItems`, `getRandomItems`) return a bare array with no total.
|
||||||
|
- **Page/pageSize** (admin lists, storefront engagement lists, media) — request `{ page, pageSize, ...filters }`, response `{ items, total, page, pageSize }`. Client derives `totalPages = ceil(total / pageSize)` itself.
|
||||||
|
|
||||||
|
No cursor/keyset pagination exists anywhere. No server-side page-size cap is enforced by the client (it just sends 50 as a default) — **requires backend decision** on max page size.
|
||||||
|
|
||||||
|
**Sorting:** enumerated in bootstrap `catalog.availableSorts`: `relevance | latest | price_asc | price_desc | rating | popular | discount` (7 values). The live `sort` query param on `GET /searchitems` only accepts a 5-value subset: `relevance | price_asc | price_desc | popular | rating` — `latest`/`discount` have no confirmed search-endpoint mapping. **Requires backend decision** to reconcile these two vocabularies, and to define wire encoding for admin-list sorting (no convention exists yet — admin CRUD is mock-only).
|
||||||
|
|
||||||
|
**Filtering:** storefront search accepts `categoryIDs` (comma-joined ints), `minPrice`, `maxPrice`, `tag`. Admin list filter objects (in-memory today, not confirmed wire contracts) all follow `{ search: string, <field>: 'all' | <enum>, page, pageSize }` — `'all'` is the "no filter on this facet" sentinel. **Requires backend decision:** whether `'all'` is sent literally or the param omitted.
|
||||||
|
|
||||||
|
**Search:** `GET /searchitems?search=<q>&count=&skip=[&categoryIDs&minPrice&maxPrice&tag&sort]` → `{ items, total }`. No dedicated autocomplete/suggestion/trending backend endpoint exists — those are derived client-side from already-loaded catalog data today.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Error model
|
||||||
|
|
||||||
|
**The frontend does not currently parse any backend error envelope for any real endpoint** — no interceptor inspects error responses; every caller reacts at the raw `HttpErrorResponse.status`/`.message` level. The one partial exception (Ed25519 admin auth) derives its error code from **HTTP status only**, ignoring any body field, which is itself a known bug (see below). Everything in this section is therefore a **recommended envelope to adopt going forward**, not something already wired end-to-end — apply it to new endpoints and treat the frontend gaps below as follow-up work, not something this doc can silently paper over.
|
||||||
|
|
||||||
|
### The envelope
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": {
|
||||||
|
"code": "VALIDATION_FAILED",
|
||||||
|
"message": "One or more fields are invalid.",
|
||||||
|
"status": 422,
|
||||||
|
"requestId": "b3f1c2a0-4e21-4d3a-9e77-1e8f6a2d9c11",
|
||||||
|
"details": [{ "field": "sku", "code": "REQUIRED", "message": "SKU is required." }]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Field | Required | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `error.code` | yes | Stable, `UPPER_SNAKE_CASE`, never localized — this is what code should branch on, never `message`. |
|
||||||
|
| `error.message` | yes | Human-readable English fallback only. |
|
||||||
|
| `error.status` | yes | Mirrors the HTTP status. |
|
||||||
|
| `error.requestId` | recommended | Correlation id for support/ops, echoed in logs. |
|
||||||
|
| `error.details` | only on 422 | `{ field, code, message }[]` — matches the client's existing local-validation issue shape, so a future adapter can merge backend 422s into the same inline-error UI without inventing a second mechanism. |
|
||||||
|
|
||||||
|
### Status-by-status
|
||||||
|
|
||||||
|
| Status | `code` | Frontend reaction today |
|
||||||
|
|---|---|---|
|
||||||
|
| 401 | `UNAUTHENTICATED` | Ed25519 flow → generic "Unauthorized, sign in" screen. Customer Telegram auth: no 401 branch anywhere — session validity is only ever discovered by polling. Admin CRUD facades: none have ever seen a real 401 (all mock). |
|
||||||
|
| 403 | `FORBIDDEN` | Ed25519 flow → "Forbidden, back to dashboard." No tenant-vs-role distinction exists — both render identical copy. |
|
||||||
|
| 404 | `NOT_FOUND` | No code path distinguishes 404 from any other failure — a deleted product and a 500 render the identical generic empty-state today. |
|
||||||
|
| 409 | `CONFLICT` | Nothing reacts to 409 anywhere. Only related mechanism: `AdminCategoriesGateway.isSlugTaken()`, a proactive pre-check, not a 409 handler. |
|
||||||
|
| 422 | `VALIDATION_FAILED` + `details[]` | No admin form parses a backend validation body today (all mock). Client's own `ProjectEditorFacade.fieldError(fieldKey)` inline-error pattern is the convention to align a future adapter to. |
|
||||||
|
| 429 | `RATE_LIMITED` (+`retryAfterSeconds`) | **Zero handling anywhere** — no interceptor, facade, or component references 429 at all. |
|
||||||
|
| 500 | `INTERNAL_ERROR` | Falls into whatever generic catch-all a given caller has (retry-button empty state, or — for `LocationService.getRegions()` — silently falls back to 6 hardcoded regions with no visible error at all). |
|
||||||
|
| 503 (infra down) | `SERVICE_UNAVAILABLE` | Same "backend unavailable, retry" screen as 500, on the Ed25519 flow only. |
|
||||||
|
| 503 (maintenance) | `MAINTENANCE_MODE` (+`maintenanceUntil`) | **No maintenance-mode concept exists in the frontend at all today.** Same HTTP status as infra-down 503 — `error.code` is the only way to distinguish them. |
|
||||||
|
| 403 (tenant disabled) | `TENANT_DISABLED` | **No handling exists.** No code path today distinguishes "tenant exists but is disabled" from any other 403. |
|
||||||
|
| 401 (token expired) | `TOKEN_EXPIRED` | **Known bug, not just a gap:** the client has a dedicated "Session expired" screen wired and ready, but `toAuthErrorShape()` only reaches it via a no-refresh-token-present client-side branch — a *real* backend 401 on `/refresh` always renders the generic "Unauthorized" screen instead, because the mapping function ignores any body code and derives purely from HTTP status. Fix requires the backend to send `error.code: "TOKEN_EXPIRED"` **and** a small frontend change to prefer it. |
|
||||||
|
| 401 (bad signature) | `INVALID_SIGNATURE` | Same bug class as above — dedicated screen exists, unreachable from a real HTTP response for the identical reason. |
|
||||||
|
|
||||||
|
**Every admin backoffice list page** (Users/Orders/Monitoring/Moderation/Transactions/Products/Categories/Analytics/Customers/Dashboard) shares one generic pattern: a boolean `error` signal → "Something went wrong" + retry button. None of them branch on status or `code` today — every status above collapses into the same generic UI until facades are individually updated.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Marketplace / storefront API (LIVE)
|
||||||
|
|
||||||
|
Base: `ApiConfigService.getBaseUrl()`. Headers on every call (`apiHeadersInterceptor`): `X-Region`, `X-Language` (`ru→RU, en→EN, hy→AM`), `Currency` (default `RUB`), `WebSessionID`. Source: `src/app/services/api.service.ts`.
|
||||||
|
|
||||||
|
| Endpoint | Method | Params / Body | Response |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `/ping` | GET | — | `{ message }` |
|
||||||
|
| `/category` | GET | — | `Category[]` (normalized) |
|
||||||
|
| `/category/{id}` | GET | `count`, `skip` | `Item[]` |
|
||||||
|
| `/items/{id}` | GET | — | `Item` |
|
||||||
|
| `/items/randomitems` | GET | `count`, `category?` | `Item[]` (featured/random) |
|
||||||
|
| `/searchitems` | GET | `search`, `count`, `skip`, `categoryIDs?`, `minPrice?`, `maxPrice?`, `tag?`, `sort?` | `{ items: Item[], total: number }` |
|
||||||
|
| `/websession/{sessionId}` | POST | item array | cart echo |
|
||||||
|
| `/items/{id}/callback` | POST | `{ rating, comment, sessionID, timestamp }` | `{ message }` — review |
|
||||||
|
| `/items/{id}/questiion` | POST | `{ question, sessionID, timestamp }` | `{ message }` — **literal typo `questiion`, preserve it, matches the client** |
|
||||||
|
| `/purchase-email` | POST | `{ email, phone?, telegramUserId, items[] }` | `{ message }` |
|
||||||
|
| `/regions` | GET | — | `Region[]` — client falls back **silently** to 6 hardcoded regions on any error |
|
||||||
|
|
||||||
|
### 6.1 Products — the tolerance contract
|
||||||
|
|
||||||
|
The wire DTO `Item` (`src/app/models/item.model.ts`) is reconciled by `ApiService.normalizeItem()` — the single largest inline adapter in the codebase. It tolerates **two historical shapes at once**:
|
||||||
|
|
||||||
|
- `id` (string) ↔ `itemID` (numeric)
|
||||||
|
- `imgs[]` ↔ `photos[]`
|
||||||
|
- `names[]` ↔ `translations`
|
||||||
|
- `description` as a key/value array ↔ a plain string
|
||||||
|
- `comments` ↔ `callbacks` (reviews)
|
||||||
|
- color `0xRRGGBB` → normalized `#RRGGBB`
|
||||||
|
- `remaining` count → a stock band
|
||||||
|
|
||||||
|
**A real backend can send either historical shape — do not invent a third, cleaner shape.** `normalizeCategory()` does the same job for categories.
|
||||||
|
|
||||||
|
### 6.2 Categories — two parallel stacks exist
|
||||||
|
|
||||||
|
- **Clean stack (real, LIVE):** `GET /category` → `CategoryDto[]` (`{ categoryID, names: [{lang,name}], subcategories: [...] }`) → `CategoryMapper` flattens the tree, dedupes by id, normalizes `am→hy` → domain `Category`.
|
||||||
|
- **Legacy stack:** the same `/category` response also feeds `ApiService.normalizeCategory()` → a *different* `Category` type (`src/app/models/category.model.ts`). **Two unrelated `Category` types exist in the codebase with the same name** — a known duplication, not a bug to silently fix on the backend side; just be aware both consume the same wire shape.
|
||||||
|
|
||||||
|
```json
|
||||||
|
[{ "categoryID": 12, "names": [{ "lang": "ru", "name": "Электроника" }, { "lang": "en", "name": "Electronics" }], "subcategories": [{ "categoryID": 34, "names": [{ "lang": "en", "name": "Phones" }] }] }]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Cart / Orders / Payments (LIVE)
|
||||||
|
|
||||||
|
Cart **contents** are LOCAL-ONLY (localStorage `marketplace_cart`, + Telegram CloudStorage in-app) — there is no backend cart. Checkout produces real payment + order calls.
|
||||||
|
|
||||||
|
| Endpoint | Method | Base | Body | Response |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| `/cart` | POST | marketplace | `CartPaymentRequest` | `QrCreateResponse` |
|
||||||
|
| `/orders` | POST | marketplace | `CreateOrderRequest` | `CreateOrderResponse` — fire-and-forget after payment succeeds, doesn't touch the payment call chain |
|
||||||
|
| `/qr` | POST | `qrApiUrl` | `QrCreateRequest` (headers `authorization-key`, `userid-value`) | `QrCreateResponse` |
|
||||||
|
| `/qr/dynamic/{partnerId}/{qrId}` | GET | `qrApiUrl` | — | `QrDynamicStatusResponse` |
|
||||||
|
| `/card/{partnerId}/{orderId}` | GET | `qrApiUrl` | — | `QrDynamicStatusResponse` |
|
||||||
|
|
||||||
|
Const `partnerId` = `web-97ec-9c57-4dde-9037-3a68f7f83750`.
|
||||||
|
|
||||||
|
```ts
|
||||||
|
interface CartPaymentRequest {
|
||||||
|
amount: number; currency: 'RUB'; siteuserID: string; siteorderID: string; redirectUrl: string;
|
||||||
|
telegramUsername: string; paymentMethod: 'qr' | 'card'; qrDescription?: string; customerID?: string;
|
||||||
|
items: Array<{ itemID: number; price: number; name: string; quantity?: number }>;
|
||||||
|
}
|
||||||
|
interface CreateOrderRequest {
|
||||||
|
items: Array<{ productId: string; name: string; quantity: number; price: number }>;
|
||||||
|
customer: { name: string; email: string; phone: string };
|
||||||
|
payment?: { method: string; currency: string };
|
||||||
|
shipping?: { address: string; method: string; trackingNumber: string };
|
||||||
|
}
|
||||||
|
interface CreateOrderResponse { id: string; orderNumber: string; status: string; total: number; currency: string; }
|
||||||
|
```
|
||||||
|
|
||||||
|
`QrCreateResponse` is deliberately alias-tolerant — many casings accepted for id/url/partner fields (`qrId`/`qrID`, `nspkurl`/`nspkId`, `partnerID`/`partnerId`/`PartnerID`, etc). Pick one canonical casing on the backend; the client resolves whichever it gets.
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST https://api.dexarmarket.ru:445/cart
|
||||||
|
WebSessionID: 3f1c2a0e-…
|
||||||
|
{ "amount": 4990, "currency": "RUB", "siteuserID": "8823771", "siteorderID": "order-2026-0007", "redirectUrl": "https://marketplace.local/checkout/done", "telegramUsername": "buyer_ivan", "paymentMethod": "qr", "items": [{ "itemID": 101, "price": 4990, "name": "Wireless Keyboard", "quantity": 1 }] }
|
||||||
|
```
|
||||||
|
```json
|
||||||
|
{ "qrId": "QR-77f0", "nspkurl": "https://qr.nspk.ru/AD10…", "status": "created", "qrExpirationDate": "2026-07-26T04:10:00Z" }
|
||||||
|
```
|
||||||
|
|
||||||
|
**Payments are frozen** — this call chain is explicitly out of scope for changes; document only, don't modify.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Admin (backoffice) domains
|
||||||
|
|
||||||
|
**Structural finding, the single most important fact in this section:** of 11 admin gateway domains, only **Categories** and **Dashboard-metrics** are bound through a DI token — a real backend can be dropped in for those two with zero facade changes. **Every other admin domain's facade injects its mock `*LocalGateway` class directly**, so a token has to be added before a real backend can be wired in at all, regardless of whether the endpoint itself is easy to build. Only one real admin HTTP implementation exists anywhere: `AdminCategoriesApiGateway`.
|
||||||
|
|
||||||
|
| Domain | Interface | Real impl? | DI token? | Facade | Seam status |
|
||||||
|
|---|---|---|---|---|---|
|
||||||
|
| Categories | `AdminCategoriesGateway` | **yes** (`admin-categories-api.gateway.ts`) | yes (`ADMIN_CATEGORIES_GATEWAY`) | `AdminCategoriesFacade` | MOCK-SWAPPABLE, done |
|
||||||
|
| Dashboard metrics | `AdminDashboardMetricsGateway` | no | yes (`ADMIN_DASHBOARD_METRICS_GATEWAY`) | `AdminDashboardFacade` | MOCK-SWAPPABLE, token only |
|
||||||
|
| Orders | `AdminOrdersGateway` | no | **none** | `AdminOrdersFacade` | MOCK-ONLY, no seam |
|
||||||
|
| Products | `AdminProductsGateway` | no | **none** | `AdminProductsFacade` | MOCK-ONLY, no seam |
|
||||||
|
| Users | `AdminUsersGateway` | no | **none** | `AdminUsersFacade` | MOCK-ONLY, no seam |
|
||||||
|
| Transactions | `AdminTransactionsGateway` | no | **none** | `AdminTransactionsFacade` | MOCK-ONLY, no seam |
|
||||||
|
| Monitoring | `AdminMonitoringGateway` | no | **none** | `AdminMonitoringFacade` | MOCK-ONLY, no seam |
|
||||||
|
| Moderation | `AdminModerationGateway` | no | **none** | `AdminModerationFacade` | MOCK-ONLY, no seam |
|
||||||
|
| Customers | *(none — derived)* | no | n/a | `AdminCustomersFacade` | derives from Orders' mock gateway |
|
||||||
|
| Analytics | *(none — derived)* | no | partial | `AdminAnalyticsFacade` | composes 5 other gateways, no data source |
|
||||||
|
| Media | abstract class `MediaRepository` | no | yes (class token) | `MediaLibraryFacade` | MOCK-SWAPPABLE |
|
||||||
|
|
||||||
|
### Gateway interface method contracts (what a real backend must satisfy)
|
||||||
|
|
||||||
|
- **Categories** — `loadCategories(filters)`, `loadCategory(id)`, `createCategory`, `updateCategory`, `deleteCategory`, `restoreCategory`, `isSlugTaken(slug, excludingId)`.
|
||||||
|
- **Dashboard metrics** — `loadMetrics(): AdminDashboardMetrics` (no params — a seller/scope filter would need a new parameter, no object to extend).
|
||||||
|
- **Orders** — `loadOrders(filters)`, `loadOrder(id)`, `updateStatus(id, status)`, `requestRefund(id)`, `addNote(id, note, internal)`, `archiveOrder`, `restoreOrder`, `deleteOrder`.
|
||||||
|
- **Products** — `loadProducts(filters)`, `loadProduct(id)`, `loadCategories()`, `createProduct`, `updateProduct`, `deleteProduct`, `duplicateProduct`, `archiveProduct`, `restoreProduct`.
|
||||||
|
- **Users** — `loadUsers`, `loadRoles`, `loadInvitations`, `loadSessions(userId)`, `loadAudit(userId)`, `setUserRole`, `setUserStatus`, `inviteUser(email, roleId, scope)`, `revokeInvitation`, `revokeSession`.
|
||||||
|
- **Transactions** — `loadTransactions(filters)`, `retryFailed(id)`, `setFraudFlag(id, flagged)`.
|
||||||
|
- **Monitoring** — `loadEvents(filters)`, `loadQueues()`, `loadWebhooks()`.
|
||||||
|
- **Moderation** — `loadReviews(filters)`, `loadReview(id)`, `setReviewStatus`, `setReviewVisible`, `setReviewPinned`, `setReviewFeatured`, `addModeratorNote`, `deleteReview`, `loadReports()`, `setReportStatus(id, status)`.
|
||||||
|
- **Media** — `list(params?)`, `upload(file, options?)`, `remove(id)`, `update(id, patch)`, `listFolders()`.
|
||||||
|
|
||||||
|
### The one real admin endpoint — Categories, exact paths
|
||||||
|
|
||||||
|
Base: `${apiConfig.getBaseUrl()}/backoffice/categories`. Mode-switched between this and the local mock via `getCategoryProviderMode()` — mock in local dev (no reachable backoffice API there), real API in production.
|
||||||
|
|
||||||
|
| Method | Path | Body | Response |
|
||||||
|
|---|---|---|---|
|
||||||
|
| GET | `/backoffice/categories?search=&visibility=&includeDeleted=` | — | `AdminCategory[]` |
|
||||||
|
| GET | `/backoffice/categories/{id}` | — | `AdminCategory \| null` (404 → null) |
|
||||||
|
| POST | `/backoffice/categories` | `AdminCategory` minus `{id, itemsCount, deletedAt, createdAt, updatedAt}` | `AdminCategory` |
|
||||||
|
| PUT | `/backoffice/categories/{id}` | full `AdminCategory` | `AdminCategory` |
|
||||||
|
| DELETE | `/backoffice/categories/{id}` | — | `void` — **soft delete only, no hard delete exists** |
|
||||||
|
| POST | `/backoffice/categories/{id}/restore` | `{}` | `AdminCategory \| null` |
|
||||||
|
| GET | `/backoffice/categories/slug-taken?slug=&excludingId=` | — | `{ taken: boolean }` |
|
||||||
|
|
||||||
|
Use this exact path shape as the template for every other admin domain in §8.5's build order — it's the only one proven end-to-end.
|
||||||
|
|
||||||
|
### Worked example — Admin Orders (no mapper exists yet, backend has freedom here)
|
||||||
|
|
||||||
|
Unlike Categories/Products (which have a wire DTO to match), admin domains other than Categories have **no wire DTO and no mapper today** — the mock gateways build view models directly in memory. This means the JSON shape below is a *proposal* the new `AdminOrdersApiGateway` would map into the existing `AdminOrder` view model, not a shape already fixed by an adapter:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "ord_1042", "status": "processing", "paymentStatus": "paid",
|
||||||
|
"customer": { "id": "cus_88", "name": "…", "email": "…" },
|
||||||
|
"items": [{ "productId": "…", "title": "…", "qty": 2, "unitPrice": 1990 }],
|
||||||
|
"shipping": { "method": "…", "address": "…" },
|
||||||
|
"timeline": [{ "event": "created", "at": "2026-07-01T10:00:00Z" }]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The same "no mapper exists, write one inside the new `*ApiGateway`" note applies to Products, Users, Transactions, Monitoring, Moderation.
|
||||||
|
|
||||||
|
### Widget manifest (LIVE — static/remote JSON, separate from admin CRUD)
|
||||||
|
|
||||||
|
`GET <bootstrap.widgetRegistry.manifestUrl>` (default `/assets/mock/bootstrap/widget-manifest.json`), falls back to `{ widgets: [] }` on any error, never throws to the UI.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "widgets": [{ "type": "hero", "version": "1.0.0", "componentKey": "HeroWidgetComponent", "supportedLayouts": ["hero"], "supportedDataSources": ["manual"], "settingsSchema": { "type": "object", "properties": { "title": { "type": "string" } } }, "defaultSettings": { "title": "Welcome" }, "enabled": true }] }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Backoffice storefront cards (LIVE — distinct from admin CRUD above)
|
||||||
|
|
||||||
|
`GET /api/backoffice/products`, `GET /api/backoffice/categories` — feeds storefront product/category card widgets, not the admin panel.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Everything that is LOCAL-ONLY (no backend call exists at all)
|
||||||
|
|
||||||
|
Worth knowing explicitly, so nobody assumes a gateway swap will "just work" for these:
|
||||||
|
|
||||||
|
- **Content management / static pages (CMS)** — reads/writes `BootstrapConfig.staticPages` in-memory. No dedicated backend call. Publishing = writing bootstrap back, for which no client write call exists.
|
||||||
|
- **Project editor / builder** — edits an in-memory `BootstrapConfig`, persists drafts to `localStorage` only. "Publish" today only promotes the local draft signal. A builder API is declared only as an empty `apiEndpoints.builder: {}` placeholder in bootstrap.
|
||||||
|
- **Search** — `SearchFacade` is a client-side orchestration over the product/category providers (history, trending, autocomplete, cache all local). The only real backend traffic underneath it is `GET /searchitems`.
|
||||||
|
- **User experience (wishlist/compare/recently-viewed/saved-searches)** — fully denormalized objects in `localStorage`, guest-first. A DI token exists for a future authenticated repository, but nothing is bound to it — comment in code notes it "can be switched to authenticated repository later."
|
||||||
|
- **Diagnostics** — inspects runtime/bootstrap/widget state locally; the one live-ish probe is a `/ping` health check.
|
||||||
|
- **Cart contents** — see §7, real payment/order calls exist, cart *state* never round-trips to a backend.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Backend build order (dependency-driven, not document order)
|
||||||
|
|
||||||
|
1. **Auth + session** — blocks everything admin-gated.
|
||||||
|
2. **Bootstrap content** (branding/theme/nav/seo) — transport (`GET /bootstrap`) already works; the *content* is still default stubs. Tenant resolution depends on it.
|
||||||
|
3. **Categories** — already LIVE both storefront and admin; products reference categories.
|
||||||
|
4. **Products / catalog** — storefront reads are LIVE; admin Products CRUD is the first no-seam admin domain to build.
|
||||||
|
5. **Media** — products/categories editors reference media assets.
|
||||||
|
6. **Cart / Orders / Transactions** — checkout is LIVE; admin Orders CRUD, then Transactions (derives from Orders).
|
||||||
|
7. **Reviews / Moderation** — customer writes are LIVE; admin Moderation gates them.
|
||||||
|
8. **Users / roles / invitations** — independent of commerce, needs auth.
|
||||||
|
9. **Dashboard metrics, then Monitoring** — operational visibility layers.
|
||||||
|
10. **Analytics — last.** Needs orders/products/moderation real *and* a tracking pipeline that doesn't exist yet anywhere (not just a missing endpoint — no data source at all).
|
||||||
|
11. **Builder draft/publish + CMS** — net-new write paths, can proceed in parallel once bootstrap content (step 2) is real.
|
||||||
|
12. **User-experience sync, search suggestions** — enhancements over already-working local features.
|
||||||
|
|
||||||
|
Per-domain migration pattern for the six no-seam admin domains (Orders, Products, Users, Transactions, Monitoring, Moderation): add a DI token → switch the facade to inject the token instead of the concrete mock class → implement the `*ApiGateway` (contains the DTO→view-model mapper) → bind the token → retire or keep the mock behind the existing `useMockData` flag. This is the exact pattern already proven by Categories — replicate it, don't redesign it per domain.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Known discrepancies to reconcile before/while building
|
||||||
|
|
||||||
|
- **`AdminRole` defined twice** with unrelated shapes (§2b) — auth string-union vs. Users-page display interface.
|
||||||
|
- **`Category` defined twice** (§6.2) — legacy vs. clean-stack, both fed by the same `/category` response.
|
||||||
|
- **Duplicate search models** under `features/search/models/` and `core/search/models/`.
|
||||||
|
- **`submitQuestion` endpoint path has a literal typo** (`questiion`, not `question`) — this matches the real backend spec, do not "fix" it.
|
||||||
|
- **The Ed25519 error-code bug** (§5) — `TOKEN_EXPIRED`/`INVALID_SIGNATURE` screens are fully built and unreachable from real HTTP responses today because the client only reads HTTP status, never a body code. Needs a coordinated backend + frontend fix, not backend alone.
|
||||||
|
- **`ADMIN_DASHBOARD_METRICS_GATEWAY` and `USER_EXPERIENCE_REPOSITORY` token factories return the mock/local class in every mode** — a real implementation must be written *and* explicitly bound; the seam existing does not mean a real backend is one line away.
|
||||||
|
|
||||||
|
For open product/business decisions this document deliberately does not resolve (rate limiting posture, refresh-token reuse detection, tenant-scoped auth, API versioning scheme, etc.), see [GAPS-AND-IMPROVEMENTS.md](GAPS-AND-IMPROVEMENTS.md).
|
||||||
34
CHANGELOG.md
34
CHANGELOG.md
@@ -1,34 +0,0 @@
|
|||||||
# Changelog
|
|
||||||
|
|
||||||
Format loosely follows [Keep a Changelog](https://keepachangelog.com/). Dates are commit dates on the `B2B` branch.
|
|
||||||
|
|
||||||
## [Unreleased]
|
|
||||||
|
|
||||||
### Added
|
|
||||||
|
|
||||||
- **Category management** (`feat(admin): complete category management`) — full admin CRUD for categories: hierarchy (parent/child), drag-and-drop reorder, visibility toggle, item counter, empty-category handling, soft delete + restore, draft/publish workflow with local draft recovery, unsaved-changes guard, slug validation, translations, SEO fields, breadcrumb preview, category image via the shared media picker.
|
|
||||||
- **Product management completion** (`feat(admin): complete product management`) — archive/restore, barcode field, lightweight variants, related-products picker, gallery via the shared media picker, discounted-price preview, infinite-scroll list mode; products now source their category list from the new category management module instead of a separate mock.
|
|
||||||
- **Media system hardening** (`feat(media): reusable media management`) — folder tagging, tag editing, upload validation (size/type), SVG sanitization (script/event-handler stripping), automatic image compression/resize on upload; the shared media picker is now wired into category images, product gallery, and Project Editor branding (logo/compact logo/favicon).
|
|
||||||
- **Order management** (`feat(admin): order management`) — new admin module: order list (search/status/pagination/CSV export) and detail view (customer/payment/shipping, itemized total, status timeline, change-status, refund request, cancel, customer + internal notes, print invoice). Seeded with synthetic mock orders — no backend order domain exists yet.
|
|
||||||
- **Transaction management** (`feat(admin): transaction management`) — payments/refunds/QR transaction list derived from the mock order data, with status/type filters, retry-failed, fraud flagging, per-transaction audit log, CSV export.
|
|
||||||
- **Users & permissions** (`feat(admin): users and permissions`) — new admin module: users (marketplace vs office admin scope), 4 built-in roles, invitations, per-user mock session list with revoke, per-user audit log. Confirms passwordless (Telegram QR) admin login was already real and links to it rather than reimplementing.
|
|
||||||
- **Monitoring center** (`feat(admin): monitoring center`) — unified audit/security/login/failed-login/API/error/warning event feed, mock queue and webhook-delivery views, and a Health section that reuses the existing real dashboard health checks.
|
|
||||||
- **Analytics dashboard** (`feat(admin): analytics dashboard`) — revenue/orders/average-order-value/top-products computed from the mock order data, product/category counts from their respective modules, a sales-over-time bar chart with 7/30/90-day ranges, CSV export. Visitor/funnel/heatmap sections show an explicit "awaiting backend integration" state rather than fabricated numbers, since no analytics pipeline exists.
|
|
||||||
|
|
||||||
### Changed
|
|
||||||
|
|
||||||
- `refactor: marketplace release polish` — accessibility pass (explicit `aria-label` on every previously-unlabeled filter `<select>` across the new admin modules), loading-skeleton consistency across admin list pages that previously rendered blank during the initial fetch, and consolidation of the admin dashboard card's custom loading shimmer onto the shared skeleton component.
|
|
||||||
|
|
||||||
- **Storefront premium UX polish** (RC-Visual-02, RC-Premium-01, RC STORE-01) — composition fixes (shared skeleton/empty-state components, undefined theme vars), visual/interaction polish (hover/focus states, color-only-signal fixes), and cleanup across Home/Catalog/Search/Product/Compare/Wishlist/Cart/Static Pages. Full history: `docs/archive/`.
|
|
||||||
- **Performance audit** (RC PERF-01) — initial bundle 1.47 MB → 1.12 MB (−24%), biggest win from lazy-loading en/hy i18n packs; dead `items-carousel`/primeng-only component removed.
|
|
||||||
- **WCAG 2.1 AA accessibility audit** (RC A11Y-01) — first skip link added app-wide, dialog focus-trap fixes, keyboard-operable drag-and-drop fallbacks, contrast fixes.
|
|
||||||
- **Release-candidate walkthrough** — 2 P0s fixed: an app-wide query-param routing bug, and Backoffice Categories CRUD being completely broken end-to-end.
|
|
||||||
- **Dead-code cleanup** — removed unregistered auth guards/interceptor, unused search-analytics service, empty backoffice scaffold directories, orphaned shared barrels/models.
|
|
||||||
|
|
||||||
### Please note
|
|
||||||
|
|
||||||
Orders, transactions, users/roles, monitoring, and analytics run on realistic sample data for now — the backend endpoints for these don't exist yet (tracked in `docs/BACKEND_API.md`). Categories are fully wired to a real HTTP gateway; products and media remain local-storage-backed, ready for a real API to be plugged in behind the same interfaces.
|
|
||||||
|
|
||||||
### Known gaps
|
|
||||||
|
|
||||||
Every feature above that reads "mock/local" or "seeded" has no real backend yet — see `docs/BACKEND_API_REMAINING_WORK.md` for the full punch list (products, media, orders, transactions, users/roles, and monitoring/analytics all need real endpoints before they reflect production data; categories are already wired end-to-end). `docs/ADMIN.md` documents the architecture and trade-off decisions for each module in detail. Full current status: `docs/PROJECT_INDEX.md`, `docs/FRONTEND-ROADMAP.md`, `docs/KNOWN-ISSUES.md`.
|
|
||||||
234
DESIGN.md
234
DESIGN.md
@@ -1,234 +0,0 @@
|
|||||||
---
|
|
||||||
name: Marketplaces Platform
|
|
||||||
description: Config-driven multi-tenant marketplace platform — quiet chrome, tenant-led storefronts.
|
|
||||||
colors:
|
|
||||||
primary: "#497671"
|
|
||||||
primary-hover: "#3d635f"
|
|
||||||
secondary: "#a1b4b5"
|
|
||||||
secondary-hover: "#8da3a4"
|
|
||||||
accent: "#a7ceca"
|
|
||||||
accent-hover: "#91b9b5"
|
|
||||||
text-primary: "#1e3c38"
|
|
||||||
text-secondary: "#667a77"
|
|
||||||
text-light: "#828e8d"
|
|
||||||
bg-primary: "#ffffff"
|
|
||||||
bg-secondary: "#f5f5f5"
|
|
||||||
bg-tertiary: "#f0f0f0"
|
|
||||||
border: "#d3dad9"
|
|
||||||
border-dark: "#677b78"
|
|
||||||
success: "#10b981"
|
|
||||||
warning: "#f59e0b"
|
|
||||||
error: "#ef4444"
|
|
||||||
info: "#3b82f6"
|
|
||||||
typography:
|
|
||||||
display:
|
|
||||||
fontFamily: "DM Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif"
|
|
||||||
fontSize: "clamp(2rem, 4vw, 2.75rem)"
|
|
||||||
fontWeight: 700
|
|
||||||
lineHeight: 1.25
|
|
||||||
letterSpacing: "normal"
|
|
||||||
headline:
|
|
||||||
fontFamily: "DM Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif"
|
|
||||||
fontSize: "clamp(1.5rem, 3vw, 2rem)"
|
|
||||||
fontWeight: 700
|
|
||||||
lineHeight: 1.25
|
|
||||||
letterSpacing: "normal"
|
|
||||||
title:
|
|
||||||
fontFamily: "DM Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif"
|
|
||||||
fontSize: "1.125rem"
|
|
||||||
fontWeight: 600
|
|
||||||
lineHeight: 1.3
|
|
||||||
letterSpacing: "normal"
|
|
||||||
body:
|
|
||||||
fontFamily: "DM Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif"
|
|
||||||
fontSize: "1rem"
|
|
||||||
fontWeight: 400
|
|
||||||
lineHeight: 1.6
|
|
||||||
letterSpacing: "normal"
|
|
||||||
label:
|
|
||||||
fontFamily: "DM Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif"
|
|
||||||
fontSize: "0.7rem"
|
|
||||||
fontWeight: 600
|
|
||||||
lineHeight: 1.4
|
|
||||||
letterSpacing: "0.4px"
|
|
||||||
rounded:
|
|
||||||
sm: "8px"
|
|
||||||
md: "12px"
|
|
||||||
lg: "13px"
|
|
||||||
xl: "22px"
|
|
||||||
field: "10px"
|
|
||||||
spacing:
|
|
||||||
xs: "4px"
|
|
||||||
sm: "8px"
|
|
||||||
md: "16px"
|
|
||||||
lg: "24px"
|
|
||||||
xl: "32px"
|
|
||||||
components:
|
|
||||||
button-primary:
|
|
||||||
backgroundColor: "{colors.primary}"
|
|
||||||
textColor: "#ffffff"
|
|
||||||
rounded: "{rounded.md}"
|
|
||||||
padding: "0.625rem 1rem"
|
|
||||||
button-primary-hover:
|
|
||||||
backgroundColor: "{colors.primary-hover}"
|
|
||||||
textColor: "#ffffff"
|
|
||||||
rounded: "{rounded.md}"
|
|
||||||
button-secondary:
|
|
||||||
backgroundColor: "{colors.secondary}"
|
|
||||||
textColor: "#ffffff"
|
|
||||||
rounded: "{rounded.md}"
|
|
||||||
padding: "0.625rem 1rem"
|
|
||||||
button-ghost:
|
|
||||||
backgroundColor: "transparent"
|
|
||||||
textColor: "{colors.text-primary}"
|
|
||||||
rounded: "{rounded.md}"
|
|
||||||
padding: "0.625rem 1rem"
|
|
||||||
card:
|
|
||||||
backgroundColor: "{colors.bg-primary}"
|
|
||||||
rounded: "{rounded.md}"
|
|
||||||
padding: "16px"
|
|
||||||
input:
|
|
||||||
backgroundColor: "{colors.bg-primary}"
|
|
||||||
textColor: "{colors.text-primary}"
|
|
||||||
rounded: "{rounded.field}"
|
|
||||||
padding: "10px 12px"
|
|
||||||
badge:
|
|
||||||
textColor: "#ffffff"
|
|
||||||
rounded: "{rounded.sm}"
|
|
||||||
padding: "2px 8px"
|
|
||||||
---
|
|
||||||
|
|
||||||
# Design System: Marketplaces Platform
|
|
||||||
|
|
||||||
## 1. Overview
|
|
||||||
|
|
||||||
**Creative North Star: "The Operator's Workbench"**
|
|
||||||
|
|
||||||
This is a tool before it is a brand. The platform chrome — the Project Editor, the Admin backoffice, the shared UI primitives — is a dependable workbench an operator returns to session after session to build and run a marketplace. It rewards precision and speed: state is always legible (draft vs published, saved vs unsaved, safe vs destructive), controls map visibly to what they change, and nothing on screen competes with the work. The palette is a calm Muted Pine teal-green, warm enough to feel like commerce, quiet enough to disappear behind a tenant's own theme.
|
|
||||||
|
|
||||||
The system is deliberately configuration-first. Every storefront is themed per tenant from a runtime `bootstrap.json`, so the platform's own identity stays neutral by design — the tenant's colors, type, and layout carry the storefront's character, and the workbench chrome recedes. Where components do appear, they are tactile and confident: solid fills, decisive hover lift, honest disabled and error states. Depth is real but restrained — surfaces sit on soft tonal shadows at rest, and structural elevation is reserved for things that genuinely float (modals, dropdowns, the save bar).
|
|
||||||
|
|
||||||
This system explicitly rejects three looks. It is **not dated enterprise admin** — no cluttered gray dashboards, no tiny dense tables, no 2010-era Bootstrap backoffice. It is **not a generic AI-SaaS template** — no cream/violet gradient landings, no hero-metric card rows, no tracked-uppercase eyebrows on every section, no identical icon-heading-text grids. It is **not a consumer toy** — no bubbly rounded-everything, no mascots, no candy colors, no gamified UI.
|
|
||||||
|
|
||||||
**Key Characteristics:**
|
|
||||||
- Quiet, neutral chrome so per-tenant themes lead the storefront.
|
|
||||||
- Muted Pine teal-green primary; retail-warm but low-drama.
|
|
||||||
- Tactile, confident components with decisive states.
|
|
||||||
- Legible state above decoration in every tool surface.
|
|
||||||
- WCAG 2.2 AA; contrast holds across tenant themes, not just the default.
|
|
||||||
|
|
||||||
## 2. Colors
|
|
||||||
|
|
||||||
A grounded teal-green core over cool near-white neutrals; retail warmth without shouting. The tokens below are the canonical Dexar theme — the platform default. Tenant themes (Lavero, Novo, and future tenants) override these same CSS custom properties, so components must consume the variables, never hardcode hex (ADR-008).
|
|
||||||
|
|
||||||
### Primary
|
|
||||||
- **Muted Pine** (#497671): The core brand teal-green. Primary buttons, active nav, focus outlines, links, key accents. On hover it deepens to **Pine Deep** (#3d635f). Grounded and natural — the color of the workbench itself.
|
|
||||||
|
|
||||||
### Secondary
|
|
||||||
- **Sage Grey** (#a1b4b5): Muted blue-grey-green for secondary actions and supporting surfaces; hover **Sage Grey Deep** (#8da3a4). Quieter than primary, never competes.
|
|
||||||
|
|
||||||
### Tertiary
|
|
||||||
- **Pale Mint** (#a7ceca): Soft light accent (#91b9b5 on hover) for gentle highlights, hero gradient stops, and low-emphasis fills.
|
|
||||||
|
|
||||||
### Neutral
|
|
||||||
- **Deep Pine Ink** (#1e3c38): Primary text. Tinted toward the brand hue, not pure black — carries 4.5:1+ on white.
|
|
||||||
- **Muted Pine Grey** (#667a77): Secondary text, captions, field descriptions.
|
|
||||||
- **Faint Pine Grey** (#828e8d): Light/tertiary text, placeholders — reserve for large or non-essential text.
|
|
||||||
- **White** (#ffffff): Primary surface (cards, inputs, panels).
|
|
||||||
- **Soft Grey** (#f5f5f5): App background, secondary surface.
|
|
||||||
- **Faint Grey** (#f0f0f0): Tertiary surface, subtle fills.
|
|
||||||
- **Divider Grey** (#d3dad9): Borders, dividers, input strokes.
|
|
||||||
- **Border Deep** (#677b78): Stronger borders where a divider needs weight.
|
|
||||||
|
|
||||||
### Status
|
|
||||||
- **Success** (#10b981), **Warning** (#f59e0b), **Error** (#ef4444), **Info** (#3b82f6): Standard semantic set, consistent across all themes. Error text darkens to #991b1b on light backgrounds for AA.
|
|
||||||
|
|
||||||
### Named Rules
|
|
||||||
**The Quiet Chrome Rule.** The platform's own surfaces stay neutral so tenant themes carry storefront identity. Never introduce a platform-branded color that would fight a tenant's palette.
|
|
||||||
|
|
||||||
**The Variable-Only Rule.** Components and widgets consume CSS custom properties (`--primary-color`, `--text-primary`, `--border-color`) only. A hardcoded hex in a component is a bug (ADR-008) — it breaks per-tenant theming.
|
|
||||||
|
|
||||||
## 3. Typography
|
|
||||||
|
|
||||||
**Display / Body Font:** DM Sans (with `-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif` fallback)
|
|
||||||
**Label Font:** DM Sans (same family, tracked and uppercased for badges)
|
|
||||||
|
|
||||||
**Character:** One family, four weights (400/500/600/700). DM Sans is a low-contrast geometric-humanist sans — clean, legible at dense sizes, neutral enough to sit behind tenant content. Hierarchy comes from weight and size, never a second display face.
|
|
||||||
|
|
||||||
### Hierarchy
|
|
||||||
- **Display** (700, clamp(2rem, 4vw, 2.75rem), 1.25): Page-level headings, storefront hero titles. Never exceeds ~2.75rem — the workbench does not shout.
|
|
||||||
- **Headline** (700, clamp(1.5rem, 3vw, 2rem), 1.25): Section headings, admin page titles.
|
|
||||||
- **Title** (600, 1.125rem, 1.3): Card titles, editor section labels, form group headings.
|
|
||||||
- **Body** (400, 1rem, 1.6): Default reading text. Cap prose at 65–75ch.
|
|
||||||
- **Label** (600, 0.7rem, 1.4, letter-spacing 0.4px, uppercase): Badges and tags only — the one place tracked uppercase is legitimate.
|
|
||||||
|
|
||||||
### Named Rules
|
|
||||||
**The One Family Rule.** DM Sans in multiple weights carries the entire system. Do not pair a second sans; do not add a display serif. Contrast is weight and size.
|
|
||||||
|
|
||||||
**The Uppercase-Is-Earned Rule.** Tracked uppercase lives on badges/tags exclusively. It is forbidden as a section eyebrow — that is a named anti-reference.
|
|
||||||
|
|
||||||
## 4. Elevation
|
|
||||||
|
|
||||||
A hybrid: soft tonal shadows give resting surfaces gentle separation from the background, while structural elevation is reserved for elements that genuinely float — modals, dropdowns, the sticky save bar. On top of that, interactive surfaces lift on hover (a 1–2px translate plus a stronger shadow). Depth is present and purposeful, never heavy.
|
|
||||||
|
|
||||||
### Shadow Vocabulary
|
|
||||||
- **shadow-sm** (`0 2px 8px rgba(0,0,0,0.1)`): Resting cards, inputs, low panels. The default ambient layer.
|
|
||||||
- **shadow-md** (`0 4px 12px rgba(0,0,0,0.15)`): Hover state for cards and buttons; raised toolbars.
|
|
||||||
- **shadow-lg** (`0 12px 32px rgba(73,118,113,0.2)`): Structural float — modals, dropdowns, popovers, the save bar. Tinted with the brand hue.
|
|
||||||
|
|
||||||
### Named Rules
|
|
||||||
**The Lift-on-Intent Rule.** Resting surfaces carry at most `shadow-sm`. `shadow-md` is a response to hover/focus; `shadow-lg` means the element floats above the page. Never use `shadow-lg` as decoration on a static card.
|
|
||||||
|
|
||||||
## 5. Components
|
|
||||||
|
|
||||||
### Buttons
|
|
||||||
- **Shape:** Gently curved (12px radius, `{rounded.md}`); editor action buttons use 10px (`{rounded.field}`).
|
|
||||||
- **Primary:** Muted Pine fill (#497671), white text, padding `0.625rem 1rem`, weight 600–700. Tactile and confident.
|
|
||||||
- **Hover / Focus:** Background deepens to #3d635f, `translateY(-1px)` lift with `shadow-sm`; focus-visible shows a 2px Muted Pine outline offset 2px. `:active` returns to `translateY(0)`.
|
|
||||||
- **Secondary:** Sage Grey (#a1b4b5) fill, white text; hover #8da3a4.
|
|
||||||
- **Ghost:** Transparent, Deep Pine Ink text, Divider Grey border; hover fills `rgba(73,118,113,0.08)` and border shifts to Muted Pine.
|
|
||||||
- **Disabled:** `opacity: 0.6`, no lift, no shadow, `cursor: not-allowed`.
|
|
||||||
|
|
||||||
### Cards / Containers
|
|
||||||
- **Corner Style:** 12px (`{rounded.md}`).
|
|
||||||
- **Background:** White (#ffffff) on Soft Grey (#f5f5f5) page.
|
|
||||||
- **Border:** 1px Divider Grey (#d3dad9).
|
|
||||||
- **Shadow Strategy:** `shadow-sm` at rest → `shadow-md` on hover with `translateY(-2px)` (product cards add a subtle `scale(1.01)`). See Elevation.
|
|
||||||
- **Internal Padding:** 16px (`{spacing.md}`).
|
|
||||||
- **Nested cards:** Editor sub-cards use `#fbfcfc` fill with the same 12px radius and 1px border.
|
|
||||||
|
|
||||||
### Inputs / Fields
|
|
||||||
- **Style:** White fill, 1px Divider Grey border, 10px radius (`{rounded.field}`), padding `10px 12px`, inherits body font.
|
|
||||||
- **Focus:** 2px Muted Pine focus-visible outline, offset 2px (global rule).
|
|
||||||
- **Field description:** 12px, Muted Pine Grey (#667a77), sits under the label at weight 400.
|
|
||||||
- **Error:** Error text #991b1b; color input controls get a 44px min-height touch target.
|
|
||||||
|
|
||||||
### Navigation
|
|
||||||
- Neutral chrome, DM Sans, weight 600 for active items. Default text is Deep Pine Ink; active/hover carries Muted Pine. Header uses a low-tint `--bg-header` wash (brand hue at ~10% alpha). Mobile collapses to a menu; `body.platform-menu-open` locks scroll.
|
|
||||||
|
|
||||||
### Badges & Tags (signature)
|
|
||||||
- **Badge:** Uppercase Label type (0.7rem, 600, 0.4px tracking), white text, 8px radius, `2px 8px` padding, solid semantic fills (new #4caf50, sale #f44336, hot #ff5722, limited #ff9800, bestseller #2196f3, featured #607d8b). Absolutely-positioned overlay top-left on product media.
|
|
||||||
- **Tag:** Pill (12px radius), Muted Pine text on `rgba(73,118,113,0.08)` fill with a faint brand border. Low-emphasis metadata.
|
|
||||||
|
|
||||||
### Save Bar (signature)
|
|
||||||
- Sticky, structurally elevated (`shadow-lg`), always states current state (unsaved changes / saving / published). The clearest expression of the Operator's Workbench: the operator always knows where the work stands.
|
|
||||||
|
|
||||||
## 6. Do's and Don'ts
|
|
||||||
|
|
||||||
### Do:
|
|
||||||
- **Do** consume theme CSS custom properties (`--primary-color`, `--text-primary`, `--border-color`) — never hardcode hex in a component (ADR-008).
|
|
||||||
- **Do** keep platform chrome neutral so tenant themes lead the storefront (The Quiet Chrome Rule).
|
|
||||||
- **Do** carry hierarchy with DM Sans weight and size; one family only.
|
|
||||||
- **Do** keep resting surfaces on `shadow-sm`; reserve `shadow-lg` for genuinely floating elements.
|
|
||||||
- **Do** make state unambiguous — draft vs published, saved vs unsaved, safe vs destructive — in every tool surface.
|
|
||||||
- **Do** give every hover/transform a `prefers-reduced-motion: reduce` fallback (handled globally in `styles.scss`).
|
|
||||||
- **Do** hold 4.5:1 body-text contrast across every tenant theme, not just Dexar.
|
|
||||||
|
|
||||||
### Don't:
|
|
||||||
- **Don't** ship dated enterprise admin: no cluttered gray dashboards, tiny dense tables, or 2010-era Bootstrap backoffice.
|
|
||||||
- **Don't** ship generic AI-SaaS template: no cream/violet gradient landings, hero-metric card rows, tracked-uppercase eyebrows on every section, or identical icon-heading-text card grids.
|
|
||||||
- **Don't** ship consumer-toy UI: no bubbly rounded-everything, mascots, candy colors, or gamified surfaces.
|
|
||||||
- **Don't** use tracked uppercase anywhere except badges/tags (The Uppercase-Is-Earned Rule).
|
|
||||||
- **Don't** exceed ~2.75rem on display headings — the workbench does not shout.
|
|
||||||
- **Don't** add a second type family or a display serif.
|
|
||||||
- **Don't** let platform-branded color fight a tenant's palette.
|
|
||||||
223
GAPS-AND-IMPROVEMENTS.md
Normal file
223
GAPS-AND-IMPROVEMENTS.md
Normal file
@@ -0,0 +1,223 @@
|
|||||||
|
# Gaps & Improvements
|
||||||
|
|
||||||
|
Findings only — nothing in this document has been fixed as part of writing it. Sourced from re-verifying prior audits against current source, plus a fresh automated review pass across the storefront (website) and backoffice (admin). Organized by the lens each finding matters most to; several findings matter to more than one role and are cross-referenced rather than duplicated.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## As a Customer / End User
|
||||||
|
|
||||||
|
1. **Ed25519 admin-auth "session expired" and "invalid signature" recovery screens are dead UI.** Both are fully built and wired, but `toAuthErrorShape()` (`core/auth/services/auth.service.ts:110-118`) derives the error code from HTTP status only, never a body-level code — so a real backend 401 always shows the generic "Unauthorized" screen instead. Also an [Engineering](#as-backend--api-engineer) and [Backend](#as-backend--api-engineer) item.
|
||||||
|
2. **Dark mode selector does nothing.** The light/dark/system dropdown saves correctly, but no CSS anywhere reads the `data-theme-mode` attribute it sets — picking anything but Light changes nothing visually.
|
||||||
|
3. **"Site Layout" selector (Theme section) has no effect.** `layout.type` is edited but page rendering only ever reads each page's own `layout`, never the top-level selector.
|
||||||
|
4. **Footer "Contacts" link has nothing behind it.** No static-page content exists for it at all in the bootstrap data (unlike other footer legal pages, which are populated).
|
||||||
|
5. **Product pages get no per-product SEO.** `SeoService.setItemMeta(item)` — the method that would set per-product Open Graph/canonical tags — exists but is **never called anywhere in the codebase**. Every product page ships only the site-wide default meta tags.
|
||||||
|
6. **`og:locale` is hardcoded to `'ru_RU'`** in both SEO meta-tag code paths, regardless of the active locale — a real gap for EN/HY visitors' social-share previews.
|
||||||
|
7. **No structured data (JSON-LD) and no sitemap generation exist anywhere** — confirmed absent, not partially built. Sitemap is backend-only work; JSON-LD would need net-new frontend code.
|
||||||
|
8. **Checkout's payment-description fallback is a hardcoded Russian string** (`'Покупка на Маркетплейсе'`) used as a last resort when no brand name or hostname is available — single-tenant-framed wording in a multi-tenant product.
|
||||||
|
9. **Brand color contrast fails WCAG AA.** `--border-color` measures 1.24–1.42:1 against a 3:1 UI-component requirement in every theme; `--success`/`--warning`/`--error`/`--info-color` fail 4.5:1 when used as plain text. Real palette colors, not a token bug — see [Accessibility](#as-accessibility-reviewer).
|
||||||
|
10. **`stars.component.scss:10` uses a literal hex color** (`#cdd6d5`) with no design token behind it — any future palette change will silently miss this one glyph.
|
||||||
|
11. **No multi-vendor cart handling exists.** Checkout is one inline flow producing exactly one order from one payment popup; a cart with items from multiple sellers has no defined behavior (relevant the moment Seller Management ships beyond its current disabled-by-default placeholder).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## As Product Owner / Business
|
||||||
|
|
||||||
|
1. **Backend completion is ~10%.** Only Categories has a real HTTP implementation on the admin side; every other domain (Orders, Products, Users, Transactions, Monitoring, Moderation, Analytics, Customers) runs entirely on mock data today. The frontend is feature-complete against that mock data; production readiness is blocked entirely on backend work, not frontend polish.
|
||||||
|
2. **The admin role model is decorative.** `AdminRole`/permissions exist in code, but **nothing gates any button, page, or action on them anywhere in the app.** Anyone who passes admin authentication has full access regardless of their assigned role. This is a real authorization gap, not a display nicety, and should be scoped before any real admin backend goes live with multiple operators.
|
||||||
|
3. **Payment options are limited to QR and card via one custom flow** — no additional providers (wallets, buy-now-pay-later) are wired or planned; needs a business decision on which providers, if any, before integration work starts.
|
||||||
|
4. **Advanced analytics (traffic, funnels, heatmaps) has no data source at all** — not a missing endpoint, a missing tracking pipeline. Flagged as the single largest ("XL") remaining backend effort, deliberately last in the build order because it depends on every other commerce domain being real first.
|
||||||
|
5. **Seller Management has eight cross-linked documents for a capability that is disabled by default and has zero backend bytes.** Real risk if it proceeds: at least three of those documents independently restate the same undecided "Unified vs. Split Orders" question — a decision change means updating multiple documents in sync, not one. Worth a consolidation pass before backend implementation starts.
|
||||||
|
6. **Two competing "seller" type shapes exist with no conversion between them** (`SellerConfig` in bootstrap models vs. `Seller`/`SellerBranding` in the domain layer) — self-flagged during Seller Management design work, restated here as unresolved. Recommend resolving (pick one, or document a mapping) before real backend work on that capability begins.
|
||||||
|
7. **No reusable feature-flag/capability-guard service exists**, despite one being promised by an existing ADR. The one current consumer of `sellerManagement.enabled` hand-rolls the check inline; every future flag will either duplicate that pattern or need the promised service built retroactively under time pressure.
|
||||||
|
8. **The Seller Management "enabled" code path has never been manually exercised**, even once — every verification claim about it was tested with the flag at its real-world value, `false`. Low risk today (nothing renders differently yet), but worth a fixture-based test the first time any enabled-state UI is actually built.
|
||||||
|
9. **Two large lazy-loaded bundle chunks remain unaddressed**: `project-editor` (~1.0 MB) and `catalog-container` (~330–375 kB). No mechanical split has been found; needs a dedicated profiling pass, ideally under real backend latency rather than instant mock responses.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## As QA / Test Engineering
|
||||||
|
|
||||||
|
1. **Automated test coverage is thin relative to the stated 80% target.** 11 spec files exist repo-wide (up from 5 before this cycle's test-foundation sprint); measured baseline is ~32% statements, ~19% branches, ~22% functions, ~33% lines. This is an honest foundation, not a coverage floor — no CI gate is set on it yet, deliberately, until a real floor number can be justified.
|
||||||
|
2. **Zero E2E tests exist anywhere in the repo.** No Playwright/Cypress/equivalent config found. Critical flows (storefront checkout, admin CRUD, builder draft→publish→live) have no automated regression coverage beyond the unit/facade specs added this cycle.
|
||||||
|
3. **Several "verified live" claims in prior audits were actually code-inspection only**, not real authenticated click-throughs — consistently because `/edit`, `/edit/:section`, and `/backoffice` require Telegram admin login, which cannot be completed in the automated environment those passes ran in. Worth flagging to a human tester before trusting those UI claims as fully proven: the manifest-aware layout picker (Sprint E), and multiple backoffice-auth-gated wording checks (Monitoring, Reports) among them.
|
||||||
|
4. **No real screen-reader software pass (NVDA/VoiceOver) has ever been performed anywhere in the app** — every accessibility claim in every audit to date is based on automated accessibility-tree inspection only (`role`, `aria-*` attribute presence), never an actual screen-reader session. This is a repo-wide gap, not specific to one page.
|
||||||
|
5. **A reactive-signal staleness bug was found and fixed in Seller Management's enabled-flag read** (it read the bootstrap snapshot once at construction instead of reactively) — worth a general regression-test pattern for any future flag/config read that should track `bootstrapRevision()`, since this bug class is easy to reintroduce and was invisible until specifically looked for.
|
||||||
|
6. **No facade-level tests exist yet for cart/checkout, moderation, or most admin domains** (Orders, Products, Users, Transactions, Monitoring were explicitly scoped out of this cycle's test-foundation sprint to stay within its time budget) — these are exactly the domains about to get real backends, so they carry the most regression risk with the least current coverage.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## As Backend / API Engineer
|
||||||
|
|
||||||
|
See [BACKEND-API-REFERENCE.md](BACKEND-API-REFERENCE.md) for the full contract. Structural gaps worth flagging here specifically:
|
||||||
|
|
||||||
|
1. **Only 2 of 11 admin gateway domains (Categories, Dashboard-metrics) have a DI-token seam.** The other 9 — Orders, Products, Users, Transactions, Monitoring, Moderation, plus derived Customers/Analytics — inject their mock gateway class directly. A token has to be added to each before any real backend can be bound, independent of how easy that domain's actual endpoint is to build.
|
||||||
|
2. **`AdminRole` is defined twice with unrelated shapes** (auth string-union vs. a Users-page display interface) — needs a naming reconciliation before the real role table is built.
|
||||||
|
3. **Two unrelated `Category` types exist**, both fed by the same `/category` response, both still in active use.
|
||||||
|
4. **Duplicate search models** exist under two different module paths.
|
||||||
|
5. **The error envelope is entirely a proposal** — no interceptor in the app inspects error response bodies today; every error reaction happens at the raw HTTP-status level. Adopting an envelope is a net-new build for both sides, not a preservation of existing behavior.
|
||||||
|
6. **429 (rate limiting) has zero client-side handling anywhere** — no interceptor, facade, or component references it. If the backend rate-limits, today's frontend has no graceful path for that response.
|
||||||
|
7. **No API versioning scheme has been decided** — no version segment, no version header, anywhere in the client.
|
||||||
|
8. **Centralized error-handling scaffolding exists but was never built.** `src/app/core/error-handling/`, `src/app/core/guards/`, and `src/app/core/interceptors/` each contain only a `.gitkeep` file — someone planned a shared error-handling layer, and every caller still handles failures ad hoc at the call site instead. Worth building once real backends start returning the error envelope in [BACKEND-API-REFERENCE.md](BACKEND-API-REFERENCE.md), rather than adding another one-off handler per facade.
|
||||||
|
9. **Admin Reports and Seller Management pages have zero data wiring of any kind** — not even a mock gateway call. Reports reuses `AdminAnalyticsFacade` (itself mock-derived) for its numbers; Seller Management is a static placeholder page with no `HttpClient` reference anywhere. Neither is currently a "swap the gateway" job — Reports inherits whatever Analytics becomes, Seller Management has no data layer to swap yet.
|
||||||
|
10. **Two per-domain provider tokens have a dead mock branch, silently.** `PRODUCT_DATA_PROVIDER` and `CATEGORY_REPOSITORY` always resolve to the real API implementation regardless of `useMockData` — there is no mock class bound to either token. Anyone toggling mock mode expecting storefront products/categories to mock out will be surprised; only Bootstrap, Backoffice-widget-data, and Admin-Categories actually respect the mock/api switch.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## As Accessibility Reviewer
|
||||||
|
|
||||||
|
1. **Brand color contrast genuinely fails WCAG AA** — see [Product Owner item 9 above](#as-product-owner--business) for the numbers. This requires a theme-owner sign-off before any fix ships, since it changes brand appearance, not just token values.
|
||||||
|
2. **No screen-reader software testing has ever been performed on this codebase** — every existing accessibility verification (including in this review) is automated accessibility-tree inspection, never a real NVDA/VoiceOver session. Recommend at least one manual pass on the highest-traffic flows (checkout, product page, admin login) before treating any part of the app as accessibility-verified end to end.
|
||||||
|
3. **Known past pattern worth re-checking elsewhere:** a raw `<textarea>` (no dedicated shared textarea component exists in the codebase) previously shipped without its `aria-label`/label association wired correctly in one place (Seller Management's Message field, since fixed). Any other raw `<textarea>` usage in the app should be checked for the same gap, since the shared `app-input` component handles this automatically but plain textareas do not.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## As Engineering / Tech Debt
|
||||||
|
|
||||||
|
1. **`navigation.header`** (header top-nav list) is editable in the builder but has zero runtime consumer — the header's actual menu comes from a different source entirely. Needs a product decision on positioning/behavior before it's real feature work, not a wiring fix.
|
||||||
|
2. **`catalog.navigationMode`** renders an intentional placeholder — confirmed not a bug, but the alternate nav UIs it implies (mega-menu, top-carousel, left-nav) don't exist yet if ever wanted.
|
||||||
|
3. **Angular 22 upgrade is researched but not started** (~2–3.5 days estimated, needs a dependency fix and Node version bump first). Explicitly recommended as its own dedicated session, never bundled with feature work.
|
||||||
|
4. **`MarketplaceRef` and `TenantConfig` both represent "a marketplace" from two different vantage points** — a deliberate, documented distinction today, but worth consolidating if a third marketplace-shaped type is ever proposed.
|
||||||
|
5. **`sellerId` fields are typed as bare `string` instead of the `UUID` alias** used everywhere else in the newer sellers domain — zero functional impact, pure convention drift, cheap to fix opportunistically.
|
||||||
|
6. **No shared breadcrumb component exists anywhere** — the only breadcrumb logic in the entire storefront is one local signal inside the catalog container, duplicated conceptually wherever a future breadcrumb might be needed.
|
||||||
|
7. **Bootstrap `apiEndpoints.{website,builder,backoffice}` are empty objects in the mock today** — meaning no builder or backoffice CRUD path exists as a literal anywhere in the client. Any concrete path documented for those domains is a proposal until this is populated.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Cross-cutting / process
|
||||||
|
|
||||||
|
- **Documentation was spread across 60+ overlapping markdown files** at the time of this review (status trackers, sprint plans, multiple overlapping backend specs, several audit reports referencing each other) — consolidated as part of this same pass into this file, [BACKEND-API-REFERENCE.md](BACKEND-API-REFERENCE.md), and whatever the team chooses to keep going forward. Recommend a lighter-weight doc set than before: one living gaps list (this file), one backend contract, source-of-truth code — not a new pile of point-in-time sprint reports.
|
||||||
|
- **A running list of "Requires backend decision" items with recommended defaults already exists** inside `BACKEND-API-REFERENCE.md` and the source material behind it — treat those as the first thing to walk through with the client/backend team, since most already have a suggested default and don't need a meeting, only a sign-off.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Automated code review — website (storefront)
|
||||||
|
|
||||||
|
*Findings from a fresh source-level pass over `src/app/pages`, `src/app/features/website`, `src/app/features/search`, `src/app/widgets`, and the project-editor/builder. Each item includes a file:line reference and the role it matters most to.*
|
||||||
|
|
||||||
|
### Cart / Checkout
|
||||||
|
|
||||||
|
- `[Product Owner]` No dedicated checkout feature exists — `src/app/features/website/checkout/` and `src/app/features/website/cart/` are empty `.gitkeep` placeholders; the entire cart/payment flow lives in the legacy `src/app/pages/cart/`.
|
||||||
|
- `[Engineering]` The post-payment email/phone capture flow (`submitEmail`, `onEmailInput`, `onPhoneInput`, `validateEmail`, `validatePhone`) is dead code — the template has no matching `<input>` anywhere, so these methods are never invoked (`src/app/pages/cart/cart.component.ts:507-729`).
|
||||||
|
- `[Product Owner]` Because that form is unreachable, `recordOrder()` always submits the backoffice order with an empty `email`/`phone` for every purchase (`src/app/pages/cart/cart.component.ts:418-441`).
|
||||||
|
- `[Engineering]` `autoSubmitPurchase()` schedules navigation to home via `setTimeout(…, 0)` unconditionally at the top of the method, before checking for a Telegram user ID or waiting on the `submitPurchaseEmail` call — navigation fires regardless of submission success or failure (`cart.component.ts:443-454`).
|
||||||
|
- `[User]` When no Telegram user ID is available, `autoSubmitPurchase()` only logs to console and returns silently — no toast/notification, even as the popup is already closing (`cart.component.ts:450-454`).
|
||||||
|
- `[Engineering / Security]` Payment `currency` is hardcoded to `'RUB'` in both `createPayment()` and `recordOrder()`, ignoring `LanguageService.currentCurrency()` — the total shown to the user can diverge from the currency actually sent to the payment gateway (`cart.component.ts:257,436`).
|
||||||
|
- `[Security]` `amount` and per-item prices sent to `POST /cart` are computed entirely client-side from cart data in localStorage/Telegram CloudStorage, with no server round-trip to re-verify live prices before payment creation — a tampered local cart could request payment at an incorrect amount unless the backend independently revalidates (`cart.component.ts:253-266`, `services/cart.service.ts:133-190`).
|
||||||
|
- `[QA]` `copyPaymentLink()` failure path only does `console.error` — no visible feedback that "copy link" failed (`cart.component.ts:495-505`).
|
||||||
|
- `[Engineering]` Hardcoded Russian fallback string `'Покупка на Маркетплейсе'` used as the QR payment description when no brand name/hostname resolves — bypasses i18n entirely (`cart.component.ts:592-604`). See also [Customer item 8](#as-a-customer--end-user).
|
||||||
|
- `[QA]` Cart quantity increases (`increaseQuantity`, `CartService.updateQuantity`/`addItem`) never validate against the item's available stock — a user can raise a cart line past what's in stock with no cap or warning (`cart.component.ts:119-121`, `cart.service.ts:206-256`).
|
||||||
|
- `[Accessibility]` Swipe-to-reveal-delete on mobile cart rows is touch-only; a fallback always-visible delete button exists, but nothing makes the swipe *state itself* keyboard-reachable (`cart.component.ts:140-163`).
|
||||||
|
- `[Product Owner]` Terms-of-service links (public offer, return policy, guarantee, privacy policy) are plain placeholder text on the cart page, explicitly flagged in-code as needing real backend-configured links (`cart.component.html:147-152`).
|
||||||
|
|
||||||
|
### Auth
|
||||||
|
|
||||||
|
- `[Security]` The customer web session id is stored in a plain, non-`HttpOnly` cookie set via `document.cookie` — readable by any script, exfiltratable via XSS (`services/auth.service.ts:173-180`).
|
||||||
|
|
||||||
|
### Search
|
||||||
|
|
||||||
|
- `[i18n]` `SearchFacade.popularSearches` is a hardcoded English list ("Smartphones", "Sneakers", …) never routed through translation — renders in English regardless of active locale (`features/search/facade/search.facade.ts:58-91`).
|
||||||
|
- `[Product Owner]` `SearchTrendingService.loadTrending()` is a stub that always returns `null` ("Endpoint not available yet") — trending searches are non-functional end to end, and it overwrites the (already-hardcoded) fallback popular list with an empty one every time (`features/search/services/search-trending.service.ts:7-10`).
|
||||||
|
|
||||||
|
### Catalog
|
||||||
|
|
||||||
|
- `[Performance]` Catalog fetches at most 200 products per category in one call, then filters/sorts/paginates entirely client-side over that fixed batch — categories with more than 200 products silently truncate with no indication, and every filter/sort change re-processes the whole in-memory array instead of re-querying (`features/website/catalog/containers/catalog-container.component.ts:160,675-699`).
|
||||||
|
- `[Engineering / tech-debt]` `restoreContinueBrowsing()` is fully implemented (restores search/sort/layout/scroll) but never called anywhere — "continue browsing" state is saved on every interaction but never actually restored (`catalog-container.component.ts:901-929`).
|
||||||
|
- `[Engineering]` Non-numeric category route tokens are resolved by fetching the entire category tree and slugifying titles client-side — fragile against duplicate or renamed category titles, and loads the full tree just to resolve one slug (`catalog-container.component.ts:943-959`).
|
||||||
|
- `[Performance]` Price-range filter inputs trigger a full catalog recompute + URL sync on every keystroke, with no debounce (unlike the search box) (`features/website/catalog/components/filters-panel/filters-panel.component.ts:80-94`).
|
||||||
|
- `[QA]` Range filter min/max inputs have no validation preventing `min > max` — an inverted range silently yields zero results with no explicit error state (`filters-panel.component.ts:80-94`, `.html:56-76`).
|
||||||
|
|
||||||
|
### Product details
|
||||||
|
|
||||||
|
- `[User]` The "Notify Me" button (shown when out of stock) is wired to `toggleWishlist()` — it does not create any real back-in-stock subscription, just relabels the wishlist button (`features/website/product/containers/product-details-container.component.ts:356-358`, `product-actions.component.html:22-24`).
|
||||||
|
- `[Engineering]` "Buy Now" calls `addToCart()` (which resolves item data via an async, subscribed call inside `CartService.addItem`) and immediately navigates to `/cart` without awaiting completion — the cart page can render before the item has actually been added (`product-details-container.component.ts:306-320`, `cart.service.ts:206-243`).
|
||||||
|
|
||||||
|
### Product cards / search results
|
||||||
|
|
||||||
|
- `[Engineering / tech-debt]` The "Quick View" button on every search-results product card emits `quickViewPlaceholder`, but no parent component anywhere binds that output — clicking it is a dead end (`components/product-card/product-card.component.html:23-25`, `.ts:83-87`, `catalog/components/search-results/search-results.component.html:18-33`).
|
||||||
|
|
||||||
|
### Wishlist / Compare
|
||||||
|
|
||||||
|
- `[i18n]` The Compare table renders `product.name`/description fields/color/size straight off the raw product object instead of through `getTranslatedField()` — names and specs on the Compare page always show the source language regardless of active locale (`features/website/user-experience/compare/components/compare-table.component.ts:42-58`).
|
||||||
|
- `[Product Owner]` Wishlist, compare, recently-viewed, and saved searches are all localStorage-only via `USER_EXPERIENCE_REPOSITORY`, with no server sync to the authenticated Telegram session — data is lost on device change or storage clear despite the app having real login (`facades/platform/user-experience.facade.ts:1-137`).
|
||||||
|
|
||||||
|
### Widgets / Page builder
|
||||||
|
|
||||||
|
- `[Engineering]` `DataSourceResolverService.resolve()` has no `catchError`/fallback on any branch — an API failure while loading a widget's data propagates as an unhandled Observable error (`widgets/resolvers/data-source-resolver.service.ts:20-52`).
|
||||||
|
- `[User]` Because of the above, a single failing widget just silently fails to render (stays blank) — no retry, error message, or loading skeleton anywhere in the chain (`layouts/containers/dynamic-page-layout.component.ts:55-61`, `dynamic-renderer/widget-host/widget-host.service.ts:23-58`).
|
||||||
|
- `[Engineering / tech-debt]` `'html'`, `'banner'`, and `'partners'` widget types have full data-resolution logic written but no entry in `APPROVED_WIDGET_COMPONENTS` — configuring one of these renders `UnknownWidgetComponent` on the live storefront instead of real content (`widgets/registry/widget-registry.bootstrap.service.ts:9-17`, `data-source-resolver.service.ts:218-257`).
|
||||||
|
- `[Accessibility]` The hero widget carousel auto-advances every 5s whenever `data.autoplay` is set, with no pause/stop control exposed to the user — only the CSS entrance animation respects `prefers-reduced-motion`, the autoplay timer itself does not (WCAG 2.2.2 risk) (`widgets/ui/hero-widget.component.ts:292-301`).
|
||||||
|
|
||||||
|
### Static / CMS pages
|
||||||
|
|
||||||
|
- `[User]` `loadByKey`/`loadByPath` subscribe with only a `next` handler, no `error` callback — if bootstrap loading fails, `loading` stays `true` forever and the page shows an infinite spinner with no error state (`pages/static-page/static-page.component.ts:76-92`).
|
||||||
|
|
||||||
|
### i18n / Performance
|
||||||
|
|
||||||
|
- `[Performance]` `TranslatePipe` is declared `pure: false`, so every `| translate` binding (hundreds across templates — 40+ on the cart page alone) re-evaluates on every change-detection cycle instead of only when the language changes — a real cost at scale even under `OnPush` components (`i18n/translate.pipe.ts:4-14`).
|
||||||
|
|
||||||
|
## Automated code review — backoffice (admin)
|
||||||
|
|
||||||
|
*Findings from a fresh source-level pass over every `src/app/features/admin/*` module and `src/app/features/backoffice`. Each item includes a file:line reference and the role it matters most to.*
|
||||||
|
|
||||||
|
### Security / Authorization
|
||||||
|
|
||||||
|
- `[Security]` `adminAuthGuard` only checks `isAuthenticated()` — there is no role/permission check anywhere in the codebase (zero matches for a permission check project-wide). Any authenticated admin, including a seeded "viewer" role, can perform every destructive action: delete products/orders, change any user's role, refund orders (`core/admin-auth/admin-auth.guard.ts:6-15`). Same root cause as [Product Owner item 2](#as-product-owner--business).
|
||||||
|
- `[Security]` `AdminRole.permissions` arrays (owner/admin/editor/viewer) exist only as display labels — nothing gates a button, route, or action on them (`features/admin/users/services/admin-users-local.gateway.ts:7-12`, `admin-users-page.component.ts:59-64`).
|
||||||
|
- `[Security]` Nothing prevents suspending or demoting the last remaining `owner`-role user — `setStatus`/`setRole` apply unconditionally (`features/admin/users/facade/admin-users.facade.ts:35-41`).
|
||||||
|
- `[Security]` Category slug-uniqueness check **fails open**: on API error, `isSlugTaken` swallows the error and returns `false` ("not taken"), letting a duplicate/conflicting slug through silently instead of blocking submission (`features/admin/categories/services/admin-categories-api.gateway.ts:56-65`).
|
||||||
|
|
||||||
|
### Audit / Traceability
|
||||||
|
|
||||||
|
- `[Security]` Audit/timeline entries hardcode `actor: 'admin'` as a literal string instead of the real authenticated admin's identity — the "who did this" record is meaningless the moment more than one admin uses the system. Affects role/status changes, transaction retry/fraud-flag, and review moderation (`features/admin/users/services/admin-users-local.gateway.ts:93-94`; `transactions/services/admin-transactions-local.gateway.ts:41,50`; `moderation/services/admin-moderation-local.gateway.ts:64,74`).
|
||||||
|
- `[Security]` Orders have no actor/audit field at all — `AdminOrderTimelineEntry` has no `actor` property, so cancel/refund/status-change history records *what* changed but never *who* changed it, for the most financially sensitive module in the app (`features/admin/orders/models/admin-order.model.ts:32-36`).
|
||||||
|
|
||||||
|
### Destructive actions with missing/inconsistent confirmation
|
||||||
|
|
||||||
|
- `[Admin-operator]` Product delete (single row and bulk) removes the product permanently with **zero confirmation of any kind**, not even a native `confirm()` (`features/admin/products/components/admin-products-list.component.html:134,161` → `admin-products.facade.ts:316-317`; bulk: `admin-products-list-page.component.ts:36` → `facade.ts:175-178`).
|
||||||
|
- `[Admin-operator]` Order bulk-delete removes selected orders permanently with zero confirmation — destroys financial records in one click (`features/admin/orders/pages/admin-orders-list-page.component.html:48` → `admin-orders.facade.ts:134-140`).
|
||||||
|
- `[Admin-operator]` The review bulk-action button is labeled **"archive"** (implying reversible) but actually calls `deleteReview`, which permanently splices the review out — no confirmation dialog (`moderation/pages/admin-reviews-list-page.component.html:56` → `admin-moderation.facade.ts:148-154` → `admin-moderation-local.gateway.ts:94-97`).
|
||||||
|
- `[Admin-operator]` Category bulk-delete has no confirmation, inconsistent with the same module's single-delete flow, which does confirm (`categories/pages/admin-categories-list-page.component.ts:40` vs `76-84`).
|
||||||
|
- `[QA]` The order-detail "Change status" dropdown bypasses the confirm-gated Cancel/Refund buttons next to it — picking `cancelled`/`refunded` from the dropdown applies immediately with no confirmation (`orders/pages/admin-order-detail-page.component.html:49` vs `55-57`).
|
||||||
|
- `[QA]` Terminal order statuses aren't enforced in the UI — the status dropdown stays active after an order reaches `cancelled`/`refunded`, so a terminal order can be silently moved back to any other status (`admin-order-detail-page.component.html:47-58`).
|
||||||
|
- `[Accessibility / Engineering]` Confirmation UX is implemented three inconsistent ways across the app: native `window.confirm()`/`alert()` (Categories, Orders cancel/refund, Users suspend), a themed dialog component (Media Library only), and nothing at all (Products, Orders/Reviews bulk-delete) (`categories/pages/admin-categories-list-page.component.ts:78,81`; `orders/pages/admin-order-detail-page.component.ts:80,86`; `users/pages/admin-users-page.component.ts:43`; vs `features/backoffice/media/media-library-page.component.html:126-140`).
|
||||||
|
|
||||||
|
### Missing/incorrect loading, empty, error states
|
||||||
|
|
||||||
|
- `[QA]` Order-detail and Customer-detail pages collapse "loading," "not found," and "error" into one static "Loading…" string shown forever if the record isn't found or the request errors — `loadDetail` has no `error` handler (`orders/pages/admin-order-detail-page.component.html:89-91`, facade `admin-orders.facade.ts:98-100`; `customers/pages/admin-customer-detail-page.component.html:51-53`).
|
||||||
|
- `[QA]` Products, Categories, Orders, Customers, and Transactions facades swallow load errors into an empty array with no distinct `error` signal — a genuine API failure renders as "No results found" rather than an error-with-retry state, unlike Users/Monitoring/Analytics, which do track error separately (`products/facade/admin-products.facade.ts:101-114`; `customers/facade/admin-customers.facade.ts:42-54`; `transactions/facade/admin-transactions.facade.ts:15-29`).
|
||||||
|
- `[QA]` The Reports page never checks `facade.error()` even though `AdminAnalyticsFacade` exposes it — on load failure it silently renders 0%/0 stats instead of an error message (`admin/reports/pages/admin-reports-page.component.html:1-32`, facade `admin-analytics.facade.ts:41,77`).
|
||||||
|
- `[Engineering]` Save/mutate calls across Products, Categories, and Users subscribe with only a `next` handler — a failed save/delete/role-change fails completely silently with no user-facing feedback (`products/facade/admin-products.facade.ts:305-314`; `categories/facade/admin-categories.facade.ts:314-332`; `users/facade/admin-users.facade.ts:35-50`).
|
||||||
|
|
||||||
|
### Fake/stubbed data presented as real
|
||||||
|
|
||||||
|
- `[Engineering / Product Owner]` Monitoring's security/audit events, queue depths, and webhook deliveries are entirely synthetic (seeded fake generators, hardcoded queue states, modulo-based fake webhook statuses) with no connection to any real backend, yet presented as a live security/audit surface (`monitoring/services/admin-monitoring-local.gateway.ts:14-92`).
|
||||||
|
- `[Admin-operator]` The Monitoring page loads once on construction with no polling/auto-refresh and no manual refresh control (only a retry-on-error button) (`monitoring/pages/admin-monitoring-page.component.ts:39-41`; template `:79`).
|
||||||
|
- `[Admin-operator]` The topbar global search input has no `(input)`/`(keyup.enter)` binding and no handler anywhere — it is entirely decorative (`shell/admin-layout.component.html:118`).
|
||||||
|
- `[Admin-operator]` The notification bell always opens a panel showing a static "no notifications" message — no notification data source is wired up at all (`shell/admin-layout.component.html:141-157`).
|
||||||
|
- `[Product Owner]` The Dashboard's "images without alt text" health check is hardcoded to `status: 'unknown'` with no code path that could ever resolve it — a permanent placeholder sitting alongside real, resolvable checks (`dashboard/facade/admin-dashboard.facade.ts:132`).
|
||||||
|
- `[Product Owner]` "Request Refund" doesn't touch any payment processor — it only flips `payment.status` to `refund_requested`; actually completing the refund means separately picking "refunded" from the unrelated status dropdown, with no workflow linking the two (`orders/services/admin-orders-local.gateway.ts:43-50`).
|
||||||
|
|
||||||
|
### Incomplete modules
|
||||||
|
|
||||||
|
- `[Product Owner]` Settings (`/backoffice/settings`) is fully routed and linked in nav but contains exactly one control (density toggle to localStorage) — no store/payment/tax/shipping/notification settings exist despite the nav entry implying a general settings page.
|
||||||
|
- `[Product Owner]` Seller Management's "Request Access" form submission is mocked with a bare `setTimeout` — no backend call exists, "Learn more" is static copy. Confirms [Product Owner item 5-8](#as-product-owner--business) are still accurate against current source.
|
||||||
|
- `[Product Owner]` Customer-detail "Notes" card always shows a static "notes unavailable" message — no way to add customer notes at all, unlike Orders, which supports both customer-facing and internal notes (`customers/pages/admin-customer-detail-page.component.html:28-31`).
|
||||||
|
- `[Product Owner]` "Reports" duplicates "Analytics" 1:1 — both consume the same facade and independently re-run the same nested aggregation — but Reports exposes only 3 CSV export buttons. Unclear differentiation between the two nav entries for an operator (`reports/pages/admin-reports-page.component.ts:15-20`).
|
||||||
|
|
||||||
|
### Missing validation
|
||||||
|
|
||||||
|
- `[QA / Product Owner]` The product create/edit form has **zero client-side validation** — no required-field checks (name, price, SKU), no min/max on price/discount/quantity. A completely empty or negative-priced product can be saved with no warning (`products/components/admin-product-form.component.ts`, entire file; save path `admin-products.facade.ts:305-314`).
|
||||||
|
|
||||||
|
### Performance
|
||||||
|
|
||||||
|
- `[Performance]` `AdminAnalyticsFacade.load()` chains four nested subscriptions (orders → products → categories → reviews) instead of `forkJoin`/`combineLatest`, with no cancellation of in-flight requests — rapidly toggling the date-range filter can let a stale response overwrite a newer one (`analytics/facade/admin-analytics.facade.ts:65-130`).
|
||||||
|
- `[Performance]` Dashboard-stat computations across Orders, Customers, Transactions, and Analytics each independently re-fetch the entire order list with `pageSize: 100000` rather than sharing one cached read (`orders/facade/admin-orders.facade.ts:166-169`; `customers/facade/admin-customers.facade.ts:44,57`; `analytics/facade/admin-analytics.facade.ts:79,92`).
|
||||||
|
|
||||||
|
### Engineering / tech-debt
|
||||||
|
|
||||||
|
- `[Engineering]` `AdminCustomersFacade.buildCustomers()` treats `customerOrders[0]` as the customer's "latest" order with no local sort — correctness depends entirely on the orders gateway happening to already return descending-by-`createdAt` order; swapping in a differently-ordered real gateway would silently corrupt "last order" with no compiler or runtime signal (`customers/facade/admin-customers.facade.ts:24-39` vs `orders/services/admin-orders-local.gateway.ts:20`).
|
||||||
|
- `[Engineering]` Bulk operations (Orders, Categories, Products, Moderation) fire N independent gateway calls in a loop with no `forkJoin`, no per-item error handling, and no aggregate loading indicator — one failed item in a batch gives the user no signal at all (`moderation/facade/admin-moderation.facade.ts:133-154`; `orders/facade/admin-orders.facade.ts:119-140`; `categories/facade/admin-categories.facade.ts:391-397`).
|
||||||
|
|
||||||
|
### Doc-drift confirmed against the Seller-Management audit
|
||||||
|
|
||||||
|
- `[Engineering]` `Seller-Management-Backoffice-Readiness-Audit.md` stated Settings "No route exists... Skipped, nothing to audit" — now stale: `/backoffice/settings` is a real routed page with no `comingSoon` flag (`shell/admin-nav.model.ts:48`, `app.routes.ts:266-274`).
|
||||||
|
- `[Engineering]` Since that audit, `AdminOrder` and `AdminProduct` have both gained an explicit, unread `sellerId?: string` groundwork field — partially updates the audit's "no injection point" framing at the order level, though its core point (no per-item seller attribution on `AdminOrderItem`) remains accurate (`orders/models/admin-order.model.ts:54-59`; `products/models/admin-product.model.ts:115-120`).
|
||||||
49
PRODUCT.md
49
PRODUCT.md
@@ -1,49 +0,0 @@
|
|||||||
# Product
|
|
||||||
|
|
||||||
## Register
|
|
||||||
|
|
||||||
product
|
|
||||||
|
|
||||||
## Platform
|
|
||||||
|
|
||||||
web
|
|
||||||
|
|
||||||
## Users
|
|
||||||
|
|
||||||
Primary users are tenant operators — merchants and admins who build and run their own marketplace through the Project Editor (builder) and the Admin/backoffice. They are task-focused power users: configuring theme, layout, navigation, pages, products, and static content, then publishing. Their context is repeated, deliberate work sessions where speed, clarity, and confidence that a change did what they expected matter more than delight.
|
|
||||||
|
|
||||||
Secondary users are end shoppers browsing a tenant storefront — catalog, product pages, cart, static pages. They arrive casually, judge fast, and are conversion-driven. Every storefront is themed per tenant, so shoppers should experience the tenant's identity, not the platform's.
|
|
||||||
|
|
||||||
Operators come first; shoppers second. The tool must be genuinely good to work in, and the storefront it produces must convert.
|
|
||||||
|
|
||||||
## Product Purpose
|
|
||||||
|
|
||||||
A configuration-driven, multi-tenant marketplace platform. One Angular frontend serves unlimited tenants: identity, theme, navigation, page/section/widget composition, and static content all resolve at runtime from a per-tenant `bootstrap.json`, with the tenant chosen by request host. No tenant-specific code paths exist. A new marketplace is onboarded by domain plus config plus backend data — never by forking the frontend. Success is an operator standing up and running a complete, on-brand storefront end to end without writing code, and a shopper on that storefront never sensing the platform underneath.
|
|
||||||
|
|
||||||
## Positioning
|
|
||||||
|
|
||||||
Launch and run a full marketplace with no code: from one runtime config a tenant gets a brandable storefront, an admin backoffice, and a visual editor, onboarded by domain alone. The frontend renders entirely from bootstrap JSON, so tenant identity is fully configurable and the data backend can change without touching the app. The single claim every surface reinforces: everything you see is config, not custom code.
|
|
||||||
|
|
||||||
## Brand Personality
|
|
||||||
|
|
||||||
Precise, calm, trustworthy. The platform chrome behaves like commerce infrastructure: confident, low-drama, and out of the way. It states what happened plainly, makes destructive and publishing actions unambiguous, and never competes for attention with the tenant's own branding. Voice is direct and operator-literate, not salesy.
|
|
||||||
|
|
||||||
## Anti-references
|
|
||||||
|
|
||||||
Not dated enterprise admin: no cluttered gray dashboards, tiny dense tables, or 2010-era Bootstrap backoffice. Not generic AI-SaaS template: no cream/violet gradient landings, hero-metric card rows, tracked-uppercase eyebrows on every section, or identical icon-heading-text card grids. Not consumer toy: no bubbly rounded-everything, mascots, candy colors, or gamified UI.
|
|
||||||
|
|
||||||
## Design Principles
|
|
||||||
|
|
||||||
Config, not custom — the UI's job is to make an entirely configuration-driven system feel direct and predictable; every editor control maps visibly to what it changes.
|
|
||||||
|
|
||||||
Quiet chrome, tenant identity leads — the platform's own shell stays neutral so per-tenant themes carry the storefront's character; the platform never imposes an identity over the tenant's.
|
|
||||||
|
|
||||||
Operator-first clarity — density, task speed, and unambiguous state (draft vs published, saved vs unsaved, destructive vs safe) win over decoration in the tooling surfaces.
|
|
||||||
|
|
||||||
Trust through precision — plain confirmation of what happened, honest empty/error states, and no surprises around publish, reset, or delete.
|
|
||||||
|
|
||||||
Practice what you preach — the editor and admin should feel as considered as the storefronts they produce; the tool is itself a demonstration of the platform's quality.
|
|
||||||
|
|
||||||
## Accessibility & Inclusion
|
|
||||||
|
|
||||||
WCAG 2.2 AA. Body text meets 4.5:1 contrast, all interactive flows are keyboard-navigable with visible focus states, and every animation has a `prefers-reduced-motion` alternative. Because storefront palettes are tenant-configurable, contrast must hold across themes, not just the default one.
|
|
||||||
78
README.md
78
README.md
@@ -1,78 +0,0 @@
|
|||||||
# Marketplace Frontend
|
|
||||||
|
|
||||||
Angular 21 multi-tenant marketplace platform frontend. Standalone components, signals, no NgRx. One codebase serves unlimited tenants ("marketplaces") via a per-tenant `bootstrap.json` fetched at runtime — no tenant-specific code paths.
|
|
||||||
|
|
||||||
Three surfaces on this one codebase:
|
|
||||||
- **Storefront** (`/`) — the public shopping site: catalog, product pages, cart, static/CMS pages.
|
|
||||||
- **Builder / Project Editor** (`/edit/**`) — in-app editor that edits the tenant's `BootstrapConfig` (theme, nav, homepage sections, widgets, footer, languages, static pages).
|
|
||||||
- **Backoffice / Admin** (`/:lang/backoffice/**`) — products, categories, orders, transactions, users, moderation, media, monitoring, analytics.
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
`Component (container) → Facade → Domain Service → Repository/Provider (DI token, swappable mock↔API) → Mock | API`
|
|
||||||
|
|
||||||
Enforced by `npm run arch:check` (import boundaries + circular deps), not just convention. Full detail: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), governance ADRs at `docs/architecture/foundation/**`.
|
|
||||||
|
|
||||||
## Frontend status
|
|
||||||
|
|
||||||
**Release Candidate — feature-complete.** See [`docs/PROJECT_STATUS.md`](docs/PROJECT_STATUS.md) for the honest current-state breakdown (completion %, known limitations, readiness for demo/production/backend).
|
|
||||||
|
|
||||||
## Backend
|
|
||||||
|
|
||||||
**Not implemented yet — fully specified.** Every domain currently runs against an in-memory/mock gateway except Categories (the one domain wired to a real HTTP API). The complete contract a backend engineer needs — every endpoint, DTO, auth flow, error model, upload contract, and a step-by-step implementation checklist — lives in one canonical document:
|
|
||||||
|
|
||||||
**[`docs/BACKEND.md`](docs/BACKEND.md)**
|
|
||||||
|
|
||||||
## How to switch Mock ↔ API
|
|
||||||
|
|
||||||
Toggle `useMockData` in `src/environments/environment.ts` (or `environment.production.ts`). `RuntimeProviderStrategyService` (`src/app/core/providers/runtime-provider-strategy.service.ts`) reads this flag per-domain to decide whether a facade gets the mock or real gateway. On `localhost` with `useMockData: false`, some domains (bootstrap, categories) still fall back to mock automatically so local dev never silently hits a real backend by accident — see that service for the exact per-domain logic.
|
|
||||||
|
|
||||||
## Development
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm install # install dependencies
|
|
||||||
npm start # local dev server
|
|
||||||
npm run build # production build -> dist/dexarmarket/
|
|
||||||
npm run arch:check # import-boundary + circular-dependency check
|
|
||||||
```
|
|
||||||
|
|
||||||
## Folder structure
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/
|
|
||||||
├── app/
|
|
||||||
│ ├── components/ # Shared storefront components (header, footer, product-card, etc.)
|
|
||||||
│ ├── core/ # Auth, admin-auth, config/tenant resolution, DI providers, interceptors
|
|
||||||
│ ├── dynamic-renderer/ # Bootstrap JSON -> section/widget rendering pipeline (live homepage engine)
|
|
||||||
│ ├── facades/ # Runtime, website, builder, and backoffice facades
|
|
||||||
│ ├── features/ # Domain features: admin/*, project-editor, content-management, website/*
|
|
||||||
│ ├── guards/ # Route guards (language, admin-auth, dirty-state, etc.)
|
|
||||||
│ ├── i18n/ # Translation service, pipe, and locale packs (en/ru/hy)
|
|
||||||
│ ├── pages/ # Top-level routed pages: home, cart, static-page
|
|
||||||
│ ├── services/ # API, cart, auth, SEO, Telegram, and language services
|
|
||||||
│ ├── shared/ # Shared UI primitives (button, dialog, confirm-dialog, table, etc.)
|
|
||||||
│ └── widgets/ # Dynamic-renderer widget components
|
|
||||||
├── assets/mock/ # Local mock configuration and catalog data
|
|
||||||
├── environments/ # Development and production environment settings (incl. useMockData)
|
|
||||||
└── styles/ # Shared global styles and themes
|
|
||||||
```
|
|
||||||
|
|
||||||
## Documentation map
|
|
||||||
|
|
||||||
Full index: [`docs/PROJECT_INDEX.md`](docs/PROJECT_INDEX.md). Key entry points:
|
|
||||||
|
|
||||||
| Doc | What it covers |
|
|
||||||
|---|---|
|
|
||||||
| [`docs/PROJECT_STATUS.md`](docs/PROJECT_STATUS.md) | Current completion status, honest limitations, demo/production readiness |
|
|
||||||
| [`docs/BACKEND.md`](docs/BACKEND.md) | The one canonical backend spec — endpoints, DTOs, auth, security, errors, uploads, checklist |
|
|
||||||
| [`docs/NEXT_PHASE.md`](docs/NEXT_PHASE.md) | Roadmap: backend integration → testing → performance → monitoring → v2 |
|
|
||||||
| [`docs/TODO.md`](docs/TODO.md) | Release blockers only |
|
|
||||||
| [`docs/KNOWN-ISSUES.md`](docs/KNOWN-ISSUES.md) | Real, reproducible, currently-open frontend bugs |
|
|
||||||
| [`docs/PRODUCT_BACKLOG.md`](docs/PRODUCT_BACKLOG.md) | Items needing a client/business decision |
|
|
||||||
| [`DESIGN.md`](DESIGN.md) | Visual design system |
|
|
||||||
| [`PRODUCT.md`](PRODUCT.md) | Product positioning |
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
|
|
||||||
- Authentication and payment integrations are on their existing contracts — see `docs/BACKEND.md` for the auth/security contract a real backend must satisfy.
|
|
||||||
- Client-facing content should avoid placeholder names, mock labels, and temporary routes.
|
|
||||||
@@ -1,70 +0,0 @@
|
|||||||
# Angular 22 Upgrade Plan (research only — not applied)
|
|
||||||
|
|
||||||
Feasibility assessment for upgrading from the current Angular 21.1.5 to Angular 22. **No upgrade was performed** — this is a plan, per mission instructions ("Do NOT upgrade automatically. Stop.").
|
|
||||||
|
|
||||||
## Current state (verified against `package.json` + npm registry, 2026-07-25)
|
|
||||||
|
|
||||||
| Package | Current | Latest available |
|
|
||||||
|---|---|---|
|
|
||||||
| `@angular/core` (+ animations/cdk/common/compiler/forms/platform-browser/router/service-worker) | 21.1.5 | 21.2.18 (latest 21.x) / 22.1.0-rc.0 (latest 22.x) |
|
|
||||||
| `typescript` | ~5.9.3 | 6.0.3 stable |
|
|
||||||
| `rxjs` | ~7.8.0 | compatible with both 21 and 22 |
|
|
||||||
| `zone.js` | ~0.16.0 | compatible with 22 (`~0.15.0 \|\| ~0.16.0` required) |
|
|
||||||
| `primeng` | ^21.0.3 | 22.0.0 stable exists |
|
|
||||||
| `@lucide/angular` | ^1.25.0 | no upper Angular bound (`>=17.0.0`) — not a blocker |
|
|
||||||
| Node.js (this environment) | v22.16.0 | Angular 22 CLI requires `^22.22.3 \|\| ^24.15.0 \|\| >=26.0.0` — **current Node does not satisfy this** |
|
|
||||||
|
|
||||||
Correction to the project's own status tracking: `docs/PROJECT_INDEX.md`/`CLAUDE.md` describe this as "Angular 18+" — the repo is actually already on **21.1.5**, one major behind the latest stable (22.1). This is a much smaller jump than "18→22" would imply.
|
|
||||||
|
|
||||||
## Verdict: upgrade is safe, with 2 concrete pre-requisites
|
|
||||||
|
|
||||||
Nothing found in this codebase blocks the jump on its own merits — the risk is entirely in the dependency chain, not the app code:
|
|
||||||
|
|
||||||
1. **`primeng@^21.0.3` peer-depends on `@angular/core@^21.0.7` only** — it does not accept Angular 22 today. **However**, this dependency is already dead code (`docs/KNOWN-ISSUES.md` item 12): its only consumer, `items-carousel`, was deleted during RC PERF-01, and its removal is already planned, just blocked on an unrelated `npm uninstall` failure (see #2). Once `primeng`/`primeicons` are actually removed from `package.json`, this blocker disappears entirely — no need to wait for/adopt `primeng@22`.
|
|
||||||
2. **`barry-cache@^0.1.0` in `package.json` no longer resolves** (`ETARGET`) — confirmed via `npm view barry-cache`: the real published range is now `0.9.3` (20 versions total), and `^0.1.0` doesn't intersect anything currently on the registry. This is what's been silently blocking `npm install`/`npm uninstall` all cycle (referenced in `docs/PERFORMANCE_REPORT.md`, `docs/KNOWN-ISSUES.md` item 12). **This must be fixed first** — bump `barry-cache` to a current version — or `ng update` itself will fail the same way `npm uninstall primeng` already does.
|
|
||||||
3. **Node.js**: this dev environment runs v22.16.0; Angular 22's CLI requires `^22.22.3 \| ^24.15.0 \| >=26.0.0`. A Node bump is required before `ng update` will even run, independent of the app.
|
|
||||||
|
|
||||||
Once those 3 are resolved, the app itself is well-positioned:
|
|
||||||
- 100% standalone components already (no NgModules to migrate).
|
|
||||||
- 190/191 components already `ChangeDetectionStrategy.OnPush` (per `docs/PERFORMANCE_REPORT.md`) — directly aligned with v22 making OnPush the default; this app barely changes behavior from that shift.
|
|
||||||
- Heavy existing signals usage (facades are signal-based per `docs/ARCHITECTURE.md`/ADR-007) — aligned with where Angular is going (Signal Forms, `resource()`), no fighting the framework.
|
|
||||||
- Zero usage found of the specific APIs v22 removes: `ComponentFactoryResolver`, `ComponentFactory`, `provideRoutes()`, `CanMatchFn` (grepped `src/app/**`, zero hits).
|
|
||||||
- Zone-based (not zoneless) via `provideZoneChangeDetection({eventCoalescing: true})` in `app.config.ts` — this continues to work under v22, no forced zoneless migration needed to upgrade.
|
|
||||||
|
|
||||||
## Benefits
|
|
||||||
|
|
||||||
- Bug fixes and perf improvements shipped between 21.1 and 22.1 (6+ months of patches this repo isn't getting).
|
|
||||||
- OnPush-by-default aligns with where this codebase already is — near-zero migration cost for that specific change, unlike a codebase still on default change detection.
|
|
||||||
- Keeps pace with `primeng`/ecosystem packages that are already moving to v22-only releases (relevant once primeng is actually removed and no longer a constraint either way).
|
|
||||||
- Closes the gap before the next major (v23) makes this a two-major jump instead of one.
|
|
||||||
|
|
||||||
## Risks / breaking changes relevant to this codebase
|
|
||||||
|
|
||||||
1. **Route parameter inheritance changes from `emptyOnly` to `always`.** No explicit `paramsInheritanceStrategy` override was found in `app.routes.ts` or `app.config.ts` — meaning this app is on the default, and the default is changing. **Concrete risk**: any component reading `ActivatedRoute.params`/`paramMap` that currently expects to NOT see a parent route's params (e.g. a child route under `/:lang/backoffice/:id/edit` reading only its own segment) could start receiving inherited params it didn't before. Needs a manual audit of nested routes with route params at each level — `src/app/app.routes.ts` has several (product detail, category, admin edit routes) — not just a blanket "run the test suite and hope."
|
|
||||||
2. **TypeScript 6.0 minimum** — current is 5.9.3, a straightforward `npm install typescript@^6.0.3` bump, but TS 6 does include its own (separate) breaking changes to check independently of Angular (stricter inference in some cases) — budget a pass for TS compiler errors post-bump, not just Angular's.
|
|
||||||
3. **`primeng`/`primeicons` removal must land first** (see Verdict #1) — sequencing matters: remove dead deps → fix `barry-cache` → bump Node → `ng update`, not the reverse.
|
|
||||||
4. **No automated test suite beyond the default Jasmine/Karma scaffold** was confirmed running in this session (`docs/SPRINT-PLAN.md` Sprint 29 notes: "Translation validation / lint... No lint script exists") — meaning post-upgrade regression detection leans entirely on `tsc --noEmit` + `ng build` + manual verification, the same constraint every other pass this cycle has worked under. The route-params risk above in particular needs *manual* route-by-route verification, not just a green build, since it's a runtime behavior change a type-checker can't catch.
|
|
||||||
|
|
||||||
## Migration steps (sequenced)
|
|
||||||
|
|
||||||
1. **Unblock tooling**: bump `barry-cache` in `package.json` to a currently-published version (`0.9.3` or latest at execution time) — verify with `npm view barry-cache versions` first.
|
|
||||||
2. **Remove dead `primeng`/`primeicons`** (already-planned, `docs/KNOWN-ISSUES.md` item 12) — now unblocked by step 1. Verify `npm run build` still green afterward (it was already confirmed code-dead in RC PERF-01, this just finishes the dependency removal).
|
|
||||||
3. **Bump Node.js** in the dev/CI environment to satisfy `^22.22.3 | ^24.15.0 | >=26.0.0`.
|
|
||||||
4. **Bump TypeScript** to `^6.0.3`, run `tsc --noEmit`, fix any TS-6-specific compiler errors before touching Angular.
|
|
||||||
5. **Run `ng update @angular/core@22 @angular/cli@22`** (and `@angular/cdk@22` if still a dependency) — let the official schematic handle the mechanical parts.
|
|
||||||
6. **Audit route-param inheritance** manually across every nested route with params in `app.routes.ts` (product detail, category, admin edit/detail routes) — the one behavior change with no automated safety net.
|
|
||||||
7. **Full verification pass**: `tsc --noEmit`, `npm run build`, `npm run arch:check`, plus a live browser walkthrough of the same route list used in `docs/RELEASE_REPORT.md` (storefront/builder/backoffice) — this upgrade deserves the same rigor as that pass, not just a build check.
|
|
||||||
8. **Commit, do not push** without explicit sign-off, same as every other pass this cycle.
|
|
||||||
|
|
||||||
## Estimated effort
|
|
||||||
|
|
||||||
- Steps 1-4 (unblock tooling, remove dead deps, Node/TS bump): **0.5-1 day** — mechanical, low risk, mostly already-planned work.
|
|
||||||
- Step 5 (`ng update`): **0.5 day** — the schematic does most of the work given zero deprecated-API usage found.
|
|
||||||
- Step 6 (route-param audit): **0.5-1 day** — the one genuinely manual, judgment-requiring step; depends on how many nested-param routes actually exist and how many read parent params today (needs a route-by-route trace, not estimated further without doing that trace).
|
|
||||||
- Step 7 (verification): **0.5-1 day** — matches the RC walkthrough pass's effort, since that's the closest analog in this codebase's own history.
|
|
||||||
|
|
||||||
**Total: ~2-3.5 days** for one engineer, assuming no surprises in the route-param audit (the one genuinely unknown risk). This is a small-to-medium upgrade, not a large one — the app's existing standalone/signals/OnPush posture did the hard work already.
|
|
||||||
|
|
||||||
## Recommendation
|
|
||||||
|
|
||||||
Safe to schedule. Not urgent (still only one major behind), but low-risk and the gap only grows if deferred further. Do the two prerequisite fixes (`barry-cache`, `primeng` removal) regardless of upgrade timing — they're blocking other things too (this dependency chain is also what's stopping the `primeng` bundle-size win noted in `docs/PERFORMANCE_REPORT.md`).
|
|
||||||
@@ -1,73 +0,0 @@
|
|||||||
# ARCHITECTURE
|
|
||||||
|
|
||||||
## Platform principles
|
|
||||||
|
|
||||||
- One codebase, unlimited tenants. No tenant-specific implementation code in the frontend.
|
|
||||||
- Tenant behavior is controlled entirely by configuration loaded at bootstrap (`GET /bootstrap`, tenant resolved server-side by domain).
|
|
||||||
- Prefer configuration over conditionals, composition over inheritance.
|
|
||||||
- Authentication, payment, and authorization contracts/behavior are frozen and must not be redesigned as part of platform work (`docs/architecture/foundation/adr/ADR-010-backward-compatibility-for-auth-payment-authorization.md`).
|
|
||||||
- No circular dependencies; shared/UI layers are feature-agnostic.
|
|
||||||
|
|
||||||
These rules are enforced, not aspirational — see `docs/architecture/foundation/README.md` and the ADR set below, plus `npm run arch:check` (import-boundary + circular-dependency checks).
|
|
||||||
|
|
||||||
## Architecture Decision Records (source of truth — read directly, do not treat this file as a paraphrase)
|
|
||||||
|
|
||||||
All under `docs/architecture/foundation/adr/`:
|
|
||||||
|
|
||||||
- **ADR-001** — platform model (multi-tenant, config-driven).
|
|
||||||
- **ADR-002** — layered feature architecture.
|
|
||||||
- **ADR-003** — import boundaries and dependency direction.
|
|
||||||
- **ADR-004** — configuration bootstrap and provider abstraction.
|
|
||||||
- **ADR-005** — dynamic page/section/widget rendering.
|
|
||||||
- **ADR-006** — UI component purity and container/facade pattern.
|
|
||||||
- **ADR-007** — state management and facade boundaries.
|
|
||||||
- **ADR-008** — theme engine and design-token runtime.
|
|
||||||
- **ADR-009** — feature flags and capability guards.
|
|
||||||
- **ADR-010** — backward compatibility for auth/payment/authorization.
|
|
||||||
- **ADR-011** — optional Seller Management module (typed foundation only, not built; see `docs/architecture/foundation/Seller-Management-Diagrams.md`).
|
|
||||||
|
|
||||||
Companion standards docs (also `docs/architecture/foundation/`, kept as-is, enforced): `Coding-Standards.md`, `Naming-Conventions.md`, `Dependency-Rules.md`, `Folder-Blueprint.md`, `Import-Boundary-Matrix.md`, `State-Management-Standards.md`, `Configuration-Standards.md`, `Component-Standards.md`, `Service-Standards.md`.
|
|
||||||
|
|
||||||
## Layered architecture
|
|
||||||
|
|
||||||
```
|
|
||||||
Component (container) --> Facade --> Domain Service --> Repository/Provider --> Mock | API
|
|
||||||
```
|
|
||||||
|
|
||||||
- **Container/page components** own routing, orchestration, and DI of a facade. They hold no business logic.
|
|
||||||
- **Presentational components** are `@Input()`/`@Output()`-only: no `HttpClient`, no storage, no environment access, no facade injection (ADR-006). The Project Editor's *sections* (`features/project-editor/sections/*`) are an accepted exception — they are container/section components, not shared presentational UI, so they may inject the facade directly (see `docs/EDITOR.md`).
|
|
||||||
- **Facades** (`facades/**`, or feature-local `facade/`) are the only thing components talk to. They expose signals/observables and imperative methods; they compose one or more domain services (ADR-007).
|
|
||||||
- **Domain services** (`core/<domain>/*.service.ts`) convert backend DTOs into domain models via a **mapper**, and expose domain-shaped methods. DTOs never leak past the mapper boundary.
|
|
||||||
- **Repositories/providers** are swappable via injection tokens (e.g. `PRODUCT_DATA_PROVIDER`, `CATEGORY_REPOSITORY`, `BACKOFFICE_DATA_PROVIDER`, `ADMIN_DASHBOARD_METRICS_GATEWAY`) so mock and real-API implementations can be swapped without touching facades or components — the same pattern used throughout `core/`, `features/admin/*`, and `features/backoffice/*`.
|
|
||||||
|
|
||||||
## Bootstrap / configuration engine
|
|
||||||
|
|
||||||
- `ConfigService` loads `BootstrapConfig` (see `docs/BACKEND.md#1-bootstrap`) once at startup; `PlatformRuntimeService` applies it (theme, branding, runtime state) and can `reloadFromBootstrap()` for in-memory preview without a full page reload.
|
|
||||||
- The bootstrap is the single source of truth for pages, sections, widgets, theme, navigation, footer, static pages, and feature flags (ADR-004).
|
|
||||||
- The Project Editor mutates an in-memory draft of the same `BootstrapConfig` — there is no parallel editor-only model.
|
|
||||||
|
|
||||||
## Dynamic page / section / widget rendering (ADR-005)
|
|
||||||
|
|
||||||
Render pipeline: `page config -> section engine -> section renderer -> widget host -> registered widget component`.
|
|
||||||
|
|
||||||
- **Section Engine** (`dynamic-renderer/section-engine/section-engine.service.ts`) builds an ordered page render model from `PageConfig.sections`, applying `order`, `layout` (`SectionLayoutConfig.strategy`: `stack | grid | hero | carousel | split`), and `visibility` (desktop/tablet/mobile).
|
|
||||||
- **Page Renderer** (`dynamic-renderer/page-renderer/page-renderer.service.ts`) delegates to the Section Engine.
|
|
||||||
- **Widget Host** (`dynamic-renderer/widget-host/widget-host.service.ts`) resolves each widget's component via the **Widget Manifest** (`widgets/registry/widget-manifest.service.ts`, `widgets/contracts/widget-manifest.contract.ts`) and its data via the **Data Source Resolver** (`widgets/resolvers/data-source-resolver.service.ts`), which delegates to `CategoryFacade`/`ProductFacade` — widgets never call APIs directly.
|
|
||||||
- Widgets receive only `{ section config, resolved data }` as inputs; they render presentation only, never fetch or mutate.
|
|
||||||
- Unknown/unregistered widget types render a safe fallback; this is also surfaced in `features/diagnostics` (dev-only, route `/__diagnostics`).
|
|
||||||
- `dynamic-page-layout.component.ts` (`layouts/containers/`) is the top-level container that composes Section Engine output using `PlatformLayoutConfig.type` (`default | sidebar-left | carousel-home | minimal`).
|
|
||||||
|
|
||||||
## Theme engine (ADR-008)
|
|
||||||
|
|
||||||
- `ThemeConfig` (`shared/models/config/theme.model.ts`): `themeId`, `mode` (`light | dark | system`), `palette` (12 semantic colors), `typography`, `spacing`, `borderRadiusScale`, `shadows`, `iconSet`.
|
|
||||||
- Applied as CSS custom properties at runtime; components/widgets consume tokens, never hardcoded brand colors.
|
|
||||||
- Three tenant theme stylesheets live under `src/styles/themes/*.theme.scss` — see `docs/FRONTEND.md` for the CSS custom property convention.
|
|
||||||
|
|
||||||
## Feature flags / capability guards (ADR-009)
|
|
||||||
|
|
||||||
- `bootstrap.featureFlags` (typed) plus the broader `bootstrap.features` (`MarketplaceFeaturesConfig`) surface for UI-facing toggles (wishlist, compare, reviews, recommendations, search history, etc.).
|
|
||||||
- Feature resolution falls back across older config surfaces to preserve behavior as the flag model evolved across sprints — see `docs/BACKEND.md#1-bootstrap` for the full field list.
|
|
||||||
|
|
||||||
## Diagnostics (dev-only)
|
|
||||||
|
|
||||||
`features/diagnostics/` (route `/__diagnostics`, excluded from production) validates bootstrap structure (missing fields, unknown widget types, duplicate ids, unknown layout values, missing translations) and runtime health (widget render failures, missing datasources), scored 0-100. Useful when investigating a bootstrap authored by the Project Editor.
|
|
||||||
5214
docs/BACKEND.md
5214
docs/BACKEND.md
File diff suppressed because it is too large
Load Diff
@@ -1,68 +0,0 @@
|
|||||||
# Dead-Config Audit (Sprint G)
|
|
||||||
|
|
||||||
Mechanical sweep of every field in `BootstrapConfig` and its sub-models
|
|
||||||
(`src/app/shared/models/config/*.model.ts`), cross-referenced against
|
|
||||||
`src/app/features/project-editor/schema/editor-schema.ts` (`SECTION_FIELD_SCHEMAS`)
|
|
||||||
to find fields that are editable in the Project Editor but have no real runtime
|
|
||||||
consumer — the same bug class as `HeaderConfig.showProfile` and `layout.columns`
|
|
||||||
(both fixed earlier this cycle). Non-editable fields are listed for completeness
|
|
||||||
but were not a priority (nothing in the editor lets a client set them, so there's
|
|
||||||
no ghost-setting UX to fix).
|
|
||||||
|
|
||||||
Status legend: **live** (read, has effect) / **dead** (never read outside the
|
|
||||||
editor) / **inert** (read, but the effect is unreachable or a stub) / **n/a**
|
|
||||||
(not client-editable today, lower priority per sprint scope).
|
|
||||||
|
|
||||||
## Editable fields (client-facing — checked first)
|
|
||||||
|
|
||||||
| Field | Status | Recommendation | Outcome |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `header.show*` (8 flags) | live | none | `header.component.html` reads every one |
|
|
||||||
| `theme.palette.*` (12 colors) | live | none | `theme-css-vars.mapper.ts` |
|
|
||||||
| `theme.mode` | inert | needs decision | already tracked in `PRODUCT_BACKLOG.md` |
|
|
||||||
| `layout.type` ("Site Layout") | **dead** | needs decision | see below — not fixed this pass |
|
|
||||||
| `branding.brandName/logoUrl/logoCompactUrl/faviconUrl` | live | none | header/footer/meta consumers |
|
|
||||||
| `seo.default.title/description` | live | none | `seo.service.ts` |
|
|
||||||
| `localization.defaultLocale/supportedLocales` | live | none | language switching |
|
|
||||||
| `tenant.host/websiteBaseUrl` | inert by design | none | frontend never resolves its own tenant (ADR-001) — this is backend routing metadata, not something the SPA is meant to read back |
|
|
||||||
| `company.companyName` | **dead** | needs decision | see below — not fixed this pass |
|
|
||||||
| `company.address.street` | **dead → fixed** | wire | now shown in footer bottom bar |
|
|
||||||
| `company.contacts.phone` | **dead → fixed** | wire | now shown in footer bottom bar (`tel:` link) |
|
|
||||||
| `company.contacts.email` | live | none | `ui-runtime.facade.ts` fallback chain |
|
|
||||||
| `footer.copyrightText/paymentIcons/socialLinks/columns` | live | none | `footer-resolver.service.ts` |
|
|
||||||
| `footer.logoUrl` | **dead → fixed** | wire | `LogoComponent` gained `srcOverride`, footer passes it |
|
|
||||||
| `catalog.navigationMode` | inert (deliberate placeholder) | leave as-is | renders a labeled placeholder card + `catalog.navigationPlaceholder` i18n string; the alternate nav UIs (mega-menu, top-carousel, left-nav) don't exist yet — building them is a real feature, not a wiring fix |
|
|
||||||
| `catalog.suggestionsEnabled` | **dead → fixed** | wire | `SearchFacade.autocomplete()` now short-circuits to no suggestions when false |
|
|
||||||
| `catalog.searchHistoryEnabled` | live | none | `catalog-container.component.ts` |
|
|
||||||
| `productPage.questions.*` | live | none | `product-details-container.component.ts` |
|
|
||||||
| `userExperience.recentlyViewed.enabled` | live | none | multiple consumers |
|
|
||||||
| `navigation.header` | **dead** | needs decision | see below — not fixed this pass |
|
|
||||||
| `navigation.footer` | live | none | `footer-resolver.service.ts` fallback tier |
|
|
||||||
| `pages` / `staticPages` | live | none | core rendering pipeline |
|
|
||||||
|
|
||||||
## Non-editable fields (lower priority — `n/a`)
|
|
||||||
|
|
||||||
`branding.legalName/slogan/supportPhone/appIconUrl/galleryUrls`,
|
|
||||||
`company.registrationNumber/taxId`, `tenant.defaultCurrency/supportedCurrencies/timezone`,
|
|
||||||
`featureFlags.blog/chat/coupons/loyalty/giftCards/invoices`,
|
|
||||||
`features.brands/manufacturers`, `permissions.definitions/roles` (used elsewhere,
|
|
||||||
not via this config path), `userExperience.recentlyViewed.widgetEnabled`,
|
|
||||||
`catalog.showBreadcrumbs/showCategoryBanner/showSubcategoryChips/enabledFilters/availableSorts/defaultSort`
|
|
||||||
— none of these have an editor control today, so no client can create a false
|
|
||||||
expectation by setting them. Flagged here for completeness; no action taken.
|
|
||||||
|
|
||||||
## Fixed this pass (trivially wireable)
|
|
||||||
|
|
||||||
1. **`footer.logoUrl`** — `LogoComponent` (`src/app/components/logo/logo.component.ts`) gained an optional `srcOverride` input; `FooterResolverService`/`FooterComponent` now resolve and pass `footer.logoUrl`, falling back to the brand logo exactly as before when unset.
|
|
||||||
2. **`company.address.street` / `company.contacts.phone`** — `UiRuntimeFacade` gained `contactPhone()`/`companyAddress()` (same fallback pattern as the existing `contactEmail()`); footer bottom bar now renders a `tel:` link and the address next to the existing email link when present.
|
|
||||||
3. **`catalog.suggestionsEnabled`** — `SearchFacade.autocomplete()` now reads the bootstrap snapshot and returns no suggestions when the flag is `false`, instead of always running autocomplete regardless of the toggle.
|
|
||||||
|
|
||||||
## Left dead, tracked (needs a decision, not a mechanical fix)
|
|
||||||
|
|
||||||
- **`layout.type`** ("Site Layout" selector, Theme section) — top-level `BootstrapConfig.layout` is edited but never applied to any page; page layout comes entirely from each `PageConfig.layout` (see `SectionEngineService.resolveLayoutType`), which this global selector doesn't touch. Wiring it requires deciding *which* page(s) it should drive (homepage only? every page without its own override?) — a product decision, not a mechanical fix. Tracked in `docs/PRODUCT_BACKLOG.md`.
|
|
||||||
- **`company.companyName`** — Footer editor has a "Company Name" field with zero runtime consumers. The footer already has a copyright fallback (`© {year} {brandName}`, `footer.component.html`) using `branding.brandName`, not `company.companyName` — these are meant to be distinct (brand vs. legal entity name), so blindly reusing one for the other would be a content decision, not a safe mechanical fix. Tracked in `docs/PRODUCT_BACKLOG.md`.
|
|
||||||
- **`navigation.header`** — editable list of header nav items in the Navigation section, but `HeaderComponent` never reads `NavigationConfig.header` at all; the header's own category menu comes from `CategoryFacade`, not this list. Rendering an actual configurable top-nav (positioning, active-state, children/dropdowns) is real feature work, not a one-line wire. Tracked in `docs/KNOWN-ISSUES.md`.
|
|
||||||
|
|
||||||
## Not touched
|
|
||||||
|
|
||||||
`theme.mode` (dark mode) stays exactly as already tracked in `docs/PRODUCT_BACKLOG.md` — no new information found, confirmed still inert.
|
|
||||||
163
docs/EDITOR.md
163
docs/EDITOR.md
@@ -1,163 +0,0 @@
|
|||||||
# EDITOR (Project Editor)
|
|
||||||
|
|
||||||
Replaces the old `docs/Project-Editor.md` (content merged in below and extended with the Sprint 19 field-description/dropdown work).
|
|
||||||
|
|
||||||
The Project Editor (`src/app/features/project-editor/`) edits the tenant's `BootstrapConfig` (`docs/BACKEND.md#1-bootstrap`) directly — no parallel model. It is out of scope for products, categories, orders, or analytics management (those live under `features/admin/*`/`features/backoffice/*`, see `docs/BACKEND.md` §3 CRUD Contracts).
|
|
||||||
|
|
||||||
```
|
|
||||||
src/app/features/project-editor/
|
|
||||||
pages/ route container
|
|
||||||
sections/ one component per editor tab (see below)
|
|
||||||
components/ shared editor UI (save bar, HTML editor)
|
|
||||||
models/ ProjectEditorState, EDITOR_SECTION_BOOTSTRAP_KEYS
|
|
||||||
schema/ field-schema registry, validators/, history.util (Sprint X+1, see below)
|
|
||||||
services/ ProjectValidator, ProjectEditorDraftStorageService, LocaleSyncService
|
|
||||||
facade/ ProjectEditorFacade
|
|
||||||
```
|
|
||||||
|
|
||||||
Route: `/edit/:section` or `/{lang}/edit/:section`. `/backoffice/static-pages` (the Admin dashboard) redirects here (`/edit/static-pages`) rather than hosting a second CRUD surface over the same `bootstrap.staticPages` data (Sprint X+2 — see `docs/StaticPages.md`).
|
|
||||||
|
|
||||||
## Facade
|
|
||||||
|
|
||||||
`ProjectEditorFacade` exposes: `loadBootstrap()`, `updateBootstrap(updater)`, `exportBootstrap()`, `importBootstrap()`, `preview()`, `save()`, `publish()`, `undo()`, `redo()`, plus signals `bootstrap`, `status` (`draft|published`), `dirty`, `canUndo`, `canRedo`, `lastSavedAt`, `lastPublishedAt`, `validationIssues`, `blockingIssues`, `hasBlockingIssues`, `issuesByField`, `issuesBySection`, `modifiedFields`, `modifiedSections`, `changeSummary`, `homepageWidgets`, `homepagePage`, plus the `fieldError(key)` method. Components in `sections/*` inject this facade directly (an accepted exception to the presentational-component rule, per ADR-006 — these are container/section components, not shared UI). See "Configuration schema, form engine, and validation architecture" below for the schema/validator/undo internals.
|
|
||||||
|
|
||||||
## Sections
|
|
||||||
|
|
||||||
| Section | Component | Covers |
|
|
||||||
|---|---|---|
|
|
||||||
| General | `general-section` | marketplace name, domain, description, default/supported languages |
|
|
||||||
| Branding | `branding-section` | logo, small logo, favicon, social share (OG) image, gallery, marketplace title — all image fields use `app-image-field` (thumbnail preview + replace/remove) |
|
|
||||||
| Theme | `theme-section` | palette colors (live, applied as CSS custom properties), theme mode (**not applied at runtime, see Known gaps**), site layout mode |
|
|
||||||
| Header | `header-section` | logo/search/categories/languages/cart/profile/wishlist/compare/region toggles, layout (default/centered), sticky |
|
|
||||||
| Footer | `footer-section` | company info, address, phone, email, copyright, payment icons, social links, static pages list |
|
|
||||||
| Homepage | `homepage-section` | homepage section list: visibility, order (drag-and-drop), layout strategy, columns |
|
|
||||||
| Widgets | `widgets-section` | homepage widget configuration — typed editors for hero/categories/product-collection, JSON fallback (with draft-preserving inline error, not silent-discard) for everything else |
|
|
||||||
| Static Pages | `static-pages-editor` (`features/content-management/`) | Full CRUD, media, SEO, per-page draft/publish, device preview, nav integration — see `docs/StaticPages.md` (Sprint X+2) |
|
|
||||||
| Marketplace Features | `features-section` | feature flags, catalog navigation mode, search suggestions/history, recently viewed, reviews/questions/recommendations |
|
|
||||||
| Languages | `languages-section` | add/remove supported locale, set default locale; syncs translation keys across static pages and nav labels via `LocaleSyncService` |
|
|
||||||
| Navigation | `navigation-section` | header nav: add/remove/reorder/edit label/URL/visibility, per-locale via `app-locale-tabs`. Flat footer nav: same. Grouped (column-based) footer nav is read-only here — edit via Footer tab. |
|
|
||||||
| Preview | `preview-section` | export/import JSON, in-memory runtime preview without full reload |
|
|
||||||
|
|
||||||
## Save / publish / draft / reset model
|
|
||||||
|
|
||||||
- **Save**: `save()` snapshots the current in-memory bootstrap as "last saved" (`lastSavedAt`). `ProjectEditorDraftStorageService` persists the full draft to `localStorage` (`projectEditor.draftBootstrap.v1`, scoped by `tenant.id`) on every `updateBootstrap()`, `save()`, and `publish()` call.
|
|
||||||
- **Publish**: runs `ProjectValidator`; if clean, calls `PlatformRuntimeService.reloadFromBootstrap()`, sets `status = 'published'`, sets `lastPublishedAt`, and becomes the new `originalBootstrap` baseline used by reset.
|
|
||||||
- **Draft restore**: on `loadBootstrap()`, if a stored draft exists for the same tenant it loads instead of the fresh fetch, and `draftRestored` is set (shown as a dismissible banner in the save bar).
|
|
||||||
- **Reset section**: reverts one section's bootstrap keys (per `EDITOR_SECTION_BOOTSTRAP_KEYS` in `models/project-editor.model.ts`) to `originalBootstrap`. Confirmation required.
|
|
||||||
- **Reset draft**: reverts the entire bootstrap to `originalBootstrap` and clears the persisted local draft. Confirmation required.
|
|
||||||
- **Per-field reset is not implemented** — no per-field default registry exists; only section- and project-level reset.
|
|
||||||
- **No backend persistence exists for any of this today** — see `docs/BACKEND.md` §1 (Bootstrap: Draft vs Published) and §8 (Real Backend Implementation Guide) for the endpoints needed.
|
|
||||||
|
|
||||||
## Configuration schema, form engine, and validation architecture (Sprint X+1)
|
|
||||||
|
|
||||||
**Approach: metadata-augmented, not fully schema-driven.** Section templates stay hand-authored (`sections/*.component.html`); a field-schema registry sits alongside them as the single source of truth for field identity, labels, and validator wiring. This was chosen over a schema-driven renderer to preserve every existing template/UX pixel-for-pixel while still centralizing metadata and validation — the highest-value, lowest-regression-risk option given 11 mature section templates already built on the `shared/ui` primitives (see the primitives table above).
|
|
||||||
|
|
||||||
### Field-schema registry (`schema/`)
|
|
||||||
|
|
||||||
- `field-schema.model.ts` — `FieldSchema`: `{ key, section, type, labelKey, hintKey?, default?, required?, validators? }`. `key` is a dot path into `BootstrapConfig` (e.g. `theme.palette.primary`), unique per section. `validators` references reusable validator names (`hexColor`, `url`, `email`, `json`, `css`, `localeCompleteness`, `duplicateRoutes`, `widgetConfig`) rather than embedding logic.
|
|
||||||
- `editor-schema.ts` — `SECTION_FIELD_SCHEMAS`: every editable field, one entry per section, sourced from what each template already renders. `ALL_FIELD_SCHEMAS` flattens it.
|
|
||||||
- `editor-schema.service.ts` (`EditorSchemaService`, `providedIn: 'root'`) — `getFields(section)`, `getField(key)`, `all()`, `getByPath(source, key)` (safe dot-path resolver, never throws on a missing segment).
|
|
||||||
|
|
||||||
The schema is currently consumed by the facade (validation issue → field mapping, modified-field diffing, change-summary labels), not by the templates directly — templates keep calling `facade.updateBootstrap()` the same way they always did.
|
|
||||||
|
|
||||||
### Centralized validators (`schema/validators/`)
|
|
||||||
|
|
||||||
`primitives.ts` holds pure, framework-free functions — one per concern, reused everywhere that concern appears: `isValidHexColor`, `isValidHttpUrl`, `isValidEmail`, `validateJson`, `validateCss` (brace-balance check, comments stripped), `extractStyleBlocks` (pulls `<style>` bodies out of static-page HTML), `normalizeRoute` (trim/strip-slashes/lowercase for duplicate comparison).
|
|
||||||
|
|
||||||
`ProjectValidator` (`services/project-validator.service.ts`) composes these primitives into checks and tags every `ProjectValidationIssue` with `section`, `fieldKey`, and `severity` (`'error'` blocks Publish, `'warning'` is advisory). Checks: missing `branding.logoUrl`, no supported locales, **default locale not itself in the supported-locales list** (error — catches General's free-text default-language field pointing at an unsupported code), invalid `tenant.websiteBaseUrl`, duplicate static-page slugs, **duplicate routes** across `pages`/`staticPages` (warning), empty homepage, a homepage widget with no `type`, **malformed widget config** — missing `id`/`type`/`version`/`props` (error), duplicate header nav links, invalid theme colors, **invalid CSS** inside static-page `<style>` blocks (warning), missing translations for a supported locale, layout/section-layout values outside the known enums, **invalid company contact email** (error), **invalid footer social-link URL** (warning), and **incomplete footer payment icon** — only one of `src`/`alt` set (warning).
|
|
||||||
|
|
||||||
### Live inline feedback (facade)
|
|
||||||
|
|
||||||
`ProjectEditorFacade` exposes, on top of `validationIssues`: `blockingIssues` / `hasBlockingIssues` (severity-filtered), `issuesByField: Map<string, ProjectValidationIssue[]>`, `issuesBySection: Map<ProjectEditorSectionId, number>`, and `fieldError(key)` (first message for a field, or `null`). `publish()` gates on `hasBlockingIssues()`, not "any issue" — a duplicate-route or invalid-CSS warning no longer blocks publishing. Sections bind `[error]` on `app-form-field` (or a standalone `<p class="editor-error">` where the target isn't a single form-field, e.g. a whole list) for every field that has a matching `ProjectValidator` `fieldKey` today: theme palette, general name/domain/default-locale, branding logo, languages (`localization.supportedLocales`), homepage/widgets (`pages`), navigation (`navigation.header`), static-pages (`staticPages`), and footer (contact email, social links, payment icons). Header/features have no matching validator checks (every field there is a bool/enum, always valid by construction), so nothing is wired there — not an oversight. `project-editor-nav` shows a red badge with the blocking-issue count per section.
|
|
||||||
|
|
||||||
### Undo / redo (`schema/history.util.ts` + facade)
|
|
||||||
|
|
||||||
A pure, framework-free reducer (`emptyHistory`, `commit`, `undo`, `redo`) over immutable `BootstrapConfig` snapshots, capped at 50 entries. The facade wraps it with **debounced commits** (~300ms): `updateBootstrap()` captures the pre-burst snapshot on the first call in a burst and only pushes it to history once edits settle, so a run of rapid typing collapses into one undo step instead of one per keystroke. `undo()`/`redo()` route through the same draft-save path as every other mutation, so the `localStorage` autosave never desyncs from the in-memory undo stack. History is cleared on `loadBootstrap()`, `publish()`, and `resetDraft()` (a fresh baseline invalidates old snapshots). UI: save-bar Undo/Redo buttons (`canUndo`/`canRedo`), `Ctrl/Cmd+Z` / `Ctrl/Cmd+Shift+Z` / `Ctrl/Cmd+Y` page-level shortcuts (skipped while a text field has focus, so native per-field text undo still works).
|
|
||||||
|
|
||||||
### Modified-field tracking
|
|
||||||
|
|
||||||
`modifiedFields` (facade, `computed<Set<string>>`) diffs every schema field's current value against `originalBootstrap`. `modifiedSections` rolls that up per section for an amber dot in the nav (shown only when a section has no blocking-issue badge). `changeSummary` builds the before/after rows (schema label + stringified value, truncated for objects) consumed by the Preview section below.
|
|
||||||
|
|
||||||
### Pre-publish preview
|
|
||||||
|
|
||||||
The Preview tab (`preview-section`) now opens with a "changes since last publish" card: the full validation issue list (warning/error styled) plus a before/after table from `changeSummary`, ahead of the existing export/import/live-preview card. Reuses the existing `ProjectEditorPreviewService.preview()` — no new preview mechanism, just more visibility before triggering it.
|
|
||||||
|
|
||||||
### What stayed the same
|
|
||||||
|
|
||||||
No changes to `ProjectEditorIoService` (export/import), `ProjectEditorDraftStorageService` (draft `localStorage` format), or the publish/draft/reset flow described above — draft/publish/import/export compatibility is fully preserved. Section templates are unchanged except for `[error]` bindings on already-existing `app-form-field` usages.
|
|
||||||
|
|
||||||
## Admin Authentication (QR reuse)
|
|
||||||
|
|
||||||
Admin login shares the exact same Telegram QR/session backend and `TelegramLoginComponent` as customer login (`mode: 'admin'` vs `'customer'`) — only the cookie name/`SameSite` policy, token storage keys, and guard differ. **Backend gap:** because both flows hit the same session endpoint, the backend cannot distinguish an admin scan from a customer scan today — real admin authorization must be enforced server-side. Full detail: `docs/BACKEND.md` §4 Authentication and §5 Security (permission matrix).
|
|
||||||
|
|
||||||
## Design system primitives (post-Sprint 30 redesign)
|
|
||||||
|
|
||||||
All 11 section components (`sections/*.component.html`) share these 6 `shared/ui/*` primitives instead of copy-pasted markup. They mirror the existing `InputComponent` CVA idiom (standalone, `OnPush`, `NG_VALUE_ACCESSOR` where they're form controls):
|
|
||||||
|
|
||||||
| Primitive | Selector | Replaces | Used in |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `ToggleComponent` | `app-toggle` | raw `<input type="checkbox">` + `$any($event.target).checked` | header, homepage, widgets, navigation, features |
|
|
||||||
| `SelectComponent` | `app-select` | raw `<select>` | theme (`theme.mode`, `layout.type`) |
|
|
||||||
| `ColorPickerComponent` | `app-color-picker` | raw `<input type="color">` | theme (8 palette colors) |
|
|
||||||
| `SectionCardComponent` | `app-section-card` | the copy-pasted `editor-section-card`/`<h2>` shell | all 11 sections |
|
|
||||||
| `LocaleTabsComponent` | `app-locale-tabs` | (new capability) | languages, navigation |
|
|
||||||
| `KeyValueEditorComponent<T>` | `app-key-value-editor` | pipe-delimited `<textarea>` lists | footer (payment icons, social links) |
|
|
||||||
| `ImageFieldComponent` | `app-image-field` | manual URL `<input>` + separate "choose image" button, no preview | branding (logo/small-logo/favicon/social/gallery), footer (logo, payment icons) — thumbnail preview + Replace/Remove, opens its own `app-media-picker` |
|
|
||||||
| `CodeEditorComponent` | `app-code-editor` | plain `<textarea>` for raw-HTML mode | `MarketplaceHtmlEditorComponent`'s "Код" toggle — overlay-textarea syntax highlighting (no Monaco/CodeMirror dependency); tokenizes HTML tags/comments and delegates `<style>` block contents to a CSS tokenizer (selector/property/value/string/comment-aware) |
|
|
||||||
|
|
||||||
`section.shared.scss`'s `.editor-grid.*` classes are unchanged and still used inside `SectionCard` bodies; only the outer `.editor-section-card` shell and per-section `<h2>` were replaced (that rule has been removed from the shared stylesheet since it has no remaining consumers).
|
|
||||||
|
|
||||||
## Interaction / motion pass (2026-07-16)
|
|
||||||
|
|
||||||
Interaction feedback + motion applied consistently, all gated behind `prefers-reduced-motion`:
|
|
||||||
|
|
||||||
- `section.shared.scss` `button`/`button.secondary` gained hover/active/`focus-visible`/`disabled` states (previously flat, no feedback across all 11 sections).
|
|
||||||
- `project-editor-page.component.scss`: the active section fades/slides in (220ms) when the `@switch` swaps components; the "reset section" button got matching hover/focus states.
|
|
||||||
- `project-editor-save-bar` buttons now use the shared `app-button` primitive (danger / secondary / primary variants) instead of unstyled native `<button>`s.
|
|
||||||
|
|
||||||
## HTML editor (Static Pages)
|
|
||||||
|
|
||||||
`MarketplaceHtmlEditorComponent` (`components/html-editor/marketplace-html-editor.component.ts`) is a `contenteditable` WYSIWYG used inside the Static Pages editor (`features/content-management/.../static-pages-editor.component.html`), one instance per locale, bound `[html]` / `(htmlChange)`.
|
|
||||||
|
|
||||||
**Status: working.** Verified live 2026-07-16 — typing captured, toolbar commands functional (bold toggles, `insertUnorderedList` wraps `<ul><li>`, H2/H3/link/image/table), `htmlChange` emits on every edit, and a "Код" toggle swaps to raw-HTML editing.
|
|
||||||
|
|
||||||
**Toolbar (Sprint X+2 additions):** horizontal rule, code block (`<pre>`), embed (prompt for a URL, inserts a sandboxed `<iframe sandbox="allow-scripts allow-same-origin">`) — alongside the original bold/italic/underline/H2/H3/lists/link/image/table set.
|
|
||||||
|
|
||||||
**HTML-mode validation (Sprint X+2):** switching from raw-HTML back to the visual surface now runs `schema/validators/primitives.validateHtml` (stack-based tag-balance check) first; a malformed edit (unclosed/mismatched tag) stays in code mode with an inline error instead of silently corrupting the visual editor.
|
|
||||||
|
|
||||||
**Caveat:** implemented on the deprecated `document.execCommand` API. It works in all current browsers today but is a legacy web API with no modern drop-in replacement; if a future browser drops it, this component needs a rewrite (e.g. a maintained rich-text library). By design it emits **raw, unsanitized** HTML — sanitization is a storefront-render concern, not an authoring one (see `docs/BACKEND.md` §3 CRUD Contracts, CMS, on server-side content moderation on publish; `StaticPageComponent` and `StaticPagePreviewComponent` both run content through `DomSanitizer` before render).
|
|
||||||
|
|
||||||
## Field-description / dropdown UX (Sprint 19+)
|
|
||||||
|
|
||||||
Every field across the 10 editor section templates now carries a one-line, i18n'd description under its label explaining what it does in plain language (all new copy routed through `TranslateService`/`TranslatePipe`, added to `Translations` + `en.ts`/`ru.ts`/`hy.ts` following the existing `builder.*` key pattern — see `src/app/i18n/translations.ts`).
|
|
||||||
|
|
||||||
**Converted from free-text `<input>` to `<select>`** (backed by a closed TypeScript union), each option carrying a human label and a short description (via `title` attribute) instead of the raw enum value:
|
|
||||||
|
|
||||||
- `section.layout.strategy` (Homepage section) — `SectionLayoutStrategy`: `stack | grid | hero | carousel | split`.
|
|
||||||
- `theme.mode` (Theme section) — `light | dark | system`.
|
|
||||||
- `layout.type` (Theme section, "Site Layout") — `PlatformLayoutType`: `default | sidebar-left | carousel-home | minimal`.
|
|
||||||
- `catalog.navigationMode` (Marketplace Features section) — `CatalogNavigationModeConfig`: `default | left-category-navigation | mega-category-layout | top-category-carousel`.
|
|
||||||
|
|
||||||
Each of these components defines a local `readonly` options array of `{ value, labelKey, descriptionKey }` (per ADR-006, these are section/container components so this is allowed without a new shared UI library).
|
|
||||||
|
|
||||||
**Still plain text/checkbox, with a description added, and why:** marketplace name, domain, description, logo/favicon/small-logo URLs, palette colors (already `<input type="color">`, which is the correct native widget), company/address/phone/email, copyright, payment icons/social links (JSON-ish textarea), homepage section `columns` (a number, not an enum), widget-specific props (`hero`/`categories`/`product-collection` typed fields like layout/height/overlay/autoplay/cardsPerRow — these are widget `props` strings/booleans, not modeled as TypeScript unions anywhere, so they stay free text/checkbox with a description rather than a fabricated enum), navigation link label/URL, and the widget JSON fallback textarea for any widget type without a dedicated editor. These are genuinely open-ended or already have the correct native input type; converting them to `<select>` would either be wrong (URLs/colors/free text) or invent an enum that doesn't exist in the schema.
|
|
||||||
|
|
||||||
## Bug-hunt audit pass (2026-07-17)
|
|
||||||
|
|
||||||
A section-by-section correctness audit (not a feature pass) — for each section, checked whether its controls actually do what they claim at runtime, not just whether they render. 9 real, verified defects found and fixed (each confirmed live via `window.ng.getComponent()` reproducing the exact bug, then re-verified fixed):
|
|
||||||
|
|
||||||
- **Footer**: `createSocialLinkRow`'s id was derived from array length (`social-${length+1}`) — add/remove/add reliably collides with a surviving row's id, corrupting `footer.component.html`'s `@for (... track item.id)` DOM identity on the public storefront. Payment-icon `@for` tracked by `icon.src`, which collides whenever two rows share a src (most commonly two blank ones). Both switched to safe keys.
|
|
||||||
- **Features**: wishlist/compare visibility is gated by *two* flags at runtime (`featureFlags.<key>` AND `userExperience.<key>.enabled` — see `feature-config.service.ts`), but the editor only exposed a toggle for the first. Both default `true` so it was silent, but a config with the second explicitly `false` left the toggle looking "on" with no way to fix it from this screen. Now one toggle drives both.
|
|
||||||
- **Widgets**: the JSON-fallback textarea's `updateJson()` caught parse errors and did nothing, but the textarea was bound to `propsJson(committed props)` — so an in-progress invalid edit got silently overwritten on the next change-detection pass. Now keeps the user's draft on screen with an inline error until it's valid.
|
|
||||||
- **Languages**: `addLocale()` cleared the input regardless of whether `LocaleSyncService` actually accepted the code — adding an already-supported locale silently no-opped. Now shows an inline error and leaves the input untouched.
|
|
||||||
- **Preview**: `importBootstrap()` replaced `state.bootstrap` directly instead of routing through `updateBootstrap()` — so an import never got a `draftStorage.save()` (lost on refresh before an explicit Save) and was never an undo-able history step. Now routed through the same pipeline as every other edit.
|
|
||||||
- **Static Pages**: `createPage()`'s slug (`custom-page-${length+1}`) and `duplicatePage()`'s slug/route (fixed `-copy` suffix) both reproducibly collide the same way as the footer bug above (create/delete/create; duplicate the same page twice). Added a shared `uniqueValue()` helper (appends `-2`, `-3`, ... until free).
|
|
||||||
- **General**: "Supported Languages" is a free-text comma list that bypassed `LocaleSyncService` entirely, so adding a locale here never seeded the empty translation entries Languages' add-button produces — the two UI paths silently diverged. Now diffs and routes through `facade.addLocale()`/`removeLocale()`. Also added the "default locale not itself supported" validator check described above, since this field had (and still has, by design — it's free text) no format guard.
|
|
||||||
- **Branding → SEO**: `branding.socialImageUrl` (added earlier this same pass) wasn't actually read by `SeoService.resetToDefaults()` — the OG/Twitter image fallback stayed on `appIconUrl || logoUrl`. Fixed to check it first.
|
|
||||||
- **Media picker**: `MediaLibraryFacade` is a root-provided singleton shared by *every* `app-media-picker` instance on a page (branding alone renders 4). `ngOnInit` loaded unconditionally on mount regardless of dialog state, and `search`/`folder`/`page` filters leaked between independently-opened picker dialogs. Replaced with an `effect()` that resets those filters and loads only when that instance's own `open` input actually becomes `true`.
|
|
||||||
|
|
||||||
### Known gaps found but not fixed (real, out of scope for this pass)
|
|
||||||
|
|
||||||
- **Theme Mode has no runtime effect.** `theme-section`'s light/dark/system selector correctly saves and sets a `data-theme-mode` attribute (`theme-engine.service.ts`), but zero CSS anywhere in the app reads that attribute — picking Dark or System currently changes nothing visually. (Theme palette colors *are* live — real CSS custom properties consumed throughout the stylesheets — only the mode switch is dead.) Fixing this is a real dark-mode implementation project (dark palette + CSS strategy + `matchMedia` for "system"), not a wiring fix. Tracked: `docs/PRODUCT_BACKLOG.md`.
|
|
||||||
- ~~`HeaderConfig.showProfile` has no corresponding profile/account menu~~ — **fixed**: `header.component.html`/`.ts` now render a login/logout-only control (no dropdown, no account links) gated by this toggle, reusing the customer Telegram `AuthService`. See `docs/KNOWN-ISSUES.md` "Fixed (this cycle)" and `docs/GLOBAL-SPRINT-PLAN.md` Sprint A.
|
|
||||||
- ~~`layout.type`/homepage `type` field feed an unwired `dynamic-renderer/`~~ — **stale, corrected**: `dynamic-renderer/` (`PageRendererService`/`SectionRendererService`/`WidgetHostService`) is the live homepage rendering pipeline, wired through `dynamic-page-layout.component.ts`. Verified fixed/non-issue in `docs/KNOWN-ISSUES.md` "Fixed (this cycle)".
|
|
||||||
@@ -1,54 +0,0 @@
|
|||||||
# FRONTEND
|
|
||||||
|
|
||||||
Angular 18+, standalone components throughout (no NgModules). See `docs/PROJECT-STRUCTURE.md` for the full `src/app/**` folder tour and `docs/ARCHITECTURE.md` for the layered container/facade/service pattern.
|
|
||||||
|
|
||||||
## App structure at a glance
|
|
||||||
|
|
||||||
```
|
|
||||||
src/app/
|
|
||||||
core/ domain services, DTOs, mappers, repositories (per domain: categories, products, search, admin-auth)
|
|
||||||
facades/ cross-feature facades (platform/category.facade.ts, platform/search.facade.ts, ...)
|
|
||||||
features/ feature modules (project-editor, admin/*, backoffice/*, website/catalog, website/product, diagnostics, content-management, search)
|
|
||||||
shared/ models/config (BootstrapConfig + ~20 sub-configs), shared UI, utils — feature-agnostic
|
|
||||||
widgets/ widget contracts, registry/manifest, resolvers, ui components
|
|
||||||
dynamic-renderer/ section-engine, page-renderer, section-renderer, widget-host
|
|
||||||
layouts/ page-chrome containers (dynamic-page-layout, header/footer shells)
|
|
||||||
i18n/ translations.ts (interface), en.ts, ru.ts, hy.ts, translate.pipe.ts, TranslateService
|
|
||||||
pages/ top-level routed pages (home, cart, category, ...)
|
|
||||||
components/ reusable standalone components used across features (product-card, telegram-login, ...)
|
|
||||||
guards/ route guards (admin-auth guard, etc.)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Routing (`app.routes.ts`)
|
|
||||||
|
|
||||||
- Locale-prefixed routes: `/:lang/...` (lang from `LanguageService.currentLanguage()`), plus root redirects.
|
|
||||||
- Storefront: `/`, `/catalog`, `/catalog/:id`, `/product/:id` (legacy `/item/:id` and `/category/:id[/items]` redirect for compatibility).
|
|
||||||
- Static/CMS pages resolve dynamically: `/:lang/:staticPath` (legacy `/:lang/page/:key` kept for compatibility) — no hardcoded page list, resolved from `bootstrap.staticPages`.
|
|
||||||
- Project Editor: `/edit/:section` or `/{lang}/edit/:section`.
|
|
||||||
- Admin/backoffice: `/:lang/backoffice/**`, guarded by `adminAuthGuard` (`core/admin-auth/admin-auth.guard.ts`) — dashboard, products, categories, orders, transactions, users, moderation, media, monitoring, analytics. See `docs/BACKEND.md` for the data-source contract for each.
|
|
||||||
- Dev-only diagnostics: `/__diagnostics` (excluded from production).
|
|
||||||
|
|
||||||
## i18n system
|
|
||||||
|
|
||||||
- `src/app/i18n/translations.ts` defines the `Translations` interface — the single schema every locale file must satisfy (TypeScript enforces this at compile time: a missing key in any locale is a build error).
|
|
||||||
- `en.ts`, `ru.ts`, `hy.ts` implement that interface, keyed identically and nested by feature area (`header`, `footer`, `home`, `builder`, `dashboard`, ...).
|
|
||||||
- `TranslateService` resolves the active locale and exposes translated strings; `TranslatePipe` (`| translate`) is the template-facing API — **never hardcode user-facing strings in templates**, always add a key to all three locale files.
|
|
||||||
- 3 locales: `en`, `ru`, `hy` (Armenian). `LanguageService` tracks the active locale and drives the `/:lang/` route prefix.
|
|
||||||
- Adding a new UI string: add the key to the `Translations` interface first, then to `en.ts`/`ru.ts`/`hy.ts` in the same position (see `docs/EDITOR.md` for the pattern used by the field-description work).
|
|
||||||
|
|
||||||
## Theming
|
|
||||||
|
|
||||||
- 3 tenant theme stylesheets: `src/styles/themes/*.theme.scss`.
|
|
||||||
- Convention: each theme file defines CSS custom properties (`--color-primary`, `--text-primary`, `--border-color`, etc.) that mirror `ThemeConfig.palette`/`typography`/`shadows`/`borderRadiusScale`; components and widgets consume only these custom properties, never hardcoded hex values (ADR-008).
|
|
||||||
- `theme.mode` (`light | dark | system`) and the palette are runtime-configurable per tenant via bootstrap and editable via the Project Editor's Theme section (`docs/EDITOR.md`).
|
|
||||||
|
|
||||||
## State management
|
|
||||||
|
|
||||||
- **Signals-based facades, no NgRx.** Every feature/domain exposes a facade (`ProjectEditorFacade`, `CategoryFacade`, `ProductFacade`, `SearchFacade`, `AdminDashboardFacade`, ...) built on Angular signals (`signal`, `computed`, `effect`), following ADR-007.
|
|
||||||
- Components inject exactly one facade and read/write through it; no direct service or HTTP access from components (ADR-006).
|
|
||||||
- Local component state (e.g. draft form values) stays in the component; cross-cutting/shared state lives in the facade.
|
|
||||||
- Persistence for local-only features (Project Editor drafts, admin dashboard activity history) uses scoped `localStorage` keys behind a dedicated service (`ProjectEditorDraftStorageService`, `AdminDashboardHistoryService`) — never raw `localStorage` calls from components/facades.
|
|
||||||
|
|
||||||
## Dynamic widget/section rendering from bootstrap JSON
|
|
||||||
|
|
||||||
Full detail in `docs/ARCHITECTURE.md` and `docs/BACKEND.md#1-bootstrap`. Summary: `page config (bootstrap.pages) -> Section Engine (order/layout/visibility) -> Page Renderer -> Widget Host (resolves component via Widget Manifest + data via Data Source Resolver) -> widget component (props + resolved data only)`. Nothing in this pipeline calls an API directly except the Data Source Resolver, which delegates to `CategoryFacade`/`ProductFacade`.
|
|
||||||
@@ -1,27 +0,0 @@
|
|||||||
# Future Features
|
|
||||||
|
|
||||||
Nice-to-have, non-blocking work — no client decision needed, just not worth doing now. Verified against current repo state 2026-07-26.
|
|
||||||
|
|
||||||
## Cart payment modal → `app-dialog` migration
|
|
||||||
|
|
||||||
**Done, 2026-08-06.** `.payment-modal`/`.bank-payment-modal` on the cart page now render through the shared `app-dialog` primitive instead of hand-rolled overlays. Two earlier same-session attempts were reverted before landing (one stopped cleanly after finding real conflicts, one botched the sequencing — deleted the old focus-trap before finishing the swap); this pass fixed the actual API gaps first, then migrated, then verified live in a browser before shipping:
|
|
||||||
|
|
||||||
- `DialogComponent` gained `closeOnEscape`/`closeOnBackdropClick` inputs (default `true`, backward-compatible with its other 13 call sites) and an `ariaLabel` input (for dialogs with no visible title header — cart's modals render their own close button in content instead). `FOCUSABLE_SELECTOR` now includes `iframe` (needed for the bank-payment panel's focus trap).
|
|
||||||
- Cart wires `[closeOnBackdropClick]="false"` on both dialogs (in-flight payment shouldn't cancel on a stray click) and `[closeOnEscape]="!showBankPaymentPopup()"` on the QR/status dialog (so Escape closes the bank iframe first, falls back to the QR view, matches the original nested-modal priority).
|
|
||||||
- Exact original geometry (500px QR modal, 40px padding; 960×760 bank iframe modal, 56/16/16 padding, both mobile breakpoints) preserved via `:host ::ng-deep` overrides on `.app-dialog-panel`/`.app-dialog-panel__body`/`.app-dialog-backdrop`, scoped per-instance via `.payment-dialog`/`.bank-payment-dialog` host classes — same `::ng-deep` pattern already used by `product-carousel-widget.component.ts`.
|
|
||||||
- `cart.component.ts` lost its hand-rolled `@ViewChild`/`@HostListener`/focus-trap methods (~90 lines) — `app-dialog` owns all of that now.
|
|
||||||
- Verified live: both dialogs render at correct size/padding/aria-label at mobile and desktop breakpoints, backdrop-click confirmed inert, Escape-priority confirmed (closes bank first, then QR), initial focus confirmed landing on the close button. 83/83 tests pass, tsc/build clean.
|
|
||||||
|
|
||||||
## Angular 22 upgrade
|
|
||||||
|
|
||||||
Researched, not executed. Estimated ~2–3.5 days, needs the `barry-cache` dependency fix and a Node version bump first. Explicitly out of scope for the Backend Finalization Sprint. Plan: `docs/ANGULAR22_PLAN.md`.
|
|
||||||
|
|
||||||
## Bundle splitting
|
|
||||||
|
|
||||||
**Initial (eagerly-loaded) bundle carries an ~11 MB chunk that is the entire `@lucide/angular` icon set**, confirmed 2026-08-05 by inspecting build output — `app-icon`/`IconComponent` only ever needs the ~85 icons named in `icon-registry.ts`, but esbuild is not eliminating the other ~1500+ unused icon classes from `@lucide/angular`'s single-file `fesm2022/lucide-angular.mjs` bundle, despite the package declaring `sideEffects: false` and every usage in this codebase being clean named imports (no wildcard imports found). Root cause not fully diagnosed — likely each icon's Angular component metadata assignment isn't PURE-annotated in that build, so esbuild can't drop unreferenced classes within the single shared module even though it can drop unreferenced *exports*. The package ships no per-icon deep-import path as a workaround (single fesm file only). Real fix options, neither attempted here (touches a dependency, needs sign-off): (a) check for a newer `@lucide/angular` release with better tree-shaking, (b) drop the dependency and hand-roll inline SVG path data for just the ~85 used icons (removes a dependency, matches this repo's minimal-deps convention, but is real work — extracting/verifying 85 icon paths). This alone is roughly **6x the size of the two lazy chunks below combined** and, unlike them, ships to every visitor on first load.
|
|
||||||
|
|
||||||
Two lazy chunks are also large: `project-editor` (~1.0 MB), `catalog-container` (~330–375 kB, varies by build). No mechanical split found yet for either — needs a dedicated profiling task, ideally under real backend latency per `docs/NEXT_PHASE.md` Phase 3.
|
|
||||||
|
|
||||||
## Homepage hero-to-categories spacing investigation
|
|
||||||
|
|
||||||
A dead-space gap between the hero and categories section on the storefront home page traces to bootstrap mock config (widget/section padding values in the dev fixture), not a confirmed code defect. Needs reproduction with real tenant data before it's worth investigating further — not a bug until it's confirmed to happen outside the mock fixture.
|
|
||||||
@@ -1,76 +0,0 @@
|
|||||||
# Global Sprint Plan — "Coming Soon" Stub Closure
|
|
||||||
|
|
||||||
Supersedes `docs/COMING-SOON-AUDIT.md` §5 sprint breakdown. One consolidated tracker for the four stub-closure sprints. Approved decisions (from AskUserQuestion): Reports/Settings ship as minimal real pages (not fake data, not empty shells); Documentation/Help nav uses an external-link approach; `docs/COMING-SOON-AUDIT.md` is deleted once all sprints land, folded into `docs/KNOWN-ISSUES.md`. Profile control constraint: **login/logout only — no dropdown, no account links.**
|
|
||||||
|
|
||||||
## Sprint A — Profile menu (storefront header)
|
|
||||||
|
|
||||||
- [x] i18n: `header.login` / `header.logout` keys in en/ru/hy (`translations.ts` type already updated)
|
|
||||||
- [x] `header.component.ts`: inject `AuthService`, expose `isAuthenticated`, add `login()`/`logout()`
|
|
||||||
- [x] `header.component.ts`: import `TelegramLoginComponent`
|
|
||||||
- [x] `header.component.html`: profile control gated by `headerConfig().showProfile`, login/logout only, `<app-telegram-login />` rendered once
|
|
||||||
- [x] SCSS matches existing header button conventions (reused `.platform-ux-btn`, no new SCSS needed)
|
|
||||||
|
|
||||||
**What shipped:** Header profile control wired to the customer `AuthService` (Telegram QR login). Gated by `headerConfig().showProfile` (already a real toggle in Project Editor, previously dead). Logged-out shows a login button (`user` icon), logged-in shows a logout button (`logOut` icon) — no dropdown, no account links, per the explicit constraint.
|
|
||||||
|
|
||||||
## Sprint B — Admin Reports page
|
|
||||||
|
|
||||||
- [x] `admin-reports-page.component.ts/.html/.scss` (mirrors `admin-analytics-page` structure), reuses `AdminAnalyticsFacade`
|
|
||||||
- [x] Report cards: Sales, Top Products, Marketplace Health
|
|
||||||
- [x] CSV export wired to existing facade export methods / existing download helper (same Blob pattern as `admin-analytics-page.component.ts`)
|
|
||||||
- [x] Route `backoffice/reports` in `app.routes.ts`, i18n keys `adminShell.pages.reports.*` + new `adminReports.*` block
|
|
||||||
- [x] Remove `comingSoon: true` from `reports` nav entry
|
|
||||||
|
|
||||||
**What shipped:** Minimal real Reports page with 3 cards (Sales, Top Products, Marketplace Health), each showing a live summary from `AdminAnalyticsFacade` and a CSV export button. Orders card was scoped out — see final report for why (reuse would require mutating a shared singleton facade's pagination state).
|
|
||||||
|
|
||||||
## Sprint C — Admin Settings page
|
|
||||||
|
|
||||||
- [x] `AdminPreferencesService` (density signal, localStorage-backed, key `adminPreferences.density.v1`)
|
|
||||||
- [x] `admin-layout.component` applies `admin-density-compact` class to `#admin-content` shell wrapper
|
|
||||||
- [x] `admin-settings-page.component.ts/.html/.scss` — density toggle (`app-toggle`), auto-persists on change, no separate Save button
|
|
||||||
- [x] Route `backoffice/settings`, i18n keys `adminShell.pages.settings.*` + `adminSettings.*` block
|
|
||||||
- [x] Remove `comingSoon: true` from nav entry AND dashboard shortcut; shortcut route → `['backoffice','settings']`
|
|
||||||
- [x] Compact-density CSS rule added to the shared `app-table` component stylesheet (`.admin-density-compact .app-table th/td`) — applies to every admin list page built on `app-table` (orders, products, categories, etc.), not just one
|
|
||||||
|
|
||||||
**What shipped:** Genuinely real, backend-independent UI density preference. No maintenance-mode toggle built (explicitly deferred per `docs/NEXT_PHASE.md` Phase 4).
|
|
||||||
|
|
||||||
## Sprint D — Documentation / Help nav
|
|
||||||
|
|
||||||
- [x] Help: `mailto:` using existing `supportEmail` read path (`UiRuntimeFacade.contactEmail()`, same one `header.component.ts` already uses for `bootstrap.branding.supportEmail`)
|
|
||||||
- [x] `AdminNavLink` gains optional `externalHref?: string`; nav renderer renders `<a>` branch (bottom nav)
|
|
||||||
- [x] Documentation: added `tenant.documentationUrl?: string` to `TenantConfig`, populated mock with `https://docs.marketplace.local`
|
|
||||||
- [x] `help`/`documentation` resolved dynamically in `admin-layout.component.ts` (`navBottom` computed) — real `<a>` when bootstrap data present, static `comingSoon: true` entries kept as defensive fallback for the (currently unreachable, since mock always has both fields) case where the backend omits them
|
|
||||||
|
|
||||||
**What shipped:** Both Help and Documentation wired to real external links, not just Help. `comingSoon: true` remains in `admin-nav.model.ts` source as a fallback flag only — it is overridden to `false` at render time whenever bootstrap actually has the data, which it does today.
|
|
||||||
|
|
||||||
## Sprint E — Widget layout config correctness (manifest-aware editor)
|
|
||||||
|
|
||||||
Root cause confirmed 2026-08-05: `widget-manifest.json` already declares `supportedLayouts` per widget type (`hero`→`[hero, split]`, `categories`→`[grid]`, `product-collection`→`[carousel, grid]`), but `homepage-section.component.ts`'s `layoutStrategyPickerOptions` is a static 5-option list (`stack/grid/hero/carousel/split`) shown identically for every homepage section regardless of which widget backs it — it never reads the manifest. The `columns` field (`homepage-section.component.html:49`) is shown for every section too, but **no widget component reads `layout.columns`** — it is currently dead everywhere.
|
|
||||||
|
|
||||||
- [x] `homepage-section.component.ts`: resolve each section's widget type (via its bound widget id → `widget-registry`/manifest lookup) and filter `layoutStrategyPickerOptions` down to that widget's `supportedLayouts` before rendering the picker
|
|
||||||
- [x] Hide/disable the `columns` field for any section whose resolved widget doesn't consume it (only `product-collection` and, after Sprint F, `hero` will)
|
|
||||||
- [x] No behavior change for widgets that already worked (categories/recently-viewed/footer-nav keep their single valid layout, picker just stops offering the other 4 nonsensically)
|
|
||||||
|
|
||||||
**What shipped:** `homepage-section.component.ts` now injects `WidgetManifestService`, resolves each section's manifest entry directly by `section.type` (confirmed identical to the manifest `type` key — no separate widget-id lookup needed), and derives `layoutOptionsFor(section)` by filtering the static option list down to that entry's `supportedLayouts`. A stale/unsupported saved `strategy` value is appended back into the options list rather than dropped, so `app-visual-layout-picker` never renders with no active card. `showColumnsFor(section)` gates the `columns` field to the two componentKeys that actually read it (`hero` always, `product-collection` only in `carousel` strategy — grid mode ignores it). One correction to the plan's assumption: `recently-viewed`'s actual manifest entry declares `supportedLayouts: ["stack", "grid", "carousel"]` (3 options, not 1) — the picker now correctly reflects that per the manifest rather than the plan's guess.
|
|
||||||
|
|
||||||
## Sprint F — Carousel items-per-page (closes the client bug report)
|
|
||||||
|
|
||||||
Confirmed real, reported by a client, not fixed anywhere: neither carousel widget has an "items/slides per page" concept. Design: reuse the existing (currently dead) `layout.columns` field rather than inventing a new one — it is already editable in the Homepage section editor once Sprint E gates it to the right widgets.
|
|
||||||
|
|
||||||
- [x] `ProductCarouselWidgetComponent`: read `section.layout.columns` (default 4, min 1) to size `.catalog-product-shell` width as a fraction of the scroller instead of the hardcoded `220px` — gives real "items per page" control, arrows/scroll logic unchanged (already works)
|
|
||||||
- [x] `HeroWidgetComponent`: add manual prev/next arrows (parity with the product carousel's arrow buttons) in addition to the existing dots — closes "not scrollable manually"
|
|
||||||
- [x] `HeroWidgetComponent`: add swipe/drag (pointer events) support for touch — closes "not scrollable manually" on mobile
|
|
||||||
- [x] `HeroWidgetComponent`: support `layout.columns` = 1 or 2 to show one or two slide panels at once ("big carousel one or two slides per page") — 2-panel mode shows the active slide plus the next one side by side
|
|
||||||
- [x] Verify autoplay (`props.autoplay`, already exists, editor toggle already exists per `widgets-section.component.html:61`) still functions correctly alongside the new manual controls (manual interaction should not fight the autoplay timer — reset/pause timer on manual nav, matching common carousel UX)
|
|
||||||
- [x] i18n: any new aria-labels for the new hero arrows (reuse `common.previousProducts`/`common.nextProducts` keys if wording fits, or add `common.previousSlide`/`common.nextSlide`)
|
|
||||||
|
|
||||||
**What shipped:** `ProductCarouselWidgetComponent` sets `--items-per-page` as a CSS custom property (`[style.--items-per-page]`) driven by `itemsPerPage()` (default 4, min 1, floored), and `.catalog-product-shell` width is now `calc((100% - (var(--items-per-page, 4) - 1) * var(--space-md, 16px)) / var(--items-per-page, 4))` instead of a fixed `220px`. `HeroWidgetComponent` gained prev/next arrow buttons (same circular/bordered visual language as the product carousel's arrows), touch-event swipe (same threshold-based approach as `cart.component.ts`'s `onSwipeStart`, 50px threshold, left swipe = next, right swipe = prev), and 2-panel support via `layout.columns` (defaults to 1; `columns === 2` shows the active slide plus the next one side by side, falling back to 1 panel when there's only one slide total). All manual navigation (arrows, swipe, dots) routes through the existing `goTo()`, which already clears+restarts the autoplay timer, so no duplicate timer logic was needed. New i18n keys `common.previousSlide` / `common.nextSlide` added to `translations.ts`, `en.ts`, `ru.ts`, `hy.ts`.
|
|
||||||
|
|
||||||
Verification: `npx tsc --noEmit` and `npx ng build --configuration=development` both clean. Visually verified in the browser preview (`ng serve` on port 4200) by temporarily patching the embedded home-page sections in `src/assets/mock/bootstrap/bootstrap.json` (the actual runtime source for `/` — `src/assets/mock/bootstrap/homepage.json` is a separate, unused-by-this-route file) to `columns: 2` + a second slide for hero and `columns: 3` for the product carousel, confirming via DOM/computed-style inspection: hero rendered 2 slide panels with 2 working arrows, arrow clicks and simulated touch swipe both advanced/reversed the active dot correctly, and the carousel's `--items-per-page` CSS var read `3` with each `.catalog-product-shell` measuring ~348px (vs. the fixed 1110px/220px before). All temporary mock-data edits were reverted afterward (`git checkout`) — `bootstrap.json` and `homepage.json` are unchanged in the final diff. The Sprint E manifest-aware picker itself could only be verified by code inspection, not live in the browser — `/edit/:section` requires Telegram admin login, which cannot be completed in this environment.
|
|
||||||
|
|
||||||
## Housekeeping
|
|
||||||
|
|
||||||
- [x] Delete `docs/COMING-SOON-AUDIT.md`
|
|
||||||
- [x] Fold summary into `docs/KNOWN-ISSUES.md` "Fixed (this cycle)"; remove the `HeaderConfig.showProfile` dead-toggle entry from "Open"
|
|
||||||
- [x] Update `docs/BACKEND.md` (`tenant.documentationUrl` field added §1.3; no `docs/backend/BACKEND-INTEGRATION.md` exists in this repo)
|
|
||||||
- [x] `npm run barry -- validate` (clean, only pre-existing unrelated warnings)
|
|
||||||
- [x] Typecheck touched files (`tsc --noEmit` + full `ng build` both clean)
|
|
||||||
@@ -1,57 +0,0 @@
|
|||||||
# Known Issues
|
|
||||||
|
|
||||||
Real, reproducible, currently-open frontend bugs only. Everything that needed a product/business decision moved to `docs/PRODUCT_BACKLOG.md`; everything nice-to-have moved to `docs/FUTURE_FEATURES.md`; everything backend-shaped moved to `docs/BACKEND.md`. Re-verified against source 2026-07-26.
|
|
||||||
|
|
||||||
## Open
|
|
||||||
|
|
||||||
1. **Ed25519 admin-auth error codes `session-expired` and `invalid-signature` are unreachable — dead UI.**
|
|
||||||
`AuthError.code` is documented as routing to a dedicated recovery screen per code
|
|
||||||
(`core/auth/models/auth-error.model.ts:1-4`), but `toAuthErrorShape()` in
|
|
||||||
`core/auth/services/auth.service.ts:110-118` derives the code for any real
|
|
||||||
`HttpErrorResponse` *exclusively* from `authErrorCodeFromStatus(error.status)`
|
|
||||||
(line 112) — it never reads the caller-supplied `fallbackCode` parameter for
|
|
||||||
real HTTP errors, and never reads any body-level error code from the response.
|
|
||||||
`authErrorCodeFromStatus()` (`auth-error.model.ts:21-32`) only ever returns
|
|
||||||
`'unauthorized'`, `'forbidden'`, or `'backend-unavailable'` — there is no status
|
|
||||||
or body condition anywhere in the codebase that produces `'session-expired'` or
|
|
||||||
`'invalid-signature'`. Both screens exist and are wired, but are permanently
|
|
||||||
unreachable from any real backend response today.
|
|
||||||
- **Fix requires both sides**: a backend that returns a distinguishable
|
|
||||||
`error.code` in the response body (see `docs/BACKEND.md` §6 Error Model), and a small
|
|
||||||
frontend change to `toAuthErrorShape()` to prefer that body code over the
|
|
||||||
blanket status-based fallback.
|
|
||||||
- Found: 2026-07-26, Backend Finalization Sprint documentation pass (traced while
|
|
||||||
writing `docs/BACKEND.md` §4 Authentication / §6 Error Model).
|
|
||||||
|
|
||||||
2. **`NavigationConfig.header` dead editable field — top nav links list has no renderer.**
|
|
||||||
The Navigation editor section lets a client edit a list of header nav items
|
|
||||||
(`navigation.header`), but `HeaderComponent` never reads `NavigationConfig.header`
|
|
||||||
anywhere — its category menu comes from `CategoryFacade` instead. Editing this
|
|
||||||
list currently has zero visible effect on the storefront.
|
|
||||||
- **Fix requires real feature work**, not a wiring change: rendering a
|
|
||||||
configurable top-nav means deciding positioning relative to the existing
|
|
||||||
category menu, active-route styling, and whether `children` (dropdowns) are
|
|
||||||
supported — out of scope for a mechanical fix.
|
|
||||||
- Found: 2026-08-05, Sprint G dead-config sweep (`docs/DEAD-CONFIG-AUDIT.md`).
|
|
||||||
|
|
||||||
## Fixed (this cycle)
|
|
||||||
|
|
||||||
Condensed — full detail in commit history and `docs/RELEASE_REPORT.md`.
|
|
||||||
|
|
||||||
- App-wide query-param routing broken (P0) — `language.guard.ts` legacy redirect percent-encoded query strings into the path.
|
|
||||||
- Backoffice Categories CRUD broken end-to-end (P0) — wrong provider-mode fallback always picked the real HTTP gateway with no backend present.
|
|
||||||
- Cart/builder native `confirm()`/`alert()` (16 call sites) replaced with shared `app-confirm-dialog` / toast service.
|
|
||||||
- `getMainImage()` no-photo fallback and footer payment-icon assets referenced files that didn't exist — both fixed, `onerror` fallback added everywhere.
|
|
||||||
- Backoffice Monitoring showed raw HTTP/queue/webhook strings by default — now friendly wording with technical detail collapsed behind a `<details>`.
|
|
||||||
- Category/subcategory empty states used apology wording ("Oops!") for a normal zero-results state.
|
|
||||||
- `pages/category`, `pages/search`, `pages/item-detail`, `pages/info/**`, `pages/legal/**` (40+ files) were unrouted dead code — deleted.
|
|
||||||
- `dynamic-renderer/` was believed unwired — verified it's the live homepage rendering pipeline, no action needed.
|
|
||||||
- `admin/products/:id/edit` missing `canDeactivate` guard — added, mirrors categories.
|
|
||||||
- `primeng`/`primeicons` unused dependency — removed.
|
|
||||||
- Builder static-page body editor hidden inside a mislabeled collapsed section — un-hidden, relabeled.
|
|
||||||
- Several project-editor/admin-categories correctness bugs (footer icon id collisions, features toggle only driving one flag, languages silent duplicate no-op, static-pages slug collision, branding `socialImageUrl` never read, media-picker facade filter leakage between dialogs, categories draft-recovery/drag-reorder bugs, hardcoded locale-tab order) — see git history for the full per-bug list.
|
|
||||||
- `HeaderConfig.showProfile` dead toggle — wired up (login/logout only, no dropdown), reuses the existing customer Telegram `AuthService`.
|
|
||||||
- Admin `reports` nav stub — real page (`backoffice/reports`), reuses `AdminAnalyticsFacade` for Sales/Top Products/Marketplace Health cards with CSV export.
|
|
||||||
- Admin `settings` nav stub — real page (`backoffice/settings`), UI density preference (comfortable/compact), persisted to `localStorage`, applied to admin list tables.
|
|
||||||
- Admin `documentation`/`help` nav stubs — both wired to real external links (`mailto:` support email, `tenant.documentationUrl`).
|
|
||||||
- Sprint G dead-config sweep: `footer.logoUrl`, `company.address.street`, `company.contacts.phone`, `catalog.suggestionsEnabled` were editable with no runtime consumer — all four wired up. Full findings table in `docs/DEAD-CONFIG-AUDIT.md`.
|
|
||||||
@@ -1,23 +0,0 @@
|
|||||||
# Next Phase — Roadmap
|
|
||||||
|
|
||||||
The one roadmap. Everything after this point assumes the previous phase is done — don't start Phase 2 work before Phase 1 lands.
|
|
||||||
|
|
||||||
## Phase 1 — Backend integration
|
|
||||||
|
|
||||||
Implement the backend per `BACKEND.md`, then swap every frontend mock gateway for a real one behind its DI token, in the dependency order `BACKEND.md` §8 specifies (auth/tenant/bootstrap first, then read-heavy catalog, then write-heavy customer domains, then admin, then builder/CMS). Wire the currently-dormant Ed25519 admin-auth interceptor/guard once the backend can issue/verify challenges. Enforce the admin role model in route guards once real roles exist server-side.
|
|
||||||
|
|
||||||
## Phase 2 — Production testing
|
|
||||||
|
|
||||||
Add the automated test suite that doesn't exist yet: facade-level integration tests against real endpoints (not mocks), and E2E coverage for the critical flows — storefront checkout, admin product/category CRUD, builder draft → publish → live storefront reflects the change, admin auth once Ed25519 is live.
|
|
||||||
|
|
||||||
## Phase 3 — Performance
|
|
||||||
|
|
||||||
Re-profile under real backend latency (mock responses are instant today, real ones won't be) — loading states, skeleton timing. Revisit the two known large lazy chunks (`project-editor`, `catalog-container`) with real data before committing to a bundle-splitting approach.
|
|
||||||
|
|
||||||
## Phase 4 — Monitoring
|
|
||||||
|
|
||||||
Wire real error tracking/APM and a real event source for the admin Monitoring page (currently mock activity data). Implement the maintenance-mode frontend UI gaps `BACKEND.md` §10 flags as not existing yet (full-page takeover, per-module banners, scheduled-maintenance countdown), once the backend maintenance contract is live.
|
|
||||||
|
|
||||||
## Phase 5 — Version 2 ideas
|
|
||||||
|
|
||||||
Everything in `docs/PRODUCT_BACKLOG.md` (dark mode, brand-color contrast decision, advanced analytics, additional payment providers, Contacts page content) and `docs/FUTURE_FEATURES.md` (Angular 22 upgrade, cart-modal composition cleanup) — none of it scheduled, all of it deliberately deferred past initial launch. The former stub-page/dead-toggle inventory (profile menu, admin Reports, admin Settings, Documentation/Help) is closed — see `docs/GLOBAL-SPRINT-PLAN.md` and `docs/KNOWN-ISSUES.md` "Fixed (this cycle)".
|
|
||||||
@@ -1,62 +0,0 @@
|
|||||||
# Product Backlog
|
|
||||||
|
|
||||||
Items that need a client/business decision before any code is written — not blockers, not bugs, not backend work. Verified against current repo state 2026-07-26.
|
|
||||||
|
|
||||||
## Dark mode / Theme selector
|
|
||||||
|
|
||||||
`theme-section`'s light/dark/system dropdown saves correctly and `theme-engine.service.ts` sets a `data-theme-mode` attribute on `<html>`, but no CSS anywhere in the app reads that attribute — picking Dark or System changes nothing visually today. Theme palette colors themselves are unaffected (real CSS custom properties, genuinely live).
|
|
||||||
|
|
||||||
**Decision needed:** does the client want a real dark mode? If yes, this is a real feature project (dark palette + `[data-theme-mode]`/`prefers-color-scheme` strategy + a `matchMedia` listener for "system"), not a wiring fix.
|
|
||||||
|
|
||||||
## Brand color contrast (WCAG AA)
|
|
||||||
|
|
||||||
`--border-color` fails 3:1 UI-component contrast in every theme (1.24–1.42:1 measured); `--success`/`--warning`/`--error`/`--info-color` fail 4.5:1 when used as plain text-on-white in a handful of places. These are real palette colors, not a token bug — fixing means visibly changing the brand.
|
|
||||||
|
|
||||||
**Decision needed:** theme-owner sign-off on adjusted brand colors before any change ships.
|
|
||||||
|
|
||||||
## Design-token gap: `stars.component` rating glyph color
|
|
||||||
|
|
||||||
`src/app/features/website/product/engagement/components/stars/stars.component.scss:10` uses a literal hex (`#cdd6d5`) with no matching design token.
|
|
||||||
|
|
||||||
**Decision needed:** add a token for this exact shade, or intentionally reuse an existing token (visual shift either way) — needs a design-system owner's call, not an engineering guess.
|
|
||||||
|
|
||||||
## `layout.type` ("Site Layout" selector) — dead editable field
|
|
||||||
|
|
||||||
The Theme section's "Site Layout" dropdown edits top-level `BootstrapConfig.layout.type`,
|
|
||||||
but page rendering (`SectionEngineService.resolveLayoutType`) only ever reads each
|
|
||||||
individual `PageConfig.layout`, never the top-level `bootstrap.layout` — so the
|
|
||||||
selector has no visible effect regardless of what's chosen.
|
|
||||||
|
|
||||||
**Decision needed:** which page(s) should this selector actually drive — only the
|
|
||||||
homepage, or every page that doesn't set its own `layout`? That decision determines
|
|
||||||
the wiring, not an engineering guess. Found: Sprint G dead-config sweep, `docs/DEAD-CONFIG-AUDIT.md`.
|
|
||||||
|
|
||||||
## `company.companyName` — dead editable field, needs a copyright-fallback decision
|
|
||||||
|
|
||||||
The Footer section's "Company Name" field has no runtime consumer. The footer
|
|
||||||
already has a copyright fallback (`© {year} {brandName}`) using `branding.brandName`
|
|
||||||
when `footer.copyrightText` is empty — reusing `company.companyName` there instead
|
|
||||||
(or in addition) is a content/legal-wording decision (brand name vs. legal entity
|
|
||||||
name are intentionally different fields), not a safe mechanical fix.
|
|
||||||
|
|
||||||
**Decision needed:** should the copyright fallback use the legal company name
|
|
||||||
instead of (or alongside) the brand name? Found: Sprint G dead-config sweep,
|
|
||||||
`docs/DEAD-CONFIG-AUDIT.md`.
|
|
||||||
|
|
||||||
## Footer "Contacts" page content
|
|
||||||
|
|
||||||
The footer's "Contacts" link (`footer-contacts` / `nav.contacts`) has no static-page content in the bootstrap mock data at all — unlike "About" (which was a route-name mismatch, already fixed), there's simply nothing written for Contacts.
|
|
||||||
|
|
||||||
**Decision needed:** what should the Contacts page actually say (address, phone, hours, map?) — a content question, not a code fix.
|
|
||||||
|
|
||||||
## Advanced analytics (traffic, funnels, heatmaps)
|
|
||||||
|
|
||||||
No data source exists for site traffic, conversion funnels, or heatmaps anywhere in the frontend or backend plan — this is a from-scratch analytics pipeline, not a missing endpoint.
|
|
||||||
|
|
||||||
**Decision needed:** does the client want this for launch or later, and which analytics vendor/build to use (build vs. buy).
|
|
||||||
|
|
||||||
## Payment providers
|
|
||||||
|
|
||||||
Current checkout supports QR and card via the existing custom payment flow (`bank-payment-modal`, `payViaCard`). No alternative payment providers are wired or planned.
|
|
||||||
|
|
||||||
**Decision needed:** if additional payment providers (e.g. wallets, buy-now-pay-later) are wanted, needs a business decision on which providers before any integration work starts.
|
|
||||||
@@ -1,60 +0,0 @@
|
|||||||
# PROJECT STRUCTURE
|
|
||||||
|
|
||||||
Folder-by-folder tour of `src/app/**`, then one worked example (the Sprint 19 admin dashboard) followed as a literal file-by-file walk-through, ending with a checklist for adding your own feature.
|
|
||||||
|
|
||||||
Standards referenced below are enforced, not suggestions: `docs/architecture/foundation/Folder-Blueprint.md`, `Naming-Conventions.md`, `Dependency-Rules.md`, `Import-Boundary-Matrix.md`.
|
|
||||||
|
|
||||||
## Top-level folders
|
|
||||||
|
|
||||||
| Folder | What belongs here | Why |
|
|
||||||
|---|---|---|
|
|
||||||
| `core/` | Per-domain: DTOs, mappers, domain models, repositories, domain services (e.g. `core/categories/`, `core/products/`, `core/search/`, `core/admin-auth/`). | Isolates backend-shaped data (DTOs) from the rest of the app. Only the mapper inside a domain's `core/<domain>/` folder is allowed to see both DTO and domain model shapes (ADR-003 import boundaries). |
|
|
||||||
| `facades/` | Cross-feature facades not owned by a single feature, e.g. `facades/platform/category.facade.ts`, `facades/platform/search.facade.ts`. | The only thing components are allowed to inject for data/state (ADR-006/007). Feature-local facades instead live inside that feature's own `facade/` folder (see `features/project-editor/facade/`, `features/admin/dashboard/facade/`). |
|
|
||||||
| `features/` | One folder per feature/domain: `project-editor/`, `admin/<subfeature>/`, `backoffice/<subfeature>/`, `website/catalog/`, `website/product/`, `search/`, `content-management/`, `diagnostics/`. | Organized by feature, not by file type — a feature's models/services/facade/components/pages all live together (`docs/architecture/foundation/Folder-Blueprint.md`). |
|
|
||||||
| `shared/` | `shared/models/config/*` (the `BootstrapConfig` and ~20 sub-configs), reusable presentational UI, utils. | Feature-agnostic by contract — `shared/` must never import from `features/` (Import-Boundary-Matrix). |
|
|
||||||
| `widgets/` | `contracts/` (widget manifest contract), `registry/` (manifest service), `resolvers/` (data-source resolver), `ui/` (widget components). | The dynamic rendering engine — see `docs/ARCHITECTURE.md`. |
|
|
||||||
| `dynamic-renderer/` | `section-engine/`, `page-renderer/`, `section-renderer/`, `widget-host/`. | The page-composition pipeline that turns bootstrap JSON into rendered pages. |
|
|
||||||
| `layouts/` | Page-chrome containers, e.g. `layouts/containers/dynamic-page-layout.component.ts`. | Top-level layout composition, one level above pages. |
|
|
||||||
| `i18n/` | `translations.ts` (interface), `en.ts`/`ru.ts`/`hy.ts`, `translate.pipe.ts`, `TranslateService`. | Single source of truth for all user-facing copy — see `docs/FRONTEND.md`. |
|
|
||||||
| `pages/` | Top-level routed pages not part of a larger feature module (`home`, `cart`, `category`). | Simpler routed pages that don't warrant a full `features/` module. |
|
|
||||||
| `components/` | Reusable standalone components shared across features/pages (`product-card`, `telegram-login`). | Presentational, input/output-only (ADR-006) — no facade/HttpClient/storage access. |
|
|
||||||
| `guards/` | Route guards. | Kept separate from `core/admin-auth/` because `admin-auth.guard.ts` is domain-specific; generic guards live here. |
|
|
||||||
|
|
||||||
## Worked example, end to end: the Sprint 19 admin dashboard
|
|
||||||
|
|
||||||
`src/app/features/admin/dashboard/` — read in the order a new engineer would build it.
|
|
||||||
|
|
||||||
1. **Model** — `models/admin-dashboard.model.ts`. Plain interfaces/types for card data, card status (`loading|empty|error|pending-backend|ready`), health-check entries. No behavior, no imports from Angular DI.
|
|
||||||
|
|
||||||
2. **Gateway interface** — `services/admin-dashboard-metrics.gateway.interface.ts`. An abstract contract (`AdminDashboardMetricsGateway`) for "however we get category/product counts" — deliberately decoupled from *how* (local computation vs. real API) so the facade never knows which implementation is active.
|
|
||||||
|
|
||||||
3. **Gateway implementation** — `services/admin-dashboard-metrics.local.gateway.ts`. `AdminDashboardMetricsLocalGateway implements AdminDashboardMetricsGateway`, composing `BackofficeDataService.loadCategories()/loadProducts()` (already used elsewhere) into counts. A future `AdminDashboardMetricsApiGateway` would implement the same interface against a real endpoint (see `docs/BACKEND.md` §3 CRUD Contracts / §8 migration guide) — nothing above this layer changes when that happens.
|
|
||||||
|
|
||||||
4. **DI token** — `services/admin-dashboard-metrics-gateway.token.ts`. `const ADMIN_DASHBOARD_METRICS_GATEWAY = new InjectionToken<AdminDashboardMetricsGateway>(...)`, bound to the local gateway by default in `app.config.ts`. This is the swap point: rebinding this token to a real API gateway is the *only* change needed to go from mock to real data.
|
|
||||||
|
|
||||||
5. **Supporting service** — `services/admin-dashboard-history.service.ts`. `localStorage`-backed activity log, scoped per tenant — a second, narrower concern (recent activity) that doesn't belong in the metrics gateway.
|
|
||||||
|
|
||||||
6. **Facade** — `facade/admin-dashboard.facade.ts`. `AdminDashboardFacade` is the *only* thing the components below are allowed to inject. It composes `ProjectEditorFacade` (existing — bootstrap/status/validation), `ADMIN_DASHBOARD_METRICS_GATEWAY` (via the token, not the concrete class), and `AdminDashboardHistoryService`, and exposes computed signals per card (status + value) plus the health-check list and quick-actions list.
|
|
||||||
|
|
||||||
7. **Presentational components** — `components/admin-dashboard-card.component.*`, `admin-dashboard-quick-actions.component.*`, `admin-dashboard-activity.component.*`, `admin-dashboard-health.component.*`. Each takes only `@Input()`s (card data, health entries, quick-action list) — no `HttpClient`, no `localStorage`, no route access, no facade injection. This is what makes them independently testable and reusable.
|
|
||||||
|
|
||||||
8. **Page container** — `pages/admin-dashboard-page.component.*`. Injects `AdminDashboardFacade`, computes per-card status from bootstrap-loaded/metrics-error/empty conditions, prefixes `routerLink`s with the current locale (`LanguageService.currentLanguage()`), and passes plain data down to the presentational components above. This is the only place in the feature that knows about routing or the facade.
|
|
||||||
|
|
||||||
9. **Route wiring** — `app.routes.ts`. `/:lang/backoffice/dashboard -> AdminDashboardPageComponent`, guarded by `adminAuthGuard`; `/:lang/backoffice` (empty path) redirects to `dashboard`.
|
|
||||||
|
|
||||||
Full narrative and known gaps: `docs/archive/ADMIN.md` (historical build log) and `docs/BACKEND.md` (current contract).
|
|
||||||
|
|
||||||
## Steps to add a new feature (derived from the example above)
|
|
||||||
|
|
||||||
1. Decide: does this belong in `features/<area>/<feature>/`, or is it simple enough for `pages/`? Route-guarded, multi-component admin/backoffice work goes in `features/admin/*` or `features/backoffice/*`.
|
|
||||||
2. Define the domain model(s) first (`models/*.model.ts`) — no behavior, no DI.
|
|
||||||
3. If the feature needs data that might later come from a real backend, define a gateway/repository **interface** before writing any implementation.
|
|
||||||
4. Implement a local/mock gateway against existing data sources where possible (reuse, don't duplicate — check `core/*` and other features' services first).
|
|
||||||
5. Create an `InjectionToken` for the gateway and bind it to the local implementation in `app.config.ts` (or the relevant provider scope). This is the seam a backend integration will use later — never inject the concrete class directly from a facade or component.
|
|
||||||
6. Write the facade. It is the only consumer of the gateway token, and the only thing components inject.
|
|
||||||
7. Build presentational components as `@Input()`/`@Output()`-only — verify none of them import `HttpClient`, storage, or a facade.
|
|
||||||
8. Build the container/page component that injects the facade and wires routing.
|
|
||||||
9. Add routes in `app.routes.ts`, with `adminAuthGuard` (or the relevant guard) if it's an admin surface.
|
|
||||||
10. Add every new user-facing string to `i18n/translations.ts` (interface) then `en.ts`/`ru.ts`/`hy.ts` — never hardcode copy in a template.
|
|
||||||
11. Document backend gaps (if any) in `docs/BACKEND.md` §3 (CRUD Contracts, endpoints by domain), marking proposed/unimplemented endpoints as such.
|
|
||||||
12. Run `npm run arch:check` (import boundaries + circular dependencies) and `npx tsc -p tsconfig.app.json --noEmit` before committing.
|
|
||||||
@@ -1,90 +0,0 @@
|
|||||||
# Marketplace Platform — Documentation Index
|
|
||||||
|
|
||||||
This is the entry point. Read this first — it links to everything else and tells you what's actually true right now versus what's historical.
|
|
||||||
|
|
||||||
## What this is
|
|
||||||
|
|
||||||
A configuration-driven, multi-tenant SaaS marketplace platform (Angular 21.1, standalone components). One frontend codebase serves unlimited tenants ("marketplaces"). Tenant identity, theme, navigation, page/section/widget composition, and static content all resolve from a per-tenant `bootstrap.json` fetched at runtime — no tenant-specific code paths exist in the frontend. New tenants are onboarded by domain + config + backend data, never by forking the frontend.
|
|
||||||
|
|
||||||
Every tenant has three surfaces on this one codebase:
|
|
||||||
- **Website** — the public storefront (catalog, product pages, cart, static pages).
|
|
||||||
- **Builder** (Project Editor, `/edit/**`) — an in-app editor that edits the tenant's `BootstrapConfig`.
|
|
||||||
- **Backoffice** (Admin, `/:lang/backoffice/**`) — the admin area: products, categories (live-wired to a real gateway), orders, transactions, users, monitoring, analytics, media.
|
|
||||||
|
|
||||||
## System overview
|
|
||||||
|
|
||||||
- **Architecture**: `Component (container) → Facade → Domain Service → Repository/Provider (DI token, swappable mock↔API) → Mock | API`. Enforced by `npm run arch:check` (import boundaries + circular deps), not just convention. Full detail: [ARCHITECTURE.md](ARCHITECTURE.md), governance docs at `docs/architecture/foundation/**` (11 ADRs + 9 standards docs).
|
|
||||||
- **Seller Management** (optional, not built): typed foundation + Phase 1 Backoffice placeholder UI only — `modules.sellerManagement.enabled` gate on `BootstrapConfig`, disabled by default, zero effect on existing marketplaces. Full capability doc: `docs/architecture/foundation/Seller-Management.md`.
|
|
||||||
- **State**: Signals-based facades everywhere, no NgRx (ADR-007).
|
|
||||||
- **Rendering**: Bootstrap JSON → Section Engine → Page Renderer → Widget Host → registered widget component (ADR-005). 100% lazy-loaded routes.
|
|
||||||
- **Theming**: CSS custom properties per tenant, 3 theme stylesheets, never hardcoded hex in a component (ADR-008). Design system spec: [`DESIGN.md`](../DESIGN.md) (root of repo).
|
|
||||||
- **i18n**: 3 locales (en/ru/hy), compile-time-enforced key parity across locale files.
|
|
||||||
- **Backend**: mostly PLANNED (mock gateways behind swappable provider tokens) — see [BACKEND.md](BACKEND.md), the single canonical backend spec (architecture, bootstrap, auth, JWT, Ed25519, permissions, maintenance mode, error model, every endpoint, DTOs, uploads, pagination/filters/sorting, publish workflow, media, builder, implementation checklist). Categories is the one domain fully wired to a real HTTP gateway; everything else is local/mock.
|
|
||||||
|
|
||||||
## Doc index (living documents)
|
|
||||||
|
|
||||||
Read these directly — they're the current source of truth, not one-off reports:
|
|
||||||
|
|
||||||
| Doc | What it covers |
|
|
||||||
|---|---|
|
|
||||||
| [ARCHITECTURE.md](ARCHITECTURE.md) | Layered architecture, container/facade/service pattern, bootstrap/theme/widget engines, links to the enforced ADRs |
|
|
||||||
| [BACKEND.md](BACKEND.md) | **The one canonical backend spec** — auth, JWT, Ed25519, permissions, maintenance mode, every endpoint, DTOs, uploads, error model, migration guide, checklist |
|
|
||||||
| [FRONTEND.md](FRONTEND.md) | App structure, routing, i18n, theming, state management, dynamic rendering |
|
|
||||||
| [EDITOR.md](EDITOR.md) | The Project Editor: every section, save/publish/draft/reset model |
|
|
||||||
| [StaticPages.md](StaticPages.md) | The Static Pages CMS module (the thing that actually serves About/Contacts/etc. today) |
|
|
||||||
| [PROJECT-STRUCTURE.md](PROJECT-STRUCTURE.md) | Folder-by-folder tour of `src/app/**` with a worked feature-add example |
|
|
||||||
| [PROJECT_STATUS.md](PROJECT_STATUS.md) | **Current status** — completion %, readiness for demo/production/backend, honest limitations |
|
|
||||||
| [NEXT_PHASE.md](NEXT_PHASE.md) | The one roadmap — backend integration → testing → performance → monitoring → v2 ideas |
|
|
||||||
| [TODO.md](TODO.md) | Release blockers only — currently empty |
|
|
||||||
| [KNOWN-ISSUES.md](KNOWN-ISSUES.md) | Real, reproducible, currently-open frontend bugs only |
|
|
||||||
| [PRODUCT_BACKLOG.md](PRODUCT_BACKLOG.md) | Items needing a client/business decision (dark mode, brand colors, page content, etc.) |
|
|
||||||
| [FUTURE_FEATURES.md](FUTURE_FEATURES.md) | Nice-to-have, non-blocking future work (Angular 22, bundle splitting, etc.) |
|
|
||||||
| [ANGULAR22_PLAN.md](ANGULAR22_PLAN.md) | Angular 22 upgrade feasibility (research only, not yet executed — tracked in FUTURE_FEATURES.md) |
|
|
||||||
| [SALES-GUIDE.md](SALES-GUIDE.md) | Plain-language guide for the sales team — what to demo, what's not live yet |
|
|
||||||
| [`../DESIGN.md`](../DESIGN.md) | Visual design system: colors, typography, elevation, component specs |
|
|
||||||
| [`../PRODUCT.md`](../PRODUCT.md) | Product positioning, users, brand personality, anti-references |
|
|
||||||
| [`../CHANGELOG.md`](../CHANGELOG.md) | Keep-a-Changelog-format history of shipped features |
|
|
||||||
| `docs/architecture/foundation/**` | Enforced ADRs (ADR-001…ADR-011) and standards docs — governance, read directly |
|
|
||||||
| `docs/context/**` | Barry Cache's own source-backed memory system — infrastructure, not project documentation, do not edit by hand |
|
|
||||||
| `docs/archive/**` | Superseded docs, kept for history only — do not implement against these |
|
|
||||||
|
|
||||||
**One topic, one place**: routing lives in FRONTEND.md, not repeated here. Backend contract lives entirely in BACKEND.md — nowhere else. Design tokens live in DESIGN.md, not repeated elsewhere.
|
|
||||||
|
|
||||||
## What's still open
|
|
||||||
|
|
||||||
[TODO.md](TODO.md) — release blockers only. [PRODUCT_BACKLOG.md](PRODUCT_BACKLOG.md) and [FUTURE_FEATURES.md](FUTURE_FEATURES.md) hold everything else that isn't a blocker.
|
|
||||||
|
|
||||||
## Historical reports
|
|
||||||
|
|
||||||
19 one-off audit/sprint/review reports were archived, then deleted once every open finding worth keeping was confirmed merged into [KNOWN-ISSUES.md](KNOWN-ISSUES.md)/[TODO.md](TODO.md). A 20th (`FRONTEND-ROADMAP.md`, despite its name a shipped-history changelog, not a forward roadmap) was archived to `docs/archive/` on 2026-07-26 for the same reason. Full original text recoverable via `git log --diff-filter=D -- docs/archive` or `docs/archive/FRONTEND-ROADMAP.md` itself.
|
|
||||||
|
|
||||||
## How to run it
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm install
|
|
||||||
npm run start # ng serve
|
|
||||||
npm run start:dexar # ng serve --configuration=development --port 4200
|
|
||||||
npm run build # ng build
|
|
||||||
npm run build:dexar # ng build --configuration=production
|
|
||||||
npm run arch:check # boundary + circular-dependency checks
|
|
||||||
```
|
|
||||||
|
|
||||||
Barry Cache (repo memory, optional but recommended before/after non-trivial work):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run barry -- resume --task "<task>"
|
|
||||||
npm run barry -- validate
|
|
||||||
```
|
|
||||||
|
|
||||||
See root `CLAUDE.md` for the full Barry Cache workflow and memory policy.
|
|
||||||
|
|
||||||
## Current status
|
|
||||||
|
|
||||||
Full detail (completion %, per-area readiness, known limitations): [PROJECT_STATUS.md](PROJECT_STATUS.md). Short version:
|
|
||||||
|
|
||||||
- **Frontend**: Release Candidate, feature-complete. `TODO.md` has no blockers.
|
|
||||||
- **Backend**: not implemented, fully specified. Categories is the one domain wired to a real gateway; everything else is mock. See [BACKEND.md](BACKEND.md).
|
|
||||||
- **Documentation**: consolidated (Final Documentation Consolidation pass, 2026-07-26) — one canonical backend doc, one roadmap, one status doc, historical/sprint docs moved to `docs/archive/`.
|
|
||||||
- **First client demo**: ready, with one caveat — admin role enforcement doesn't exist yet, see `PROJECT_STATUS.md`.
|
|
||||||
|
|
||||||
Draft/publish for the Project Editor is still **frontend-only** (localStorage), no backend persistence — the single largest backend gap, see [BACKEND.md §1 (Bootstrap: Draft vs Published)](BACKEND.md#1-bootstrap) and §8 (Real Backend Implementation Guide).
|
|
||||||
@@ -1,44 +0,0 @@
|
|||||||
# Project Status
|
|
||||||
|
|
||||||
Date: 2026-07-26. Branch: `B2B`. Honest snapshot, verified against source — not aspirational.
|
|
||||||
|
|
||||||
## Completion estimates
|
|
||||||
|
|
||||||
Frontend-engineering estimates only (not effort/story-point estimates) — how much of the intended surface is built and working against mock data.
|
|
||||||
|
|
||||||
| Area | Completion | Basis |
|
|
||||||
|---|---|---|
|
|
||||||
| **Frontend (overall)** | **~95%** | `TODO.md` has zero release blockers; one known minor bug open (`KNOWN-ISSUES.md`); several items deliberately deferred as product decisions, not gaps. |
|
|
||||||
| **Backend** | **~10%** | Only Categories has a real HTTP implementation. Every other domain is a working mock. The *specification* is 100% done (`BACKEND.md`); the *implementation* is not started. |
|
|
||||||
| **UI (visual/component layer)** | **~95%** | No native browser dialogs, no known broken-image paths, no raw dev jargon in default admin views, no apology-toned empty states, consistent shared primitives across all three surfaces. |
|
|
||||||
| **Admin (backoffice)** | **~85%** | UI built and working for every domain (dashboard, products, categories, orders, customers, transactions, users, moderation, media, monitoring, analytics) against mock data. Missing: role enforcement (model exists, nothing checks it), real data everywhere except Categories. |
|
|
||||||
| **Storefront** | **~95%** | Feature-complete for the audited surfaces (home, catalog, product detail, cart, checkout UI, wishlist/compare, search, static/CMS pages). i18n complete (en/ru/hy near-parity). Runs against mock data. |
|
|
||||||
|
|
||||||
## Ready for first customer?
|
|
||||||
|
|
||||||
**Yes, for a demo. No, for production.** The storefront and builder demo end-to-end with no visible rough edges. Production readiness is blocked entirely on the backend not existing yet — see `BACKEND.md`.
|
|
||||||
|
|
||||||
## Known limitations
|
|
||||||
|
|
||||||
- One real frontend bug open: Ed25519 admin-auth error codes `session-expired`/`invalid-signature` are currently unreachable (see `KNOWN-ISSUES.md`).
|
|
||||||
- Admin role model exists in code but isn't enforced by any route guard or UI gate — anyone who passes admin auth has full access regardless of assigned role.
|
|
||||||
- No automated test suite exists for the components touched across recent RC passes (none existed before either).
|
|
||||||
- Two large lazy chunks (`project-editor` 320 kB, `catalog-container` 126 kB) — not release-blocking (`FUTURE_FEATURES.md`).
|
|
||||||
- 53 local `B2B` commits not yet pushed to `origin` (verified 2026-07-26) — pending explicit go-ahead, a process step not a code blocker.
|
|
||||||
- Several product-decision items (dark mode, brand-color contrast, Contacts page content, advanced analytics, additional payment providers) documented but not scheduled — `PRODUCT_BACKLOG.md`.
|
|
||||||
|
|
||||||
## Backend waiting items
|
|
||||||
|
|
||||||
Everything in `BACKEND.md` §9 (Backend Checklist) — 34 items across 6 phases, from foundation (auth, tenant resolution, bootstrap, error envelope) through hardening (rate limiting, CSP, audit logging, maintenance mode). The single largest gap: the Project Editor (builder) has **no save/publish HTTP call at all** today — drafts live in-memory and in `localStorage` only.
|
|
||||||
|
|
||||||
## Authentication status
|
|
||||||
|
|
||||||
**Storefront: live.** Telegram/QR session login is the only way customers authenticate today, and it works end-to-end. **Admin: dormant.** Ed25519 challenge/response admin auth is fully built client-side (keypair service, signing flow, guard, interceptor) but the interceptor isn't registered in `app.config.ts` and the guard isn't attached to any route — it doesn't run in production today. No token refresh exists for either flow. Full contract: `BACKEND.md` §4.
|
|
||||||
|
|
||||||
## Builder status
|
|
||||||
|
|
||||||
Fully functional editor of in-memory/`localStorage` draft state (homepage sections, widgets, languages, navigation, footer, branding, theme, static pages). "Publish" today only promotes the local draft signal — nothing reaches a backend.
|
|
||||||
|
|
||||||
## Documentation status
|
|
||||||
|
|
||||||
Consolidated in this closeout pass. One canonical backend doc (`BACKEND.md`, merges everything that used to be five overlapping files). One roadmap (`NEXT_PHASE.md`). One status doc (this file). Historical sprint/audit reports live in `docs/archive/`, not in root `docs/`. `PROJECT_INDEX.md` is the entry point and every remaining doc is reachable from it. Not fully swept: a handful of low-traffic architecture docs (`docs/architecture/foundation/adr/**`, `FRONTEND.md`, `EDITOR.md`, `ARCHITECTURE.md`, `PROJECT-STRUCTURE.md`, `StaticPages.md`) still contain a few old filename references from before this consolidation — historical-context docs, not the navigation entry point, left as a known gap rather than swept blindly.
|
|
||||||
@@ -1,123 +0,0 @@
|
|||||||
# Release Candidate RC-02 — Final Release Report
|
|
||||||
|
|
||||||
Date: 2026-07-26
|
|
||||||
Branch: `B2B`
|
|
||||||
|
|
||||||
## Completed
|
|
||||||
|
|
||||||
1. **Storefront localization.** Replaced remaining hardcoded English strings
|
|
||||||
(rating/discount aria-labels, hero-carousel dots, product-carousel prev/next
|
|
||||||
buttons, dialog close button, toast dismiss, QR-code alt text, bank-payment
|
|
||||||
iframe title, guest checkout fallback name) with `translate` pipe/service
|
|
||||||
calls, backed by new `common.*` i18n keys in en/ru/hy.
|
|
||||||
Commit: `1163bfd`.
|
|
||||||
|
|
||||||
2. **Empty-store wording.** Audited every empty-collection branch across
|
|
||||||
storefront, builder, and backoffice. Found and fixed one real defect: the
|
|
||||||
category/subcategory empty states used "Oops!"/"Упс!" apology framing for a
|
|
||||||
normal zero-results condition. Everywhere else in the codebase already
|
|
||||||
correctly separates a real `error()` branch from an empty-collection
|
|
||||||
branch with distinct, neutral wording (verified across catalog, product,
|
|
||||||
cart, wishlist/compare, admin list pages, dashboard, media, builder).
|
|
||||||
Commit: `1163bfd`.
|
|
||||||
|
|
||||||
3. **Merchant-friendly wording (Monitoring/Analytics/Reports/Diagnostics).**
|
|
||||||
Analytics, Reports (moderation/reports), and Diagnostics were already
|
|
||||||
clean — no raw HTTP/queue-worker strings found. Monitoring had three
|
|
||||||
developer-facing spots: background queue slugs, webhook event keys, and
|
|
||||||
the activity log's "api" category showing a raw
|
|
||||||
`GET /api/products responded 200 in 84ms` line as the primary message.
|
|
||||||
All three now show plain-language labels by default, with the raw string
|
|
||||||
for API/error/warning events moved behind a collapsed "Technical details"
|
|
||||||
`<details>`. Commit: `ca343c4`.
|
|
||||||
|
|
||||||
4. **Dialog consistency.** Replaced all 12 native `confirm()` calls and 4
|
|
||||||
native `alert()` calls across cart, media library, static-pages editor,
|
|
||||||
and 5 builder components. Confirms now use a new shared
|
|
||||||
`app-confirm-dialog` (composes the existing `app-dialog` + `app-button` —
|
|
||||||
no new dependency), following the same local-signal pattern already used
|
|
||||||
in admin-categories. Cart's alerts route through the existing
|
|
||||||
`UserNotificationService` toast pipeline instead. Zero native
|
|
||||||
`confirm`/`alert`/`prompt` remain in production code (verified by grep).
|
|
||||||
Commit: `6c6fa00`.
|
|
||||||
|
|
||||||
5. **Images.** Found and fixed a real defect: `getMainImage()`'s no-photo
|
|
||||||
fallback pointed at `/assets/images/placeholder.svg`, but that file (and
|
|
||||||
the whole `assets/images/` directory) never existed — any item with zero
|
|
||||||
photos rendered a browser broken-image icon. Added the asset. Also added
|
|
||||||
an `(error)` handler on every dynamic `<img>` that renders a
|
|
||||||
user/admin-supplied URL (product card, cart line item, cart payment QR,
|
|
||||||
product gallery main + thumbnails), so a 404'd image URL swaps to the
|
|
||||||
placeholder instead of shipping broken. Commit: `3e54e88`.
|
|
||||||
|
|
||||||
6. **Legacy cleanup.** Investigated `pages/category`, `pages/search`,
|
|
||||||
`pages/item-detail`, `pages/info/**`, `pages/legal/**` (40+ files) and
|
|
||||||
`dynamic-renderer/`. First five were confirmed unrouted dead code (each
|
|
||||||
had a live replacement already serving its traffic) — deleted outright.
|
|
||||||
`dynamic-renderer/` was confirmed **active** (it's the live homepage
|
|
||||||
rendering pipeline via `HomeComponent` → `WebsiteRuntimeFacade` →
|
|
||||||
`PageRendererService`/`PageResolverService` →
|
|
||||||
`DynamicPageLayoutComponent`) — a prior doc note calling it "unwired" was
|
|
||||||
stale and has been corrected. `docs/TODO.md`, `docs/KNOWN-ISSUES.md`,
|
|
||||||
`docs/FRONTEND-ROADMAP.md`, `docs/PROJECT_INDEX.md` updated accordingly.
|
|
||||||
Commit: `a670ca9`.
|
|
||||||
|
|
||||||
7. **Final QA.** `npx tsc --noEmit` clean after every commit above.
|
|
||||||
`ng serve` production-mode build compiles with no errors. Manually
|
|
||||||
smoke-tested in-browser: home page loads with zero console errors; cart
|
|
||||||
page loads with mock data; the new clear-cart confirm dialog opens with
|
|
||||||
correctly translated title/message/buttons, Cancel closes it without
|
|
||||||
side effects, zero console errors throughout. Backoffice route requires
|
|
||||||
an authenticated admin session (existing `adminAuthGuard` behavior,
|
|
||||||
unrelated to this pass) so the Monitoring page's new wording was verified
|
|
||||||
by reading the compiled template/component, not by an authenticated
|
|
||||||
click-through.
|
|
||||||
|
|
||||||
## Known limitations
|
|
||||||
|
|
||||||
- The i18n string audit and empty-state audit were scoped to storefront/
|
|
||||||
customer-facing surfaces per the task list; backoffice/builder templates
|
|
||||||
were spot-checked but not exhaustively re-audited for hardcoded strings.
|
|
||||||
- `app-confirm-dialog` is a new small shared component (composes existing
|
|
||||||
`app-dialog`/`app-button`, no new library). It intentionally does not
|
|
||||||
cover every dialog in the codebase — only the sites that were previously
|
|
||||||
using native `confirm()`/`alert()`.
|
|
||||||
- Backoffice Monitoring's Technical-details fix only touches the mock local
|
|
||||||
gateway (`AdminMonitoringLocalGateway`); once a real API-backed gateway
|
|
||||||
exists, it will need to populate `technicalDetail` the same way to keep
|
|
||||||
the "Technical details" affordance working.
|
|
||||||
- No new automated tests were added for this pass (none existed for the
|
|
||||||
touched components beforehand either); verification was typecheck +
|
|
||||||
manual smoke test as described above.
|
|
||||||
|
|
||||||
## Deferred items
|
|
||||||
|
|
||||||
- Everything already tracked in `docs/TODO.md` under "Backend — skipped,
|
|
||||||
doing together" remains deferred (bootstrap real content, builder
|
|
||||||
publish/validate backend, backoffice CRUD, media pipeline) — explicitly
|
|
||||||
out of scope per this task's "NO BACKEND CHANGES" instruction.
|
|
||||||
- Non-blocking pre-existing items from prior RC passes noted in
|
|
||||||
`docs/KNOWN-ISSUES.md` (genuine brand-color contrast failures needing
|
|
||||||
theme-owner sign-off, 2 large lazy chunks needing a dedicated split task,
|
|
||||||
`primeng`/`primeicons` removal blocked on an unrelated `barry-cache`
|
|
||||||
dependency issue) are unchanged by this pass.
|
|
||||||
|
|
||||||
## Launch recommendation
|
|
||||||
|
|
||||||
**Ready to ship** from a customer-demo-polish standpoint: no native browser
|
|
||||||
dialogs, no broken-image paths on the audited surfaces, no raw developer
|
|
||||||
jargon in Monitoring's default view, no apology-toned empty states, and the
|
|
||||||
five dead-code page directories are gone rather than lingering as
|
|
||||||
demo-confusing zombies. The remaining known limitations above are scope
|
|
||||||
boundaries (backend, exhaustive re-audit, test coverage) rather than found
|
|
||||||
defects — recommend proceeding, with the backoffice-auth-gated smoke test
|
|
||||||
as the one item worth a human doing a real authenticated click-through on
|
|
||||||
before the actual demo.
|
|
||||||
|
|
||||||
## Commits (this pass)
|
|
||||||
|
|
||||||
- `1163bfd` fix(storefront): replace hardcoded strings with i18n, neutral empty-state wording
|
|
||||||
- `a670ca9` chore(cleanup): delete unrouted legacy pages, update docs
|
|
||||||
- `6c6fa00` fix(ui): replace native confirm()/alert() with shared dialogs and toasts
|
|
||||||
- `3e54e88` fix(storefront): add missing placeholder image asset and onerror fallback
|
|
||||||
- `ca343c4` fix(backoffice): merchant-friendly wording in Monitoring
|
|
||||||
@@ -1,79 +0,0 @@
|
|||||||
# Sales Guide — How to Use & Demo the Marketplace Platform
|
|
||||||
|
|
||||||
Audience: sales team. Plain-language guide to what the product does and how to show it. No code. When something isn't live yet, it's marked **Coming soon** so you never over-promise in a demo.
|
|
||||||
|
|
||||||
## What we're selling in one sentence
|
|
||||||
|
|
||||||
A **multi-tenant marketplace platform**: one codebase runs many branded marketplaces, and each customer gets their own storefront + a self-service admin panel to run it — no developer needed for day-to-day changes.
|
|
||||||
|
|
||||||
## The two halves of the product
|
|
||||||
|
|
||||||
1. **The storefront** — what shoppers see: homepage, catalog, product pages, search, cart, wishlist, compare, multi-language, multi-currency.
|
|
||||||
2. **The admin / editor** — what the marketplace owner uses to run and customize it, without touching code.
|
|
||||||
|
|
||||||
## The headline demo: "change your whole store without a developer"
|
|
||||||
|
|
||||||
This is the strongest pitch. Open the **Project Editor** and show that a marketplace owner can restyle and reconfigure the entire storefront themselves. It has 11 tabs:
|
|
||||||
|
|
||||||
| Tab | What you show the prospect |
|
|
||||||
|---|---|
|
|
||||||
| General | Set the marketplace name, domain, description, and languages |
|
|
||||||
| Branding | Upload logo, small logo, favicon |
|
|
||||||
| Theme | Pick brand colors with a color picker, light/dark mode, choose a site layout |
|
|
||||||
| Header | Toggle which features appear in the top bar (search, cart, wishlist, languages…) |
|
|
||||||
| Footer | Company info, address, contacts, payment icons, social links |
|
|
||||||
| Homepage | Drag-and-drop the order of homepage sections, choose layouts |
|
|
||||||
| Widgets | Configure homepage blocks (hero banner, category grid, product rows) |
|
|
||||||
| Marketplace Features | Turn features on/off (reviews, recommendations, recently-viewed, search history…) |
|
|
||||||
| Languages | Add or remove a language for the whole store |
|
|
||||||
| Navigation | Edit the menu links, per language |
|
|
||||||
| Static Pages | Write pages like "About Us" with a rich text editor |
|
|
||||||
|
|
||||||
**Demo flow that lands well:**
|
|
||||||
1. Change the brand color in **Theme** → show the store instantly reflecting it in **Preview**.
|
|
||||||
2. Reorder homepage sections in **Homepage** by dragging.
|
|
||||||
3. Edit an "About Us" page in **Static Pages** using the text editor (bold, headings, lists, links, images, tables).
|
|
||||||
4. Point out the **Save / Publish** bar: work is saved as a **draft** first, and only goes live when they hit **Publish** — safe to experiment.
|
|
||||||
|
|
||||||
> The rich-text editor for static pages **works today**: type text, make it bold, add headings, bullet lists, links, images, and tables, or switch to a "Code" view for raw HTML.
|
|
||||||
|
|
||||||
## The admin backoffice (running the business)
|
|
||||||
|
|
||||||
Beyond styling, there's a full back-office. In demos, show the **layout and workflow** — the screens are built and polished. Be aware most of these currently run on **sample data** for demo purposes; real live data connects during onboarding (that's a backend integration step, not missing product).
|
|
||||||
|
|
||||||
| Area | What it does | Demo note |
|
|
||||||
|---|---|---|
|
|
||||||
| Dashboard | At-a-glance status: store status, theme, languages, counts, health, recent activity | Cards are live for config; sales counts show "pending backend" until integrated |
|
|
||||||
| Products | Add/edit products: price, variants, images, categories, badges, bulk actions | **Sample data** in demo |
|
|
||||||
| Categories | Category tree with drag-reorder, SEO, translations, soft-delete/restore | **Sample data** in demo |
|
|
||||||
| Orders | Order list/detail, status changes, refunds, cancel, notes, CSV export, invoices | **Sample data** in demo |
|
|
||||||
| Transactions | Payment records, retry failed, fraud flags, audit log, CSV | **Sample data** in demo |
|
|
||||||
| Users & Roles | Team members, roles/permissions, invitations, session/audit history | **Sample data** in demo |
|
|
||||||
| Monitoring | System health + security/event feeds, queues, webhooks | Health is live; feeds are sample |
|
|
||||||
| Analytics | Revenue, orders, top products, plus visitors/funnels | Revenue/orders demo from sample; traffic analytics **Coming soon** |
|
|
||||||
|
|
||||||
## What's polished and worth showing off
|
|
||||||
|
|
||||||
A full UX pass was done across storefront, dashboard, admin, and editor:
|
|
||||||
- Clean, consistent buttons and controls everywhere (one design system).
|
|
||||||
- Smooth, tasteful motion — cards and sections animate in, buttons respond to hover/press — and it automatically respects "reduce motion" accessibility settings.
|
|
||||||
- Works responsively down to phone size.
|
|
||||||
|
|
||||||
## Honest "coming soon" list (don't promise these as live)
|
|
||||||
|
|
||||||
- **Live business data** (real products/orders/customers) — connects per-customer during onboarding; demos use sample data.
|
|
||||||
- **Saving edits to the cloud** — today the editor saves drafts in the browser; server-side save/publish is an onboarding integration.
|
|
||||||
- **Traffic analytics** (visitors, funnels, heatmaps) — the screens exist; the data pipeline is not built yet.
|
|
||||||
- **Per-customer sitemaps / advanced SEO automation** — baseline SEO is in; full automation is roadmap.
|
|
||||||
|
|
||||||
## Quick answers to likely prospect questions
|
|
||||||
|
|
||||||
- **"Do we need a developer to change our store?"** No — the Project Editor covers branding, colors, layout, pages, menus, languages, and feature toggles self-service.
|
|
||||||
- **"Can we have our own domain and branding?"** Yes — each marketplace is its own tenant with its own domain, logo, colors, and content.
|
|
||||||
- **"Multiple languages?"** Yes — add/remove languages in the editor; content is editable per language.
|
|
||||||
- **"Is it safe to experiment?"** Yes — changes are drafts until Published.
|
|
||||||
- **"Is it mobile-friendly?"** Yes — responsive across phone/tablet/desktop.
|
|
||||||
|
|
||||||
## One rule for demos
|
|
||||||
|
|
||||||
If a screen shows sample/placeholder data or a "pending backend" label, say **"this connects to your live data during onboarding"** — it's a real, built screen waiting on integration, not a gap in the product.
|
|
||||||
@@ -1,94 +0,0 @@
|
|||||||
# Sprint Plan — Next Wave (G onward)
|
|
||||||
|
|
||||||
Continues the sprint lettering from `docs/GLOBAL-SPRINT-PLAN.md` (Sprints A–F, all closed 2026-08-05: stub-page closure + widget layout/carousel fixes). Created 2026-08-05.
|
|
||||||
|
|
||||||
**Relationship to `docs/NEXT_PHASE.md`:** that file stays the one *phase-level* roadmap and owns the backend-integration sequencing. This file is the *task-level* tracker for work that is actionable now, plus an explicit parking list for what is blocked and on what. Where the two overlap, `NEXT_PHASE.md` wins on ordering.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Tier 1 — Actionable now (nothing blocks these)
|
|
||||||
|
|
||||||
### Sprint G — Dead-config sweep
|
|
||||||
|
|
||||||
**Why:** This is a config-driven multi-tenant product, so "setting exists in the editor, nothing reads it at runtime" is the signature failure mode — and it reaches clients directly. Three instances were found *by accident* during other work: theme mode (`data-theme-mode` set, no CSS reads it), `HeaderConfig.showProfile` (fixed, Sprint A), `layout.columns` (fixed, Sprint F, and was the root cause of a real client bug report). A mechanical sweep finds the rest in one pass instead of one complaint at a time.
|
|
||||||
|
|
||||||
- [x] Enumerate every field in `BootstrapConfig` and its sub-models (`src/app/shared/models/config/*.model.ts`) — produce the full field inventory as a working list
|
|
||||||
- [x] For each field, grep for a real runtime consumer (a component/service that reads it and changes behavior), distinguishing: **live** (read + has effect), **dead** (never read), **inert** (read but effect is unreachable/no-op — the `data-theme-mode` case)
|
|
||||||
- [x] Cross-check against the editor: which dead/inert fields are *user-editable* today (those are the client-facing ones, highest priority)
|
|
||||||
- [x] Produce a findings table: field → status → editable? → recommendation (wire it / hide the control / delete the field)
|
|
||||||
- [x] Fix the trivially-wireable ones in the same pass (a field with an obvious consumer that was simply never connected)
|
|
||||||
- [x] For each remaining dead field, either hide its editor control or open a scoped follow-up — do **not** leave an editable control for a field nothing reads
|
|
||||||
- [x] Record findings in `docs/KNOWN-ISSUES.md` (real defects) / `docs/PRODUCT_BACKLOG.md` (needs a decision), matching how the earlier audit was folded in
|
|
||||||
|
|
||||||
**Known starting points (already confirmed dead/inert):** theme mode (`PRODUCT_BACKLOG.md`, needs a dark-mode decision — not a wiring fix). Verify no others in `HeaderConfig`, `FooterConfig`, `CatalogConfig`, `ProductPageConfig`, `UserExperienceConfig`, `FeatureFlags`, `SeoConfig`.
|
|
||||||
|
|
||||||
**What shipped:** Full findings table in `docs/DEAD-CONFIG-AUDIT.md`. Fixed and wired: `footer.logoUrl` (new `LogoComponent.srcOverride` input), `company.address.street` + `company.contacts.phone` (new `UiRuntimeFacade.companyAddress()`/`contactPhone()`, rendered in footer bottom bar), `catalog.suggestionsEnabled` (`SearchFacade.autocomplete()` now gates on it). Left dead but tracked (needs a business/design decision, not a mechanical fix): `layout.type` site-layout selector, `company.companyName` copyright-fallback wording (both → `PRODUCT_BACKLOG.md`), `navigation.header` top-nav rendering (→ `KNOWN-ISSUES.md`). `catalog.navigationMode` confirmed intentionally inert (labeled placeholder card, not a bug). No editor control was hidden — every remaining dead field's saved value stays visible and none risked losing already-saved client data.
|
|
||||||
|
|
||||||
### Sprint H — Test suite foundation
|
|
||||||
|
|
||||||
**Why:** 5 `.spec.ts` files exist in the entire repository. Project standards mandate 80% coverage and a TDD workflow; neither is happening. `NEXT_PHASE.md` Phase 2 defers testing until after backend integration — **this sprint deliberately front-runs part of that**, on the argument that tests written against the *current mock gateways* lock in today's behavior and make the eventual real-gateway swap far safer. Post-backend E2E work stays in Phase 2 where it is.
|
|
||||||
|
|
||||||
- [x] Confirm the test runner actually works end to end (`npm test` → `ng test --watch=false --browsers=ChromeHeadlessNoSandbox`) and fix the harness if it doesn't
|
|
||||||
- [x] Establish the house pattern with one exemplar spec per layer, so later tests have something to copy: a pure util, a service, a facade, a component
|
|
||||||
- [x] Facade-level tests against existing mock gateways for the highest-risk domains first: `ProjectEditorFacade` (undo/redo, draft persistence, validation gating on publish), `AdminAnalyticsFacade` (the never-fabricate-a-number contract)
|
|
||||||
- [x] Unit tests for the pure validator primitives (`project-editor/schema/validators/primitives.ts`) — zero-dependency, highest value per line of test
|
|
||||||
- [x] Regression tests for the bugs fixed this cycle so they cannot silently return (carousel `layout.columns` sizing, hero `layout.columns` panel count, header profile login/logout gating)
|
|
||||||
- [x] Wire coverage reporting — **done**: installed `karma-coverage` as a devDependency, added it to `karma.conf.js` (`coverage` reporter + `coverageReporter` block emitting `text-summary`, `html`, and `lcovonly` into `coverage/`). `npx ng test --watch=false --code-coverage` runs clean (83/83 specs pass). Baseline: Statements 32.02% (1025/3201), Branches 18.53% (353/1904), Functions 21.73% (220/1012), Lines 32.76% (946/2887).
|
|
||||||
- [x] Decide whether to gate CI on it — **no, not yet**: 11 spec files is a foundation, not the coverage floor CI gating implies; gate once coverage reporting exists and a real floor number can be set, not before.
|
|
||||||
|
|
||||||
**What shipped:** Harness confirmed working (`npm test` was already green, 57/57). Added 6 new spec files (test count 57 → 75): `ProjectEditorFacade` facade spec (undo/redo, draft-persistence round-trip via a second facade instance reading the same localStorage draft, publish blocked/allowed on `hasBlockingIssues()`) mocking `CONFIG_PROVIDER` as the gateway boundary; `AdminAnalyticsFacade` facade spec asserting `summary().conversionRate` stays `null` and `performance`/`backend-connectivity` health checks stay `'unknown'` rather than being guessed, mocking all 4 gateways + `AdminDashboardFacade`; `HeroWidgetComponent` and `ProductCarouselWidgetComponent` component specs regression-covering `layout.columns` (panel count / items-per-page); `HeaderComponent` component spec regression-covering the login/logout profile toggle (asserts on icon name, not translated aria-label text, since Russian is the default active language in tests). `primitives.ts` and the pure-util/service exemplar layers were already covered by pre-existing specs — verified, not re-done. Cart/checkout facade tests and a "manifest-filtered layout options" regression were scoped out to stay within this sprint's time budget — breadth across the 4 required layers (util/service/facade/component) was prioritized over a 5th facade.
|
|
||||||
|
|
||||||
### Sprint I — Widget `settingsSchema` enforcement
|
|
||||||
|
|
||||||
**Why:** Same disease Sprint E cured for `supportedLayouts`. Every widget in `widget-manifest.json` declares a JSON Schema for its props under `settingsSchema`, and **nothing reads it** — verified: only `supportedDataSources` is consumed anywhere (and only by a diagnostics validator, not the editor). Consequences: widget props are never validated against their own declared contract, and unknown widget types fall back to raw JSON editing in the Widgets section. (`enabled` *is* honored correctly — `widget-registry.bootstrap.service.ts` filters on it.)
|
|
||||||
|
|
||||||
- [x] Read `settingsSchema` in the Widgets editor section and validate widget props against it, surfacing failures through the existing `ProjectValidator` issue pipeline (`fieldKey`/`section`/`severity`) rather than a parallel mechanism
|
|
||||||
- [x] Add a `widgetSettingsSchema` validator alongside the existing `widgetConfig` check in `project-validator.service.ts`
|
|
||||||
- [x] Evaluate replacing the raw-JSON fallback editor with schema-generated fields for widget types that have no hand-authored editor — scope this honestly; if the schemas are too thin to generate a decent UI, keep the JSON fallback and just add validation on top
|
|
||||||
- [x] Confirm the diagnostics page (`features/diagnostics/`) reflects schema violations too, since it already consumes the manifest
|
|
||||||
|
|
||||||
**What shipped:** `validateAgainstSchemaLite(value, schema)` (`schema/validators/primitives.ts`) — a shallow, dependency-free type+required checker (no nested schemas/enums/$ref; checked first, no existing schema-validation utility or library in the repo). `ProjectValidator.widgetSettingsSchemaIssues()` runs it against every widget's `props` vs. its manifest entry's `settingsSchema`, added to the same `validate()` composition as a `widgets`-section warning tagged `fieldKey: 'pages'` — it surfaces automatically through the existing `fieldError('pages')` call already in `widgets-section.component.html`, no template changes needed. `WidgetManifestService` gained a synchronous `getManifestSnapshot()` (same pattern as `ConfigService.getBootstrapSnapshot()`) since `ProjectValidator.validate()` is called synchronously and can't await the manifest HTTP fetch; the check no-ops (matching `RuntimeDiagnosticsValidator`'s existing null-manifest convention) until the manifest has loaded once elsewhere in the app (it always has, by the time a user reaches the editor). Schema-generated form fields were evaluated and explicitly skipped: every widget's `settingsSchema.properties` tops out at 7 flat string/number fields with zero `required` arrays and zero enums/nesting across all 10 widget types in `widget-manifest.json` — too thin to justify generated UI over the existing JSON fallback (`widgets-section.component.ts`'s `updateJson`/`widgetJsonError`), so the JSON editor stays and only gets the new validation layered on top. Diagnostics: `BootstrapDiagnosticsValidator` gained a sibling `validateWidgetSettingsSchema()` next to its existing `validateUnknownWidgetTypes()`, reusing the identical `validateAgainstSchemaLite` call so the editor and diagnostics page can never disagree about what counts as a violation — one check, two surfaces, not a parallel one.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Tier 2 — Blocked on backend
|
|
||||||
|
|
||||||
Sequencing is owned by `docs/BACKEND.md` §9 and `docs/NEXT_PHASE.md` Phase 1. Not re-planned here — that checklist is already the authoritative task list. Frontend-side items that unblock the moment backend lands:
|
|
||||||
|
|
||||||
- [ ] **Ed25519 auth error codes** (`docs/KNOWN-ISSUES.md` Open #1) — `session-expired` and `invalid-signature` recovery screens are built and wired but permanently unreachable, because `toAuthErrorShape()` derives the code purely from HTTP status and never reads a body-level code. Needs: backend returning a distinguishable `error.code` (`BACKEND.md` §6), then a small frontend change to prefer it over the status fallback.
|
|
||||||
- [ ] **Swap every mock gateway for its real counterpart** behind the existing DI tokens, in the dependency order `BACKEND.md` §8 specifies
|
|
||||||
- [ ] **Maintenance-mode frontend UI** (`BACKEND.md` §10 flags full-page takeover, per-module banners, scheduled countdown as not existing) — deliberately not built during Sprint C for exactly this reason
|
|
||||||
- [ ] **Real Monitoring data source** — page currently renders mock activity (`NEXT_PHASE.md` Phase 4)
|
|
||||||
- [ ] **Re-profile performance under real latency** (`NEXT_PHASE.md` Phase 3) — mock responses are instant, real ones won't be; loading/skeleton timing is untested against reality
|
|
||||||
|
|
||||||
## Tier 3 — Blocked on a business decision
|
|
||||||
|
|
||||||
No engineering work should start on these until answered. Full detail in `docs/PRODUCT_BACKLOG.md`.
|
|
||||||
|
|
||||||
- [ ] **Dark mode** — does the client want it? If yes it's a real project (dark palette + CSS strategy + `matchMedia` for "system"), not a wiring fix. Blocks the theme-mode selector, which is inert today.
|
|
||||||
- [ ] **Brand color contrast (WCAG AA)** — `--border-color` fails 3:1 in every theme; several status colors fail 4.5:1 as text. Fixing means visibly changing the brand — needs theme-owner sign-off.
|
|
||||||
- [ ] **Stars rating glyph token** — literal hex with no matching design token; add a token or reuse an existing one (visual shift either way).
|
|
||||||
- [ ] **Contacts page content** — nothing written for it at all. Content question.
|
|
||||||
- [ ] **Advanced analytics** — no data source exists for traffic/funnels/heatmaps. Build vs. buy, and launch vs. later.
|
|
||||||
- [ ] **Additional payment providers** — which ones, if any, before integration work starts.
|
|
||||||
|
|
||||||
## Tier 4 — Deferred, non-blocking
|
|
||||||
|
|
||||||
From `docs/FUTURE_FEATURES.md`. No decision needed, just not worth doing now.
|
|
||||||
|
|
||||||
- [ ] **Angular 22 upgrade** — researched, ~2–3.5 days, needs a dependency fix and Node bump first. Plan: `docs/ANGULAR22_PLAN.md`. **Run as its own dedicated session** — framework upgrades don't share a session with feature work.
|
|
||||||
- [ ] **Bundle splitting** — `project-editor` (~896 kB) and `catalog-container` (~330 kB) lazy chunks are large; no mechanical split found, needs a dedicated profiling task, ideally under real backend latency
|
|
||||||
- [ ] **Cart payment modal → `app-dialog`** — composition cleanup, functionally and accessibly complete as-is
|
|
||||||
- [ ] **Homepage hero-to-categories spacing** — traces to mock fixture padding values, not a confirmed defect; needs reproduction with real tenant data before it's worth investigating
|
|
||||||
|
|
||||||
## Tier 5 — Infrastructure
|
|
||||||
|
|
||||||
- [ ] **Server deploy** — no deploy pipeline exists in this repo (only `.github/workflows/architecture-governance.yml`). Deploys are currently manual/out-of-band. Worth deciding whether a real pipeline should exist; separately, SSH from the agent harness is blocked, so agent-driven deploys need either a permission rule or a different mechanism.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Suggested order
|
|
||||||
|
|
||||||
**G → H → I.** Sprint G is cheap, mechanical, and directly prevents more client-reported ghost settings (it is the same class of bug as the one already reported). Sprint H is the highest-value thing available that isn't blocked on anything, and it gets more valuable the earlier it lands, since every later change rides on it. Sprint I is real but narrower — it hardens an editor path rather than fixing something users hit today.
|
|
||||||
|
|
||||||
Tier 2 starts the moment backend Phase 1 lands. Tier 3 needs answers, not engineering. Tier 4 is genuinely optional.
|
|
||||||
@@ -1,84 +0,0 @@
|
|||||||
# Static Pages (Project Editor module)
|
|
||||||
|
|
||||||
Sprint X+2. Full-featured CRUD editor for tenant static content (About, Privacy, Terms, Contacts, custom pages, etc.), living inside the Project Editor at `/edit/static-pages`. Edits `bootstrap.staticPages` directly — the same model the storefront renders from (`docs/BACKEND.md` §3 CRUD Contracts, CMS), no parallel content store.
|
|
||||||
|
|
||||||
`/backoffice/static-pages` (Admin dashboard) redirects here rather than hosting a second CRUD UI over the same data.
|
|
||||||
|
|
||||||
## Where it lives
|
|
||||||
|
|
||||||
```
|
|
||||||
src/app/features/content-management/
|
|
||||||
models/content-page.model.ts ContentPage — the CRUD-facing shape
|
|
||||||
services/content-page.service.ts normalize / resolve / validate / serialize <-> StaticPageConfig
|
|
||||||
facade/content-management.facade.ts
|
|
||||||
components/
|
|
||||||
static-pages-editor.component.* the editor UI (list + per-page card)
|
|
||||||
static-page-preview/ device preview (desktop/tablet/mobile)
|
|
||||||
|
|
||||||
src/app/shared/models/config/static-page.model.ts StaticPageConfig — the bootstrap wire format
|
|
||||||
src/app/features/project-editor/components/html-editor/ MarketplaceHtmlEditorComponent (rich text)
|
|
||||||
src/app/core/config/static-page-resolver.service.ts storefront resolver
|
|
||||||
```
|
|
||||||
|
|
||||||
`ContentPageService` is the single translation layer between the editor's `ContentPage[]` and the bootstrap's `Record<string, StaticPageConfig>` (or the legacy array format) — normalize/resolve/validate/serialize all live there. Nothing else should hand-roll that mapping.
|
|
||||||
|
|
||||||
## Field reference
|
|
||||||
|
|
||||||
### General
|
|
||||||
- `id` — stable key, also the bootstrap record key.
|
|
||||||
- `slug` — used for duplicate-slug detection and as the `route` default.
|
|
||||||
- `route` — **independently editable** from `slug` (defaults from it, but can diverge — e.g. a legacy redirect path). Validated for duplicates against every other page's route.
|
|
||||||
- `enabled` — master on/off switch. A disabled page never resolves on the storefront, regardless of `status`.
|
|
||||||
- Navigation visibility — `showInHeader`, `showInFooter`, `showInSitemap` (independent per-surface flags, unrelated to `enabled`).
|
|
||||||
- `order` — sort position in the editor list and (for footer pages) the auto-generated footer nav group.
|
|
||||||
- `icon` — optional icon identifier.
|
|
||||||
|
|
||||||
### Localization
|
|
||||||
- `title` (per locale, in `translations[locale].title`) and a top-level `title` fallback.
|
|
||||||
- `translations[locale].html` — the rich-text/HTML body, one per supported locale.
|
|
||||||
- `customTemplate` — optional template identifier; consumed by nothing yet (data-only field, forward-compatible with a future template-selection feature).
|
|
||||||
|
|
||||||
### SEO
|
|
||||||
Per top-level `seo` and per-translation `translations[locale].seo` (locale-specific overrides win when resolving): `title`, `description`, `keywords`, `canonical`, `robots`, `ogTitle`, `ogDescription`, `ogImage`.
|
|
||||||
|
|
||||||
### Media
|
|
||||||
- `heroImage`, `thumbnail` — wired through the shared `MediaPickerComponent` (same picker used by Branding/Footer logos).
|
|
||||||
- `gallery: string[]` — a lightweight comma-separated URL list ("future ready" per the brief; no dedicated multi-upload UI yet).
|
|
||||||
|
|
||||||
### Publishing
|
|
||||||
- `status: 'draft' | 'published'` — **per-page** publish lifecycle, independent of the whole-bootstrap draft/publish cycle (see below).
|
|
||||||
- Modified indicator — an "unsaved changes" badge per page, diffed against the originally loaded/published snapshot (`ProjectEditorFacade.originalStaticPages`).
|
|
||||||
|
|
||||||
## The enabled + status gating story
|
|
||||||
|
|
||||||
A static page resolves on the storefront (`ContentPageService.resolvePage`, used by both `StaticPageResolverService` for the page route and `FooterResolverService` for the auto-generated footer nav group) **only when `enabled === true` AND `status === 'published'`.** This is independent of whether the surrounding bootstrap itself has been published — a page marked `draft` stays invisible even after the tenant hits "Publish" on the whole config, and only becomes visible once its own status flips to `published`.
|
|
||||||
|
|
||||||
**Compatibility default:** normalizing existing bootstrap data (loaded from the backend, imported, or read from a legacy array-format `staticPages`) defaults missing `enabled`/`status` to `enabled: true, status: 'published'` — pre-existing pages never get silently un-published by this feature landing. Only the editor's **create-page** action opts a brand-new page into `status: 'draft'` by default, so newly authored content doesn't go live until an author explicitly publishes it.
|
|
||||||
|
|
||||||
The Static Pages editor's own **Live Preview** (desktop/tablet/mobile, `StaticPagePreviewComponent`) intentionally bypasses this gate — it renders straight from the page's current in-memory HTML, so a draft page can still be previewed before publishing.
|
|
||||||
|
|
||||||
## CRUD, search, filter, bulk actions
|
|
||||||
|
|
||||||
- Create, duplicate (clones a page as a new `draft`), delete (confirm dialog), reorder (up/down — not drag-and-drop; see below).
|
|
||||||
- Search across id/slug/route/title (all locales); filter by status (draft/published) or by locale (hides pages missing a translation for the selected locale).
|
|
||||||
- Bulk actions (multi-select checkboxes): delete, enable, disable, publish, unpublish.
|
|
||||||
- **Important implementation detail:** every mutation (create/duplicate/delete/move/bulk) operates on the full, unfiltered page list, never the search/filter-narrowed view — reading from the filtered view before writing back would silently delete whatever the active filter was hiding. See the `persist()` comment in `static-pages-editor.component.ts`.
|
|
||||||
- Reorder is up/down (`move()`), not literal drag handles — a deliberate, lower-complexity scope call; swapping in drag-and-drop later is additive.
|
|
||||||
|
|
||||||
## Validation
|
|
||||||
|
|
||||||
`ContentPageService.validatePages()` returns: `duplicateSlugs`, `duplicateRoutes` (checked independently — a route can diverge from its slug), `emptyTitles`, `invalidHtml` (via `schema/validators/primitives.validateHtml`), `invalidSeo` (canonical/OG-image URL shape, and `robots` against a known-token set: `index`, `noindex`, `follow`, `nofollow`, and their comma-joined combinations). Surfaced as per-page badges in the editor.
|
|
||||||
|
|
||||||
This is layered under (not a replacement for) `ProjectValidator`'s existing platform-wide checks (`docs/EDITOR.md`'s "Configuration schema..." section), which already cover duplicate slugs and cross-surface duplicate routes (pages vs. static pages) at the whole-bootstrap level.
|
|
||||||
|
|
||||||
## Rich text editor
|
|
||||||
|
|
||||||
`MarketplaceHtmlEditorComponent` — see `docs/EDITOR.md`'s "HTML editor (Static Pages)" section for the full toolbar list, the Sprint X+2 additions (horizontal rule, code block, embed), and the HTML-mode validation contract.
|
|
||||||
|
|
||||||
## Navigation integration
|
|
||||||
|
|
||||||
The Navigation section (`navigation-section.component`) has an "Insert page link" control (page picker + button) next to both header and footer "Add link." It creates a `NavigationItemConfig { type: 'staticPage', key: <pageId> }` — a shape the resolvers (`StaticPageResolverService`, `FooterResolverService`) already understood before this sprint; only the editor-side create path was missing. A static-page-linked nav row shows a "Linked to page" indicator instead of editable label/URL fields, since both are derived dynamically from the linked page.
|
|
||||||
|
|
||||||
## Export / import / draft / publish
|
|
||||||
|
|
||||||
No changes to `ProjectEditorIoService` or `ProjectEditorDraftStorageService` — static pages flow through `bootstrap.staticPages` exactly as before, so JSON export/import and the draft-autosave/publish cycle work unmodified. All Sprint X+2 fields are additive and optional at the wire level.
|
|
||||||
@@ -1,7 +0,0 @@
|
|||||||
# TODO
|
|
||||||
|
|
||||||
No frontend blockers.
|
|
||||||
|
|
||||||
Frontend Release Candidate complete.
|
|
||||||
|
|
||||||
Waiting for backend integration.
|
|
||||||
@@ -1,44 +0,0 @@
|
|||||||
# Coding Standards
|
|
||||||
|
|
||||||
Status: Mandatory
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Core Principles
|
|
||||||
|
|
||||||
- Keep modules small and cohesive.
|
|
||||||
- Prefer pure functions where possible.
|
|
||||||
- Prefer composition over inheritance.
|
|
||||||
- Prefer configuration over conditionals.
|
|
||||||
- Avoid duplication; extract shared behavior above 70 percent overlap.
|
|
||||||
|
|
||||||
## Type Safety
|
|
||||||
|
|
||||||
- No any in domain and configuration contracts.
|
|
||||||
- Strict typing for API payloads and configuration schemas.
|
|
||||||
- Use discriminated unions for widget and section types.
|
|
||||||
|
|
||||||
## Error Handling
|
|
||||||
|
|
||||||
- Errors normalized at service/integration boundaries.
|
|
||||||
- UI displays user-safe messages from facades/view models.
|
|
||||||
- No unhandled promise rejections.
|
|
||||||
|
|
||||||
## API and IO
|
|
||||||
|
|
||||||
- IO is performed in services/integrations only.
|
|
||||||
- Use facades to orchestrate calls and map outputs.
|
|
||||||
- Keep presentation layer side-effect free.
|
|
||||||
|
|
||||||
## Testing Expectations
|
|
||||||
|
|
||||||
- Unit tests for facades, services, and mapping logic.
|
|
||||||
- Contract tests for bootstrap schema compatibility.
|
|
||||||
- Boundary tests for forbidden imports.
|
|
||||||
|
|
||||||
## Review Checklist
|
|
||||||
|
|
||||||
- Does this code violate layer boundaries?
|
|
||||||
- Is tenant behavior configuration-driven?
|
|
||||||
- Is logic duplicated and extractable?
|
|
||||||
- Are auth/payment contracts unchanged?
|
|
||||||
- Is the app still compilable?
|
|
||||||
@@ -1,41 +0,0 @@
|
|||||||
# Component Standards
|
|
||||||
|
|
||||||
Status: Mandatory
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Component Categories
|
|
||||||
|
|
||||||
- UI Component: presentational, reusable, stateless or locally visual state only.
|
|
||||||
- Container Component: binds facades and maps view model to UI inputs.
|
|
||||||
- Layout Component: structural composition of sections/widgets.
|
|
||||||
|
|
||||||
## Reusable UI Rules
|
|
||||||
|
|
||||||
A reusable component must:
|
|
||||||
|
|
||||||
- Receive data via Inputs.
|
|
||||||
- Emit user intent via Outputs.
|
|
||||||
- Contain no HttpClient usage.
|
|
||||||
- Contain no localStorage/sessionStorage usage.
|
|
||||||
- Import no environment data.
|
|
||||||
- Have no tenant-specific behavior.
|
|
||||||
- Have no project-name-specific behavior (including legacy variant naming paths).
|
|
||||||
- Have no auth/payment/authorization logic.
|
|
||||||
- Have no route navigation logic.
|
|
||||||
- Render no hardcoded UI copy when translation keys are expected.
|
|
||||||
|
|
||||||
## Container Rules
|
|
||||||
|
|
||||||
- Orchestrate business behavior through facades.
|
|
||||||
- Map facade state into UI-friendly view model.
|
|
||||||
- Handle route and guard interactions.
|
|
||||||
- Never leak domain internals to UI components.
|
|
||||||
|
|
||||||
## Reuse and Duplication Rule
|
|
||||||
|
|
||||||
- If two components share more than 70 percent behavior or template structure, extract reusable component.
|
|
||||||
|
|
||||||
## Accessibility and UX
|
|
||||||
|
|
||||||
- Components must provide semantic markup and keyboard support.
|
|
||||||
- Outputs must represent intent, not implementation details.
|
|
||||||
@@ -1,62 +0,0 @@
|
|||||||
# Configuration Standards
|
|
||||||
|
|
||||||
Status: Mandatory
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Source of Truth
|
|
||||||
|
|
||||||
- All runtime application configuration originates from bootstrap payload.
|
|
||||||
- ConfigService is the only component allowed to load configuration.
|
|
||||||
- No direct JSON loading outside ConfigService.
|
|
||||||
|
|
||||||
## Provider Abstraction
|
|
||||||
|
|
||||||
- Configuration provider must be swappable.
|
|
||||||
- Mock and API providers must return identical schema.
|
|
||||||
- Consumer code remains unchanged when provider changes.
|
|
||||||
|
|
||||||
## Bootstrap Contract Scope
|
|
||||||
|
|
||||||
Bootstrap includes at minimum:
|
|
||||||
|
|
||||||
- Tenant
|
|
||||||
- Branding
|
|
||||||
- Theme
|
|
||||||
- Company
|
|
||||||
- Feature flags
|
|
||||||
- Navigation
|
|
||||||
- Pages, sections, widgets
|
|
||||||
- Localization
|
|
||||||
- SEO
|
|
||||||
- Permissions and capability model
|
|
||||||
- Endpoint descriptors
|
|
||||||
|
|
||||||
## Backend Compatibility
|
|
||||||
|
|
||||||
- Frontend calls GET /bootstrap.
|
|
||||||
- Backend resolves tenant from Host.
|
|
||||||
- Frontend does not send tenant id/project key.
|
|
||||||
|
|
||||||
## Validation and Versioning
|
|
||||||
|
|
||||||
- Bootstrap payload must include schema version.
|
|
||||||
- Validate payload before applying to runtime.
|
|
||||||
- Invalid payload fails fast with controlled fallback.
|
|
||||||
|
|
||||||
## Mock Rules
|
|
||||||
|
|
||||||
- Mock payloads must match future API responses exactly.
|
|
||||||
- No mock-only fields.
|
|
||||||
- No mock-only nesting conventions.
|
|
||||||
|
|
||||||
## Sprint 11.5 Bootstrap Audit Addendum
|
|
||||||
|
|
||||||
- Every configurable website behavior must be representable in bootstrap contracts or widget metadata.
|
|
||||||
- Missing configuration must be documented before implementation work starts.
|
|
||||||
- Frontend teams must not implement backend contract changes in standardization sprints.
|
|
||||||
|
|
||||||
Current documented gaps:
|
|
||||||
|
|
||||||
- Widget role/permission enforcement requires richer auth session claims than currently available.
|
|
||||||
- Catalog popular-search defaults should move from facade constants into bootstrap `catalog` config.
|
|
||||||
- Optional override support for persistent-storage key prefixes is not yet represented in bootstrap schema.
|
|
||||||
@@ -1,35 +0,0 @@
|
|||||||
# Dependency Rules
|
|
||||||
|
|
||||||
Status: Mandatory
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Rule Set
|
|
||||||
|
|
||||||
1. One-way dependency direction only.
|
|
||||||
2. No circular dependencies.
|
|
||||||
3. No feature imports another feature directly.
|
|
||||||
4. Shared is dependency-minimal and feature-agnostic.
|
|
||||||
5. Core is platform base and does not consume feature modules.
|
|
||||||
6. UI Library is pure presentation and cannot depend on facades/services with business behavior.
|
|
||||||
7. Widgets depend on UI Library and contracts, not on feature internals.
|
|
||||||
8. Pages compose layouts/widgets via contracts and facades.
|
|
||||||
9. Facades depend on services/contracts, never on UI components.
|
|
||||||
10. Integrations isolate external systems and expose stable interfaces.
|
|
||||||
|
|
||||||
## Dependency Injection Rules
|
|
||||||
|
|
||||||
- Depend on interfaces/tokens where replacement is expected.
|
|
||||||
- Avoid direct concrete service references across bounded contexts.
|
|
||||||
- Use adapter pattern for legacy stable modules.
|
|
||||||
|
|
||||||
## Cross-Domain Communication
|
|
||||||
|
|
||||||
- Allowed through contracts, events, and facade APIs.
|
|
||||||
- Forbidden through direct state mutation across domains.
|
|
||||||
|
|
||||||
## Forbidden Patterns
|
|
||||||
|
|
||||||
- Component to HttpClient direct calls in reusable visual components.
|
|
||||||
- Direct environment import in visual components.
|
|
||||||
- Direct localStorage/sessionStorage usage in UI components.
|
|
||||||
- Route navigation logic in UI library components.
|
|
||||||
@@ -1,122 +0,0 @@
|
|||||||
# Folder Blueprint
|
|
||||||
|
|
||||||
Status: Mandatory
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Objective
|
|
||||||
|
|
||||||
Define the target folder layout for the Foundation Phase and all subsequent phases.
|
|
||||||
|
|
||||||
## Blueprint
|
|
||||||
|
|
||||||
src
|
|
||||||
- app
|
|
||||||
- core
|
|
||||||
- bootstrap
|
|
||||||
- providers
|
|
||||||
- loaders
|
|
||||||
- validators
|
|
||||||
- config
|
|
||||||
- application-config.token.ts
|
|
||||||
- config.service.ts
|
|
||||||
- feature-flag.service.ts
|
|
||||||
- runtime
|
|
||||||
- app-runtime.service.ts
|
|
||||||
- platform-context.service.ts
|
|
||||||
- guards
|
|
||||||
- interceptors
|
|
||||||
- error-handling
|
|
||||||
- shared
|
|
||||||
- models
|
|
||||||
- api
|
|
||||||
- config
|
|
||||||
- domain
|
|
||||||
- ui
|
|
||||||
- types
|
|
||||||
- enums
|
|
||||||
- contracts
|
|
||||||
- utils
|
|
||||||
- constants
|
|
||||||
- ui-library
|
|
||||||
- atoms
|
|
||||||
- molecules
|
|
||||||
- organisms
|
|
||||||
- directives
|
|
||||||
- pipes
|
|
||||||
- widgets
|
|
||||||
- registry
|
|
||||||
- contracts
|
|
||||||
- containers
|
|
||||||
- ui
|
|
||||||
- layouts
|
|
||||||
- shells
|
|
||||||
- sections
|
|
||||||
- containers
|
|
||||||
- pages
|
|
||||||
- public
|
|
||||||
- builder
|
|
||||||
- backoffice
|
|
||||||
- features
|
|
||||||
- website
|
|
||||||
- catalog
|
|
||||||
- product
|
|
||||||
- cart
|
|
||||||
- checkout
|
|
||||||
- builder
|
|
||||||
- theme-editor
|
|
||||||
- page-editor
|
|
||||||
- navigation-editor
|
|
||||||
- seo-editor
|
|
||||||
- feature-flag-editor
|
|
||||||
- backoffice
|
|
||||||
- products
|
|
||||||
- categories
|
|
||||||
- orders
|
|
||||||
- customers
|
|
||||||
- inventory
|
|
||||||
- media
|
|
||||||
- settings
|
|
||||||
- facades
|
|
||||||
- website
|
|
||||||
- builder
|
|
||||||
- backoffice
|
|
||||||
- platform
|
|
||||||
- integrations
|
|
||||||
- auth
|
|
||||||
- payment
|
|
||||||
- authorization
|
|
||||||
- theme
|
|
||||||
- tokens
|
|
||||||
- mappers
|
|
||||||
- runtime
|
|
||||||
- dynamic-renderer
|
|
||||||
- page-renderer
|
|
||||||
- section-renderer
|
|
||||||
- widget-host
|
|
||||||
- app.routes.ts
|
|
||||||
- app.config.ts
|
|
||||||
- app.ts
|
|
||||||
- app.html
|
|
||||||
- assets
|
|
||||||
- mock
|
|
||||||
- bootstrap
|
|
||||||
- website
|
|
||||||
- builder
|
|
||||||
- backoffice
|
|
||||||
|
|
||||||
## Foundation Phase Scope
|
|
||||||
|
|
||||||
During Phase 1:
|
|
||||||
|
|
||||||
- Create folder structure and placeholders only.
|
|
||||||
- Do not create business feature implementations.
|
|
||||||
- Keep app runnable and compilable.
|
|
||||||
|
|
||||||
## Placement Rules
|
|
||||||
|
|
||||||
- Contracts and interfaces go to shared models/contracts/types.
|
|
||||||
- Pure visual components go to ui-library.
|
|
||||||
- Configuration-driven blocks go to widgets.
|
|
||||||
- Page composition logic goes to layouts and dynamic-renderer.
|
|
||||||
- Domain orchestration belongs to facades.
|
|
||||||
- Stable auth/payment integrations stay in integrations wrappers.
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
# Import Boundary Matrix
|
|
||||||
|
|
||||||
Status: Mandatory
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Allowed Import Matrix
|
|
||||||
|
|
||||||
Legend:
|
|
||||||
|
|
||||||
- Yes: Allowed
|
|
||||||
- No: Forbidden
|
|
||||||
- Limited: Allowed only via published contracts
|
|
||||||
|
|
||||||
| From \ To | Core | Shared | UI Library | Widgets | Layouts | Pages | Features | Facades | Integrations |
|
|
||||||
|---|---|---|---|---|---|---|---|---|---|
|
|
||||||
| Core | Yes | Yes | No | No | No | No | No | No | Limited |
|
|
||||||
| Shared | Yes | Yes | No | No | No | No | No | No | No |
|
|
||||||
| UI Library | Shared only | Yes | Yes | No | No | No | No | No | No |
|
|
||||||
| Widgets | Shared/Core contracts | Yes | Yes | Yes | No | No | No | Limited | No |
|
|
||||||
| Layouts | Shared/Core contracts | Yes | Yes | Yes | Yes | No | No | Limited | No |
|
|
||||||
| Pages | Shared/Core contracts | Yes | Yes | Yes | Yes | Yes | No | Yes | No |
|
|
||||||
| Features | Shared/Core contracts | Yes | Yes | Yes | Yes | Yes | No direct feature-to-feature | Yes | Limited |
|
|
||||||
| Facades | Shared/Core contracts | Yes | No | No | No | No | Limited | Yes | Yes |
|
|
||||||
| Integrations | Shared/Core contracts | Yes | No | No | No | No | No | Limited | Yes |
|
|
||||||
|
|
||||||
## Additional Constraints
|
|
||||||
|
|
||||||
- Features cannot import other features directly.
|
|
||||||
- Shared cannot import any feature, page, layout, widget, or UI layer.
|
|
||||||
- UI Library cannot import facades, integrations, router, or HttpClient.
|
|
||||||
- Core cannot import features.
|
|
||||||
- Circular dependencies are forbidden in all directions.
|
|
||||||
|
|
||||||
## Enforcement
|
|
||||||
|
|
||||||
- Enforce with lint module boundaries.
|
|
||||||
- Enforce with dependency graph checks in CI.
|
|
||||||
- Merge blocked on violations.
|
|
||||||
@@ -1,56 +0,0 @@
|
|||||||
# Naming Conventions
|
|
||||||
|
|
||||||
Status: Mandatory
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## General
|
|
||||||
|
|
||||||
- Use clear domain-oriented names.
|
|
||||||
- Prefer explicit names over abbreviations.
|
|
||||||
- Keep naming consistent across Website, Builder, Backoffice.
|
|
||||||
|
|
||||||
## Files and Folders
|
|
||||||
|
|
||||||
- Folders: kebab-case.
|
|
||||||
- TypeScript files: kebab-case with suffix.
|
|
||||||
- Interfaces: PascalCase.
|
|
||||||
- Types: PascalCase.
|
|
||||||
- Enums: PascalCase.
|
|
||||||
- Constants: UPPER_SNAKE_CASE for true constants.
|
|
||||||
|
|
||||||
## Angular Artifacts
|
|
||||||
|
|
||||||
- Component: name.component.ts
|
|
||||||
- Container component: name.container.component.ts
|
|
||||||
- Facade: name.facade.ts
|
|
||||||
- Service: name.service.ts
|
|
||||||
- Adapter: name.adapter.ts
|
|
||||||
- Token: name.token.ts
|
|
||||||
- Guard: name.guard.ts
|
|
||||||
- Resolver: name.resolver.ts
|
|
||||||
- Pipe: name.pipe.ts
|
|
||||||
|
|
||||||
## Configuration Contracts
|
|
||||||
|
|
||||||
- Bootstrap payload root: BootstrapConfig.
|
|
||||||
- Domain segments named by function:
|
|
||||||
- TenantConfig
|
|
||||||
- BrandingConfig
|
|
||||||
- ThemeConfig
|
|
||||||
- FeatureFlagsConfig
|
|
||||||
- NavigationConfig
|
|
||||||
- PageConfig
|
|
||||||
- SectionConfig
|
|
||||||
- WidgetConfig
|
|
||||||
|
|
||||||
## Event and Action Naming
|
|
||||||
|
|
||||||
- Outputs: actionRequested, valueChanged, selectionChanged.
|
|
||||||
- Facade commands: loadX, updateX, saveX, publishX.
|
|
||||||
- Selectors/signals: xState, xViewModel, isXEnabled.
|
|
||||||
|
|
||||||
## Prohibited Names
|
|
||||||
|
|
||||||
- Generic names without domain meaning such as DataService or UtilsService.
|
|
||||||
- Tenant-coded names in frontend source.
|
|
||||||
- Brand-specific class names in reusable layers.
|
|
||||||
@@ -1,128 +0,0 @@
|
|||||||
# Marketplace Platform Architecture Foundation
|
|
||||||
|
|
||||||
Status: Approved
|
|
||||||
Owner: Lead Software Architect
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
This folder defines the mandatory engineering governance for transforming this codebase into a reusable, configuration-driven, multi-tenant Marketplace Platform (Marketplace-as-a-Service).
|
|
||||||
|
|
||||||
This repository is not treated as a single marketplace website.
|
|
||||||
It is a platform runtime that must support unlimited tenants from one Angular application.
|
|
||||||
|
|
||||||
## Platform Principles
|
|
||||||
|
|
||||||
- One codebase, unlimited tenants.
|
|
||||||
- Every tenant has three surfaces: Website, Builder, Backoffice.
|
|
||||||
- Frontend contains no tenant-specific implementation code.
|
|
||||||
- Tenant behavior is controlled by configuration loaded at bootstrap.
|
|
||||||
- Authentication, payment, authorization behavior and contracts remain unchanged.
|
|
||||||
- Prefer composition over inheritance.
|
|
||||||
- Prefer configuration over conditionals.
|
|
||||||
- No circular dependencies.
|
|
||||||
- Shared and UI layers are feature-agnostic.
|
|
||||||
|
|
||||||
## Non-Negotiable Constraints
|
|
||||||
|
|
||||||
- Authentication behavior remains exactly as current implementation.
|
|
||||||
- Payment API behavior remains exactly as current implementation.
|
|
||||||
- Authorization behavior remains exactly as current implementation.
|
|
||||||
- Existing authentication and payment API contracts cannot be changed.
|
|
||||||
- Proven modules are reused, wrapped, and isolated, not redesigned.
|
|
||||||
|
|
||||||
## Document Set
|
|
||||||
|
|
||||||
### Architecture Decision Records
|
|
||||||
|
|
||||||
- [ADR-001](adr/ADR-001-platform-model.md)
|
|
||||||
- [ADR-002](adr/ADR-002-layered-feature-architecture.md)
|
|
||||||
- [ADR-003](adr/ADR-003-import-boundaries-and-dependency-direction.md)
|
|
||||||
- [ADR-004](adr/ADR-004-configuration-bootstrap-and-provider-abstraction.md)
|
|
||||||
- [ADR-005](adr/ADR-005-dynamic-page-section-widget-rendering.md)
|
|
||||||
- [ADR-006](adr/ADR-006-ui-component-purity-and-container-facade-pattern.md)
|
|
||||||
- [ADR-007](adr/ADR-007-state-management-and-facade-boundaries.md)
|
|
||||||
- [ADR-008](adr/ADR-008-theme-engine-and-design-token-runtime.md)
|
|
||||||
- [ADR-009](adr/ADR-009-feature-flags-and-capability-guards.md)
|
|
||||||
- [ADR-010](adr/ADR-010-backward-compatibility-for-auth-payment-authorization.md)
|
|
||||||
- [ADR-011](adr/ADR-011-optional-seller-management-module.md)
|
|
||||||
|
|
||||||
### Seller Management (optional, in preparation — not built)
|
|
||||||
|
|
||||||
- [Seller-Management.md](Seller-Management.md) — capability overview, start here
|
|
||||||
- [ADR-011](adr/ADR-011-optional-seller-management-module.md) — decision record
|
|
||||||
- [Seller-Management-Diagrams.md](Seller-Management-Diagrams.md) — hierarchy, bootstrap gate, type diagram
|
|
||||||
- [Seller-Management-Domain-Models.md](Seller-Management-Domain-Models.md) — typed models, optional sellerId fields
|
|
||||||
- [Seller-Management-UX-Review.md](Seller-Management-UX-Review.md) — UX/accessibility review of the Phase 1 UI
|
|
||||||
- [Seller-Management-Backoffice-Readiness-Audit.md](Seller-Management-Backoffice-Readiness-Audit.md) — per-module scoping/permissions readiness audit
|
|
||||||
- [Seller-Management-Storefront-Audit.md](Seller-Management-Storefront-Audit.md) — `market.com`/`seller.market.com` storefront readiness audit
|
|
||||||
- [Seller-Management-Backend-Migration-Plan.md](Seller-Management-Backend-Migration-Plan.md) — full backend migration plan, module-by-module, phased
|
|
||||||
- [Seller-Management-Final-Design-Review.md](Seller-Management-Final-Design-Review.md) — principal-architect review, findings, verdict
|
|
||||||
|
|
||||||
### Engineering Rule Documents
|
|
||||||
|
|
||||||
- [Folder Blueprint](Folder-Blueprint.md)
|
|
||||||
- [Import Boundary Matrix](Import-Boundary-Matrix.md)
|
|
||||||
- [Dependency Rules](Dependency-Rules.md)
|
|
||||||
- [Naming Conventions](Naming-Conventions.md)
|
|
||||||
- [Coding Standards](Coding-Standards.md)
|
|
||||||
- [Component Standards](Component-Standards.md)
|
|
||||||
- [Service Standards](Service-Standards.md)
|
|
||||||
- [Configuration Standards](Configuration-Standards.md)
|
|
||||||
- [State Management Standards](State-Management-Standards.md)
|
|
||||||
|
|
||||||
## Compliance
|
|
||||||
|
|
||||||
All new work must comply with this foundation.
|
|
||||||
If an implementation conflicts with these rules, implementation must be adjusted.
|
|
||||||
If a rule must change, an ADR update is required first.
|
|
||||||
|
|
||||||
## Sprint 11.5 Standardization Audit (2026-07-09)
|
|
||||||
|
|
||||||
Platform-wide standardization was executed before Admin Platform work.
|
|
||||||
|
|
||||||
### Completed Standardization
|
|
||||||
|
|
||||||
- Verified and enforced container/facade/domain/infrastructure boundaries across active website features.
|
|
||||||
- Removed remaining legacy variant naming in application-layer templates/styles.
|
|
||||||
- Removed duplicate legacy search-history implementation in catalog feature module.
|
|
||||||
- Standardized design-token surface with explicit spacing, radius, shadow, and transition tokens.
|
|
||||||
- Added widget metadata support for title/subtitle/visibility/layout/animation/style/permissions in shared contracts and dynamic rendering path.
|
|
||||||
- Converted remaining identified hardcoded UI strings in audited runtime pages/components to translation keys.
|
|
||||||
|
|
||||||
### Bootstrap/Configuration Gaps Identified
|
|
||||||
|
|
||||||
- Widget permission model supports auth gating but role/permission enforcement is limited by current auth session shape (no role list in session model).
|
|
||||||
- Popular search defaults are currently facade-local and should be moved to bootstrap-configurable catalog search settings.
|
|
||||||
- Storage key naming conventions for local persistence are platform-scoped but still static constants; optional bootstrap override could improve tenant isolation.
|
|
||||||
|
|
||||||
### Validation Baseline
|
|
||||||
|
|
||||||
- Build and architecture checks are required for acceptance of this sprint.
|
|
||||||
- Final details and file-level changes are tracked in `Platform-Standardization-Report.md`.
|
|
||||||
|
|
||||||
## Mandatory Phase Order
|
|
||||||
|
|
||||||
Implementation must proceed only in this order:
|
|
||||||
|
|
||||||
1. Foundation structure only, app compiles.
|
|
||||||
2. Shared interfaces and types only.
|
|
||||||
3. Mocked configuration payloads only.
|
|
||||||
4. ConfigService abstraction only.
|
|
||||||
5. Theme engine.
|
|
||||||
6. Dynamic rendering engine.
|
|
||||||
7. Reusable widget library.
|
|
||||||
8. Website from configuration.
|
|
||||||
9. Builder from configuration domain.
|
|
||||||
10. Backoffice from business domain.
|
|
||||||
11. Backend documentation.
|
|
||||||
|
|
||||||
For each phase:
|
|
||||||
|
|
||||||
1. Explain what will be created.
|
|
||||||
2. Explain why.
|
|
||||||
3. List files to create.
|
|
||||||
4. Explain dependencies.
|
|
||||||
5. Implement only that phase.
|
|
||||||
6. Verify build integrity.
|
|
||||||
7. Stop and wait.
|
|
||||||
@@ -1,567 +0,0 @@
|
|||||||
# Seller Management — Backend Migration Plan
|
|
||||||
|
|
||||||
Documentation only. No code, no implementation. This plan synthesizes the
|
|
||||||
three prior audits — do not re-derive facts already established there,
|
|
||||||
read them for detail:
|
|
||||||
|
|
||||||
- [Seller-Management.md](Seller-Management.md) — capability overview,
|
|
||||||
Implemented/Planned/Future legend
|
|
||||||
- [Seller-Management-Backoffice-Readiness-Audit.md](Seller-Management-Backoffice-Readiness-Audit.md)
|
|
||||||
— per-admin-module scoping facts
|
|
||||||
- [Seller-Management-Storefront-Audit.md](Seller-Management-Storefront-Audit.md)
|
|
||||||
— storefront/subdomain facts
|
|
||||||
- `BACKEND.md` §11 — the backend documentation this plan assumes as its
|
|
||||||
starting contract
|
|
||||||
|
|
||||||
**Non-negotiable constraint repeated from the mission, and load-bearing for
|
|
||||||
every classification below:** existing marketplaces without sellers must
|
|
||||||
continue working exactly as today. Seller Management stays optional
|
|
||||||
forever, not just at launch. No endpoint may require seller support unless
|
|
||||||
`modules.sellerManagement.enabled` is true. Every classification and every
|
|
||||||
migration strategy in this document is written to satisfy that constraint
|
|
||||||
first — where a module can't satisfy it without a structural rework, that's
|
|
||||||
called out explicitly, not glossed over.
|
|
||||||
|
|
||||||
## Endpoint classification legend
|
|
||||||
|
|
||||||
- **No change** — endpoint's request/response/behavior is untouched.
|
|
||||||
- **Minor change** — an optional field/parameter added (e.g. `sellerId?` in
|
|
||||||
a filters object or DTO); absent value behaves identically to today.
|
|
||||||
- **Major change** — data model or endpoint semantics change beyond an
|
|
||||||
optional field (e.g. a new join, a new required decision like split
|
|
||||||
orders, a new aggregation dimension).
|
|
||||||
- **New endpoint** — doesn't exist today, net-new surface.
|
|
||||||
|
|
||||||
## Module-by-module
|
|
||||||
|
|
||||||
### Authentication
|
|
||||||
- **Current:** Two live mechanisms (`BACKEND.md` §4) — Telegram/QR
|
|
||||||
customer session login (live), Ed25519 admin challenge/response (built
|
|
||||||
client-side, not wired live). No seller concept in either.
|
|
||||||
- **Future:** `SellerPermissionRole` (`marketplaceOwner`/`seller`/
|
|
||||||
`sellerStaff`/`platformAdmin`) as a role a session can carry, and a
|
|
||||||
decision on whether Seller/Seller Staff authenticate via a third
|
|
||||||
mechanism or reuse Telegram/Ed25519 with a different claim.
|
|
||||||
- **Migration strategy:** additive only — a new optional claim/role field
|
|
||||||
on the existing JWT structure (§4 §3), never a new auth mechanism forced
|
|
||||||
onto existing flows. Existing customer and admin login must not gain any
|
|
||||||
new required step.
|
|
||||||
- **Backward compatibility:** total, if done as an additive claim. A
|
|
||||||
session with no seller claim today is indistinguishable from a session
|
|
||||||
before this work existed.
|
|
||||||
- **Risk:** **Medium** — auth is the most consequence-sensitive surface in
|
|
||||||
the app (ADR-010 froze it once already); any change here needs
|
|
||||||
security review, not just a schema add.
|
|
||||||
- **Effort:** Medium (claim/role addition) once the role-vs-`AdminRole`
|
|
||||||
reconciliation decision (§11.4) is made; that decision itself is the
|
|
||||||
bigger unknown, not the wiring.
|
|
||||||
- **Endpoint classification:** existing login/verify/refresh/logout —
|
|
||||||
**Minor change** (optional claim), contingent on the role decision above.
|
|
||||||
New seller-specific login/enrollment flow (if Seller/Seller Staff need
|
|
||||||
one) — **New endpoint**, Future, not designed.
|
|
||||||
|
|
||||||
### Authorization
|
|
||||||
- **Current:** Coarse `AdminRole` (Owner/Manager/Support/ReadOnly) mapped
|
|
||||||
to `backoffice.read`/`backoffice.write`/`builder.read`/`builder.write`/
|
|
||||||
`settings.manage` (§4 §9.1). No route currently enforces even this — the
|
|
||||||
admin role model exists but nothing gates on it yet (confirmed by the
|
|
||||||
Backoffice audit: "no admin module anywhere does role-based hiding of
|
|
||||||
buttons or data today").
|
|
||||||
- **Future:** `SellerPermissionRole` layered in, deciding whether it
|
|
||||||
extends or sits alongside `AdminRole`.
|
|
||||||
- **Migration strategy:** since authorization enforcement doesn't exist yet
|
|
||||||
even for the current roles, there is no existing enforcement to break —
|
|
||||||
this is genuinely additive design space, not a migration of live
|
|
||||||
behavior.
|
|
||||||
- **Backward compatibility:** trivial today (nothing to preserve because
|
|
||||||
nothing enforces roles yet) but becomes a real compatibility question the
|
|
||||||
moment `AdminRole` enforcement is eventually added — sequence matters:
|
|
||||||
whichever role model ships first should be designed with the other in
|
|
||||||
mind, or the second one becomes a breaking migration of the first.
|
|
||||||
- **Risk:** **Low today, Medium if sequenced wrong** — the risk is entirely
|
|
||||||
about doing `AdminRole` enforcement and `SellerPermissionRole` design in
|
|
||||||
the wrong order, not about either individually.
|
|
||||||
- **Effort:** Low to design (no live behavior to preserve); Medium to
|
|
||||||
implement once both role systems' relationship is decided.
|
|
||||||
- **Endpoint classification:** all admin endpoints — **No change** today
|
|
||||||
(no enforcement exists to change); **Major change** whenever
|
|
||||||
role-enforcement is added generally, seller-aware or not.
|
|
||||||
|
|
||||||
### Bootstrap
|
|
||||||
- **Current:** `GET /bootstrap`, backend resolves tenant by Host (ADR-001,
|
|
||||||
§1). `BootstrapConfig` already has optional `modules?`/`seller?` fields
|
|
||||||
(§11.6), always absent/false — no backend populates them.
|
|
||||||
- **Future:** backend resolving `{seller}.{marketplace-domain}` (§11.5) and
|
|
||||||
populating `modules.sellerManagement.enabled` + `seller` for a real
|
|
||||||
seller-scoped request.
|
|
||||||
- **Migration strategy:** the fields already exist and are optional — the
|
|
||||||
only backend work is *populating* them correctly for a resolved seller
|
|
||||||
scope, not adding new frontend-facing shape. Existing marketplaces'
|
|
||||||
bootstrap responses need zero changes; they simply never populate the
|
|
||||||
new fields.
|
|
||||||
- **Backward compatibility:** already verified — these are optional fields
|
|
||||||
added to a live contract with zero consumer changes required (confirmed
|
|
||||||
`tsc --noEmit` clean at the time they were added).
|
|
||||||
- **Risk:** **Low** — this is the best-prepared module in the whole
|
|
||||||
migration, precisely because the frontend contract was already extended
|
|
||||||
in advance without needing backend cooperation.
|
|
||||||
- **Effort:** Medium — the resolution logic (subdomain → seller lookup) is
|
|
||||||
new backend work, but the response shape is already spoken for.
|
|
||||||
- **Endpoint classification:** `GET /bootstrap` — **Minor change** (two new
|
|
||||||
optional response fields to populate, conditionally).
|
|
||||||
|
|
||||||
### Products
|
|
||||||
- **Current:** No real backend yet (§8) — mock gateway. `AdminProductListFilters`
|
|
||||||
already has `search/categoryId/visibility/stock/includeArchived/sort/page/pageSize`.
|
|
||||||
`Item`/`AdminProduct` already carry optional `sellerId?` (§11.8),
|
|
||||||
read/written by nobody today.
|
|
||||||
- **Future:** `sellerId` filter on list endpoints; ownership enforcement on
|
|
||||||
create/update/delete once a real seller session exists.
|
|
||||||
- **Migration strategy:** add `sellerId` as one more optional field to the
|
|
||||||
existing filters object and DTOs — the field already exists in the
|
|
||||||
frontend type, so there's no frontend change required at all, only
|
|
||||||
backend query logic (`WHERE seller_id = ? OR seller_id IS NULL` pattern
|
|
||||||
or equivalent) gated behind the feature flag.
|
|
||||||
- **Backward compatibility:** guaranteed at the frontend type level
|
|
||||||
already; backend guarantee depends on making the new column/filter
|
|
||||||
nullable and defaulting existing rows to `NULL` (marketplace-owned) —
|
|
||||||
see Database changes below.
|
|
||||||
- **Risk:** **Low** for the filter addition; **Medium** for ownership
|
|
||||||
*enforcement* (a bug here could hide a marketplace owner's own products
|
|
||||||
from themselves, or leak a seller's products to another seller).
|
|
||||||
- **Effort:** Small (list/filter) once the DI-token seam this domain
|
|
||||||
currently lacks (per Backoffice audit) is added — that seam is
|
|
||||||
independent prerequisite work, not seller-specific.
|
|
||||||
- **Endpoint classification:** list/get — **Minor change**. Create/update
|
|
||||||
(ownership assignment) — **Minor change** if `sellerId` is just an
|
|
||||||
optional write field; **Major change** if ownership transfer or
|
|
||||||
seller-side write restrictions are added.
|
|
||||||
|
|
||||||
### Categories
|
|
||||||
- **Current:** The most backend-mature domain — real HTTP already
|
|
||||||
(`AdminCategoriesApiGateway`, DI-token-bound, §3.2). Facade currently
|
|
||||||
hardcodes a full unfiltered fetch and does all real filtering
|
|
||||||
client-side to preserve tree parent/child chains (Backoffice audit
|
|
||||||
finding).
|
|
||||||
- **Future:** categories are conceptually marketplace-wide (shared
|
|
||||||
taxonomy) — the real future question is scoping *products within* a
|
|
||||||
category by seller, not scoping categories themselves.
|
|
||||||
- **Migration strategy:** likely **no backend change at all** for
|
|
||||||
Categories proper; ownership scoping happens one level down, at Products.
|
|
||||||
- **Backward compatibility:** trivial — no change anticipated.
|
|
||||||
- **Risk:** **Low.**
|
|
||||||
- **Effort:** Low (frontend-only fix: the facade's hardcoded full-fetch
|
|
||||||
pattern, unrelated to backend).
|
|
||||||
- **Endpoint classification:** **No change** anticipated.
|
|
||||||
|
|
||||||
### Orders
|
|
||||||
- **Current:** `AdminOrderListFilters` has `search/status/page/pageSize`;
|
|
||||||
`AdminOrder` has optional `sellerId?` (§11.8) at the order level.
|
|
||||||
`AdminOrderItem` (per-line-item) has **no seller attribution field at
|
|
||||||
all** — the concrete gap behind Checkout Modes (§11.7).
|
|
||||||
- **Future:** per-item seller attribution, plus the Unified-vs-Split-Orders
|
|
||||||
decision (§11.7) — the single most consequential undecided item in this
|
|
||||||
entire plan.
|
|
||||||
- **Migration strategy:** cannot be resolved by an additive field alone.
|
|
||||||
**Unified Order** path: add optional `sellerId` to each order-item row
|
|
||||||
(minor, additive). **Split Orders** path: checkout must decide, at
|
|
||||||
creation time, whether to write N order records instead of one for a
|
|
||||||
multi-seller cart — that changes `POST /orders`' semantics for any cart
|
|
||||||
containing mixed-seller items, which is a **major** change regardless of
|
|
||||||
how carefully it's gated, because "how many order records does this
|
|
||||||
checkout produce" is not optional-field-shaped.
|
|
||||||
- **Backward compatibility:** guaranteed for any cart containing only
|
|
||||||
marketplace-owned items (the only kind that exists today) under either
|
|
||||||
path. The compatibility risk is entirely about *new* multi-seller carts,
|
|
||||||
which cannot exist until Products have real seller ownership — so there
|
|
||||||
is a natural sequencing safety net here, not just a promise.
|
|
||||||
- **Risk:** **High** — this is the highest-risk item in the whole plan.
|
|
||||||
Payments, refunds, and financial reporting all depend on the
|
|
||||||
Unified-vs-Split decision; getting it wrong after sellers exist means a
|
|
||||||
breaking change to live financial data, not a code refactor.
|
|
||||||
- **Effort:** Large — this decision should be made and locked before any
|
|
||||||
seller onboarding is possible, not discovered mid-rollout.
|
|
||||||
- **Endpoint classification:** `GET /orders` (list/filter) — **Minor
|
|
||||||
change**. `POST /orders` (create) — **Major change** (semantics change
|
|
||||||
based on the Unified/Split decision). `PATCH` status transitions — likely
|
|
||||||
**Minor change** if orders stay 1:1 with a single seller scope (Split
|
|
||||||
path) or **Major change** if partial per-seller status exists within one
|
|
||||||
unified order.
|
|
||||||
|
|
||||||
### Payments
|
|
||||||
- **Current:** **Frozen** (ADR-010) — Telegram QR/card payment flow,
|
|
||||||
`POST /cart` (`CartPaymentRequest` → `QrCreateResponse`), status polling.
|
|
||||||
Explicitly preserved unchanged through every prior platform-refactoring
|
|
||||||
pass in this codebase's history.
|
|
||||||
- **Future:** if Split Orders is chosen (§ Orders above), a single checkout
|
|
||||||
may need to create multiple payment records or split a captured payment
|
|
||||||
across sellers — a genuinely new payment-flow shape, not a parameter
|
|
||||||
addition.
|
|
||||||
- **Migration strategy:** **do not touch the frozen flow for the Unified
|
|
||||||
Order path** — a unified order with mixed-seller items can still use
|
|
||||||
today's exact single-payment flow, only the *order* record differs
|
|
||||||
internally. Only the Split Orders path forces any payment-flow change,
|
|
||||||
and even then, the existing flow should remain the path for
|
|
||||||
seller-disabled marketplaces with zero exceptions.
|
|
||||||
- **Backward compatibility:** absolute requirement, restated from ADR-010 —
|
|
||||||
this is the one area of the whole codebase with an explicit prior
|
|
||||||
"freeze, do not redesign" decision, and Seller Management does not
|
|
||||||
override it.
|
|
||||||
- **Risk:** **High** if Split Orders is chosen — payment/financial flows
|
|
||||||
are the least forgiving place for a design misstep in this entire system.
|
|
||||||
- **Effort:** Large, only if Split Orders is chosen; **zero** for Unified
|
|
||||||
Order.
|
|
||||||
- **Endpoint classification:** **No change** under Unified Order. **Major
|
|
||||||
change or New endpoint** under Split Orders (undecided, Future).
|
|
||||||
|
|
||||||
### Transactions
|
|
||||||
- **Current:** Derived entirely from the same unscoped Orders list
|
|
||||||
(`AdminTransactionsLocalGateway` mirrors `AdminOrdersLocalGateway`'s
|
|
||||||
pattern, Backoffice audit finding). `AdminTransactionListFilters` has
|
|
||||||
`search/status/type/page/pageSize`.
|
|
||||||
- **Future:** per-seller transaction filtering/reporting.
|
|
||||||
- **Migration strategy:** inherits whatever Orders decides — Transactions
|
|
||||||
cannot be scoped correctly until Orders resolves per-item seller
|
|
||||||
attribution (§ Orders above). Adding a `sellerId` filter here today would
|
|
||||||
be cosmetic without that prerequisite.
|
|
||||||
- **Backward compatibility:** same guarantee as Orders — blocked on the
|
|
||||||
same prerequisite, not an independent risk.
|
|
||||||
- **Risk:** **Medium** — inherits Orders' risk one level removed (financial
|
|
||||||
reporting, not the payment flow itself).
|
|
||||||
- **Effort:** Small once Orders is resolved; not independently schedulable
|
|
||||||
before that.
|
|
||||||
- **Endpoint classification:** **Minor change** (filter field), contingent
|
|
||||||
on Orders' Major change landing first.
|
|
||||||
|
|
||||||
### Reviews
|
|
||||||
- **Current:** Storefront submission is live; admin moderation
|
|
||||||
(`AdminModerationGateway`) is mock-only. `AdminReviewListFilters` has
|
|
||||||
`search/status/rating/page/pageSize`. Reviews carry `productId` — no
|
|
||||||
direct seller field.
|
|
||||||
- **Future:** a seller sees reviews on their own products, via a join
|
|
||||||
through Products' `sellerId`, not a new field on the review itself.
|
|
||||||
- **Migration strategy:** add `sellerId` as a filter that internally joins
|
|
||||||
through the product's ownership — additive at the API surface, but
|
|
||||||
implemented as a join, not a stored column on reviews.
|
|
||||||
- **Backward compatibility:** total — the filter is purely additive and
|
|
||||||
optional.
|
|
||||||
- **Risk:** **Low.**
|
|
||||||
- **Effort:** Small, contingent on Products having real `sellerId` data to
|
|
||||||
join against.
|
|
||||||
- **Endpoint classification:** review list/detail — **Minor change**.
|
|
||||||
Reports (`loadReports()`, currently bare no-arg, no filters object at
|
|
||||||
all) — **Minor change** too, but requires adding a filters parameter
|
|
||||||
that doesn't exist on the endpoint today, so slightly more surface than
|
|
||||||
the reviews list.
|
|
||||||
|
|
||||||
### Analytics
|
|
||||||
- **Current:** No aggregation endpoint exists at all (§3.20) — every
|
|
||||||
number (revenue, top products, health, recommendations) is computed
|
|
||||||
client-side by summing the *entire* orders/products/categories/reviews
|
|
||||||
corpus. This gap exists independent of Seller Management.
|
|
||||||
- **Future:** per-seller analytics, requiring the underlying domains
|
|
||||||
(Orders, Products, Reviews) to be seller-scoped first, then a real
|
|
||||||
aggregation endpoint partitioned by seller.
|
|
||||||
- **Migration strategy:** do not attempt to seller-scope analytics before
|
|
||||||
a real aggregation endpoint exists for the marketplace as a whole — that
|
|
||||||
is a prerequisite gap, not a Seller Management task. Once it exists,
|
|
||||||
seller-partitioning is an additional dimension on the same aggregation
|
|
||||||
query, not a new endpoint family.
|
|
||||||
- **Backward compatibility:** unaffected — a marketplace with no sellers
|
|
||||||
gets marketplace-wide aggregates exactly as it always has, whenever the
|
|
||||||
real aggregation endpoint is eventually built.
|
|
||||||
- **Risk:** **Medium** — mostly the risk of building the wrong aggregation
|
|
||||||
shape before seller-partitioning is even a consideration, and having to
|
|
||||||
redo it.
|
|
||||||
- **Effort:** Large — this is explicitly the last domain recommended for
|
|
||||||
real backend work in `BACKEND.md` §9, and Seller Management adds a
|
|
||||||
further dimension on top of an already-large lift.
|
|
||||||
- **Endpoint classification:** **New endpoint** (the aggregation endpoint
|
|
||||||
itself doesn't exist yet, seller-aware or not).
|
|
||||||
|
|
||||||
### Media
|
|
||||||
- **Current:** `MediaRepository` abstract class, DI-token-bound already
|
|
||||||
(mock live, `ApiMediaRepository` not yet written). `MediaListParams`
|
|
||||||
already accepts `page/pageSize/search/folder/kind/sort`. `MediaAsset` has
|
|
||||||
no owner/uploader field at all.
|
|
||||||
- **Future:** `sellerId` filter, requiring an owner field added to
|
|
||||||
`MediaAsset` first.
|
|
||||||
- **Migration strategy:** two small additive changes — a new optional
|
|
||||||
`sellerId`/`ownerId` field on the asset model, and a matching optional
|
|
||||||
filter field on `MediaListParams`. This module and Categories are the
|
|
||||||
two best-positioned in the entire audit for a low-risk addition.
|
|
||||||
- **Backward compatibility:** total — both changes are optional-field
|
|
||||||
additions to an already-flexible params object.
|
|
||||||
- **Risk:** **Low.**
|
|
||||||
- **Effort:** Small.
|
|
||||||
- **Endpoint classification:** list — **Minor change**. Upload/update
|
|
||||||
(§7) — **Minor change** (one new optional field in the request body).
|
|
||||||
|
|
||||||
### Search
|
|
||||||
- **Current:** Standard search contract exists (§2.5) as a framework
|
|
||||||
convention (keyword, no dedicated backend endpoint beyond catalog list
|
|
||||||
filtering — `/search` reuses the same catalog container/endpoint as
|
|
||||||
`/catalog` per the Storefront audit). No autocomplete/trending endpoint
|
|
||||||
exists; explicitly flagged as its own open "Requires backend decision"
|
|
||||||
in §2.12.
|
|
||||||
- **Future:** filtering search results by seller scope, same mechanism as
|
|
||||||
Products (search is not architecturally distinct from catalog browsing
|
|
||||||
today).
|
|
||||||
- **Migration strategy:** inherits Products' migration entirely — no
|
|
||||||
separate search-specific backend work anticipated beyond what Products
|
|
||||||
already needs.
|
|
||||||
- **Backward compatibility:** total, same guarantee as Products.
|
|
||||||
- **Risk:** **Low.**
|
|
||||||
- **Effort:** None beyond Products — not independently schedulable.
|
|
||||||
- **Endpoint classification:** **Minor change**, identical to Products'
|
|
||||||
classification (same underlying endpoint).
|
|
||||||
|
|
||||||
### CMS (Static Pages)
|
|
||||||
- **Current:** No backend call at all — reads/writes
|
|
||||||
`BootstrapConfig.staticPages` in-memory (§1, §3.8). Marketplace-wide
|
|
||||||
content (legal, about) by nature.
|
|
||||||
- **Future:** **conceptually does not apply** — no per-seller static page
|
|
||||||
concept exists in this document or in product intent. If sellers ever
|
|
||||||
need their own content pages, that is new product surface, not an
|
|
||||||
extension of this module.
|
|
||||||
- **Migration strategy:** none anticipated. Flag if product strategy later
|
|
||||||
decides otherwise — treat as a new capability, not a CMS migration.
|
|
||||||
- **Backward compatibility:** unaffected — no change proposed.
|
|
||||||
- **Risk:** **None.**
|
|
||||||
- **Effort:** **None.**
|
|
||||||
- **Endpoint classification:** **No change.**
|
|
||||||
|
|
||||||
### Builder
|
|
||||||
- **Current:** No backend write path at all (§1.10, §8) — draft/publish is
|
|
||||||
`localStorage`-only, editing one global `BootstrapConfig` document per
|
|
||||||
marketplace. The single strongest one-owner assumption in the codebase
|
|
||||||
(Backoffice audit finding).
|
|
||||||
- **Future:** a seller-scoped builder (per-seller storefront layout/
|
|
||||||
branding) would be an entirely new product surface built on a different
|
|
||||||
premise than "one config document per marketplace" — not an extension of
|
|
||||||
the existing builder.
|
|
||||||
- **Migration strategy:** none proposed for the existing Builder. If a
|
|
||||||
seller-facing builder is ever wanted, it should be scoped as its own ADR
|
|
||||||
and its own backend surface, not bolted onto the marketplace Builder's
|
|
||||||
existing draft/publish contract.
|
|
||||||
- **Backward compatibility:** unaffected — no change proposed to the
|
|
||||||
existing module.
|
|
||||||
- **Risk:** **None** for the existing module; **High** if a future team
|
|
||||||
attempts to retrofit seller-awareness into the existing single-document
|
|
||||||
model rather than building fresh — flagged explicitly as an
|
|
||||||
anti-pattern to avoid.
|
|
||||||
- **Effort:** **None** now; a seller-facing builder, if ever built, is a
|
|
||||||
large, independent effort, not a migration of this one.
|
|
||||||
- **Endpoint classification:** **No change** to the existing (still
|
|
||||||
nonexistent) builder write path. Any future seller-builder surface is
|
|
||||||
**New endpoint**, Future, not designed.
|
|
||||||
|
|
||||||
### Settings
|
|
||||||
- **Current:** No route exists — `comingSoon: true` in the admin nav, no
|
|
||||||
component backs it (confirmed, Backoffice audit).
|
|
||||||
- **Future:** if Settings is ever built, it's the natural home for
|
|
||||||
marketplace-level Seller Management configuration (e.g. enabling the
|
|
||||||
module, default seller policies) — speculative, not designed.
|
|
||||||
- **Migration strategy:** none — there's nothing to migrate.
|
|
||||||
- **Backward compatibility:** not applicable.
|
|
||||||
- **Risk:** **None.**
|
|
||||||
- **Effort:** **None** attributable to Seller Management specifically.
|
|
||||||
- **Endpoint classification:** **No change** — no endpoint exists.
|
|
||||||
|
|
||||||
### Notifications
|
|
||||||
- **Current:** A marketplace-facing feature flag exists
|
|
||||||
(`FeatureFlagsConfig.notifications: boolean`) but this gates a storefront
|
|
||||||
UI feature, not a backend notification/email service — no such service
|
|
||||||
exists in this codebase for anyone today.
|
|
||||||
- **Future:** seller onboarding (invitation accepted, application
|
|
||||||
approved/rejected) would need real notification delivery — entirely
|
|
||||||
net-new, not an extension of the existing flag.
|
|
||||||
- **Migration strategy:** none — nothing exists to migrate.
|
|
||||||
- **Backward compatibility:** not applicable.
|
|
||||||
- **Risk:** **Low** (net-new work carries normal build risk, not migration
|
|
||||||
risk).
|
|
||||||
- **Effort:** Medium, whenever built — but zero today and not a
|
|
||||||
prerequisite for anything else in this plan.
|
|
||||||
- **Endpoint classification:** **New endpoint**, Future, not designed.
|
|
||||||
|
|
||||||
### Emails
|
|
||||||
- **Current:** No email-sending capability exists anywhere in this
|
|
||||||
codebase.
|
|
||||||
- **Future:** the mocked "Request Access" form on the Phase 1 UI
|
|
||||||
(`admin-seller-management-page.component.ts`) implies a real email would
|
|
||||||
eventually be sent on submission — today it's a `setTimeout`-mocked
|
|
||||||
success dialog with zero delivery.
|
|
||||||
- **Migration strategy:** none — nothing exists to migrate.
|
|
||||||
- **Backward compatibility:** not applicable.
|
|
||||||
- **Risk:** **Low** (net-new, not migration).
|
|
||||||
- **Effort:** Small to Medium, whenever built (transactional email for one
|
|
||||||
form submission is a contained scope).
|
|
||||||
- **Endpoint classification:** **New endpoint**, Future, not designed.
|
|
||||||
|
|
||||||
### Audit Logs
|
|
||||||
- **Current:** Documented in `BACKEND.md` §5.14 as a proposed convention
|
|
||||||
(structured audit-log entries with actor/action/target/timestamp) — no
|
|
||||||
backend implementation confirmed to exist; this is itself already
|
|
||||||
Planned/Future in the base backend doc, independent of Seller
|
|
||||||
Management.
|
|
||||||
- **Future:** any seller-specific action (seller created, activated,
|
|
||||||
suspended, branding changed) should flow through the same audit-log
|
|
||||||
convention once it exists, with an added seller-scope dimension on the
|
|
||||||
log entry — not a parallel logging system.
|
|
||||||
- **Migration strategy:** none specific to Seller Management beyond
|
|
||||||
ensuring, whenever audit logging is built, that its schema includes an
|
|
||||||
optional seller-scope field from day one rather than retrofitting it
|
|
||||||
later.
|
|
||||||
- **Backward compatibility:** not applicable — nothing exists yet to
|
|
||||||
preserve.
|
|
||||||
- **Risk:** **Low.**
|
|
||||||
- **Effort:** None additional if sequenced correctly (add the field when
|
|
||||||
audit logging is first built); Medium if audit logging ships first
|
|
||||||
without it and needs a schema migration later.
|
|
||||||
- **Endpoint classification:** **New endpoint** (audit log query surface,
|
|
||||||
if one is ever exposed to admins) — Future, not designed.
|
|
||||||
|
|
||||||
## Database changes
|
|
||||||
|
|
||||||
No schema exists yet for any of this (§8 — no backend implemented at all).
|
|
||||||
Recommendations, not decisions:
|
|
||||||
|
|
||||||
- A `sellers` table (id, marketplace_id, name, slug, status, branding
|
|
||||||
JSON/columns, timestamps) — new table, no impact on existing schema.
|
|
||||||
- A nullable `seller_id` foreign key on `products`/`items` and `orders` (or
|
|
||||||
order-items, pending the Unified/Split decision) — nullable by
|
|
||||||
design, defaulting existing rows to `NULL` (marketplace-owned). This is
|
|
||||||
the one schema change that touches existing tables; every other addition
|
|
||||||
is a new table.
|
|
||||||
- A nullable `seller_id`/`owner_id` on the media-assets table, if Media
|
|
||||||
ownership scoping is pursued.
|
|
||||||
- No column should ever be added as `NOT NULL` without a default — that
|
|
||||||
would force a backfill migration on existing data, which this plan's
|
|
||||||
constraint explicitly rules out.
|
|
||||||
|
|
||||||
## Permission changes
|
|
||||||
|
|
||||||
- New `sellers` and `seller_users` (or equivalent) authorization checks —
|
|
||||||
entirely new policy, not a modification of existing `AdminRole` checks
|
|
||||||
(which, per the Backoffice audit, don't enforce anything yet regardless).
|
|
||||||
- Existing admin/customer authorization paths: **no change** required for
|
|
||||||
marketplaces with `modules.sellerManagement.enabled = false`.
|
|
||||||
- Recommendation: implement seller-scoped authorization as an additional
|
|
||||||
policy layer evaluated only when a request resolves to a seller scope
|
|
||||||
(§11.5) — never as a modification of the existing marketplace-level
|
|
||||||
policy evaluation path.
|
|
||||||
|
|
||||||
## Caching
|
|
||||||
|
|
||||||
- Bootstrap responses are already cached client-side per tenant (§1.7); a
|
|
||||||
seller-scoped bootstrap response should be cached under a cache key that
|
|
||||||
includes the resolved seller identity (e.g. keyed by full resolved Host,
|
|
||||||
which it already effectively is), not the marketplace alone — otherwise
|
|
||||||
a seller subdomain risks serving a cached marketplace-level response or
|
|
||||||
vice versa.
|
|
||||||
- No existing cache invalidation logic needs to change for marketplaces
|
|
||||||
without sellers.
|
|
||||||
|
|
||||||
## Indexes
|
|
||||||
|
|
||||||
- `sellers(marketplace_id)` — every seller lookup is scoped by marketplace.
|
|
||||||
- `products(seller_id)` / `orders(seller_id)` (or order-items equivalent)
|
|
||||||
— nullable-column indexes; most databases index `NULL` efficiently, but
|
|
||||||
this should be verified against the chosen database engine before
|
|
||||||
assuming query performance is unaffected for the common (`NULL`) case.
|
|
||||||
- No index changes required on any table for marketplaces that never
|
|
||||||
populate `seller_id`.
|
|
||||||
|
|
||||||
## Security
|
|
||||||
|
|
||||||
- Seller-scoped data access is a new cross-tenant-adjacent boundary (a
|
|
||||||
seller must never see another seller's data within the same
|
|
||||||
marketplace) — recommend treating this with the same rigor as tenant
|
|
||||||
isolation (§5.10/§4 §10), not as a lesser internal boundary.
|
|
||||||
- The existing frozen payment flow (ADR-010) must not be reopened for the
|
|
||||||
Unified Order path — only the Split Orders path (if chosen) touches
|
|
||||||
payment security surface at all, and that touch should get the same
|
|
||||||
security review rigor as the original payment implementation.
|
|
||||||
|
|
||||||
## Performance
|
|
||||||
|
|
||||||
- Analytics is already the heaviest computation path in the app (full
|
|
||||||
client-side aggregation over the entire corpus, §3.20) — building the
|
|
||||||
real aggregation endpoint this plan's Analytics section calls for should
|
|
||||||
happen with seller-partitioning in mind from the start, to avoid a
|
|
||||||
second heavy migration shortly after the first.
|
|
||||||
- No performance regression is anticipated for marketplaces without
|
|
||||||
sellers — every proposed change is either a new table/endpoint (zero
|
|
||||||
cost when unused) or a nullable-field filter (negligible cost when the
|
|
||||||
filter is never applied).
|
|
||||||
|
|
||||||
## API Versioning
|
|
||||||
|
|
||||||
Already documented as an open, undecided item in `BACKEND.md` §2.10 (no
|
|
||||||
path/header versioning scheme exists today). Recommendation specific to
|
|
||||||
this migration: whichever versioning decision is made generally should
|
|
||||||
land **before** any Seller Management endpoint ships, so new endpoints
|
|
||||||
(Seller CRUD, Activation, Invitations, Branding, Analytics, Dashboard) are
|
|
||||||
versioned consistently with the rest of the API from their first day,
|
|
||||||
rather than being retrofitted later as the one inconsistent set.
|
|
||||||
|
|
||||||
## Migration order
|
|
||||||
|
|
||||||
Strict dependency order, not a preference:
|
|
||||||
|
|
||||||
1. **Bootstrap** (already prepared, lowest risk) — backend starts
|
|
||||||
populating `modules`/`seller` fields for a resolved seller scope.
|
|
||||||
2. **Products** — `seller_id` column + filter, the foundation every
|
|
||||||
downstream domain depends on.
|
|
||||||
3. **Categories** — confirm no change needed (likely true, low effort to
|
|
||||||
verify).
|
|
||||||
4. **Media** — independent, can happen in parallel with Products.
|
|
||||||
5. **Reviews** — depends on Products (join through product ownership).
|
|
||||||
6. **Orders** — the Unified-vs-Split-Orders decision must be made here,
|
|
||||||
informed by Products already existing. This is the hard gate — nothing
|
|
||||||
past this point should start before it's resolved.
|
|
||||||
7. **Payments** — only touched if Split Orders is chosen; otherwise
|
|
||||||
untouched, in parallel with everything above.
|
|
||||||
8. **Transactions** — depends on Orders.
|
|
||||||
9. **Analytics** — depends on Orders, Products, Reviews all being scoped;
|
|
||||||
also depends on the pre-existing (non-seller-specific) real aggregation
|
|
||||||
endpoint being built first.
|
|
||||||
10. **Authentication/Authorization** — the `SellerPermissionRole` design
|
|
||||||
and its relationship to `AdminRole` should be settled in parallel with
|
|
||||||
steps 2-6, not deferred to the end, since Seller Activation and any
|
|
||||||
real seller-facing endpoint depend on it.
|
|
||||||
11. **Seller CRUD/Activation/Invitations/Branding** — depends on
|
|
||||||
Authentication/Authorization being settled.
|
|
||||||
12. **Seller Dashboard/Analytics endpoints** — last, depends on Analytics'
|
|
||||||
real aggregation endpoint existing.
|
|
||||||
13. **Notifications/Emails/Audit Logs** — can start any time after step 11
|
|
||||||
(Seller Invitations existing gives them something to notify about);
|
|
||||||
not blocking anything else.
|
|
||||||
14. **CMS, Builder, Settings** — no migration anticipated; revisit only if
|
|
||||||
product strategy changes.
|
|
||||||
|
|
||||||
## Recommended implementation phases
|
|
||||||
|
|
||||||
- **Phase A — Foundation** (steps 1-4, 10 above): bootstrap population,
|
|
||||||
Products/Categories/Media scoping, and the permission-role design done
|
|
||||||
in parallel. Nothing customer-visible yet. Lowest risk, unblocks
|
|
||||||
everything else.
|
|
||||||
- **Phase B — The hard decision** (step 6, Orders): Unified-vs-Split-Orders
|
|
||||||
locked before any real seller can transact. This phase is a design
|
|
||||||
decision plus its implementation, not a feature — treat it as a gate,
|
|
||||||
not a sprint item.
|
|
||||||
- **Phase C — Dependent domains** (steps 5, 7, 8): Reviews, Payments (if
|
|
||||||
Split chosen), Transactions — mechanical once Phase B lands.
|
|
||||||
- **Phase D — Seller-facing surface** (step 11): Seller CRUD, Activation,
|
|
||||||
Invitations, Branding — the first point where a seller account can
|
|
||||||
actually exist and do something.
|
|
||||||
- **Phase E — Analytics & reporting** (steps 9, 12): the largest single
|
|
||||||
remaining lift, deliberately last since it depends on everything above.
|
|
||||||
- **Phase F — Operational polish** (step 13): Notifications, Emails, Audit
|
|
||||||
Logs — improves the experience of Phase D/E but blocks nothing.
|
|
||||||
|
|
||||||
At every phase boundary: re-verify the non-negotiable constraint. A
|
|
||||||
marketplace with `modules.sellerManagement.enabled = false` must show zero
|
|
||||||
behavioral difference before and after each phase ships. If a phase can't
|
|
||||||
satisfy that, it isn't ready to ship — regardless of how much of it is
|
|
||||||
"done."
|
|
||||||
@@ -1,319 +0,0 @@
|
|||||||
# Seller Management — Backoffice Readiness Audit
|
|
||||||
|
|
||||||
Audit only. **No code changed by this pass** — every fact below was gathered
|
|
||||||
by reading current source (facades, gateway interfaces, local
|
|
||||||
implementations, components) on `feature/seller-management-foundation`, not
|
|
||||||
inferred or assumed. Companion to
|
|
||||||
[Seller-Management.md](Seller-Management.md) §5 (Roles & Permissions) and §6
|
|
||||||
(Seller Ownership).
|
|
||||||
|
|
||||||
## How to read this
|
|
||||||
|
|
||||||
For each module: three readiness questions, then **where** a future scope
|
|
||||||
would be injected (not "if seller" conditionals — an injection point in an
|
|
||||||
existing method signature or facade call), then components that currently
|
|
||||||
assume there is exactly one owner of the whole dataset, then a
|
|
||||||
classification.
|
|
||||||
|
|
||||||
**Classification legend:**
|
|
||||||
- **Ready** — either already scope-injectable with no structural change, or
|
|
||||||
conceptually marketplace-wide data that a seller scope shouldn't apply to
|
|
||||||
at all.
|
|
||||||
- **Needs scope** — a filters object or DI-token seam already exists; adding
|
|
||||||
a scope field is additive, not structural.
|
|
||||||
- **Needs permissions** — the open question is *who sees this at all*
|
|
||||||
(Marketplace Owner vs Seller vs Seller Staff vs Platform Admin), not data
|
|
||||||
filtering.
|
|
||||||
- **Needs API change** — the method signature itself has no parameter to
|
|
||||||
extend (bare no-arg calls), the data model has no owner attribution field
|
|
||||||
to filter on, or the module's whole premise assumes one global record.
|
|
||||||
|
|
||||||
Repo-wide baseline established by this audit: **only Categories, Dashboard-
|
|
||||||
metrics, and Media have a DI-token-swappable gateway today** (per
|
|
||||||
`BACKEND.md` §8's pattern — interface + `*LocalGateway` + `*ApiGateway` +
|
|
||||||
`InjectionToken`). Every other admin domain's facade injects its
|
|
||||||
`*LocalGateway` concretely; that seam has to be added before any real
|
|
||||||
scoping work lands, independent of the scoping question itself. No module
|
|
||||||
currently does role-based hiding of any button or data — Users displays
|
|
||||||
role/permission *labels* only, nothing gates on them.
|
|
||||||
|
|
||||||
## Module-by-module
|
|
||||||
|
|
||||||
### Dashboard
|
|
||||||
- Owner sees everything? Yes — today's only mode.
|
|
||||||
- Seller sees only their own? Not possible today — `loadMetrics()` has no
|
|
||||||
parameters at all.
|
|
||||||
- Seller Staff limited? Undetermined — no permission model touches this yet.
|
|
||||||
- **Injection point:** `AdminDashboardMetricsGateway.loadMetrics()` would
|
|
||||||
need a new parameter (interface change, not a filters-object field —
|
|
||||||
there is no object to extend).
|
|
||||||
- **Assumes global ownership:** `admin-dashboard-metrics.local.gateway.ts`
|
|
||||||
computes `categoriesCount`/`productsCount` as raw `.length` over the
|
|
||||||
entire catalog.
|
|
||||||
- **Classification: Needs API change.**
|
|
||||||
|
|
||||||
### Products
|
|
||||||
- Owner sees everything? Yes.
|
|
||||||
- Seller sees only their own? Not yet, but the shape is close — filters
|
|
||||||
object already exists.
|
|
||||||
- Seller Staff limited? Undetermined.
|
|
||||||
- **Injection point:** `AdminProductListFilters` (already has
|
|
||||||
`search/categoryId/visibility/stock/includeArchived/sort/page/pageSize`)
|
|
||||||
— an optional `sellerId` field slots in next to the existing ones; one
|
|
||||||
more `.filter()` line in `AdminProductsLocalGateway`.
|
|
||||||
- **Assumes global ownership:** `loadDashboardStats()` calls
|
|
||||||
`loadProducts({page:1, pageSize:100000, includeArchived:true, ...})` to
|
|
||||||
sum stock/health stats with no per-seller split.
|
|
||||||
- **Classification: Needs scope** (small, once the DI-token seam this
|
|
||||||
module still lacks is added — see baseline note above).
|
|
||||||
|
|
||||||
### Categories
|
|
||||||
- Owner sees everything? Yes.
|
|
||||||
- Seller sees only their own? Categories are conceptually a **shared,
|
|
||||||
marketplace-wide taxonomy** — the real future question is "which products
|
|
||||||
in category X belong to seller Y," not "which categories belong to seller
|
|
||||||
Y." Likely Owner-only editable regardless of seller scope.
|
|
||||||
- Seller Staff limited? Undetermined.
|
|
||||||
- **Injection point:** `AdminCategoryListFilters` already has
|
|
||||||
`search/visibility/includeDeleted` and the gateway is already DI-token-
|
|
||||||
swappable (`ADMIN_CATEGORIES_GATEWAY`) — **but** the facade's `loadList()`
|
|
||||||
currently calls the gateway with a hardcoded
|
|
||||||
`{search:'', visibility:'all', includeDeleted:true}` and does all real
|
|
||||||
filtering client-side in `filteredCategories()`/`visibleTreeRows()` to
|
|
||||||
preserve tree parent/child chains. A `sellerId` filter passed to the
|
|
||||||
gateway would be silently bypassed unless this hardcoded call is updated
|
|
||||||
too.
|
|
||||||
- **Assumes global ownership:** `loadDashboardStats()` sums the whole
|
|
||||||
category tree.
|
|
||||||
- **Classification: Needs scope** — gateway/interface layer is Ready, the
|
|
||||||
facade's full-fetch-then-client-filter pattern is the actual gap.
|
|
||||||
|
|
||||||
### Orders
|
|
||||||
- Owner sees everything? Yes.
|
|
||||||
- Seller sees only their own? **Not modeled at all** — `AdminOrderItem` has
|
|
||||||
no seller/vendor attribution field; a multi-vendor order (one order,
|
|
||||||
items from several sellers) has no representation today. This is the
|
|
||||||
concrete blocker behind the Unified-vs-Split-Orders open question in
|
|
||||||
`Seller-Management.md` §6.
|
|
||||||
- Seller Staff limited? Undetermined.
|
|
||||||
- **Injection point:** `AdminOrderListFilters` has `search/status/page/
|
|
||||||
pageSize` — a `sellerId` field is syntactically cheap to add, but
|
|
||||||
filtering by it means nothing until orders/order-items carry seller
|
|
||||||
attribution in the data model.
|
|
||||||
- **Assumes global ownership:** `loadDashboardStats()` fetches
|
|
||||||
`pageSize:100000` and sums orders/revenue/customers globally; this same
|
|
||||||
full-fetch feeds Customers, Transactions, and Analytics (see below),
|
|
||||||
compounding the single-owner assumption across four modules.
|
|
||||||
- **Classification: Needs API change** — the data-model gap (per-item
|
|
||||||
seller attribution, unified-vs-split decision) is the real blocker, not
|
|
||||||
the filter object.
|
|
||||||
|
|
||||||
### Customers
|
|
||||||
- Owner sees everything? Yes.
|
|
||||||
- Seller sees only their own? Not possible today — "customer" is a
|
|
||||||
**derived aggregate** grouping the full order list by email in-memory;
|
|
||||||
there is no first-class Customers gateway to add a filter to at all.
|
|
||||||
- Seller Staff limited? Undetermined.
|
|
||||||
- **Injection point:** none exists yet. Either (a) derive from an
|
|
||||||
already-scoped Orders call once Orders itself supports `sellerId`, or (b)
|
|
||||||
introduce a first-class `AdminCustomersGateway` — `BACKEND.md` already
|
|
||||||
recommends the latter independent of Seller Management.
|
|
||||||
- **Assumes global ownership:** `buildCustomers()` groups the entire
|
|
||||||
unscoped order list; hardcoded `pageSize:100000` fetch, "search" is
|
|
||||||
client-side only.
|
|
||||||
- **Classification: Needs API change.**
|
|
||||||
|
|
||||||
### Users
|
|
||||||
- Owner sees everything? Yes.
|
|
||||||
- Seller sees only their own? Not modeled — `loadUsers()` is bare no-arg,
|
|
||||||
no filters object exists to extend.
|
|
||||||
- Seller Staff limited? **This is where the answer will actually live** —
|
|
||||||
`AdminUser` already carries an `AdminUserScope` field (`'marketplace' |
|
|
||||||
'office'` in seed data) and an `AdminRole` with a permission-array shape.
|
|
||||||
This is the closest existing hook to the future `SellerPermissionRole`
|
|
||||||
vocabulary (`marketplaceOwner`/`seller`/`sellerStaff`/`platformAdmin`,
|
|
||||||
`Seller-Management.md` §5) — but today it's used for labels only
|
|
||||||
(`roleLabel`/`permissionLabel` in the page component), nothing gates
|
|
||||||
actions or visibility on it anywhere in the app.
|
|
||||||
- **Injection point:** `loadUsers()` needs a parameter added (interface
|
|
||||||
change — no object to extend); `AdminUserScope` is the natural place a
|
|
||||||
seller-scope value would eventually live.
|
|
||||||
- **Assumes global ownership:** `loadAll()` fetches every user
|
|
||||||
unconditionally, no per-seller user set exists.
|
|
||||||
- **Classification: Needs API change** (data fetch) **+ Needs permissions**
|
|
||||||
(this module is the eventual home of the Marketplace Owner / Seller /
|
|
||||||
Seller Staff / Platform Admin distinction — right now it's purely
|
|
||||||
informational).
|
|
||||||
|
|
||||||
### Analytics
|
|
||||||
- Owner sees everything? Yes.
|
|
||||||
- Seller sees only their own? Not possible today — every number (revenue,
|
|
||||||
top products, health, recommendations) is summed across the *entire*
|
|
||||||
orders+products+categories+reviews corpus with no per-owner dimension
|
|
||||||
anywhere, and there's no gateway of its own to add a filter to (it
|
|
||||||
composes five other gateways/facades directly).
|
|
||||||
- Seller Staff limited? Undetermined.
|
|
||||||
- **Injection point:** none today — depends entirely on Orders/Products/
|
|
||||||
Categories/Moderation each supporting `sellerId` first, then every one of
|
|
||||||
this facade's ~6 nested subscribe calls would need the field passed
|
|
||||||
through, plus every aggregate builder (`buildSeries`, `buildTopProducts`,
|
|
||||||
`buildCustomerAnalytics`) reworked to partition by seller instead of
|
|
||||||
summing globally.
|
|
||||||
- **Assumes global ownership:** the strongest case in the audit — literally
|
|
||||||
every displayed number.
|
|
||||||
- **Classification: Needs API change** — `BACKEND.md` already independently
|
|
||||||
flags this as the last domain to get a real backend; Seller Management
|
|
||||||
scoping compounds on top of that, not ahead of it.
|
|
||||||
|
|
||||||
### Reviews / Moderation
|
|
||||||
- Owner sees everything? Yes.
|
|
||||||
- Seller sees only their own? Reviews carry `productId`/`productName` — a
|
|
||||||
seller would see reviews on *their own products*, which means joining
|
|
||||||
through product ownership (once Products has `sellerId`), not a direct
|
|
||||||
seller field on the review itself. Reports (`loadReports()`) has no
|
|
||||||
filters object at all today, separate code path from reviews.
|
|
||||||
- Seller Staff limited? Undetermined.
|
|
||||||
- **Injection point:** `AdminReviewListFilters`
|
|
||||||
(`search/status/rating/page/pageSize`) — cheap field add, correctness
|
|
||||||
depends on a product-ownership join. `loadReports()` needs a signature
|
|
||||||
change first (no params exist).
|
|
||||||
- **Assumes global ownership:** `loadDashboardStats()` sums the full review
|
|
||||||
queue with `pageSize:100000`, no per-product/per-seller split.
|
|
||||||
- **Classification: Needs scope** (reviews, small, blocked on Products)
|
|
||||||
**+ Needs API change** (reports, no params today).
|
|
||||||
|
|
||||||
### Media
|
|
||||||
- Owner sees everything? Yes.
|
|
||||||
- Seller sees only their own? Not modeled — `MediaAsset` has no
|
|
||||||
uploader/owner field at all (`filename/mimeType/size/tags/folder` only);
|
|
||||||
"folder" is the closest existing scoping primitive, used generically
|
|
||||||
today.
|
|
||||||
- Seller Staff limited? Undetermined.
|
|
||||||
- **Injection point:** `MediaListParams` (`page/pageSize/search/folder/
|
|
||||||
kind/sort`) is already a rich optional-params object — a `sellerId` field
|
|
||||||
is a cheap addition, and the repository is already DI-token-bound
|
|
||||||
(`MediaRepository` abstract class, mock vs API swap already established).
|
|
||||||
`MediaAsset` itself needs an owner field added for the filter to mean
|
|
||||||
anything.
|
|
||||||
- **Assumes global ownership:** none beyond the missing owner field itself.
|
|
||||||
- **Classification: Needs scope** (small — best-positioned module in the
|
|
||||||
audit alongside Categories).
|
|
||||||
|
|
||||||
### CMS / Static Pages
|
|
||||||
- Owner sees everything? Yes — and likely always will.
|
|
||||||
- Seller sees only their own? **Conceptually doesn't apply.** Static pages
|
|
||||||
(legal, about, etc.) are inherently marketplace-wide; there is no
|
|
||||||
per-seller "static page" concept in the domain, and no fetch method
|
|
||||||
exists to add a filter to in the first place — this module reads/writes
|
|
||||||
`BootstrapConfig.staticPages` in-memory, no gateway, no HTTP call
|
|
||||||
(confirmed by `BACKEND.md`: "has no backend call today").
|
|
||||||
- Seller Staff limited? Not applicable.
|
|
||||||
- **Injection point:** none — would require inventing an entirely new data
|
|
||||||
source, not adding a filter to an existing one.
|
|
||||||
- **Assumes global ownership:** the whole module's premise, but
|
|
||||||
appropriately so — this is marketplace-wide content by nature.
|
|
||||||
- **Classification: Ready** — no scoping work belongs here; flag if product
|
|
||||||
strategy later decides sellers need their own static pages, which is a
|
|
||||||
new capability, not a gap in this one.
|
|
||||||
|
|
||||||
### Builder / Project Editor
|
|
||||||
- Owner sees everything? Yes — the entire module edits one global
|
|
||||||
`BootstrapConfig` document.
|
|
||||||
- Seller sees only their own? Not modeled, and not a filter question at
|
|
||||||
all — there is no `load*`/`list*` gateway method anywhere in this module
|
|
||||||
to extend; `save()`/`publish()`/`resetDraft()` all operate on the single
|
|
||||||
in-memory config object, with no backend write path yet either
|
|
||||||
(`BACKEND.md`: "no client write call exists today").
|
|
||||||
- Seller Staff limited? Not applicable at this structural level.
|
|
||||||
- **Injection point:** none exists. A seller-scoped builder (per-seller
|
|
||||||
storefront layout/branding) would be a **different product concept**, not
|
|
||||||
an extension of this module's current single-document model.
|
|
||||||
- **Assumes global ownership:** total and structural — the single strongest
|
|
||||||
one-owner assumption in the codebase.
|
|
||||||
- **Classification: Needs API change** — biggest structural gap in the
|
|
||||||
audit if seller-level storefront customization is ever wanted; this is
|
|
||||||
new work, not scoping.
|
|
||||||
|
|
||||||
### Settings
|
|
||||||
No route exists — `admin-nav.model.ts` marks it `comingSoon: true`, no
|
|
||||||
component backs it. **Skipped, nothing to audit.**
|
|
||||||
|
|
||||||
### Monitoring
|
|
||||||
- Owner sees everything? Yes.
|
|
||||||
- Seller sees only their own? Likely **shouldn't** — events/queues/webhooks
|
|
||||||
(logins, API health, queue depth) are platform-operational data. A seller
|
|
||||||
has no legitimate reason to see other users' login events or system
|
|
||||||
queue depth regardless of any future scoping.
|
|
||||||
- Seller Staff limited? Same reasoning — this looks like a Marketplace
|
|
||||||
Owner / Platform Admin-only surface once roles exist, not something a
|
|
||||||
Seller role should reach at all.
|
|
||||||
- **Injection point:** `AdminMonitoringEventFilters` (`category/search`)
|
|
||||||
exists for events; `loadQueues()`/`loadWebhooks()` are bare no-arg.
|
|
||||||
- **Assumes global ownership:** appropriately so — this is genuinely
|
|
||||||
system-wide data.
|
|
||||||
- **Classification: Needs permissions** — the open question is route-level
|
|
||||||
visibility per role, not data filtering.
|
|
||||||
|
|
||||||
### Transactions
|
|
||||||
- Owner sees everything? Yes.
|
|
||||||
- Seller sees only their own? Not modeled — transactions are derived 1:1
|
|
||||||
from the same unscoped global order list as Customers, inheriting the
|
|
||||||
same seller-attribution gap.
|
|
||||||
- Seller Staff limited? Undetermined.
|
|
||||||
- **Injection point:** `AdminTransactionListFilters`
|
|
||||||
(`search/status/type/page/pageSize`) exists — cheap field syntactically,
|
|
||||||
but real correctness is blocked on Orders resolving per-item seller
|
|
||||||
attribution first.
|
|
||||||
- **Assumes global ownership:** derives wholesale from
|
|
||||||
`AdminOrdersLocalGateway`, same pattern as Customers.
|
|
||||||
- **Classification: Needs scope** (small syntactically, blocked on Orders'
|
|
||||||
**Needs API change** classification for real correctness).
|
|
||||||
|
|
||||||
## Summary table
|
|
||||||
|
|
||||||
| Module | Classification |
|
|
||||||
|---|---|
|
|
||||||
| Dashboard | Needs API change |
|
|
||||||
| Products | Needs scope |
|
|
||||||
| Categories | Needs scope |
|
|
||||||
| Orders | Needs API change |
|
|
||||||
| Customers | Needs API change |
|
|
||||||
| Users | Needs API change + Needs permissions |
|
|
||||||
| Analytics | Needs API change |
|
|
||||||
| Reviews / Moderation | Needs scope (reviews) + Needs API change (reports) |
|
|
||||||
| Media | Needs scope |
|
|
||||||
| CMS / Static Pages | Ready (not applicable) |
|
|
||||||
| Builder / Project Editor | Needs API change |
|
|
||||||
| Settings | N/A — no route |
|
|
||||||
| Monitoring | Needs permissions |
|
|
||||||
| Transactions | Needs scope (blocked on Orders) |
|
|
||||||
|
|
||||||
**Nothing in this repo is currently classified "Ready" for actual seller
|
|
||||||
data scoping** — CMS/Static Pages is "Ready" only in the sense that it
|
|
||||||
correctly needs no scoping at all. Categories and Media are the
|
|
||||||
best-positioned modules for a future scope field (filters object + DI seam
|
|
||||||
either fully or mostly in place already). Orders is the load-bearing
|
|
||||||
blocker — Customers, Transactions, and half of Analytics all derive from
|
|
||||||
it, so its data-model gap (no per-item seller attribution, unified-vs-split
|
|
||||||
undecided) should be resolved before scoping any of its three dependents.
|
|
||||||
|
|
||||||
## Cross-cutting findings
|
|
||||||
|
|
||||||
- **No admin module anywhere does role-based hiding of buttons or data
|
|
||||||
today.** Users is the only module with a role *concept* in its data
|
|
||||||
(`AdminRole`, permission arrays) and even there it's label-only.
|
|
||||||
- **Only 3 of 13 audited gateways are DI-token-swappable today**
|
|
||||||
(Categories, Dashboard-metrics, Media) — everything else needs that seam
|
|
||||||
added before any scoping work, independent of Seller Management.
|
|
||||||
- **The heaviest single dependency chain**: Orders → Customers,
|
|
||||||
Transactions, and Analytics all derive from the same unscoped, full-fetch
|
|
||||||
order list. Fixing Orders' data model is the one change with the largest
|
|
||||||
downstream effect.
|
|
||||||
- **Two modules are structurally not about data scoping at all**: CMS/
|
|
||||||
Static Pages (marketplace-wide by nature) and Builder/Project Editor
|
|
||||||
(single global document, no query surface) — seller-level work here
|
|
||||||
would be new product surface, not an extension.
|
|
||||||
- **No "if seller" conditional exists anywhere in the codebase** — this
|
|
||||||
audit deliberately did not introduce any. Every injection point above is
|
|
||||||
described as a parameter/field addition to an existing method or
|
|
||||||
interface, never a runtime branch.
|
|
||||||
@@ -1,72 +0,0 @@
|
|||||||
# Seller Management — Architecture Diagrams
|
|
||||||
|
|
||||||
Companion diagrams for [ADR-011](adr/ADR-011-optional-seller-management-module.md).
|
|
||||||
Architecture only — no UI, no backend, no business logic exists yet.
|
|
||||||
|
|
||||||
## 1. Hierarchy
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
graph TD
|
|
||||||
Platform["Platform<br/>(one Angular runtime)"]
|
|
||||||
Marketplace["Marketplace (tenant)<br/>always present · backend-resolved from Host<br/>ADR-001"]
|
|
||||||
SellerA["Seller A<br/>optional, 0..N"]
|
|
||||||
SellerB["Seller B<br/>optional, 0..N"]
|
|
||||||
NoSeller["No sellers<br/>(default — most marketplaces today)"]
|
|
||||||
|
|
||||||
Platform --> Marketplace
|
|
||||||
Marketplace --> SellerA
|
|
||||||
Marketplace --> SellerB
|
|
||||||
Marketplace -.default state.-> NoSeller
|
|
||||||
```
|
|
||||||
|
|
||||||
Marketplace is the only primary tenant. Seller is a child scope of exactly
|
|
||||||
one marketplace — never a sibling tier, never resolved on its own.
|
|
||||||
|
|
||||||
## 2. Bootstrap module gate
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
graph LR
|
|
||||||
Request["GET /bootstrap"] --> Backend["Backend resolves:<br/>tenant (always)<br/>seller (only if applicable)"]
|
|
||||||
Backend --> Bootstrap["BootstrapConfig"]
|
|
||||||
Bootstrap --> ModulesCheck{"modules.sellerManagement.enabled?"}
|
|
||||||
ModulesCheck -->|false / absent, default| Identical["Behavior identical to today.<br/>No new routes, menus, or API calls."]
|
|
||||||
ModulesCheck -->|true| Available["Seller-aware behavior becomes available<br/>(not built yet — future work, own ADR)"]
|
|
||||||
Bootstrap -.optional field.-> SellerField["BootstrapConfig.seller<br/>(SellerConfig, present only when<br/>backend resolved a seller scope)"]
|
|
||||||
```
|
|
||||||
|
|
||||||
The frontend performs no resolution — it reads whatever the backend already
|
|
||||||
decided into `BootstrapConfig.modules` / `BootstrapConfig.seller`, exactly
|
|
||||||
the same discipline as tenant resolution (ADR-001) and feature-flag gating
|
|
||||||
(ADR-009).
|
|
||||||
|
|
||||||
## 3. Type contracts introduced (this ADR only)
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
classDiagram
|
|
||||||
class BootstrapConfig {
|
|
||||||
+TenantConfig tenant
|
|
||||||
+PlatformModulesConfig? modules
|
|
||||||
+SellerConfig? seller
|
|
||||||
...existing fields unchanged
|
|
||||||
}
|
|
||||||
class PlatformModulesConfig {
|
|
||||||
+SellerManagementModuleConfig sellerManagement
|
|
||||||
}
|
|
||||||
class SellerManagementModuleConfig {
|
|
||||||
+boolean enabled
|
|
||||||
}
|
|
||||||
class SellerConfig {
|
|
||||||
+UUID id
|
|
||||||
+UUID marketplaceId
|
|
||||||
+string slug
|
|
||||||
+string name
|
|
||||||
+string defaultLocale
|
|
||||||
+string[] supportedLocales
|
|
||||||
}
|
|
||||||
BootstrapConfig --> PlatformModulesConfig
|
|
||||||
BootstrapConfig --> SellerConfig
|
|
||||||
PlatformModulesConfig --> SellerManagementModuleConfig
|
|
||||||
```
|
|
||||||
|
|
||||||
`modules` and `seller` are both optional on `BootstrapConfig`. Every field
|
|
||||||
already on `BootstrapConfig` is untouched.
|
|
||||||
@@ -1,64 +0,0 @@
|
|||||||
# Seller Management — Domain Models (Preparation)
|
|
||||||
|
|
||||||
Companion to [ADR-011](adr/ADR-011-optional-seller-management-module.md) and
|
|
||||||
[Seller-Management-Diagrams.md](Seller-Management-Diagrams.md). This document
|
|
||||||
covers the second preparation pass: typed domain models for a future Seller
|
|
||||||
entity, and optional seller-ownership fields on existing Product/Order
|
|
||||||
models. **Typed models only — no repository, gateway, facade, CRUD, API, or
|
|
||||||
authentication/authorization change exists as a result of this work.**
|
|
||||||
|
|
||||||
## New: `core/sellers/models/`
|
|
||||||
|
|
||||||
A new domain model group, mirroring the existing `core/products/models/`,
|
|
||||||
`core/auth/models/` convention. Nothing outside this directory imports from
|
|
||||||
it yet — these types exist for future work to build against.
|
|
||||||
|
|
||||||
| Type | File | Purpose |
|
|
||||||
|---|---|---|
|
|
||||||
| `MarketplaceRef` | `marketplace-ref.model.ts` | Minimal `{id, slug, name}` reference from a seller record back to its owning marketplace. Not a replacement for `TenantConfig` (bootstrap's runtime tenant contract, ADR-001) — just enough to say which marketplace a seller belongs to. |
|
|
||||||
| `SellerStatus` | `seller-status.model.ts` | Lifecycle vocabulary: `'pending' \| 'active' \| 'suspended' \| 'disabled'`. No transition logic. |
|
|
||||||
| `SellerScope` | `seller-scope.model.ts` | `{sellerId, marketplaceId}` — the domain-level counterpart to `BootstrapConfig.seller` (`SellerConfig`). Backend-resolved only, same rule as tenant resolution (ADR-001, ADR-011). |
|
|
||||||
| `SellerBranding` (+ `SellerContact`, `SellerAddress`, `SellerThemeOverrides`) | `seller-branding.model.ts` | Logo, banner, description, contacts, address, theme overrides — **all fields optional**. Absent means marketplace branding/theme applies, unchanged (`BrandingConfig`/`ThemeConfig`). Nothing consumes this yet. |
|
|
||||||
| `SellerPermissionRole`, `SellerPermissions` | `seller-permissions.model.ts` | Four future roles: `marketplaceOwner`, `seller`, `sellerStaff`, `platformAdmin`. **A separate vocabulary from the existing `AdminRole`** (Owner/Manager/Support/ReadOnly, `core/auth/models/permission.model.ts`) — not merged, not wired into any guard, no auth behavior change. |
|
|
||||||
| `Seller` | `seller.model.ts` | The eventual entity: `id`, `marketplace: MarketplaceRef`, `name`, `slug`, `status: SellerStatus`, optional `branding: SellerBranding`, `createdAt`/`updatedAt`. |
|
|
||||||
|
|
||||||
All exported via `core/sellers/models/index.ts`.
|
|
||||||
|
|
||||||
## Changed: optional seller ownership on existing entities
|
|
||||||
|
|
||||||
Three existing entities gained one new **optional** field each. In every
|
|
||||||
case: absent = marketplace-owned (today's only reality for every existing
|
|
||||||
product/order), nothing reads the field yet, no consumer needed updating,
|
|
||||||
`tsc`/`arch:check` both verified clean after the change.
|
|
||||||
|
|
||||||
| Entity | File | Field added |
|
|
||||||
|---|---|---|
|
|
||||||
| `Item` (storefront product) | `models/item.model.ts` | `sellerId?: string` |
|
|
||||||
| `AdminProduct` (admin product editor) | `features/admin/products/models/admin-product.model.ts` | `sellerId?: string` |
|
|
||||||
| `AdminOrder` (admin order editor) | `features/admin/orders/models/admin-order.model.ts` | `sellerId?: string` |
|
|
||||||
|
|
||||||
Deliberately **not** touched: `AdminOrderItem` (per-line-item seller
|
|
||||||
ownership is a finer-grained decision than this preparation pass covers —
|
|
||||||
order-level `sellerId` is enough for now), and both existing bootstrap
|
|
||||||
`PermissionsConfig`/`AdminRole` (no authentication change, per mission).
|
|
||||||
|
|
||||||
## Non-goals (explicitly out of scope)
|
|
||||||
|
|
||||||
- No repository, gateway, facade, or API call reads or writes `sellerId`,
|
|
||||||
`Seller`, or any type in this document.
|
|
||||||
- No route, guard, or UI surfaces any of this.
|
|
||||||
- No change to `AdminRole`, `ROLE_PERMISSIONS`, or any existing
|
|
||||||
authentication/authorization code path.
|
|
||||||
- No change to marketplace branding/theme defaults or precedence — a
|
|
||||||
marketplace with no sellers, or a seller with no branding overrides,
|
|
||||||
behaves exactly as today.
|
|
||||||
|
|
||||||
## What this unblocks later
|
|
||||||
|
|
||||||
Once Seller Management is actually implemented (its own ADR/implementation
|
|
||||||
pass, per ADR-011 §"Scope of this ADR"): a `SellerRepository`/`SellerGateway`
|
|
||||||
can return `Seller` objects instead of inventing a shape; product/order
|
|
||||||
CRUD can start populating `sellerId` without a breaking schema change;
|
|
||||||
permission guards can consume `SellerPermissionRole` once a real role system
|
|
||||||
decision is made; branding resolution can check `Seller.branding` before
|
|
||||||
falling back to marketplace `BrandingConfig`/`ThemeConfig`.
|
|
||||||
@@ -1,190 +0,0 @@
|
|||||||
# Seller Management — Final Design Review
|
|
||||||
|
|
||||||
Principal-architect-level review of everything built and documented for
|
|
||||||
Seller Management so far. One real bug found and fixed (below, in scope per
|
|
||||||
this mission's "unless absolutely required" carve-out); everything else is
|
|
||||||
findings only, no further code changed. Reviewed against source directly
|
|
||||||
(fresh `tsc --noEmit` and `arch:check` run for this review, not recalled
|
|
||||||
from memory) plus every doc in the series:
|
|
||||||
[Seller-Management.md](Seller-Management.md),
|
|
||||||
[ADR-011](adr/ADR-011-optional-seller-management-module.md),
|
|
||||||
[Seller-Management-Diagrams.md](Seller-Management-Diagrams.md),
|
|
||||||
[Seller-Management-Domain-Models.md](Seller-Management-Domain-Models.md),
|
|
||||||
[Seller-Management-UX-Review.md](Seller-Management-UX-Review.md),
|
|
||||||
[Seller-Management-Backoffice-Readiness-Audit.md](Seller-Management-Backoffice-Readiness-Audit.md),
|
|
||||||
[Seller-Management-Storefront-Audit.md](Seller-Management-Storefront-Audit.md),
|
|
||||||
[Seller-Management-Backend-Migration-Plan.md](Seller-Management-Backend-Migration-Plan.md),
|
|
||||||
and `BACKEND.md` §11.
|
|
||||||
|
|
||||||
## Checklist verification (evidence-based, not asserted)
|
|
||||||
|
|
||||||
| Item | Status | Evidence |
|
|
||||||
|---|---|---|
|
|
||||||
| No existing marketplace breaks | ✓ Verified | Fresh `tsc --noEmit` clean, fresh `arch:check` clean (this review); live browser tests at 3 separate checkpoints across storefront home + backoffice dashboard/route |
|
|
||||||
| Feature is optional | ✓ Verified | `DEFAULT_PLATFORM_MODULES_CONFIG.sellerManagement.enabled = false`; no backend anywhere sets it true |
|
|
||||||
| Bootstrap remains backward compatible | ✓ Verified | `modules?`/`seller?` both optional on `BootstrapConfig`; `tsc` stayed clean the moment they were added, no consumer touched |
|
|
||||||
| No API breaking changes | ✓ Verified (trivially) | No API exists to break — documentation-only for the backend side |
|
|
||||||
| Existing frontend continues working | ✓ Verified | Live-tested at every UI-touching commit, zero regressions found |
|
|
||||||
| Existing backend continues working | N/A | No backend exists; not applicable until implementation begins |
|
|
||||||
| Dependency direction (ADR-002) | ✓ Verified | `arch:check:boundaries` clean, run fresh for this review |
|
|
||||||
| Import boundaries (ADR-003) | ✓ Verified | Same tool, same clean result |
|
|
||||||
| No tenant-specific conditions | ✓ Verified | Reviewed every new file directly — zero `if (tenant...)`/`if (seller===...)` conditionals exist anywhere |
|
|
||||||
| Seller scope is additive | ✓ Verified | Every new field on every touched type is optional; nothing required changed |
|
|
||||||
| UI consistency | ✓ Verified, with 2 fixes already applied | Dedicated UX-review pass found and fixed a label/a11y gap and a native-bullet inconsistency |
|
|
||||||
| Translation readiness | ✓ Verified | en/ru/hy all carry every new key, confirmed by exact-count grep |
|
|
||||||
| Accessibility readiness | ✓ Verified structurally, **one caveat** | Confirmed via accessibility-tree inspection (`role=dialog`, `aria-modal`, focus trap, `aria-label`) — **no real screen-reader software (NVDA/VoiceOver) pass was ever done**, only automated tree inspection. Flagged below (Low). |
|
|
||||||
| Performance considerations | ✓ Verified | New route is its own lazy chunk (confirmed in build output), doesn't touch the initial bundle |
|
|
||||||
| Future scalability | ✓ Addressed at design level | `Seller-Management-Backend-Migration-Plan.md` covers indexes, caching, phased rollout |
|
|
||||||
|
|
||||||
## Findings
|
|
||||||
|
|
||||||
### 1. `SellerConfig` vs. `Seller`/`SellerBranding` — two unreconciled type hierarchies — **Medium**
|
|
||||||
|
|
||||||
`shared/models/config/seller.model.ts` (`SellerConfig`, the bootstrap wire
|
|
||||||
shape: `id, marketplaceId, slug, name, defaultLocale, supportedLocales`) and
|
|
||||||
`core/sellers/models/seller.model.ts` (`Seller`, the domain entity:
|
|
||||||
`id, marketplace: MarketplaceRef, name, slug, status, branding?,
|
|
||||||
createdAt, updatedAt`) describe overlapping concepts with different shapes
|
|
||||||
and no conversion function between them. This was **self-identified during
|
|
||||||
this same body of work** (`BACKEND.md` §11.6 already flags it as an open
|
|
||||||
question) — restating it here as an independently-confirmed architectural
|
|
||||||
finding, not a new discovery, because a final design review should not
|
|
||||||
let a self-flagged gap quietly become "someone else's problem later."
|
|
||||||
**Recommendation:** resolve before real backend work starts — either
|
|
||||||
`SellerConfig` becomes a strict projection of `Seller` (documented mapping),
|
|
||||||
or they're merged into one type with bootstrap-specific fields marked
|
|
||||||
optional. Either is fine; leaving it unreconciled through implementation
|
|
||||||
risks two competing "seller" shapes drifting further apart.
|
|
||||||
|
|
||||||
### 2. No reusable capability-guard abstraction exists — **Medium**
|
|
||||||
|
|
||||||
ADR-011 (and ADR-009 before it) both prescribe checking a capability flag
|
|
||||||
"in one place, not scattered conditionals." In practice, **no such
|
|
||||||
reusable guard exists anywhere in this codebase** — not for
|
|
||||||
`sellerManagement.enabled`, and not for any existing feature flag either.
|
|
||||||
ADR-009 itself describes a `FeatureFlagService` that was never actually
|
|
||||||
built (confirmed: no file of that name exists in `src/app/core`). The one
|
|
||||||
current consumer (`AdminSellerManagementPageComponent`) hand-rolls the
|
|
||||||
optional-chain read directly. With one consumer this is harmless; the
|
|
||||||
moment a second consumer needs the same check, it will either duplicate
|
|
||||||
the same expression (drift risk: `?? false` vs `=== true` vs missing a
|
|
||||||
null-check) or someone will need to build the guard ADR-009 already
|
|
||||||
promised. **Recommendation:** build one small `SellerManagementGuardService`
|
|
||||||
(or equivalent) the first time a second consumer needs the flag — don't
|
|
||||||
let a third or fourth hand-rolled copy accumulate first.
|
|
||||||
|
|
||||||
### 3. Reactive-signal bug in the Phase 1 page — **Fixed during this review**
|
|
||||||
|
|
||||||
`AdminSellerManagementPageComponent.sellerManagementEnabled` read
|
|
||||||
`configService.getBootstrapSnapshot()` once via a plain `signal()` at
|
|
||||||
construction time — not reactively tied to `configService.bootstrapRevision()`
|
|
||||||
the way `UiRuntimeFacade` and `SeoService` both correctly do. If bootstrap
|
|
||||||
ever reloaded after initial page load (tenant context switch, revalidation)
|
|
||||||
with the flag now `true`, this signal would never update — a real
|
|
||||||
staleness bug, currently invisible because the flag is always `false` and
|
|
||||||
the signal was never even read in the template. **Fixed in this review**
|
|
||||||
(changed to `computed()` keyed on `bootstrapRevision()`, matching the
|
|
||||||
established codebase pattern exactly) — a one-line correctness fix to
|
|
||||||
already-committed code, not new feature work, so it fell inside this
|
|
||||||
mission's "unless absolutely required" carve-out. Verified `tsc --noEmit`
|
|
||||||
clean after the change.
|
|
||||||
|
|
||||||
### 4. `sellerId` typed as bare `string`, not `UUID` — **Low / Nice to have**
|
|
||||||
|
|
||||||
`Item.sellerId?`, `AdminProduct.sellerId?`, `AdminOrder.sellerId?` are all
|
|
||||||
typed `string`, while every ID in the new `core/sellers/models/` uses the
|
|
||||||
`UUID` type alias (`type UUID = string` — functionally identical, purely a
|
|
||||||
signaling convention used consistently elsewhere in this codebase, e.g.
|
|
||||||
`TenantConfig.id: UUID`). Zero functional impact since `UUID` is a bare
|
|
||||||
alias, but a future reader will reasonably wonder why the new sellerId
|
|
||||||
fields didn't follow the convention the sellers domain itself established
|
|
||||||
one file away. **Recommendation:** trivial fix, do it opportunistically
|
|
||||||
next time any of these three files is touched — not worth a dedicated pass.
|
|
||||||
|
|
||||||
### 5. `MarketplaceRef` vs. `TenantConfig` — acceptable but worth flagging — **Low**
|
|
||||||
|
|
||||||
`MarketplaceRef {id, slug, name}` and the existing `TenantConfig` (id, slug,
|
|
||||||
code, host, name, locales, currencies, timezone, base URLs) both represent
|
|
||||||
"a marketplace," from two different vantage points (seller-record reference
|
|
||||||
vs. full runtime tenant contract). This is a deliberate, documented
|
|
||||||
distinction (`Seller-Management-Domain-Models.md` explains it), not an
|
|
||||||
accidental duplication — but it's the kind of decision that reads clearly
|
|
||||||
today and could easily read as "why are there two Marketplace types" to
|
|
||||||
someone joining later without the context. **Recommendation:** no action
|
|
||||||
needed now; if a third marketplace-shaped type is ever proposed, that's the
|
|
||||||
signal to consolidate, not before.
|
|
||||||
|
|
||||||
### 6. The flag's "true" branch has never been exercised, even manually — **Medium**
|
|
||||||
|
|
||||||
Every verification claim in this document's checklist table (and every
|
|
||||||
prior audit) was tested with `modules.sellerManagement.enabled` at its
|
|
||||||
real-world value: `false` (or absent). **Nobody has ever manually set it to
|
|
||||||
`true`** — not in a browser dev-tools override, not in a mock fixture — to
|
|
||||||
confirm the flag-reading code path actually behaves as intended when the
|
|
||||||
condition it exists to detect is met. Today that's low-stakes (there's no
|
|
||||||
enabled-state UI to differ), but the review checklist item "Seller scope is
|
|
||||||
additive" was verified by reading the code, not by observing the `true`
|
|
||||||
branch execute. **Recommendation:** the first time any enabled-state UI is
|
|
||||||
built, that's also the moment to add one manual (or fixture-based) test
|
|
||||||
confirming the `true` path — don't let a second feature get built on top of
|
|
||||||
an assumption that was never actually observed.
|
|
||||||
|
|
||||||
### 7. Documentation-to-code ratio is unusually high — **Low / Nice to have**
|
|
||||||
|
|
||||||
Eight documents (this one included) exist for a capability that has zero
|
|
||||||
backend bytes and one placeholder frontend page. That's not inherently
|
|
||||||
wrong — the mission explicitly asked for staged documentation-first work —
|
|
||||||
but it carries two real risks worth naming: (a) maintenance burden keeping
|
|
||||||
eight cross-linked documents consistent if any single decision changes
|
|
||||||
(e.g., if Unified-vs-Split-Orders resolves one way, at least three of these
|
|
||||||
docs reference it and would need a coordinated update), and (b) the more
|
|
||||||
times an undecided item ("Future," "not designed") is repeated across
|
|
||||||
documents, the more it can start to feel settled by sheer repetition even
|
|
||||||
though nothing has actually been decided. **Recommendation:** before
|
|
||||||
backend implementation begins, do one consolidation pass collapsing
|
|
||||||
overlapping content (the Unified/Split-Orders question in particular
|
|
||||||
appears in `Seller-Management.md`, the Storefront audit, `BACKEND.md` §11,
|
|
||||||
and the Migration Plan) into a single canonical statement the others link
|
|
||||||
to, rather than four independent restatements.
|
|
||||||
|
|
||||||
### 8. No automated test coverage — **Low / Nice to have, not new**
|
|
||||||
|
|
||||||
Zero unit or integration tests cover any file introduced in this work —
|
|
||||||
consistent with the rest of the codebase (`PROJECT_STATUS.md` already
|
|
||||||
documents "no automated test suite exists," a pre-existing, repo-wide gap,
|
|
||||||
not something this work introduced or made worse). Noting it here for
|
|
||||||
completeness, not as a Seller-Management-specific defect.
|
|
||||||
|
|
||||||
## What I did NOT find
|
|
||||||
|
|
||||||
No architectural weaknesses beyond the above. Specifically checked for and
|
|
||||||
did **not** find: circular dependencies (verified fresh, clean), scattered
|
|
||||||
tenant/seller conditionals (none exist anywhere), over-engineering relative
|
|
||||||
to the "typed models only" mandate (the six new model files map 1:1 to the
|
|
||||||
six concepts explicitly requested, nothing extra), hidden coupling between
|
|
||||||
`core/sellers/models` and any `features/` folder (the new domain models
|
|
||||||
import only from `shared/types`, nothing reaches into a feature module),
|
|
||||||
or any security-sensitive code path touched (no auth, no payment code was
|
|
||||||
modified anywhere in this entire body of work).
|
|
||||||
|
|
||||||
## Verdict
|
|
||||||
|
|
||||||
**Not an unqualified "ready for implementation."** Two Medium findings
|
|
||||||
(#1, the unreconciled `SellerConfig`/`Seller` type split, and #2, the
|
|
||||||
missing capability-guard abstraction) are genuine architectural loose ends
|
|
||||||
that should be resolved by decision or by a small build, respectively,
|
|
||||||
before real backend/CRUD work begins — not because either blocks anything
|
|
||||||
today, but because both compound in cost the longer they're left
|
|
||||||
unresolved (more consumers = more places to reconcile later; the type
|
|
||||||
duality especially, since a real `SellerRepository`/`SellerGateway` would
|
|
||||||
otherwise have to pick one shape or invent a mapping ad hoc under time
|
|
||||||
pressure). Finding #6 (the flag's true-branch never observed) is a
|
|
||||||
process gap to close at the next milestone, not before it.
|
|
||||||
|
|
||||||
**Everything that has actually been built — the typed foundation, the
|
|
||||||
disabled-by-default feature flag, the Phase 1 UI, and the one real bug
|
|
||||||
this review found and fixed — is solid and ready to stay exactly as it
|
|
||||||
is.** The design as a *whole plan* is sound and internally consistent; the
|
|
||||||
two Medium findings are refinements to make before the next phase starts,
|
|
||||||
not defects in what exists today. No Critical or High-severity issue was
|
|
||||||
found anywhere in this review.
|
|
||||||
@@ -1,197 +0,0 @@
|
|||||||
# Seller Management — Storefront Audit (`market.com` / `seller.market.com`)
|
|
||||||
|
|
||||||
Audit only, no code changed. Every fact below was gathered by reading
|
|
||||||
current source on `feature/seller-management-foundation`, not assumed.
|
|
||||||
Companion to [Seller-Management.md](Seller-Management.md) §6 (Seller
|
|
||||||
Storefronts, Seller Branding — both marked Future there) and
|
|
||||||
[Seller-Management-Backoffice-Readiness-Audit.md](Seller-Management-Backoffice-Readiness-Audit.md)
|
|
||||||
(the equivalent admin-side audit).
|
|
||||||
|
|
||||||
## The core question: does the architecture already support a seller subdomain?
|
|
||||||
|
|
||||||
**Yes, at the resolution layer — no frontend change needed there.** Tenant
|
|
||||||
resolution is entirely backend-side by request Host (ADR-001): the frontend
|
|
||||||
calls `GET /bootstrap` and renders whatever comes back, with no client-side
|
|
||||||
knowledge of what hostname it's running on beyond what it reads from
|
|
||||||
`window.location`. If a backend ever resolves `seller.market.com` to a
|
|
||||||
seller-scoped bootstrap response, the frontend's fetch-and-render pipeline
|
|
||||||
doesn't need to know that happened — it already just consumes
|
|
||||||
`BootstrapConfig`. **This is the single most important finding of this
|
|
||||||
audit**: the hard problem is not "can the frontend handle a second
|
|
||||||
hostname" (it already architecturally can, by design), it's "does the
|
|
||||||
*data* the frontend renders (branding, breadcrumbs, SEO, contact info)
|
|
||||||
carry a seller-aware value to render instead of the marketplace-wide one."
|
|
||||||
That's a bootstrap-response and per-surface question, audited area by area
|
|
||||||
below — not a routing or hosting question.
|
|
||||||
|
|
||||||
## Global structure
|
|
||||||
|
|
||||||
Every storefront route sits under one `:lang` prefix (`app.routes.ts`) —
|
|
||||||
`/${lang}/catalog/:id`, `/${lang}/product/:id`, `/${lang}/wishlist`,
|
|
||||||
`/${lang}/cart`, `/${lang}/search`. No seller/tenant segment exists in the
|
|
||||||
route tree today, and none needs to for the subdomain approach — the
|
|
||||||
hostname carries the seller scope, not a path segment. `/search` is not a
|
|
||||||
distinct page — it lazy-loads the same `CatalogContainerComponent` as
|
|
||||||
`/catalog`. **Checkout is not a separate route or component** — it's a
|
|
||||||
payment-popup flow inline inside `cart.component.ts`
|
|
||||||
(`features/website/checkout/` and `features/website/cart/` are empty
|
|
||||||
placeholder folders, `.gitkeep` only).
|
|
||||||
|
|
||||||
## Area by area
|
|
||||||
|
|
||||||
### Homepage — Ready structurally
|
|
||||||
`pages/home/home.component.ts` is a thin wrapper: gets a page-render model
|
|
||||||
from `WebsiteRuntimeFacade.getPageRenderModelForUrl()` and renders it. No
|
|
||||||
branding/URL logic of its own, nothing hardcoded. **Future:** a seller-scoped
|
|
||||||
home would need `WebsiteRuntimeFacade`'s page-model resolution to become
|
|
||||||
seller-aware — out of scope of this file, belongs to whichever facade
|
|
||||||
resolves the page model once a seller bootstrap concept exists.
|
|
||||||
|
|
||||||
### Categories / Search — single injection point identified
|
|
||||||
`features/website/catalog/containers/catalog-container.component.ts`
|
|
||||||
(shared by both `/catalog` and `/search`) builds its own breadcrumb via
|
|
||||||
`CategoryFacade.getBreadcrumb()` → `CategoryTreeUtils.getBreadcrumb()` — pure
|
|
||||||
category-parent-chain traversal, no marketplace-root assumption baked into
|
|
||||||
the algorithm itself, but no seller dimension either. Reads
|
|
||||||
`catalogConfig`/`userExperienceConfig` straight from the bootstrap snapshot
|
|
||||||
(marketplace-wide today). **Future — Seller breadcrumbs:** since **no
|
|
||||||
dedicated breadcrumb component or service exists anywhere in the
|
|
||||||
storefront** (confirmed repo-wide — this is the only breadcrumb logic that
|
|
||||||
exists at all), a future "Seller X > Category > Product" trail has exactly
|
|
||||||
one call site to touch: this component's `breadcrumb` signal build.
|
|
||||||
|
|
||||||
### Products — reviews live here too, one dead SEO hook found
|
|
||||||
`features/website/product/containers/product-details-container.component.ts`.
|
|
||||||
Product URLs and share links (`shareProduct()`) are built from
|
|
||||||
`window.location.origin` dynamically, never hardcoded. Reviews and Q&A
|
|
||||||
render inside this same container (`ReviewListComponent`,
|
|
||||||
`QuestionListComponent`) — **there is no separate Reviews page/route to
|
|
||||||
audit independently.** **Real finding, not seller-specific but directly
|
|
||||||
relevant:** `SeoService.setItemMeta(item)` — the method that would set
|
|
||||||
per-product OG/canonical tags — is defined but **never called anywhere in
|
|
||||||
the codebase**. Product pages today get only the site-wide default meta
|
|
||||||
tags, not per-product ones. **Future — Seller SEO on product pages**
|
|
||||||
depends on first wiring this already-existing but currently dead hook, not
|
|
||||||
on inventing a new one.
|
|
||||||
|
|
||||||
### Favorites / Wishlist — Ready, no change needed today
|
|
||||||
`features/website/user-experience/wishlist/containers/wishlist-page.component.ts`.
|
|
||||||
Thin list view, no branding, no URL construction, no SEO. **Future:** if
|
|
||||||
sellers want their own "favorited from my store" filtering, that's a filter
|
|
||||||
on the already-prepared `Item.sellerId?` field (`Seller-Management-Domain-Models.md`)
|
|
||||||
applied at read time — no structural change to this page.
|
|
||||||
|
|
||||||
### Cart / Checkout — one literal string worth flagging
|
|
||||||
`pages/cart/cart.component.ts`. Checkout logic (`openPaymentPopup`,
|
|
||||||
`createPayment`, status polling) lives entirely in this one file — there is
|
|
||||||
no separate checkout page. `getPaymentDescription()` falls back, in order:
|
|
||||||
`bootstrap.branding.brandName` → `TenantResolverService.getHostname()`
|
|
||||||
(non-localhost) → the literal string `'Покупка на Маркетплейсе'`
|
|
||||||
("Purchase on Marketplace") for the payment-provider's description field.
|
|
||||||
This is a generic last-resort fallback, not a hardcoded brand name, but it
|
|
||||||
is single-tenant-framed. `recordOrder()` posts to `apiService.createOrder`
|
|
||||||
with no explicit marketplace/seller field — backend infers via Host
|
|
||||||
(ADR-001), same pattern as everywhere else. **Future — this is where
|
|
||||||
Checkout Modes and Unified/Split Orders (both marked Future, undecided, in
|
|
||||||
`Seller-Management.md` §6) would actually land**: today one cart always
|
|
||||||
produces one order via one popup flow; a cart containing items from
|
|
||||||
multiple sellers has no defined behavior here at all yet.
|
|
||||||
|
|
||||||
### Header — clean, single injection point for branding
|
|
||||||
`components/header/header.component.ts`. `brandName` →
|
|
||||||
`UiRuntimeFacade.marketplaceDisplayName()`; `logo` →
|
|
||||||
`UiRuntimeFacade.logoUrl()`. Both fully dynamic, sourced from
|
|
||||||
`bootstrap.branding` via `UiRuntimeFacade.reloadFromBootstrap()`
|
|
||||||
(`facades/runtime/ui-runtime.facade.ts`). No hardcoded name/logo anywhere.
|
|
||||||
`homeUrl` is `/${lang}` (root-relative — correct as-is for a seller
|
|
||||||
subdomain, since the subdomain itself carries the scope, not a path
|
|
||||||
segment). **Future — Seller logo / Seller banner / Seller branding**: this
|
|
||||||
facade's `reloadFromBootstrap()` method is the **single highest-leverage
|
|
||||||
place to add a seller-branding override** — if `bootstrap.seller?.branding`
|
|
||||||
(the already-typed but unused `SellerBranding`, `Seller-Management-Domain-Models.md`)
|
|
||||||
is ever populated, this one method could prefer it over
|
|
||||||
`bootstrap.branding` before setting facade state, and Header/Footer would
|
|
||||||
pick it up automatically with zero changes of their own, since they already
|
|
||||||
read exclusively through this facade.
|
|
||||||
|
|
||||||
### Footer — same source as Header, plus contact info
|
|
||||||
`components/footer/footer.component.ts`. `brandName` →
|
|
||||||
`uiRuntime.marketplaceName()`, `contactEmail` → `uiRuntime.contactEmail()` —
|
|
||||||
identical facade source as Header. Footer link groups/payment icons come
|
|
||||||
from `FooterResolverService.resolveFooterModelFromBootstrap()`, entirely
|
|
||||||
bootstrap-driven, nothing hardcoded. **Future — Seller contact page**: no
|
|
||||||
such page or concept exists today; the footer currently only ever surfaces
|
|
||||||
one marketplace-wide contact email/address. A seller contact page would be
|
|
||||||
net-new routed content, not an extension of the footer's existing contact
|
|
||||||
surfacing — the footer would, at most, link to it once it exists.
|
|
||||||
|
|
||||||
### SEO — canonical URLs already correct; structured data and sitemap are 100% net-new
|
|
||||||
`services/seo.service.ts` is the sole SEO surface in the app — confirmed no
|
|
||||||
sitemap generator, no robots.txt handler, and no JSON-LD/structured-data
|
|
||||||
code exists anywhere in the repository.
|
|
||||||
|
|
||||||
- **Canonical URLs — Ready today, no change needed.** `siteUrl` is derived
|
|
||||||
from `this.doc?.location?.origin` (actual browser location), not
|
|
||||||
hardcoded — a page served from `seller.market.com` already gets a
|
|
||||||
correct `seller.market.com` canonical URL with zero code changes. This is
|
|
||||||
the one area in the whole audit that needs nothing further.
|
|
||||||
- **Seller branding in meta tags** — `siteName` getter reads
|
|
||||||
`this.uiRuntime.marketplaceDisplayName() || 'Marketplace'`; the
|
|
||||||
`resetToDefaults()` effect reads `bootstrap.seo.default` +
|
|
||||||
`bootstrap.branding` (including `og:image` from
|
|
||||||
`branding.socialImageUrl`/`logoUrl`). **Future:** the same single
|
|
||||||
injection point as Header/Footer above (`UiRuntimeFacade`) — once that
|
|
||||||
facade can prefer seller branding, `SeoService` inherits it automatically
|
|
||||||
without its own changes, since it already reads through the same facade.
|
|
||||||
- **Seller structured data (JSON-LD)** — **does not exist for anything
|
|
||||||
today**, marketplace or seller. This is entirely Future/net-new work, not
|
|
||||||
an extension of an existing pattern.
|
|
||||||
- **Seller sitemap** — no client-side sitemap code exists at all; dynamic
|
|
||||||
sitemap generation is already flagged in `BACKEND.md` as a
|
|
||||||
server-side-only remaining-work item with no frontend action. A
|
|
||||||
per-seller sitemap is the same story: entirely a backend concern.
|
|
||||||
- **Pre-existing, unrelated to seller-scoping, worth flagging anyway**:
|
|
||||||
`og:locale` is hardcoded to `'ru_RU'` in both `setItemMeta()` and
|
|
||||||
`resetToDefaults()` — a real gap for multi-locale SEO generally, not
|
|
||||||
something to fix as part of Seller Management, but adjacent enough to
|
|
||||||
note here since it lives in the same service this audit reviewed closely.
|
|
||||||
|
|
||||||
### Breadcrumbs — no shared component, one call site
|
|
||||||
Already covered under Categories/Search above — repeating for completeness
|
|
||||||
since the mission listed it separately: there is no dedicated breadcrumb
|
|
||||||
component or service anywhere in the storefront. The only breadcrumb logic
|
|
||||||
in the entire codebase is `catalog-container.component.ts`'s local signal,
|
|
||||||
built from `CategoryFacade.getBreadcrumb()`.
|
|
||||||
|
|
||||||
## Summary — future changes only (nothing here is implemented)
|
|
||||||
|
|
||||||
| Area | Current state | Future seller-scoped change |
|
|
||||||
|---|---|---|
|
|
||||||
| Homepage | Ready — thin page-model wrapper | Depends on `WebsiteRuntimeFacade` becoming seller-aware |
|
|
||||||
| Categories / Search | One breadcrumb call site, no seller dimension | Extend `CategoryFacade.getBreadcrumb()` call in `catalog-container.component.ts` |
|
|
||||||
| Products | URLs already dynamic; `setItemMeta()` exists but is dead code | Wire the existing (currently unused) per-page SEO hook before adding seller data to it |
|
|
||||||
| Reviews | Lives inside Product detail, no separate page | No independent seller-scoping work — follows Products |
|
|
||||||
| Favorites | Ready — no branding/URL logic | Optional future filter on already-prepared `Item.sellerId?` |
|
|
||||||
| Cart / Checkout | One inline flow, one popup, no seller/multi-vendor concept | Where Checkout Modes + Unified/Split Orders (both Future in `Seller-Management.md`) would land |
|
|
||||||
| Header | Fully dynamic via `UiRuntimeFacade` | **Highest-leverage single injection point**: prefer `bootstrap.seller?.branding` in `reloadFromBootstrap()` |
|
|
||||||
| Footer | Same facade source as Header | Inherits the Header fix automatically; Seller contact page is net-new routed content |
|
|
||||||
| SEO — canonical URLs | **Already correct**, derived from `location.origin` | None needed |
|
|
||||||
| SEO — branding in meta tags | Reads through `UiRuntimeFacade` | Inherits the Header/Footer fix automatically |
|
|
||||||
| SEO — structured data (JSON-LD) | Does not exist for anything today | 100% net-new, not an extension |
|
|
||||||
| SEO — sitemap | No client-side code at all; backend-only concern (`BACKEND.md`) | No frontend action, ever |
|
|
||||||
| Breadcrumbs | One ad hoc signal, no shared component | Same single call site as Categories/Search |
|
|
||||||
|
|
||||||
## Conclusion
|
|
||||||
|
|
||||||
The storefront's existing discipline — everything reads through
|
|
||||||
`UiRuntimeFacade`/`ConfigService`/bootstrap, nothing hardcodes marketplace
|
|
||||||
identity, canonical URLs derive from actual browser location — means a
|
|
||||||
`seller.market.com` subdomain is **structurally closer to already working
|
|
||||||
than any other part of this audit found**. The entire future-work surface
|
|
||||||
collapses to two real gaps: (1) `UiRuntimeFacade.reloadFromBootstrap()`
|
|
||||||
needs to prefer seller branding when present (one method, cascades to
|
|
||||||
Header/Footer/SEO for free), and (2) Cart/Checkout's single-seller-per-order
|
|
||||||
assumption needs the Unified-vs-Split-Orders decision from
|
|
||||||
`Seller-Management.md` before multi-vendor carts can be handled at all.
|
|
||||||
Structured data and sitemap are not seller-specific gaps — they're simply
|
|
||||||
unbuilt for anyone today.
|
|
||||||
@@ -1,80 +0,0 @@
|
|||||||
# Seller Management — UX Review
|
|
||||||
|
|
||||||
Review pass over the Phase 1 UI (`admin-seller-management-page.component.*`)
|
|
||||||
against the rest of the Backoffice. Two real issues found and fixed; the
|
|
||||||
rest of the checklist was verified as already consistent because the page
|
|
||||||
is built entirely from existing shared components.
|
|
||||||
|
|
||||||
## Fixed this pass
|
|
||||||
|
|
||||||
1. **Missing label association on the Message field (real a11y bug).**
|
|
||||||
`app-input` self-wires `id`/`aria-describedby` from its injected
|
|
||||||
`FormFieldContext` (confirmed in `input.component.html`); the raw
|
|
||||||
`<textarea>` used for the optional Message field — no dedicated textarea
|
|
||||||
component exists yet anywhere in the app — never received that wiring.
|
|
||||||
The visible label's `for` pointed at an id the textarea never got, so a
|
|
||||||
screen reader wouldn't announce "Message" on focus via the label
|
|
||||||
association (proximity only). Fixed with an explicit `[attr.aria-label]`
|
|
||||||
bound to the same translation key already used for the visible label —
|
|
||||||
correct regardless of the broken `for` linkage.
|
|
||||||
|
|
||||||
2. **Native browser bullets in the Learn More dialog (visual inconsistency).**
|
|
||||||
No global `list-style: none` reset exists for plain `<ul>` anywhere in
|
|
||||||
`src/styles.scss` (only `details > summary` gets one, for the expander
|
|
||||||
chevron). The feature list would have rendered default browser discs —
|
|
||||||
the one place in this page not reusing an existing shared visual
|
|
||||||
language. Replaced with `checkCircle` icon + text rows (`app-icon`,
|
|
||||||
`--success-color` token), consistent with how the rest of the app pairs
|
|
||||||
icons with status/list meaning rather than bare bullets.
|
|
||||||
|
|
||||||
## Verified already consistent (no change needed)
|
|
||||||
|
|
||||||
- **Empty state usage**: every other empty-state consumer in the app
|
|
||||||
(`admin-products-list`, `media-library-page`, `admin-reviews-list`, etc.)
|
|
||||||
uses `app-empty-state` bare — no card wrapper. This page matches that. It
|
|
||||||
is the only one filling the `icon` slot (a subtle primary-tinted circle
|
|
||||||
behind a `store` icon); no other page does this, but this page is also
|
|
||||||
the only one that's *entirely* an empty state as its whole content
|
|
||||||
(every other example sits inside a page that also has a toolbar/table),
|
|
||||||
so a slightly more deliberate visual treatment for the "coming soon"
|
|
||||||
moment is a reasonable, isolated deviation rather than drift.
|
|
||||||
`app-empty-state`'s own description already caps at `max-width: 32rem` —
|
|
||||||
no extra width-constraint code needed.
|
|
||||||
- **Icon reuse**: `store` (empty-state) and `checkCircle` (feature list) —
|
|
||||||
neither icon is reused with a conflicting meaning elsewhere in the app
|
|
||||||
(checked against `icon-registry.ts`'s existing 85-icon map from the prior
|
|
||||||
icon audit).
|
|
||||||
- **Buttons/dialogs/inputs/hover/focus**: 100% shared components
|
|
||||||
(`app-button`, `app-dialog`, `app-input`, `app-form-field`, `app-badge`).
|
|
||||||
Hover, focus-visible, disabled, and loading states are whatever those
|
|
||||||
components already define — verified by inspecting each component's own
|
|
||||||
`.scss`, not re-implemented here. Same reasoning covers contrast (reused
|
|
||||||
tokens, not new color decisions) and dark-theme readiness (every value in
|
|
||||||
this page's own `.scss` is `var(--token, fallback)`, same fallback values
|
|
||||||
already used in `input.component.scss` — nothing hardcoded that a future
|
|
||||||
dark theme couldn't override).
|
|
||||||
- **Dialog accessibility**: `app-dialog` provides `role="dialog"`,
|
|
||||||
`aria-modal="true"`, Tab/Shift+Tab focus trap, Escape-to-close, and
|
|
||||||
focus-restore-on-close — confirmed via the accessibility tree
|
|
||||||
(`role=dialog`, correct `aria-label` matching each dialog's title) and by
|
|
||||||
live-testing focus behavior, not assumed.
|
|
||||||
- **Merchant wording**: every string matches the original brief's exact
|
|
||||||
business-facing copy (Company/Email/Message, "Coming Soon", capability
|
|
||||||
bullets in plain language) — no developer terminology introduced.
|
|
||||||
- **Responsive**: re-verified at 1280px, and at 375px mobile (button rows
|
|
||||||
stack full-width per the existing breakpoint in this page's `.scss`,
|
|
||||||
dialog/list content re-rendered correctly, no layout break).
|
|
||||||
- **Translations**: all new keys (`adminShell.nav.partnersGroup`,
|
|
||||||
`adminShell.nav.sellerManagement`, `adminShell.pages.sellerManagement`,
|
|
||||||
and the full `adminSellerManagement.*` namespace) exist in `en.ts`,
|
|
||||||
`ru.ts`, `hy.ts`, and `translations.ts` (types) — verified by exact-count
|
|
||||||
grep across all three locale files, no hardcoded string found in the
|
|
||||||
component's template or TypeScript.
|
|
||||||
|
|
||||||
## Verification
|
|
||||||
|
|
||||||
`tsc --noEmit` clean. `arch:check` (boundaries + cycles) clean. Live-tested
|
|
||||||
(ru locale, `devBypassAdmin`, desktop 1280px + mobile 375px): Learn More
|
|
||||||
dialog now shows all 6 items with a check icon each (confirmed via DOM
|
|
||||||
query - `svg` present on every `<li>`), Message textarea confirmed to carry
|
|
||||||
`aria-label="Сообщение"`, no console errors at any point.
|
|
||||||
@@ -1,214 +0,0 @@
|
|||||||
# Seller Management — Capability Documentation
|
|
||||||
|
|
||||||
Status legend used throughout this document:
|
|
||||||
|
|
||||||
- **Implemented** — exists in source on `feature/seller-management-foundation` today, verified (`tsc`, `arch:check`, or live browser test).
|
|
||||||
- **Planned** — has a typed contract or explicit ADR decision, but no code reads/writes it yet.
|
|
||||||
- **Future** — a concept named in this document for roadmap completeness only. No shape, contract, or decision exists yet. Do not build against this section without a new ADR.
|
|
||||||
|
|
||||||
This document is the entry point. Detail lives in its companion docs:
|
|
||||||
[ADR-011](adr/ADR-011-optional-seller-management-module.md) (decision),
|
|
||||||
[Seller-Management-Diagrams.md](Seller-Management-Diagrams.md) (hierarchy/bootstrap-gate diagrams),
|
|
||||||
[Seller-Management-Domain-Models.md](Seller-Management-Domain-Models.md) (every type, field by field),
|
|
||||||
[Seller-Management-UX-Review.md](Seller-Management-UX-Review.md) (Phase 1 UI review).
|
|
||||||
|
|
||||||
## 1. Overview
|
|
||||||
|
|
||||||
Seller Management is an **optional platform capability** that would let one
|
|
||||||
marketplace host multiple independent sellers, each with their own
|
|
||||||
inventory/orders/branding, under one centralized administration. It is not
|
|
||||||
another tenant — a seller is a child scope beneath exactly one marketplace
|
|
||||||
(ADR-011).
|
|
||||||
|
|
||||||
**Implemented today:** typed contracts for the whole hierarchy, a disabled-
|
|
||||||
by-default feature flag, one Backoffice page that explains the capability
|
|
||||||
and collects interest ("Request Access" / "Learn More"). **Nothing else** —
|
|
||||||
no CRUD, no backend, no seller-facing UI, no checkout/order behavior change.
|
|
||||||
|
|
||||||
## 2. Architecture & Hierarchy — Implemented (types only)
|
|
||||||
|
|
||||||
```
|
|
||||||
Platform
|
|
||||||
└── Marketplace (tenant) — always present, backend-resolved (ADR-001)
|
|
||||||
└── Seller (optional) — 0..N per marketplace, backend-resolved (ADR-011)
|
|
||||||
```
|
|
||||||
|
|
||||||
Full diagram set: [Seller-Management-Diagrams.md](Seller-Management-Diagrams.md).
|
|
||||||
|
|
||||||
Rules (ADR-011, enforced by review, not yet by any lint rule):
|
|
||||||
Marketplace is the sole primary tenant. Seller is a child scope, never a
|
|
||||||
sibling tier. The frontend never resolves seller identity itself — same
|
|
||||||
rule as tenant resolution. All seller-aware behavior must check one
|
|
||||||
capability flag, never scattered marketplace/seller conditionals.
|
|
||||||
|
|
||||||
## 3. Marketplace — Implemented (existing, unchanged)
|
|
||||||
|
|
||||||
The marketplace is the existing `TenantConfig`
|
|
||||||
(`shared/models/config/tenant.model.ts`) — resolved by the backend from
|
|
||||||
request Host, exactly as before this work started. Seller Management adds a
|
|
||||||
new `MarketplaceRef` (`core/sellers/models/marketplace-ref.model.ts`): a
|
|
||||||
minimal `{id, slug, name}` view of a marketplace *as seen from a seller
|
|
||||||
record*, not a replacement for `TenantConfig`.
|
|
||||||
|
|
||||||
## 4. Seller — Implemented (types only)
|
|
||||||
|
|
||||||
`Seller` (`core/sellers/models/seller.model.ts`): `id`, `marketplace:
|
|
||||||
MarketplaceRef`, `name`, `slug`, `status: SellerStatus`, optional `branding:
|
|
||||||
SellerBranding`, `createdAt`/`updatedAt`. No repository, gateway, facade, or
|
|
||||||
UI reads or writes this type yet — it exists so future CRUD work has a
|
|
||||||
settled shape instead of inventing one ad hoc.
|
|
||||||
|
|
||||||
**Planned:** a `SellerRepository`/`SellerGateway` pair following the same
|
|
||||||
mock↔API DI-token pattern every other admin domain already uses
|
|
||||||
(`BACKEND.md` §8). **Future:** the actual CRUD screens, list/detail pages,
|
|
||||||
onboarding flow.
|
|
||||||
|
|
||||||
## 5. Roles & Permissions — Implemented (types only)
|
|
||||||
|
|
||||||
`SellerPermissionRole` (`core/sellers/models/seller-permissions.model.ts`):
|
|
||||||
four values — `marketplaceOwner`, `seller`, `sellerStaff`, `platformAdmin`.
|
|
||||||
This is a **separate vocabulary** from the existing `AdminRole` (Owner/
|
|
||||||
Manager/Support/ReadOnly, `core/auth/models/permission.model.ts`) — not
|
|
||||||
merged, not wired into any guard. **No authentication or authorization
|
|
||||||
change exists anywhere in this work.**
|
|
||||||
|
|
||||||
**Planned:** once a real permission model is designed, these roles gate
|
|
||||||
seller-scoped routes/actions the same way `AdminRole` gates admin routes
|
|
||||||
today (ADR-009 capability-guard pattern). **Future:** the actual
|
|
||||||
permission-to-action mapping, custom/finer-grained roles per marketplace.
|
|
||||||
|
|
||||||
## 6. Future Roadmap
|
|
||||||
|
|
||||||
### Feature Flags — Implemented (contract), Planned (real use)
|
|
||||||
|
|
||||||
`BootstrapConfig.modules.sellerManagement.enabled`
|
|
||||||
(`shared/models/config/platform-modules.model.ts`), default `false`
|
|
||||||
(`DEFAULT_PLATFORM_MODULES_CONFIG`). Implemented as a typed contract read by
|
|
||||||
the Phase 1 page (`admin-seller-management-page.component.ts`); no backend
|
|
||||||
sets it to `true` anywhere today, so it is always `false` in practice.
|
|
||||||
|
|
||||||
### Bootstrap — Implemented (contract), Planned (real data)
|
|
||||||
|
|
||||||
`BootstrapConfig.modules?` and `BootstrapConfig.seller?` (`SellerConfig`,
|
|
||||||
`shared/models/config/seller.model.ts`) — both optional, both absent in
|
|
||||||
every real bootstrap response today. When a backend eventually resolves a
|
|
||||||
seller scope, it populates `seller`; until then this field simply doesn't
|
|
||||||
exist on the wire.
|
|
||||||
|
|
||||||
### Future API — Future
|
|
||||||
|
|
||||||
No endpoint exists. When built, it should follow `BACKEND.md`'s existing
|
|
||||||
mock↔API-gateway pattern (§8) rather than a new convention — this is a
|
|
||||||
statement of intent, not a designed contract. No URL, DTO, or status-code
|
|
||||||
behavior is decided.
|
|
||||||
|
|
||||||
### Seller Storefronts — Future
|
|
||||||
|
|
||||||
Concept: a seller-branded storefront view within a marketplace (e.g. a
|
|
||||||
seller's own product listing page reachable from the marketplace). **Not
|
|
||||||
designed.** No route, component, or URL scheme exists or is decided.
|
|
||||||
|
|
||||||
### Seller Branding — Implemented (types only), Future (usage)
|
|
||||||
|
|
||||||
`SellerBranding` (`core/sellers/models/seller-branding.model.ts`): logo,
|
|
||||||
banner, description, contacts, address, theme overrides — every field
|
|
||||||
optional. **Implemented as a type only.** Nothing renders it, nothing falls
|
|
||||||
back from it to marketplace branding — that precedence logic is **Future**
|
|
||||||
work, not yet designed.
|
|
||||||
|
|
||||||
### Seller Ownership — Implemented (schema only), Future (logic)
|
|
||||||
|
|
||||||
`sellerId?: string` added to `Item` (storefront), `AdminProduct`, and
|
|
||||||
`AdminOrder` — optional, absent means marketplace-owned (every existing
|
|
||||||
product/order today). **No code reads or writes this field anywhere.**
|
|
||||||
Ownership rules, transfer, and enforcement are **Future** work.
|
|
||||||
|
|
||||||
### Checkout Modes — Future
|
|
||||||
|
|
||||||
Concept: how checkout behaves when a cart contains items from multiple
|
|
||||||
sellers (e.g. single combined checkout vs. per-seller checkout flows).
|
|
||||||
**Not designed.** No decision exists on this; today every product is
|
|
||||||
marketplace-owned and checkout has exactly one flow, unchanged by this work.
|
|
||||||
|
|
||||||
### Unified Orders / Split Orders — Future
|
|
||||||
|
|
||||||
Concept: whether one customer purchase spanning multiple sellers becomes
|
|
||||||
one order record or splits into one order per seller. **Not designed.**
|
|
||||||
This is a real business decision (payments, refunds, and reporting all
|
|
||||||
depend on the answer) with no default assumed — explicitly listed as an
|
|
||||||
open question for whenever Seller Management moves past preparation.
|
|
||||||
|
|
||||||
## 7. Migration & Compatibility
|
|
||||||
|
|
||||||
### Why existing marketplaces remain unchanged
|
|
||||||
|
|
||||||
- `modules.sellerManagement.enabled` defaults to `false` and no backend
|
|
||||||
sets it — every marketplace today gets identical behavior whether the
|
|
||||||
field is present-and-false or entirely absent from its bootstrap
|
|
||||||
response.
|
|
||||||
- `BootstrapConfig.modules` and `BootstrapConfig.seller` are optional
|
|
||||||
fields; no existing field's type changed.
|
|
||||||
- `sellerId?` on `Item`/`AdminProduct`/`AdminOrder` is optional; no
|
|
||||||
consumer of any of these three types needed updating, verified by
|
|
||||||
`tsc --noEmit` staying clean after each change.
|
|
||||||
- Zero components, facades, services, or routes branch on marketplace or
|
|
||||||
seller identity anywhere in this work (ADR-011 compliance requirement) —
|
|
||||||
there is no conditional to accidentally trigger.
|
|
||||||
- Every commit in this line of work was verified with `tsc --noEmit`,
|
|
||||||
`arch:check` (import boundaries + circular deps), and — for the UI
|
|
||||||
commits — a live browser pass, specifically to confirm no regression to
|
|
||||||
existing pages.
|
|
||||||
|
|
||||||
## 8. Developer Notes
|
|
||||||
|
|
||||||
- All seller domain types live in `core/sellers/models/` (mirrors
|
|
||||||
`core/products/models`, `core/auth/models`). Extend there, not ad hoc in
|
|
||||||
feature folders.
|
|
||||||
- When real seller-aware behavior is eventually built, gate it behind
|
|
||||||
`modules.sellerManagement.enabled` in one place (a capability guard,
|
|
||||||
ADR-009's pattern) — never scattered `if` checks on tenant/seller identity.
|
|
||||||
- The Phase 1 page (`features/admin/seller-management/`) is disposable —
|
|
||||||
it exists to communicate the capability to merchants, not as a
|
|
||||||
foundation to extend. Real seller CRUD UI should be planned fresh once
|
|
||||||
the backend contract exists, not bolted onto this page.
|
|
||||||
|
|
||||||
## 9. Builder Notes
|
|
||||||
|
|
||||||
The Project Editor / Marketplace Builder has **zero seller-awareness**
|
|
||||||
today. Its draft/publish model (`localStorage`-only, no backend write path
|
|
||||||
per `BACKEND.md` §1.10) is entirely marketplace-scoped. If/when a seller
|
|
||||||
needs their own builder-like surface (branding, storefront layout), it must
|
|
||||||
be designed as its own ADR — do not assume the existing builder can be
|
|
||||||
reused as-is for a seller scope without that review, since its facades and
|
|
||||||
schema (ADR-005, ADR-007) were built assuming exactly one config document
|
|
||||||
per marketplace.
|
|
||||||
|
|
||||||
## 10. Backend Notes
|
|
||||||
|
|
||||||
No backend implementation exists for any part of Seller Management. When
|
|
||||||
work begins, follow `BACKEND.md`'s established pattern exactly: a
|
|
||||||
`SellerRepository`/`SellerGateway` behind a DI token, `MockSellerGateway`
|
|
||||||
first, `ApiSellerGateway` swapped in later, same convention every other
|
|
||||||
admin domain in this codebase already uses (`BACKEND.md` §8). The typed
|
|
||||||
models in `core/sellers/models/` are the DTO shapes to implement against —
|
|
||||||
treat them as the contract, not a suggestion to redesign.
|
|
||||||
|
|
||||||
## Diagrams
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
graph LR
|
|
||||||
A["Types & feature flag<br/>(this + prior 3 commits)"] -->|Implemented| B["Phase 1 UI<br/>(Partners > Seller Management page)"]
|
|
||||||
B -->|Implemented| C["Backend contract decisions<br/>(BACKEND.md gaps, own ADR)"]
|
|
||||||
C -->|Future| D["Seller CRUD + real gateway"]
|
|
||||||
D -->|Future| E["Seller Branding rendering<br/>+ Storefronts"]
|
|
||||||
E -->|Future| F["Checkout Modes +<br/>Unified/Split Orders"]
|
|
||||||
|
|
||||||
classDef done fill:#2e7d3222,stroke:#2e7d32,color:inherit;
|
|
||||||
classDef future fill:#6b728022,stroke:#6b7280,color:inherit;
|
|
||||||
class A,B done;
|
|
||||||
class C,D,E,F future;
|
|
||||||
```
|
|
||||||
|
|
||||||
Rollout is strictly left-to-right — no stage after "Phase 1 UI" has started.
|
|
||||||
See [Seller-Management-Diagrams.md](Seller-Management-Diagrams.md) for the
|
|
||||||
hierarchy and bootstrap-gate diagrams (unchanged, still accurate).
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
# Service Standards
|
|
||||||
|
|
||||||
Status: Mandatory
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Service Categories
|
|
||||||
|
|
||||||
- Domain Service: business operations and rules.
|
|
||||||
- Integration Service: external API/system communication.
|
|
||||||
- Platform Service: cross-cutting platform concerns.
|
|
||||||
|
|
||||||
## Rules
|
|
||||||
|
|
||||||
- Services must have one clear responsibility.
|
|
||||||
- Services should expose typed contracts only.
|
|
||||||
- Services should avoid UI-specific formatting.
|
|
||||||
- Services should not depend on component classes.
|
|
||||||
- Shared services must not depend on feature modules.
|
|
||||||
- Business decisions must not be driven by `environment.*` flags.
|
|
||||||
- Environment values are limited to infrastructure concerns (API base URLs, provider strategy wiring, auth endpoint origins).
|
|
||||||
|
|
||||||
## Facade Interaction
|
|
||||||
|
|
||||||
- Components call facades.
|
|
||||||
- Facades call services.
|
|
||||||
- Services do not call UI components.
|
|
||||||
|
|
||||||
## Stable Module Protection
|
|
||||||
|
|
||||||
- Existing authentication, payment, authorization services remain behavior-compatible.
|
|
||||||
- Wrap legacy stable behavior with adapters where needed.
|
|
||||||
- No contract changes for auth/payment APIs.
|
|
||||||
|
|
||||||
## Storage and Runtime Access
|
|
||||||
|
|
||||||
- Browser storage access allowed only in approved service boundaries.
|
|
||||||
- Prefer abstraction interfaces for storage access.
|
|
||||||
- Never use storage APIs in UI components.
|
|
||||||
@@ -1,42 +0,0 @@
|
|||||||
# State Management Standards
|
|
||||||
|
|
||||||
Status: Mandatory
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Objectives
|
|
||||||
|
|
||||||
- Keep state predictable, scoped, and replaceable.
|
|
||||||
- Support Website, Builder, and Backoffice without coupling.
|
|
||||||
|
|
||||||
## State Layers
|
|
||||||
|
|
||||||
- Platform State: bootstrap, feature flags, theme, localization, session status.
|
|
||||||
- Domain State: feature-specific bounded context state.
|
|
||||||
- UI State: ephemeral visual state local to component/container.
|
|
||||||
|
|
||||||
## Facade Rules
|
|
||||||
|
|
||||||
- Every domain exposes state through facades.
|
|
||||||
- Facades expose readonly projections/selectors/signals.
|
|
||||||
- Mutations happen through explicit facade commands.
|
|
||||||
|
|
||||||
## Isolation Rules
|
|
||||||
|
|
||||||
- No direct cross-domain state mutation.
|
|
||||||
- No component writes directly into service internals.
|
|
||||||
- Shared state contracts must be explicit and typed.
|
|
||||||
|
|
||||||
## Persistence Rules
|
|
||||||
|
|
||||||
- Persisted state access must be centralized in approved services.
|
|
||||||
- UI components never access localStorage/sessionStorage directly.
|
|
||||||
|
|
||||||
## Feature Flag Interaction
|
|
||||||
|
|
||||||
- State branches for optional capabilities must be capability-driven.
|
|
||||||
- Missing capability paths must return safe defaults.
|
|
||||||
|
|
||||||
## Migration and Compatibility
|
|
||||||
|
|
||||||
- Existing auth/payment behavior remains intact while wrapped by facade boundaries.
|
|
||||||
- Refactoring must preserve observable behavior for critical flows.
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
# ADR-001: Platform Model and Tenancy Strategy
|
|
||||||
|
|
||||||
Status: Accepted
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
The existing repository has evolved from marketplace website delivery.
|
|
||||||
The target product is Marketplace-as-a-Service with unlimited tenants on one runtime.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
Adopt a platform runtime model:
|
|
||||||
|
|
||||||
- One Angular application serves all tenants.
|
|
||||||
- Tenant identity is resolved by backend from request Host.
|
|
||||||
- Frontend does not pass tenant id or project key.
|
|
||||||
- Frontend starts by requesting GET /bootstrap.
|
|
||||||
- Tenant-specific website, builder, and backoffice behavior derives from bootstrap configuration.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
Positive:
|
|
||||||
|
|
||||||
- Tenant onboarding becomes configuration-driven.
|
|
||||||
- Eliminates tenant forks and branch divergence.
|
|
||||||
- Strong separation of platform engine and tenant data.
|
|
||||||
|
|
||||||
Negative:
|
|
||||||
|
|
||||||
- Requires strict discipline against tenant conditionals in UI code.
|
|
||||||
- Requires robust bootstrap schema governance.
|
|
||||||
|
|
||||||
## Compliance Requirements
|
|
||||||
|
|
||||||
- No environment-based tenant branching in presentation logic.
|
|
||||||
- No tenant-specific routes hardcoded in feature components.
|
|
||||||
- Tenant behavior is represented in typed configuration contracts.
|
|
||||||
@@ -1,43 +0,0 @@
|
|||||||
# ADR-002: Layered Feature Architecture with Single Responsibility
|
|
||||||
|
|
||||||
Status: Accepted
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
The platform must support Website, Builder, and Backoffice while keeping shared capabilities reusable and independent.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
Adopt the following architecture layers and responsibilities:
|
|
||||||
|
|
||||||
- Core: bootstrap, app wiring, global policies, base adapters.
|
|
||||||
- Shared: pure contracts, pure utilities, generic primitives.
|
|
||||||
- UI Library: reusable presentational components only.
|
|
||||||
- Widgets: configurable functional blocks built from UI components.
|
|
||||||
- Layouts: page section composition and structural orchestration.
|
|
||||||
- Pages: route containers mapping configuration to layouts/widgets.
|
|
||||||
- Website: public commerce experience.
|
|
||||||
- Builder: configuration editing domain.
|
|
||||||
- Backoffice: business data management domain.
|
|
||||||
|
|
||||||
Single responsibility is mandatory for each layer.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
Positive:
|
|
||||||
|
|
||||||
- Predictable layering and ownership.
|
|
||||||
- Higher reuse across Website, Builder, and Backoffice.
|
|
||||||
- Reduced accidental coupling.
|
|
||||||
|
|
||||||
Negative:
|
|
||||||
|
|
||||||
- Requires import boundary enforcement.
|
|
||||||
- Requires upfront contracts before feature implementation.
|
|
||||||
|
|
||||||
## Compliance Requirements
|
|
||||||
|
|
||||||
- Shared and UI layers cannot depend on feature layers.
|
|
||||||
- Feature layers interact through contracts/facades, not direct imports.
|
|
||||||
- New artifacts must be placed in the correct layer folder.
|
|
||||||
@@ -1,39 +0,0 @@
|
|||||||
# ADR-003: Import Boundaries and Dependency Direction
|
|
||||||
|
|
||||||
Status: Accepted
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
Without strict dependency direction, large Angular codebases accumulate circular dependencies and feature coupling that block reuse.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
Enforce one-way dependency flow:
|
|
||||||
|
|
||||||
Website/Builder/Backoffice -> Pages -> Layouts -> Widgets -> UI Library -> Shared -> Core
|
|
||||||
|
|
||||||
Additional constraints:
|
|
||||||
|
|
||||||
- No circular dependencies.
|
|
||||||
- No feature importing another feature directly.
|
|
||||||
- Core does not depend on any feature.
|
|
||||||
- Shared does not depend on features.
|
|
||||||
- UI Library does not depend on features.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
Positive:
|
|
||||||
|
|
||||||
- Stable architecture evolution.
|
|
||||||
- Easier testability and extraction.
|
|
||||||
- Faster onboarding with clear module contracts.
|
|
||||||
|
|
||||||
Negative:
|
|
||||||
|
|
||||||
- Some existing direct imports must be replaced by contracts.
|
|
||||||
|
|
||||||
## Compliance Requirements
|
|
||||||
|
|
||||||
- Enforce via lint boundaries and dependency checks.
|
|
||||||
- Violations block merge.
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
# ADR-004: Configuration Bootstrap and Provider Abstraction
|
|
||||||
|
|
||||||
Status: Superseded
|
|
||||||
Date: 2026-07-03
|
|
||||||
Superseded by: `docs/BACKEND_API.md` §4 (Bootstrap) and §14 (Backend replacement pattern)
|
|
||||||
|
|
||||||
## Original decision (preserved for history)
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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_API.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 +0,0 @@
|
|||||||
# ADR-005: Dynamic Page, Section, and Widget Rendering
|
|
||||||
|
|
||||||
Status: Accepted
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
Platform websites must be generated from configuration. Hardcoded page composition blocks tenant scalability.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
Adopt dynamic rendering engine:
|
|
||||||
|
|
||||||
- A page definition contains ordered sections.
|
|
||||||
- A section contains ordered widgets.
|
|
||||||
- WidgetHost resolves widget type through registry.
|
|
||||||
- Registry-based resolution avoids renderer edits for every new widget.
|
|
||||||
- Hero, Carousel, Header, Footer, and other blocks are widgets/layout entries from configuration.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
Positive:
|
|
||||||
|
|
||||||
- New tenant pages created by configuration.
|
|
||||||
- Supports Builder-driven composition.
|
|
||||||
|
|
||||||
Negative:
|
|
||||||
|
|
||||||
- Requires robust schema validation.
|
|
||||||
- Requires widget compatibility and versioning discipline.
|
|
||||||
|
|
||||||
## Compliance Requirements
|
|
||||||
|
|
||||||
- Page templates must not hardcode specific widget combinations.
|
|
||||||
- Widget rendering must be data-driven from configuration contracts.
|
|
||||||
@@ -1,42 +0,0 @@
|
|||||||
# ADR-006: UI Component Purity and Container-Facade Pattern
|
|
||||||
|
|
||||||
Status: Accepted
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
Reusable platform components cannot contain business and integration concerns.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
Separate visual and business responsibilities:
|
|
||||||
|
|
||||||
- UI components are presentational only.
|
|
||||||
- Container components connect facades to UI components.
|
|
||||||
- Facades own orchestration and use services.
|
|
||||||
- Services handle IO and integration.
|
|
||||||
|
|
||||||
UI component restrictions:
|
|
||||||
|
|
||||||
- No HttpClient.
|
|
||||||
- No localStorage/sessionStorage access.
|
|
||||||
- No environment import.
|
|
||||||
- No tenant awareness.
|
|
||||||
- No authentication/payment logic.
|
|
||||||
- No route logic.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
Positive:
|
|
||||||
|
|
||||||
- Maximum reuse and testability.
|
|
||||||
- Supports widget library portability.
|
|
||||||
|
|
||||||
Negative:
|
|
||||||
|
|
||||||
- Requires refactoring of mixed legacy components.
|
|
||||||
|
|
||||||
## Compliance Requirements
|
|
||||||
|
|
||||||
- Components must use Inputs for data and Outputs for events.
|
|
||||||
- Business behavior belongs to facades/containers only.
|
|
||||||
@@ -1,33 +0,0 @@
|
|||||||
# ADR-007: State Management and Facade Boundaries
|
|
||||||
|
|
||||||
Status: Accepted
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
State must be predictable and isolated by domain to support Website, Builder, and Backoffice without cross-domain leakage.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
Use facade-centered state management by bounded context:
|
|
||||||
|
|
||||||
- Each feature domain exposes one or more facades.
|
|
||||||
- Facades expose read models and command methods.
|
|
||||||
- State is local to domain and projected as readonly selectors/signals.
|
|
||||||
- Shared/global state is limited to platform concerns (configuration, theme, localization, session status).
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
Positive:
|
|
||||||
|
|
||||||
- Clear ownership of state transitions.
|
|
||||||
- Improved maintainability and testability.
|
|
||||||
|
|
||||||
Negative:
|
|
||||||
|
|
||||||
- Requires disciplined facade boundaries.
|
|
||||||
|
|
||||||
## Compliance Requirements
|
|
||||||
|
|
||||||
- Components do not mutate service internals directly.
|
|
||||||
- Cross-domain communication is contract-based, not direct state access.
|
|
||||||
@@ -1,32 +0,0 @@
|
|||||||
# ADR-008: Theme Engine and Runtime Design Tokens
|
|
||||||
|
|
||||||
Status: Accepted
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
Tenant branding must be configuration-driven and must not require tenant-specific code branches.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
Introduce theme engine based on runtime design tokens:
|
|
||||||
|
|
||||||
- Branding, color palette, typography, spacing, icons, logos, favicon derive from configuration.
|
|
||||||
- Theme tokens are applied at runtime through token service and CSS variable mapping.
|
|
||||||
- Feature code consumes semantic tokens, not tenant constants.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
Positive:
|
|
||||||
|
|
||||||
- Tenant branding changes are configuration-only.
|
|
||||||
- Removes environment-based visual branching.
|
|
||||||
|
|
||||||
Negative:
|
|
||||||
|
|
||||||
- Requires token schema governance and fallback policy.
|
|
||||||
|
|
||||||
## Compliance Requirements
|
|
||||||
|
|
||||||
- No tenant-specific style imports in feature components.
|
|
||||||
- UI styling must resolve through semantic token set.
|
|
||||||
@@ -1,32 +0,0 @@
|
|||||||
# ADR-009: Feature Flags and Capability Guards
|
|
||||||
|
|
||||||
Status: Accepted
|
|
||||||
Date: 2026-07-03
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
Platform tenants have optional capabilities. Features cannot be assumed always present.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
Introduce capability model backed by bootstrap feature flags:
|
|
||||||
|
|
||||||
- FeatureFlagService exposes tenant capabilities.
|
|
||||||
- Routes, widgets, and actions are guarded by capability checks.
|
|
||||||
- Missing capability must degrade gracefully with fallback behavior.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
Positive:
|
|
||||||
|
|
||||||
- One runtime supports variable tenant feature sets.
|
|
||||||
- Reduces tenant branching and dead code.
|
|
||||||
|
|
||||||
Negative:
|
|
||||||
|
|
||||||
- Requires explicit defaults and fallback UX.
|
|
||||||
|
|
||||||
## Compliance Requirements
|
|
||||||
|
|
||||||
- Components and pages cannot assume optional feature availability.
|
|
||||||
- Capability checks must be centralized, not scattered conditionals.
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
# ADR-010: Backward Compatibility for Authentication, Payment, and Authorization
|
|
||||||
|
|
||||||
Status: Superseded
|
|
||||||
Date: 2026-07-03
|
|
||||||
Superseded by: `docs/BACKEND_API.md` §2 (Authentication), §2.8 (Payments), §2.5 (admin authorization gap)
|
|
||||||
|
|
||||||
## Original decision (preserved for history)
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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_API.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.
|
|
||||||
@@ -1,117 +0,0 @@
|
|||||||
# ADR-011: Optional Seller Management Module
|
|
||||||
|
|
||||||
Status: Accepted
|
|
||||||
Date: 2026-07-26
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
The platform today has a two-level hierarchy: Platform → Marketplace (tenant),
|
|
||||||
per ADR-001. Some marketplaces will eventually need a third, optional level:
|
|
||||||
individual Sellers operating storefronts within one marketplace (a
|
|
||||||
marketplace-of-marketplaces / multi-vendor model). Not every marketplace
|
|
||||||
needs this — most tenants today have none.
|
|
||||||
|
|
||||||
Seller Management must not become a second tenancy model. ADR-001 already
|
|
||||||
established that tenant identity is backend-resolved from request Host and
|
|
||||||
the frontend never passes or resolves tenant identity itself. Introducing
|
|
||||||
sellers must not weaken that discipline or introduce a second, parallel
|
|
||||||
resolution mechanism the frontend has to reason about.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
Seller Management is an **optional platform capability module**, not a new
|
|
||||||
tenancy tier equal to Marketplace:
|
|
||||||
|
|
||||||
```
|
|
||||||
Platform
|
|
||||||
└── Marketplace (tenant) — always present, resolved by backend (ADR-001)
|
|
||||||
└── Seller (optional) — 0..N per marketplace, resolved by backend
|
|
||||||
```
|
|
||||||
|
|
||||||
- **Marketplace remains the sole primary tenant.** A seller is a child scope
|
|
||||||
of exactly one marketplace, never a sibling of Marketplace and never
|
|
||||||
resolved independently of it.
|
|
||||||
- **The frontend never resolves seller identity itself** — same rule as
|
|
||||||
tenant resolution (ADR-001). The backend decides whether the current
|
|
||||||
request scope is marketplace-level or seller-level and reflects that
|
|
||||||
decision in the bootstrap response.
|
|
||||||
- **The frontend consumes bootstrap only.** No new endpoint, header, or
|
|
||||||
client-side resolution logic is introduced by this ADR. If a seller scope
|
|
||||||
applies, `BootstrapConfig.seller` (see `SellerConfig`) is present; if not,
|
|
||||||
it's absent. There is no other channel.
|
|
||||||
- **Gated by a module flag, not scattered conditionals.** The capability is
|
|
||||||
controlled by one typed flag — `BootstrapConfig.modules.sellerManagement.
|
|
||||||
enabled` (see `PlatformModulesConfig`) — checked in one place if/when
|
|
||||||
seller-aware behavior is built, never as ad hoc `if (tenant.id === 'x')`
|
|
||||||
or similar marketplace-specific conditionals anywhere in feature code.
|
|
||||||
This follows the same capability-guard discipline ADR-009 already
|
|
||||||
established for feature flags.
|
|
||||||
|
|
||||||
## Backward Compatibility (non-negotiable)
|
|
||||||
|
|
||||||
- `modules` and `seller` are both optional fields on `BootstrapConfig`.
|
|
||||||
Existing marketplaces whose bootstrap response never includes them are
|
|
||||||
unaffected — untyped-absent is not a special case to handle, it's the
|
|
||||||
default.
|
|
||||||
- `DEFAULT_PLATFORM_MODULES_CONFIG` defaults `sellerManagement.enabled` to
|
|
||||||
`false`. A marketplace that has never heard of this feature, and a
|
|
||||||
marketplace where the backend explicitly disables it, behave identically:
|
|
||||||
no new routes, no new menu entries, no new API calls, no visual change.
|
|
||||||
- No existing `BootstrapConfig` field, route, guard, or component changes as
|
|
||||||
a result of this ADR. This ADR adds types; it changes nothing that already
|
|
||||||
runs.
|
|
||||||
|
|
||||||
## Scope of this ADR
|
|
||||||
|
|
||||||
This ADR and its accompanying typed contracts (`PlatformModulesConfig`,
|
|
||||||
`SellerManagementModuleConfig`, `SellerConfig`) are **architecture only**:
|
|
||||||
|
|
||||||
- No UI is introduced — no seller-facing pages, no admin seller-management
|
|
||||||
screens, no navigation entries.
|
|
||||||
- No backend is implemented — no endpoints, no seller data model, no
|
|
||||||
resolution logic.
|
|
||||||
- No business logic is introduced — no seller CRUD, no seller-scoped
|
|
||||||
permissions, no seller onboarding flow.
|
|
||||||
|
|
||||||
Those are all future work, gated behind `modules.sellerManagement.enabled`,
|
|
||||||
and each will need its own ADR/implementation pass once the module is
|
|
||||||
actually being built out (routing strategy under a seller scope, admin UI,
|
|
||||||
backend data model and resolution, permission model for seller-level roles).
|
|
||||||
This ADR exists so that future work has a typed foundation to build on
|
|
||||||
without retrofitting the platform/marketplace hierarchy after the fact.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
Positive:
|
|
||||||
|
|
||||||
- Marketplaces that don't need multi-vendor support pay zero cost — no new
|
|
||||||
code path executes, no new field is even present in their bootstrap
|
|
||||||
response.
|
|
||||||
- Future Seller Management work has a settled hierarchy and typed contract
|
|
||||||
to build against instead of ad hoc per-feature decisions about where
|
|
||||||
"seller" fits.
|
|
||||||
- Consistent with the platform's existing capability-guard discipline
|
|
||||||
(ADR-009) — one flag, checked in one place, not scattered conditionals.
|
|
||||||
|
|
||||||
Negative:
|
|
||||||
|
|
||||||
- Adds two optional fields to `BootstrapConfig` that most of the codebase
|
|
||||||
will never populate — acceptable, matches the existing pattern of several
|
|
||||||
other optional bootstrap fields (`header?`, `catalog?`, `layout?`, etc.).
|
|
||||||
- Defers real design decisions (seller-scoped routing, seller admin
|
|
||||||
permissions, seller data ownership) to whenever the module is actually
|
|
||||||
implemented — intentional; this ADR does not pre-invent that design.
|
|
||||||
|
|
||||||
## Compliance Requirements
|
|
||||||
|
|
||||||
- No component, facade, or service may branch on marketplace identity or
|
|
||||||
seller identity directly. All seller-aware behavior, once built, must
|
|
||||||
check `modules.sellerManagement.enabled` (or a capability-guard built on
|
|
||||||
top of it) as the single gate.
|
|
||||||
- No frontend code may attempt to resolve which seller is active by itself
|
|
||||||
(URL parsing, local storage, guessed convention, etc.) — that information
|
|
||||||
only ever comes from `BootstrapConfig.seller`, backend-resolved, exactly
|
|
||||||
like tenant resolution today.
|
|
||||||
- Any future work that adds seller-facing routes, UI, or backend calls must
|
|
||||||
keep all of it inert and unreachable while `modules.sellerManagement.
|
|
||||||
enabled` is `false`, with no exception.
|
|
||||||
@@ -1,640 +0,0 @@
|
|||||||
> **ARCHIVED 2026-07-26.** Historical sprint log (Sprint 19-28 admin backoffice build-out). Living admin architecture reference now lives in [`docs/BACKEND.md`](../BACKEND.md) (backend contract) and [`docs/ARCHITECTURE.md`](../ARCHITECTURE.md) (frontend architecture). Kept for history only.
|
|
||||||
|
|
||||||
# Marketplace Admin Dashboard - Sprint 19
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
Sprint 19 adds the production Admin Dashboard and makes it the default landing
|
|
||||||
page for the admin area. It also wires the previously-unrouted `admin/products`
|
|
||||||
feature and adds route placeholders for backoffice sections that don't have a
|
|
||||||
feature built yet.
|
|
||||||
|
|
||||||
## Routing
|
|
||||||
|
|
||||||
All admin routes live under `/:lang/backoffice/**` (`app.routes.ts`), guarded
|
|
||||||
by the existing `adminAuthGuard` (`core/admin-auth/admin-auth.guard.ts`):
|
|
||||||
|
|
||||||
```text
|
|
||||||
/:lang/backoffice -> redirects to dashboard
|
|
||||||
/:lang/backoffice/dashboard -> AdminDashboardPageComponent
|
|
||||||
/:lang/backoffice/products -> AdminProductsListPageComponent
|
|
||||||
/:lang/backoffice/products/create -> AdminProductEditorPageComponent
|
|
||||||
/:lang/backoffice/products/:id/edit -> AdminProductEditorPageComponent
|
|
||||||
/:lang/backoffice/products/:id/duplicate -> AdminProductEditorPageComponent
|
|
||||||
/:lang/backoffice/categories -> AdminCategoriesListPageComponent
|
|
||||||
/:lang/backoffice/categories/create -> AdminCategoryEditorPageComponent
|
|
||||||
/:lang/backoffice/categories/:id/edit -> AdminCategoryEditorPageComponent
|
|
||||||
/:lang/backoffice/static-pages -> BackofficeComingSoonPageComponent
|
|
||||||
/:lang/backoffice/transactions -> BackofficeComingSoonPageComponent
|
|
||||||
/:lang/backoffice/orders -> BackofficeComingSoonPageComponent
|
|
||||||
/:lang/backoffice/media -> BackofficeComingSoonPageComponent
|
|
||||||
```
|
|
||||||
|
|
||||||
`admin/products` (`features/admin/products/`) was already fully implemented
|
|
||||||
in an earlier sprint but was never wired into `app.routes.ts` and its internal
|
|
||||||
navigation hardcoded the `ru` locale segment. Both are fixed in this sprint:
|
|
||||||
routes are wired, and `admin-products-list-page.component.ts` /
|
|
||||||
`admin-product-editor-page.component.ts` now build the locale segment from
|
|
||||||
`LanguageService.currentLanguage()`.
|
|
||||||
|
|
||||||
**Dashboard as default admin page:** on successful admin Telegram QR login,
|
|
||||||
`TelegramLoginComponent` (`mode="admin"`) navigates to
|
|
||||||
`/:lang/backoffice/dashboard` (`components/telegram-login/telegram-login.component.ts`).
|
|
||||||
The `backoffice` route's empty path also redirects to `dashboard`, so any bare
|
|
||||||
`/:lang/backoffice` link lands there too.
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/app/features/admin/dashboard/
|
|
||||||
models/ admin-dashboard.model.ts
|
|
||||||
services/ admin-dashboard-metrics.gateway.interface.ts
|
|
||||||
admin-dashboard-metrics.local.gateway.ts
|
|
||||||
admin-dashboard-metrics-gateway.token.ts
|
|
||||||
admin-dashboard-history.service.ts
|
|
||||||
facade/ admin-dashboard.facade.ts
|
|
||||||
components/ admin-dashboard-card.component.*
|
|
||||||
admin-dashboard-quick-actions.component.*
|
|
||||||
admin-dashboard-activity.component.*
|
|
||||||
admin-dashboard-health.component.*
|
|
||||||
pages/ admin-dashboard-page.component.*
|
|
||||||
|
|
||||||
src/app/features/backoffice/shared/
|
|
||||||
backoffice-coming-soon-page.component.*
|
|
||||||
```
|
|
||||||
|
|
||||||
Follows the existing container/facade/service split (ADR-006, ADR-007):
|
|
||||||
`AdminDashboardPageComponent` is the container, `AdminDashboardFacade` owns
|
|
||||||
orchestration, presentational card/quick-actions/activity/health components
|
|
||||||
take only `@Input()`s and have no HttpClient/localStorage/route access.
|
|
||||||
|
|
||||||
### Data sources (future-ready)
|
|
||||||
|
|
||||||
Cards never read `ConfigService`, `localStorage`, or an HTTP client directly -
|
|
||||||
everything routes through `AdminDashboardFacade`, which composes:
|
|
||||||
|
|
||||||
- **`ProjectEditorFacade`** (already existed) - `bootstrap`, `status`,
|
|
||||||
`lastSavedAt`, `lastPublishedAt` (new, see below), `validationIssues`,
|
|
||||||
`homepageWidgets`. Backs Marketplace Status, Project Name, Current Theme,
|
|
||||||
Languages, Last Publish, Last Draft Save, Bootstrap Version, Active Layout,
|
|
||||||
Enabled Widgets, and the System Health checks.
|
|
||||||
- **`ADMIN_DASHBOARD_METRICS_GATEWAY`** (new `InjectionToken`, same swap
|
|
||||||
pattern as `BACKOFFICE_DATA_PROVIDER`) - defaults to
|
|
||||||
`AdminDashboardMetricsLocalGateway`, which composes
|
|
||||||
`BackofficeDataService.loadCategories()/loadProducts()` (already used by
|
|
||||||
`AdminProductsLocalGateway`) into counts. Backs Categories Count and
|
|
||||||
Products Count. Swapping to a real dashboard-metrics endpoint later means
|
|
||||||
implementing `AdminDashboardMetricsGateway` and rebinding the token - the
|
|
||||||
facade and cards don't change.
|
|
||||||
- **`AdminDashboardHistoryService`** (new) - localStorage-backed activity log,
|
|
||||||
scoped per tenant, same pattern as `ProjectEditorDraftStorageService`. The
|
|
||||||
facade appends an entry whenever `lastSavedAt`/`lastPublishedAt` change
|
|
||||||
(detected via an `effect()`, primed on first read so the initial bootstrap
|
|
||||||
load doesn't get logged as an activity event). Backs Recent Activity.
|
|
||||||
|
|
||||||
### Orders / Revenue
|
|
||||||
|
|
||||||
No backend or local data model exists for orders or revenue anywhere in the
|
|
||||||
codebase (`features/backoffice/orders` is an empty placeholder folder). These
|
|
||||||
two cards render an honest **`pending-backend`** card state ("Awaiting backend
|
|
||||||
integration") rather than fabricated numbers - not a "no data" empty state,
|
|
||||||
since the gap is structural, not a temporarily-empty dataset.
|
|
||||||
|
|
||||||
### Card states
|
|
||||||
|
|
||||||
`AdminDashboardCardComponent` (`components/admin-dashboard-card.component.ts`)
|
|
||||||
renders one of: `loading` (skeleton), `empty`, `error`, `pending-backend`, or
|
|
||||||
the ready value + optional subtitle. The container computes each card's status
|
|
||||||
per data source (bootstrap not yet loaded -> `loading`; metrics gateway error
|
|
||||||
-> `error`; no supported locales -> `empty`; Orders/Revenue -> always
|
|
||||||
`pending-backend`).
|
|
||||||
|
|
||||||
### System Health
|
|
||||||
|
|
||||||
`ProjectValidator` (`features/project-editor/services/project-validator.service.ts`)
|
|
||||||
already covered 5 of the 6 required checks. This sprint added two more:
|
|
||||||
|
|
||||||
- `translationIssues()` - flags a supported non-default locale missing a
|
|
||||||
header nav label translation or a static-page `translations` entry.
|
|
||||||
- `layoutIssues()` - flags `bootstrap.layout.type` or any section's
|
|
||||||
`layout.strategy` that isn't one of the known enum values
|
|
||||||
(`PlatformLayoutType` / `SectionLayoutStrategy`). Runtime validation matters
|
|
||||||
here because bootstrap JSON isn't type-checked at load time.
|
|
||||||
|
|
||||||
Dashboard mapping (`AdminDashboardFacade.healthChecks`):
|
|
||||||
|
|
||||||
| Dashboard label | Validator code |
|
|
||||||
|---|---|
|
|
||||||
| Bootstrap valid | structural: `bootstrap !== null && schemaVersion` set |
|
|
||||||
| Configuration valid | no validation issues at all |
|
|
||||||
| Missing translations | `missing-translations` (new) |
|
|
||||||
| Invalid colors | `invalid-colors` (existing) |
|
|
||||||
| Invalid widget references | `missing-widget` (existing - a homepage widget with no `type`) |
|
|
||||||
| Invalid layouts | `invalid-layouts` (new) |
|
|
||||||
|
|
||||||
### Quick Actions
|
|
||||||
|
|
||||||
Static list in `AdminDashboardFacade` (`route` arrays relative to the lang
|
|
||||||
root); the page component prefixes the current locale
|
|
||||||
(`LanguageService.currentLanguage()`) before binding `routerLink`. Categories,
|
|
||||||
Static Pages, Transactions, Orders, and Media Library currently land on
|
|
||||||
`BackofficeComingSoonPageComponent` since those features aren't built yet -
|
|
||||||
this is a routing placeholder, not a dashboard card placeholder.
|
|
||||||
|
|
||||||
### `lastPublishedAt` (ProjectEditorFacade change)
|
|
||||||
|
|
||||||
Before this sprint, `publish()` only updated `lastSavedAt`, so "last draft
|
|
||||||
save" and "last publish" were indistinguishable after a publish. Added
|
|
||||||
`lastPublishedAt: number | null` to `ProjectEditorState` /
|
|
||||||
`ProjectEditorFacade`, set only inside `publish()`. `lastSavedAt` behavior is
|
|
||||||
unchanged (still updated by both `save()` and `publish()`).
|
|
||||||
|
|
||||||
## Sprint 20 - Category Management
|
|
||||||
|
|
||||||
`features/admin/categories/` (model/gateway/facade/pages/components), same
|
|
||||||
container/facade/service split as `admin/products` and `admin/dashboard`:
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/app/features/admin/categories/
|
|
||||||
models/ admin-category.model.ts
|
|
||||||
services/ admin-categories-gateway.interface.ts
|
|
||||||
admin-categories-local.gateway.ts
|
|
||||||
admin-categories-form.factory.ts
|
|
||||||
facade/ admin-categories.facade.ts
|
|
||||||
guards/ admin-category-dirty.guard.ts
|
|
||||||
components/ admin-categories-list.component.*
|
|
||||||
admin-category-form.component.*
|
|
||||||
pages/ admin-categories-list-page.component.ts
|
|
||||||
admin-category-editor-page.component.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
- **Hierarchy**: `AdminCategory.parentId` (nullable). List page renders a
|
|
||||||
flattened, indented tree (`AdminCategoriesFacade.rootCategories()` /
|
|
||||||
`childrenOf(id)`); the editor's parent `<select>` excludes the category
|
|
||||||
itself and its descendants to prevent cycles.
|
|
||||||
- **Reordering**: native HTML5 drag-and-drop in
|
|
||||||
`admin-categories-list.component.ts` (`draggable`, `dragstart`/`drop`),
|
|
||||||
persists via `AdminCategoriesFacade.reorder()` which just rewrites `order`.
|
|
||||||
- **Delete/restore**: soft delete (`deletedAt` timestamp). Blocked
|
|
||||||
client-side (`facade.canDelete()`) if the category has children or
|
|
||||||
`itemsCount > 0`; list has an "include deleted" filter with a Restore
|
|
||||||
action for soft-deleted rows.
|
|
||||||
- **Draft/publish**: `status: 'draft' | 'published'`, set by the editor's
|
|
||||||
"Save Draft" vs "Publish" buttons (`AdminCategoriesFacade.saveDraft(publish)`).
|
|
||||||
- **Local draft recovery + unsaved-changes guard**: every `updateDraft()`
|
|
||||||
call persists the in-progress category to `localStorage` under
|
|
||||||
`admin-category-draft:<id>` (via the existing `LocalStorageService`,
|
|
||||||
same pattern as Project Editor autosave); the editor reloads that draft
|
|
||||||
ahead of the saved value if present, and is cleared on save.
|
|
||||||
`adminCategoryDirtyGuard` (mirrors `projectEditorDirtyGuard`) blocks
|
|
||||||
navigation away from an unsaved edit with `window.confirm`.
|
|
||||||
- **Image**: reuses the existing `MediaPickerComponent` (same one used by
|
|
||||||
Media Manager) rather than a free-text URL field.
|
|
||||||
- **Seed data**: `AdminCategoriesLocalGateway` seeds its in-memory cache from
|
|
||||||
`BackofficeDataService.loadCategories()` (`CategoryCardConfig`, currently
|
|
||||||
flat/no hierarchy) - same swappable-provider pattern as
|
|
||||||
`AdminProductsLocalGateway`.
|
|
||||||
- **Not yet wired**: `admin/products`' category `<select>` still uses
|
|
||||||
`AdminProductsGateway.loadCategories()` (its own `AdminProductCategoryOption`
|
|
||||||
seed), not `AdminCategoriesGateway` - unifying them is Sprint 21 scope
|
|
||||||
(`docs/SPRINT-PLAN.md`).
|
|
||||||
|
|
||||||
## Sprint 21 - Product Management completion
|
|
||||||
|
|
||||||
- **Categories now real**: `AdminProductsLocalGateway` seeds its category dropdown from `AdminCategoriesLocalGateway.loadCategories()` (Sprint 20) instead of raw `BackofficeDataService.loadCategories()` - product `categoryId` now points at real admin-managed categories.
|
|
||||||
- **Archive/restore**: `AdminProduct.archived` (soft, distinct from `visible`). List has an "include archived" filter + per-row Archive/Restore action; archived products excluded by default (mirrors categories' `deletedAt`/restore pattern).
|
|
||||||
- **Barcode**: added alongside `sku`.
|
|
||||||
- **Variants**: lightweight `AdminProductVariant[]` (`name`/`price`/`quantity`), edited as `name|price|quantity` lines (same textarea-parse convention as `specifications`/`attributes`). Not a full options-matrix variant system - scoped to what the model/backend contract actually needs today.
|
|
||||||
- **Related products**: `relatedProductIds: string[]`, checkbox picker in the editor sourced from `AdminProductFormComponent`'s `allProducts` input - which is `AdminProductsFacade.products()`, i.e. whatever page is currently loaded in the facade (usually primed by navigating from the list). Not a full catalog search; fine for the current mock-data scale, worth revisiting if `AdminProductsLocalGateway` is ever swapped for a real API with more than a page of products.
|
|
||||||
- **Gallery**: `media.gallery` now built via the shared `MediaPickerComponent` (add/remove thumbnails) instead of a raw URL textarea; `media.images`/`media.videos` unchanged (still textarea, out of this ticket's scope).
|
|
||||||
- **Preview**: simple read-only line in the editor showing computed discounted price.
|
|
||||||
- **Infinite scroll**: `AdminProductsFacade.infiniteScroll` toggle - when on, `loadMore()` appends the next page to `products()` instead of replacing it; pagination UI swaps for a "Load more" button. Off by default (existing paginated behavior unchanged).
|
|
||||||
|
|
||||||
## Sprint 22 - Media System hardening
|
|
||||||
|
|
||||||
`core/media/` (`MediaRepository` abstraction, `MockMediaRepository` IndexedDB
|
|
||||||
implementation) + `features/backoffice/media/` + the shared
|
|
||||||
`shared/media/media-picker/`:
|
|
||||||
|
|
||||||
- **Folders**: flat `folder?: string` tag on `MediaAsset` (no nesting) -
|
|
||||||
"New folder" just sets the active filter to a name typed via
|
|
||||||
`window.prompt` (mirrors the `window.confirm` pattern already used for
|
|
||||||
destructive actions elsewhere); the folder is created implicitly the next
|
|
||||||
time something uploads into it. `MediaRepository.listFolders()` derives
|
|
||||||
the folder list from existing records rather than a separate folder
|
|
||||||
entity - intentionally light, matches the flat-storage reality of an
|
|
||||||
IndexedDB mock.
|
|
||||||
- **Tags**: already existed on `MediaAsset`; added an edit affordance
|
|
||||||
(`window.prompt`, comma-separated) and `MediaLibraryFacade.updateTags()`.
|
|
||||||
- **Validation**: `MockMediaRepository.validateFile()` rejects anything over
|
|
||||||
10MB or outside the allow-list (`jpeg/png/webp/gif/svg+xml/pdf`); errors
|
|
||||||
now propagate as real messages through `MediaLibraryFacade.error` (both
|
|
||||||
`media-library-page` and `media-picker` display it - previously upload
|
|
||||||
failures were swallowed into a generic string).
|
|
||||||
- **SVG sanitization**: `sanitizeSvg()` strips `<script>` tags and
|
|
||||||
`on*="..."` attributes from uploaded SVG markup before storing it, since
|
|
||||||
SVG is the one accepted format that can carry inline script.
|
|
||||||
- **Compression/resize**: raster images (not SVG/GIF) are downscaled to a
|
|
||||||
2000px max dimension and re-encoded (JPEG/PNG, quality 0.85) via
|
|
||||||
`<canvas>` before being stored - client-side only, no crop UI. A full
|
|
||||||
interactive cropper was out of scope for this ticket; revisit if a real
|
|
||||||
design need for manual cropping shows up.
|
|
||||||
- **Reuse confirmed**: `MediaPickerComponent` is now wired into Category
|
|
||||||
images (Sprint 20), Product gallery (Sprint 21), and Project Editor
|
|
||||||
branding (logo / compact logo / favicon, this sprint) - one media library
|
|
||||||
for the whole platform, per the sprint goal. Static Pages editor has no
|
|
||||||
image fields to wire (confirmed, not a gap). Hero image: no dedicated
|
|
||||||
hero-image field exists in `BootstrapConfig` today - nothing to wire.
|
|
||||||
- **Storage abstraction**: already existed via `MediaRepository` (abstract
|
|
||||||
class + DI token `providedIn: 'root'` on `MockMediaRepository`) - swapping
|
|
||||||
to a real CDN/backend means implementing `MediaRepository` against a real
|
|
||||||
API and rebinding the provider; no consumer (`MediaLibraryFacade`,
|
|
||||||
`MediaPickerComponent`, or any of the pickers above) changes.
|
|
||||||
|
|
||||||
## Sprint 22 - Media System hardening
|
|
||||||
|
|
||||||
`core/media/` (`MediaRepository` abstraction, `MockMediaRepository` IndexedDB
|
|
||||||
implementation) + `features/backoffice/media/` + the shared
|
|
||||||
`shared/media/media-picker/`:
|
|
||||||
|
|
||||||
- **Folders**: flat `folder?: string` tag on `MediaAsset` (no nesting) -
|
|
||||||
"New folder" just sets the active filter to a name typed via
|
|
||||||
`window.prompt` (mirrors the `window.confirm` pattern already used for
|
|
||||||
destructive actions elsewhere); the folder is created implicitly the next
|
|
||||||
time something uploads into it. `MediaRepository.listFolders()` derives
|
|
||||||
the folder list from existing records rather than a separate folder
|
|
||||||
entity - intentionally light, matches the flat-storage reality of an
|
|
||||||
IndexedDB mock.
|
|
||||||
- **Tags**: already existed on `MediaAsset`; added an edit affordance
|
|
||||||
(`window.prompt`, comma-separated) and `MediaLibraryFacade.updateTags()`.
|
|
||||||
- **Validation**: `MockMediaRepository.validateFile()` rejects anything over
|
|
||||||
10MB or outside the allow-list (`jpeg/png/webp/gif/svg+xml/pdf`); errors
|
|
||||||
now propagate as real messages through `MediaLibraryFacade.error` (both
|
|
||||||
`media-library-page` and `media-picker` display it - previously upload
|
|
||||||
failures were swallowed into a generic string).
|
|
||||||
- **SVG sanitization**: `sanitizeSvg()` strips `<script>` tags and
|
|
||||||
`on*="..."` attributes from uploaded SVG markup before storing it, since
|
|
||||||
SVG is the one accepted format that can carry inline script.
|
|
||||||
- **Compression/resize**: raster images (not SVG/GIF) are downscaled to a
|
|
||||||
2000px max dimension and re-encoded (JPEG/PNG, quality 0.85) via
|
|
||||||
`<canvas>` before being stored - client-side only, no crop UI. A full
|
|
||||||
interactive cropper was out of scope for this ticket; revisit if a real
|
|
||||||
design need for manual cropping shows up.
|
|
||||||
- **Reuse confirmed**: `MediaPickerComponent` is now wired into Category
|
|
||||||
images (Sprint 20), Product gallery (Sprint 21), and Project Editor
|
|
||||||
branding (logo / compact logo / favicon, this sprint) - one media library
|
|
||||||
for the whole platform, per the sprint goal. Static Pages editor has no
|
|
||||||
image fields to wire (confirmed, not a gap). Hero image: no dedicated
|
|
||||||
hero-image field exists in `BootstrapConfig` today ('hero' only appears
|
|
||||||
as a `SectionLayoutStrategy` enum value) - nothing to wire.
|
|
||||||
- **Storage abstraction**: already existed via `MediaRepository` (abstract
|
|
||||||
class + DI token `providedIn: 'root'` on `MockMediaRepository`) - swapping
|
|
||||||
to a real CDN/backend means implementing `MediaRepository` against a real
|
|
||||||
API and rebinding the provider; no consumer (`MediaLibraryFacade`,
|
|
||||||
`MediaPickerComponent`, or any of the pickers above) changes.
|
|
||||||
|
|
||||||
## Sprint 23 - Orders (mock/local)
|
|
||||||
|
|
||||||
`features/admin/orders/` (model/gateway/facade/pages), same
|
|
||||||
container/facade/service split as the rest of `admin/*`:
|
|
||||||
|
|
||||||
- **No real data source exists for orders anywhere in this repo** (already
|
|
||||||
called out in Sprint 19's dashboard gap and `docs/BACKEND_API.md#611-backoffice--orders-planned`) -
|
|
||||||
`AdminOrdersLocalGateway` seeds 24 deterministic synthetic orders in
|
|
||||||
memory (cycling through all statuses/customers) rather than reading from
|
|
||||||
`BackofficeDataService`, since there is nothing there to read. This is
|
|
||||||
explicitly a placeholder to unblock the admin UI, not a real mock of
|
|
||||||
production order volume.
|
|
||||||
- List: search (order number/customer/email), status filter, pagination,
|
|
||||||
CSV export (client-side `Blob` download, no server round-trip).
|
|
||||||
- Detail: customer/payment/shipping info, itemized line items + total,
|
|
||||||
status timeline, change-status dropdown, refund request and cancel
|
|
||||||
(both `window.confirm`-gated), customer-visible notes vs internal-only
|
|
||||||
notes (two separate free-text logs), print invoice via `window.print()`
|
|
||||||
with a `@media print` rule hiding all non-invoice chrome (`.no-print`) -
|
|
||||||
no PDF generation library, deliberately minimal.
|
|
||||||
- Wired into `/:lang/backoffice/orders` and `/:lang/backoffice/orders/:id`,
|
|
||||||
replacing the coming-soon placeholder.
|
|
||||||
|
|
||||||
## Sprint 24 - Transactions (mock/local)
|
|
||||||
|
|
||||||
`features/admin/transactions/`. `AdminTransactionsLocalGateway` derives its
|
|
||||||
mock data from `AdminOrdersLocalGateway`'s 24 seeded orders (one
|
|
||||||
transaction per order, deterministic type/status/method assignment) rather
|
|
||||||
than a separate synthetic dataset - keeps order numbers/totals consistent
|
|
||||||
between the two mock feature areas.
|
|
||||||
|
|
||||||
- List: search, status filter, type filter (payment/refund/qr_payment),
|
|
||||||
pagination, CSV export.
|
|
||||||
- Retry failed transactions (`status: 'failed' -> 'retried'`, appends an
|
|
||||||
audit entry).
|
|
||||||
- Fraud flag toggle per transaction.
|
|
||||||
- Audit log: each transaction carries its own `audit: AdminTransactionAuditEntry[]`
|
|
||||||
(creation, retries, fraud-flag changes), viewed via a dialog - this is a
|
|
||||||
per-transaction audit trail, not the system-wide audit/security log
|
|
||||||
planned for Sprint 26 (Monitoring); the two are intentionally separate
|
|
||||||
scopes.
|
|
||||||
- Wired into `/:lang/backoffice/transactions`, replacing the coming-soon
|
|
||||||
placeholder.
|
|
||||||
|
|
||||||
## Sprint 25 - Users & Roles (mock/local)
|
|
||||||
|
|
||||||
`features/admin/users/`. Single consolidated page (`admin-users-page`) at
|
|
||||||
`/:lang/backoffice/users` - not previously in the Quick Actions list or
|
|
||||||
routes at all, this is a net-new admin section.
|
|
||||||
|
|
||||||
- **Users**: name, Telegram username, `scope` (`marketplace` vs `office`
|
|
||||||
admin - distinguishes tenant-level owners/admins from internal staff),
|
|
||||||
role, status (`active`/`invited`/`suspended`), last login. Role change is
|
|
||||||
an inline `<select>`; suspend/reactivate is confirm-gated for suspend
|
|
||||||
only.
|
|
||||||
- **Roles/permissions**: 4 built-in roles (`owner`/`admin`/`editor`/`viewer`)
|
|
||||||
with a flat permission-string list (`products.manage`, `*` for owner,
|
|
||||||
etc.) - a real permission catalog and custom-role creation don't exist,
|
|
||||||
intentionally scoped down to what's needed to demonstrate the model.
|
|
||||||
- **Invitations**: email + role + scope form, pending list with revoke.
|
|
||||||
No email actually sends - `AdminUsersLocalGateway.inviteUser()` only
|
|
||||||
creates the local record.
|
|
||||||
- **Passwordless login**: already existed before this sprint -
|
|
||||||
`AdminAuthService`'s Telegram QR flow (`docs/ADMIN.md`'s existing admin
|
|
||||||
login section, `docs/BACKEND_API.md#25-the-admin-authorization-gap-critical--security-relevant-unresolved`). This sprint's Users page links
|
|
||||||
to it via a hint, doesn't reimplement it.
|
|
||||||
- **Session manager / device manager**: per-user session list (device, IP,
|
|
||||||
last active, current-session badge) with per-session revoke, mocked
|
|
||||||
(`AdminUsersLocalGateway.loadSessions()` fabricates 2 sessions per user
|
|
||||||
on first view) - the real `AdminAuthService`/session-cookie flow only
|
|
||||||
ever tracks the *current* browser's session, so multi-device session
|
|
||||||
listing has no real backend counterpart yet (see `docs/BACKEND_API.md#25-the-admin-authorization-gap-critical--security-relevant-unresolved`).
|
|
||||||
- **Audit**: per-user audit log (role/status changes), same dialog pattern
|
|
||||||
as Sprint 24's per-transaction audit - not the system-wide security/audit
|
|
||||||
log planned for Sprint 26.
|
|
||||||
- Wired into `AdminDashboardFacade`'s Quick Actions list (`dashboard.actionUsers`
|
|
||||||
-> `/:lang/backoffice/users`).
|
|
||||||
|
|
||||||
## Sprint 26 - Monitoring (mock/local, health reuses real data)
|
|
||||||
|
|
||||||
`features/admin/monitoring/`, single page at `/:lang/backoffice/monitoring`
|
|
||||||
(new Dashboard Quick Action).
|
|
||||||
|
|
||||||
- **Health**: reuses `AdminDashboardFacade.healthChecks` directly (the same
|
|
||||||
real, non-mocked bootstrap-validation checks from Sprint 19's dashboard)
|
|
||||||
instead of duplicating the logic - this is the one section on this page
|
|
||||||
backed by real data.
|
|
||||||
- **Audit / security / login / failed-login / API / error / warning
|
|
||||||
events**: one unified `AdminMonitoringEvent` feed (`category` + `level`
|
|
||||||
discriminators) with category filter + search, seeded with 40
|
|
||||||
deterministic synthetic entries by `AdminMonitoringLocalGateway` - no
|
|
||||||
logging backend exists anywhere in this system, so there is nothing real
|
|
||||||
to read from.
|
|
||||||
- **Queue monitoring**: 3 mock named queues with depth + status.
|
|
||||||
- **Webhook monitoring**: mock delivery log (endpoint/event/status/time).
|
|
||||||
- This is deliberately a separate, system-wide log from the two
|
|
||||||
narrower-scoped audit trails added earlier: Sprint 24's per-transaction
|
|
||||||
audit and Sprint 25's per-user audit. No consolidation attempted - they
|
|
||||||
track different things.
|
|
||||||
|
|
||||||
## Sprint 27 - Analytics
|
|
||||||
|
|
||||||
`features/admin/analytics/`, net-new `/:lang/backoffice/analytics` route
|
|
||||||
+ Dashboard Quick Action.
|
|
||||||
|
|
||||||
- **Real, derived data**: revenue/orders/avg-order-value/sales-over-time
|
|
||||||
chart/top-products are computed by composing the existing
|
|
||||||
`AdminOrdersLocalGateway` (Sprint 23's seeded mock orders) - not a
|
|
||||||
separate fabricated dataset. Products/Categories counts come from
|
|
||||||
`AdminProductsLocalGateway`/`AdminCategoriesLocalGateway`. All of this is
|
|
||||||
still ultimately backed by mock order/product/category data (per those
|
|
||||||
sprints), but the *aggregation* is real arithmetic over that data, not
|
|
||||||
invented numbers.
|
|
||||||
- **Visitors, funnels, heatmaps**: no analytics/tracking pipeline exists
|
|
||||||
anywhere in this codebase, so these render an explicit
|
|
||||||
"Awaiting backend integration" (`pending-backend`) badge, same convention
|
|
||||||
as the Sprint 19 dashboard's Orders/Revenue cards before Sprint 23 -
|
|
||||||
not fabricated numbers, not a generic empty state.
|
|
||||||
- **Chart**: a plain inline `<div>`-bar chart driven by `[style.height.%]`,
|
|
||||||
no charting library pulled in - reasonable for one sales-over-time series
|
|
||||||
at this scale; revisit if more chart types are actually needed.
|
|
||||||
- **Date ranges**: 7/30/90-day toggle filters orders by `createdAt`.
|
|
||||||
- **Export**: CSV of the sales series (client-side `Blob` download, same
|
|
||||||
pattern as Orders/Transactions).
|
|
||||||
|
|
||||||
## Sprint 28 - Marketplace Polish
|
|
||||||
|
|
||||||
Full scope per `docs/SPRINT-PLAN.md`: Lighthouse/a11y sweep, animations,
|
|
||||||
skeleton/empty/error state consistency, responsive fixes, SEO/meta/social
|
|
||||||
preview/robots/sitemap. Landed across two commits in the same session (an
|
|
||||||
earlier, narrower "admin/*-only" pass, then this session's follow-up
|
|
||||||
completing the rest of the brief) - this section describes the combined,
|
|
||||||
final result, not just the later commit.
|
|
||||||
|
|
||||||
- **Design-system consistency (skeleton/empty states)**: audited every
|
|
||||||
admin section built in Sprints 20-27 against the shared `app-skeleton` /
|
|
||||||
`app-empty-state` primitives (`shared/ui/skeleton`, `shared/ui/empty-state`,
|
|
||||||
see their own "add reusable ... primitive" commits). Before this sprint,
|
|
||||||
`admin/products`, `admin/users`, `admin/monitoring`, and `admin/analytics`
|
|
||||||
had a `loading` facade signal that was never read in the template (blank
|
|
||||||
table during fetch, no empty-state fallback); `admin/categories`,
|
|
||||||
`admin/orders`, `admin/transactions`, and the media library already had
|
|
||||||
`app-empty-state` but no loading skeleton; `admin/dashboard`'s card
|
|
||||||
component used a hand-rolled shimmer `<div>` + ad-hoc `<p>` text that
|
|
||||||
pre-dated the shared primitives. Fixed: all eight now show `app-skeleton`
|
|
||||||
rows/cards while `loading()` is true, then either `app-empty-state` (new
|
|
||||||
`adminProducts.emptyTitle`/`adminUsers.emptyTitle`/
|
|
||||||
`adminMonitoring.eventsEmptyTitle`/`adminAnalytics.topProductsEmptyTitle`
|
|
||||||
+ description keys added to `translations.ts`/`en.ts`/`ru.ts`/`hy.ts`) or
|
|
||||||
the populated table. `admin-dashboard-card.component.html`'s loading case
|
|
||||||
now renders `<app-skeleton shape="rect" height="24px" width="60%" />`
|
|
||||||
instead of its own shimmer CSS (removed the now-dead
|
|
||||||
`dashboard-card__skeleton` rule + keyframes). Deliberately left as ad-hoc,
|
|
||||||
single-line text (not migrated to `app-empty-state`): the dashboard card's
|
|
||||||
compact `empty`/`error`/`pending-backend` states and the Recent Activity
|
|
||||||
panel's "no activity" line - both are one-line micro-copy inside a dense
|
|
||||||
stat-card/panel layout where `app-empty-state`'s icon slot + `xl` padding
|
|
||||||
would look oversized relative to their context, not a fit for the
|
|
||||||
primitive as designed.
|
|
||||||
- **Accessibility**: every bare `<select>` across `admin/categories`,
|
|
||||||
`admin/products`, `admin/orders`, `admin/transactions`, `admin/users`,
|
|
||||||
and `admin/monitoring` that wasn't already inside a `<label>` (which
|
|
||||||
provides implicit association) now has an explicit `aria-label`. Selects
|
|
||||||
already nested in `<label>` (e.g. product form's category/stock-status
|
|
||||||
selects, category form's parent select) were left as-is - already
|
|
||||||
correct. Manual audit otherwise: `DialogComponent` (`shared/ui/dialog/`)
|
|
||||||
already had a real focus trap, Escape-to-close, `aria-modal`, and
|
|
||||||
`aria-label` from an earlier sprint - no changes needed. Every `<img>` in
|
|
||||||
`src/app/**` was checked for missing `alt` (grepped for `<img` without an
|
|
||||||
`alt`/`[alt]`/`[attr.alt]` binding) - none found; all images already have
|
|
||||||
real or bound alt text.
|
|
||||||
- **Animations**: added a global `prefers-reduced-motion: reduce` override
|
|
||||||
in `src/styles.scss` that neutralizes animation/transition durations and
|
|
||||||
smooth-scroll everywhere, so the many existing hover transforms
|
|
||||||
(`.card:hover`, `.btn:hover`, `.product-card:hover`), the `.section`
|
|
||||||
fade-in, and every skeleton shimmer respect the OS accessibility setting
|
|
||||||
in one place, rather than requiring each component to opt in individually
|
|
||||||
(a few, like `shared/ui/skeleton`, already had their own local override).
|
|
||||||
- **SEO**: `SeoService.resetToDefaults()` (`src/app/services/seo.service.ts`)
|
|
||||||
previously hardcoded the site-wide `<title>`/description/OG/Twitter
|
|
||||||
defaults (including a reference to a nonexistent `/og-image.jpg`)
|
|
||||||
regardless of tenant. It now reads the real `bootstrap.seo.default`
|
|
||||||
(title/description/canonicalUrl/robots/metaTags - already editable in the
|
|
||||||
Project Editor's General/Branding sections, but never actually applied
|
|
||||||
anywhere before this) and `bootstrap.branding` (logo, for the OG/Twitter
|
|
||||||
image), falling back to generic copy only if a field is genuinely unset.
|
|
||||||
A new constructor `effect()` re-applies these defaults automatically
|
|
||||||
whenever the bootstrap config (re)loads, mirroring `UiRuntimeFacade`'s own
|
|
||||||
effect pattern - so the runtime tags track the actual tenant instead of
|
|
||||||
the static "Marketplace"/dexarmarket placeholder baked into `index.html`
|
|
||||||
(which remains as the pre-JS/no-JS-crawler fallback only, unavoidable
|
|
||||||
without SSR).
|
|
||||||
- **Sitemap/robots**: added `public/sitemap.xml` (new) with the statically-
|
|
||||||
known top-level marketplace routes (home/catalog/search/wishlist/compare)
|
|
||||||
for the default `ru` locale segment, referenced from a new `Sitemap:`
|
|
||||||
directive in `public/robots.txt` (which also now blocks
|
|
||||||
`/*/backoffice`, `/*/edit`, `/*/project-editor`, and `/__diagnostics`
|
|
||||||
from crawling). Documented limitation (not faked): this is a config-driven,
|
|
||||||
multi-tenant platform - locales/categories/products/static pages are only
|
|
||||||
known at runtime per tenant, not enumerable client-side at build time. A
|
|
||||||
real per-tenant sitemap needs a backend/build-time generator - see
|
|
||||||
`docs/BACKEND_API.md#619-sitemap-future--static-baseline-only-today`.
|
|
||||||
- **Responsive**: spot-checked the admin backoffice and customer-facing
|
|
||||||
marketplace at mobile/tablet/desktop widths. `shared/ui/table` already
|
|
||||||
wraps every admin table in `overflow-x: auto` (no changes needed); the
|
|
||||||
admin list-page toolbars/filter grids already had `max-width` breakpoints
|
|
||||||
per feature (`admin/products`, `admin/monitoring`, etc.) - added the same
|
|
||||||
`.skeleton-rows` grid class alongside those existing breakpoints rather
|
|
||||||
than introducing a new layout system.
|
|
||||||
- **Lighthouse**: no live browser/Lighthouse run in this environment (same
|
|
||||||
constraint noted in every prior sprint's admin verification - the guarded
|
|
||||||
admin route is blocked from live click-through here); the SEO/a11y/
|
|
||||||
animation items above are the manual-audit equivalent of what a
|
|
||||||
Lighthouse pass would flag (missing meta tags, missing alt text, motion
|
|
||||||
without a reduced-motion fallback, missing loading feedback).
|
|
||||||
- **Bundle size**: the `700 kB` initial-bundle budget warning (~198 kB over,
|
|
||||||
configured in `angular.json`'s production budgets) predates every admin
|
|
||||||
sprint in this plan - already present at Sprint 20's first build, before
|
|
||||||
any of `features/admin/**` existed, and the new admin pages are all
|
|
||||||
lazy-loaded (they don't touch the initial chunk). Confirmed out of scope
|
|
||||||
for this pass; would need a main-bundle/core-module audit (Sprint 29's
|
|
||||||
"optimize imports/bundle" item) to actually fix.
|
|
||||||
- **Found but deferred to Sprint 29** (see `docs/KNOWN-ISSUES.md`): almost
|
|
||||||
every string across `admin/products`/`admin/categories`/`admin/orders`/
|
|
||||||
`admin/transactions`/`admin/users`/`admin/monitoring`/`admin/analytics`
|
|
||||||
(~178 distinct `adminXxx.*` translate-pipe keys) has no corresponding
|
|
||||||
entry in `translations.ts`/`en.ts`/`ru.ts`/`hy.ts` and renders as a raw
|
|
||||||
key string - the same bug class as the dashboard Quick Actions fix in
|
|
||||||
`1db63ac`, at much larger scale. Sprint 28 only adds the small number of
|
|
||||||
new keys its own empty-state work introduces (see above); authoring the
|
|
||||||
full ~178-key backfill is Sprint 29's explicit "translation validation"
|
|
||||||
scope, not squeezed into this polish pass.
|
|
||||||
|
|
||||||
## Bug-hunt audit pass (2026-07-17)
|
|
||||||
|
|
||||||
Same method as the project-editor audit (`docs/EDITOR.md`'s "Bug-hunt audit
|
|
||||||
pass" section): read `admin/products` and `admin/categories` end to end
|
|
||||||
(facades, gateways, form factories, guards, presentational components), find
|
|
||||||
real reproducible bugs (not cosmetic nitpicks), reproduce each live via
|
|
||||||
`window.ng.getComponent()` on `/:lang/backoffice/{products,categories}/...
|
|
||||||
?devBypassAdmin=true` before fixing, re-verify after. The real backend is
|
|
||||||
unreachable in this environment (same constraint as every prior admin
|
|
||||||
sprint's verification note) - `AdminCategoriesLocalGateway`/
|
|
||||||
`AdminProductsLocalGateway` sit behind `BackofficeDataService`, which itself
|
|
||||||
calls out to an HTTP provider that 404s here, so both facades' `loadList()`
|
|
||||||
error handlers reset to an empty array. Where the list couldn't populate via
|
|
||||||
the real click-through, bugs were reproduced by seeding
|
|
||||||
`facade.categories.set([...])`/`facade.products.set([...])` directly with
|
|
||||||
synthetic rows and driving the exact same facade methods the UI calls - the
|
|
||||||
gateway calls captured are identical either way, since the facade doesn't
|
|
||||||
branch on how its signals got populated.
|
|
||||||
|
|
||||||
Found 2 real bugs in `admin/categories`, both fixed:
|
|
||||||
|
|
||||||
- **Create-category draft recovery was permanently dead + leaked
|
|
||||||
`localStorage` forever.** `AdminCategoriesFacade.startCreate()` generated
|
|
||||||
the draft's id via `category-${Date.now()}` and read/wrote its autosave
|
|
||||||
entry under `admin-category-draft:<that id>`. Since the id is different
|
|
||||||
every single call, a draft written during one "create category" visit can
|
|
||||||
never be found by a later `startCreate()` call (even seconds later, same
|
|
||||||
tab) - the recovery feature the sprint 20 changelog describes ("the editor
|
|
||||||
reloads that draft ahead of the saved value if present") never actually
|
|
||||||
triggered for new categories, only for edits (stable real `id`). Every
|
|
||||||
abandoned create attempt also left an orphaned, never-cleaned
|
|
||||||
`localStorage` entry. Fixed by tracking a `draftStorageKey` field on the
|
|
||||||
facade, set to a fixed `admin-category-draft:new` key in create mode
|
|
||||||
(stable across calls) and to `admin-category-draft:<id>` in edit mode
|
|
||||||
(unchanged, already correct); `saveDraft()`/`discardDraftRecovery()` clear
|
|
||||||
whichever key is current instead of re-deriving it from the (possibly
|
|
||||||
stale) draft id.
|
|
||||||
- Verified live: `updateDraft({title})` -> localStorage key
|
|
||||||
`admin-category-draft:category-<ts1>`; calling `startCreate()` again
|
|
||||||
(simulating navigate-away/back) generated `category-<ts2>` and recovered
|
|
||||||
nothing (`title` reset to `''`, `dirty=false`, old key orphaned). After
|
|
||||||
the fix, the same sequence recovers the title/dirty state correctly under
|
|
||||||
the stable key, and `saveDraft()` clears it.
|
|
||||||
- **Drag-and-drop category reordering silently did nothing (or moved items
|
|
||||||
to the wrong spot) because it wrote duplicate `order` values instead of
|
|
||||||
repositioning.** `AdminCategoriesFacade.reorder(id, targetOrder)` took the
|
|
||||||
dropped-on row's numeric `order` and wrote that exact value onto the
|
|
||||||
dragged category - leaving two siblings tied on the same `order` instead of
|
|
||||||
actually reordering. `AdminCategoriesLocalGateway.loadCategories()` sorts
|
|
||||||
by `left.order - right.order` using `Array.prototype.sort` (stable), so
|
|
||||||
ties break by original array position, not by drop intent - some drags
|
|
||||||
silently no-op. Worse, every seeded category starts at `order: 0`
|
|
||||||
(`AdminCategoriesLocalGateway.toAdminCategory`), so on fresh data *every*
|
|
||||||
drag was a no-op: dropping item C onto item A sent `{ id: 'c', order: 0 }`,
|
|
||||||
which was already A's (and C's) value. Fixed by changing the drag payload
|
|
||||||
to carry the target's `id` (not its ambiguous/duplicable `order` value);
|
|
||||||
`reorder(id, targetId)` now computes the full same-parent sibling sequence
|
|
||||||
with the dragged item spliced into the target's position and persists
|
|
||||||
sequential `0..n-1` order values for every sibling whose order actually
|
|
||||||
changed. Cross-parent drops (`dragged.parentId !== target.parentId`) are a
|
|
||||||
no-op, matching the tree UI's existing scope (no reparent-via-drag support
|
|
||||||
before or after this fix). Updated end to end:
|
|
||||||
`AdminCategoriesListComponent`'s `reorder` output now emits
|
|
||||||
`{ id, targetId }` instead of `{ id, targetOrder }`; the list page binding
|
|
||||||
follows.
|
|
||||||
- Verified live: seeded 3 siblings with distinct orders (0/1/2), dragged
|
|
||||||
the last onto the first. Before the fix, the gateway only received
|
|
||||||
`{ id: 'c', order: 0 }` (tying `a` and `c`). After the fix, the gateway
|
|
||||||
receives the correct 3-way reshuffle: `c:0, a:1, b:2`.
|
|
||||||
|
|
||||||
A third bug, found in the same pass, was fixed in a follow-up commit:
|
|
||||||
`admin-product-form.component` and `admin-category-form.component` both
|
|
||||||
hardcoded their translation-tab locales to `['en', 'ru', 'hy']` instead of
|
|
||||||
reading the tenant's actual configured `supportedLocales` (which live on
|
|
||||||
`ProjectEditorFacade.bootstrap()`, the same source
|
|
||||||
`static-pages-editor.component.ts` already reads correctly) - neither
|
|
||||||
`AdminProductsFacade` nor `AdminCategoriesFacade` depended on project-editor
|
|
||||||
state at all before this. Fixed by giving both facades a `supportedLocales`
|
|
||||||
computed (`bootstrap()?.localization.supportedLocales ?? ['en']`) and an
|
|
||||||
`ensureLocalesLoaded()` that calls `ProjectEditorFacade.loadBootstrap()` if
|
|
||||||
it hasn't loaded yet (same lazy-load pattern
|
|
||||||
`AdminDashboardFacade.ensureLoaded()` already uses for the same dependency);
|
|
||||||
both editor pages call it in their constructor and pass
|
|
||||||
`[locales]="facade.supportedLocales()"` down to the form components, which
|
|
||||||
now iterate a `locales: string[]` `@Input()` instead of the literal array.
|
|
||||||
Verified live: both `facade.supportedLocales()` and the form's bound
|
|
||||||
`locales` changed from the hardcoded `['en','ru','hy']` to the real tenant
|
|
||||||
order `['ru','en','hy']` (default locale first), confirmed by the rendered
|
|
||||||
tab order in both editors.
|
|
||||||
|
|
||||||
The already-documented, deliberately-scoped-down items from earlier sprints
|
|
||||||
(related-products picker limited to the current page, not a full catalog
|
|
||||||
search; the ~178 untranslated `adminXxx.*` i18n keys) were re-confirmed
|
|
||||||
during this pass and are unchanged - see their existing sections above and
|
|
||||||
`docs/KNOWN-ISSUES.md`.
|
|
||||||
|
|
||||||
## Known gaps / backend needs
|
|
||||||
|
|
||||||
- **Dashboard metrics endpoint.** Categories/Products counts are computed
|
|
||||||
client-side from `BackofficeDataService` (itself mock/API-switchable via
|
|
||||||
`BACKOFFICE_DATA_PROVIDER`). A dedicated `/builder/dashboard/summary`-style
|
|
||||||
endpoint would let `AdminDashboardMetricsGateway` return richer data
|
|
||||||
(real-time counts, trend deltas) without touching the facade or cards.
|
|
||||||
- **Orders/Revenue have no backend at all** (see above) - needs an order
|
|
||||||
domain and revenue aggregation before these cards can show real data.
|
|
||||||
- **Recent Activity is local-only**, scoped to the browser/tenant via
|
|
||||||
localStorage (`adminDashboard.activityHistory.v1`), same limitation as the
|
|
||||||
existing draft-save local storage. It will not show another editor's
|
|
||||||
activity until a real audit-log endpoint exists.
|
|
||||||
- **Admin authorization is still not enforced server-side** (see
|
|
||||||
`Project-Editor.md` - "Admin Authentication" section); this sprint does not
|
|
||||||
change that. Nothing new here beyond routing/dashboard.
|
|
||||||
@@ -1,274 +0,0 @@
|
|||||||
> **ARCHIVED 2026-07-26.** Superseded by [`docs/BACKEND_INTEGRATION.md`](../BACKEND_INTEGRATION.md), the single canonical backend integration document. Kept for history only — do not implement against this file.
|
|
||||||
|
|
||||||
# Admin Authentication — Ed25519 Foundation
|
|
||||||
|
|
||||||
Status: **FRONTEND PREPARED, NOT LIVE.** Everything in this document describes
|
|
||||||
code that exists in `src/app/core/auth/` today, wired to endpoints that do
|
|
||||||
not exist on the backend yet. No route currently requires this flow — the
|
|
||||||
live admin gate remains the Telegram-QR-based `AdminAuthService` /
|
|
||||||
`adminAuthGuard` (`src/app/core/admin-auth/`, documented in
|
|
||||||
`docs/BACKEND_API.md` §2.4–2.5). This module is the
|
|
||||||
integration target once the backend ships the endpoints below.
|
|
||||||
|
|
||||||
Do not point any live route's `canActivate` at `ed25519AuthGuard` until the
|
|
||||||
backend endpoints in §API Contracts exist and have been verified — doing so
|
|
||||||
before then would lock every admin out.
|
|
||||||
|
|
||||||
## 1. Why this exists
|
|
||||||
|
|
||||||
`docs/BACKEND_API.md` §2.5 documents the current system's
|
|
||||||
biggest security gap: admin and customer login hit the *same* Telegram
|
|
||||||
session endpoint, so the backend has no way to distinguish an admin login
|
|
||||||
attempt from a customer one at the moment of login — authorization is
|
|
||||||
effectively unenforced. Ed25519 challenge/response auth closes this by
|
|
||||||
requiring proof of possession of a specific, pre-registered private key
|
|
||||||
before a session is ever issued, instead of "any Telegram account that
|
|
||||||
happened to scan the right QR code."
|
|
||||||
|
|
||||||
## 2. Sequence diagram
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
sequenceDiagram
|
|
||||||
participant Admin as Admin (browser)
|
|
||||||
participant FE as Frontend (AuthService)
|
|
||||||
participant BE as Backend
|
|
||||||
|
|
||||||
Admin->>FE: Click "Sign in"
|
|
||||||
FE->>BE: GET /api/admin/auth/challenge
|
|
||||||
BE-->>FE: { nonce, issuedAt, expiresAt }
|
|
||||||
FE->>FE: Ed25519KeypairService.sign(nonce)<br/>(WebCrypto, non-extractable private key)
|
|
||||||
FE->>BE: POST /api/admin/auth/verify<br/>{ publicKey, signature, nonce }
|
|
||||||
alt signature valid & publicKey is a provisioned admin key
|
|
||||||
BE-->>FE: 200 { token, refreshToken }
|
|
||||||
FE->>FE: SessionService.activate(tokens)<br/>decode JWT claims, schedule refresh
|
|
||||||
FE-->>Admin: Redirect to /backoffice
|
|
||||||
else invalid signature / unknown key / expired nonce
|
|
||||||
BE-->>FE: 401/403
|
|
||||||
FE-->>Admin: Redirect to /admin-login/error/invalid-signature
|
|
||||||
end
|
|
||||||
```
|
|
||||||
|
|
||||||
### Refresh sequence
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
sequenceDiagram
|
|
||||||
participant FE as Frontend (SessionService)
|
|
||||||
participant IC as authInterceptor
|
|
||||||
participant BE as Backend
|
|
||||||
|
|
||||||
Note over FE: Timer fires ~60s before JWT exp
|
|
||||||
FE->>BE: POST /api/admin/auth/refresh { refreshToken }
|
|
||||||
alt refresh token still valid
|
|
||||||
BE-->>FE: 200 { token, refreshToken }
|
|
||||||
FE->>FE: activate(tokens) - reschedules next refresh
|
|
||||||
else refresh token expired/revoked
|
|
||||||
BE-->>FE: 401
|
|
||||||
FE->>FE: SessionService.markExpired()
|
|
||||||
FE-->>FE: Route to /admin-login/error/session-expired
|
|
||||||
end
|
|
||||||
|
|
||||||
Note over IC: Reactive path - any 401 on an admin request
|
|
||||||
IC->>BE: Admin API request (expired token)
|
|
||||||
BE-->>IC: 401
|
|
||||||
IC->>BE: POST /api/admin/auth/refresh (single retry)
|
|
||||||
alt refresh succeeds
|
|
||||||
BE-->>IC: 200 tokens
|
|
||||||
IC->>BE: Retry original request with new token
|
|
||||||
else refresh fails
|
|
||||||
IC-->>FE: Propagate error, route to session-expired
|
|
||||||
end
|
|
||||||
```
|
|
||||||
|
|
||||||
## 3. Ed25519 flow, step by step
|
|
||||||
|
|
||||||
1. **Key generation (once per device):** `Ed25519KeypairService.getOrCreateKeyPair()`
|
|
||||||
generates a non-extractable Ed25519 keypair via `crypto.subtle.generateKey`
|
|
||||||
and persists the `CryptoKey` handles in IndexedDB (`admin-auth-ed25519` DB).
|
|
||||||
The private key is never exported, serialized, or transmitted — by
|
|
||||||
construction, not by convention.
|
|
||||||
2. **Registering the public key with the backend is out of scope for this
|
|
||||||
frontend.** An Owner/Administrator must associate a new device's
|
|
||||||
`publicKeyBase64` with an admin account through some out-of-band
|
|
||||||
mechanism (e.g. a backend admin tool, a one-time enrollment link) before
|
|
||||||
that device can complete step 4. This document does not prescribe that
|
|
||||||
mechanism — it is a backend/ops concern.
|
|
||||||
3. **Challenge:** `GET /api/admin/auth/challenge` returns a fresh `nonce` the
|
|
||||||
client must sign before `expiresAt`.
|
|
||||||
4. **Sign:** the raw `nonce` string is signed with the device's private key
|
|
||||||
(`Ed25519KeypairService.sign`), producing a base64 signature.
|
|
||||||
5. **Verify:** `POST /api/admin/auth/verify` sends `{ publicKey, signature,
|
|
||||||
nonce }`. The backend re-derives the signed message from the nonce it
|
|
||||||
issued, verifies the signature against its own record of that
|
|
||||||
`publicKey → admin account` mapping, and only then issues tokens.
|
|
||||||
6. **Session:** the returned `{ token, refreshToken }` pair is stored
|
|
||||||
(`SessionService`, `localStorage: ed25519AdminToken` /
|
|
||||||
`ed25519AdminRefreshToken`) and the JWT is decoded client-side for
|
|
||||||
`role`/`exp` — decoding only, never signature verification (the frontend
|
|
||||||
has no trusted key to check it against).
|
|
||||||
|
|
||||||
## 4. API contracts
|
|
||||||
|
|
||||||
All under `{environment.authApiUrl}/api/admin/auth` (see
|
|
||||||
`src/environments/environment.ts`). None of these exist on the backend
|
|
||||||
today — this is the contract the frontend was built against, not a
|
|
||||||
confirmed backend spec.
|
|
||||||
|
|
||||||
| Method | Path | Request body | Response | Notes |
|
|
||||||
|---|---|---|---|---|
|
|
||||||
| GET | `/challenge` | — | `200 AuthChallenge` | `{ nonce, issuedAt, expiresAt }`, all ISO 8601 except `nonce` |
|
|
||||||
| POST | `/verify` | `VerifySignatureRequest` | `200 AuthTokenPair` \| `401` \| `403` | `{ publicKey, signature, nonce }` → `{ token, refreshToken }` |
|
|
||||||
| POST | `/refresh` | `RefreshTokenRequest` | `200 AuthTokenPair` \| `401` | `{ refreshToken }` → new pair (rotation expected — old refresh token should be invalidated server-side) |
|
|
||||||
| POST | `/logout` | `{ refreshToken }` | `204` | Should revoke the refresh token server-side; frontend clears local state regardless of response |
|
|
||||||
|
|
||||||
Types: `src/app/core/auth/models/auth-api.model.ts`.
|
|
||||||
|
|
||||||
## 5. JWT claims
|
|
||||||
|
|
||||||
```ts
|
|
||||||
interface JwtClaims {
|
|
||||||
sub: string; // admin account id
|
|
||||||
role: AdminRole; // 'Owner' | 'Administrator' | 'Editor' | 'Support' | 'ReadOnly'
|
|
||||||
iat: number; // seconds since epoch
|
|
||||||
exp: number; // seconds since epoch
|
|
||||||
publicKey: string; // the Ed25519 public key this token was issued for
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
The frontend decodes these (`JwtService.decode`) for UX only — role-based UI
|
|
||||||
gating, expiry countdowns, refresh scheduling. **Every admin API request
|
|
||||||
must be independently authorized server-side**; a decoded-but-unverified
|
|
||||||
claim is not proof of anything to the backend.
|
|
||||||
|
|
||||||
## 6. Permission model
|
|
||||||
|
|
||||||
Five roles, coarse-grained permission keys (`src/app/core/auth/models/permission.model.ts`):
|
|
||||||
|
|
||||||
| Role | Permissions |
|
|
||||||
|---|---|
|
|
||||||
| Owner | `backoffice.read`, `backoffice.write`, `builder.read`, `builder.write`, `users.manage`, `settings.manage` |
|
|
||||||
| Administrator | `backoffice.read`, `backoffice.write`, `builder.read`, `builder.write`, `users.manage` |
|
|
||||||
| Editor | `backoffice.read`, `backoffice.write`, `builder.read`, `builder.write` |
|
|
||||||
| Support | `backoffice.read` |
|
|
||||||
| ReadOnly | `backoffice.read`, `builder.read` |
|
|
||||||
|
|
||||||
This is deliberately coarse and mirrors the existing bootstrap-level
|
|
||||||
`PermissionsConfig` shape (`src/app/shared/models/config/permissions.model.ts`).
|
|
||||||
Finer-grained, per-domain permissions (e.g. "can edit prices but not delete
|
|
||||||
products") stay server-side until a real permission model exists there —
|
|
||||||
see `docs/BACKEND_API.md` §"Admin-role-required". Use
|
|
||||||
`PermissionService.has(permission)` / `permissionGuard(permission)` to gate
|
|
||||||
UI and routes; never treat a passing client-side check as authorization by
|
|
||||||
itself.
|
|
||||||
|
|
||||||
## 7. Error screens
|
|
||||||
|
|
||||||
Single component (`AuthErrorPageComponent`, `/admin-login/error/:code`)
|
|
||||||
renders all five, keyed by route param:
|
|
||||||
|
|
||||||
| Code | Trigger | User action offered |
|
|
||||||
|---|---|---|
|
|
||||||
| `session-expired` | Refresh token rejected/expired | Sign in again |
|
|
||||||
| `invalid-signature` | `verify` returns 401/403 during login | Try again |
|
|
||||||
| `unauthorized` | Route guard sees no active session | Sign in |
|
|
||||||
| `forbidden` | `permissionGuard` denies (authenticated but insufficient role) | Back to dashboard |
|
|
||||||
| `backend-unavailable` | Network error / 5xx / status 0 | Retry |
|
|
||||||
|
|
||||||
`authErrorCodeFromStatus` (`models/auth-error.model.ts`) maps HTTP status →
|
|
||||||
code: `401→unauthorized`, `403→forbidden`, `0→backend-unavailable`,
|
|
||||||
`5xx→backend-unavailable`, else `unauthorized`. `AuthService.login()`
|
|
||||||
additionally maps any failure during the challenge/sign/verify sequence to
|
|
||||||
`invalid-signature` when it isn't a clearer HTTP-status-derived code.
|
|
||||||
|
|
||||||
## 8. Refresh lifecycle
|
|
||||||
|
|
||||||
- On `SessionService.activate(tokens)`, a timer is scheduled for
|
|
||||||
`max(exp - now - 60s, 5s)` — refresh fires ~60 seconds before expiry so a
|
|
||||||
concurrent request never races an expiring token.
|
|
||||||
- **Proactive path:** the timer fires `AuthService.refresh()` directly.
|
|
||||||
- **Reactive path:** `authInterceptor` catches a 401 on any admin-gated
|
|
||||||
request, attempts one `refresh()`, retries the original request once on
|
|
||||||
success, and routes to `session-expired` on failure. It does not retry
|
|
||||||
more than once — a second 401 after a successful-looking refresh means
|
|
||||||
something is wrong server-side, not a transient race.
|
|
||||||
- `SessionService.restore()` runs on app bootstrap (call
|
|
||||||
`AuthFacade.restoreSession()` from an app initializer once this flow goes
|
|
||||||
live) — reads persisted tokens, decodes claims, and either resumes with a
|
|
||||||
scheduled refresh or marks `expired` without any network call, so a stale
|
|
||||||
session is caught before it reaches any component.
|
|
||||||
|
|
||||||
## 9. Module map
|
|
||||||
|
|
||||||
```
|
|
||||||
src/app/core/auth/
|
|
||||||
├── auth.routes.ts # /admin-login, /admin-login/error/:code
|
|
||||||
├── models/
|
|
||||||
│ ├── auth-api.model.ts # AuthChallenge, VerifySignatureRequest, AuthTokenPair, JwtClaims
|
|
||||||
│ ├── auth-error.model.ts # AuthErrorCode, authErrorCodeFromStatus()
|
|
||||||
│ └── permission.model.ts # AdminRole, Permission, ROLE_PERMISSIONS
|
|
||||||
├── services/
|
|
||||||
│ ├── ed25519-keypair.service.ts # WebCrypto keygen/sign, IndexedDB persistence
|
|
||||||
│ ├── auth-api.service.ts # HttpClient calls to the 4 endpoints in §4
|
|
||||||
│ ├── jwt.service.ts # decode-only JWT parsing
|
|
||||||
│ ├── session.service.ts # token/claims state, persistence, refresh scheduling
|
|
||||||
│ ├── permission.service.ts # role -> permission set
|
|
||||||
│ ├── auth.service.ts # orchestrates challenge -> sign -> verify -> refresh -> logout
|
|
||||||
│ └── auth-facade.service.ts # public surface for components
|
|
||||||
├── interceptors/
|
|
||||||
│ └── auth.interceptor.ts # Authorization: Bearer + 401 refresh-and-retry
|
|
||||||
├── guards/
|
|
||||||
│ ├── ed25519-auth.guard.ts # requires SessionService.isAuthenticated()
|
|
||||||
│ └── permission.guard.ts # permissionGuard(permission) factory
|
|
||||||
└── pages/
|
|
||||||
├── admin-login-page.component.* # sign-in UI
|
|
||||||
└── auth-error-page.component.* # parameterized error screen (§7)
|
|
||||||
```
|
|
||||||
|
|
||||||
`AuthFacade` is the only thing components/pages should depend on;
|
|
||||||
`AuthService`/`SessionService`/`PermissionService` are internal
|
|
||||||
collaborators reachable through it.
|
|
||||||
|
|
||||||
## 10. Cutover plan (when the backend ships)
|
|
||||||
|
|
||||||
1. Verify the four endpoints in §4 against a real backend, including error
|
|
||||||
shapes.
|
|
||||||
2. Register `authInterceptor` in `app.config.ts`'s `withInterceptors([...])`
|
|
||||||
list (currently not registered).
|
|
||||||
3. Decide the relationship to the existing Telegram flow: replace
|
|
||||||
`adminAuthGuard` with `ed25519AuthGuard` outright, or run both and let
|
|
||||||
role/tenant config pick — this is a product decision, not made here.
|
|
||||||
4. Wire `AuthFacade.restoreSession()` into an `APP_INITIALIZER` (or root
|
|
||||||
component `ngOnInit`) so a page refresh restores state before any guard
|
|
||||||
runs.
|
|
||||||
5. Only after 1–4: point `/backoffice` and `/edit`'s `canActivate` at
|
|
||||||
`ed25519AuthGuard` (and `permissionGuard(...)` where a route needs a
|
|
||||||
specific role).
|
|
||||||
|
|
||||||
## 11. Security considerations
|
|
||||||
|
|
||||||
- **Private key never leaves the device.** Generated non-extractable via
|
|
||||||
WebCrypto; `Ed25519KeypairService` has no export path. Losing the device
|
|
||||||
means losing the key — key rotation/recovery (revoking a lost device's
|
|
||||||
public key, provisioning a new one) is a backend/ops process, not
|
|
||||||
implemented here.
|
|
||||||
- **The frontend is not the authorization boundary.** Every admin
|
|
||||||
request must be independently checked server-side against the caller's
|
|
||||||
actual role, exactly as `docs/BACKEND_API.md` §2.5
|
|
||||||
already states for the Telegram flow. A decoded JWT claim or a passing
|
|
||||||
`PermissionService.has()` check is UX, not proof.
|
|
||||||
- **Refresh tokens should rotate.** Every `POST /refresh` response is
|
|
||||||
expected to include a *new* refresh token; the backend should invalidate
|
|
||||||
the one just used. The frontend always stores whatever pair it receives
|
|
||||||
and never reuses an old refresh token after a successful rotation.
|
|
||||||
- **CSRF/replay:** the nonce from `/challenge` must be single-use and
|
|
||||||
time-boxed server-side (`expiresAt`) — the frontend enforces nothing here
|
|
||||||
beyond passing the nonce back unmodified; replay protection is the
|
|
||||||
backend's responsibility.
|
|
||||||
- **No fallback to unsigned auth.** There is no code path in this module
|
|
||||||
that issues a session without a valid signature. If the backend is
|
|
||||||
unreachable, the user sees `backend-unavailable`, never a degraded or
|
|
||||||
bypassed login.
|
|
||||||
- **Dev bypass exclusion:** unlike `AdminAuthService.devBypassLogin()` in
|
|
||||||
the Telegram flow, this module intentionally has no dev bypass — an
|
|
||||||
Ed25519 keypair is cheap to generate locally, so local testing should
|
|
||||||
point at a real (even if mocked-in-dev) `/challenge`/`/verify` pair
|
|
||||||
rather than fabricating a session.
|
|
||||||
File diff suppressed because it is too large
Load Diff
@@ -1,92 +0,0 @@
|
|||||||
> **ARCHIVED 2026-07-26.** Superseded by [`docs/BACKEND_INTEGRATION.md`](../BACKEND_INTEGRATION.md), the single canonical backend integration document. Kept for history only — do not implement against this file.
|
|
||||||
|
|
||||||
# Remaining backend work (everything except auth/session)
|
|
||||||
|
|
||||||
Companion to the `API-CONTRACT.md` backend delivered separately (covers `GET /bootstrap`
|
|
||||||
transport + `/users/sessions/*` — done, see prior conversation). This file lists what's
|
|
||||||
still outstanding. Full request/response shapes, TypeScript
|
|
||||||
interfaces, and validation rules for every item below already exist in
|
|
||||||
[`docs/BACKEND_API.md`](BACKEND_API.md) — this is a prioritized
|
|
||||||
punch list with links into that spec, not a duplicate of it. **Do not re-document
|
|
||||||
endpoint shapes here** — edit the master spec if a shape needs to change.
|
|
||||||
|
|
||||||
Status legend (same as master spec): **PLANNED** = shape fully specified client-side,
|
|
||||||
served by a mock gateway today, nothing built server-side yet. **FUTURE** = reserved
|
|
||||||
contract only, no urgency. Bootstrap's *content* (branding/theme/nav values, not the
|
|
||||||
`GET /bootstrap` transport itself) is also still outstanding — see P0 below.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Status legend for this list
|
|
||||||
|
|
||||||
**DONE** = wired end-to-end on the frontend (real HTTP gateway or real call site, no mock
|
|
||||||
left in the path). **PLANNED** = shape fully specified client-side, still served by a mock
|
|
||||||
gateway, nothing wired yet. Everything below that isn't marked DONE is still open.
|
|
||||||
|
|
||||||
## P0 — blocks going live at all
|
|
||||||
|
|
||||||
| # | Item | Status | Spec section |
|
|
||||||
|---|---|---|---|
|
|
||||||
| 1 | `bootstrap.json` real content (branding, theme, navigation, seo) — currently default stubs per backend's own note in API-CONTRACT.md | open | [§4](BACKEND_API.md#4-bootstrap) |
|
|
||||||
| 2 | Builder — bootstrap draft/publish/validate (`GET/PUT /builder/bootstrap/draft`, `POST /builder/bootstrap/publish`, `POST /builder/bootstrap/validate`) — this is how the Marketplace Builder actually saves anything | open | [§6.7](BACKEND_API.md#67-builder--bootstrap-draftpublishvalidate-planned-highest-priority) |
|
|
||||||
| 3 | Backoffice — Products CRUD + variants | open | [§6.10](BACKEND_API.md#610-backoffice--products-planned), DTOs [§7.2](BACKEND_API.md#72-products--srcappfeaturesadminproductsmodelsadmin-productmodelts) |
|
|
||||||
| 4 | Backoffice — Categories CRUD (tree) | **DONE** — `admin-categories-api.gateway.ts` + `admin-categories-gateway.token.ts` wired, swaps on `RuntimeProviderStrategyService` | [§6.9](BACKEND_API.md#69-backoffice--categories-planned), DTOs [§7.1](BACKEND_API.md#71-categories--srcappfeaturesadmincategoriesmodelsadmin-categorymodelts) |
|
|
||||||
| 5 | Media upload/delete/replace pipeline | open | [§6.18](BACKEND_API.md#618-media-planned--adr-0002), [§10](BACKEND_API.md#10-media) |
|
|
||||||
|
|
||||||
## P1 — needed for real order/commerce flow
|
|
||||||
|
|
||||||
| # | Item | Status | Spec section |
|
|
||||||
|---|---|---|---|
|
|
||||||
| 6 | Backoffice — Orders CRUD + status transitions | open | [§6.11](BACKEND_API.md#611-backoffice--orders-planned), state machine [§8.1](BACKEND_API.md#81-orders--adminorderstatus) |
|
|
||||||
| 7 | Backoffice — Transactions (list/detail, tied to orders) | open | [§6.12](BACKEND_API.md#612-backoffice--transactions-planned) |
|
|
||||||
| 8 | Order creation — checkout calls `POST /orders` on payment success | **DONE** — `ApiService.createOrder()` + `CartComponent.recordOrder()`, fire-and-forget alongside `clearCart()`, doesn't touch the frozen payment call chain | [§16.9](BACKEND_API.md#169-order-creation-future--no-order-creation-endpoint-exists-anywhere-yet) |
|
|
||||||
| 9 | Backoffice — Users/roles/invitations | open | [§6.13](BACKEND_API.md#613-backoffice--users-roles-invitations-planned) |
|
|
||||||
| 10 | Backoffice — Moderation (review + report status transitions) | open | [§6.14](BACKEND_API.md#614-backoffice--moderation-reviews--reports-planned), state machines [§8.4](BACKEND_API.md#84-reviews--adminreviewstatus)/[§8.5](BACKEND_API.md#85-reports--adminreportstatus) |
|
|
||||||
|
|
||||||
## P2 — dashboards / operational visibility
|
|
||||||
|
|
||||||
| # | Item | Status | Spec section |
|
|
||||||
|---|---|---|---|
|
|
||||||
| 11 | Backoffice — Dashboard metrics & recent activity | open | [§6.15](BACKEND_API.md#615-backoffice--dashboard-metrics--recent-activity-planned) |
|
|
||||||
| 12 | Backoffice — Monitoring (all but Health) | open | [§6.16](BACKEND_API.md#616-backoffice--monitoring-planned-except-health) |
|
|
||||||
| 13 | Backoffice — Analytics summary (real once orders are real) | open | [§6.17](BACKEND_API.md#617-backoffice--analytics-mostly-future--no-data-source) |
|
|
||||||
| 14 | Builder — Content pages / CMS | open | [§6.8](BACKEND_API.md#68-builder--content-pages--cms-planned) |
|
|
||||||
|
|
||||||
## P3 — nice-to-have, no urgency
|
|
||||||
|
|
||||||
| # | Item | Status | Spec section |
|
|
||||||
|---|---|---|---|
|
|
||||||
| 15 | Search suggestions / catalog filters | open | [§6.6](BACKEND_API.md#66-search--autocomplete--trending-planned) |
|
|
||||||
| 16 | Cross-device wishlist/compare/saved-searches sync — backend confirmed id-only stays, added `GET /items/batch?ids=` for hydration. Frontend needs `UserExperienceRepository` redesign: id-array + local product cache hydrated via the batch endpoint, replacing today's fully-synchronous denormalized-object storage | open (unblocked, not started) | [§6.6](BACKEND_API.md#66-search--autocomplete--trending-planned) |
|
|
||||||
| 17 | Analytics traffic/funnels/heatmaps — needs a tracking pipeline that doesn't exist yet, not just an endpoint | open | [§6.17](BACKEND_API.md#617-backoffice--analytics-mostly-future--no-data-source) |
|
|
||||||
| 18 | Sitemap — dynamic generation (static baseline today) | open (server-side, no frontend action) | [§6.19](BACKEND_API.md#619-sitemap-future--static-baseline-only-today) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Explicitly not in this list
|
|
||||||
|
|
||||||
- Auth / Telegram session (`GET /bootstrap` transport, `/users/sessions/*`) — covered by
|
|
||||||
backend's `API-CONTRACT.md`, frontend wiring matches it exactly.
|
|
||||||
- `authApiUrl` env value — **fixed**, now points at the same host as `apiUrl`
|
|
||||||
(`https://api.dexarmarket.ru:445`) in both `environment.ts` and `environment.production.ts`.
|
|
||||||
- `AdminWebSessionID` header — **fixed a real bug**: the interceptor only attached it to
|
|
||||||
URLs containing `/admin/`, but every real backend path is `/backoffice/*`, `/builder/*`,
|
|
||||||
`/media/*` — none of those matched, so every new admin call would have silently gone out
|
|
||||||
with no admin auth header at all. Broadened the guard in `admin-auth-headers.interceptor.ts`.
|
|
||||||
- `telegramBot` username — still unverified against `bot.go`'s `startbot()`.
|
|
||||||
- Frontend deploy domain vs. CORS allow-list — **decided**: frontend and API stay on the
|
|
||||||
same domain, so this is a non-issue by design rather than something to reconcile against
|
|
||||||
an allow-list.
|
|
||||||
- Payments — frozen, unchanged, out of scope per [§2.8](BACKEND_API.md#28-payments-frozen-documented-for-completeness).
|
|
||||||
- Storefront reads/writes (categories, items, search, cart, reviews) — already real HTTP,
|
|
||||||
already working, no backend work needed. See [§6.1](BACKEND_API.md#61-storefront-reads-current--frozen-shapes-srcappservicesapiservicets)–[§6.2](BACKEND_API.md#62-storefront-writes-current--frozen-shapes).
|
|
||||||
|
|
||||||
## For every open item above, when implementing
|
|
||||||
|
|
||||||
Read the interface + model file cited in the linked spec section before writing the
|
|
||||||
endpoint — the shape is already fixed by the frontend gateway interface, not up for
|
|
||||||
renegotiation without a frontend change. Follow the pattern now established for Categories
|
|
||||||
(`admin-categories-api.gateway.ts` + `admin-categories-gateway.token.ts`): one `*ApiGateway`
|
|
||||||
class implementing the existing `*Gateway` interface, plus one `InjectionToken` factory that
|
|
||||||
picks mock vs. real off `RuntimeProviderStrategyService`, then switch the facade(s) to inject
|
|
||||||
the token instead of the concrete mock class. See [§14](BACKEND_API.md#14-backend-replacement-pattern) for the general pattern.
|
|
||||||
@@ -1,44 +0,0 @@
|
|||||||
> **ARCHIVED 2026-07-26.** Despite its filename this was a shipped-history changelog, not a forward roadmap — superseded by [`../NEXT_PHASE.md`](../NEXT_PHASE.md) (the one roadmap), [`../CHANGELOG.md`](../../CHANGELOG.md) (shipped history), and [`../PROJECT_STATUS.md`](../PROJECT_STATUS.md)/[`../KNOWN-ISSUES.md`](../KNOWN-ISSUES.md)/[`../PRODUCT_BACKLOG.md`](../PRODUCT_BACKLOG.md)/[`../FUTURE_FEATURES.md`](../FUTURE_FEATURES.md) (open items, now category-split). Kept for history only.
|
|
||||||
|
|
||||||
# Frontend Roadmap
|
|
||||||
|
|
||||||
Status snapshot, refreshed from recent commits only. Full sprint history: `SPRINT-PLAN.md` (removed, see git history). Open bugs: `docs/KNOWN-ISSUES.md`.
|
|
||||||
|
|
||||||
## Recently shipped
|
|
||||||
|
|
||||||
**RC-Visual-02 — Composition audit** (storefront, builder, backoffice)
|
|
||||||
Fixed undefined CSS theme vars, hand-rolled skeletons/empty-states migrated to shared `app-skeleton`/`app-empty-state`/`app-button`, missing `<th scope="col">`, dead CSS (~530-line unused cart `.alt` theme). Detail: `UI-COMPOSITION-REVIEW.md` (removed, see git history).
|
|
||||||
|
|
||||||
**RC-Premium-01 — Storefront premium UX polish**
|
|
||||||
Visual/interaction polish on top of the RC-Visual-02 baseline — no redesign, no logic/route changes. Fixed color-only state signaling app-wide (added `aria-pressed`/`aria-current`/`aria-live` + icon/checkmark pairing to selected swatches, active filters/tabs/sort, toggle buttons), normalized remaining hardcoded hex to design tokens, added hover/focus-visible/active/disabled states across interactive controls, capped legal/CMS prose at 70ch, converted FAQ to native `<details>` disclosures. Four commits (Home/Catalog/Search, Product/Compare/Wishlist, Cart/Checkout, Static Pages). Detail: `STORE_FRONT_UX_REVIEW.md` (removed, see git history).
|
|
||||||
|
|
||||||
**RC STORE-01 — Storefront cleanup**
|
|
||||||
Closed 2 of the 5 gaps RC-Premium-01 deliberately deferred: category/search skeleton markup migrated to shared `app-skeleton`, dead cart `.email-form` markup/CSS removed. The other 3 (payment modal, cart confirm() dialog, untokenized colors) need an architecture/design-system decision, correctly left alone again. Detail: `STORE_REVIEW.md` (removed, see git history).
|
|
||||||
|
|
||||||
**RC PERF-01 — Performance audit** (production-readiness, app-wide)
|
|
||||||
Initial bundle **1.47 MB → 1.12 MB raw (−24%)**: biggest win was lazy-loading en/hy i18n packs (346 KB were eagerly loaded regardless of visitor language), plus a dead `items-carousel`/primeng-only component deleted, dead global CSS removed. RxJS/change-detection audit found the codebase already clean (0 leaks, 190/191 components already OnPush). Detail: `PERFORMANCE_REPORT.md` (removed, see git history).
|
|
||||||
|
|
||||||
**RC A11Y-01 — WCAG 2.1 AA audit** (storefront, builder, backoffice)
|
|
||||||
Added the app's first skip link (didn't exist anywhere before), fixed cart's custom payment modals having zero focus-trap, fixed `app-icon`'s "decorative by default" claim never actually being implemented, fixed 2 keyboard-inaccessible drag-and-drop reorder UIs (Builder homepage/footer, Backoffice categories), fixed an undefined `--color-primary` token in Builder, fixed admin sidebar nav announcing itself as "Dashboard" everywhere. Contrast fixes applied where safe; genuine brand-color contrast failures flagged for theme-owner sign-off, not changed unilaterally. Detail: `ACCESSIBILITY_REPORT.md` (removed, see git history).
|
|
||||||
|
|
||||||
**Release Candidate — live browser walkthrough** (storefront, builder, backoffice)
|
|
||||||
Found and fixed **2 P0s**: (1) `language.guard.ts`'s legacy-URL redirect broke query params on every route app-wide (silently dead-ended any bookmarked/shared deep link with query params); (2) Backoffice Categories CRUD was completely broken end-to-end — wrong gateway-resolution fallback always picked the real HTTP gateway instead of the local mock in this environment, so every create/publish silently failed with zero user feedback. Plus 6 P1s (cart description, compare table raw enum values, search empty-state messaging, footer link 404, missing placeholder image, builder save-bar reset-state bug, backoffice mislabeled button). Detail: `RELEASE_REPORT.md` (removed, see git history).
|
|
||||||
|
|
||||||
## Sprint status
|
|
||||||
|
|
||||||
**Sprint 30 — Final Release**: verify pass re-run 2026-07-23 (tsc --noEmit, `npm run build`, `arch:check:boundaries`, `arch:check:cycles`) — all green, only pre-existing bundle-budget warning. Working tree otherwise clean. Only remaining item: `git push` of 10 local `B2B` commits to `origin/B2B` — awaiting explicit user go-ahead (declined once already this sprint, per safety rules re-ask each time). Full checklist: `SPRINT-PLAN.md` (removed, see git history).
|
|
||||||
|
|
||||||
## Known open items (not yet scheduled)
|
|
||||||
|
|
||||||
As of the 2026-07-26 Final Project Closeout, open items are split by category instead of one mixed list:
|
|
||||||
- Real, reproducible frontend bugs: `docs/KNOWN-ISSUES.md` (one open item).
|
|
||||||
- Items needing a client/business decision (dark mode, brand-color contrast, Contacts page content, advanced analytics, payment providers): `docs/PRODUCT_BACKLOG.md`.
|
|
||||||
- Nice-to-have, non-blocking future work (Angular 22, bundle splitting, cart-modal composition cleanup, hero-spacing investigation): `docs/FUTURE_FEATURES.md`.
|
|
||||||
- Backend integration: fully specified, not yet implemented — the single canonical spec is `docs/BACKEND.md`.
|
|
||||||
- Release blockers: `docs/TODO.md` — currently none.
|
|
||||||
|
|
||||||
Overall status: `docs/PROJECT_STATUS.md`.
|
|
||||||
|
|
||||||
## Not audited / out of scope
|
|
||||||
|
|
||||||
Settings (no route exists), Diagnostics (dev-only, excluded from production).
|
|
||||||
@@ -1,823 +0,0 @@
|
|||||||
# Backend Surface Audit
|
|
||||||
|
|
||||||
Machine-oriented, exhaustive audit of every backend touch-point the Angular frontend
|
|
||||||
expects — derived from the current source tree on branch `B2B`, not copied from prior
|
|
||||||
docs. Purpose: single input for downstream backend-integration documentation tasks.
|
|
||||||
|
|
||||||
Legend for maturity (mirrors `docs/BACKEND_API.md`'s tagging so the two stay reconcilable):
|
|
||||||
|
|
||||||
- **LIVE** — real `HttpClient` call exists in code today (file cited).
|
|
||||||
- **MOCK-SWAPPABLE** — interface + mock implementation exist, wired through an Angular
|
|
||||||
DI token so a real `*Api*` class can be dropped in without touching UI. A real impl
|
|
||||||
may or may not exist yet.
|
|
||||||
- **MOCK-ONLY (no seam)** — mock/local implementation exists but the facade injects the
|
|
||||||
concrete local class **directly** (no DI token). Adding a backend here first requires
|
|
||||||
introducing a token seam. This is the single most important structural finding below.
|
|
||||||
- **LOCAL-ONLY** — never talks to a backend by design (localStorage / in-memory /
|
|
||||||
derived from already-loaded bootstrap). Listed for completeness.
|
|
||||||
|
|
||||||
## Table of contents
|
|
||||||
|
|
||||||
1. [Executive summary & key findings](#1-executive-summary--key-findings)
|
|
||||||
2. [Runtime provider strategy & environment](#2-runtime-provider-strategy--environment)
|
|
||||||
3. [HTTP interceptor pipeline](#3-http-interceptor-pipeline)
|
|
||||||
4. [Live HTTP endpoints (verified in code)](#4-live-http-endpoints-verified-in-code)
|
|
||||||
5. [Domain: Auth (customer + admin)](#5-domain-auth-customer--admin)
|
|
||||||
6. [Domain: Bootstrap / config / tenant](#6-domain-bootstrap--config--tenant)
|
|
||||||
7. [Domain: Products & catalog](#7-domain-products--catalog)
|
|
||||||
8. [Domain: Categories](#8-domain-categories)
|
|
||||||
9. [Domain: Backoffice storefront data](#9-domain-backoffice-storefront-data)
|
|
||||||
10. [Domain: Cart / orders / payments](#10-domain-cart--orders--payments)
|
|
||||||
11. [Domain: Reviews & questions (engagement)](#11-domain-reviews--questions-engagement)
|
|
||||||
12. [Domain: Location / regions](#12-domain-location--regions)
|
|
||||||
13. [Domain: Widgets / dynamic renderer](#13-domain-widgets--dynamic-renderer)
|
|
||||||
14. [Admin gateways (feature area)](#14-admin-gateways-feature-area)
|
|
||||||
15. [Domain: Media library](#15-domain-media-library)
|
|
||||||
16. [Domain: Content management / static pages](#16-domain-content-management--static-pages)
|
|
||||||
17. [Domain: Project editor / builder](#17-domain-project-editor--builder)
|
|
||||||
18. [Domain: Search](#18-domain-search)
|
|
||||||
19. [Domain: User experience (wishlist/compare/etc.)](#19-domain-user-experience-wishlistcomparetc)
|
|
||||||
20. [Domain: Diagnostics](#20-domain-diagnostics)
|
|
||||||
21. [Facade catalog](#21-facade-catalog)
|
|
||||||
22. [Gateway / provider master table](#22-gateway--provider-master-table)
|
|
||||||
23. [Model / DTO catalog](#23-model--dto-catalog)
|
|
||||||
24. [Endpoint URL literals found in code](#24-endpoint-url-literals-found-in-code)
|
|
||||||
25. [Cross-check against existing docs](#25-cross-check-against-existing-docs)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. Executive summary & key findings
|
|
||||||
|
|
||||||
- **~9 real HTTP-speaking domains** exist today: product/catalog, categories, cart/orders/
|
|
||||||
payments, reviews/questions, telegram session auth, bootstrap, backoffice storefront data,
|
|
||||||
widget manifest, location/regions. Plus **Ed25519 admin auth** — wired to real `HttpClient`
|
|
||||||
but the endpoints are not implemented server-side yet (calls 404 today, by design).
|
|
||||||
- **Two provider seams are token-bound and API-ready today**: `PRODUCT_DATA_PROVIDER`
|
|
||||||
(→ `ApiProductDataProvider`, LIVE) and `CATEGORY_REPOSITORY` (→ `ApiCategoryRepository`, LIVE),
|
|
||||||
plus `CONFIG_PROVIDER` and `BACKOFFICE_DATA_PROVIDER` which switch mock↔api by strategy.
|
|
||||||
- **KEY STRUCTURAL FINDING — most admin CRUD domains have no swap seam.** Of the 11 admin
|
|
||||||
gateway domains, only **categories** (`ADMIN_CATEGORIES_GATEWAY`) and **dashboard-metrics**
|
|
||||||
(`ADMIN_DASHBOARD_METRICS_GATEWAY`) are injected via DI token. The other 9 (orders, products,
|
|
||||||
users, transactions, monitoring, moderation, customers, analytics, and the products/orders
|
|
||||||
gateways reused by analytics/customers) have their facades inject the concrete
|
|
||||||
`Admin*LocalGateway` **class directly**. A backend engineer cannot "just rebind a token" for
|
|
||||||
those — a token must be introduced first. This partially contradicts the blanket
|
|
||||||
"PLANNED / rebind the token" framing in `docs/BACKEND_API.md`.
|
|
||||||
- **Only one real `*Api*Gateway` exists in the admin area**: `AdminCategoriesApiGateway`
|
|
||||||
(`src/app/features/admin/categories/services/admin-categories-api.gateway.ts`). Every other
|
|
||||||
admin domain is local-mock only.
|
|
||||||
- **Media** is bound by class token (`MediaRepository` abstract class → `MockMediaRepository`
|
|
||||||
via `app.config.ts`), so it is MOCK-SWAPPABLE but no real impl exists.
|
|
||||||
- **Content-management and project-editor never hit a dedicated backend** — they read/mutate
|
|
||||||
the in-memory `BootstrapConfig` (loaded once from `GET /bootstrap`) and persist drafts to
|
|
||||||
localStorage. Publishing a marketplace = writing bootstrap back, for which no client write
|
|
||||||
call exists yet (LOCAL-ONLY today; a builder publish endpoint is FUTURE).
|
|
||||||
- **Two API base URLs are in play**: the tenant marketplace API (`ApiConfigService.getBaseUrl()`,
|
|
||||||
default `https://api.dexarmarket.ru:445`, `/api` on localhost) and a separate payment/QR API
|
|
||||||
(`environment.qrApiUrl` = `https://qr.vitanova.network/api`). Auth session API uses
|
|
||||||
`environment.authApiUrl` (= `https://api.dexarmarket.ru:445`).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. Runtime provider strategy & environment
|
|
||||||
|
|
||||||
`src/app/core/providers/runtime-provider-strategy.service.ts` — `RuntimeProviderStrategyService`
|
|
||||||
decides mock vs api per domain. Modes: `'mock' | 'api' | 'remote-config'`.
|
|
||||||
|
|
||||||
| Method | Returns `mock` when | Else |
|
|
||||||
|---|---|---|
|
|
||||||
| `getBootstrapProviderMode()` | `useMockData` true, OR `useMockBootstrapOnLocal && isLocalhost()` | `api` |
|
|
||||||
| `getBackofficeProviderMode()` | `useMockData` true | `api` |
|
|
||||||
| `getProductProviderMode()` | `useMockData` true | `api` (mock/remote-config fall through to api in token factory) |
|
|
||||||
| `getCategoryProviderMode()` | `useMockData` true, OR `useMockBootstrapOnLocal && isLocalhost()` | `api` |
|
|
||||||
|
|
||||||
Note: `PRODUCT_DATA_PROVIDER` and `CATEGORY_REPOSITORY` token factories currently return the
|
|
||||||
**Api** provider for every mode (the `case 'mock'` falls through) — there is no mock product/
|
|
||||||
category provider class bound. `getCategoryProviderMode()` returning `mock` only matters for
|
|
||||||
`ADMIN_CATEGORIES_GATEWAY` (which does honor it → `AdminCategoriesLocalGateway`).
|
|
||||||
|
|
||||||
`src/environments/environment.ts` relevant keys:
|
|
||||||
|
|
||||||
```
|
|
||||||
useMockData: false
|
|
||||||
useMockBootstrapOnLocal: true
|
|
||||||
allowBootstrapApiOverride: false
|
|
||||||
localhostApiUrl: '/api'
|
|
||||||
tenantApiTemplate: 'https://{tenant}.api.dexarmarket.ru:445'
|
|
||||||
tenantApiBaseUrls: { default: 'https://api.dexarmarket.ru:445', dexarmarket: 'https://api.dexarmarket.ru:445' }
|
|
||||||
apiUrl: '/api'
|
|
||||||
authApiUrl: 'https://api.dexarmarket.ru:445'
|
|
||||||
qrApiUrl: 'https://qr.vitanova.network/api'
|
|
||||||
telegramBot: 'myAMLKYCBOT' (fallback in code: 'DexarSupport_bot')
|
|
||||||
```
|
|
||||||
|
|
||||||
`src/app/core/config/api-config.service.ts` — `ApiConfigService.getBaseUrl()` resolves the
|
|
||||||
tenant marketplace API base: localhost → `localhostApiUrl`; else `tenantApiBaseUrls[tenantKey]`;
|
|
||||||
else `tenantApiTemplate` with `{tenant}` substituted; else optional bootstrap override
|
|
||||||
(gated by `allowBootstrapApiOverride`, reads `bootstrap.apiEndpoints.website.baseUrl` /
|
|
||||||
`bootstrap.tenant.apiBaseUrl`). `isApiRequest(url)` = starts with `/api` or the base URL.
|
|
||||||
`toApiUrl(url)` rewrites a `/api`-prefixed relative URL onto the resolved base.
|
|
||||||
|
|
||||||
Tenant key comes from `TenantResolverService` (`src/app/core/config/tenant-resolver.service.ts`).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. HTTP interceptor pipeline
|
|
||||||
|
|
||||||
Registered in `src/app/app.config.ts` in this order:
|
|
||||||
|
|
||||||
```
|
|
||||||
withInterceptors([mockDataInterceptor, apiBaseUrlInterceptor, apiHeadersInterceptor, adminAuthHeadersInterceptor, cacheInterceptor])
|
|
||||||
```
|
|
||||||
|
|
||||||
| Interceptor | File | Responsibility |
|
|
||||||
|---|---|---|
|
|
||||||
| `mockDataInterceptor` | `src/app/interceptors/mock-data.interceptor.ts` | When `environment.useMockData`, short-circuits marketplace endpoints with in-memory fixtures (categories, items, search, cart, qr, callback, purchase-email, sessions). Matches URL patterns — see §24. |
|
|
||||||
| `apiBaseUrlInterceptor` | `src/app/interceptors/api-base-url.interceptor.ts` | Rewrites `/api/*` relative URLs to `ApiConfigService.toApiUrl()`. |
|
|
||||||
| `apiHeadersInterceptor` | `src/app/interceptors/api-headers.interceptor.ts` | For marketplace API requests, sets headers: `X-Region`, `X-Language` (RU/EN/AM), `Currency` (default RUB), `WebSessionID` (auth session id or persisted anonymous 32-hex id in localStorage key `web_session_id`). |
|
|
||||||
| `adminAuthHeadersInterceptor` | `src/app/core/admin-auth/admin-auth-headers.interceptor.ts` | For requests whose URL contains `/admin/`, `/backoffice/`, `/builder/`, `/media/`, sets `AdminWebSessionID` header (from `AdminAuthService.session()`) and `Authorization: Bearer <token>` if an admin token is stored. |
|
|
||||||
| `cacheInterceptor` | `src/app/interceptors/cache.interceptor.ts` | Client-side GET response caching. |
|
|
||||||
|
|
||||||
Header value maps (from `apiHeadersInterceptor`): language `ru→RU, en→EN, hy→AM`;
|
|
||||||
region `moscow→Moscow, spb→ST. Petersburg, yerevan→Yerevan`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. Live HTTP endpoints (verified in code)
|
|
||||||
|
|
||||||
All paths relative to `ApiConfigService.getBaseUrl()` unless a full origin is shown. Payment
|
|
||||||
endpoints use `environment.qrApiUrl`; session endpoints use `environment.authApiUrl`.
|
|
||||||
|
|
||||||
### Marketplace API — `src/app/services/api.service.ts` (`ApiService`)
|
|
||||||
|
|
||||||
| Method | HTTP | Path | Notes |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `ping()` | GET | `/ping` | `{ message }` |
|
|
||||||
| `getCategories()` | GET | `/category` | normalized to `Category[]` |
|
|
||||||
| `getCategoryItems(id,count,skip)` | GET | `/category/{categoryID}?count&skip` | `Item[]` |
|
|
||||||
| `getItem(id)` | GET | `/items/{itemID}` | single `Item` |
|
|
||||||
| `searchItems(search,count,skip,opts)` | GET | `/searchitems?search&count&skip[&categoryIDs&minPrice&maxPrice&tag&sort]` | `{ items, total }` |
|
|
||||||
| `getRandomItems(count,categoryID?)` | GET | `/items/randomitems?count[&category]` | `Item[]` (featured) |
|
|
||||||
| `addToCart(sessionId,items)` | POST | `/websession/{sessionId}` | body = item array |
|
|
||||||
| `submitReview(data)` | POST | `/items/{itemID}/callback` | body: rating, comment, sessionID, timestamp |
|
|
||||||
| `submitQuestion(data)` | POST | `/items/{itemID}/questiion` | **NOTE: literal typo `questiion`** matches backend spec |
|
|
||||||
| `createCartPayment(payload)` | POST | `/cart` | `CartPaymentRequest` → `QrCreateResponse` |
|
|
||||||
| `createOrder(payload)` | POST | `/orders` | `CreateOrderRequest` → `CreateOrderResponse`; fire-and-forget after payment |
|
|
||||||
| `submitPurchaseEmail(data)` | POST | `/purchase-email` | email receipt |
|
|
||||||
| `createPayment(payload,headers)` | POST | `{qrApiUrl}/qr` | headers `authorization-key`, `userid-value` |
|
|
||||||
| `checkCartPaymentStatus(qrId)` | GET | `{qrApiUrl}/qr/dynamic/{partnerId}/{qrId}` | partnerId const `web-97ec-9c57-4dde-9037-3a68f7f83750` |
|
|
||||||
| `checkCartCardPaymentStatus(orderId)` | GET | `{qrApiUrl}/card/{partnerId}/{orderId}` | |
|
|
||||||
| `checkPaymentStatus(partnerQrId,qrId)` | GET | `{qrApiUrl}/qr/dynamic/{partnerQrId}/{qrId}` | |
|
|
||||||
|
|
||||||
Also builds an external QR image URL (`https://api.qrserver.com/v1/create-qr-code/...`) — not a backend of this platform.
|
|
||||||
|
|
||||||
### Other live callers
|
|
||||||
|
|
||||||
| Caller (file) | HTTP | Path | Base |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `ApiHealthService` (`src/app/services/api-health.service.ts`) | GET | `/ping` | marketplace base |
|
|
||||||
| `ApiCategoryRepository` (`src/app/core/categories/repositories/api-category.repository.ts`) | GET | `/category` | marketplace base; retry x2 |
|
|
||||||
| `ApiBootstrapProvider` (`src/app/core/bootstrap/providers/api-bootstrap.provider.ts`) | GET | `/bootstrap` | relative |
|
|
||||||
| `MockBootstrapProvider` | GET | `/assets/mock/bootstrap/bootstrap.json` | static asset |
|
|
||||||
| `ApiBackofficeDataProvider` (`src/app/core/backoffice/providers/api-backoffice-data.provider.ts`) | GET | `/api/backoffice/products`, `/api/backoffice/categories` | |
|
|
||||||
| `WidgetManifestService` (`src/app/widgets/registry/widget-manifest.service.ts`) | GET | `bootstrap.widgetRegistry.manifestUrl` or `/assets/mock/bootstrap/widget-manifest.json` | |
|
|
||||||
| `LocationService` (`src/app/services/location.service.ts`) | GET | `/regions` (marketplace base); `http://ip-api.com/json/...` (external geo-IP) | |
|
|
||||||
| `TelegramSessionApiService` (`src/app/services/telegram-session-api.service.ts`) | POST/GET/DELETE | `{authApiUrl}/users/sessions`, `/users/sessions/{id}` | session auth |
|
|
||||||
| `AuthApiService` (`src/app/core/auth/services/auth-api.service.ts`) | GET/POST | `{authApiUrl}/api/admin/auth/challenge|verify|refresh|logout` | **not implemented server-side yet** |
|
|
||||||
| `ApiProductDataProvider` | (delegates to `ApiService`) | see above | |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. Domain: Auth (customer + admin)
|
|
||||||
|
|
||||||
Two distinct auth mechanisms coexist.
|
|
||||||
|
|
||||||
### 5a. Telegram session auth (LIVE) — customer AND admin
|
|
||||||
|
|
||||||
`src/app/services/telegram-session-api.service.ts` — `TelegramSessionApiService`. Single source
|
|
||||||
for both customer (`AuthService`) and admin (`AdminAuthService`) login; there is no separate
|
|
||||||
admin backend endpoint. Only storage is kept separate (distinct cookie/signals).
|
|
||||||
|
|
||||||
| Method | HTTP | Path | Request | Response (normalized) |
|
|
||||||
|---|---|---|---|---|
|
|
||||||
| `createSession()` | POST | `{authApiUrl}/users/sessions` | `{ webSessionID }` + header `WebSessionID` | `WebSessionStart { webSessionID, url }` (url = `https://t.me/{bot}?start={id}`) |
|
|
||||||
| `checkSessionOnce(id)` | GET | `{authApiUrl}/users/sessions/{id}` | — | `AuthSession | null` (heavily field-tolerant normalizer) |
|
|
||||||
| `logout(id)` | DELETE | `{authApiUrl}/users/sessions/{id}` | header `WebSessionID` | ignored |
|
|
||||||
|
|
||||||
Consumers: `AuthService` (`src/app/services/auth.service.ts`, customer),
|
|
||||||
`AdminAuthService` (`src/app/core/admin-auth/admin-auth.service.ts`, admin — separate cookie
|
|
||||||
`adminSessionID`, has dev-only `devBypassLogin()`), `AuthFacade`
|
|
||||||
(`src/app/core/auth/services/auth-facade.service.ts`) wrapping AuthService/SessionService/
|
|
||||||
PermissionService for components. Also `src/app/shared/qr-login/`.
|
|
||||||
|
|
||||||
Models: `AuthSession`, `WebSessionStart`, `AuthStatus` (`src/app/models/auth.model.ts`);
|
|
||||||
`AdminAuthStatus` (`src/app/models/admin-auth.model.ts`).
|
|
||||||
|
|
||||||
### 5b. Ed25519 challenge/response admin auth (LIVE wiring, backend absent)
|
|
||||||
|
|
||||||
`src/app/core/auth/services/auth-api.service.ts` — `AuthApiService`. Real `HttpClient` wiring
|
|
||||||
against a documented contract that the backend has NOT implemented yet (calls 404 today,
|
|
||||||
mapped to a `backend-unavailable` error screen). No mocks fabricated.
|
|
||||||
|
|
||||||
| Method | HTTP | Path (`{authApiUrl}/api/admin/auth`) | Request | Response |
|
|
||||||
|---|---|---|---|---|
|
|
||||||
| `requestChallenge()` | GET | `/challenge` | — | `AuthChallenge { nonce, issuedAt, expiresAt }` |
|
|
||||||
| `verifySignature(req)` | POST | `/verify` | `VerifySignatureRequest { publicKey, signature, nonce }` | `AuthTokenPair { token, refreshToken }` |
|
|
||||||
| `refresh(req)` | POST | `/refresh` | `RefreshTokenRequest { refreshToken }` | `AuthTokenPair` |
|
|
||||||
| `logout(refreshToken)` | POST | `/logout` | `{ refreshToken }` | void |
|
|
||||||
|
|
||||||
Models: `src/app/core/auth/models/auth-api.model.ts` (`AuthChallenge`, `VerifySignatureRequest`,
|
|
||||||
`AuthTokenPair`, `RefreshTokenRequest`, `JwtClaims`). Supporting:
|
|
||||||
`src/app/core/auth/services/ed25519-keypair.service.ts` (keypair gen/signing);
|
|
||||||
`src/app/core/admin-auth/ed25519-verification.model.ts` +
|
|
||||||
`noop-ed25519-verification.service.ts` (bound in `app.config.ts` via
|
|
||||||
`{ provide: Ed25519VerificationService, useClass: NoopEd25519VerificationService }`).
|
|
||||||
|
|
||||||
Permissions/roles: `src/app/core/auth/models/permission.model.ts` — `AdminRole`
|
|
||||||
(`Owner|Administrator|Editor|Support|ReadOnly`), `Permission` union.
|
|
||||||
Errors: `src/app/core/auth/models/auth-error.model.ts` — `AuthErrorCode`, `AuthError`.
|
|
||||||
Guards: `src/app/core/admin-auth/admin-auth.guard.ts`, `src/app/guards/**`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Domain: Bootstrap / config / tenant
|
|
||||||
|
|
||||||
The runtime configuration document that drives the entire multi-tenant platform.
|
|
||||||
|
|
||||||
- **Contract interface**: `ConfigProvider` (`src/app/core/config/config-provider.interface.ts`)
|
|
||||||
— `loadBootstrap(): Observable<BootstrapConfig>`.
|
|
||||||
- **DI token**: `CONFIG_PROVIDER` (`src/app/core/config/config-provider.token.ts`), factory
|
|
||||||
switches on `getBootstrapProviderMode()`: `mock` → `MockBootstrapProvider`
|
|
||||||
(`/assets/mock/bootstrap/bootstrap.json`), else → `ApiBootstrapProvider` (`GET /bootstrap`).
|
|
||||||
- **Implementations**: `ApiBootstrapProvider`, `MockBootstrapProvider`
|
|
||||||
(`src/app/core/bootstrap/providers/*`).
|
|
||||||
- **Consuming services**: `ConfigService` (`src/app/core/config/config.service.ts`,
|
|
||||||
holds the bootstrap snapshot), `ApiConfigService`, `FeatureConfigService`,
|
|
||||||
`TenantResolverService`, `FooterResolverService`, `StaticPageResolverService`
|
|
||||||
(all `src/app/core/config/*`).
|
|
||||||
- **Consuming facades**: `UiRuntimeFacade` (`src/app/facades/runtime/ui-runtime.facade.ts`),
|
|
||||||
`WebsiteRuntimeFacade` (`src/app/facades/website/website-runtime.facade.ts`),
|
|
||||||
`ProjectEditorFacade`, `ContentManagementFacade`, `DiagnosticsFacade`.
|
|
||||||
|
|
||||||
`BootstrapConfig` (`src/app/shared/models/config/bootstrap-config.model.ts`) aggregates ~24
|
|
||||||
sub-configs, each its own file under `src/app/shared/models/config/`:
|
|
||||||
|
|
||||||
`schemaVersion, generatedAt, tenant, branding, theme, company, featureFlags, features?,
|
|
||||||
apiEndpoints, localization, seo, permissions, header?, catalog?, layout?, navigation, footer?,
|
|
||||||
productPage?, userExperience?, pages[], staticPages?, widgetRegistry?`
|
|
||||||
|
|
||||||
Sub-config model files (all backend-shaped, served inside bootstrap):
|
|
||||||
`api-endpoints.model.ts` (`ApiEndpointConfig{path,method,timeoutMs?}`, `ApiEndpointsConfig{
|
|
||||||
bootstrap, website:Record<...>, builder:Record<...>, backoffice:Record<...>}`),
|
|
||||||
`tenant.model.ts` (`TenantConfig{id,slug,code,host,name,websiteBaseUrl,builderBaseUrl,
|
|
||||||
backofficeBaseUrl,defaultLocale,supportedLocales,defaultCurrency,supportedCurrencies,timezone}`),
|
|
||||||
`branding.model.ts`, `theme.model.ts`, `company.model.ts`, `feature-flags.model.ts`,
|
|
||||||
`features-config.model.ts`, `footer-config.model.ts`, `header-config.model.ts`, `layout.model.ts`,
|
|
||||||
`localization.model.ts`, `navigation.model.ts`, `page.model.ts`, `permissions.model.ts`,
|
|
||||||
`product-page-config.model.ts`, `catalog-config.model.ts`, `seo.model.ts`,
|
|
||||||
`static-page.model.ts`, `user-experience-config.model.ts`, `widget-registry.model.ts`,
|
|
||||||
`widget.model.ts`, `section.model.ts`. Barrel: `src/app/shared/models/config/index.ts`.
|
|
||||||
|
|
||||||
`ApiEndpointsConfig.website/builder/backoffice` are `Record<string, ApiEndpointConfig>` —
|
|
||||||
i.e. the bootstrap document is where a tenant's PLANNED endpoint paths are declared at runtime.
|
|
||||||
No literal builder/backoffice path constants exist in code (see §24).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Domain: Products & catalog
|
|
||||||
|
|
||||||
- **Contract interface**: `ProductDataProvider`
|
|
||||||
(`src/app/core/products/providers/product-data-provider.interface.ts`).
|
|
||||||
- **DI token**: `PRODUCT_DATA_PROVIDER` (`src/app/core/products/product-data-provider.token.ts`)
|
|
||||||
— factory returns `ApiProductDataProvider` for all modes (no mock provider class bound).
|
|
||||||
- **Real impl (LIVE)**: `ApiProductDataProvider`
|
|
||||||
(`src/app/core/products/providers/api-product-data.provider.ts`) — delegates to `ApiService`
|
|
||||||
+ `CategoryService`; contains inline mapping (item→reviews/questions/rating summary).
|
|
||||||
- **Domain service**: `ProductDataService` (`src/app/core/products/product-data.service.ts`)
|
|
||||||
injected by `ProductFacade`.
|
|
||||||
- **Consuming facade**: `ProductFacade` (`src/app/facades/platform/product.facade.ts`).
|
|
||||||
- **Consuming components**: `catalog-container.component.ts`,
|
|
||||||
`product-details-container.component.ts` (`src/app/features/website/**`), home/catalog pages.
|
|
||||||
|
|
||||||
Interface methods: `getProducts(query?)`, `getProduct(productID)`, `getCategories()`,
|
|
||||||
`searchProducts(query)`, `getFeaturedProducts(query?)`, `getLatestProducts(query?)`,
|
|
||||||
`getProductsByCategory(categoryID,query?)`, `getRelatedProducts(query)`, `loadRating(productID)`,
|
|
||||||
`loadReviews(productID,query?)`, `loadQuestions(productID,query?)`, `submitReview(productID,input)`,
|
|
||||||
`submitQuestion(productID,input)`.
|
|
||||||
|
|
||||||
Models — `src/app/core/products/models/`:
|
|
||||||
- `product-domain.model.ts`: `Product = Item` (alias), `ProductCategory = Category`,
|
|
||||||
`ProductSort`, `ProductFilters`, `ProductListQuery`, `ProductSearchQuery`, `ProductListResult`,
|
|
||||||
`RelatedProductsQuery`, `RelatedProductCollection`, `ProductVariantSelection`.
|
|
||||||
- `product-engagement.model.ts`: `RatingStars`, `RatingDistributionEntry`, `RatingSummary`,
|
|
||||||
`Review`, `Answer`, `Question`, `EngagementListQuery`, `EngagementListResult<T>`,
|
|
||||||
`SubmitReviewInput`, `SubmitQuestionInput`.
|
|
||||||
- `catalog-experience.model.ts`: `SearchCriteria`, `FilterDefinition`, `FilterOption`,
|
|
||||||
`SortDefinition`, `CatalogView`, `SearchResult`, layout/nav mode types.
|
|
||||||
|
|
||||||
The **backend-shaped** product DTO is `Item` (`src/app/models/item.model.ts`) — the raw wire
|
|
||||||
shape. `ApiService.normalizeItem()` is the adapter: it reconciles legacy marketplace format and
|
|
||||||
newer backOffice format (string `id`↔numeric `itemID`, `imgs[]`↔`photos[]`, `names[]`↔
|
|
||||||
`translations`, `itemDetails[]`, `description` key/value array↔string, `comments`↔`callbacks`,
|
|
||||||
`specificationGroups`, `variantOptions`, `relatedCollections`, delivery normalization, color
|
|
||||||
`0xRRGGBB`→`#RRGGBB`, remaining→stock band). This is the single largest inline mapper in the
|
|
||||||
codebase — a backend engineer should treat `normalizeItem`/`normalizeCategory` as the tolerance
|
|
||||||
contract. `Item` supporting types: `ProductMedia`, `DescriptionField`, `ItemName`,
|
|
||||||
`ProductSpecificationField/Group`, `ProductVariantOption(Group)`, `RelatedProductCollection`,
|
|
||||||
`DeliveryOption`, `ItemDetail`, `CartItem`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. Domain: Categories
|
|
||||||
|
|
||||||
Two parallel category stacks exist (legacy + clean-architecture):
|
|
||||||
|
|
||||||
**Clean stack (MOCK-SWAPPABLE, real impl LIVE):**
|
|
||||||
- **Interface**: `CategoryRepository` (`src/app/core/categories/repositories/category.repository.ts`)
|
|
||||||
— `getCategories(): Observable<CategoryDto[]>`.
|
|
||||||
- **DI token**: `CATEGORY_REPOSITORY` (`src/app/core/categories/category-repository.token.ts`)
|
|
||||||
→ `ApiCategoryRepository` for all modes.
|
|
||||||
- **Real impl (LIVE)**: `ApiCategoryRepository` — `GET /category`, retry x2.
|
|
||||||
- **DTO**: `CategoryDto`, `CategoryNameDto` (`src/app/core/categories/dto/category.dto.ts`).
|
|
||||||
- **Adapter**: `CategoryMapper` (`src/app/core/categories/mappers/category.mapper.ts`) —
|
|
||||||
`CategoryDto → Category` domain (flattens subcategory tree, dedupes by id, language
|
|
||||||
normalization `am→hy`).
|
|
||||||
- **Domain model**: `Category`, `CategoryTranslation`
|
|
||||||
(`src/app/core/categories/models/category-domain.model.ts`).
|
|
||||||
- **Facade**: `CategoryFacade` (`src/app/facades/platform/category.facade.ts`) via
|
|
||||||
`CategoryService` (`src/app/core/categories/category.service.ts`). Utils:
|
|
||||||
`category-tree.utils.ts`.
|
|
||||||
|
|
||||||
**Legacy stack**: `ApiService.getCategories()` → `Category` (`src/app/models/category.model.ts`,
|
|
||||||
with `Subcategory`) via `normalizeCategory()`. Used by `ApiProductDataProvider.getCategories()`.
|
|
||||||
Note: two different `Category` types exist (`src/app/models/category.model.ts` vs
|
|
||||||
`src/app/core/categories/models/category-domain.model.ts`) — a known duplication.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. Domain: Backoffice storefront data
|
|
||||||
|
|
||||||
Storefront-facing "cards" data (distinct from the admin/backoffice feature area).
|
|
||||||
|
|
||||||
- **Interface**: `BackofficeDataProvider`
|
|
||||||
(`src/app/core/backoffice/providers/backoffice-data-provider.interface.ts`) —
|
|
||||||
`loadProducts(): Observable<ProductCardConfig[]>`, `loadCategories(): Observable<CategoryCardConfig[]>`.
|
|
||||||
- **DI token**: `BACKOFFICE_DATA_PROVIDER` (`src/app/core/backoffice/backoffice-data-provider.token.ts`)
|
|
||||||
— `mock` → `MockBackofficeDataProvider`, else → `ApiBackofficeDataProvider`.
|
|
||||||
- **Impls**: `ApiBackofficeDataProvider` (LIVE, `GET /api/backoffice/products`,
|
|
||||||
`GET /api/backoffice/categories`), `MockBackofficeDataProvider`
|
|
||||||
(`src/app/core/backoffice/providers/*`).
|
|
||||||
- **Models**: `ProductCardConfig` (`src/app/shared/models/ui/product-card.model.ts`),
|
|
||||||
`CategoryCardConfig` (`src/app/shared/models/ui/category-card.model.ts`),
|
|
||||||
`ButtonConfig` (`button.model.ts`). Barrel: `src/app/shared/models/ui/index.ts`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. Domain: Cart / orders / payments
|
|
||||||
|
|
||||||
Cart state is **LOCAL-ONLY** but checkout produces LIVE payment/order calls.
|
|
||||||
|
|
||||||
- **`CartService`** (`src/app/services/cart.service.ts`) — signal-based cart, persisted to
|
|
||||||
localStorage key `marketplace_cart` (+ Telegram CloudStorage when in Telegram WebApp). No
|
|
||||||
backend for cart contents. Models: `CartItem` (extends `Item`), `DeliveryOption`.
|
|
||||||
- **Checkout → `ApiService`** (see §4): `POST /cart` (`CartPaymentRequest`),
|
|
||||||
`POST /orders` (`CreateOrderRequest`→`CreateOrderResponse`), `POST /purchase-email`,
|
|
||||||
QR/card status polling on `qrApiUrl`.
|
|
||||||
- Request/response DTOs live inline in `api.service.ts`: `QrCreateRequest`, `QrCreateResponse`,
|
|
||||||
`CartPaymentRequest`, `CreateOrderRequest`, `CreateOrderResponse`, `QrDynamicStatusResponse`.
|
|
||||||
- Admin-side order/transaction views are a **separate** mock domain — see §14.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 11. Domain: Reviews & questions (engagement)
|
|
||||||
|
|
||||||
Customer-facing. LIVE via `ApiService`. Interface methods on `ProductDataProvider`:
|
|
||||||
`loadRating`, `loadReviews`, `loadQuestions`, `submitReview`, `submitQuestion`.
|
|
||||||
Endpoints: `POST /items/{id}/callback` (review), `POST /items/{id}/questiion` (question, typo
|
|
||||||
preserved). Reads derive reviews/questions/rating from `GET /items/{id}` payload (no dedicated
|
|
||||||
list endpoints yet). Models in `product-engagement.model.ts` (§7). Admin **moderation** of
|
|
||||||
reviews/reports is a separate mock domain — see §14.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 12. Domain: Location / regions
|
|
||||||
|
|
||||||
`LocationService` (`src/app/services/location.service.ts`), LIVE:
|
|
||||||
- `GET /regions` (marketplace base) → `Region[]`; falls back to 6 hardcoded regions on error.
|
|
||||||
- `GET http://ip-api.com/json/?fields=...` (external geo-IP, no key) for auto-detect.
|
|
||||||
Models: `Region`, `GeoIpResponse` (`src/app/models/location.model.ts`). Region id feeds the
|
|
||||||
`X-Region` header (§3).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 13. Domain: Widgets / dynamic renderer
|
|
||||||
|
|
||||||
Widget manifest is LIVE (static/remote JSON), widget data is derived from products/categories.
|
|
||||||
|
|
||||||
- **`WidgetManifestService`** (`src/app/widgets/registry/widget-manifest.service.ts`) — GETs
|
|
||||||
`bootstrap.widgetRegistry.manifestUrl` or fallback
|
|
||||||
`/assets/mock/bootstrap/widget-manifest.json` → `WidgetManifestFile`.
|
|
||||||
- **`WidgetRegistryService`** (`src/app/widgets/registry/widget-registry.service.ts`),
|
|
||||||
**`WidgetHostService`** (`src/app/dynamic-renderer/widget-host/widget-host.service.ts`).
|
|
||||||
- Contracts (`src/app/widgets/contracts/`): `widget-manifest.contract.ts`
|
|
||||||
(`WidgetManifestEntry/File`, `WidgetSettingsSchema`, `WidgetMetadataSupport`,
|
|
||||||
`WidgetLayoutSupport`, `WidgetDataSourceName`), `widget-component.contract.ts`
|
|
||||||
(`WidgetRenderContext`, `RegisteredWidget`, `ResolvedWidget`), `widget-data.contract.ts`
|
|
||||||
(`HeroWidgetData`, `CategoriesWidgetData`, `ProductCollectionWidgetData`, `BannerWidgetData`,
|
|
||||||
`HtmlWidgetData`, `PartnersWidgetData`, `FooterWidgetData`, `HeroSlideData`,
|
|
||||||
`WidgetResolvedContext`).
|
|
||||||
- Renderer models: `src/app/dynamic-renderer/{page-renderer,section-renderer,widget-host}/*.model.ts`.
|
|
||||||
- Widget data sources (`featured|latest|category|manual|related|root|parent`) map back onto
|
|
||||||
the product/category providers of §7–§8.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 14. Admin gateways (feature area)
|
|
||||||
|
|
||||||
`src/app/features/admin/**`. Each domain follows Facade → Gateway (interface) → LocalGateway.
|
|
||||||
**Only categories and dashboard-metrics use a DI token; all others inject the local class
|
|
||||||
directly (MOCK-ONLY, no seam).** Only `AdminCategoriesApiGateway` is a real HTTP impl.
|
|
||||||
|
|
||||||
| Domain | Interface | Local (mock) impl | Real impl | DI token | Facade | Seam status |
|
|
||||||
|---|---|---|---|---|---|---|
|
|
||||||
| Categories | `admin-categories-gateway.interface.ts` (`AdminCategoriesGateway`) | `admin-categories-local.gateway.ts` | `admin-categories-api.gateway.ts` (**HttpClient**) | `ADMIN_CATEGORIES_GATEWAY` (`admin-categories-gateway.token.ts`) | `AdminCategoriesFacade` | MOCK-SWAPPABLE (real impl exists) |
|
|
||||||
| Dashboard metrics | `admin-dashboard-metrics.gateway.interface.ts` (`AdminDashboardMetricsGateway`) | `admin-dashboard-metrics.local.gateway.ts` | none | `ADMIN_DASHBOARD_METRICS_GATEWAY` (`admin-dashboard-metrics-gateway.token.ts`) | `AdminDashboardFacade` | MOCK-SWAPPABLE (token only) |
|
|
||||||
| Orders | `admin-orders-gateway.interface.ts` (`AdminOrdersGateway`) | `admin-orders-local.gateway.ts` | none | **none** | `AdminOrdersFacade` (injects `AdminOrdersLocalGateway`) | MOCK-ONLY (no seam) |
|
|
||||||
| Products | `admin-products-gateway.interface.ts` (`AdminProductsGateway`) | `admin-products-local.gateway.ts` | none | **none** | `AdminProductsFacade` (injects local) | MOCK-ONLY (no seam) |
|
|
||||||
| Users | `admin-users-gateway.interface.ts` (`AdminUsersGateway`) | `admin-users-local.gateway.ts` | none | **none** | `AdminUsersFacade` (injects local) | MOCK-ONLY (no seam) |
|
|
||||||
| Transactions | `admin-transactions-gateway.interface.ts` (`AdminTransactionsGateway`) | `admin-transactions-local.gateway.ts` | none | **none** | `AdminTransactionsFacade` (injects local) | MOCK-ONLY (no seam) |
|
|
||||||
| Monitoring | `admin-monitoring-gateway.interface.ts` (`AdminMonitoringGateway`) | `admin-monitoring-local.gateway.ts` | none | **none** | `AdminMonitoringFacade` (injects local) | MOCK-ONLY (no seam) |
|
|
||||||
| Moderation | `admin-moderation-gateway.interface.ts` (`AdminModerationGateway`) | `admin-moderation-local.gateway.ts` | none | **none** | `AdminModerationFacade` (injects local) | MOCK-ONLY (no seam) |
|
|
||||||
| Customers | (no gateway of its own) | reuses `AdminOrdersLocalGateway` | none | **none** | `AdminCustomersFacade` (injects orders local) | MOCK-ONLY (derived) |
|
|
||||||
| Analytics | (no gateway of its own) | reuses orders/products/moderation local + `ADMIN_CATEGORIES_GATEWAY` + `AdminDashboardFacade` | none | partial (categories token) | `AdminAnalyticsFacade` | MOCK-ONLY (derived) |
|
|
||||||
|
|
||||||
Gateway interface method contracts (the shapes a backend must satisfy):
|
|
||||||
|
|
||||||
- **`AdminCategoriesGateway`**: `loadCategories(filters)`, `loadCategory(id)`, `createCategory`,
|
|
||||||
`updateCategory`, `deleteCategory`, `restoreCategory`, `isSlugTaken(slug,excludingId)`.
|
|
||||||
- **`AdminDashboardMetricsGateway`**: `loadMetrics(): AdminDashboardMetrics`.
|
|
||||||
- **`AdminOrdersGateway`**: `loadOrders(filters)`, `loadOrder(id)`, `updateStatus(id,status)`,
|
|
||||||
`requestRefund(id)`, `addNote(id,note,internal)`, `archiveOrder`, `restoreOrder`, `deleteOrder`.
|
|
||||||
- **`AdminProductsGateway`**: `loadProducts(filters)`, `loadProduct(id)`, `loadCategories()`,
|
|
||||||
`createProduct`, `updateProduct`, `deleteProduct`, `duplicateProduct`, `archiveProduct`,
|
|
||||||
`restoreProduct`.
|
|
||||||
- **`AdminUsersGateway`**: `loadUsers`, `loadRoles`, `loadInvitations`, `loadSessions(userId)`,
|
|
||||||
`loadAudit(userId)`, `setUserRole`, `setUserStatus`, `inviteUser(email,roleId,scope)`,
|
|
||||||
`revokeInvitation`, `revokeSession`.
|
|
||||||
- **`AdminTransactionsGateway`**: `loadTransactions(filters)`, `retryFailed(id)`,
|
|
||||||
`setFraudFlag(id,flagged)`.
|
|
||||||
- **`AdminMonitoringGateway`**: `loadEvents(filters)`, `loadQueues()`, `loadWebhooks()`.
|
|
||||||
- **`AdminModerationGateway`**: `loadReviews(filters)`, `loadReview(id)`, `setReviewStatus`,
|
|
||||||
`setReviewVisible`, `setReviewPinned`, `setReviewFeatured`, `addModeratorNote`, `deleteReview`,
|
|
||||||
`loadReports()`, `setReportStatus(id,status)`.
|
|
||||||
|
|
||||||
Admin model files (all under `src/app/features/admin/<domain>/models/`) — see §23.
|
|
||||||
|
|
||||||
Note: `AdminRole` is defined **twice** with different meaning — `src/app/core/auth/models/
|
|
||||||
permission.model.ts` (auth roles `Owner|Administrator|Editor|Support|ReadOnly`) vs
|
|
||||||
`src/app/features/admin/users/models/admin-user.model.ts` (`AdminRole` interface {id,name,...}).
|
|
||||||
Flag for backend/naming reconciliation.
|
|
||||||
|
|
||||||
Local gateways are localStorage / in-memory backed (facades also inject `LocalStorageService`
|
|
||||||
for overlay persistence, e.g. orders/moderation/categories/products).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 15. Domain: Media library
|
|
||||||
|
|
||||||
MOCK-SWAPPABLE via abstract-class token, no real impl.
|
|
||||||
|
|
||||||
- **Contract**: abstract class `MediaRepository` (`src/app/core/media/media-repository.ts`) —
|
|
||||||
`list(params?)`, `upload(file,options?)`, `remove(id)`, `update(id,patch)`, `listFolders()`.
|
|
||||||
- **Binding**: `app.config.ts` → `{ provide: MediaRepository, useClass: MockMediaRepository }`.
|
|
||||||
- **Mock impl**: `MockMediaRepository` (`src/app/core/media/mock-media-repository.service.ts`,
|
|
||||||
uses `HttpClient` to read seed assets). Also `MediaUsageService`
|
|
||||||
(`src/app/core/media/media-usage.service.ts`).
|
|
||||||
- **Facade**: `MediaLibraryFacade` (`src/app/features/backoffice/media/facade/media-library.facade.ts`),
|
|
||||||
page `media-library-page.component.ts`.
|
|
||||||
- **Models** (`src/app/core/media/models/media-asset.model.ts`): `MediaAsset`, `MediaAssetKind`,
|
|
||||||
`MediaSort`, `MediaListParams`, `MediaUploadOptions`, `MediaListResult`.
|
|
||||||
- Admin-auth interceptor already gates `/media/` paths (§3), anticipating a real media backend.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 16. Domain: Content management / static pages
|
|
||||||
|
|
||||||
**LOCAL-ONLY** — operates on the already-loaded `BootstrapConfig.staticPages`, no dedicated
|
|
||||||
backend calls. Publishing/writing bootstrap is not implemented client-side (FUTURE).
|
|
||||||
|
|
||||||
- **Facade**: `ContentManagementFacade` (`src/app/features/content-management/facade/content-management.facade.ts`)
|
|
||||||
→ `ContentPageService` (`.../services/content-page.service.ts`). Public API: `pages(bootstrap)`,
|
|
||||||
`hasSeoContent(page)`, `contentHealth(bootstrap)`, `resolvePage(bootstrap,keyOrSlug,locale)`,
|
|
||||||
`validatePages(bootstrap)`, `toBootstrapRecord(bootstrap)`, `serializePages(pages)`,
|
|
||||||
`normalizeSlug`.
|
|
||||||
- `ContentPageService` maps between bootstrap `StaticPagesConfig` and the editor `ContentPage`
|
|
||||||
view model (normalize / validate / `toBootstrapRecord`). This is the adapter.
|
|
||||||
- **Models** (`src/app/features/content-management/models/`): `ContentPage`,
|
|
||||||
`ContentPageTranslation`, `ContentPageSeoConfig`, `ContentPageStatus`,
|
|
||||||
`ContentPageBootstrapInput` (`content-page.model.ts`); `LegalPageKey`, `LegalPageDefinition`
|
|
||||||
(`legal-pages.model.ts`). Backend-shaped counterpart: `StaticPageConfig`,
|
|
||||||
`StaticPagesConfig`, `ResolvedStaticPage`, `LocalizedHtmlContent`, `LocalizedTextContent`
|
|
||||||
(`src/app/shared/models/config/static-page.model.ts`).
|
|
||||||
- Consumers: `static-pages-editor.component.ts`, `page-editor.component.ts`,
|
|
||||||
`static-page.component.ts` (`src/app/pages/static-page/`), resolved via
|
|
||||||
`StaticPageResolverService`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 17. Domain: Project editor / builder
|
|
||||||
|
|
||||||
**LOCAL-ONLY** today — edits an in-memory `BootstrapConfig`, persists drafts to localStorage;
|
|
||||||
no publish/save-to-backend HTTP call exists. A builder API is declared only as
|
|
||||||
`BootstrapConfig.apiEndpoints.builder` (runtime-declared, FUTURE).
|
|
||||||
|
|
||||||
- **Facade**: `ProjectEditorFacade` (`src/app/features/project-editor/facade/project-editor.facade.ts`)
|
|
||||||
— orchestrates undo/redo `History<BootstrapConfig>`, injects `ConfigService`,
|
|
||||||
`ProjectEditorIoService` (JSON import/export of bootstrap), `ProjectEditorPreviewService`,
|
|
||||||
`LocaleSyncService`, `PlatformRuntimeService`, `ProjectValidator`,
|
|
||||||
`ProjectEditorDraftStorageService` (localStorage drafts), `EditorSchemaService`.
|
|
||||||
- Services (`src/app/features/project-editor/services/`): `project-editor-io.service.ts`
|
|
||||||
(`exportBootstrap`/`importBootstrap` = JSON.stringify/parse), `project-editor-draft-storage.service.ts`,
|
|
||||||
`project-editor-preview.service.ts`, `project-validator.service.ts`, `locale-sync.service.ts`.
|
|
||||||
Schema: `schema/editor-schema.service.ts`, `schema/field-schema.model.ts`, `schema/validators/`.
|
|
||||||
- **Models**: `project-editor.model.ts` (`ProjectEditorState`, `ProjectEditorSectionId`,
|
|
||||||
`ProjectEditorWidgetPreset`, `BuilderSectionStatus`), `builder/builder-groups.model.ts`.
|
|
||||||
- Consumers: `project-editor-page.component.ts`, `homepage-section.component.ts`,
|
|
||||||
`project-editor-nav.component.ts`. Also drives admin products/categories/dashboard facades
|
|
||||||
(which inject `ProjectEditorFacade`).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 18. Domain: Search
|
|
||||||
|
|
||||||
**LOCAL-ONLY orchestration over the product/category providers** — no dedicated search backend;
|
|
||||||
`SearchFacade` composes `ProductFacade` + `CategoryFacade` results and manages history/trending/
|
|
||||||
autocomplete/cache client-side.
|
|
||||||
|
|
||||||
- **Facade**: `SearchFacade` (`src/app/features/search/facade/search.facade.ts`) injects
|
|
||||||
`ProductFacade`, `CategoryFacade`, `SearchAutocompleteService`, `SearchHistoryService`,
|
|
||||||
`SearchTrendingService`, `SearchCacheService`, `SearchStore`, `TranslateService`.
|
|
||||||
- Services (`src/app/features/search/services/`): `search-autocomplete.service.ts`,
|
|
||||||
`search-history.service.ts` + `search-history.repository.ts` (interface
|
|
||||||
`SearchHistoryRepository{load,save,clear}`, localStorage), `search-trending.service.ts`,
|
|
||||||
`search-cache.service.ts`. Store: `store/search.store.ts`.
|
|
||||||
- **Models**: `src/app/features/search/models/search.model.ts` (`SearchQuery`, `SearchResult<T>`,
|
|
||||||
`SearchSuggestion`, `SearchFilterType`, `FilterGroup`, `FilterOption`, `SortOption`,
|
|
||||||
`SearchHistory`, `SearchAnalyticsEvent`, `SearchNavigationTarget`), `search-state.model.ts`
|
|
||||||
(`SearchState`). Duplicated under `src/app/core/search/models/`.
|
|
||||||
- Underlying live traffic is `GET /searchitems` (§4) via `ProductFacade.searchProducts`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 19. Domain: User experience (wishlist/compare/etc.)
|
|
||||||
|
|
||||||
**LOCAL-ONLY** (guest-first). MOCK-SWAPPABLE token exists for a future authenticated backend.
|
|
||||||
|
|
||||||
- **Interface**: `UserExperienceRepository`
|
|
||||||
(`src/app/core/user-experience/repositories/user-experience.repository.ts`).
|
|
||||||
- **DI token**: `USER_EXPERIENCE_REPOSITORY`
|
|
||||||
(`src/app/core/user-experience/user-experience-repository.token.ts`) → currently always
|
|
||||||
`LocalUserExperienceRepository` (localStorage). Comment notes it "can be switched to
|
|
||||||
authenticated repository later."
|
|
||||||
- **Facade**: `UserExperienceFacade` (`src/app/facades/platform/user-experience.facade.ts`) —
|
|
||||||
wishlist / compare / recently-viewed / saved-searches / continue-browsing, all signals.
|
|
||||||
- **Models** (`src/app/core/user-experience/models/user-experience.model.ts`): `FavoriteItem`,
|
|
||||||
`ComparedProduct`, `RecentlyViewedItem`, `SavedSearch`, `ContinueBrowsingState`. Config shape:
|
|
||||||
`user-experience-config.model.ts` (limits, from bootstrap).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 20. Domain: Diagnostics
|
|
||||||
|
|
||||||
**LOCAL-ONLY** — inspects runtime/bootstrap/widget state; the one live-ish probe is API ping.
|
|
||||||
|
|
||||||
- **Facade**: `DiagnosticsFacade` (`src/app/features/diagnostics/facade/diagnostics.facade.ts`)
|
|
||||||
injects `ConfigService`, `TenantResolverService`, `PlatformRuntimeStateService`,
|
|
||||||
`RuntimeDiagnosticsService`, `WidgetManifestService`, `WidgetRegistryService`,
|
|
||||||
`RuntimeProviderStrategyService`, `DiagnosticsLoggerService`, `TranslateService`, `Router`.
|
|
||||||
- Validators: `validators/runtime-diagnostics.validator.ts` (uses `HttpClient` for API health
|
|
||||||
probe), `bootstrap-diagnostics.validator.ts`, `diagnostics-health-score.util.ts`.
|
|
||||||
- **Models** (`src/app/features/diagnostics/models/diagnostics.model.ts`): `DiagnosticEntry`,
|
|
||||||
`DiagnosticSeverity`, `DiagnosticsHealthSummary`, `DiagnosticsReport`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 21. Facade catalog
|
|
||||||
|
|
||||||
| Facade | File | Depends on | Consumed by (examples) |
|
|
||||||
|---|---|---|---|
|
|
||||||
| `ProductFacade` | `facades/platform/product.facade.ts` | `ProductDataService` → `PRODUCT_DATA_PROVIDER` | catalog/product containers, `SearchFacade` |
|
|
||||||
| `CategoryFacade` | `facades/platform/category.facade.ts` | `CategoryService` → `CATEGORY_REPOSITORY` | catalog nav, `SearchFacade` |
|
|
||||||
| `SearchFacade` | `features/search/facade/search.facade.ts` | ProductFacade, CategoryFacade, search services | search bar/pages |
|
|
||||||
| `UserExperienceFacade` | `facades/platform/user-experience.facade.ts` | `USER_EXPERIENCE_REPOSITORY` | wishlist/compare UI |
|
|
||||||
| `UiRuntimeFacade` | `facades/runtime/ui-runtime.facade.ts` | `ConfigService` | header/branding |
|
|
||||||
| `WebsiteRuntimeFacade` | `facades/website/website-runtime.facade.ts` | config/page renderer | dynamic pages |
|
|
||||||
| `AuthFacade` | `core/auth/services/auth-facade.service.ts` | AuthService, SessionService, PermissionService | login/guarded UI |
|
|
||||||
| `MediaLibraryFacade` | `features/backoffice/media/facade/media-library.facade.ts` | `MediaRepository` | media page |
|
|
||||||
| `ContentManagementFacade` | `features/content-management/facade/...` | `ContentPageService` (bootstrap) | content dashboard/editor |
|
|
||||||
| `ProjectEditorFacade` | `features/project-editor/facade/...` | config + editor services (localStorage) | builder pages, admin facades |
|
|
||||||
| `DiagnosticsFacade` | `features/diagnostics/facade/...` | runtime/config/widget services | diagnostics page |
|
|
||||||
| `AdminCategoriesFacade` | `features/admin/categories/facade/...` | `ADMIN_CATEGORIES_GATEWAY`, ProjectEditorFacade | admin categories pages |
|
|
||||||
| `AdminProductsFacade` | `features/admin/products/facade/...` | `AdminProductsLocalGateway`, ProjectEditorFacade | admin products pages |
|
|
||||||
| `AdminOrdersFacade` | `features/admin/orders/facade/...` | `AdminOrdersLocalGateway` | admin orders pages |
|
|
||||||
| `AdminUsersFacade` | `features/admin/users/facade/...` | `AdminUsersLocalGateway` | admin users pages |
|
|
||||||
| `AdminTransactionsFacade` | `features/admin/transactions/facade/...` | `AdminTransactionsLocalGateway` | admin transactions pages |
|
|
||||||
| `AdminMonitoringFacade` | `features/admin/monitoring/facade/...` | `AdminMonitoringLocalGateway` | admin monitoring page |
|
|
||||||
| `AdminModerationFacade` | `features/admin/moderation/facade/...` | `AdminModerationLocalGateway` | moderation pages |
|
|
||||||
| `AdminCustomersFacade` | `features/admin/customers/facade/...` | `AdminOrdersLocalGateway` (derives customers from orders) | customers pages |
|
|
||||||
| `AdminAnalyticsFacade` | `features/admin/analytics/facade/...` | orders/products/moderation local + `ADMIN_CATEGORIES_GATEWAY` + `AdminDashboardFacade` | analytics page |
|
|
||||||
| `AdminDashboardFacade` | `features/admin/dashboard/facade/...` | `ADMIN_DASHBOARD_METRICS_GATEWAY`, ProjectEditorFacade, AdminAuthService | admin dashboard |
|
|
||||||
|
|
||||||
`ProductFacade` public API: `getProducts, getProduct, getCategories, searchProducts,
|
|
||||||
getFeaturedProducts, getLatestProducts, getProductsByCategory, getRelatedProducts, loadRating,
|
|
||||||
loadReviews, loadQuestions, submitReview, submitQuestion, search(criteria), filter, sort,
|
|
||||||
loadCatalog`. `CategoryFacade`: signals (`allCategories, categoryTree, rootCategories,
|
|
||||||
selectedCategory, breadcrumb, children, loading, error`) + `loadCategories, selectCategory,
|
|
||||||
getAllCategories, getCategoryTree, getRootCategories, getCategoryById, getBreadcrumb, getChildren`.
|
|
||||||
`UserExperienceFacade`: `isInWishlist, toggleWishlist, clearWishlist, isInCompare, addToCompare,
|
|
||||||
removeFromCompare, clearCompare, trackRecentlyViewed, saveSearch, removeSavedSearch,
|
|
||||||
saveContinueBrowsing, getContinueBrowsing` + wishlist/compare signals & counts.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 22. Gateway / provider master table
|
|
||||||
|
|
||||||
| Gateway/provider | Interface path | Mock/local impl | Real/API impl | DI token | Consuming facade(s) | Status |
|
|
||||||
|---|---|---|---|---|---|---|
|
|
||||||
| ConfigProvider | `core/config/config-provider.interface.ts` | `core/bootstrap/providers/mock-bootstrap.provider.ts` | `core/bootstrap/providers/api-bootstrap.provider.ts` | `CONFIG_PROVIDER` | UiRuntime, WebsiteRuntime, ProjectEditor, ContentMgmt, Diagnostics (via ConfigService) | LIVE (`GET /bootstrap`) |
|
|
||||||
| ProductDataProvider | `core/products/providers/product-data-provider.interface.ts` | none bound | `core/products/providers/api-product-data.provider.ts` | `PRODUCT_DATA_PROVIDER` | ProductFacade | LIVE |
|
|
||||||
| CategoryRepository | `core/categories/repositories/category.repository.ts` | none bound | `core/categories/repositories/api-category.repository.ts` | `CATEGORY_REPOSITORY` | CategoryFacade | LIVE |
|
|
||||||
| BackofficeDataProvider | `core/backoffice/providers/backoffice-data-provider.interface.ts` | `mock-backoffice-data.provider.ts` | `api-backoffice-data.provider.ts` | `BACKOFFICE_DATA_PROVIDER` | storefront cards | LIVE (`/api/backoffice/*`) |
|
|
||||||
| UserExperienceRepository | `core/user-experience/repositories/user-experience.repository.ts` | `local-user-experience.repository.ts` | none | `USER_EXPERIENCE_REPOSITORY` | UserExperienceFacade | LOCAL-ONLY |
|
|
||||||
| MediaRepository | `core/media/media-repository.ts` (abstract class) | `core/media/mock-media-repository.service.ts` | none | `MediaRepository` class (app.config.ts) | MediaLibraryFacade | MOCK-SWAPPABLE |
|
|
||||||
| SearchHistoryRepository | `features/search/services/search-history.repository.ts` | (localStorage impl) | none | (injected concretely) | SearchFacade (via SearchHistoryService) | LOCAL-ONLY |
|
|
||||||
| AdminCategoriesGateway | `features/admin/categories/services/admin-categories-gateway.interface.ts` | `admin-categories-local.gateway.ts` | `admin-categories-api.gateway.ts` | `ADMIN_CATEGORIES_GATEWAY` | AdminCategoriesFacade, AdminAnalyticsFacade | MOCK-SWAPPABLE (real impl exists) |
|
|
||||||
| AdminDashboardMetricsGateway | `features/admin/dashboard/services/admin-dashboard-metrics.gateway.interface.ts` | `admin-dashboard-metrics.local.gateway.ts` | none | `ADMIN_DASHBOARD_METRICS_GATEWAY` | AdminDashboardFacade | MOCK-SWAPPABLE (token only) |
|
|
||||||
| AdminOrdersGateway | `features/admin/orders/services/admin-orders-gateway.interface.ts` | `admin-orders-local.gateway.ts` | none | **none** | AdminOrdersFacade, AdminCustomersFacade, AdminAnalyticsFacade | MOCK-ONLY (no seam) |
|
|
||||||
| AdminProductsGateway | `features/admin/products/services/admin-products-gateway.interface.ts` | `admin-products-local.gateway.ts` | none | **none** | AdminProductsFacade, AdminAnalyticsFacade | MOCK-ONLY (no seam) |
|
|
||||||
| AdminUsersGateway | `features/admin/users/services/admin-users-gateway.interface.ts` | `admin-users-local.gateway.ts` | none | **none** | AdminUsersFacade | MOCK-ONLY (no seam) |
|
|
||||||
| AdminTransactionsGateway | `features/admin/transactions/services/admin-transactions-gateway.interface.ts` | `admin-transactions-local.gateway.ts` | none | **none** | AdminTransactionsFacade | MOCK-ONLY (no seam) |
|
|
||||||
| AdminMonitoringGateway | `features/admin/monitoring/services/admin-monitoring-gateway.interface.ts` | `admin-monitoring-local.gateway.ts` | none | **none** | AdminMonitoringFacade | MOCK-ONLY (no seam) |
|
|
||||||
| AdminModerationGateway | `features/admin/moderation/services/admin-moderation-gateway.interface.ts` | `admin-moderation-local.gateway.ts` | none | **none** | AdminModerationFacade, AdminAnalyticsFacade | MOCK-ONLY (no seam) |
|
|
||||||
| (Auth session) | — (`TelegramSessionApiService`) | mock via `mockDataInterceptor` | `services/telegram-session-api.service.ts` | n/a (concrete) | AuthService, AdminAuthService, AuthFacade | LIVE |
|
|
||||||
| (Ed25519 admin auth) | — (`AuthApiService`) | none | `core/auth/services/auth-api.service.ts` | n/a (concrete) | AuthService (Ed25519 flow) | LIVE wiring, backend absent |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 23. Model / DTO catalog
|
|
||||||
|
|
||||||
Grouped by boundary role. B = backend-shaped/wire DTO, V = frontend view model, C = bootstrap
|
|
||||||
config shape. Adapter column names the mapper if distinct.
|
|
||||||
|
|
||||||
### Core wire DTOs / domain (B)
|
|
||||||
- `Item` + supporting (`src/app/models/item.model.ts`) — **primary product wire shape**; adapter
|
|
||||||
`ApiService.normalizeItem()`.
|
|
||||||
- `Category`, `Subcategory` (`src/app/models/category.model.ts`) — legacy category wire; adapter
|
|
||||||
`ApiService.normalizeCategory()`.
|
|
||||||
- `CategoryDto`, `CategoryNameDto` (`src/app/core/categories/dto/category.dto.ts`) — clean-stack
|
|
||||||
wire DTO; adapter `CategoryMapper`.
|
|
||||||
- `Region`, `GeoIpResponse` (`src/app/models/location.model.ts`).
|
|
||||||
- Payment/order DTOs inline in `src/app/services/api.service.ts`: `QrCreateRequest`,
|
|
||||||
`QrCreateResponse`, `CartPaymentRequest`, `CreateOrderRequest`, `CreateOrderResponse`,
|
|
||||||
`QrDynamicStatusResponse`.
|
|
||||||
- Auth: `AuthSession`, `WebSessionStart` (`src/app/models/auth.model.ts`); `AuthChallenge`,
|
|
||||||
`VerifySignatureRequest`, `AuthTokenPair`, `RefreshTokenRequest`, `JwtClaims`
|
|
||||||
(`src/app/core/auth/models/auth-api.model.ts`).
|
|
||||||
|
|
||||||
### Domain / view models (V)
|
|
||||||
- Products: `Product`(=Item alias), `ProductListQuery`, `ProductSearchQuery`, `ProductListResult`,
|
|
||||||
`ProductFilters`, `RelatedProductsQuery`, `RelatedProductCollection`, `ProductVariantSelection`
|
|
||||||
(`core/products/models/product-domain.model.ts`).
|
|
||||||
- Engagement: `Review`, `Answer`, `Question`, `RatingSummary`, `RatingDistributionEntry`,
|
|
||||||
`EngagementListQuery`, `EngagementListResult<T>`, `SubmitReviewInput`, `SubmitQuestionInput`
|
|
||||||
(`core/products/models/product-engagement.model.ts`).
|
|
||||||
- Catalog experience: `SearchCriteria`, `FilterDefinition`, `FilterOption`, `SortDefinition`,
|
|
||||||
`CatalogView`, `SearchResult` (`core/products/models/catalog-experience.model.ts`);
|
|
||||||
catalog state (`features/website/catalog/models/catalog-state.model.ts`).
|
|
||||||
- Category domain: `Category`, `CategoryTranslation` (`core/categories/models/category-domain.model.ts`).
|
|
||||||
- Media: `MediaAsset` + params/results (`core/media/models/media-asset.model.ts`).
|
|
||||||
- User experience: `FavoriteItem`, `ComparedProduct`, `RecentlyViewedItem`, `SavedSearch`,
|
|
||||||
`ContinueBrowsingState` (`core/user-experience/models/user-experience.model.ts`).
|
|
||||||
- Search: `search.model.ts` + `search-state.model.ts` (`features/search/models/`, dup in `core/search/models/`).
|
|
||||||
- Content: `ContentPage`, `ContentPageTranslation`, `ContentPageSeoConfig`, `ContentPageStatus`,
|
|
||||||
`ContentPageBootstrapInput`, `LegalPageKey`, `LegalPageDefinition`
|
|
||||||
(`features/content-management/models/`); adapter `ContentPageService`.
|
|
||||||
- Project editor: `ProjectEditorState`, `ProjectEditorSectionId`, `ProjectEditorWidgetPreset`,
|
|
||||||
`BuilderSectionStatus` (`features/project-editor/models/`), `builder-groups.model.ts`.
|
|
||||||
- Diagnostics: `DiagnosticEntry`, `DiagnosticsHealthSummary`, `DiagnosticsReport`
|
|
||||||
(`features/diagnostics/models/diagnostics.model.ts`).
|
|
||||||
- Widgets: contracts in `src/app/widgets/contracts/*` and renderer `*.model.ts` (see §13).
|
|
||||||
|
|
||||||
### Admin models (V, all under `features/admin/<domain>/models/`)
|
|
||||||
- `admin-order.model.ts`: `AdminOrder`, `AdminOrderCustomer`, `AdminOrderPayment`,
|
|
||||||
`AdminOrderShipping`, `AdminOrderItem`, `AdminOrderTimelineEntry`, `AdminOrderStatus`,
|
|
||||||
`AdminOrderPaymentStatus`, `AdminOrderTimelineEventKey`, `AdminOrderListFilters`,
|
|
||||||
`AdminOrdersListResult`.
|
|
||||||
- `admin-product.model.ts`: `AdminProduct` (+ `AdminProductMedia`, `AdminProductSpecification`,
|
|
||||||
`AdminProductVariant(Price)`, `AdminProductVariantAttributeDef`, `AdminProductAttribute`,
|
|
||||||
`AdminProductTranslation`, `AdminProductSeo`, `AdminProductReview`, `AdminProductQuestion`),
|
|
||||||
`AdminProductListFilters`, `AdminProductsListResult`, `AdminProductCategoryOption`, status/sort/mode types.
|
|
||||||
- `admin-category.model.ts`: `AdminCategory`, `AdminCategoryTranslation`, `AdminCategorySeo`,
|
|
||||||
`AdminCategoryAttribute`, `AdminCategoryListFilters`, status/mode types.
|
|
||||||
- `admin-user.model.ts`: `AdminUser`, `AdminRole`, `AdminInvitation`, `AdminSession`,
|
|
||||||
`AdminUserAuditEntry`, scope/status/invitation-status types.
|
|
||||||
- `admin-transaction.model.ts`: `AdminTransaction`, `AdminTransactionAuditEntry`,
|
|
||||||
`AdminTransactionListFilters`, `AdminTransactionsListResult`, type/status types.
|
|
||||||
- `admin-monitoring.model.ts`: `AdminMonitoringEvent`, `AdminMonitoringEventFilters`,
|
|
||||||
`AdminQueue`, `AdminWebhookDelivery`, category/level/queue/webhook status types.
|
|
||||||
- `admin-review.model.ts`: `AdminReview`, `AdminReviewTimelineEntry`, `AdminReviewListFilters`,
|
|
||||||
`AdminReviewsListResult`, status/timeline types.
|
|
||||||
- `admin-report.model.ts`: `AdminReport`, `AdminReportTargetType`, `AdminReportStatus`.
|
|
||||||
- `admin-customer.model.ts`: `AdminCustomer`.
|
|
||||||
- `admin-analytics.model.ts`: `AdminAnalyticsSummary`, `AdminAnalyticsSeriesPoint`,
|
|
||||||
`AdminAnalyticsTopProduct`, `AdminLowStockProduct`, `AdminRecentActivityEntry`,
|
|
||||||
`AdminMarketplaceHealthCheck`, `AdminProductAnalytics(Row)`, `AdminCustomerAnalytics`,
|
|
||||||
`AdminRecommendationCard`, date-range/severity/health types.
|
|
||||||
- `admin-dashboard.model.ts`: `AdminDashboardMetrics`, `AdminDashboardCardState<T>`,
|
|
||||||
`AdminDashboardQuickAction(Id)`, `AdminDashboardActivityEntry`, `AdminDashboardHealthCheck`,
|
|
||||||
`AdminDashboardHomeHealthCheck`, `AdminDashboardDraftField`, `AdminDashboardShortcut`, status types.
|
|
||||||
- Shell: `features/admin/shell/admin-nav.model.ts`.
|
|
||||||
|
|
||||||
### Bootstrap config shapes (C)
|
|
||||||
All under `src/app/shared/models/config/` — see §6 for the full list (24 files + barrel).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 24. Endpoint URL literals found in code
|
|
||||||
|
|
||||||
Marketplace API (relative to base): `/ping`, `/bootstrap`, `/category`, `/category/{id}`,
|
|
||||||
`/items/{id}`, `/items/randomitems`, `/searchitems`, `/cart`, `/orders`, `/purchase-email`,
|
|
||||||
`/regions`, `/websession/{sessionId}`, `/items/{id}/callback`, `/items/{id}/questiion`.
|
|
||||||
|
|
||||||
Backoffice storefront: `/api/backoffice/products`, `/api/backoffice/categories`.
|
|
||||||
|
|
||||||
Payment (`qrApiUrl` = `https://qr.vitanova.network/api`): `/qr`, `/qr/dynamic/{partnerId}/{qrId}`,
|
|
||||||
`/card/{partnerId}/{orderId}`. Const partner id `web-97ec-9c57-4dde-9037-3a68f7f83750`.
|
|
||||||
|
|
||||||
Session auth (`authApiUrl`): `/users/sessions`, `/users/sessions/{id}`.
|
|
||||||
|
|
||||||
Ed25519 admin auth (`authApiUrl`): `/api/admin/auth/challenge|verify|refresh|logout`
|
|
||||||
(not implemented server-side).
|
|
||||||
|
|
||||||
Static assets (not backend): `/assets/mock/bootstrap/bootstrap.json`,
|
|
||||||
`/assets/mock/bootstrap/widget-manifest.json`.
|
|
||||||
|
|
||||||
External (not this platform): `http://ip-api.com/json/...` (geo-IP),
|
|
||||||
`https://api.qrserver.com/v1/create-qr-code/...` (QR image), `https://t.me/{bot}`,
|
|
||||||
`tg://resolve?...`.
|
|
||||||
|
|
||||||
`mockDataInterceptor` URL matchers (mock mode only): `/ping`, `/users/sessions[/{id}]`,
|
|
||||||
`/category`, `/category/{id}`, `/items/{id}`, `/searchitems`, `/randomitems`, `/cart`,
|
|
||||||
`/websession/{id}[/qr]`, `/qr`, `/items/{id}/callback`, `/purchase-email`, `/qr/payment/{id}`.
|
|
||||||
|
|
||||||
**No literal `/admin/*`, `/builder/*`, or per-admin-domain backoffice CRUD paths exist in code.**
|
|
||||||
Those live only as `apiEndpoints.{builder,backoffice}` records inside the runtime bootstrap
|
|
||||||
document, and admin gateways are in-memory (they never construct a URL). Any concrete admin CRUD
|
|
||||||
path is therefore a proposal, not a verified literal — consistent with `docs/BACKEND_API.md`
|
|
||||||
Assumption #2.
|
|
||||||
|
|
||||||
The admin-auth-headers interceptor gates these path **segments** (anticipatory, not called yet):
|
|
||||||
`/admin/`, `/backoffice/`, `/builder/`, `/media/`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 25. Cross-check against existing docs
|
|
||||||
|
|
||||||
Skimmed: `docs/BACKEND_API.md` (canonical master spec, CURRENT/PLANNED/FUTURE tagging),
|
|
||||||
`docs/AUTH.md`, `docs/ADMIN.md`, `docs/BACKEND_API_REMAINING_WORK.md`,
|
|
||||||
`docs/architecture/foundation/**`, `docs/backend/BACKEND-INTEGRATION.md`.
|
|
||||||
|
|
||||||
Agreements (preserve these conventions downstream):
|
|
||||||
- `docs/BACKEND_API.md` already uses `GET /bootstrap`, the `*LocalGateway` → `*ApiGateway`
|
|
||||||
rebind pattern, and frozen auth/payment (ADR-010). Its CURRENT/PLANNED/FUTURE tagging maps
|
|
||||||
cleanly onto LIVE / MOCK-SWAPPABLE / MOCK-ONLY here.
|
|
||||||
- Assumption #2 (builder/backoffice paths are proposals, not literals) is confirmed by code.
|
|
||||||
- `submitQuestion` typo `questiion` and `callback` review path confirmed against code.
|
|
||||||
|
|
||||||
Discrepancies / things to flag for a human:
|
|
||||||
1. **`docs/BACKEND_API.md` PLANNED framing implies every admin domain is a token rebind.**
|
|
||||||
In code, only `ADMIN_CATEGORIES_GATEWAY` and `ADMIN_DASHBOARD_METRICS_GATEWAY` are
|
|
||||||
token-bound. Orders, products, users, transactions, monitoring, moderation (and derived
|
|
||||||
customers/analytics) inject the concrete `*LocalGateway` directly — no seam. A backend
|
|
||||||
integration for those requires adding a token first. This should be reconciled in the docs.
|
|
||||||
2. **Only one real admin API impl exists** (`AdminCategoriesApiGateway`). Everything else admin
|
|
||||||
is mock. Docs that describe admin endpoints as "PLANNED, served by local gateway" are
|
|
||||||
accurate in spirit but the swap ergonomics differ per domain (see #1).
|
|
||||||
3. **Duplicate `Category` types** (`src/app/models/category.model.ts` vs
|
|
||||||
`core/categories/models/category-domain.model.ts`) and **duplicate `AdminRole`**
|
|
||||||
(auth `permission.model.ts` string-union vs users `admin-user.model.ts` interface) — naming
|
|
||||||
collisions a backend/contract author should be warned about.
|
|
||||||
4. **Duplicate search models** under `features/search/models/` and `core/search/models/`.
|
|
||||||
5. **Content-management & project-editor "save/publish" has no client HTTP call.** Docs that
|
|
||||||
imply a builder publish endpoint should tag it FUTURE — there is no `PUT /bootstrap` or
|
|
||||||
builder-write call anywhere in code today; changes live in localStorage drafts + in-memory
|
|
||||||
bootstrap only.
|
|
||||||
6. `PRODUCT_DATA_PROVIDER` / `CATEGORY_REPOSITORY` token factories return the Api provider even
|
|
||||||
in `mock` mode (no mock class bound) — so `useMockData` does NOT mock products/categories at
|
|
||||||
the provider layer; mocking there relies entirely on `mockDataInterceptor`. Worth noting if a
|
|
||||||
doc claims a mock product provider exists.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
_Generated from source on branch `B2B`. Every path above is repo-relative to
|
|
||||||
`F:\dx\remote\marketplaces\`._
|
|
||||||
@@ -1,67 +0,0 @@
|
|||||||
---
|
|
||||||
id: ADR-0001
|
|
||||||
title: Multi-tenant marketplace platform vision and config-driven architecture
|
|
||||||
status: active
|
|
||||||
date: 2026-07-13
|
|
||||||
tags: ["architecture", "philosophy", "multi-tenant", "bootstrap"]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
This is not a single marketplace — it is a multi-tenant platform powering unlimited
|
|
||||||
marketplaces (e.g. electronics.example.com, books.example.com) from one codebase.
|
|
||||||
Every marketplace is configured from the backend via a bootstrap configuration
|
|
||||||
(`GET /bootstrap`). No marketplace-specific code may exist in the frontend.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
- The frontend (Angular 20, standalone components, Signals, RxJS, SCSS) is a pure
|
|
||||||
renderer. It owns render, navigation, interaction, validation, animations only.
|
|
||||||
- The backend (ASP.NET Core REST API) owns branding, pages, layouts, languages,
|
|
||||||
homepage, navigation, categories, products, footer, static pages, payment
|
|
||||||
configuration, and enabled features.
|
|
||||||
- Flow: Bootstrap → Runtime Provider → Configuration Store → Renderer → Widgets.
|
|
||||||
Nothing depends on build-time environments; everything depends on runtime
|
|
||||||
configuration.
|
|
||||||
- Bootstrap contains only data needed before the app starts (name, logo, colors,
|
|
||||||
languages, footer pages, homepage layout, navigation, enabled widgets). It must
|
|
||||||
never contain products, orders, cart, or users.
|
|
||||||
- Widgets never own page spacing — only their own internal layout. The renderer
|
|
||||||
owns sections, spacing, and page width.
|
|
||||||
- Homepage is composed from a configurable, ordered list of sections (Section
|
|
||||||
Engine): Hero, Categories, Featured Products, Banner, Latest Products, Custom
|
|
||||||
HTML, Newsletter, etc.
|
|
||||||
- All layouts (homepage, PLP, etc.) must be backend-configurable without frontend
|
|
||||||
changes.
|
|
||||||
- All user-facing text is translatable via a `translations.{lang}` shape, not a
|
|
||||||
flat `title` field. Adding/removing a supported language must automatically
|
|
||||||
expose/remove translation fields across all translatable objects, generically —
|
|
||||||
never per-field hardcoding.
|
|
||||||
- Static pages (About Us, Privacy, Terms, Contacts, Return Policy, Delivery,
|
|
||||||
custom pages) are backend-delivered HTML, multilingual, and drive the footer.
|
|
||||||
- Admin and storefront share a domain but are fully separate applications: the
|
|
||||||
marketplace bundle never ships admin code and vice versa. Bootstrap is public;
|
|
||||||
Admin is protected by JWT + roles/permissions + tenant isolation (Super Admin,
|
|
||||||
Marketplace Admin, Moderator, Editor, Support, Customer).
|
|
||||||
|
|
||||||
## Coding rules
|
|
||||||
|
|
||||||
- Never hardcode marketplace data or introduce marketplace-specific conditionals.
|
|
||||||
- Never use environment flags to drive UI — everything is config-driven.
|
|
||||||
- Keep components small; prefer composition and reusable widgets; never
|
|
||||||
duplicate layouts.
|
|
||||||
- Business logic lives in services/facades, not components.
|
|
||||||
- Prefer Signals and standalone components.
|
|
||||||
- Every new feature ships with docs: frontend docs, backend contract, bootstrap
|
|
||||||
updates, API examples, migration notes if needed.
|
|
||||||
|
|
||||||
## Guiding question
|
|
||||||
|
|
||||||
Before implementing anything: "Will this still make sense after 50 marketplaces
|
|
||||||
and 100 developers?" If not, redesign before coding.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
Any feature (including the Sprint 16 Project Editor) must edit the same Bootstrap
|
|
||||||
model the storefront consumes — no parallel/duplicate configuration models are
|
|
||||||
permitted anywhere in the platform.
|
|
||||||
@@ -1,53 +0,0 @@
|
|||||||
---
|
|
||||||
id: ADR-0002
|
|
||||||
title: Media Manager backend contract and mock storage adapter
|
|
||||||
status: active
|
|
||||||
date: 2026-07-15
|
|
||||||
tags: ["architecture", "media", "backend-gap", "repository-pattern"]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
Sprint 4 (Media Manager) needs a media library: upload, browse, delete, and pick
|
|
||||||
images/files for use across Product Editor, Static Pages (CMS), and Branding.
|
|
||||||
No media backend exists yet — `/media` currently routes to a "coming soon"
|
|
||||||
placeholder (`BackofficeComingSoonPageComponent`), and `docs/BACKEND.md` does
|
|
||||||
not document any upload/storage endpoint. This mirrors the already-documented
|
|
||||||
draft-publish-flow gap in the Project Editor (see `PE-20260713T010000Z-0003`):
|
|
||||||
build the real contract, then implement a client-side mock adapter behind the
|
|
||||||
same interface so the UI never needs to change when the backend ships.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
- **Domain model** `MediaAsset`: `{ id, url, thumbnailUrl?, filename, mimeType,
|
|
||||||
size, width?, height?, altText?: Record<locale, string>, tags?: string[],
|
|
||||||
createdAt }`. `altText` follows the platform's `translations.{lang}` rule
|
|
||||||
(ADR-0001) — never a flat string.
|
|
||||||
- **Repository contract** (future backend, to be implemented server-side):
|
|
||||||
- `GET /media?page=&pageSize=&search=` → paginated `MediaAsset[]`
|
|
||||||
- `POST /media/upload` (multipart) → `MediaAsset`
|
|
||||||
- `DELETE /media/:id` → 204
|
|
||||||
- `PATCH /media/:id` (altText/tags only) → `MediaAsset`
|
|
||||||
- **Frontend abstraction**: a `MediaRepository` interface (Repository pattern,
|
|
||||||
per `docs/context/features/*` conventions) with two implementations selected
|
|
||||||
via DI token:
|
|
||||||
- `MockMediaRepository` — stores assets in IndexedDB (not localStorage: binary
|
|
||||||
blobs need it) as an interim store until the backend exists. Data URLs are
|
|
||||||
generated for rendering; the shape returned matches `MediaAsset` exactly.
|
|
||||||
- `HttpMediaRepository` — thin wrapper over the endpoints above, added when
|
|
||||||
the backend ships. Swapping providers is the only change required.
|
|
||||||
- **Media never enters the Bootstrap model.** Like products/orders/users, media
|
|
||||||
assets are runtime admin data, not tenant configuration — consistent with
|
|
||||||
ADR-0001's rule that Bootstrap contains only what's needed before the app
|
|
||||||
starts.
|
|
||||||
- **Media Picker** is a standalone, reusable dialog (built on the existing
|
|
||||||
`app-dialog` Design System primitive) so Product Editor and CMS editors
|
|
||||||
consume the same selection UI instead of each building their own.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
- Any feature needing to reference an image (product gallery, static page
|
|
||||||
hero, branding logo) does so via `MediaAsset.url`/`id`, obtained through the
|
|
||||||
shared Media Picker — never a raw file input duplicated per feature.
|
|
||||||
- When the backend ships, only `MediaRepository`'s DI provider changes; no
|
|
||||||
component or facade code should need to change.
|
|
||||||
@@ -1,42 +0,0 @@
|
|||||||
---
|
|
||||||
id: ADR-0002
|
|
||||||
title: Project Editor field-schema registry, centralized validation, and metadata-augmented form engine
|
|
||||||
status: active
|
|
||||||
date: 2026-07-16
|
|
||||||
tags: ["project-editor", "schema", "validation", "undo-redo"]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
The Project Editor (`src/app/features/project-editor/`) edits the tenant `BootstrapConfig` across 11 hand-authored section templates, all built on the `shared/ui` field primitives (ADR established post-Sprint 30 redesign; see `docs/EDITOR.md`). Field labels/hints/defaults lived inline per template, `ProjectValidator` issues were not addressable to a field, there was no undo/redo, and no per-field modified/error state. Sprint X+1 ("Configuration Engine & Dynamic Form Foundation") required: a field-schema registry, centralized validation (JSON/CSS/URL/color/locale/duplicate-route/widget-config), live inline validation with publish-gating, pre-publish preview, dirty/modified-field tracking with a leave-warning, and session undo/redo — without duplicating form logic or validators, and without breaking draft/publish/import/export.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
**Metadata-augmented, not fully schema-driven.** A field-schema registry (`schema/field-schema.model.ts`, `schema/editor-schema.ts`, `schema/editor-schema.service.ts`) declares every editable field (dot-path key, section, type, label/hint keys, default, required, validator refs) as the single source of truth for field identity and validator wiring — but section templates stay hand-authored. The schema drives validation and metadata; it does not render fields. This was chosen over a fully schema-driven renderer because 11 mature templates already exist on top of the `shared/ui` kit, and a renderer rewrite carried materially higher regression risk against "preserve all existing functionality" for no UX gain.
|
|
||||||
|
|
||||||
**Validators are pure, composed, and tagged.** `schema/validators/primitives.ts` holds one pure function per concern (hex color, HTTP URL, email, JSON, CSS brace-balance, style-block extraction, route normalization). `ProjectValidator` composes them and attaches `section`, `fieldKey`, and `severity` (`error` | `warning`) to every issue, so the same validator is never re-implemented per field or per section.
|
|
||||||
|
|
||||||
**Severity splits blocking from advisory.** `publish()` now gates on `hasBlockingIssues()` (`severity === 'error'`) instead of "any issue exists." All 9 pre-existing checks stayed `error` (no behavior change); the new duplicate-routes and invalid-CSS checks are `warning` — informative, non-blocking, by design.
|
|
||||||
|
|
||||||
**Undo/redo is a pure reducer wrapped in debounced facade state.** `schema/history.util.ts` is a framework-free `{past, future}` snapshot reducer (commit/undo/redo, depth-capped). The facade debounces commits (~300ms) so a typing burst collapses into one undo step, and routes undo/redo through the same `localStorage` draft-save path as every other mutation so the autosave never desyncs from the undo stack.
|
|
||||||
|
|
||||||
**Modified-field tracking is a schema diff, not a form-state library.** `modifiedFields` walks every schema field and compares current vs. `originalBootstrap` by dot-path — no new dependency, reuses `EditorSchemaService.getByPath`.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
Positive:
|
|
||||||
- One registry answers "what fields exist, what validates them, what do they mean" — new fields register once and get validation + inline-error wiring for free.
|
|
||||||
- No validator is duplicated: JSON/CSS/color/URL/email logic lives in exactly one place each.
|
|
||||||
- Zero changes to `ProjectEditorIoService`, `ProjectEditorDraftStorageService`, or the draft/publish/reset flow — full backward compatibility.
|
|
||||||
- Undo/redo and modified-field tracking added without a state-management library.
|
|
||||||
|
|
||||||
Negative / accepted debt:
|
|
||||||
- Inline `[error]` binding is wired on a subset of fields (theme palette, general name/domain, branding logo) — not yet every schema-backed field across all 11 sections. Section-level visibility (nav badges, save-bar issue list) covers the rest today.
|
|
||||||
- The field-schema registry is not yet consumed by templates for label/hint rendering (still inline i18n keys in each template) — only for validation, diffing, and change-summary labels. A future pass could fully drive labels from the schema.
|
|
||||||
- CSS/JSON validators have a thin binding surface today (CSS only via static-page `<style>` blocks; JSON only via import) since no dedicated `customCss`/raw-JSON field exists yet in `BootstrapConfig`.
|
|
||||||
|
|
||||||
## Compliance Requirements
|
|
||||||
|
|
||||||
- New editable `BootstrapConfig` fields should get a `FieldSchema` entry in `editor-schema.ts` alongside their template addition.
|
|
||||||
- New validation rules must be added as a pure function in `schema/validators/primitives.ts` and composed into `ProjectValidator` — never inlined ad hoc in a section component.
|
|
||||||
- `severity: 'error'` is reserved for checks that must block Publish; anything advisory is `'warning'`.
|
|
||||||
@@ -1,8 +0,0 @@
|
|||||||
# Mock Data Boundaries
|
|
||||||
|
|
||||||
- `bootstrap/`: tenant and platform configuration only.
|
|
||||||
- `website/`: website business/content mocks.
|
|
||||||
- `builder/`: builder configuration editing mocks.
|
|
||||||
- `backoffice/`: business domain data (products, categories, orders, customers).
|
|
||||||
|
|
||||||
Backoffice business data must not be stored under `bootstrap/`.
|
|
||||||
Reference in New Issue
Block a user