# Catalog Browser with Filter Management & CSV Export

## Context

Users need to browse their Evotor catalog (stores, groups, products) in a table view, manage sync whitelist/blacklist rules inline, and export data to CSV.

This feature **replaces** the separate `/sync/stores`, `/sync/groups`, `/sync/products` pages from the sync-configuration plan. The catalog browser becomes the unified place for both viewing data and managing filter rules.

Data is cached in DB with a refresh mechanism — not fetched live on every page load.

## Data Model

### Catalog Cache Tables

```
tablename: "cached_stores"
- id (Integer, PK)
- user_id (Integer, FK users.id CASCADE)
- evotor_id (String 255)               # Evotor UUID
- name (String 255)
- address (String 500, nullable)
- fetched_at (DateTime)                 # when this snapshot was taken

UniqueConstraint: (user_id, evotor_id)
Index: user_id
```

```
tablename: "cached_groups"
- id (Integer, PK)
- user_id (Integer, FK users.id CASCADE)
- evotor_id (String 255)               # Evotor UUID
- store_evotor_id (String 255)         # parent store UUID
- name (String 255)
- fetched_at (DateTime)

UniqueConstraint: (user_id, evotor_id)
Index: (user_id, store_evotor_id)
```

```
tablename: "cached_products"
- id (Integer, PK)
- user_id (Integer, FK users.id CASCADE)
- evotor_id (String 255)               # Evotor UUID
- store_evotor_id (String 255)         # parent store UUID
- group_evotor_id (String 255, nullable)  # parent group UUID
- name (String 255)
- price (Numeric(12,2), nullable)
- quantity (Numeric(12,3), nullable)
- measure_name (String 20, nullable)
- article_number (String 100, nullable)
- allow_to_sell (Boolean, nullable)
- fetched_at (DateTime)

UniqueConstraint: (user_id, evotor_id)
Index: (user_id, store_evotor_id, group_evotor_id)
```

### `SyncFilter` (from sync-configuration plan, unchanged)

```
tablename: "sync_filters"
- sync_config_id, entity_type, entity_id, entity_name, filter_mode, parent_entity_id
```

The catalog browser reads from cache tables for display and from `sync_filters` for the current filter state of each entity.

### Cache Refresh

`web/evotor_api.py` gets a new function:

```python
async def refresh_catalog_cache(user_id: int, access_token: str, db: Session):
    """Fetch all stores, groups, products from Evotor API and upsert into cache tables."""
```

Triggered by:
- Manual "Обновить" button on the catalog page
- Background job (optional, can reuse health_checker interval or separate setting)
- First visit to catalog if cache is empty

## Plan

### 1. New Models — `web/models.py`

Add `CachedStore`, `CachedGroup`, `CachedProduct` models as described above.

### 2. Alembic Migration

Create `cached_stores`, `cached_groups`, `cached_products` tables.

### 3. Evotor API Helper — `web/evotor_api.py`

Extend with:

```python
async def fetch_stores(access_token: str) -> list[dict]
async def fetch_groups(access_token: str, store_id: str) -> list[dict]
async def fetch_products(access_token: str, store_id: str) -> list[dict]
async def refresh_catalog_cache(user_id: int, access_token: str, db: Session)
```

`refresh_catalog_cache` does:
1. Fetch all stores
2. For each store, fetch groups and products
3. Upsert into cache tables (delete old rows for user, insert fresh)
4. Update `fetched_at` timestamps

### 4. Catalog Route — `web/routes/catalog.py` (new)

**`GET /catalog`** — Stores table. Requires auth + Evotor connection.
- Reads `cached_stores` for user
- If cache is empty, triggers refresh
- Shows table with columns: Название, Адрес, Статус фильтра, Действия
- Each row shows the store's current `SyncFilter` state (included/excluded/no rule)
- Link to drill into groups for each store
- "Обновить каталог" button, "Экспорт CSV" button, back link

**`GET /catalog/groups?store_id=UUID`** — Groups table for a store.
- Reads `cached_groups` filtered by `store_evotor_id`
- Table columns: Название, Статус фильтра, Кол-во товаров, Действия
- Each row shows group's `SyncFilter` state
- Link to drill into products for each group
- "Экспорт CSV" button, back to stores

**`GET /catalog/products?store_id=UUID&group_id=UUID`** — Products table for a group.
- Reads `cached_products` filtered by `store_evotor_id` and `group_evotor_id`
- Table columns: Название, Артикул, Цена, Кол-во, Ед. изм., В продаже, Статус фильтра, Действия
- Each row shows product's `SyncFilter` state
- "Экспорт CSV" button, back to groups

**`GET /catalog/products?store_id=UUID`** — All products for a store (no group filter).
- Same table, but shows all products in the store with a "Группа" column added

**`POST /catalog/filter`** — Toggle filter for an entity.
- Body: `entity_type`, `entity_id`, `entity_name`, `filter_mode` (include/exclude/none), `parent_entity_id`
- Creates, updates, or deletes the `SyncFilter` row
- Redirects back to the referring page

**`POST /catalog/refresh`** — Manual cache refresh.
- Calls `refresh_catalog_cache()`
- Redirects back to `/catalog`

