marketplaces/docs/Project-Editor.md

Marketplace Project Editor - Sprint 13 (updated Sprint 18)

Scope

Sprint 13 introduces first version of Marketplace Project Editor.

Editor only manages bootstrap configuration.

Out of scope:

• products
• categories
• orders
• analytics management

Architecture

src/app/features/project-editor/
  pages/
  components/
  sections/
  models/
  services/
  facade/

Editor uses strongly typed bootstrap models and isolated feature state. Components do not call APIs directly.

Facade API

ProjectEditorFacade exposes:

• loadBootstrap()
• updateBootstrap()
• exportBootstrap()
• importBootstrap()
• preview()

Current source of truth:

• existing bootstrap provider via ConfigService

Future backend integration:

• replace local import/export/save flow with builder endpoints
• keep component contracts unchanged

Supported Sections

• General
  • marketplace name
  • domain
  • description
  • default language
  • supported languages
• Branding
  • logo
  • small logo
  • favicon
  • marketplace title
• Theme
  • palette tokens via color pickers
• Header
  • logo/search/categories/languages/cart/profile/wishlist/compare/region toggles
• Footer
  • company information
  • address
  • phone
  • email
  • copyright
  • payment icons
  • social links
  • static pages
• Homepage
  • home page sections list
  • visibility
  • order
  • layout
  • drag-and-drop ordering
• Widgets
  • homepage widget configuration
  • typed shortcuts for hero/categories/product collection widgets
  • JSON fallback for other widget props
• Marketplace Features
  • feature flags
  • search suggestions/history
  • recently viewed
  • reviews/questions/recommendations
• Preview
  • export JSON
  • import JSON
  • runtime preview without full browser refresh
• Languages (Sprint 16)
  • add/remove supported locale
  • set default locale
  • generically syncs translation keys across static pages and navigation labels (LocaleSyncService)
• Navigation (Sprint 16)
  • header navigation: add/remove/reorder/edit label/URL/visibility
  • flat footer navigation: same actions
  • grouped footer navigation (column-based) is read-only in this tab for now

Preview Strategy

Preview updates bootstrap snapshot in memory and re-applies:

• theme
• branding
• runtime state
• route-based page rendering on next Angular navigation

This keeps bootstrap engine intact while enabling fast local preview.

Widget Configuration

Current widget editor supports explicit fields for:

• Hero
  • layout
  • height
  • overlay
  • autoplay
• Categories
  • layout
  • columns
• Product Collection
  • layout
  • cards per row
  • filters
  • badges
  • rating
  • price

Other widgets use JSON props fallback until dedicated editors are added.

Draft / Publish (Sprint 16, autosave added Sprint 18)

There is still no backend draft/publish API. This sprint models it client-side in ProjectEditorFacade:

• status: 'draft' | 'published' and dirty (diffed against the last-saved snapshot) live in facade state.
• save() snapshots the current in-memory bootstrap as "last saved" and timestamps it (lastSavedAt).
• publish() runs ProjectValidator, and if there are no issues, applies the bootstrap via PlatformRuntimeService.reloadFromBootstrap, marks status published, and becomes the new originalBootstrap snapshot used by reset.

Backend gap, not yet implemented: real persistence needs PUT /builder/bootstrap/draft and POST /builder/bootstrap/publish endpoints so drafts/publishes survive a reload and are shared across editors.

Autosave (Sprint 18)

ProjectEditorDraftStorageService (services/project-editor-draft-storage.service.ts) persists the full bootstrap draft to localStorage (key projectEditor.draftBootstrap.v1, scoped by tenant.id) on every updateBootstrap() call, save(), and publish(). On loadBootstrap(), if a stored draft exists for the same tenant it is loaded instead of the freshly-fetched bootstrap and draftRestored is set true (surfaced in the save bar as a dismissible notice). The published/loaded bootstrap is never overwritten automatically — only explicit publish() calls change what the runtime actually serves; the localStorage draft is a separate, purely local concern that survives refreshes and browser restarts.

Status indicators in ProjectEditorSaveBarComponent:

• Unsaved changes - shown while dirty() is true.
• Last saved: HH:MM:SS - shown once not dirty and lastSavedAt is set.
• Draft restored banner - shown once after a local draft is loaded from a previous session, dismissible.

Reset (Sprint 18)

• Reset section - button above the active section (shown only for sections with a bootstrap-key mapping in EDITOR_SECTION_BOOTSTRAP_KEYS, models/project-editor.model.ts). Reverts that section's bootstrap keys to originalBootstrap (the last loaded/published snapshot). Confirmation required.
• Reset draft - button in the save bar. Reverts the entire bootstrap to originalBootstrap and clears the persisted local draft. Confirmation required.
• Per-field reset is not implemented - the bootstrap schema has no registry of per-field defaults, so only section- and project-level reset exist. Adding field-level reset would require either a default-value registry per field or storing per-field undo history; deferred.

