docs: complete enterprise architecture map, AI agent playbook and disaster recovery guides

AI_AGENT_PLAYBOOK.md

@@ -0,0 +1,168 @@
+# 🤖 AI Agent Playbook & Safety Protocol (KSP Steel)
+
+> **ВНИМАНИЕ ДЛЯ AI-АГЕНТОВ (LLM / Copilot / Autonomous Agents):**  
+> Вы работаете с критической производственной и информационной инфраструктурой промышленного металлургического предприятия ТОО «KSP Steel».  
+> Любое некорректное действие может повлиять на мониторинг безопасности завода, работу почты и контроллеров домена.  
+> **Ознакомьтесь с этим документом перед выполнением любых задач.**
+
+---
+
+## 🛑 Правило №1: «НЕ СЛОМАЙ НИЧЕГО» (Safety First)
+
+Любые изменения должны подчиняться четырем железным принципам:
+
+1. **Обязательный бэкап перед изменением любого файла**:
+   ```bash
+   # Перед редактированием ВСЕГДА делайте копию с таймстемпом:
+   cp filename filename.bak_$(date +%Y%m%d_%H%M%S)
+   ```
+2. **Сначала Read-Only диагностика**:
+   Перед изменением или перезапуском любого сервиса проверьте его текущее состояние и статус:
+   ```bash
+   systemctl status <service>
+   docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
+   journalctl -u <service> -n 50 --no-pager
+   ```
+3. **Обязательная валидация синтаксиса до перезапуска**:
+   - Nginx: `nginx -t`
+   - Docker Compose: `docker compose config`
+   - Python: `python3 -m py_compile <script.py>`
+   - Ansible: `ansible-playbook --syntax-check <playbook.yaml>`
+4. **Безопасность учетных данных (Zero Plaintext Secrets)**:
+   - **СТРОГО ЗАПРЕЩЕНО** коммитить в Git реальные пароли, SSH-ключи, токены Telegram или базы данных.
+   - Реальные пароли хранятся **ТОЛЬКО** в HashiCorp Vault (`http://172.16.8.8:8200`).
+   - В Git коммитятся только обезличенные шаблоны (`.env.example`, `config.example.json`).
+
+---
+
+## 🗺️ Архитектурная карта и взаимосвязи проектов
+
+Инфраструктура состоит из 4 взаимосвязанных блоков:
+
+```mermaid
+graph TD
+    User["Пользователь / Администратор"] --> Web["Инфосистема 2.0 (172.16.8.75:8090)"]
+    Web -->|"Интеграция ящиков (?mailbox=)"| MG["MailGuard SOC (172.16.8.151)"]
+    Web -->|"Телеметрия & AD"| DC["Active Directory (172.16.8.9 / 19)"]
+    
+    TG["Telegram Чат (KSP INFO)"] --> Bot["ChatOps Bot (172.16.8.8)"]
+    Bot -->|"Триггер шаблонов"| Sem["Ansible Semaphore (172.16.8.8:3000)"]
+    Sem -->|"Запуск плейбуков"| Playbooks["Ansible Core (172.16.8.8)"]
+    
+    Playbooks -->|"Динамический запрос паролей"| Vault["HashiCorp Vault (172.16.8.8:8200)"]
+    Playbooks -->|"Аудит & Бэкапы"| KVM["Гипервизоры KVM (172.16.15.1)"]
+    Playbooks -->|"Дампы mysqldump"| DB["Кластер MySQL (192.168.220.x)"]
+    Playbooks -->|"Аудит безопасности"| DC
+```
+
+---
+
+## 🔑 Как AI-агенту получить доступ к серверам через Vault
+
+Все root-пароли, учетные записи и мастер-ключи хранятся в защищенном виде в **HashiCorp Vault** (`http://172.16.8.8:8200`).
+
+### Шаг 1: Авторизация в Vault
+```bash
+export VAULT_ADDR="http://172.16.8.8:8200"
+export VAULT_TOKEN="<ВАШ_РООТ_ТОКЕН_VAULT>"
+```
+
+### Шаг 2: Извлечение мастер-ключа SSH (Рекомендуется для беспарольного доступа)
+В Vault хранится закрытый ключ Ed25519, публичная часть которого прописана в `/root/.ssh/authorized_keys` на серверах:
+```bash
+# Получить закрытый ключ SSH и настроить окружение:
+mkdir -p ~/.ssh && chmod 700 ~/.ssh
+curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/master-ssh-key" \
+  | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['private_key'])" > ~/.ssh/id_ed25519
+chmod 600 ~/.ssh/id_ed25519
+
+# Подключение к любому серверу по SSH без запроса пароля:
+ssh root@172.16.8.8     # Сервер автоматизации и Gitea
+ssh root@172.16.8.151   # Почтовый архив MailGuard
+```
+
+### Шаг 3: Получение root-паролей серверов из Vault
+Если требуется прямой пароль root (например, для локального терминала или Web-консоли Proxmox):
+```bash
+# 1. Сервер 172.16.8.8 (Gitea / Vault / Semaphore):
+curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/server-8-8" \
+  | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['password'])"
+
+# 2. Сервер 172.16.8.151 (MailGuard):
+curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/server-151" \
+  | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['password'])"
+
+# 3. KVM гипервизор vm-host01 (172.16.15.1):
+curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/vm-host01" \
+  | python3 -c "import sys, json; print(json.load(sys.stdin)['data']['data']['password'])"
+
+# 4. Серверы баз данных MySQL:
+curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/servers/data/mysql-main" \
+  | python3 -c "import sys, json; d=json.load(sys.stdin)['data']['data']; print('SSH:', d['ssh_password'], 'DB:', d['db_password'])"
+```
+
+---
+
+### 1. `KSP-Steel/Infosystem` (Портал предприятия)
+- **Сервер**: `172.16.8.75` (Proxmox LXC, папка `/opt/infosystem`)
+- **Стек**: Vue 3 (Composition API, TypeScript, Tailwind CSS, Pinia, Lucide icons), FastAPI (Python 3.11), MySQL (порт 3307), Nginx.
+- **Особенности**:
+  - `v2/frontend`: Современный SPA-интерфейс предприятия.
+  - Поддержка быстрого перехода в почтовый архив MailGuard: вызов `resolveMailboxEmail()`, который транслирует внутренние адреса леса домена (`@network.bkv-pvl.kz`) в реальные внешние ящики (`@ksp-steel.kz`), отображая визуально правильный email сотрудника.
+
+### 2. `KSP-Steel/mailguard` (Почтовый архив ИБ)
+- **Сервер**: `172.16.8.151` (папка `/opt/mailguard`)
+- **Стек**: Python 3 worker/ingestion, Meilisearch (полнотекстовый поиск), PostgreSQL, Nginx, Docker.
+- **Особенности**:
+  - Индексирует 700 000+ входящих и исходящих писем завода.
+  - Deep-link механизм: переход по `#mailboxes?mailbox=<email>` автоматически подставляет email в поле поиска, раскрывает буквенную ветку сотрудника в алфавитном дереве и открывает досье переписки справа.
+
+### 3. `KSP-Steel/ansible` (Автоматизация и ChatOps)
+- **Сервер**: `172.16.8.8` (папка `/opt/ansible/playbooks`)
+- **Стек**: Ansible Core 2.15+, Semaphore UI (порт 3000), Python Telegram Bot (`semaphore-bot.service`).
+- **Особенности**:
+  - Плейбуки для аудита безопасности AD (`ad_security_and_health.yaml`), создания учетных записей (`ad_exim_user_onboarding.yaml`), сброса паролей (`ad_user_password_reset.yaml`), мониторинга гипервизора (`vm-host01_health_check.yaml`), дампов MySQL (`mysql_audit_and_dump.yaml`).
+  - Все учетные данные подтягиваются на лету из Vault через lookup-плагин:
+    `{{ lookup('community.hashi_vault.hashi_vault', 'secret=servers/data/...:password') }}`
+
+### 4. `KSP-Steel/hashicorp-vault` (Хранилище секретов)
+- **Сервер**: `172.16.8.8` (папка `/opt/infra`)
+- **Стек**: HashiCorp Vault (`hashicorp/vault:latest`), Gitea, PostgreSQL, Docker Compose.
+- **Особенности**:
+  - Точка входа: `http://172.16.8.8:8200`
+  - Распечатка (Unseal): `/opt/infra/scripts/unseal_vault.sh`
+  - Резервное копирование: `/opt/infra/scripts/backup_vault.sh`
+  - Движок `servers/` (KV v2):
+    - `servers/data/vm-host01` — пароль гипервизора
+    - `servers/data/mysql-main` — пароли основных MySQL
+    - `servers/data/mysql-special` — пароли спец-серверов MySQL
+
+---
+
+## 📋 Пошаговый алгоритм выполнения задач для AI-агента
+
+При получении задачи действуйте строго по этапам:
+
+1. **Исследование (Research)**:
+   - Определите, к какому проекту относится задача.
+   - Прочитайте локальный `README.md` соответствующего репозитория.
+   - Не делайте предположений о путях и портах — проверяйте их через системные конфиги.
+
+2. **Создание плана (Plan)**:
+   - Если задача затрагивает боевые сервисы, составьте план изменений.
+   - Убедитесь, что откат (rollback) возможен в один клик.
+
+3. **Бэкап и внесение изменений (Execute)**:
+   - Создайте бэкап затронутых файлов.
+   - Внесите точечные изменения без переписывания несвязанного функционала.
+   - Сохраняйте существующие комментарии и структуру кода.
+
+4. **Проверка работоспособности (Verify)**:
+   - Проверьте синтаксис конфигов (`nginx -t`, `docker compose config`).
+   - Проверьте статус сервисов (`systemctl is-active`, `docker ps`).
+   - Убедитесь в отсутствии ошибок в логах (`journalctl -n 20`, `docker compose logs --tail=20`).
+
+5. **Фиксация в Git (Commit & Push)**:
+   - Проверьте `git status` и `git diff`.
+   - Напишите информативное сообщение коммита в формате Conventional Commits (`feat(...)`, `fix(...)`, `docs(...)`).
+   - Отправьте коммит в корпоративный Gitea.