From 34745811223a10bc40317fbcd93e1dd2ddb0db7d Mon Sep 17 00:00:00 2001 From: sdarbinyan Date: Thu, 16 Jul 2026 23:37:29 +0400 Subject: [PATCH] docs: add backend diff-vs-main + sales guide, document editor motion & HTML editor - docs/BACKEND-DIFF-VS-MAIN.md: backend handoff summary framing BACKEND.md - docs/SALES-GUIDE.md: non-technical demo/enablement guide - docs/EDITOR.md: document interaction/motion pass and HTML editor status Co-Authored-By: Claude Opus 4.8 --- docs/BACKEND-DIFF-VS-MAIN.md | 50 +++++++++++++++++++++++ docs/EDITOR.md | 16 ++++++++ docs/SALES-GUIDE.md | 79 ++++++++++++++++++++++++++++++++++++ 3 files changed, 145 insertions(+) create mode 100644 docs/BACKEND-DIFF-VS-MAIN.md create mode 100644 docs/SALES-GUIDE.md diff --git a/docs/BACKEND-DIFF-VS-MAIN.md b/docs/BACKEND-DIFF-VS-MAIN.md new file mode 100644 index 0000000..d0d733e --- /dev/null +++ b/docs/BACKEND-DIFF-VS-MAIN.md @@ -0,0 +1,50 @@ +# Backend Handoff — B2B branch vs `main` + +Audience: backend developer. This is the "what changed and what you need to build" summary for the `B2B` branch compared to `main`. It frames the detailed punch list in [`BACKEND.md`](BACKEND.md) — read that file for exact endpoint shapes and the frontend files that change once each endpoint exists. + +## TL;DR + +`B2B` is **~138 commits ahead of `main`**. Almost all of it is **frontend that has been built ahead of the backend**: a full admin backoffice, a project editor, a media manager, and a design-system component library. Every data-writing feature runs today against an **in-memory / `localStorage` mock gateway** that is already designed to be swapped for a real API via an injection token — the UI, facades, and pages do **not** change when you wire a real backend; you implement one gateway/provider class per domain and rebind its token. + +**You are not changing any existing contract.** Existing auth, payments, `GET /bootstrap`, and `GET /category` are frozen. Everything below is *new* backend surface the frontend is waiting on. + +## What `B2B` adds over `main` (feature-level) + +| Area | What's new on the frontend | Backend today | Priority | +|---|---|---|---| +| Design system | Reusable primitives (Button, Input, Card, Badge, Dialog, Table, Pagination, Skeleton, EmptyState, FormField) + editor primitives (Toggle, Select, ColorPicker, SectionCard, LocaleTabs, KeyValueEditor) | n/a (pure UI) | — | +| Project Editor | Full tenant `BootstrapConfig` editor (11 sections, draft/publish, validation, per-locale content, HTML editor for static pages) | **mock**: draft/publish is `localStorage` only, no persistence | **High** | +| Media manager | Upload / grid / delete + reusable media picker | **mock**: IndexedDB adapter, nothing server-side | High | +| Categories admin | List + create/edit, hierarchy, drag reorder, soft delete/restore, draft/publish, SEO/translations | **mock**: in-memory, no write path | High | +| Products admin | List + editor (variants, barcode, archive, related products, bulk actions) | **mock**: in-memory gateway | High | +| Orders admin | List/detail, status changes, refund, cancel, notes, CSV, invoice | **mock**: 24 synthetic orders | High | +| Transactions admin | List, retry, fraud flag, audit log, CSV | **mock**: derived from mock orders | Medium | +| Users / roles admin | Users, roles, invitations, sessions, audit log | **mock**: synthetic; ties to auth gap below | High | +| Dashboard metrics | Counts, status, health, activity feed | **partial**: counts composed client-side; activity is `localStorage` | Medium | +| Monitoring | Health (real) + event/queue/webhook feeds | **mock** except Health | Medium | +| Analytics | Revenue/orders/top-products (from mock orders) + visitors/funnels/heatmaps | **no data source** for traffic/funnels | Low | +| SEO | Tenant-driven meta tags, `sitemap.xml` / `robots.txt` baseline | **static baseline** only, not per-tenant | Low | + +## The two things to do first + +1. **Admin authorization (security).** Admin and customer login currently share **one** Telegram QR session backend, so the server has no concept of "this is an admin session." Any Telegram user who completes the QR flow on the admin login screen gets an `adminSessionID`. **Server-side authorization keyed off the session id is required** — nothing on the frontend can substitute. See [`BACKEND.md`](BACKEND.md) §1. + +2. **Bootstrap draft / publish persistence.** The Project Editor edits the same `BootstrapConfig` the storefront consumes, but Save is `localStorage`-only and Publish is in-memory — no backend call. Needs `GET/PUT /builder/bootstrap/draft`, `POST /builder/bootstrap/publish`, optional `POST /builder/bootstrap/validate`, and **server-side re-validation** (the client validator is not a trust boundary). See [`BACKEND.md`](BACKEND.md) §2. + +## The pattern for every mocked domain + +For categories, products, orders, transactions, users, monitoring, dashboard metrics: + +1. A `*LocalGateway` (or `*Provider`) implements a gateway interface and is bound via an Angular injection token. +2. You implement a `*ApiGateway` against the **same interface**, hitting real endpoints matching the domain model in `features/admin//models/*.model.ts`. +3. You rebind the token in DI config. **Facades and page components do not change.** + +Model shapes to build against are named per area in [`BACKEND.md`](BACKEND.md) §5–§16. + +## Known production issue not fixable here + +Intermittent `502`/`504` on refresh / back-navigation in production originates from the **backend API's own reverse proxy** (`api.dexarmarket.ru:445`, `users.vitanova.network:456`) — the frontend calls those absolute URLs directly, bypassing this repo's nginx. Needs DevOps/backend investigation of upstream health and timeouts around session-check + bootstrap endpoints. See [`BACKEND.md`](BACKEND.md) "Known reliability issues". + +## Verifying the frontend locally without a backend + +`environment.ts` ships `useMockBootstrapOnLocal: true` and mock gateways are the default bindings, so `npm run dexar` runs the whole thing offline. Admin routes are reachable in dev via `?devBypassAdmin=true`. Flipping a domain to a real API is the gateway-swap above — no mock removal needed to start. diff --git a/docs/EDITOR.md b/docs/EDITOR.md index 5391e94..a83e257 100644 --- a/docs/EDITOR.md +++ b/docs/EDITOR.md @@ -69,6 +69,22 @@ All 11 section components (`sections/*.component.html`) share these 6 `shared/ui `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 `

` 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 `