api doc

docs/backend/REMAINING-BACKEND-WORK.md

@@ -0,0 +1,75 @@
+# Remaining backend work (everything except auth/session)
+
+Companion to the `API-CONTRACT.md` backend delivered separately (covers `GET /bootstrap`
+transport + `/users/sessions/*` — done, see prior conversation). This file lists what's
+still outstanding. Full request/response shapes, TypeScript
+interfaces, and validation rules for every item below already exist in
+[`docs/backend/BACKEND-INTEGRATION.md`](BACKEND-INTEGRATION.md) — this is a prioritized
+punch list with links into that spec, not a duplicate of it. **Do not re-document
+endpoint shapes here** — edit the master spec if a shape needs to change.
+
+Status legend (same as master spec): **PLANNED** = shape fully specified client-side,
+served by a mock gateway today, nothing built server-side yet. **FUTURE** = reserved
+contract only, no urgency. Bootstrap's *content* (branding/theme/nav values, not the
+`GET /bootstrap` transport itself) is also still outstanding — see P0 below.
+
+---
+
+## P0 — blocks going live at all
+
+| # | Item | Spec section |
+|---|---|---|
+| 1 | `bootstrap.json` real content (branding, theme, navigation, seo) — currently default stubs per backend's own note in API-CONTRACT.md | [§4](BACKEND-INTEGRATION.md#4-bootstrap) |
+| 2 | Builder — bootstrap draft/publish/validate (`GET/PUT /builder/bootstrap/draft`, `POST /builder/bootstrap/publish`, `POST /builder/bootstrap/validate`) — this is how the Marketplace Builder actually saves anything | [§6.7](BACKEND-INTEGRATION.md#67-builder--bootstrap-draftpublishvalidate-planned-highest-priority) |
+| 3 | Backoffice — Products CRUD + variants | [§6.10](BACKEND-INTEGRATION.md#610-backoffice--products-planned), DTOs [§7.2](BACKEND-INTEGRATION.md#72-products--srcappfeaturesadminproductsmodelsadmin-productmodelts) |
+| 4 | Backoffice — Categories CRUD (tree) | [§6.9](BACKEND-INTEGRATION.md#69-backoffice--categories-planned), DTOs [§7.1](BACKEND-INTEGRATION.md#71-categories--srcappfeaturesadmincategoriesmodelsadmin-categorymodelts) |
+| 5 | Media upload/delete/replace pipeline | [§6.18](BACKEND-INTEGRATION.md#618-media-planned--adr-0002), [§10](BACKEND-INTEGRATION.md#10-media) |
+
+## P1 — needed for real order/commerce flow
+
+| # | Item | Spec section |
+|---|---|---|
+| 6 | Backoffice — Orders CRUD + status transitions | [§6.11](BACKEND-INTEGRATION.md#611-backoffice--orders-planned), state machine [§8.1](BACKEND-INTEGRATION.md#81-orders--adminorderstatus) |
+| 7 | Backoffice — Transactions (list/detail, tied to orders) | [§6.12](BACKEND-INTEGRATION.md#612-backoffice--transactions-planned) |
+| 8 | Order creation endpoint — **does not exist anywhere yet**; checkout today only calls the frozen cart-payment endpoints, nothing creates an `AdminOrder` | [§16.9](BACKEND-INTEGRATION.md#169-order-creation-future--no-order-creation-endpoint-exists-anywhere-yet) |
+| 9 | Backoffice — Users/roles/invitations | [§6.13](BACKEND-INTEGRATION.md#613-backoffice--users-roles-invitations-planned) |
+| 10 | Backoffice — Moderation (review + report status transitions) | [§6.14](BACKEND-INTEGRATION.md#614-backoffice--moderation-reviews--reports-planned), state machines [§8.4](BACKEND-INTEGRATION.md#84-reviews--adminreviewstatus)/[§8.5](BACKEND-INTEGRATION.md#85-reports--adminreportstatus) |
+
+## P2 — dashboards / operational visibility
+
+| # | Item | Spec section |
+|---|---|---|
+| 11 | Backoffice — Dashboard metrics & recent activity | [§6.15](BACKEND-INTEGRATION.md#615-backoffice--dashboard-metrics--recent-activity-planned) |
+| 12 | Backoffice — Monitoring (all but Health) | [§6.16](BACKEND-INTEGRATION.md#616-backoffice--monitoring-planned-except-health) |
+| 13 | Backoffice — Analytics summary (real once orders are real) | [§6.17](BACKEND-INTEGRATION.md#617-backoffice--analytics-mostly-future--no-data-source) |
+| 14 | Builder — Content pages / CMS | [§6.8](BACKEND-INTEGRATION.md#68-builder--content-pages--cms-planned) |
+
+## P3 — nice-to-have, no urgency
+
+| # | Item | Spec section |
+|---|---|---|
+| 15 | Search suggestions / catalog filters | [§6.6](BACKEND-INTEGRATION.md#66-search--autocomplete--trending-planned) |
+| 16 | Cross-device wishlist/compare/saved-searches sync (currently 100% localStorage, works fine without this) | [§6.6](BACKEND-INTEGRATION.md#66-search--autocomplete--trending-planned) |
+| 17 | Analytics traffic/funnels/heatmaps — needs a tracking pipeline that doesn't exist yet, not just an endpoint | [§6.17](BACKEND-INTEGRATION.md#617-backoffice--analytics-mostly-future--no-data-source) |
+| 18 | Sitemap — dynamic generation (static baseline today) | [§6.19](BACKEND-INTEGRATION.md#619-sitemap-future--static-baseline-only-today) |
+
+---
+
+## Explicitly not in this list
+
+- Auth / Telegram session (`GET /bootstrap` transport, `/users/sessions/*`) — covered by
+  backend's `API-CONTRACT.md`, frontend wiring already matches it exactly. Three small
+  gaps remain from that delivery (see prior conversation): `authApiUrl` env value still
+  points at the old host, `telegramBot` username unverified, frontend deploy domain needs
+  confirming against the CORS allow-list. None of those are new backend work — they're
+  config/confirmation follow-ups on what was already delivered.
+- Payments — frozen, unchanged, out of scope per [§2.8](BACKEND-INTEGRATION.md#28-payments-frozen-documented-for-completeness).
+- Storefront reads/writes (categories, items, search, cart, reviews) — already real HTTP,
+  already working, no backend work needed. See [§6.1](BACKEND-INTEGRATION.md#61-storefront-reads-current--frozen-shapes-srcappservicesapiservicets)–[§6.2](BACKEND-INTEGRATION.md#62-storefront-writes-current--frozen-shapes).
+
+## For every item above, when implementing
+
+Read the interface + model file cited in the linked spec section before writing the
+endpoint — the shape is already fixed by the frontend gateway interface, not up for
+renegotiation without a frontend change. When an endpoint is done, the frontend swap is
+a one-file gateway rebind (see [§14](BACKEND-INTEGRATION.md#14-backend-replacement-pattern)) — no page/component changes needed on our side.