# QuoteForge - Claude Code Instructions

## Overview
Корпоративный конфигуратор серверов и формирование КП. MariaDB (RFQ_LOG) + SQLite для оффлайн.

## Development Phases

### Phase 1: Pricelists in MariaDB ✅ DONE
### Phase 2: Local SQLite Database ✅ DONE

### Phase 2.5: Full Offline Mode 🔶 IN PROGRESS
**Local-first architecture:** приложение ВСЕГДА работает с SQLite, MariaDB только для синхронизации.

**Принцип работы:**
- ВСЕ операции (CRUD) выполняются в SQLite
- При создании конфигурации:
  1. Если online → проверить новые прайслисты на сервере → скачать если есть
  2. Далее работаем с local_pricelists (и online, и offline одинаково)
- Background sync: push pending_changes → pull updates

**DONE:**
- ✅ Sync queue table (pending_changes) - `internal/localdb/models.go`
- ✅ Model converters: MariaDB ↔ SQLite - `internal/localdb/converters.go`
- ✅ LocalConfigurationService: все CRUD через SQLite - `internal/services/local_configuration.go`
- ✅ Pre-create pricelist check: `SyncPricelistsIfNeeded()` - `internal/services/sync/service.go`
- ✅ Push pending changes: `PushPendingChanges()` - sync service + handlers
- ✅ Sync API endpoints: `/api/sync/push`, `/pending/count`, `/pending`
- ✅ Integrate LocalConfigurationService in main.go (replace ConfigurationService)
- ✅ Add routes for new sync endpoints (`/api/sync/push`, `/pending/count`, `/pending`)
- ✅ ConfigurationGetter interface for handler compatibility
- ✅ Background sync worker: auto-sync every 5min (push + pull) - `internal/services/sync/worker.go`
- ✅ UI: sync status indicator (pending badge + sync button + offline/online dot) - `web/templates/partials/sync_status.html`
- ✅ RefreshPrices for local mode:
  - `RefreshPrices()` / `RefreshPricesNoAuth()` в `local_configuration.go`
  - Берёт цены из `local_components.current_price`
  - Graceful degradation при отсутствии компонента
  - Добавлено поле `price_updated_at` в `LocalConfiguration` (models.go:72)
  - Обновлены converters для PriceUpdatedAt
  - UI кнопка "Пересчитать цену" работает offline/online
- ✅ Fixed sync bugs:
  - Duplicate entry error при update конфигураций (`sync/service.go:334-365`)
  - pushConfigurationUpdate теперь проверяет наличие server_id перед update
  - Если нет ID → получает из LocalConfiguration.ServerID или ищет на сервере
  - Fixed setup.go: `settings.Password` → `settings.PasswordEncrypted`

**TODO:**
- ❌ Conflict resolution (Phase 4, last-write-wins default)

### UI Improvements 🔶 IN PROGRESS

**1. Sync icon + pricelist badge в header (tasks 4+2):**
- ❌ `sync_status.html`: заменить текст Online/Offline на SVG иконку
- ❌ Кнопка sync → иконка (circular arrows) вместо текста
- ❌ Dropdown при клике: Push changes, Full sync, статус последней синхронизации
- ❌ `configs.html`: рядом с кнопкой "Создать" показать badge с версией активного прайслиста
- ❌ Загружать через `/api/pricelists/latest` при DOMContentLoaded

**2. Прайслисты → вкладка в "Администратор цен" (task 1):**
- ❌ `base.html`: убрать отдельную ссылку "Прайслисты" из навигации
- ❌ `admin_pricing.html`: добавить 4-ю вкладку "Прайслисты"
- ❌ Перенести логику из `pricelists.html` (table, create modal, CRUD) в эту вкладку
- ❌ Route `/pricelists` → редирект на `/admin/pricing?tab=pricelists` или удалить

