Import Vector lab project

2026-06-06 18:31:55 +00:00
commit fcc22063ed
105 changed files with 31639 additions and 0 deletions
@@ -0,0 +1,149 @@
+# API для определения психотипа
+
+## Endpoint: POST /api/v1/analyze/psychotype
+
+Определяет психотип пропавшего человека на основе ответов на психологические вопросы и возвращает модификаторы зон поиска с рекомендациями.
+
+**Основано на методике:** Рындина О.Г., Иванова О.Ю. (Чебоксары, 2015)
+
+### Request Body
+
+```json
+{
+  "stress_reaction": "active|cry|freeze|calm",
+  "group_role": "leader|follower",
+  "risk_taking": "high|medium|low",
+  "unfamiliar_env": "explore|wait|freeze"
+}
+```
+
+### Response
+
+```json
+{
+  "psychotype": "dominant|harmonic|anxious|introvert_passive|introvert_active",
+  "modifiers": {
+    "zone_0_500": 0.7,
+    "zone_500_1500": 1.2,
+    "zone_1500_2500": 1.4,
+    "zone_2500plus": 1.1,
+    "movement_model": "chaotic_far|linear_landmark|stay|stay_hidden",
+    "description": "Описание психотипа"
+  },
+  "recommendations": {
+    "priority_zones": "Приоритетные зоны поиска",
+    "search_pattern": "Паттерн поиска",
+    "key_locations": "Ключевые локации",
+    "communication": "Способы коммуникации"
+  }
+}
+```
+
+## Психотипы
+
+### 1. Dominant (Доминантный)
+- **Триггер:** active + leader + high
+- **Модификаторы:** Низкая вероятность в ближней зоне (0.7), высокая в средних/дальних (1.2-1.4)
+- **Модель движения:** chaotic_far - хаотичное движение на большие расстояния
+- **Приоритет:** Средние и дальние зоны (500-2500м)
+
+### 2. Harmonic (Гармоничный)
+- **Триггер:** calm + leader + low
+- **Модификаторы:** Равномерное распределение с акцентом на средние зоны
+- **Модель движения:** linear_landmark - движение по ориентирам
+- **Приоритет:** Все зоны равномерно, акцент на 500-1500м
+
+### 3. Anxious (Тревожный)
+- **Триггер:** cry + follower + low
+- **Модификаторы:** Очень высокая вероятность в ближней зоне (1.4), низкая в дальних (0.3)
+- **Модель движения:** stay - минимальное движение
+- **Приоритет:** Ближняя зона (0-500м) критически важна
+
+### 4. Introvert Passive (Интроверт пассивный)
+- **Триггер:** freeze + follower + low
+- **Модификаторы:** Высокая вероятность в ближней зоне (1.3), очень низкая в дальних (0.2)
+- **Модель движения:** stay_hidden - прячется, минимальное движение
+- **Приоритет:** Ближняя зона, укрытия
+
+### 5. Introvert Active (Интроверт активный)
+- **Триггер:** active + leader + medium
+- **Модификаторы:** Средние значения с акцентом на зоны 500-2500м
+- **Модель движения:** linear_landmark - целенаправленное движение
+- **Приоритет:** Средние зоны вдоль линейных ориентиров
+
+## Примеры использования
+
+### Пример 1: Доминантный тип
+
+```bash
+curl -X POST http://192.168.0.99:8000/api/v1/analyze/psychotype \
+  -H "Content-Type: application/json" \
+  -d '{
+    "stress_reaction": "active",
+    "group_role": "leader",
+    "risk_taking": "high",
+    "unfamiliar_env": "explore"
+  }'
+```
+
+**Результат:**
+- Психотип: dominant
+- Зона 0-500м: коэффициент 0.7 (низкий приоритет)
+- Зона 1500-2500м: коэффициент 1.4 (высокий приоритет)
+- Рекомендация: Широкий охват, проверка нелинейных маршрутов
+
+### Пример 2: Тревожный тип
+
+```bash
+curl -X POST http://192.168.0.99:8000/api/v1/analyze/psychotype \
+  -H "Content-Type: application/json" \
+  -d '{
+    "stress_reaction": "cry",
+    "group_role": "follower",
+    "risk_taking": "low",
+    "unfamiliar_env": "freeze"
+  }'
+```
+
+**Результат:**
+- Психотип: anxious
+- Зона 0-500м: коэффициент 1.4 (критически важна!)
+- Зона 2500+м: коэффициент 0.3 (очень низкий приоритет)
+- Рекомендация: Тщательный осмотр ближайшей территории, укрытия
+
+## Интеграция с другими сервисами
+
+Модификаторы из психотипа можно использовать для корректировки вероятностей в:
+- `scoring_service.py` - взвешивание зон поиска
+- `geo_service.py` - построение приоритетных зон
+- `distance_service.py` - корректировка максимальной дистанции поиска
+
+### Пример интеграции
+
+```python
+from services.psychotype_service import detect_psychotype, get_psychotype_modifiers
+
+# Определяем психотип
+psychotype = detect_psychotype(answers)
+modifiers = get_psychotype_modifiers(psychotype)
+
+# Применяем модификаторы к базовым вероятностям
+base_prob_near = 0.5
+adjusted_prob = base_prob_near * modifiers['zone_0_500']
+
+# Для anxious: 0.5 * 1.4 = 0.7 (увеличение приоритета ближней зоны)
+# Для dominant: 0.5 * 0.7 = 0.35 (снижение приоритета ближней зоны)
+```
+
+## Валидация
+
+API валидирует входные данные:
+- Все поля обязательны
+- Значения должны соответствовать допустимым вариантам
+- При невалидных данных возвращается HTTP 400 с описанием ошибки
+
+```json
+{
+  "detail": "Invalid stress_reaction: unknown_value"
+}
+```