sdarbinyan/marketplaces
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ce63931bc2799073c3a1f032a21e2539d8aba7c6
marketplaces/docs/archive/BACKEND_API_REMAINING_WORK.md

93 lines
7.6 KiB
Markdown
Raw Normal View History

docs: assemble BACKEND_INTEGRATION.md, single canonical backend spec 4349 lines, 9 numbered sections per the Backend Finalization Sprint spec: Bootstrap, Endpoint Framework, CRUD Contracts (~102 endpoints across 20 domains), Authentication (spliced from AUTHENTICATION.md), Security, Error Model (spliced from ERROR_CONTRACT.md), Uploads, Real Backend Implementation Guide, Backend Checklist (34 items). Everything traced to docs/context/BACKEND-AUDIT.md and actual current source - proposed (unverified) paths explicitly marked as such, everything the frontend has no opinion on marked "Requires backend decision" rather than invented. Archived the three docs this supersedes (BACKEND_API.md, AUTH.md, BACKEND_API_REMAINING_WORK.md) to docs/archive/ with pointers back to this file. AUTHENTICATION.md, ERROR_CONTRACT.md, MAINTENANCE_MODE.md kept in place as standalone companion references (their content is also inlined/cross-referenced here). ADMIN.md left untouched - it's a frontend admin-UI sprint doc, not a backend spec, no overlap. Verified via repo-wide search: no other backend/API spec docs remain outside archive/ and this canonical file.
2026-07-26 12:17:51 +04:00
> **ARCHIVED 2026-07-26.** Superseded by [`docs/BACKEND_INTEGRATION.md`](../BACKEND_INTEGRATION.md), the single canonical backend integration document. Kept for history only — do not implement against this file.
docs: consolidate documentation and archive temporary reports Step 1-2 (audit + plan): classified 35 project markdown files into Core/Architecture/ADR/Temporary-audit/Sprint-report/Generated-review/ Duplicate/Obsolete/Historical. Agent-tooling files (.agents/skills/**, .superpowers/**, docs/context/**, CLAUDE.md/GEMINI.md/AGENTS.md/ .github/copilot-instructions.md) explicitly out of scope — intentional per-tool duplication, not documentation debt. Step 3 (merge, no information lost): - docs/PROJECT.md -> docs/PROJECT_INDEX.md, rewritten as the single entry point: system overview, living-doc index, archive pointer, current status, and a critical-finding callout up top. - docs/backend/BACKEND-INTEGRATION.md -> docs/BACKEND_API.md, docs/backend/REMAINING-BACKEND-WORK.md -> docs/BACKEND_API_REMAINING_WORK.md (also folded in a legitimate uncommitted status update that had been sitting unstaged all session: categories marked DONE, order-creation endpoint noted done). - RELEASE-NOTES.md merged into CHANGELOG.md (was a near-duplicate of the same release content in friendlier prose), then deleted. - KNOWN-ISSUES.md: added item 13 (see below) and item 14 (missing canDeactivate on admin/products edit, from the archived PROJECT-STATE audit, re-verified still true); added a correction note to Fixed item 7. - All cross-references to renamed/moved files fixed across every kept doc (grep+sed pass, then verified with a link-existence check across all 58 in-scope markdown files -> 0 broken links). Step 4 (archive, nothing deleted without merging first): created docs/archive/, moved 19 files there (3 root sprint reports, 1 platform report, SPRINT-PLAN.md, and 14 one-off audit/review/report docs). Added correction headers to the 3 archived docs whose conclusions were affected by the finding below, rather than silently leaving them misleading. Step 5: docs/PROJECT_INDEX.md rewritten per the mission brief - someone opening the repo should understand the whole system from it. IMPORTANT FINDING (surfaced during this audit, not the mission's primary goal but too significant to bury): pages/category/*, pages/search/*, pages/item-detail/*, pages/info/**, pages/legal/** (40+ files) are entirely unrouted dead code - app.routes.ts's cmsContentRoutes is a literal empty array, and category/search/product routes redirect to CatalogContainerComponent/ ProductDetailsContainerComponent, not these files. Confirmed against app.routes.ts directly and cross-checked against FRONTEND.md's own routing description. This means several fixes from earlier this cycle (RC-Premium-01, RC STORE-01) and the dead-code cleanup sprint's conclusion that these files were live were all wrong - documented as KNOWN-ISSUES.md item 13, flagged at the top of PROJECT_INDEX.md, and noted on the 3 archived docs whose conclusions it affects. No application code was changed to fix this (out of scope per this session's 'documentation only' constraint) - it needs a wire-it-up-or- delete-it decision first. Verification: tsc --noEmit clean, npm run build green, all markdown links across 58 in-scope files resolve (checked programmatically). No application/Angular/backend code modified. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-25 19:10:49 +04:00
# Remaining backend work (everything except auth/session)
Companion to the `API-CONTRACT.md` backend delivered separately (covers `GET /bootstrap`
transport + `/users/sessions/*` — done, see prior conversation). This file lists what's
still outstanding. Full request/response shapes, TypeScript
interfaces, and validation rules for every item below already exist in
[`docs/BACKEND_API.md`](BACKEND_API.md) — this is a prioritized
punch list with links into that spec, not a duplicate of it. **Do not re-document
endpoint shapes here** — edit the master spec if a shape needs to change.
Status legend (same as master spec): **PLANNED** = shape fully specified client-side,
served by a mock gateway today, nothing built server-side yet. **FUTURE** = reserved
contract only, no urgency. Bootstrap's *content* (branding/theme/nav values, not the
`GET /bootstrap` transport itself) is also still outstanding — see P0 below.
---
## Status legend for this list
**DONE** = wired end-to-end on the frontend (real HTTP gateway or real call site, no mock
left in the path). **PLANNED** = shape fully specified client-side, still served by a mock
gateway, nothing wired yet. Everything below that isn't marked DONE is still open.
## P0 — blocks going live at all
| # | Item | Status | Spec section |
|---|---|---|---|
| 1 | `bootstrap.json` real content (branding, theme, navigation, seo) — currently default stubs per backend's own note in API-CONTRACT.md | open | [§4](BACKEND_API.md#4-bootstrap) |
| 2 | Builder — bootstrap draft/publish/validate (`GET/PUT /builder/bootstrap/draft`, `POST /builder/bootstrap/publish`, `POST /builder/bootstrap/validate`) — this is how the Marketplace Builder actually saves anything | open | [§6.7](BACKEND_API.md#67-builder--bootstrap-draftpublishvalidate-planned-highest-priority) |
| 3 | Backoffice — Products CRUD + variants | open | [§6.10](BACKEND_API.md#610-backoffice--products-planned), DTOs [§7.2](BACKEND_API.md#72-products--srcappfeaturesadminproductsmodelsadmin-productmodelts) |
| 4 | Backoffice — Categories CRUD (tree) | **DONE** — `admin-categories-api.gateway.ts` + `admin-categories-gateway.token.ts` wired, swaps on `RuntimeProviderStrategyService` | [§6.9](BACKEND_API.md#69-backoffice--categories-planned), DTOs [§7.1](BACKEND_API.md#71-categories--srcappfeaturesadmincategoriesmodelsadmin-categorymodelts) |
| 5 | Media upload/delete/replace pipeline | open | [§6.18](BACKEND_API.md#618-media-planned--adr-0002), [§10](BACKEND_API.md#10-media) |
## P1 — needed for real order/commerce flow
| # | Item | Status | Spec section |
|---|---|---|---|
| 6 | Backoffice — Orders CRUD + status transitions | open | [§6.11](BACKEND_API.md#611-backoffice--orders-planned), state machine [§8.1](BACKEND_API.md#81-orders--adminorderstatus) |
| 7 | Backoffice — Transactions (list/detail, tied to orders) | open | [§6.12](BACKEND_API.md#612-backoffice--transactions-planned) |
| 8 | Order creation — checkout calls `POST /orders` on payment success | **DONE** — `ApiService.createOrder()` + `CartComponent.recordOrder()`, fire-and-forget alongside `clearCart()`, doesn't touch the frozen payment call chain | [§16.9](BACKEND_API.md#169-order-creation-future--no-order-creation-endpoint-exists-anywhere-yet) |
| 9 | Backoffice — Users/roles/invitations | open | [§6.13](BACKEND_API.md#613-backoffice--users-roles-invitations-planned) |
| 10 | Backoffice — Moderation (review + report status transitions) | open | [§6.14](BACKEND_API.md#614-backoffice--moderation-reviews--reports-planned), state machines [§8.4](BACKEND_API.md#84-reviews--adminreviewstatus)/[§8.5](BACKEND_API.md#85-reports--adminreportstatus) |
## P2 — dashboards / operational visibility
| # | Item | Status | Spec section |
|---|---|---|---|
| 11 | Backoffice — Dashboard metrics & recent activity | open | [§6.15](BACKEND_API.md#615-backoffice--dashboard-metrics--recent-activity-planned) |
| 12 | Backoffice — Monitoring (all but Health) | open | [§6.16](BACKEND_API.md#616-backoffice--monitoring-planned-except-health) |
| 13 | Backoffice — Analytics summary (real once orders are real) | open | [§6.17](BACKEND_API.md#617-backoffice--analytics-mostly-future--no-data-source) |
| 14 | Builder — Content pages / CMS | open | [§6.8](BACKEND_API.md#68-builder--content-pages--cms-planned) |
## P3 — nice-to-have, no urgency
| # | Item | Status | Spec section |
|---|---|---|---|
| 15 | Search suggestions / catalog filters | open | [§6.6](BACKEND_API.md#66-search--autocomplete--trending-planned) |
| 16 | Cross-device wishlist/compare/saved-searches sync — backend confirmed id-only stays, added `GET /items/batch?ids=` for hydration. Frontend needs `UserExperienceRepository` redesign: id-array + local product cache hydrated via the batch endpoint, replacing today's fully-synchronous denormalized-object storage | open (unblocked, not started) | [§6.6](BACKEND_API.md#66-search--autocomplete--trending-planned) |
| 17 | Analytics traffic/funnels/heatmaps — needs a tracking pipeline that doesn't exist yet, not just an endpoint | open | [§6.17](BACKEND_API.md#617-backoffice--analytics-mostly-future--no-data-source) |
| 18 | Sitemap — dynamic generation (static baseline today) | open (server-side, no frontend action) | [§6.19](BACKEND_API.md#619-sitemap-future--static-baseline-only-today) |
---
## Explicitly not in this list
- Auth / Telegram session (`GET /bootstrap` transport, `/users/sessions/*`) — covered by
backend's `API-CONTRACT.md`, frontend wiring matches it exactly.
- `authApiUrl` env value — **fixed**, now points at the same host as `apiUrl`
(`https://api.dexarmarket.ru:445`) in both `environment.ts` and `environment.production.ts`.
- `AdminWebSessionID` header — **fixed a real bug**: the interceptor only attached it to
URLs containing `/admin/`, but every real backend path is `/backoffice/*`, `/builder/*`,
`/media/*` — none of those matched, so every new admin call would have silently gone out
with no admin auth header at all. Broadened the guard in `admin-auth-headers.interceptor.ts`.
- `telegramBot` username — still unverified against `bot.go`'s `startbot()`.
- Frontend deploy domain vs. CORS allow-list — **decided**: frontend and API stay on the
same domain, so this is a non-issue by design rather than something to reconcile against
an allow-list.
- Payments — frozen, unchanged, out of scope per [§2.8](BACKEND_API.md#28-payments-frozen-documented-for-completeness).
- Storefront reads/writes (categories, items, search, cart, reviews) — already real HTTP,
already working, no backend work needed. See [§6.1](BACKEND_API.md#61-storefront-reads-current--frozen-shapes-srcappservicesapiservicets)–[§6.2](BACKEND_API.md#62-storefront-writes-current--frozen-shapes).
## For every open item above, when implementing
Read the interface + model file cited in the linked spec section before writing the
endpoint — the shape is already fixed by the frontend gateway interface, not up for
renegotiation without a frontend change. Follow the pattern now established for Categories
(`admin-categories-api.gateway.ts` + `admin-categories-gateway.token.ts`): one `*ApiGateway`
class implementing the existing `*Gateway` interface, plus one `InjectionToken` factory that
picks mock vs. real off `RuntimeProviderStrategyService`, then switch the facade(s) to inject
the token instead of the concrete mock class. See [§14](BACKEND_API.md#14-backend-replacement-pattern) for the general pattern.
Reference in New Issue Copy Permalink