# Описание проекта MAG для ИИ-помощника

> Полное описание проекта: структура, компоненты, API, frontend, аналитика. Используй при ответах, доработках и отладке.

---

## 1. Общая архитектура

### 1.1 Структура репозитория

```
mag/
├── api/                    # Backend авторизации, задач, корзин (Node.js, port 5710)
├── magapi/                 # Backend аналитики, MS SQL (Node.js, port 9001)
├── quasar/                 # SPA на Quasar/Vue 3
├── analytics/              # PBI модель, SQL схема, база знаний
│   ├── pbi/                # Power BI отчёт (TMDL)
│   ├── sql_db_mag_pbi/     # Схема БД mag_pbi
│   ├── 01_ПОЛНАЯ_СТРУКТУРА_PBI_И_SQL.md  # База знаний SQL/PBI
│   └── 02_КОММЕНТАРИИ_ДЛЯ_ИИ_ПОМОЩНИКА.md # Этот файл
├── .cursor/rules/          # analize.mdc — правила для AI
└── nginx-agent-snippet.conf
```

### 1.2 Схема взаимодействия

```
Quasar (SPA)
    ├── api (axios) → MagAPI (/mag/) — данные аналитики, MSSQL
    ├── apiAuth     → API (/mag_backend/) — авторизация
    └── apiMain     → API (/mag_backend/) — JWT, задачи, корзины, endpoints

MagAPI (9001)  ──► MSSQL mag_pbi
API (5710)     ──► MySQL (users, jobs, basket)
```

---

## 2. API (api/) — порт 5710

### 2.1 Маршруты

Динамический роутинг: `GET|POST /mag_backend/:lib/:path*`

| lib | Назначение | Примеры функций |
|-----|------------|----------------|
| auth | Авторизация | signIn, signInOneC, registerUser |
| admin | Админка | users, addUser, updateUser, impersonate |
| user | Профиль | fetchMe, myCategories |
| jobs | Задачи | createJob, getJobs, startJob, startWBReviewsSync |
| basket | Корзины | loadBaskets, addProductToBasket |
| endpoints | Файлы, аналитика | uploadExcelToBD, getWBContentAnalytics |
| products | Товары | getDetails, search |
| potentialOrders | Потенциальные заказы | getPotentialOrders |
| suppliers | Поставщики | loadProducts, getSupplierSettings |
| ozon, ozonFbo, ozonFbs | Ozon | getOzonStocks, getOzonFboOrders |
| agent | ИИ-помощник | **chat**, **chatStatus** |
| ImportTask | Импорт | updateForecastFromFile |

### 2.2 ИИ-агент (`api/lib/agent.js`)

- **POST /agent/chat** — запуск Cursor Agent. Тело: `{ prompt, history }`. Ответ: `{ jobId }`.
- **GET /agent/chatStatus?jobId=xxx** — polling результата. Ответ: `{ content, done }`.
- Маркер конца: `__AGENT_DONE__` в файле.
- CWD агента: `analytics/` (относительно api).
- `CURSOR_API_KEY` в .env — обязателен.

### 2.3 Система задач (JobManager)

- **Файлы:** `api/lib/jobManager.js`, `api/lib/jobsInit.js`, `api/lib/jobHandlers/*`
- **Модель:** `api/models/Job.js` (Sequelize, SQLite/MySQL)
- **Типы:** sync_wb_reviews, sync_ozon_reviews, load_ozon_orders, load_ozon_stocks, update_wb_competitors_prices, update_ozon_competitors_prices, update_magok_content, analyze_wb_content
- **Cron:** 02:00 WB, 03:00 Ozon, 04:00 Ozon orders, 05:00 Ozon stocks, 06:00 WB competitors, 07:00 Magok/Ozon competitors
- **DISABLE_MARKET_JOBS=true** — отключить задачи маркетов

### 2.4 Роли и доступ

