sync: clean stale local pricelists and migrate runtime config handling

2026-02-08 10:01:27 +03:00
parent eb8555c11a
commit 593280de99
12 changed files with 434 additions and 426 deletions
--- a/README.md
+++ b/README.md
@@ -56,13 +56,13 @@ git clone https://github.com/your-company/quoteforge.git
 cd quoteforge
 ```

-### 2. Настройка конфигурации
+### 2. Настройка runtime-конфига (опционально)

-```bash
-cp config.example.yaml config.yaml
-```
+`config.yaml` создаётся автоматически при первом старте в той же user-state папке, где находится `qfs.db`.
+Если найден старый формат, приложение автоматически мигрирует файл в актуальный runtime-формат
+(оставляя только используемые секции `server` и `logging`).

-Отредактируйте `config.yaml`:
+При необходимости можно создать/отредактировать файл вручную:

 ```yaml
 server:
@@ -70,16 +70,10 @@ server:
  port: 8080
  mode: "release"

-database:
-  host: "localhost"
-  port: 3306
-  name: "RFQ_LOG"
-  user: "quoteforge"
-  password: "your-secure-password"
-
-auth:
-  jwt_secret: "your-jwt-secret-min-32-chars"
-  token_expiry: "24h"
+logging:
+  level: "info"
+  format: "json"
+  output: "stdout"
 ```

 ### 3. Миграции базы данных
@@ -96,19 +90,19 @@ go run ./cmd/qfs -migrate
 Сначала всегда смотрите preview:

 ```bash
-go run ./cmd/migrate_ops_projects -config config.yaml
+go run ./cmd/migrate_ops_projects
 ```

 Применение изменений:

 ```bash
-go run ./cmd/migrate_ops_projects -config config.yaml -apply
+go run ./cmd/migrate_ops_projects -apply
 ```

 Без интерактивного подтверждения:

 ```bash
-go run ./cmd/migrate_ops_projects -config config.yaml -apply -yes
+go run ./cmd/migrate_ops_projects -apply -yes
 ```

 ### Минимальные права БД для пользователя квотаций
@@ -222,6 +216,44 @@ make help            # Показать все команды
 - sync API возвращает `423 Locked` с `reason_code` и `reason_text`;
 - в UI показывается красный индикатор и причина блокировки в модалке синхронизации.

+#### Схема потоков данных синхронизации
+
+```text
+                          [ SERVER / MariaDB ]
+                     ┌───────────────────────────┐
+                     │ qt_projects               │
+                     │ qt_configurations         │
+                     │ qt_pricelists             │
+                     │ qt_pricelist_items        │
+                     │ qt_pricelist_sync_status  │
+                     └─────────────┬─────────────┘
+                                   │
+                    pull (projects/configs/pricelists)
+                                   │
+                ┌──────────────────┴──────────────────┐
+                │                                     │
+      [ CLIENT A / local SQLite ]           [ CLIENT B / local SQLite ]
+   ┌───────────────────────────────┐       ┌───────────────────────────────┐
+   │ local_projects                │       │ local_projects                │
+   │ local_configurations          │       │ local_configurations          │
+   │ local_pricelists              │       │ local_pricelists              │
+   │ local_pricelist_items         │       │ local_pricelist_items         │
+   │ pending_changes (proj/config) │       │ pending_changes (proj/config) │
+   └───────────────┬───────────────┘       └───────────────┬───────────────┘
+                   │                                       │
+      push (projects/configurations only)     push (projects/configurations only)
+                   │                                       │
+                   └──────────────────┬────────────────────┘
+                                      │
+                              [ SERVER / MariaDB ]
+```
+
+По сущностям:
+- Конфигурации: `Client <-> Server <-> Other Clients`
+- Проекты: `Client <-> Server <-> Other Clients`
+- Прайслисты: `Server -> Clients only` (локальный push отсутствует)
+- Локальная очистка прайслистов на клиенте: удаляются записи, которых нет на сервере и которые не используются активными локальными конфигурациями
+
 ### Версионность конфигураций (local-first)

 Для `local_configurations` используется append-only versioning через полные snapshot-версии:
@@ -255,6 +287,7 @@ POST /api/configs/:uuid/rollback
 ### Локальный config.yaml

 По умолчанию `qfs` ищет `config.yaml` в той же user-state папке, где лежит `qfs.db` (а не рядом с бинарником).
+Если файла нет, он создаётся автоматически. Если формат устарел, он автоматически мигрируется в runtime-формат (`server` + `logging`).
 Можно переопределить путь через `-config` или `QFS_CONFIG_PATH`.

 ## Docker
@@ -285,9 +318,7 @@ quoteforge/
 │   ├── templates/       # HTML шаблоны
 │   └── static/          # CSS, JS, изображения
 ├── migrations/          # SQL миграции
-├── config.yaml          # Конфигурация
-├── Dockerfile
-├── docker-compose.yml
+├── config.example.yaml  # Пример конфигурации
 └── go.mod
 ```

