mkd/docs/PIPELINE_AUTOMATION_FLOW.md

Схема автоматизации воронки развития

Обзор потока данных

┌─────────────────────────────────────────────────────────────────┐
│                    ИСТОЧНИКИ ДАННЫХ                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │  Ручное      │  │  Импорт      │  │  Интеграция  │        │
│  │  добавление  │  │  из файлов   │  │  с API       │        │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘        │
│         │                  │                  │                 │
│         └──────────────────┼──────────────────┘                 │
│                            │                                    │
│                    ┌───────▼────────┐                          │
│                    │  ВОРОНКА       │                          │
│                    │  (analysis)    │                          │
│                    └───────┬────────┘                          │
└────────────────────────────┼────────────────────────────────────┘
                             │
                             │ Автоматические переходы
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
┌───────▼────────┐  ┌────────▼────────┐  ┌────────▼────────┐
│  NEGOTIATION   │  │  PREPARATION   │  │    VOTING       │
│                │  │                │  │                 │
│ Триггеры:      │  │ Триггеры:      │  │ Триггеры:       │
│ • probability  │  │ • probability  │  │ • ОСС создано   │
│   >= 30%       │  │   >= 60%       │  │   (автоматически│
│ • активисты    │  │ • аудит готов  │  │    через триггер│
│ • встречи      │  │ • документы    │  │    БД)          │
└───────┬────────┘  └────────┬───────┘  └────────┬────────┘
        │                    │                    │
        │                    │                    │
        └────────────────────┼────────────────────┘
                             │
                    ┌────────▼────────┐
                    │    TRANSFER     │
                    │                 │
                    │ Триггеры:       │
                    │ • ОСС успешно   │
                    │   (кворум > 50%)│
                    │ • probability   │
                    │   >= 90%        │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Создание       │
                    │  Building       │
                    │  (автоматически)│
                    └─────────────────┘

Детальная схема автоматических переходов

1. Analysis → Negotiation

Условия:

• probability >= 30% ИЛИ
• Создана маркетинговая активность с activists_count >= 1 ИЛИ
• Проведена первая встреча (meetings_held >= 1)

Действия:

• Автоматический переход статуса
• Создание маркетинговой активности (если еще нет)
• Уведомление менеджеру

Код:

// В pipelineAutomation.js
if (pipeline.status === 'analysis' && 
    (probability >= 30 || marketing.activists_count >= 1 || marketing.meetings_held >= 1)) {
  await transitionStatus(pipeline.id, 'analysis', 'negotiation', 'Автоматический переход: условия выполнены', 'auto');
}

2. Negotiation → Preparation

Условия:

• probability >= 60% И
• activists_count >= 5 И
• meetings_held >= 3 И
• Технический аудит завершен (development_audits существует)

Действия:

• Автоматический переход статуса
• Создание задачи на подготовку ОСС
• Уведомление менеджеру

3. Preparation → Voting

Условия:

• Создано ОСС со статусом active (триггер БД)
• probability >= 70%

Действия:

• Триггер БД автоматически переводит в voting
• Логирование в development_pipeline_history
• Уведомление менеджеру

SQL Триггер:

-- Автоматически срабатывает при создании ОСС
CREATE TRIGGER trigger_auto_transition_to_voting
  AFTER INSERT OR UPDATE ON development_oss_sessions
  WHEN (NEW.status = 'active')
  EXECUTE FUNCTION auto_transition_to_voting();

4. Voting → Transfer

Условия:

• ОСС завершено (status = 'completed')
• Кворум > 50%
• Результат голосования положительный

Действия:

• Триггер БД автоматически переводит в transfer
• Создание записи в buildings (если еще нет)
• Связывание building_id с pipeline объектом
• Уведомление менеджеру и директору

SQL Триггер:

-- Автоматически срабатывает при завершении ОСС
CREATE TRIGGER trigger_auto_handle_oss_completion
  AFTER UPDATE ON development_oss_sessions
  WHEN (NEW.status = 'completed' AND OLD.status != 'completed')
  EXECUTE FUNCTION auto_handle_oss_completion();

Автоматический расчет probability

Формула:

probability = 20 (базовая) +
              (activists_count * 5, макс 50) +
              (meetings_held * 3, макс 30) +
              (ads_distributed / 10, макс 20) +
              (audit_score * 0.2, макс 20) -
              (days_inactive * 0.5, макс 30)

Когда пересчитывается:

1. При обновлении маркетинговых метрик (PUT /api/development/marketing/:id/metrics)
2. При создании/обновлении аудита (POST/PUT /api/development/audits)
3. Ежедневно (cron задача в 9:00)
4. Вручную (POST /api/development/pipeline/:id/recalculate)

Источники попадания в воронку

1. Ручное добавление ✅ (реализовано)

• Форма в UI
• Статус: analysis
• Probability: 20%

2. Импорт из файлов (TODO)

// POST /api/development/pipeline/import
// Принимает CSV/Excel с колонками:
// - address, type, floors, area, apartments, manager
// Автоматически создает записи в analysis

3. Интеграция с PR модулем (TODO)

// При обнаружении негативных отзывов о текущей УК:
// - Автоматически создается pipeline объект
// - Статус: analysis
// - Создается маркетинговая активность

4. Мониторинг внешних источников (TODO)

• Парсинг сайтов конкурентов
• Мониторинг ГИС ЖКХ
• Интеграция с CRM

Откаты стадий

Negotiation → Analysis

Условия:

• Нет активности > 30 дней
• probability < 20%

Preparation → Negotiation

Условия:

• ОСС отменено
• probability < 50%

Voting → Preparation

Условия:

• ОСС провалено (кворум < 50%)
• Автоматически через триггер БД

Уведомления

Типы уведомлений:

1. Переход на следующую стадию - менеджеру объекта
2. Откат стадии - менеджеру + руководителю отдела
3. Риск потери объекта (30 дней без активности) - менеджеру + директору
4. ОСС завершено успешно - менеджеру + директору + финансисту
5. Объект передан в управление - всем заинтересованным

API Endpoints для автоматизации

Ручной запуск проверки

POST /api/development/pipeline/auto-check

Запускает ежедневную проверку всех объектов вручную.

Пересчет probability

POST /api/development/pipeline/:id/recalculate

Пересчитывает probability для конкретного объекта и проверяет условия для перехода.

Мониторинг и логирование

Все автоматические переходы логируются в development_pipeline_history:

• from_status - предыдущий статус
• to_status - новый статус
• reason - причина перехода
• triggered_by - 'auto' | 'manual' | user_id
• created_at - время перехода

Примеры workflow

Успешный сценарий:

1. Объект добавлен → analysis (20%)
2. Встреча + 2 активиста → probability: 35% → negotiation
3. 3 встречи + 5 активистов + аудит → probability: 68% → preparation
4. Создано ОСС → автоматически voting (триггер БД)
5. ОСС успешно (кворум 55%) → автоматически transfer (триггер БД)
6. Создан Building → объект в управлении

Неудачный сценарий:

1. Объект в voting (ОСС идет)
2. ОСС провалено (кворум 45%) → автоматически preparation (триггер БД)
3. Probability снижен на 20%
4. Уведомление менеджеру о необходимости дополнительной работы