# Техническое Задание (ТЗ)
# TenerifeProp - Агентство недвижимости на Тенерифе

## 1. Введение

### 1.1 Назначение документа
Данный документ содержит полное техническое задание на разработку веб-приложения для агентства недвижимости TenerifeProp, расположенного на острове Тенерифе (Канарские острова, Испания).

### 1.2 Область применения
Веб-приложение предназначено для:
- Публичного показа объектов недвижимости (участки, дома, квартиры)
- Сбора заявок от потенциальных клиентов
- Управления контентом и объектами через административную панель
- Работы на испанском и русском языках

### 1.3 Термины и определения

| Термин | Определение |
|--------|-------------|
| Property | Объект недвижимости (участок, дом, квартира) |
| Lead | Потенциальный клиент, оставивший заявку |
| Agricultural land | Сельскохозяйственный участок (terreno agrícola) |
| Urban land | Городской участок (terreno urbano) |
| Ruins | Руины, здания под восстановление |

---

## 2. Сущности данных

### 2.1 Property (Недвижимость)

#### Атрибуты

| Поле | Тип | Обязательно | Описание |
|------|-----|--------------|----------|
| id | TEXT (UUID) | Да | Уникальный идентификатор |
| slug | TEXT | Да | URL-friendly идентификатор |
| reference | TEXT | Да | Человекочитаемый ID (TP-001) |
| type | ENUM | Да | agricultural, urban, house, apartment, ruins |
| status | ENUM | Да | active, reserved, sold, inactive |
| land_type | ENUM | Да | agricultural, urban, rustic, buildable |
| title_es | TEXT | Да | Название на испанском |
| title_ru | TEXT | Да | Название на русском |
| description_es | TEXT | Да | Описание на испанском |
| description_ru | TEXT | Да | Описание на русском |
| short_description_es | TEXT | Нет | Краткое описание ES |
| short_description_ru | TEXT | Нет | Краткое описание RU |
| address | TEXT | Да | Адрес |
| city | TEXT | Да | Город |
| province | TEXT | Да | Провинция |
| postal_code | TEXT | Да | Почтовый индекс |
| zone | TEXT | Нет | Район/зона |
| lat | REAL | Да | Широта |
| lng | REAL | Да | Долгота |
| area | INTEGER | Да | Площадь (m²) |
| price | INTEGER | Да | Цена (EUR) |
| price_per_m2 | INTEGER | Нет | Цена за m² |
| bedrooms | INTEGER | Нет | Спальни (для домов) |
| bathrooms | INTEGER | Нет | Ванные (для домов) |
| water | TEXT | Да | water status: available, unavailable, planned |
| electricity | TEXT | Да | electricity status |
| phone | TEXT | Да | phone status |
| drainage | TEXT | Да | drainage status |
| road | TEXT | Да | road type: asphalt, dirt, planned |
| gas | TEXT | Да | gas status |
| orientation | TEXT | Да | north, south, east, west |
| views_sea | BOOLEAN | Да | Вид на море |
| views_mountain | BOOLEAN | Да | Вид на горы |
| views_valley | BOOLEAN | Да | Вид на долину |
| topography | TEXT | Да | flat, slope, terraced |
| has_ruins | BOOLEAN | Да | Есть руины |
| has_license | BOOLEAN | Да | Есть лицензия |
| is_buildable | BOOLEAN | Да | Можно строить |
| max_floors | INTEGER | Нет | Макс. этажей |
| buildability_ratio | REAL | Нет | Коэф. застройки |
| images | TEXT (JSON) | Да | Массив URL изображений |
| videos | TEXT (JSON) | Нет | Массив URL видео |
| badges | TEXT (JSON) | Нет | Метки: new, exclusive, featured |
| meta_title_es | TEXT | Нет | SEO title ES |
| meta_title_ru | TEXT | Нет | SEO title RU |
| meta_description_es | TEXT | Нет | SEO description ES |
| meta_description_ru | TEXT | Нет | SEO description RU |
| views_count | INTEGER | Да | Счётчик просмотров |
| favorite_count | INTEGER | Да | Счётчик избранного |
| inquiry_count | INTEGER | Да | Счётчик заявок |
| is_featured | BOOLEAN | Да | Рекомендуемый |
| is_exclusive | BOOLEAN | Да | Эксклюзивный |
| agent_id | TEXT | Да | ID агента |
| created_at | TEXT (ISO) | Да | Дата создания |
| updated_at | TEXT (ISO) | Да | Дата обновления |
| published_at | TEXT (ISO) | Нет | Дата публикации |

