TenerifeProp/docs/ARCHITECTURE.md

TenerifeProp - Архитектура агентства недвижимости на Тенерифе

📋 Обзор проекта

TenerifeProp — веб-приложение для агентства недвижимости на острове Тенерифе (Канарские острова, Испания). Позволяет просматривать, фильтровать и подбирать земельные участки, дома и квартиры. Включает публичную часть (Landing, каталог, страница объекта) и административную панель.

🏗️ Сущности данных

Основные сущности

Сущность	Описание	Файл
Property	Недвижимость (участки, дома, квартиры)	src/types/property.ts
Lead	Потенциальный клиент (заявка)	src/types/user.ts
User	Пользователь системы (админ, агент)	src/types/user.ts
Testimonial	Отзыв клиента	src/types/content.ts
Service	Услуга агентства	src/types/content.ts
FAQ	Вопрос-ответ	src/types/content.ts
Settings	Настройки сайта	src/types/content.ts

Типы недвижимости

type PropertyType = 
  | 'agricultural'  // Сельскохозяйственный участок
  | 'urban'         // Городской участок
  | 'house'         // Дом/вилла
  | 'apartment'     // Квартира
  | 'ruins'         // Руины (под восстановление)

Статусы недвижимости

type PropertyStatus = 
  | 'active'    // Активен (в продаже)
  | 'reserved'  // Зарезервирован
  | 'sold'      // Продан
  | 'inactive'  // Неактивен

Статусы лидов

type LeadStatus = 
  | 'new'         // Новая заявка
  | 'contacted'   // Связались
  | 'qualified'   // Квалифицирован
  | 'negotiating' // Переговоры
  | 'closed'      // Сделка закрыта
  | 'lost'        // Потерян

📁 Структура файлов

TenerifeProp/
├── public/                     # Публичные файлы
│   ├── index.html              # Главная страница (Landing)
│   ├── property.html           # Страница объекта
│   ├── admin.html              # Админ-панель
│   ├── css/
│   │   ├── variables.css       # CSS переменные (цвета, шрифты)
│   │   ├── main.css            # Основные стили
│   │   ├── property.css        # Стили страницы объекта
│   │   └── admin.css           # Стили админки
│   ├── js/
│   │   ├── app.js              # Главная логика приложения
│   │   ├── property.js         # Логика страницы объекта
│   │   ├── admin.js            # Логика админки
│   │   ├── map.js              # Инициализация карты (Leaflet)
│   │   ├── charts.js           # Графики (Chart.js)
│   │   ├── i18n.js             # Система переводов
│   │   └── utils.js            # Утилиты
│   └── images/
│       ├── properties/         # Фото объектов
│       ├── agents/             # Фото агентов
│       └── icons/              # Иконки
├── src/
│   ├── types/                  # TypeScript типы
│   │   ├── property.ts         # Типы недвижимости
│   │   ├── user.ts             # Типы пользователей и лидов
│   │   ├── content.ts          # Типы контента
│   │   └── index.ts            # Экспорт
│   ├── data/                   # JSON база данных
│   │   ├── properties.json     # Объекты недвижимости
│   │   ├── leads.json          # Заявки
│   │   ├── testimonials.json   # Отзывы
│   │   ├── faq.json            # FAQ
│   │   └── services.json       # Услуги
│   ├── i18n/                   # Переводы
│   │   ├── es.json             # Испанский (основной)
│   │   ├── ru.json             # Русский
│   │   └── en.json              # Английский
│   └── utils/
│       ├── format.ts           # Форматирование данных
│       ├── validation.ts       # Валидация форм
│       └── api.ts              # API клиент
├── docs/                       # Документация
│   ├── ARCHITECTURE.md         # Этот файл
│   ├── API.md                  # Документация API
│   └── DEPLOYMENT.md           # Инструкции по деплою
├── .gitignore                  # Игнорируемые файлы
├── package.json                # Зависимости проекта
├── tsconfig.json               # Конфигурация TypeScript
└── README.md                   # Описание проекта

