# Runbook реагирования на инциденты

## Паспорт документа

- Статус документа: working reference
- Актуально на: 29 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении production runtime, ownership-модели, мониторинга или rollback-процедуры
- Область применения: production-инциденты Qadam на текущем host-based контуре
- Связанные документы:
  - [Runbook эксплуатации и деплоя](./deployment-runbook.md)
  - [Runbook резервного копирования и восстановления](./backup-restore-runbook.md)
  - [Environment matrix](./environment-matrix.md)

## Цель документа

Этот документ фиксирует канонический порядок действий при production-инциденте. Его задача — убрать импровизацию и сделать реакцию воспроизводимой для любой команды, которая сопровождает Qadam.

## 1. Уровни серьёзности

- `SEV-1` — полная недоступность продукта или риск потери/компрометации данных.
- `SEV-2` — критичный broken flow для значимой части пользователей, но без полной потери сервиса.
- `SEV-3` — частичный сбой, деградация производительности или дефект без немедленного простоя ядра.

## 2. Первые 15 минут

1. Зафиксировать UTC-время начала инцидента.
2. Заморозить деплой и любые несвязанные ручные изменения на сервере.
3. Определить, что именно упало:
   - `qadam-api`
   - `qadam-web`
   - `qadam-roadmap`
   - `nginx`
   - PostgreSQL
   - Redis
   - TLS / домен
4. Проверить живые health endpoints.
5. Принять решение: hotfix, restart, rollback или restore.

## 3. Быстрая диагностика

### Сервисы

```bash
systemctl status qadam-api qadam-web qadam-roadmap nginx
journalctl -u qadam-api -n 200 --no-pager
journalctl -u qadam-web -n 200 --no-pager
journalctl -u qadam-roadmap -n 200 --no-pager
journalctl -u nginx -n 200 --no-pager
```

### Внешняя доступность

```bash
curl -I https://qadam.2fab.app
curl https://qadam.2fab.app/api/v1/health
curl -I https://qadam.2fab.app/api/docs
curl -I -u <login>:<password> https://qadam-roadmap.2fab.app
curl -u <login>:<password> https://qadam-roadmap.2fab.app/api/health
```

### Сетевые сокеты

```bash
ss -ltnp | grep -E ':(80|443|3000|3001|5001|5432|6379)\b'
```

## 4. Типовые сценарии

### API недоступен

Проверить:

- `qadam-api.service`;
- сборку `/data/qadam-core/apps/api/dist/main.js`;
- Prisma migrations;
- локальную доступность PostgreSQL и Redis;
- ошибки в `journalctl -u qadam-api`.

Если проблема в последнем релизе:

1. Откатить код к предыдущему рабочему коммиту.
2. Пересобрать `qadam-core`.
3. Перезапустить `qadam-api`.

Если проблема в данных или миграции:

1. Оценить, можно ли обойтись rollback кода.
2. Если нет, перейти к [backup/restore runbook](./backup-restore-runbook.md).

### Product web недоступен

Проверить:

- `qadam-web.service`;
- наличие `.next/standalone/apps/web/server.js`;
- symlink на `public` и `.next/static`;
- `API_URL` и `NEXT_PUBLIC_API_URL`;
- ошибки в `journalctl -u qadam-web`.

### Roadmap-портал недоступен

Проверить:

- `qadam-roadmap.service`;
- `QADAM_PROJECT_ROOT=/data/qadam-core`;
- `QADAM_ROADMAP_STORAGE_DIR=/var/lib/qadam-roadmap`;
- basic auth на уровне `nginx`;
- `journalctl -u qadam-roadmap`.

### TLS или домен

Проверить:

```bash
systemctl status certbot.timer
certbot certificates
nginx -t
systemctl reload nginx
```

### Auth или cookie-flow сломан

Проверить:

- `JWT_SECRET` и env drift;
- `qadam_at`, `qadam_rt` cookie behavior;
- `POST /api/v1/auth/login`, `POST /api/v1/auth/refresh`, `GET /api/v1/auth/me`;
- доменные ошибки `ACCOUNT_BLOCKED`, `ACCOUNT_UNDER_REVIEW`, `INVALID_CREDENTIALS`;
- совпадение runtime OpenAPI и `docs/architecture/api-routes.md`.

## 5. Когда делать rollback

Rollback обязателен, если выполняется хотя бы одно из условий:

- `SEV-1`, вызванный последним change package;
- критичный бизнес-flow перестал работать после релиза;
- hotfix не устраняет проблему в разумное время;
- ошибка связана с runtime drift или broken build, а не с внешней зависимостью.

Rollback выполняется по [deployment-runbook.md](./deployment-runbook.md), а при риске потери данных — совместно с [backup-restore-runbook.md](./backup-restore-runbook.md).

## 6. Что обязательно зафиксировать после инцидента

- время начала и окончания;
- уровень `SEV`;
- затронутые сервисы и домены;
- root cause или текущую гипотезу;
- какие действия сработали;
- нужен ли follow-up change package;
- требуется ли обновление `current-state`, `deployment-runbook`, `environment-matrix` или `project/project-change-log.md`.

## 7. Пост-инцидентные действия

После восстановления обязательно:

1. Обновить каноническую документацию, если инцидент выявил ложные допущения.
2. Добавить regression test, если сбой был вызван кодом.
3. Добавить запись в [project/project-change-log.md](../project/project-change-log.md), если был hotfix, rollback или изменение runtime.
4. Обновить [project/execution-checkpoints.md](../project/execution-checkpoints.md), если статус крупного этапа изменился.

## 8. Чего нельзя делать

- Нельзя лечить инцидент ручной магией без фиксации действий.
- Нельзя менять production secrets и env без документирования.
- Нельзя выполнять разрушительные git-команды без понимания состояния рабочей директории.
- Нельзя объявлять инцидент закрытым без минимального smoke-check после восстановления.