Validation

ProjectValidator (services/project-validator.service.ts) runs on every render of the save bar: missing logo, no languages, invalid marketplace URL, duplicate static-page slugs, empty homepage, a homepage widget with no type, duplicate header navigation links, invalid theme colors. Publish is blocked while any issue is present; Save is not.

Rich HTML editing

Static page HTML is edited via MarketplaceHtmlEditorComponent (components/html-editor/), a contentEditable + toolbar component with no external dependency. It emits raw HTML on every change and never sanitizes — sanitization remains a storefront-render concern.

QR Login Reuse (Sprint 18)

The Telegram QR-login flow (QR image, polling, expiry, "return from app" recovery via visibilitychange/focus/pageshow) was extracted from TelegramLoginComponent into shared/qr-login/qr-login.engine.ts (QrLoginEngine<TSession>) plus an adapter interface (shared/qr-login/qr-login.model.ts, QrLoginAdapter<TSession>). The engine is not a DI singleton - each login surface instantiates its own new QrLoginEngine(adapter) and drives it from an effect() watching its own dialog-visibility signal. TelegramLoginComponent was refactored onto this engine with no behavior change. AdminLoginComponent (core/admin-auth/admin-login.component.ts) reuses the same engine against a separate adapter backed by AdminAuthService, so QR/polling/timeout logic is not duplicated between customer and admin login.

Admin Authentication (Sprint 18)

Admin authentication is completely separate from the customer/storefront session (AuthService), by design - one must never authenticate the other:

	Customer (AuthService)	Admin (AdminAuthService, core/admin-auth/)
Cookie	webSessionID	adminSessionID (SameSite=Strict)
Anonymous/local id	web_session_id (localStorage, API attribution only)	adminToken / adminRefreshToken (localStorage, reserved for future JWT pair)
Signals	session, status, showLoginDialog on AuthService	session, status, showLoginDialog, role on AdminAuthService
Guard	none yet for customer routes	adminAuthGuard (core/admin-auth/admin-auth.guard.ts)
Interceptor	apiHeadersInterceptor	adminAuthHeadersInterceptor (core/admin-auth/admin-auth-headers.interceptor.ts), self-guards on /admin/ in the URL, sets AdminWebSessionID + Authorization: Bearer <adminToken> when present
Login UI	TelegramLoginComponent (mounted per-page, e.g. cart)	AdminLoginComponent (mounted once, globally, in app.html)

Backend gap: environment.adminAuthApiUrl (https://users.vitanova.network:456/admin) is a placeholder path under the existing auth host - there is no real admin session/login backend yet. AdminAuthService.createWebSession() / checkSessionOnce() / logout() call POST|GET|DELETE {adminAuthApiUrl}/sessions... following the same shape as the customer session API; confirm/repoint this once the backend ships dedicated admin endpoints.

Login test mode

?login=true and ?adminLogin=true query params (handled once in App.ngOnInit via openLoginDialogsFromTestModeQueryParams(), app.ts) call AuthService.requestLogin() / AdminAuthService.requestLogin() respectively, for manual testing. This only sets the same signal a normal "please log in" action would set - it does not bypass authentication or change any other behavior, so it is safe in all environments. Note TelegramLoginComponent is currently mounted only on the cart page, so ?login=true only shows a dialog there; AdminLoginComponent is mounted globally so ?adminLogin=true works from any route.

Ed25519 prep

core/admin-auth/ed25519-verification.model.ts defines Ed25519VerificationService (abstract, injectable) with requestChallenge() / verify(signedResponse) and the Ed25519Challenge / Ed25519SignedResponse / Ed25519VerificationResult shapes (nonce, timestamp, payload, public key, signature). No crypto is implemented. The current DI binding, NoopEd25519VerificationService (registered in app.config.ts), fails closed (throws) rather than silently accepting anything, so it's safe to wire into a real login path today - it will error loudly instead of pretending to verify a signature. Swap the DI binding for a real implementation once the backend ships challenge/verify endpoints; nothing else needs to change.

Known gaps / deferred (Sprint 18)

Full field-by-field coverage of every supported bootstrap property (with bilingual EN/RU labels, description, and validation state per field) was not completed in this pass - the bootstrap schema is large (theme typography/ spacing/shadows, full company address, per-locale footer copyright, grouped footer navigation editing, sidebar navigation, per-page SEO map, catalog/ product-page/user-experience sub-fields, permissions, API endpoints) and several concepts named in the sprint brief (payments, delivery/shipping, checkout, unified search config) have no corresponding model in shared/models/config at all - they would need new bootstrap schema before an editor could expose them. See the section-by-section gap list gathered during Sprint 18 investigation for the full inventory; treat as a follow-up sprint rather than something silently skipped.

Constraints

• runtime bootstrap engine not replaced
• configuration stays source of truth
• no hardcoded marketplace values
• no business domain management mixed into editor