merge: B2B into main

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

BACKEND-API-REFERENCE.md

@@ -539,7 +539,15 @@ Either way, the *authoritative* amount charged (`createCartPayment`'s `amount`,
 
 **Ask:** nothing new beyond what §10/§11 already ask for — once a real `AdminOrdersApiGateway` is bound, this feature starts working with no additional frontend change. Flagging here only so nobody spends time debugging "why doesn't the notification ever fire" against the mock.
 
-### 12.9 Trending search terms
+### 12.9 Admin product view counts
+
+**Gap:** Admin Products (§8) runs on a fully separate mock domain from the storefront's live catalog — `AdminProduct.visits` is a new field added to support a "Views" column in Admin Products, but the mock gateway always defaults it to `0` because there is no real tracking source available to the admin domain today. This is unrelated to the storefront's `Item.visits` field (§6, `/items/{id}`), which is live-wired but never displayed anywhere in the UI.
+
+**Ask:** two options, not mutually exclusive:
+1. Once admin Products gets a real backend (§10 step 4), include a per-product view/visit count in the response.
+2. Bridge `AdminProduct.visits` to the storefront's already-live `Item.visits` by product id, if a unified product identity exists between the storefront and admin domains — smaller change than building new tracking infrastructure.
+
+### 12.10 Trending search terms
 
 **Gap:** `SearchTrendingService.loadTrending()` is a stub returning `of(null)` - no trending-searches endpoint exists. It already degrades gracefully (UI hides the trending section rather than showing an error), so this is purely a missing-feature gap, not a bug.
 

docs/superpowers/plans/2026-08-15-admin-product-views-column.md

@@ -0,0 +1,225 @@
+# Admin Product Views Column Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Show a real (currently-zero) per-product view count as a toggleable column in Admin Products list, and document the backend gap that keeps it at zero today.
+
+**Architecture:** Add `visits: number` to the `AdminProduct` model, default it to `0` everywhere the mock gateway constructs an `AdminProduct`, add `'visits'` to the existing toggleable-column system (`ALL_PRODUCT_COLUMNS`), render it in the table view using the established `isColumnVisible()` pattern.
+
+**Tech Stack:** Angular signals, existing `LocalStorageService`-backed column-visibility persistence (already built, not touched).
+
+## Global Constraints
+
+- Never fabricate view numbers — the mock gateway has no real tracking source, so `visits` must default to `0`, not a random/seeded number.
+- Table view only — no grid-view or product-detail-page display (out of scope per design doc).
+- Follow the existing `isColumnVisible('stock')`-style pattern exactly — no new column-visibility mechanism.
+
+---
+
+### Task 1: `visits` field, column, and backend doc ask
+
+**Files:**
+- Modify: `src/app/features/admin/products/models/admin-product.model.ts:81-121` (add field)
+- Modify: `src/app/features/admin/products/services/admin-products-local.gateway.ts:82-94,133-166` (default the field)
+- Modify: `src/app/features/admin/products/facade/admin-products.facade.ts:39` (add to column list)
+- Modify: `src/app/features/admin/products/components/admin-products-list.component.html:96-112` (render column + header)
+- Modify: `src/app/i18n/en.ts:1647,1670`, `src/app/i18n/ru.ts:1642`, `src/app/i18n/hy.ts:1642`, `src/app/i18n/translations.ts:1655` (i18n keys)
+- Modify: `BACKEND-API-REFERENCE.md` (new §12.10 ask)
+- Test: `src/app/features/admin/products/services/admin-products-local.gateway.spec.ts` (new)
+
+**Interfaces:**
+- Produces: `AdminProduct.visits: number`
+- Produces: `ALL_PRODUCT_COLUMNS` includes `'visits'` (so `AdminProductColumn` union includes `'visits'`)
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/app/features/admin/products/services/admin-products-local.gateway.spec.ts`:
+
+```typescript
+import { TestBed } from '@angular/core/testing';
+import { provideHttpClient } from '@angular/common/http';
+import { provideHttpClientTesting } from '@angular/common/http/testing';
+import { AdminProductsLocalGateway } from './admin-products-local.gateway';
+
+describe('AdminProductsLocalGateway visits field', () => {
+  let gateway: AdminProductsLocalGateway;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [provideHttpClient(), provideHttpClientTesting()],
+    });
+    gateway = TestBed.inject(AdminProductsLocalGateway);
+  });
+
+  it('defaults visits to 0 on every loaded product', (done) => {
+    gateway.loadProducts({ search: '', categoryId: 'all', visibility: 'all', stockStatus: 'all', page: 1, pageSize: 50 }).subscribe(result => {
+      expect(result.items.length).toBeGreaterThan(0);
+      expect(result.items.every(product => product.visits === 0)).toBe(true);
+      done();
+    });
+  });
+
+  it('resets visits to 0 on a duplicated product, even if the source had a nonzero count', (done) => {
+    gateway.loadProducts({ search: '', categoryId: 'all', visibility: 'all', stockStatus: 'all', page: 1, pageSize: 50 }).subscribe(result => {
+      const source = result.items[0];
+      gateway.duplicateProduct(source.id).subscribe(duplicated => {
+        expect(duplicated).not.toBeNull();
+        expect(duplicated!.visits).toBe(0);
+        done();
+      });
+    });
+  });
+});
+```
+
+Note: read `src/app/features/admin/products/models/admin-product.model.ts` for the exact `AdminProductListFilters` shape before writing the test's filter object — if the field names above (`categoryId`, `visibility`, `stockStatus`, `page`, `pageSize`) don't match exactly, use the real ones; don't guess.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npm run test -- --include='**/admin-products-local.gateway.spec.ts'`
+Expected: FAIL — `Property 'visits' does not exist on type 'AdminProduct'` (TS compile error surfaces as a Karma failure).
+
+- [ ] **Step 3: Add the field to the model**
+
+In `src/app/features/admin/products/models/admin-product.model.ts`, add to the `AdminProduct` interface (next to `quantity: number;`):
+
+```typescript
+  quantity: number;
+  visits: number;
+```
+
+- [ ] **Step 4: Default it in the mock gateway**
+
+In `src/app/features/admin/products/services/admin-products-local.gateway.ts`, in `toAdminProduct()` (around line 155, next to the `quantity` line):
+
+```typescript
+      quantity: product.stockStatus === 'out_of_stock' ? 0 : product.stockStatus === 'low_stock' ? 3 : 25,
+      visits: 0,
+```
+
+In `duplicateProduct()` (around line 82-91), add `visits: 0` to the override object so a duplicate never inherits the source's count via the `...source` spread:
+
+```typescript
+    const duplicated: AdminProduct = {
+      ...source,
+      archived: false,
+      id: `${source.id}-copy-${Date.now()}`,
+      sku: `${source.sku}-COPY`,
+      slug: `${source.slug}-copy-${Date.now()}`,
+      name: `${source.name} Copy`,
+      visits: 0,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `npm run test -- --include='**/admin-products-local.gateway.spec.ts'`
+Expected: PASS (2/2)
+
+- [ ] **Step 6: Add the column**
+
+In `src/app/features/admin/products/facade/admin-products.facade.ts:39`, change:
+
+```typescript
+export const ALL_PRODUCT_COLUMNS = ['sku', 'brand', 'price', 'stock', 'visibility', 'updated'] as const;
+```
+
+to:
+
+```typescript
+export const ALL_PRODUCT_COLUMNS = ['sku', 'brand', 'price', 'stock', 'visibility', 'updated', 'visits'] as const;
+```
+
+In `src/app/features/admin/products/components/admin-products-list.component.html`, add a header cell after the `visibility` header (around line 100):
+
+```html
+          @if (isColumnVisible('visibility')) { <th scope="col">{{ 'adminProducts.visibility' | translate }}</th> }
+          @if (isColumnVisible('visits')) { <th scope="col">{{ 'adminProducts.views' | translate }}</th> }
+```
+
+And a matching body cell after the `visibility` cell (around line 126, right after its closing `}`):
+
+```html
+            @if (isColumnVisible('visits')) { <td>{{ product.visits }}</td> }
+```
+
+The column-picker panel (`admin-products-list.component.html:50-59`) needs no template change — it already iterates `allColumns` generically and looks up `adminProducts.column_<name>`, so it auto-picks up `'visits'` once the i18n key exists (Step 7).
+
+- [ ] **Step 7: Add i18n keys**
+
+In `src/app/i18n/translations.ts`, in the `adminProducts` interface block, add two lines (next to `stockStatus: string;` and near the other `column_*` entries):
+
+```typescript
+    stockStatus: string;
+    views: string;
+```
+```typescript
+    column_updated: string;
+    column_visits: string;
+```
+
+In `src/app/i18n/en.ts`, `adminProducts` block:
+```typescript
+    stockStatus: 'Stock status',
+    views: 'Views',
+```
+```typescript
+    column_updated: 'Last updated',
+    column_visits: 'Views',
+```
+
+In `src/app/i18n/ru.ts`, `adminProducts` block (next to its `stockStatus:` line and its `column_updated:` line — read the file first to find them, they're at different line numbers than en.ts):
+```typescript
+    views: 'Просмотры',
+```
+```typescript
+    column_visits: 'Просмотры',
+```
+
+In `src/app/i18n/hy.ts`, `adminProducts` block:
+```typescript
+    views: 'Դիտումներ',
+```
+```typescript
+    column_visits: 'Դիտումներ',
+```
+
+(For ru.ts/hy.ts: read the file first, find the exact existing `stockStatus:`/`column_updated:` lines in the `adminProducts` block — there may be more than one `column_updated:` in the file for a different admin domain, only edit the one inside `adminProducts`, at the location already found: `ru.ts:1642` area, `hy.ts:1642` area.)
+
+- [ ] **Step 8: Run full verification**
+
+Run: `npx tsc --noEmit -p tsconfig.json`
+Expected: no errors.
+
+Run: `npx ng build --configuration development`
+Expected: build succeeds.
+
+Run: `npm run test -- --include='**/admin-products-local.gateway.spec.ts'`
+Expected: PASS (2/2).
+
+- [ ] **Step 9: Document the backend gap**
+
+In `BACKEND-API-REFERENCE.md`, after the existing §12.8 section (search for `### 12.8 Admin purchase notifications depend on Orders CRUD being real` — it currently ends right before `### 12.9 Trending search terms`), insert a new section, and renumber `12.9` to `12.10`:
+
+```markdown
+### 12.9 Admin product view counts
+
+**Gap:** Admin Products (§8) runs on a fully separate mock domain from the storefront's live catalog — `AdminProduct.visits` is a new field added to support a "Views" column in Admin Products, but the mock gateway always defaults it to `0` because there is no real tracking source available to the admin domain today. This is unrelated to the storefront's `Item.visits` field (§6, `/items/{id}`), which is live-wired but never displayed anywhere in the UI.
+
+**Ask:** two options, not mutually exclusive:
+1. Once admin Products gets a real backend (§10 step 4), include a per-product view/visit count in the response.
+2. Bridge `AdminProduct.visits` to the storefront's already-live `Item.visits` by product id, if a unified product identity exists between the storefront and admin domains — smaller change than building new tracking infrastructure.
+
+### 12.10 Trending search terms
+```
+
+(The existing body text of the old `### 12.9 Trending search terms` section stays exactly as-is below the renumbered heading — only the heading number changes, from `12.9` to `12.10`.)
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add src/app/features/admin/products/models/admin-product.model.ts src/app/features/admin/products/services/admin-products-local.gateway.ts src/app/features/admin/products/services/admin-products-local.gateway.spec.ts src/app/features/admin/products/facade/admin-products.facade.ts src/app/features/admin/products/components/admin-products-list.component.html src/app/i18n/en.ts src/app/i18n/ru.ts src/app/i18n/hy.ts src/app/i18n/translations.ts BACKEND-API-REFERENCE.md
+git commit -m "feat: admin product views column (always 0 until backend tracks it)"
+```

docs/superpowers/specs/2026-08-15-admin-product-views-column-design.md

@@ -0,0 +1,38 @@
+# Admin product view count column — design
+
+**Status:** Approved
+**Date:** 2026-08-15
+**Related backlog item:** #1 (site traffic counter)
+
+## Problem
+
+User reported "site traffic isn't visible, counter shows low." Investigation found two separate things already exist and are working as intended, neither of which is the actual gap:
+
+- Admin Analytics → Traffic tab already shows an honest `"Unknown - available after backend"` badge (`admin-analytics-page.component.html:231`) — no fake data, correctly reflects that no traffic-tracking pipeline exists at all (`BACKEND-API-REFERENCE.md` §10 step 10).
+- The storefront `Item.visits` field is wired end-to-end from the live backend (`api.service.ts:438`) but is never rendered anywhere in the UI, and the backend mock always seeds it `0`.
+
+User confirmed (via clarifying question) the actual complaint is: **no per-product view count visible in Admin Products.**
+
+Further investigation found Admin Products runs on a fully separate mock domain (`AdminProduct` model, `admin-products-local.gateway.ts`, seeded from `list.json`) that has no relationship to the storefront's live `Item.visits` pipeline at all. So a "Views" column here cannot show real per-product traffic today — there is no data source for it in the admin domain. This mirrors the currency/FX and order-notification gaps already documented this session: build the honest client-side piece, document the backend gap explicitly, never fabricate numbers.
+
+## Design
+
+**Model:** add `visits: number` to `AdminProduct` (`src/app/features/admin/products/models/admin-product.model.ts`), alongside the other stat-like fields (`priority`, `quantity`).
+
+**Mock gateway:** `admin-products-local.gateway.ts` defaults `visits: 0` when building the in-memory seed from `list.json` — no fabricated numbers, matches the field's actual state (nothing increments it yet).
+
+**List column:** `ALL_PRODUCT_COLUMNS` (`admin-products.facade.ts:39`) gains `'visits'`. Rendered in `admin-products-list.component.html` table view only (grid view is out of scope per user's placement choice), following the exact existing `isColumnVisible('stock')`/`isColumnVisible('price')` pattern — toggleable via the same column-picker UI, persisted the same way (`LocalStorageService`, `COLUMNS_KEY`).
+
+**i18n:** one new key, `adminProducts.views` (label for the column header), added to `en.ts`/`ru.ts`/`hy.ts`/`translations.ts`.
+
+## Backend doc update
+
+New `BACKEND-API-REFERENCE.md` §12.x ask (numbered after the existing 12.8, following the established "Gap / Ask" format): the admin Products domain has no view-count source. Two options to raise:
+1. Once admin Products gets a real backend (§10 step 4), include a view/visit count per product in the response.
+2. Alternatively, bridge to the storefront's already-live `Item.visits` (§6, `/items/{id}`) by product id — smaller change if a unified product identity exists between the storefront and admin domains.
+
+## Out of scope
+
+- Storefront customer-facing "N people viewed this" display — not requested, deferred (was offered as a placement option, not chosen).
+- Product edit/detail page display — not requested (list column only, per user's placement choice).
+- Any client-side view tracking/incrementing — explicitly rejected in favor of the honest display-only approach; a client-only counter would only reflect the admin's own browser, not real shoppers, same trap already avoided for currency rates.

src/app/features/admin/products/components/admin-products-list.component.html

@@ -98,6 +98,7 @@
           @if (isColumnVisible('price')) { <th scope="col">{{ 'backoffice.price' | translate }}</th> }
           @if (isColumnVisible('stock')) { <th scope="col">{{ 'adminProducts.stockStatus' | translate }}</th> }
           @if (isColumnVisible('visibility')) { <th scope="col">{{ 'adminProducts.visibility' | translate }}</th> }
+          @if (isColumnVisible('visits')) { <th scope="col">{{ 'adminProducts.views' | translate }}</th> }
           <th scope="col">{{ 'adminProducts.healthColumn' | translate }}</th>
           <th scope="col">{{ 'adminProducts.actions' | translate }}</th>
         </tr>
@@ -124,6 +125,7 @@
                 </app-badge>
               </td>
             }
+            @if (isColumnVisible('visits')) { <td>{{ product.visits }}</td> }
             <td class="health-cell"><app-product-health-widget [items]="healthItems(product)" [completionPercent]="health(product).completionPercent" [compact]="true" /></td>
             <td class="actions">
               <app-button variant="secondary" size="sm" (click)="edit.emit(product.id)">{{ 'adminProducts.edit' | translate }}</app-button>

src/app/features/admin/products/facade/admin-products.facade.ts

@@ -36,7 +36,7 @@ const VIEW_MODE_KEY = 'admin-products:view-mode';
 const DENSITY_KEY = 'admin-products:density';
 const COLUMNS_KEY = 'admin-products:visible-columns';
 
-export const ALL_PRODUCT_COLUMNS = ['sku', 'brand', 'price', 'stock', 'visibility', 'updated'] as const;
+export const ALL_PRODUCT_COLUMNS = ['sku', 'brand', 'price', 'stock', 'visibility', 'updated', 'visits'] as const;
 export type AdminProductColumn = typeof ALL_PRODUCT_COLUMNS[number];
 
 @Injectable({ providedIn: 'root' })

src/app/features/admin/products/models/admin-product.model.ts

@@ -101,6 +101,7 @@ export interface AdminProduct {
   specifications: AdminProductSpecification[];
   attributes: AdminProductAttribute[];
   variantAttributes: AdminProductVariantAttributeDef[];
+  visits: number;
   variants: AdminProductVariant[];
   relatedProductIds: string[];
   translations: Record<string, AdminProductTranslation>;

src/app/features/admin/products/services/admin-products-form.factory.ts

@@ -20,6 +20,7 @@ export class AdminProductsFormFactory {
       discount: 0,
       currency: 'RUB',
       quantity: 0,
+      visits: 0,
       stockStatus: 'in_stock',
       availability: 'in_stock',
       shortDescription: '',

src/app/features/admin/products/services/admin-products-local.gateway.spec.ts

@@ -0,0 +1,64 @@
+import { TestBed } from '@angular/core/testing';
+import { of } from 'rxjs';
+import { AdminProductsLocalGateway } from './admin-products-local.gateway';
+import { BackofficeDataService } from '../../../../core/backoffice/backoffice-data.service';
+import { AdminCategoriesLocalGateway } from '../../categories/services/admin-categories-local.gateway';
+import { ProductCardConfig } from '../../../../shared/models/ui';
+import { AdminProductListFilters } from '../models/admin-product.model';
+
+function makeProductCard(id: string): ProductCardConfig {
+  return {
+    id,
+    sku: `SKU-${id}`,
+    title: `Product ${id}`,
+    imageUrl: '/image.png',
+    price: { amount: 1000, currency: 'RUB' },
+    stockStatus: 'in_stock',
+  };
+}
+
+function makeFilters(): AdminProductListFilters {
+  return {
+    search: '',
+    categoryId: null,
+    visibility: 'all',
+    stock: 'all',
+    includeArchived: true,
+    sort: 'title',
+    page: 1,
+    pageSize: 50,
+  };
+}
+
+describe('AdminProductsLocalGateway visits field', () => {
+  let gateway: AdminProductsLocalGateway;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [
+        { provide: BackofficeDataService, useValue: { loadProducts: () => of([makeProductCard('p1'), makeProductCard('p2')]) } },
+        { provide: AdminCategoriesLocalGateway, useValue: { loadCategories: () => of([{ id: 'cat-001', title: 'Category' }]) } },
+      ],
+    });
+    gateway = TestBed.inject(AdminProductsLocalGateway);
+  });
+
+  it('defaults visits to 0 on every loaded product', (done) => {
+    gateway.loadProducts(makeFilters()).subscribe(result => {
+      expect(result.items.length).toBe(2);
+      expect(result.items.every(product => product.visits === 0)).toBe(true);
+      done();
+    });
+  });
+
+  it('resets visits to 0 on a duplicated product', (done) => {
+    gateway.loadProducts(makeFilters()).subscribe(result => {
+      const source = result.items[0];
+      gateway.duplicateProduct(source.id).subscribe(duplicated => {
+        expect(duplicated).not.toBeNull();
+        expect(duplicated!.visits).toBe(0);
+        done();
+      });
+    });
+  });
+});

src/app/features/admin/products/services/admin-products-local.gateway.ts

@@ -86,6 +86,7 @@ export class AdminProductsLocalGateway implements AdminProductsGateway {
       sku: `${source.sku}-COPY`,
       slug: `${source.slug}-copy-${Date.now()}`,
       name: `${source.name} Copy`,
+      visits: 0,
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
     };
@@ -153,6 +154,7 @@ export class AdminProductsLocalGateway implements AdminProductsGateway {
         : 0,
       currency: product.price.currency,
       quantity: product.stockStatus === 'out_of_stock' ? 0 : product.stockStatus === 'low_stock' ? 3 : 25,
+      visits: 0,
       stockStatus: product.stockStatus ?? 'in_stock',
       availability: product.stockStatus ?? 'in_stock',
       shortDescription: product.subtitle ?? '',

src/app/i18n/en.ts

@@ -1645,6 +1645,7 @@ export const en: Translations = {
     visible: 'Visible',
     hidden: 'Hidden',
     stockStatus: 'Stock status',
+    views: 'Views',
     allStock: 'All stock levels',
     inStock: 'In stock',
     lowStock: 'Low stock',
@@ -1669,6 +1670,7 @@ export const en: Translations = {
     column_stock: 'Stock',
     column_visibility: 'Visibility',
     column_updated: 'Last updated',
+    column_visits: 'Views',
     create: 'Create product',
     edit: 'Edit product',
     duplicate: 'Duplicate',

src/app/i18n/hy.ts

@@ -1640,6 +1640,7 @@ export const hy: Translations = {
     visible: 'Տեսանելի',
     hidden: 'Թաքցված',
     stockStatus: 'Պահեստի կարգավիճակ',
+    views: 'Դիտումներ',
     allStock: 'Ցանկացած մնացորդ',
     inStock: 'Առկա է',
     lowStock: 'Քիչ է մնացել',
@@ -1664,6 +1665,7 @@ export const hy: Translations = {
     column_stock: 'Մնացորդ',
     column_visibility: 'Տեսանելիություն',
     column_updated: 'Վերջին փոփոխություն',
+    column_visits: 'Դիտումներ',
     create: 'Ստեղծել ապրանք',
     edit: 'Խմբագրել ապրանքը',
     duplicate: 'Կրկնօրինակել',

src/app/i18n/ru.ts

@@ -1640,6 +1640,7 @@ export const ru: Translations = {
     visible: 'Видимый',
     hidden: 'Скрытый',
     stockStatus: 'Статус наличия',
+    views: 'Просмотры',
     allStock: 'Любой остаток',
     inStock: 'В наличии',
     lowStock: 'Мало на складе',
@@ -1664,6 +1665,7 @@ export const ru: Translations = {
     column_stock: 'Остаток',
     column_visibility: 'Видимость',
     column_updated: 'Последнее изменение',
+    column_visits: 'Просмотры',
     create: 'Создать товар',
     edit: 'Редактировать товар',
     duplicate: 'Дублировать',

src/app/i18n/translations.ts

@@ -1653,6 +1653,7 @@ export interface Translations {
     visible: string;
     hidden: string;
     stockStatus: string;
+    views: string;
     allStock: string;
     inStock: string;
     lowStock: string;
@@ -1677,6 +1678,7 @@ export interface Translations {
     column_stock: string;
     column_visibility: string;
     column_updated: string;
+    column_visits: string;
     create: string;
     edit: string;
     duplicate: string;