| Маршрут | Роли |
|---------|------|
| /agent/* | admin |
| /jobs/* | admin, user |
| /admin/* | admin |

---

## 3. MagAPI (magapi/) — порт 9001

### 3.1 Маршруты

`POST /mag/:lib/:fn`

| lib | Функции |
|-----|---------|
| markets | getDopRekvizit, getGroups, getNomenclature, getImages |
| mag | getGroups, getPaymentRequests, getForecastScenarios, updateForecastFromFile |
| cards | search, filterValues, getSupplierOrderInfo |
| contractorProducer | getContractors, getProducers, calcNormalizedRoic |

### 3.2 База данных

- **MSSQL** mag_pbi (prdsql)
- **Файлы:** `magapi/dbconfig.js`, `magapi/lib/markets.js`, `mag.js`, `cards.js`
- **Swagger:** `/docs` — OpenAPI

---

## 4. Quasar (quasar/) — frontend

### 4.1 Конфигурация

- **settings.js:** baseURL (magapi), authURL (api), MAG_SECRET, AUTH_SECRET
- **Роли:** admin, user, stocks, supplier_products, markets_products, uploader, image_uploader, pay, agent

### 4.2 Страницы и роуты

| Path | Роли | Страница |
|------|------|----------|
| / | — | IndexPage |
| /auth | — | PageLogin |
| /stocks | admin, stocks | PageStocksNew — остатки, прогноз |
| /where_in_ozon | admin | PageWhereInOzon |
| /where_goods | admin | PageWhereGoods |
| /time_line | admin | PageTimeLine |
| /potential_orders | admin | PagePotentialOrders |
| /supplier_orders | admin, pay, stocks | PageSupplierOrders |
| /supplier_products | admin | PageSupplierProducts |
| /markets_products | admin | PageMarketsProducts |
| /uploader | admin | PageFileUploader |
| /image_uploader | admin | PageProductImageUploader |
| /pay | admin | PagePayments |
| **/agent** | **admin** | **PageAgent — чат с ИИ** |
| /admin, /admin/jobs-log | admin | Админка, лог задач |

### 4.3 Ключевые компоненты отчётов

- **stocksNew/** — PageStocksNew, ForecastView, CardView, AnalyticsCol
- **ForecastView.vue** — прогноз дефицита, план по месяцам
- **AnalyticsCol.vue** — ROIC, средний остаток, ТН
- **MainLayout.vue** — меню, корзина, drawer

---

## 5. Аналитика (analytics/)

### 5.1 Файлы базы знаний

- **01_ПОЛНАЯ_СТРУКТУРА_PBI_И_SQL.md** — таблицы, представления, процедуры, PBI-источники. Использовать при трассировке мер и работе с SQL.
- **02_КОММЕНТАРИИ_ДЛЯ_ИИ_ПОМОЩНИКА.md** — этот файл.

### 5.2 Правила данных (соблюдать)

- **Stock quantity:** только `quantity`. Не `sellable_stock`.
- **MP stock:** отдельно.
- **Входящие заказы:** В пути, В производстве, Выгружен на складе, Согласован.
- **Интервалы:** `[start, end)`.

### 5.3 Дефицит и прогноз

1. `analytics.forecast` + `sp_build_deficit_proposal` → `deficit_proposal`
2. `sp_rebuild_stock_plan_by_arrival` → `stock_plan_by_arrival`
3. opening_qty из `pbi.w_ostatok_da_net`

---

## 6. Рекомендации для ИИ-помощника

### 6.1 При ответах

- Аналитика: использовать `01_ПОЛНАЯ_СТРУКТУРА_PBI_И_SQL.md`.
- Не выдумывать объекты схемы — только из файлов.
- Отвечать на русском.

### 6.2 При доработке

- API: Express, JWT, checkRole.
- Quasar: Vue 3, Pinia.
- Аналитика: quantity, не sellable_stock.

### 6.3 Безопасность

- Ключи Ozon, WB, CURSOR_API_KEY — в .env.
- JWT_SECRET, MAG_SECRET, AUTH_SECRET — в .env.

### 6.4 Типичные проблемы

- **Остатки не сходятся:** фильтр `Категория склада <> Виртуальный`, источник ostatki_short vs w_ostatok_da_net.
- **Меры PBI пустые:** связи с .Календарь, REMOVEFILTERS.
- **Дефицит не считается:** выполнить sp_build_deficit_proposal до sp_rebuild_stock_plan_by_arrival.
- **Агент не отвечает:** CURSOR_API_KEY, путь agent.exe (Windows).

---

## 7. Файлы для быстрого поиска

| Вопрос | Файл |
|--------|------|
| Структура SQL/PBI | analytics/01_ПОЛНАЯ_СТРУКТУРА_PBI_И_SQL.md |
| Этот документ | analytics/02_КОММЕНТАРИИ_ДЛЯ_ИИ_ПОМОЩНИКА.md |
| API маршруты | api/api.js |
| ИИ-агент | api/lib/agent.js |
| Задачи cron | api/lib/jobsInit.js |
| Роуты frontend | quasar/src/router/routes.js |
| Настройки | quasar/src/config/settings.js |
| Схема SQL | analytics/sql_db_mag_pbi/mag_pbi_schema.sql |
| Меры PBI | analytics/pbi/model/report/Model/tables/Основной отчет.tmdl |
| Cursor rules | .cursor/rules/analize.mdc |

---

*Документ для загрузки на сервер и использования ИИ-помощником при работе с проектом MAG.*