Глубокий анализ проекта Bridge CRM

🏗️ Общая архитектура проекта

Принцип построения

Проект использует модульную архитектуру Django с четким разделением ответственности:

bridge_crm_django/
├── core/              # Базовые классы (BaseModel, BaseTimestampedModel)
├── common/            # Справочники (Currency, Kato, SubjectType)
├── accounts/         # Пользователи и профили (UserProfile, роли)
├── announces/        # Объявления о тендерах (Announce, AnnounceLot)
├── deals/            # 🎯 ЦЕНТРАЛЬНАЯ СУЩНОСТЬ - Сделки
├── customers/         # Заказчики (Interest, Order)
├── suppliers/         # Поставщики (Product, Offer)
├── operators_kz/      # Оператор Казахстан
├── operators_cn/      # Оператор Китай
├── carriers/          # Перевозчики
├── customs/           # Таможня
├── integrations/      # Внешние API (read-only)
└── tenders/           # Панель управления (legacy)

Ключевые принципы

• Deal-центричная архитектура - все бизнес-процессы вращаются вокруг модели Deal
• Один лот = одна сделка - строгое правило системы
• State Machine - управление жизненным циклом через конечный автомат
• Разделение ответственности - каждая роль имеет свой модуль

🔄 Архитектура бизнес-процессов

Жизненный цикл сделки (Deal)

Сделка проходит через 7 уровней с тремя параллельными статусами:

Уровень 1: Интерес (Interest)

• Заказчик проявляет интерес к лоту
• Ещё не обязательство, только намерение
• Модель: customers.Interest

Уровень 2: Коммерческое предложение (Offer)

• Поставщик создаёт коммерческое предложение
• Юридически значимый документ
• Модель: suppliers.Offer

Уровень 3: Заказ (Order)

• Заказчик создаёт заказ на основе лота
• При создании автоматически создаётся Deal
• Модель: customers.Order

Уровень 4: Финансовый статус (Financial Status)

• PENDING → Ожидает оплаты
• PAYMENT_INITIATED → Оплата инициирована заказчиком
• PAYMENT_RECEIVED → Оплата получена платформой (блокировка средств)
• FUNDS_TRANSFERRED → Средства переданы оператору КЗ
• OPERATOR_CN_FUNDS_RECEIVED → Оператор CN получил средства
• SUPPLIER_PAID → Поставщик оплачен
• COMPLETED → Финансы закрыты

Уровень 5-6: Статус груза (Cargo Status)

• NOT_STARTED → Груз не начат
• CARGO_TRANSFERRED → Груз передан перевозчику
• IN_TRANSIT → В пути
• AT_CUSTOMS → На таможне
• CUSTOMS_CLEARED → Таможня пройдена
• DELIVERED → Доставлен заказчику

Уровень 7: Статус документов (Document Status)

• PENDING → Документы ожидают
• SUBMITTED → Документы поданы
• UNDER_REVIEW → На рассмотрении
• CORRIDOR_ASSIGNED → Коридор назначен
• CLEARED → Выпущен
• REJECTED → Отклонен

State Machine (Конечный автомат)

Система использует State Machine для управления переходами между состояниями:

DealState.CREATED
  → DealState.OFFER_SUBMITTED
  → DealState.SUPPLIER_SELECTED
  → DealState.PAYMENT_INITIATED
  → DealState.PAYMENT_RECEIVED
  → DealState.FUNDS_TRANSFERRED
  → DealState.OPERATOR_CN_FUNDS_RECEIVED
  → DealState.SUPPLIER_PAID
  → DealState.CARGO_TRANSFERRED
  → DealState.IN_TRANSIT
  → DealState.AT_CUSTOMS
  → DealState.CUSTOMS_CLEARED
  → DealState.DELIVERED
  → DealState.COMPLETED

Платёжная схема (Гибкая система управления денежными потоками)

Платформа формирует платёжную схему (PaymentScheme), которая определяет:

• Кто платит
• Кому платит
• За что платит
• В каком порядке

