# IT Secretary CRM — итоговый отчёт (v6.0)

**Продукт:** цифровой сотрудник IT-службы — секретарь первой линии + CRM + ops + биллинг.  
**Версия:** 6.0.0 · пайплайн фаз 0–6 завершён.

---

## 1. Что сделано

Построен полноценный Python-агент и веб-CRM для сисадмина/вайбкодера:

| Блок | Результат |
|------|-----------|
| Секретарь | Вежливый stateful-диалог, классификация, KB, дедуп, автоназначение, L1-закрытие |
| CRM | JWT-роли, заявки, тарифы, публичный статус, оценка клиента |
| Ops | Очередь дня, таймер времени, SLA, runbook-чеклист |
| Каналы | Web-чат, Telegram webhook, email inbound, единый тред |
| Дежурства | Смены, ночная эскалация, учёт дежурного при назначении |
| Биллинг | Тарифы, абонементы, ночной/выходной коэффициент, PDF-счета |
| Hardening | Rate-limit, health/metrics, аудит решений, TOTP 2FA, Postgres-ready + Docker |

---

## 2. Технологии реализации

| Слой | Стек |
|------|------|
| Backend | Python 3.12, **FastAPI**, Uvicorn |
| ORM / БД | **SQLAlchemy 2**, SQLite (dev) / **PostgreSQL** (prod, docker-compose) |
| Auth | JWT (`python-jose`), passlib/bcrypt, **TOTP 2FA** (pyotp + qrcode) |
| UI | Jinja2-шаблоны, vanilla JS/CSS (без тяжёлого SPA) |
| Отчёты | CSV, Excel (`openpyxl`), PDF (`reportlab`) |
| Интеграции | httpx, Telegram Bot API, webhook мониторинга, email intake API |
| LLM (опц.) | OpenAI API для «полировки» ответов секретаря |
| Observability | `/health`, `/ready`, `/metrics` (Prometheus text), аудит `agent_decisions` |
| Deploy | Dockerfile, docker-compose (app + Postgres 16) |

---

## 3. Функционал агента (секретаря)

1. **Приём и диалог** — выясняет проблему, контакты, уточняет 1–2 вопроса, ведёт сессию.
2. **Классификация** — категория, подкатегория, приоритет, confidence; VIP повышает приоритет.
3. **База знаний** — поиск статей, подсказки клиенту, чеклист runbook специалисту.
4. **Дедупликация** — предупреждение о похожих открытых заявках.
5. **Автоназначение** — по навыкам специалиста + учёт **дежурной смены** ночью.
6. **Безопасная диагностика** — DNS/SSL/HTTP по разрешённым хостам клиента.
7. **Память клиента** — активы, тон (формальный/простой), история.
8. **Качество** — оценка ответов агента, summary диалога в заявке.
9. **L1** — черновик диагноза, чеклист с подтверждением шагов, закрытие простых кейсов.
10. **Обучение** — из закрытых заявок черновики статей KB.
11. **Проактив** — истечение SSL/доменов, напоминания waiting_client, **SLA breach → эскалация**.
12. **Мультиканал** — web / Telegram / email → единый ConversationThread.
13. **Аудит решений** — запись classification / ticket_create в `agent_decisions`.
14. **Защита** — rate-limit чата, логина и webhooks.

---

## 4. Роли и интерфейсы

| Роль | Доступ |
|------|--------|
| Клиент | Чат, свои заявки, публичный статус, оценка |
| Специалист | Ops-очередь, таймер, чеклисты, треды |
| Диспетчер | Назначения, дежурства, решения агента |
| Админ | Пользователи, тарифы, отчёты, 2FA, биллинг |

**Страницы:** `/` чат · `/crm` · `/ops` · `/assets` · `/billing` · `/kb` · `/threads` · `/duty` · `/security` (2FA) · `/admin` · `/status/{token}`

**Демо:** `admin/admin123`, `client/client123`, `sysadmin/spec123`, `devops/spec123`, `dispatcher/disp123`

---

## 5. Production-hardening (фаза 6)

- `GET /health`, `GET /ready`, `GET /metrics`
- `GET /api/system/stats`, `GET /api/system/decisions`
- Rate-limit: chat / login / email & Telegram webhooks
- TOTP 2FA: setup → QR → enable; вход с кодом; страница `/security`
- Postgres через `DATABASE_URL=postgresql+psycopg2://...`
- Docker Compose: сервис `db` + `app`

---

## 6. Как запустить

```bash
# локально
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\python main.py
# → http://localhost:8000  ·  API: /docs

# с Postgres
docker compose up --build
```

Конфиг: `.env` / `.env.example` (`SECRET_KEY`, `DATABASE_URL`, Telegram, `WEBHOOK_SECRET`, `REQUIRE_ADMIN_2FA`).

---

## 7. Коммерческая ценность

Готовый **цифровой L1-сотрудник** для небольшой IT-практики или MSP: снижает ручной приём заявок, стандартизирует классификацию и маршрутизацию, даёт прозрачный SLA/таймер, биллинг и клиентский статус — с путём в production (2FA, лимиты, метрики, Postgres).