analytics/02_КОММЕНТАРИИ_ДЛЯ_ИИ_ПОМОЩНИКА.md

Описание проекта 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.