Структура платёжной схемы

Пример структуры (текущая схема через операторов):

{
  "payments": [
    {
      "from": "platform",
      "to": "operator_kz",
      "amount": 1000.00,
      "currency": "KZT",
      "purpose": "supplier_payment",
      "order": 1,
      "status": "pending"
    },
    {
      "from": "operator_kz",
      "to": "operator_cn",
      "amount": 1000.00,
      "currency": "KZT",
      "purpose": "supplier_payment",
      "order": 2,
      "status": "pending"
    },
    {
      "from": "operator_cn",
      "to": "supplier",
      "amount": 1000.00,
      "currency": "CNY",
      "purpose": "supplier_payment",
      "order": 3,
      "status": "pending"
    },
    {
      "from": "operator_kz",
      "to": "carrier",
      "amount": 100.00,
      "currency": "KZT",
      "purpose": "logistics",
      "order": 4,
      "status": "pending"
    },
    {
      "from": "operator_kz",
      "to": "customs",
      "amount": 50.00,
      "currency": "KZT",
      "purpose": "customs_duties",
      "order": 5,
      "status": "pending"
    }
  ]
}

Пример структуры (альтернативная схема - платформа платит напрямую):

{
  "payments": [
    {
      "from": "platform",
      "to": "operator_cn",
      "amount": 1000.00,
      "currency": "KZT",
      "purpose": "supplier_payment",
      "order": 1,
      "status": "pending"
    },
    {
      "from": "operator_cn",
      "to": "supplier",
      "amount": 1000.00,
      "currency": "CNY",
      "purpose": "supplier_payment",
      "order": 2,
      "status": "pending"
    },
    {
      "from": "platform",
      "to": "carrier",
      "amount": 100.00,
      "currency": "KZT",
      "purpose": "logistics",
      "order": 3,
      "status": "pending"
    },
    {
      "from": "platform",
      "to": "customs",
      "amount": 50.00,
      "currency": "KZT",
      "purpose": "customs_duties",
      "order": 4,
      "status": "pending"
    }
  ]
}

Возможные значения полей

• from: "platform", "operator_kz", "operator_cn"
• to: "operator_kz", "operator_cn", "supplier", "carrier", "customs"
• purpose: "supplier_payment", "logistics", "customs_duties"
• status: "pending", "completed", "failed"

Управление схемой

Платформа может:

1. Создать схему при создании сделки
2. Обновить схему (создаётся новая версия, старая сохраняется для истории)
3. Выполнить платежи согласно схеме в правильном порядке
4. Просмотреть историю изменений схемы

🚀 Как работает платформа

Основной поток работы

1. Создание объявления (Announce)

Источники:

• Ручное создание - заказчик создаёт объявление вручную
• ГосЗакуп - автоматическая синхронизация через GraphQL API
• Самрук - автоматическая синхронизация через REST API

2. Проявление интереса (Interest)

Заказчик:

• Просматривает объявления и лоты
• Может создать Interest (типы: Слежение, Расчёт, Участие)
• Ещё не обязательство

3. Создание коммерческого предложения (Offer)

Поставщик:

• Просматривает доступные лоты
• Создаёт Offer на основе лота
• Указывает цены, условия доставки и оплаты
• Связывает продукты из каталога (Product)

4. Создание заказа и сделки (Order → Deal)

Заказчик:

• Создаёт Order на основе лота
• Выбирает поставщика (из предложений)
• При сохранении автоматически создаётся Deal

5. Финансовый поток

1. Инициирование оплаты (Заказчик) - Статус: PAYMENT_INITIATED
2. Получение оплаты платформой - Средства блокируются, статус: PAYMENT_RECEIVED
3. Передача средств оператору КЗ - Статус: FUNDS_TRANSFERRED
4. Получение средств оператором CN - Статус: OPERATOR_CN_FUNDS_RECEIVED
5. Оплата поставщика (Оператор CN) - Статус: SUPPLIER_PAID
   Важно: Только оператор CN может оплачивать поставщика, так как поставщик находится в Китае
