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

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

```
┌─────────────────────────────────────────────────────────────────┐
│                    ИСТОЧНИКИ ДАННЫХ                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │  Ручное      │  │  Импорт      │  │  Интеграция  │        │
│  │  добавление  │  │  из файлов   │  │  с 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`)

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

**Код:**
```javascript
// В 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 Триггер:**
```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 Триггер:**
```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)
```javascript
// POST /api/development/pipeline/import
// Принимает CSV/Excel с колонками:
// - address, type, floors, area, apartments, manager
// Автоматически создает записи в analysis
```

### 3. Интеграция с PR модулем (TODO)
```javascript
// При обнаружении негативных отзывов о текущей УК:
// - Автоматически создается 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. Уведомление менеджеру о необходимости дополнительной работы