#### Индексы
- `idx_property_slug` ON slug
- `idx_property_type` ON type
- `idx_property_status` ON status
- `idx_property_city` ON city
- `idx_property_price` ON price

### 2.2 Lead (Заявка)

| Поле | Тип | Обязательно | Описание |
|------|-----|--------------|----------|
| id | TEXT (UUID) | Да | Уникальный идентификатор |
| name | TEXT | Да | Имя клиента |
| email | TEXT | Да | Email |
| phone | TEXT | Да | Телефон |
| message | TEXT | Нет | Сообщение |
| property_id | TEXT | Нет | ID интересующего объекта |
| property_ids | TEXT (JSON) | Нет | Массив ID объектов |
| budget_min | INTEGER | Нет | Мин. бюджет |
| budget_max | INTEGER | Нет | Макс. бюджет |
| currency | TEXT | Да | EUR, USD, RUB |
| language | TEXT | Да | Предпочитаемый язык |
| source | TEXT | Да | whatsapp, webform, phone, email |
| utm_source | TEXT | Нет | UTM Source |
| utm_medium | TEXT | Нет | UTM Medium |
| utm_campaign | TEXT | Нет | UTM Campaign |
| status | TEXT | Да | new, contacted, qualified, negotiating, closed, lost |
| priority | TEXT | Да | low, medium, high, urgent |
| notes | TEXT | Нет | Заметки |
| assigned_to | TEXT | Нет | ID агента |
| created_at | TEXT (ISO) | Да | Дата создания |
| updated_at | TEXT (ISO) | Да | Дата обновления |

### 2.3 User (Пользователь)

| Поле | Тип | Обязательно | Описание |
|------|-----|--------------|----------|
| id | TEXT (UUID) | Да | Уникальный идентификатор |
| email | TEXT | Да | Email (уникальный) |
| password_hash | TEXT | Да | Хеш пароля |
| name | TEXT | Да | Имя |
| role | TEXT | Да | admin, agent, editor |
| avatar | TEXT | Нет | URL аватара |
| phone | TEXT | Нет | Телефон |
| language | TEXT | Да | es, ru |
| is_active | BOOLEAN | Да | Активен |
| last_login_at | TEXT (ISO) | Нет | Последний вход |
| created_at | TEXT (ISO) | Да | Дата создания |
| updated_at | TEXT (ISO) | Да | Дата обновления |

### 2.4 Testimonial (Отзыв)

| Поле | Тип | Обязательно | Описание |
|------|-----|--------------|----------|
| id | TEXT (UUID) | Да | Уникальный идентификатор |
| name | TEXT | Да | Имя клиента |
| avatar | TEXT | Нет | URL аватара |
| location | TEXT | Да | Местоположение |
| rating | INTEGER | Да | Оценка 1-5 |
| text_es | TEXT | Да | Текст ES |
| text_ru | TEXT | Да | Текст RU |
| property_id | TEXT | Нет | ID объекта |
| is_approved | BOOLEAN | Да | Одобрен |
| is_featured | BOOLEAN | Да | Рекомендуемый |
| created_at | TEXT (ISO) | Да | Дата создания |

### 2.5 FAQ (Вопрос-ответ)

| Поле | Тип | Обязательно | Описание |
|------|-----|--------------|----------|
| id | TEXT (UUID) | Да | Уникальный идентификатор |
| question_es | TEXT | Да | Вопрос ES |
| question_ru | TEXT | Да | Вопрос RU |
| answer_es | TEXT | Да | Ответ ES |
| answer_ru | TEXT | Да | Ответ RU |
| category | TEXT | Да | Категория |
| order_num | INTEGER | Да | Порядок |
| is_active | BOOLEAN | Да | Активен |

### 2.6 Service (Услуга)

| Поле | Тип | Обязательно | Описание |
|------|-----|--------------|----------|
| id | TEXT (UUID) | Да | Уникальный идентификатор |
| icon | TEXT | Да | Имя иконки |
| title_es | TEXT | Да | Название ES |
| title_ru | TEXT | Да | Название RU |
| description_es | TEXT | Да | Описание ES |
| description_ru | TEXT | Да | Описание RU |
| order_num | INTEGER | Да | Порядок |
| is_active | BOOLEAN | Да | Активна |

### 2.7 Settings (Настройки)

| Поле | Тип | Описание |
|------|-----|----------|
| key | TEXT | Ключ настройки |
| value | TEXT | Значение (JSON) |

**Системные настройки:**
- `site_name` - Название сайта
- `phone` - Телефон
- `whatsapp` - WhatsApp номер
- `email` - Email
- `address` - Адрес (JSON)
- `social` - Социальные сети (JSON)
- `default_map_center` - Центр карты по умолчанию (JSON)
- `default_map_zoom` - Масштаб карты