6. Подтверждение оплаты поставщиком - Флаг: supplier_payment_confirmed = True

6. Логистический поток

1. Передача груза перевозчику (Поставщик) - Статус: CARGO_TRANSFERRED
2. Принятие груза перевозчиком - Флаг: carrier_cargo_confirmed = True, Статус: IN_TRANSIT
3. Доставка на таможню - Статус: AT_CUSTOMS
4. Подтверждение получения таможней - Флаг: customs_cargo_confirmed = True
5. Таможенное оформление - Статус документов: CLEARED, Статус груза: CUSTOMS_CLEARED
6. Доставка заказчику - Статус: DELIVERED

👥 Взаимодействие ролей

Роли в системе

5. Перевозчик (Carrier)

Профиль: UserProfile с profile_type = CARRIER

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

• Принятие груза от поставщика
• Подтверждение получения груза
• Транспортировка груза
• Доставка на таможню
• Доставка заказчику
• Получение оплаты за логистические услуги (от платформы или оператора КЗ согласно схеме)

Ограничения:

• Видит только связанные сделки
• Не может изменять финансовые статусы

6. Таможня (Customs)

Профиль: UserProfile с profile_type = CUSTOMS

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

• Подтверждение получения груза
• Обработка таможенного оформления
• Назначение коридора (зелёный/жёлтый/красный)
• Выпуск с таможни
• Получение оплаты за таможенные услуги (от платформы или оператора КЗ согласно схеме)

Ограничения:

• Видит только связанные сделки
• Не может изменять финансовые статусы

Матрица взаимодействия

🛠️ Техническая архитектура

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

Backend:

• Django 5.2.8
• Django REST Framework
• PostgreSQL (production) / SQLite (development)
• Redis (кэширование, Celery брокер)
• Celery (фоновые задачи)
• Gunicorn (WSGI сервер)

Frontend:

• HTML5, CSS3, JavaScript
• jQuery
• AOS (анимации)
• Swiper (слайдеры)
• Flatpickr (даты)

Структура данных

Базовые классы

• BaseModel - UUID primary key
• TimestampedModel - create_date, update_date
• BaseTimestampedModel - UUID + timestamps

Модель Deal (центральная)

Сделка содержит:

• Связь с лотом (announce_lot)
• Заказчик (customer)
• Поставщик (supplier)
• Участники: operator_kz, operator_cn, carrier, customs
• Три защищённых статуса: _financial_status, _cargo_status, _document_status
• Блокировка средств (funds_locked)

Платёжная схема (PaymentScheme)

Гибкая система управления денежными потоками:

• Поля: status, version, previous_version
• Методы: get_active_payments(), get_next_payment(), mark_payment_completed(), update_scheme()
• Версионирование для истории изменений

Новые модели

• CarrierPayment - оплата перевозчику за логистические услуги
• CustomsPayment - оплата таможне за таможенные услуги

PaymentExecutor сервис

Сервис для выполнения платежей согласно платёжной схеме:

• can_execute_payment() - проверка прав на выполнение платежа
• validate_payment_order() - проверка порядка выполнения
• execute_payment() - выполнение платежа для всех типов получателей

API архитектура

Основной endpoint: /api/v1/deals/

Действия:

