diff --git a/02_КОММЕНТАРИИ_ДЛЯ_ИИ_ПОМОЩНИКА.md b/02_КОММЕНТАРИИ_ДЛЯ_ИИ_ПОМОЩНИКА.md deleted file mode 100644 index 23209cb..0000000 --- a/02_КОММЕНТАРИИ_ДЛЯ_ИИ_ПОМОЩНИКА.md +++ /dev/null @@ -1,211 +0,0 @@ -# Описание проекта 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.*