From e4c1c6e2a04bc428c6c3d8e8e93a8636da4042e6 Mon Sep 17 00:00:00 2001 From: sdarbinyan Date: Fri, 24 Jul 2026 10:51:05 +0400 Subject: [PATCH] docs: sync documentation after perf/a11y/release-candidate work MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - PROJECT.md: Current Status updated (perf/a11y/RC walkthrough all done, new report docs added to index). - FRONTEND-ROADMAP.md: RC PERF-01, RC A11Y-01, and Release Candidate walkthrough entries added; known-open-items list updated (2 new flags from RC walkthrough, primeng removal blocker, large chunks, backend-ready sprint explicitly deferred pending a real API contract). - KNOWN-ISSUES.md: corrected item 6 (payment modal focus-trap assumption was wrong, now actually fixed); added items 9-12 (brand contrast failures, Contacts content gap, WYSIWYG editor mislabeled, primeng removal blocker); added 2 Fixed entries for this cycle's P0s (query-param routing, Categories CRUD). - Graphify graph regenerated (graphify-out/, cache only, not tracked). - Obsidian: skipped, no running Obsidian instance in this session. - No architecture change this cycle (perf/a11y/bug fixes only) — no new ADR. - No application code touched. Co-Authored-By: Claude Sonnet 5 --- docs/FRONTEND-ROADMAP.md | 19 ++++++++++-- docs/KNOWN-ISSUES.md | 63 ++++++++++++++++++++++++++++++++++++++-- docs/PROJECT.md | 37 +++++++++++++++++++---- 3 files changed, 108 insertions(+), 11 deletions(-) diff --git a/docs/FRONTEND-ROADMAP.md b/docs/FRONTEND-ROADMAP.md index ae1691d..03a56d8 100644 --- a/docs/FRONTEND-ROADMAP.md +++ b/docs/FRONTEND-ROADMAP.md @@ -10,9 +10,18 @@ Fixed undefined CSS theme vars, hand-rolled skeletons/empty-states migrated to s **RC-Premium-01 — Storefront premium UX polish** Visual/interaction polish on top of the RC-Visual-02 baseline — no redesign, no logic/route changes. Fixed color-only state signaling app-wide (added `aria-pressed`/`aria-current`/`aria-live` + icon/checkmark pairing to selected swatches, active filters/tabs/sort, toggle buttons), normalized remaining hardcoded hex to design tokens, added hover/focus-visible/active/disabled states across interactive controls, capped legal/CMS prose at 70ch, converted FAQ to native `
` disclosures. Four commits (Home/Catalog/Search, Product/Compare/Wishlist, Cart/Checkout, Static Pages). Detail: `docs/STORE_FRONT_UX_REVIEW.md`. -**RC STORE-01 — Storefront cleanup** (this session) +**RC STORE-01 — Storefront cleanup** Closed 2 of the 5 gaps RC-Premium-01 deliberately deferred: category/search skeleton markup migrated to shared `app-skeleton`, dead cart `.email-form` markup/CSS removed. The other 3 (payment modal, cart confirm() dialog, untokenized colors) need an architecture/design-system decision, correctly left alone again. Detail: `docs/STORE_REVIEW.md`. +**RC PERF-01 — Performance audit** (production-readiness, app-wide) +Initial bundle **1.47 MB → 1.12 MB raw (−24%)**: biggest win was lazy-loading en/hy i18n packs (346 KB were eagerly loaded regardless of visitor language), plus a dead `items-carousel`/primeng-only component deleted, dead global CSS removed. RxJS/change-detection audit found the codebase already clean (0 leaks, 190/191 components already OnPush). Detail: `docs/PERFORMANCE_REPORT.md`. + +**RC A11Y-01 — WCAG 2.1 AA audit** (storefront, builder, backoffice) +Added the app's first skip link (didn't exist anywhere before), fixed cart's custom payment modals having zero focus-trap, fixed `app-icon`'s "decorative by default" claim never actually being implemented, fixed 2 keyboard-inaccessible drag-and-drop reorder UIs (Builder homepage/footer, Backoffice categories), fixed an undefined `--color-primary` token in Builder, fixed admin sidebar nav announcing itself as "Dashboard" everywhere. Contrast fixes applied where safe; genuine brand-color contrast failures flagged for theme-owner sign-off, not changed unilaterally. Detail: `docs/ACCESSIBILITY_REPORT.md`. + +**Release Candidate — live browser walkthrough** (storefront, builder, backoffice) +Found and fixed **2 P0s**: (1) `language.guard.ts`'s legacy-URL redirect broke query params on every route app-wide (silently dead-ended any bookmarked/shared deep link with query params); (2) Backoffice Categories CRUD was completely broken end-to-end — wrong gateway-resolution fallback always picked the real HTTP gateway instead of the local mock in this environment, so every create/publish silently failed with zero user feedback. Plus 6 P1s (cart description, compare table raw enum values, search empty-state messaging, footer link 404, missing placeholder image, builder save-bar reset-state bug, backoffice mislabeled button). Detail: `docs/RELEASE_REPORT.md`. + ## Sprint status **Sprint 30 — Final Release**: verify pass re-run 2026-07-23 (tsc --noEmit, `npm run build`, `arch:check:boundaries`, `arch:check:cycles`) — all green, only pre-existing bundle-budget warning. Working tree otherwise clean. Only remaining item: `git push` of 10 local `B2B` commits to `origin/B2B` — awaiting explicit user go-ahead (declined once already this sprint, per safety rules re-ask each time). Full checklist: `docs/SPRINT-PLAN.md`. @@ -20,13 +29,19 @@ Closed 2 of the 5 gaps RC-Premium-01 deliberately deferred: category/search skel ## Known open items (not yet scheduled) Full detail in `docs/KNOWN-ISSUES.md`. Summary: -- Payment modal / bank-payment iframe on Cart still custom (own focus-trap, multi-step state) — candidate for `app-dialog` migration. +- Payment modal / bank-payment iframe on Cart still custom (own focus-trap, multi-step state — note: RC A11Y-01 added a real focus-trap to it, but it's still not `app-dialog` itself) — candidate for `app-dialog` migration. - Cart's native `confirm()` on clear-cart — no existing confirm-dialog pattern to follow yet. +- Genuine brand-color contrast failures (`--border-color`, `--success/warning/error/info-color` as text) — flagged by RC A11Y-01, need theme-owner sign-off before changing. - `stars.component` rating glyph color and a few legacy hex literals in `pages/category`/`pages/search` have no exact token match — needs a deliberate token-extension decision. - Homepage hero-to-categories dead-space gap — traces to mock bootstrap config, not a code defect; needs real-tenant-data reproduction. +- Footer "Contacts" link has no static-page content in mock data — needs a content decision (found during RC walkthrough). +- Builder's static-page body editor is hidden inside a collapsed "Advanced" section, mislabeled "Source HTML (advanced)" — works, but needs a navigation/labeling decision (found during RC walkthrough). - ~178 missing `adminXxx.*` i18n keys across admin backoffice. - Theme Mode (dark/system) selector has no runtime CSS effect — real feature project, not a wiring fix. - `dynamic-renderer/` pipeline exists but is unwired — needs a finish-or-delete decision. +- `primeng`/`primeicons` still in `package.json` despite the only consumer being deleted (RC PERF-01) — `npm uninstall` blocked by an unrelated broken `barry-cache` devDependency (`ETARGET`); fix that first. +- 2 large lazy chunks (`project-editor` 320 kB, `catalog-container` 126 kB) — no mechanical split found, needs a dedicated task. +- Backend integration: still mostly PLANNED/mock — a "backend ready" sprint was attempted and explicitly deferred (2026-07-24) pending a real API contract (no `docs/BACKEND-API.md`, no live endpoint confirmation beyond what's already CURRENT). ## Not audited / out of scope diff --git a/docs/KNOWN-ISSUES.md b/docs/KNOWN-ISSUES.md index 4e29e56..415d96e 100644 --- a/docs/KNOWN-ISSUES.md +++ b/docs/KNOWN-ISSUES.md @@ -77,9 +77,13 @@ don't fix inline unless asked. - Found: 2026-07-17, project-editor bug-hunt audit. 6. **Payment modal / bank-payment iframe on Cart still custom, not `app-dialog`.** - Has its own multi-step state and focus-trap already — migrating to the - shared dialog primitive is a composition change, deliberately left out of - RC-Premium-01's visual-polish scope. + Correction (2026-07-24, RC A11Y-01): the "already has focus-trap" assumption + below was wrong — it had none. RC A11Y-01 ported `app-dialog`'s confirmed- + correct focus-trap/Escape/return-focus pattern directly onto it + (`docs/ACCESSIBILITY_REPORT.md`), so the accessibility gap is closed. It's + still a separate custom component, not the shared `app-dialog` itself — + migrating it to the actual primitive remains a composition change, + deliberately left out of every polish pass so far. - Found: 2026-07-23, RC-Premium-01 (`docs/STORE_FRONT_UX_REVIEW.md`). 7. **Cart's `clearCart()` uses native `confirm()`, no styled confirm dialog.** @@ -93,6 +97,34 @@ don't fix inline unless asked. token-extension decision before normalizing. - Found: 2026-07-23, RC-Premium-01. +9. **Genuine brand-color contrast failures (WCAG AA).** `--border-color` + fails 3:1 UI-component contrast in every theme (1.24-1.42:1 measured); + `--success/--warning/--error/--info-color` fail 4.5:1 when used as plain + text-on-white in a handful of places. Real palette colors, not a token + bug — fixing means visibly changing the brand, needs theme-owner sign-off. + - Found: 2026-07-24, RC A11Y-01 (`docs/ACCESSIBILITY_REPORT.md`). + +10. **Footer "Contacts" link has no static-page content in mock data.** + Unlike the "About" link (which was a route-name mismatch, fixed), no + content exists for Contacts at all — needs a content decision, not a + code fix. + - Found: 2026-07-24, Release Candidate walkthrough (`docs/RELEASE_REPORT.md`). + +11. **Builder's static-page body editor is hidden and mislabeled.** The + actual WYSIWYG content editor isn't on the "Content" tab (title/image + only) — it's inside a collapsed `
` under "Advanced", labeled + "Source HTML (advanced)" though it's the only way to edit page content. + Works correctly once found; relocating/relabeling is a navigation + decision, not a bug fix. + - Found: 2026-07-24, Release Candidate walkthrough. + +12. **`primeng`/`primeicons` still in `package.json` after their only + consumer was deleted.** `npm uninstall` fails (`ETARGET`) on a + pre-existing, unrelated broken `barry-cache` devDependency resolution — + fix that first, then drop the now-fully-unused dependency (likely closes + most of the remaining bundle-budget overage in one move). + - Found: 2026-07-24, RC PERF-01 (`docs/PERFORMANCE_REPORT.md`). + ## Fixed 1. **Full-project UX/UI + motion pass across storefront, admin dashboard, @@ -255,6 +287,31 @@ don't fix inline unless asked. ~90-line dead CSS block still shipping in the bundle. - Fixed: 2026-07-23, RC STORE-01. +9. **App-wide query-param routing broken (P0).** `language.guard.ts`'s + legacy-URL redirect built the target with `router.createUrlTree([...])` + using a single path-segment string with the query string baked in, so it + got percent-encoded into the path instead of parsed as query params + (`/edit/branding?devBypassAdmin=true` → `/ru/edit/branding%3FdevBypassAdmin%3Dtrue`, + a dead route). This guard runs on every top-level route app-wide, so any + bookmarked/shared deep link with query params was silently broken — + found during the Builder RC walkthrough but affects all 3 surfaces. + - Fixed: 2026-07-24, Release Candidate walkthrough (`docs/RELEASE_REPORT.md`), + `router.parseUrl()` instead of a hand-built path segment. + +10. **Backoffice Categories CRUD completely broken end-to-end (P0).** + `admin-categories-gateway.token.ts` resolved via + `RuntimeProviderStrategyService.getBackofficeProviderMode()`, which — + unlike `getBootstrapProviderMode()` — has no `isLocalhost()` fallback, + so it always picked the real HTTP `AdminCategoriesApiGateway` instead of + the local mock in an environment with no real backend. Combined with + `saveDraft()` having no error handler: every create/publish click + silently failed, `dirty` never cleared, and the unsaved-changes guard + then blocked navigation with zero feedback. + - Fixed: 2026-07-24, Release Candidate walkthrough, wired to the + already-defined `getCategoryProviderMode()` + added the same + `isLocalhost()` fallback `getBootstrapProviderMode()` already had. + Live-verified: create/edit/reorder all persist correctly now. + ## Notes (not bugs, just flag before shipping) - `src/environments/environment.ts`: `useMockData` was temporarily flipped to diff --git a/docs/PROJECT.md b/docs/PROJECT.md index b4db58c..117bc95 100644 --- a/docs/PROJECT.md +++ b/docs/PROJECT.md @@ -1,4 +1,14 @@ -# PROJECT +# Marketplace Platform + +## Read First + +- **DESIGN.md** — does not exist under this name; closest equivalent is [ARCHITECTURE.md](ARCHITECTURE.md) (system design) + `docs/architecture/foundation/**` (enforced standards/ADRs). +- **BACKEND-API.md** — does not exist under this name; canonical spec is [backend/BACKEND-INTEGRATION.md](backend/BACKEND-INTEGRATION.md). +- **[ADMIN.md](ADMIN.md)** +- **[EDITOR.md](EDITOR.md)** +- **[KNOWN-ISSUES.md](KNOWN-ISSUES.md)** +- **[FRONTEND-ROADMAP.md](FRONTEND-ROADMAP.md)** +- **ADR/** — `docs/architecture/foundation/adr/` (ADR-001…ADR-010) and `docs/context/adrs/`. ## What this is @@ -26,6 +36,11 @@ Every tenant conceptually has three surfaces on this one codebase: - **[StaticPages.md](StaticPages.md)** — the Static Pages module: full field reference, per-page draft/publish gating, CRUD/search/filter/bulk, rich text, device preview, nav integration (Sprint X+2). - **[PROJECT-STRUCTURE.md](PROJECT-STRUCTURE.md)** — folder-by-folder tour of `src/app/**` with a worked "add a new feature" example (admin dashboard). - **[ADMIN.md](ADMIN.md)** — Sprint 19 admin dashboard: routing, architecture, data sources, known gaps. +- **[FRONTEND-ROADMAP.md](FRONTEND-ROADMAP.md)** — status snapshot refreshed from recent commits; sprint progress, known open items. +- **[KNOWN-ISSUES.md](KNOWN-ISSUES.md)** — running list of open/fixed bugs found during manual verification. +- **[PERFORMANCE_REPORT.md](PERFORMANCE_REPORT.md)** — RC PERF-01: bundle/reactivity/asset audit and fixes. +- **[ACCESSIBILITY_REPORT.md](ACCESSIBILITY_REPORT.md)** — RC A11Y-01: WCAG 2.1 AA audit and fixes across all 3 surfaces. +- **[RELEASE_REPORT.md](RELEASE_REPORT.md)** — live browser release-candidate walkthrough, P0/P1 findings and fixes. - `docs/architecture/foundation/**` — the enforced ADRs (ADR-001…ADR-010) and standards docs (Coding-Standards, Naming-Conventions, Dependency-Rules, Folder-Blueprint, Import-Boundary-Matrix, State-Management-Standards, Configuration-Standards, Component-Standards, Service-Standards). These are governance, not narrative — read them directly; `ARCHITECTURE.md` only links to them. - `docs/context/**` — Barry Cache's own source-backed memory system. Infrastructure, not project documentation; do not edit by hand. @@ -52,9 +67,19 @@ npm run barry -- validate See root `CLAUDE.md` for the full Barry Cache workflow and memory policy. -## Current status (this sprint) +## Current Status -- **Sprint 19** shipped the production Admin Dashboard (`src/app/features/admin/dashboard/`) as the default `/​:lang/backoffice` landing page, wired the previously-unrouted `admin/products` feature into routing, and added `lastPublishedAt` tracking to `ProjectEditorFacade`. See `docs/ADMIN.md`. -- **Sprint 18** added Project Editor autosave (localStorage draft), section/draft reset, admin QR-login reuse (shared Telegram session API/component, separate cookie/guard), and Ed25519 verification scaffolding (no crypto implemented yet — fails closed). See `docs/EDITOR.md`. -- Draft/publish for the Project Editor is still **frontend-only** (localStorage), with no backend persistence. This is the single largest backend gap — see `docs/backend/BACKEND-INTEGRATION.md#67-builder--bootstrap-draftpublishvalidate-planned-highest-priority`. -- This documentation set (`docs/PROJECT.md`, `ARCHITECTURE.md`, `backend/BACKEND-INTEGRATION.md`, `FRONTEND.md`, `EDITOR.md`, `PROJECT-STRUCTURE.md`) replaces ~35 previously scattered files under `docs/platform/`, `docs/backend-platform/`, and various one-off sprint reports, which have been consolidated and removed. +- **Frontend: 96%** +- **Backend:** in progress — still mostly PLANNED/mock gateways, no confirmed live backend contract (see `docs/backend/BACKEND-INTEGRATION.md`) +- **Storefront polish:** done (RC-Visual-02, RC-Premium-01, RC STORE-01) +- **Performance audit:** done — see [PERFORMANCE_REPORT.md](PERFORMANCE_REPORT.md) (initial bundle −24%) +- **Angular v22:** pending +- **Accessibility audit:** done — see [ACCESSIBILITY_REPORT.md](ACCESSIBILITY_REPORT.md) (WCAG 2.1 AA, storefront/builder/backoffice) +- **Release-candidate walkthrough:** done — see [RELEASE_REPORT.md](RELEASE_REPORT.md) (2 P0s + 6 P1s found and fixed via live browser walkthrough) +- **First client demo:** upcoming + +Detail behind each line: sprint-by-sprint history in [FRONTEND-ROADMAP.md](FRONTEND-ROADMAP.md) / `docs/SPRINT-PLAN.md` (Sprints 20-30, all shipped except Sprint 30's `git push`, pending explicit go-ahead), open defects in [KNOWN-ISSUES.md](KNOWN-ISSUES.md), backend gap list in `docs/backend/BACKEND-INTEGRATION.md` and `docs/backend/REMAINING-BACKEND-WORK.md`. + +Draft/publish for the Project Editor is still **frontend-only** (localStorage), with no backend persistence — the single largest backend gap, see `docs/backend/BACKEND-INTEGRATION.md#67-builder--bootstrap-draftpublishvalidate-planned-highest-priority`. + +This documentation set (`docs/PROJECT.md`, `ARCHITECTURE.md`, `backend/BACKEND-INTEGRATION.md`, `FRONTEND.md`, `EDITOR.md`, `PROJECT-STRUCTURE.md`) replaces ~35 previously scattered files under `docs/platform/`, `docs/backend-platform/`, and various one-off sprint reports, which have been consolidated and removed.