Support Operator Panel

Applied support-workflow prototype — an operator-facing web panel that connects calls, roles and analytics with a separate semantic retrieval and reranking component for knowledge-base answers.

Case overview

Problem. Contact-centre operators need relevant scripts and operational context without switching between disconnected tools during a call.

Workflow. Operator UI → FastAPI API → knowledge-base retrieval service → embed → retrieve → rerank → suggested material in the operator workflow.

My contribution. I worked on the operator workflow and product engineering across the FastAPI/PostgreSQL backend, API integration, roles, calls and retrieval-oriented support tooling.

Status and boundary. This is a validated workflow / functional prototype, not a corporate production deployment. The workflow was tested by its owner; planned corporate rollout did not proceed because of information-security requirements. Use only synthetic or properly authorized support data.

Architecture diagram

flowchart TD
    subgraph Client ["Operator Workspace (React 19 / TypeScript)"]
        UI["Operator Interface (HomePage)"]
        Form["Call Form & Live Timer"]
        KBPanel["Knowledge Search Box (Ctrl+S)"]
    end

    subgraph Backend ["FastAPI Core Services (Python 3.12)"]
        Auth["JWT Auth & RBAC"]
        CallAPI["Call & Analytics API"]
        SearchAPI["Knowledge Search Integration"]
    end

    subgraph Retrieval ["Semantic Subsystem (assist-craft-qna)"]
        RetrievalAPI["Retrieval & Rerank API"]
        Embedder["Vector Search (Embeddings)"]
        Reranker["Cross-Encoder Reranker"]
        KB[("Knowledge Base Store")]
    end

    subgraph Storage ["Persistence Layer"]
        PG[("PostgreSQL 16 (Calls, Users, Scripts, Audit)")]
    end

    UI -->|"1. User Action"| Auth
    Form -->|"2. Log Call (Ctrl+Enter)"| CallAPI
    CallAPI -->|"3. Save & Audit"| PG
    KBPanel -->|"4. Query Knowledge Base"| SearchAPI
    SearchAPI -->|"5. HTTP Request"| RetrievalAPI
    RetrievalAPI --> Embedder
    Embedder --> KB
    Embedder -->|"Candidate Documents"| Reranker
    Reranker -->|"6. Ranked Results & Scores"| SearchAPI
    SearchAPI -->|"7. Render Suggestions"| KBPanel

See assist-craft-qna for the public retrieval component. The two repositories deliberately use different stacks and form one umbrella case rather than a single application.

Умная веб-панель для операторов контакт-центра. Создана как помощник, а не инструмент контроля! Фокус на максимальном удобстве интерфейса (минимальная когнитивная нагрузка) и мощных AI-алгоритмах поиска по базе скриптов.

✨ Возможности

🎯 Удобство для операторов

Продуманный UX/UI — чистый интерфейс, где форма звонка и подсказки интегрированы в одно рабочее окно
Поиск по базе знаний — поиск нужных скриптов и руководств по ключевым словам или смыслу
Автоматизация рутины — таймер звонка запускается сам, а шаблоны подсказывают готовые ответы
Топ актуальных вопросов — всегда под рукой статистика по частым проблемам клиентов
Горячие клавиши — управление без мышки: Ctrl+Enter сохранить, Ctrl+S поиск по базе

📊 Для руководителей

Аналитический дашборд — KPI, графики, статистика
История звонков — поиск, фильтры, редактирование
Управление пользователями — роли, временные права
Справочники — регионы, отделы, типы звонков
Ревью скриптов — модерация предложений операторов

🛠 Технологический стек

Frontend

Backend

Database

DevOps

🚀 Быстрый старт

Требования

Docker Desktop с WSL 2 (для Windows)
Git

Запуск

# 1. Клонировать репозиторий
git clone https://github.com/laser54/support_operator_panel.git
cd support_operator_panel

# 2. Запустить все сервисы
docker-compose up --build -d

# 3. Применить миграции
docker-compose exec backend uv run alembic upgrade head

# 4. Создать администратора
docker-compose exec backend uv run python create_admin.py

