перед внедрением веб интерфейса и API для взаимодействием с gemini.

HOWTO/работа с кодом.md

@@ -0,0 +1,73 @@
+# 🛠 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`).