mkd/docs/DEVELOPMENT_PIPELINE_AUTOMATION.md

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

## Обзор
Воронка развития должна автоматически управлять жизненным циклом потенциальных объектов от момента обнаружения до передачи в управление.

## Источники данных для воронки

### 1. Ручное добавление (реализовано)
- Менеджер вручную добавляет объект через форму
- Статус: `analysis` (по умолчанию)

### 2. Импорт из файлов (CSV/Excel)
- Массовый импорт объектов из внешних источников
- Парсинг адресов, характеристик, контактов
- Автоматическое создание записей в воронке

### 3. Интеграция с внешними API
- Парсинг публичных реестров (Росреестр, ГИС ЖКХ)
- Мониторинг сайтов конкурентов
- Интеграция с CRM системами

### 4. Автоматическое обнаружение
- Анализ отзывов жильцов (модуль PR)
- Выявление недовольства текущей УК
- Мониторинг социальных сетей и форумов

## Автоматическое перемещение по стадиям

### Стадии воронки:
1. **analysis** (Анализ) - начальная стадия
2. **negotiation** (Переговоры) - активная работа с собственниками
3. **preparation** (Подготовка) - подготовка к ОСС
4. **voting** (Голосование) - идет ОСС
5. **transfer** (Передача) - объект передан в управление

### Правила автоматического перехода:

#### 1. Analysis → Negotiation
**Триггеры:**
- Probability >= 30% (автоматически)
- Создана маркетинговая активность для объекта
- Проведена первая встреча с активистами

**Условия:**
- Минимум 3 контакта с собственниками
- Наличие хотя бы 1 активиста

#### 2. Negotiation → Preparation
**Триггеры:**
- Probability >= 60%
- Собрано >= 5 активистов
- Проведено >= 3 встреч

**Условия:**
- Технический аудит завершен
- Подготовлен проект договора управления

#### 3. Preparation → Voting
**Триггеры:**
- Создано ОСС для объекта (автоматически)
- Probability >= 70%

**Условия:**
- ОСС создано и запланировано
- Подготовлены все документы

#### 4. Voting → Transfer
**Триггеры:**
- ОСС завершено успешно (quorum > 50%, решение "за")
- Probability >= 90%

**Условия:**
- ОСС статус = 'completed'
- Результат голосования положительный

#### 5. Откат стадий
**Negotiation → Analysis:**
- Нет активности > 30 дней
- Probability < 20%

**Preparation → Negotiation:**
- ОСС отменено
- Probability < 50%

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

### Формула расчета:
```
probability = baseProbability + 
              (activistsCount * 5) + 
              (meetingsHeld * 3) + 
              (adsDistributed / 10) + 
              (auditScore * 0.2) - 
              (daysInactive * 0.5)
```

Где:
- `baseProbability` = 20% (для новых объектов)
- `activistsCount` = количество активистов (макс 10)
- `meetingsHeld` = количество встреч (макс 10)
- `adsDistributed` = количество розданных листовок (макс 500)
- `auditScore` = оценка технического аудита (0-100)
- `daysInactive` = дней без активности (макс 60)

### Обновление probability:
- При каждом изменении маркетинговых метрик
- При завершении технического аудита
- Ежедневно (cron job) для пересчета по времени

## События и триггеры

### 1. Создание ОСС
```sql
-- При создании ОСС автоматически:
-- 1. Обновить статус pipeline на 'voting'
-- 2. Связать ОСС с pipeline объектом
-- 3. Отправить уведомление менеджеру
```

### 2. Завершение ОСС
```sql
-- При завершении ОСС:
-- 1. Если quorum > 50% и решение "за":
--    - Обновить статус pipeline на 'transfer'
--    - Создать запись в buildings (если еще нет)
--    - Связать building_id с pipeline
-- 2. Если ОСС провалено:
--    - Обновить probability (-20%)
--    - Вернуть статус на 'preparation' или 'negotiation'
```

### 3. Завершение технического аудита
```sql
-- При завершении аудита:
-- 1. Обновить probability на основе wear_percent и projected_margin
-- 2. Если wear_percent > 70%:
--    - Уменьшить probability на 15%
-- 3. Если projected_margin < 10%:
--    - Уменьшить probability на 10%
```

### 4. Обновление маркетинговых метрик
```sql
-- При обновлении метрик:
-- 1. Пересчитать probability
-- 2. Проверить условия для перехода на следующую стадию
-- 3. Автоматически перевести, если условия выполнены
```

## Deadlines и напоминания

### Автоматические напоминания:
- **7 дней в стадии** - напомнить менеджеру о необходимости действий
- **30 дней без активности** - предупреждение о риске потери объекта
- **Deadline ОСС** - напоминание за 3 дня до окончания
- **Просроченные задачи** - ежедневные уведомления

## Интеграция с другими модулями

### Связь с модулями:
1. **ОСС модуль** - автоматическое создание ОСС при переходе в 'preparation'
2. **Аудит модуль** - автоматическое создание задачи на аудит при 'negotiation'
3. **Маркетинг модуль** - автоматическое создание активности при добавлении объекта
4. **Buildings модуль** - автоматическое создание здания при 'transfer'

## Реализация

### 1. Таблица для истории переходов
```sql
CREATE TABLE development_pipeline_history (
  id BIGSERIAL PRIMARY KEY,
  pipeline_id VARCHAR(50) REFERENCES development_pipeline(id) ON DELETE CASCADE,
  from_status VARCHAR(20),
  to_status VARCHAR(20),
  reason TEXT,
  triggered_by VARCHAR(50), -- 'auto' | 'manual' | user_id
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

### 2. Таблица для правил автоматизации
```sql
CREATE TABLE development_automation_rules (
  id BIGSERIAL PRIMARY KEY,
  rule_name VARCHAR(100) NOT NULL,
  from_status VARCHAR(20),
  to_status VARCHAR(20),
  conditions JSONB, -- условия для срабатывания
  enabled BOOLEAN DEFAULT TRUE,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

### 3. Cron задачи (Node.js)
- Ежедневная проверка условий для автоматических переходов
- Пересчет probability для всех объектов
- Проверка deadlines и отправка уведомлений

### 4. Триггеры в БД
- Автоматическое обновление статуса при создании ОСС
- Автоматическое обновление при завершении ОСС
- Логирование всех изменений статуса

## Примеры workflow

### Сценарий 1: Успешный объект
1. Объект добавлен вручную → `analysis` (probability: 20%)
2. Проведена встреча, найдены активисты → probability: 35% → `negotiation`
3. Проведено 3 встречи, 5 активистов → probability: 65% → `preparation`
4. Создан технический аудит → probability: 70%
5. Создано ОСС → автоматически `voting`
6. ОСС завершено успешно → автоматически `transfer` + создан building

### Сценарий 2: Потеря объекта
1. Объект в `negotiation` 45 дней без активности
2. Автоматическое снижение probability до 15%
3. Автоматический откат в `analysis`
4. Уведомление менеджеру о риске потери

### Сценарий 3: Импорт из файла
1. Загружен CSV с 50 объектами
2. Автоматическое создание записей в `analysis`
3. Автоматическое создание маркетинговых активностей
4. Распределение по менеджерам (round-robin или по районам)