sdarbinyan/marketplaces
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: consolidate documentation and archive temporary reports

Browse Source 
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>
This commit is contained in:
sdarbinyan
2026-07-25 19:10:49 +04:00
parent 5707755576
commit 5374401257
38 changed files with 281 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/RELEASE_REPORT.md
View File

@@ -1,47 +0,0 @@
# Release Candidate Report
Live browser walkthrough of every route across Storefront, Builder, Backoffice — "pretend this ships tomorrow." No redesign, no route/API changes. Three sequential commits on branch `B2B` (not pushed):
| Commit | Scope |
|---|---|
| `0a1acbd` | Storefront |
| `2cbb62a` | Builder |
| `907ac2c` | Backoffice |
`npm run build` verified green after every commit. `npx tsc --noEmit` clean throughout. Dev server run against the local mock bootstrap + dev-proxy `/api/*` (real seeded data, expected setup — not a bug).
## P0s found and fixed
Two genuine ship-blockers, both app-wide in effect despite being caught during a single-surface walkthrough:
1. **Query-param routing broken on every route (`src/app/guards/language.guard.ts`).** The 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` became `/ru/edit/branding%3FdevBypassAdmin%3Dtrue`, a dead route. This guard runs on every top-level route, so **any bookmarked or shared deep link carrying query params was silently broken app-wide** — not a Builder-only bug, just discovered there. Fixed with `router.parseUrl()`.
2. **Categories CRUD completely broken end-to-end (`admin-categories-gateway.token.ts`).** `RuntimeProviderStrategyService.getBackofficeProviderMode()` has no `isLocalhost()` fallback (unlike `getBootstrapProviderMode()`), so the categories gateway always resolved to the real HTTP `AdminCategoriesApiGateway` instead of the purpose-built local mock — in an environment with no real backend (see `docs/PERFORMANCE_REPORT.md`/`docs/ACCESSIBILITY_REPORT.md` context: backend integration is still PLANNED). Combined with `saveDraft()` having no error handler, every create/publish click **silently failed** — nothing saved, the dirty flag never cleared, and the unsaved-changes guard then blocked navigation with zero feedback to the admin user. Fixed by wiring the token to the already-defined `getCategoryProviderMode()` + adding the same `isLocalhost()` mock fallback. Live-verified: created/edited/reordered categories, all persist correctly now. Production/non-localhost behavior unchanged.
## P1s found and fixed
**Storefront:**
- Cart item description rendered a bare `...` when an item had no description.
- Compare table showed raw internal stock enum values (`high`/`low`) instead of localized labels.
- Zero-result search stacked confusing "browse categories" empty-category messaging on top of the search's own "nothing found" message.
- Footer "About" link 404'd (`/about` vs actual route `/about-us`) — fixed in mock bootstrap.
- Missing fallback placeholder image for items with no photo — added `public/assets/images/placeholder.svg`.
**Builder:**
- `resetDraft()` discarded the draft but never resynced `lastSavedBootstrap`, so the save bar immediately showed "unsaved changes" right after a full reset.
**Backoffice:**
- Categories list mislabeled its Edit button "Edit product" (wrong i18n key — `adminProducts.edit` instead of the already-correct `adminCategories.edit`). Not part of the tracked ~178-key i18n gap, since the right key already existed.
## Flagged, not fixed (need a decision, not a code fix)
- **Storefront**: Footer "Contacts" link has no static-page content in mock data at all (unlike About, which was just a route-name mismatch) — needs a content decision. `/images/*.webp` 404s on product cards are numeric-ID paths meant to resolve against a real backend/CDN not present in local dev — expected dev-only gap, not a bug. Russian pluralization ("1 товаров" vs "1 товар") — cosmetic, out of scope.
- **Builder**: the static page editor's actual body-content WYSIWYG editor lives inside a collapsed `<details>` under "Advanced", mislabeled "Source HTML (advanced)" though it's the only way to edit page content — works correctly once found, relocating/relabeling it is a navigation/design decision for product sign-off.
## Verification
Live browser walkthrough performed in all three passes (not static-only) — every route above was actually navigated, forms actually submitted, CRUD actually exercised (categories create/edit/delete/reorder, cart add/remove, compare/wishlist add), both desktop and mobile viewports checked, console + network inspected after each navigation. `tsc --noEmit` and `npm run build` green after each commit.
## Cross-reference
This pass sits on top of four prior audits this cycle: `docs/UI-COMPOSITION-REVIEW.md` (composition), `docs/STORE_FRONT_UX_REVIEW.md` / `docs/STORE_REVIEW.md` (storefront polish), `docs/PERFORMANCE_REPORT.md` (bundle/reactivity), `docs/ACCESSIBILITY_REPORT.md` (WCAG 2.1 AA). Known, already-tracked gaps not re-reported here: ~178 missing `adminXxx.*` i18n keys, Theme Mode has no runtime effect, `dynamic-renderer/` unwired, `primeng` still in `package.json` pending an unrelated lockfile blocker — all in `docs/KNOWN-ISSUES.md`.