**3. Страница настроек: расширить + синхронизация (task 3):**
- ❌ `setup.html`: переделать на `{{template "base" .}}` структуру
- ❌ Увеличить до `max-w-4xl`, разделить на 2 секции
- ❌ Секция A: Подключение к БД (текущая форма)
- ❌ Секция B: Синхронизация данных:
  - Статус Online/Offline
  - Кнопки: "Синхронизировать всё", "Обновить компоненты", "Обновить прайслисты"
  - Журнал синхронизации (последние N операций)
- ❌ Возможно: новый API endpoint для sync log

### Phase 3: Projects and Specifications
- qt_projects, qt_specifications tables (MariaDB)
- Replace qt_configurations → Project/Specification hierarchy
- Fields: opty, customer_requirement, variant, qty, rev
- Local projects/specs with server sync

### Phase 4: Price Versioning
- Bind specifications to pricelist versions
- Price diff comparison
- Auto-cleanup expired pricelists (>1 year, usage_count=0)

## Tech Stack
Go 1.22+ | Gin | GORM | MariaDB 11 | SQLite (glebarez/sqlite) | htmx + Tailwind CDN | excelize

## Key Tables

### READ-ONLY (external systems)
- `lot` (lot_name PK, lot_description)
- `lot_log` (lot, supplier, date, price, quality, comments)
- `supplier` (supplier_name PK)

### MariaDB (qt_* prefix)
- `qt_lot_metadata` - component prices, methods, popularity
- `qt_categories` - category codes and names
- `qt_pricelists` - version snapshots (YYYY-MM-DD-NNN format)
- `qt_pricelist_items` - prices per pricelist
- `qt_projects` - uuid, opty, customer_requirement, name (Phase 3)
- `qt_specifications` - project_id, pricelist_id, variant, rev, qty, items JSON (Phase 3)

### SQLite (data/quoteforge.db)
- `connection_settings` - encrypted DB credentials (PasswordEncrypted field)
- `local_pricelists/items` - cached from server
- `local_components` - lot cache for offline search (with current_price)
- `local_configurations` - UUID, items, price_updated_at, sync_status (pending/synced/conflict), server_id
- `local_projects/specifications` - Phase 3
- `pending_changes` - sync queue (entity_type, uuid, op, payload, created_at, attempts, last_error)

## Business Logic

**Part number parsing:** `CPU_AMD_9654` → category=`CPU`, model=`AMD_9654`

**Price methods:** manual | median | average | weighted_median

**Price freshness:** fresh (<30d, ≥3 quotes) | normal (<60d) | stale (<90d) | critical

**Pricelist version:** `YYYY-MM-DD-NNN` (e.g., `2024-01-31-001`)

## API Endpoints

| Group | Endpoints |
|-------|-----------|
| Setup | GET/POST /setup, POST /setup/test |
| Components | GET /api/components, /api/categories |
| Pricelists | CRUD /api/pricelists, GET /latest, POST /compare |
| Projects | CRUD /api/projects/:uuid (Phase 3) |
| Specs | CRUD /api/specs/:uuid, POST /upgrade, GET /diff (Phase 3) |
| Configs | POST /:uuid/refresh-prices (обновить цены из local_components) |
| Sync | GET /status, POST /components, /pricelists, /push, /pull, /resolve-conflict |
| Export | GET /api/specs/:uuid/export, /api/projects/:uuid/export |

## Commands
```bash
go run ./cmd/server          # Dev server
go run ./cmd/cron -job=X     # cleanup-pricelists | update-prices | update-popularity
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/quoteforge ./cmd/server
```

## Code Style
- gofmt, structured logging (slog), wrap errors with context
- snake_case files, PascalCase types
- RBAC disabled: DB username = user_id via `models.EnsureDBUser()`

## UI Guidelines
- htmx (hx-get/post/target/swap), Tailwind CDN
- Freshness colors: green (fresh) → yellow → orange → red (critical)
- Sync status + offline indicator in header