**`GET /catalog/export?type=stores|groups|products&store_id=UUID&group_id=UUID`** — CSV export.
- Reads from cache tables
- Returns `StreamingResponse` with `text/csv` content type and `Content-Disposition: attachment`
- Filename: `{type}_{date}.csv`

### 5. Templates

**`web/templates/catalog_stores.html`** — Stores table:

```
┌──────────────────────────────────────────────────────────────┐
│  Каталог                        [Обновить]  [Экспорт CSV]   │
│  Последнее обновление: 06.03.2026 14:30                      │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  Магазины                                                    │
│  ┌──────────────────────────────────────────────────────┐    │
│  │ Название        │ Адрес        │ Фильтр   │         │    │
│  ├──────────────────────────────────────────────────────┤    │
│  │ Чайная           │ ул. Мира, 1  │ ✓ Вкл    │ [→][▼] │    │
│  │ Склад            │ —            │ ✗ Выкл   │ [→][▼] │    │
│  │ Точка 2          │ ул. Мира, 5  │ — Нет    │ [→][▼] │    │
│  └──────────────────────────────────────────────────────┘    │
│                                                              │
│  [→] = перейти к группам                                     │
│  [▼] = dropdown: Включить / Исключить / Убрать правило      │
│                                                              │
└──────────────────────────────────────────────────────────────┘
```

**Filter status column** shows:
- `✓ Включено` (green badge) — entity has an "include" rule
- `✗ Исключено` (red badge) — entity has an "exclude" rule
- `— Нет правила` (grey badge) — no filter rule (follows default behavior)

**Actions column** per row:
- Link icon → drill into children (groups for stores, products for groups)
- Dropdown button with filter actions: "Включить в синхронизацию" / "Исключить из синхронизации" / "Убрать правило". Each is a small POST form to `/catalog/filter`.

**`web/templates/catalog_groups.html`** — Groups table:
- Breadcrumb: Каталог > {Store name} > Группы
- Same table pattern, columns: Название, Кол-во товаров, Фильтр, Действия
- Drill-down link to products per group

**`web/templates/catalog_products.html`** — Products table:
- Breadcrumb: Каталог > {Store name} > {Group name} > Товары
- Columns: Название, Артикул, Цена, Кол-во, Ед. изм., В продаже, Фильтр, Действия
- "В продаже" column: green check / red cross based on `allow_to_sell`

All tables use Bootstrap table styling (`table table-striped table-hover`) with responsive wrapper.

### 6. CSV Export Format

**Stores CSV:**
```
Название,Адрес,ID,Фильтр
Чайная,"ул. Мира, 1",uuid-123,Включено
```

**Groups CSV:**
```
Магазин,Название,ID,Фильтр
Чайная,Белый чай,uuid-456,Включено
```

**Products CSV:**
```
Магазин,Группа,Название,Артикул,Цена,Количество,Ед. измерения,В продаже,ID,Фильтр
Чайная,Белый чай,Бай Му Дань,1005,350.00,180.0,г,Да,uuid-789,Включено
```

UTF-8 with BOM (`\ufeff`) for Excel compatibility. Delimiter: comma.

### 7. Update Sync Configuration Plan

The `/sync` page links to `/catalog` instead of separate filter pages:
- "Настроить фильтры" button → `/catalog`
- Filter summary on `/sync` reads from `SyncFilter` table (unchanged)
- Remove `/sync/stores`, `/sync/groups`, `/sync/products` routes from sync-configuration plan — replaced by catalog browser

### 8. Navbar / Navigation

Add "Каталог" link to navbar for logged-in users. Order: Подключения → Каталог → Синхронизация → Личный кабинет → Выход.

### 9. Register Route — `web/main.py`

```python
from web.routes import catalog
app.include_router(catalog.router)
```

## Files Summary

| File | Action |
|------|--------|
| `web/models.py` | Modify — add `CachedStore`, `CachedGroup`, `CachedProduct` |
| `web/evotor_api.py` | Create — API fetch + cache refresh functions |
| `web/routes/catalog.py` | Create — catalog routes (tables, filter toggle, refresh, CSV export) |
| `web/templates/catalog_stores.html` | Create — stores table |
| `web/templates/catalog_groups.html` | Create — groups table |
| `web/templates/catalog_products.html` | Create — products table |
| `web/templates/base.html` | Modify — add "Каталог" nav link |
| `web/main.py` | Modify — register catalog router |
| `docs/plans/sync-configuration.md` | Update — remove /sync/stores,groups,products; link to /catalog |
| Alembic migration | Create — cache tables |

## Verification

1. Run `alembic upgrade head`
2. Visit `/catalog` without Evotor connection → warning to connect first
3. Connect Evotor, visit `/catalog` → triggers first cache refresh, shows stores table
4. Click store → shows groups table with group names from Evotor
5. Click group → shows products table with full product details
6. Toggle filter on a product → badge changes, `SyncFilter` row created in DB
7. Go to `/sync` → filter summary reflects the change
8. Click "Экспорт CSV" on products page → downloads CSV, opens correctly in Excel
9. Click "Обновить каталог" → re-fetches from Evotor API, updates cache
10. Verify breadcrumb navigation works correctly through the hierarchy