• POST /api/v1/deals/ - Создание сделки (заказчик)
• GET /api/v1/deals/ - Список сделок (с фильтрацией по роли)
• GET /api/v1/deals/{id}/ - Детали сделки
• POST /api/v1/deals/{id}/submit-offer/ - Подача предложения (поставщик)
• POST /api/v1/deals/{id}/select-supplier/ - Выбор поставщика (заказчик)
• POST /api/v1/deals/{id}/initiate-payment/ - Инициирование оплаты (заказчик)
• POST /api/v1/deals/{id}/confirm-payment/ - Подтверждение оплаты (платформа)
• POST /api/v1/deals/{id}/transfer-funds/ - Передача средств (платформа)
• POST /api/v1/deals/{id}/create-payment-scheme/ - Создание платёжной схемы (платформа)
• POST /api/v1/deals/{id}/update-payment-scheme/ - Обновление платёжной схемы (платформа)
• POST /api/v1/deals/{id}/execute-payment/ - Выполнение платежа по схеме
• GET /api/v1/deals/{id}/payment-scheme/ - Просмотр платёжной схемы
• GET /api/v1/deals/{id}/payment-scheme/history/ - История изменений схемы
• POST /api/v1/deals/{id}/pay-supplier/ - Оплата поставщика (оператор CN) - устаревший метод, использовать execute-payment
• POST /api/v1/deals/{id}/accept-cargo/ - Принятие груза (перевозчик)
• POST /api/v1/deals/{id}/deliver-to-customs/ - Доставка на таможню (перевозчик)
• POST /api/v1/deals/{id}/process-customs/ - Обработка таможни (таможня)
• POST /api/v1/deals/{id}/complete/ - Завершение сделки

🔌 Интеграции

ГосЗакуп (goszakup.gov.kz)

• Тип: GraphQL API
• URL: https://ows.goszakup.gov.kz/v3/graphql
• Аутентификация: Bearer Token
• Функциональность: Получение тендеров, автоматическая синхронизация

Самрук (zakup.sk.kz)

• Тип: REST API
• URL: https://zakup.sk.kz/eprocsearch/api/external/4dv3rts
• Метод: POST
• Функциональность: Получение тендеров по фильтрам

Национальный Банк РК

• Тип: RSS XML
• URL: https://nationalbank.kz/rss/get_rates.cfm
• Функциональность: Получение курсов валют, автоматическое обновление

NCANode (ЭЦП)

• Тип: REST API
• URL: https://v3.ncanode.kz/api/v1
• Функциональность: Проверка электронной цифровой подписи, верификация сертификатов

🔒 Безопасность и права доступа

Система permissions

View-level permissions (DRF):

• IsPlatform - Платформа (is_staff)
• IsCustomer - Заказчик
• IsSupplier - Поставщик
• IsOperatorKZ - Оператор КЗ
• IsOperatorCN - Оператор CN
• IsCarrier - Перевозчик
• IsCustoms - Таможня

Object-level permissions (DealPolicy):

• DealPolicy.can_view() - Просмотр сделки
• DealPolicy.can_submit_offer() - Подача предложения
• DealPolicy.can_select_supplier() - Выбор поставщика
• DealPolicy.can_pay() - Оплата
• DealPolicy.can_confirm_payment() - Подтверждение оплаты
• DealPolicy.can_transfer_funds() - Передача средств
• И другие методы...

🗺️ Полная архитектурная диаграмма (Ментальная карта)

1. Общая структура проекта

2. Жизненный цикл сделки (Deal Flow)

3. Взаимодействие ролей в сделке

4. Финансовый поток

5. Логистический поток

🎯 Выводы

Сильные стороны

1. Чёткая архитектура - модульная структура, разделение ответственности
2. Deal-центричность - все процессы вращаются вокруг одной сущности
3. State Machine - гарантированная валидация переходов
4. Безопасность - защищённые поля, централизованные проверки прав
5. История изменений - полный аудит всех действий
6. Интеграции - автоматическая синхронизация с внешними системами

Области для улучшения

1. Платёжная схема - ✅ РЕАЛИЗОВАНО - гибкая система управления денежными потоками
   • ✅ Добавлены модели CarrierPayment и CustomsPayment
   • ✅ Расширена PaymentScheme (статусы, версии, методы управления)
   • ✅ Создан PaymentExecutor для выполнения платежей
   • ✅ API endpoints для управления схемой
   • ✅ Тесты созданы и протестированы (17 тестов прошли успешно)
2. Уведомления - можно добавить систему уведомлений для участников
3. Отчёты - можно добавить аналитику и отчёты по сделкам
4. Тестирование - увеличить покрытие тестами (особенно для PaymentExecutor и новых моделей)