# 5. (Опционально) Загрузить тестовые данные
docker-compose exec backend uv run python load_fixtures.py

Доступ

Сервис	URL
🌐 Frontend	http://localhost:3001
📚 API Docs	http://localhost:8000/docs
🔧 API Health	http://localhost:8000/

Локальный доступ: создайте отдельного администратора командой выше. Не используйте общие или предустановленные учётные данные в публичном развёртывании.

📁 Структура проекта

support_operator_panel/
├── 📂 backend/                 # FastAPI приложение
│   ├── 📂 app/
│   │   ├── 📂 api/v1/          # REST API endpoints
│   │   │   ├── auth.py         # Аутентификация (JWT)
│   │   │   ├── calls.py        # CRUD звонков
│   │   │   ├── users.py        # Управление пользователями
│   │   │   ├── scripts.py      # Скрипты и ревью
│   │   │   ├── search.py       # AI-поиск по базе знаний
│   │   │   └── ...             # Справочники
│   │   ├── 📂 models/          # SQLAlchemy ORM модели
│   │   ├── 📂 schemas/         # Pydantic валидация
│   │   ├── 📂 services/        # Бизнес-логика
│   │   └── 📂 core/            # Конфигурация, безопасность
│   ├── 📂 alembic/             # Миграции БД
│   └── 📂 fixtures/            # Тестовые данные
│
├── 📂 frontend/                # React SPA
│   └── 📂 src/
│       ├── 📂 pages/           # Страницы приложения
│       │   ├── HomePage.tsx    # Рабочее место оператора
│       │   ├── HistoryPage.tsx # История звонков
│       │   ├── DashboardPage.tsx # Аналитика
│       │   ├── UsersPage.tsx   # Управление пользователями
│       │   └── ...
│       ├── 📂 components/      # React компоненты
│       │   ├── OperatorForm.tsx    # Форма звонка
│       │   ├── KnowledgePanel.tsx  # Панель базы знаний
│       │   ├── 📂 ui/              # shadcn/ui компоненты
│       │   └── 📂 layout/          # Layout компоненты
│       ├── 📂 api/             # Axios клиент
│       └── 📂 hooks/           # Custom React hooks
│
├── 📂 docs/                    # Документация
├── 📂 .github/workflows/       # CI/CD
└── docker-compose.yml          # Docker конфигурация

👥 Роли и права

Роль	Описание	Доступ
Operator	Оператор контакт-центра	Звонки, история (свои), поиск
Supervisor	Руководитель группы	+ Дашборд, ревью скриптов, все звонки
Admin	Администратор	+ Пользователи, справочники

💡 Поддерживаются временные роли — можно выдать повышенные права на определённый срок

⌨️ Горячие клавиши

Комбинация	Действие
`Ctrl + Enter`	Сохранить звонок
`Ctrl + S`	Фокус на поиск в базе знаний
`Escape`	Очистить форму (с подтверждением)

🔧 Команды разработки

Make (WSL/Linux)

make dev          # Запустить с hot reload
make up           # Запустить в фоне
make down         # Остановить
make db-migrate   # Применить миграции
make db-shell     # Подключиться к PostgreSQL
make lint         # Проверить код
make lint-fix     # Автоисправление

Docker (любая ОС)

docker-compose up --build -d          # Запустить
docker-compose down                   # Остановить
docker-compose logs -f backend        # Логи бэкенда
docker-compose exec backend uv run alembic upgrade head  # Миграции

Локальная разработка

Backend:

cd backend
uv sync                                    # Установить зависимости
uv run uvicorn app.main:app --reload       # Запустить dev server
uv run alembic revision --autogenerate -m "msg"  # Создать миграцию

Frontend:

cd frontend
pnpm install        # Установить зависимости
pnpm dev            # Запустить dev server
pnpm build          # Сборка для продакшена
pnpm lint           # Проверка ESLint

⚙️ Конфигурация

Backend (.env)

DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/support_panel
SECRET_KEY=your-secret-key-here
FRONTEND_URL=http://localhost:3001
KNOWLEDGE_BASE_URL=https://your-kb-api.com
KNOWLEDGE_BASE_PASSWORD=secret

