# 🛠 HOWTO: Правила внесения изменений и передачи кода в проекте

## 📌 Зачем это нужно
Проект `scud_orion_ai_v2` активно растет (17+ модулей, СУБД SQLite, ИИ-контур). Передача полных файлов кода при каждой мелкой правке сжигает окно контекста LLM, замедляет диалог и приводит к потере ранее внесенных архитектурных фич.

---

## 🎯 Правила для разработчика и ИИ

### 1. Формат передачи изменений
При запросах и ответах используются **точечные фрагменты кода** (Diff-стиль) с указанием привязок.

Любой фрагмент должен содержать:
1. **Точный путь к файлу** (`services/excel_exporter.py`).
2. **Имя целевой функции/класса** (`generate_summary_excel`).
3. **Зацепку (Context Anchor)** — уникальную соседнюю строку или блок `try/except`.

---

## 📐 Шаблоны фрагментов

### Вариант А: Замена существующей логики

> **Файл:** `services/excel_exporter.py`  
> **Функция:** `generate_summary_excel()`  
> **Место:** Строка ~150, блок фильтрации `no_pass_df`  
>
> ❌ **Удалить:**
> ```python
> no_pass_df = merged_df[merged_df.get('no_scud_pass', False) == True]
> ```
>
> ✅ **Вставить:**
> ```python
> if 'no_scud_pass' in merged_df.columns:
>     no_pass_df = merged_df[merged_df['no_scud_pass'] == True]
> else:
>     no_pass_df = pd.DataFrame()
> ```

---

### Вариант Б: Вставка нового условия/блока

> **Файл:** `main.py`  
> **Функция:** `detect_all_anomalies()`  
> **Место:** После цикла `for idx, row in merged_df.iterrows():`
>
> ➕ **Вставить код:**
> ```python
> # ИСКЛЮЧЕНИЯ без документов 1С НЕ пропускаются дальше к аномалиям СКУД
> if is_exc and not has_1c_reason:
>     continue
> ```

---

### Вариант В: Git Unified Diff Format

> **Файл:** `services/data_loader.py`
> ```diff
> @@ def process_scud_anomalies(df_scud, exceptions=None): @@
> -  first_act = '—'
> +  # Сохраняем вычисленную ранее активность из БД/файла
> +  first_act = existing_fa if existing_fa not in ['—', '', 'None'] else '—'
> ```

---

## 🚀 Чек-лист перед запуском
1. Проверить синтаксис через `python -m py_compile <файл.py>`.
2. Запустить скрипт с флагом отладки `python main.py -d`.
3. Убедиться, что снапшот записан в SQLite (`python scripts/db_cli.py snapshots`).