sdarbinyan/marketplaces
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: sdarbinyan:9344f2702c175511226be4774af511c6f10dcad1
Branches Tags
sdarbinyan:main sdarbinyan:B2B sdarbinyan:main-backup-20260726 sdarbinyan:back-office-integration sdarbinyan:auth-system sdarbinyan:reorganize
..
compare: sdarbinyan:main-backup-20260726
Branches Tags
sdarbinyan:B2B sdarbinyan:main sdarbinyan:main-backup-20260726 sdarbinyan:back-office-integration sdarbinyan:auth-system sdarbinyan:reorganize

1 Commits
9344f2702c ... main-backu

Author SHA1 Message Date
sdarbinyan
905c8be8c5 translations 2026-07-04 23:34:00 +04:00
1247 changed files with 34545 additions and 73986 deletions
Expand all files Collapse all files

11
.gitattributes vendored
View File

@@ -1,11 +0,0 @@
* text=auto
# Anything executed by a Linux shell must keep LF endings. A CRLF checkout
# makes bash fail with "\r: command not found" on the very first line.
*.sh text eol=lf
*.yml text eol=lf
*.yaml text eol=lf
# systemd chokes on trailing CR in unit values.
*.service text eol=lf
*.timer text eol=lf

30
.github/workflows/architecture-governance.yml vendored
View File

@@ -1,30 +0,0 @@
name: Architecture Governance
on:
push:
branches:
- '**'
pull_request:
jobs:
architecture:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- name: Install Dependencies
run: npm ci
- name: Enforce Boundaries
run: npm run arch:check
- name: Build
run: npm run build

134
.github/workflows/deploy.yml vendored
View File

@@ -1,134 +0,0 @@
name: Deploy Frontend
# Multi-tenant: one bundle serves every customer domain, so a single deploy
# updates all of them at once. There is no per-tenant build or per-tenant deploy.
on:
push:
branches:
- main
workflow_dispatch:
inputs:
ref:
description: Branch or SHA to deploy
required: false
default: main
concurrency:
group: deploy-frontend
cancel-in-progress: false # never abandon a half-finished release swap
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: ${{ github.event.inputs.ref || github.ref }}
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- name: Install dependencies
run: npm ci
- name: Enforce boundaries
run: npm run arch:check
- name: Build
run: npm run build -- --configuration production
- name: Resolve build output
id: dist
run: |
set -euo pipefail
# @angular/build:application emits into dist/<name>/browser.
# Fall back to the flat layout so this survives a builder change.
if [ -d dist/dexarmarket/browser ]; then
DIR=dist/dexarmarket/browser
elif [ -f dist/dexarmarket/index.html ]; then
DIR=dist/dexarmarket
else
echo "no build output found under dist/dexarmarket" >&2
ls -R dist || true
exit 1
fi
test -f "$DIR/index.html" || { echo "$DIR has no index.html" >&2; exit 1; }
echo "dir=$DIR" >> "$GITHUB_OUTPUT"
echo "Deploying from $DIR ($(find "$DIR" -type f | wc -l) files)"
- name: Configure SSH
env:
DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
DEPLOY_KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
run: |
set -euo pipefail
test -n "$DEPLOY_SSH_KEY" || { echo "secret DEPLOY_SSH_KEY is empty" >&2; exit 1; }
test -n "$DEPLOY_KNOWN_HOSTS" || { echo "secret DEPLOY_KNOWN_HOSTS is empty" >&2; exit 1; }
mkdir -p ~/.ssh
printf '%s\n' "$DEPLOY_SSH_KEY" > ~/.ssh/deploy_key
chmod 600 ~/.ssh/deploy_key
# Pinned host key, so a MITM or a rebuilt server fails the deploy
# instead of being trusted silently.
printf '%s\n' "$DEPLOY_KNOWN_HOSTS" > ~/.ssh/known_hosts
chmod 644 ~/.ssh/known_hosts
- name: Upload release
env:
HOST: ${{ secrets.DEPLOY_HOST }}
USER: ${{ secrets.DEPLOY_USER }}
SRC: ${{ steps.dist.outputs.dir }}
run: |
set -euo pipefail
RELEASE="${GITHUB_SHA::12}"
echo "RELEASE=$RELEASE" >> "$GITHUB_ENV"
SSH="ssh -i ~/.ssh/deploy_key -o BatchMode=yes"
$SSH "$USER@$HOST" "mkdir -p /srv/marketplaces/releases/$RELEASE/frontend"
rsync -az --delete \
-e "$SSH" \
"$SRC/" "$USER@$HOST:/srv/marketplaces/releases/$RELEASE/frontend/"
- name: Activate release
env:
HOST: ${{ secrets.DEPLOY_HOST }}
USER: ${{ secrets.DEPLOY_USER }}
run: |
set -euo pipefail
ssh -i ~/.ssh/deploy_key -o BatchMode=yes "$USER@$HOST" bash -euo pipefail <<EOSSH
BASE=/srv/marketplaces
REL="\$BASE/releases/$RELEASE"
test -f "\$REL/frontend/index.html" || { echo "upload incomplete, refusing to swap" >&2; exit 1; }
# ln -T onto a temp name then mv: the swap is atomic, so no request
# is ever served from a half-updated root.
ln -sfnT "\$REL" "\$BASE/current.new"
mv -Tf "\$BASE/current.new" "\$BASE/current"
sudo /bin/systemctl reload nginx
# Keep the last 5 releases so a rollback is a symlink change.
ls -1dt "\$BASE"/releases/*/ | tail -n +6 | xargs -r rm -rf
echo "active: \$(readlink -f \$BASE/current)"
EOSSH
- name: Verify
env:
HOST: ${{ secrets.DEPLOY_HOST }}
USER: ${{ secrets.DEPLOY_USER }}
run: |
set -euo pipefail
ssh -i ~/.ssh/deploy_key -o BatchMode=yes "$USER@$HOST" \
'curl -fsS -o /dev/null -w "health=%{http_code}\n" http://127.0.0.1/health &&
curl -fsS -o /dev/null -w "index=%{http_code}\n" http://127.0.0.1/'
- name: Report
if: always()
run: |
if [ "${{ job.status }}" = "success" ]; then
echo "Deployed ${GITHUB_SHA::12} to ${{ secrets.DEPLOY_HOST }}" >> "$GITHUB_STEP_SUMMARY"
else
echo "Deploy of ${GITHUB_SHA::12} FAILED. The previous release is still active — the symlink only moves after a successful upload." >> "$GITHUB_STEP_SUMMARY"
fi

37
.gitignore vendored
View File

@@ -2,15 +2,11 @@
# Compiled output
/dist
packages/*/dist
/tmp
/out-tsc
/bazel-out
/files
changes.txt
/agent
/agents
.agents
# Node
/node_modules
@@ -46,36 +42,3 @@ testem.log
# System files
.DS_Store
Thumbs.db
# Claude Code worktrees/session state, graphify knowledge-graph output
.claude/
graphify-out/
<!-- barry-cache:start -->
.context-state/
.context-cache/
.barry-cache/
<!-- barry-cache:end -->
AGENTS.md
CLAUDE.md
GEMINI.md
llms.txt
.cursor/rules/barry-cache.mdc
.github/copilot-instructions.md
docs/context/INDEX.md
docs/context/LOG.md
docs/context/MAINTENANCE.md
docs/context/README.md
docs/context/adrs/README.md
docs/context/concepts/project-context-model.md
docs/context/schema/adr.schema.json
docs/context/schema/fact.schema.json
docs/context/schema/failure.schema.json
docs/context/schema/route.schema.json
docs/context/schema/strategy.schema.json
docs/context/schema/work-state.schema.json
docs/context/schema/workspace.schema.json
# Playwright artifacts
/test-results
/playwright-report

124
.impeccable/design.json
View File

@@ -1,124 +0,0 @@
{
"schemaVersion": 2,
"generatedAt": "2026-07-17T00:00:00Z",
"title": "Design System: Marketplaces Platform",
"extensions": {
"colorMeta": {
"primary": { "role": "primary", "displayName": "Muted Pine", "canonical": "#497671", "tonalRamp": ["#182927", "#243d3a", "#2f4f4b", "#3d635f", "#497671", "#6b918d", "#93b3af", "#c3d6d3"] },
"secondary": { "role": "secondary", "displayName": "Sage Grey", "canonical": "#a1b4b5", "tonalRamp": ["#2c3838", "#3f5150", "#556c6b", "#6c8583", "#8da3a4", "#a1b4b5", "#c0cfcf", "#e2eaea"] },
"accent": { "role": "tertiary", "displayName": "Pale Mint", "canonical": "#a7ceca", "tonalRamp": ["#243936", "#33514d", "#456a65", "#5a857f", "#7fa9a3", "#a7ceca", "#c6e0dd", "#e6f2f0"] },
"text-primary": { "role": "neutral", "displayName": "Deep Pine Ink", "canonical": "#1e3c38", "tonalRamp": ["#0f1e1c", "#1e3c38", "#2c5651", "#3d716b", "#5a8d87", "#84aca7", "#b1cbc8", "#dfeae9"] },
"bg-secondary": { "role": "neutral", "displayName": "Soft Grey", "canonical": "#f5f5f5", "tonalRamp": ["#2b2b2b", "#4a4a4a", "#6e6e6e", "#949494", "#b8b8b8", "#d7d7d7", "#eaeaea", "#f5f5f5"] },
"border": { "role": "neutral", "displayName": "Divider Grey", "canonical": "#d3dad9", "tonalRamp": ["#333938", "#4a5251", "#636d6c", "#7f8a89", "#9da8a7", "#bcc5c4", "#d3dad9", "#eef1f1"] }
},
"typographyMeta": {
"display": { "displayName": "Display", "purpose": "Page-level and storefront hero titles; ceiling ~2.75rem." },
"headline": { "displayName": "Headline", "purpose": "Section headings and admin page titles." },
"title": { "displayName": "Title", "purpose": "Card titles, editor section labels." },
"body": { "displayName": "Body", "purpose": "Default reading text; cap prose at 65-75ch." },
"label": { "displayName": "Label", "purpose": "Badges and tags only; tracked uppercase." }
},
"shadows": [
{ "name": "shadow-sm", "value": "0 2px 8px rgba(0,0,0,0.1)", "purpose": "Resting cards, inputs, low panels. Default ambient layer." },
{ "name": "shadow-md", "value": "0 4px 12px rgba(0,0,0,0.15)", "purpose": "Hover state for cards and buttons; raised toolbars." },
{ "name": "shadow-lg", "value": "0 12px 32px rgba(73,118,113,0.2)", "purpose": "Structural float: modals, dropdowns, save bar. Brand-tinted." }
],
"motion": [
{ "name": "transition-fast", "value": "120ms ease", "purpose": "Button and small-control state changes." },
{ "name": "transition-normal", "value": "180ms ease", "purpose": "Card hover lift, transforms." },
{ "name": "transition-slow", "value": "300ms ease", "purpose": "Default for links/inputs/textareas." }
],
"breakpoints": [
{ "name": "sm", "value": "640px" },
{ "name": "md", "value": "900px" },
{ "name": "lg", "value": "1200px" },
{ "name": "container", "value": "1280px" }
]
},
"components": [
{
"name": "Primary Button",
"kind": "button",
"refersTo": "button-primary",
"description": "The default confident action. Muted Pine fill, lifts on hover.",
"html": "<button class=\"ds-btn-primary\">Save changes</button>",
"css": ".ds-btn-primary { display: inline-flex; align-items: center; justify-content: center; gap: 0.5rem; background: #497671; color: #fff; border: 1px solid #497671; border-radius: 12px; padding: 0.625rem 1rem; font-weight: 600; line-height: 1.2; cursor: pointer; transition: background-color 180ms ease, transform 180ms ease, box-shadow 180ms ease; } .ds-btn-primary:hover { background: #3d635f; border-color: #3d635f; transform: translateY(-1px); box-shadow: 0 2px 8px rgba(0,0,0,0.1); } .ds-btn-primary:active { transform: translateY(0); } .ds-btn-primary:focus-visible { outline: 2px solid #497671; outline-offset: 2px; }"
},
{
"name": "Ghost Button",
"kind": "button",
"refersTo": "button-ghost",
"description": "Low-emphasis action. Transparent with a divider border until hover.",
"html": "<button class=\"ds-btn-ghost\">Cancel</button>",
"css": ".ds-btn-ghost { display: inline-flex; align-items: center; justify-content: center; background: transparent; color: #1e3c38; border: 1px solid #d3dad9; border-radius: 12px; padding: 0.625rem 1rem; font-weight: 600; cursor: pointer; transition: background-color 180ms ease, border-color 180ms ease; } .ds-btn-ghost:hover { background: rgba(73,118,113,0.08); border-color: #497671; } .ds-btn-ghost:focus-visible { outline: 2px solid #497671; outline-offset: 2px; }"
},
{
"name": "Card",
"kind": "card",
"refersTo": "card",
"description": "Resting surface with a soft ambient shadow that lifts on hover.",
"html": "<div class=\"ds-card\"><h3 class=\"ds-card-title\">Product title</h3><p class=\"ds-card-body\">Supporting copy sits in Muted Pine Grey at a comfortable line height.</p></div>",
"css": ".ds-card { background: #ffffff; border: 1px solid #d3dad9; border-radius: 12px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); padding: 16px; transition: transform 180ms ease, box-shadow 180ms ease; } .ds-card:hover { transform: translateY(-2px); box-shadow: 0 4px 12px rgba(0,0,0,0.15); } .ds-card-title { margin: 0 0 6px; font-size: 1.125rem; font-weight: 600; color: #1e3c38; line-height: 1.3; } .ds-card-body { margin: 0; font-size: 1rem; font-weight: 400; color: #667a77; line-height: 1.6; }"
},
{
"name": "Text Input",
"kind": "input",
"refersTo": "input",
"description": "Editor/admin field with a divider stroke and brand focus outline.",
"html": "<label class=\"ds-field\"><span class=\"ds-field-label\">Store name</span><span class=\"ds-field-desc\">Shown in the storefront header.</span><input class=\"ds-input\" type=\"text\" placeholder=\"My marketplace\" /></label>",
"css": ".ds-field { display: grid; gap: 6px; color: #1e3c38; font-weight: 600; } .ds-field-label { font-size: 1rem; } .ds-field-desc { font-weight: 400; font-size: 12px; line-height: 1.4; color: #667a77; } .ds-input { width: 100%; padding: 10px 12px; border: 1px solid #d3dad9; border-radius: 10px; background: #fff; color: #1e3c38; font: inherit; } .ds-input:focus-visible { outline: 2px solid #497671; outline-offset: 2px; } .ds-input::placeholder { color: #828e8d; }"
},
{
"name": "Badge",
"kind": "chip",
"refersTo": "badge",
"description": "Uppercase status marker overlaid on product media.",
"html": "<span class=\"ds-badge ds-badge-sale\">Sale</span>",
"css": ".ds-badge { display: inline-block; padding: 2px 8px; border-radius: 8px; font-size: 0.7rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.4px; color: #fff; line-height: 1.4; } .ds-badge-sale { background: #f44336; }"
},
{
"name": "Tag",
"kind": "chip",
"refersTo": "badge",
"description": "Low-emphasis metadata pill in brand tint.",
"html": "<span class=\"ds-tag\">Digital</span>",
"css": ".ds-tag { display: inline-block; padding: 2px 8px; border-radius: 12px; font-size: 0.72rem; color: #497671; background: rgba(73,118,113,0.08); border: 1px solid rgba(73,118,113,0.15); }"
}
],
"narrative": {
"northStar": "The Operator's Workbench",
"overview": "This is a tool before it is a brand. The platform chrome is a dependable workbench an operator returns to session after session to build and run a marketplace: state is always legible, controls map to what they change, and nothing 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 configuration-first: every storefront is themed per tenant from a runtime bootstrap, so the platform's identity stays neutral and the tenant's leads. Components are tactile and confident; depth is real but restrained, with structural elevation reserved for things that genuinely float.",
"keyCharacteristics": [
"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."
],
"rules": [
{ "name": "The Quiet Chrome Rule", "body": "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.", "section": "colors" },
{ "name": "The Variable-Only Rule", "body": "Components and widgets consume CSS custom properties only. A hardcoded hex in a component is a bug (ADR-008) that breaks per-tenant theming.", "section": "colors" },
{ "name": "The One Family Rule", "body": "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.", "section": "typography" },
{ "name": "The Uppercase-Is-Earned Rule", "body": "Tracked uppercase lives on badges/tags exclusively. It is forbidden as a section eyebrow.", "section": "typography" },
{ "name": "The Lift-on-Intent Rule", "body": "Resting surfaces carry at most shadow-sm. shadow-md is a response to hover/focus; shadow-lg means the element floats above the page.", "section": "elevation" }
],
"dos": [
"Do consume theme CSS custom properties, never hardcode hex in a component (ADR-008).",
"Do keep platform chrome neutral so tenant themes lead the storefront.",
"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 in every tool surface.",
"Do give every hover/transform a prefers-reduced-motion fallback.",
"Do hold 4.5:1 body-text contrast across every tenant theme, not just Dexar."
],
"donts": [
"Don't ship dated enterprise admin: cluttered gray dashboards, tiny dense tables, 2010-era Bootstrap backoffice.",
"Don't ship generic AI-SaaS template: cream/violet gradient landings, hero-metric card rows, tracked-uppercase eyebrows, identical card grids.",
"Don't ship consumer-toy UI: bubbly rounded-everything, mascots, candy colors, gamified surfaces.",
"Don't use tracked uppercase anywhere except badges/tags.",
"Don't exceed ~2.75rem on display headings.",
"Don't add a second type family or a display serif.",
"Don't let platform-branded color fight a tenant's palette."
]
}
}

6
.impeccable/live/config.json
View File

@@ -1,6 +0,0 @@
{
"files": ["src/index.html"],
"insertBefore": "</body>",
"commentSyntax": "html",
"cspChecked": true
}

599
BACKEND-API-REFERENCE.md
View File

@@ -1,599 +0,0 @@
# 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.
**For what doesn't exist yet:** this doc describes the live surface only. The full set of forward-looking wire contracts for Product Plan v3.1 (money/FX, orders, catalog/offer split, connectors, seller portal, identity, tenant registry, RBAC, analytics — 10 phases + 2 tracks) lives in [docs/backend/](docs/backend/README.md).
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.
### 2c. Email/phone OTP login — customer (NOT IMPLEMENTED, proposed)
**Gap:** customer storefront login/checkout requires Telegram (Mechanism A) — shoppers without Telegram have no way to identify themselves. Raised as a real usability problem, not a hypothetical.
**Ask:** a third, independent auth mechanism (coexists with 2a/2b, replaces neither):
```
POST /auth/otp/request
Body: { "identifier": "user@example.com" } // or E.164 phone, e.g. "+79991234567"
Response: { "requestId": "...", "expiresAt": "2026-08-15T10:15:00Z" }
```
```
POST /auth/otp/verify
Body: { "requestId": "...", "code": "482913" }
Response (on success): {
"sessionId": "...", "userId": 8823771, "username": null,
"displayName": "user@example.com", "active": true, "expires": "2026-08-15T11:15:00Z"
}
```
The success response must be shaped identically to the existing `AuthSession` (`sessionId, userId, username, displayName, active, expires`, §2a's client model) — this lets every existing downstream consumer (guards, session signals, cart/checkout) work unchanged regardless of which mechanism produced the session.
Rate limiting/expiry, explicit so nothing is left to guesswork: 60s resend cooldown per identifier between `/request` calls; code expires 10 minutes after issuance; `requestId` allows up to 5 verify attempts before it's invalidated (consumed on success, on the 5th wrong attempt, or on expiry) — not single-use-per-attempt, so one mistyped digit doesn't force a full 60s wait for a new code.
**Error responses must use the existing envelope** (§5), with these codes on `/verify` (the client maps each to distinct UX — see the design doc):
| `error.code` | HTTP status | Meaning |
|---|---|---|
| `VALIDATION_FAILED` | 422 | Malformed identifier (`error.details[0]` names the field). |
| `RATE_LIMITED` | 429 | Resend cooldown not yet elapsed. |
| `CODE_EXPIRED` | 410 | 10-minute window passed. |
| `CODE_INVALID` | 401 | Wrong code, attempts remain on this `requestId`. |
| `REQUEST_NOT_FOUND` | 404 | `requestId` unknown, exhausted (5 wrong attempts), or expired. |
Admin can toggle which login methods (Telegram/Email/Phone) are shown to shoppers — this is a client-only UI gate (Admin Settings, `LocalStorageService`-persisted), not a backend flag; all endpoints stay available regardless of the toggle state.
See `docs/superpowers/specs/2026-08-15-email-phone-login-design.md` for the full design. No client code exists yet — nothing to build against a 404.
---
## 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) now reads `error.error.code` from the body when present (`authErrorCodeFromBackendCode()`), falling back to HTTP status only when no body code is sent. 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` | **Fixed** — `toAuthErrorShape()` (`core/auth/services/auth.service.ts`) now reads `error.error.code` via `authErrorCodeFromBackendCode()` before falling back to HTTP status. A backend 401 on `/refresh` sending `error.code: "TOKEN_EXPIRED"` reaches the dedicated "Session expired" screen. |
| 401 (bad signature) | `INVALID_SIGNATURE` | **Fixed**, same mechanism — reaches the dedicated screen when the backend sends `error.code: "INVALID_SIGNATURE"`. |
**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 were frozen; unfrozen 2026-08-17** (Sprint 0.1 decision, see `docs/PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md`). This call chain is now in scope for the Phase 1 rework specified in `docs/backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md` — the server-authoritative-amount contract there replaces the client-trusted `amount`/`price` fields described below.
---
## 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.
- **Currency conversion / display rates** — `CurrencyRatesService` holds RUB-based conversion rates in-memory, admin-editable via Admin Settings, persisted to `localStorage` only. `CurrencyConvertPipe` applies them client-side wherever a storefront price is rendered. The `Currency` request header (§6) is still sent on every call, but nothing round-trips a rate from the backend — see §12.7.
---
## 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).
---
## 12. Frontend-blocked TODOs — needs backend
Raised during the Phase 0 security hardening pass (see the sprint plan). Each of these has a client-side mitigation already in place where one exists, but none of them close the actual gap without a backend change.
### 12.1 Admin role claim on the session
**Gap:** `adminAuthGuard` (Mechanism A, Telegram/QR) only checks "is there an active session" — the session API has no concept of admin role at all, so the frontend cannot enforce permissions server-authoritatively. Client mitigation: `AdminPermissionsService` derives a cosmetic permission set by matching the Telegram username against the mock Users domain locally — this is UI-only and trivially bypassed by calling the API directly.
**Ask:** either (a) add a `role` field to the existing `GET /users/sessions/{id}` response when the session belongs to a registered admin, or (b) finish Mechanism B (Ed25519 challenge/response, already wired client-side, `/challenge` and `/verify` currently 404) so the JWT `role` claim becomes real. Whichever is chosen, every admin-mutating endpoint must independently authorize the request — a role claim on the session is necessary but not sufficient.
Proposed minimal shape for option (a), added to the existing poll response (§2a):
```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",
"adminRole": "admin"
}
```
`adminRole` absent/null → treat as non-admin regardless of what `/backoffice/**` UI is reachable client-side.
### 12.2 HttpOnly session cookie
**Gap:** the customer session cookie (`webSessionID`, `services/auth.service.ts`) is set via `document.cookie` from the frontend, which means it cannot be `HttpOnly` — only a `Set-Cookie` response header from the backend can set that flag, and JS-set cookies are readable by any injected script. Client mitigation: CSP hardened on all three nginx tenant blocks (was missing entirely on two of three) as defense-in-depth, but this does not close the gap.
**Ask:** `POST /users/sessions` and `GET /users/sessions/{id}` issue the session id via `Set-Cookie: webSessionID=…; HttpOnly; Secure; SameSite=Lax; Max-Age=…` instead of (or in addition to, during migration) returning it in the JSON body. Once that ships, the frontend stops writing `document.cookie` itself and relies on the browser sending the cookie automatically; `credentials: 'include'` needs enabling on the relevant HTTP calls.
### 12.3 Server-side order pricing
**Gap:** `POST` order creation (§7) let the client send a computed, discount-applied `price` per line item with no server-side revalidation. Client fix already shipped: `CreateOrderRequest.items` no longer sends `price` — only `{ productId, name, quantity }`.
**Ask:** the order-creation endpoint must price every line item itself by looking up `productId` in its own catalog (applying whatever discount/promo logic is authoritative server-side), and reject/[400] if the resulting total doesn't reconcile with what the client displayed (or just recompute and use the server total as-of-record, ignoring any client total entirely). Example of the request shape now sent:
```json
{
"items": [{ "productId": "prod_1042", "name": "Sample Product", "quantity": 2 }],
"customer": { "name": "Ivan P", "email": "ivan@example.com", "phone": "79991234567" },
"payment": { "method": "card", "currency": "RUB" }
}
```
Separately, `createCartPayment()` (payment-gateway charge creation) still sends a client-computed `amount` — that field can't simply be dropped, since it's what tells the payment provider how much to charge. That endpoint must independently revalidate `amount` against its own pricing before creating the charge, and reject on mismatch.
### 12.4 Real order audit trail
**Gap:** `AdminOrder` had no actor/audit field at all. Client fix already shipped: `AdminOrderTimelineEntry.actor` now exists and is populated from the signed-in admin's display name in the local mock gateway — but that's client-only bookkeeping with no server-side record.
**Ask:** when admin Orders CRUD gets a real backend (§10, step 6), every mutating endpoint (`updateStatus`, `requestRefund`, `addNote`, etc.) should record who performed the action server-side (from the authenticated session/JWT, not a client-supplied field) and return it in the order/timeline response:
```json
{
"timeline": [
{ "status": "processing", "timestamp": "2026-08-13T10:15:00Z", "eventKey": "statusChanged", "actor": "anna@dexar.market" }
]
}
```
`actor` must be derived server-side from the authenticated caller, never trusted from the request body.
### 12.5 Back-in-stock ("Notify Me") subscription
**Gap:** the "Notify Me" button on out-of-stock products had no real subscription mechanism at all - it just toggled wishlist. Client fix already shipped: `notifyMe()` now calls `POST /items/{id}/notify-me` and, if that fails (today it always will - the endpoint doesn't exist), falls back to a local-only record in `localStorage['restockSubscriptions']` so the request isn't silently dropped while waiting on the backend. The shopper sees the same confirmation either way.
**Ask:** implement `POST /items/{id}/notify-me`, plus whatever mechanism actually sends the notification once the item restocks (Telegram message, most likely, given the rest of the auth stack). Request body sent today:
```json
{ "telegramUserId": "8823771" }
```
`telegramUserId` may be `null` for a non-Telegram web session - decide whether to also accept an email address as an alternative identifier (the frontend has no email capture on this flow today, so that would need a small frontend addition too). Once this ships, the frontend's localStorage fallback becomes purely a resilience path rather than the common case, and could optionally sync any locally-queued subscriptions on next successful call.
### 12.7 Currency conversion / FX rates
**Gap:** the backend has no per-currency pricing — it sends prices in one base currency (`RUB`) regardless of the `Currency` header (§6), and there's no exchange-rate endpoint. Client fix already shipped: admin manually enters a RUB-based rate per supported currency (Admin Settings → Currency rates), and every storefront price display converts client-side via that static, admin-typed number. Rates never update themselves and can drift from the real market rate.
**Ask:** this was raised as a real accounting concern (bank settlement totals not reconciling against order counts) — two options, not mutually exclusive:
1. Backend returns prices already converted per the `Currency` header (removes client-side conversion entirely, most correct).
2. Backend exposes a live/periodically-updated FX-rate endpoint (e.g. pegged to Rapira or another exchange) that the frontend polls instead of relying on an admin-typed static number — smaller change, keeps pricing display client-side but removes the manual-entry drift.
Either way, the *authoritative* amount charged (`createCartPayment`'s `amount`, §12.3) must be computed/validated server-side against whichever rate source is authoritative — a client-side conversion (current or future) must never be trusted for the actual charge amount.
### 12.8 Admin purchase notifications depend on Orders CRUD being real
**Gap:** `AdminOrderWatcherService` (new — polls for new orders to toast/badge the admin) polls `AdminOrdersGateway.loadOrders()` (§8), which is bound to the mock `AdminOrdersLocalGateway` — a static, 24-row in-memory seed with no create path (see §8's gateway table, "Orders … MOCK-ONLY, no seam"). No genuinely new order can ever appear today, so the feature is functionally inert until Orders CRUD gets a real backend (§10 step 6).
**Ask:** nothing new beyond what §10/§11 already ask for — once a real `AdminOrdersApiGateway` is bound, this feature starts working with no additional frontend change. Flagging here only so nobody spends time debugging "why doesn't the notification ever fire" against the mock.
### 12.9 Admin product view counts
**Gap:** Admin Products (§8) runs on a fully separate mock domain from the storefront's live catalog — `AdminProduct.visits` is a new field added to support a "Views" column in Admin Products, but the mock gateway always defaults it to `0` because there is no real tracking source available to the admin domain today. This is unrelated to the storefront's `Item.visits` field (§6, `/items/{id}`), which is live-wired but never displayed anywhere in the UI.
**Ask:** two options, not mutually exclusive:
1. Once admin Products gets a real backend (§10 step 4), include a per-product view/visit count in the response.
2. Bridge `AdminProduct.visits` to the storefront's already-live `Item.visits` by product id, if a unified product identity exists between the storefront and admin domains — smaller change than building new tracking infrastructure.
### 12.10 Trending search terms
**Gap:** `SearchTrendingService.loadTrending()` is a stub returning `of(null)` - no trending-searches endpoint exists. It already degrades gracefully (UI hides the trending section rather than showing an error), so this is purely a missing-feature gap, not a bug.
**Ask:** an endpoint returning the top N search queries over some recent window, e.g.:
```json
{ "trending": [{ "query": "wireless earbuds", "count": 214 }, { "query": "winter jacket", "count": 187 }] }
```
Once it exists, wire `loadTrending()` to it and map `query` -> `SearchSuggestion.title/text`.

27
CHANGELOG.md
View File

@@ -1,27 +0,0 @@
# Changelog
Recent work, newest first. Scoped to what changed and why — see `BACKEND-API-REFERENCE.md` for the backend-dependency detail on anything marked "depends on backend."
## 2026-08-15 — Admin purchase notifications
Admin gets notified when a new order lands: a toast (click-to-navigate) plus an unread badge + order list on the topbar bell icon (previously an unused "no notifications" placeholder). Poll-based — the backend has no WebSocket/SSE, so this follows the same polling pattern already used for payment status.
- `AdminOrderWatcherService` (new) polls `AdminOrdersGateway.loadOrders()` on an admin-editable interval (default 15s, editable in Admin Settings), diffs against persisted "last notified"/"last acknowledged" order pointers, and fires toasts only for genuinely new orders — never spams on first load.
- `UserNotificationService` gained an optional click-to-navigate `route` so a toast can jump straight to the order detail page.
- Reactively stops/starts polling off `AdminAuthService.isAuthenticated()` — a first attempt at this (tying it to component destruction) turned out not to work because logout never navigates or destroys the admin shell; caught and corrected before merge.
- **Depends on backend:** the mock `AdminOrdersLocalGateway` has no create path, so this feature is functionally inert until Orders CRUD gets a real backend gateway. See `BACKEND-API-REFERENCE.md` §12.8.
- Design/plan: `docs/superpowers/specs/2026-08-15-admin-purchase-notifications-design.md`, `docs/superpowers/plans/2026-08-15-admin-purchase-notifications.md`.
## 2026-08-14 — Currency conversion (client-side)
Switching currency (RUB/USD/EUR/AMD) now actually converts displayed prices, instead of just swapping the currency label next to an unchanged number.
- `CurrencyRatesService` (new) holds RUB-based conversion rates, admin-editable in Admin Settings → Currency rates, persisted to `localStorage`.
- `CurrencyConvertPipe` (new) applies the selected currency's rate wherever a storefront price renders: product cards, product detail page, quick-view dialog, delivery pricing, compare table, cart line items and totals, delivery selector.
- Admin backoffice screens intentionally keep showing raw stored-currency values — that's the existing convention for every other admin price display.
- Fixed a follow-on bug: the cart's delivery-selector component was using the item's *source* currency as both the display label and the conversion target, so the amount never actually converted (only the label matched) — same number shown in every currency.
- **Depends on backend:** rates are a manually-typed admin number today, not a live exchange rate, because the backend doesn't return per-currency pricing. See `BACKEND-API-REFERENCE.md` §12.7 for the two proposed backend directions (server-side conversion, or a live FX-rate endpoint) — raised because bank settlement totals weren't reconciling against order counts, which points at a real pricing-accuracy gap, not just a display one.
---
Earlier history: `git log`.

223
GAPS-AND-IMPROVEMENTS.md
View File

@@ -1,223 +0,0 @@
# 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. **FIXED (verified 2026-08-17).** ~~Ed25519 admin-auth "session expired"/"invalid signature" screens were dead UI~~ — `toAuthErrorShape()` now reads `error.error.code` via `authErrorCodeFromBackendCode()` before falling back to HTTP status. See `BACKEND-API-REFERENCE.md` §5.
2. **FIXED (2026-08-17).** ~~Dark mode selector did nothing~~ — structural dark overrides (bg/text/border/shadow) now wired for all three tenant themes under `[data-theme-mode="dark"]`. Brand colors intentionally unchanged pending a theme-owner-approved dark palette.
3. **FIXED (verified 2026-08-17).** ~~"Site Layout" selector had no effect~~ — `SectionEngineService.resolveLayoutType()` now falls back to `bootstrap.layout.type` when a page has no layout of its own.
4. **Not a code gap (re-verified 2026-08-17), a content gap.** The mechanism is already fully generic: `features/project-editor/sections/footer-section.component.ts`'s Footer Builder lets an admin create any static page via the CMS and link it into a footer column by `pageKey`, resolved by `FooterResolverService`. "Contacts" just has no authored static page yet on whichever tenant's bootstrap this was checked against — that's a per-tenant content task, not a frontend fix.
5. **FIXED (verified 2026-08-17).** ~~Product pages got no per-product SEO~~ — `SeoService.setItemMeta(item)` is called from `product-details-container.component.ts`.
6. **FIXED (verified 2026-08-17).** ~~`og:locale` was hardcoded to `ru_RU`~~ — reads `languageService.currentLanguage()` via `OG_LOCALE_MAP` at both call sites.
7. **FIXED (verified 2026-08-17) on JSON-LD; sitemap remains backend-only work.** ~~No structured data (JSON-LD) exists anywhere~~ — `SeoService.setJsonLd()` injects a real `<script type="application/ld+json">` for `Product` (per-item, via `setItemMeta()`) and `Organization` (site default, via `resetToDefaults()`). No JSON-LD exists yet for `BreadcrumbList` or `ItemList`/category pages — smaller net-new addition if wanted. Sitemap generation is still backend-only, unchanged.
8. **FIXED (verified 2026-08-17).** ~~Checkout's payment-description fallback was a hardcoded Russian string~~ — `getPaymentDescription()` (`pages/cart/cart.component.ts:613`) already tries `branding.brandName`, then hostname, and only falls to `i18n.t('cart.paymentDescriptionFallback')` last, translated in all 3 languages (`i18n/{en,ru,hy}.ts`).
9. **FIXED (2026-08-17), user-authorized.** ~~Brand color contrast failed WCAG AA~~ — `--border-color` and `--success`/`--warning`/`--error`/`--info-color` darkened, hue-preserving, in all three theme files to clear 3:1 (border, non-text) and 4.5:1 (status colors, plain text). See [Accessibility](#as-accessibility-reviewer).
10. **FIXED (verified 2026-08-17).** ~~`stars.component.scss:10` used a literal hex color~~ — now uses `var(--border-color)`.
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. **FIXED (verified 2026-08-17).** ~~`AdminRole` was defined twice with unrelated shapes~~ — only one `AdminRole` export exists (`core/auth/models/permission.model.ts`); the Users-page shape is `AdminUserRoleRecord` with a disambiguating comment.
3. **Two unrelated `Category` types exist**, both fed by the same `/category` response, both still in active use.
4. **Worse than previously stated (re-verified 2026-08-17): three overlapping `SearchState`-shaped types, not two.** `core/search/models/search.model.ts` is already a clean re-export shim (fixed), but `core/search/models/search-state.model.ts` is a genuine second copy consumed by `catalog-container.component.ts`, and `features/search/facade/search.facade.ts` additionally defines its own private `LegacySearchState` interface with the same fields again. Reconciling all three touches the highest-traffic storefront surface (catalog rendering) — needs its own careful pass with full consumer tracing, not a quick rename.
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. **FIXED (verified 2026-08-17).** ~~`PRODUCT_DATA_PROVIDER`/`CATEGORY_REPOSITORY` had a dead mock branch~~ — both tokens' factories now resolve directly to the real API implementation with the dead switch removed, documented inline as intentional.
---
## As Accessibility Reviewer
1. **FIXED (2026-08-17), user-authorized.** ~~Brand color contrast failed WCAG AA~~ — see [Product Owner item 9 above](#as-product-owner--business). Applied a hue-preserving darkening of the failing tokens rather than a redesign; a distinct dark-mode-specific status palette (introduced alongside dark mode this session) has not been separately contrast-checked and remains open.
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. **FIXED (verified 2026-08-17).** ~~`sellerId` fields were typed as bare `string`~~ — `core/sellers/models/seller-scope.model.ts` and all other sellers-domain usages type it `UUID`.
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`).

374
README.md Normal file
View File

@@ -0,0 +1,374 @@
# Dexar Market (Multi-Brand Marketplace)
A modern, responsive marketplace application built with Angular 20 that supports multiple brands from a single codebase.
## 🎨 Multi-Brand Support
This project supports **two brands** with the same codebase:
- **Dexar Market** - Purple theme (`http://localhost:4200`)
- **Novo Market** - Green theme (`http://localhost:4201`)
Each brand has its own:
- Colors and themes
- Logos and branding
- Environment configuration
- Production builds
## Features
- 🎨 **Multi-Brand Architecture** - Single codebase, multiple brands
- 📱 **Fully Responsive** - Optimized for desktop, tablet, and mobile devices
- 🏪 **Category Browsing** - Hierarchical category navigation
- ♾️ **Infinite Scroll** - Seamless product loading in categories and search
- 🔍 **Real-time Search** - Debounced search with live results
- 🛒 **Shopping Cart** - API-managed cart with quantity support
- 📞 **Phone Collection** - Russian phone number formatting and validation
- ⭐ **Product Reviews** - Display ratings, reviews, and Q&A
- 💳 **Payment Integration** - Telegram Web App payment flow
- 📧 **Email Notifications** - Purchase confirmation emails
- 📱 **PWA Support** - Progressive Web App with offline support
- 🔔 **Service Worker** - Smart caching for better performance
- 🎨 **Modern UI** - Clean, intuitive interface with smooth animations
## Tech Stack
- **Angular 21** - Latest Angular with standalone components and signals
- **TypeScript** - Type-safe development
- **SCSS** - Modular styling with theme-based architecture
- **RxJS** - Reactive programming for API calls
- **Signals** - Angular signals for reactive state management
- **Telegram Web App** - Integration with Telegram Mini Apps
- **PWA** - Service workers and offline support
## Quick Start
### Development
**Run Dexar Market (Purple):**
```bash
npm start
# or
npm run start:dexar
```
Open: http://localhost:4200
**Run Novo Market (Green):**
```bash
npm run start:novo
```
Open: http://localhost:4201
### Production Build
**Build Dexar Market:**
```bash
npm run build:dexar
```
Output: `dist/dexarmarket/`
**Build Novo Market:**
```bash
npm run build:novo
```
Output: `dist/novomarket/`
## Project Structure
```
src/
├── app/
│ ├── components/
│ │ ├── header/ # Brand-aware header
│ │ ├── footer/ # Brand-aware footer
│ │ └── logo/ # Dynamic logo component
│ ├── models/
│ │ ├── category.model.ts # Category interface
│ │ └── item.model.ts # Item, Photo, Callback, Question
│ ├── pages/
│ │ ├── home/ # Categories overview
│ │ ├── category/ # Product listing with infinite scroll
│ │ ├── item-detail/ # Product details
│ │ ├── search/ # Search with infinite scroll
│ │ ├── cart/ # Shopping cart with checkout
│ │ ├── info/ # About, contacts, FAQ, etc.
│ │ └── legal/ # Legal documents
│ ├── services/
│ │ ├── api.service.ts # HTTP API integration
│ │ ├── cart.service.ts # Cart state management (signals)
│ │ └── telegram.service.ts # Telegram WebApp integration
│ └── interceptors/
│ └── cache.interceptor.ts # API caching
├── environments/
│ ├── environment.ts # Dexar development
│ ├── environment.production.ts # Dexar production
│ ├── environment.novo.ts # Novo development
│ └── environment.novo.production.ts # Novo production
├── styles/
│ ├── themes/
│ │ ├── dexar.theme.scss # Purple theme
│ │ └── novo.theme.scss # Green theme
│ └── shared-legal.scss # Shared legal page styles
├── index.html # Dexar HTML
└── index.novo.html # Novo HTML
```
## API Endpoints
**Base URL:** Configured per environment
### Health Check
- `GET /ping` - Server availability check
### Categories
- `GET /category` - Get all categories (hierarchical)
### Items
- `GET /category/:categoryID?count=50&skip=100` - Get items in category (paginated)
- `GET /items?search=query&count=50&skip=100` - Search items (paginated)
### Cart
- `GET /cart` - Get cart items with quantities
- `POST /cart` - Add item `{ itemID: number, quantity?: number }`
- `PATCH /cart` - Update quantity `{ itemID: number, quantity: number }`
- `DELETE /cart` - Remove items `[itemID1, itemID2, ...]`
### Payment
- `POST /payment/create` - Create payment intent
- `POST /purchase-email` - Send purchase confirmation
See [docs/API_CHANGES_REQUIRED.md](docs/API_CHANGES_REQUIRED.md) for detailed API specifications.
## Environment Configuration
Each brand has development and production environments:
### Dexar Market
**Development** (`environment.ts`):
```typescript
{
production: false,
brandName: 'Dexar Market',
apiUrl: '/api', // Uses proxy
// ... other config
}
```
**Production** (`environment.production.ts`):
```typescript
{
production: true,
brandName: 'Dexar Market',
apiUrl: 'https://api.dexarmarket.ru',
// ... other config
}
```
### Novo Market
**Development** (`environment.novo.ts`):
```typescript
{
production: false,
brandName: 'novo Market',
apiUrl: '/api', // Uses proxy
// ... other config
}
```
**Production** (`environment.novo.production.ts`):
```typescript
{
production: true,
brandName: 'novo Market',
apiUrl: 'https://api.novomarket.ru', // To be configured
// ... other config
}
```
## Deployment
### Prerequisites
1. Node.js 18+ and npm installed
2. Backend API running and accessible
3. Domain names configured (dexarmarket.ru, novomarket.ru)
### Build for Production
**For Dexar Market:**
```bash
npm run build:dexar
```
Output: `dist/dexarmarket/`
**For Novo Market:**
```bash
npm run build:novo
```
Output: `dist/novomarket/`
### Nginx Configuration
When deploying to production, you **must** configure nginx to handle Angular routing properly.
**Example nginx config (Dexar):**
```nginx
server {
listen 80;
server_name dexarmarket.ru www.dexarmarket.ru;
root /var/www/dexarmarket;
index index.html;
# Angular routing support
location / {
try_files $uri $uri/ /index.html;
}
# Gzip compression
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
# Cache static assets
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}
```
**For Novo Market**, use the same config with `novomarket.ru` and `/var/www/novomarket`.
### SSL Setup
Enable HTTPS with Let's Encrypt:
```bash
sudo certbot --nginx -d dexarmarket.ru -d www.dexarmarket.ru
sudo certbot --nginx -d novomarket.ru -d www.novomarket.ru
```
### Deploy Steps
1. Build the project:
```bash
npm run build:dexar
npm run build:novo
```
2. Upload to server:
```bash
scp -r dist/dexarmarket/* user@server:/var/www/dexarmarket/
scp -r dist/novomarket/* user@server:/var/www/novomarket/
```
3. Configure nginx (see above)
4. Reload nginx:
```bash
sudo nginx -t
sudo systemctl reload nginx
```
### Important Notes
- The `try_files $uri $uri/ /index.html;` directive is **critical** for Angular routing
- Without it, direct URL access or page refreshes will cause 404 errors
- Each brand needs its own server block with separate domain
- Update API URLs in production environment files before building
## PWA (Progressive Web App)
The application includes PWA support with:
- Service worker for offline caching
- Install prompts on mobile devices
- Brand-specific app icons and manifests
- Background sync capabilities
**Manifests:**
- Dexar: `public/manifest.webmanifest`
- Novo: `public/manifest.novo.webmanifest`
**Configuration:** `ngsw-config.json`
## Development
### Angular CLI Commands
**Generate a new component:**
```bash
ng generate component component-name
```
**For a complete list of schematics:**
```bash
ng generate --help
```
### Running Tests
**Unit tests:**
```bash
ng test
```
**E2E tests:**
```bash
ng e2e
```
## Documentation
Comprehensive documentation is available in the `docs/` folder:
- **[MULTI_BRAND.md](docs/MULTI_BRAND.md)** - Multi-brand architecture guide
- **[QUICK_START_NOVO.md](docs/QUICK_START_NOVO.md)** - Quick start for Novo brand
- **[API_CHANGES_REQUIRED.md](docs/API_CHANGES_REQUIRED.md)** - Backend API requirements
- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Deployment instructions
- **[PWA_SETUP.md](docs/PWA_SETUP.md)** - PWA configuration guide
- **[IMPLEMENTATION.md](docs/IMPLEMENTATION.md)** - Implementation details
- **[RECOMMENDATIONS.md](docs/RECOMMENDATIONS.md)** - Roadmap and improvements
- **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues and solutions
## Telegram Integration
The marketplace is designed to work as a Telegram Mini App:
1. Cart data is stored on backend per Telegram user
2. Payment flow uses Telegram's payment system
3. Deep linking support for sharing products
4. Telegram user info auto-collection
## Browser Compatibility
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Mobile browsers (iOS Safari, Chrome Mobile)
## Known Issues & Limitations
1. **Cart quantity support** - Backend needs to implement quantity fields (see [API_CHANGES_REQUIRED.md](docs/API_CHANGES_REQUIRED.md))
2. **Novo brand assets** - Logo and custom images need to be added
3. **Legal documents** - Need real company details for Novo brand before deployment
## Contributing
When contributing, please:
1. Follow the existing code style (use Prettier)
2. Write unit tests for new features
3. Update documentation as needed
4. Test both Dexar and Novo brands before committing
## License
Proprietary - All rights reserved
## Support
For technical support or questions:
- Email: dev@dexarmarket.ru
- Telegram: @dexarmarket
## Additional Resources
- [Angular CLI Documentation](https://angular.dev/tools/cli)
- [Angular Docs](https://angular.dev)
- [Telegram Web Apps](https://core.telegram.org/bots/webapps)

197
angular.json
View File

@@ -28,11 +28,6 @@
{
"glob": "**/*",
"input": "public"
},
{
"glob": "**/*",
"input": "src/assets",
"output": "assets"
}
],
"styles": [
@@ -58,8 +53,8 @@
"budgets": [
{
"type": "initial",
"maximumWarning": "700kB",
"maximumError": "1.8MB"
"maximumWarning": "600kB",
"maximumError": "1MB"
},
{
"type": "anyComponentStyle",
@@ -91,6 +86,146 @@
"optimization": false,
"extractLicenses": false,
"sourceMap": true
},
"novo": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.novo.ts"
},
{
"replace": "src/app/brands/brand-routes.ts",
"with": "src/app/brands/brand-routes.novo.ts"
},
{
"replace": "src/app/interceptors/mock-data.interceptor.ts",
"with": "src/app/interceptors/mock-data.interceptor.production.ts"
}
],
"index": "src/index.novo.html",
"styles": [
"src/styles.scss",
"src/styles/themes/novo.theme.scss"
],
"outputPath": "dist/novomarket",
"optimization": false,
"extractLicenses": false,
"sourceMap": true
},
"novo-production": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.novo.production.ts"
},
{
"replace": "src/app/brands/brand-routes.ts",
"with": "src/app/brands/brand-routes.novo.ts"
}
],
"index": "src/index.novo.html",
"styles": [
"src/styles.scss",
"src/styles/themes/novo.theme.scss"
],
"outputPath": "dist/novomarket",
"budgets": [
{
"type": "initial",
"maximumWarning": "600kB",
"maximumError": "1MB"
},
{
"type": "anyComponentStyle",
"maximumWarning": "40kB",
"maximumError": "50kB"
}
],
"outputHashing": "all",
"optimization": {
"scripts": true,
"styles": {
"minify": true,
"inlineCritical": true
},
"fonts": {
"inline": true
}
},
"sourceMap": false,
"namedChunks": false,
"extractLicenses": true,
"serviceWorker": "ngsw-config.json"
},
"lavero": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.lavero.ts"
},
{
"replace": "src/app/brands/brand-routes.ts",
"with": "src/app/brands/brand-routes.lavero.ts"
},
{
"replace": "src/app/interceptors/mock-data.interceptor.ts",
"with": "src/app/interceptors/mock-data.interceptor.production.ts"
}
],
"index": "src/index.lavero.html",
"styles": [
"src/styles.scss",
"src/styles/themes/lavero.theme.scss"
],
"outputPath": "dist/laveromarket",
"optimization": false,
"extractLicenses": false,
"sourceMap": true
},
"lavero-production": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.lavero.production.ts"
},
{
"replace": "src/app/brands/brand-routes.ts",
"with": "src/app/brands/brand-routes.lavero.ts"
}
],
"index": "src/index.lavero.html",
"styles": [
"src/styles.scss",
"src/styles/themes/lavero.theme.scss"
],
"outputPath": "dist/laveromarket",
"budgets": [
{
"type": "initial",
"maximumWarning": "600kB",
"maximumError": "1MB"
},
{
"type": "anyComponentStyle",
"maximumWarning": "40kB",
"maximumError": "50kB"
}
],
"outputHashing": "all",
"optimization": {
"scripts": true,
"styles": {
"minify": true,
"inlineCritical": true
},
"fonts": {
"inline": true
}
},
"sourceMap": false,
"namedChunks": false,
"extractLicenses": true,
"serviceWorker": "ngsw-config.json"
}
},
"defaultConfiguration": "production"
@@ -98,10 +233,13 @@
"serve": {
"options": {
"allowedHosts": [
"novo.market",
"dexarmarket.ru",
"dexar.market",
"localhost"
]
"localhost",
"lovero.store"
],
"proxyConfig": "proxy.conf.json"
},
"builder": "@angular/build:dev-server",
"configurations": {
@@ -109,40 +247,27 @@
"buildTarget": "Dexarmarket:build:production"
},
"development": {
"proxyConfig": "proxy.conf.json",
"buildTarget": "Dexarmarket:build:development"
},
"novo": {
"buildTarget": "Dexarmarket:build:novo",
"proxyConfig": "proxy.conf.novo.json"
},
"novo-production": {
"buildTarget": "Dexarmarket:build:novo-production"
},
"lavero": {
"buildTarget": "Dexarmarket:build:lavero",
"proxyConfig": "proxy.conf.lavero.json"
},
"lavero-production": {
"buildTarget": "Dexarmarket:build:lavero-production"
}
},
"defaultConfiguration": "development"
},
"extract-i18n": {
"builder": "@angular/build:extract-i18n"
},
"test": {
"builder": "@angular/build:karma",
"options": {
"polyfills": [
"zone.js",
"zone.js/testing"
],
"tsConfig": "tsconfig.spec.json",
"karmaConfig": "karma.conf.js",
"inlineStyleLanguage": "scss",
"assets": [
{
"glob": "**/*",
"input": "public"
},
{
"glob": "**/*",
"input": "src/assets",
"output": "assets"
}
],
"styles": [
"src/styles.scss"
]
}
}
}
}

726
docs/API_CHANGES_REQUIRED.md Normal file
View File

@@ -0,0 +1,726 @@
# Complete Backend API Documentation
> **Last updated:** February 2026
> **Frontend:** Angular 21 · Dual-brand (Dexar + Novo)
> **Covers:** Catalog, Cart, Payments, Reviews, Regions, Auth, i18n, BackOffice
---
## Base URLs
| Brand | Dev | Production |
|--------|----------------------------------|----------------------------------|
| Dexar | `https://api.dexarmarket.ru:445` | `https://api.dexarmarket.ru:445` |
| Novo | `https://api.novo.market:444` | `https://api.novo.market:444` |
---
## Global HTTP Headers
The frontend **automatically attaches** two custom headers to **every API request** via an interceptor. The backend should read these headers and use them to filter/translate responses accordingly.
| Header | Example Value | Description |
|---------------|---------------|------------------------------------------------------------|
| `X-Region` | `moscow` | Region ID selected by the user. **Absent** = global (all). |
| `X-Language` | `ru` | Active UI language: `ru`, `en`, or `hy`. |
### Backend behavior
- **`X-Region`**: If present, filter items/categories to only those available in that region. If absent, return everything (global catalog).
- **`X-Language`**: If present, return translated `name`, `description`, etc. for categories/items when translations exist. If absent or `ru`, use russians defaults.
### CORS requirements for these headers
```
Access-Control-Allow-Headers: Content-Type, X-Region, X-Language
```
---
## 1. Health Check
### `GET /ping`
Simple health check.
**Response `200`:**
```json
{ "message": "pong" }
```
---
## 2. Catalog — Categories
### `GET /category`
Returns all top-level categories. Respects `X-Region` and `X-Language` headers.
**Response `200`:**
```json
[
{
"categoryID": 1,
"name": "Электроника",
"parentID": 0,
"icon": "https://...",
"wideBanner": "https://...",
"itemCount": 42,
"priority": 10,
"id": "cat_abc123",
"visible": true,
"img": "https://...",
"projectId": "proj_xyz",
"subcategories": [
{
"id": "sub_001",
"name": "Смартфоны",
"visible": true,
"priority": 5,
"img": "https://...",
"categoryId": "cat_abc123",
"parentId": "cat_abc123",
"itemCount": 20,
"hasItems": true,
"subcategories": []
}
]
}
]
```
**Category object:**
| Field | Type | Required | Description |
|------------------|---------------|----------|----------------------------------------------------|
| `categoryID` | number | yes | Legacy numeric ID |
| `name` | string | yes | Category display name (translated if `X-Language`) |
| `parentID` | number | yes | Parent category ID (`0` = top-level) |
| `icon` | string | no | Category icon URL |
| `wideBanner` | string | no | Wide banner image URL |
| `itemCount` | number | no | Number of items in category |
| `priority` | number | no | Sort priority (higher = first) |
| `id` | string | no | BackOffice string ID |
| `visible` | boolean | no | Whether category is shown (`true` default) |
| `img` | string | no | BackOffice image URL (maps to `icon`) |
| `projectId` | string | no | BackOffice project reference |
| `subcategories` | Subcategory[] | no | Nested subcategories |
**Subcategory object:**
| Field | Type | Required | Description |
|------------------|---------------|----------|------------------------------------|
| `id` | string | yes | Subcategory ID |
| `name` | string | yes | Display name |
| `visible` | boolean | no | Whether visible |
| `priority` | number | no | Sort priority |
| `img` | string | no | Image URL |
| `categoryId` | string | yes | Parent category ID |
| `parentId` | string | yes | Direct parent ID |
| `itemCount` | number | no | Number of items |
| `hasItems` | boolean | no | Whether has any items |
| `subcategories` | Subcategory[] | no | Nested children |
---
### `GET /category/:categoryID`
Returns items in a specific category. Respects `X-Region` and `X-Language` headers.
**Query params:**
| Param | Type | Default | Description |
|----------|--------|---------|--------------------|
| `count` | number | `50` | Items per page |
| `skip` | number | `0` | Offset for paging |
**Response `200`:** Array of [Item](#item-object) objects.
---
## 3. Items
### `GET /item/:itemID`
Returns a single item. Respects `X-Region` and `X-Language` headers.
**Response `200`:** A single [Item](#item-object) object.
---
### `GET /searchitems`
Full-text search across items. Respects `X-Region` and `X-Language` headers.
**Query params:**
| Param | Type | Default | Description |
|----------|--------|---------|----------------------|
| `search` | string | — | Search query (required) |
| `count` | number | `50` | Items per page |
| `skip` | number | `0` | Offset for paging |
**Response `200`:**
```json
{
"items": [ /* Item objects */ ],
"total": 128,
"count": 50,
"skip": 0
}
```
---
### `GET /randomitems`
Returns random items for carousel/recommendations. Respects `X-Region` and `X-Language` headers.
**Query params:**
| Param | Type | Default | Description |
|------------|--------|---------|------------------------------------|
| `count` | number | `5` | Number of items to return |
| `category` | number | — | Optional: limit to this category |
**Response `200`:** Array of [Item](#item-object) objects.
---
### Item Object
The backend can return items in **either** legacy format or BackOffice format. The frontend normalizes both.
```json
{
"categoryID": 1,
"itemID": 123,
"name": "iPhone 15 Pro",
"photos": [{ "url": "https://..." }],
"description": "Описание товара",
"currency": "RUB",
"price": 89990,
"discount": 10,
"remainings": "high",
"rating": 4.5,
"callbacks": [
{
"rating": 5,
"content": "Отличный товар!",
"userID": "user_123",
"timestamp": "2026-02-01T12:00:00Z"
}
],
"questions": [
{
"question": "Есть ли гарантия?",
"answer": "Да, 12 месяцев",
"upvotes": 5,
"downvotes": 0
}
],
"id": "item_abc123",
"visible": true,
"priority": 10,
"imgs": ["https://img1.jpg", "https://img2.jpg"],
"tags": ["new", "popular"],
"badges": ["bestseller", "sale"],
"simpleDescription": "Краткое описание",
"descriptionFields": [
{ "key": "Процессор", "value": "A17 Pro" },
{ "key": "Память", "value": "256 GB" }
],
"subcategoryId": "sub_001",
"translations": {
"en": {
"name": "iPhone 15 Pro",
"simpleDescription": "Short description",
"description": [
{ "key": "Processor", "value": "A17 Pro" }
]
},
"hy": {
"name": "iPhone 15 Pro",
"simpleDescription": "Կարcheck check check"
}
},
"comments": [
{
"id": "cmt_001",
"text": "Отличный товар!",
"author": "user_123",
"stars": 5,
"createdAt": "2026-02-01T12:00:00Z"
}
],
"quantity": 50
}
```
**Full Item fields:**
| Field | Type | Required | Description |
|---------------------|-------------------|----------|------------------------------------------------------------|
| `categoryID` | number | yes | Category this item belongs to |
| `itemID` | number | yes | Legacy numeric item ID |
| `name` | string | yes | Item display name |
| `photos` | Photo[] | no | Legacy photo array `[{ url }]` |
| `description` | string | yes | Text description |
| `currency` | string | yes | Currency code (default: `RUB`) |
| `price` | number | yes | Price in the currency's smallest display unit |
| `discount` | number | yes | Discount percentage (`0`–`100`) |
| `remainings` | string | no | Stock level: `high`, `medium`, `low`, `out` |
| `rating` | number | yes | Average rating (`0`–`5`) |
| `callbacks` | Review[] | no | Legacy reviews (alias for reviews) |
| `questions` | Question[] | no | Q&A entries |
| `id` | string | no | BackOffice string ID |
| `visible` | boolean | no | Whether item is visible (`true` default) |
| `priority` | number | no | Sort priority (higher = first) |
| `imgs` | string[] | no | BackOffice image URLs (maps to `photos`) |
| `tags` | string[] | no | Item tags for filtering |
| `badges` | string[] | no | Display badges (`bestseller`, `sale`, etc.) |
| `simpleDescription` | string | no | Short plain-text description |
| `descriptionFields` | DescriptionField[]| no | Structured `[{ key, value }]` descriptions |
| `subcategoryId` | string | no | BackOffice subcategory reference |
| `translations` | Record | no | Translations keyed by lang code (see below) |
| `comments` | Comment[] | no | BackOffice comments format |
| `quantity` | number | no | Numeric stock count (maps to `remainings` on frontend) |
**Nested types:**
| Type | Fields |
|--------------------|-----------------------------------------------------------------|
| `Photo` | `url: string`, `photo?: string`, `video?: string`, `type?: string` |
| `DescriptionField` | `key: string`, `value: string` |
| `Comment` | `id?: string`, `text: string`, `author?: string`, `stars?: number`, `createdAt?: string` |
| `Review` | `rating?: number`, `content?: string`, `userID?: string`, `answer?: string`, `timestamp?: string` |
| `Question` | `question: string`, `answer: string`, `upvotes: number`, `downvotes: number` |
| `ItemTranslation` | `name?: string`, `simpleDescription?: string`, `description?: DescriptionField[]` |
---
## 4. Cart
### `POST /cart` — Add item to cart
**Request body:**
```json
{ "itemID": 123, "quantity": 1 }
```
**Response `200`:**
```json
{ "message": "Added to cart" }
```
---
### `PATCH /cart` — Update item quantity
**Request body:**
```json
{ "itemID": 123, "quantity": 3 }
```
**Response `200`:**
```json
{ "message": "Updated" }
```
---
### `DELETE /cart` — Remove items from cart
**Request body:** Array of item IDs
```json
[123, 456]
```
**Response `200`:**
```json
{ "message": "Removed" }
```
---
### `GET /cart` — Get cart contents
**Response `200`:** Array of [Item](#item-object) objects (each with `quantity` field).
---
## 5. Payments (SBP / QR)
### `POST /cart` — Create payment (SBP QR)
> Note: Same endpoint as add-to-cart but with different body schema.
**Request body:**
```json
{
"amount": 89990,
"currency": "RUB",
"siteuserID": "tg_123456789",
"siteorderID": "order_abc123",
"redirectUrl": "",
"telegramUsername": "john_doe",
"items": [
{ "itemID": 123, "price": 89990, "name": "iPhone 15 Pro" }
]
}
```
**Response `200`:**
```json
{
"qrId": "qr_abc123",
"qrStatus": "CREATED",
"qrExpirationDate": "2026-02-28T13:00:00Z",
"payload": "https://qr.nspk.ru/...",
"qrUrl": "https://qr.nspk.ru/..."
}
```
---
### `GET /qr/payment/:qrId` — Check payment status
**Response `200`:**
```json
{
"additionalInfo": "",
"paymentPurpose": "Order #order_abc123",
"amount": 89990,
"code": "SUCCESS",
"createDate": "2026-02-28T12:00:00Z",
"currency": "RUB",
"order": "order_abc123",
"paymentStatus": "COMPLETED",
"qrId": "qr_abc123",
"transactionDate": "2026-02-28T12:01:00Z",
"transactionId": 999,
"qrExpirationDate": "2026-02-28T13:00:00Z",
"phoneNumber": "+7XXXXXXXXXX"
}
```
| `paymentStatus` values | Meaning |
|------------------------|---------------------------|
| `CREATED` | QR generated, not paid |
| `WAITING` | Payment in progress |
| `COMPLETED` | Payment successful |
| `EXPIRED` | QR code expired |
| `CANCELLED` | Payment cancelled |
---
### `POST /purchase-email` — Submit email after payment
**Request body:**
```json
{
"email": "user@example.com",
"telegramUserId": "123456789",
"items": [
{ "itemID": 123, "name": "iPhone 15 Pro", "price": 89990, "currency": "RUB" }
]
}
```
**Response `200`:**
```json
{ "message": "Email sent" }
```
---
## 6. Reviews / Comments
### `POST /comment` — Submit a review
**Request body:**
```json
{
"itemID": 123,
"rating": 5,
"comment": "Great product!",
"username": "john_doe",
"userId": 123456789,
"timestamp": "2026-02-28T12:00:00Z"
}
```
**Response `200`:**
```json
{ "message": "Review submitted" }
```
---
## 7. Regions
### `GET /regions` — List available regions
Returns regions where the marketplace operates.
**Response `200`:**
```json
[
{
"id": "moscow",
"city": "Москва",
"country": "Россия",
"countryCode": "RU",
"timezone": "Europe/Moscow"
},
{
"id": "spb",
"city": "Санкт-Петербург",
"country": "Россия",
"countryCode": "RU",
"timezone": "Europe/Moscow"
},
{
"id": "yerevan",
"city": "Ереван",
"country": "Армения",
"countryCode": "AM",
"timezone": "Asia/Yerevan"
}
]
```
**Region object:**
| Field | Type | Required | Description |
|---------------|--------|----------|--------------------------|
| `id` | string | yes | Unique region identifier |
| `city` | string | yes | City name (display) |
| `country` | string | yes | Country name |
| `countryCode` | string | yes | ISO 3166-1 alpha-2 |
| `timezone` | string | no | IANA timezone |
> **Fallback:** If this endpoint is down, the frontend uses 6 hardcoded defaults: Moscow, SPB, Yerevan, Minsk, Almaty, Tbilisi.
---
## 8. Authentication (Telegram Login)
Authentication is **Telegram-based** with **cookie sessions** (HttpOnly, Secure, SameSite=None).
All auth endpoints must include `withCredentials: true` CORS support.
### Auth flow
```
1. User clicks "Checkout" → not authenticated → login dialog shown
2. User clicks "Log in with Telegram" → opens https://t.me/{bot}?start=auth_{callback}
3. User starts the bot in Telegram
4. Bot sends user data → backend /auth/telegram/callback
5. Backend creates session → sets Set-Cookie
6. Frontend polls GET /auth/session every 3s
7. Session detected → dialog closes → checkout proceeds
```
---
### `GET /auth/session` — Check current session
**Request:** Cookies only (session cookie set by backend).
**Response `200`** (authenticated):
```json
{
"sessionId": "sess_abc123",
"telegramUserId": 123456789,
"username": "john_doe",
"displayName": "John Doe",
"active": true,
"expiresAt": "2026-03-01T12:00:00Z"
}
```
**Response `200`** (expired):
```json
{
"sessionId": "sess_abc123",
"telegramUserId": 123456789,
"username": "john_doe",
"displayName": "John Doe",
"active": false,
"expiresAt": "2026-02-27T12:00:00Z"
}
```
**Response `401`** (no session):
```json
{ "error": "No active session" }
```
**AuthSession object:**
| Field | Type | Required | Description |
|------------------|---------|----------|--------------------------------------------|
| `sessionId` | string | yes | Unique session ID |
| `telegramUserId` | number | yes | Telegram user ID |
| `username` | string? | no | Telegram @username (can be null) |
| `displayName` | string | yes | User display name (first + last) |
| `active` | boolean | yes | Whether session is valid |
| `expiresAt` | string | yes | ISO 8601 expiration datetime |
---
### `GET /auth/telegram/callback` — Telegram bot auth callback
Called by the Telegram bot after user authenticates.
**Request body (from bot):**
```json
{
"id": 123456789,
"first_name": "John",
"last_name": "Doe",
"username": "john_doe",
"photo_url": "https://t.me/i/userpic/...",
"auth_date": 1709100000,
"hash": "abc123def456..."
}
```
**Response:** Must set a session cookie and return:
```json
{
"sessionId": "sess_abc123",
"message": "Authenticated successfully"
}
```
**Cookie requirements:**
| Attribute | Value | Notes |
|------------|----------------|--------------------------------------------|
| `HttpOnly` | `true` | Not accessible via JS |
| `Secure` | `true` | HTTPS only |
| `SameSite` | `None` | Required for cross-origin (API ≠ frontend) |
| `Path` | `/` | |
| `Max-Age` | `86400` (24h) | Or as needed |
---
### `POST /auth/logout` — End session
**Request:** Cookies only, empty body `{}`
**Response `200`:**
```json
{ "message": "Logged out" }
```
Must clear/invalidate the session cookie.
---
### Session refresh
The frontend re-checks the session **60 seconds before `expiresAt`**. If the backend supports sliding expiration, it can reset the cookie's `Max-Age` on each `GET /auth/session`.
---
## 9. i18n / Translations
The frontend supports 3 languages: **Russian (ru)**, **English (en)**, **Armenian (hy)**.
The active language is sent via the `X-Language` HTTP header on every request.
### What the backend should do with `X-Language`
1. **Categories & items**: If `translations` field exists for the requested language, return the translated `name`, `description`, etc. OR the backend can apply translations server-side and return already-translated fields.
2. **The `translations` field** on items (optional approach):
```json
{
"translations": {
"en": {
"name": "iPhone 15 Pro",
"simpleDescription": "Short desc in English",
"description": [{ "key": "Processor", "value": "A17 Pro" }]
},
"hy": {
"name": "iPhone 15 Pro",
"simpleDescription": "Կarcheck check"
}
}
}
```
3. **Recommended approach**: Read `X-Language` header and return the `name`/`description` in that language directly. If no translation exists, return the Russian default.
---
## 10. CORS Configuration
For auth cookies and custom headers to work, the backend CORS config must include:
```
Access-Control-Allow-Origin: https://dexarmarket.ru (NOT wildcard *)
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, X-Region, X-Language
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
```
> **Important:** `Access-Control-Allow-Origin` cannot be `*` when `Allow-Credentials: true`. Must be the exact frontend origin.
**Allowed origins:**
- `https://dexarmarket.ru`
- `https://novo.market`
- `http://localhost:4200` (dev)
- `http://localhost:4201` (dev, Novo)
---
## 11. Telegram Bot Setup
Each brand needs its own bot:
- **Dexar:** `@dexarmarket_bot`
- **Novo:** `@novomarket_bot`
The bot should:
1. Listen for `/start auth_{callbackUrl}` command
2. Extract the callback URL
3. Send the user's Telegram data (`id`, `first_name`, `username`, etc.) to that callback URL
4. The callback URL is `{apiUrl}/auth/telegram/callback`
---
## Complete Endpoint Reference
### New endpoints
| Method | Path | Description | Auth |
|--------|---------------------------|----------------------------|----------|
| `GET` | `/regions` | List available regions | No |
| `GET` | `/auth/session` | Check current session | Cookie |
| `GET` | `/auth/telegram/callback` | Telegram bot auth callback | No (bot) |
| `POST` | `/auth/logout` | End session | Cookie |
### Existing endpoints
| Method | Path | Description | Auth | Headers |
|----------|-----------------------|-------------------------|------|--------------------|
| `GET` | `/ping` | Health check | No | — |
| `GET` | `/category` | List categories | No | X-Region, X-Language |
| `GET` | `/category/:id` | Items in category | No | X-Region, X-Language |
| `GET` | `/item/:id` | Single item | No | X-Region, X-Language |
| `GET` | `/searchitems` | Search items | No | X-Region, X-Language |
| `GET` | `/randomitems` | Random items | No | X-Region, X-Language |
| `POST` | `/cart` | Add to cart / Payment | No* | — |
| `PATCH` | `/cart` | Update cart quantity | No* | — |
| `DELETE` | `/cart` | Remove from cart | No* | — |
| `GET` | `/cart` | Get cart contents | No* | — |
| `POST` | `/comment` | Submit review | No | — |
| `GET` | `/qr/payment/:qrId` | Check payment status | No | — |
| `POST` | `/purchase-email` | Submit email after pay | No | — |
> \* Cart/payment endpoints may use the session cookie if available for order association, but don't strictly require auth. The frontend enforces auth before checkout.

726
docs/API_DOCS_RU.md Normal file
View File

@@ -0,0 +1,726 @@
# Полная документация Backend API
> **Последнее обновление:** Февраль 2026
> **Фронтенд:** Angular 21 · Два бренда (Dexar + Novo)
> **Охватывает:** Каталог, Корзина, Оплата, Отзывы, Регионы, Авторизация, i18n, BackOffice
---
## Базовые URL
| Бренд | Dev | Production |
|--------|----------------------------------|----------------------------------|
| Dexar | `https://api.dexarmarket.ru:445` | `https://api.dexarmarket.ru:445` |
| Novo | `https://api.novo.market:444` | `https://api.novo.market:444` |
---
## Глобальные HTTP-заголовки
Фронтенд **автоматически добавляет** два кастомных заголовка к **каждому API-запросу** через interceptor. Бэкенд должен читать эти заголовки и использовать для фильтрации/перевода ответов.
| Заголовок | Пример значения | Описание |
|---------------|-----------------|-------------------------------------------------------------------|
| `X-Region` | `moscow` | ID региона, выбранного пользователем. **Отсутствует** = все регионы. |
| `X-Language` | `ru` | Активный язык интерфейса: `ru`, `en` или `hy`. |
### Поведение бэкенда
- **`X-Region`**: Если присутствует — фильтровать товары/категории только по этому региону. Если отсутствует — возвращать всё (глобальный каталог).
- **`X-Language`**: Если присутствует — возвращать переведённые `name`, `description` и т.д., если переводы существуют. Если отсутствует или `ru` — возвращать на русском (по умолчанию).
### Требования CORS для этих заголовков
```
Access-Control-Allow-Headers: Content-Type, X-Region, X-Language
```
---
## 1. Проверка состояния
### `GET /ping`
Простая проверка работоспособности.
**Ответ `200`:**
```json
{ "message": "pong" }
```
---
## 2. Каталог — Категории
### `GET /category`
Возвращает все категории верхнего уровня. Учитывает заголовки `X-Region` и `X-Language`.
**Ответ `200`:**
```json
[
{
"categoryID": 1,
"name": "Электроника",
"parentID": 0,
"icon": "https://...",
"wideBanner": "https://...",
"itemCount": 42,
"priority": 10,
"id": "cat_abc123",
"visible": true,
"img": "https://...",
"projectId": "proj_xyz",
"subcategories": [
{
"id": "sub_001",
"name": "Смартфоны",
"visible": true,
"priority": 5,
"img": "https://...",
"categoryId": "cat_abc123",
"parentId": "cat_abc123",
"itemCount": 20,
"hasItems": true,
"subcategories": []
}
]
}
]
```
**Объект Category:**
| Поле | Тип | Обязат. | Описание |
|------------------|---------------|---------|-----------------------------------------------------|
| `categoryID` | number | да | Числовой ID (legacy) |
| `name` | string | да | Название категории (переведённое если `X-Language`) |
| `parentID` | number | да | ID родительской категории (`0` = верхний уровень) |
| `icon` | string | нет | URL иконки категории |
| `wideBanner` | string | нет | URL широкого баннера |
| `itemCount` | number | нет | Количество товаров в категории |
| `priority` | number | нет | Приоритет сортировки (больше = выше) |
| `id` | string | нет | Строковый ID из BackOffice |
| `visible` | boolean | нет | Видима ли категория (по умолч. `true`) |
| `img` | string | нет | URL изображения из BackOffice (маппится на `icon`) |
| `projectId` | string | нет | Ссылка на проект в BackOffice |
| `subcategories` | Subcategory[] | нет | Вложенные подкатегории |
**Объект Subcategory:**
| Поле | Тип | Обязат. | Описание |
|------------------|---------------|---------|----------------------------------|
| `id` | string | да | ID подкатегории |
| `name` | string | да | Отображаемое название |
| `visible` | boolean | нет | Видима ли |
| `priority` | number | нет | Приоритет сортировки |
| `img` | string | нет | URL изображения |
| `categoryId` | string | да | ID родительской категории |
| `parentId` | string | да | ID прямого родителя |
| `itemCount` | number | нет | Количество товаров |
| `hasItems` | boolean | нет | Есть ли товары |
| `subcategories` | Subcategory[] | нет | Вложенные дочерние подкатегории |
---
### `GET /category/:categoryID`
Возвращает товары определённой категории. Учитывает заголовки `X-Region` и `X-Language`.
**Query-параметры:**
| Параметр | Тип | По умолч. | Описание |
|----------|--------|-----------|-----------------------|
| `count` | number | `50` | Товаров на страницу |
| `skip` | number | `0` | Смещение для пагинации |
**Ответ `200`:** Массив объектов [Item](#объект-item).
---
## 3. Товары
### `GET /item/:itemID`
Возвращает один товар. Учитывает заголовки `X-Region` и `X-Language`.
**Ответ `200`:** Один объект [Item](#объект-item).
---
### `GET /searchitems`
Полнотекстовый поиск по товарам. Учитывает заголовки `X-Region` и `X-Language`.
**Query-параметры:**
| Параметр | Тип | По умолч. | Описание |
|----------|--------|-----------|-------------------------------|
| `search` | string | — | Поисковый запрос (обязателен) |
| `count` | number | `50` | Товаров на страницу |
| `skip` | number | `0` | Смещение для пагинации |
**Ответ `200`:**
```json
{
"items": [ /* объекты Item */ ],
"total": 128,
"count": 50,
"skip": 0
}
```
---
### `GET /randomitems`
Возвращает случайные товары для карусели/рекомендаций. Учитывает заголовки `X-Region` и `X-Language`.
**Query-параметры:**
| Параметр | Тип | По умолч. | Описание |
|------------|--------|-----------|--------------------------------------|
| `count` | number | `5` | Количество товаров |
| `category` | number | — | Ограничить данной категорией (опц.) |
**Ответ `200`:** Массив объектов [Item](#объект-item).
---
### Объект Item
Бэкенд может возвращать товары в **любом** из двух форматов — legacy или BackOffice. Фронтенд нормализует оба варианта.
```json
{
"categoryID": 1,
"itemID": 123,
"name": "iPhone 15 Pro",
"photos": [{ "url": "https://..." }],
"description": "Описание товара",
"currency": "RUB",
"price": 89990,
"discount": 10,
"remainings": "high",
"rating": 4.5,
"callbacks": [
{
"rating": 5,
"content": "Отличный товар!",
"userID": "user_123",
"timestamp": "2026-02-01T12:00:00Z"
}
],
"questions": [
{
"question": "Есть ли гарантия?",
"answer": "Да, 12 месяцев",
"upvotes": 5,
"downvotes": 0
}
],
"id": "item_abc123",
"visible": true,
"priority": 10,
"imgs": ["https://img1.jpg", "https://img2.jpg"],
"tags": ["new", "popular"],
"badges": ["bestseller", "sale"],
"simpleDescription": "Краткое описание",
"descriptionFields": [
{ "key": "Процессор", "value": "A17 Pro" },
{ "key": "Память", "value": "256 GB" }
],
"subcategoryId": "sub_001",
"translations": {
"en": {
"name": "iPhone 15 Pro",
"simpleDescription": "Short description",
"description": [
{ "key": "Processor", "value": "A17 Pro" }
]
},
"hy": {
"name": "iPhone 15 Pro",
"simpleDescription": "Կարcheck check"
}
},
"comments": [
{
"id": "cmt_001",
"text": "Отличный товар!",
"author": "user_123",
"stars": 5,
"createdAt": "2026-02-01T12:00:00Z"
}
],
"quantity": 50
}
```
**Все поля Item:**
| Поле | Тип | Обязат. | Описание |
|---------------------|-------------------|---------|-----------------------------------------------------------|
| `categoryID` | number | да | Категория, к которой принадлежит товар |
| `itemID` | number | да | Числовой ID товара (legacy) |
| `name` | string | да | Название товара |
| `photos` | Photo[] | нет | Массив фотографий `[{ url }]` (legacy) |
| `description` | string | да | Текстовое описание |
| `currency` | string | да | Код валюты (по умолч. `RUB`) |
| `price` | number | да | Цена |
| `discount` | number | да | Процент скидки (`0`–`100`) |
| `remainings` | string | нет | Уровень остатка: `high`, `medium`, `low`, `out` |
| `rating` | number | да | Средний рейтинг (`0`–`5`) |
| `callbacks` | Review[] | нет | Отзывы (legacy формат) |
| `questions` | Question[] | нет | Вопросы и ответы |
| `id` | string | нет | Строковый ID из BackOffice |
| `visible` | boolean | нет | Виден ли товар (по умолч. `true`) |
| `priority` | number | нет | Приоритет сортировки (больше = выше) |
| `imgs` | string[] | нет | URL картинок из BackOffice (маппится на `photos`) |
| `tags` | string[] | нет | Теги для фильтрации |
| `badges` | string[] | нет | Бейджи (`bestseller`, `sale` и т.д.) |
| `simpleDescription` | string | нет | Краткое текстовое описание |
| `descriptionFields` | DescriptionField[]| нет | Структурированное описание `[{ key, value }]` |
| `subcategoryId` | string | нет | Ссылка на подкатегорию из BackOffice |
| `translations` | Record | нет | Переводы по ключу языка (см. ниже) |
| `comments` | Comment[] | нет | Комментарии в формате BackOffice |
| `quantity` | number | нет | Числовое кол-во на складе (маппится на `remainings`) |
**Вложенные типы:**
| Тип | Поля |
|--------------------|-----------------------------------------------------------------|
| `Photo` | `url: string`, `photo?: string`, `video?: string`, `type?: string` |
| `DescriptionField` | `key: string`, `value: string` |
| `Comment` | `id?: string`, `text: string`, `author?: string`, `stars?: number`, `createdAt?: string` |
| `Review` | `rating?: number`, `content?: string`, `userID?: string`, `answer?: string`, `timestamp?: string` |
| `Question` | `question: string`, `answer: string`, `upvotes: number`, `downvotes: number` |
| `ItemTranslation` | `name?: string`, `simpleDescription?: string`, `description?: DescriptionField[]` |
---
## 4. Корзина
### `POST /cart` — Добавить товар в корзину
**Тело запроса:**
```json
{ "itemID": 123, "quantity": 1 }
```
**Ответ `200`:**
```json
{ "message": "Added to cart" }
```
---
### `PATCH /cart` — Обновить количество товара
**Тело запроса:**
```json
{ "itemID": 123, "quantity": 3 }
```
**Ответ `200`:**
```json
{ "message": "Updated" }
```
---
### `DELETE /cart` — Удалить товары из корзины
**Тело запроса:** Массив ID товаров
```json
[123, 456]
```
**Ответ `200`:**
```json
{ "message": "Removed" }
```
---
### `GET /cart` — Получить содержимое корзины
**Ответ `200`:** Массив объектов [Item](#объект-item) (каждый с полем `quantity`).
---
## 5. Оплата (СБП / QR)
### `POST /cart` — Создать платёж (СБП QR)
> Примечание: Тот же эндпоинт что и добавление в корзину, но с другой схемой тела запроса.
**Тело запроса:**
```json
{
"amount": 89990,
"currency": "RUB",
"siteuserID": "tg_123456789",
"siteorderID": "order_abc123",
"redirectUrl": "",
"telegramUsername": "john_doe",
"items": [
{ "itemID": 123, "price": 89990, "name": "iPhone 15 Pro" }
]
}
```
**Ответ `200`:**
```json
{
"qrId": "qr_abc123",
"qrStatus": "CREATED",
"qrExpirationDate": "2026-02-28T13:00:00Z",
"payload": "https://qr.nspk.ru/...",
"qrUrl": "https://qr.nspk.ru/..."
}
```
---
### `GET /qr/payment/:qrId` — Проверить статус оплаты
**Ответ `200`:**
```json
{
"additionalInfo": "",
"paymentPurpose": "Order #order_abc123",
"amount": 89990,
"code": "SUCCESS",
"createDate": "2026-02-28T12:00:00Z",
"currency": "RUB",
"order": "order_abc123",
"paymentStatus": "COMPLETED",
"qrId": "qr_abc123",
"transactionDate": "2026-02-28T12:01:00Z",
"transactionId": 999,
"qrExpirationDate": "2026-02-28T13:00:00Z",
"phoneNumber": "+7XXXXXXXXXX"
}
```
| Значение `paymentStatus` | Значение |
|--------------------------|------------------------------|
| `CREATED` | QR создан, не оплачен |
| `WAITING` | Оплата в процессе |
| `COMPLETED` | Оплата успешна |
| `EXPIRED` | QR-код истёк |
| `CANCELLED` | Оплата отменена |
---
### `POST /purchase-email` — Отправить email после оплаты
**Тело запроса:**
```json
{
"email": "user@example.com",
"telegramUserId": "123456789",
"items": [
{ "itemID": 123, "name": "iPhone 15 Pro", "price": 89990, "currency": "RUB" }
]
}
```
**Ответ `200`:**
```json
{ "message": "Email sent" }
```
---
## 6. Отзывы / Комментарии
### `POST /comment` — Оставить отзыв
**Тело запроса:**
```json
{
"itemID": 123,
"rating": 5,
"comment": "Отличный товар!",
"username": "john_doe",
"userId": 123456789,
"timestamp": "2026-02-28T12:00:00Z"
}
```
**Ответ `200`:**
```json
{ "message": "Review submitted" }
```
---
## 7. Регионы
### `GET /regions` — Список доступных регионов
Возвращает регионы, в которых работает маркетплейс.
**Ответ `200`:**
```json
[
{
"id": "moscow",
"city": "Москва",
"country": "Россия",
"countryCode": "RU",
"timezone": "Europe/Moscow"
},
{
"id": "spb",
"city": "Санкт-Петербург",
"country": "Россия",
"countryCode": "RU",
"timezone": "Europe/Moscow"
},
{
"id": "yerevan",
"city": "Ереван",
"country": "Армения",
"countryCode": "AM",
"timezone": "Asia/Yerevan"
}
]
```
**Объект Region:**
| Поле | Тип | Обязат. | Описание |
|---------------|--------|---------|----------------------------------|
| `id` | string | да | Уникальный идентификатор региона |
| `city` | string | да | Название города |
| `country` | string | да | Название страны |
| `countryCode` | string | да | Код страны ISO 3166-1 alpha-2 |
| `timezone` | string | нет | Часовой пояс IANA |
> **Фоллбэк:** Если эндпоинт недоступен, фронтенд использует 6 захардкоженных значений: Москва, СПб, Ереван, Минск, Алматы, Тбилиси.
---
## 8. Авторизация (вход через Telegram)
Авторизация **через Telegram** с **cookie-сессиями** (HttpOnly, Secure, SameSite=None).
Все auth-эндпоинты должны поддерживать CORS с `credentials: true`.
### Процесс авторизации
```
1. Пользователь нажимает «Оформить заказ» → не авторизован → показывается диалог входа
2. Нажимает «Войти через Telegram» → открывается https://t.me/{bot}?start=auth_{callback}
3. Пользователь запускает бота в Telegram
4. Бот отправляет данные пользователя → бэкенд /auth/telegram/callback
5. Бэкенд создаёт сессию → устанавливает Set-Cookie
6. Фронтенд опрашивает GET /auth/session каждые 3 секунды
7. Сессия обнаружена → диалог закрывается → оформление заказа продолжается
```
---
### `GET /auth/session` — Проверить текущую сессию
**Запрос:** Только cookie (сессионная cookie, установленная бэкендом).
**Ответ `200`** (авторизован):
```json
{
"sessionId": "sess_abc123",
"telegramUserId": 123456789,
"username": "john_doe",
"displayName": "John Doe",
"active": true,
"expiresAt": "2026-03-01T12:00:00Z"
}
```
**Ответ `200`** (сессия истекла):
```json
{
"sessionId": "sess_abc123",
"telegramUserId": 123456789,
"username": "john_doe",
"displayName": "John Doe",
"active": false,
"expiresAt": "2026-02-27T12:00:00Z"
}
```
**Ответ `401`** (нет сессии):
```json
{ "error": "No active session" }
```
**Объект AuthSession:**
| Поле | Тип | Обязат. | Описание |
|------------------|---------|---------|-------------------------------------------|
| `sessionId` | string | да | Уникальный ID сессии |
| `telegramUserId` | number | да | ID пользователя в Telegram |
| `username` | string? | нет | @username в Telegram (может быть null) |
| `displayName` | string | да | Отображаемое имя (имя + фамилия) |
| `active` | boolean | да | Действительна ли сессия |
| `expiresAt` | string | да | Дата истечения в формате ISO 8601 |
---
### `GET /auth/telegram/callback` — Callback авторизации Telegram-бота
Вызывается Telegram-ботом после авторизации пользователя.
**Тело запроса (от бота):**
```json
{
"id": 123456789,
"first_name": "John",
"last_name": "Doe",
"username": "john_doe",
"photo_url": "https://t.me/i/userpic/...",
"auth_date": 1709100000,
"hash": "abc123def456..."
}
```
**Ответ:** Должен установить cookie сессии и вернуть:
```json
{
"sessionId": "sess_abc123",
"message": "Authenticated successfully"
}
```
**Требования к cookie:**
| Атрибут | Значение | Примечание |
|------------|----------------|-----------------------------------------------------|
| `HttpOnly` | `true` | Недоступна из JavaScript |
| `Secure` | `true` | Только HTTPS |
| `SameSite` | `None` | Обязательно для cross-origin (API ≠ фронтенд) |
| `Path` | `/` | |
| `Max-Age` | `86400` (24ч) | Или по необходимости |
---
### `POST /auth/logout` — Завершить сессию
**Запрос:** Только cookie, пустое тело `{}`
**Ответ `200`:**
```json
{ "message": "Logged out" }
```
Должен очистить/инвалидировать cookie сессии.
---
### Обновление сессии
Фронтенд повторно проверяет сессию за **60 секунд до `expiresAt`**. Если бэкенд поддерживает скользящий срок действия (sliding expiration), можно обновлять `Max-Age` cookie при каждом вызове `GET /auth/session`.
---
## 9. i18n / Переводы
Фронтенд поддерживает 3 языка: **Русский (ru)**, **Английский (en)**, **Армянский (hy)**.
Активный язык отправляется через HTTP-заголовок `X-Language` с каждым запросом.
### Что бэкенд должен делать с `X-Language`
1. **Категории и товары**: Если для запрошенного языка есть поле `translations`, вернуть переведённые `name`, `description` и т.д. ИЛИ бэкенд может применять переводы на стороне сервера и возвращать уже переведённые поля.
2. **Поле `translations`** на товарах (опциональный подход):
```json
{
"translations": {
"en": {
"name": "iPhone 15 Pro",
"simpleDescription": "Short desc in English",
"description": [{ "key": "Processor", "value": "A17 Pro" }]
},
"hy": {
"name": "iPhone 15 Pro",
"simpleDescription": "Կarcheck check"
}
}
}
```
3. **Рекомендуемый подход**: Читать заголовок `X-Language` и возвращать `name`/`description` на этом языке напрямую. Если перевода нет — возвращать русский вариант по умолчанию.
---
## 10. Настройка CORS
Для работы auth-cookie и кастомных заголовков конфигурация CORS бэкенда должна включать:
```
Access-Control-Allow-Origin: https://dexarmarket.ru (НЕ wildcard *)
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, X-Region, X-Language
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
```
> **Важно:** `Access-Control-Allow-Origin` не может быть `*` при `Allow-Credentials: true`. Должен быть точный origin фронтенда.
**Разрешённые origins:**
- `https://dexarmarket.ru`
- `https://novo.market`
- `http://localhost:4200` (dev)
- `http://localhost:4201` (dev, Novo)
---
## 11. Настройка Telegram-бота
Каждому бренду нужен свой бот:
- **Dexar:** `@dexarmarket_bot`
- **Novo:** `@novomarket_bot`
Бот должен:
1. Слушать команду `/start auth_{callbackUrl}`
2. Извлечь callback URL
3. Отправить данные пользователя (`id`, `first_name`, `username` и т.д.) на этот callback URL
4. Callback URL: `{apiUrl}/auth/telegram/callback`
---
## Полный справочник эндпоинтов
### Новые эндпоинты
| Метод | Путь | Описание | Авторизация |
|--------|---------------------------|---------------------------------|-------------|
| `GET` | `/regions` | Список доступных регионов | Нет |
| `GET` | `/auth/session` | Проверка текущей сессии | Cookie |
| `GET` | `/auth/telegram/callback` | Callback авторизации через бота | Нет (бот) |
| `POST` | `/auth/logout` | Завершение сессии | Cookie |
### Существующие эндпоинты
| Метод | Путь | Описание | Авт. | Заголовки |
|----------|-----------------------|---------------------------|------|--------------------|
| `GET` | `/ping` | Проверка состояния | Нет | — |
| `GET` | `/category` | Список категорий | Нет | X-Region, X-Language |
| `GET` | `/category/:id` | Товары категории | Нет | X-Region, X-Language |
| `GET` | `/item/:id` | Один товар | Нет | X-Region, X-Language |
| `GET` | `/searchitems` | Поиск товаров | Нет | X-Region, X-Language |
| `GET` | `/randomitems` | Случайные товары | Нет | X-Region, X-Language |
| `POST` | `/cart` | Добавить в корзину / Оплата | Нет* | — |
| `PATCH` | `/cart` | Обновить кол-во | Нет* | — |
| `DELETE` | `/cart` | Удалить из корзины | Нет* | — |
| `GET` | `/cart` | Содержимое корзины | Нет* | — |
| `POST` | `/comment` | Оставить отзыв | Нет | — |
| `GET` | `/qr/payment/:qrId` | Статус оплаты | Нет | — |
| `POST` | `/purchase-email` | Отправить email после оплаты | Нет | — |
> \* Эндпоинты корзины/оплаты могут использовать cookie сессии (если есть) для привязки к заказу, но не требуют авторизации строго. Фронтенд проверяет авторизацию перед оформлением заказа.

824
docs/BACKEND_AUTH_INTEGRATION.md Normal file
View File

@@ -0,0 +1,824 @@
# Авторизация через Telegram — Backend & Bot
> Всё что нужно Go-разработчику для реализации авторизации.
> Фронтенд **полностью готов** и ждёт эти эндпоинты.
---
## Статус
| Компонент | Готов? |
|-----------|--------|
| Frontend (Angular) — диалог, QR, поллинг, корзина | ✅ Готов |
| Telegram бот (обработка `/start`) | ❌ Нужно |
| Backend — 6 HTTP-эндпоинтов | ❌ Нужно |
| Хранилище сессий + QR-токенов | ❌ Нужно |
| CORS для cookie-based запросов | ❌ Нужно |
---
## Архитектура
Два сценария авторизации:
### Сценарий 1: Прямой вход (кнопка "Войти через Telegram")
Пользователь нажимает кнопку → открывается Telegram → бот выдаёт кнопку "Войти на сайт" → callback ставит cookie → фронтенд поллит `/auth/session`.
### Сценарий 2: QR-логин с десктопа (основной)
```
ДЕСКТОП БРАУЗЕР СЕРВЕР (Go) TELEGRAM
│ │ │
│ 1. POST /auth/qr/create │ │
│ ─────────────────────────────> │ │
│ { token: "abc", url: "..." } │ │
│ <───────────────────────────── │ │
│ │ │
│ 2. Показать QR: │ │
│ t.me/Bot?start=login_abc │ │
│ │ │
│ ПОЛЬЗОВАТЕЛЬ СКАНИРУЕТ ТЕЛЕФОНОМ │
│ │ │
│ │ 3. /start login_abc │
│ │ <────────────────────────│
│ │ │
│ │ Бот → POST /auth/qr/confirm
│ │ Бот → "✅ Вы вошли!" │
│ │ ────────────────────────>│
│ │ │
│ 4. GET /auth/qr/poll?token=abc │ │
│ (каждые 3 сек) │ │
│ ─────────────────────────────> │ │
│ { status: "confirmed", │ │
│ session: {...} } │ │
│ + Set-Cookie: dx_session=... │ │
│ <───────────────────────────── │ │
│ │ │
│ 5. POST /websession/{sessionId} │ │
│ [{ itemID, quantity, ... }] │ ← корзина │
│ ─────────────────────────────> │ │
│ │ │
│ 6. Готово! Авторизован + корзина│ │
```
---
## Бренды и боты
| Бренд | Username бота | Домен фронтенда | API сервер | Cookie Domain |
|-------|---------------|------------------|------------|---------------|
| Dexar | `DexarSupport_bot` | `dexarmarket.ru` | `api.dexarmarket.ru:445` | `.dexarmarket.ru` |
| Novo | `novomarket_bot` | `novo.market` | `api.novo.market:444` | `.novo.market` |
Бот создаётся через https://t.me/BotFather → `/newbot`. Сохранить `BOT_TOKEN`.
---
## Хранилище
### Структура: Сессия
```go
type Session struct {
SessionID string `json:"sessionId"`
TelegramUserID int64 `json:"telegramUserId"`
Username *string `json:"username"` // может быть null
DisplayName string `json:"displayName"`
Active bool `json:"active"`
ExpiresAt time.Time `json:"expiresAt"`
}
```
**TTL:** 24 часа.
### Структура: QR-токен (одноразовый)
```go
type AuthToken struct {
Token string `json:"token"`
Status string `json:"status"` // "pending" | "confirmed" | "expired"
SessionID string `json:"sessionId"` // заполняется после подтверждения ботом
CreatedAt time.Time `json:"createdAt"`
ExpiresAt time.Time `json:"expiresAt"`
}
```
**TTL:** 5 минут.
### Варианты хранения
**Redis (рекомендуется):**
```go
// Сессия
redisClient.Set(ctx, "session:"+s.SessionID, json, 24*time.Hour)
// QR-токен
redisClient.Set(ctx, "auth_token:"+t.Token, json, 5*time.Minute)
```
**sync.Map (для MVP):**
```go
var sessions sync.Map
var authTokens sync.Map
// Очистка устаревших токенов — запустить горутину при старте
func cleanupExpiredTokens() {
ticker := time.NewTicker(1 * time.Minute)
for range ticker.C {
authTokens.Range(func(key, value any) bool {
t := value.(AuthToken)
if time.Now().After(t.ExpiresAt) {
authTokens.Delete(key)
}
return true
})
}
}
```
---
## HTTP-эндпоинты
### 1. `POST /auth/qr/create`
Фронтенд вызывает при открытии диалога логина. Создаёт одноразовый QR-токен.
```go
func handleQrCreate(w http.ResponseWriter, r *http.Request) {
// 1. Сгенерировать криптографически безопасный токен
tokenBytes := make([]byte, 32)
if _, err := rand.Read(tokenBytes); err != nil {
http.Error(w, "internal error", 500)
return
}
token := base64.URLEncoding.WithPadding(base64.NoPadding).EncodeToString(tokenBytes)
// 2. Определить бота по origin
botUsername := getBotForOrigin(r.Header.Get("Origin"))
// 3. Сохранить токен
authToken := AuthToken{
Token: token,
Status: "pending",
CreatedAt: time.Now(),
ExpiresAt: time.Now().Add(5 * time.Minute),
}
saveAuthToken(authToken)
// 4. Ответить
qrURL := fmt.Sprintf("https://t.me/%s?start=login_%s", botUsername, token)
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]string{
"token": token,
"url": qrURL,
})
}
func getBotForOrigin(origin string) string {
if strings.Contains(origin, "novo.market") {
return "novomarket_bot"
}
return "DexarSupport_bot"
}
```
**Ответ:**
```json
{ "token": "dG9rZW4tYWJj....", "url": "https://t.me/DexarSupport_bot?start=login_dG9rZW4tYWJj...." }
```
> Telegram ограничивает `start` до 64 символов. `login_` (6) + base64url из 32 байт (43) = 49 ✅
---
### 2. `GET /auth/qr/poll?token={token}`
Фронтенд вызывает каждые 3 секунды. Когда бот подтвердил — возвращает сессию и ставит cookie.
```go
func handleQrPoll(w http.ResponseWriter, r *http.Request) {
tokenStr := r.URL.Query().Get("token")
if tokenStr == "" {
http.Error(w, "missing token", 400)
return
}
authToken, ok := getAuthToken(tokenStr)
if !ok {
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]string{"status": "expired"})
return
}
switch authToken.Status {
case "pending":
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]string{"status": "pending"})
case "confirmed":
session, err := getSession(authToken.SessionID)
if err != nil {
http.Error(w, "session not found", 500)
return
}
// Cookie в ДЕСКТОПНЫЙ браузер
domain := getDomainForOrigin(r.Header.Get("Origin"))
http.SetCookie(w, &http.Cookie{
Name: "dx_session",
Value: session.SessionID,
Path: "/",
HttpOnly: true,
Secure: true,
SameSite: http.SameSiteNoneMode,
MaxAge: 86400,
Domain: domain,
})
// Удалить использованный токен
deleteAuthToken(tokenStr)
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]interface{}{
"status": "confirmed",
"session": session,
})
}
}
func getDomainForOrigin(origin string) string {
if strings.Contains(origin, "novo.market") {
return ".novo.market"
}
return ".dexarmarket.ru"
}
```
**Ответы:**
| Статус | JSON |
|--------|------|
| Ждём | `{ "status": "pending" }` |
| Подтверждено | `{ "status": "confirmed", "session": { sessionId, telegramUserId, username, displayName, active, expiresAt } }` + `Set-Cookie` |
| Истекло | `{ "status": "expired" }` |
---
### 3. `POST /auth/qr/confirm` (внутренний, для бота)
Бот вызывает когда пользователь отсканировал QR. Привязывает сессию к токену.
```go
func handleQrConfirm(w http.ResponseWriter, r *http.Request) {
// Проверить секрет бота
if r.Header.Get("X-Bot-Secret") != os.Getenv("BOT_INTERNAL_SECRET") {
http.Error(w, "forbidden", 403)
return
}
var req struct {
Token string `json:"token"`
User struct {
ID int64 `json:"id"`
FirstName string `json:"first_name"`
LastName string `json:"last_name"`
Username string `json:"username"`
} `json:"telegram_user"`
}
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
http.Error(w, "bad request", 400)
return
}
authToken, ok := getAuthToken(req.Token)
if !ok || authToken.Status != "pending" {
http.Error(w, "token not found or already used", 404)
return
}
// Создать сессию
displayName := req.User.FirstName
if req.User.LastName != "" {
displayName += " " + req.User.LastName
}
var username *string
if req.User.Username != "" {
username = &req.User.Username
}
session := Session{
SessionID: uuid.New().String(),
TelegramUserID: req.User.ID,
Username: username,
DisplayName: displayName,
Active: true,
ExpiresAt: time.Now().Add(24 * time.Hour),
}
saveSession(session)
// Привязать сессию к токену
authToken.Status = "confirmed"
authToken.SessionID = session.SessionID
saveAuthToken(*authToken)
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}
```
**Запрос от бота:**
```json
{
"token": "dG9rZW4tYWJj...",
"telegram_user": {
"id": 123456789,
"first_name": "Иван",
"last_name": "Петров",
"username": "ivan_petrov"
}
}
```
---
### 4. `GET /auth/session`
Фронтенд вызывает для проверки текущей сессии. Читает cookie.
```go
func handleGetSession(w http.ResponseWriter, r *http.Request) {
cookie, err := r.Cookie("dx_session")
if err != nil {
http.Error(w, "unauthorized", 401)
return
}
session, err := getSession(cookie.Value)
if err != nil {
http.Error(w, "unauthorized", 401)
return
}
if time.Now().After(session.ExpiresAt) {
session.Active = false
saveSession(session)
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(session)
}
```
**Формат ответа (200)** — фронтенд ожидает **точно эти поля**:
```json
{
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
"telegramUserId": 123456789,
"username": "ivan_petrov",
"displayName": "Иван Петров",
"active": true,
"expiresAt": "2026-03-25T14:30:00Z"
}
```
| Поле | Тип | Обязательно | Примечание |
|------|-----|-------------|------------|
| `sessionId` | string (UUID) | да | Используется для `/websession/{sessionId}` |
| `telegramUserId` | number | да | Telegram user ID |
| `username` | string / null | нет | Telegram @username |
| `displayName` | string | да | "Имя Фамилия" — показывается в UI |
| `active` | boolean | да | `false` = истекла |
| `expiresAt` | string (ISO 8601) | да | Фронтенд перепроверяет за 60 сек до |
**Ошибка:** любой HTTP не-200 → фронтенд считает "не авторизован".
---
### 5. `GET /auth/telegram/callback`
Для прямого входа (по кнопке в Telegram, не через QR). Открывается в браузере.
```go
func handleTelegramCallback(w http.ResponseWriter, r *http.Request) {
token := r.URL.Query().Get("token")
if token == "" {
http.Error(w, "missing token", 400)
return
}
session, err := getSession(token)
if err != nil || !session.Active {
http.Error(w, "invalid or expired token", 401)
return
}
domain := getDomainForOrigin(r.Header.Get("Origin"))
if domain == "" {
domain = ".dexarmarket.ru" // fallback для прямого перехода
}
http.SetCookie(w, &http.Cookie{
Name: "dx_session",
Value: session.SessionID,
Path: "/",
HttpOnly: true,
Secure: true,
SameSite: http.SameSiteNoneMode,
MaxAge: 86400,
Domain: domain,
})
// Редирект на сайт
http.Redirect(w, r, "https://dexarmarket.ru", http.StatusFound)
}
```
---
### 6. `POST /auth/logout`
```go
func handleLogout(w http.ResponseWriter, r *http.Request) {
cookie, err := r.Cookie("dx_session")
if err == nil {
deleteSession(cookie.Value)
}
http.SetCookie(w, &http.Cookie{
Name: "dx_session",
Value: "",
Path: "/",
HttpOnly: true,
Secure: true,
SameSite: http.SameSiteNoneMode,
MaxAge: -1,
Domain: ".dexarmarket.ru",
})
w.Header().Set("Content-Type", "application/json")
w.Write([]byte(`{"message":"ok"}`))
}
```
---
## Cookie-параметры
| Параметр | Значение | Почему |
|----------|----------|--------|
| `Name` | `dx_session` | |
| `SameSite` | `None` | Фронтенд на `dexarmarket.ru`, API на `api.dexarmarket.ru:445` — разные origins |
| `Secure` | `true` | Обязательно при `SameSite=None` |
| `Domain` | `.dexarmarket.ru` | Доступна и на `dexarmarket.ru` и на `api.dexarmarket.ru` |
| `HttpOnly` | `true` | Недоступна из JS — защита от XSS |
| `MaxAge` | `86400` | 24 часа |
---
## CORS
Фронтенд шлёт `withCredentials: true`. Бэкенд обязан вернуть правильные заголовки.
```go
func corsMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
origin := r.Header.Get("Origin")
allowed := map[string]bool{
"https://dexarmarket.ru": true,
"https://www.dexarmarket.ru": true,
"https://novo.market": true,
"https://www.novo.market": true,
"http://localhost:4200": true,
}
if allowed[origin] {
w.Header().Set("Access-Control-Allow-Origin", origin) // НЕ "*"
w.Header().Set("Access-Control-Allow-Credentials", "true")
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
}
if r.Method == "OPTIONS" {
w.WriteHeader(200)
return
}
next.ServeHTTP(w, r)
})
}
```
> **Критично:** `Access-Control-Allow-Origin` не может быть `"*"` при `withCredentials`. Вернуть конкретный origin.
---
## Роутинг
```go
mux := http.NewServeMux()
// Существующие
mux.HandleFunc("GET /items/{id}", handleGetItem)
mux.HandleFunc("GET /category", handleGetCategories)
mux.HandleFunc("POST /websession/{id}", handleWebSession)
mux.HandleFunc("POST /websession/{id}/qr", handleCreateQR)
mux.HandleFunc("GET /websession/{id}/{qrId}", handleCheckPayment)
// Auth — прямой вход
mux.HandleFunc("GET /auth/session", handleGetSession)
mux.HandleFunc("GET /auth/telegram/callback", handleTelegramCallback)
mux.HandleFunc("POST /auth/logout", handleLogout)
// Auth — QR-логин
mux.HandleFunc("POST /auth/qr/create", handleQrCreate)
mux.HandleFunc("GET /auth/qr/poll", handleQrPoll)
mux.HandleFunc("POST /auth/qr/confirm", handleQrConfirm)
handler := corsMiddleware(mux)
http.ListenAndServeTLS(":445", "cert.pem", "key.pem", handler)
```
---
## Telegram-бот
### Обработчик `/start`
```go
const (
confirmURL = "http://localhost:8080/auth/qr/confirm"
botInternalSecret = os.Getenv("BOT_INTERNAL_SECRET")
)
func handleStart(update tgbotapi.Update) {
text := update.Message.Text
user := update.Message.From
switch {
case strings.HasPrefix(text, "/start login_"):
handleQrLogin(update, user, strings.TrimPrefix(text, "/start login_"))
case strings.HasPrefix(text, "/start auth"):
handleDirectAuth(update, user)
default:
sendWelcome(update)
}
}
```
### QR-логин (основной)
```go
func handleQrLogin(update tgbotapi.Update, user *tgbotapi.User, token string) {
reqBody := map[string]interface{}{
"token": token,
"telegram_user": map[string]interface{}{
"id": user.ID,
"first_name": user.FirstName,
"last_name": user.LastName,
"username": user.UserName,
},
}
bodyBytes, _ := json.Marshal(reqBody)
req, _ := http.NewRequest("POST", confirmURL, bytes.NewReader(bodyBytes))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Bot-Secret", botInternalSecret)
resp, err := http.DefaultClient.Do(req)
if err != nil || resp.StatusCode != 200 {
msg := tgbotapi.NewMessage(update.Message.Chat.ID,
"❌ Не удалось войти. QR-код мог устареть. Попробуйте обновить страницу и отсканировать новый QR.")
bot.Send(msg)
return
}
defer resp.Body.Close()
displayName := buildDisplayName(user)
msg := tgbotapi.NewMessage(update.Message.Chat.ID,
fmt.Sprintf("✅ Вы вошли на сайт как %s!\n\nМожете вернуться в браузер — страница обновится автоматически.", displayName))
bot.Send(msg)
}
func buildDisplayName(user *tgbotapi.User) string {
name := user.FirstName
if user.LastName != "" {
name += " " + user.LastName
}
return name
}
```
### Прямой вход (кнопка, для обратной совместимости)
```go
func handleDirectAuth(update tgbotapi.Update, user *tgbotapi.User) {
session := Session{
SessionID: uuid.New().String(),
TelegramUserID: user.ID,
Username: stringPtr(user.UserName),
DisplayName: buildDisplayName(user),
Active: true,
ExpiresAt: time.Now().Add(24 * time.Hour),
}
saveSession(session)
callbackURL := "https://api.dexarmarket.ru:445/auth/telegram/callback"
loginURL := callbackURL + "?token=" + session.SessionID
msg := tgbotapi.NewMessage(update.Message.Chat.ID, "Нажмите кнопку чтобы войти:")
msg.ReplyMarkup = tgbotapi.NewInlineKeyboardMarkup(
tgbotapi.NewInlineKeyboardRow(
tgbotapi.NewInlineKeyboardButtonURL("🔐 Войти на сайт", loginURL),
),
)
bot.Send(msg)
}
```
### Запуск бота (long polling)
```go
func main() {
bot, _ := tgbotapi.NewBotAPI(os.Getenv("BOT_TOKEN"))
u := tgbotapi.NewUpdate(0)
u.Timeout = 60
updates := bot.GetUpdatesChan(u)
for update := range updates {
if update.Message != nil && strings.HasPrefix(update.Message.Text, "/start") {
handleStart(update)
}
}
}
```
---
## Синхронизация корзины
Сразу после QR-логина фронтенд автоматически отправляет корзину:
```
POST /websession/{sessionId}
```
Тело — массив:
```json
[
{
"itemID": 123,
"quantity": 2,
"colour": "#ff0000",
"size": "XL",
"price": 1500
}
]
```
| Поле | Тип | Примечание |
|------|-----|------------|
| `itemID` | number | ID товара |
| `quantity` | number | Количество |
| `colour` | string | CSS hex (`#ff0000`). Бэкенд отдаёт `0xff0000`, фронтенд конвертирует |
| `size` | string | `"default"` если размер один |
| `price` | number | Финальная цена **с учётом скидки** |
> Этот эндпоинт (`POST /websession/{id}`) уже существует. Ничего менять не нужно, просто учитывать что он вызывается сразу после успешного логина.
---
## Безопасность
### Криптографический токен
```go
tokenBytes := make([]byte, 32) // 256 бит
crypto/rand.Read(tokenBytes)
token := base64.URLEncoding.WithPadding(base64.NoPadding).EncodeToString(tokenBytes)
```
**НЕ использовать:** `math/rand`, UUID, timestamp.
### Токен одноразовый
- После `confirmed` → удалить при первом успешном `poll`
- После 5 минут → автоудаление (TTL)
- Повторный `poll` → `"expired"`
### Защита `/auth/qr/confirm`
```go
if r.Header.Get("X-Bot-Secret") != os.Getenv("BOT_INTERNAL_SECRET") {
http.Error(w, "forbidden", 403)
return
}
```
Дополнительно: можно ограничить по IP (`127.0.0.1`) если бот на том же сервере.
### Rate limiting для `/auth/qr/create`
Не более **5 токенов в минуту** с одного IP:
```go
var ipCounts sync.Map
func rateLimitQrCreate(ip string) bool {
key := ip + ":" + time.Now().Format("2006-01-02T15:04")
val, _ := ipCounts.LoadOrStore(key, new(int32))
count := atomic.AddInt32(val.(*int32), 1)
return count <= 5
}
```
---
## Переменные окружения
```env
BOT_TOKEN=123456:ABC-DEF...
BOT_INTERNAL_SECRET=случайная-строка-минимум-32-символа
FRONTEND_URL=https://dexarmarket.ru
SESSION_TTL=24h
REDIS_URL=localhost:6379
```
`BOT_INTERNAL_SECRET` должен совпадать в env сервера и env бота.
---
## Тестирование
### curl-тесты
**1. Создание токена:**
```bash
curl -X POST https://api.dexarmarket.ru:445/auth/qr/create \
-H "Origin: https://dexarmarket.ru"
# → { "token": "dG9r...", "url": "https://t.me/DexarSupport_bot?start=login_dG9r..." }
```
**2. Поллинг (до подтверждения):**
```bash
curl "https://api.dexarmarket.ru:445/auth/qr/poll?token=dG9r..."
# → { "status": "pending" }
```
**3. Подтверждение (имитация бота):**
```bash
curl -X POST https://api.dexarmarket.ru:445/auth/qr/confirm \
-H "Content-Type: application/json" \
-H "X-Bot-Secret: ваш-секрет" \
-d '{"token":"dG9r...","telegram_user":{"id":123,"first_name":"Тест","last_name":"","username":"testuser"}}'
# → { "status": "ok" }
```
**4. Поллинг (после подтверждения):**
```bash
curl -v "https://api.dexarmarket.ru:445/auth/qr/poll?token=dG9r..."
# → { "status": "confirmed", "session": {...} } + Set-Cookie: dx_session=...
```
**5. E2E:**
1. Открыть маркетплейс → добавить товар в корзину
2. Нажать "Оформить заказ" → появляется диалог с QR
3. Отсканировать QR телефоном → Telegram → бот: "✅ Вы вошли!"
4. Через 3 сек диалог закрывается → авторизован
5. Корзина синхронизирована (`POST /websession/{sessionId}`)
### Отладка
| Проблема | Где смотреть |
|----------|-------------|
| QR не показывается | `POST /auth/qr/create` — ошибка? CORS? |
| QR отсканирован, ничего не происходит | Бот получил `/start login_...`? Бот вызвал `confirm`? |
| Бот пишет "❌ QR устарел" | Токен expired? 5 минут прошло? |
| Поллинг "pending" бесконечно | Бот не вызвал `confirm`. Логи бота |
| Поллинг "confirmed" но cookie нет | `SameSite`, `Secure`, `Domain`, CORS |
---
## Чеклист
### Бэкенд (Go)
- [ ] Структура `Session` + `AuthToken`, функции save/get/delete
- [ ] `POST /auth/qr/create` — генерация токена
- [ ] `GET /auth/qr/poll?token=...` — статус + cookie при confirmed
- [ ] `POST /auth/qr/confirm` — приём от бота с `X-Bot-Secret`
- [ ] `GET /auth/session` — чтение cookie, JSON сессии
- [ ] `GET /auth/telegram/callback?token=...` — cookie + редирект
- [ ] `POST /auth/logout` — удаление сессии и cookie
- [ ] TTL 5 мин для токенов, 24ч для сессий
- [ ] Rate limiting `/auth/qr/create` (5/мин/IP)
- [ ] Очистка устаревших токенов
- [ ] CORS middleware
- [ ] `BOT_INTERNAL_SECRET` в env
### Telegram бот
- [ ] Обработка `/start login_{token}` → `POST /auth/qr/confirm`
- [ ] Обработка `/start auth` → создание сессии + кнопка "Войти"
- [ ] Сообщения: "✅ Вы вошли" / "❌ QR устарел"
- [ ] `BOT_INTERNAL_SECRET` в env (совпадает с сервером)
- [ ] `BOT_TOKEN` в env

321
docs/DEPLOYMENT.md
View File

@@ -1,197 +1,156 @@
# Deployment — server provisioning, CD, TLS
# Dexar Market - Deployment Guide
Frontend only. The backend service (`:8080`) is a separate developer's responsibility; nginx already proxies `/api/` to it and will `502` until it exists.
## Prerequisites
- Ubuntu/Debian server with root access
- Domain: dexarmarket.ru
- Node.js 18+ installed
**Multi-tenant, one bundle.** Every customer domain is served by the same build. The SPA resolves its tenant from the `Host` header ([BACKEND-HANDOFF §1a](backend/BACKEND-HANDOFF.md)). One deploy updates every domain simultaneously — there is no per-tenant build and no per-tenant deploy.
---
## 1. Files
| Path | Purpose |
|---|---|
| `scripts/deploy/server-setup.sh` | One-time server provisioning. Idempotent. Run as root. |
| `scripts/deploy/add-domain.sh` | Attach one domain + issue TLS. Run per domain, as root, after DNS resolves. |
| `.github/workflows/deploy.yml` | CD: build → upload → atomic swap → verify. Triggers on push to `main`. |
---
## 2. Layout on the server
```
/srv/marketplaces/
├── releases/
│ ├── a1b2c3d4e5f6/frontend/ <- one directory per deployed commit
│ └── ... (last 5 kept)
└── current -> releases/a1b2c3d4e5f6
```
nginx root is `/srv/marketplaces/current/frontend`. Activation is a symlink swap, so no request is ever served from a half-written directory, and a rollback is a symlink change rather than a rebuild.
---
## 3. First-time setup
### 3.1 Generate a CI deploy key
On your machine, **not** on the server:
## Quick Deployment
### 1. Build locally
```bash
ssh-keygen -t ed25519 -C "ci@marketplaces" -f ./marketplaces_deploy -N ""
npm install
npm run build
```
Output: `dist/dexarmarket/browser/`
**VERIFY BUILD LOCALLY:**
```bash
cd dist/dexarmarket/browser
ls -la
```
You MUST see `index.html`, chunk files, `assets/` folder, etc.
### 2. Upload to server
```bash
scp -r dist/dexarmarket/browser/* user@your-server:/var/www/dexarmarket/browser/
```
Two files result. `marketplaces_deploy.pub` goes to the server; `marketplaces_deploy` (private) goes into CI secrets and nowhere else.
### 3.2 Provision the server
Copy `scripts/deploy/` to the server and run:
### 3. Set permissions on server
```bash
sudo bash server-setup.sh --pubkey "$(cat marketplaces_deploy.pub)"
```
This installs nginx + certbot, creates a **key-only** `deploy` user with no password, writes the catch-all nginx config, opens 80/443/OpenSSH in ufw, and grants `deploy` exactly one sudo right: `systemctl reload nginx`.
Verify before continuing:
```bash
curl -I http://<server-ip>/health
```
Expect `200`. A placeholder page is served until the first real deploy.
### 3.3 Capture the host key
```bash
ssh-keyscan -H <server-ip>
```
The output is the `DEPLOY_KNOWN_HOSTS` secret. Pinning it means a rebuilt or impersonated server fails the deploy instead of being trusted silently.
### 3.4 Add CI secrets
| Secret | Value |
|---|---|
| `DEPLOY_HOST` | server IP or hostname |
| `DEPLOY_USER` | `deploy` |
| `DEPLOY_SSH_KEY` | contents of the **private** key file |
| `DEPLOY_KNOWN_HOSTS` | output of `ssh-keyscan -H <server-ip>` |
### 3.5 Deploy
Push to `main`, or run the workflow manually with a ref. The workflow refuses to swap the symlink unless the uploaded release contains an `index.html`, so a failed upload leaves the previous release serving.
---
## 4. Domains and TLS — dynamic by default
Domains arrive continuously: one today, five tomorrow. Nothing here requires a person per domain.
**HTTP already needs zero configuration.** The nginx catch-all serves *any* `Host`, and the SPA resolves its tenant from that header. Point a domain's A record at the server and it works over port 80 immediately. Only TLS needs a certificate per name — that is the whole problem this section solves.
Two mechanisms, used together:
### 4.1 Wildcard — tenants on our own apex
One certificate covers every `<slug>.<apex>`. A new tenant subdomain is then live over HTTPS the moment DNS resolves, with **no certificate work at all**.
```bash
sudo bash setup-wildcard-tls.sh \
--apex marketplaces.example.com \
--email ops@example.com \
--dns cloudflare --creds /root/cloudflare.ini
```
Wildcards require DNS-01 validation, so certbot must write a `_acme-challenge` TXT record. With a provider plugin (`cloudflare`, `route53`) renewal is unattended. `--dns manual` works but prompts for a TXT record at **every** renewal — fine to prove the setup out, not acceptable as a steady state.
**Hostinger has no certbot plugin.** If DNS lives there: either move DNS to a provider that has one (Cloudflare is free, minutes of work), or drive issuance from the [Phase 9](backend/PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md) domain-automation API once it exists.
### 4.2 Reconciler — tenants on their own domains
A wildcard cannot cover a customer's own domain. `sync-domains.sh` runs on a 10-minute timer and reconciles the live set against a desired list:
- issues certificates for domains that lack one
- skips domains whose certificate has more than 30 days left
- skips subdomains already covered by `WILDCARD_APEX`
- leaves domains alone while their DNS has not propagated yet, and retries next tick
- disables server blocks for domains removed from the source — **without deleting the certificate**, so re-adding one later is instant
- caps issuance per run, so a misconfigured source cannot burn the weekly ACME budget in a single pass
Configure `/etc/marketplaces/domains.env`:
```bash
DOMAINS_SOURCE=file:/etc/marketplaces/domains.txt
CERTBOT_EMAIL=ops@example.com
MAX_ISSUE_PER_RUN=10
```
Then:
```bash
sudo systemctl enable --now marketplaces-domains.timer
sudo /srv/marketplaces/bin/sync-domains.sh --dry-run # see the plan, change nothing
```
Adding a domain becomes: append a line to `/etc/marketplaces/domains.txt` (or add the row in the backend registry), point DNS, wait one tick.
### 4.3 Backend-driven, once Phase 9 ships
Point the reconciler at the registry instead of a file and the loop closes — `MarketplaceDomain` already carries exactly the statuses this needs (`planned → dns_pending → ssl_pending → active → failed`):
```bash
DOMAINS_SOURCE=https://api.example.com/api/admin/v2/domains
DOMAINS_API_TOKEN=...
```
The script accepts a bare JSON array of hostnames, or objects with `domain` + `status`, in which case it acts only on `active` rows. **A fetch failure aborts the run rather than reading as "remove every domain."**
### 4.4 One-off
For a single domain, outside the reconciler:
```bash
sudo bash add-domain.sh shop.example.com --email ops@example.com --with-www
```
### 4.5 Verify
```bash
curl -I https://shop.example.com/health
sudo certbot certificates
journalctl -u marketplaces-domains.service --since "1 hour ago"
```
---
## 5. Rollback
```bash
ssh deploy@<server-ip>
ls -1dt /srv/marketplaces/releases/*/ # newest first
ln -sfnT /srv/marketplaces/releases/<sha> /srv/marketplaces/current.new
mv -Tf /srv/marketplaces/current.new /srv/marketplaces/current
sudo chown -R www-data:www-data /var/www/dexarmarket
sudo chmod -R 755 /var/www/dexarmarket
sudo nginx -t
sudo systemctl reload nginx
```
Only the last 5 releases are retained. Older ones need a rebuild from the tag.
---
## 6. Operational checks
## Initial Server Setup (one-time)
### Install and configure Nginx
```bash
curl -I http://<host>/health # 200 from nginx
readlink -f /srv/marketplaces/current # which commit is live
sudo nginx -t # config valid
systemctl status nginx certbot.timer # both active
sudo tail -f /var/log/nginx/marketplaces.error.log
sudo apt update
sudo apt install nginx -y
sudo mkdir -p /var/www/dexarmarket/browser
```
---
Copy `nginx.conf` content to `/etc/nginx/sites-available/dexarmarket`:
```bash
sudo nano /etc/nginx/sites-available/dexarmarket
```
## 7. Known limits
Then enable it:
```bash
sudo ln -s /etc/nginx/sites-available/dexarmarket /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
```
- **`/api/` 502s until the backend runs.** Expected. nginx proxies to `127.0.0.1:8080`; nothing listens there yet.
- **No staging environment.** `main` goes straight to production. Adding one means a second server plus a `staging` branch trigger.
- **No smoke test beyond HTTP 200.** The verify step confirms nginx serves the shell, not that the app boots. A real check needs the E2E harness from Track Q.
- **Caching.** `index.html` is `no-store`; hashed assets are `immutable` for a year. A deploy therefore takes effect on the next page load, with no cache purge.
### Setup SSL (recommended)
```bash
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d dexarmarket.ru -d www.dexarmarket.ru
```
## Common Issues & Solutions
### ❌ 404 Error - Files Not Found
**Check 1: Verify files on server**
```bash
ls -la /var/www/dexarmarket/browser/
```
Should show: `index.html`, `chunk-*.js`, `assets/`, etc.
**If empty:**
```bash
# Re-upload files
scp -r dist/dexarmarket/browser/* user@your-server:/var/www/dexarmarket/browser/
```
**Check 2: Verify permissions**
```bash
namei -l /var/www/dexarmarket/browser/index.html
```
All directories need `x` (execute) permission.
**Fix permissions:**
```bash
sudo chown -R www-data:www-data /var/www/dexarmarket
sudo chmod -R 755 /var/www/dexarmarket
```
**Check 3: Test nginx config**
```bash
sudo nginx -t
```
Should say "syntax is ok" and "test is successful".
**Check 4: View nginx error log**
```bash
sudo tail -f /var/log/nginx/error.log
```
This shows the actual error!
### ❌ 502 Bad Gateway - API Issues
**This means the API backend is down or unreachable.**
**Check 1: Is API accessible?**
```bash
curl -v https://api.dexarmarket.ru:445/ping
```
**Check 2: Port 445 problem**
Port 445 is unusual for HTTPS and may be blocked by firewalls. Standard HTTPS uses port 443.
**Check 3: CORS issues**
The API must allow requests from `https://dexarmarket.ru`. Check API CORS configuration.
**Check 4: SSL certificate**
```bash
curl -k https://api.dexarmarket.ru:445/ping
```
If this works but without `-k` doesn't, SSL cert is invalid.
### ✅ Final Verification Checklist
On server, run all these:
```bash
# 1. Files exist
ls -la /var/www/dexarmarket/browser/index.html
# 2. Nginx config is valid
sudo nginx -t
# 3. Nginx is running
sudo systemctl status nginx
# 4. Site is enabled
ls -la /etc/nginx/sites-enabled/ | grep dexarmarket
# 5. Test API from server
curl -v https://api.dexarmarket.ru:445/ping
# 6. Check logs
sudo tail -20 /var/log/nginx/error.log
sudo tail -20 /var/log/nginx/access.log
```
### Debug Steps
If still having issues:
1. Check browser console (F12 → Console tab) - shows JavaScript errors
2. Check browser network tab (F12 → Network tab) - shows failed requests
3. Check exact error message in nginx logs
4. Test locally: `cd dist/dexarmarket/browser && python3 -m http.server 8000`

140
docs/IMPLEMENTATION.md Normal file
View File

@@ -0,0 +1,140 @@
# Dexar Market - Implementation Summary
## ✅ Completed Features
### 1. **Data Models** (`src/app/models/`)
- **Category Model**: Hierarchical category structure
- **Item Model**: Complete product data including photos/videos, pricing, reviews, Q&A
### 2. **Services** (`src/app/services/`)
- **API Service**: All endpoint integrations
- Health check (`/ping`)
- Categories (`/category`)
- Category items with pagination (`/category/:id`)
- Search with pagination (`/items`)
- Cart operations (GET, POST, DELETE)
- **Cart Service**: Reactive state management using Angular signals
- Add/remove items
- Real-time cart count
- Automatic total price calculation
### 3. **Pages** (`src/app/pages/`)
#### **Home Page** (`/`)
- Display all categories in grid layout
- Show subcategories
- Responsive category cards
#### **Category Page** (`/category/:id`)
- **Infinite Scroll**: Automatically loads more items on scroll
- Product grid with images, pricing, ratings
- Discount badges
- Stock status indicators
- Add to cart functionality
#### **Search Page** (`/search`)
- **Real-time search** with debounce (300ms)
- **Infinite Scroll** for results
- Same product display as category page
- Empty state handling
#### **Item Detail Page** (`/item/:id`)
- Photo/video gallery with thumbnails
- Full product information
- Pricing with discount display
- Reviews section with ratings
- Q&A section with voting counts (👍👎)
- Add to cart
#### **Cart Page** (`/cart`)
- List all cart items with details
- Remove individual items
- Clear entire cart
- Real-time total calculation
- Empty state with call-to-action
- Checkout button (placeholder)
### 4. **Components** (`src/app/components/`)
#### **Header Component**
- Sticky navigation
- Cart icon with badge showing item count
- Mobile-responsive hamburger menu
- Active route highlighting
### 5. **Routing & Configuration**
- Lazy-loaded routes for performance
- HTTP client configured
- All pages connected and navigable
### 6. **Responsive Design**
- Mobile-first approach
- Breakpoints at 768px and 968px
- Adaptive layouts for all screen sizes
- Touch-friendly interface
## 🎨 Design Features
- **Color Scheme**: Purple gradient theme (#667eea primary)
- **Smooth Animations**: Hover effects, transitions
- **Modern UI**: Card-based layouts, rounded corners
- **Custom Scrollbar**: Themed scrollbar styling
- **Loading States**: Spinners and skeleton states
- **Error Handling**: User-friendly error messages
## 📱 Performance Optimizations
1. **Infinite Scroll**: Loads 20 items at a time
2. **Lazy Loading**: Route-based code splitting
3. **Image Lazy Loading**: Native lazy loading for images
4. **Debounced Search**: Prevents excessive API calls
5. **Angular Signals**: Efficient reactivity
## 🔧 Technical Stack
- Angular 20 (standalone components)
- TypeScript
- RxJS for reactive programming
- SCSS for styling
- Angular Signals for state management
## 📦 API Integration
All endpoints from the provided documentation are integrated:
- ✅ GET /ping
- ✅ GET /category
- ✅ GET /category/:categoryID
- ✅ GET /items (search)
- ✅ GET /cart
- ✅ POST /cart
- ✅ DELETE /cart
## 🚀 How to Run
```bash
# Install dependencies (if needed)
npm install
# Start development server
ng serve
# Open browser
http://localhost:4200
```
## 📝 Notes
- **Item Detail Limitation**: Currently fetches items from cart for demo. In production, you may want to add a dedicated `/item/:id` endpoint or cache category results.
- **Checkout**: Placeholder button ready for payment integration
- **No Authentication**: As per requirements, no user management implemented
- **API Base URL**: Configured as `https://api.dexarmarket.ru`
## 🎯 Ready for Production
The application is production-ready with:
- Type-safe TypeScript
- Modular architecture
- Responsive design
- Error handling
- Performance optimizations
- Clean, maintainable code

146
docs/MULTI_BRAND.md Normal file
View File

@@ -0,0 +1,146 @@
# Multi-Brand Configuration
Этот проект поддерживает несколько брендов с разными темами и конфигурациями.
## Доступные бренды
### 1. Dexar Market (фиолетовый)
- **Цвета**: Фиолетовый/пурпурный (#667eea, #764ba2)
- **Домен**: dexarmarket.ru
- **Email**: info@dexarmarket.ru
### 2. novo Market (зеленый)
- **Цвета**: Зеленый (#10b981, #14b8a6)
- **Домен**: novomarket.ru (будет настроено)
- **Email**: info@novomarket.ru (будет настроено)
## Команды запуска
### Dexar Market (разработка)
```bash
ng serve
# или
ng serve --configuration=development
```
### novo Market (разработка)
```bash
ng serve --configuration=novo
```
### Сборка для продакшена
#### Dexar Market
```bash
ng build --configuration=production
```
Результат: `dist/dexarmarket/`
#### novo Market
```bash
ng build --configuration=novo-production
```
Результат: `dist/novomarket/`
## Структура файлов
```
src/
├── environments/
│ ├── environment.ts # Dexar Development
│ ├── environment.production.ts # Dexar Production
│ ├── environment.novo.ts # novo Development
│ └── environment.novo.production.ts # novo Production
├── styles/
│ └── themes/
│ ├── dexar.theme.scss # Dexar цвета (фиолетовый)
│ └── novo.theme.scss # novo цвета (зеленый)
```
## Что настраивается через Environment
В файлах environment можно настроить:
```typescript
{
brandName: 'Название бренда',
brandFullName: 'Полное название бренда',
theme: 'dexar' | 'novo',
apiUrl: 'URL API',
logo: 'Путь к логотипу',
contactEmail: 'Email контактов',
supportEmail: 'Email поддержки',
domain: 'Домен сайта',
telegram: 'Telegram канал',
phones: {
russia: 'Телефон в России',
armenia: 'Телефон в Армении'
}
}
```
## CSS Переменные
Темы используют CSS переменные, которые можно изменить:
```scss
:root {
--primary-color: #10b981; // Основной цвет
--primary-hover: #059669; // Hover эффект
--secondary-color: #14b8a6; // Вторичный цвет
--gradient-primary: linear-gradient(...);
--gradient-hero: linear-gradient(...);
// и другие...
}
```
## Обновление для нового бренда
### Что нужно обновить для novo Market:
1. ✅ **Environment файлы** - созданы
2. ✅ **Темы (SCSS)** - созданы (зеленые цвета)
3. ✅ **Angular.json конфигурации** - настроены
4. ⏳ **Логотипы и изображения** - добавить в `public/assets/images/`
5. ⏳ **Реквизиты компании** - обновить когда будут готовы
6. ⏳ **Домен и SSL** - настроить при деплое
7. ⏳ **API endpoint** - обновить когда будет готов
## Деплой
### Dexar Market
```bash
ng build --configuration=production
# Deploy dist/dexarmarket/ to dexarmarket.ru
```
### novo Market
```bash
ng build --configuration=novo-production
# Deploy dist/novomarket/ to novomarket.ru
```
## Отличия брендов
| Параметр | Dexar Market | novo Market |
|----------|--------------|-------------|
| Основной цвет | Фиолетовый (#667eea) | Зеленый (#10b981) |
| Название | Dexar Market | novo Market |
| Домен | dexarmarket.ru | novomarket.ru |
| Email | info@dexarmarket.ru | info@novomarket.ru |
| Telegram | @dexarmarket | @novomarket |
| Реквизиты | Текущие | Будут обновлены |
## Следующие шаги для novo Market
1. Добавить логотип novo Market (`public/assets/images/novo-logo.svg`)
2. Обновить реквизиты компании в правовых документах
3. Настроить API endpoint для novo
4. Настроить домен и SSL сертификаты
5. Обновить контактную информацию (телефоны, адреса)
## Примечания
- Оба бренда используют одну кодовую базу
- Все компоненты автоматически адаптируются под выбранный бренд
- Легко добавить новые бренды по той же схеме

58
docs/PACKAGE-EXTRACTION.md
View File

@@ -1,58 +0,0 @@
# @marketplaces/auth & @marketplaces/payment — build, version, release, infrastructure
See [ADR-0001](context/adrs/ADR-0001-extract-auth-and-payment-into-shared-marketplaces-packages.md) for why. This doc is the how. For *consuming* the packages (install, DI providers, exported API), see [PACKAGES-USAGE.md](PACKAGES-USAGE.md).
## Current state
Working end to end with no credentials. `marketplaces` has no local copy of either package and no `.npmrc` — it installs `@marketplaces/auth` directly over git. A fresh clone plus `npm install` builds and tests green on any machine or CI runner.
## 1. Source repo
[sources.vitanova.network/sdarbinyan/vitanovaPackages](https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git) — npm workspaces monorepo, `packages/auth` + `packages/payment`, source on `main`.
## 2. How releases work
npm cannot install a subdirectory of a git repo, so each package is published to its own **release branch** where the repo root *is* the package: `release/auth`, `release/payment`. Each contains only `package.json`, the built `dist/`, and a generated README.
```
"@marketplaces/auth": "git+https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git#release/auth"
```
This was chosen over a registry because it needs **nothing**: no npm registry, no token, no tunnel, no CI secret. Anonymous git read is the only requirement, which is what makes CI and fresh clones work unattended.
`release/*` branches are generated and force-pushed. Never commit to them by hand.
## 3. Versioning
[Changesets](https://github.com/changesets/changesets). A PR that changes a package adds a changeset file (`npx changeset` at the repo root — pick package, bump type, one-line description). `ci.yml` rejects PRs without one.
## 4. CI/CD (vitanovaPackages)
- **`ci.yml`** — on PRs and non-main pushes: install, build, test, require a changeset.
- **`release.yml`** — on push to `main`, two jobs:
- `release-branches` (matrix over `auth`/`payment`): builds each package and force-pushes its output to `release/<pkg>`. Skips cleanly when nothing changed.
- `version-pr`: opens/updates a "Version Packages" PR when unreleased changesets exist. Merging it bumps versions on `main`, which re-triggers the release.
Only the checkout token is needed — no secrets to configure.
Workflows use GitHub Actions syntax; Gitea/Forgejo Actions are compatible. Other CI needs translating (steps are: install, build, test, force-push a branch).
## 5. The Verdaccio registry (superseded, still running)
A private Verdaccio instance runs on the dev server: Docker container `verdaccio`, port 4873, config and storage at `/srv/marketplaces/verdaccio/`, registry user `marketplaces-ci`. It holds `@marketplaces/auth@0.1.0` and `@marketplaces/payment@0.1.0`.
**Nothing uses it.** It was the original plan, but it listens on `127.0.0.1:4873` and the server firewall allows only 80/443/SSH — so no CI runner and no developer could reach it without an SSH tunnel, which defeats the point. The git-release-branch approach (§2) replaced it.
Keep it or remove it; no code or workflow depends on it. To reach it manually:
```bash
ssh -L 4873:127.0.0.1:4873 seto@213.21.246.138
```
Making it the primary path again would need a reverse proxy through nginx plus TLS (no certificate exists on that box), or an open port carrying credentials over plain HTTP — neither is done, and neither is necessary now.
## 6. Migration status
**Auth: done.** `@marketplaces/auth` holds the real implementation — `telegram/` (live QR/session auth, customer + admin) and `ed25519/` (challenge/response admin auth, backend not shipped). Environment coupling was replaced with `AUTH_API_URL`/`TELEGRAM_BOT_USERNAME` injection tokens; `environment.production` became Angular's `isDevMode()`. `AdminPermissionsService` and `requireAdminPermission` stayed in `marketplaces` (`core/admin-auth/`) — they read this app's mock Users domain, not a portable auth concern. All ~30 call sites import from the package; the old in-app auth files are deleted. Build, boundary checks, and 103/103 tests pass.
**Payment: not started.** `core/finance`/`core/pricing` still live in `marketplaces`. `@marketplaces/payment` is published as an empty scaffold and is not a dependency of anything.

126
docs/PACKAGES-USAGE.md
View File

@@ -1,126 +0,0 @@
# Using `@marketplaces/auth` and `@marketplaces/payment`
How to install and consume the shared packages in `marketplaces` or any other project. For *why* they exist see [ADR-0001](context/adrs/ADR-0001-extract-auth-and-payment-into-shared-marketplaces-packages.md); for how they are built and released see [PACKAGE-EXTRACTION.md](PACKAGE-EXTRACTION.md).
## 1. Install
Nothing to set up. The packages are installed straight over git from release branches in [vitanovaPackages](https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git), where the repo root *is* the package:
```json
"@marketplaces/auth": "git+https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git#release/auth"
```
That is already in `marketplaces`' `package.json`, so a fresh clone plus `npm install` just works — **no npm registry, no auth token, no SSH tunnel, no CI secret.** Anonymous git read is the only requirement.
To add it to another project:
```bash
npm install "git+https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git#release/auth"
```
**On pinning:** a branch ref tracks the tip, so `npm install` can pick up a new build. That is deliberate while the package churns. For reproducible installs, replace `#release/auth` with a commit SHA. See [ADR-0001](context/adrs/ADR-0001-extract-auth-and-payment-into-shared-marketplaces-packages.md) on blast radius.
## 2. Required providers
`@marketplaces/auth` has no knowledge of any specific app's environment config. It reads two injection tokens, both provided by the consuming app in `app.config.ts`:
```ts
import { AUTH_API_URL, TELEGRAM_BOT_USERNAME } from '@marketplaces/auth';
import { environment } from '../environments/environment';
export const appConfig: ApplicationConfig = {
providers: [
{ provide: AUTH_API_URL, useValue: environment.authApiUrl },
{ provide: TELEGRAM_BOT_USERNAME, useValue: environment.telegramBot },
// ...
]
};
```
| Token | Required | Meaning |
|---|---|---|
| `AUTH_API_URL` | yes | Base URL of the auth backend, e.g. `https://api.example.com`. Both auth mechanisms build their endpoints from this. |
| `TELEGRAM_BOT_USERNAME` | no | Bot username for QR/deep-link login URLs. Falls back to a default if absent. |
Missing `AUTH_API_URL` produces `NG0201: No provider found for InjectionToken @marketplaces/auth AUTH_API_URL` at the first injection — including in unit tests, where any `TestBed` that constructs a component touching auth must provide it:
```ts
TestBed.configureTestingModule({
providers: [{ provide: AUTH_API_URL, useValue: 'https://test.local' }],
});
```
## 3. What is in the package
Two independent auth mechanisms. They deliberately share no state — a customer QR scan never authenticates an admin session or vice versa (distinct cookies, signals, guards, interceptors).
### `telegram/` — live today
Telegram QR/session auth against `{AUTH_API_URL}/users/sessions`. One backend endpoint set, used by both customer and admin login; only *storage* differs.
| Export | What it is |
|---|---|
| `AuthService` | Customer session. Signals: `session`, `status`, `isAuthenticated`, `showLoginDialog`, `displayName`. Methods: `checkSession()`, `createWebSession()`, `requestLogin()`, `hideLogin()`, `logout()`, `onTelegramLoginComplete()`, `getTelegramAppLoginUrl()`. Cookie `webSessionID`, `SameSite=Lax`. |
| `AdminAuthService` | Admin session. Same signal/method shape plus `getAdminToken()`/`setAdminTokens()`/`clearAdminTokens()` (reserved for when the backend issues admin JWTs) and `devBypassLogin()` (no-ops outside dev mode). Cookie `adminSessionID`, `SameSite=Strict`. |
| `TelegramSessionApiService` | Thin HTTP client + response normalization. Holds no state, writes no cookies. |
| `adminAuthGuard` | `CanActivateFn` — allows if the admin session is authenticated, otherwise opens the login dialog. |
| `adminAuthHeadersInterceptor` | Attaches `AdminWebSessionID` (and `Authorization: Bearer` when a token exists) to admin-gated paths only (`/admin/`, `/backoffice/`, `/builder/`, `/media/`). Never touches customer requests. |
| `AuthSession`, `WebSessionStart`, `AuthStatus`, `AdminAuthStatus` | Wire/state types. |
Typical usage:
```ts
import { AuthService, AdminAuthService, adminAuthGuard, adminAuthHeadersInterceptor } from '@marketplaces/auth';
// routes
{ path: 'backoffice', canActivate: [adminAuthGuard], loadComponent: ... }
// http
provideHttpClient(withInterceptors([adminAuthHeadersInterceptor, ...]))
// component
private readonly auth = inject(AuthService);
readonly isLoggedIn = this.auth.isAuthenticated; // signal
```
**Security note:** the Telegram session API has no concept of "admin." The frontend cannot distinguish an admin Telegram session from a regular one — it only decides *where to store* the result. Real admin authorization must be enforced server-side on every admin request. See [TRACK-S](backend/TRACK-S-SECURITY-RBAC-CONTRACT.md).
### `ed25519/` — prepared, backend not shipped
Challenge/response admin auth: `GET /api/admin/auth/challenge` → sign nonce with a device-local non-extractable Ed25519 key → `POST /api/admin/auth/verify` → JWT pair. Calling these today 404s/connection-errors, which surfaces as the `backend-unavailable` error screen. Nothing is mocked.
| Export | What it is |
|---|---|
| `AuthFacade` | The surface components should use. `isAuthenticated`, `status`, `role`, `loginPhase`, `lastError`; `login(redirectTo?)`, `logout(redirectTo?)`, `restoreSession()`, `can(permission)`. |
| `Ed25519AuthService` | Low-level flow orchestrator (exported under this name so it doesn't collide with the telegram `AuthService`). |
| `SessionService` | JWT/refresh pair + derived claims, auto-refresh before expiry. |
| `Ed25519KeypairService` | WebCrypto Ed25519 keypair in IndexedDB. Private key is non-extractable and never leaves the device. |
| `PermissionService` | Derives permissions from the JWT `role` claim. UI-only gate. |
| `JwtService` | Decode only, never verification — the frontend has no trusted key; signature checking is the backend's job on every request. |
| `Ed25519VerificationService` / `NoopEd25519VerificationService` | Abstract seam + fail-closed default binding. |
| `AdminRole`, `Permission`, `ROLE_PERMISSIONS`, `AuthChallenge`, `AuthTokenPair`, `JwtClaims`, `AuthError`, `AuthErrorCode`, … | Types and wire contracts. |
Bind the verification seam in `app.config.ts`:
```ts
{ provide: Ed25519VerificationService, useClass: NoopEd25519VerificationService },
```
## 4. What deliberately stayed in the app
`AdminPermissionsService` and `requireAdminPermission` live in `marketplaces` (`src/app/core/admin-auth/`), not in the package. They read this app's mock Users domain to derive a permission set — app-specific, not a portable auth concern. If another project needs permission gating it should use the package's `PermissionService` (JWT-claim-driven) instead.
## 5. `@marketplaces/payment`
Published at `0.1.0` but **scaffold only** — no implementation yet, nothing exported, and `marketplaces` does not depend on it. `core/finance` and `core/pricing` still live in the app. Payment business logic is server-side by design (see [Phase 1](backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) and [Phase 7](backend/PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md)); the eventual package is a thin client for FX/pricing/checkout gateways.
## 6. Making a change to a package
1. Clone [vitanovaPackages](https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git).
2. Edit under `packages/auth/src` (or `packages/payment/src`), export from `index.ts`.
3. `npx changeset` at the repo root — pick the package and bump type, write one line about the change.
4. Commit, push, open a PR to `main`. CI builds, tests, and rejects the PR if the changeset is missing.
5. On merge, CI rebuilds and force-pushes `release/auth` / `release/payment`, and opens a "Version Packages" PR if there are unreleased changesets.
6. In `marketplaces`, run `npm update @marketplaces/auth`, then the build + test suite before merging.
Never commit to a `release/*` branch — they are generated and force-pushed. Never edit `node_modules/@marketplaces/*` — overwritten on every install.

479
docs/PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md
View File

@@ -1,479 +0,0 @@
# Product Plan v3.1 — Delivery Plan (Phases → Sprints → Todos)
Companion to [PRODUCT-PLAN-v3.1-GAP-ANALYSIS.md](PRODUCT-PLAN-v3.1-GAP-ANALYSIS.md). Every gap identified there is assigned here exactly once. Wire contracts for every `[BE]`/`[BOTH]` phase and track below are written up in [docs/backend/](backend/README.md) — hand that directory to whoever builds the backend.
**No calendar dates.** The plan itself (§12) refuses invented dates and fixes *sequence + exit criteria* instead. This document does the same. Sprints are ordered units of work, not two-week promises. Sizes are relative: **S** / **M** / **L** / **XL**.
**Ownership tags:** `[FE]` this repo · `[BE]` backend/platform service · `[BOTH]` coordinated contract change · `[DEC]` decision, no code.
**Deviation from the plan's own order, and why:** the plan sequences P0-C (external ingestion) before P0-D (catalog integrity). We swap them. External order ingestion maps `externalSKU → internal offer` (§5.1), and `Offer` does not exist yet — ingestion has nothing to map onto until the Product/Offer split ships. Everything else follows the plan's ordering.
---
## Phase map
| Phase | Name | Plan ref | Gate |
|---|---|---|---|
| **0** | Unblock & seams | — | Decisions answered; every admin domain swappable |
| **1** | Money & payment truth | P0-A, §2.3 §3.3 §3.8 §7 | An order total is explainable from data |
| **2** | Orders canonical + notifications | P0-B, §2.8 §2.10 §3.5 | Paid order appears and notifies without refresh |
| **3** | Catalog integrity + fulfillment | P0-D, §2.1 §2.4 §3.6 | Any published offer is genuinely buyable and fulfillable |
| **4** | External order ingestion | P0-C, §5 §3.7 | External purchase lands in Orders, no duplicates |
| **🚦** | **PRODUCTION LAUNCH GATE** | §3 LAUNCH BLOCKERS, §13.2 | All P0 closed and evidenced |
| **5** | Seller Portal | P1-A, §2.2 | Seller runs own offers and orders in scoped UI |
| **6** | Server cart + checkout session | P1-B, §2.5 §2.6 | Client price never trusted; repeat-safe |
| **7** | Payments hardening + reconciliation | P1-C, §2.7 §7.3 | Internal vs provider matched, mismatches visible |
| **8** | Identity & messaging | §2.9 §3.4 §14 | VK/MAX/Telegram linked; bot collects delivery |
| **9** | Tenant registry, domains, releases | P2-A, §4.3 §8 | New marketplace launched with no hardcode |
| **10** | Tenant content modules (Gorbushka) | P2-B, §11 | Content tenant on same runtime/backoffice |
**Parallel tracks** (start early, run across phases): **A** Analytics pipeline · **S** Security/RBAC/audit · **P** Partner provisioning API (P1–P3 gate Phase 1) · **Q** QA & E2E · **N** API namespace migration · **Z** Pre-existing repo debt.
---
## Phase 0 — Unblock & seams
Nothing downstream can be honestly estimated until this closes. Two sprints: one is other people answering questions, one is work we can do today with no answers.
### Sprint 0.1 — Decisions `[DEC]`
**Answered 2026-08-17.** Kept as a record — the reasoning behind each answer still governs how later phases get built.
- [x] **Backend ownership — answered 2026-08-18.** A separate backend developer implements against `docs/backend/`. This repository's team owns the frontend and the contract set itself, which is why the contracts are the primary handoff artifact rather than a side deliverable.
- [x] **Unfreeze the payment chain — YES.** `BACKEND-API-REFERENCE.md §7`'s do-not-modify note no longer applies. Phases 1, 6, 7 are unblocked to proceed.
- [x] **External marketplaces — no fixed list.** User: connectors must onboard "our new ones, partners, new, etc." as they arrive — i.e. the platform's own future partner integrations, not a fixed enumeration of named third-party marketplaces to build against up front. **Consequence for Phase 4:** build the Sprint 4.1 connector framework generic/config-driven (auth, mapping, retry, dead-letter as pluggable per-connector config) so a new partner is an onboarding, not a code change. Sprint 4.2 ("one sprint per named marketplace") is retired as written — replaced by a generic "add connector" runbook, sized once the framework exists, not per-name up front.
- [x] **FX rate source — build our own, as a safety gate.** User: "not yet, lets handle from our side, if they dont" — no external provider is committed yet. Backend owns FX computation in-house as the authoritative source; the `source` field in the Phase 1 contract stays provider-agnostic and can point at an internal computed rate as legitimately as an external adapter. This *is* the "configured fallback" the contract doc's §3.2 already describes — now the default, not the fallback.
- [x] **§14 vs. email/phone OTP — VK ID first, then everything else.** User: "do all after vk." Delivery-plan Phase 8 sprint order changes: 8.3 (VK ID) now precedes 8.2 (OTP) — see Phase 8 below.
- [x] **Multi-seller orders — unified**, judgment call as instructed. One `Order` per checkout regardless of seller count, split into per-seller `Fulfillment` groups internally (matches §2.8's "canonical Order regardless of source" and §2.5's cart-level seller-grouping requirement without introducing parallel parent orders). Applies to Phase 3's `Offer` model, Phase 5's Seller Portal order view (scoped to that seller's fulfillment groups within the shared order), and closes the three-document disagreement flagged in Z16.
- [x] **"Fixed 5-second payment" claim — resolved as a non-issue.** User: "make polling 5 secs." Checked `config/constants.ts`: `PAYMENT_POLL_INTERVAL_MS` is already `5000`. This is a poll *cadence* against real provider status each tick, not an artificial fixed-delay-then-success — stays compliant with the plan's §3.2 prohibition. No code change needed; confirmed and left as-is.
- [x] **API namespace migration — adopt for new endpoints only, no forced migration.** User: unclear on the question, deferred to "what's recommended," noted "APIs are our domains" (i.e. we control the surface, lower urgency to force a big-bang rename). Recommendation taken: `docs/backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md` already specifies all-new endpoints under the `/api/v2/...` namespace family. Legacy endpoints (`/cart`, `/orders`, `/items`, etc.) stay as-is until a dedicated migration sprint is scheduled — not blocking Phase 1.
- [x] **Document version — v3.1 is canonical.** The source file's internal "3.0" version block is stale/wrong; all our docs treat v3.1 as authoritative going forward.
**Exit:** all nine answered in writing.
### Sprint 0.2 — Seams and type reconciliation `[FE]` — runs regardless of answers
- [ ] Add DI tokens to the 9 admin domains that have none: Orders, Products, Users, Transactions, Monitoring, Moderation (+ derived Customers, Analytics). **M** — hard prerequisite for every `[BE]` swap in Phases 1–7.
- [ ] Reconcile `AdminRole` — defined twice with unrelated shapes (auth string-union vs. Users-page display interface). **S**
- [ ] Reconcile the two `Category` types, both fed by the same `/category` response, both in use. **S**
- [ ] Resolve `SellerConfig` (bootstrap) vs. `Seller`/`SellerBranding` (domain) — pick one or document the mapping. Blocks Phase 5. **S**
- [ ] Build the feature-flag / capability-guard service an existing ADR already promises; migrate the hand-rolled `sellerManagement.enabled` check onto it. **S**
- [ ] Build the centralized error-handling layer (`core/error-handling/`, `core/interceptors/` are `.gitkeep`-only today): error-envelope interceptor + 429 handling. **M** `[BOTH]` — envelope shape needs backend agreement.
- [ ] Fix `toAuthErrorShape()` to read a body-level code, not HTTP status alone — the built "session expired" / "invalid signature" screens are currently dead UI. **S**
- [ ] Bind mock implementations to `PRODUCT_DATA_PROVIDER` and `CATEGORY_REPOSITORY`, or delete the dead mock branch. Today both silently ignore `useMockData`. **S**
**Exit:** any admin domain can be pointed at a real backend by swapping one provider.
---
## Phase 1 — Money & payment truth (P0-A)
Closes §3.3 and §3.8, and half of the §13.1 acceptance table. The single highest-value phase: it is what makes totals explainable to a bank.
### Sprint 1.1 — Money model `[BOTH]`
- [ ] `Money = { amountMinor: int, currency }` end to end. Kill float arithmetic in `CurrencyRatesService.convert()`. **L**
- [ ] Currency minor-units + rounding rules table (RUB/USD/EUR/AMD at minimum). **M**
- [ ] Delete browser-owned rates: remove `currencyRates.v1` from `localStorage` and the hardcoded `DEFAULT_RATES` fallbacks (`USD: 0.011`, `AMD: 4.3`). **S**
- [ ] Remove the admin-typed rate editor from Admin Settings once a real source exists. **S**
### Sprint 1.2 — FX quote + rate source `[BE]` + `[FE]`
- [ ] `FxQuote { base, quote, rate, source, observedAt, expiresAt, quoteId }` entity + endpoint. **M**
- [ ] Rate-source adapter behind an interface; concrete provider pluggable (§7.1). **M**
- [ ] Stale/outlier quote rules; checkout **blocks** or uses an explicitly configured fallback. **M**
- [ ] `PriceBook`: offer base currency + allowed display/checkout currencies per tenant. **M**
### Sprint 1.3 — Price snapshot + server-authoritative amount `[BOTH]` — needs the freeze lifted
- [ ] `PriceSnapshot { offerId, amount, currency, fxQuoteId, capturedAt }`, immutable. **L**
- [ ] Server computes and validates the charged amount. Stop trusting `CartPaymentRequest.amount` and the per-item `price[]` array from the browser. **L** — the plan's §2.5 headline requirement.
- [ ] Old orders never recalculated when a rate updates. **S**
- [ ] Backoffice "total formula" panel: lines × qty − discounts + delivery + fees, plus the FX quote used (§7.2). **M**
- [ ] `PriceHistory` on offer price and stock, with author/source (§2.1). **M**
### Sprint 1.4 — Payment timeline `[BE]` + `[FE]`
- [ ] Explicit state machines: `PaymentIntent` (created→pending→authorized/paid→failed/cancelled), `Payment` (received→confirmed→captured/settled→refunded), `Order` (pending_payment→paid→processing→fulfilled). **L**
- [ ] Persist `provider event id`, `provider timestamp`, `receivedAt`, `processedAt` per transition. **M**
- [ ] Webhook entrypoint with signature verification + idempotency (§2.7). **L**
- [ ] Idempotency keys on checkout, payment and order creation. Zero `idempot*` exists today. **M**
- [ ] Replace client-polled status signals with server truth; keep polling only as a UI fallback. **M**
- [ ] Keep the current honest behaviour: no artificial delay. Already compliant — protect it with a test. **S**
**Exit criteria (plan's own):** currency converts correctly; payment timeline reconstructable from provider events; every total explainable from `SKU/qty/delivery/discount/FX`.
---
## Phase 2 — Orders canonical + notifications (P0-B)
### Sprint 2.1 — Canonical order model `[BOTH]`
- [ ] `Order` header: `marketplaceId, source, customer, currency, subtotal, discounts, delivery, total, paymentStatus, orderStatus`. **L**
- [ ] `OrderLine` with `offerId, sellerId, skuSnapshot, titleSnapshot, qty, unitPriceMinor, lineTotalMinor, priceSnapshotId`. **M**
- [ ] `OrderEvent` timeline: created, paid, seller notified, accepted, fulfilled, cancelled, refunded (§2.8). Closes our own "Real order audit trail" TODO. **M**
- [ ] Real `AdminOrdersApiGateway` replacing the 24-row static seed with no create path. **L** `[BE]`
- [ ] Admin order actions: assign, resend notification, replay sync, cancel/refund by permission, comment, export. **M**
- [ ] `OrderContactSnapshot` — name/contacts frozen at order time, immune to later profile edits (§2.9). **S**
### Sprint 2.2 — Event bus + Notification Center `[BE]` + `[FE]`
- [ ] Platform event bus emitting `order.created`, `order.paid`, `payment.failed`, `webhook.error`, `stock.low`, `oversell`, `refund.requested/completed`, `external_order.imported`. **L**
- [ ] `Notification` entity: `unread/read`, `severity`, `marketplaceId`, entity type/id, **deep link**. **M**
- [ ] `DeliveryAttempt` log per external channel — a Telegram/email failure must never lose the internal notification (§2.10). **M**
- [ ] Backoffice Notifications section: unread queue, incidents, filter by marketplace and event type. Missing entirely from our nav today. **M**
- [ ] Repoint `AdminOrderWatcherService` from polling to the event stream. Feature is already built and inert — this is what switches it on. **S**
**Exit:** a paid order appears in backoffice without manual refresh, with deep link and seller/source.
---
## Phase 3 — Catalog integrity + fulfillment (P0-D)
Biggest structural change in the whole programme. Everything about multi-seller commerce hangs off it.
### Sprint 3.1 — Product / Offer split `[BOTH]`
- [ ] Introduce `Offer/Listing { id, marketplaceId, sellerId, variantId, sellerSku, priceMinor, currency, stockPolicy, status, publishedAt }`. **XL** — does not exist in any form today.
- [ ] Move price, stock, currency and status off `Product` onto `Offer`. **L**
- [ ] Formalise `Product` / `Variant` / `SKU` / `Category` (with `attributesSchema`, SEO) as content-only. **L**
- [ ] Unify the admin mock product domain with the live storefront `Item` domain — two unrelated shapes today. **L**
- [ ] Offer lookup in backoffice by internal SKU, seller SKU, product ID or external mapping (§2.1 "готово, когда"). **M**
### Sprint 3.2 — Lifecycle, import, inventory `[BOTH]`
- [ ] `draft → moderation → published → paused/archived` for both product and offer; wire the existing mock Moderation module to it. **M**
- [ ] Bulk import CSV/API: required-field validation, **error preview before apply**. Nothing exists (current "bulk" is Admin Categories edit actions only). **L**
- [ ] `InventoryRecord`: `available` / `reserved` / `sold` counted separately. **L**
- [ ] Reservations at checkout or pre-payment per strategy, with TTL. **M**
- [ ] Idempotent upsert for seller feed stock updates; repeat webhook must not double-decrement. **M**
- [ ] Oversell → dedicated incident queue, never silently hidden (§2.4). **M**
### Sprint 3.3 — Fulfillment + executability `[BOTH]`
- [ ] `Fulfillment` entity: manual / warehouse / pickup / digital; `status, assignedTo, issuedAt/shippedAt`, evidence where applicable. One `fulfil*` reference exists in the entire codebase today. **L**
- [ ] Publish-time executability validation — an offer that cannot actually be fulfilled cannot be published (§3.6). **M**
- [ ] Explicit test proving there is **no** inspector-detection branch anywhere: same production flow for every buyer (§3.6, §10.2, §13.2 last item). **S**
- [ ] Multi-seller cart grouping by seller and fulfillment rules — currently undefined behaviour (§2.5). **M** — **Sprint 0.1 decision (2026-08-17): unified.** One `Order` per checkout regardless of seller count; group lines into per-seller `Fulfillment` entries internally, no parallel parent orders.
**Exit:** any published, available offer really passes order → fulfillment.
---
## Phase 4 — External order ingestion (P0-C)
Zero percent built today. **Sprint 0.1 decision (2026-08-17): no fixed marketplace list** — connectors onboard "our new ones, partners, new, etc." as they arrive, not a pre-named enumeration. Sprint 4.2 is retired as originally written ("one sprint per named marketplace") and replaced with a generic onboarding runbook — Sprint 4.1's framework is now the deliverable that matters, sized to be genuinely config-driven rather than one-off per provider.
### Sprint 4.1 — Connector framework `[BE]`
- [ ] `Connector` + `ConnectorCredentialRef` in secret storage, scoped per marketplace/seller. **M**
- [ ] Inbound: webhook where the provider supports it, polling fallback with cursor/since. **L**
- [ ] `RawExternalEvent` — persist the raw payload before parsing, for traceability. **S**
- [ ] Normalizer: external payload → canonical `ExternalOrderEvent` → internal `Order`. **L**
- [ ] `ExternalOrderMapping`: `externalSellerId / externalProductId / externalSKU → internal seller/offer`. **L**
- [ ] Idempotency on `source + externalOrderId/eventId`; a repeat must not create a duplicate order. **M**
- [ ] Exponential retry, `DeadLetter`, manual replay from backoffice. **M**
- [ ] **Unmatched queue** for events with no SKU mapping. **M**
- [ ] Status/fulfillment push back to the external marketplace where its API allows (§5.2 step 8). **M**
- [ ] **Config-driven adapter contract** — a new partner connector is authored as configuration (auth type, field mapping, rate limits) against the Sprint 4.1 framework, not a bespoke integration each time. **L** — this is what "no fixed list" requires structurally.
### Sprint 4.2 — Connector onboarding runbook `[BE]` — repeats per new partner, no longer named up front
- [ ] Generic onboarding checklist against the Sprint 4.1 framework: auth, endpoint mapping, rate limits, sandbox verification. **M each**, sized down from **L** now that the framework absorbs the bespoke work.
### Sprint 4.3 — Connector observability `[FE]` + `[BE]`
- [ ] Backoffice **Integrations** section (missing from our nav): connectors, payment providers, FX sources, messaging. **M**
- [ ] Per-connector health: last success, lag, errors, rate limit, backlog, unmatched mapping. **M**
- [ ] Trace id on every connector error, visible in backoffice (§5.2 SLA). **S**
- [ ] SLA instrumentation: webhook 99% under 60s; polling ≤ interval + 60s; **0** duplicate orders. **M**
**Exit:** an external purchase creates/updates an order automatically, never duplicates, and notifies the responsible manager.
---
## 🚦 PRODUCTION LAUNCH GATE
Per §3 "LAUNCH BLOCKERS" and the §13.2 checklist. Do not schedule a launch before every line is green **and evidenced by a test, not an assertion**.
- [ ] All P0 closed and confirmed by tests
- [ ] Production analytics collecting real events (Track A)
- [ ] Catalog contains only genuinely available/publishable offers
- [ ] Seller permissions verified (Phase 5 or enforced-empty)
- [ ] cart → checkout → payment → order end-to-end smoke passed
- [ ] Webhook signatures, idempotency, retry verified
- [ ] External connector reconciliation passed
- [ ] FX source live, stale-quote policy verified
- [ ] Notification delivery + fallback verified
- [ ] Refund flow + reconciliation smoke passed
- [ ] Domains/SSL/health checks green (Phase 9)
- [ ] Backup/rollback exists
- [ ] Audit enabled (Track S)
- [ ] **No branch anywhere alters commerce flow based on who the buyer appears to be**
---
## Phase 5 — Seller Portal (P1-A)
A placeholder page with a `false` flag and zero backend bytes today. Note: the enabled code path has **never been exercised even once** — every prior verification ran with the flag at its real value.
### Sprint 5.1 — Seller foundation `[BOTH]`
- [ ] `SellerOrganization`, `SellerUser`, `SellerMarketplaceMembership`, `SellerIntegration`. **L**
- [ ] Onboarding: organisation, credentials/profile, contacts, marketplace applications, moderation status. **L**
- [ ] Backoffice **Sellers** section (missing from nav): organisations, applications, roles, status, listings, integration health. **L**
### Sprint 5.2 — Seller working surfaces `[FE]` + `[BE]`
- [ ] Catalog: create/edit products & offers, media, attributes, submit for moderation, bulk import. **L**
- [ ] Prices & Stock: mass edit, API/feed sync, change history, sync errors. **L**
- [ ] Orders: new, confirm, pick/issue/ship, cancel, return, SLA, comments. Per the unified-orders decision (Sprint 0.1), this view is scoped to *this seller's* `Fulfillment` group within each shared `Order`, not a separate seller-owned order. **L**
- [ ] Finance: accruals, commissions, refunds, settlement/payout register, report export. **L**
- [ ] Team: `SELLER_OWNER`, `SELLER_CATALOG_MANAGER`, `SELLER_ORDER_MANAGER`, `SELLER_FINANCE_VIEWER`, `SELLER_VIEWER`. **M**
- [ ] Integrations: API credentials, webhook/feed status, external SKU mapping, sync logs. **M**
### Sprint 5.3 — Seller isolation `[BE]` + `[Q]`
- [ ] A seller cannot see another seller's products, orders, customers, finance or API keys — enforced backend-side, tested. **M**
- [ ] Bank/payment detail changes: step-up auth + audit event + approval when maker/checker is on. **M**
- [ ] Seller staff permissions verified backend-side regardless of UI visibility. **M**
- [ ] First-ever fixture test of the seller-management enabled state. **S**
---
## Phase 6 — Server cart + checkout session (P1-B)
Partly pulled forward into Sprint 1.3 (server-authoritative amount). This phase completes the move.
### Sprint 6.1 — Server cart `[BOTH]`
- [ ] `Cart` / `CartLine` server-side, keyed on `offerId`. Replaces `localStorage` + Telegram CloudStorage. **L**
- [ ] Idempotent add/update/remove; quantity validated against stock and seller rules. **M**
- [ ] Price-refresh: cart surfaces price changes before checkout and requires explicit confirmation when the total moved. **M**
- [ ] Guest cart via session token; authenticated cart bound to customer account. **M**
- [ ] Expiration: inactive carts cleared, reservations released on TTL. **S**
### Sprint 6.2 — Checkout session `[BOTH]`
- [ ] `CheckoutSession` entity. `features/website/checkout/` is an empty directory today; checkout lives in a 751-line cart popup. **XL**
- [ ] Server re-validates offers and stock at checkout start. **M**
- [ ] Contact requirements enforced by tenant policy: email and/or phone verifiable (§2.6 step 4). **M**
- [ ] Clear total breakdown shown to the customer. **M**
- [ ] `PaymentIntent` via provider adapter; repeat click must not create a second intent. **M**
- [ ] Guest-checkout on/off per tenant policy (§6.2). **S**
- [ ] `DeliveryOption` entity. **M**
---
## Phase 7 — Payments hardening + reconciliation (P1-C)
### Sprint 7.1 — Refunds `[BOTH]`
- [ ] `Refund` as a first-class operation with reason, actor and order-line linkage. `requestRefund(id)` is a mock method today. **L**
- [ ] Partial refunds; `refunded / partially_refunded` states. **M**
### Sprint 7.2 — Reconciliation `[BE]` + `[FE]`
- [ ] `ReconciliationRecord`; match on `providerPaymentId` / merchant reference / amount+currency fallback (§7.3). **L** — zero `reconcil*` in the codebase today.
- [ ] Classify: unmatched, duplicate, amount mismatch, status mismatch. **M**
- [ ] Backoffice **Payments & Finance** section (missing from nav): payments, refunds, reconciliation queue, unmatched events, settlements. **L**
- [ ] Controlled resolution with full audit trail. **M**
- [ ] Settlements / payout register. **L** — zero `settlement*` today.
### Sprint 7.3 — Provider breadth `[DEC]` + `[BOTH]`
- [ ] Decide additional providers beyond the current QR/card flow (wallets, BNPL) — open business question. **DEC**
- [ ] Provider adapter interface so a new provider is a plug-in, not a rewrite. **M**
---
## Phase 8 — Identity & messaging (§2.9, §3.4, §14)
**Sprint 0.1 decision (2026-08-17): VK ID first, then everything else** ("do all after vk"). Order below is resequenced accordingly — VK ID moved ahead of OTP.
### Sprint 8.1 — Customer identity core `[BOTH]`
- [ ] `Customer`, `ExternalIdentity`, `ContactMethod`, `Verification`, `Consent`. **L**
- [ ] Telegram demoted from sole identity to one provider among several. **M**
- [ ] `emailVerifiedAt` / `phoneVerifiedAt` / `telegramLinkedAt`. **S**
- [ ] Backoffice **Customers** on real data: profiles, verified contacts, orders, consent. **M**
- [ ] Sensitive profile changes logged. **S**
### Sprint 8.2 — VK ID `[BOTH]` — new in v3.1, now first per Sprint 0.1
- [ ] OAuth 2.1/PKCE completed **backend-side**; link external identity to `Customer`. **L**
- [ ] VK ID as the primary storefront social login. **M**
- [ ] Repeat login must never create a duplicate customer. **M**
- [ ] Identity-conflict handling → controlled resolution, never overwrite an existing binding (§14.3). **M**
### Sprint 8.3 — Email/phone OTP `[BOTH]` — after VK ID
- [ ] Implement the approved [email/phone login spec](superpowers/specs/2026-08-15-email-phone-login-design.md). **L**
- [ ] Position it as recovery/fallback per v3.1 §14, not as the primary path. **S**
### Sprint 8.4 — MAX + Telegram bot channels `[BOTH]` — new in v3.1
- [ ] `ContactChannel`, `BotConversationBinding`, `MessagingConsent`. **L**
- [ ] MAX bot-assisted linking: one-time code, TTL, single-use, bound to marketplace + browser session. **L**
- [ ] Provider secrets never reach the frontend; all bot updates handled idempotently. **M**
- [ ] Bot adapters (VK / MAX / Telegram) normalised into one `MessagingEvent` keyed to `orderId`. **L**
### Sprint 8.5 — Notification Orchestrator + delivery conversation `[BE]` — new in v3.1
- [ ] Orchestrator routes `order.paid` to the customer's chosen channel; the backoffice notification always fires regardless. **L**
- [ ] Channel choice in checkout ("where should we send confirmation?"), recorded in `OrderContactSnapshot`; linking flow must not lose the cart or checkout session. **M**
- [ ] Delivery Conversation State Machine: `not_started → awaiting_customer → details_received → manager_assigned/auto_confirmed → shipment_planned → completed`. **L**
- [ ] Bot collects city/address/recipient/phone/time window/comment; backend validates and snapshots into the order. **L**
- [ ] **The bot must never change financial statuses** — delivery fields only, via Delivery Service. **M**
- [ ] Follow-up rules per tenant; after N attempts hand off to a manager, no infinite spam. **M**
- [ ] Manager handoff view: message history, current conversation state, accept handoff. **M**
- [ ] Messenger unavailability creates a `DeliveryAttempt` error and triggers fallback — never blocks the order. **M**
---
## Phase 9 — Tenant registry, domains, releases (P2-A)
### Sprint 9.1 — Marketplace Registry `[BOTH]`
- [ ] `Marketplace`, `MarketplaceDomain`, `MarketplaceFeatureSet`, `MarketplaceRevision`. **L**
- [ ] Backoffice **Marketplaces** section (missing from nav): registry, type, status, domains, currencies, feature set, responsible manager. **L**
- [ ] Onboarding wizard, all 8 steps of §4.3 (card → feature set → domains → design → roles → integrations → staging + smoke → production launch). **XL**
- [ ] Lifecycle state machine `draft → configured → content_ready → domains_planned → staging_live → qa_passed → production_ready → live → paused/archived`, **showing which blocker prevents the next transition**. **L**
- [ ] Marketplace dashboard (§4.2): GMV, paid orders, conversion, payment failure rate, orders needing action, seller moderation queue, low stock, unmatched events, integration health, domain/SSL/release status. **L**
- [ ] Re-scope the [super-admin Phase 1 design](superpowers/specs/superuser.md) against this — it overlaps registry and audit. **M**
- [ ] Consolidate `MarketplaceRef` vs. `TenantConfig` if a third marketplace-shaped type appears. **S**
### Sprint 9.2 — Domain automation `[BE]`
- [ ] Hostinger DNS integration, all 7 endpoints from §8.2. Zero references exist today. **L**
- [ ] Read current zone → snapshot/rollback payload → build and validate plan → apply only after production approval. **L**
- [ ] **Never touch MX/SPF/DKIM/DMARC/CAA** without a separate task. **S**
- [ ] Propagation, SSL and health verification; mark domain active only after checks pass. **M**
- [ ] Backoffice **Domains & Releases** section (missing from nav). **M**
### Sprint 9.3 — Publish model `[BOTH]`
- [ ] `draft → validation → preview → publish` with immutable published revisions; rollback creates a new revision (§8.3). **L**
- [ ] Real builder persistence — today `apiEndpoints.builder` is an empty placeholder and "publish" only promotes a `localStorage` signal. **L**
- [ ] CMS/static pages get a real backend write path (currently in-memory bootstrap only). **L**
- [ ] Enforce that orders/payments/inventory ledger are **not** part of a content revision and never roll back with the storefront. **S**
- [ ] Tenant resolution hardening: verified Host server-side, unknown Host → 404 with **no fallback tenant** (§6.1). **M**
---
## Phase 10 — Tenant content modules (P2-B, Gorbushka)
Only after Commerce Core is real. The plan is explicit that Gorbushka does not define the architecture.
### Sprint 10.1 — Directory content entities `[BOTH]`
- [ ] `Shop`, `ShopCategory`, `Service`, `Floor`, `SchemePin`, `RentListing`, `News/Promo`, `StaticPage`, `Lead`, `MallSettings`. Only static pages exist today. **XL**
- [ ] Every entity carries `marketplaceId`, audit, and publish/preview flow. **M**
- [ ] Mall scheme / floors / pins UI. **L**
- [ ] Rent listings + lead capture. **M**
### Sprint 10.2 — Gorbushka tenant config `[FE]`
- [ ] Feature set per §11.1: CMS, shops, services, scheme, rent, news, SEO/media/domains **on**; catalog / seller portal / commerce **platform-ready but off**. **M**
- [ ] Prove commerce can be switched on later without touching backend or storefront code. **M**
---
## Parallel tracks
### Track A — Analytics pipeline (P1-D, §3.1 §6.3)
**Start at Phase 1, not last.** Longest lead time in the programme, and it is a P0 in the plan's own §3. There is no tracking infrastructure at all today — this is not a missing endpoint.
- [ ] **A1** Server-side event logging spine. **XL** `[BE]`
- [ ] **A2** Traffic events: `session_started`, `page_view`, source/utm/referrer, unique users/sessions. **M**
- [ ] **A3** Catalog events: `search`, `category_view`, `product_view`, `seller_view`. **M**
- [ ] **A4** Commerce events: `add_to_cart`, `cart_view`, `checkout_started`, `payment_started`, `payment_success/failed`, `order_created`. **M**
- [ ] **A5** Operations metrics: `order_paid_to_notification` latency, fulfillment time, connector lag, payment webhook lag. **M**
- [ ] **A6** Quality metrics: frontend/backend errors, checkout validation failures, FX stale-rate blocks. **M**
- [ ] **A7** Real funnel dashboard in backoffice, replacing the mock-composed Analytics facade. **L**
- [ ] **A8** **Synthetic traffic technically separated** from production analytics — staging/test only, never presented as real visits (§3.1, §6.3). **M**
- [ ] **A9** Real product view counts — the shipped "Views" column always renders `0`. Either bridge to the live storefront `Item.visits` or serve it from the real Products backend. **S**
- [ ] **A10** Post-launch monitoring set (§13.3): checkout conversion, payment success/failure, webhook lag, order-notification lag, connector lag, FX quote age, unmatched reconciliation, stuck fulfillment. **L**
- [ ] **A11** Trending search terms endpoint — `loadTrending()` is a stub returning `of(null)`. **S**
### Track S — Security, RBAC, audit (§4.4, §10)
**Gate on Phase 5 and on the launch gate.** Today the role model is decorative: types exist, nothing gates any button, page or action. Anyone who authenticates has full access.
- [ ] **S1** Enforce RBAC backend-side with tenant scope on every request. **L**
- [ ] **S2** Implement the 17 roles across 3 scopes (5 platform / 7 marketplace / 5 seller). **L**
- [ ] **S3** Frontend permission guards on routes and actions — currently zero. **M**
- [ ] **S4** Audit log covering permissions, seller changes, catalog moderation, price, payment/refund, manual order actions, integrations, production launch. `audit` appears only as mock display fields today. **L**
- [ ] **S5** Backoffice **Audit & Security** section (missing from nav): role changes, sensitive actions, login/security events, exports. **M**
- [ ] **S6** Step-up authentication for sensitive financial actions. **M**
- [ ] **S7** Rate limits and abuse controls on storefront/auth/provider endpoints; client-side 429 handling (zero today). **M**
- [ ] **S8** Secret storage for provider/connector credentials, scoped per marketplace/seller. **M**
- [ ] **S9** PII minimisation: store only necessary customer data, restrict access and export. **M**
- [ ] **S10** Ed25519 admin auth backend — wired client-side, 404s today. Decide: build it, or drop it for the plan's conventional RBAC. **DEC** + **L**
- [ ] **S11** HttpOnly session cookie (existing frontend-blocked TODO). **M**
### Track P — Partner provisioning API (added 2026-08-18)
Inbound partner API for programmatic merchant-hierarchy management. Contract: [PARTNER-PROVISIONING-API-CONTRACT.md](backend/PARTNER-PROVISIONING-API-CONTRACT.md). Decision: [ADR-0003](context/adrs/ADR-0003-generic-partner-provisioning-api.md).
**P1–P3 gate Phase 1.** They change the payments and tenant schemas, so they must land before Phase 1 is implemented — retrofitting a routing dimension onto a populated payments table costs far more than carrying it from the first row. P4 onward can run any time after.
- [ ] **P1** Add `RoutingContext` to `CheckoutSession`/`PaymentIntent`/`Payment` ([Phase 1 §6.5](backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md)) and to `Refund`/`ReconciliationRecord` ([Phase 7](backend/PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md)). Frozen at checkout-session creation, immutable after. **M**
- [ ] **P2** Add `Company` and `Project` above `Marketplace`; `Marketplace` gains `companyId`/`projectId`/`externalReference` ([Phase 9 §1](backend/PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md)). **M**
- [ ] **P3** Add `PaymentPoint` (one payment method per marketplace; `qr` and `card` both ship today) and backfill existing marketplaces per [Phase 9 §1.2](backend/PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md). **M**
- [ ] **P4** Provisioning endpoints: create/read/status/disable for project, store, payment point, with cascading disable. **L**
- [ ] **P5** Idempotency-Key handling: replay on identical body, `409` on same key + different body, in-flight collision, 24h retention. **M**
- [ ] **P6** Partner credentials: public-key registration, node-scoped authority, signed-request verification, rotation with overlap, immediate revoke ([Track S §4.1](backend/TRACK-S-SECURITY-RBAC-CONTRACT.md)). **L**
- [ ] **P7** Read surfaces: full-hierarchy fetch, `externalReference` lookup, partner-scoped audit query. **M**
- [ ] **P8** `PartnerProfile` config: required levels, level aliases, routing field names, rate tier, rotation window. Onboarding a partner must be a config row, not a deployment. **M**
- [ ] **P9** TEST/LIVE partition: disjoint credentials, disjoint ids, `403` on cross-environment access. **M**
- [ ] **P10** Partner OpenAPI spec generated from the implementation, plus documented error codes and published rate limits. **M**
### Track Q — QA & E2E (§13)
The plan's entire Definition of Done is end-to-end. We have **zero** E2E tests and ~32% statement / ~19% branch coverage across 11 spec files.
- [ ] **Q1** Stand up an E2E harness (Playwright or equivalent) — none exists. **L**
- [ ] **Q2** Solve automated admin login; several past "verified live" claims were code-inspection only because `/edit` and `/backoffice` need Telegram login. **M**
- [ ] **Q3** E2E: full §13.1 acceptance path — seller → catalog → storefront → cart → checkout → payment → order → notification → fulfillment. **XL**
- [ ] **Q4** E2E: currency switch recalculates by FX quote — explicitly, `160 RUB` must not become `160 USD/AMD`. **M**
- [ ] **Q5** E2E: repeat webhook and double-click create exactly one order. **M**
- [ ] **Q6** E2E: external marketplace purchase imports and notifies. **M**
- [ ] **Q7** Facade tests for cart/checkout, moderation, Orders, Products, Users, Transactions, Monitoring — the domains about to get real backends carry the most regression risk with the least coverage. **L**
- [ ] **Q8** Regression pattern for reactive flag/config reads that must track `bootstrapRevision()` — this bug class already bit us once and was invisible until specifically hunted. **S**
- [ ] **Q9** Set a justified coverage floor and a CI gate. Deliberately unset today. **M**
- [ ] **Q10** One real screen-reader pass (NVDA/VoiceOver). Never performed on this codebase — every accessibility claim to date is automated tree inspection only. **M**
### Track N — API namespace migration (§9.3)
Cheapest now, more expensive every phase. Decision in Sprint 0.1.
- [ ] **N1** Adopt `/api/v2/storefront/*`, `/api/admin/v2/*`, `/api/seller/v1/*`, `/api/identity/v1/*`, `/api/providers/v1/*`, `/api/integrations/v1/*`. **L** `[BOTH]`
- [ ] **N2** Migrate today's flat unversioned endpoints (`/cart`, `/orders`, `/items`, `/category`, `/searchitems`) plus the separate `qrApiUrl` host. **L**
- [ ] **N3** Agree the structured error envelope; today no interceptor reads error bodies at all. **M** (implementation lands in Sprint 0.2)
### Track Z — Pre-existing repo debt
Not in the plan, but real. Fold into whichever phase touches the same surface.
- [ ] **Z1** Dark-mode selector does nothing — nothing reads `data-theme-mode`. **S**
- [ ] **Z2** "Site Layout" selector has no effect — `layout.type` is edited but never read. **S**
- [ ] **Z3** Footer "Contacts" link has no content behind it. **S**
- [ ] **Z4** `SeoService.setItemMeta()` exists but is **never called** — product pages ship only site-wide meta. **S**
- [ ] **Z5** `og:locale` hardcoded to `ru_RU` regardless of active locale. **S**
- [ ] **Z6** No JSON-LD structured data, no sitemap generation. **M**
- [ ] **Z7** Hardcoded Russian payment-description fallback (`'Покупка на Маркетплейсе'`) in a multi-tenant product. **S**
- [ ] **Z8** Brand colours fail WCAG AA — `--border-color` at 1.24–1.42:1 against a 3:1 requirement; status colours fail 4.5:1 as text. **Needs theme-owner sign-off, not just a code fix.** **M**
- [ ] **Z9** Literal hex `#cdd6d5` in `stars.component.scss:10` with no token behind it. **S**
- [ ] **Z10** Two large lazy chunks unaddressed: `project-editor` (~1.0 MB), `catalog-container` (~330–375 kB). Profile under real backend latency, not instant mock responses. **M**
- [ ] **Z11** `navigation.header` is editable in the builder with zero runtime consumer — needs a product decision, not a wiring fix. **DEC**
- [ ] **Z12** `catalog.navigationMode` renders a deliberate placeholder; the mega-menu / carousel / left-nav variants it implies do not exist. **DEC**
- [ ] **Z13** `sellerId` typed as bare `string` instead of the `UUID` alias used elsewhere. **S**
- [ ] **Z14** No shared breadcrumb component; the only breadcrumb logic is a local signal in the catalog container. **S**
- [ ] **Z15** Duplicate search models under two module paths. **S**
- [ ] **Z16** Consolidate the eight cross-linked Seller Management documents onto the now-resolved decision (unified orders, Sprint 0.1, 2026-08-17) — at least three independently restated the question before it was answered. Do this **before** Phase 5 starts. **M**
- [ ] **Z17** Angular 22 upgrade — researched, not started; needs a dependency fix and a Node bump. **Its own dedicated session, never bundled with feature work.** **M**
---
## Critical path
```
Sprint 0.1 (decisions)
└─> Sprint 0.2 (seams)
└─> Phase 1 (money truth) ──────────────┐
└─> Phase 2 (orders + notif) │
└─> Phase 3 (offer split) │
└─> Phase 4 (external ingestion)
└─> 🚦 LAUNCH GATE
Track A (analytics) ── starts at Phase 1, gates the launch ──┘
Track S (RBAC/audit) ── starts at Phase 2, gates the launch ──┘
Track Q (E2E) ── starts at Phase 1, evidences the gate ┘
```
Phases 5–10 all sit behind the launch gate and can be resequenced by business priority. Phases 1–4 cannot.
**Single hardest dependency:** Phase 1 Sprint 1.3 needs the payment chain unfrozen. If that answer is "no", the programme stops at Sprint 0.2 and the plan's P0s cannot be delivered — that outcome should go back to them in writing, not be worked around.

279
docs/PRODUCT-PLAN-v3.1-GAP-ANALYSIS.md
View File

@@ -1,279 +0,0 @@
# Product Plan v3.1 — What They Want vs. What We Have
**Source:** `Marketplaces-Platform-Product-Plan-v3.1.pdf` (27 pages, RU). Version block inside still reads `3.0 / 17 августа 2026` — the filename says v3.1. Section 14 is the v3.1 addition (appended after the document's own conclusion).
**Our side, as verified in this repo:** Angular frontend only (426 `.ts` files). Sources for "what we have": [BACKEND-API-REFERENCE.md](../BACKEND-API-REFERENCE.md), [GAPS-AND-IMPROVEMENTS.md](../GAPS-AND-IMPROVEMENTS.md), and direct source inspection.
---
## 1. What they are actually asking for
One sentence: **stop building storefronts, build a platform** — a single multi-tenant commerce core where launching a new marketplace is a configuration act, not an engineering project.
Their own acceptance bar (§"ГЛАВНЫЙ КРИТЕРИЙ" and §13):
> A real product walks the whole path: seller → catalog → storefront → cart → checkout → payment → order → notification → fulfillment → reconciliation.
Three things the document is really about, under the product language:
1. **They do not trust our numbers.** Traffic counters, payment timings, order totals and currency amounts are all called out as unexplainable. §10.2 says it outright: don't fix appearance, fix the data.
2. **They suspect demo behaviour in production.** "No fixed 5-second payment", "no synthetic traffic in production analytics", "no special branch for banks/inspectors" (§3.2, §3.1, §3.6, §10.2, and again in the launch checklist). This is an audit/compliance posture, not a feature request — a bank or NSPK is checking this platform.
3. **Commerce Core is no longer optional.** In v3.0 language, Catalog/Seller Portal/Cart/Checkout/Payments/Orders stopped being "a possible extension" and became mandatory platform modules. Gorbushka is demoted to "one tenant scenario" (§11) — it does not define the architecture.
**Launch blockers they define (§3, "LAUNCH BLOCKERS"):** all P0s — money/FX, payment timeline, notifications, external order ingestion, price traceability, guaranteed fulfillability of published offers.
---
## 2. What is new in v3.1 vs v3.0
Everything in **§14 "Customer Identity и коммуникация после покупки"** (pages 26–27). Nothing else in the document is marked as changed.
| New in v3.1 | Detail | Our state |
|---|---|---|
| **VK ID as primary social login** | Backend completes OAuth 2.1/PKCE, links external identity to `Customer` | Zero. No `vk` reference anywhere in source; one `oauth` reference total. |
| **MAX messenger bot** | Bot-assisted account linking via one-time code; official MAX Bot API | Zero. |
| **Telegram demoted** | Kept, but as *one* identity provider among several | Today Telegram is the **only** login for both customers and admins. |
| **Notification Orchestrator** | Routes `order.paid` to the customer's chosen channel; backoffice notification always fires even if the messenger is down | Zero. |
| **Delivery Conversation State Machine** | `not_started → awaiting_customer → details_received → manager_assigned/auto_confirmed → shipment_planned → completed`, bot collects delivery details, manager handoff | Zero. |
| **Channel choice in checkout** | "Where should we send confirmation?" — VK / MAX / Telegram / email-SMS fallback, recorded in `OrderContactSnapshot` | Zero. |
| **`ExternalIdentity` / `ContactChannel` / `BotConversationBinding` / `MessagingConsent`** | Four new entities | Zero. |
**Manager note:** §14 partially collides with our approved [email/phone OTP login spec](superpowers/specs/2026-08-15-email-phone-login-design.md). v3.1 keeps email/phone but reduces them to *recovery/fallback* when a messenger is unavailable. Our in-flight work is still valid, but its priority drops below VK ID. Needs a call before that spec is implemented.
---
## 3. The differences — detailed
Legend: ✅ have · 🟡 partial / mock only · ❌ missing · ⚠️ conflicts with something we already decided.
### 3.1 Platform components (§1.1) — 8 named components, we have 2
| Plan component | Our state |
|---|---|
| Storefront Runtime | ✅ Bootstrap-driven, tenant-configured, no per-project fork. This is our strongest match to the plan. |
| Platform Backoffice | 🟡 14 admin modules exist, but only **Categories** has a real HTTP backend. 9 of 11 admin domains inject their mock gateway directly — no DI seam to swap at all. |
| Platform API | 🟡 Storefront catalog/search/cart-payment are live; everything admin-side is mock. |
| Seller Portal | ❌ A static placeholder page, feature flag `false` by default, zero backend bytes, zero `HttpClient` reference. |
| Workers / Event Processing | ❌ Nothing. No event bus, no retry, no dead-letter. |
| Integration Hub | ❌ Nothing. Zero `reconcil*`, zero `idempot*` in the whole codebase. |
| Domain Automation | ❌ Nothing. Zero `hostinger` references — the plan's §8.2 lists seven Hostinger DNS endpoints we have never touched. |
| Marketplace Registry / Launch Center | ❌ Nothing shipped. Closest thing is our unshipped [super-admin Phase 1 design](superpowers/specs/superuser.md), which covers cross-tenant *viewing* but not registry/feature-set/launch. |
### 3.2 Catalog model (§2.1) — the biggest structural gap
The plan's core catalog idea is a **two-layer split**: `Product` (content card) vs. `Offer/Listing` (the seller's commercial proposition, which owns price, stock, currency, status). Order lines then snapshot the offer.
| Plan entity | Our state |
|---|---|
| `Product` / `Variant` / `SKU` | 🟡 Exists as admin mock + a separate live storefront `Item` domain. Two unrelated `Category` types, both fed by the same response, both in use. |
| `Offer / Listing` | ❌ Does not exist. Price and stock hang off the product. Multi-seller pricing on one product card is not expressible. |
| `PriceSnapshot` | ❌ Does not exist. |
| `InventoryRecord` (available/reserved/sold) | ❌ Does not exist. No reservations, no TTL, no oversell queue. |
| `PriceHistory` | ❌ Does not exist. |
| Draft → moderation → published → paused/archived | 🟡 An admin Moderation module exists, on mock data. |
| Bulk import CSV/API with pre-apply error preview | ❌ Only bulk *edit* actions inside Admin Categories. No import pipeline. |
| "Storefront search/filters run on published data, not local mock arrays" | ⚠️ Directly aimed at us. `PRODUCT_DATA_PROVIDER` and `CATEGORY_REPOSITORY` silently always resolve to the real API — but Search, wishlist/compare, cart contents and CMS are entirely `localStorage`. |
### 3.3 Money, FX and price traceability (§2.3, §3.3, §3.8, §7)
This is where the plan is most explicit, and where we most clearly do the forbidden thing.
| Plan requirement | Our state |
|---|---|
| `Money = amountMinor + currency`, **no float for money math** | ⚠️ We use plain `number` prices and float division/multiplication in `CurrencyRatesService.convert()`. |
| Rates come from a configurable **external source** with `source`, `rate`, `timestamp`, `TTL` | ⚠️ Rates are **hand-typed by an admin** into Admin Settings and stored in **browser `localStorage`** (`currencyRates.v1`), with hardcoded fallbacks (`USD: 0.011`, `AMD: 4.3`). They never update and drift from market. |
| `FxQuote { base, quote, rate, source, observedAt, expiresAt, quoteId }` | ❌ Does not exist. |
| Stale-quote control blocks checkout | ❌ Does not exist. |
| Checkout writes an immutable price snapshot; old orders never recalculated | ❌ Does not exist. |
| `PriceBook` (base currency + allowed display/checkout currencies) | ❌ Does not exist. |
| Backoffice shows the total formula: lines × qty − discounts + delivery + fees, plus the FX quote used | ❌ Does not exist. |
| Reconciliation of internal orders vs. provider transactions | ❌ Does not exist (`reconcil*` = 0 hits repo-wide). |
**Nuance worth telling them:** their §3.3 complaint is *"switching RUB/USD/AMD keeps the same number"*. Our storefront **does** convert the displayed number. Their real, unstated problem is the one our own [§12.7](../BACKEND-API-REFERENCE.md) already flagged: the **charged** amount is computed client-side in RUB and posted to `/cart` as `amount`, so bank settlement totals don't reconcile against order counts. We agree with the plan here — we raised it first.
### 3.4 Cart and Checkout (§2.5, §2.6) — ⚠️ head-on conflict with a frozen system
| Plan requirement | Our state |
|---|---|
| Cart is **server-side**, keyed on `offerId` | ⚠️ Cart is `localStorage` + Telegram CloudStorage. There is no backend cart at all. |
| "Client never sends a trusted price to the server" | ⚠️ `CartPaymentRequest` sends `amount`, `currency`, and a per-item `price` array from the browser. This is exactly the pattern the plan forbids. |
| Checkout is a **server session** producing a price snapshot + contact snapshot | ❌ Checkout is an inline popup in `pages/cart/cart.component.ts` (751 lines). `features/website/checkout/` is an empty directory. |
| Idempotent order creation keyed on the payment | ❌ `/orders` is called fire-and-forget after payment success. Zero `idempot*` in the codebase. |
| Backend re-validates offers/stock at checkout | ❌ No stock concept exists to validate. |
| Multi-seller cart grouped by seller and fulfillment rules | ❌ Undefined behaviour — already flagged in our own gaps doc. |
| No duplicate payment intents on double-click | 🟡 Popup state guards the UI; nothing server-side. |
**Blocker:** [BACKEND-API-REFERENCE.md §7](../BACKEND-API-REFERENCE.md) states *"Payments are frozen — this call chain is explicitly out of scope for changes."* The plan's P0-A and P0-C cannot be delivered without unfreezing it. **This needs an explicit decision from whoever froze it.**
### 3.5 Payments (§2.7, §3.2)
| Plan requirement | Our state |
|---|---|
| Explicit state machines: `PaymentIntent` / `Payment` / `Order` | ❌ None. Payment status is a client-side signal with values `creating/waiting/success/timeout/error`. |
| Webhook signature verification + idempotency | ❌ None. `webhook` appears only as a display field in the admin **monitoring mock**. |
| Store `provider event id`, `provider timestamp`, `receivedAt`, `processedAt` | ❌ None. |
| "No artificial fixed delays" | ✅ **We already comply.** We poll real provider status (`/qr/dynamic/{partnerId}/{qrId}`, `/card/{partnerId}/{orderId}`) on an interval bounded by the QR TTL. There is no 5-second timer in this codebase. |
| Refunds as a first-class operation with reason/actor/order-line link | ❌ `requestRefund(id)` exists only as a mock gateway method. |
| Reconciliation queue | ❌ None. |
**Ask them:** §3.2 describes a fixed 5-second payment. We cannot reproduce it here. Either they observed a different build/environment, or they inferred it from the *admin* mock data. Worth pinning down before we spend P0 budget on a problem that may not be ours.
### 3.6 Orders and Fulfillment (§2.8, §3.6)
| Plan requirement | Our state |
|---|---|
| Canonical `Order` regardless of source (storefront / external marketplace / backoffice / API partner) | ❌ Admin Orders is a **static 24-row in-memory seed with no create path**, and no DI token to swap it. |
| `OrderLine` with SKU/title/price snapshots | ❌ |
| `Source mapping` (`externalMarketplace`, `externalOrderId`, `connectorId`) | ❌ |
| `Fulfillment` (manual / warehouse / pickup / digital) with evidence | ❌ One `fulfil*` hit in the entire codebase. |
| `Timeline` of all order events | ❌ Already logged as our own frontend-blocked TODO ("Real order audit trail"). |
| Admin actions: assign, resend notification, replay sync, cancel/refund by permission | ❌ |
| **No special branch for inspectors — any published, available product must be genuinely buyable and fulfillable** | ❌ We have no publish-time executability validation and no fulfillment flow, so we cannot currently *prove* compliance either way. |
### 3.7 Customer identity (§2.9, §3.4, §14)
| Plan requirement | Our state |
|---|---|
| `Customer` + multiple `ExternalIdentity` + verified `ContactMethod` | ❌ Telegram user is effectively the customer identity. |
| `emailVerifiedAt` / `phoneVerifiedAt` / `telegramLinkedAt` | ❌ |
| Order contact snapshot, immutable after order creation | ❌ |
| Email/phone OTP | 🟡 **Designed, not built** — spec approved 2026-08-15. |
| VK ID / MAX | ❌ New in v3.1, nothing exists. |
| Guest checkout toggled by tenant policy | ❌ |
### 3.8 Notifications (§2.10, §3.5)
| Plan requirement | Our state |
|---|---|
| Platform event bus emitting `order.created` / `order.paid` / `payment.failed` / `webhook.error` / `stock.low` / `oversell` / `refund.*` / `external_order.imported` | ❌ |
| Notification with `unread/read`, `severity`, `marketplaceId`, entity type/id, **deep link** | 🟡 `AdminOrderWatcherService` polls for new orders and toasts/badges the admin — the right shape, wrong data source. |
| Unread counter + filter by marketplace / event type in backoffice | 🟡 Partial (counter yes, marketplace filter no). |
| External channel delivery status logged; a Telegram/email failure must not lose the internal notification | ❌ |
**Status:** the notification feature is built and **functionally inert** — it polls the mock Orders gateway, which has no create path, so no new order can ever appear. It starts working the day Orders gets a real backend, with no further frontend change.
### 3.9 Analytics (§3.1, §6.3)
| Plan requirement | Our state |
|---|---|
| Server-side event logging: `session_started`, `page_view`, `product_view`, `add_to_cart`, `checkout_started`, `payment_started/success/failed`, `order_created` | ❌ **No tracking pipeline exists at all.** Not a missing endpoint — missing infrastructure. Our own docs rate it the single largest remaining backend effort. |
| Operational metrics: notification latency, fulfillment time, connector lag, webhook lag | ❌ |
| Quality metrics: frontend/backend errors, checkout validation failures, FX stale blocks | ❌ |
| Real funnel in backoffice | ❌ Admin Analytics composes five mock gateways and has no data source. |
| Synthetic traffic technically separated from production analytics | ⚠️ Cannot comply — there is no production analytics to separate it from. |
| Product view counts | 🟡 A "Views" column was shipped in Admin Products; it always renders `0` because no tracking source exists. Storefront `Item.visits` is live-wired but displayed nowhere. |
### 3.10 Backoffice navigation (§4.1) — 12 required sections, 5 missing outright
Have (mock unless noted): Overview/Dashboard, Catalog (Categories real, Products mock), Orders, Payments partial (Transactions), Customers, Notifications partial, Content & Design (builder/CMS, `localStorage` only), Monitoring, Reports, Users, Settings.
Missing entirely:
- **Marketplaces** — registry, type, status, domains, currencies, feature set, responsible manager. Nothing.
- **Sellers** — organizations, applications, roles, listings, integration health. Placeholder page only.
- **Payments & Finance** — refunds, reconciliation, unmatched events, settlements. `settlement*` = 0 hits.
- **Integrations** — external connectors, payment providers, FX sources, messaging. Nothing.
- **Domains & Releases** — DNS/SSL, staging, production, health checks, rollback. Nothing.
- **Audit & Security** — role changes, sensitive actions, login/security events, exports. `audit` appears only as display fields on mock models.
### 3.11 Roles and RBAC (§4.4, §10.1) — ⚠️ our most serious security gap
The plan specifies three scopes and 17 named roles (5 platform, 7 marketplace, 5 seller).
Our state: **the admin role model is decorative.** `AdminRole` and permissions exist as types, but nothing gates any button, page or action anywhere in the app. Anyone who passes admin authentication has full access. `AdminRole` is additionally defined twice with unrelated shapes.
Also missing from §10.1: idempotency keys, rate-limit handling (429 has zero client-side handling), step-up authentication for financial actions, audit log, PII minimisation policy.
### 3.12 External marketplace integrations (§5) — 0% built
Nothing in this section exists in any form: connector contract, webhook-preferred/polling-fallback ingestion, raw event storage, normalizer, SKU mapping, unmatched queue, exponential retry, dead-letter, manual replay, reconciliation, connector observability, and the proposed SLA (99% of webhook events processed under 60s, zero duplicate orders).
**Blocking unknown:** the plan never names which external marketplaces. Ozon? Wildberries? Yandex Market? Avito? Each is a separate connector with its own auth and rate limits. We cannot size this without the list.
### 3.13 Domains, publishing and tenant launch (§8)
| Plan requirement | Our state |
|---|---|
| Marketplace lifecycle `draft → configured → content_ready → domains_planned → staging_live → qa_passed → production_ready → live → paused/archived`, with the blocking item shown per transition | ❌ |
| DNS automation via Hostinger API (7 endpoints listed), snapshot + rollback, never touching MX/SPF/DKIM/DMARC/CAA, approval gate in production, propagation + SSL + health checks | ❌ Zero references. |
| Publish model: `draft → validation → preview → publish`, immutable published revision, rollback creates a new revision | 🟡 The builder edits an in-memory config and persists drafts to `localStorage`. "Publish" only promotes a local signal. No revisions, no server-side publish endpoint (`apiEndpoints.builder` is an empty placeholder). |
| Commerce data explicitly **not** part of content revisions | ✅ Structurally true today — orders/payments simply aren't in the revision at all. |
### 3.14 API boundaries (§9.3) — ⚠️ a naming migration we have not planned
Plan namespaces: `/api/v2/storefront/*`, `/api/admin/v2/*`, `/api/seller/v1/*`, `/api/identity/v1/*`, `/api/providers/v1/*`, `/api/integrations/v1/*`.
Ours: unversioned, flat — `/cart`, `/orders`, `/items`, `/category`, `/searchitems`, plus a separate `qrApiUrl` host. Our own reference says **"No API versioning scheme has been decided"**.
Adopting the plan's namespaces is a coordinated frontend+backend rename, not a config change. It should be sequenced *before* the new commerce endpoints are built, not after.
Also in §9: the plan's error model assumes a structured envelope. Ours is a proposal only — no interceptor inspects error bodies today; every error reaction happens at raw HTTP-status level.
### 3.15 Gorbushka as a tenant (§11)
The plan lists mall-directory content entities: `Shop`, `ShopCategory`, `Service`, `Floor`, `SchemePin`, `RentListing`, `News/Promo`, `StaticPage`, `Lead`, `MallSettings` — each with `marketplaceId`, audit, and publish/preview.
We have: static pages inside the bootstrap document. None of the other nine entity types exist, and CMS content has no backend write path at all.
Positive read: the plan explicitly says Gorbushka must **not** dictate platform architecture, and that the existing frontend is UX reference only. That matches our ADR-0001 constraint ("frontend must not contain marketplace-specific code"). No conflict here — just unbuilt scope.
### 3.16 Definition of Done (§13) — where we stand today
Of the 13 launch-checklist items, we can currently claim **zero** as green. Additionally, our own QA position makes their DoD hard to evidence:
- ~32% statement coverage, ~19% branch coverage, 11 spec files repo-wide.
- **Zero E2E tests** — no Playwright/Cypress config anywhere. The plan's acceptance criteria are all end-to-end by construction.
- Several past "verified live" claims were code-inspection only, because `/edit` and `/backoffice` require Telegram admin login that automated environments cannot complete.
---
## 4. What we have that the plan does not account for
Not gaps — assets and risks they should know about before sequencing:
1. **Project editor / builder** (~1.0 MB lazy chunk) — a full visual site builder. The plan's §8.3 publish model would replace its persistence layer entirely.
2. **Ed25519 challenge/response admin auth** — fully wired client-side, backend returns 404 today. The plan never mentions it; it assumes conventional RBAC.
3. **Widget manifest / dynamic renderer** — the mechanism that makes one storefront runtime serve many tenants. This is the part of the plan we have *already* solved and should defend.
4. **Super-admin Phase 1 design** (`docs/superpowers/specs/superuser.md`) — cross-tenant read-only view. Overlaps §4.3 Marketplace Registry and §10 audit. Worth re-scoping against the plan rather than building as specified.
5. **Three in-flight items already answer v3.0 P0s:** admin purchase notifications (§3.5), admin product views column (§3.1), email/phone OTP login (§3.4). Two of the three are inert until a real backend exists.
---
## 5. Manager's read — the honest framing
**Split of ownership.** Roughly 80% of this document is backend and platform-service work: Platform API, Workers/Event Processing, Integration Hub, Domain Automation, payment state machines, reconciliation, analytics pipeline. This repository is a frontend. Of the plan's ~14 sections, only Storefront Runtime (§6.1) is substantially delivered, and it is delivered *well*.
**The real message is trust, not features.** Every P0 in §3 is a variant of "we cannot explain your numbers." Sequencing should follow that: traceability first (money model, price snapshot, payment timeline, audit), feature breadth second. That happens to also be the plan's own P0-A ordering.
**The largest single risk is not scope — it is the frozen payment chain.** Cart is client-owned, price is client-supplied, orders are fire-and-forget, and the whole chain is marked "do not modify." Three P0s sit behind that freeze. Nothing else in this list can be honestly estimated until that decision is reversed or explained.
**Second risk: RBAC.** The plan assumes 17 enforced roles across three scopes. We enforce none. Any real admin backend going live before this is fixed hands full platform access to every authenticated operator.
---
## 6. Decisions — answered 2026-08-17
See [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Sprint 0.1 for the full record and downstream consequences. Summary:
1. **Backend ownership — answered 2026-08-18.** A separate backend developer implements against `docs/backend/`. This repository owns the frontend and the contract set.
2. **Payment chain — unfrozen. Yes.** Phases 1, 6, 7 proceed.
3. **External marketplaces — no fixed list.** Connectors onboard partners as they arrive; build the Phase 4 framework config-driven/generic, not per-named-provider.
4. **FX rate source — ours, in-house, as a safety gate.** No external provider committed; backend computes FX authoritatively until/unless one is chosen later.
5. **§14 vs. OTP — VK ID first, then everything else** ("do all after vk"). Phase 8 resequenced.
6. **Multi-seller orders — unified.** One `Order` per checkout, seller-scoped `Fulfillment` groups internally. Resolves the three-document disagreement.
7. **"Fixed 5-second payment" — resolved as a non-issue.** `PAYMENT_POLL_INTERVAL_MS` is already `5000` — that's poll cadence against real provider status, not an artificial delay. Confirmed compliant, no change needed.
8. **API namespace — new endpoints only, no forced migration.** `/api/v2/...` used for all new Phase 1+ contracts; legacy endpoints stay as-is pending a dedicated migration sprint.
9. **Document version — v3.1 is canonical.** The source PDF's internal "3.0" version block is stale.
---
## 7. Suggested first slice (if they want a proposal back)
Following their own dependency order, restricted to what is buildable and provable:
1. **Money model + FX quote + price snapshot** (P0-A) — needs the payment freeze lifted. Removes client-supplied `amount`, kills the float math, gives every total an explainable formula. This one item closes §3.3, §3.8 and half of §13.1.
2. **Order canonical model + timeline + notification wiring** (P0-B) — the notification feature already exists and switches on for free.
3. **RBAC enforcement** — not on their P0 list, but it is the gate on everything else in the backoffice going live safely.
4. **Analytics event pipeline** (P0/§3.1) — long lead time, so start it in parallel rather than last.
Explicitly *not* in a first slice: Seller Portal, external connectors, domain automation, VK/MAX bots. All of them depend on the commerce core being real first, which is what the plan itself says in §12.1.

206
docs/PWA_SETUP.md Normal file
View File

@@ -0,0 +1,206 @@
# PWA Setup Guide
## ✅ Implemented Features
### 1. Service Worker
- **Caching Strategy**: Aggressive prefetch for app shell
- **API Caching**: Freshness strategy with 1-hour cache (max 100 requests)
- **Image Caching**: Performance strategy with 7-day cache (max 50 images)
- **Configuration**: `ngsw-config.json`
### 2. Web App Manifests
- **Dexar**: `public/manifest.webmanifest` (purple theme #a855f7)
- **Novo**: `public/manifest.novo.webmanifest` (green theme #10b981)
- **Features**:
- Installable on mobile/desktop
- Standalone display mode
- 8 icon sizes (72px to 512px)
- Russian language metadata
### 3. Offline Support
- App shell loads instantly from cache
- API responses cached for 1 hour
- Product images cached for 7 days
- Automatic background updates
## 🚀 Testing PWA Functionality
### Local Testing with Production Build
```bash
# Build for production
npm run build -- --configuration=production
# Serve the production build
npx http-server dist/dexarmarket -p 4200 -c-1
# For Novo brand
npx http-server dist/novomarket -p 4201 -c-1
```
### Chrome DevTools Testing
1. Open `http://localhost:4200`
2. Open DevTools (F12)
3. Go to **Application** tab
4. Check:
- **Service Workers**: Should show registered worker
- **Cache Storage**: Should show `ngsw:/:db`, `ngsw:/:assets`
- **Manifest**: Should show app details
### Install Prompt Testing
1. Open app in Chrome/Edge
2. Click the **install icon** in address bar (➕)
3. Confirm installation
4. App opens as standalone window
5. Check Start Menu/Home Screen for app icon
### Offline Testing
1. Open app while online
2. Navigate through pages (loads assets)
3. Open DevTools → Network → Toggle **Offline**
4. Refresh page - should still work!
5. Navigate to cached pages - should load instantly
## 📱 Mobile Testing
### Android Chrome
1. Open app URL
2. Chrome shows "Add to Home Screen" banner
3. Install and open - works like native app
4. Splash screen with your logo/colors
### iOS Safari
1. Open app URL
2. Tap Share → "Add to Home Screen"
3. Icon appears on home screen
4. Opens in full-screen mode
## 🔧 Configuration Details
### Service Worker Caching Strategy
```json
{
"app": {
"installMode": "prefetch", // Download immediately
"updateMode": "prefetch" // Auto-update in background
},
"assets": {
"installMode": "lazy", // Load on-demand
"updateMode": "prefetch"
},
"api-cache": {
"strategy": "freshness", // Network first, fallback to cache
"maxAge": "1h" // Keep for 1 hour
},
"product-images": {
"strategy": "performance", // Cache first, update in background
"maxAge": "7d" // Keep for 7 days
}
}
```
### Manifest Differences
| Property | Dexar | Novo |
|----------|-------|------|
| Theme Color | #a855f7 (purple) | #10b981 (green) |
| Name | Dexar Market | Novo Market |
| Icons | Default Angular | Default Angular |
| Background | White (#ffffff) | White (#ffffff) |
## 🎨 Custom Icons (Recommended)
Replace the default Angular icons with brand-specific ones:
```bash
public/icons/
├── icon-72x72.png # Smallest (splash screen)
├── icon-96x96.png
├── icon-128x128.png
├── icon-144x144.png
├── icon-152x152.png # iOS home screen
├── icon-192x192.png # Android home screen
├── icon-384x384.png
└── icon-512x512.png # Largest (splash, install prompt)
```
**Design Guidelines**:
- Use solid background color (purple for Dexar, green for Novo)
- Center white logo/icon
- Keep design simple (shows at small sizes)
- Export as PNG with transparency or solid background
## 🔄 Update Strategy
### How Updates Work
1. User visits app
2. Service worker checks for updates
3. New version downloads in background
4. User refreshes → gets updated version
5. Old cache automatically cleared
### Force Update (Development)
```bash
# Clear all caches
chrome://serviceworker-internals/ # Unregister worker
chrome://settings/clearBrowserData # Clear cache
# Or in code (add to app.config.ts)
navigator.serviceWorker.getRegistrations().then(registrations => {
registrations.forEach(reg => reg.unregister());
});
```
## 📊 Performance Benefits
### Before PWA
- Initial load: ~2-3s (network dependent)
- Subsequent loads: ~1-2s
- Offline: ❌ Not available
### After PWA
- Initial load: ~2-3s (first visit)
- Subsequent loads: **~200-500ms** (cached)
- Offline: ✅ **Fully functional**
- Install: ✅ **Native app experience**
## 🐛 Troubleshooting
### Service Worker Not Registering
- Check console for errors
- Ensure HTTPS (or localhost)
- Clear browser cache and reload
### Old Version Not Updating
- Hard refresh: `Ctrl+Shift+R` (Windows) or `Cmd+Shift+R` (Mac)
- Unregister worker in DevTools
- Wait 24 hours (automatic update)
### Manifest Not Loading
- Check `index.html` has `<link rel="manifest">`
- Verify manifest path is correct
- Check manifest JSON is valid (no syntax errors)
### Icons Not Showing
- Check icon paths in manifest
- Ensure icons exist in `public/icons/`
- Verify icon sizes match manifest
## 📚 Next Steps
1. **Custom Icons**: Create brand-specific icons for both themes
2. **Push Notifications**: Add user engagement (requires backend)
3. **Background Sync**: Queue offline orders, sync when online
4. **Analytics**: Track PWA installs, offline usage
5. **A2HS Prompt**: Show custom "Install App" banner
## 🔗 Resources
- [PWA Checklist](https://web.dev/pwa-checklist/)
- [Angular PWA Guide](https://angular.dev/ecosystem/service-workers)
- [Manifest Generator](https://www.simicart.com/manifest-generator.html/)
- [Icon Generator](https://realfavicongenerator.net/)

181
docs/RAIFFEISENBANK_REQUIREMENTS.md Normal file
View File

@@ -0,0 +1,181 @@
# Рекомендации по работе с платежными ссылками
## Требования Райффайзенбанка для оплаты по ссылке
### ✅ Что уже реализовано:
1. **Реквизиты организации** - полностью заполнены
2. **Правила оплаты** - подробная страница с требованиями ЦБ РФ, PCI DSS, 3D-Secure
3. **Политика возврата** - полная информация о возврате физических и цифровых товаров
4. **Публичная оферта** - модель маркетплейса, разграничение ответственности
5. **Политика конфиденциальности** - обработка персональных данных (152-ФЗ)
6. **Чекбокс согласия в корзине** - со ссылками на:
- Публичную оферту
- Политику возврата
- Условия гарантии
- Политику конфиденциальности
7. **Логотипы платежных систем**:
- МИР (обязательно!)
- Visa
- Mastercard
- Размещены в футере и на странице оплаты
---
## 📧 Рекомендации при отправке платежной ссылки покупателю
### Шаблон письма/сообщения:
```
Здравствуйте, [Имя покупателя]!
Ваш заказ №[НОМЕР] оформлен.
Для оплаты перейдите по ссылке:
[ПЛАТЕЖНАЯ ССЫЛКА]
Сумма к оплате: [СУММА] ₽
Перед оплатой, пожалуйста, ознакомьтесь с условиями:
• Публичная оферта: https://dexarmarket.ru/public-offer
• Политика возврата: https://dexarmarket.ru/return-policy
• Условия гарантии: https://dexarmarket.ru/guarantee
• Политика конфиденциальности: https://dexarmarket.ru/privacy-policy
Оплачивая заказ, вы подтверждаете, что ознакомились и согласны с данными условиями.
---
С уважением,
Команда Dexarmarket
Техподдержка: Info@dexarmarket.ru
Телефон: +7 (926) 459-31-57
```
### ✅ Важно получить подтверждение от покупателя!
**Вариант 1 - Автоматическое подтверждение:**
После оплаты отправить покупателю:
```
Спасибо за оплату заказа №[НОМЕР]!
Вы подтвердили согласие с:
✓ Публичной офертой
✓ Политикой возврата
✓ Условиями гарантии
✓ Политикой конфиденциальности
Чек отправлен на email: [EMAIL]
Статус заказа можно отслеживать в личном кабинете.
```
**Вариант 2 - Ручное подтверждение (желательно):**
Перед отправкой ссылки запросить:
```
Для оформления заказа подтвердите, пожалуйста, что вы ознакомились с условиями
(https://dexarmarket.ru/public-offer) и согласны с ними.
Ответьте "Согласен" или "Подтверждаю" для продолжения.
```
---
## 🛡️ Защита от оспаривания платежей (Chargeback)
### Что сохранять для доказательной базы:
1. **Переписка с покупателем:**
- Скриншоты чатов
- Email переписка
- SMS/WhatsApp сообщения с подтверждением
2. **Логи действий покупателя:**
- IP-адрес при оформлении заказа
- Timestamp (дата и время)
- Согласие с чекбоксом (если есть личный кабинет)
3. **Документы об отправке:**
- Трек-номер посылки
- Подтверждение доставки
- Подпись получателя (если есть)
4. **Платежная информация:**
- Номер транзакции
- Дата и время оплаты
- Сумма платежа
---
## 🔒 Дополнительные меры безопасности
### 1. Двухфакторное подтверждение
Для крупных заказов (>10 000 ₽) рекомендуется:
- Звонок покупателю для подтверждения заказа
- Запись разговора (с уведомлением клиента)
### 2. Проверка благонадежности
Для новых покупателей:
- Проверить совпадение адреса доставки с регионом телефона
- При подозрительных заказах запросить фото документа
### 3. Страхование рисков
- Оформить договор с платежным провайдером на защиту от мошенничества
- Использовать холдирование средств (72 часа на проверку)
---
## 📊 Статистика оспариваний
**Риски по категориям товаров:**
- Электроника: ~2-5% оспариваний
- Одежда: ~1-3%
- Цифровые товары: ~0.5-2%
- Продукты питания: ~0.1-0.5%
**Причины оспариваний:**
1. "Не получил товар" (40%)
2. "Товар не соответствует описанию" (30%)
3. "Не заказывал" (20%)
4. "Дубликат платежа" (10%)
---
## ✅ Чек-лист готовности к работе с Райффайзенбанком
- [x] Реквизиты организации заполнены
- [x] Правила оплаты на русском языке
- [x] Политика возврата опубликована
- [x] Публичная оферта опубликована
- [x] Политика конфиденциальности опубликована
- [x] Логотип МИР размещен на сайте
- [x] Чекбокс согласия с условиями в корзине
- [x] Ссылки на все документы в чекбоксе
- [ ] Настроен процесс отправки платежных ссылок с условиями
- [ ] Настроен процесс получения подтверждений от покупателей
- [ ] Настроена система логирования действий пользователей
- [ ] Подготовлена база для работы с оспариваниями
---
## 📞 Контакты для связи с банком
**АО "Райффайзенбанк"**
- Сайт: https://www.raiffeisen.ru
- Требования к сайтам: https://www.raiffeisen.ru/common/img/uploaded/files/business/treb_k_saity.pdf
- Техподдержка эквайринга: указывается при подключении
**Платежная система МИР**
- Требования к использованию логотипа: https://mironline.ru/support/merchantam/brand/
- Обязательно размещение логотипа при приеме карт МИР
---
## 🚀 Статус проекта
**Готовность к подключению эквайринга: 95%**
Осталось реализовать:
1. Автоматизацию отправки ссылок с условиями
2. Систему получения подтверждений от покупателей
3. Логирование действий для доказательной базы
**Все юридические и информационные требования выполнены!** ✅

423
docs/RECOMMENDATIONS.md Normal file
View File

@@ -0,0 +1,423 @@
# Project Recommendations & Roadmap
## 📊 Current Status: 9.2/10
Your project is production-ready with excellent architecture! Here's what to focus on next:
---
## ✅ Recently Completed (January 2026)
1. **Phone Number Collection**
- Real-time formatting (+7 XXX XXX-XX-XX)
- Comprehensive validation (11 digits)
- Raw digits sent to API
2. **HTML Structure Unification**
- Single template for both themes
- CSS-only differentiation (Novo/Dexar)
- Eliminated code duplication
3. **PWA Implementation**
- Service worker with smart caching
- Dual manifests (brand-specific)
- Offline support
- Installable app
4. **Code Quality**
- Removed 3 duplicate methods
- Fixed SCSS syntax errors
- Optimized cart component
---
## 🎯 Priority Roadmap
### 🔥 HIGH PRIORITY (Next 2 Weeks)
#### 1. Custom PWA Icons
**Why**: Branding, professionalism
**Effort**: 2-3 hours
**Impact**: High visibility
**Action Items**:
```bash
# Create 8 icon sizes for each brand:
# Dexar: Purple (#a855f7) background + white logo
# Novo: Green (#10b981) background + white logo
public/icons/dexar/
├── icon-72x72.png
├── icon-512x512.png
└── ...
public/icons/novo/
├── icon-72x72.png
└── ...
# Update manifests to point to brand folders
```
**Tools**: Figma, Photoshop, or [RealFaviconGenerator](https://realfavicongenerator.net/)
---
#### 2. Unit Testing
**Why**: Code reliability, easier refactoring
**Effort**: 1-2 weeks
**Impact**: Development velocity, bug reduction
**Target Coverage**: 80%+
**Priority Test Files**:
```typescript
// 1. Services (highest ROI)
cart.service.spec.ts // Test signal updates, cart logic
api.service.spec.ts // Mock HTTP calls
telegram.service.spec.ts // Test WebApp initialization
// 2. Components (critical paths)
cart.component.spec.ts // Payment flow, validation
header.component.spec.ts // Cart count, navigation
item-detail.component.spec.ts // Add to cart, variant selection
// 3. Interceptors
cache.interceptor.spec.ts // Verify caching logic
```
**Quick Start**:
```bash
# Generate test with Angular CLI
ng test --code-coverage
# Write first test
describe('CartService', () => {
it('should add item to cart', () => {
service.addToCart(mockItem, mockVariant);
expect(service.cartItems().length).toBe(1);
});
});
```
---
#### 3. Error Boundary & User Feedback
**Why**: Graceful failures, better UX
**Effort**: 1 day
**Impact**: User trust, reduced support tickets
**Implementation**:
```typescript
// src/app/services/error-handler.service.ts
@Injectable({ providedIn: 'root' })
export class ErrorHandlerService {
showError(message: string) {
// Show toast notification
// Log to analytics
// Optionally send to backend
}
}
// Usage in cart.component.ts
this.apiService.createPayment(data).subscribe({
next: (response) => { /* handle success */ },
error: (err) => {
this.errorHandler.showError(
'Не удалось создать платеж. Попробуйте позже.'
);
console.error(err);
}
});
```
**Add Toast Library**:
```bash
npm install ngx-toastr --save
```
---
### ⚡ MEDIUM PRIORITY (Next Month)
#### 4. E2E Testing
**Why**: Catch integration bugs, confidence in releases
**Effort**: 3-5 days
**Impact**: Release quality
**Recommended**: [Playwright](https://playwright.dev/) (better than Cypress for modern apps)
```bash
npm install @playwright/test --save-dev
npx playwright install
```
**Critical Test Scenarios**:
1. Browse categories → View item → Add to cart → Checkout
2. Search product → Filter results → Add to cart
3. Empty cart → Add items → Remove items
4. Payment flow (mock SBP QR code response)
5. Email/phone validation on success screen
---
#### 5. Analytics Integration
**Why**: Data-driven decisions, understand users
**Effort**: 1 day
**Impact**: Business insights
**Recommended Setup**:
```typescript
// Yandex Metrica (best for Russian market)
<!-- index.html -->
<script>
(function(m,e,t,r,i,k,a){
// Yandex Metrica snippet
})(window, document, "yandex_metrica_callbacks2");
</script>
// Track events
yaCounter12345678.reachGoal('ADD_TO_CART', {
product_id: item.id,
price: variant.price
});
```
**Key Metrics to Track**:
- Product views
- Add to cart events
- Checkout initiation
- Payment success/failure
- Search queries
- PWA installs
---
#### 6. Performance Optimization
**Why**: Better UX, SEO, conversion rates
**Effort**: 2-3 days
**Impact**: User satisfaction
**Action Items**:
```typescript
// 1. Image Optimization
// Use WebP format with fallbacks
<picture>
<source srcset="image.webp" type="image/webp">
<img src="image.jpg" alt="Product">
</picture>
// 2. Lazy Load Images
<img loading="lazy" src="product.jpg">
// 3. Preload Critical Assets
// index.html
<link rel="preload" href="logo.svg" as="image">
// 4. Virtual Scrolling for Long Lists
// npm install @angular/cdk
<cdk-virtual-scroll-viewport itemSize="150">
@for (item of items; track item.id) {
<div>{{ item.title }}</div>
}
</cdk-virtual-scroll-viewport>
```
**Measure First**:
```bash
# Lighthouse audit
npm install -g lighthouse
lighthouse http://localhost:4200 --view
# Target scores:
# Performance: 90+
# Accessibility: 95+
# Best Practices: 100
# SEO: 90+
```
---
### 🔮 FUTURE ENHANCEMENTS (Next Quarter)
#### 7. Push Notifications
**Why**: Re-engage users, promote offers
**Effort**: 1 week (needs backend)
**Impact**: Retention, sales
**Requirements**:
- Firebase Cloud Messaging (FCM)
- Backend endpoint to send notifications
- User permission flow
---
#### 8. Background Sync
**Why**: Queue orders offline, sync when online
**Effort**: 2-3 days
**Impact**: Offline-first experience
```typescript
// Register background sync
navigator.serviceWorker.ready.then(registration => {
registration.sync.register('sync-orders');
});
// ngsw-config.json - already set up!
// Your PWA is ready for this
```
---
#### 9. Advanced Features
**Effort**: Varies
**Impact**: Competitive advantage
- **Product Recommendations**: "You might also like..."
- **Recently Viewed**: Track browsing history
- **Wishlist**: Save items for later
- **Price Alerts**: Notify when price drops
- **Social Sharing**: Share products on Telegram/VK
- **Dark Mode**: Theme switcher
- **Multi-language**: Support English, etc.
---
## 🛠️ Technical Debt & Improvements
### Quick Wins (< 1 hour each)
1. **Environment Variables for API URLs**
```typescript
// Don't hardcode API URLs
// Use environment.apiUrl consistently
```
2. **Content Security Policy (CSP)**
```nginx
# nginx.conf
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline';";
```
3. **Rate Limiting**
```typescript
// Prevent API spam
import { debounceTime } from 'rxjs';
searchQuery$.pipe(
debounceTime(300)
).subscribe(/* search */);
```
4. **Loading States**
```html
<!-- Show skeletons while loading -->
@if (loading()) {
<div class="skeleton"></div>
} @else {
<div>{{ content }}</div>
}
```
5. **SEO Meta Tags**
```typescript
// Use Angular's Meta service
constructor(private meta: Meta) {}
ngOnInit() {
this.meta.updateTag({
name: 'description',
content: this.product.description
});
}
```
---
## 📈 Success Metrics
### Before Optimizations
- Test Coverage: ~10%
- Lighthouse Score: ~85
- Error Tracking: Console only
- Analytics: None
- PWA: ❌
### After Optimizations (Target)
- Test Coverage: **80%+**
- Lighthouse Score: **95+**
- Error Tracking: ✅ Centralized
- Analytics: ✅ Yandex Metrica
- PWA: ✅ **Fully functional**
- User Engagement: **+30%** (with push notifications)
---
## 🎓 Learning Resources
### Testing
- [Angular Testing Guide](https://angular.dev/guide/testing)
- [Testing Library](https://testing-library.com/docs/angular-testing-library/intro/)
### Performance
- [Web.dev Performance](https://web.dev/performance/)
- [Angular Performance Checklist](https://github.com/mgechev/angular-performance-checklist)
### PWA
- [PWA Workshop](https://web.dev/learn/pwa/)
- [Workbox](https://developer.chrome.com/docs/workbox/) (service worker library)
### Analytics
- [Yandex Metrica Guide](https://yandex.ru/support/metrica/)
- [Google Analytics 4](https://developers.google.com/analytics/devguides/collection/ga4)
---
## 💡 Pro Tips
1. **Ship Frequently**: Deploy small updates often
2. **Monitor Production**: Set up error tracking (Sentry, Rollbar)
3. **User Feedback**: Add feedback button in app
4. **A/B Testing**: Test different checkout flows
5. **Mobile First**: 70%+ of e-commerce is mobile
6. **Accessibility**: Test with screen readers
7. **Security**: Regular dependency updates (`npm audit fix`)
---
## 🚀 Next Actions (This Week)
```bash
# Day 1: PWA Icons
1. Design icons for both brands
2. Update manifests
3. Test installation on mobile
# Day 2-3: Error Handling
1. Install ngx-toastr
2. Add ErrorHandlerService
3. Update all API calls with error handling
# Day 4-5: First Unit Tests
1. Set up testing utilities
2. Write tests for CartService
3. Write tests for cart validation logic
4. Run coverage report: npm test -- --code-coverage
# Weekend: Analytics
1. Set up Yandex Metrica
2. Add tracking to key events
3. Monitor dashboard
```
---
## 💬 Questions?
If you need help with any of these tasks:
1. Ask for specific code examples
2. Request architectural guidance
3. Need library recommendations
4. Want code reviews
Your project is already excellent - these improvements will make it world-class! 🌟

327
docs/TELEGRAM_USERAUTH_BACKEND.md Normal file
View File

@@ -0,0 +1,327 @@
# Telegram UserAuth Backend Contract
This document extracts the existing Telegram login flow into a repo-neutral contract for reuse in other projects.
The UI behavior, payloads, polling cadence, and session model stay the same. Only route names and cookie naming are generalized.
## Endpoint Renaming
| Current app contract | Reusable contract |
|---|---|
| `GET /auth/session` | `GET /userauth/session` |
| `POST /auth/qr/create` | `POST /userauth/qr/create` |
| `GET /auth/qr/poll?token=...` | `GET /userauth/qr/poll?token=...` |
| `POST /auth/qr/confirm` | `POST /userauth/qr/confirm` |
| `GET /auth/telegram/callback` | `GET /userauth/telegram/callback` |
| `POST /auth/logout` | `POST /userauth/logout` |
| `POST /websession/{sessionId}` | `POST /usersession/{sessionId}` |
| Cookie `dx_session` | Cookie `userauth_session` |
## Flow Summary
There are two supported flows.
### 1. Direct login from button
1. Frontend opens `https://t.me/{botUsername}?start=auth_{callbackUrl}`.
2. Telegram bot creates a session and sends the user a login button.
3. The button points to `GET /userauth/telegram/callback?token={sessionId}`.
4. Backend sets `userauth_session` cookie and redirects back to the storefront.
5. Frontend calls `GET /userauth/session` and becomes authenticated.
### 2. QR login from desktop
1. Frontend opens dialog.
2. Frontend calls `POST /userauth/qr/create`.
3. Backend returns `{ token, url }` where `url` is a Telegram deep link.
4. Frontend renders a QR from that URL.
5. User scans QR and bot calls `POST /userauth/qr/confirm`.
6. Frontend polls `GET /userauth/qr/poll?token=...` every 3 seconds.
7. When status becomes `confirmed`, backend returns session payload and sets the cookie.
8. Frontend syncs local cart using `POST /usersession/{sessionId}`.
## Session Shape
The frontend expects this exact response shape for the authenticated session.
```json
{
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
"telegramUserId": 123456789,
"username": "ivan_petrov",
"displayName": "Ivan Petrov",
"active": true,
"expiresAt": "2026-05-21T14:30:00Z"
}
```
| Field | Type | Required | Notes |
|---|---|---|---|
| `sessionId` | string | yes | Session identifier used in cart sync |
| `telegramUserId` | number | yes | Telegram user ID |
| `username` | string or null | no | Telegram username |
| `displayName` | string | yes | User-facing full name |
| `active` | boolean | yes | `false` means expired session |
| `expiresAt` | ISO 8601 string | yes | Used by frontend refresh scheduling |
Recommended TTL:
- Session TTL: 24 hours
- QR token TTL: 5 minutes
## HTTP Contract
### `POST /userauth/qr/create`
Creates a one-time QR login token when the dialog opens.
Request body:
```json
{}
```
Response `200`:
```json
{
"token": "dG9rZW4tYWJjMTIz",
"url": "https://t.me/userauth_bot?start=login_dG9rZW4tYWJjMTIz"
}
```
Requirements:
- Generate a cryptographically secure token.
- Save token with status `pending`.
- Return a Telegram deep link in `url`.
- Rate limit to 5 requests per minute per IP.
### `GET /userauth/qr/poll?token={token}`
Called every 3 seconds until confirmation or expiration.
Possible responses:
Pending:
```json
{ "status": "pending" }
```
Confirmed:
```json
{
"status": "confirmed",
"session": {
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
"telegramUserId": 123456789,
"username": "ivan_petrov",
"displayName": "Ivan Petrov",
"active": true,
"expiresAt": "2026-05-21T14:30:00Z"
}
}
```
Expired:
```json
{ "status": "expired" }
```
Behavior:
- If confirmed, set cookie `userauth_session` in the response.
- Delete or invalidate the QR token after the first successful confirmed poll.
- If token is unknown or expired, return `status: "expired"`.
### `POST /userauth/qr/confirm`
Internal endpoint called by the Telegram bot after the user scans the QR code.
Required header:
```text
X-Bot-Secret: <shared secret between bot and backend>
```
Request body:
```json
{
"token": "dG9rZW4tYWJjMTIz",
"telegram_user": {
"id": 123456789,
"first_name": "Ivan",
"last_name": "Petrov",
"username": "ivan_petrov"
}
}
```
Response `200`:
```json
{ "status": "ok" }
```
Behavior:
- Validate `X-Bot-Secret`.
- Validate token exists and is still `pending`.
- Create a user session.
- Store session ID on the QR token.
- Mark QR token as `confirmed`.
### `GET /userauth/session`
Returns the currently active session based on the cookie.
Frontend behavior depends on this endpoint in two places:
- initial auth check on app startup
- fallback polling if QR token creation fails
Response `200`:
```json
{
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
"telegramUserId": 123456789,
"username": "ivan_petrov",
"displayName": "Ivan Petrov",
"active": true,
"expiresAt": "2026-05-21T14:30:00Z"
}
```
Error handling:
- Any non-200 response is treated by the frontend as unauthenticated.
### `GET /userauth/telegram/callback?token={sessionId}`
Used for direct Telegram login from the primary button flow.
Behavior:
- Read the `token` query param.
- Resolve it to a valid active session.
- Set cookie `userauth_session`.
- Redirect user to the storefront URL.
### `POST /userauth/logout`
Clears the backend session and expires the cookie.
Request body:
```json
{}
```
Response `200`:
```json
{ "message": "ok" }
```
### `POST /usersession/{sessionId}`
Synchronizes local cart immediately after successful login.
Request body:
```json
[
{
"itemID": 123,
"quantity": 2,
"colour": "#ff0000",
"size": "XL",
"price": 1500
}
]
```
Notes:
- This payload is unchanged from the existing implementation.
- `price` is already discounted on the frontend side.
- The frontend skips the call if cart is empty.
## Telegram Deep Link Format
Direct login link format:
```text
https://t.me/{botUsername}?start=auth_{urlEncodedCallbackUrl}
```
QR login link format:
```text
https://t.me/{botUsername}?start=login_{qrToken}
```
Important limit:
- Telegram limits the `start` payload to 64 characters.
- A base64url encoding of 32 random bytes plus `login_` fits safely.
## Cookie Requirements
Use these cookie settings for the frontend to work correctly across site and API origins.
| Property | Value |
|---|---|
| Name | `userauth_session` |
| Path | `/` |
| HttpOnly | `true` |
| Secure | `true` |
| SameSite | `None` |
| MaxAge | `86400` |
| Domain | your shared parent domain, for example `.example.com` |
## CORS Requirements
Because the frontend sends credentials, backend must return an explicit origin.
Required headers:
```text
Access-Control-Allow-Origin: https://your-frontend.example
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type
```
Do not use `*` for `Access-Control-Allow-Origin` together with credentials.
## Frontend Runtime Expectations
The current dialog behavior is fixed and should be preserved by backend responses.
- QR polling interval: every 3 seconds
- QR expiration on frontend: after 100 checks
- If QR creation fails, frontend falls back to direct login URL and session polling
- After login, frontend closes the dialog and re-checks session
## Minimal Backend Checklist
- Implement all six `userauth` endpoints and the `usersession` sync endpoint.
- Store sessions for 24 hours.
- Store QR tokens for 5 minutes.
- Protect `POST /userauth/qr/confirm` with `X-Bot-Secret`.
- Set `userauth_session` cookie on confirmed QR poll and direct callback.
- Return the exact session JSON shape.
- Support credentialed CORS.
## Bot Checklist
- Handle `/start login_{token}` and call `POST /userauth/qr/confirm`.
- Handle `/start auth_{callbackUrl}` and provide a button that opens the callback URL.
- Send success and expiration messages back to the user.
- Share the same `X-Bot-Secret` value with backend.

193
docs/TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,193 @@
# 🔧 Troubleshooting Guide for 404 and 502 Errors
## Quick Diagnosis
Run these commands on your Ubuntu server to diagnose the issue:
```bash
# 1. Check if files exist
ls -la /var/www/dexarmarket/browser/index.html
# 2. Check nginx config syntax
sudo nginx -t
# 3. Check nginx error logs (THIS IS MOST IMPORTANT!)
sudo tail -30 /var/log/nginx/error.log
# 4. Check if nginx is running
sudo systemctl status nginx
# 5. Test API from server
curl -v https://api.dexarmarket.ru:445/ping
```
## Error: 404 Not Found
### Cause: Files not uploaded or wrong path
**Solution 1: Verify files are on server**
```bash
ls -la /var/www/dexarmarket/browser/
```
Should show:
- `index.html`
- `main-*.js`
- `chunk-*.js`
- `polyfills-*.js`
- `styles-*.css`
- `assets/` folder
**If files are missing:**
```bash
# From your local machine:
cd F:\dx\marketplace\Dexarmarket
npm run build
scp -r dist/dexarmarket/browser/* user@your-server:/var/www/dexarmarket/browser/
```
**Solution 2: Fix permissions**
```bash
sudo chown -R www-data:www-data /var/www/dexarmarket
sudo chmod -R 755 /var/www/dexarmarket
```
**Solution 3: Check nginx config is loaded**
```bash
# Check which config is active
ls -la /etc/nginx/sites-enabled/
# Should show symlink to dexarmarket config
# If not:
sudo ln -s /etc/nginx/sites-available/dexarmarket /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```
**Solution 4: Verify nginx root path**
```bash
sudo cat /etc/nginx/sites-available/dexarmarket | grep root
```
Should show: `root /var/www/dexarmarket/browser;`
## Error: 502 Bad Gateway
### This means the API backend (https://api.dexarmarket.ru:445) is unreachable
**Solution 1: Check if API is running**
```bash
# From Ubuntu server:
curl -v https://api.dexarmarket.ru:445/ping
# If this fails, your API backend is down!
```
**Solution 2: Port 445 is blocked**
Port 445 is typically blocked by many firewalls because it's used for SMB file sharing.
**Check from browser console (F12):**
- Open browser Developer Tools (F12)
- Go to Console tab
- Look for errors like: `net::ERR_CONNECTION_REFUSED` or `net::ERR_SSL_PROTOCOL_ERROR`
**Possible fixes:**
- Use standard port 443 for HTTPS
- Or use port 8443, 8080, or other non-standard but common ports
- Configure firewall to allow port 445
**Solution 3: CORS issues**
The API must have CORS headers allowing requests from `https://dexarmarket.ru`
Check API response headers:
```bash
curl -v -H "Origin: https://dexarmarket.ru" https://api.dexarmarket.ru:445/ping
```
Should include headers like:
```
Access-Control-Allow-Origin: https://dexarmarket.ru
```
**Solution 4: SSL Certificate issues**
```bash
# Test with SSL verification disabled
curl -k https://api.dexarmarket.ru:445/ping
# If this works but normal curl doesn't, SSL cert is invalid
```
## Still Not Working?
### Get detailed error information:
**1. Browser Console (JavaScript errors)**
```
F12 → Console tab
Look for red errors
```
**2. Browser Network Tab (Failed requests)**
```
F12 → Network tab
Reload page
Look for red (failed) requests
Click on failed request to see details
```
**3. Nginx Error Log (Server-side errors)**
```bash
sudo tail -50 /var/log/nginx/error.log
```
**4. Nginx Access Log (See what requests come in)**
```bash
sudo tail -50 /var/log/nginx/access.log
```
**5. Test Build Locally**
```bash
cd F:\dx\marketplace\Dexarmarket\dist\dexarmarket\browser
python -m http.server 8000
# Visit http://localhost:8000
```
If local test works, the issue is with deployment, not the build.
## Common Mistakes
❌ **Uploading to wrong directory**
- Correct: `/var/www/dexarmarket/browser/`
- Wrong: `/var/www/dexarmarket/` (missing browser/)
❌ **Wrong permissions**
```bash
# Must be readable by www-data
sudo chown -R www-data:www-data /var/www/dexarmarket
sudo chmod -R 755 /var/www/dexarmarket
```
❌ **Nginx config not reloaded**
```bash
# After ANY change to nginx config:
sudo nginx -t
sudo systemctl reload nginx
```
❌ **Old files cached**
```bash
# Clear browser cache: Ctrl+Shift+R (hard refresh)
```
❌ **API port blocked**
- Port 445 is unusual and often blocked
- Consider using port 443 (standard HTTPS)
## Contact Information for Support
When asking for help, provide:
1. Output of `sudo nginx -t`
2. Last 30 lines of nginx error log: `sudo tail -30 /var/log/nginx/error.log`
3. Browser console errors (F12 → Console)
4. Result of `curl -v https://api.dexarmarket.ru:445/ping` from server
5. Screenshot of browser Network tab showing failed request

97
docs/backend/BACKEND-HANDOFF.md
View File

@@ -1,97 +0,0 @@
# Backend handoff — start here
Single entry point for a backend developer picking this up cold. Written 2026-08-18.
## 1. What this is
`marketplaces` is a multi-tenant marketplace platform frontend (Angular 22). The frontend is built and waiting; **there is no backend yet**. Every wire contract the backend needs to implement is already written and sitting in this directory — see [README.md](README.md) for the full index and build order.
## 1a. Multi-tenancy — the thing that shapes every endpoint
One deployed bundle serves **every customer domain**. There is no per-tenant build. The chain is:
1. [`TenantResolverService`](../../src/app/core/config/tenant-resolver.service.ts) derives a `tenantKey` from `window.location.hostname` (first label; `www.` skipped; localhost falls back to a configured key).
2. [`ApiConfigService`](../../src/app/core/config/api-config.service.ts) turns that key into the API base URL — via an explicit per-tenant map or a `{tenant}` URL template.
3. `ApiBootstrapProvider` fetches that tenant's **bootstrap config**, which drives branding, theme, locales, currencies, navigation, footer, and which pages exist.
4. nginx is `default_server` / `server_name _`, so any domain pointed at the server IP gets the same bundle and self-resolves.
**What this means for you:** the bootstrap endpoint is the single most important thing to build after auth. Every request must be tenant-scoped server-side, and a tenant must never be able to read another tenant's data — return `403`, not an empty result (see [TRACK-S §2](TRACK-S-SECURITY-RBAC-CONTRACT.md)). The frontend supplies the tenant identity from the hostname; the backend must treat that as an untrusted hint and derive real scope from the authenticated session.
Constraints already fixed by the frontend design (see the platform-vision facts in `docs/context/`): no marketplace-specific code or hardcoded marketplace data in the frontend; bootstrap carries only what is needed before app start (branding, languages, homepage layout, navigation, enabled widgets, footer pages) and **never** products, orders, cart, or users.
[PHASE-9](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md) covers the marketplace registry, domain attachment, and publish/revision model.
## 2. Read in this order
1. [README.md](README.md) — index of all contracts, build order, and what's deliberately excluded.
2. [PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md](PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) — start here. Everything after depends on the money model.
3. Phases 2→4 — the rest of the launch gate (orders, catalog, connectors).
4. [TRACK-S-SECURITY-RBAC-CONTRACT.md](TRACK-S-SECURITY-RBAC-CONTRACT.md) — **gates the launch.** Today the admin role model is decorative: nothing server-side enforces any permission. §8 covers per-marketplace bootstrap admin accounts and self-service sub-admin management.
5. [TRACK-A-ANALYTICS-CONTRACT.md](TRACK-A-ANALYTICS-CONTRACT.md) — longest lead time, start it in parallel with Phase 1.
6. Phases 5→10 — post-launch-gate.
7. [PARTNER-PROVISIONING-API-CONTRACT.md](PARTNER-PROVISIONING-API-CONTRACT.md) — the inbound partner API. Read it **before implementing Phase 1**, not after: it adds `RoutingContext` to `CheckoutSession`/`PaymentIntent`/`Payment` ([Phase 1 §6.5](PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md)) and two levels above `Marketplace` ([Phase 9 §1](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md)). Building the partner API itself can wait; carrying its routing dimension in the payments tables cannot.
[../../BACKEND-API-REFERENCE.md](../../BACKEND-API-REFERENCE.md) documents the *current* live API surface (legacy endpoints, error envelope, mock-only areas). New endpoints use `/api/v2/...` namespaces; legacy endpoints are not being migrated.
## 3. Auth — read before writing any endpoint
Auth is no longer part of this repo. It lives in `@marketplaces/auth`, published from [vitanovaPackages](https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git). See [../PACKAGES-USAGE.md](../PACKAGES-USAGE.md) for the full client surface. What matters on the backend side:
**Two mechanisms exist client-side.**
- **Telegram QR/session (live).** Endpoints under `{authApiUrl}/users/sessions` — `POST` to create, `GET /{id}` to poll, `DELETE /{id}` to log out. Both customer and admin login call the *same* endpoints; only client-side storage differs. The response shape is normalized permissively client-side (many key spellings accepted), but a clean implementation should return `{ webSessionID, user: { userId, username, firstName, lastName }, status, expiresAt }`.
- **Ed25519 challenge/response (not built).** `GET /api/admin/auth/challenge`, `POST /api/admin/auth/verify`, `POST /api/admin/auth/refresh`, `POST /api/admin/auth/logout`. Contracts in [TRACK-S](TRACK-S-SECURITY-RBAC-CONTRACT.md) and the package's `ed25519/models/auth-api.model.ts`. Until these ship, the client shows a `backend-unavailable` screen — nothing is mocked.
**The critical gap:** the session API has no concept of "admin." The frontend cannot distinguish an admin session from a customer one — it only chooses where to *store* the result. **Every admin endpoint must independently verify authorization server-side.** Client-side guards are UI convenience, never security. This is the single most serious open issue in the system.
Admin requests carry `AdminWebSessionID: <sessionId>` (and `Authorization: Bearer <token>` once admin JWTs exist) on paths containing `/admin/`, `/backoffice/`, `/builder/`, `/media/`.
## 4. Environment / infrastructure state
Dev server `213.21.246.138` (user `seto`, sudo, SSH key provided separately).
| Thing | State |
|---|---|
| nginx 1.24 | **Installed, running.** Config at `/etc/nginx/sites-enabled/marketplaces-dev.conf`. Serves frontend from `/srv/marketplaces/current/frontend`, backoffice from `/srv/marketplaces/current/backoffice`, proxies `/api/` → `127.0.0.1:8080`. `/health` returns `ok`. |
| Go toolchain | Installed (`/usr/local/bin/go`). |
| Backend service on :8080 | **Not running.** Nothing is listening. `/srv/marketplaces/current/api` is an empty shell. nginx's `/api/` proxy currently 502s. |
| PostgreSQL | **Installed but inactive.** Needs starting, a database, a user, and schema before anything works. |
| Shared packages | `@marketplaces/auth` installs over plain git from a release branch — no registry, token, or tunnel needed. `npm install` works out of the box. |
| Verdaccio (npm registry) | Running in Docker on port 4873, but **superseded and unused** — nothing depends on it. See [../PACKAGE-EXTRACTION.md](../PACKAGE-EXTRACTION.md) §5. |
| Firewall (ufw) | Active. 80/tcp, 443/tcp, OpenSSH. |
| TLS / certbot | **Not installed.** No certificates. Everything is plain HTTP today. For multi-tenant this is real work: every customer domain needs a certificate (per-domain issuance, or a wildcard if all tenants sit under one apex). |
| DNS / dynamic subdomains | **Not set up.** No domain currently points at the server (reverse DNS is the provider default `silky-bronze.ptr.network`). No wildcard record, no per-tenant subdomain automation, no Hostinger DNS integration. The *application* is fully multi-tenant (§1a) — this is the missing infrastructure underneath it. [PHASE-9](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md) specifies the target. |
| Frontend deploy (CD) | **None.** Pushing to `main` deploys nothing. `architecture-governance.yml` builds and checks boundaries but has no deploy step, and nothing writes to `/srv/marketplaces/current/frontend`. Deploys are manual today. |
| CI runner | None on this server; `sources.vitanova.network` CI runs elsewhere. |
## 5. To get a working dev environment
Nothing here is done yet — this is the setup a backend dev does on day one.
1. Start and configure PostgreSQL; create the database and application user.
2. Design the schema from the Phase 1–4 contracts (schema design is explicitly the backend's own call — the contracts specify entities, endpoints, and invariants, never tables). Tenant scoping belongs in the schema from day one; retrofitting it is painful.
3. Build the API service, listen on `127.0.0.1:8080`. nginx already proxies `/api/` to it.
4. Implement the **bootstrap config endpoint** (§1a) — without it the frontend cannot render for any tenant.
5. Implement the Telegram session endpoints — the login flow is fully built client-side and blocked only on these.
6. Implement `GET /api/identity/v1/session/permissions` ([TRACK-S §2](TRACK-S-SECURITY-RBAC-CONTRACT.md)) — frontend route guards derive from it.
7. Seed per-marketplace bootstrap admins ([TRACK-S §8](TRACK-S-SECURITY-RBAC-CONTRACT.md)): login = marketplace slug, password = `{slug}2026$`, `mustChangePassword: true`.
Steps 4–6 unblock the entire frontend. Everything after is feature work.
## 6. Frontend deploy
```bash
git clone <marketplaces repo>
npm install # pulls @marketplaces/auth over git, no credentials needed
npm run build # -> dist/dexarmarket
```
Angular 22, Node 20+. nginx serves `/srv/marketplaces/current/frontend`, so deploying means copying `dist/dexarmarket` there — **manually, today.** There is no CD pipeline. Because of the multi-tenant design (§1a), one such deploy updates every domain at once.
## 7. Known open decisions
- Registry reachability for CI (reverse proxy + TLS, or a different registry entirely).
- ~~Backend ownership.~~ Answered 2026-08-18: implemented by a separate backend developer against this contract set.
- Additional payment providers (wallets, BNPL) — [Phase 7 §4](PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md).
- Per-connector marketplace adapters — written per partner at onboarding, [Phase 4 §8](PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md).
- Backfill of `Company`/`Project`/`PaymentPoint` for existing marketplaces — sequence specified in [Phase 9 §1.2](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md), not yet scheduled.

272
docs/backend/FRONTEND-API-SURFACE-COMPLETE.md
View File

@@ -1,272 +0,0 @@
# Complete Frontend API Surface — Master Endpoint List
Generated 2026-08-18 directly from source (every `this.http.get/post/patch/put/delete` call across `src/app/core/`, `src/app/features/admin/`, `src/app/services/api.service.ts`). This is not a design document — it is a **census**: every endpoint this codebase currently calls or will call once its gateway swap goes live, in one place, cross-referenced against the contracts that already exist.
**Why this exists.** The individual Phase/Track contracts in this directory each cover one domain well. Nothing until now listed the *entire* surface in one pass, so a backend dev building against these docs had no way to see what's fully specified, what's inferred-and-needs-confirmation, and what has no contract at all. This closes that gap.
**Status legend**
| Status | Meaning |
|---|---|
| ✅ Specified | Exact shape exists in a Phase/Track contract doc. Build as written. |
| ⚠️ Inferred | Endpoint follows this codebase's own REST conventions (path pattern, verb) but no contract doc states it explicitly. Flagged in source with a comment at the call site. **Confirm or correct before building — do not treat as final.** |
| ❌ Undocumented | Legacy endpoint, no contract anywhere, still called by `api.service.ts`. Will be replaced when the corresponding `/api/v2` migration lands (Track N) — do not invest in these long-term, but they are live today. |
---
## 1. Legacy surface (still called today, no `/api/v2` contract)
These come from `BACKEND-API-REFERENCE.md`, not `docs/backend/`. Base URL is `environment.localhostApiUrl` / tenant-resolved; `qrBaseUrl` is a separate provider base for QR-specific calls.
| Method | Path | Called from | Status |
|---|---|---|---|
| GET | `/ping` | `api.service.ts` | ❌ Undocumented — health check |
| GET | `/category` | `api.service.ts`, `api-category.repository.ts` | ❌ Undocumented — full category tree |
| GET | `/category/{categoryID}` | `api.service.ts` | ❌ Undocumented — one category + its items |
| GET | `/items/{itemID}` | `api.service.ts` | ❌ Undocumented — single item detail |
| GET | `/searchitems` | `api.service.ts` | ❌ Undocumented — search |
| GET | `/items/randomitems` | `api.service.ts` | ❌ Undocumented — related/random items |
| POST | `/websession/{sessionId}` | `api.service.ts` | ❌ Undocumented — sync cart to a Telegram web session |
| POST | `/items/{itemID}/callback` | `api.service.ts` | ❌ Undocumented — "call me back" request |
| POST | `/items/{itemID}/questiion` | `api.service.ts` | ❌ Undocumented — product Q&A (note: `questiion` typo is load-bearing, do not silently "fix" without checking the live backend uses the same typo) |
| POST | `/items/{itemID}/notify-me` | `api.service.ts` | ❌ Undocumented — back-in-stock subscription |
| POST | `/purchase-email` | `api.service.ts` | ❌ Undocumented — post-purchase email collection |
| POST | `{qrBaseUrl}/qr` | `api.service.ts` | ❌ Undocumented — direct QR payment creation |
| POST | `/cart` | `api.service.ts` | ❌ Undocumented — legacy payment creation, client-sent `amount` (superseded by §2 below for new checkout flow; **still live** for any caller not yet migrated) |
| GET | `{qrBaseUrl}/qr/dynamic/{partnerId}/{qrId}` | `api.service.ts` | ❌ Undocumented — QR payment status poll |
| GET | `{qrBaseUrl}/card/{partnerId}/{orderId}` | `api.service.ts` | ❌ Undocumented — card payment status poll |
| POST | `/orders` | `api.service.ts` | ❌ Undocumented — records a paid cart as a backoffice order, fire-and-forget |
**Recommendation:** these 15 need their own contract doc if they are staying, or a deprecation timeline if `/api/v2/storefront/*` replaces them. Right now they are simply undocumented and live — the single biggest gap in `docs/backend/`.
---
## 2. Storefront checkout & cart — ✅ Specified
Contract: [PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md](PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) §5.2, [PHASE-6-CART-CHECKOUT-CONTRACT.md](PHASE-6-CART-CHECKOUT-CONTRACT.md) §3, §5.
| Method | Path | Called from |
|---|---|---|
| GET | `/api/v2/storefront/cart` | `server-cart-api.gateway.ts` |
| POST | `/api/v2/storefront/cart/lines` | `server-cart-api.gateway.ts` |
| PATCH | `/api/v2/storefront/cart/lines/{lineId}` | `server-cart-api.gateway.ts` |
| DELETE | `/api/v2/storefront/cart/lines/{lineId}` | `server-cart-api.gateway.ts` |
| POST | `/api/v2/storefront/checkout` | `server-cart-api.gateway.ts`, `api.service.ts` (two different callers, same contract) |
| POST | `/api/v2/storefront/payments/intents` | `api.service.ts` |
## 3. Pricing — ✅ Specified
Contract: [PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md](PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) §3.1.
| Method | Path | Called from |
|---|---|---|
| GET | `/api/v2/pricing/fx-quote?base=&quote=` | `fx-quote-api.gateway.ts` |
## 4. Identity & permissions — ✅ Specified
Contracts: [PHASE-8-IDENTITY-MESSAGING-CONTRACT.md](PHASE-8-IDENTITY-MESSAGING-CONTRACT.md) §2, [TRACK-S-SECURITY-RBAC-CONTRACT.md](TRACK-S-SECURITY-RBAC-CONTRACT.md) §2.
| Method | Path | Called from |
|---|---|---|
| GET | `/api/identity/v1/vk/authorize` | `vk-id-api.gateway.ts` |
| POST | `/api/identity/v1/vk/callback` | `vk-id-api.gateway.ts` |
| GET | `/api/identity/v1/session/permissions` | `permission-api.gateway.ts` |
## 5. Team / RBAC — mixed
Contract: [TRACK-S-SECURITY-RBAC-CONTRACT.md](TRACK-S-SECURITY-RBAC-CONTRACT.md) §8.
| Method | Path | Called from | Status |
|---|---|---|---|
| GET | `/api/admin/v2/audit` | `permission-api.gateway.ts`, `admin-users-api.gateway.ts?actor=` | ✅ Specified |
| POST | `/api/admin/v2/team/invite` | `admin-users-api.gateway.ts` | ✅ Specified |
| GET | `/api/admin/v2/team?marketplaceId=` | `admin-users-api.gateway.ts` | ✅ Specified |
| PATCH | `/api/admin/v2/team/{userId}` | `admin-users-api.gateway.ts` | ✅ Specified |
| DELETE | `/api/admin/v2/team/{userId}` | (interface exists, not yet called) | ✅ Specified |
| GET | `/api/admin/v2/team/roles` | `admin-users-api.gateway.ts` | ⚠️ Inferred |
| GET | `/api/admin/v2/team/invitations` | `admin-users-api.gateway.ts` | ⚠️ Inferred |
| GET | `/api/admin/v2/team/{userId}/sessions` | `admin-users-api.gateway.ts` | ⚠️ Inferred |
| PATCH | `/api/admin/v2/team/{userId}/status` | `admin-users-api.gateway.ts` | ⚠️ Inferred |
| DELETE | `/api/admin/v2/team/invitations/{id}` | `admin-users-api.gateway.ts` | ⚠️ Inferred |
| DELETE | `/api/admin/v2/team/sessions/{sessionId}` | `admin-users-api.gateway.ts` | ⚠️ Inferred |
## 6. Orders & notifications — ✅ Specified
Contract: [PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md](PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md).
| Method | Path | Called from |
|---|---|---|
| GET | `/api/admin/v2/orders?marketplaceId=&status=&source=&page=&pageSize=` | `admin-orders-api.gateway.ts` |
| GET | `/api/admin/v2/orders/{id}` | `admin-orders-api.gateway.ts` |
| PATCH | `/api/admin/v2/orders/{id}/status` | `admin-orders-api.gateway.ts` |
| POST | `/api/admin/v2/orders/{id}/refund-request` | `admin-orders-api.gateway.ts` (note: gateway calls this `refund-request`; interface method is named `requestRefund` — same endpoint) |
| POST | `/api/admin/v2/orders/{id}/notes` | `admin-orders-api.gateway.ts` |
| POST | `/api/admin/v2/orders/{id}/archive` | `admin-orders-api.gateway.ts` |
| POST | `/api/admin/v2/orders/{id}/restore` | `admin-orders-api.gateway.ts` |
| DELETE | `/api/admin/v2/orders/{id}` | `admin-orders-api.gateway.ts` |
| GET | `/api/admin/v2/notifications?marketplaceId=&unreadOnly=&eventType=` | `admin-notifications-api.gateway.ts` |
| PATCH | `/api/admin/v2/notifications/{id}/read` | `admin-notifications-api.gateway.ts` |
| PATCH | `/api/admin/v2/notifications/read-all` | `admin-notifications-api.gateway.ts` | ⚠️ Inferred (bulk mark-read not in contract) |
## 7. Catalog / offers — ✅ Specified + ⚠️ Inferred
Contract: [PHASE-3-CATALOG-OFFER-FULFILLMENT-CONTRACT.md](PHASE-3-CATALOG-OFFER-FULFILLMENT-CONTRACT.md) §7.
| Method | Path | Called from | Status |
|---|---|---|---|
| GET | `/api/admin/v2/products?marketplaceId=&status=&search=&page=&pageSize=` | `admin-products-api.gateway.ts` | ✅ Specified |
| GET | `/api/admin/v2/products/{id}` | `admin-products-api.gateway.ts` | ✅ Specified |
| POST | `/api/admin/v2/products` | `admin-products-api.gateway.ts` | ✅ Specified |
| PATCH | `/api/admin/v2/products/{id}` | `admin-products-api.gateway.ts` | ✅ Specified |
| GET | `/api/admin/v2/offers?productId=&sellerId=&status=` | `offer-api.gateway.ts` | ✅ Specified |
| POST | `/api/admin/v2/offers/{id}/publish` | `offer-api.gateway.ts` | ✅ Specified — 422 + `details[]` on executability failure |
| GET | `/api/admin/v2/offers/lookup?sku=&sellerSku=&externalId=` | `offer-api.gateway.ts` | ✅ Specified |
| GET | `/api/admin/v2/products/categories` | `admin-products-api.gateway.ts` | ⚠️ Inferred |
| DELETE | `/api/admin/v2/products/{id}` | `admin-products-api.gateway.ts` | ⚠️ Inferred |
| POST | `/api/admin/v2/products/{id}/duplicate` | `admin-products-api.gateway.ts` | ⚠️ Inferred |
| POST | `/api/admin/v2/products/{id}/archive` | `admin-products-api.gateway.ts` | ⚠️ Inferred |
| POST | `/api/admin/v2/products/{id}/restore` | `admin-products-api.gateway.ts` | ⚠️ Inferred |
| GET | `/api/admin/v2/offers/{offerId}/inventory` | `offer-api.gateway.ts` | ⚠️ Inferred |
## 8. Categories — ✅ Specified (pre-existing, F29 done before this session)
| Method | Path | Called from |
|---|---|---|
| GET | `{baseUrl}` (categories collection) | `admin-categories-api.gateway.ts` |
| GET | `{baseUrl}/{id}` | `admin-categories-api.gateway.ts` |
| POST | `{baseUrl}` | `admin-categories-api.gateway.ts` |
| PUT | `{baseUrl}/{id}` | `admin-categories-api.gateway.ts` |
| DELETE | `{baseUrl}/{id}` | `admin-categories-api.gateway.ts` |
| POST | `{baseUrl}/{id}/restore` | `admin-categories-api.gateway.ts` |
| GET | `{baseUrl}/slug-taken` | `admin-categories-api.gateway.ts` |
## 9. Seller portal — mixed
Contract: [PHASE-5-SELLER-PORTAL-CONTRACT.md](PHASE-5-SELLER-PORTAL-CONTRACT.md) §3.
| Method | Path | Called from | Status |
|---|---|---|---|
| GET | `/api/seller/v1/finance/settlements` | (contract-only, no current caller) | ✅ Specified |
| GET | `/api/admin/v2/sellers` | `seller-api.gateway.ts` | ⚠️ Inferred — contract only specifies the caller's own `GET /api/seller/v1/profile`, not an admin list-all |
| GET | `/api/admin/v2/sellers/{sellerId}/team` | `seller-api.gateway.ts` | ⚠️ Inferred — contract's `GET /api/seller/v1/team` is session-scoped, not parameterized |
## 10. Payments, refunds, reconciliation, settlements — ✅ Specified
Contract: [PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md](PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md).
| Method | Path | Called from |
|---|---|---|
| GET | `/api/admin/v2/orders/{orderId}/refunds` | `finance-api.gateway.ts` |
| GET | `/api/admin/v2/reconciliation/queue` | `finance-api.gateway.ts` |
| POST | `/api/admin/v2/reconciliation/{id}/resolve` | `finance-api.gateway.ts` |
| GET | `/api/admin/v2/finance/settlements?sellerId=` | `finance-api.gateway.ts` |
## 11. Tenant registry — mixed
Contract: [PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md).
| Method | Path | Called from | Status |
|---|---|---|---|
| GET | `/api/admin/v2/marketplaces/{id}/lifecycle` | `marketplace-api.gateway.ts` | ✅ Specified |
| GET | `/api/admin/v2/marketplaces` (list) | `marketplace-api.gateway.ts` | ⚠️ Inferred — contract specifies `POST` for creation, not the list `GET` |
| GET | `/api/admin/v2/marketplaces/{id}/domains` | `marketplace-api.gateway.ts` | ⚠️ Inferred |
## 12. Connector framework — mixed
Contract: [PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md](PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md) §7-8.
| Method | Path | Called from | Status |
|---|---|---|---|
| GET | `/api/admin/v2/integrations` | `connector-api.gateway.ts` | ✅ Specified |
| PATCH | `/api/admin/v2/integrations/{id}` | `connector-api.gateway.ts` (pause/resume via `status` field) | ✅ Specified |
| GET | `/api/admin/v2/integrations/{connectorId}/dead-letter` | `connector-api.gateway.ts` | ⚠️ Inferred — contract specifies replay, not the list |
| POST | `/api/admin/v2/integrations/{connectorId}/dead-letter/{id}/replay` | `connector-api.gateway.ts` | ✅ Specified — path corrected 2026-08-18; the gateway initially omitted `connectorId`, caught while writing this doc, fixed in the same pass |
## 13. Content modules (Gorbushka-class) — ⚠️ Mostly inferred
Contract: [PHASE-10-CONTENT-MODULES-CONTRACT.md](PHASE-10-CONTENT-MODULES-CONTRACT.md) §2.
| Method | Path | Called from | Status |
|---|---|---|---|
| POST | `/api/admin/v2/content/rent-listings/{id}/leads` | `mall-content-api.gateway.ts` | ✅ Specified |
| GET | `/api/admin/v2/content/shops` | `mall-content-api.gateway.ts` | ⚠️ Inferred |
| GET | `/api/admin/v2/content/shop-categories` | `mall-content-api.gateway.ts` | ⚠️ Inferred |
| GET | `/api/admin/v2/content/floors` | `mall-content-api.gateway.ts` | ⚠️ Inferred |
| GET | `/api/admin/v2/content/floors/{floorId}/pins` | `mall-content-api.gateway.ts` | ⚠️ Inferred |
| GET | `/api/admin/v2/content/rent-listings` | `mall-content-api.gateway.ts` | ⚠️ Inferred |
## 14. Analytics — ✅ Specified
Contract: [TRACK-A-ANALYTICS-CONTRACT.md](TRACK-A-ANALYTICS-CONTRACT.md) §1.
| Method | Path | Called from |
|---|---|---|
| POST | `/api/v2/storefront/analytics/events` | `analytics-api.gateway.ts` |
## 15. Transactions, monitoring, moderation — ❌ No contract doc exists
These three domains have gateways calling `/api/admin/v2/{resource}` by convention only. No Phase/Track doc covers any of them.
| Method | Path | Called from |
|---|---|---|
| GET | `/api/admin/v2/transactions` | `admin-transactions-api.gateway.ts` |
| POST | `/api/admin/v2/transactions/{id}/retry` | `admin-transactions-api.gateway.ts` |
| PATCH | `/api/admin/v2/transactions/{id}` | `admin-transactions-api.gateway.ts` |
| GET | `/api/admin/v2/monitoring/events` | `admin-monitoring-api.gateway.ts` |
| GET | `/api/admin/v2/monitoring/queues` | `admin-monitoring-api.gateway.ts` |
| GET | `/api/admin/v2/monitoring/webhooks` | `admin-monitoring-api.gateway.ts` |
| GET | `/api/admin/v2/moderation/reviews` | `admin-moderation-api.gateway.ts` |
| GET | `/api/admin/v2/moderation/reviews/{id}` | `admin-moderation-api.gateway.ts` |
| PATCH | `/api/admin/v2/moderation/reviews/{id}` | `admin-moderation-api.gateway.ts` (status/visible/pinned/featured — 4 different PATCH bodies, same endpoint) |
| POST | `/api/admin/v2/moderation/reviews/{id}/notes` | `admin-moderation-api.gateway.ts` |
| DELETE | `/api/admin/v2/moderation/reviews/{id}` | `admin-moderation-api.gateway.ts` |
| GET | `/api/admin/v2/moderation/reports` | `admin-moderation-api.gateway.ts` |
| PATCH | `/api/admin/v2/moderation/reports/{id}` | `admin-moderation-api.gateway.ts` |
| GET | `/api/admin/v2/dashboard/metrics` | `admin-dashboard-metrics-api.gateway.ts` |
**Recommendation: these are the highest-priority gap.** Three full admin domains with real UI and real gateways, zero backend contract. Whoever picks up Phase 5/7 next should write these as proper contract docs — the endpoint shapes above are a starting point, not a spec.
## 16. Partner provisioning API — ✅ Specified
Contract: [PARTNER-PROVISIONING-API-CONTRACT.md](PARTNER-PROVISIONING-API-CONTRACT.md) §4, §6. This is the one domain where the frontend gateway was built *from* the contract, not the other way around — no drift to reconcile.
| Method | Path | Called from |
|---|---|---|
| GET | `/api/partner/v1/companies/{companyId}/hierarchy?environment=` | `partner-hierarchy-api.gateway.ts` |
| GET | `/api/partner/v1/nodes/{nodeId}` | `partner-hierarchy-api.gateway.ts` |
| GET | `/api/partner/v1/nodes/lookup?externalReference=&environment=` | `partner-hierarchy-api.gateway.ts` |
| POST | `/api/partner/v1/companies/{companyId}/projects` | `partner-hierarchy-api.gateway.ts` |
| POST | `/api/partner/v1/projects/{projectId}/stores` | `partner-hierarchy-api.gateway.ts` |
| POST | `/api/partner/v1/stores/{storeId}/payment-points` | `partner-hierarchy-api.gateway.ts` |
| PATCH | `/api/partner/v1/nodes/{nodeId}/status` | `partner-hierarchy-api.gateway.ts` |
| POST | `/api/partner/v1/nodes/{nodeId}/disable` | `partner-hierarchy-api.gateway.ts` |
| GET | `/api/partner/v1/credentials?companyId=` | `partner-hierarchy-api.gateway.ts` |
| POST | `/api/partner/v1/credentials` | `partner-hierarchy-api.gateway.ts` |
| POST | `/api/partner/v1/credentials/{keyId}/rotate` | `partner-hierarchy-api.gateway.ts` |
| DELETE | `/api/partner/v1/credentials/{keyId}` | `partner-hierarchy-api.gateway.ts` |
## 17. Backoffice data & bootstrap — ✅ Specified elsewhere (not a Phase/Track doc, but stable)
| Method | Path | Called from |
|---|---|---|
| GET | `/api/backoffice/products` | `api-backoffice-data.provider.ts` |
| GET | `/api/backoffice/categories` | `api-backoffice-data.provider.ts` |
| GET | (tenant bootstrap URL) | `api-bootstrap.provider.ts` — see `BACKEND-HANDOFF.md` §1a |
---
## Summary counts
| Status | Count |
|---|---|
| ✅ Specified | 47 |
| ⚠️ Inferred (needs confirmation) | 24 |
| ❌ Undocumented (legacy) | 15 |
| **Total distinct endpoints called** | **86** |
## What backend needs to do with this
1. **Build the ✅ rows as written** — they match an existing contract doc exactly.
2. **Confirm or correct every ⚠️ row** — each one has a comment at its call site in source explaining the inference. Search the codebase for `Inferred` to find all 24 in place, with the reasoning right next to the code.
3. **Write a contract for §15** (transactions, monitoring, moderation) — real UI, real gateways, zero spec. Highest-priority gap in this whole list.
4. **Decide the fate of §1** — 15 legacy endpoints with no contract at all, still live. Either document them as a stable, permanent surface, or set a Track N migration date.

323
docs/backend/PARTNER-PROVISIONING-API-CONTRACT.md
View File

@@ -1,323 +0,0 @@
# Partner Provisioning API Contract — Merchant Hierarchy, Credentials, Routing
Cross-cutting contract. Partner-facing, **inbound**: external partners call us. Distinct from [Phase 4](PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md), which is outbound/ingest.
Depends on [Phase 1](PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) (payment state machine), [Phase 5](PHASE-5-SELLER-PORTAL-CONTRACT.md) (seller org), [Phase 9](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md) (marketplace registry), [Track S](TRACK-S-SECURITY-RBAC-CONTRACT.md) (keys, audit, rate limiting).
**Status: draft — level mapping decided (§10), two new entities required.**
Origin: a partner integration request (2026-08-18). **This contract is deliberately generic.** No partner name appears in any entity, field, endpoint, or status value. Partner-specific behaviour lives entirely in a `PartnerProfile` config row (§8). A second partner asking for the same thing must require zero schema and zero endpoint change.
---
## 1. Why this exists
Partners need to provision and manage their own merchant hierarchy programmatically, then have payments route unambiguously back to the correct leaf. Today we have no partner-facing write API at all, no entity above `Marketplace`, and payments carry no store dimension — reconciliation cannot attribute a payment to a store.
---
## 2. Hierarchy model
Four levels, fixed. Middle levels are **optional per partner**, never free-form depth.
```
Company -> Project -> Store -> PaymentPoint
```
```ts
type NodeLevel = 'company' | 'project' | 'store' | 'payment_point';
interface ProvisioningNode {
id: string; // stable, opaque, never reused
level: NodeLevel;
parentId: string | null; // null only for level 'company'
companyId: string; // denormalized root, present on every node
path: string[]; // ordered ancestor ids, root first, inclusive of self
environment: Environment;
status: NodeStatus;
externalReference: string; // partner's own id for this node
displayName: string;
createdAt: string; // ISO 8601
updatedAt: string; // ISO 8601
}
type Environment = 'TEST' | 'LIVE';
type NodeStatus = 'active' | 'suspended' | 'disabled';
```
### Invariants
1. `parentId` must be the immediately preceding **enabled** level in the partner's profile. Skipping a required level is `422`.
2. `companyId` and `environment` are inherited from the parent and are immutable.
3. `externalReference` is unique per `(companyId, environment, level)`. Collision is `409`.
4. `path` is server-computed. Never accepted from the client.
5. A node cannot be re-parented. Ever. Move = disable + create new.
6. Creating any node **never** enables a financial capability, never creates a payment, never opens a settlement account. Financial enablement is a separate, explicitly approved flow outside this contract.
### Status semantics
| Status | Meaning | Accepts payments | Reversible |
|---|---|---|---|
| `active` | normal | yes | — |
| `suspended` | temporarily halted | no | yes, back to `active` |
| `disabled` | terminal | no | no |
- Disabling a node cascades `disabled` to every descendant, atomically.
- Suspending a node cascades `suspended` to descendants; un-suspending restores **only** descendants that were suspended by that same cascade (tracked by cascade id), never descendants suspended independently.
- `disabled` never returns to any other status. Re-provisioning creates a new node with a new id.
---
## 3. Environments
`TEST` and `LIVE` are a hard partition:
- Separate credentials. A `TEST` key can never address a `LIVE` node, and vice versa — cross-environment access is `403`, not `404`.
- Node ids never collide across environments and are never transferable.
- `externalReference` uniqueness is scoped per environment — the same partner reference may exist once in each.
- No data, config, or hierarchy copy between environments in this API.
---
## 4. Endpoints
Namespace `/api/partner/v1/`. All timestamps ISO 8601 UTC.
### 4.1 Write
```
POST /api/partner/v1/companies/{companyId}/projects
POST /api/partner/v1/projects/{projectId}/stores
POST /api/partner/v1/stores/{storeId}/payment-points
PATCH /api/partner/v1/nodes/{nodeId}/status -- { status: 'active' | 'suspended', reason?: string }
POST /api/partner/v1/nodes/{nodeId}/disable -- terminal, cascading
```
Creation body:
```ts
interface CreateNodeRequest {
externalReference: string;
displayName: string;
metadata?: Record<string, string>; // opaque to us, echoed back, never interpreted
}
```
### 4.2 Read
```
GET /api/partner/v1/nodes/{nodeId}
GET /api/partner/v1/companies/{companyId}/hierarchy?environment=TEST|LIVE&status=...&depth=...
GET /api/partner/v1/nodes/lookup?externalReference=...&level=...&environment=...
GET /api/partner/v1/companies/{companyId}/audit?from=...&to=...&cursor=...
```
- `hierarchy` returns the full tree with current statuses, one call, cursor-paginated over nodes when large.
- `lookup` is the `externalReference` resolver. Returns `404` when unmatched — never a partial or fuzzy match.
- Read endpoints are the partner's own verification surface for what was actually created. They read from the same store as writes — never a cache that can lag behind a create.
### 4.3 Not in this API
Company creation. A `Company` is created by us during commercial onboarding, out of band. Partners provision **inside** a company they already have.
---
## 5. Idempotency
Every `POST` requires an `Idempotency-Key` header. `PATCH` status changes accept one optionally.
```
Idempotency-Key: <partner-generated, opaque, <=255 chars>
```
Rules, in order:
1. Key scope is `(partnerId, endpoint, key)`. Two partners may use the same key string without interference.
2. Same key + byte-identical request body → the **original stored response** is replayed, with the original status code. No new node.
3. Same key + different body → `409 Conflict`, error code `idempotency_key_reuse`. Nothing is created or modified.
4. Retention: 24 hours from first use. After expiry the key is free again — partners must not rely on replay beyond 24h.
5. A request that arrives while an identical key is still in flight returns `409` with `idempotency_request_in_progress`. Partner retries after a short backoff.
6. **No partial hierarchy.** A creation request either commits its node fully or commits nothing. If a partner creates project → store → payment point in three calls and the third fails, the first two remain — that is three operations, each atomic. A single call is never partially applied.
Body comparison uses a canonical hash (sorted keys, normalized whitespace) so key ordering does not cause a false `409`.
---
## 6. Credentials and key management
### 6.1 Model — answered generically
Partners asked whether a credential is per-company, per-project, or per-store. **All three, one mechanism:** a credential is bound to **any single node**, and its authority is that node's subtree.
```ts
interface PartnerCredential {
partnerId: string;
keyId: string;
scopeNodeId: string; // credential may act on this node and all descendants
environment: Environment;
algorithm: 'ed25519' | 'rsa-pss-sha256';
publicKey: string; // PEM or base64 raw, per algorithm
status: 'active' | 'rotating' | 'revoked';
createdAt: string;
expiresAt?: string;
}
```
- Partner generates the keypair. The **private key never leaves the partner** and is never transmitted to us, never logged, never accepted by any endpoint.
- Partner registers the public key; we return `partnerId` + `keyId`.
- Authority is strictly the `scopeNodeId` subtree. Any request touching a node outside it is `403`.
- A credential can never widen its own scope, register another credential at a wider scope, or create a node above its scope.
### 6.2 Endpoints
```
POST /api/partner/v1/credentials -- register public key, returns partnerId + keyId
GET /api/partner/v1/credentials
POST /api/partner/v1/credentials/{keyId}/rotate -- register successor public key, overlap window
DELETE /api/partner/v1/credentials/{keyId} -- revoke, effective immediately
```
- **Rotation:** the successor key is registered while the current key stays valid for a bounded overlap (default 7 days, configurable per profile). Both keys verify during overlap. The predecessor auto-revokes at window end.
- **Revocation is immediate and irreversible.** In-flight requests signed with a revoked key fail. Revoking a credential does not touch any node it created.
- Registration, rotation, and revocation each emit a Track S audit event. Key lifecycle actions are always attributable to a named actor.
### 6.3 Request authentication
Requests are signed, not bearer-token'd:
- Signature covers: HTTP method, path, canonical body hash, `Idempotency-Key` (when present), and a timestamp.
- Timestamp skew tolerance ±5 minutes. Outside that → `401`.
- Signature replay within the window is rejected by nonce tracking → `401`.
- `keyId` travels in the signature header so we select the right public key without trusting the body.
---
## 7. Payment routing
Every payment, callback, refund, and settlement row carries a routing context.
```ts
interface RoutingContext {
companyId: string;
routingPath: string[]; // ordered node ids, root -> leaf, resolves to exactly one leaf
leafNodeId: string; // convenience: last element of routingPath
environment: Environment;
merchantReference: string; // partner-supplied, opaque to us, echoed on every related event
providerPaymentId: string; // our payment id, stable, unique
}
```
### Invariants
1. `routingPath` must resolve to exactly one leaf node. Ambiguous or unresolvable → the payment is rejected at creation, never accepted and reconciled later.
2. `merchantReference` is stored verbatim and echoed on **every** downstream event: payment status change, refund, settlement line, webhook.
3. A payment whose leaf node is `suspended` or `disabled` is rejected at creation.
4. Routing context is immutable for the life of the payment. Node status changes afterwards never rewrite it.
### Contract amendments this requires
`RoutingContext` must be added to:
- [Phase 1](PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) — `Payment`, `PaymentEvent`, checkout session
- [Phase 7](PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md) — refund, reconciliation row, settlement line
**Do this before backend implements Phase 1.** Retrofitting a routing dimension onto a live payments table is materially more expensive than adding it now.
Partner-facing serialization uses the partner's own field names (§8) — `routingPath` is emitted as `projectId`/`storeId`/`paymentPointId` for a partner using those terms, without the core model knowing those words.
---
## 8. Partner profile — the only partner-specific surface
```ts
interface PartnerProfile {
partnerId: string;
requiredLevels: NodeLevel[]; // subset; 'company' and the leaf are always required
levelAliases: Record<NodeLevel, string>; // e.g. { project: 'Project', store: 'Store' }
routingFieldNames: Record<NodeLevel, string>; // e.g. { store: 'storeId' }
rateLimitTier: string;
keyRotationOverlapDays: number;
webhookFieldMap?: Record<string, string>;
}
```
A partner with no "project" concept omits it from `requiredLevels`; their stores hang directly off the company and the hierarchy still validates. A partner calling stores "branches" changes one alias. **Adding a partner is a config row, not a deployment.**
What is deliberately **not** configurable, because configurability here breaks reconciliation or safety:
- `NodeStatus` values and their transition rules
- Idempotency semantics
- Environment partitioning
- Signature scheme and skew tolerance
- The four-level ceiling
---
## 9. Operational requirements
| Requirement | Contract |
|---|---|
| OpenAPI | Machine-readable spec published per version, generated from the implementation, never hand-maintained |
| Sandbox | `TEST` environment is the sandbox. Same code path as `LIVE`, isolated data, no real money |
| Error codes | Stable string codes, documented, never renamed. HTTP status + `code` + human `message` + `requestId` |
| Rate limits | Per `partnerId`, per tier. `429` with `Retry-After`. Limits published in the spec, per Track S |
| Audit | Every write is an audit event: actor (`keyId`), action, target node, before/after status, `requestId`, timestamp. Immutable, queryable via §4.2 |
| Idempotency observability | `Idempotency-Replayed: true` response header when a stored response is replayed |
### Error codes
```
validation_failed 422
parent_not_found 404
level_skipped 422
external_reference_conflict 409
idempotency_key_reuse 409
idempotency_request_in_progress 409
scope_forbidden 403
environment_mismatch 403
node_disabled 409
signature_invalid 401
signature_expired 401
rate_limited 429
```
---
## 10. Mapping onto our model
Decided 2026-08-18.
| Partner level | Our entity | State |
|---|---|---|
| `company` | — | **New.** No entity above `Marketplace` exists today. Legal/commercial owner, created out of band (§4.3). |
| `project` | — | **New.** A product line, e.g. `marketplaces`. One company runs several. Not the same thing as a `Marketplace`. |
| `store` | `Marketplace` ([Phase 9](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md)) | Exists. Gains `companyId`, `projectId`, `externalReference`. |
| `payment_point` | — | **New.** An acceptance channel: one payment method bound to one store. Many per store. |
### 10.1 PaymentPoint = acceptance channel
A `PaymentPoint` is a payment method enabled on a store, not a physical location and not a settlement account.
```ts
interface PaymentPointConfig {
method: PaymentMethod; // 'qr' | 'card', extensible
currencies: string[]; // ISO 4217 subset the channel accepts
providerAccountRef?: string; // opaque provider-side binding, set during financial enablement
}
```
Both current methods ship today — `src/app/pages/cart/cart.component.ts` (`PaymentMethod = 'qr' | 'card'`, separate create + status-poll paths per method). A store accepting both has two payment points.
Creating a payment point registers the channel. It does **not** enable it for real money — §2 invariant 6 still holds. Financial enablement sets `providerAccountRef` through a separate approved flow.
### 10.2 Seller is orthogonal
`Seller` ([Phase 5](PHASE-5-SELLER-PORTAL-CONTRACT.md)) is **not** a level in this hierarchy. A multi-seller marketplace is one `store` with many sellers underneath; seller-level settlement splitting happens in [Phase 7](PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md) reconciliation, after the payment has already been routed to the store. Putting `Seller` in the partner hierarchy would force every partner to model our multi-seller concept, which most will not have.
### 10.3 Consequences
1. Two new entities: `Company`, `Project`. Both are thin — id, name, `externalReference`, status, timestamps — and both sit above `Marketplace`.
2. `Marketplace` gains `companyId` + `projectId`. Existing marketplaces need a backfill company and project.
3. `PaymentPoint` is new and is what `routingPath` terminates at (§7).
4. §7's contract amendments to Phases 1 and 7 do not depend on any of the above — start them now.

256
docs/backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md
View File

@@ -1,256 +0,0 @@
# Phase 1 Backend Contract — Money, FX, Price Snapshot, Payment State Machine
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Phase 1 (Sprints 1.1–1.4) and [PRODUCT-PLAN-v3.1-GAP-ANALYSIS.md](../PRODUCT-PLAN-v3.1-GAP-ANALYSIS.md) §3.3/§3.5/§3.6.
**Status: unblocked (2026-08-17).** [BACKEND-API-REFERENCE.md §7](../../BACKEND-API-REFERENCE.md) previously marked the cart/payment call chain frozen. Per the delivery plan's Sprint 0.1 decision, the freeze is lifted — this contract can move to implementation. Backend ownership was answered 2026-08-18 — a separate backend developer builds against it.
This doc is the frontend's ask, in the same style as `BACKEND-API-REFERENCE.md`. It does not prescribe backend implementation (DB schema, service boundaries) — only the wire contract and the invariants the frontend needs to hold.
---
## 1. Why this exists
Current behaviour (`services/currency-rates.service.ts`, `pages/cart/cart.component.ts`):
- Currency conversion rates are typed by an admin into Admin Settings and persisted to browser `localStorage`. They never update and drift from market.
- The amount charged is computed **client-side** and sent as `CartPaymentRequest.amount` to `POST /cart`. The backend currently trusts this number.
- No record exists anywhere of which FX rate produced a given displayed price, or when it was captured.
Result: bank/NSPK settlement totals don't reconcile against order counts, because nothing on the backend can reconstruct *why* a given amount was charged. This document's contract exists to close that gap — it is the same complaint as Product Plan v3.1 §3.3/§3.8, and our own [§12.7](../../BACKEND-API-REFERENCE.md) raised it first.
---
## 2. Money representation
All money fields in every new endpoint below use minor units, never float.
```ts
interface Money {
amountMinor: number; // integer, no float. 4990 = 49.90 for a 2-decimal currency.
currency: string; // ISO 4217, e.g. "RUB" | "USD" | "EUR" | "AMD"
}
```
| Currency | Minor unit | Decimals |
|---|---|---|
| RUB | kopeck | 2 |
| USD | cent | 2 |
| EUR | cent | 2 |
| AMD | luma | 2 |
Rounding rule for any conversion: round half up to the currency's minor-unit precision, applied once, at the point of conversion — never re-rounded on redisplay.
---
## 3. FX Quote
### 3.1 Endpoint
```
GET /api/v2/pricing/fx-quote?base=RUB&quote=USD
```
```json
{
"quoteId": "fxq_8a3f1c2a",
"base": "RUB",
"quote": "USD",
"rate": 0.0108,
"source": "rapira",
"observedAt": "2026-08-20T09:14:00Z",
"expiresAt": "2026-08-20T09:19:00Z"
}
```
| Field | Notes |
|---|---|
| `quoteId` | Opaque, referenced by every `PriceSnapshot` that used this quote. |
| `rate` | `1 base = rate * quote`. Float is acceptable here — it's a market rate, not a money amount. |
| `source` | Adapter name. Frontend never hardcodes a provider; treat as an opaque label for display in the backoffice reconciliation panel. |
| `expiresAt` | TTL, provider-configurable. Frontend must not use an expired quote to display or charge. |
### 3.2 Stale-quote policy
- If the frontend holds a quote past `expiresAt`, it must re-fetch before checkout can proceed.
- If the rate source is unavailable, the backend decides: **block** (`503 SERVICE_UNAVAILABLE` with `error.code: "FX_SOURCE_UNAVAILABLE"`) or serve a configured fallback quote explicitly marked `"source": "fallback"`. Which policy applies is a tenant setting, not a frontend choice — see delivery-plan Sprint 0.1 decision on FX source.
- Outlier detection (e.g. a quote >X% off the previous one) is a backend concern; the frontend has no opinion on the threshold, only on obeying `expiresAt`.
---
## 4. PriceSnapshot
Created once, at checkout, immutable afterward. This is what makes a total explainable months later.
```ts
interface PriceSnapshot {
id: string;
offerId: string;
amount: Money; // price in the offer's base currency
displayAmount: Money; // price in the currency the customer checked out in
fxQuoteId: string | null; // null when displayAmount.currency === amount.currency
capturedAt: string; // ISO 8601
}
```
Rule: once a `PriceSnapshot` exists on an order line, it is never recalculated — not on rate update, not on currency-setting change, not on replay. An old order shows the price it was actually charged at.
---
## 5. Server-authoritative checkout amount
This is the contract change with the highest priority in Phase 1 — it removes the client-trusted `amount` field entirely.
### 5.1 Current (to be replaced)
```http
POST /cart
{ "amount": 4990, "currency": "RUB", "items": [{ "itemID": 101, "price": 4990, ... }], ... }
```
The backend trusts `amount` and each line's `price` as sent by the browser.
### 5.2 Target
```http
POST /api/v2/storefront/checkout
{
"offers": [{ "offerId": "off_9a1", "qty": 2 }],
"currency": "USD",
"deliveryOptionId": "del_standard"
}
```
```json
{
"checkoutSessionId": "chk_7f2e",
"lines": [
{
"offerId": "off_9a1",
"qty": 2,
"unitPrice": { "amountMinor": 5390, "currency": "USD" },
"lineTotal": { "amountMinor": 10780, "currency": "USD" },
"priceSnapshotId": "snap_3b1c"
}
],
"subtotal": { "amountMinor": 10780, "currency": "USD" },
"discount": { "amountMinor": 0, "currency": "USD" },
"delivery": { "amountMinor": 500, "currency": "USD" },
"total": { "amountMinor": 11280, "currency": "USD" },
"fxQuoteId": "fxq_8a3f1c2a",
"expiresAt": "2026-08-20T09:19:00Z"
}
```
**The frontend sends offer IDs and quantities. The backend computes every price, using the offer's live price and the current FX quote. No `amount` or `price` field is ever accepted from the client for anything that affects the charge.**
`POST /api/v2/storefront/payments/intents` then references `checkoutSessionId` only — the amount charged is read server-side from the checkout session, never re-sent by the client.
### 5.3 Total formula (must be reconstructable, per line)
```
order.total = sum(line.unitPrice * line.qty)
- discounts
+ delivery
+ taxes/fees (if applicable)
```
Backoffice must be able to render this formula, with the FX quote used, for any order — this is what Product Plan §7.2 asks for and what a bank reconciliation needs.
---
## 6. Payment state machine
### 6.1 States
```
PaymentIntent: created -> pending -> authorized/paid -> failed/cancelled
Payment: received -> confirmed -> captured/settled -> refunded/partially_refunded
Order: pending_payment -> paid -> processing -> fulfilled/completed
```
### 6.2 Required fields per transition
```ts
interface PaymentEvent {
id: string;
paymentIntentId: string;
fromState: string;
toState: string;
providerEventId: string; // idempotency key from the provider
providerTimestamp: string; // when the provider says it happened
receivedAt: string; // when our webhook received it
processedAt: string; // when our system finished processing it
}
```
No fixed delays anywhere in this chain. The frontend already complies with this (polls real provider status via `/qr/dynamic/{partnerId}/{qrId}` and `/card/{partnerId}/{orderId}` on an interval bounded by QR TTL) — this section documents the backend side of the same principle.
### 6.3 Webhook contract
```
POST /api/providers/v1/payments/{provider}/webhook
```
- Signature verification is mandatory; reject unsigned/invalid-signature payloads with `401`, do not silently accept.
- Idempotency key = `provider + providerEventId`. A repeated delivery of the same event must be a no-op — same `PaymentEvent` row, no second order, no second notification.
- On success, emit `payment.confirmed` / `payment.failed` onto the platform event bus (Phase 2) so Order creation is driven by the event, not by the webhook handler doing double duty.
### 6.4 Idempotent order creation
```
POST /api/admin/v2/orders (internal, from the payment-confirmation handler)
Idempotency-Key: <checkoutSessionId>
```
A retried call with the same `checkoutSessionId` must return the existing order, not create a second one. This is the mechanism that makes "double-click doesn't create two orders" true regardless of frontend debouncing.
### 6.5 Routing context
Added 2026-08-18. Full definition in [PARTNER-PROVISIONING-API-CONTRACT.md §7](PARTNER-PROVISIONING-API-CONTRACT.md).
```ts
interface RoutingContext {
companyId: string;
routingPath: string[]; // ordered node ids, root -> leaf
leafNodeId: string; // the payment point money is accepted at
environment: 'TEST' | 'LIVE';
merchantReference: string; // partner-supplied, opaque, echoed on every related event
providerPaymentId: string; // our payment id, stable, unique
}
```
`RoutingContext` is a **required** field on `CheckoutSession`, `PaymentIntent`, and `Payment`. `PaymentEvent` does not carry its own copy — it inherits via `paymentIntentId` — but every event **emitted** to the bus or to a partner must include the resolved context so consumers never need a second lookup.
Invariants:
1. Resolved and frozen at checkout-session creation. Immutable for the life of the payment. Later node status changes never rewrite it.
2. `routingPath` must resolve to exactly one leaf. Ambiguous or unresolvable → reject at creation. Never accept a payment and resolve routing during reconciliation.
3. A payment whose leaf node is `suspended` or `disabled` is rejected at creation.
4. `merchantReference` is stored verbatim, never parsed, never normalized.
5. `environment` must match the credential's environment. Mismatch is `403`.
**This is why it lands now, not later.** Without it, a payment cannot be attributed to a store, and §5's reconciliation goal — reconstructing why a given amount was charged — stops one level short of who it was charged for. Adding a routing dimension to a populated payments table after launch is materially more expensive than carrying it from the first row.
---
## 7. What the frontend will stop doing once this ships
- Delete `CurrencyRatesService`'s `localStorage`-persisted admin-typed rates and hardcoded `DEFAULT_RATES` fallback (`USD: 0.011`, `AMD: 4.3`).
- Delete the Admin Settings currency-rate editor UI.
- Stop sending `amount` / `price` in any checkout-related request.
- Replace client-side float conversion (`CurrencyRatesService.convert()`) with server-supplied `Money` values everywhere a price is displayed.
## 8. What the frontend will start doing
- Fetch `GET /api/v2/pricing/fx-quote` on currency switch; block checkout if the held quote has expired.
- Render the backoffice "total formula" panel (lines × qty − discounts + delivery + fees, FX quote used) once §5.2 and the admin Orders API exist (Phase 2).
- Surface `FX_SOURCE_UNAVAILABLE` and `error.code`-driven stale-quote UI per the error envelope in `BACKEND-API-REFERENCE.md §5`.
---
## 9. Resolved / open questions (Sprint 0.1, 2026-08-17)
1. **Payment chain freeze — lifted.** §5 can proceed.
2. **FX rate source/provider — ours, in-house, as the default (not just a fallback).** No external provider committed. Backend computes and serves the quote itself; the `source` field in §3.1 can legitimately read `"internal"` as the normal case. Revisit if an external provider is chosen later — the contract shape doesn't need to change, only the value of `source`.
3. **Backend-converted prices vs. frontend-requested display currency — still open, needs confirmation before implementation.** This doc's §5.2 models the frontend sending a target `currency` and the backend returning the converted total. Confirm this is the intended flow before backend implementation starts.
4. **Backend ownership — answered 2026-08-18.** A separate backend developer implements against this contract. Note §6.5: `RoutingContext` must be carried from the first payment row, not retrofitted.

118
docs/backend/PHASE-10-CONTENT-MODULES-CONTRACT.md
View File

@@ -1,118 +0,0 @@
# Phase 10 Backend Contract — Tenant Content Modules (Gorbushka-class tenants)
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Phase 10 (Sprints 10.1–10.2). Covers plan §11.
**Status: ready to build, lowest priority.** Only after Commerce Core (Phases 1–7) is real — the plan is explicit that this tenant type does not define the platform architecture; it is one configuration of the shared runtime, not a separate build.
---
## 1. Entities
```ts
interface Shop {
id: string;
marketplaceId: string;
shopCategoryId: string;
name: string;
floorId?: string;
status: 'draft' | 'published';
}
interface ShopCategory {
id: string;
marketplaceId: string;
title: string;
}
interface Service {
id: string;
marketplaceId: string;
title: string;
description: string;
status: 'draft' | 'published';
}
interface Floor {
id: string;
marketplaceId: string;
order: number;
label: string;
}
interface SchemePin {
id: string;
marketplaceId: string;
floorId: string;
shopId?: string;
x: number;
y: number;
}
interface RentListing {
id: string;
marketplaceId: string;
title: string;
areaSqm: number;
floorId?: string;
status: 'available' | 'leased';
}
interface Lead {
id: string;
marketplaceId: string;
rentListingId?: string;
contactName: string;
contactPhone: string;
message?: string;
createdAt: string;
}
interface NewsPromo {
id: string;
marketplaceId: string;
title: string;
body: string;
publishedAt?: string;
}
interface MallSettings {
marketplaceId: string;
openingHours: Record<string, string>;
contactInfo: Record<string, string>;
}
```
Every entity above carries `marketplaceId`, an audit trail, and the same draft/preview/publish flow as [Phase 9's revision model](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md) §5 — not a separate content pipeline.
## 2. Endpoints
```
GET/POST/PATCH/DELETE /api/admin/v2/content/shops
GET/POST/PATCH/DELETE /api/admin/v2/content/shop-categories
GET/POST/PATCH/DELETE /api/admin/v2/content/services
GET/POST/PATCH/DELETE /api/admin/v2/content/floors
GET/POST/PATCH/DELETE /api/admin/v2/content/scheme-pins
GET/POST/PATCH/DELETE /api/admin/v2/content/rent-listings
POST /api/admin/v2/content/rent-listings/{id}/leads
GET/POST/PATCH/DELETE /api/admin/v2/content/news
PATCH /api/admin/v2/content/mall-settings
```
## 3. Tenant feature configuration (Gorbushka's v1 default, per plan §11.1)
```json
{
"cms": true, "shops": true, "services": true, "mallScheme": true,
"rentListings": true, "news": true, "seoMedia": true,
"catalog": false, "sellerPortal": false,
"cart": false, "checkout": false, "payments": false, "orders": false
}
```
Commerce modules are **platform-ready but off** — the point of Phase 10 is proving this tenant can flip `catalog`/`cart`/`checkout`/etc. to `true` later via [Phase 9's `MarketplaceFeatureSet`](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md) with zero backend or storefront code changes, since the commerce core is already generic by the time Phase 10 starts.
## 4. What the frontend will start doing once this ships
- Mall scheme / floor / pin editor UI.
- Rent listing + lead capture forms.
- Confirm the existing Gorbushka frontend/archive is used as UX reference only — production data and auth route through the shared platform per ADR-0001.

152
docs/backend/PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md
View File

@@ -1,152 +0,0 @@
# Phase 2 Backend Contract — Canonical Orders, Event Bus, Notification Center
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Phase 2 (Sprints 2.1–2.2). Depends on [Phase 1](PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) (Money/PriceSnapshot/PaymentIntent) being implemented first — an Order line references a `priceSnapshotId` from that contract.
**Status: ready to build.** No open decisions block this phase.
---
## 1. Why this exists
Today `AdminOrdersLocalGateway` is a static 24-row in-memory seed with no create path — a real order can never appear. `AdminOrderWatcherService` already polls for new orders to toast/badge the admin, but is functionally inert against the mock. This contract makes both real.
## 2. Multi-seller model — Sprint 0.1 decision: unified
**One `Order` per checkout, regardless of how many sellers are represented.** Lines are grouped into per-seller `Fulfillment` entries internally. There is no parent/child order splitting, no separate order-per-seller. A seller only ever sees their own `Fulfillment` group within a shared order (see [Phase 5 contract](PHASE-5-SELLER-PORTAL-CONTRACT.md) for the seller-scoped view).
## 3. Entities
```ts
interface Order {
id: string;
marketplaceId: string;
source: 'storefront' | 'external' | 'backoffice' | 'api_partner';
externalOrderRef?: string; // set when source === 'external', see Phase 4
customerId?: string;
currency: string;
subtotal: Money;
discount: Money;
delivery: Money;
total: Money;
paymentStatus: 'pending_payment' | 'paid' | 'failed' | 'refunded' | 'partially_refunded';
orderStatus: 'pending_payment' | 'paid' | 'processing' | 'fulfilled' | 'completed' | 'cancelled';
createdAt: string;
paidAt?: string;
}
interface OrderLine {
id: string;
orderId: string;
offerId: string; // see Phase 3 contract
sellerId: string;
skuSnapshot: string;
titleSnapshot: string;
qty: number;
unitPrice: Money;
lineTotal: Money;
priceSnapshotId: string; // references Phase 1's PriceSnapshot
}
interface Fulfillment {
id: string;
orderId: string;
sellerId: string; // the seller-scoping unit for the unified-order model
type: 'manual' | 'warehouse' | 'pickup' | 'digital';
status: 'pending' | 'assigned' | 'in_progress' | 'issued' | 'shipped' | 'cancelled';
assignedTo?: string;
issuedAt?: string;
shippedAt?: string;
evidence?: { type: string; url: string }[]; // e.g. shipment proof, digital delivery receipt
}
interface OrderEvent {
id: string;
orderId: string;
type: 'created' | 'paid' | 'seller_notified' | 'accepted' | 'fulfilled' | 'cancelled' | 'refunded';
actor?: string; // user/system id, null for automated system events
occurredAt: string;
metadata?: Record<string, unknown>;
}
interface OrderContactSnapshot {
orderId: string;
name: string;
email?: string;
phone?: string;
preferredChannel?: 'telegram' | 'vk' | 'max' | 'email' | 'sms';
capturedAt: string; // immutable after order creation, independent of later Customer profile edits
}
```
## 4. Endpoints
```
GET /api/admin/v2/orders?marketplaceId=&status=&source=&page=&pageSize=
GET /api/admin/v2/orders/{id}
PATCH /api/admin/v2/orders/{id}/status { status }
POST /api/admin/v2/orders/{id}/refund-request { reason }
POST /api/admin/v2/orders/{id}/notes { note, internal: boolean }
POST /api/admin/v2/orders/{id}/archive
POST /api/admin/v2/orders/{id}/restore
DELETE /api/admin/v2/orders/{id}
GET /api/seller/v1/orders?fulfillmentStatus=&page=&pageSize=
-> returns Order + only the Fulfillment groups belonging to the authenticated seller,
OrderLines filtered to that seller's lines. Never the full order's other-seller lines.
```
Replaces `AdminOrdersLocalGateway` behind the `ADMIN_ORDERS_GATEWAY` token already wired this session (see [BACKEND-API-REFERENCE.md §8](../../BACKEND-API-REFERENCE.md)) — no facade change needed, only binding a real `AdminOrdersApiGateway`.
## 5. Event bus
```ts
type PlatformEvent =
| { type: 'order.created'; orderId: string; marketplaceId: string }
| { type: 'order.paid'; orderId: string; marketplaceId: string }
| { type: 'payment.failed'; orderId: string; reason: string }
| { type: 'webhook.error'; source: string; traceId: string }
| { type: 'stock.low'; offerId: string; available: number }
| { type: 'oversell'; offerId: string; requested: number; available: number }
| { type: 'refund.requested'; orderId: string; refundId: string }
| { type: 'refund.completed'; orderId: string; refundId: string }
| { type: 'external_order.imported'; orderId: string; connectorId: string };
```
Backend owns the bus implementation (queue, pub/sub, whatever fits existing infra). Frontend's only contract: the Notification entity below, and the requirement that `order.paid` always produces a backoffice notification **even if every external channel is down** (see [Phase 8](PHASE-8-IDENTITY-MESSAGING-CONTRACT.md) §5 for the messenger-side orchestration).
## 6. Notification Center
```ts
interface Notification {
id: string;
marketplaceId: string;
entityType: 'order' | 'payment' | 'offer' | 'connector' | 'refund';
entityId: string;
severity: 'info' | 'warning' | 'critical';
eventType: PlatformEvent['type'];
read: boolean;
deepLink: string; // e.g. /admin/orders/{id}
createdAt: string;
}
interface DeliveryAttempt {
notificationId: string;
channel: 'telegram' | 'email' | 'sms' | 'vk' | 'max';
status: 'sent' | 'failed';
error?: string;
attemptedAt: string;
}
```
```
GET /api/admin/v2/notifications?marketplaceId=&unreadOnly=&eventType=
PATCH /api/admin/v2/notifications/{id}/read
```
Invariant: a `DeliveryAttempt` failure on an external channel **never** prevents the `Notification` row itself from being created and visible in the backoffice unread queue.
## 7. What the frontend will start doing once this ships
- Repoint `AdminOrderWatcherService` from polling `AdminOrdersLocalGateway` to the event stream / `GET /api/admin/v2/notifications?unreadOnly=true`.
- Build the backoffice **Notifications** section (unread queue, severity, marketplace/event-type filter) — currently missing from admin nav entirely.
- Wire admin order actions (assign, resend notification, replay sync, cancel/refund, comment, export) to the endpoints in §4.

144
docs/backend/PHASE-3-CATALOG-OFFER-FULFILLMENT-CONTRACT.md
View File

@@ -1,144 +0,0 @@
# Phase 3 Backend Contract — Product/Offer Split, Inventory, Executability
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Phase 3 (Sprints 3.1–3.3). The largest structural change in the programme — nothing about multi-seller commerce works without it.
**Status: ready to build.** No open decisions block this phase.
---
## 1. Why this exists
Today price, stock and currency hang directly off a single admin `Product` mock domain, unrelated to the live storefront `Item` domain. A product cannot have two sellers, two prices, or two stock levels. `Offer/Listing` does not exist in any form.
## 2. The two-layer split
`Product` describes the item itself (content). `Offer` describes one seller's commercial proposition against that product (price, stock, currency, status). One product, many offers.
```ts
interface Product {
id: string;
marketplaceId: string;
categoryId: string;
brand?: string;
title: string;
description: string;
attributes: Record<string, unknown>;
media: string[];
status: 'draft' | 'moderation' | 'published' | 'paused' | 'archived';
}
interface Variant {
id: string;
productId: string;
sku: string;
barcode?: string;
optionValues: Record<string, string>; // e.g. { color: 'red', size: 'M' }
dimensions?: { weight?: number; length?: number; width?: number; height?: number };
}
interface Category {
id: string;
marketplaceId: string;
parentId: string | null;
slug: string;
attributesSchema: Record<string, unknown>;
order: number;
seo: { title?: string; description?: string };
}
interface Offer {
id: string;
marketplaceId: string;
sellerId: string;
variantId: string;
sellerSku: string;
price: Money; // Money type from Phase 1 contract
stockPolicy: 'track' | 'no_track' | 'preorder';
status: 'draft' | 'moderation' | 'published' | 'paused' | 'archived';
publishedAt?: string;
executabilityChecked: boolean; // see §5
}
interface PriceHistory {
offerId: string;
price: Money;
changedBy: string; // user id or 'sync:{connectorId}'
changedAt: string;
}
```
## 3. Inventory
```ts
interface InventoryRecord {
offerId: string;
available: number;
reserved: number;
sold: number;
warehouse?: string;
source: 'manual' | 'feed_sync' | 'connector';
}
interface StockReservation {
id: string;
offerId: string;
qty: number;
reason: 'checkout' | 'pre_payment';
expiresAt: string; // TTL
released: boolean;
}
```
Invariants:
- `available`, `reserved`, `sold` are counted separately, never derived from one another implicitly.
- Reservations are created at checkout or pre-payment (tenant-configurable strategy) and expire by TTL, releasing `reserved` back to `available`.
- Seller feed stock updates are an **idempotent upsert** — a repeated webhook must not double-decrement.
- Oversell (a sale exceeding `available`) routes to a dedicated incident queue, never silently hidden or auto-corrected.
## 4. Lifecycle
```
draft -> moderation -> published -> paused/archived
```
Applies independently to both `Product` and `Offer`. Wires to the already-existing (mock) Admin Moderation module — no new frontend module needed, just a real gateway behind `ADMIN_MODERATION_GATEWAY` (token already added this session).
## 5. Publish-time executability
**An offer that cannot actually be fulfilled must not be publishable.** Before allowing `status: 'published'`, the backend validates:
- The offer has a valid `Fulfillment` type it can realistically satisfy (see [Phase 2 contract](PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md) `Fulfillment.type`).
- Stock policy is `track` with `available > 0`, or `no_track`/`preorder` explicitly.
- Required attributes for the offer's category (`Category.attributesSchema`) are present.
This is the mechanism behind the plan's §3.6/§10.2 requirement: **no branch anywhere may distinguish a normal buyer from an inspector.** The only way to guarantee that is to make every published offer genuinely executable at publish time, not to special-case checkout behavior later.
## 6. Bulk import
```
POST /api/admin/v2/products/bulk-import
Content-Type: multipart/form-data (CSV) or application/json (array)
```
Response returns a **preview** of validation errors before anything is applied — required-field validation, category-attribute validation, duplicate-SKU detection — with a separate `POST .../bulk-import/{importId}/apply` to commit after review.
## 7. Endpoints
```
GET /api/admin/v2/products?marketplaceId=&status=&search=&page=&pageSize=
GET /api/admin/v2/products/{id}
POST /api/admin/v2/products
PATCH /api/admin/v2/products/{id}
GET /api/admin/v2/offers?productId=&sellerId=&status=
POST /api/admin/v2/offers
PATCH /api/admin/v2/offers/{id}
POST /api/admin/v2/offers/{id}/publish -> runs §5 executability check, 422 with details[] on failure
GET /api/admin/v2/offers/lookup?sku=&sellerSku=&externalId= -- "find any offer by internal SKU, seller SKU, product ID, or external mapping" per plan §2.1
```
Replaces `AdminProductsLocalGateway` behind `ADMIN_PRODUCTS_GATEWAY` (token already wired this session).
## 8. What the frontend will start doing once this ships
- Unify the admin mock product domain with the live storefront `Item` domain — currently two unrelated shapes.
- Multi-seller product page: same product card, multiple offers/sellers/prices — undefined behaviour today.
- Wire the Moderation module to real lifecycle transitions instead of mock data.

123
docs/backend/PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md
View File

@@ -1,123 +0,0 @@
# Phase 4 Backend Contract — External Order Connector Framework
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Phase 4 (Sprint 4.1, generic framework; Sprint 4.2 retired as "per named marketplace"). Depends on [Phase 3](PHASE-3-CATALOG-OFFER-FULFILLMENT-CONTRACT.md) (`Offer`/`sellerSku` must exist to map onto) and [Phase 2](PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md) (`Order` canonical model).
**Status: ready to build, generic by design.** Sprint 0.1 decision (2026-08-17): no fixed marketplace list — "our new ones, partners, new, etc." This contract specifies a config-driven framework, not a per-provider integration. Zero of this exists in the codebase today (`reconcil*`, `idempot*`, `hostinger` all return 0 hits).
---
## 1. Design principle
**A new partner connector is an onboarding action against this framework, not a code change.** Auth type, field mapping, and rate limits are configuration; the pipeline (ingest → normalize → map → idempotency-check → create/update order → notify) is fixed and shared across every connector.
## 2. Entities
```ts
interface Connector {
id: string;
marketplaceId: string;
provider: string; // free-text label, e.g. "ozon", "wildberries" - not an enum, new values need no code change
authType: 'webhook_signed' | 'api_key' | 'oauth2';
credentialRef: string; // pointer into secret storage, never the secret itself
pollingIntervalSeconds?: number; // set only when the provider has no webhook
cursorState?: string; // opaque, connector-specific pagination/since cursor
status: 'active' | 'paused' | 'error';
}
interface RawExternalEvent {
id: string;
connectorId: string;
payload: unknown; // stored verbatim, before any parsing - the traceability anchor
receivedAt: string;
processedAt?: string;
}
interface ExternalOrderMapping {
connectorId: string;
externalSellerId: string;
externalProductId: string;
externalSku: string;
internalSellerId: string;
internalOfferId: string; // references Phase 3's Offer
}
interface DeadLetter {
id: string;
connectorId: string;
rawEventId: string;
reason: string;
retryCount: number;
lastAttemptAt: string;
resolvedAt?: string;
}
```
## 3. Pipeline (fixed, shared across every connector)
```
1. Connector receives webhook, or polling finds a new event via cursorState.
2. Signature/auth verified. Idempotency key = connectorId + externalOrderId/eventId.
3. Payload persisted as RawExternalEvent BEFORE any parsing.
4. Normalizer maps payload -> canonical ExternalOrderEvent shape (fixed schema, see §4).
5. SKU mapping resolves externalSku -> internal Offer via ExternalOrderMapping.
No mapping found -> event goes to the Unmatched queue (§5), does NOT fail silently.
6. Order created/updated via the Phase 2 Order API, source: 'external', externalOrderRef set.
7. external_order.imported and order.created events emitted (Phase 2 event bus).
8. Fulfillment/status changes pushed back to the external marketplace if its API supports it.
```
## 4. Canonical external order event (what the normalizer produces)
```ts
interface ExternalOrderEvent {
connectorId: string;
externalOrderId: string;
externalCreatedAt: string;
customer: { name?: string; contact?: string };
lines: Array<{ externalSku: string; qty: number; unitPriceMinor: number; currency: string }>;
totalMinor: number;
currency: string;
rawEventId: string; // traceability back to §2
}
```
Every provider's adapter is responsible only for producing this shape from its own payload — everything downstream (§3 steps 5–8) is provider-agnostic.
## 5. Unmatched queue + retry
```
GET /api/admin/v2/integrations/{connectorId}/unmatched
POST /api/admin/v2/integrations/{connectorId}/unmatched/{eventId}/resolve { internalOfferId }
POST /api/admin/v2/integrations/{connectorId}/dead-letter/{id}/replay
```
Retry policy: exponential backoff, capped attempts, then `DeadLetter` with manual replay from backoffice. No connector is allowed to silently drop an event.
## 6. Connector-agnostic SLA (applies to every provider, per plan §5.2)
- Webhook source: 99% of valid events processed in under 60 seconds.
- Polling source: delay no worse than `pollingIntervalSeconds + 60`.
- **Zero** duplicate orders on repeated event delivery (guaranteed by the idempotency key in §3 step 2).
- Every connector error carries a trace id, visible in backoffice.
## 7. Endpoints
```
POST /api/providers/v1/{connector}/webhook -- generic entrypoint, connector resolved by path + auth
GET /api/admin/v2/integrations -- list all connectors + health (last success, lag, errors, backlog)
POST /api/admin/v2/integrations -- onboard a new connector: { provider, authType, credentialRef, marketplaceId }
PATCH /api/admin/v2/integrations/{id} -- pause/resume, update mapping config
```
## 8. Onboarding a new partner (replaces the old "one sprint per named marketplace")
1. Register credentials in secret storage, scoped to marketplace/seller.
2. `POST /api/admin/v2/integrations` with the provider's auth type and mapping config.
3. Write the provider-specific adapter (payload → §4 canonical shape) — the only genuinely bespoke piece per partner.
4. Verify in sandbox against the fixed pipeline (§3) — nothing else changes.
## 9. What the frontend will start doing once this ships
- Build the backoffice **Integrations** section (missing from admin nav today): connector list, health (last success/lag/errors/backlog/unmatched), FX sources, messaging providers.
- Trace-id surfacing on connector errors.
- Unmatched-queue resolution UI.

88
docs/backend/PHASE-5-SELLER-PORTAL-CONTRACT.md
View File

@@ -1,88 +0,0 @@
# Phase 5 Backend Contract — Seller Portal
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Phase 5 (Sprints 5.1–5.3). Depends on [Phase 3](PHASE-3-CATALOG-OFFER-FULFILLMENT-CONTRACT.md) (Offer) and [Phase 2](PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md) (unified Order + Fulfillment).
**Status: ready to build behind the launch gate.** Frontend note: Seller Management is currently a static placeholder, feature-flagged off by default, with **zero backend bytes and zero `HttpClient` reference** — this contract is a from-scratch build, not a gateway swap.
---
## 1. Multi-seller model reminder
Per the Phase 2 unified-orders decision: a seller never owns a separate `Order`. They see the `Fulfillment` group(s) that belong to them within shared orders, and the `OrderLine`s scoped to their `sellerId`. All endpoints below are pre-filtered server-side to the authenticated seller — never trust a frontend-supplied `sellerId` filter.
## 2. Entities
```ts
interface SellerOrganization {
id: string;
marketplaceId: string;
legalName: string;
status: 'pending' | 'approved' | 'suspended' | 'rejected';
bankDetailsRef: string; // pointer into secret storage, never raw account numbers over the wire
createdAt: string;
}
interface SellerUser {
id: string;
sellerOrganizationId: string;
role: 'SELLER_OWNER' | 'SELLER_CATALOG_MANAGER' | 'SELLER_ORDER_MANAGER' | 'SELLER_FINANCE_VIEWER' | 'SELLER_VIEWER';
email: string;
status: 'active' | 'invited' | 'suspended';
}
interface SellerMarketplaceMembership {
sellerOrganizationId: string;
marketplaceId: string;
status: 'pending' | 'approved' | 'suspended';
}
interface SellerIntegration {
sellerOrganizationId: string;
apiCredentialRef: string;
webhookUrl?: string;
lastSyncAt?: string;
lastSyncError?: string;
}
```
## 3. Endpoints (all scoped server-side to the authenticated seller's org)
```
POST /api/seller/v1/onboarding { legalName, contacts, marketplaceId }
GET /api/seller/v1/profile
GET /api/seller/v1/offers?status=&page=
POST /api/seller/v1/offers
PATCH /api/seller/v1/offers/{id}
POST /api/seller/v1/offers/bulk-price-update -- mass price/stock edit, see Phase 3 §6 for the shared bulk-import pattern
GET /api/seller/v1/orders?fulfillmentStatus=
PATCH /api/seller/v1/orders/{orderId}/fulfillment/{fulfillmentId} { status, evidence }
GET /api/seller/v1/finance/accruals
GET /api/seller/v1/finance/settlements
POST /api/seller/v1/finance/bank-details -- step-up auth + audit event required, see §5
GET /api/seller/v1/team
POST /api/seller/v1/team/invite { email, role }
GET /api/seller/v1/integrations
```
## 4. Roles (fixed set, enforced backend-side)
```
SELLER_OWNER - full access within the org
SELLER_CATALOG_MANAGER - offers/catalog only
SELLER_ORDER_MANAGER - orders/fulfillment only
SELLER_FINANCE_VIEWER - read-only finance
SELLER_VIEWER - read-only everything
```
No UI-only gating. Every endpoint above checks `SellerUser.role` server-side regardless of what the frontend renders — this is the same principle as [Track S](TRACK-S-SECURITY-RBAC-CONTRACT.md), scoped to the seller domain specifically.
## 5. Sensitive-action rules
- Bank/payment detail changes (`POST .../finance/bank-details`) require step-up authentication, produce an audit event, and — if maker/checker mode is enabled for the tenant — require a second approver before taking effect.
- A seller can never query, by any endpoint or parameter manipulation, another seller's products, orders, customers, finance data, or API keys. This must be enforced at the query layer (implicit `WHERE sellerOrganizationId = :authenticatedSeller`), not left to the frontend to "not ask for it."
## 6. What the frontend will start doing once this ships
- Replace the static Seller Management placeholder with real screens: Onboarding, Catalog, Prices & Stock, Orders, Finance, Team, Integrations (per plan §2.2).
- Resolve the two competing seller type shapes flagged in `GAPS-AND-IMPROVEMENTS.md` (`SellerConfig` in bootstrap models vs. `Seller`/`SellerBranding` in the domain layer) against this contract's `SellerOrganization`/`SellerUser` shapes.
- First-ever exercise of the `sellerManagement.enabled` flag at `true` — write a fixture test, since it has never been tested at its real-world-eventual value.

90
docs/backend/PHASE-6-CART-CHECKOUT-CONTRACT.md
View File

@@ -1,90 +0,0 @@
# Phase 6 Backend Contract — Server Cart + Checkout Session
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Phase 6 (Sprints 6.1–6.2). Extends [Phase 1](PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) §5 (server-authoritative checkout amount) into a full server-owned cart.
**Status: ready to build** — payment chain unfrozen per Sprint 0.1.
---
## 1. Why this exists
Cart today is `localStorage` + Telegram CloudStorage — no backend cart exists at all. `features/website/checkout/` is an empty directory; checkout lives entirely inside a 751-line cart popup component. Phase 1 §5 already specifies the server-authoritative *amount* at checkout time; this phase makes the *cart itself* server-owned, from add-to-cart onward.
## 2. Entities
```ts
interface Cart {
id: string;
marketplaceId: string;
customerId?: string; // set for authenticated customers
sessionToken?: string; // set for guest carts
createdAt: string;
expiresAt: string; // TTL for inactive carts
}
interface CartLine {
id: string;
cartId: string;
offerId: string; // never a client-supplied price - see Phase 1 §5
qty: number;
addedAt: string;
}
interface CheckoutSession {
id: string;
cartId: string;
customerContact: { email?: string; phone?: string; verified: boolean };
deliveryOptionId: string;
status: 'open' | 'confirmed' | 'expired';
createdAt: string;
expiresAt: string;
}
interface DeliveryOption {
id: string;
marketplaceId: string;
label: string;
price: Money;
type: 'pickup' | 'courier' | 'digital';
}
```
## 3. Cart endpoints
```
POST /api/v2/storefront/cart/lines { offerId, qty }
PATCH /api/v2/storefront/cart/lines/{lineId} { qty }
DELETE /api/v2/storefront/cart/lines/{lineId}
GET /api/v2/storefront/cart
```
Invariants:
- Idempotent add/update/remove.
- Quantity validated against `Offer`/`InventoryRecord` (Phase 3) on every mutation, not just at checkout.
- Guest cart identified by `sessionToken` (cookie or header); authenticated cart bound to `customerId`. Adding to a guest cart, then logging in, must merge into the customer's cart — not silently drop items.
- Inactive carts and their `StockReservation`s (Phase 3 §3) clear on `expiresAt`.
## 4. Price-refresh rule
If an offer's price changed since it was added to the cart, `GET /api/v2/storefront/cart` returns both the line's captured price and the current price, with a `priceChanged: boolean` flag. The frontend must show this and require explicit confirmation before checkout proceeds if the total moved — this is a UX requirement on the frontend, but the backend must expose the comparison, not silently use whichever price it prefers.
## 5. Checkout session
Builds directly on [Phase 1 §5.2](PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md#5-server-authoritative-checkout-amount):
```
POST /api/v2/storefront/checkout { cartId, currency, deliveryOptionId }
```
reads the server-owned `Cart`/`CartLine`s directly (no client-supplied offer list needed anymore, unlike the Phase 1 doc's example which pre-dates the server cart). Response shape unchanged from Phase 1 §5.2.
Additional checkout-time validation beyond Phase 1:
- Contact requirement enforced per tenant policy: email and/or phone must be present and (if the tenant requires it) verified before `CheckoutSession.status` can move to `confirmed`.
- Guest checkout allowed/disallowed per tenant policy (`MarketplaceFeatureSet`, see [Phase 9](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md)).
## 6. What the frontend will start doing once this ships
- Build the `features/website/checkout/` module for real — currently an empty directory.
- Retire `localStorage`/Telegram-CloudStorage cart persistence.
- Show the price-refresh confirmation UI described in §4.
- Delete the client-side offer/qty tracking currently duplicated inside the cart popup component.

112
docs/backend/PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md
View File

@@ -1,112 +0,0 @@
# Phase 7 Backend Contract — Refunds + Reconciliation
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Phase 7 (Sprints 7.1–7.3). Extends [Phase 1](PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) §6 (payment state machine).
**Status: ready to build.** `requestRefund(id)` exists today only as a mock gateway method; `reconcil*` and `settlement*` return zero hits anywhere in the codebase.
---
## 1. Refunds
```ts
interface Refund {
id: string;
orderId: string;
orderLineIds: string[]; // which lines this refund covers - partial refunds must specify
amount: Money;
reason: string;
actor: string; // user id who initiated it, never anonymous
status: 'requested' | 'approved' | 'processing' | 'completed' | 'failed';
requestedAt: string;
completedAt?: string;
routing: RoutingContext; // copied verbatim from the original Payment, never recomputed
}
```
A refund always carries the routing context of the payment it reverses. It is copied, not re-resolved — a store suspended after the payment must still be refundable.
```
POST /api/admin/v2/orders/{orderId}/refunds { orderLineIds, amount, reason }
GET /api/admin/v2/orders/{orderId}/refunds
```
A `Refund` updates `Payment.status` to `refunded` or `partially_refunded` (Phase 1 §6.1) and emits `refund.requested`/`refund.completed` on the Phase 2 event bus.
## 2. Reconciliation
```ts
interface ReconciliationRecord {
id: string;
orderId: string;
providerPaymentId?: string;
internalAmount: Money;
providerAmount?: Money;
matchStrategy: 'provider_payment_id' | 'merchant_reference' | 'amount_currency_fallback';
result: 'matched' | 'unmatched' | 'duplicate' | 'amount_mismatch' | 'status_mismatch';
resolvedBy?: string;
resolvedAt?: string;
resolutionNote?: string;
routing: RoutingContext; // from the Payment; makes every row attributable to one payment point
}
```
Process (per plan §7.3):
```
1. Collect internal paid orders for a period.
2. Fetch provider transactions/events for the same period.
3. Match by providerPaymentId, falling back to merchant reference, falling back to amount+currency.
4. Classify: matched / unmatched / duplicate / amount_mismatch / status_mismatch.
5. Surface the non-matched set in backoffice with controlled, audited resolution.
```
```
GET /api/admin/v2/reconciliation/queue?marketplaceId=&companyId=&projectId=&leafNodeId=&result=
POST /api/admin/v2/reconciliation/{id}/resolve { note }
```
Step 3's `merchant_reference` strategy matches on `RoutingContext.merchantReference` — the partner-supplied value, stored verbatim (Phase 1 §6.5). The queue is filterable at every hierarchy level so an unmatched set can be narrowed to one payment point without a join the backoffice has to build itself.
## 3. Settlements
```ts
interface Settlement {
id: string;
sellerId: string;
periodStart: string;
periodEnd: string;
grossAmount: Money;
commission: Money;
refunds: Money;
netPayout: Money;
status: 'pending' | 'paid';
}
```
```
GET /api/seller/v1/finance/settlements
GET /api/admin/v2/finance/settlements?sellerId=&companyId=&projectId=&storeId=&period=
```
### 3.1 Seller split happens after routing
Added 2026-08-18. `Seller` is deliberately **not** a level in the partner hierarchy ([PARTNER-PROVISIONING-API-CONTRACT.md §10.2](PARTNER-PROVISIONING-API-CONTRACT.md)). Order of operations:
```
payment -> routed to exactly one payment point (Phase 1 §6.5, frozen at checkout)
-> reconciled at that payment point
-> split across the sellers whose lines the order contains (this phase)
```
- A `Settlement` belongs to one seller **within one store**. A seller trading in two stores gets two settlements per period, never one merged row.
- Splitting never rewrites `RoutingContext`. The money arrived at one payment point; the split decides who is owed from it.
- `grossAmount` summed across a store's settlements for a period must reconcile against that store's matched reconciliation rows for the same period. A mismatch is a reconciliation defect, not a rounding tolerance.
## 4. Provider breadth (open business question)
Current flow supports QR and card only, via one custom provider integration. Adding wallets/BNPL is an explicit open business decision (not answered in Sprint 0.1) — this contract's `PaymentIntent`/`Payment` shapes from Phase 1 §6 are provider-agnostic already, so a new provider is a new adapter behind the same state machine, not a schema change. No action needed here until that business decision is made.
## 5. What the frontend will start doing once this ships
- Wire the mock `requestRefund(id)` to a real endpoint.
- Build the backoffice **Payments & Finance** section (missing from admin nav today): payments, refunds, reconciliation queue, unmatched events, settlements.
- Reconciliation-queue resolution UI with full audit trail.

151
docs/backend/PHASE-8-IDENTITY-MESSAGING-CONTRACT.md
View File

@@ -1,151 +0,0 @@
# Phase 8 Backend Contract — Customer Identity, VK ID, MAX/Telegram Messaging
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Phase 8 (Sprints 8.1–8.5). Covers plan §2.9, §3.4, and all of §14 (the v3.1-only addition).
**Status: ready to build. Sprint order fixed by Sprint 0.1 decision: VK ID first, then everything else** ("do all after vk"). Sequence below follows that: identity core → VK ID → email/phone OTP → MAX/Telegram → Notification Orchestrator.
---
## 1. Entities
```ts
interface Customer {
id: string;
marketplaceId: string; // or global identity strategy, tenant-configurable
name?: string;
email?: string;
phone?: string;
status: 'active' | 'suspended';
createdAt: string;
}
interface ExternalIdentity {
customerId: string;
provider: 'vk_id' | 'telegram' | 'max';
providerUserId: string;
verifiedAt: string;
metadata: Record<string, unknown>;
lastUsedAt: string;
}
interface ContactMethod {
customerId: string;
type: 'email' | 'phone';
value: string;
verifiedAt?: string;
}
interface ContactChannel {
customerId: string;
provider: 'telegram' | 'vk' | 'max';
chatId: string;
verified: boolean;
notificationsEnabled: boolean;
deliveryEnabled: boolean;
}
interface MessagingConsent {
customerId: string;
channel: string;
purpose: 'marketing' | 'order_service_messages';
grantedAt?: string;
revokedAt?: string;
}
```
Telegram is demoted from sole identity to one `ExternalIdentity` provider among several — it must remain fully functional, just no longer the only path.
## 2. Sprint 8.2 — VK ID (build first)
```
GET /api/identity/v1/vk/authorize -> redirects into VK's OAuth 2.1/PKCE flow
POST /api/identity/v1/vk/callback { code, codeVerifier } -> completes OAuth **backend-side**,
links ExternalIdentity, returns session
```
Invariants:
- OAuth completion happens entirely backend-side; the VK client secret never reaches the frontend.
- A repeat login for the same `providerUserId` must resolve to the same `Customer`, never create a duplicate.
- If `providerUserId` is already linked to a *different* `Customer` than the one currently authenticated (or none), this is an identity conflict — route to controlled resolution, never silently overwrite the existing binding (plan §14.3).
## 3. Sprint 8.3 — Email/phone OTP (after VK ID)
Implements the already-approved [email/phone login spec](../superpowers/specs/2026-08-15-email-phone-login-design.md). Per v3.1 §14, position this as **recovery/fallback** when a messenger channel is unavailable — not the primary login path. No new contract beyond that spec; this section exists only to fix its place in the build order relative to VK ID.
## 4. Sprint 8.4 — MAX + Telegram bot channels
```ts
interface BotConversationBinding {
customerId: string;
marketplaceId: string;
provider: 'telegram' | 'max';
chatId: string;
state: string; // see §5 state machine
orderId?: string;
lastMessageAt: string;
}
```
MAX linking flow (bot-assisted, one-time code):
```
POST /api/identity/v1/max/link-code -> { code, expiresAt } (TTL, single-use, bound to marketplace + browser session)
```
User opens the MAX bot, sends the code; a confirmed bot update on the backend calls:
```
POST /api/providers/v1/max/bot-webhook -- idempotent; a repeated update must not create a duplicate binding
```
which links the pending `Customer` session to the MAX `chatId`.
All three providers' incoming bot updates (VK, MAX, Telegram) normalize into one shape:
```ts
interface MessagingEvent {
provider: 'telegram' | 'vk' | 'max';
chatId: string;
orderId?: string;
text?: string;
receivedAt: string;
}
```
Provider bot tokens/secrets never reach the frontend, ever — only the backend calls each provider's Bot API.
## 5. Sprint 8.5 — Notification Orchestrator + Delivery Conversation State Machine
On `order.paid` (Phase 2 event bus), the orchestrator picks the customer's chosen channel (captured at checkout, see [Phase 6](PHASE-6-CART-CHECKOUT-CONTRACT.md) and `OrderContactSnapshot` in [Phase 2](PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md)) and drives:
```
not_started -> awaiting_customer -> details_received -> manager_assigned/auto_confirmed -> shipment_planned -> completed
```
```ts
interface DeliveryDetailsSnapshot {
orderId: string;
city?: string;
address?: string;
recipientName?: string;
phone?: string;
timeWindow?: string;
comment?: string;
receivedAt: string;
}
```
Hard rules:
- **The bot never changes financial statuses.** It can only write `DeliveryDetailsSnapshot` fields via a dedicated Delivery Service — no bot code path touches `Order.paymentStatus`/`orderStatus`.
- The backoffice `Notification` (Phase 2 §6) fires unconditionally on `order.paid`, independent of whether the customer's messenger channel is reachable.
- If the chosen channel is unavailable, log a `DeliveryAttempt` error (Phase 2 §6) and fall back per tenant-configured policy (e.g. email/SMS) — never block the order itself.
- Follow-up messages are rate-limited per tenant policy; after the configured attempt limit, hand off to a human manager instead of continuing to message.
```
POST /api/providers/v1/{provider}/bot-webhook -- generic entrypoint for all three providers
GET /api/admin/v2/orders/{orderId}/conversation -- message history + current state, for manager handoff
POST /api/admin/v2/orders/{orderId}/conversation/handoff
```
## 6. What the frontend will start doing once this ships
- VK ID login button + OAuth redirect flow on storefront (primary social login).
- MAX/Telegram linking UI (one-time code flow).
- Checkout channel-choice step ("where should we send confirmation?") — VK / MAX / Telegram / email/SMS fallback.
- Manager-facing conversation view (message history, current delivery state, accept handoff).

196
docs/backend/PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md
View File

@@ -1,196 +0,0 @@
# Phase 9 Backend Contract — Tenant Registry, Domain Automation, Publish Model
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Phase 9 (Sprints 9.1–9.3). Covers plan §4.3, §8.
**Status: ready to build.** Zero `hostinger` references exist in the codebase today.
---
## 1. Entities
Added 2026-08-18: two levels now sit **above** `Marketplace`, introduced by [PARTNER-PROVISIONING-API-CONTRACT.md §10](PARTNER-PROVISIONING-API-CONTRACT.md).
```ts
interface Company {
id: string;
name: string;
externalReference?: string; // partner's own id, when provisioned via the partner API
status: 'active' | 'suspended' | 'disabled';
createdAt: string;
updatedAt: string;
}
interface Project {
id: string;
companyId: string;
name: string; // a product line, e.g. "marketplaces"
externalReference?: string;
status: 'active' | 'suspended' | 'disabled';
createdAt: string;
updatedAt: string;
}
```
Both are deliberately thin — they exist to scope ownership, credentials, and payment routing, not to hold configuration. All marketplace configuration stays on `Marketplace` below.
A `Marketplace` **is** the partner hierarchy's `store` level. One project holds many marketplaces; one marketplace holds many sellers (Phase 5), and sellers are not part of that hierarchy.
```ts
interface Marketplace {
id: string;
companyId: string; // added 2026-08-18
projectId: string; // added 2026-08-18
externalReference?: string; // added 2026-08-18, partner's own id for this store
name: string;
code: string;
type: 'commerce' | 'mall_directory' | 'hybrid' | 'single_brand';
ownerId: string;
countries: string[];
locales: string[];
currencies: string[];
timezone: string;
lifecycleState: MarketplaceLifecycleState;
}
type MarketplaceLifecycleState =
| 'draft' | 'configured' | 'content_ready' | 'domains_planned'
| 'staging_live' | 'qa_passed' | 'production_ready' | 'live' | 'paused' | 'archived';
interface MarketplaceDomain {
marketplaceId: string;
domain: string;
type: 'production' | 'www' | 'staging' | 'preview' | 'api' | 'seller';
status: 'planned' | 'dns_pending' | 'ssl_pending' | 'active' | 'failed';
}
interface MarketplaceFeatureSet {
marketplaceId: string;
features: Record<string, boolean>; // e.g. { catalog: true, sellers: true, cart: true, checkout: true, payments: true, orders: true, refunds: true, directory: false, ... }
}
interface MarketplaceRevision {
id: string;
marketplaceId: string;
status: 'draft' | 'validated' | 'preview' | 'published';
publishedAt?: string;
supersedesRevisionId?: string; // rollback creates a NEW revision, never mutates the old one
}
```
**Hard invariant:** `Order`, `Payment`, `InventoryRecord`, and every financial ledger row are **not part of a `MarketplaceRevision`**. Rolling back a storefront design revision must never touch commerce data.
### 1.1 PaymentPoint
Added 2026-08-18. The leaf of the partner hierarchy: one payment method accepted at one marketplace. A marketplace taking both QR and card has two payment points.
```ts
interface PaymentPoint {
id: string;
marketplaceId: string;
method: 'qr' | 'card'; // extensible; both ship today
currencies: string[]; // ISO 4217 subset this channel accepts
externalReference?: string;
status: 'active' | 'suspended' | 'disabled';
providerAccountRef?: string; // set only by financial enablement, never by provisioning
createdAt: string;
updatedAt: string;
}
```
- Creating a payment point registers the channel. It does **not** enable real money — that requires `providerAccountRef`, set through a separate approved flow.
- A payment point is what `RoutingContext.leafNodeId` points at (Phase 1 §6.5).
- `MarketplaceFeatureSet.features.payments` gates whether the marketplace may have enabled payment points at all; the payment point gates which method.
### 1.2 Backfill
Existing marketplaces predate `Company` and `Project`. Migration, in this order:
```
1. Create one Company for the current owning entity.
2. Create one Project ("marketplaces") under it.
3. Set companyId + projectId on every existing Marketplace.
4. Create PaymentPoints for the methods each marketplace already accepts (qr, card).
5. Make companyId and projectId non-nullable only after 3 completes.
```
`externalReference` stays null for backfilled rows — it is only meaningful for partner-provisioned nodes.
## 2. Lifecycle state machine
```
draft -> configured -> content_ready -> domains_planned -> staging_live -> qa_passed -> production_ready -> live -> paused/archived
```
Every state transition endpoint must return the specific blocker preventing the next transition — not just "not ready."
```
GET /api/admin/v2/marketplaces/{id}/lifecycle -> { currentState, nextState, blockers: string[] }
POST /api/admin/v2/marketplaces/{id}/lifecycle/advance
```
## 3. Onboarding wizard (8 steps, plan §4.3)
```
POST /api/admin/v2/marketplaces -- step 1: name/code/type/owner/countries/locales/currencies/timezone
PATCH /api/admin/v2/marketplaces/{id}/feature-set -- step 2
POST /api/admin/v2/marketplaces/{id}/domains -- step 3
PATCH /api/admin/v2/marketplaces/{id}/design -- step 4
POST /api/admin/v2/marketplaces/{id}/roles -- step 5
PATCH /api/admin/v2/marketplaces/{id}/integrations -- step 6
POST /api/admin/v2/marketplaces/{id}/staging-launch -- step 7, runs smoke tests
POST /api/admin/v2/marketplaces/{id}/production-launch -- step 8, requires all P0 blockers closed + explicit approval
```
## 4. Domain automation (Hostinger API, per plan §8.2)
```
GET /api/dns/v1/zones/{domain}
POST /api/dns/v1/zones/{domain}/validate
PUT /api/dns/v1/zones/{domain}
DELETE /api/dns/v1/zones/{domain}
GET /api/dns/v1/snapshots/{domain}
GET /api/dns/v1/snapshots/{domain}/{snapshotId}
POST /api/dns/v1/snapshots/{domain}/{snapshotId}/restore
```
Process, strictly in this order:
```
1. Read current DNS zone.
2. Save a snapshot (rollback payload) BEFORE any change.
3. Build and validate a DNS plan.
4. NEVER touch MX/SPF/DKIM/DMARC/CAA records without a separate, explicitly scoped task.
5. Apply records only after production approval.
6. Verify propagation, SSL issuance, and health checks.
7. Mark the domain 'active' only after all checks in step 6 pass.
```
## 5. Publish model
```
draft -> validation -> preview -> publish
```
```
POST /api/admin/v2/marketplaces/{id}/revisions -- create draft
POST /api/admin/v2/marketplaces/{id}/revisions/{revId}/validate
POST /api/admin/v2/marketplaces/{id}/revisions/{revId}/publish -- becomes immutable
POST /api/admin/v2/marketplaces/{id}/revisions/{revId}/rollback -- creates a NEW revision pointing at the prior published content
```
Replaces the current builder's `localStorage`-only draft persistence and the empty `apiEndpoints.builder: {}` placeholder in bootstrap. CMS/static-page content (currently in-memory bootstrap only) gets a real write path through this same revision model.
## 6. Tenant resolution hardening
```
GET /api/v2/storefront/bootstrap -- resolved server-side from verified Host header
```
- Host is normalized and matched against `MarketplaceDomain` server-side — the marketplace ID from the browser is never a trust boundary.
- Unknown Host → `404`, with **no fallback to any other tenant**.
## 7. What the frontend will start doing once this ships
- Build the backoffice **Marketplaces** section (missing from admin nav today): registry, type, status, domains, currencies, feature set, responsible manager.
- Build the **Domains & Releases** section: DNS/SSL status, staging/production, health checks, rollback.
- Wire the project editor/builder to real revision persistence instead of `localStorage`.
- Marketplace dashboard: GMV, paid orders, conversion, payment failure rate, moderation queue, low stock, unmatched events, integration health, domain/SSL/release status (plan §4.2).

47
docs/backend/README.md
View File

@@ -1,47 +0,0 @@
# Backend Contracts Index — Product Plan v3.1
> **New here? Start with [BACKEND-HANDOFF.md](BACKEND-HANDOFF.md)** — reading order, current infrastructure state, auth surface, and what a working dev environment still needs.
>
> **Want every endpoint in one place? [FRONTEND-API-SURFACE-COMPLETE.md](FRONTEND-API-SURFACE-COMPLETE.md)** — generated directly from source, all 86 endpoints the frontend currently calls, marked Specified / Inferred / Undocumented against the contracts below. Use it to see gaps across all contracts at once; use the individual Phase/Track docs for full entity shapes and invariants.
This directory is the complete set of wire contracts for building the backend behind [Product Plan v3.1](../PRODUCT-PLAN-v3.1-GAP-ANALYSIS.md). Each doc specifies entities, endpoints, and invariants only — never DB schema or service boundaries, which stay backend's own call.
**Read order matches build order.** Every doc after Phase 1 depends on the ones before it (noted at the top of each). All Sprint 0.1 decisions referenced throughout were answered 2026-08-17 — see [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Sprint 0.1 for the full record.
## Launch-gate phases (P0 — required before production)
| Doc | Covers | Status |
|---|---|---|
| [PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md](PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) | Money model, FX quote, price snapshot, server-authoritative checkout amount, payment state machine | Ready |
| [PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md](PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md) | Canonical Order/OrderLine/Fulfillment (unified multi-seller), event bus, Notification Center | Ready |
| [PHASE-3-CATALOG-OFFER-FULFILLMENT-CONTRACT.md](PHASE-3-CATALOG-OFFER-FULFILLMENT-CONTRACT.md) | Product/Offer split, inventory/reservations, publish-time executability | Ready |
| [PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md](PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md) | Generic external-order connector framework (no fixed marketplace list) | Ready |
## Post-launch-gate phases (P1/P2)
| Doc | Covers | Status |
|---|---|---|
| [PHASE-5-SELLER-PORTAL-CONTRACT.md](PHASE-5-SELLER-PORTAL-CONTRACT.md) | Seller org/user/membership, seller-scoped order/fulfillment views | Ready |
| [PHASE-6-CART-CHECKOUT-CONTRACT.md](PHASE-6-CART-CHECKOUT-CONTRACT.md) | Server-owned cart, checkout session | Ready |
| [PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md](PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md) | Refunds, reconciliation, settlements | Ready |
| [PHASE-8-IDENTITY-MESSAGING-CONTRACT.md](PHASE-8-IDENTITY-MESSAGING-CONTRACT.md) | Customer identity, VK ID (built first), OTP, MAX/Telegram bots, Notification Orchestrator | Ready |
| [PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md) | Marketplace registry, Hostinger DNS automation, publish/revision model | Ready |
| [PHASE-10-CONTENT-MODULES-CONTRACT.md](PHASE-10-CONTENT-MODULES-CONTRACT.md) | Gorbushka-class mall/directory content entities | Ready, lowest priority |
## Cross-cutting tracks
| Doc | Covers | Status |
|---|---|---|
| [TRACK-A-ANALYTICS-CONTRACT.md](TRACK-A-ANALYTICS-CONTRACT.md) | Event pipeline, funnel, operational/quality metrics, synthetic-traffic separation | Ready — start alongside Phase 1, longest lead time |
| [TRACK-S-SECURITY-RBAC-CONTRACT.md](TRACK-S-SECURITY-RBAC-CONTRACT.md) | 17 roles/3 scopes, enforcement, audit log, secrets, rate limiting, step-up auth | Ready — gates the launch |
| [PARTNER-PROVISIONING-API-CONTRACT.md](PARTNER-PROVISIONING-API-CONTRACT.md) | Inbound partner API: merchant hierarchy provisioning, idempotency, public-key credentials, payment routing context | Draft — mapping decided, needs Company/Project entities |
## What is deliberately not in this directory
- **API namespace migration** — Sprint 0.1 decision: new endpoints only use `/api/v2/...` etc; legacy endpoints (`/cart`, `/orders`, `/items`) are not being migrated as part of this contract set. See `BACKEND-API-REFERENCE.md` for the current live surface.
- **Per-connector adapters** (Ozon, Wildberries, etc.) — Sprint 0.1 decision: no fixed list. [Phase 4](PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md) §8 is the onboarding runbook; each partner's adapter is written when that partner is actually onboarded.
- **Additional payment providers** (wallets, BNPL) — open business decision, not yet made. [Phase 7](PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md) §4.
## One open item across all of these
**Backend ownership — answered 2026-08-18.** A separate backend developer implements against these contracts. This repository's team owns the frontend and owns *this contract set* — the docs here are the handoff surface between the two, so a change to any contract is a change both sides must see. Keep them current; they are not a one-time deliverable.

89
docs/backend/TRACK-A-ANALYTICS-CONTRACT.md
View File

@@ -1,89 +0,0 @@
# Track A Backend Contract — Analytics Event Pipeline
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Track A. Covers plan §3.1, §6.3, §13.3.
**Status: ready to build. Start alongside Phase 1, not last** — longest lead time in the programme, and it's a P0 in the plan's own §3.1. No tracking infrastructure exists at all today; this is missing infrastructure, not a missing endpoint.
---
## 1. Event logging spine
```ts
interface AnalyticsEvent {
eventType: string; // see §2-4 for the fixed vocabulary
marketplaceId: string;
sessionId: string;
customerId?: string;
timestamp: string;
properties: Record<string, unknown>;
isSynthetic: boolean; // see §6 - mandatory, never inferred
}
```
```
POST /api/v2/storefront/analytics/events { eventType, properties } -- server-side batched ingest
```
Frontend fires events client-side; backend is the source of truth for `sessionId` and `isSynthetic` — never trust a client-asserted synthetic flag without a matching signed staging/test-environment token.
## 2. Traffic events
```
session_started, page_view, product_view (with source/utm/referrer), unique users/sessions rollups
```
## 3. Catalog events
```
search, category_view, product_view, seller_view
```
## 4. Commerce events
```
add_to_cart, cart_view, checkout_started, payment_started, payment_success, payment_failed, order_created
```
These map directly onto the Phase 1/2/6 contracts' own state transitions — emit them from the same backend code paths that already produce `PaymentEvent`/`OrderEvent`, not a separately-maintained tracking layer that can drift.
## 5. Operational + quality metrics
```ts
interface OperationalMetric {
name: 'order_paid_to_notification_latency' | 'fulfillment_time' | 'connector_lag' | 'payment_webhook_lag';
marketplaceId: string;
value: number;
unit: 'seconds' | 'minutes';
measuredAt: string;
}
```
Quality events: frontend/backend errors, checkout validation failures, FX stale-rate blocks (Phase 1 §3.2).
## 6. Synthetic traffic separation (hard requirement, plan §3.1/§6.3/§10.2)
Synthetic/load-test traffic is permitted in staging and demo environments **only**, and must be technically inseparable-by-accident from production data — i.e. `isSynthetic: true` set server-side based on environment/token, never a client-settable flag that a real visit could accidentally or deliberately carry. Business reports must filter it out by construction, not by a manual exclusion query someone has to remember to add.
## 7. Endpoints
```
GET /api/admin/v2/analytics/funnel?marketplaceId=&period=
GET /api/admin/v2/analytics/operational?marketplaceId=&metric=
GET /api/admin/v2/analytics/quality?marketplaceId=
GET /api/v2/storefront/search/trending?marketplaceId= -- top N queries over a recent window, closes the existing SearchTrendingService.loadTrending() stub (returns of(null) today)
```
## 8. Post-launch monitoring set (plan §13.3, reuses the same event stream)
```
checkout_conversion, payment_success_failure_rate, webhook_processing_lag,
order_notification_lag, external_connector_lag, fx_quote_age_errors,
unmatched_reconciliation_count, fulfillment_stuck_count
```
## 9. What the frontend will start doing once this ships
- Replace the fully mock-composed `AdminAnalyticsFacade` with real funnel data.
- Fire the event vocabulary above from the relevant storefront interaction points.
- Bridge or replace the currently-always-zero `AdminProduct.visits` column with real tracking (see `GAPS-AND-IMPROVEMENTS.md`'s admin-product-views item — already partially speced in this session's [admin product views design](../superpowers/plans/2026-08-15-admin-product-views-column.md)).
- Wire `SearchTrendingService.loadTrending()` to the real endpoint in §7.

127
docs/backend/TRACK-S-SECURITY-RBAC-CONTRACT.md
View File

@@ -1,127 +0,0 @@
# Track S Backend Contract — RBAC, Audit, Secrets, Rate Limiting
Companion to [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Track S. Covers plan §4.4, §10.
**Status: ready to build. Gates the launch — this is the single most serious security gap identified in this session's audit.** Today the admin role model is decorative: `AdminRole` and permissions exist as types, but nothing gates any button, page, or action anywhere in the app. Any authenticated admin has full access.
---
## 1. Roles (17 total, 3 scopes, per plan §4.4)
```ts
type PlatformRole = 'PLATFORM_OWNER' | 'TECH_ADMIN' | 'SECURITY_ADMIN' | 'DOMAIN_MANAGER' | 'VIEWER';
type MarketplaceRole =
| 'MARKETPLACE_ADMIN' | 'CONTENT_MANAGER' | 'CATALOG_MANAGER' | 'ORDER_MANAGER'
| 'FINANCE_MANAGER' | 'SUPPORT_MANAGER' | 'VIEWER';
type SellerRole =
| 'SELLER_OWNER' | 'SELLER_CATALOG_MANAGER' | 'SELLER_ORDER_MANAGER'
| 'SELLER_FINANCE_VIEWER' | 'SELLER_VIEWER';
```
`SellerRole` is already specified in [Phase 5's contract](PHASE-5-SELLER-PORTAL-CONTRACT.md) §4 — this doc adds the platform and marketplace scopes around it.
## 2. Enforcement (backend-side, non-negotiable)
Every `/api/admin/v2/*` and `/api/platform/v1/*` endpoint must check `(role, tenantScope)` against the acting user's session — **before** touching data, not as a post-hoc filter. `tenant scope` here means: a `MARKETPLACE_ADMIN` for marketplace A must get a `403` (not an empty result) querying marketplace B's data, never a silently-scoped response that looks like "there's just nothing here."
```
GET /api/identity/v1/session/permissions -> { role, scopes: string[], marketplaceIds: string[] }
```
Frontend route/action guards derive from this endpoint's response — never hardcode role logic client-side beyond hiding UI affordances (which is convenience, not security).
## 3. Audit log
```ts
interface AuditEvent {
id: string;
actor: string;
action: string; // e.g. 'role.changed', 'offer.price_updated', 'refund.approved'
entityType: string;
entityId: string;
before?: unknown;
after?: unknown;
reason?: string;
occurredAt: string;
ip?: string;
}
```
Mandatory coverage (plan §10.1): permission changes, seller status changes, catalog moderation actions, price changes, payment/refund actions, manual order overrides, integration credential changes, production launch actions.
```
GET /api/admin/v2/audit?marketplaceId=&entityType=&actor=&from=&to=
```
## 4. Secrets
All provider/connector credentials (payment providers, external marketplace connectors, VK/MAX/Telegram bot tokens, FX source keys) live in dedicated secret storage, referenced by opaque `credentialRef` strings in every other contract in this series — never returned in any API response body, never logged in plaintext.
### 4.1 Partner credentials (inbound)
Added 2026-08-18. Partners calling our API authenticate with signed requests, not bearer tokens. Full contract: [PARTNER-PROVISIONING-API-CONTRACT.md §6](PARTNER-PROVISIONING-API-CONTRACT.md).
These are the opposite direction from the rest of §4 and follow a different rule:
- We hold only the partner's **public** key. The private key is generated by the partner and never transmitted to us, never accepted by any endpoint, never logged. There is nothing to store in secret storage on our side.
- Authority is node-scoped: a credential may act on its `scopeNodeId` and that node's descendants, nothing above or beside it. This is a separate axis from the 17 roles in §1 — partner credentials never map onto a human role, and a partner credential can never be granted an admin role.
- `TEST` and `LIVE` credentials are disjoint. A `TEST` key addressing a `LIVE` node is `403`.
- Rotation runs with a bounded overlap window (default 7 days) during which both keys verify. Revocation is immediate and irreversible.
- A credential can never widen its own scope or register another credential at a wider scope.
Audit coverage (§3) extends to: `partner_credential.registered`, `partner_credential.rotated`, `partner_credential.revoked`, and every partner-initiated node write, with `actor` set to the `keyId` that signed the request.
## 5. Rate limiting
```
429 response: { error: { code: 'RATE_LIMITED', retryAfterSeconds: number } }
```
Applies to storefront/auth/provider endpoints. Frontend currently has **zero** 429 handling anywhere — see [BACKEND-API-REFERENCE.md §5](../../BACKEND-API-REFERENCE.md) for the full error-envelope contract this should follow.
Partner API limits are per `partnerId`, by tier, with the tier set on `PartnerProfile`. Published in the partner OpenAPI spec — a partner must be able to read its own limit rather than discover it by getting `429`.
## 6. Step-up authentication
Required before: bank/payment detail changes (Phase 5 §5), production launch (Phase 9 §3 step 8), role grants at `PLATFORM_OWNER`/`MARKETPLACE_ADMIN` level, and any manual financial override (refund approval outside normal flow, price override on a live order).
## 7. PII minimization
Customer/seller PII is exposed only to roles that need it for their scope (e.g. `FINANCE_VIEWER` sees payout totals, not raw bank account numbers unless `FINANCE_MANAGER`+). Export endpoints (`GET .../export`) are themselves audit-logged actions per §3.
## 8. Initial admin provisioning & self-service admin management
Each marketplace ships with one bootstrap `MARKETPLACE_ADMIN` account, seeded at provisioning time (Phase 9 launch step):
- `login` = marketplace slug (`projectName`)
- `password` = `{projectName}2026$`, flagged `mustChangePassword: true`
- Login succeeds but every non-auth request 403s with `PASSWORD_CHANGE_REQUIRED` until password is changed.
```
POST /api/identity/v1/session/change-password { currentPassword, newPassword }
```
A `MARKETPLACE_ADMIN` can then provision sub-admins scoped to their own marketplace only — mirrors the seller-team invite pattern in [Phase 5](PHASE-5-SELLER-PORTAL-CONTRACT.md) (`POST /api/seller/v1/team/invite`):
```
POST /api/admin/v2/team/invite { email, role: MarketplaceRole, marketplaceId }
GET /api/admin/v2/team?marketplaceId=
PATCH /api/admin/v2/team/{userId} { role }
DELETE /api/admin/v2/team/{userId}
```
Invariants:
- `role` must be one of the `MarketplaceRole` set (§1) — never `PlatformRole`. Backend rejects any attempt to grant a platform-scope role through this endpoint (`403 SCOPE_ESCALATION_DENIED`).
- `marketplaceId` is forced server-side to the caller's own tenant scope — request body value is ignored/validated, never trusted.
- Every invite/role-change/removal is an audit-logged action (§3, `action: 'admin_team.invited' | 'admin_team.role_changed' | 'admin_team.removed'`).
- Role grants at `MARKETPLACE_ADMIN` level require step-up auth (§6).
- Invited admins get their own credentials (email + set-password flow), not the shared bootstrap login — the bootstrap account is for first login only and should be rotated/retired once real admins exist.
## 9. What the frontend will start doing once this ships
- Route guards and action-level permission checks across the entire backoffice — currently none exist.
- Backoffice **Audit & Security** section (missing from admin nav today): role changes, sensitive actions, login/security events, exports.
- Reconcile `AdminRole` (already de-duplicated to one canonical type this session) against the real 17-role table from §1.
- 429 interceptor + retry-after UI.

46
docs/context/adrs/ADR-0001-extract-auth-and-payment-into-shared-marketplaces-packages.md
View File

@@ -1,46 +0,0 @@
---
id: ADR-0001
title: Extract auth and payment into shared @marketplaces packages
status: active
date: 2026-08-17
supersedes: []
tags: [architecture, auth, payment, monorepo]
---
# ADR-0001: Extract auth and payment into shared @marketplaces packages
## Context
`marketplaces` currently owns auth end-to-end: customer auth (`core/auth` — VK ID, OTP, session, facade), admin auth (`core/admin-auth` — ed25519-verified admin sessions, permission guards, interceptor), and a legacy `services/auth.service.ts`. Payment/finance logic (`core/finance`, `core/pricing`) is server-owned per [Phase 1](../../backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) and [Phase 7](../../backend/PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md) contracts — the frontend piece is thin (gateways/tokens, no business logic).
Multiple marketplace projects beyond this repo need the same auth and payment client logic. Duplicating it per-project drifts fast (auth bugs get fixed in one place, not others) and blocks a consistent security posture across projects — directly relevant to [TRACK-S-SECURITY-RBAC-CONTRACT.md](../../backend/TRACK-S-SECURITY-RBAC-CONTRACT.md), which already treats auth/RBAC as the single most serious cross-cutting concern.
## Decision
Extract auth and payment client logic into two standalone, independently versioned npm packages:
- `@marketplaces/auth` — customer auth (VK ID/OTP/session), admin auth (ed25519 verification, permission guards, interceptors), token/session management.
- `@marketplaces/payment` — payment/finance client gateways, FX/pricing models, checkout client contracts (thin — business logic stays backend per Phase 1/7).
Each package:
1. Lives in its own git repo (handed over separately; this repo does not host it long-term).
2. Is consumed by `marketplaces` (and other projects) as an installed node_modules dependency — imported, never copy-pasted.
3. Is versioned with semver; CI on the package repo auto-bumps and publishes on push to `main`, driven by conventional commit prefixes already used in this repo (`feat:`/`fix:`/etc — semantic-release reads these directly).
4. Ships with its own test suite; `marketplaces` treats it as a black-box dependency, not source to edit in place.
Rollout order: scaffold packages and CI in this repo first (reversible, local-only) → hand over target git repo → publish → migrate `marketplaces` call sites to import from the package → delete the in-repo originals only after the app builds and passes tests against the package.
## Amendment 2026-08-18 — distribution mechanism
The original decision left distribution open ("private registry ... or installed straight from git"). A private Verdaccio registry was stood up on the dev server and both packages published to it. **That approach was then abandoned**: the registry listens on `127.0.0.1:4873` behind a firewall allowing only 80/443/SSH, so neither CI runners nor developers could install without an SSH tunnel. That broke `marketplaces`' existing `architecture-governance` workflow, whose `npm ci` step could no longer resolve `@marketplaces/auth`.
Distribution is now **git release branches**: `release/auth` and `release/payment` in vitanovaPackages, each an orphan branch whose root *is* the package (`package.json` + built `dist/`), force-pushed by CI on every release. Consumers install with `git+<repo>#release/auth` — no registry, no token, no tunnel, no CI secret; anonymous git read suffices.
The Verdaccio instance still runs but nothing depends on it. Making a registry the primary path again would require a reverse proxy plus TLS on the dev server, which buys nothing over the current approach at this scale.
## Consequences
- `marketplaces` loses direct edit access to auth/payment source — changes go through the package's own repo/PR/release cycle. Slower iteration, but consistent behavior across all consuming projects.
- ~30 call sites in `marketplaces` (see `core/auth`, `core/admin-auth`, `services/auth.service.ts`, interceptors) need import rewiring during migration — tracked as follow-up work, not done in this ADR.
- New failure mode: `marketplaces` builds now depend on `sources.vitanova.network` being reachable. A branch ref also tracks its tip, so an install can pick up a new build — acceptable while the package churns, but pin to a commit SHA once it stabilises.
- [TRACK-S-SECURITY-RBAC-CONTRACT.md](../../backend/TRACK-S-SECURITY-RBAC-CONTRACT.md) §8 (admin provisioning) becomes package-owned behavior once migrated — that doc's endpoint contracts stay backend-side and unaffected, only the frontend client implementation moves.

72
docs/context/adrs/ADR-0003-generic-partner-provisioning-api.md
View File

@@ -1,72 +0,0 @@
---
id: ADR-0003
title: Build partner merchant-provisioning as a generic API, not a per-partner integration
status: active
date: 2026-08-18
supersedes: []
tags: [architecture, api, payments, multi-tenant, security, decision]
---
# ADR-0003: Build partner merchant-provisioning as a generic API, not a per-partner integration
## Context
A partner asked (2026-08-18) for an API to programmatically manage a merchant hierarchy — Company → Project → Store → PaymentPoint — with idempotent provisioning, `externalReference` lookup, TEST/LIVE separation, public-key credentials with scoped authority and rotation, and payment/callback fields that route a payment unambiguously to one store.
Their request arrived written in their own vocabulary. Building against that vocabulary directly would produce a partner-shaped API, and the next partner asking for the same capability with different level names would either get a second parallel surface or force a rename through our schema.
Three facts about our current model made the ask non-trivial:
1. Nothing exists above `Marketplace` ([Phase 9](../../backend/PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md)). No company, no project.
2. Payments carry no store dimension ([Phase 1](../../backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md) §6). Reconciliation can reconstruct *why* an amount was charged but not *who for*.
3. We have no partner-facing write API at all. [Phase 4](../../backend/PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md) is outbound/ingest — the opposite direction.
## Decision
Build one generic partner provisioning API. Contract: [PARTNER-PROVISIONING-API-CONTRACT.md](../../backend/PARTNER-PROVISIONING-API-CONTRACT.md).
### 1. Partner-specific behaviour is config, never schema
No partner name appears in any entity, field, endpoint, or status value. Everything partner-varying lives in a `PartnerProfile` row: which levels are required, level name aliases, routing field names, rate-limit tier, key rotation window, webhook field map. **Onboarding a partner is a config row, not a deployment.**
Deliberately *not* configurable, because configurability there breaks reconciliation or safety: status values and transitions, idempotency semantics, environment partitioning, signature scheme, the four-level ceiling.
### 2. Fixed four levels with optional middles, not a free-form tree
`company → project → store → payment_point`. Middle levels are omittable per partner profile; depth is never partner-defined. An arbitrary-depth tree would push every downstream consumer — routing, reconciliation, settlement, audit — into handling shapes no partner actually has.
### 3. Credentials are node-scoped
The partner asked us to choose between per-company, per-project, and per-store credentials. We answer all three with one mechanism: a credential binds to **any single node**, and its authority is that node's subtree. Partner keypairs are partner-generated; we hold only the public key. Rotation runs with a bounded overlap; revocation is immediate and irreversible.
### 4. Level mapping onto our model
| Partner level | Our entity |
|---|---|
| `company` | new, thin |
| `project` | new, thin — a product line (e.g. `marketplaces`) |
| `store` | `Marketplace` (Phase 9), gains `companyId`/`projectId`/`externalReference` |
| `payment_point` | new — one payment method accepted at one marketplace (`qr`, `card`; both ship today) |
`PaymentPoint` is an acceptance channel, not a physical till and not a settlement account. Registering one never enables real money — financial enablement is a separate approved flow that sets `providerAccountRef`.
### 5. Seller is excluded from the hierarchy
`Seller` ([Phase 5](../../backend/PHASE-5-SELLER-PORTAL-CONTRACT.md)) is orthogonal. A payment routes to one payment point, is reconciled there, and only then splits across the sellers whose lines the order contains ([Phase 7](../../backend/PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md) §3.1). Putting `Seller` in the partner hierarchy would force every partner to model our multi-seller concept, which most do not have.
### 6. RoutingContext lands in Phase 1 before implementation, not after
`RoutingContext` (companyId, routingPath, leafNodeId, environment, merchantReference, providerPaymentId) is required on `CheckoutSession`, `PaymentIntent`, `Payment`, `Refund`, `ReconciliationRecord`. Frozen at checkout-session creation, immutable thereafter.
## Consequences
**Cost now:** two new entities (`Company`, `Project`), one new leaf (`PaymentPoint`), three amended contracts (Phases 1, 7, 9) plus Track S §4.1, and a backfill for existing marketplaces (Phase 9 §1.2).
**Cost avoided:** retrofitting a routing dimension onto a populated payments table after launch; a second parallel provisioning surface for partner number two.
**Accepted limits:**
- A partner needing more than four levels cannot be served without a contract change. Judged unlikely enough to be worth the simplicity.
- Backfilled rows carry a synthetic company and project. `externalReference` stays null for them.
- Partners cannot create companies through the API — company creation stays a commercial, out-of-band action.
**Unaffected:** the `@marketplaces/auth` / `@marketplaces/payment` package split ([ADR-0001](ADR-0001-extract-auth-and-payment-into-shared-marketplaces-packages.md)). The provisioning API is backend-side; nothing about it belongs in a frontend package.

2
docs/context/features/media-manager/FACTS.jsonl
View File

@@ -1,2 +0,0 @@
{"id":"MM-20260715T000000Z-0001","subject":"media-backend","predicate":"is","object":"not implemented yet; /media routes to BackofficeComingSoonPageComponent; GET /media, POST /media/upload, DELETE /media/:id, PATCH /media/:id are the documented backend gap","src":["docs/context/adrs/ADR-0002-media-manager-contract.md","src/app/app.routes.ts"],"status":"active","kind":"constraint","confidence":"high","updated_at":"2026-07-15T00:00:00Z","tags":["media-manager","backend-gap"]}
{"id":"MM-20260715T000000Z-0002","subject":"media-storage","predicate":"is-implemented-by","object":"MediaRepository interface with MockMediaRepository (IndexedDB-backed, interim) and HttpMediaRepository (future) selected via DI token; media assets never enter the Bootstrap model","src":["docs/context/adrs/ADR-0002-media-manager-contract.md"],"status":"active","kind":"decision","confidence":"high","updated_at":"2026-07-15T00:00:00Z","tags":["media-manager","repository-pattern"]}

13
docs/context/features/platform-vision/FACTS.jsonl
View File

@@ -1,13 +0,0 @@
{"id":"PV-20260713T000000Z-0001","subject":"platform","predicate":"is-architected-as","object":"multi-tenant marketplace platform powering unlimited marketplaces from one codebase, driven entirely by backend bootstrap configuration","src":["docs/context/adrs/ADR-0001-marketplace-platform-vision.md"],"status":"active","kind":"decision","updated_at":"2026-07-13T00:00:00Z","confidence":"high","tags":["architecture","multi-tenant"]}
{"id":"PV-20260713T000000Z-0002","subject":"frontend","predicate":"must-not","object":"contain marketplace-specific code, hardcoded marketplace data, or environment-flag-driven UI","src":["docs/context/adrs/ADR-0001-marketplace-platform-vision.md"],"status":"active","kind":"constraint","updated_at":"2026-07-13T00:00:00Z","confidence":"high","tags":["frontend","constraint"]}
{"id":"PV-20260713T000000Z-0003","subject":"bootstrap","predicate":"must-only-contain","object":"data needed before app start (branding, languages, homepage layout, navigation, enabled widgets, footer pages) and must never contain products, orders, cart, or users","src":["docs/context/adrs/ADR-0001-marketplace-platform-vision.md"],"status":"active","kind":"constraint","updated_at":"2026-07-13T00:00:00Z","confidence":"high","tags":["bootstrap","constraint"]}
{"id":"PV-20260713T000000Z-0004","subject":"translatable-fields","predicate":"must-be-modeled-as","object":"generic translations.{lang} map so adding/removing a language automatically exposes/removes translation fields across all translatable objects","src":["docs/context/adrs/ADR-0001-marketplace-platform-vision.md"],"status":"active","kind":"constraint","updated_at":"2026-07-13T00:00:00Z","confidence":"high","tags":["i18n","constraint"]}
{"id":"PV-20260713T000000Z-0005","subject":"admin-app","predicate":"is-isolated-from","object":"marketplace storefront bundle: admin code never ships to storefront and vice versa, though they may share a domain","src":["docs/context/adrs/ADR-0001-marketplace-platform-vision.md"],"status":"active","kind":"constraint","updated_at":"2026-07-13T00:00:00Z","confidence":"high","tags":["admin","security"]}
{"id":"PV-20260713T000000Z-0006","subject":"widgets","predicate":"must-not-own","object":"page spacing or page width; the renderer owns sections, spacing, and page width, widgets own only their internal layout","src":["docs/context/adrs/ADR-0001-marketplace-platform-vision.md"],"status":"active","kind":"constraint","updated_at":"2026-07-13T00:00:00Z","confidence":"high","tags":["widgets","layout"]}
{"id":"PV-20260818T001500Z-a1f3","subject":"auth-and-payment-client-logic","predicate":"is-decided-to-extract-into","object":"standalone versioned npm packages @marketplaces/auth and @marketplaces/payment, installed as dependencies rather than edited in-repo","src":["docs/context/adrs/ADR-0001-extract-auth-and-payment-into-shared-marketplaces-packages.md"],"status":"active","kind":"decision","updated_at":"2026-08-18T00:15:00Z","confidence":"high","tags":["architecture","auth","payment","decision"]}
{"id":"PV-20260818T104000Z-c7d1","subject":"partner-merchant-provisioning","predicate":"is-decided-to-build-as","object":"one generic inbound API where all partner-specific behaviour is a PartnerProfile config row (required levels, level aliases, routing field names, rate tier); no partner name appears in any entity, field, endpoint or status value","src":["docs/context/adrs/ADR-0003-generic-partner-provisioning-api.md","docs/backend/PARTNER-PROVISIONING-API-CONTRACT.md"],"status":"active","kind":"decision","updated_at":"2026-08-18T10:40:00Z","confidence":"high","tags":["architecture","api","partner","decision"]}
{"id":"PV-20260818T104100Z-e2b8","subject":"partner-hierarchy-levels","predicate":"map-onto","object":"company and project are new thin entities above Marketplace; store IS Marketplace (Phase 9); payment_point is new and equals one payment method accepted at one marketplace (qr, card)","src":["docs/context/adrs/ADR-0003-generic-partner-provisioning-api.md","docs/backend/PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md"],"status":"active","kind":"decision","updated_at":"2026-08-18T10:41:00Z","confidence":"high","tags":["architecture","multi-tenant","payments","decision"]}
{"id":"PV-20260818T104200Z-f5a9","subject":"Seller","predicate":"is-excluded-from","object":"the partner provisioning hierarchy; a payment routes to exactly one payment point, is reconciled there, and only then splits across sellers in Phase 7 settlement","src":["docs/context/adrs/ADR-0003-generic-partner-provisioning-api.md","docs/backend/PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md"],"status":"active","kind":"constraint","updated_at":"2026-08-18T10:42:00Z","confidence":"high","tags":["payments","reconciliation","sellers"]}
{"id":"PV-20260818T104300Z-b3c4","subject":"RoutingContext","predicate":"is-required-on","object":"CheckoutSession, PaymentIntent, Payment, Refund and ReconciliationRecord; frozen at checkout-session creation and immutable thereafter, so a payment is always attributable to exactly one payment point","src":["docs/backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md","docs/backend/PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md"],"status":"active","kind":"constraint","updated_at":"2026-08-18T10:43:00Z","confidence":"high","tags":["payments","reconciliation","contract"]}
{"id":"PV-20260818T104400Z-d9e2","subject":"partner-api-credentials","predicate":"are-scoped-by","object":"a single node whose subtree defines authority; we hold only the partner-generated public key, rotation runs on a bounded overlap window and revocation is immediate and irreversible","src":["docs/backend/PARTNER-PROVISIONING-API-CONTRACT.md","docs/backend/TRACK-S-SECURITY-RBAC-CONTRACT.md"],"status":"active","kind":"decision","updated_at":"2026-08-18T10:44:00Z","confidence":"high","tags":["security","credentials","partner"]}
{"id":"PV-20260818T104500Z-a6f7","subject":"checkout-payment-methods","predicate":"already-support","object":"both qr and card end to end in src/app/pages/cart/cart.component.ts (separate create paths and separate status pollers); card is not an outstanding gap","src":["src/app/pages/cart/cart.component.ts","src/app/services/api.service.ts"],"status":"active","kind":"implemented","updated_at":"2026-08-18T10:45:00Z","confidence":"high","tags":["payments","frontend"]}

6
docs/context/features/project-editor/FACTS.jsonl
View File

@@ -1,6 +0,0 @@
{"id":"PE-20260713T010000Z-0001","subject":"project-editor-routing","predicate":"is","object":"flat routes under /edit/:section (no projectId — a project is the domain-resolved tenant); /builder and /project-editor redirect to /edit/general","src":["docs/superpowers/specs/2026-07-13-marketplace-project-editor-sprint16-design.md","src/app/app.routes.ts"],"status":"active","kind":"decision","updated_at":"2026-07-13T01:00:00Z","confidence":"high","tags":["project-editor","routing"]}
{"id":"PE-20260713T010000Z-0002","subject":"locale-sync","predicate":"is-implemented-by","object":"LocaleSyncService, which generically adds/removes a locale key across static page translations and navigation labels without per-field hardcoding","src":["src/app/features/project-editor/services/locale-sync.service.ts"],"status":"active","kind":"implemented","confidence":"high","updated_at":"2026-07-13T01:00:00Z","tags":["project-editor","i18n"]}
{"id":"PE-20260713T010000Z-0003","subject":"draft-publish-flow","predicate":"is","object":"client-side only (ProjectEditorFacade.status/dirty/save/publish) because no backend draft/publish endpoint exists yet; PUT /builder/bootstrap/draft and POST /builder/bootstrap/publish are the documented backend gap","src":["docs/Project-Editor.md","src/app/features/project-editor/facade/project-editor.facade.ts"],"status":"active","kind":"constraint","confidence":"high","updated_at":"2026-07-13T01:00:00Z","tags":["project-editor","backend-gap"]}
{"id":"PE-20260713T010000Z-0004","subject":"html-editing","predicate":"uses","object":"MarketplaceHtmlEditorComponent, a contentEditable + toolbar component with no external rich-text dependency; emits raw HTML, never sanitizes during editing","src":["src/app/features/project-editor/components/html-editor/marketplace-html-editor.component.ts"],"status":"active","kind":"decision","confidence":"high","updated_at":"2026-07-13T01:00:00Z","tags":["project-editor","html-editor"]}
{"id":"PE-20260713T010000Z-0005","subject":"navigation-tab","predicate":"supports","object":"header navigation and flat-list footer navigation (add/remove/reorder/edit); grouped-column footer navigation is read-only until a future sprint","src":["src/app/features/project-editor/sections/navigation-section.component.ts"],"status":"active","kind":"constraint","confidence":"high","updated_at":"2026-07-13T01:00:00Z","tags":["project-editor","navigation"]}
{"id":"PE-20260716T220000Z-0006","subject":"config-schema-and-validation","predicate":"is-implemented-by","object":"a field-schema registry (schema/editor-schema.ts, EditorSchemaService) driving centralized, severity-tagged validation (ProjectValidator composing pure schema/validators/primitives functions) and debounced undo/redo (schema/history.util) in ProjectEditorFacade; section templates stay hand-authored (metadata-augmented, not schema-rendered)","src":["docs/context/adrs/ADR-0002-project-editor-config-schema-and-validation-engine.md","src/app/features/project-editor/schema/editor-schema.ts","src/app/features/project-editor/services/project-validator.service.ts","src/app/features/project-editor/facade/project-editor.facade.ts"],"status":"active","kind":"decision","confidence":"high","updated_at":"2026-07-16T22:00:00Z","tags":["project-editor","schema","validation","undo-redo"]}

225
docs/superpowers/plans/2026-08-15-admin-product-views-column.md
View File

@@ -1,225 +0,0 @@
# Admin Product Views Column Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Show a real (currently-zero) per-product view count as a toggleable column in Admin Products list, and document the backend gap that keeps it at zero today.
**Architecture:** Add `visits: number` to the `AdminProduct` model, default it to `0` everywhere the mock gateway constructs an `AdminProduct`, add `'visits'` to the existing toggleable-column system (`ALL_PRODUCT_COLUMNS`), render it in the table view using the established `isColumnVisible()` pattern.
**Tech Stack:** Angular signals, existing `LocalStorageService`-backed column-visibility persistence (already built, not touched).
## Global Constraints
- Never fabricate view numbers — the mock gateway has no real tracking source, so `visits` must default to `0`, not a random/seeded number.
- Table view only — no grid-view or product-detail-page display (out of scope per design doc).
- Follow the existing `isColumnVisible('stock')`-style pattern exactly — no new column-visibility mechanism.
---
### Task 1: `visits` field, column, and backend doc ask
**Files:**
- Modify: `src/app/features/admin/products/models/admin-product.model.ts:81-121` (add field)
- Modify: `src/app/features/admin/products/services/admin-products-local.gateway.ts:82-94,133-166` (default the field)
- Modify: `src/app/features/admin/products/facade/admin-products.facade.ts:39` (add to column list)
- Modify: `src/app/features/admin/products/components/admin-products-list.component.html:96-112` (render column + header)
- Modify: `src/app/i18n/en.ts:1647,1670`, `src/app/i18n/ru.ts:1642`, `src/app/i18n/hy.ts:1642`, `src/app/i18n/translations.ts:1655` (i18n keys)
- Modify: `BACKEND-API-REFERENCE.md` (new §12.10 ask)
- Test: `src/app/features/admin/products/services/admin-products-local.gateway.spec.ts` (new)
**Interfaces:**
- Produces: `AdminProduct.visits: number`
- Produces: `ALL_PRODUCT_COLUMNS` includes `'visits'` (so `AdminProductColumn` union includes `'visits'`)
- [ ] **Step 1: Write the failing test**
Create `src/app/features/admin/products/services/admin-products-local.gateway.spec.ts`:
```typescript
import { TestBed } from '@angular/core/testing';
import { provideHttpClient } from '@angular/common/http';
import { provideHttpClientTesting } from '@angular/common/http/testing';
import { AdminProductsLocalGateway } from './admin-products-local.gateway';
describe('AdminProductsLocalGateway visits field', () => {
let gateway: AdminProductsLocalGateway;
beforeEach(() => {
TestBed.configureTestingModule({
providers: [provideHttpClient(), provideHttpClientTesting()],
});
gateway = TestBed.inject(AdminProductsLocalGateway);
});
it('defaults visits to 0 on every loaded product', (done) => {
gateway.loadProducts({ search: '', categoryId: 'all', visibility: 'all', stockStatus: 'all', page: 1, pageSize: 50 }).subscribe(result => {
expect(result.items.length).toBeGreaterThan(0);
expect(result.items.every(product => product.visits === 0)).toBe(true);
done();
});
});
it('resets visits to 0 on a duplicated product, even if the source had a nonzero count', (done) => {
gateway.loadProducts({ search: '', categoryId: 'all', visibility: 'all', stockStatus: 'all', page: 1, pageSize: 50 }).subscribe(result => {
const source = result.items[0];
gateway.duplicateProduct(source.id).subscribe(duplicated => {
expect(duplicated).not.toBeNull();
expect(duplicated!.visits).toBe(0);
done();
});
});
});
});
```
Note: read `src/app/features/admin/products/models/admin-product.model.ts` for the exact `AdminProductListFilters` shape before writing the test's filter object — if the field names above (`categoryId`, `visibility`, `stockStatus`, `page`, `pageSize`) don't match exactly, use the real ones; don't guess.
- [ ] **Step 2: Run test to verify it fails**
Run: `npm run test -- --include='**/admin-products-local.gateway.spec.ts'`
Expected: FAIL — `Property 'visits' does not exist on type 'AdminProduct'` (TS compile error surfaces as a Karma failure).
- [ ] **Step 3: Add the field to the model**
In `src/app/features/admin/products/models/admin-product.model.ts`, add to the `AdminProduct` interface (next to `quantity: number;`):
```typescript
quantity: number;
visits: number;
```
- [ ] **Step 4: Default it in the mock gateway**
In `src/app/features/admin/products/services/admin-products-local.gateway.ts`, in `toAdminProduct()` (around line 155, next to the `quantity` line):
```typescript
quantity: product.stockStatus === 'out_of_stock' ? 0 : product.stockStatus === 'low_stock' ? 3 : 25,
visits: 0,
```
In `duplicateProduct()` (around line 82-91), add `visits: 0` to the override object so a duplicate never inherits the source's count via the `...source` spread:
```typescript
const duplicated: AdminProduct = {
...source,
archived: false,
id: `${source.id}-copy-${Date.now()}`,
sku: `${source.sku}-COPY`,
slug: `${source.slug}-copy-${Date.now()}`,
name: `${source.name} Copy`,
visits: 0,
createdAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
};
```
- [ ] **Step 5: Run test to verify it passes**
Run: `npm run test -- --include='**/admin-products-local.gateway.spec.ts'`
Expected: PASS (2/2)
- [ ] **Step 6: Add the column**
In `src/app/features/admin/products/facade/admin-products.facade.ts:39`, change:
```typescript
export const ALL_PRODUCT_COLUMNS = ['sku', 'brand', 'price', 'stock', 'visibility', 'updated'] as const;
```
to:
```typescript
export const ALL_PRODUCT_COLUMNS = ['sku', 'brand', 'price', 'stock', 'visibility', 'updated', 'visits'] as const;
```
In `src/app/features/admin/products/components/admin-products-list.component.html`, add a header cell after the `visibility` header (around line 100):
```html
@if (isColumnVisible('visibility')) { <th scope="col">{{ 'adminProducts.visibility' | translate }}</th> }
@if (isColumnVisible('visits')) { <th scope="col">{{ 'adminProducts.views' | translate }}</th> }
```
And a matching body cell after the `visibility` cell (around line 126, right after its closing `}`):
```html
@if (isColumnVisible('visits')) { <td>{{ product.visits }}</td> }
```
The column-picker panel (`admin-products-list.component.html:50-59`) needs no template change — it already iterates `allColumns` generically and looks up `adminProducts.column_<name>`, so it auto-picks up `'visits'` once the i18n key exists (Step 7).
- [ ] **Step 7: Add i18n keys**
In `src/app/i18n/translations.ts`, in the `adminProducts` interface block, add two lines (next to `stockStatus: string;` and near the other `column_*` entries):
```typescript
stockStatus: string;
views: string;
```
```typescript
column_updated: string;
column_visits: string;
```
In `src/app/i18n/en.ts`, `adminProducts` block:
```typescript
stockStatus: 'Stock status',
views: 'Views',
```
```typescript
column_updated: 'Last updated',
column_visits: 'Views',
```
In `src/app/i18n/ru.ts`, `adminProducts` block (next to its `stockStatus:` line and its `column_updated:` line — read the file first to find them, they're at different line numbers than en.ts):
```typescript
views: 'Просмотры',
```
```typescript
column_visits: 'Просмотры',
```
In `src/app/i18n/hy.ts`, `adminProducts` block:
```typescript
views: 'Դիտումներ',
```
```typescript
column_visits: 'Դիտումներ',
```
(For ru.ts/hy.ts: read the file first, find the exact existing `stockStatus:`/`column_updated:` lines in the `adminProducts` block — there may be more than one `column_updated:` in the file for a different admin domain, only edit the one inside `adminProducts`, at the location already found: `ru.ts:1642` area, `hy.ts:1642` area.)
- [ ] **Step 8: Run full verification**
Run: `npx tsc --noEmit -p tsconfig.json`
Expected: no errors.
Run: `npx ng build --configuration development`
Expected: build succeeds.
Run: `npm run test -- --include='**/admin-products-local.gateway.spec.ts'`
Expected: PASS (2/2).
- [ ] **Step 9: Document the backend gap**
In `BACKEND-API-REFERENCE.md`, after the existing §12.8 section (search for `### 12.8 Admin purchase notifications depend on Orders CRUD being real` — it currently ends right before `### 12.9 Trending search terms`), insert a new section, and renumber `12.9` to `12.10`:
```markdown
### 12.9 Admin product view counts
**Gap:** Admin Products (§8) runs on a fully separate mock domain from the storefront's live catalog — `AdminProduct.visits` is a new field added to support a "Views" column in Admin Products, but the mock gateway always defaults it to `0` because there is no real tracking source available to the admin domain today. This is unrelated to the storefront's `Item.visits` field (§6, `/items/{id}`), which is live-wired but never displayed anywhere in the UI.
**Ask:** two options, not mutually exclusive:
1. Once admin Products gets a real backend (§10 step 4), include a per-product view/visit count in the response.
2. Bridge `AdminProduct.visits` to the storefront's already-live `Item.visits` by product id, if a unified product identity exists between the storefront and admin domains — smaller change than building new tracking infrastructure.
### 12.10 Trending search terms
```
(The existing body text of the old `### 12.9 Trending search terms` section stays exactly as-is below the renumbered heading — only the heading number changes, from `12.9` to `12.10`.)
- [ ] **Step 10: Commit**
```bash
git add src/app/features/admin/products/models/admin-product.model.ts src/app/features/admin/products/services/admin-products-local.gateway.ts src/app/features/admin/products/services/admin-products-local.gateway.spec.ts src/app/features/admin/products/facade/admin-products.facade.ts src/app/features/admin/products/components/admin-products-list.component.html src/app/i18n/en.ts src/app/i18n/ru.ts src/app/i18n/hy.ts src/app/i18n/translations.ts BACKEND-API-REFERENCE.md
git commit -m "feat: admin product views column (always 0 until backend tracks it)"
```

944
docs/superpowers/plans/2026-08-15-admin-purchase-notifications.md
View File

@@ -1,944 +0,0 @@
# Admin Purchase Notifications Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Notify admin (toast + topbar bell badge/panel) when a new order lands on the marketplace, poll-based since the backend has no WebSocket/SSE.
**Architecture:** A single `AdminOrderWatcherService` polls `AdminOrdersLocalGateway.loadOrders()` on an editable interval (default 15s), diffs against a persisted "last notified" order id to fire toasts for genuinely new orders, and exposes a `recentOrders`/`unreadCount` signal pair that the existing (currently-empty) topbar bell panel renders. Poll interval is editable in the admin settings page, same pattern as the currency-rates section added previously.
**Tech Stack:** Angular 17+ signals, RxJS, Jasmine/Karma (`ng test`), existing `LocalStorageService`/`UserNotificationService`/`TranslateService` patterns.
## Global Constraints
- No WebSocket/SSE available — polling only (confirmed `BACKEND-API-REFERENCE.md:20`).
- Persist state via `LocalStorageService` (`getItem`/`setItem`), never raw `localStorage`.
- Reuse the existing topbar bell (`admin-layout.component.html:141-157`) instead of adding a new nav badge.
- Admin backoffice price/amount displays stay in the order's raw stored currency (no `currencyConvert` pipe) — consistent with every other admin screen.
- Route arrays for admin navigation use the pattern `[languageService.currentLanguage(), 'backoffice', 'orders', id]` (no leading `/`), matching `admin-orders-list-page.component.ts:52`.
---
### Task 1: `UserNotificationService` gains an optional click-to-navigate route
**Files:**
- Modify: `src/app/features/website/user-experience/services/user-notification.service.ts`
- Modify: `src/app/features/website/user-experience/components/floating-notifications/floating-notifications.component.ts`
- Modify: `src/app/features/website/user-experience/components/floating-notifications/floating-notifications.component.html`
- Test: `src/app/features/website/user-experience/services/user-notification.service.spec.ts` (new)
**Interfaces:**
- Produces: `UserNotificationService.show(message: string, type?: UserNotificationType, durationMs?: number, route?: string[]): void`
- Produces: `UserNotification.route?: string[]`
- [ ] **Step 1: Write the failing test**
Create `src/app/features/website/user-experience/services/user-notification.service.spec.ts`:
```typescript
import { TestBed } from '@angular/core/testing';
import { UserNotificationService } from './user-notification.service';
describe('UserNotificationService', () => {
let service: UserNotificationService;
beforeEach(() => {
TestBed.configureTestingModule({});
service = TestBed.inject(UserNotificationService);
});
it('stores the route on the notification when provided', () => {
service.show('New order #1042', 'info', 4000, ['en', 'backoffice', 'orders', 'ord_1']);
const [note] = service.notifications();
expect(note.message).toBe('New order #1042');
expect(note.route).toEqual(['en', 'backoffice', 'orders', 'ord_1']);
});
it('leaves route undefined when not provided', () => {
service.show('Saved');
const [note] = service.notifications();
expect(note.route).toBeUndefined();
});
});
```
- [ ] **Step 2: Run test to verify it fails**
Run: `npm run test -- --include='**/user-notification.service.spec.ts'`
Expected: FAIL — `show` has no fourth parameter, `route` does not exist on `UserNotification`.
- [ ] **Step 3: Implement**
Replace the full contents of `src/app/features/website/user-experience/services/user-notification.service.ts`:
```typescript
import { Injectable, signal } from '@angular/core';
export type UserNotificationType = 'success' | 'info' | 'warning';
export interface UserNotification {
id: string;
message: string;
type: UserNotificationType;
/** Route to navigate to when the notification is clicked. Absent means not clickable. */
route?: string[];
}
@Injectable({ providedIn: 'root' })
export class UserNotificationService {
private readonly state = signal<UserNotification[]>([]);
readonly notifications = this.state.asReadonly();
show(message: string, type: UserNotificationType = 'info', durationMs: number = 2500, route?: string[]): void {
const next: UserNotification = {
id: `note-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
message,
type,
...(route ? { route } : {}),
};
this.state.update(items => [next, ...items].slice(0, 4));
setTimeout(() => this.dismiss(next.id), durationMs);
}
dismiss(id: string): void {
this.state.update(items => items.filter(item => item.id !== id));
}
}
```
Modify `src/app/features/website/user-experience/components/floating-notifications/floating-notifications.component.ts` — replace full contents:
```typescript
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { Router } from '@angular/router';
import { UserNotification, UserNotificationService } from '../../services/user-notification.service';
import { TranslatePipe } from '../../../../../i18n/translate.pipe';
@Component({
selector: 'app-floating-notifications',
standalone: true,
imports: [TranslatePipe],
templateUrl: './floating-notifications.component.html',
styleUrls: ['./floating-notifications.component.scss'],
changeDetection: ChangeDetectionStrategy.OnPush
})
export class FloatingNotificationsComponent {
private readonly notificationsService = inject(UserNotificationService);
private readonly router = inject(Router);
readonly notifications = this.notificationsService.notifications;
dismiss(id: string): void {
this.notificationsService.dismiss(id);
}
navigate(note: UserNotification): void {
if (note.route) {
void this.router.navigate(note.route);
}
this.dismiss(note.id);
}
}
```
Replace full contents of `src/app/features/website/user-experience/components/floating-notifications/floating-notifications.component.html`:
```html
@if (notifications().length > 0) {
<aside class="floating-notifications" aria-live="polite" aria-atomic="true">
@for (note of notifications(); track note.id) {
<article
class="floating-note"
[class]="'floating-note floating-note-' + note.type"
[class.floating-note-clickable]="!!note.route"
(click)="note.route && navigate(note)"
>
<p>{{ note.message }}</p>
<button type="button" (click)="$event.stopPropagation(); dismiss(note.id)" [attr.aria-label]="'common.dismiss' | translate">×</button>
</article>
}
</aside>
}
```
- [ ] **Step 4: Run test to verify it passes**
Run: `npm run test -- --include='**/user-notification.service.spec.ts'`
Expected: PASS (2 specs)
- [ ] **Step 5: Commit**
```bash
git add src/app/features/website/user-experience/services/user-notification.service.ts src/app/features/website/user-experience/services/user-notification.service.spec.ts src/app/features/website/user-experience/components/floating-notifications/floating-notifications.component.ts src/app/features/website/user-experience/components/floating-notifications/floating-notifications.component.html
git commit -m "feat: UserNotificationService supports click-to-navigate toasts"
```
---
### Task 2: `AdminOrderWatcherService` — polling, diffing, toast firing
**Files:**
- Create: `src/app/features/admin/shell/services/admin-order-watcher.service.ts`
- Test: `src/app/features/admin/shell/services/admin-order-watcher.service.spec.ts`
- Modify: `src/app/i18n/translations.ts`, `src/app/i18n/en.ts`, `src/app/i18n/ru.ts`, `src/app/i18n/hy.ts` (one new key)
**Interfaces:**
- Consumes: `AdminOrdersLocalGateway.loadOrders(filters: AdminOrderListFilters): Observable<AdminOrdersListResult>` (existing)
- Consumes: `UserNotificationService.show(message, type?, durationMs?, route?)` (Task 1)
- Consumes: `LocalStorageService.getItem(key): string | null`, `.setItem(key, value): void` (existing)
- Produces: `AdminOrderWatcherService.recentOrders: Signal<AdminOrder[]>`
- Produces: `AdminOrderWatcherService.unreadCount: Signal<number>`
- Produces: `AdminOrderWatcherService.intervalMs: Signal<number>`
- Produces: `AdminOrderWatcherService.start(): void`
- Produces: `AdminOrderWatcherService.markAllSeen(): void`
- Produces: `AdminOrderWatcherService.setIntervalSeconds(seconds: number): void`
- [ ] **Step 1: Add the i18n key first (needed by the test's translated toast message)**
In `src/app/i18n/translations.ts`, inside the `topbar:` block under `adminShell` (next to `notificationsEmpty: string;`):
```typescript
notificationsEmpty: string;
notificationNewOrder: string;
```
In `src/app/i18n/en.ts`, inside `adminShell.topbar` (next to `notificationsEmpty:`):
```typescript
notificationsEmpty: 'No new notifications',
notificationNewOrder: 'New order #{{orderNumber}}',
```
In `src/app/i18n/ru.ts`, inside `adminShell.topbar`:
```typescript
notificationsEmpty: 'Нет новых уведомлений',
notificationNewOrder: 'Новый заказ №{{orderNumber}}',
```
In `src/app/i18n/hy.ts`, inside `adminShell.topbar`:
```typescript
notificationsEmpty: 'Նոր ծանուցումներ չկան',
notificationNewOrder: 'Նոր պատվեր #{{orderNumber}}',
```
(Match each file's existing `notificationsEmpty` value/indentation exactly — only add the new line after it.)
- [ ] **Step 2: Write the failing test**
Create `src/app/features/admin/shell/services/admin-order-watcher.service.spec.ts`:
```typescript
import { TestBed, fakeAsync, tick } from '@angular/core/testing';
import { provideRouter } from '@angular/router';
import { of } from 'rxjs';
import { AdminOrderWatcherService } from './admin-order-watcher.service';
import { AdminOrdersLocalGateway } from '../../orders/services/admin-orders-local.gateway';
import { AdminOrder, AdminOrdersListResult } from '../../orders/models/admin-order.model';
import { UserNotificationService } from '../../../website/user-experience/services/user-notification.service';
function makeOrder(id: string, orderNumber: string, createdAt: string): AdminOrder {
return {
id,
orderNumber,
status: 'pending',
customer: { name: 'Test Customer', email: 't@example.com', phone: '+70000000000' },
payment: { method: 'card', status: 'paid', amount: 1000, currency: 'RUB' },
shipping: { address: '', method: '', trackingNumber: '' },
items: [],
total: 1000,
currency: 'RUB',
notes: '',
internalNotes: '',
timeline: [],
archived: false,
createdAt,
updatedAt: createdAt,
};
}
describe('AdminOrderWatcherService', () => {
let ordersByPoll: AdminOrder[][];
let pollIndex: number;
let notifications: UserNotificationService;
let service: AdminOrderWatcherService;
function fakeGateway() {
return {
loadOrders: () => {
const items = ordersByPoll[pollIndex] ?? ordersByPoll[ordersByPoll.length - 1];
const result: AdminOrdersListResult = { items, total: items.length, page: 1, pageSize: 20 };
return of(result);
},
};
}
beforeEach(() => {
pollIndex = 0;
ordersByPoll = [
[makeOrder('o2', '1002', '2026-08-15T10:00:00.000Z'), makeOrder('o1', '1001', '2026-08-15T09:00:00.000Z')],
];
localStorage.clear();
TestBed.configureTestingModule({
providers: [
provideRouter([]),
{ provide: AdminOrdersLocalGateway, useValue: fakeGateway() as unknown as AdminOrdersLocalGateway },
],
});
notifications = TestBed.inject(UserNotificationService);
service = TestBed.inject(AdminOrderWatcherService);
});
it('does not toast on the very first poll and marks everything as acknowledged', fakeAsync(() => {
service.start();
tick(0);
expect(notifications.notifications().length).toBe(0);
expect(service.unreadCount()).toBe(0);
expect(service.recentOrders().map(o => o.id)).toEqual(['o2', 'o1']);
}));
it('toasts and increments unreadCount for orders newer than the last-notified one', fakeAsync(() => {
service.start();
tick(0);
pollIndex = 1;
ordersByPoll.push([
makeOrder('o3', '1003', '2026-08-15T11:00:00.000Z'),
makeOrder('o2', '1002', '2026-08-15T10:00:00.000Z'),
makeOrder('o1', '1001', '2026-08-15T09:00:00.000Z'),
]);
tick(service.intervalMs());
expect(notifications.notifications().length).toBe(1);
expect(notifications.notifications()[0].message).toContain('1003');
expect(notifications.notifications()[0].route).toEqual(['ru', 'backoffice', 'orders', 'o3']);
expect(service.unreadCount()).toBe(1);
}));
it('markAllSeen resets unreadCount without clearing recentOrders', fakeAsync(() => {
service.start();
tick(0);
pollIndex = 1;
ordersByPoll.push([
makeOrder('o3', '1003', '2026-08-15T11:00:00.000Z'),
makeOrder('o2', '1002', '2026-08-15T10:00:00.000Z'),
makeOrder('o1', '1001', '2026-08-15T09:00:00.000Z'),
]);
tick(service.intervalMs());
expect(service.unreadCount()).toBe(1);
service.markAllSeen();
expect(service.unreadCount()).toBe(0);
expect(service.recentOrders().map(o => o.id)).toEqual(['o3', 'o2', 'o1']);
}));
it('setIntervalSeconds updates intervalMs and rejects invalid values', () => {
service.setIntervalSeconds(30);
expect(service.intervalMs()).toBe(30000);
service.setIntervalSeconds(0);
expect(service.intervalMs()).toBe(30000);
service.setIntervalSeconds(-5);
expect(service.intervalMs()).toBe(30000);
});
});
```
Note: `LanguageService` defaults to `'ru'` (see `language.service.ts:23`), which is why the expected route in the second test starts with `'ru'`.
- [ ] **Step 3: Run test to verify it fails**
Run: `npm run test -- --include='**/admin-order-watcher.service.spec.ts'`
Expected: FAIL — `admin-order-watcher.service.ts` does not exist yet.
- [ ] **Step 4: Implement**
Create `src/app/features/admin/shell/services/admin-order-watcher.service.ts`:
```typescript
import { Injectable, Signal, computed, inject, signal } from '@angular/core';
import { AdminOrder } from '../../orders/models/admin-order.model';
import { AdminOrdersLocalGateway } from '../../orders/services/admin-orders-local.gateway';
import { LocalStorageService } from '../../../../core/storage/local-storage.service';
import { UserNotificationService } from '../../../website/user-experience/services/user-notification.service';
import { LanguageService } from '../../../../services/language.service';
import { TranslateService } from '../../../../i18n/translate.service';
const LAST_NOTIFIED_KEY = 'adminOrderWatcher.lastNotifiedOrderId.v1';
const LAST_ACKNOWLEDGED_KEY = 'adminOrderWatcher.lastAcknowledgedOrderId.v1';
const POLL_INTERVAL_KEY = 'adminOrderWatcher.pollIntervalMs.v1';
export const DEFAULT_POLL_INTERVAL_MS = 15000;
const MIN_POLL_INTERVAL_MS = 1000;
const RECENT_ORDERS_LIMIT = 20;
const TOAST_DURATION_MS = 4000;
@Injectable({ providedIn: 'root' })
export class AdminOrderWatcherService {
private readonly gateway = inject(AdminOrdersLocalGateway);
private readonly storage = inject(LocalStorageService);
private readonly notifications = inject(UserNotificationService);
private readonly languageService = inject(LanguageService);
private readonly i18n = inject(TranslateService);
private readonly recentOrdersSignal = signal<AdminOrder[]>([]);
readonly recentOrders: Signal<AdminOrder[]> = this.recentOrdersSignal.asReadonly();
private readonly lastAcknowledgedOrderIdSignal = signal<string | null>(this.storage.getItem(LAST_ACKNOWLEDGED_KEY));
readonly unreadCount = computed(() => {
const orders = this.recentOrdersSignal();
if (orders.length === 0) {
return 0;
}
const ackId = this.lastAcknowledgedOrderIdSignal();
if (ackId === null) {
return orders.length;
}
const idx = orders.findIndex(order => order.id === ackId);
return idx === -1 ? orders.length : idx;
});
private readonly intervalMsSignal = signal<number>(this.readStoredIntervalMs());
readonly intervalMs: Signal<number> = this.intervalMsSignal.asReadonly();
private lastNotifiedOrderId: string | null = this.storage.getItem(LAST_NOTIFIED_KEY);
private timerId: ReturnType<typeof setInterval> | null = null;
private started = false;
start(): void {
if (this.started) {
return;
}
this.started = true;
this.poll();
this.scheduleNext();
}
setIntervalSeconds(seconds: number): void {
if (!Number.isFinite(seconds) || seconds < MIN_POLL_INTERVAL_MS / 1000) {
return;
}
const ms = Math.round(seconds * 1000);
this.intervalMsSignal.set(ms);
this.storage.setItem(POLL_INTERVAL_KEY, String(ms));
if (this.started) {
this.scheduleNext();
}
}
markAllSeen(): void {
const newestId = this.recentOrdersSignal()[0]?.id ?? null;
this.lastAcknowledgedOrderIdSignal.set(newestId);
if (newestId) {
this.storage.setItem(LAST_ACKNOWLEDGED_KEY, newestId);
}
}
private scheduleNext(): void {
if (this.timerId !== null) {
clearInterval(this.timerId);
}
this.timerId = setInterval(() => this.poll(), this.intervalMsSignal());
}
private poll(): void {
this.gateway.loadOrders({ search: '', status: 'all', page: 1, pageSize: RECENT_ORDERS_LIMIT }).subscribe({
next: result => this.handleOrders(result.items),
error: err => console.error('Error polling for new orders:', err),
});
}
private handleOrders(items: AdminOrder[]): void {
this.recentOrdersSignal.set(items);
if (items.length === 0) {
return;
}
const isFirstPoll = this.lastNotifiedOrderId === null;
const notifyIndex = isFirstPoll ? -1 : items.findIndex(order => order.id === this.lastNotifiedOrderId);
const newOrders = isFirstPoll ? [] : (notifyIndex === -1 ? items : items.slice(0, notifyIndex));
this.lastNotifiedOrderId = items[0].id;
this.storage.setItem(LAST_NOTIFIED_KEY, this.lastNotifiedOrderId);
if (isFirstPoll) {
// Nothing existed to compare against yet - treat current orders as already
// acknowledged so a fresh admin session doesn't see the whole history as unread.
if (this.lastAcknowledgedOrderIdSignal() === null) {
this.lastAcknowledgedOrderIdSignal.set(items[0].id);
this.storage.setItem(LAST_ACKNOWLEDGED_KEY, items[0].id);
}
return;
}
for (let i = newOrders.length - 1; i >= 0; i--) {
const order = newOrders[i];
this.notifications.show(
this.i18n.t('adminShell.topbar.notificationNewOrder', { orderNumber: order.orderNumber }),
'info',
TOAST_DURATION_MS,
[this.languageService.currentLanguage(), 'backoffice', 'orders', order.id]
);
}
}
private readStoredIntervalMs(): number {
const stored = Number(this.storage.getItem(POLL_INTERVAL_KEY));
return Number.isFinite(stored) && stored >= MIN_POLL_INTERVAL_MS ? stored : DEFAULT_POLL_INTERVAL_MS;
}
}
```
- [ ] **Step 5: Run test to verify it passes**
Run: `npm run test -- --include='**/admin-order-watcher.service.spec.ts'`
Expected: PASS (4 specs)
- [ ] **Step 6: Commit**
```bash
git add src/app/features/admin/shell/services/admin-order-watcher.service.ts src/app/features/admin/shell/services/admin-order-watcher.service.spec.ts src/app/i18n/translations.ts src/app/i18n/en.ts src/app/i18n/ru.ts src/app/i18n/hy.ts
git commit -m "feat: AdminOrderWatcherService polls for new orders and toasts"
```
---
### Task 3: Wire the watcher into the admin topbar bell
**Files:**
- Modify: `src/app/features/admin/shell/admin-layout.component.ts`
- Modify: `src/app/features/admin/shell/admin-layout.component.html`
- Modify: `src/app/features/admin/shell/admin-layout.component.scss`
- Test: `src/app/features/admin/shell/admin-layout.component.spec.ts` (new)
**Interfaces:**
- Consumes: `AdminOrderWatcherService.{recentOrders, unreadCount, start, markAllSeen}` (Task 2)
- [ ] **Step 1: Write the failing test**
Create `src/app/features/admin/shell/admin-layout.component.spec.ts`:
```typescript
import { TestBed } from '@angular/core/testing';
import { provideRouter } from '@angular/router';
import { signal } from '@angular/core';
import { AdminLayoutComponent } from './admin-layout.component';
import { AdminOrderWatcherService } from './services/admin-order-watcher.service';
import { AdminOrder } from '../orders/models/admin-order.model';
function makeOrder(id: string, orderNumber: string): AdminOrder {
return {
id,
orderNumber,
status: 'pending',
customer: { name: 'Test Customer', email: 't@example.com', phone: '' },
payment: { method: 'card', status: 'paid', amount: 500, currency: 'RUB' },
shipping: { address: '', method: '', trackingNumber: '' },
items: [],
total: 500,
currency: 'RUB',
notes: '',
internalNotes: '',
timeline: [],
archived: false,
createdAt: '2026-08-15T10:00:00.000Z',
updatedAt: '2026-08-15T10:00:00.000Z',
};
}
describe('AdminLayoutComponent notifications bell', () => {
let watcherStub: {
recentOrders: ReturnType<typeof signal<AdminOrder[]>>;
unreadCount: ReturnType<typeof signal<number>>;
start: jasmine.Spy;
markAllSeen: jasmine.Spy;
};
beforeEach(() => {
watcherStub = {
recentOrders: signal<AdminOrder[]>([makeOrder('o1', '1001')]),
unreadCount: signal(1),
start: jasmine.createSpy('start'),
markAllSeen: jasmine.createSpy('markAllSeen'),
};
TestBed.configureTestingModule({
imports: [AdminLayoutComponent],
providers: [
provideRouter([]),
{ provide: AdminOrderWatcherService, useValue: watcherStub },
],
});
});
it('starts the watcher once on construction', () => {
TestBed.createComponent(AdminLayoutComponent);
expect(watcherStub.start).toHaveBeenCalledTimes(1);
});
it('exposes unreadCount and recentOrders from the watcher', () => {
const fixture = TestBed.createComponent(AdminLayoutComponent);
const component = fixture.componentInstance;
expect(component.unreadCount()).toBe(1);
expect(component.recentOrders().map(o => o.id)).toEqual(['o1']);
});
it('marks orders seen when the notifications panel opens', () => {
const fixture = TestBed.createComponent(AdminLayoutComponent);
const component = fixture.componentInstance;
component.toggleNotifications();
expect(component.notificationsOpen()).toBe(true);
expect(watcherStub.markAllSeen).toHaveBeenCalledTimes(1);
component.toggleNotifications();
expect(component.notificationsOpen()).toBe(false);
expect(watcherStub.markAllSeen).toHaveBeenCalledTimes(1);
});
});
```
- [ ] **Step 2: Run test to verify it fails**
Run: `npm run test -- --include='**/admin-layout.component.spec.ts'`
Expected: FAIL — `AdminOrderWatcherService` not referenced by the component yet, `unreadCount`/`recentOrders` don't exist on `AdminLayoutComponent`.
- [ ] **Step 3: Implement**
In `src/app/features/admin/shell/admin-layout.component.ts`, add the import and field (place near the other service injections):
```typescript
import { AdminOrderWatcherService } from './services/admin-order-watcher.service';
```
```typescript
private readonly orderWatcher = inject(AdminOrderWatcherService);
readonly unreadCount = this.orderWatcher.unreadCount;
readonly recentOrders = this.orderWatcher.recentOrders;
```
In the constructor, after `this.readRouteData();`, add:
```typescript
this.orderWatcher.start();
```
Replace the `toggleNotifications` method:
```typescript
toggleNotifications(): void {
this.notificationsOpen.update(open => !open);
if (this.notificationsOpen()) {
this.orderWatcher.markAllSeen();
}
}
```
Add a navigation helper next to `adminLinkFor`:
```typescript
goToOrder(orderId: string): void {
void this.router.navigate([this.currentLang(), 'backoffice', 'orders', orderId]);
this.notificationsOpen.set(false);
}
```
In `src/app/features/admin/shell/admin-layout.component.html`, replace the notifications block (lines 141-157):
```html
<div class="admin-layout__notifications">
<button
type="button"
class="admin-layout__icon-button"
aria-haspopup="true"
[attr.aria-expanded]="notificationsOpen()"
[attr.aria-label]="'adminShell.topbar.notifications' | translate"
(click)="toggleNotifications()"
>
<app-icon name="bell" [size]="18" />
@if (unreadCount() > 0) {
<span class="admin-layout__notifications-badge">{{ unreadCount() }}</span>
}
</button>
@if (notificationsOpen()) {
<div class="admin-layout__notifications-panel" role="menu">
@if (recentOrders().length === 0) {
<p>{{ 'adminShell.topbar.notificationsEmpty' | translate }}</p>
} @else {
@for (order of recentOrders(); track order.id) {
<button
type="button"
class="admin-layout__notification-item"
role="menuitem"
(click)="goToOrder(order.id)"
>
<span class="admin-layout__notification-order">#{{ order.orderNumber }}</span>
<span class="admin-layout__notification-customer">{{ order.customer.name }}</span>
<span class="admin-layout__notification-amount">{{ order.total }} {{ order.currency }}</span>
</button>
}
}
</div>
}
</div>
```
In `src/app/features/admin/shell/admin-layout.component.scss`, add (near other `.admin-layout__notifications*` rules if any exist, otherwise at the end):
```scss
.admin-layout__notifications {
position: relative;
}
.admin-layout__notifications-badge {
position: absolute;
top: 2px;
right: 2px;
min-width: 16px;
height: 16px;
padding: 0 4px;
border-radius: 999px;
background: var(--color-danger, #ef4444);
color: #fff;
font-size: 10px;
line-height: 16px;
text-align: center;
}
.admin-layout__notification-item {
display: flex;
flex-direction: column;
gap: 2px;
width: 100%;
padding: 8px 10px;
border: none;
background: none;
text-align: left;
cursor: pointer;
border-radius: var(--radius-sm, 4px);
}
.admin-layout__notification-item:hover {
background: var(--bg-secondary, #f4f6f5);
}
.admin-layout__notification-order { font-weight: var(--font-weight-medium, 500); }
.admin-layout__notification-customer { color: var(--text-secondary, #6b7280); font-size: var(--font-size-sm, 0.8125rem); }
.admin-layout__notification-amount { font-size: var(--font-size-sm, 0.8125rem); }
```
- [ ] **Step 4: Run test to verify it passes**
Run: `npm run test -- --include='**/admin-layout.component.spec.ts'`
Expected: PASS (3 specs)
- [ ] **Step 5: Run full build to catch template errors**
Run: `npx ng build --configuration development`
Expected: build succeeds, no template compile errors.
- [ ] **Step 6: Commit**
```bash
git add src/app/features/admin/shell/admin-layout.component.ts src/app/features/admin/shell/admin-layout.component.html src/app/features/admin/shell/admin-layout.component.scss src/app/features/admin/shell/admin-layout.component.spec.ts
git commit -m "feat: wire order watcher into admin topbar bell (badge + panel)"
```
---
### Task 4: Editable poll interval in admin settings
**Files:**
- Modify: `src/app/features/admin/settings/pages/admin-settings-page.component.ts`
- Modify: `src/app/features/admin/settings/pages/admin-settings-page.component.html`
- Modify: `src/app/i18n/translations.ts`, `src/app/i18n/en.ts`, `src/app/i18n/ru.ts`, `src/app/i18n/hy.ts`
- Test: `src/app/features/admin/settings/pages/admin-settings-page.component.spec.ts` (new)
**Interfaces:**
- Consumes: `AdminOrderWatcherService.{intervalMs, setIntervalSeconds}` (Task 2)
- [ ] **Step 1: Add i18n keys**
In `src/app/i18n/translations.ts`, inside `adminSettings:` (after `currencyRatesSaved: string;`):
```typescript
notificationInterval: string;
notificationIntervalExplain: string;
notificationIntervalSave: string;
notificationIntervalSaved: string;
```
In `src/app/i18n/en.ts`, inside `adminSettings` (after `currencyRatesSaved: 'Rates saved',`):
```typescript
notificationInterval: 'New-order check interval (seconds)',
notificationIntervalExplain: 'How often the admin panel polls for new orders to show a notification.',
notificationIntervalSave: 'Save interval',
notificationIntervalSaved: 'Interval saved',
```
In `src/app/i18n/ru.ts`, inside `adminSettings` (after `currencyRatesSaved: 'Курсы сохранены',`):
```typescript
notificationInterval: 'Интервал проверки новых заказов (сек)',
notificationIntervalExplain: 'Как часто админ-панель проверяет новые заказы для уведомления.',
notificationIntervalSave: 'Сохранить интервал',
notificationIntervalSaved: 'Интервал сохранён',
```
In `src/app/i18n/hy.ts`, inside `adminSettings` (after `currencyRatesSaved: 'Փոխարժեքները պահպանվեցին',`):
```typescript
notificationInterval: 'Նոր պատվերների ստուգման ինտերվալ (վրկ)',
notificationIntervalExplain: 'Որքան հաճախ է ադմին վահանակը ստուգում նոր պատվերներ ծանուցման համար։',
notificationIntervalSave: 'Պահպանել ինտերվալը',
notificationIntervalSaved: 'Ինտերվալը պահպանվեց',
```
- [ ] **Step 2: Write the failing test**
Create `src/app/features/admin/settings/pages/admin-settings-page.component.spec.ts`:
```typescript
import { TestBed } from '@angular/core/testing';
import { provideRouter } from '@angular/router';
import { signal } from '@angular/core';
import { AdminSettingsPageComponent } from './admin-settings-page.component';
import { AdminOrderWatcherService } from '../../shell/services/admin-order-watcher.service';
describe('AdminSettingsPageComponent notification interval', () => {
let watcherStub: {
intervalMs: ReturnType<typeof signal<number>>;
setIntervalSeconds: jasmine.Spy;
};
beforeEach(() => {
watcherStub = {
intervalMs: signal(15000),
setIntervalSeconds: jasmine.createSpy('setIntervalSeconds'),
};
TestBed.configureTestingModule({
imports: [AdminSettingsPageComponent],
providers: [
provideRouter([]),
{ provide: AdminOrderWatcherService, useValue: watcherStub },
],
});
});
it('initializes the draft from the current interval in seconds', () => {
const fixture = TestBed.createComponent(AdminSettingsPageComponent);
expect(fixture.componentInstance.notificationIntervalSecondsDraft()).toBe(15);
});
it('saveNotificationInterval calls setIntervalSeconds with the draft value', () => {
const fixture = TestBed.createComponent(AdminSettingsPageComponent);
const component = fixture.componentInstance;
component.notificationIntervalSecondsDraft.set(30);
component.saveNotificationInterval();
expect(watcherStub.setIntervalSeconds).toHaveBeenCalledWith(30);
});
});
```
- [ ] **Step 3: Run test to verify it fails**
Run: `npm run test -- --include='**/admin-settings-page.component.spec.ts'`
Expected: FAIL — `notificationIntervalSecondsDraft`/`saveNotificationInterval` don't exist yet.
- [ ] **Step 4: Implement**
In `src/app/features/admin/settings/pages/admin-settings-page.component.ts`, add the import:
```typescript
import { AdminOrderWatcherService } from '../../shell/services/admin-order-watcher.service';
```
Add the field and methods to the class (alongside the currency-rates fields):
```typescript
readonly orderWatcher = inject(AdminOrderWatcherService);
readonly notificationIntervalSecondsDraft = signal(Math.round(this.orderWatcher.intervalMs() / 1000));
readonly showNotificationIntervalSaved = signal(false);
saveNotificationInterval(): void {
this.orderWatcher.setIntervalSeconds(this.notificationIntervalSecondsDraft());
this.showNotificationIntervalSaved.set(true);
setTimeout(() => this.showNotificationIntervalSaved.set(false), SAVED_MESSAGE_DURATION_MS);
}
```
In `src/app/features/admin/settings/pages/admin-settings-page.component.html`, add a new `.settings-card` block after the currency-rates one (before the closing `</section>`):
```html
<div class="settings-card">
<h2>{{ 'adminSettings.notificationInterval' | translate }}</h2>
<p class="settings-explain">{{ 'adminSettings.notificationIntervalExplain' | translate }}</p>
<div class="rate-row">
<input
class="rate-input"
type="number"
min="1"
step="1"
[ngModel]="notificationIntervalSecondsDraft()"
(ngModelChange)="notificationIntervalSecondsDraft.set($event)"
/>
</div>
<div class="rate-actions">
<button type="button" class="save-button" (click)="saveNotificationInterval()">{{ 'adminSettings.notificationIntervalSave' | translate }}</button>
<span class="saved-message" *ngIf="showNotificationIntervalSaved()">{{ 'adminSettings.notificationIntervalSaved' | translate }}</span>
</div>
</div>
```
- [ ] **Step 5: Run test to verify it passes**
Run: `npm run test -- --include='**/admin-settings-page.component.spec.ts'`
Expected: PASS (2 specs)
- [ ] **Step 6: Full verification**
Run: `npx tsc --noEmit -p tsconfig.json`
Expected: no errors.
Run: `npx ng build --configuration development`
Expected: build succeeds.
Run: `npm run test -- --include='**/admin-order-watcher.service.spec.ts' --include='**/admin-layout.component.spec.ts' --include='**/admin-settings-page.component.spec.ts' --include='**/user-notification.service.spec.ts'`
Expected: all specs PASS.
- [ ] **Step 7: Commit**
```bash
git add src/app/features/admin/settings/pages/admin-settings-page.component.ts src/app/features/admin/settings/pages/admin-settings-page.component.html src/app/features/admin/settings/pages/admin-settings-page.component.spec.ts src/app/i18n/translations.ts src/app/i18n/en.ts src/app/i18n/ru.ts src/app/i18n/hy.ts
git commit -m "feat: editable new-order poll interval in admin settings"
```
---
## Manual Verification (after all tasks)
1. `npm run barry -- kb search --source cq --query "admin order notifications"` if KB sharing is enabled (skip if local-only — see project `CLAUDE.md`).
2. Start the dev server, log into `/backoffice`, leave the tab open.
3. In another tab (or via `admin-orders-local.gateway.ts`'s seed data timing), wait for the poll interval — confirm no toast fires on first load.
4. Trigger a new order (checkout flow in `cart.component.ts`, or temporarily lower `SEED_COUNT`/seed timing in `admin-orders-local.gateway.ts` to simulate one — revert after testing) and confirm: toast appears with the order number, bell badge shows `1`, clicking either navigates to `/backoffice/orders/:id`.
5. Open the bell panel without clicking a row — confirm badge clears but the order still lists in the panel.
6. Change the interval in Admin Settings, save, confirm the toast "Interval saved" message. no crash on next poll cycle.

38
docs/superpowers/specs/2026-08-15-admin-product-views-column-design.md
View File

@@ -1,38 +0,0 @@
# Admin product view count column — design
**Status:** Approved
**Date:** 2026-08-15
**Related backlog item:** #1 (site traffic counter)
## Problem
User reported "site traffic isn't visible, counter shows low." Investigation found two separate things already exist and are working as intended, neither of which is the actual gap:
- Admin Analytics → Traffic tab already shows an honest `"Unknown - available after backend"` badge (`admin-analytics-page.component.html:231`) — no fake data, correctly reflects that no traffic-tracking pipeline exists at all (`BACKEND-API-REFERENCE.md` §10 step 10).
- The storefront `Item.visits` field is wired end-to-end from the live backend (`api.service.ts:438`) but is never rendered anywhere in the UI, and the backend mock always seeds it `0`.
User confirmed (via clarifying question) the actual complaint is: **no per-product view count visible in Admin Products.**
Further investigation found Admin Products runs on a fully separate mock domain (`AdminProduct` model, `admin-products-local.gateway.ts`, seeded from `list.json`) that has no relationship to the storefront's live `Item.visits` pipeline at all. So a "Views" column here cannot show real per-product traffic today — there is no data source for it in the admin domain. This mirrors the currency/FX and order-notification gaps already documented this session: build the honest client-side piece, document the backend gap explicitly, never fabricate numbers.
## Design
**Model:** add `visits: number` to `AdminProduct` (`src/app/features/admin/products/models/admin-product.model.ts`), alongside the other stat-like fields (`priority`, `quantity`).
**Mock gateway:** `admin-products-local.gateway.ts` defaults `visits: 0` when building the in-memory seed from `list.json` — no fabricated numbers, matches the field's actual state (nothing increments it yet).
**List column:** `ALL_PRODUCT_COLUMNS` (`admin-products.facade.ts:39`) gains `'visits'`. Rendered in `admin-products-list.component.html` table view only (grid view is out of scope per user's placement choice), following the exact existing `isColumnVisible('stock')`/`isColumnVisible('price')` pattern — toggleable via the same column-picker UI, persisted the same way (`LocalStorageService`, `COLUMNS_KEY`).
**i18n:** one new key, `adminProducts.views` (label for the column header), added to `en.ts`/`ru.ts`/`hy.ts`/`translations.ts`.
## Backend doc update
New `BACKEND-API-REFERENCE.md` §12.x ask (numbered after the existing 12.8, following the established "Gap / Ask" format): the admin Products domain has no view-count source. Two options to raise:
1. Once admin Products gets a real backend (§10 step 4), include a view/visit count per product in the response.
2. Alternatively, bridge to the storefront's already-live `Item.visits` (§6, `/items/{id}`) by product id — smaller change if a unified product identity exists between the storefront and admin domains.
## Out of scope
- Storefront customer-facing "N people viewed this" display — not requested, deferred (was offered as a placement option, not chosen).
- Product edit/detail page display — not requested (list column only, per user's placement choice).
- Any client-side view tracking/incrementing — explicitly rejected in favor of the honest display-only approach; a client-only counter would only reflect the admin's own browser, not real shoppers, same trap already avoided for currency rates.

86
docs/superpowers/specs/2026-08-15-admin-purchase-notifications-design.md
View File

@@ -1,86 +0,0 @@
# Admin purchase notifications — design
**Status:** Approved
**Date:** 2026-08-15
**Related backlog item:** #7 (marked ВАЖНО — important)
## Problem
Admin has no signal when a purchase happens on the marketplace. Orders only surface if
someone manually opens the Orders list and refreshes. Backend exposes no WebSocket/SSE
(confirmed in `BACKEND-API-REFERENCE.md:20` — every "live" feature today, e.g. payment
status, is plain polling), so this has to be poll-based like the rest of the app.
## Architecture
**`AdminOrderWatcherService`** (new, `providedIn: root`, admin-scoped)
- Polls `AdminOrdersLocalGateway.loadOrders()` (sorted `createdAt` desc, already the
default sort) on an interval.
- Diffs the newest order's `id`/`createdAt` against the last-seen value, kept in memory
and persisted via `LocalStorageService` (survives page reload, same pattern as
`AdminPreferencesService`).
- On finding order(s) newer than last-seen: fires one toast per new order and
increments an `unreadCount` signal.
- Started once at the admin shell root, so it keeps polling regardless of which admin
page is open.
**Poll interval**
- Editable by admin, default 15s.
- Setting lives in the same admin-settings page as currency rates
(`admin-settings-page.component.ts`), persisted via `LocalStorageService`.
**Toast delivery**
- Reuses the existing `UserNotificationService` / `FloatingNotificationsComponent`
(already global — `providedIn: root`, mounted once in `app.html`). No new toast UI.
- `UserNotification` gains an optional `route: string[]` field.
- `FloatingNotificationsComponent` gets a click handler: navigate to `route` (if set)
then dismiss.
**Badge — reuses existing topbar bell**
`admin-layout.component.html:141-157` already has an unused bell icon +
dropdown panel (currently hardcoded to always show "no notifications").
Wire the watcher's data into it instead of adding a new indicator:
- `unreadCount` signal (from `AdminOrderWatcherService`) rendered as a badge
on the bell icon (`admin-layout__icon-button`).
- Opening the panel (`notificationsOpen()`, already wired to the bell click)
lists the unread new orders instead of the static "notificationsEmpty"
text.
- Opening the panel marks all currently-known orders as seen → badge resets
to 0 (same trigger `AdminLayoutComponent.toggleNotifications()` already
has).
**Click behavior**
- Toast click → `/admin/orders/:id` (the new order's detail page).
- Clicking an order row inside the bell panel → same, then closes the panel.
## Data flow
```
AdminOrderWatcherService (interval timer)
-> AdminOrdersLocalGateway.loadOrders()
-> diff against last-seen order id/createdAt (LocalStorageService)
-> new order(s) found?
-> UserNotificationService.show(message, 'info', { route: ['/admin/orders', id] })
-> unreadCount.update(n => n + 1)
-> admin clicks toast/badge -> router navigate -> orders-list visit resets unreadCount
```
## Error handling
Poll failures are silent/logged only (`console.error`), consistent with existing
polling code (payment status polling in `cart.component.ts`). No toast spam on
transient network errors — watcher just retries on the next interval.
## Out of scope
- Native OS push notifications (tab not focused) — user explicitly chose in-app
toast/badge only, not browser Notification API.
- Sound alerts — not selected.
- Telegram/email alerts to staff — not selected, would need backend bot/mail
integration.

83
docs/superpowers/specs/2026-08-15-email-phone-login-design.md
View File

@@ -1,83 +0,0 @@
# Email/phone customer login (OTP) — design
**Status:** Approved
**Date:** 2026-08-15
**Related backlog item:** #4 (Telegram-only identification)
## Problem
Customer storefront login/checkout requires Telegram today (`src/app/services/auth.service.ts`, `TelegramSessionApiService`) — shoppers without Telegram have no way to identify themselves. User asked for email/phone as an alternative.
Backend has zero email/phone/OTP/password infrastructure — only Telegram session polling exists (`BACKEND-API-REFERENCE.md` §2a). Building real authentication client-side is not possible; this is fundamentally a backend feature. Per user's explicit choice, this round produces the design + backend spec only — no client UI/code, since there is no real backend to build a working feature against yet (mirrors the currency-FX and admin-notifications backend-dependency pattern already documented this session).
## Design
**Mechanism: OTP code (email or SMS)**, chosen over magic link (email-only, extra click) and password (heaviest backend lift — storage, hashing, reset flow). Passwordless matches the feel of the existing Telegram QR flow.
**A third, independent auth mechanism** — coexists with Telegram QR (§2a) and admin Ed25519 (§2b, still unimplemented) exactly the way those two already coexist. Does not replace or modify either.
### Proposed backend endpoints
```
POST /auth/otp/request
Body: { "identifier": "user@example.com" } // or E.164 phone: "+79991234567"
Response: { "requestId": "...", "expiresAt": "2026-08-15T10:15:00Z" }
```
```
POST /auth/otp/verify
Body: { "requestId": "...", "code": "482913" }
Response (on success): {
"sessionId": "...",
"userId": 8823771,
"username": null,
"displayName": "user@example.com",
"active": true,
"expires": "2026-08-15T11:15:00Z"
}
```
The success response is shaped identically to the existing `AuthSession` model (`src/app/models/auth.model.ts`) — `sessionId`, `userId`, `username`, `displayName`, `active`, `expires`. This is deliberate: every downstream consumer (auth guards, session signals, cart/checkout) already works against `AuthSession` regardless of which mechanism produced it, so wiring this in later requires no changes to guards or session state — only a new "request/verify" UI flow that ends by populating the same session shape Telegram QR already produces.
**Rate limiting / expiry (backend-enforced, not left implicit):**
- Resend cooldown: 60s between `POST /auth/otp/request` calls for the same identifier.
- Code expiry: 10 minutes from issuance.
- `requestId` allows up to 5 verify attempts before it's invalidated — consumed on success, on the 5th wrong attempt, or on expiry, whichever comes first. (Revised from an earlier single-use-per-attempt draft: burning the whole request on one typo is bad UX — a shopper should be able to correct a mistyped digit without waiting out a fresh 60s cooldown.)
### Admin-configurable login methods
Admin can enable/disable each login method independently — Telegram QR, Email OTP, Phone OTP — via three checkboxes in Admin Settings, same section/pattern as the existing currency-rates and notification-interval settings (`admin-settings-page.component.ts`, `LocalStorageService`-persisted signal).
- Default: all three enabled — a settings change must never silently lock shoppers out.
- A new `AuthMethodsService` (or an extension of the existing settings service) exposes `enabledMethods: Signal<('telegram' | 'email' | 'phone')[]>`. The storefront login screen reads it and only renders buttons for enabled methods; if exactly one is enabled, skip the method-picker screen entirely and go straight to it.
- Purely a client-side UI gate — the backend OTP endpoints stay unconditionally available; disabling "Email OTP" in admin just hides the button, it doesn't need a corresponding backend flag. (Same category of client-only gate as the existing `adminAuthGuard`/permission checks — real enforcement, if ever needed, would be a separate backend concern.)
### Error handling
The codebase has an established error envelope (`BACKEND-API-REFERENCE.md` §5: `error.code`, `error.message`, `error.status`, `error.details`) explicitly flagged as "recommended for new endpoints, not wired anywhere yet." Since the OTP endpoints are new, this is the natural first real adopter — every response maps to a specific code, not just an HTTP status:
| `error.code` | HTTP status | UX |
|---|---|---|
| `VALIDATION_FAILED` | 422 | Inline field error under the identifier input, sourced from `error.details[0].message` — same pattern the client already uses for local validation errors (`cart.component.ts`'s email/phone inline errors), so a 422 slots into the existing inline-error UI without inventing a second display mechanism. |
| `RATE_LIMITED` | 429 | "Too many attempts — try again in Ns," countdown derived from `error.details`/`Retry-After` if present, otherwise a flat 60s. Resend button stays disabled until the countdown ends. |
| `CODE_EXPIRED` | 410 | "This code expired — request a new one." Auto-focuses/enables the resend action; does not silently re-send. |
| `CODE_INVALID` | 401 | "Wrong code, try again" — stays on the code-entry screen (does not consume the whole flow; see the 5-attempt allowance above). Shows the remaining-attempts count once ≤2 remain. |
| `REQUEST_NOT_FOUND` | 404 | `requestId` unknown/already invalidated (5 wrong attempts, expiry, or a stale reload) — "This login attempt is no longer valid, start again," returns to the identifier-entry step. |
| Anything else / network error / 5xx | — | Generic fallback: "Something went wrong. Try again, or use a different login method" — the second half of that sentence is a real, populated action, not filler text: it surfaces whichever other methods are currently enabled per the admin toggle above (e.g. falls back to the Telegram QR button), not just a dead-end retry link. |
**Identifier validation:** email vs. phone format is auto-detected client-side. Extract the validation logic already written inline in `cart.component.ts` (`validateEmail`/`validatePhone`, currently only used for post-purchase contact capture) into a shared utility rather than duplicating it when the client UI is eventually built — the same email/phone shape-checking applies to both use cases.
### Future client UI (not built this round)
A "Login with email or phone" option next to the existing Telegram QR button: identifier entry → code entry → session established. Deferred until the backend endpoints above exist — no client code to write against a 404.
## Backend doc update
New `BACKEND-API-REFERENCE.md` §2c ("Email/phone OTP login — customer (NOT IMPLEMENTED)"), following the same Gap/Ask format as the existing §12.x entries, documenting the two endpoints, the response-shape compatibility requirement, and the rate-limit/expiry asks above.
## Out of scope
- Admin backoffice login — user confirmed this round is customer-storefront only (item 4 was split into two potential specs during brainstorming; admin auth is a separate future spec if wanted).
- Magic link and password mechanisms — considered, OTP chosen.
- Any client-side UI or session-handling code — explicitly deferred; nothing to build against a non-existent backend.
- Account merging (e.g. a shopper who later links Telegram + email to the same identity) — not raised, not designed.

137
docs/superpowers/specs/2026-08-15-platform-super-admin-design.md
View File

@@ -1,137 +0,0 @@
# Platform Super-Admin — Phase 1 Design
**Status:** Approved
**Date:** 2026-08-15
**Audience:** Internal admin & risk team ("super puper user")
## Purpose
A cross-tenant view for internal admin/risk staff: see every project (store/tenant) on the
platform, drill into one, and review its access list, audit log, admin edit history, and
purchase history. Read-only in this phase.
Editing project data / impersonating a store's admin ("edit all", with a per-change "notify
this store's admin" toggle) is explicitly **out of scope** for this phase — see
[Phase 2](#phase-2-out-of-scope-here) below. Phase 1 exists first because Phase 2's edit and
notify plumbing depends on the tenant-context switch this phase builds.
## Non-goals (Phase 1)
- No editing of any tenant's data.
- No impersonation of a store's admin.
- No "notify store admin" mechanism (that's a Phase 2 concern, tied to edit actions that
don't exist yet).
- No real backend — this repo is frontend-only; the backend contract is specified here for
whoever owns that service, not implemented here.
## Architecture
- New top-level feature module: `src/app/features/platform-admin/`.
- New route tree `/platform-admin/**`, own shell/layout. **Not** nested under any tenant's
`/admin/**` — a project is not "logged into" the way a store admin is.
- New `platformAdminAuthGuard` (parallel to, but sharing no state with, `adminAuthGuard` in
`core/admin-auth/admin-auth.guard.ts`).
- `PlatformAuthService` — session/login state for the super-admin, backed by a
`PlatformAuthGateway` interface: `login(credentials)`, `logout()`, `session()`.
- `PlatformAuthLocalGateway` — dev-only implementation. Reads the expected credential from
a **git-ignored** local file (`platform-auth.local-secret.ts`, added to `.gitignore`),
never committed, never present in a production build path.
- `PlatformAuthApiGateway` — later swap-in once the backend endpoint exists; same
interface, no caller changes needed.
## Data model
```ts
interface PlatformProjectSummary {
id: UUID;
name: string;
slug: string;
host: string;
status: 'active' | 'suspended';
createdAt: number;
adminCount: number;
lastActivityAt: number | null;
}
interface PlatformProjectAccessEntry {
userId: UUID;
displayName: string;
telegramUsername: string;
roleId: string; // maps to existing AdminRole / ROLE_PERMISSIONS
}
type PlatformProjectHistoryEntry =
| { kind: 'access'; tenantId: UUID; actorLabel: string; timestamp: number; summary: string }
| { kind: 'edit'; tenantId: UUID; actorLabel: string; timestamp: number; summary: string }
| { kind: 'purchase'; tenantId: UUID; actorLabel: string; timestamp: number; summary: string };
```
- `PlatformProjectSummary[]` is produced by `PlatformProjectsGateway.list()`, which aggregates
the existing `TenantConfig` fixture list plus derived stats. Mock gateway now; real
aggregation is a backend concern later.
- `PlatformProjectAccessEntry` reuses the existing `AdminRole` / `ROLE_PERMISSIONS` shape from
`core/auth/models/permission.model.ts` — no new role system.
- `PlatformProjectHistoryEntry` is a discriminated union covering all three history types the
user asked for (access/audit, admin edit history, purchase history). Mock gateway simulates
aggregation from existing per-tenant sources (e.g. the pattern in
`AdminDashboardHistoryService`, `admin-transactions`); real aggregation is a backend concern.
- Every super-admin **view** into a project also writes its own `kind: 'access'` entry
(`platform.viewedProject`) — the risk team needs to know who looked at what, not just what
changed.
## Components / pages
- `PlatformProjectsListPageComponent` — table of all projects: name, status, admin count,
last activity. Search/filter by status.
- `PlatformProjectDetailPageComponent` — project overview stats, then tabs:
- **Access** — `PlatformProjectAccessEntry[]` for that tenant.
- **Audit Log** — `history` filtered to `kind: 'access'`.
- **Edit History** — `history` filtered to `kind: 'edit'`.
- **Purchase History** — `history` filtered to `kind: 'purchase'`.
- All read-only in this phase.
## Security
- `platformAdminAuthGuard` denies unless the session carries `platform.superadmin`. Like the
existing `AdminPermissionsService`, the frontend check is defense-in-depth only — real
enforcement must happen server-side once the backend endpoint exists. This is called out
explicitly so it's never mistaken for the source of truth.
- No credential is ever hardcoded in committed source. Dev-only credential lives in a
git-ignored local file; production auth goes through the real backend endpoint below.
- Session timeout for platform-admin: 15 minutes idle (shorter than regular tenant-admin
sessions — higher-privilege session, smaller blast radius if a session is left open).
- Every super-admin action (including read-only views) is itself audit-logged.
- After implementation, run `/security-audit` on this feature specifically before it ships.
### Backend contract (for whoever owns that service — not implemented in this repo)
Add to `BACKEND-API-REFERENCE.md`:
- `POST /platform-admin/auth` — verifies a hashed credential server-side, returns a session
token scoped to `platform.superadmin`. Never a plaintext credential check in a client-shipped
artifact.
- `GET /platform-admin/projects` — returns `PlatformProjectSummary[]`.
- `GET /platform-admin/projects/:id/history` — returns `PlatformProjectHistoryEntry[]` for
that tenant, paginated.
## Testing
- Unit tests: `platformAdminAuthGuard`, `PlatformProjectsGateway` (mock), history-aggregation
mapping logic.
- No E2E in this phase — no real backend to exercise end-to-end yet.
## Phase 2 (out of scope here)
A separate spec/plan cycle, once Phase 1 ships:
- Full edit / impersonation: super-admin acts as a tenant's admin across every existing admin
module (products, orders, categories, settings, etc.), reusing those modules under a
tenant-context switch.
- Per-edit-action **"notify this store's admin about this change"** checkbox, **default
unchecked**. Uses the existing in-app notification pattern (the one behind
`admin-order-watcher.service.ts`'s unread-badge flow) so the affected tenant's admin sees it
in their notification feed. Unchecked-by-default matters: some super-admin edits are
discreet technical fixes where alerting the store admin would be noise or a reputational
concern, not every edit should ping them.
- This phase needs the tenant-context switch and audit-logging plumbing this Phase 1 spec
establishes, which is why it's sequenced after.

137
docs/superpowers/specs/superuser.md
View File

@@ -1,137 +0,0 @@
# Platform Super-Admin — Phase 1 Design
**Status:** Approved
**Date:** 2026-08-15
**Audience:** Internal admin & risk team ("super puper user")
## Purpose
A cross-tenant view for internal admin/risk staff: see every project (store/tenant) on the
platform, drill into one, and review its access list, audit log, admin edit history, and
purchase history. Read-only in this phase.
Editing project data / impersonating a store's admin ("edit all", with a per-change "notify
this store's admin" toggle) is explicitly **out of scope** for this phase — see
[Phase 2](#phase-2-out-of-scope-here) below. Phase 1 exists first because Phase 2's edit and
notify plumbing depends on the tenant-context switch this phase builds.
## Non-goals (Phase 1)
- No editing of any tenant's data.
- No impersonation of a store's admin.
- No "notify store admin" mechanism (that's a Phase 2 concern, tied to edit actions that
don't exist yet).
- No real backend — this repo is frontend-only; the backend contract is specified here for
whoever owns that service, not implemented here.
## Architecture
- New top-level feature module: `src/app/features/platform-admin/`.
- New route tree `/platform-admin/**`, own shell/layout. **Not** nested under any tenant's
`/admin/**` — a project is not "logged into" the way a store admin is.
- New `platformAdminAuthGuard` (parallel to, but sharing no state with, `adminAuthGuard` in
`core/admin-auth/admin-auth.guard.ts`).
- `PlatformAuthService` — session/login state for the super-admin, backed by a
`PlatformAuthGateway` interface: `login(credentials)`, `logout()`, `session()`.
- `PlatformAuthLocalGateway` — dev-only implementation. Reads the expected credential from
a **git-ignored** local file (`platform-auth.local-secret.ts`, added to `.gitignore`),
never committed, never present in a production build path.
- `PlatformAuthApiGateway` — later swap-in once the backend endpoint exists; same
interface, no caller changes needed.
## Data model
```ts
interface PlatformProjectSummary {
id: UUID;
name: string;
slug: string;
host: string;
status: 'active' | 'suspended';
createdAt: number;
adminCount: number;
lastActivityAt: number | null;
}
interface PlatformProjectAccessEntry {
userId: UUID;
displayName: string;
telegramUsername: string;
roleId: string; // maps to existing AdminRole / ROLE_PERMISSIONS
}
type PlatformProjectHistoryEntry =
| { kind: 'access'; tenantId: UUID; actorLabel: string; timestamp: number; summary: string }
| { kind: 'edit'; tenantId: UUID; actorLabel: string; timestamp: number; summary: string }
| { kind: 'purchase'; tenantId: UUID; actorLabel: string; timestamp: number; summary: string };
```
- `PlatformProjectSummary[]` is produced by `PlatformProjectsGateway.list()`, which aggregates
the existing `TenantConfig` fixture list plus derived stats. Mock gateway now; real
aggregation is a backend concern later.
- `PlatformProjectAccessEntry` reuses the existing `AdminRole` / `ROLE_PERMISSIONS` shape from
`core/auth/models/permission.model.ts` — no new role system.
- `PlatformProjectHistoryEntry` is a discriminated union covering all three history types the
user asked for (access/audit, admin edit history, purchase history). Mock gateway simulates
aggregation from existing per-tenant sources (e.g. the pattern in
`AdminDashboardHistoryService`, `admin-transactions`); real aggregation is a backend concern.
- Every super-admin **view** into a project also writes its own `kind: 'access'` entry
(`platform.viewedProject`) — the risk team needs to know who looked at what, not just what
changed.
## Components / pages
- `PlatformProjectsListPageComponent` — table of all projects: name, status, admin count,
last activity. Search/filter by status.
- `PlatformProjectDetailPageComponent` — project overview stats, then tabs:
- **Access** — `PlatformProjectAccessEntry[]` for that tenant.
- **Audit Log** — `history` filtered to `kind: 'access'`.
- **Edit History** — `history` filtered to `kind: 'edit'`.
- **Purchase History** — `history` filtered to `kind: 'purchase'`.
- All read-only in this phase.
## Security
- `platformAdminAuthGuard` denies unless the session carries `platform.superadmin`. Like the
existing `AdminPermissionsService`, the frontend check is defense-in-depth only — real
enforcement must happen server-side once the backend endpoint exists. This is called out
explicitly so it's never mistaken for the source of truth.
- No credential is ever hardcoded in committed source. Dev-only credential lives in a
git-ignored local file; production auth goes through the real backend endpoint below.
- Session timeout for platform-admin: 15 minutes idle (shorter than regular tenant-admin
sessions — higher-privilege session, smaller blast radius if a session is left open).
- Every super-admin action (including read-only views) is itself audit-logged.
- After implementation, run `/security-audit` on this feature specifically before it ships.
### Backend contract (for whoever owns that service — not implemented in this repo)
Add to `BACKEND-API-REFERENCE.md`:
- `POST /platform-admin/auth` — verifies a hashed credential server-side, returns a session
token scoped to `platform.superadmin`. Never a plaintext credential check in a client-shipped
artifact.
- `GET /platform-admin/projects` — returns `PlatformProjectSummary[]`.
- `GET /platform-admin/projects/:id/history` — returns `PlatformProjectHistoryEntry[]` for
that tenant, paginated.
## Testing
- Unit tests: `platformAdminAuthGuard`, `PlatformProjectsGateway` (mock), history-aggregation
mapping logic.
- No E2E in this phase — no real backend to exercise end-to-end yet.
## Phase 2 (out of scope here)
A separate spec/plan cycle, once Phase 1 ships:
- Full edit / impersonation: super-admin acts as a tenant's admin across every existing admin
module (products, orders, categories, settings, etc.), reusing those modules under a
tenant-context switch.
- Per-edit-action **"notify this store's admin about this change"** checkbox, **default
unchecked**. Uses the existing in-app notification pattern (the one behind
`admin-order-watcher.service.ts`'s unread-badge flow) so the affected tenant's admin sees it
in their notification feed. Unchecked-by-default matters: some super-admin edits are
discreet technical fixes where alerting the store admin would be noise or a reputational
concern, not every edit should ping them.
- This phase needs the tenant-context switch and audit-logging plumbing this Phase 1 spec
establishes, which is why it's sequenced after.

551
docs/telegram-login-dialog.html Normal file
View File

@@ -0,0 +1,551 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Telegram Login Dialog</title>
<style>
:root {
--bg-page: linear-gradient(135deg, #f4f7fb 0%, #e8eef4 100%);
--bg-card: #ffffff;
--bg-hover: #f0f0f0;
--text-primary: #1a1a1a;
--text-secondary: #666666;
--accent-color: #497671;
--accent-light: rgba(73, 118, 113, 0.1);
--telegram: #2aabee;
--telegram-hover: #229ed9;
--border: #e8e8e8;
--shadow: 0 20px 60px rgba(0, 0, 0, 0.15);
}
* {
box-sizing: border-box;
}
body {
margin: 0;
min-height: 100vh;
font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
color: var(--text-primary);
background: var(--bg-page);
}
.page {
min-height: 100vh;
display: grid;
grid-template-columns: minmax(320px, 448px) minmax(320px, 560px);
gap: 32px;
padding: 40px 32px;
align-items: center;
justify-content: center;
}
.panel {
background: rgba(255, 255, 255, 0.72);
border: 1px solid rgba(255, 255, 255, 0.8);
border-radius: 28px;
padding: 24px;
box-shadow: 0 18px 50px rgba(38, 52, 73, 0.12);
backdrop-filter: blur(14px);
}
.info h1 {
margin: 0 0 12px;
font-size: 32px;
line-height: 1.1;
}
.info p {
margin: 0 0 18px;
color: var(--text-secondary);
line-height: 1.6;
}
.state-switcher {
display: flex;
flex-wrap: wrap;
gap: 10px;
margin: 20px 0 24px;
}
.state-switcher button {
border: 1px solid #cfd8e3;
border-radius: 999px;
background: #fff;
color: var(--text-primary);
padding: 10px 14px;
font-size: 14px;
cursor: pointer;
transition: 0.2s ease;
}
.state-switcher button.active {
border-color: var(--accent-color);
background: var(--accent-light);
color: var(--accent-color);
}
.api-grid {
display: grid;
gap: 12px;
margin-top: 20px;
}
.api-card {
background: #fff;
border: 1px solid #eef2f7;
border-radius: 16px;
padding: 14px 16px;
}
.api-card strong {
display: block;
margin-bottom: 6px;
font-size: 14px;
}
.api-card code {
display: inline-block;
padding: 2px 8px;
border-radius: 999px;
background: #f3f7fb;
color: #21425f;
font-size: 13px;
}
.api-card p {
margin: 8px 0 0;
font-size: 13px;
}
.login-overlay {
position: relative;
min-height: 700px;
border-radius: 28px;
background: rgba(0, 0, 0, 0.5);
backdrop-filter: blur(4px);
display: flex;
align-items: center;
justify-content: center;
animation: fadeIn 0.2s ease;
padding: 16px;
}
.login-dialog {
position: relative;
background: var(--bg-card);
border-radius: 20px;
padding: 32px 28px;
max-width: 400px;
width: 100%;
text-align: center;
box-shadow: var(--shadow);
animation: scaleIn 0.25s ease;
}
.close-btn {
position: absolute;
top: 12px;
right: 12px;
width: 32px;
height: 32px;
border: none;
border-radius: 50%;
background: var(--bg-hover);
color: var(--text-secondary);
cursor: pointer;
display: flex;
align-items: center;
justify-content: center;
transition: all 0.2s ease;
}
.close-btn:hover {
background: #e0e0e0;
color: #333;
}
.login-icon {
margin: 0 auto 16px;
width: 72px;
height: 72px;
border-radius: 50%;
background: var(--accent-light);
color: var(--accent-color);
display: flex;
align-items: center;
justify-content: center;
}
.login-dialog h2 {
margin: 0 0 8px;
font-size: 20px;
font-weight: 700;
color: var(--text-primary);
}
.login-desc {
margin: 0 0 24px;
font-size: 14px;
color: var(--text-secondary);
line-height: 1.5;
}
.telegram-btn {
display: flex;
align-items: center;
justify-content: center;
gap: 10px;
width: 100%;
padding: 14px 24px;
border: none;
border-radius: 12px;
background: var(--telegram);
color: #fff;
font-size: 16px;
font-weight: 600;
cursor: pointer;
transition: all 0.2s ease;
}
.telegram-btn:hover {
background: var(--telegram-hover);
transform: translateY(-1px);
box-shadow: 0 4px 12px rgba(42, 171, 238, 0.3);
}
.telegram-btn:active {
transform: translateY(0);
}
.tg-icon {
flex-shrink: 0;
}
.qr-section {
margin-top: 20px;
}
.qr-hint {
margin: 0 0 12px;
font-size: 13px;
color: #999;
}
.qr-container {
display: inline-flex;
padding: 12px;
background: #fff;
border-radius: 12px;
border: 1px solid var(--border);
}
.qr-container img {
display: block;
border-radius: 4px;
}
.qr-loading {
align-items: center;
justify-content: center;
width: 204px;
height: 204px;
}
.qr-loading .spinner,
.login-status .spinner {
border-radius: 50%;
animation: spin 0.8s linear infinite;
}
.qr-loading .spinner {
width: 32px;
height: 32px;
border: 3px solid #e0e0e0;
border-top-color: var(--accent-color);
}
.qr-expired {
flex-direction: column;
align-items: center;
justify-content: center;
gap: 8px;
width: 204px;
height: 204px;
cursor: pointer;
color: #999;
transition: color 0.2s ease;
}
.qr-expired:hover {
color: var(--accent-color);
}
.qr-expired span {
font-size: 13px;
}
.login-note {
margin: 16px 0 0;
font-size: 12px;
color: #999;
line-height: 1.4;
}
.login-status {
display: none;
align-items: center;
justify-content: center;
gap: 10px;
padding: 16px;
color: var(--text-secondary);
font-size: 14px;
}
.login-status .spinner {
width: 20px;
height: 20px;
border: 2px solid #e0e0e0;
border-top-color: var(--accent-color);
}
.dialog-content[data-state="checking"] .login-status {
display: flex;
}
.dialog-content[data-state="checking"] .action-block,
.dialog-content[data-state="loading"] .qr-ready,
.dialog-content[data-state="loading"] .qr-expired,
.dialog-content[data-state="expired"] .qr-ready,
.dialog-content[data-state="expired"] .qr-loading,
.dialog-content[data-state="error"] .qr-loading,
.dialog-content[data-state="error"] .qr-expired,
.dialog-content[data-state="checking"] .qr-section,
.dialog-content[data-state="checking"] .login-note {
display: none;
}
.dialog-content[data-state="ready"] .qr-loading,
.dialog-content[data-state="ready"] .qr-expired,
.dialog-content[data-state="ready"] .qr-error,
.dialog-content[data-state="loading"] .qr-ready,
.dialog-content[data-state="loading"] .qr-expired,
.dialog-content[data-state="loading"] .qr-error,
.dialog-content[data-state="expired"] .qr-loading,
.dialog-content[data-state="expired"] .qr-ready,
.dialog-content[data-state="expired"] .qr-error,
.dialog-content[data-state="error"] .qr-loading,
.dialog-content[data-state="error"] .qr-expired {
display: none;
}
.dialog-content[data-state="error"] .qr-ready {
display: inline-flex;
}
.metadata {
margin-top: 22px;
padding-top: 18px;
border-top: 1px solid #e9edf2;
font-size: 13px;
color: var(--text-secondary);
}
.metadata ul {
margin: 10px 0 0;
padding-left: 18px;
}
.metadata li + li {
margin-top: 6px;
}
@keyframes fadeIn {
from { opacity: 0; }
to { opacity: 1; }
}
@keyframes scaleIn {
from {
opacity: 0;
transform: scale(0.95);
}
to {
opacity: 1;
transform: scale(1);
}
}
@keyframes spin {
to { transform: rotate(360deg); }
}
@media (max-width: 980px) {
.page {
grid-template-columns: 1fr;
padding: 24px 16px 32px;
}
.login-overlay {
min-height: 560px;
}
}
@media (max-width: 480px) {
.panel {
border-radius: 22px;
padding: 18px;
}
.login-dialog {
padding: 24px 20px;
border-radius: 16px;
}
.qr-container img {
width: 140px;
height: 140px;
}
.qr-loading,
.qr-expired {
width: 164px;
height: 164px;
}
}
</style>
</head>
<body>
<main class="page">
<section class="panel info">
<h1>Telegram Login Dialog</h1>
<p>
Standalone extraction of the current login popup: same layout, same visual states,
same QR flow, but with reusable neutral endpoint names for moving into a separate repo.
</p>
<div class="state-switcher" aria-label="Dialog state switcher">
<button class="active" data-state-btn="ready" type="button">Ready</button>
<button data-state-btn="loading" type="button">QR Loading</button>
<button data-state-btn="checking" type="button">Checking</button>
<button data-state-btn="expired" type="button">Expired</button>
<button data-state-btn="error" type="button">Fallback</button>
</div>
<div class="api-grid">
<div class="api-card">
<strong>Start QR session</strong>
<code>POST /userauth/qr/create</code>
<p>Returns a one-time token and Telegram deeplink for the QR image.</p>
</div>
<div class="api-card">
<strong>Poll QR confirmation</strong>
<code>GET /userauth/qr/poll?token=...</code>
<p>Returns pending, confirmed, or expired. On confirmed, also returns the user session.</p>
</div>
<div class="api-card">
<strong>Read current session</strong>
<code>GET /userauth/session</code>
<p>Cookie-based session lookup used for initial auth check and fallback polling.</p>
</div>
<div class="api-card">
<strong>Sync cart after login</strong>
<code>POST /usersession/{sessionId}</code>
<p>Existing cart payload is preserved. Only the namespace is generalized for reuse.</p>
</div>
</div>
<div class="metadata">
<strong>Behavior kept intact</strong>
<ul>
<li>Open Telegram directly from the primary button.</li>
<li>Show QR immediately and poll every 3 seconds.</li>
<li>Expire the QR after 100 checks and allow manual refresh.</li>
<li>Re-check cookie session if QR creation fails.</li>
</ul>
</div>
</section>
<section class="panel">
<div class="login-overlay">
<div class="login-dialog">
<button class="close-btn" type="button" aria-label="Close dialog">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
<path d="M18 6L6 18M6 6l12 12"></path>
</svg>
</button>
<div class="dialog-content" data-state="ready" id="dialog-content">
<div class="login-icon">
<svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
<path d="M21 11.5a8.38 8.38 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.38 8.38 0 0 1-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.38 8.38 0 0 1 3.8-.9h.5a8.48 8.48 0 0 1 8 8v.5z"></path>
</svg>
</div>
<h2>Login required</h2>
<p class="login-desc">Please log in via Telegram to proceed with your order.</p>
<div class="login-status checking">
<div class="spinner"></div>
<span>Checking...</span>
</div>
<div class="action-block">
<button class="telegram-btn" type="button">
<svg class="tg-icon" width="22" height="22" viewBox="0 0 24 24" fill="currentColor">
<path d="M11.944 0A12 12 0 0 0 0 12a12 12 0 0 0 12 12 12 12 0 0 0 12-12A12 12 0 0 0 12 0a12 12 0 0 0-.056 0zm4.962 7.224c.1-.002.321.023.465.14a.506.506 0 0 1 .171.325c.016.093.036.306.02.472-.18 1.898-.962 6.502-1.36 8.627-.168.9-.499 1.201-.82 1.23-.696.065-1.225-.46-1.9-.902-1.056-.693-1.653-1.124-2.678-1.8-1.185-.78-.417-1.21.258-1.91.177-.184 3.247-2.977 3.307-3.23.007-.032.014-.15-.056-.212s-.174-.041-.249-.024c-.106.024-1.793 1.14-5.061 3.345-.48.33-.913.49-1.302.48-.428-.008-1.252-.241-1.865-.44-.752-.245-1.349-.374-1.297-.789.027-.216.325-.437.893-.663 3.498-1.524 5.83-2.529 6.998-3.014 3.332-1.386 4.025-1.627 4.476-1.635z"></path>
</svg>
Log in with Telegram
</button>
<div class="qr-section">
<p class="qr-hint">Or scan the QR code</p>
<div class="qr-container qr-loading">
<div class="spinner"></div>
</div>
<div class="qr-container qr-ready">
<img
src="https://api.qrserver.com/v1/create-qr-code/?size=180x180&data=https%3A%2F%2Ft.me%2Fuserauth_bot%3Fstart%3Dlogin_sample_token"
alt="QR Code"
width="180"
height="180"
loading="eager"
/>
</div>
<div class="qr-container qr-expired" role="button" tabindex="0" aria-label="Refresh QR code">
<svg width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
<path d="M1 4v6h6M23 20v-6h-6"></path>
<path d="M20.49 9A9 9 0 0 0 5.64 5.64L1 10m22 4l-4.64 4.36A9 9 0 0 1 3.51 15"></path>
</svg>
<span>QR code expired. Click to refresh</span>
</div>
</div>
<p class="login-note">You will be redirected back after login.</p>
</div>
</div>
</div>
</div>
</section>
</main>
<script>
const content = document.getElementById('dialog-content');
const buttons = document.querySelectorAll('[data-state-btn]');
buttons.forEach((button) => {
button.addEventListener('click', () => {
const state = button.getAttribute('data-state-btn');
content.setAttribute('data-state', state);
buttons.forEach((candidate) => candidate.classList.remove('active'));
button.classList.add('active');
});
});
</script>
</body>
</html>

36
e2e/README.md
View File

@@ -1,36 +0,0 @@
# E2E — Playwright
Track Q (`docs/PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md`, Q1). None of this existed before 2026-08-18.
## Run
```bash
npm run e2e # headless, boots the dev server automatically
npm run e2e:ui # interactive runner
npm run e2e:report # last HTML report
```
Against a different server (staging, a locally-started backend):
```bash
BASE_URL=https://staging.example.com npm run e2e
```
## What this suite currently covers, and what it doesn't
`environment.ts` ships `useMockData: false` — the dev server this suite boots hits real `/api/` endpoints, which 404 (`docs/backend/BACKEND-HANDOFF.md` — no backend is running anywhere this session can reach). The product catalog itself renders from a separate mocked bootstrap/catalog path (`useMockBootstrapOnLocal: true`), so real prices and real currency conversion ARE exercised — `smoke.spec.ts` explicitly ignores the expected 404 console noise rather than pretending it isn't there.
**This is not the same guarantee as running against a live backend.** Checkout, payment, and anything behind a real endpoint are not covered until `BASE_URL` points at a live environment. Confirmed once, concretely: on the first run, this suite caught a real bug (`@marketplaces/auth` shipping without Angular Ivy metadata, breaking app bootstrap) and a real test defect (a duplicate hidden dropdown made the first currency-switch attempt click a no-op element) — both fixed as part of standing this suite up. See the commit history in `src/main.ts` and this directory for what each was.
## Files
| File | Covers |
|---|---|
| `currency-switch.spec.ts` | `160 RUB` must not silently become `160 USD` on a currency switch — Track Q Q4, and the regression guard `docs/backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md` §5 exists to close. Written **before** the checkout money-truth rewrite (F10–F16 in the frontend backlog), specifically so that rewrite has a net under it. |
| `smoke.spec.ts` | App boots, storefront renders, no console errors on first paint. |
## Adding a test
- Prefer existing CSS classes / ARIA roles already in the templates (`.currency-button`, `role="option"`, etc.) over inventing new selectors — there are no `data-testid` attributes in this codebase yet, and adding them project-wide is out of scope for this suite.
- One behavior per test. Name the file after the behavior, not the page.
- If a test needs backend state that mock data can't produce, mark it `test.skip(!process.env.BASE_URL, 'needs a live backend')` rather than deleting it — it documents the gap.

27
e2e/admin-dev-bypass.spec.ts
View File

@@ -1,27 +0,0 @@
import { expect, test } from '@playwright/test';
/**
* Track Q Q2 / frontend backlog F59: past "verified live" admin claims were
* code-inspection only, because /backoffice needs a real Telegram login this
* suite cannot perform. ?devBypassAdmin=true (src/app/app.ts, gated by
* Angular's isDevMode() at runtime in @marketplaces/auth's
* AdminAuthService.devBypassLogin - not just build-time, and a no-op in any
* production build) is the existing, already-shipped answer - this test just
* proves it actually gets an E2E run into the admin shell.
*/
test.describe('admin dev bypass', () => {
test('?devBypassAdmin=true reaches the admin shell without a Telegram login', async ({ page }) => {
await page.goto('/?devBypassAdmin=true');
await page.waitForLoadState('networkidle');
// The bypass alone doesn't navigate anywhere - it only activates the
// session, so the admin surface has to be reached directly afterwards.
await page.goto('/admin/dashboard');
await page.waitForLoadState('networkidle');
// A real Telegram-gated admin route would redirect to a login dialog;
// reaching dashboard content is the actual proof the bypass worked.
await expect(page).not.toHaveURL(/login/i);
await expect(page.locator('body')).not.toContainText(/scan.*qr|log in with telegram/i);
});
});

76
e2e/checkout-idempotent-click.spec.ts
View File

@@ -1,76 +0,0 @@
import { Page, Route, expect, test } from '@playwright/test';
/**
* Track Q Q5 / frontend backlog F62: "repeat webhook and double-click create
* exactly one order." The webhook-idempotency half is a backend contract
* (PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md §6.3, provider + providerEventId as
* the dedup key) this suite cannot exercise without a live backend. This
* test covers the half that IS frontend-testable: a double-click on the
* checkout button must not fire two checkout-session requests.
*/
const FAKE_ITEM = {
categoryID: 1, itemID: 5151, name: 'Idempotency Test Item', photos: null,
description: '', currency: 'RUB', price: 500, discount: 0, rating: 0,
callbacks: null, questions: null, quantity: 1,
};
test('double-clicking checkout sends exactly one checkout-session request', async ({ page, context }) => {
await page.addInitScript(item => {
window.localStorage.setItem('marketplace_cart', JSON.stringify([item]));
}, FAKE_ITEM);
await context.addCookies([{ name: 'webSessionID', value: 'e2e-fake-session', domain: 'localhost', path: '/' }]);
await page.route('**/users/sessions/**', route =>
route.fulfill({
status: 200, contentType: 'application/json',
body: JSON.stringify({ sessionId: 'e2e-fake-session', status: 'active', username: 'e2e_user', userId: 1 }),
}),
);
await page.route('**/api/v2/pricing/fx-quote**', route =>
route.fulfill({
status: 200, contentType: 'application/json',
body: JSON.stringify({ quoteId: 'fxq_e2e', base: 'RUB', quote: 'RUB', rate: 1, source: 'e2e', observedAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 300000).toISOString() }),
}),
);
let checkoutRequestCount = 0;
await page.route('**/api/v2/storefront/checkout', async (route: Route) => {
checkoutRequestCount += 1;
// Deliberately slow, so a real double-click's second event has to land
// while the first request is still in flight - the exact race this test
// exists to catch.
await new Promise(resolve => setTimeout(resolve, 300));
route.fulfill({
status: 200, contentType: 'application/json',
body: JSON.stringify({
checkoutSessionId: 'chk_e2e_idempotent',
lines: [{ offerId: String(FAKE_ITEM.itemID), qty: 1, unitPrice: { amountMinor: 50000, currency: 'RUB' }, lineTotal: { amountMinor: 50000, currency: 'RUB' }, priceSnapshotId: 'snap_e2e' }],
subtotal: { amountMinor: 50000, currency: 'RUB' }, discount: { amountMinor: 0, currency: 'RUB' },
delivery: { amountMinor: 0, currency: 'RUB' }, total: { amountMinor: 50000, currency: 'RUB' },
fxQuoteId: 'fxq_e2e', expiresAt: new Date(Date.now() + 300000).toISOString(),
}),
});
});
await page.route('**/api/v2/storefront/payments/intents', route =>
route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ qrId: 'qr_e2e', nspkurl: 'https://example.com/pay', qrTTL: 5 }) }),
);
await page.goto('/cart');
await page.waitForLoadState('networkidle');
// No <label for="terms-checkbox"> exists in the markup - the checkbox and
// its text share a plain clickable wrapper - so toggle the input directly.
await page.locator('#terms-checkbox').dispatchEvent('click');
await expect(page.locator('#terms-checkbox')).toBeChecked();
const qrButton = page.getByRole('button', { name: /qr/i }).first();
await expect(qrButton).toBeEnabled({ timeout: 10_000 });
await qrButton.dblclick();
// Give the deliberately slow mock time to resolve and for any second,
// erroneously-fired request to have landed.
await page.waitForTimeout(1000);
expect(checkoutRequestCount, 'a double-click must not create two checkout sessions').toBe(1);
});

186
e2e/checkout-request-shape.spec.ts
View File

@@ -1,186 +0,0 @@
import { Page, Route, expect, test } from '@playwright/test';
/**
* Guards the specific contract this rewrite exists to enforce
* (PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md §5.2): the amount actually charged
* must be computed server-side, never sent by the client. Before this
* rewrite, POST /cart carried a client-computed `amount` the backend was
* asked to trust.
*
* cart.component.ts has no unit spec (no src/app/pages/cart/*.spec.ts
* exists), so this E2E test is the only coverage the checkout request shape
* has. Scoped narrowly on purpose: cart state is seeded directly into
* localStorage and the customer session is faked via cookie + intercepted
* session-check, rather than driving a full add-to-cart-then-login UI
* journey - that journey is real product surface worth its own test, but
* would make this test about navigation, not about what it exists to prove.
*/
const FAKE_SESSION_ID = 'e2e-fake-session';
const FAKE_ITEM = {
categoryID: 1,
itemID: 4242,
name: 'E2E Test Item',
photos: null,
description: '',
currency: 'RUB',
price: 1000,
discount: 0,
rating: 0,
callbacks: null,
questions: null,
quantity: 2,
};
test.describe('checkout request shape', () => {
test.beforeEach(async ({ page, context }) => {
await seedCart(page);
await fakeCustomerSession(page, context);
await mockFxQuoteEndpoint(page);
});
test('checkout session request carries offers and qty, never amount or price', async ({ page }) => {
const checkoutRequest = interceptCheckoutSession(page);
await page.goto('/cart');
await acceptTermsAndCheckout(page);
const body = await checkoutRequest;
expect(body, 'must never send a client-computed amount').not.toHaveProperty('amount');
expect(body, 'must never send a client-computed price').not.toHaveProperty('price');
expect(Array.isArray(body.offers), 'must send an offers array').toBe(true);
expect(body.offers[0]).toMatchObject({ offerId: String(FAKE_ITEM.itemID), qty: FAKE_ITEM.quantity });
});
test('payment intent request references the checkout session id, not a raw amount', async ({ page }) => {
interceptCheckoutSession(page); // must resolve for the intent call to fire at all
const intentRequest = interceptPaymentIntent(page);
await page.goto('/cart');
await acceptTermsAndCheckout(page);
const body = await intentRequest;
expect(body.checkoutSessionId, 'must reference the session created in step 1').toBe('chk_e2e_fixture');
expect(body).not.toHaveProperty('amount');
expect(typeof body.merchantReference).toBe('string');
expect(body.merchantReference.length).toBeGreaterThan(0);
});
});
async function seedCart(page: Page): Promise<void> {
await page.addInitScript(item => {
window.localStorage.setItem('marketplace_cart', JSON.stringify([item]));
}, FAKE_ITEM);
}
async function fakeCustomerSession(page: Page, context: import('@playwright/test').BrowserContext): Promise<void> {
await context.addCookies([
{
name: 'webSessionID',
value: FAKE_SESSION_ID,
domain: 'localhost',
path: '/',
},
]);
// Matches TelegramSessionApiService.normalizeWebSession's expected shape.
await page.route('**/users/sessions/**', route => {
route.fulfill({
status: 200,
contentType: 'application/json',
body: JSON.stringify({
sessionId: FAKE_SESSION_ID,
status: 'active',
username: 'e2e_user',
userId: 1,
}),
});
});
}
async function mockFxQuoteEndpoint(page: Page): Promise<void> {
await page.route('**/api/v2/pricing/fx-quote**', route => {
route.fulfill({
status: 200,
contentType: 'application/json',
body: JSON.stringify({
quoteId: 'fxq_e2e',
base: 'RUB',
quote: 'RUB',
rate: 1,
source: 'e2e-fixture',
observedAt: new Date().toISOString(),
expiresAt: new Date(Date.now() + 300_000).toISOString(),
}),
});
});
}
function interceptCheckoutSession(page: Page): Promise<Record<string, unknown>> {
return new Promise(resolve => {
page.route('**/api/v2/storefront/checkout', (route: Route) => {
const body = route.request().postDataJSON();
resolve(body);
route.fulfill({
status: 200,
contentType: 'application/json',
body: JSON.stringify({
checkoutSessionId: 'chk_e2e_fixture',
lines: [{
offerId: String(FAKE_ITEM.itemID),
qty: FAKE_ITEM.quantity,
unitPrice: { amountMinor: FAKE_ITEM.price * 100, currency: 'RUB' },
lineTotal: { amountMinor: FAKE_ITEM.price * FAKE_ITEM.quantity * 100, currency: 'RUB' },
priceSnapshotId: 'snap_e2e',
}],
subtotal: { amountMinor: FAKE_ITEM.price * FAKE_ITEM.quantity * 100, currency: 'RUB' },
discount: { amountMinor: 0, currency: 'RUB' },
delivery: { amountMinor: 0, currency: 'RUB' },
total: { amountMinor: FAKE_ITEM.price * FAKE_ITEM.quantity * 100, currency: 'RUB' },
fxQuoteId: 'fxq_e2e',
expiresAt: new Date(Date.now() + 300_000).toISOString(),
}),
});
});
});
}
function interceptPaymentIntent(page: Page): Promise<Record<string, unknown>> {
return new Promise(resolve => {
page.route('**/api/v2/storefront/payments/intents', (route: Route) => {
const body = route.request().postDataJSON();
resolve(body);
route.fulfill({
status: 200,
contentType: 'application/json',
body: JSON.stringify({
qrId: 'qr_e2e_fixture',
nspkurl: 'https://example.com/pay/e2e',
qrTTL: 5,
}),
});
});
});
}
async function acceptTermsAndCheckout(page: Page): Promise<void> {
await page.waitForLoadState('networkidle');
// #terms-checkbox is a custom-styled input (zero-size native element, a
// <label> renders the visible box) - .check() refuses on geometry even
// with force:true, so toggle it via its label the way a real user would.
const termsCheckbox = page.locator('#terms-checkbox');
if (await termsCheckbox.count() > 0) {
const label = page.locator('label[for="terms-checkbox"]');
if (await label.count() > 0) {
await label.click();
} else {
await termsCheckbox.dispatchEvent('click');
}
}
const qrButton = page.getByRole('button', { name: /qr/i }).first();
await qrButton.click();
}

124
e2e/currency-switch.spec.ts
View File

@@ -1,124 +0,0 @@
import { Page, Route, expect, test } from '@playwright/test';
/**
* Track Q Q4: currency switch must recalculate by FX quote. Explicitly,
* "160 RUB" must not become "160 USD" - the number has to change, not just
* the label next to it.
*
* Written before the checkout money-truth rewrite (frontend backlog F10-F16,
* which deletes CurrencyRatesService's client-side float math and switches
* checkout to a server-computed total per
* docs/backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md §5). This test exists so
* that rewrite has something to break loudly if it silently stops converting.
*
* This session has no live backend to run against, so GET
* /api/v2/pricing/fx-quote is intercepted with a response shaped exactly per
* contract §3.1. That exercises the REAL code path - FxQuoteApiGateway,
* CurrencyRatesService, the currencyConvert pipe - rather than switching the
* whole app into mock mode, which would test a different (mock) gateway
* instead of the one actually shipped.
*/
/** Rate relative to RUB, only what this test needs. */
const MOCK_RATE: Record<string, number> = { USD: 0.0108, EUR: 0.0092, AMD: 4.31 };
test.describe('currency switch', () => {
test.beforeEach(async ({ page }) => {
await mockFxQuoteEndpoint(page);
});
test('switching currency changes the displayed price value, not just its label', async ({ page }) => {
await page.goto('/');
await page.waitForLoadState('networkidle');
const priceLocator = page.locator('.current-price, .original-price').first();
await expect(priceLocator).toBeVisible({ timeout: 15_000 });
const before = await readPrice(priceLocator);
expect(before.value, 'a price must be a real positive number before switching').toBeGreaterThan(0);
await switchCurrency(page, before.currency === 'USD' ? 'RUB' : 'USD');
// The currency LABEL flips synchronously (a signal write), but the rate
// itself arrives from the mocked network call asynchronously - polling
// only the label races ahead of the actual conversion and passes before
// the number has caught up. Poll the parsed numeric value instead, since
// that is what this test exists to guard.
await expect
.poll(async () => (await readPrice(priceLocator)).value, {
message: 'price value never diverged from the pre-switch amount',
})
.not.toBeCloseTo(before.value, 2);
const after = await readPrice(priceLocator);
expect(after.currency, 'the currency label must actually change').not.toBe(before.currency);
// The literal regression this test exists to catch: a rate of 1 disguised
// as a real conversion. RUB->USD or USD->RUB is never a 1:1 rate.
expect(after.value, `${before.value} ${before.currency} must not equal ${after.value} ${after.currency}`).not.toBeCloseTo(before.value, 2);
});
test('an out-of-range rate must not silently pass as valid', async ({ page }) => {
// Guards the specific bad-data class this suite exists to catch: a
// conversion that returns something implausible (zero, negative, or
// absurdly large) instead of erroring visibly.
await page.goto('/');
const priceLocator = page.locator('.current-price, .original-price').first();
await expect(priceLocator).toBeVisible({ timeout: 15_000 });
const { value } = await readPrice(priceLocator);
expect(value).toBeGreaterThan(0);
expect(value).toBeLessThan(100_000_000);
});
});
async function mockFxQuoteEndpoint(page: Page): Promise<void> {
await page.route('**/api/v2/pricing/fx-quote**', (route: Route) => {
const url = new URL(route.request().url());
const base = url.searchParams.get('base') ?? 'RUB';
const quote = url.searchParams.get('quote') ?? 'USD';
const rate = MOCK_RATE[quote] ?? 1;
const now = new Date();
route.fulfill({
status: 200,
contentType: 'application/json',
body: JSON.stringify({
quoteId: `fxq_e2e_${base}_${quote}_${now.getTime()}`,
base,
quote,
rate,
source: 'e2e-fixture',
observedAt: now.toISOString(),
expiresAt: new Date(now.getTime() + 5 * 60 * 1000).toISOString(),
}),
});
});
}
async function switchCurrency(page: Page, targetCode: string): Promise<void> {
// The page renders more than one language-selector instance (desktop/mobile
// variants share the same markup) - scoping to the dropdown that actually
// carries the "open" class avoids clicking an option in a hidden duplicate,
// which is silently a no-op rather than a failure.
const trigger = page.locator('.currency-button:visible').first();
await trigger.click();
const openDropdown = page.locator('.currency-dropdown.open').first();
await expect(openDropdown).toBeVisible();
await openDropdown.locator('.currency-option', { hasText: targetCode }).first().click();
}
async function readPrice(locator: import('@playwright/test').Locator): Promise<{ value: number; currency: string }> {
const text = (await locator.textContent()) ?? '';
// Matches "1 234.56 USD" / "1234.56 ₽" shapes the price templates render.
const match = text.replace(/\s/g, '').match(/([\d.,]+)([A-Z]{3}|\D+)$/);
if (!match) {
throw new Error(`could not parse price text: "${text}"`);
}
const value = Number(match[1].replace(/,/g, ''));
return { value, currency: match[2] };
}

35
e2e/smoke.spec.ts
View File

@@ -1,35 +0,0 @@
import { expect, test } from '@playwright/test';
/** First E2E test in this repo. If this fails, nothing else in the suite matters. */
test.describe('smoke', () => {
test('storefront boots with no console errors', async ({ page }) => {
const errors: string[] = [];
// pageerror catches uncaught exceptions - always a real bug, always kept.
page.on('pageerror', err => errors.push(err.message));
page.on('console', msg => {
if (msg.type() !== 'error') {
return;
}
// "Failed to load resource" is Chrome's own message for a failed
// network request (404/502/etc), not application code. With
// environment.useMockData: false and no live backend behind this dev
// server (docs/backend/BACKEND-HANDOFF.md), every /api/ call 404s by
// design - that is a backend-availability fact, not something this
// smoke test exists to catch. A real app-level console.error still
// fails this test.
if (/^Failed to load resource/.test(msg.text())) {
return;
}
errors.push(msg.text());
});
await page.goto('/');
await expect(page.locator('body')).toBeVisible();
// Give the bootstrap fetch + first render cycle time to settle before
// asserting on the error list, or this is a race against app.config.ts.
await page.waitForLoadState('networkidle');
expect(errors, `console errors on first paint: ${errors.join('\n')}`).toEqual([]);
});
});

32
karma.conf.js
View File

@@ -1,32 +0,0 @@
// Karma configuration for `ng test` (@angular/build:karma builder).
// A headless, sandbox-free Chrome launcher so the suite runs in CI and in
// restricted/dev environments where Chrome isn't on PATH. CHROME_BIN falls
// back to the default Windows install path when the env var isn't set.
process.env.CHROME_BIN =
process.env.CHROME_BIN || 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe';
module.exports = function (config) {
config.set({
frameworks: ['jasmine'],
plugins: [
require('karma-jasmine'),
require('karma-chrome-launcher'),
require('karma-jasmine-html-reporter'),
require('karma-coverage'),
],
browsers: ['ChromeHeadlessNoSandbox'],
customLaunchers: {
ChromeHeadlessNoSandbox: {
base: 'ChromeHeadless',
flags: ['--no-sandbox', '--disable-gpu', '--disable-dev-shm-usage'],
},
},
reporters: ['progress', 'coverage'],
coverageReporter: {
dir: require('path').join(__dirname, 'coverage'),
subdir: '.',
reporters: [{ type: 'text-summary' }, { type: 'html' }, { type: 'lcovonly' }],
},
restartOnFileChange: true,
});
};

93
nginx.conf
View File

@@ -7,7 +7,7 @@ server {
# Angular routing - serve index.html for all routes
location / {
try_files $uri $uri/ /index.html;
try_files $uri $uri/ /index.html =404;
}
# Static assets caching
@@ -55,7 +55,7 @@ server {
# Angular routing
location / {
try_files $uri $uri/ /index.html;
try_files $uri $uri/ /index.html =404;
}
# Proxy API calls to backend
@@ -93,93 +93,4 @@ server {
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://telegram.org; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: https:; connect-src 'self' https:; frame-src https://telegram.org;" always;
}
# Template for onboarding a new marketplace tenant.
# Replace NEWMARKETPLACE.EXAMPLE.COM, /var/www/newmarketplace, and the
# api.newmarketplace.example.com:443 proxy target with the real values,
# then rename this block's server_name/root before deploying.
#
# --- SPA routing (read before you skip this) ---
# This is an Angular app with client-side routing (all page navigation - the
# admin dashboard, project editor, catalog, product pages, etc. - happens in
# the browser, not via new server requests). Every URL the app owns
# (/:lang/backoffice/dashboard, /:lang/edit/general, /:lang/catalog/5, ...)
# must fall through to index.html on a fresh request (page refresh, typed
# URL, browser back/forward after a full reload) so Angular's router can take
# over client-side. `try_files $uri $uri/ /index.html;` below is what makes
# that work: nginx tries the literal file, then the directory, then falls
# back to index.html for anything that isn't a real static asset. If you ever
# see a raw nginx 404 page on refresh/back-navigation (not a blank app, an
# actual nginx error page), this fallback is missing or misconfigured for
# that server block - it is NOT an Angular or JS problem.
#
# --- Two ways the frontend talks to its API - pick one per tenant ---
# 1) Proxied (what this template and the lovero.store block above do):
# the frontend calls a relative `/api/...` path, and nginx proxies it to
# the real backend below. Browser never sees the backend host/port.
# 2) Direct (what the dexarmarket.ru production build does): the frontend's
# `environment.production.ts` sets `apiUrl`/`authApiUrl` to an absolute
# URL (e.g. `https://api.dexarmarket.ru:445`) and calls that directly -
# this nginx config is never involved in API calls at all for that tenant.
# If a tenant using pattern (2) reports 502/504 Bad Gateway on refresh or
# back-navigation, it is NOT this file - the app re-fires session-check and
# bootstrap-load calls on every route change/refresh, and a 502/504 means the
# *backend's own* reverse proxy/app server (the one fronting that absolute
# apiUrl/authApiUrl host) is down, overloaded, or timing out. Check that
# backend's own nginx/app logs, not this one.
server {
listen 80;
server_name newmarketplace.example.com www.newmarketplace.example.com;
root /var/www/newmarketplace/browser;
index index.html;
# Angular routing - serve index.html for all routes (client-side router
# handles /edit, /:lang/edit/:section, etc. once index.html is served)
location / {
try_files $uri $uri/ /index.html;
}
# Proxy API calls to backend - only needed if this tenant uses the
# relative `/api` pattern (see comment above); delete this block if the
# tenant's environment.*.ts uses an absolute apiUrl instead.
location /api {
proxy_pass https://api.newmarketplace.example.com:443;
proxy_set_header Host api.newmarketplace.example.com;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
rewrite ^/api(/.*)$ $1 break;
proxy_ssl_verify off;
}
# Static assets caching
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
try_files $uri =404;
}
# Don't cache index.html
location = /index.html {
add_header Cache-Control "no-cache, no-store, must-revalidate";
add_header Pragma "no-cache";
add_header Expires "0";
}
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml;
gzip_min_length 1000;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://telegram.org; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: https:; connect-src 'self' https:; frame-src https://telegram.org;" always;
}

4238
package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

58
package.json
View File

@@ -5,54 +5,38 @@
"ng": "ng",
"start": "ng serve",
"dexar": "ng serve --configuration=development --port 4200",
"novo": "ng serve --configuration=novo --port 4201 --proxy-config proxy.conf.novo.json",
"start:dexar": "ng serve --configuration=development --port 4200",
"start:novo": "ng serve --configuration=novo --port 4201",
"build": "ng build",
"build:dexar": "ng build --configuration=production",
"test": "ng test --watch=false --browsers=ChromeHeadlessNoSandbox",
"test:coverage": "ng test --watch=false --browsers=ChromeHeadlessNoSandbox --code-coverage",
"build:novo": "ng build --configuration=novo-production",
"watch": "ng build --watch --configuration development",
"arch:check:boundaries": "node tools/architecture/check-boundaries.mjs",
"arch:check:cycles": "npx --yes madge --circular --extensions ts src/app --ts-config tsconfig.app.json",
"arch:check": "npm run arch:check:boundaries ; npm run arch:check:cycles",
"barry": "barry-cache",
"barry:validate": "barry-cache validate",
"barry:resume": "barry-cache resume",
"barry:finalize": "barry-cache finalize",
"barry:failure": "barry-cache failure",
"e2e": "playwright test",
"e2e:ui": "playwright test --ui",
"e2e:report": "playwright show-report"
"lavero": "ng serve --configuration=lavero --port 4202 --proxy-config proxy.conf.lavero.json",
"start:lavero": "ng serve --configuration=lavero --port 4202",
"build:lavero": "ng build --configuration=lavero-production"
},
"private": true,
"dependencies": {
"@angular/animations": "22.0.8",
"@angular/cdk": "22.0.6",
"@angular/common": "22.0.8",
"@angular/compiler": "22.0.8",
"@angular/core": "22.0.8",
"@angular/forms": "22.0.8",
"@angular/platform-browser": "22.0.8",
"@angular/router": "22.0.8",
"@angular/service-worker": "22.0.8",
"@marketplaces/auth": "git+https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git#release/auth",
"@angular/animations": "21.1.5",
"@angular/cdk": "21.1.5",
"@angular/common": "21.1.5",
"@angular/compiler": "21.1.5",
"@angular/core": "21.1.5",
"@angular/forms": "21.1.5",
"@angular/platform-browser": "21.1.5",
"@angular/router": "21.1.5",
"@angular/service-worker": "21.1.5",
"primeicons": "^7.0.0",
"primeng": "^21.0.3",
"rxjs": "~7.8.0",
"tslib": "^2.8.0",
"zone.js": "~0.16.0"
},
"devDependencies": {
"@angular/build": "22.0.8",
"@angular/cli": "22.0.8",
"@angular/compiler-cli": "22.0.8",
"@playwright/test": "^1.62.1",
"@types/jasmine": "~5.1.0",
"barry-cache": "^0.9.3",
"istanbul-lib-instrument": "^6.0.3",
"jasmine-core": "~5.5.0",
"karma": "~6.4.0",
"karma-chrome-launcher": "~3.2.0",
"karma-coverage": "^2.2.1",
"karma-jasmine": "~5.1.0",
"karma-jasmine-html-reporter": "~2.1.0",
"typescript": "~6.0.3"
"@angular/build": "21.1.5",
"@angular/cli": "21.1.5",
"@angular/compiler-cli": "21.1.5",
"typescript": "~5.9.3"
}
}

41
playwright.config.ts
View File

@@ -1,41 +0,0 @@
import { defineConfig, devices } from '@playwright/test';
/**
* E2E harness. Track Q (docs/PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md Q1) — none
* existed before this. Runs against the mock-data build (environment.dev's
* useMockData: true, per src/environments/), because the dev server this
* session can reach has no live backend behind it.
*
* Once a real backend is reachable, point BASE_URL at it and set
* PW_USE_MOCK_DATA=false to get end-to-end coverage instead of
* frontend-only coverage. See e2e/README.md.
*/
export default defineConfig({
testDir: './e2e',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 2 : undefined,
reporter: process.env.CI ? [['github'], ['html', { open: 'never' }]] : 'list',
use: {
baseURL: process.env.BASE_URL ?? 'http://localhost:4200',
trace: 'on-first-retry',
screenshot: 'only-on-failure',
},
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
],
// Boots the mock-data dev server unless BASE_URL points somewhere already
// running (a staging box, a locally-started server).
webServer: process.env.BASE_URL
? undefined
: {
command: 'npm run dexar',
url: 'http://localhost:4200',
reuseExistingServer: !process.env.CI,
timeout: 120_000,
},
});

7
proxy.conf.json
View File

@@ -1,8 +1,11 @@
{
"/api": {
"target": "https://novo.market",
"target": "https://api.dexarmarket.ru:445",
"secure": false,
"changeOrigin": true,
"pathRewrite": {
"^/api": ""
},
"logLevel": "debug"
}
}
}

11
proxy.conf.lavero.json Normal file
View File

@@ -0,0 +1,11 @@
{
"/api": {
"target": "https://api.lovero.store:555",
"secure": false,
"changeOrigin": true,
"pathRewrite": {
"^/api": ""
},
"logLevel": "debug"
}
}

11
proxy.conf.lavero.json.bak Normal file
View File

@@ -0,0 +1,11 @@
{
"/api": {
"target": "https://api.lovero.store:555",
"secure": false,
"changeOrigin": true,
"pathRewrite": {
"^/api": ""
},
"logLevel": "debug"
}
}

11
proxy.conf.novo.json Normal file
View File

@@ -0,0 +1,11 @@
{
"/api": {
"target": "https://api.novo.market:444",
"secure": false,
"changeOrigin": true,
"pathRewrite": {
"^/api": ""
},
"logLevel": "debug"
}
}

8
public/assets/images/placeholder.svg
View File

@@ -1,8 +0,0 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 300" role="img" aria-label="No image available">
<rect width="400" height="300" fill="#e5e7eb"/>
<g fill="none" stroke="#9ca3af" stroke-width="2">
<rect x="40" y="40" width="320" height="220" rx="8"/>
<path d="M40 220 L140 130 L200 180 L260 110 L360 220" />
<circle cx="140" cy="100" r="20"/>
</g>
</svg>
Side by Side

Before

Width:  |  Height:  |  Size: 380 B

325
public/assets/mock/bootstrap/bootstrap.json
View File

@@ -1,325 +0,0 @@
{
"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"
},
"branding": {
"brandName": "Marketplace",
"legalName": "Marketplace LLC",
"slogan": "Digital commerce marketplace",
"logoUrl": "/icons/icon-192x192.png",
"logoCompactUrl": "/icons/icon-192x192.png",
"faviconUrl": "/favicon.ico",
"appIconUrl": "/icons/icon-192x192.png",
"supportEmail": "support@marketplace.local",
"supportPhone": "+7-900-000-00-00"
},
"theme": {
"themeId": "default-light",
"mode": "light",
"palette": {
"primary": "#497671",
"secondary": "#a1b4b5",
"accent": "#a7ceca",
"success": "#10b981",
"warning": "#f59e0b",
"danger": "#ef4444",
"info": "#3b82f6",
"textPrimary": "#1e3c38",
"textSecondary": "#667a77",
"backgroundPrimary": "#ffffff",
"backgroundSecondary": "#f5f5f5",
"border": "#d3dad9"
},
"typography": {
"primaryFontFamily": "DM Sans, sans-serif",
"headingFontFamily": "DM Sans, sans-serif",
"baseFontSize": 16
},
"spacing": {
"unit": 4,
"scale": [0, 4, 8, 12, 16, 24, 32, 48]
},
"borderRadiusScale": {
"sm": "8px",
"md": "12px",
"lg": "16px",
"xl": "22px"
},
"shadows": {
"sm": "0 2px 8px rgba(0,0,0,0.1)",
"md": "0 4px 12px rgba(0,0,0,0.15)",
"lg": "0 12px 32px rgba(73,118,113,0.2)"
},
"iconSet": "default"
},
"company": {
"companyName": "Marketplace LLC",
"registrationNumber": "1027700000000",
"taxId": "7700000000",
"address": {
"country": "Russia",
"region": "Moscow",
"city": "Moscow",
"street": "Tverskaya 1",
"postalCode": "125009"
},
"contacts": {
"email": "support@marketplace.local",
"phone": "+7-900-000-00-00",
"telegram": "@marketplace_support",
"website": "https://marketplace.local"
}
},
"featureFlags": {
"wishlist": true,
"compare": true,
"reviews": true,
"blog": false,
"chat": false,
"analytics": true,
"notifications": true,
"coupons": true,
"loyalty": false,
"giftCards": false,
"invoices": 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"
},
"dictionaries": [
{
"locale": "ru",
"dictionaryUrl": "/assets/i18n/ru.json",
"version": "1.0.0"
},
{
"locale": "en",
"dictionaryUrl": "/assets/i18n/en.json",
"version": "1.0.0"
},
{
"locale": "hy",
"dictionaryUrl": "/assets/i18n/hy.json",
"version": "1.0.0"
}
]
},
"seo": {
"default": {
"title": "Marketplace",
"description": "Digital commerce marketplace",
"robots": "index,follow"
},
"byPageKey": {
"home": {
"title": "Marketplace - Home",
"description": "Digital commerce marketplace",
"canonicalUrl": "https://marketplace.local/",
"robots": "index,follow"
}
}
},
"permissions": {
"definitions": [
{
"key": "builder.pages.edit",
"description": "Edit pages in builder"
},
{
"key": "backoffice.products.read",
"description": "Read products in backoffice"
}
],
"roles": [
{
"role": "builder_admin",
"permissions": ["builder.pages.edit"]
},
{
"role": "backoffice_manager",
"permissions": ["backoffice.products.read"]
}
]
},
"navigation": {
"header": [
{
"id": "nav-home",
"labelKey": "nav.home",
"route": "/",
"icon": "home",
"order": 1
},
{
"id": "nav-search",
"labelKey": "nav.search",
"route": "/search",
"icon": "search",
"order": 2
},
{
"id": "nav-cart",
"labelKey": "nav.cart",
"route": "/cart",
"icon": "cart",
"order": 3
}
],
"footer": [
{
"id": "footer-about",
"labelKey": "nav.about",
"route": "/about",
"order": 1
},
{
"id": "footer-contacts",
"labelKey": "nav.contacts",
"route": "/contacts",
"order": 2
},
{
"id": "footer-privacy",
"labelKey": "nav.privacy",
"route": "/privacy-policy",
"order": 3
}
]
},
"pages": [
{
"id": "page-home",
"key": "home",
"title": "Home",
"route": {
"path": "/",
"exact": true
},
"layout": "default-public",
"seoKey": "home",
"visible": true,
"sections": [
{
"id": "section-hero",
"type": "hero",
"order": 1,
"layout": {
"strategy": "hero",
"columns": 1,
"gap": "1.5rem",
"align": "stretch"
},
"visibility": {
"desktop": true,
"tablet": true,
"mobile": true
},
"visible": true,
"widgets": [
{
"id": "widget-hero-main",
"type": "hero",
"version": "1.0.0",
"visible": true,
"props": {
"title": "Welcome to Marketplace Platform",
"subtitle": "Configuration-driven multi-tenant commerce",
"ctaLabel": "Start Shopping"
}
}
]
},
{
"id": "section-categories",
"type": "categories",
"order": 2,
"layout": {
"strategy": "grid",
"columns": 1,
"gap": "1.5rem",
"align": "stretch"
},
"visibility": {
"desktop": true,
"tablet": true,
"mobile": true
},
"visible": true,
"widgets": [
{
"id": "widget-categories-root",
"type": "categories",
"version": "1.0.0",
"visible": true,
"props": {
"title": "Categories",
"source": "root",
"emptyMessage": "No categories available"
}
}
]
},
{
"id": "section-featured-products",
"type": "product-collection",
"order": 3,
"layout": {
"strategy": "carousel",
"columns": 1,
"gap": "1rem",
"align": "stretch"
},
"visibility": {
"desktop": true,
"tablet": true,
"mobile": true
},
"visible": true,
"widgets": [
{
"id": "widget-featured-products",
"type": "product-collection",
"version": "1.0.0",
"visible": true,
"props": {
"title": "Featured Products",
"source": "featured",
"count": 8,
"actionLabel": "Select"
}
}
]
}
]
}
]
}

12
public/manifest.novo.webmanifest
View File

@@ -1,7 +1,7 @@
{
"name": "Marketplace - Интернет-магазин",
"short_name": "Marketplace",
"description": "Интернет-магазин цифровых товаров и услуг",
"name": "Novo Market - Интернет-магазин",
"short_name": "Novo",
"description": "Novo Market - ваш онлайн магазин качественных товаров с доставкой",
"theme_color": "#10b981",
"background_color": "#ffffff",
"display": "standalone",
@@ -11,9 +11,9 @@
"categories": ["shopping", "lifestyle"],
"icons": [
{
"src": "icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png",
"src": "assets/images/novo-favicon.svg",
"sizes": "any",
"type": "image/svg+xml",
"purpose": "any"
},
{

10
public/manifest.webmanifest
View File

@@ -1,6 +1,6 @@
{
"name": "Marketplace - Интернет-магазин",
"short_name": "Marketplace",
"name": "Dexar Market - Интернет-магазин",
"short_name": "Dexar Market",
"description": "Интернет-магазин цифровых товаров и услуг",
"display": "standalone",
"orientation": "portrait-primary",
@@ -11,9 +11,9 @@
"categories": ["shopping", "marketplace"],
"icons": [
{
"src": "icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png",
"src": "assets/images/dexar-favicon.svg",
"sizes": "any",
"type": "image/svg+xml",
"purpose": "any"
},
{

13
public/robots.txt
View File

@@ -1,20 +1,9 @@
User-agent: *
Allow: /
Sitemap: https://dexarmarket.ru/sitemap.xml
# Block access to cart (user-specific data)
Disallow: /cart
# Block admin/backoffice and internal diagnostics
Disallow: /*/backoffice
Disallow: /*/edit
Disallow: /*/project-editor
Disallow: /__diagnostics
# Crawl delay for polite crawling
Crawl-delay: 1
# Static baseline sitemap (home/catalog/search/wishlist/compare only) - see
# public/sitemap.xml's own header comment for what this does and does not
# cover (no per-tenant product/category/static-page URLs yet - needs a
# backend/build-time generator, documented in docs/backend/BACKEND-INTEGRATION.md#619-sitemap-future--static-baseline-only-today).
Sitemap: /sitemap.xml

44
public/sitemap.xml
View File

@@ -1,44 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Static baseline sitemap - top-level, statically-known marketplace routes
only (home, catalog, search, wishlist, compare) for the site's default
locale segment ('ru', see app.routes.ts's `redirectTo: 'ru'` fallback).
Known limitation (documented, not faked): this is a multi-tenant,
config-driven platform (docs/ARCHITECTURE.md) - supported locales,
categories, products, and static pages are all resolved at runtime from
the tenant's bootstrap config, not enumerable at build time from the
frontend alone. A real per-tenant sitemap covering
/:lang/product/:id, /:lang/catalog/:categoryId, and /:lang/:staticPath
needs a backend/build-time job that reads the same bootstrap data source
and regenerates this file (or serves it dynamically) per tenant/domain -
see docs/backend/BACKEND-INTEGRATION.md#619-sitemap-future--static-baseline-only-today. Until that exists, this static file is a reasonable
floor, not the full picture.
-->
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>/ru</loc>
<changefreq>daily</changefreq>
<priority>1.0</priority>
</url>
<url>
<loc>/ru/catalog</loc>
<changefreq>daily</changefreq>
<priority>0.9</priority>
</url>
<url>
<loc>/ru/search</loc>
<changefreq>weekly</changefreq>
<priority>0.5</priority>
</url>
<url>
<loc>/ru/wishlist</loc>
<changefreq>monthly</changefreq>
<priority>0.3</priority>
</url>
<url>
<loc>/ru/compare</loc>
<changefreq>monthly</changefreq>
<priority>0.3</priority>
</url>
</urlset>

12
renovate.json
View File

@@ -1,12 +0,0 @@
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": ["config:recommended"],
"packageRules": [
{
"matchPackageNames": ["@marketplaces/auth", "@marketplaces/payment"],
"groupName": "marketplaces shared packages",
"automerge": false,
"labels": ["shared-package-update"]
}
]
}

125
scripts/deploy/add-domain.sh
View File

@@ -1,125 +0,0 @@
#!/usr/bin/env bash
#
# Attach one customer domain to this server and issue a TLS certificate.
# Idempotent: re-running for an existing domain renews/repairs rather than duplicates.
# Run as root, AFTER the domain's A/AAAA record already resolves to this server.
#
# bash add-domain.sh shop.example.com --email ops@example.com
# bash add-domain.sh shop.example.com --email ops@example.com --with-www
#
# Why per-domain blocks exist at all: the application is multi-tenant off the
# Host header and needs no per-domain root. Certificates are the exception —
# certbot must match a concrete server_name, which `default_server _` is not.
set -euo pipefail
DOMAIN="${1:-}"; shift || true
EMAIL=""
WITH_WWW=0
while [[ $# -gt 0 ]]; do
case "$1" in
--email) EMAIL="$2"; shift 2 ;;
--with-www) WITH_WWW=1; shift ;;
*) echo "unknown argument: $1" >&2; exit 2 ;;
esac
done
[[ $EUID -eq 0 ]] || { echo "must run as root" >&2; exit 1; }
[[ -n "$DOMAIN" ]] || { echo "usage: add-domain.sh <domain> --email <address> [--with-www]" >&2; exit 2; }
[[ -n "$EMAIL" ]] || { echo "--email is required (certbot expiry notices)" >&2; exit 2; }
# Fail loudly rather than let certbot fail obscurely on an unpointed domain.
echo "==> checking DNS for $DOMAIN"
RESOLVED="$(getent hosts "$DOMAIN" | awk '{print $1}' | head -1 || true)"
if [[ -z "$RESOLVED" ]]; then
echo "ERROR: $DOMAIN does not resolve. Point its A record at this server first." >&2
exit 1
fi
echo " resolves to $RESOLVED"
NAMES="$DOMAIN"
CERT_ARGS=(-d "$DOMAIN")
if [[ $WITH_WWW -eq 1 ]]; then
NAMES="$DOMAIN www.$DOMAIN"
CERT_ARGS+=(-d "www.$DOMAIN")
fi
CONF="/etc/nginx/sites-available/tenant-$DOMAIN.conf"
echo "==> nginx server block: $CONF"
cat > "$CONF" <<NGINX
# Tenant domain: $DOMAIN
# Same root as the catch-all — the SPA resolves the tenant from the Host header.
# This block exists so certbot has a concrete server_name to attach TLS to.
server {
listen 80;
listen [::]:80;
server_name $NAMES;
root /srv/marketplaces/current/frontend;
index index.html;
location = /index.html {
add_header Cache-Control "no-store, must-revalidate" always;
try_files \$uri =404;
}
location ~* \.(js|css|woff2?|png|jpe?g|svg|gif|webp|avif|ico)\$ {
expires 1y;
add_header Cache-Control "public, immutable" always;
try_files \$uri =404;
}
location /health {
access_log off;
return 200 "ok\n";
add_header Content-Type text/plain;
}
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_read_timeout 60s;
}
location / {
try_files \$uri \$uri/ /index.html;
}
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
gzip on;
gzip_types text/plain text/css application/javascript application/json image/svg+xml;
gzip_min_length 1024;
}
NGINX
ln -sfn "$CONF" "/etc/nginx/sites-enabled/tenant-$DOMAIN.conf"
nginx -t
systemctl reload nginx
echo "==> certificate"
# --nginx rewrites the block above in place to add listen 443 + ssl directives
# and an HTTP->HTTPS redirect. Re-running is a no-op when the cert is current.
certbot --nginx "${CERT_ARGS[@]}" \
--non-interactive --agree-tos --email "$EMAIL" \
--redirect --keep-until-expiring
nginx -t
systemctl reload nginx
echo "==> renewal timer"
systemctl enable --now certbot.timer
systemctl status certbot.timer --no-pager | head -3 || true
echo
echo "done. verify:"
echo " curl -I https://$DOMAIN/health"
echo " certbot certificates | grep -A3 $DOMAIN"

192
scripts/deploy/server-setup.sh
View File

@@ -1,192 +0,0 @@
#!/usr/bin/env bash
#
# One-time server provisioning for the marketplaces frontend.
# Idempotent: safe to re-run. Run as root on the target server.
#
# bash server-setup.sh --pubkey "ssh-ed25519 AAAA... ci@marketplaces"
#
# What it does NOT do: issue TLS certificates (no domain points here yet).
# Run add-domain.sh per domain once DNS resolves. See docs/DEPLOYMENT.md.
set -euo pipefail
DEPLOY_USER="deploy"
BASE="/srv/marketplaces"
PUBKEY=""
KEEP_RELEASES=5
while [[ $# -gt 0 ]]; do
case "$1" in
--pubkey) PUBKEY="$2"; shift 2 ;;
--user) DEPLOY_USER="$2"; shift 2 ;;
*) echo "unknown argument: $1" >&2; exit 2 ;;
esac
done
[[ $EUID -eq 0 ]] || { echo "must run as root" >&2; exit 1; }
[[ -n "$PUBKEY" ]] || { echo "--pubkey is required (the CI deploy key's PUBLIC half)" >&2; exit 1; }
echo "==> packages"
export DEBIAN_FRONTEND=noninteractive
apt-get update -qq
apt-get install -y -qq nginx certbot python3-certbot-nginx rsync ufw jq curl openssl
echo "==> deploy user: $DEPLOY_USER"
if ! id -u "$DEPLOY_USER" >/dev/null 2>&1; then
# No password is ever set: this account is key-only by construction.
adduser --system --group --shell /bin/bash --home "/home/$DEPLOY_USER" "$DEPLOY_USER"
fi
install -d -m 700 -o "$DEPLOY_USER" -g "$DEPLOY_USER" "/home/$DEPLOY_USER/.ssh"
AUTH="/home/$DEPLOY_USER/.ssh/authorized_keys"
touch "$AUTH"
grep -qxF "$PUBKEY" "$AUTH" || echo "$PUBKEY" >> "$AUTH"
chown "$DEPLOY_USER:$DEPLOY_USER" "$AUTH"
chmod 600 "$AUTH"
echo "==> directories"
install -d -m 755 -o "$DEPLOY_USER" -g "$DEPLOY_USER" "$BASE" "$BASE/releases"
# First deploy creates $BASE/current as a symlink into releases/.
# Seed a placeholder so nginx starts cleanly before anything is deployed.
if [[ ! -e "$BASE/current" ]]; then
install -d -m 755 -o "$DEPLOY_USER" -g "$DEPLOY_USER" "$BASE/releases/bootstrap/frontend"
echo "<!doctype html><title>marketplaces</title><p>Not deployed yet." \
> "$BASE/releases/bootstrap/frontend/index.html"
chown -R "$DEPLOY_USER:$DEPLOY_USER" "$BASE/releases/bootstrap"
ln -sfn "$BASE/releases/bootstrap" "$BASE/current"
chown -h "$DEPLOY_USER:$DEPLOY_USER" "$BASE/current"
fi
echo "==> nginx catch-all (multi-tenant: one bundle serves every domain)"
cat > /etc/nginx/sites-available/marketplaces.conf <<'NGINX'
# Multi-tenant by design: the SPA derives its tenant from the Host header,
# so ONE server block serves every customer domain. Do not add a per-tenant
# root here. Per-domain server blocks exist only to hold TLS certificates
# (see add-domain.sh) and proxy to this same root.
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _;
root /srv/marketplaces/current/frontend;
index index.html;
access_log /var/log/nginx/marketplaces.access.log;
error_log /var/log/nginx/marketplaces.error.log;
# Do not let the browser cache the app shell: a deploy must take effect
# on the next reload, not whenever a stale index.html expires.
location = /index.html {
add_header Cache-Control "no-store, must-revalidate" always;
try_files $uri =404;
}
# Hashed build artifacts are immutable by construction.
location ~* \.(js|css|woff2?|png|jpe?g|svg|gif|webp|avif|ico)$ {
expires 1y;
add_header Cache-Control "public, immutable" always;
try_files $uri =404;
}
location /health {
access_log off;
return 200 "ok\n";
add_header Content-Type text/plain;
}
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 60s;
}
# SPA fallback. Must stay last: every unmatched path is a client route.
location / {
try_files $uri $uri/ /index.html;
}
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
gzip on;
gzip_types text/plain text/css application/javascript application/json image/svg+xml;
gzip_min_length 1024;
}
NGINX
ln -sfn /etc/nginx/sites-available/marketplaces.conf /etc/nginx/sites-enabled/marketplaces.conf
rm -f /etc/nginx/sites-enabled/default
echo "==> firewall"
ufw allow OpenSSH >/dev/null
ufw allow 80/tcp >/dev/null
ufw allow 443/tcp >/dev/null
ufw --force enable >/dev/null
echo "==> nginx config test"
nginx -t
systemctl enable --now nginx
systemctl reload nginx
echo "==> dynamic domain reconciler"
SRC_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
install -d -m 755 "$BASE/bin" /etc/marketplaces "/var/lib/marketplaces"
if [[ -f "$SRC_DIR/sync-domains.sh" ]]; then
install -m 755 "$SRC_DIR/sync-domains.sh" "$BASE/bin/sync-domains.sh"
if [[ ! -f /etc/marketplaces/domains.env ]]; then
cat > /etc/marketplaces/domains.env <<'ENVFILE'
# Where the desired domain list comes from.
# file:/etc/marketplaces/domains.txt one hostname per line
# https://api.example.com/api/admin/v2/domains JSON, once the backend exists
DOMAINS_SOURCE=file:/etc/marketplaces/domains.txt
# Required: certbot expiry notices.
CERTBOT_EMAIL=
# Cap per run so a bad source cannot burn the weekly ACME budget in one pass.
MAX_ISSUE_PER_RUN=10
# Set by setup-wildcard-tls.sh. Subdomains of this apex skip per-domain issuance.
#WILDCARD_APEX=
ENVFILE
chmod 600 /etc/marketplaces/domains.env
fi
touch /etc/marketplaces/domains.txt
if [[ -d "$SRC_DIR/systemd" ]]; then
install -m 644 "$SRC_DIR/systemd/marketplaces-domains.service" /etc/systemd/system/
install -m 644 "$SRC_DIR/systemd/marketplaces-domains.timer" /etc/systemd/system/
systemctl daemon-reload
# Not started yet: CERTBOT_EMAIL is still blank. Enable it after filling in
# /etc/marketplaces/domains.env, or the first run just fails on every tick.
echo " timer installed but NOT started - set CERTBOT_EMAIL first, then:"
echo " systemctl enable --now marketplaces-domains.timer"
fi
else
echo " sync-domains.sh not found next to this script - skipping"
fi
echo "==> sudoers: let the deploy user reload nginx, nothing else"
cat > /etc/sudoers.d/marketplaces-deploy <<SUDO
$DEPLOY_USER ALL=(root) NOPASSWD: /bin/systemctl reload nginx
SUDO
chmod 440 /etc/sudoers.d/marketplaces-deploy
visudo -c -f /etc/sudoers.d/marketplaces-deploy
echo
echo "done."
echo " deploy user : $DEPLOY_USER (key-only, no password)"
echo " web root : $BASE/current/frontend"
echo " keep : last $KEEP_RELEASES releases"
echo
echo "next:"
echo " 1. curl -I http://<this-server>/health -> expect 200"
echo " 2. point a domain's A record here"
echo " 3. bash add-domain.sh <domain> -> issues TLS"
echo " 4. add CI secrets, push to main -> first real deploy"

148
scripts/deploy/setup-wildcard-tls.sh
View File

@@ -1,148 +0,0 @@
#!/usr/bin/env bash
#
# Issue ONE wildcard certificate covering every tenant subdomain under an apex.
# After this, a new tenant at <slug>.<apex> needs no certificate work at all —
# DNS record, and it is live over HTTPS immediately.
#
# setup-wildcard-tls.sh --apex marketplaces.example.com --email ops@example.com --dns cloudflare
# setup-wildcard-tls.sh --apex marketplaces.example.com --email ops@example.com --dns manual
#
# Wildcards require DNS-01 validation — HTTP-01 cannot issue them. That means
# certbot must create a _acme-challenge TXT record, which needs either a DNS
# provider plugin (automatic, renews unattended) or manual intervention every
# 60-90 days. Prefer a plugin. Use manual only to prove the idea out.
#
# Tenants on their OWN domains are not covered by a wildcard; those are handled
# per-domain by sync-domains.sh.
set -euo pipefail
APEX=""; EMAIL=""; DNS_PLUGIN="manual"; CREDS=""
while [[ $# -gt 0 ]]; do
case "$1" in
--apex) APEX="$2"; shift 2 ;;
--email) EMAIL="$2"; shift 2 ;;
--dns) DNS_PLUGIN="$2"; shift 2 ;;
--creds) CREDS="$2"; shift 2 ;;
*) echo "unknown argument: $1" >&2; exit 2 ;;
esac
done
[[ $EUID -eq 0 ]] || { echo "must run as root" >&2; exit 1; }
[[ -n "$APEX" ]] || { echo "--apex is required" >&2; exit 2; }
[[ -n "$EMAIL" ]] || { echo "--email is required" >&2; exit 2; }
export DEBIAN_FRONTEND=noninteractive
CERT_ARGS=(-d "$APEX" -d "*.$APEX")
case "$DNS_PLUGIN" in
cloudflare)
apt-get install -y -qq python3-certbot-dns-cloudflare
[[ -n "$CREDS" ]] || { echo "--creds <file> required for cloudflare (contains the API token)" >&2; exit 2; }
chmod 600 "$CREDS"
CERT_ARGS+=(--dns-cloudflare --dns-cloudflare-credentials "$CREDS" --dns-cloudflare-propagation-seconds 30)
;;
route53)
apt-get install -y -qq python3-certbot-dns-route53
CERT_ARGS+=(--dns-route53) # credentials come from the instance role or ~/.aws
;;
manual)
cat >&2 <<'WARN'
WARNING: manual DNS-01.
certbot will print a TXT record for you to create by hand, and will do so again
at every renewal (every 60-90 days). Unattended renewal will NOT work. This is
acceptable to prove the setup out; it is not acceptable as the steady state.
Hostinger has no certbot plugin. If DNS lives there, the options are: move DNS
to a provider with a plugin (Cloudflare is free and takes minutes), or drive
issuance from the Phase 9 domain-automation API instead.
WARN
CERT_ARGS+=(--manual --preferred-challenges dns)
;;
*)
echo "unsupported --dns: $DNS_PLUGIN (cloudflare|route53|manual)" >&2; exit 2 ;;
esac
echo "==> issuing wildcard for $APEX and *.$APEX via $DNS_PLUGIN"
certbot certonly "${CERT_ARGS[@]}" \
--agree-tos --email "$EMAIL" --keep-until-expiring \
$([[ "$DNS_PLUGIN" != "manual" ]] && echo --non-interactive)
LIVE="/etc/letsencrypt/live/$APEX"
[[ -f "$LIVE/fullchain.pem" ]] || { echo "certificate not found at $LIVE" >&2; exit 1; }
echo "==> nginx: TLS on the catch-all, so every subdomain is served immediately"
cat > /etc/nginx/snippets/marketplaces-wildcard-tls.conf <<SNIPPET
# Managed by setup-wildcard-tls.sh
ssl_certificate $LIVE/fullchain.pem;
ssl_certificate_key $LIVE/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_stapling on;
ssl_stapling_verify on;
SNIPPET
cat > /etc/nginx/sites-available/marketplaces-tls.conf <<NGINX
# Wildcard TLS catch-all for *.$APEX
# Any tenant subdomain is served here with no per-tenant configuration.
server {
listen 443 ssl default_server;
listen [::]:443 ssl default_server;
http2 on;
server_name $APEX *.$APEX;
include /etc/nginx/snippets/marketplaces-wildcard-tls.conf;
root /srv/marketplaces/current/frontend;
index index.html;
location = /index.html {
add_header Cache-Control "no-store, must-revalidate" always;
try_files \$uri =404;
}
location ~* \.(js|css|woff2?|png|jpe?g|svg|gif|webp|avif|ico)\$ {
expires 1y;
add_header Cache-Control "public, immutable" always;
try_files \$uri =404;
}
location /health { access_log off; return 200 "ok\n"; add_header Content-Type text/plain; }
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
}
location / { try_files \$uri \$uri/ /index.html; }
add_header Strict-Transport-Security "max-age=31536000" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
gzip on;
gzip_types text/plain text/css application/javascript application/json image/svg+xml;
gzip_min_length 1024;
}
NGINX
ln -sfn /etc/nginx/sites-available/marketplaces-tls.conf /etc/nginx/sites-enabled/marketplaces-tls.conf
nginx -t
systemctl reload nginx
systemctl enable --now certbot.timer
# Tell sync-domains.sh which names it can skip.
mkdir -p /etc/marketplaces
if [[ -f /etc/marketplaces/domains.env ]]; then
sed -i '/^WILDCARD_APEX=/d' /etc/marketplaces/domains.env
fi
echo "WILDCARD_APEX=$APEX" >> /etc/marketplaces/domains.env
echo
echo "done. every <slug>.$APEX is now served over HTTPS with no further action."
echo "verify: curl -I https://anything.$APEX/health"

234
scripts/deploy/sync-domains.sh
View File

@@ -1,234 +0,0 @@
#!/usr/bin/env bash
#
# Reconcile the set of TLS-enabled domains on this server against a desired
# list. Idempotent and safe to run on a timer: it issues what is missing,
# leaves what is current alone, and disables what has been removed.
#
# The nginx catch-all already serves ANY Host over HTTP with no config, so a
# new domain works on port 80 the moment DNS resolves. This script exists only
# because TLS needs a certificate per name.
#
# sync-domains.sh # reconcile from $DOMAINS_SOURCE
# sync-domains.sh --dry-run # print the plan, change nothing
#
# Config: /etc/marketplaces/domains.env
# DOMAINS_SOURCE=file:/etc/marketplaces/domains.txt
# DOMAINS_SOURCE=https://api.example.com/api/admin/v2/domains (JSON array)
# CERTBOT_EMAIL=ops@example.com
# MAX_ISSUE_PER_RUN=10
#
# Let's Encrypt caps new certificates per registered domain per week. The
# per-run issuance cap keeps a misconfigured source from burning that budget
# in one pass; the remainder is picked up on the next run.
set -euo pipefail
CONFIG="/etc/marketplaces/domains.env"
STATE_DIR="/var/lib/marketplaces"
DRY_RUN=0
RENEW_WINDOW_DAYS=30
[[ "${1:-}" == "--dry-run" ]] && DRY_RUN=1
# shellcheck source=/dev/null
[[ -f "$CONFIG" ]] && source "$CONFIG"
DOMAINS_SOURCE="${DOMAINS_SOURCE:-file:/etc/marketplaces/domains.txt}"
CERTBOT_EMAIL="${CERTBOT_EMAIL:-}"
MAX_ISSUE_PER_RUN="${MAX_ISSUE_PER_RUN:-10}"
WILDCARD_APEX="${WILDCARD_APEX:-}"
[[ $EUID -eq 0 ]] || { echo "must run as root" >&2; exit 1; }
[[ -n "$CERTBOT_EMAIL" ]] || { echo "CERTBOT_EMAIL not set in $CONFIG" >&2; exit 1; }
mkdir -p "$STATE_DIR"
log() { printf '%s %s\n' "$(date -Is)" "$*"; }
# ---------------------------------------------------------------- desired set
fetch_desired() {
case "$DOMAINS_SOURCE" in
file:*)
local path="${DOMAINS_SOURCE#file:}"
[[ -f "$path" ]] || { log "source file $path missing"; return 1; }
# one domain per line; # comments and blanks ignored
sed -e 's/#.*//' -e 's/[[:space:]]//g' "$path" | grep -v '^$' || true
;;
http://*|https://*)
# Expected shape: ["a.example.com","b.example.com"] or
# [{"domain":"a.example.com","status":"active"}, ...]
local body
body="$(curl -fsS --max-time 20 ${DOMAINS_API_TOKEN:+-H "Authorization: Bearer $DOMAINS_API_TOKEN"} "$DOMAINS_SOURCE")" || {
log "ERROR: could not fetch $DOMAINS_SOURCE — leaving current config untouched"
return 1
}
echo "$body" | jq -r '
if type=="array" and (.[0]|type)=="object"
then .[] | select((.status // "active") == "active") | .domain
else .[] end' 2>/dev/null || {
log "ERROR: unparseable response from $DOMAINS_SOURCE"
return 1
}
;;
*)
log "ERROR: unsupported DOMAINS_SOURCE: $DOMAINS_SOURCE"; return 1 ;;
esac
}
# A source failure must never be read as "all domains removed". Bail instead.
if ! DESIRED_RAW="$(fetch_desired)"; then
log "reconcile aborted: desired set unavailable"
exit 1
fi
# Reject anything that is not a plausible hostname before it reaches certbot
# or an nginx server_name.
DESIRED="$(echo "$DESIRED_RAW" | grep -Ei '^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$' | sort -u || true)"
REJECTED="$(comm -23 <(echo "$DESIRED_RAW" | sort -u) <(echo "$DESIRED") || true)"
[[ -n "$REJECTED" ]] && log "WARNING: ignoring malformed entries: $(echo "$REJECTED" | tr '\n' ' ')"
if [[ -z "$DESIRED" ]]; then
log "desired set is empty — nothing to do (not treating this as 'remove everything')"
exit 0
fi
log "desired: $(echo "$DESIRED" | wc -l) domain(s)"
# ------------------------------------------------------------------ helpers
covered_by_wildcard() {
# A domain one label under the wildcard apex needs no certificate of its own.
local d="$1"
[[ -n "$WILDCARD_APEX" ]] || return 1
[[ "$d" == *".$WILDCARD_APEX" ]] || return 1
[[ "${d%.$WILDCARD_APEX}" != *.* ]]
}
cert_is_current() {
local d="$1" live="/etc/letsencrypt/live/$1/cert.pem"
[[ -f "$live" ]] || return 1
openssl x509 -in "$live" -noout -checkend $((RENEW_WINDOW_DAYS * 86400)) >/dev/null 2>&1
}
resolves_here() {
local d="$1"
local got want
got="$(getent hosts "$d" | awk '{print $1}' | sort -u)"
[[ -n "$got" ]] || return 1
# Compare against every address this host actually answers on.
want="$(hostname -I | tr ' ' '\n' | grep -v '^$')"
grep -qxF -f <(echo "$want") <(echo "$got")
}
write_block() {
local d="$1" conf="/etc/nginx/sites-available/tenant-$1.conf"
cat > "$conf" <<NGINX
# Managed by sync-domains.sh. Manual edits are overwritten.
# Same root as the catch-all: the SPA resolves its tenant from the Host header.
server {
listen 80;
listen [::]:80;
server_name $d;
root /srv/marketplaces/current/frontend;
index index.html;
location = /index.html {
add_header Cache-Control "no-store, must-revalidate" always;
try_files \$uri =404;
}
location ~* \.(js|css|woff2?|png|jpe?g|svg|gif|webp|avif|ico)\$ {
expires 1y;
add_header Cache-Control "public, immutable" always;
try_files \$uri =404;
}
location /health { access_log off; return 200 "ok\n"; add_header Content-Type text/plain; }
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
}
location / { try_files \$uri \$uri/ /index.html; }
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
gzip on;
gzip_types text/plain text/css application/javascript application/json image/svg+xml;
gzip_min_length 1024;
}
NGINX
ln -sfn "$conf" "/etc/nginx/sites-enabled/tenant-$d.conf"
}
# ------------------------------------------------------------------ reconcile
issued=0 skipped=0 waiting=0 wildcarded=0 failed=0
while read -r d; do
[[ -n "$d" ]] || continue
if covered_by_wildcard "$d"; then
wildcarded=$((wildcarded + 1)); continue
fi
if cert_is_current "$d"; then
skipped=$((skipped + 1)); continue
fi
if ! resolves_here "$d"; then
log "waiting on DNS: $d (does not resolve to this server yet)"
waiting=$((waiting + 1)); continue
fi
if [[ $issued -ge $MAX_ISSUE_PER_RUN ]]; then
log "issuance cap ($MAX_ISSUE_PER_RUN) reached — remaining domains roll to the next run"
break
fi
if [[ $DRY_RUN -eq 1 ]]; then
log "DRY RUN would issue: $d"; issued=$((issued + 1)); continue
fi
log "issuing: $d"
write_block "$d"
if ! nginx -t >/dev/null 2>&1; then
log "ERROR: nginx config invalid after adding $d — reverting that block"
rm -f "/etc/nginx/sites-enabled/tenant-$d.conf"
failed=$((failed + 1)); continue
fi
systemctl reload nginx
if certbot --nginx -d "$d" --non-interactive --agree-tos \
--email "$CERTBOT_EMAIL" --redirect --keep-until-expiring >>"$STATE_DIR/certbot.log" 2>&1; then
issued=$((issued + 1))
log "issued: $d"
else
log "ERROR: certbot failed for $d (see $STATE_DIR/certbot.log) — HTTP still served, HTTPS not yet"
failed=$((failed + 1))
fi
done <<< "$DESIRED"
# Domains dropped from the source: stop serving them, but never delete the
# certificate — a domain re-added next week should not need a fresh issuance.
for link in /etc/nginx/sites-enabled/tenant-*.conf; do
[[ -e "$link" ]] || continue
name="$(basename "$link")"; name="${name#tenant-}"; name="${name%.conf}"
if ! grep -qxF "$name" <<< "$DESIRED"; then
if [[ $DRY_RUN -eq 1 ]]; then
log "DRY RUN would disable: $name"
else
log "disabling (removed from source): $name"
rm -f "$link"
fi
fi
done
if [[ $DRY_RUN -eq 0 ]]; then
nginx -t && systemctl reload nginx
fi
log "done. issued=$issued current=$skipped wildcard=$wildcarded awaiting-dns=$waiting failed=$failed"
[[ $failed -eq 0 ]]

12
scripts/deploy/systemd/marketplaces-domains.service
View File

@@ -1,12 +0,0 @@
[Unit]
Description=Reconcile tenant TLS domains
After=network-online.target nginx.service
Wants=network-online.target
[Service]
Type=oneshot
ExecStart=/srv/marketplaces/bin/sync-domains.sh
# A failed run must not tear down what is already serving; the next run retries.
SuccessExitStatus=0
StandardOutput=journal
StandardError=journal

12
scripts/deploy/systemd/marketplaces-domains.timer
View File

@@ -1,12 +0,0 @@
[Unit]
Description=Reconcile tenant TLS domains every 10 minutes
[Timer]
OnBootSec=2min
OnUnitActiveSec=10min
# Spread load so many servers do not all hit the ACME API at once.
RandomizedDelaySec=90s
Persistent=true
[Install]
WantedBy=timers.target

59
skills-lock.json
View File

@@ -1,59 +0,0 @@
{
"version": 1,
"skills": {
"angular-developer": {
"source": "angular/skills",
"sourceType": "github",
"skillPath": "angular-developer/SKILL.md",
"computedHash": "62e087c9cf0dc17f4ca4fed9f451f65605f43e4427016eb799409d6da39a0a87"
},
"cavecrew": {
"source": "JuliusBrussee/caveman",
"sourceType": "github",
"skillPath": "skills/cavecrew/SKILL.md",
"computedHash": "9633c1391fa246091ce68ea522c0e424b2bc93aeb69fc44221a30b53e8a2c23d"
},
"caveman": {
"source": "JuliusBrussee/caveman",
"sourceType": "github",
"skillPath": "skills/caveman/SKILL.md",
"computedHash": "723fb2a8bec1156c0f0b5bf020cc739ed09702b7726ec6377480038871339f6e"
},
"caveman-commit": {
"source": "JuliusBrussee/caveman",
"sourceType": "github",
"skillPath": "skills/caveman-commit/SKILL.md",
"computedHash": "f028652defd5fdeddcce2994083cb1a7b201ee827bba8e2495546ee159fca3de"
},
"caveman-compress": {
"source": "JuliusBrussee/caveman",
"sourceType": "github",
"skillPath": "skills/caveman-compress/SKILL.md",
"computedHash": "1055abaf7cb2f8c0ca78b64101b84dfc910d9819733ed9f0277b661441797aeb"
},
"caveman-help": {
"source": "JuliusBrussee/caveman",
"sourceType": "github",
"skillPath": "skills/caveman-help/SKILL.md",
"computedHash": "4dba39eea07a050108d47940b39600bc8f45489201ecff0ccf03627180fd8e50"
},
"caveman-review": {
"source": "JuliusBrussee/caveman",
"sourceType": "github",
"skillPath": "skills/caveman-review/SKILL.md",
"computedHash": "b9091dbc51de0f3710ea818fd4d638539f8c1784f8fda931eb159c44861e702e"
},
"caveman-stats": {
"source": "JuliusBrussee/caveman",
"sourceType": "github",
"skillPath": "skills/caveman-stats/SKILL.md",
"computedHash": "331f720e2fa97b68cacdae44384878071e8cac6013479edea68f4c8eca308852"
},
"design-taste-frontend": {
"source": "Leonxlnx/taste-skill",
"sourceType": "github",
"skillPath": "skills/taste-skill/SKILL.md",
"computedHash": "899b84384f74f540ea5284d9b2e9234e050998b42eacc805410b518d4226c0b3"
}
}
}

25
src/app/app.config.ts
View File

@@ -1,18 +1,12 @@
import { ApplicationConfig, provideBrowserGlobalErrorListeners, provideZoneChangeDetection, isDevMode } from '@angular/core';
import { provideRouter, withInMemoryScrolling } from '@angular/router';
import { provideHttpClient, withInterceptors, withXhr } from '@angular/common/http';
import { provideHttpClient, withInterceptors } from '@angular/common/http';
import { routes } from './app.routes';
import { cacheInterceptor } from './interceptors/cache.interceptor';
import { apiErrorInterceptor } from './core/interceptors/api-error.interceptor';
import { apiBaseUrlInterceptor } from './interceptors/api-base-url.interceptor';
import { apiHeadersInterceptor } from './interceptors/api-headers.interceptor';
import { mockDataInterceptor } from './interceptors/mock-data.interceptor';
import { adminAuthHeadersInterceptor, Ed25519VerificationService, NoopEd25519VerificationService, AUTH_API_URL, TELEGRAM_BOT_USERNAME } from '@marketplaces/auth';
import { provideServiceWorker } from '@angular/service-worker';
import { MediaRepository } from './core/media/media-repository';
import { MockMediaRepository } from './core/media/mock-media-repository.service';
import { environment } from '../environments/environment';
export const appConfig: ApplicationConfig = {
providers: [
@@ -22,22 +16,9 @@ export const appConfig: ApplicationConfig = {
routes,
withInMemoryScrolling({ scrollPositionRestoration: 'top' })
),
provideHttpClient(withXhr(),
// apiErrorInterceptor sits last so it observes the response after every
// other interceptor has run, and normalizes whatever actually came back.
withInterceptors([mockDataInterceptor, apiBaseUrlInterceptor, apiHeadersInterceptor, adminAuthHeadersInterceptor, cacheInterceptor, apiErrorInterceptor])
provideHttpClient(
withInterceptors([mockDataInterceptor, apiHeadersInterceptor, cacheInterceptor])
),
{ provide: AUTH_API_URL, useValue: environment.authApiUrl },
{ provide: TELEGRAM_BOT_USERNAME, useValue: environment.telegramBot },
// useFactory, not useClass: @marketplaces/auth ships plain tsc output, not
// Angular Package Format, so it carries no baked-in Ivy DI metadata for
// this class. useClass forces Angular to JIT-compile it at runtime, which
// throws when @angular/compiler isn't loaded (true for this build). A
// factory sidesteps that - NoopEd25519VerificationService has zero
// constructor deps, so this is a correct fix, not a workaround.
// Real fix belongs in vitanovaPackages: publish with ng-packagr.
{ provide: Ed25519VerificationService, useFactory: () => new NoopEd25519VerificationService() },
{ provide: MediaRepository, useClass: MockMediaRepository },
provideServiceWorker('ngsw-worker.js', {
enabled: !isDevMode(),
registrationStrategy: 'registerWhenStable:30000'

8
src/app/app.html
View File

@@ -10,24 +10,18 @@
<p>{{ 'app.serverError' | translate }}</p>
<button class="retry-btn" (click)="retryConnection()">{{ 'app.retryConnection' | translate }}</button>
</div>
} @else if (isAdminRoute()) {
<router-outlet></router-outlet>
<app-telegram-login mode="admin" />
} @else {
<a class="skip-link" href="#main-content">{{ 'app.skipToContent' | translate }}</a>
<app-header></app-header>
<main id="main-content" class="main-content" tabindex="-1">
<main class="main-content">
@if (!isHomePage()) {
<app-back-button />
}
<router-outlet></router-outlet>
</main>
<app-floating-notifications />
@defer (on viewport) {
<app-footer></app-footer>
} @placeholder {
<div class="footer-placeholder" aria-hidden="true"></div>
}
<!-- <app-telegram-login /> -->
<app-telegram-login mode="admin" />
}

367
src/app/app.routes.ts
View File

@@ -1,12 +1,6 @@
import { Routes } from '@angular/router';
import { brandInfoRoutes, brandLegalRoutes } from './brands/brand-routes';
import { languageGuard } from './guards/language.guard';
import { projectEditorDirtyGuard } from './features/project-editor/guards/project-editor-dirty.guard';
import { adminAuthGuard } from '@marketplaces/auth';
import { requireAdminPermission } from './core/admin-auth/admin-auth.guard';
import { authRoutes } from './core/auth/auth.routes';
import { adminCategoryDirtyGuard } from './features/admin/categories/guards/admin-category-dirty.guard';
import { adminProductDirtyGuard } from './features/admin/products/guards/admin-product-dirty.guard';
import { environment } from '../environments/environment';
// Core routes (same across all brands)
const coreRoutes: Routes = [
@@ -14,382 +8,37 @@ const coreRoutes: Routes = [
path: '',
loadComponent: () => import('./pages/home/home.component').then(m => m.HomeComponent)
},
{
path: 'catalog',
loadComponent: () => import('./features/website/catalog/containers/catalog-container.component').then(m => m.CatalogContainerComponent)
},
{
path: 'catalog/:id',
loadComponent: () => import('./features/website/catalog/containers/catalog-container.component').then(m => m.CatalogContainerComponent)
},
{
path: 'category/:id',
redirectTo: 'catalog/:id',
pathMatch: 'full'
loadComponent: () => import('./pages/category/subcategories.component').then(m => m.SubcategoriesComponent)
},
{
path: 'category/:id/items',
redirectTo: 'catalog/:id',
pathMatch: 'full'
},
{
path: 'product/:id',
loadComponent: () => import('./features/website/product/containers/product-details-container.component').then(m => m.ProductDetailsContainerComponent)
loadComponent: () => import('./pages/category/category.component').then(m => m.CategoryComponent)
},
{
path: 'item/:id',
redirectTo: 'product/:id',
pathMatch: 'full'
loadComponent: () => import('./pages/item-detail/item-detail.component').then(m => m.ItemDetailComponent)
},
{
path: 'search',
loadComponent: () => import('./features/website/catalog/containers/catalog-container.component').then(m => m.CatalogContainerComponent)
},
{
path: 'edit',
canActivate: [adminAuthGuard],
loadComponent: () => import('./features/project-editor/pages/builder-overview-page.component').then(m => m.BuilderOverviewPageComponent)
},
{
path: 'edit/:section',
canActivate: [adminAuthGuard],
loadComponent: () => import('./features/project-editor/pages/project-editor-page.component').then(m => m.ProjectEditorPageComponent),
canDeactivate: [projectEditorDirtyGuard]
},
{
path: 'backoffice',
canActivate: [adminAuthGuard],
loadComponent: () => import('./features/admin/shell/admin-layout.component').then(m => m.AdminLayoutComponent),
children: [
{ path: '', redirectTo: 'dashboard', pathMatch: 'full' },
{
path: 'dashboard',
loadComponent: () => import('./features/admin/dashboard/pages/admin-dashboard-page.component').then(m => m.AdminDashboardPageComponent),
data: {
titleKey: 'adminShell.pages.dashboard.title',
descriptionKey: 'adminShell.pages.dashboard.description',
breadcrumb: [{ labelKey: 'adminShell.pages.dashboard.title' }]
}
},
{
path: 'products',
loadComponent: () => import('./features/admin/products/pages/admin-products-list-page.component').then(m => m.AdminProductsListPageComponent),
data: {
titleKey: 'adminShell.pages.products.title',
descriptionKey: 'adminShell.pages.products.description',
breadcrumb: [{ labelKey: 'adminShell.nav.products' }]
}
},
{
path: 'products/create',
loadComponent: () => import('./features/admin/products/pages/admin-product-editor-page.component').then(m => m.AdminProductEditorPageComponent),
canDeactivate: [adminProductDirtyGuard],
data: {
titleKey: 'adminShell.pages.productCreate.title',
descriptionKey: 'adminShell.pages.productCreate.description',
breadcrumb: [{ labelKey: 'adminShell.nav.products', path: ['products'] }, { labelKey: 'adminShell.pages.productCreate.title' }]
}
},
{
path: 'products/:id/edit',
loadComponent: () => import('./features/admin/products/pages/admin-product-editor-page.component').then(m => m.AdminProductEditorPageComponent),
canDeactivate: [adminProductDirtyGuard],
data: {
titleKey: 'adminShell.pages.productEdit.title',
descriptionKey: 'adminShell.pages.productEdit.description',
breadcrumb: [{ labelKey: 'adminShell.nav.products', path: ['products'] }, { labelKey: 'adminShell.pages.productEdit.title' }]
}
},
{
path: 'products/:id/duplicate',
loadComponent: () => import('./features/admin/products/pages/admin-product-editor-page.component').then(m => m.AdminProductEditorPageComponent),
canDeactivate: [adminProductDirtyGuard],
data: {
titleKey: 'adminShell.pages.productDuplicate.title',
descriptionKey: 'adminShell.pages.productDuplicate.description',
breadcrumb: [{ labelKey: 'adminShell.nav.products', path: ['products'] }, { labelKey: 'adminShell.pages.productDuplicate.title' }]
}
},
{
path: 'categories',
loadComponent: () => import('./features/admin/categories/pages/admin-categories-list-page.component').then(m => m.AdminCategoriesListPageComponent),
data: {
titleKey: 'adminShell.pages.categories.title',
descriptionKey: 'adminShell.pages.categories.description',
breadcrumb: [{ labelKey: 'adminShell.nav.categories' }]
}
},
{
path: 'categories/create',
loadComponent: () => import('./features/admin/categories/pages/admin-category-editor-page.component').then(m => m.AdminCategoryEditorPageComponent),
canDeactivate: [adminCategoryDirtyGuard],
data: {
titleKey: 'adminShell.pages.categoryCreate.title',
descriptionKey: 'adminShell.pages.categoryCreate.description',
breadcrumb: [{ labelKey: 'adminShell.nav.categories', path: ['categories'] }, { labelKey: 'adminShell.pages.categoryCreate.title' }]
}
},
{
path: 'categories/:id/edit',
loadComponent: () => import('./features/admin/categories/pages/admin-category-editor-page.component').then(m => m.AdminCategoryEditorPageComponent),
canDeactivate: [adminCategoryDirtyGuard],
data: {
titleKey: 'adminShell.pages.categoryEdit.title',
descriptionKey: 'adminShell.pages.categoryEdit.description',
breadcrumb: [{ labelKey: 'adminShell.nav.categories', path: ['categories'] }, { labelKey: 'adminShell.pages.categoryEdit.title' }]
}
},
{
// Static Pages is a first-class Project Editor module (Sprint X+2), not a
// separate backoffice CRUD surface - redirect here rather than build a
// second UI over the same bootstrap.staticPages data.
path: 'static-pages',
redirectTo: '/edit/static-pages',
pathMatch: 'full'
},
{
path: 'transactions',
loadComponent: () => import('./features/admin/transactions/pages/admin-transactions-list-page.component').then(m => m.AdminTransactionsListPageComponent),
data: {
titleKey: 'adminShell.pages.transactions.title',
descriptionKey: 'adminShell.pages.transactions.description',
breadcrumb: [{ labelKey: 'adminShell.nav.transactions' }]
}
},
{
path: 'orders',
loadComponent: () => import('./features/admin/orders/pages/admin-orders-list-page.component').then(m => m.AdminOrdersListPageComponent),
data: {
titleKey: 'adminShell.pages.orders.title',
descriptionKey: 'adminShell.pages.orders.description',
breadcrumb: [{ labelKey: 'adminShell.nav.orders' }]
}
},
{
path: 'orders/:id',
loadComponent: () => import('./features/admin/orders/pages/admin-order-detail-page.component').then(m => m.AdminOrderDetailPageComponent),
data: {
titleKey: 'adminShell.pages.orderDetail.title',
descriptionKey: 'adminShell.pages.orderDetail.description',
breadcrumb: [{ labelKey: 'adminShell.nav.orders', path: ['orders'] }, { labelKey: 'adminShell.pages.orderDetail.title' }]
}
},
{
path: 'customers',
loadComponent: () => import('./features/admin/customers/pages/admin-customers-list-page.component').then(m => m.AdminCustomersListPageComponent),
data: {
titleKey: 'adminShell.pages.customers.title',
descriptionKey: 'adminShell.pages.customers.description',
breadcrumb: [{ labelKey: 'adminShell.nav.customers' }]
}
},
{
path: 'customers/:email',
loadComponent: () => import('./features/admin/customers/pages/admin-customer-detail-page.component').then(m => m.AdminCustomerDetailPageComponent),
data: {
titleKey: 'adminShell.pages.customerDetail.title',
descriptionKey: 'adminShell.pages.customerDetail.description',
breadcrumb: [{ labelKey: 'adminShell.nav.customers', path: ['customers'] }, { labelKey: 'adminShell.pages.customerDetail.title' }]
}
},
{
path: 'notifications',
loadComponent: () => import('./features/admin/notifications/pages/admin-notifications-page.component').then(m => m.AdminNotificationsPageComponent),
data: {
titleKey: 'adminShell.nav.notifications',
descriptionKey: 'adminShell.nav.notifications',
breadcrumb: [{ labelKey: 'adminShell.nav.notifications' }]
}
},
{
path: 'integrations',
loadComponent: () => import('./features/admin/integrations/pages/admin-integrations-page.component').then(m => m.AdminIntegrationsPageComponent),
data: {
titleKey: 'adminShell.nav.integrations',
descriptionKey: 'adminShell.nav.integrations',
breadcrumb: [{ labelKey: 'adminShell.nav.integrations' }]
}
},
{
path: 'finance',
loadComponent: () => import('./features/admin/finance/pages/admin-finance-page.component').then(m => m.AdminFinancePageComponent),
data: {
titleKey: 'adminShell.nav.finance',
descriptionKey: 'adminShell.nav.finance',
breadcrumb: [{ labelKey: 'adminShell.nav.finance' }]
}
},
{
path: 'marketplaces',
loadComponent: () => import('./features/admin/marketplaces/pages/admin-marketplaces-page.component').then(m => m.AdminMarketplacesPageComponent),
data: {
titleKey: 'adminShell.nav.marketplaces',
descriptionKey: 'adminShell.nav.marketplaces',
breadcrumb: [{ labelKey: 'adminShell.nav.marketplaces' }]
}
},
{
path: 'partner-hierarchy',
loadComponent: () => import('./features/admin/partner-hierarchy/pages/admin-partner-hierarchy-page.component').then(m => m.AdminPartnerHierarchyPageComponent),
data: {
titleKey: 'adminShell.nav.partnerHierarchy',
descriptionKey: 'adminShell.nav.partnerHierarchy',
breadcrumb: [{ labelKey: 'adminShell.nav.partnerHierarchy' }]
}
},
{
path: 'audit',
loadComponent: () => import('./features/admin/audit/pages/admin-audit-page.component').then(m => m.AdminAuditPageComponent),
data: {
titleKey: 'adminShell.nav.audit',
descriptionKey: 'adminShell.nav.audit',
breadcrumb: [{ labelKey: 'adminShell.nav.audit' }]
}
},
{
path: 'moderation',
loadComponent: () => import('./features/admin/moderation/pages/admin-reviews-list-page.component').then(m => m.AdminReviewsListPageComponent),
data: {
titleKey: 'adminShell.pages.moderation.title',
descriptionKey: 'adminShell.pages.moderation.description',
breadcrumb: [{ labelKey: 'adminShell.nav.moderation' }]
}
},
{
path: 'moderation/reports',
loadComponent: () => import('./features/admin/moderation/pages/admin-reports-list-page.component').then(m => m.AdminReportsListPageComponent),
data: {
titleKey: 'adminShell.pages.reportsQueue.title',
descriptionKey: 'adminShell.pages.reportsQueue.description',
breadcrumb: [{ labelKey: 'adminShell.nav.moderation', path: ['moderation'] }, { labelKey: 'adminShell.pages.reportsQueue.title' }]
}
},
{
path: 'moderation/:id',
loadComponent: () => import('./features/admin/moderation/pages/admin-review-detail-page.component').then(m => m.AdminReviewDetailPageComponent),
data: {
titleKey: 'adminShell.pages.reviewDetail.title',
descriptionKey: 'adminShell.pages.reviewDetail.description',
breadcrumb: [{ labelKey: 'adminShell.nav.moderation', path: ['moderation'] }, { labelKey: 'adminShell.pages.reviewDetail.title' }]
}
},
{
path: 'media',
loadComponent: () => import('./features/backoffice/media/media-library-page.component').then(m => m.MediaLibraryPageComponent),
data: {
titleKey: 'adminShell.pages.media.title',
descriptionKey: 'adminShell.pages.media.description',
breadcrumb: [{ labelKey: 'adminShell.nav.mediaLibrary' }]
}
},
{
path: 'users',
canActivate: [requireAdminPermission('users.manage')],
loadComponent: () => import('./features/admin/users/pages/admin-users-page.component').then(m => m.AdminUsersPageComponent),
data: {
titleKey: 'adminShell.pages.users.title',
descriptionKey: 'adminShell.pages.users.description',
breadcrumb: [{ labelKey: 'adminShell.nav.users' }]
}
},
{
path: 'monitoring',
loadComponent: () => import('./features/admin/monitoring/pages/admin-monitoring-page.component').then(m => m.AdminMonitoringPageComponent),
data: {
titleKey: 'adminShell.pages.monitoring.title',
descriptionKey: 'adminShell.pages.monitoring.description',
breadcrumb: [{ labelKey: 'adminShell.nav.monitoring' }]
}
},
{
path: 'analytics',
loadComponent: () => import('./features/admin/analytics/pages/admin-analytics-page.component').then(m => m.AdminAnalyticsPageComponent),
data: {
titleKey: 'adminShell.pages.analytics.title',
descriptionKey: 'adminShell.pages.analytics.description',
breadcrumb: [{ labelKey: 'adminShell.nav.analytics' }]
}
},
{
path: 'reports',
loadComponent: () => import('./features/admin/reports/pages/admin-reports-page.component').then(m => m.AdminReportsPageComponent),
data: {
titleKey: 'adminShell.pages.reports.title',
descriptionKey: 'adminShell.pages.reports.description',
breadcrumb: [{ labelKey: 'adminShell.nav.reports' }]
}
},
{
path: 'settings',
loadComponent: () => import('./features/admin/settings/pages/admin-settings-page.component').then(m => m.AdminSettingsPageComponent),
data: {
titleKey: 'adminShell.pages.settings.title',
descriptionKey: 'adminShell.pages.settings.description',
breadcrumb: [{ labelKey: 'adminShell.nav.settings' }]
}
},
{
path: 'partners/seller-management',
loadComponent: () => import('./features/admin/seller-management/pages/admin-seller-management-page.component').then(m => m.AdminSellerManagementPageComponent),
data: {
titleKey: 'adminShell.pages.sellerManagement.title',
descriptionKey: 'adminShell.pages.sellerManagement.description',
breadcrumb: [{ labelKey: 'adminShell.nav.sellerManagement' }]
}
},
{ path: '**', redirectTo: 'dashboard' }
]
},
{
path: 'builder',
redirectTo: 'edit',
pathMatch: 'full'
},
{
path: 'project-editor',
redirectTo: 'edit',
pathMatch: 'full'
},
{
path: 'wishlist',
loadComponent: () => import('./features/website/user-experience/wishlist/containers/wishlist-page.component').then(m => m.WishlistPageComponent)
},
{
path: 'compare',
loadComponent: () => import('./features/website/user-experience/compare/containers/compare-page.component').then(m => m.ComparePageComponent)
loadComponent: () => import('./pages/search/search.component').then(m => m.SearchComponent)
},
{
path: 'cart',
loadComponent: () => import('./pages/cart/cart.component').then(m => m.CartComponent)
},
{
path: 'page/:key',
loadComponent: () => import('./pages/static-page/static-page.component').then(m => m.StaticPageComponent)
},
{
path: ':staticPath',
loadComponent: () => import('./pages/static-page/static-page.component').then(m => m.StaticPageComponent)
}
];
// TODO(CMS): Resolve informational/legal pages from backend content configuration here.
// Disabled hardcoded pages: about, contacts, faq, delivery, guarantee,
// company-details, payment-terms, return-policy, public-offer, privacy-policy.
const cmsContentRoutes: Routes = [];
// All routes sit under a :lang prefix (e.g. /ru/cart, /en/product/5)
// All routes sit under a :lang prefix (e.g. /ru/cart, /en/item/5)
export const routes: Routes = [
...(environment.production ? [] : [{
path: '__diagnostics',
loadComponent: () => import('./features/diagnostics/components/diagnostics-page.component').then(m => m.DiagnosticsPageComponent)
}]),
...authRoutes,
{
path: ':lang',
canActivate: [languageGuard],
children: [
...coreRoutes,
...cmsContentRoutes,
...brandInfoRoutes,
...brandLegalRoutes,
{ path: '**', redirectTo: '' }
]
},

6
src/app/app.scss
View File

@@ -43,7 +43,7 @@
.server-error-overlay h2 {
margin: 0 0 0.5rem;
font-size: var(--font-size-2xl, 1.25rem);
font-size: 1.25rem;
}
.server-error-overlay p {
@@ -55,10 +55,10 @@
.retry-btn {
padding: 0.75rem 2rem;
border: none;
border-radius: var(--radius-sm, 8px);
border-radius: 8px;
background: var(--primary-color, #007bff);
color: #fff;
font-size: var(--font-size-lg, 1rem);
font-size: 1rem;
cursor: pointer;
transition: opacity 0.2s;

60
src/app/app.ts
View File

@@ -1,58 +1,43 @@
import { Component, OnInit, signal, ApplicationRef, inject, DestroyRef, ChangeDetectionStrategy } from '@angular/core';
import { Component, OnInit, signal, ApplicationRef, inject, DestroyRef } from '@angular/core';
import { Router, RouterOutlet, NavigationEnd } from '@angular/router';
import { Title } from '@angular/platform-browser';
import { HttpClient } from '@angular/common/http';
import { HeaderComponent } from './components/header/header.component';
import { FooterComponent } from './components/footer/footer.component';
import { BackButtonComponent } from './components/back-button/back-button.component';
import { interval, concat } from 'rxjs';
import { filter, first } from 'rxjs/operators';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { environment } from '../environments/environment';
import { SwUpdate } from '@angular/service-worker';
import { TranslatePipe } from './i18n/translate.pipe';
import { TranslateService } from './i18n/translate.service';
import { PlatformRuntimeService } from './core/runtime/platform-runtime.service';
import { UiRuntimeFacade } from './facades/runtime/ui-runtime.facade';
import { ApiHealthService } from './services/api-health.service';
import { SeoService } from './services/seo.service';
import { FloatingNotificationsComponent } from './features/website/user-experience/components/floating-notifications/floating-notifications.component';
import { AdminAuthService, AuthService } from '@marketplaces/auth';
import { TelegramLoginComponent } from './components/telegram-login/telegram-login.component';
@Component({
selector: 'app-root',
imports: [RouterOutlet, HeaderComponent, FooterComponent, BackButtonComponent, TranslatePipe, FloatingNotificationsComponent, TelegramLoginComponent],
imports: [RouterOutlet, HeaderComponent, FooterComponent, BackButtonComponent, TranslatePipe],
templateUrl: './app.html',
styleUrl: './app.scss',
changeDetection: ChangeDetectionStrategy.OnPush
styleUrl: './app.scss'
})
export class App implements OnInit {
protected title = '';
protected title = environment.brandName;
isHomePage = signal(true);
isAdminRoute = signal(false);
checkingServer = signal(true);
serverAvailable = signal(false);
private destroyRef = inject(DestroyRef);
private http = inject(HttpClient);
private titleService = inject(Title);
private swUpdate = inject(SwUpdate);
private appRef = inject(ApplicationRef);
private router = inject(Router);
private i18n = inject(TranslateService);
private platformRuntime = inject(PlatformRuntimeService);
private uiRuntime = inject(UiRuntimeFacade);
private apiHealth = inject(ApiHealthService);
private seoService = inject(SeoService);
private authService = inject(AuthService);
private adminAuthService = inject(AdminAuthService);
ngOnInit(): void {
this.platformRuntime.initialize();
this.title = this.uiRuntime.marketplaceName();
this.titleService.setTitle(`${this.uiRuntime.marketplaceDisplayName()} - ${this.i18n.t('app.pageTitle')}`);
this.titleService.setTitle(`${environment.brandFullName} - ${this.i18n.t('app.pageTitle')}`);
this.checkServerHealth();
this.setupAutoUpdates();
this.openLoginDialogsFromTestModeQueryParams();
// Track route changes to show/hide back button
this.router.events
@@ -65,16 +50,12 @@ export class App implements OnInit {
const url = navEnd.urlAfterRedirects || navEnd.url;
// Home pages: /ru, /en, /hy (with or without trailing slash)
this.isHomePage.set(/^\/[a-z]{2}\/?$/.test(url) || url === '/' || url === '');
// Admin backoffice and the Marketplace Builder (/edit) own their own
// shells (AdminLayoutComponent / ProjectEditorPageComponent's sidebar) -
// the storefront header/back-button/footer never render on either.
this.isAdminRoute.set(/^\/[a-z]{2}\/(backoffice|edit)(\/|$|\?)/.test(url));
});
}
private checkServerHealth(): void {
this.checkingServer.set(true);
this.apiHealth.ping()
this.http.get<{ message: string }>(`${environment.apiUrl}/ping`)
.pipe(takeUntilDestroyed(this.destroyRef))
.subscribe({
next: () => {
@@ -92,29 +73,6 @@ export class App implements OnInit {
this.checkServerHealth();
}
/**
* ?login=true / ?adminLogin=true open the respective login dialog for
* manual testing. ?devBypassAdmin=true skips the QR flow entirely and
* activates a fake local admin session - dev builds only, no effect (and
* no-ops server-side too, see AdminAuthService.devBypassLogin) in
* production. No effect when the params are absent.
*/
private openLoginDialogsFromTestModeQueryParams(): void {
if (typeof window === 'undefined') {
return;
}
const params = new URLSearchParams(window.location.search);
if (params.get('login') === 'true') {
this.authService.requestLogin();
}
if (params.get('adminLogin') === 'true') {
this.adminAuthService.requestLogin();
}
if (params.get('devBypassAdmin') === 'true') {
this.adminAuthService.devBypassLogin();
}
}
private setupAutoUpdates(): void {
if (!this.swUpdate.isEnabled) {
return;

49
src/app/brands/brand-routes.lavero.ts Normal file
View File

@@ -0,0 +1,49 @@
// Lavero brand routes
// Loaded via angular.json fileReplacements when building for novo
import { Routes } from '@angular/router';
export const brandInfoRoutes: Routes = [
{
path: 'about',
loadComponent: () => import('./lavero/pages/info/about/about.component').then(m => m.AboutLaveroComponent)
},
{
path: 'contacts',
loadComponent: () => import('./lavero/pages/info/contacts/contacts.component').then(m => m.ContactsLaveroComponent)
},
{
path: 'faq',
loadComponent: () => import('./lavero/pages/info/faq/faq.component').then(m => m.FaqLaveroComponent)
},
{
path: 'delivery',
loadComponent: () => import('./lavero/pages/info/delivery/delivery.component').then(m => m.DeliveryLaveroComponent)
},
{
path: 'guarantee',
loadComponent: () => import('./lavero/pages/info/guarantee/guarantee.component').then(m => m.GuaranteeLaveroComponent)
}
];
export const brandLegalRoutes: Routes = [
{
path: 'company-details',
loadComponent: () => import('./lavero/pages/legal/company-details/company-details.component').then(m => m.CompanyDetailsLaveroComponent)
},
{
path: 'payment-terms',
loadComponent: () => import('./lavero/pages/legal/payment-terms/payment-terms.component').then(m => m.PaymentTermsLaveroComponent)
},
{
path: 'return-policy',
loadComponent: () => import('./lavero/pages/legal/return-policy/return-policy.component').then(m => m.ReturnPolicyLaveroComponent)
},
{
path: 'public-offer',
loadComponent: () => import('./lavero/pages/legal/public-offer/public-offer.component').then(m => m.PublicOfferLaveroComponent)
},
{
path: 'privacy-policy',
loadComponent: () => import('./lavero/pages/legal/privacy-policy/privacy-policy.component').then(m => m.PrivacyPolicyLaveroComponent)
}
];

49
src/app/brands/brand-routes.novo.ts Normal file
View File

@@ -0,0 +1,49 @@
// Novo brand routes
// Loaded via angular.json fileReplacements when building for novo
import { Routes } from '@angular/router';
export const brandInfoRoutes: Routes = [
{
path: 'about',
loadComponent: () => import('./novo/pages/info/about/about.component').then(m => m.AboutNovoComponent)
},
{
path: 'contacts',
loadComponent: () => import('./novo/pages/info/contacts/contacts.component').then(m => m.ContactsNovoComponent)
},
{
path: 'faq',
loadComponent: () => import('./novo/pages/info/faq/faq.component').then(m => m.FaqNovoComponent)
},
{
path: 'delivery',
loadComponent: () => import('./novo/pages/info/delivery/delivery.component').then(m => m.DeliveryNovoComponent)
},
{
path: 'guarantee',
loadComponent: () => import('./novo/pages/info/guarantee/guarantee.component').then(m => m.GuaranteeNovoComponent)
}
];
export const brandLegalRoutes: Routes = [
{
path: 'company-details',
loadComponent: () => import('./novo/pages/legal/company-details/company-details.component').then(m => m.CompanyDetailsNovoComponent)
},
{
path: 'payment-terms',
loadComponent: () => import('./novo/pages/legal/payment-terms/payment-terms.component').then(m => m.PaymentTermsNovoComponent)
},
{
path: 'return-policy',
loadComponent: () => import('./novo/pages/legal/return-policy/return-policy.component').then(m => m.ReturnPolicyNovoComponent)
},
{
path: 'public-offer',
loadComponent: () => import('./novo/pages/legal/public-offer/public-offer.component').then(m => m.PublicOfferNovoComponent)
},
{
path: 'privacy-policy',
loadComponent: () => import('./novo/pages/legal/privacy-policy/privacy-policy.component').then(m => m.PrivacyPolicyNovoComponent)
}
];

49
src/app/brands/brand-routes.ts Normal file
View File

@@ -0,0 +1,49 @@
// Default brand routes (Dexar)
// This file is swapped via angular.json fileReplacements for each brand
import { Routes } from '@angular/router';
export const brandInfoRoutes: Routes = [
{
path: 'about',
loadComponent: () => import('../pages/info/about/about.component').then(m => m.AboutComponent)
},
{
path: 'contacts',
loadComponent: () => import('../pages/info/contacts/contacts.component').then(m => m.ContactsComponent)
},
{
path: 'faq',
loadComponent: () => import('../pages/info/faq/faq.component').then(m => m.FaqComponent)
},
{
path: 'delivery',
loadComponent: () => import('../pages/info/delivery/delivery.component').then(m => m.DeliveryComponent)
},
{
path: 'guarantee',
loadComponent: () => import('../pages/info/guarantee/guarantee.component').then(m => m.GuaranteeComponent)
}
];
export const brandLegalRoutes: Routes = [
{
path: 'company-details',
loadComponent: () => import('../pages/legal/company-details/company-details.component').then(m => m.CompanyDetailsComponent)
},
{
path: 'payment-terms',
loadComponent: () => import('../pages/legal/payment-terms/payment-terms.component').then(m => m.PaymentTermsComponent)
},
{
path: 'return-policy',
loadComponent: () => import('../pages/legal/return-policy/return-policy.component').then(m => m.ReturnPolicyComponent)
},
{
path: 'public-offer',
loadComponent: () => import('../pages/legal/public-offer/public-offer.component').then(m => m.PublicOfferComponent)
},
{
path: 'privacy-policy',
loadComponent: () => import('../pages/legal/privacy-policy/privacy-policy.component').then(m => m.PrivacyPolicyComponent)
}
];

5
src/app/brands/lavero/pages/info/about/about.component.html Normal file
View File

@@ -0,0 +1,5 @@
@switch (lang()) {
@case ('ru') { <app-about-lavero-ru /> }
@case ('en') { <app-about-lavero-en /> }
@case ('hy') { <app-about-lavero-hy /> }
}

16
src/app/brands/lavero/pages/info/about/about.component.ts Normal file
View File

@@ -0,0 +1,16 @@
import { Component, ChangeDetectionStrategy, inject } from '@angular/core';
import { LanguageService } from '../../../../../services/language.service';
import { AboutLaveroRuComponent } from './ru/about-ru.component';
import { AboutLaveroEnComponent } from './en/about-en.component';
import { AboutLaveroHyComponent } from './hy/about-hy.component';
@Component({
selector: 'app-about-lavero',
imports: [AboutLaveroRuComponent, AboutLaveroEnComponent, AboutLaveroHyComponent],
templateUrl: './about.component.html',
styleUrls: ['../../../../../pages/info/about/about.component.scss'],
changeDetection: ChangeDetectionStrategy.OnPush
})
export class AboutLaveroComponent {
lang = inject(LanguageService).currentLanguage;
}

98
src/app/brands/lavero/pages/info/about/en/about-en.component.html Normal file
View File

@@ -0,0 +1,98 @@
<div class="legal-page">
<div class="legal-container">
<div class="lavero-header">
<h1>About Us</h1>
<p class="subtitle">A modern marketplace for your convenience</p>
</div>
<div class="lavero-cards">
<div class="info-card wide">
<div class="card-icon">🚀</div>
<h3>Who We Are</h3>
<p>We are a rapidly growing marketplace connecting sellers and buyers from different countries. Our platform creates convenient conditions for safe trading of various goods and services.</p>
</div>
<div class="info-card wide">
<div class="card-icon">🎯</div>
<h3>Our Mission</h3>
<p>To create a simple and profitable ecosystem for businesses and buyers, where everyone finds the best deals.</p>
</div>
<div class="info-card wide">
<div class="card-icon">🌍</div>
<h3>Geography</h3>
<p>We operate in Russia, Armenia, UAE, Turkey, China, Kazakhstan, Kyrgyzstan, and other countries.</p>
</div>
<div class="info-card wide">
<div class="card-icon">💼</div>
<h3>For Business</h3>
<ul class="compact-list">
<li>Easy product listing</li>
<li>Ready-made audience</li>
<li>Convenient tools</li>
<li>Technical support</li>
</ul>
</div>
<div class="info-card wide">
<div class="card-icon">🛍️</div>
<h3>For Buyers</h3>
<ul class="compact-list">
<li>Wide selection of products</li>
<li>Competitive prices</li>
<li>Safe purchases</li>
<li>Fast delivery</li>
</ul>
</div>
<div class="info-card wide">
<div class="card-icon">🔒</div>
<h3>Our Values</h3>
<div class="features-list">
<div class="feature">✓ Transparency</div>
<div class="feature">✓ Reliability</div>
<div class="feature">✓ Innovation</div>
<div class="feature">✓ Customer Service</div>
</div>
</div>
<div class="info-card wide">
<div class="card-icon">📈</div>
<h3>Our Journey</h3>
<div class="timeline">
<div class="timeline-item">
<strong>2024</strong>
<p>Platform launch in Armenia</p>
</div>
<div class="timeline-item">
<strong>2025</strong>
<p>Expansion to the Russian market</p>
</div>
<div class="timeline-item">
<strong>Today</strong>
<p>International expansion</p>
</div>
</div>
</div>
<div class="info-card wide">
<div class="card-icon">🏢</div>
<h3>Company Details</h3>
<p><strong>Company:</strong> «LAVERO» LLC</p>
<p><strong>Director:</strong> GEVORG MATEVOSYAN</p>
<p><strong>TIN (ՀVHH):</strong> 03590442</p>
<p><strong>Registration No.:</strong> 999.110.1583686</p>
<p><strong>Address:</strong> ARMENIA, KOTAYK, ABOVYAN, VERIN PTGHNI, 3rd Street, 28</p>
</div>
<div class="info-card wide">
<div class="card-icon">📞</div>
<h3>Contact Us</h3>
<a href="mailto:info@lovero.store" class="contact-email">info@lovero.store</a>
<p><a [href]="env.phoneTel">{{ env.phones.support }}</a></p>
<p class="support-note">We are always in touch</p>
</div>
</div>
</div>
</div>

12
src/app/brands/lavero/pages/info/about/en/about-en.component.ts Normal file
View File

@@ -0,0 +1,12 @@
import { Component, ChangeDetectionStrategy } from '@angular/core';
import { environment } from '../../../../../../../environments/environment';
@Component({
selector: 'app-about-lavero-en',
templateUrl: './about-en.component.html',
styleUrls: ['../../../../../../pages/info/about/about.component.scss'],
changeDetection: ChangeDetectionStrategy.OnPush
})
export class AboutLaveroEnComponent {
protected readonly env = environment;
}

98
src/app/brands/lavero/pages/info/about/hy/about-hy.component.html Normal file
View File

@@ -0,0 +1,98 @@
<div class="legal-page">
<div class="legal-container">
<div class="lavero-header">
<h1>Մեր մասին</h1>
<p class="subtitle">Զամանակակից մարկեթփլեյս ձեր հարմարության համար</p>
</div>
<div class="lavero-cards">
<div class="info-card wide">
<div class="card-icon">🚀</div>
<h3>Ովքեր ենք</h3>
<p>Մենք դինամիկ զարգացող մարկեթփլեյս ենք, որը միավորում է վաճառողներին և գնորդներին տարբեր երկրներից։ Մեր հարթակը ստեղծում է հարմար պայմաններ տարբեր ապրանքների և ծառայությունների անվտանգ առևտրի համար։</p>
</div>
<div class="info-card wide">
<div class="card-icon">🎯</div>
<h3>Մեր առաքելությունը</h3>
<p>Ստեղծել պարզ և շահավետ էկոհամակարգ բիզնեսի և գնորդների համար, որտեղ բոլորը գտնեն լավագույն առաջարկները։</p>
</div>
<div class="info-card wide">
<div class="card-icon">🌍</div>
<h3>Աշխարհագրություն</h3>
<p>Մենք աշխատում ենք Ռուսաստանում, Հայաստանում, ԱՀԷ-ում, Թուրքիայում, Չինաստանում, Ղազախստանում, Ղրղզստանում և այլ երկրներում։</p>
</div>
<div class="info-card wide">
<div class="card-icon">💼</div>
<h3>Բիզնեսի համար</h3>
<ul class="compact-list">
<li>Ապրանքների հեշտ տեղադրում</li>
<li>Պատրաստ լսարան</li>
<li>Հարմար գործիքներ</li>
<li>Տեխնիկական աջակցություն</li>
</ul>
</div>
<div class="info-card wide">
<div class="card-icon">🛍️</div>
<h3>Գնորդների համար</h3>
<ul class="compact-list">
<li>Ապրանքների լայն ընտրություն</li>
<li>Մրցունակելի գներ</li>
<li>Անվտանգ գնումներ</li>
<li>Արագ առաքում</li>
</ul>
</div>
<div class="info-card wide">
<div class="card-icon">🔒</div>
<h3>Մեր արժեքները</h3>
<div class="features-list">
<div class="feature">✓ Թափանցիկություն</div>
<div class="feature">✓ Հուսալիություն</div>
<div class="feature">✓ Նորարարություն</div>
<div class="feature">✓ Հաճախորդային սպասարկում</div>
</div>
</div>
<div class="info-card wide">
<div class="card-icon">📈</div>
<h3>Մեր ճանապարհը</h3>
<div class="timeline">
<div class="timeline-item">
<strong>2024</strong>
<p>Հարթակի գործարկումը Հայաստանում</p>
</div>
<div class="timeline-item">
<strong>2025</strong>
<p>Մուտք ռուսական շուկա</p>
</div>
<div class="timeline-item">
<strong>Այսօր</strong>
<p>Միջազգային ընդլայնում</p>
</div>
</div>
</div>
<div class="info-card wide">
<div class="card-icon">🏢</div>
<h3>Ինկերության տվյալները</h3>
<p><strong>Ընկерություն՝</strong> «ԼАВЕРО» ՍՊԸ</p>
<p><strong>Տнօрен՝</strong> ГЕВORG МАТЕВОСЯН (GEVORG MATEVOSYAN)</p>
<p><strong>ՀВHH՝</strong> 03590442</p>
<p><strong>Гранцман h/h՝</strong> 999.110.1583686</p>
<p><strong>Hasцe՝</strong> ՀАЙАСТАН, КОТАЙК, АБОВЯН, ВЕРИН ПТГНИ, 3-рд ПOЛOC, 28</p>
</div>
<div class="info-card wide">
<div class="card-icon">📞</div>
<h3>Կապվել մեզ հետ</h3>
<a href="mailto:info@lovero.store" class="contact-email">info@lovero.store</a>
<p><a [href]="env.phoneTel">{{ env.phones.support }}</a></p>
<p class="support-note">Մենք միշտ կապի մեջ ենք</p>
</div>
</div>
</div>
</div>

12
src/app/brands/lavero/pages/info/about/hy/about-hy.component.ts Normal file
View File

@@ -0,0 +1,12 @@
import { Component, ChangeDetectionStrategy } from '@angular/core';
import { environment } from '../../../../../../../environments/environment';
@Component({
selector: 'app-about-lavero-hy',
templateUrl: './about-hy.component.html',
styleUrls: ['../../../../../../pages/info/about/about.component.scss'],
changeDetection: ChangeDetectionStrategy.OnPush
})
export class AboutLaveroHyComponent {
protected readonly env = environment;
}

98
src/app/brands/lavero/pages/info/about/ru/about-ru.component.html Normal file
View File

@@ -0,0 +1,98 @@
<div class="legal-page">
<div class="legal-container">
<div class="lavero-header">
<h1>О нас</h1>
<p class="subtitle">Современный маркетплейс для вашего удобства</p>
</div>
<div class="lavero-cards">
<div class="info-card wide">
<div class="card-icon">🚀</div>
<h3>Кто мы</h3>
<p>Мы - динамично развивающийся маркетплейс, объединяющий продавцов и покупателей из разных стран. Наша платформа создает удобные условия для безопасной торговли различными товарами и услугами.</p>
</div>
<div class="info-card wide">
<div class="card-icon">🎯</div>
<h3>Наша миссия</h3>
<p>Создавать простую и выгодную экосистему для бизнеса и покупателей, где каждый находит лучшие предложения.</p>
</div>
<div class="info-card wide">
<div class="card-icon">🌍</div>
<h3>География</h3>
<p>Мы работаем в России, Армении, ОАЭ, Турции, Китае, Казахстане, Кыргызстане и других странах.</p>
</div>
<div class="info-card wide">
<div class="card-icon">💼</div>
<h3>Для бизнеса</h3>
<ul class="compact-list">
<li>Простое размещение товаров</li>
<li>Готовая аудитория</li>
<li>Удобные инструменты</li>
<li>Техническая поддержка</li>
</ul>
</div>
<div class="info-card wide">
<div class="card-icon">🛍️</div>
<h3>Для покупателей</h3>
<ul class="compact-list">
<li>Широкий выбор товаров</li>
<li>Выгодные цены</li>
<li>Безопасные покупки</li>
<li>Быстрая доставка</li>
</ul>
</div>
<div class="info-card wide">
<div class="card-icon">🔒</div>
<h3>Наши ценности</h3>
<div class="features-list">
<div class="feature">✓ Прозрачность</div>
<div class="feature">✓ Надежность</div>
<div class="feature">✓ Инновации</div>
<div class="feature">✓ Клиентский сервис</div>
</div>
</div>
<div class="info-card wide">
<div class="card-icon">📈</div>
<h3>Наш путь</h3>
<div class="timeline">
<div class="timeline-item">
<strong>2024</strong>
<p>Запуск платформы в Армении</p>
</div>
<div class="timeline-item">
<strong>2025</strong>
<p>Выход на российский рынок</p>
</div>
<div class="timeline-item">
<strong>Сегодня</strong>
<p>Международная экспансия</p>
</div>
</div>
</div>
<div class="info-card wide">
<div class="card-icon">🏢</div>
<h3>Реквизиты компании</h3>
<p><strong>Компания:</strong> «ЛАВЕРО» ООО</p>
<p><strong>Директор:</strong> ГЕВОРГ МАТЕВОСЯН</p>
<p><strong>ՀВՀՀ (ИНН):</strong> 03590442</p>
<p><strong>Рег. номер:</strong> 999.110.1583686</p>
<p><strong>Адрес:</strong> АРМЕНИЯ, КОТАЙК, АБОВЯН, ВЕРИН ПТГНИ, ул. 3-я, 28</p>
</div>
<div class="info-card wide">
<div class="card-icon">📞</div>
<h3>Связаться с нами</h3>
<a href="mailto:info@lovero.store" class="contact-email">info@lovero.store</a>
<p><a [href]="env.phoneTel">{{ env.phones.support }}</a></p>
<p class="support-note">Мы всегда на связи</p>
</div>
</div>
</div>
</div>

12
src/app/brands/lavero/pages/info/about/ru/about-ru.component.ts Normal file
View File

@@ -0,0 +1,12 @@
import { Component, ChangeDetectionStrategy } from '@angular/core';
import { environment } from '../../../../../../../environments/environment';
@Component({
selector: 'app-about-lavero-ru',
templateUrl: './about-ru.component.html',
styleUrls: ['../../../../../../pages/info/about/about.component.scss'],
changeDetection: ChangeDetectionStrategy.OnPush
})
export class AboutLaveroRuComponent {
protected readonly env = environment;
}

Some files were not shown because too many files have changed in this diff Show More