diff --git a/BACKEND-API-REFERENCE.md b/BACKEND-API-REFERENCE.md index bd71f72..9a74ccf 100644 --- a/BACKEND-API-REFERENCE.md +++ b/BACKEND-API-REFERENCE.md @@ -371,7 +371,7 @@ WebSessionID: 3f1c2a0e-… { "qrId": "QR-77f0", "nspkurl": "https://qr.nspk.ru/AD10…", "status": "created", "qrExpirationDate": "2026-07-26T04:10:00Z" } ``` -**Payments are frozen** — this call chain is explicitly out of scope for changes; document only, don't modify. +**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. --- diff --git a/docs/PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md b/docs/PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md index 8ea89c2..4a9000b 100644 --- a/docs/PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md +++ b/docs/PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md @@ -37,17 +37,17 @@ Nothing downstream can be honestly estimated until this closes. Two sprints: one ### Sprint 0.1 — Decisions `[DEC]` -Blocking. Escalate as a single list, not one at a time. +**Answered 2026-08-17.** Kept as a record — the reasoning behind each answer still governs how later phases get built. -- [ ] **Backend ownership.** Platform API, Workers, Integration Hub, Domain Automation — our team or a service team? Everything `[BE]` below is unassigned until answered. -- [ ] **Unfreeze the payment chain.** `BACKEND-API-REFERENCE.md §7` marks it do-not-modify. Phases 1, 6 and 7 are unbuildable otherwise. -- [ ] **Name the external marketplaces** for §5 connectors (Ozon / Wildberries / Yandex Market / Avito / other). Each is a separate connector; Phase 4 cannot be sized without the list. -- [ ] **FX rate source** — which provider, and does the backend return converted prices or serve rates? Plan §2.3 implies backend-converted. -- [ ] **§14 vs. approved email/phone OTP spec** — VK ID first, or finish OTP first? -- [ ] **Multi-seller orders: unified or split?** Open in three of our own documents. Blocks Phase 3 and Phase 5 data model. -- [ ] **Reproduce or retract the "fixed 5-second payment" claim (§3.2).** Not present in this codebase. -- [ ] **API namespace migration (§9.3)** — migrate before new endpoints, or accept two conventions? Cost rises every phase this is deferred. -- [ ] **Document version** — file says v3.1, version block says 3.0. Which is canonical? +- [x] **Backend ownership.** *Still open — user flagged the question itself as unclear on first pass; re-ask in plain terms before Phase 1 implementation starts (not just contract-writing).* Nothing downstream is blocked by this being open — the Phase 1 backend contract doc exists regardless of who builds against it. +- [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 once backend ownership is confirmed. +- [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. @@ -154,7 +154,7 @@ Biggest structural change in the whole programme. Everything about multi-seller - [ ] `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** — blocked on the unified-vs-split decision in Sprint 0.1. +- [ ] 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. @@ -162,7 +162,7 @@ Biggest structural change in the whole programme. Everything about multi-seller ## Phase 4 — External order ingestion (P0-C) -Zero percent built today. Sized per connector; Sprint 4.2 repeats for each marketplace named in Sprint 0.1. +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]` @@ -175,10 +175,11 @@ Zero percent built today. Sized per connector; Sprint 4.2 repeats for each marke - [ ] 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 — Per-connector implementation `[BE]` — ×N +### Sprint 4.2 — Connector onboarding runbook `[BE]` — repeats per new partner, no longer named up front -- [ ] One sprint per named marketplace: auth, endpoint mapping, rate limits, sandbox verification. **L each** +- [ ] 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]` @@ -224,7 +225,7 @@ A placeholder page with a `false` flag and zero backend bytes today. Note: the e ### 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. **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** @@ -280,7 +281,7 @@ Partly pulled forward into Sprint 1.3 (server-authoritative amount). This phase ## Phase 8 — Identity & messaging (§2.9, §3.4, §14) -Order inside this phase depends on the Sprint 0.1 decision (VK ID first vs. OTP first). +**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** @@ -289,16 +290,16 @@ Order inside this phase depends on the Sprint 0.1 decision (VK ID first vs. OTP - [ ] Backoffice **Customers** on real data: profiles, verified contacts, orders, consent. **M** - [ ] Sensitive profile changes logged. **S** -### Sprint 8.2 — Email/phone OTP `[BOTH]` -- [ ] 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.3 — VK ID `[BOTH]` — new in v3.1 +### 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** @@ -436,7 +437,7 @@ Not in the plan, but real. Fold into whichever phase touches the same surface. - [ ] **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 — at least three independently restate the same undecided unified-vs-split orders question. Do this **before** Phase 5 starts. **M** +- [ ] **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** --- diff --git a/docs/PRODUCT-PLAN-v3.1-GAP-ANALYSIS.md b/docs/PRODUCT-PLAN-v3.1-GAP-ANALYSIS.md index 56a79fd..b2f1821 100644 --- a/docs/PRODUCT-PLAN-v3.1-GAP-ANALYSIS.md +++ b/docs/PRODUCT-PLAN-v3.1-GAP-ANALYSIS.md @@ -251,17 +251,19 @@ Not gaps — assets and risks they should know about before sequencing: --- -## 6. Decisions we need from them before estimating +## 6. Decisions — answered 2026-08-17 -1. **Who owns the backend?** The plan assumes Platform API, Workers, Integration Hub and Domain Automation exist or will be built. None do. Same team, or a service team we integrate with? -2. **Is the payment chain unfrozen?** P0-A/P0-C are unbuildable otherwise. -3. **Which external marketplaces**, by name, for §5 connectors? -4. **Which FX rate source?** The plan says "configurable external source"; our earlier ask named Rapira as a candidate. Also: does the backend return converted prices, or serve rates for the client to apply? The plan implies the former. -5. **§14 vs. our approved email/phone OTP spec** — build VK ID first, or finish OTP first? -6. **Multi-seller orders: unified or split?** Undecided in three of our own documents; the plan requires cart-level seller grouping (§2.5) but never resolves the order-splitting question. -7. **Where does the "fixed 5-second payment" (§3.2) come from?** We cannot reproduce it in this codebase. -8. **API namespace migration (§9.3)** — do it now, before new endpoints, or accept two conventions? -9. **Document version** — the file is v3.1 but the version block says 3.0. Which is canonical for change tracking? +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 — still open.** First-pass question wasn't understood; needs re-asking in plain terms before Phase 1 implementation (not just contract-writing) starts. +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. --- diff --git a/docs/backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md b/docs/backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md index 85e384b..02c87c9 100644 --- a/docs/backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md +++ b/docs/backend/PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md @@ -2,7 +2,7 @@ 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: blocked.** [BACKEND-API-REFERENCE.md §7](../../BACKEND-API-REFERENCE.md) marks the cart/payment call chain "frozen — explicitly out of scope for changes." This document specifies the target contract so backend work can start the moment that freeze lifts or is scoped around; it does not imply the freeze has been lifted. See open decision in the delivery plan's Sprint 0.1. +**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 once backend ownership (also Sprint 0.1, still open) is confirmed. 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. @@ -221,8 +221,9 @@ A retried call with the same `checkoutSessionId` must return the existing order, --- -## 9. Open questions (mirrors delivery-plan Sprint 0.1) +## 9. Resolved / open questions (Sprint 0.1, 2026-08-17) -1. Payment chain freeze — must be lifted or explicitly scoped around before §5 can ship. -2. FX rate source/provider — not named yet; `source` field above is provider-agnostic pending that answer. -3. Does the backend return already-converted prices, or does the frontend request a specific display currency at checkout time (as modeled in §5.2)? This doc assumes the latter; confirm before implementation. +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 — still open.** This contract is ready regardless of who builds against it, but implementation can't be scheduled until this is answered.