Регламент ведения документации
Основной принцип
Документация обновляется В ТОМ ЖЕ коммите, что и код. Не после. Не отдельно. Не "потом". Вместе с изменениями.
Когда обязательно обновлять документацию
| Тип изменения | Что обновить |
|---|---|
| Новый API эндпоинт | api/callbox.md или api/shared-admin.md |
| Изменение схемы БД | соответствующий раздел + CHANGELOG |
| Новая конфигурация сервера | infra/servers.md |
| Изменение Asterisk конфигов | asterisk/config.md, asterisk/routing.md |
| Изменение Docker-конфигурации | deploy/docker.md |
| Новый playbook Ansible | deploy/process.md |
| Изменение сетевых правил | infra/network.md |
| Изменение HA/failover | infra/ha.md |
| Изменение процесса деплоя | deploy/process.md |
| Изменение AI-сервисов (STT/TTS/LLM) | ai/stt.md, ai/tts.md, ai/llm.md |
| Добавление/изменение мониторинга | monitoring/prometheus.md, monitoring/grafana.md |
| Изменение биллинга | asterisk/billing.md |
Формат задачи для CC/Аудитора
Каждая задача, затрагивающая архитектуру или конфигурацию, ДОЛЖНА содержать пункт:
=== ОБНОВЛЕНИЕ ДОКУМЕНТАЦИИ ===
Обновить в /opt/docs/callbox-docs/docs/:
- <раздел>/<файл>.md — описание изменений
Пересобрать: /opt/docs/rebuild-docs.sh
Ответственность
- Архитектор (заказчик) — определяет что документировать, проверяет актуальность
- CC — обновляет документацию как часть задачи
- Аудитор — проверяет соответствие документации реальному состоянию
Ревизия
- Еженедельно: CC запускает check-status.yml, сверяет вывод с документацией
- При каждом инциденте: обновить раздел "Известные проблемы" в соответствующей странице
- Ежемесячно: полная ревизия всех разделов — Аудитор проверяет каждый раздел на актуальность
Структура страницы документации
Каждая страница ДОЛЖНА содержать:
- Заголовок — что описывает
- Текущее состояние — как есть сейчас
- Конфигурация — конкретные параметры, IP, порты, пути
- Известные проблемы — текущие issue и workaround
- История изменений — дата и суть последних изменений
Пересборка документации
После редактирования любого .md файла:
# На mon-1:
/opt/docs/rebuild-docs.sh
# Или через Ansible:
ansible-playbook playbooks/deploy-docs.yml
Правила оформления
- Язык: русский
- Формат: Markdown
- Код и команды: в блоках с указанием языка
- Таблицы: для структурированных данных (IP, порты, параметры)
- Без дублирования — ссылки между разделами вместо копирования
Автоматический контроль
1. Ежедневная проверка (cron)
Скрипт /opt/scripts/check-docs-freshness.sh на mon-1:
- Запускается ежедневно в 09:00 (cron sysadmin)
- Сравнивает коммиты в приложениях (lb-1) и документации (mon-1) за 24 часа
- Результат записывается в /var/log/docs-freshness.log
- Если код изменился, но документация нет — выводит предупреждение
2. Git hooks (напоминание при push)
На lb-1 в каждом bare-репозитории (callbox.git, shared-admin.git, suo.git, ansible.git)
установлен post-receive hook, который при каждом push напоминает обновить документацию.
3. Ansible deploy pre-check
Playbook deploy.yml содержит pre-check play в самом начале:
- Подсчитывает коммиты в коде и документации за 24 часа
- Выводит предупреждение если документация не обновлялась
- Не блокирует деплой — только информирует
При обнаружении расхождений — автоматическое уведомление в Telegram через бота @callbox_docs_bot (скрипт /opt/scripts/telegram-notify.sh). По понедельникам — еженедельный OK-отчёт для подтверждения работоспособности мониторинга.