@@ -325,6 +356,17 @@ POST /api/sync/components                  # Pull components (423, если bloc
 POST /api/sync/pricelists                  # Pull pricelists (423, если blocked)
 ```

+### Краткая карта sync API
+
+| Endpoint | Назначение | Поток |
+|----------|------------|-------|
+| `POST /api/sync/push` | Отправить локальные pending-изменения | `SQLite -> MariaDB` |
+| `POST /api/sync/components` | Подтянуть справочник компонентов | `MariaDB -> SQLite` |
+| `POST /api/sync/pricelists` | Подтянуть прайслисты и позиции | `MariaDB -> SQLite` |
+| `POST /api/sync/all` | Полный цикл: push + pull + импорт проектов/конфигураций | `двунаправленно` |
+| `GET /api/sync/readiness` | Статус preflight/readiness | `read-only` |
+| `GET /api/sync/status` / `GET /api/sync/info` | Сводка статуса и данных синхронизации | `read-only` |
+
 #### Sync payload для versioning

 События в `pending_changes` для конфигураций содержат:
@@ -336,50 +378,6 @@ POST /api/sync/pricelists                  # Pull pricelists (423, если bloc

 Это позволяет push-слою отправлять на сервер актуальное состояние и готовит основу для будущего conflict resolution.

-## Cron Jobs
-
-QuoteForge now includes automated cron jobs for maintenance tasks. These can be run using the built-in cron functionality in the Docker container.
-
-### Docker Compose Setup
-
-The Docker setup includes a dedicated cron service that runs the following jobs:
-
- **Alerts check**: Every hour (0 * * * *)
- **Price updates**: Daily at 2 AM (0 2 * * *)
- **Usage counter reset**: Weekly on Sunday at 1 AM (0 1 * * 0)
- **Popularity score updates**: Daily at 3 AM (0 3 * * *)
-
-To enable cron jobs in Docker, run:
-
-```bash
-docker-compose up -d
-```
-
-### Manual Cron Job Execution
-
-You can also run cron jobs manually using the quoteforge-cron binary:
-
-```bash
-# Check and generate alerts
-go run ./cmd/cron -job=alerts
-
-# Recalculate all prices
-go run ./cmd/cron -job=update-prices
-
-# Reset usage counters
-go run ./cmd/cron -job=reset-counters
-
-# Update popularity scores
-go run ./cmd/cron -job=update-popularity
-```
-
-### Cron Job Details
-
- **Alerts check**: Generates alerts for components with high demand and stale prices, trending components without prices, and components with no recent quotes
- **Price updates**: Recalculates prices for all components using configured methods (median, weighted median, average)
- **Usage counter reset**: Resets weekly and monthly usage counters for components
- **Popularity score updates**: Recalculates popularity scores based on supplier quote activity
-
 ## Разработка

 ```bash