# 🛠 HOWTO: Помощь в технической диагностике системы (`scud_orion_ai_v2`)

Данный документ содержит руководство по работе со служебными диагностическими утилитами проекта. Скрипты предназначены для быстрой оценки состояния базы данных SQLite, анализа файловой структуры и формирования контекстного снимка кодовой базы для ИИ.

---

## 📋 Содержимое папки `scripts/diagnostics/`

Рекомендуется размещать диагностические скрипты в отдельной директории `scripts/diagnostics/`:

1. **`inspect_db.py`** — Инспектор таблиц и записей базы данных SQLite.
2. **`inspect_files.py`** — Сканер дискового пространства и структуры файлов.
3. **`make_code_snapshot.py`** — Генератор единого текстового слепка кода для ИИ.

---

## 🚀 Назначение и запуск утилит

### 1. Инспектор базы данных SQLite (`inspect_db.py`)

* **Назначение:**
  * Проверяет доступность базы данных (`data/scud_orion_ai.db`).
  * Автоматически считывает список всех таблиц и их колонок.
  * Подсчитывает количество записей в каждой таблице (`scud_logs`, `zup_staff`, `zup_absences` и др.).
  * Выводит список всех активных правил из таблицы `ai_knowledge_base`.

* **Команда для запуска:**
  ```bash
  python scripts/diagnostics/inspect_db.py
2. Сканер файловой структуры (inspect_files.py)
Назначение:

Обходит структуру каталогов проекта.

Показывает точный размер каждого файла в байтах и итоговый вес проекта в мегабайтах.

Автоматически игнорирует служебные и временные папки (.git, __pycache__, venv, .venv).

Команда для запуска:

Bash
python scripts/diagnostics/inspect_files.py
3. Генератор контекстного снимка кода (make_code_snapshot.py)
Назначение:

Собирает весь исходный код Python (.py), настройки (.json), инструкции (.md) и скрипты (.sh) в единый файл project_code_snapshot.md.

Исключает тяжелые архивы, логи и виртуальное окружение.

Сформированный файл передается нейросети (LLM) для быстрого погружения в контекст проекта без потери архитектурных деталей.

Команда для запуска:

Bash
python scripts/diagnostics/make_code_snapshot.py
🎯 Чек-лист применения при сбоях
Ошибка или несостыковка в отчетах: запустить inspect_db.py и проверить, заполнены ли таблицы scud_logs и zup_absences.

Передача задачи или кода ИИ-ассистенту: запустить make_code_snapshot.py и прикрепить итоговый project_code_snapshot.md к запросу.