kleekTo

CRM для агентств недвижимости. Рынок — Грузия.

Продукт состоит из веб-приложения и расширения Chrome. Агент открывает объявление на ss.ge или myhome.ge, сам раскрывает телефон собственника, звонит — и одним действием фиксирует результат разговора. Объект попадает в базу только после согласия собственника.

Интерфейс работает на трёх языках: грузинском, английском и русском.

---

Что нужно на машине

Инструмент	Версия	Зачем
Node.js	22 или новее	Используется встроенный process.loadEnvFile
pnpm	11 или новее	Монорепозиторий на workspaces
Docker	любой свежий	Локальный PostgreSQL

Проверить: node -v && pnpm -v && docker -v

Запуск с нуля

git clone <адрес репозитория>
cd kleekTo

pnpm install
cp .env.example .env          # значения по умолчанию рабочие, править не нужно

pnpm db:up                    # поднять PostgreSQL в Docker
pnpm db:generate              # сгенерировать клиент Prisma
pnpm db:migrate               # применить миграции
pnpm db:seed                  # тестовые данные: две компании

pnpm dev                      # http://localhost:3000

Готово. Открой http://localhost:3000/api/v1/health — там должно быть:

{ "status": "ok", "database": "up", "version": "0.1.0", "databaseLatencyMs": 6 }

Если "status": "degraded" и код 503 — приложение живо, но не видит базу. Проверь pnpm db:up.

Команды

pnpm dev                # веб-приложение в режиме разработки
pnpm build              # сборка всех пакетов
pnpm typecheck          # типы
pnpm lint               # линтер и проверка форматирования
pnpm format             # применить форматирование
pnpm test               # тесты, база не нужна
pnpm test:integration   # тесты на живой базе

pnpm db:up              # поднять PostgreSQL
pnpm db:down            # остановить
pnpm db:generate        # клиент Prisma
pnpm db:migrate         # применить миграции (разработка)
pnpm db:seed            # тестовые данные: две компании, роли, статусы воронки
pnpm db:studio          # просмотр базы в браузере

Перед коммитом должны быть зелёными все четыре: typecheck, lint, test, build. То же самое проверяет CI на каждый push.

Структура

apps/
  web/          Next.js: интерфейс CRM и API по пути /api/v1/*
  extension/    Chrome MV3
packages/
  contracts/    Схемы запросов и ответов. Общие для веба и расширения
  core/         Доменная логика: сценарии, права, аутентификация. О HTTP не знает
  i18n/         Словари ka · en · ru и форматтеры
  db/           Prisma: схема, миграции, клиент
scripts/
  with-env.mjs  Подаёт корневой .env инструментам, которые ищут его в другом месте
docs/           Спецификация, архитектура, решения, дизайн

Пакет adapters появится в фазе 5 вместе с адаптерами площадок. Пустых каталогов «на будущее» в репозитории нет намеренно.

Зависимости идут только вниз, циклы запрещены:

apps/web        → contracts, core, db, i18n
apps/extension  → contracts, i18n
packages/core   → contracts, db
packages/db     → (ничего)
packages/contracts, packages/i18n → (ничего)

Направление проверяется линтером: попытка импортировать логику площадки в ядро уронит CI, а не останется на усмотрение ревью.

Расширение Chrome

Собирается вместе со всем остальным (pnpm build) в apps/extension/dist.

Установка для разработки:

1. chrome://extensions → включить «Режим разработчика»;
2. «Загрузить распакованное» → выбрать apps/extension/dist;
3. открыть объявление на ss.ge или myhome.ge, раскрыть телефон на странице, позвонить — и только потом вызвать расширение правым кликом или кнопкой.

Порядок здесь не формальность. Расширение читает DOM, который агент раскрыл своими действиями: пока номер не раскрыт, импорт заблокирован и запрос к API не уходит вообще (правило 11).

Адрес сервера подставляется на сборке и по умолчанию http://localhost:3000:

KLEEKTO_API_URL=https://app.example KLEEKTO_APP_URL=https://app.example pnpm --filter @kleekto/extension build

host_permissions в манифесте сборка приводит к этому же адресу — иначе расширение стучалось бы туда, куда ему не разрешено, и получало сетевую ошибку без внятной причины.

Окружение

Все переменные описаны в .env.example — каждая с объяснением, зачем она нужна. Файл .env в репозиторий не попадает никогда.

NODE_ENV в .env отсутствует намеренно: его выставляет сам инструмент. Значение в файле окружения сломало бы next start.

Окружение одно и лежит в корне, но Next ищет .env рядом с приложением, а Prisma — рядом с собой. Их примиряет scripts/with-env.mjs; поэтому команды запускаются через pnpm, а не напрямую.

Документы

Файл	Что там
CLAUDE.md	Правила проекта. Читается в начале каждой сессии
docs/MASTER_PROMPT.md	Мастер-промпт: правила, фазы, гейты
docs/spec/MASTER_PRODUCT_SPECIFICATION.md	Исходная спецификация. Не редактируется
docs/architecture/	Архитектура, модель данных, права, контракты API, дедупликация
docs/decisions/	ADR — по файлу на решение
docs/design/DESIGN.md	Дизайн-система, экраны, состояния
docs/progress.md	Журнал работы
docs/analysis/	Требования, противоречия, открытые вопросы, риски
docs/AUDIT.md	Аудит перед запуском: что проверено, чем, и что осталось
docs/DEPLOYMENT.md	Развёртывание на боевом окружении и установка расширения
docs/launch-checklist.md	Чек-лист готовности к первому агентству

Начинать чтение стоит с docs/architecture/system.md, затем erd.md.

Состояние

Фаза 8 из 10 — MVP собран. Полный путь агента работает от объявления до объекта и обратно: расширение читает страницу, агент звонит и одним пунктом меню фиксирует исход, объект появляется в CRM, движется по воронке и виден в сводке.

Есть: домен и изоляция арендаторов, три роли с проверкой прав на сервере, объекты и объявления, дедупликация четырёх уровней, миграция базы агентства, адаптеры чтения ss.ge и myhome.ge, расширение Chrome, веб-интерфейс CRM, дашборд по ролям, ограничение частоты входа, заголовки безопасности и CSP.

Перед первым агентством прочитайте docs/launch-checklist.md. Три пункта блокируют пилот, и два из них кодом не закрываются.

Нет: заполнения форм размещения (ждёт фикстур формы), ленты выгодных объявлений и общего индекса (фазы 9–10).