# Структура аналитики: SQL и Power BI

Справочник, объединяющий правила из `context/*.md` со структурой БД и PBI-модели.

---

## 1. Правила данных (01_DATA_RULES)

| Правило | Описание |
|---------|----------|
| Stock quantity | Только поле `quantity`. **Никогда** не использовать `sellable_stock` в расчётах остатков |
| MP stock | Остатки маркетплейса считаются отдельно и добавляются при необходимости |
| Входящие заказы | Статусы: `В пути`, `В производстве`, `Выгружен на складе`, `Согласован` |
| Интервалы дат | Формат `[start, end)` (полуоткрытый интервал) при агрегации |

---

## 2. Глоссарий (02_GLOSSARY)

| Термин | Значение |
|--------|----------|
| Stock (шт) | Физическое количество по полю `quantity` |
| Stock (руб) | Денежная оценка остатков |
| MP | Marketplace (маркетплейс) |
| Data mart | SQL view/table, подготовленная для аналитики |

---

## 3. SQL: Таблицы (analytics schema)

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

| Таблица | Назначение | Ключевые поля |
|---------|------------|---------------|
| `analytics.forecast` | Прогноз спроса по месяцам | scenario_id, 1c_id, code, month, value |
| `analytics.deficit_proposal` | Рекомендации к заказу по дефициту | place_month, arrival_month, order_qty |
| `analytics.stock_plan_by_arrival` | План по месяцам прихода | opening, inbound_confirmed, inbound_deficit, forecast_demand, closing |
| `analytics.forecast_scenarios` | Сценарии прогноза | scenario_id, name |
| `analytics.seasonality_groups` | Сезонность по группам (для sp_build_forecast_s4_by_group) | — |
| `stg.forecast_load` | Staging загрузки прогноза из Excel | — |

### 3.2 Справочники и остатки (pbi schema)

| Таблица | Назначение |
|---------|------------|
| `pbi.nomenclature` | Номенклатура (minAvailableQty для minAvailable) |
| `pbi.groups` | Группы (path для group_path) |
| `pbi.w_ostatok_da_net` | Остаток на дату (для opening_qty) |

---

## 4. SQL: Представления (Views)

| View | Назначение | Источники |
|------|------------|-----------|
| `analytics.get_orders_by_group` | Входящие заказы по группе | Заказы со статусами 01_DATA_RULES |
| `analytics.get_quantity_by_group` | Остаток склада по группе | quantity (не sellable_stock) |
| `analytics.get_mp_quantity_by_group` | MP-остатки по группе | — |
| `analytics.get_forecast_by_group` | Прогноз по группе | analytics.forecast |
| `analytics.get_forecast_scenarios` | Сценарии прогноза | analytics.forecast_scenarios |
| `analytics.deficit_orders` | Заказы по дефициту с ценой и суммой | deficit_proposal + nomenclature (status='Дефицит') |

---

## 5. SQL: Хранимые процедуры

### 5.1 Цепочка дефицита (06_DEFICIT_FORECAST)

```
forecast → sp_build_deficit_proposal → deficit_proposal
                      ↑                              ↓
stock + inbound +     │              sp_rebuild_stock_plan_by_arrival
minAvail              └──────────────────── stock_plan_by_arrival
```

### 5.2 Процедуры

| Процедура | Назначение | Параметры по умолчанию |
|-----------|------------|------------------------|
| `sp_build_deficit_proposal` | Дефицит и рекомендации к заказу | @scenario_id=4, @group_path='', @lead_time_m=4, @cover_months=6 |
| `sp_rebuild_stock_plan_by_arrival` | План остатков по месяцам прихода | @scenario_id, @from_month, @to_month |
| `sp_run_deficit_all_skus` | Пересчёт дефицита по всем SKU | Вызывает sp_build_deficit_proposal с group_path='' |
| `create_forecast_loop` | Цикл по группам (lvl=2) | — |
| `sp_build_forecast_s4_by_group` | Прогноз по группе (rate×дни×seasonal_koef) | Вставляет в forecast |
| `sp_загрузка_прогноза_закупки` | Загрузка прогноза из Excel | forecast scenario_id=8 |

### 5.3 Рекомендуемый порядок выполнения

1. **Прогноз:** `create_forecast_loop` ИЛИ `sp_build_forecast_s4_by_group` ИЛИ `sp_загрузка_прогноза_закупки`
2. **Дефицит:** `sp_build_deficit_proposal` ИЛИ `sp_run_deficit_all_skus`
3. **План:** `sp_rebuild_stock_plan_by_arrival` (читает deficit_proposal; п.2 должен быть выполнен первым)

### 5.4 Формула closing (stock_plan_by_arrival)

```
closing = opening + inbound_confirmed + inbound_deficit - forecast_demand
```

---

## 6. Power BI: Модель (TMDL)

### 6.1 Таблицы модели (PBI QueryOrder)

| Таблица | Источник |
|---------|----------|
| Номенклатура | Sql.Database |
| Партнер | Sql.Database |
| Стоимость МП | Sql.Database |
| Основной отчет | Sql.Database |
| Группы | Sql.Database |
| Остатки | Sql.Database |
| Закупки | Sql.Database |
| Заявки на оплату | Sql.Database |
| План продаж менеджеров | Sql.Database |
| План продаж по группам | Sql.Database |
| Менеджеры | Sql.Database |
| mp остатки | Sql.Database |
| mp аналитика продаж | Sql.Database |
| ПРАЙСлист | Sql.Database |
| Заказы все | Sql.Database |
| ... (см. model.tmdl) | — |

### 6.2 Связи и меры

- Связи: `relationships.tmdl`
- Меры: `expressions.tmdl`, таблицы `.tmdl` в `Model/tables/`
- Культура: ru-RU
- Compatibility level: 1600

---

## 7. Workflow: Trace Measure (03_WORKFLOWS, 05_OUTPUT_FORMATS)

### Последовательность

1. Найти меру в TMDL
2. Показать DAX
3. Указать зависимые меры/таблицы
4. Извлечь SQL source из partition (Sql.Database, Schema, Item или Query)
5. Сформировать объяснение

### Формат вывода

1. Measure Name
2. DAX Formula
3. Dependencies
4. SQL Source (server, database, schema, object)
5. Business Explanation
6. Usage Recommendations
7. Validation Checks

---

## 8. Workflow: Trace Deficit / Forecast

1. Прогноз → `sp_build_deficit_proposal` → deficit_proposal
2. deficit_proposal + forecast + inbound → `sp_rebuild_stock_plan_by_arrival` → stock_plan_by_arrival
3. order_qty = прогноз окна [T .. T+cover); дефицит при net_stock < minAvailable

---

## 9. Knowledge Base Policy (04_KB_POLICY)

- Новая документация — черновик
- Только утверждённое содержание — в общую базу знаний
- Хранить в `/docs/metrics`
- Каждая статья: DAX, SQL lineage, бизнес-объяснение

---

## 10. AI Architect (00_SYSTEM)

- Трассировка мер от TMDL к SQL
- Структурированные объяснения метрик
- Соблюдение правил данных
- **Не придумывать** объекты схемы — только из файлов проекта
- Трассировка дефицита/прогноза с процедурами