### 2.8 Analytics Event (Событие аналитики)

| Поле | Тип | Описание |
|------|-----|----------|
| id | TEXT (UUID) | Уникальный идентификатор |
| type | TEXT | Тип события |
| property_id | TEXT | ID объекта (если применимо) |
| session_id | TEXT | ID сессии |
| ip_address | TEXT | IP адрес |
| user_agent | TEXT | User Agent |
| metadata | TEXT (JSON) | Метаданные |
| created_at | TEXT (ISO) | Дата создания |

---

## 3. API Endpoints

### 3.1 Недвижимость

```
GET    /api/properties              # Список объектов (?type=&status=&city=&minPrice=&maxPrice=&minArea=&maxArea=&page=&limit=)
GET    /api/properties/:slug        # Детали по slug
GET    /api/properties/featured     # Рекомендуемые
POST   /api/properties              # Создать (admin)
PUT    /api/properties/:id          # Обновить (admin)
DELETE /api/properties/:id          # Удалить (admin)
GET    /api/properties/search       # Поиск (?q=)
```

### 3.2 Заявки

```
GET    /api/leads                   # Список заявок (admin)
GET    /api/leads/:id               # Детали заявки (admin)
POST   /api/leads                   # Создать заявку (public)
PUT    /api/leads/:id                # Обновить (admin)
PUT    /api/leads/:id/status        # Изменить статус (admin)
DELETE /api/leads/:id               # Удалить (admin)
```

### 3.3 Контент

```
GET    /api/testimonials           # Список отзывов
POST   /api/testimonials           # Создать (admin)
GET    /api/faq                    # Список FAQ
GET    /api/services               # Список услуг
GET    /api/settings               # Настройки сайта
```

### 3.4 Аналитика

```
POST   /api/analytics/event        # Записать событие
GET    /api/analytics/stats        # Статистика (admin)
```

### 3.5 Авторизация

```
POST   /api/auth/login             # Вход
POST   /api/auth/logout            # Выход
GET    /api/auth/me                # Текущий пользователь
```

---

## 4. Страницы Frontend

### 4.1 Публичные страницы

1. **Landing Page** (`/`)
   - Hero секция с CTA
   - Преимущества
   - Каталог с фильтрами
   - Интерактивная карта
   - Статистика
   - Услуги
   - Отзывы
   - FAQ
   - Контактная форма
   - Footer

2. **Страница объекта** (`/property/:slug`)
   - Галерея изображений
   - Характеристики
   - Коммуникации
   - Документы
   - Карта
   - Калькулятор
   - Форма запроса
   - Похожие объекты

3. **Страница 404** (`/404`)

### 4.2 Админ-панель (`/admin`)

1. **Dashboard**
   - Статистика
   - Графики
   - Последние заявки

2. **Управление объектами**
   - Таблица с фильтрами
   - CRUD операции

3. **Управление заявками**
   - Таблица
   - Детали
   - Изменение статуса

4. **Управление контентом**
   - Отзывы
   - FAQ
   - Услуги

5. **Настройки**
   - Контакты
   - Социальные сети
   - SEO

---

## 5. Технологии

### Frontend
- HTML5 + CSS3
- Bootstrap 5.3
- Bootstrap Icons
- Leaflet (карты)
- Chart.js (графики)
- DataTables (таблицы)
- AOS (анимации)
- Lightbox2 (галерея)

### Backend
- Bun runtime
- Hono framework
- SQLite база данных
- Zod валидация

### Deployment
- Docker контейнер
- Порт 8080

---

## 6. Требования к проекту

### 6.1 Функциональные требования

1. **Мультиязычность**
   - Испанский (ES) - основной
   - Русский (RU)
   - Переключение без перезагрузки

2. **Каталог недвижимости**
   - Фильтрация по типу, цене, площади
   - Фильтрация по коммуникациям
   - Поиск по названию/городу
   - Карта с маркерами объектов

3. **Заявки**
   - Форма на странице объекта
   - Форма в контактах
   - WhatsApp интеграция
   - Email уведомления

4. **Админ-панель**
   - Авторизация
   - CRUD для объектов
   - Управление заявками
   - Статистика и аналитика

### 6.2 Нефункциональные требования

1. **Производительность**
   - Время загрузки страницы < 3 сек
   - Время ответа API < 500 мс

2. **Безопасность**
   - Хеширование паролей (bcrypt)
   - Защита от CSRF
   - Валидация входных данных

3. **Доступность**
   - Responsive дизайн
   - Поддержка мобильных устройств
   - SEO оптимизация