212 lines
9.1 KiB
Markdown
212 lines
9.1 KiB
Markdown
# Описание проекта 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 }`.
|
||
- **GET /agent/repoInfo** — URL для git clone и дата последнего коммита. Ответ: `{ cloneUrl, lastUpdated, cloneCommand }`.
|
||
- Маркер конца: `__AGENT_DONE__` в файле.
|
||
- CWD агента: `analytics/` (по умолчанию) или `ANALYTICS_REPO_PATH` из .env.
|
||
- **Переменные .env:** `CURSOR_API_KEY` (обязательно), `ANALYTICS_REPO_PATH` (путь к репо, напр. `/home/mag/analytics`), `ANALYTICS_GIT_CLONE_URL` (если git remote не настроен).
|
||
|
||
### 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.*
|