🔗 API Endpoints

Недвижимость (Properties)

Метод	Endpoint	Описание
GET	/api/properties	Список объектов с фильтрами
GET	/api/properties/:id	Детали объекта
GET	/api/properties/:slug	Детали по slug
POST	/api/properties	Создать объект
PUT	/api/properties/:id	Обновить объект
DELETE	/api/properties/:id	Удалить объект
GET	/api/properties/featured	Избранные объекты
GET	/api/properties/search	Поиск с фильтрами

Заявки (Leads)

Метод	Endpoint	Описание
GET	/api/leads	Список заявок
GET	/api/leads/:id	Детали заявки
POST	/api/leads	Создать заявку (форма)
PUT	/api/leads/:id	Обновить заявку
PUT	/api/leads/:id/status	Изменить статус
POST	/api/leads/:id/interaction	Добавить взаимодействие

Пользователи (Users)

Метод	Endpoint	Описание
POST	/api/auth/login	Авторизация
POST	/api/auth/logout	Выход
GET	/api/users/me	Текущий пользователь
PUT	/api/users/me	Обновить профиль

Аналитика (Analytics)

Метод	Endpoint	Описание
GET	/api/analytics/stats	Статистика (Dashboard)
GET	/api/analytics/events	События
POST	/api/analytics/event	Записать событие

Контент (Content)

Метод	Endpoint	Описание
GET	/api/testimonials	Отзывы
GET	/api/faq	FAQ
GET	/api/services	Услуги
GET	/api/pages/:slug	Страница по slug
GET	/api/settings	Настройки сайта

🎨 Компоненты UI

Публичная часть (Landing)

1. Header/Navbar - Навигация, переключатель языка
2. Hero - Главный баннер с CTA
3. Advantages - Преимущества агентства
4. Catalog - Каталог с фильтрами
5. PropertyCard - Карточка объекта
6. Map - Интерактивная карта (Leaflet)
7. Statistics - Статистика в цифрах
8. Services - Услуги агентства
9. Testimonials - Отзывы клиентов
10. FAQ - Вопросы-ответы
11. Contact - Форма контакта
12. Footer - Подвал с контактами

Страница объекта (Property)

1. Gallery - Галерея изображений
2. PropertyHeader - Заголовок, цена, характеристики
3. Utilities - Коммуникации (вода, свет, etc.)
4. Documents - Документы
5. Map - Карта с местоположением
6. Calculator - Калькулятор ипотеки/налогов
7. ContactForm - Форма запроса
8. SimilarProperties - Похожие объекты

Админ-панель

1. Sidebar - Навигация по разделам
2. Topbar - Поиск, уведомления, профиль
3. Dashboard - Статистика, графики
4. PropertyTable - Таблица объектов (DataTables)
5. PropertyForm - Форма создания/редактирования
6. LeadTable - Таблица заявок
7. LeadDetail - Детали заявки
8. ContentEditor - Редактор контента

🛠️ Технологии

Frontend

Технология	Версия	Назначение
HTML5	-	Семантическая разметка
CSS3	-	Стили, анимации
Bootstrap	5.3.2	UI Framework
Bootstrap Icons	1.11.1	Иконки
Leaflet	1.9.4	Интерактивные карты
Chart.js	4.4.1	Графики
DataTables	1.13.8	Таблицы с пагинацией
AOS	2.3.4	Анимации при скролле
Lightbox2	2.11.4	Галерея изображений

Рекомендуемый Backend

Технология	Назначение
Node.js + Express или Bun + Hono	API сервер
SQLite или PostgreSQL	База данных
JWT	Авторизация
Multer	Загрузка файлов

Deployment

Платформа	Назначение
Vercel / Netlify	Статический хостинг (Frontend)
Railway / Render	API сервер (Backend)
Cloudflare R2	Хранилище изображений

