# Инструкция по установке и эксплуатации ПО «Диспетчер заявок»

## 1. Состав дистрибутива

```
dispatcher-1.0.0/
├── backend/            исходный код серверной части и веб-интерфейса
├── requirements.txt    перечень программных зависимостей с фиксацией версий
├── Dockerfile          описание сборки контейнера
├── docker-compose.yml  описание запуска связки «приложение + СУБД»
└── docs/               эксплуатационная документация
```

## 2. Требования к программному окружению

- Операционная система семейства Linux (Astra Linux SE, ALT Linux, РЕД ОС,
  Ubuntu 22.04 LTS и совместимые).
- Python версии 3.11 или выше **либо** Docker версии 24 и выше.
- PostgreSQL версии 13 и выше (для промышленной эксплуатации).

## 3. Установка в контейнере (рекомендуемый способ)

1. Распаковать дистрибутив в каталог `/opt/dispatcher`.
2. Создать файл `.env` в каталоге дистрибутива:

```
SECRET_KEY=<случайная строка не менее 32 символов>
DB_PASSWORD=<пароль СУБД>
ADMIN_EMAIL=admin@organization.ru
ADMIN_PASSWORD=<пароль администратора>
```

3. Выполнить сборку и запуск:

```bash
docker compose up -d --build
```

4. Убедиться в работоспособности:

```bash
curl http://localhost:8000/api/health
```

Ожидаемый ответ: `{"status":"ok","service":"Диспетчер заявок","version":"1.0.0"}`.

5. Открыть веб-интерфейс по адресу `http://<адрес сервера>:8000/` и войти под
   учётной записью администратора, заданной в файле `.env`.

## 4. Установка без контейнеризации

Особенность ОС «АЛЬТ»: модуль sqlite3 и совместимая библиотека потоков
поставляются отдельными пакетами. Перед установкой выполнить:

```bash
apt-get install -y python3 python3-module-pip python3-modules-sqlite3 glibc-pthread
```

Далее — общий порядок для всех ОС семейства Linux:

```bash
python3.11 -m venv /opt/dispatcher/.venv
/opt/dispatcher/.venv/bin/pip install -r /opt/dispatcher/requirements.txt
export DATABASE_URL="postgresql+psycopg2://dispatcher:<пароль>@localhost:5432/dispatcher"
export SECRET_KEY="<случайная строка не менее 32 символов>"
export ADMIN_EMAIL="admin@organization.ru"
export ADMIN_PASSWORD="<пароль администратора>"
/opt/dispatcher/.venv/bin/uvicorn backend.app.main:app --host 0.0.0.0 --port 8000
```

Схема базы данных и учётная запись администратора создаются автоматически при
первом запуске.

Для запуска в качестве системной службы используется файл
`/etc/systemd/system/dispatcher.service`:

```ini
[Unit]
Description=Диспетчер заявок
After=network.target postgresql.service

[Service]
User=dispatcher
WorkingDirectory=/opt/dispatcher
EnvironmentFile=/opt/dispatcher/.env
ExecStart=/opt/dispatcher/.venv/bin/uvicorn backend.app.main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload && systemctl enable --now dispatcher
```

## 5. Параметры настройки

| Переменная окружения | Назначение | Значение по умолчанию |
|---|---|---|
| `DATABASE_URL` | строка подключения к СУБД | `sqlite:///./dispatcher.db` |
| `SECRET_KEY` | ключ подписи токенов доступа | `dev-secret-change-me` |
| `TOKEN_TTL_HOURS` | срок действия токена, часов | `12` |
| `ADMIN_EMAIL` | учётная запись администратора | `admin@example.ru` |
| `ADMIN_PASSWORD` | пароль администратора | `admin12345` |
| `ATTACHMENTS_DIR` | каталог хранения вложений | `./attachments` |
| `MAX_UPLOAD_MB` | предельный размер вложения, МБ | `10` |
| `SEED_DEMO_DATA` | загрузка демонстрационных данных (`1` — включить) | `0` |

**Обязательно к исполнению при промышленной эксплуатации:** значения
`SECRET_KEY` и `ADMIN_PASSWORD` подлежат замене на уникальные. Значения по
умолчанию предназначены исключительно для ознакомительной установки.

## 6. Эксплуатация

### 6.1. Резервное копирование

```bash
pg_dump -U dispatcher dispatcher | gzip > /var/backups/dispatcher-$(date +%F).sql.gz
tar -czf /var/backups/attachments-$(date +%F).tar.gz -C /opt/dispatcher attachments
```

Резервному копированию подлежат и база данных, и каталог вложений.

Рекомендуемая периодичность — ежесуточно, срок хранения копий — не менее 30 суток.

### 6.2. Восстановление

```bash
gunzip -c /var/backups/dispatcher-<дата>.sql.gz | psql -U dispatcher dispatcher
```

### 6.3. Контроль работоспособности

Состояние приложения контролируется обращением к `/api/health`. При штатной
работе возвращается код 200. Журнал работы приложения доступен командой
`journalctl -u dispatcher` либо `docker compose logs app`.

### 6.4. Обновление версии

1. Выполнить резервное копирование базы данных.
2. Остановить службу.
3. Заменить каталог с дистрибутивом на новую версию.
4. Установить зависимости новой версии.
5. Запустить службу и проверить `/api/health`.

## 7. Рекомендации по защите информации

- Публикация сервиса пользователям осуществляется через обратный прокси-сервер
  (nginx, Angie) с использованием протокола TLS.
- Прямой доступ к порту 8000 из внешней сети закрывается средствами межсетевого
  экранирования.
- Доступ к СУБД ограничивается адресом узла приложения.
- Пароли пользователей задаются длиной не менее 8 символов; смена пароля
  администратора выполняется после первичной установки.