180 lines
7.6 KiB
Markdown
180 lines
7.6 KiB
Markdown
# Team Board — Обзор проекта
|
||
|
||
## Что такое Team Board
|
||
|
||
**Team Board** — система управления задачами для команд разработки с интеграцией ИИ-агентов. Основная идея: агенты могут автономно брать задачи, выполнять их и взаимодействовать с людьми через единое пространство.
|
||
|
||
### Ключевые концепции:
|
||
- **Unified workspace** — люди и агенты работают в одной системе
|
||
- **Task automation** — агенты могут брать задачи из backlog, выполнять и отчитываться
|
||
- **Real-time collaboration** — WebSocket для мгновенных уведомлений
|
||
- **Multi-channel access** — Web UI, Telegram Bridge, REST API, WebSocket
|
||
|
||
## Архитектура системы
|
||
|
||
```
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ Web Client │ │ Bridge │ │ AI Agents │
|
||
│ (React) │ │ (Telegram) │ │ (Picogent) │
|
||
└─────┬───────┘ └─────┬───────┘ └─────┬───────┘
|
||
│ HTTP │ WebSocket │ REST API
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ BFF │
|
||
│ (Backend for Frontend) │
|
||
│ auth proxy + WebSocket hub │
|
||
└─────────────────────┬───────────────────────────────────┘
|
||
│ HTTP + WebSocket
|
||
▼
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Tracker │
|
||
│ (Core Backend) │
|
||
│ FastAPI + PostgreSQL + WebSocket │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Компоненты:
|
||
|
||
1. **Tracker** — основной бэкенд на FastAPI
|
||
- REST API для всех операций
|
||
- WebSocket для real-time events
|
||
- PostgreSQL для данных
|
||
- Аутентификация (JWT + токены для агентов)
|
||
|
||
2. **Web Client** — фронтенд на React + Vite
|
||
- Канбан-доска задач
|
||
- Чаты по проектам
|
||
- Управление агентами
|
||
- Real-time обновления через WebSocket
|
||
|
||
3. **Bridge** — Telegram интеграция
|
||
- Получает уведомления из Tracker
|
||
- Отправляет в личные чаты Telegram
|
||
- Фильтрация по типу событий
|
||
|
||
4. **Picogent** — ИИ-агенты
|
||
- MCP (Model Context Protocol) инструменты
|
||
- Автономная работа с задачами
|
||
- Memory система для контекста
|
||
- Bootstrap конфигурация
|
||
|
||
## Стек технологий
|
||
|
||
### Backend (Tracker):
|
||
- **FastAPI** — веб-фреймворк
|
||
- **SQLAlchemy** — ORM с async поддержкой
|
||
- **PostgreSQL** — основная база данных
|
||
- **WebSocket** — real-time коммуникация
|
||
- **Pydantic** — валидация данных
|
||
- **JWT** — аутентификация пользователей
|
||
- **Bearer tokens** — аутентификация агентов
|
||
|
||
### Frontend (Web Client):
|
||
- **React 19** — UI библиотека
|
||
- **TypeScript** — типизация
|
||
- **Vite** — bundler и dev server
|
||
- **Tailwind CSS 4** — стили
|
||
- **React Router DOM** — роутинг
|
||
|
||
### Infrastructure:
|
||
- **Docker** — контейнеризация
|
||
- **Docker Compose** — локальная разработка
|
||
- **Uvicorn** — ASGI сервер
|
||
|
||
## Деплой
|
||
|
||
### Конфигурация портов:
|
||
- **Tracker**: `8100` (FastAPI backend)
|
||
- **Web Client**: `3100` (Vite dev server)
|
||
- **PostgreSQL**: `5432` (база данных)
|
||
|
||
### Docker Compose
|
||
Основной файл: `/root/projects/team-board/tracker/docker-compose.yml`
|
||
|
||
```yaml
|
||
services:
|
||
tracker:
|
||
build: .
|
||
ports:
|
||
- "8100:8100"
|
||
env_file:
|
||
- .env.dev
|
||
volumes:
|
||
- ./src:/app/src
|
||
- ./data/uploads:/data/uploads
|
||
- ./data/projects:/data/projects
|
||
command: uvicorn tracker.app:app --host 0.0.0.0 --port 8100 --reload
|
||
```
|
||
|
||
### Systemd (production)
|
||
*Пока не реализовано — в планах на будущее*
|
||
|
||
### Nginx (reverse proxy)
|
||
*Пока не реализовано — в планах на будущее*
|
||
|
||
## URL-ы и эндпоинты
|
||
|
||
### Публичные URL-ы:
|
||
- `https://team.uix.su` — production web UI
|
||
- `https://dev.team.uix.su` — development web UI
|
||
- `http://localhost:3100` — локальная разработка
|
||
|
||
### API endpoints:
|
||
- **Tracker API**: `http://localhost:8100/api/v1/`
|
||
- **WebSocket**: `ws://localhost:8100/ws`
|
||
- **API Docs**: `http://localhost:8100/docs` (только в dev режиме)
|
||
- **Health check**: `http://localhost:8100/health`
|
||
|
||
### CORS настройки:
|
||
```python
|
||
allow_origins=[
|
||
"https://team.uix.su",
|
||
"https://dev.team.uix.su",
|
||
"http://localhost:3100"
|
||
]
|
||
```
|
||
|
||
## Конфигурация
|
||
|
||
### Environment Variables (Tracker):
|
||
```bash
|
||
TRACKER_DATABASE_URL=postgresql+asyncpg://team_board:team_board@localhost:5432/team_board
|
||
TRACKER_HOST=0.0.0.0
|
||
TRACKER_PORT=8100
|
||
TRACKER_JWT_SECRET=change-me-in-production
|
||
TRACKER_AGENT_HEARTBEAT_INTERVAL=30
|
||
TRACKER_AGENT_HEARTBEAT_TIMEOUT=90
|
||
TRACKER_ENV=dev
|
||
```
|
||
|
||
### Файловая система:
|
||
- `/data/uploads` — загруженные файлы (attachments)
|
||
- `/data/projects` — файлы проектов
|
||
- `src/` — исходный код (dev mode с hot reload)
|
||
|
||
## Особенности архитектуры
|
||
|
||
### Аутентификация:
|
||
- **JWT токены** — для web пользователей
|
||
- **Bearer токены** (`tb-xxxxx`) — для агентов
|
||
- Middleware на всех API эндпоинтах (кроме `/docs`, `/health`, `/ws`)
|
||
|
||
### WebSocket система:
|
||
- Heartbeat мониторинг (90 сек timeout)
|
||
- Автоматический offline статус при разрыве
|
||
- Фильтрация событий по подпискам проектов
|
||
- Поддержка множественных соединений одного пользователя
|
||
|
||
### Database Seeding:
|
||
- Автоматическое создание таблиц в dev режиме
|
||
- Auto-seed данными если БД пуста
|
||
- Seeding скрипт: `src/tracker/init_db.py`
|
||
|
||
### Логирование:
|
||
- Request/Response логи всех HTTP запросов
|
||
- WebSocket события
|
||
- Heartbeat таймауты
|
||
- Ошибки с полным traceback
|
||
|
||
Этот документ описывает текущее состояние проекта по коду в `/root/projects/team-board/` на дату создания спецификации. |