alebedev/analytics
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Basoff 2026-02-25 11:57:12 +03:00
parent 366e5c59a0
commit 4295a14305
1 changed files with 0 additions and 211 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

211
02_КОММЕНТАРИИ_ДЛЯ_ИИ_ПОМОЩНИКА.md
View File

@ -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.*