Frontend (frontend/.env)

VITE_API_URL=http://localhost:8000/api/v1

📊 API Endpoints

Развернуть полный список

Method	Endpoint	Описание	Роль
`POST`	`/api/v1/auth/login`	Вход	Все
`GET`	`/api/v1/auth/me`	Текущий пользователь	Все
`GET`	`/api/v1/calls`	Список звонков	Все*
`POST`	`/api/v1/calls`	Создать звонок	Все
`PATCH`	`/api/v1/calls/{id}`	Редактировать звонок	Все*
`GET`	`/api/v1/search`	Поиск в базе знаний	Все
`GET`	`/api/v1/scripts/top-questions`	Топ вопросов	Все
`GET`	`/api/v1/scripts/review`	Скрипты на ревью	Admin/Supervisor
`GET`	`/api/v1/users`	Список пользователей	Admin
`POST`	`/api/v1/users`	Создать пользователя	Admin
`GET`	`/api/v1/regions`	Регионы	Все
`GET`	`/api/v1/departments`	Отделы	Все
`GET`	`/api/v1/call-types`	Типы звонков	Все
`GET`	`/api/v1/call-resolutions`	Резолюции	Все

* Операторы видят только свои звонки

🐛 Troubleshooting

Порт занят

# Остановить все контейнеры
docker-compose down

# Или найти процесс
netstat -ano | findstr :8000

База данных не подключается

# Проверить статус
docker-compose ps

# Посмотреть логи
docker-compose logs db
docker-compose logs backend

# Пересоздать контейнеры
docker-compose down -v
docker-compose up --build -d

Миграции не применяются

# Убедиться что БД запущена
docker-compose ps

# Применить миграции вручную
docker-compose exec backend uv run alembic upgrade head

# Проверить текущую версию
docker-compose exec backend uv run alembic current

📚 Документация

Masterplan — Видение проекта
Tech Stack — Технологии и правила
App Flow — Роли и страницы
Design Guidelines — UI/UX гайдлайны
DevOps Strategy — CI/CD и деплой

📈 Статус разработки

~~Phase 0: Инициализация~~
~~Phase 1: Backend & Database~~
~~Phase 2: Frontend Core~~
~~Phase 3: Search Integration~~
~~Phase 4: Dashboard & Analytics~~
Phase 5: Production Deploy

Made with ❤️ for Support operator Contact Center

Name		Name	Last commit message	Last commit date
.agent		.agent
.cursor/skills/frontend-design		.cursor/skills/frontend-design
.github/workflows		.github/workflows
backend		backend
docs		docs
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
QUICKSTART_GITBASH.md		QUICKSTART_GITBASH.md
README.md		README.md
cookies.txt		cookies.txt
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
start.bat		start.bat
start.sh		start.sh
token.json		token.json

Navigation Menu

Repository files navigation

Support Operator Panel

Case overview

Architecture diagram

✨ Возможности

🎯 Удобство для операторов

📊 Для руководителей

🛠 Технологический стек

🚀 Быстрый старт

Требования

Запуск

Доступ

📁 Структура проекта

👥 Роли и права

⌨️ Горячие клавиши

🔧 Команды разработки

Make (WSL/Linux)

Docker (любая ОС)

Локальная разработка

⚙️ Конфигурация

Backend (.env)

Frontend (frontend/.env)

📊 API Endpoints

🐛 Troubleshooting

📚 Документация

📈 Статус разработки

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Support Operator Panel

Case overview

Architecture diagram

✨ Возможности

🎯 Удобство для операторов

📊 Для руководителей

🛠 Технологический стек

🚀 Быстрый старт

Требования

Запуск

Доступ

📁 Структура проекта

👥 Роли и права

⌨️ Горячие клавиши

🔧 Команды разработки

Make (WSL/Linux)

Docker (любая ОС)

Локальная разработка

⚙️ Конфигурация

Backend (.env)

Frontend (frontend/.env)

📊 API Endpoints

🐛 Troubleshooting

📚 Документация

📈 Статус разработки

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages