ClientSync

Продакшн-готовая платформа агрегации клиентских данных с поддержкой кастомных контрактов и динамических полей.

Описание проекта

ClientSync — это enterprise-решение для сбора, нормализации и агрегации данных о клиентах из различных источников (CRM, биллинг, поддержка). Платформа обеспечивает единое представление клиентских данных с поддержкой до 15 кастомных полей на контракт и предоставляет REST API для агрегированных отчётов в реальном времени.

Архитектура

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

ClientSync/
├── app/                    # Основное приложение
│   ├── api/               # FastAPI роуты
│   ├── auth/              # Аутентификация и авторизация
│   ├── crud/              # CRUD операции
│   ├── db/                # Подключение к БД
│   ├── models/            # SQLAlchemy модели
│   ├── schemas/           # Pydantic схемы
│   ├── services/          # Бизнес-логика
│   ├── tasks/             # Celery задачи
│   ├── utils/             # Вспомогательные функции
│   ├── config.py          # Конфигурация
│   └── main.py           # FastAPI приложение
├── tests/                 # Тесты
│   ├── unit/             # Юнит тесты
│   └── integration/      # Интеграционные тесты
├── docs/                 # Документация
├── alembic/              # Миграции БД
├── requirements.txt      # Зависимости Python
├── docker-compose.yml    # Docker конфигурация
├── Dockerfile           # Docker образ
└── .env.example         # Пример переменных окружения

Модели данных

erDiagram
    Client ||--o{ Contract : has
    Contract ||--o{ ContractField : contains

    Client {
        int id PK
        string external_id UK
        string name
        string email
        string phone
        string company
        string source
        boolean is_active
        datetime created_at
        datetime updated_at
    }

    Contract {
        int id PK
        int client_id FK
        string contract_number UK
        string title
        string description
        decimal amount
        string currency
        date start_date
        date end_date
        date signed_date
        string status
        boolean is_active
        datetime created_at
        datetime updated_at
    }

    ContractField {
        int id PK
        int contract_id FK
        string key
        text value
        string field_type
        string description
        boolean is_required
        datetime created_at
        datetime updated_at
    }

Loading

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

Предварительные требования

• Docker и Docker Compose
• Python 3.11+ (для разработки)
• PostgreSQL 15+ (опционально, если не используете Docker)

Запуск через Docker

# Клонирование репозитория
git clone <repository-url>
cd ClientSync

# Создание файла окружения
cp .env.example .env

# Запуск всех сервисов
docker-compose up --build

# В другом терминале: применение миграций
docker-compose exec app alembic upgrade head

API будет доступен по адресу: http://localhost:8000

Разработка без Docker

# Создание виртуального окружения
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или venv\Scripts\activate  # Windows

# Установка зависимостей
pip install -r requirements.txt

# Настройка переменных окружения
cp .env.example .env
# Отредактируйте .env под ваши настройки

# Применение миграций
alembic upgrade head

# Запуск приложения
uvicorn app.main:app --reload

API Эндпоинты

Основные роуты

Метод	Путь	Описание	Аутентификация
GET	/health	Состояние системы	Нет
GET	/metrics	Prometheus метрики	Нет
GET	/clients/{id}/summary	Агрегированные данные клиента	JWT
GET	/contracts/	Список контрактов с фильтрами	JWT
POST	/contracts/	Создание контракта	JWT
POST	/webhook/data-ingest	Импорт данных	API Key

Примеры запросов

Получение агрегированных данных клиента

curl -X GET "http://localhost:8000/clients/1/summary?period=2024" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Создание контракта с кастомными полями

curl -X POST "http://localhost:8000/contracts/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "client_id": 1,
    "contract_number": "CNT-2024-001",
    "title": "Service Agreement",
    "amount": 100000.00,
    "currency": "RUB",
    "start_date": "2024-01-01",
    "status": "active",
    "custom_fields": [
      {
        "key": "priority",
        "value": "high",
        "field_type": "string",
        "description": "Contract priority level"
      },
      {
        "key": "manager",
        "value": "John Doe",
        "field_type": "string"
      }
    ]
  }'

Импорт данных через webhook

curl -X POST "http://localhost:8000/webhook/data-ingest" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_WEBHOOK_API_KEY" \
  -H "Idempotency-Key: unique-operation-id" \
  -d '{
    "source": "crm",
    "data": {
      "client": {
        "external_id": "CRM-12345",
        "name": "Example Corp",
        "email": "contact@example.com"
      },
      "contracts": [...]
    }
  }'

Безопасность

Аутентификация

• JWT токены для API доступа
• API ключи для webhook интеграций
• Refresh токены для продления сессии

Авторизация (RBAC)

• admin — полный доступ
• analyst — чтение данных и отчётов
• integration — только webhook доступ

Пример использования ролей

@require_role(["admin", "analyst"])
async def get_client_summary(client_id: int):
    # Доступ только для админов и аналитиков
    pass

Производительность

Индексы базы данных

-- Критичные индексы для производительности
CREATE INDEX idx_clients_external_id ON clients(external_id);
CREATE INDEX idx_contracts_client_start ON contracts(client_id, start_date);
CREATE INDEX idx_contract_fields_contract_key ON contract_fields(contract_id, key);

SQL оптимизация

Агрегационные запросы используют оконные функции для максимальной производительности:

-- Пример агрегации с оконными функциями
SELECT
    client_id,
    COUNT(*) OVER (PARTITION BY client_id) as total_contracts,
    SUM(amount) OVER (PARTITION BY client_id ORDER BY start_date) as running_total,
    AVG(amount) OVER (PARTITION BY client_id) as avg_amount
FROM contracts
WHERE start_date >= '2024-01-01';

Кэширование

• Redis для кэширования агрегаций (TTL: 5 минут)
• Ключи кэша: agg:client:{id}:{period}
• Автоматическая инвалидация при изменении данных

Разработка

Миграции базы данных

# Создание новой миграции
alembic revision --autogenerate -m "Add new field"

# Применение миграций
alembic upgrade head

# Откат миграции
alembic downgrade -1

Тестирование

# Запуск всех тестов
pytest

# Тесты с покрытием
pytest --cov=app tests/

# Только интеграционные тесты
pytest tests/integration/

Линтинг и форматирование

# Форматирование кода
black app/ tests/

# Проверка стиля
ruff app/ tests/

# Проверка типов
mypy app/

Docker

Сервисы

• app — FastAPI приложение
• db — PostgreSQL 15
• redis — Redis для кэша и Celery
• celery — Фоновые задачи

Полезные команды

# Просмотр логов
docker-compose logs -f app

# Подключение к контейнеру
docker-compose exec app bash

# Применение миграций в Docker
docker-compose exec app alembic upgrade head

# Запуск тестов в Docker
docker-compose exec app pytest

Мониторинг

Health Check

curl http://localhost:8000/health

Prometheus метрики

curl http://localhost:8000/metrics

Логирование

• Структурированные JSON логи
• Уровни: DEBUG, INFO, WARNING, ERROR
• Ротация и агрегация через ELK Stack (настраивается отдельно)

CI/CD

GitHub Actions pipeline включает:

1. Lint — black, ruff, mypy
2. Test — pytest с покрытием
3. Build — Docker образ
4. Deploy — автоматический деплой на Render

Вклад в проект

1. Форк репозитория
2. Создание feature ветки (git checkout -b feature/amazing-feature)
3. Коммит изменений (git commit -m 'Add amazing feature')
4. Push в ветку (git push origin feature/amazing-feature)
5. Создание Pull Request

Лицензия

Этот проект лицензирован под MIT License - см. файл LICENSE для деталей.

Поддержка

Если у вас есть вопросы или проблемы:

1. Проверьте существующие Issues
2. Создайте новый Issue с подробным описанием
3. Используйте шаблоны Issue для bug reports и feature requests

---

ClientSync — демонстрация enterprise-подходов к архитектуре, тестированию и производительности в современных Python приложениях.