🔄 Рефакторинг из HTML артефактов

Переименование файлов

Артефакт	Новый файл
artifact-...-6.html	public/index.html
artifact-...-7.html	public/property.html
artifact-...-8.html	public/admin.html

Извлечение CSS

CSS встроен в <style> внутри HTML. Нужно:

1. Создать public/css/variables.css с CSS-переменными:

   • --primary: #1a5f4a
   • --secondary: #d4a853
   • --accent: #e85d04
   • и т.д.

2. Создать public/css/main.css с общими стилями для Landing

3. Создать public/css/property.css со стилями страницы объекта

4. Создать public/css/admin.css со стилями админки

Извлечение JavaScript

JavaScript встроен в <script> внутри HTML. Нужно:

1. Создать public/js/i18n.js для системы переводов:

   • Загрузка JSON файла языка
   • Функция t(key) для перевода
   • Переключение языка

2. Создать public/js/app.js:

   • Инициализация компонентов
   • Фильтрация каталога
   • Карта Leaflet
   • Обработка форм

3. Создать public/js/admin.js:

   • Инициализация DataTables
   • CRUD операции
   • Графики Chart.js

🌍 Система переводов (i18n)

Структура JSON перевода

// src/i18n/es.json
{
  "nav": {
    "home": "Inicio",
    "catalog": "Catálogo",
    ...
  },
  "hero": {
    "title1": "Terrenos y Propiedades",
    ...
  }
}

HTML атрибуты

<h1 data-i18n="hero.title1">Terrenos y Propiedades</h1>
<p data-i18n="hero.subtitle">Encuentra tu terreno perfecto...</p>

JavaScript

// public/js/i18n.js
class I18n {
  constructor() {
    this.lang = 'es';
    this.translations = {};
  }
  
  async setLanguage(lang) {
    this.lang = lang;
    this.translations = await fetch(`/src/i18n/${lang}.json`).then(r => r.json());
    this.updateElements();
  }
  
  updateElements() {
    document.querySelectorAll('[data-i18n]').forEach(el => {
      const key = el.getAttribute('data-i18n');
      el.textContent = this.t(key);
    });
  }
  
  t(key) {
    const keys = key.split('.');
    let value = this.translations;
    keys.forEach(k => value = value?.[k]);
    return value || key;
  }
}

📊 Пример данных

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

{
  "id": "prop-001",
  "slug": "terreno-urbano-adeje",
  "type": "urban",
  "status": "active",
  "title": {
    "es": "Terreno Urbano en Adeje",
    "ru": "Городской участок в Адехе"
  },
  "area": 2500,
  "price": 385000,
  "pricePerM2": 154,
  "location": {
    "city": "Adeje",
    "zone": "Costa Adeje",
    "coordinates": { "lat": 28.1227, "lng": -16.6942 }
  },
  "utilities": {
    "water": "available",
    "electricity": "available",
    "road": "asphalt"
  }
}

🚀 План реализации

Фаза 1: Подготовка (1-2 дня)

• Создать структуру директорий
• Переименовать артефакты
• Создать TypeScript типы
• Создать JSON данные
• Создать i18n файлы

Фаза 2: Рефакторинг (2-3 дня)

• Вынести CSS в отдельные файлы
• Вынести JS в модули
• Настроить систему i18n
• Рефакторинг HTML компонентов

Фаза 3: Backend (3-5 дней)

• Настроить API сервер (Bun + Hono)
• Реализовать CRUD для Property
• Реализовать CRUD для Lead
• Добавить авторизацию

Фаза 4: Frontend (3-4 дня)

• Подключить API к Frontend
• Реализовать фильтры
• Настроить карты
• Оптимизация

Фаза 5: Деплой (1-2 дня)

• Сборка проекта
• Деплой на Vercel
• Тестирование
• Мониторинг

📝 Лицензия

MIT License - проект создан для UniqueSoft.