Глоссарий PIN
Единый словарь терминов платформы недвижимости PIN. Термины используются во всех документах
docs/06-services/* в одном и том же смысле. Один термин = одна строка; синонимы указаны явно.
Участники и роли
| Термин | Определение |
|---|---|
Компания (CompanyEntity) | Верхнеуровневая организация в PIN: Застройщик, Агентство, Брокер, Партнёр или ПИН. Бывший TenantEntity из Talent Identity. Дискриминатор — тип компании. |
| Застройщик / Девелопер (Developer) | Компания-владелец проектов и объектов недвижимости. Управляет проектами, шахматкой, заявками на фиксацию, договорами и эскроу. |
| Агентство | Компания риэлторов. Руководитель агентства управляет командой агентов, видит агрегированную клиентскую базу/канбан всех агентов, настраивает комиссионную политику. |
| Агент / Брокер / Риэлтор | Пользователь-менеджер агентства. Ведёт клиентскую базу, лиды, фиксации, сделки; получает комиссию. Синонимы в матрицах: Брокер, СуперАгент (не отдельная роль). |
| Независимый агент | Агент без родительской компании-агентства (CompanyId = null): работает самостоятельно, ведёт свою клиентскую базу/сделки. Отвязка от агентства и обратное присоединение — через CompanyInvitation (ADR-0061). |
| Инвестор | Самостоятельный пользователь без родительской компании. Покупатель объектов: смотрит каталог, аналитика, избранное/подборки, бронирует, участвует в сделках. |
| Менеджер ПИН (инвест-консультант ПИН) | Сотрудник компании ПИН с ролью консультанта: сквозная видимость всех сделок, ручное управление статусами/этапами, авто-участие в чатах сделок (US-MGR-01..06). |
| Служба заботы | Сотрудники ПИН для поддержки и арбитража: тикеты, расследования по аудиту, ручные вмешательства, база знаний. Уровни: наблюдатель / оператор / супервизор. |
| Администратор | Управляет пользователями, ролями и правами платформы. Вынесен за пределы основной Identity-системы (отдельные API/фронт) — см. ADR-0053. |
| Гость (аноним) | Неавторизованный пользователь: ограниченный просмотр каталога/карточек, избранное на сессии, вход в воронку по реферальной ссылке. |
| Менеджер застройщика | Пользователь компании-застройщика. Управляет проектами/объектами/фиксациями/сделками своей компании; профиль управляется из Talent Identity (не редактируется в PIN). |
| Мульти-агентство | Модель, при которой инвестор обслуживается несколькими агентствами одновременно по разным процессам (лидам/фиксациям/сделкам): нет единственной глобальной привязки «инвестор → агентство», участие определяется на уровне процесса (ADR-0070). |
| Активное агентство | Агентство, в scope которого ведётся конкретный процесс (лид/фиксация/сделка) по инвестору; определяет видимость записи и применимую комиссионную политику. При мульти-агентстве у инвестора их несколько — по одному на процесс (ADR-0070). |
| Увольнение (terminate) | Прекращение членства агента в агентстве: активные процессы/фиксации переназначаются или остаются за агентством, record-level доступ агента к записям отзывается по правилам; отличается от отвязки независимого агента (ADR-0072). |
Identity и доступ
| Термин | Определение |
|---|---|
| Scoped-RBAC | Модель авторизации PIN: роль с permissions назначается в scope (платформа / организация / группа проектов / проект) с наследованием по иерархии ресурсов. |
| Record-level доступ | Доступ к конкретной записи по владельцу и группам (например, фиксации видят агент-владелец и его руководитель/группа). |
| Permission | Атомарное право на действие/фичу (например crm.deals.view). Заполняется владельцами платформы через SEED. |
Роль (RoleDefinition) | Именованный набор permissions в рамках компании; связи «роль↔permission» и «пользователь↔роль» — many-to-many. |
| Workspace | Рабочее пространство компании: её пользователи, данные и настройки, изолированные scope-ом. |
| СМС-вход | Аутентификация по номеру телефона: запрос кода → подтверждение → JWT (nextAction=FillName для новых). Реализуется в контексте identity. |
| Lazy-регистрация | Автосоздание инвестора по имени+телефону при заявке (консультация/бронь); Имя обновляется, если пустое. |
Приглашение в компанию (CompanyInvitation) | Агрегат identity: приглашение агента/пользователя в агентство по номеру телефона (invite / accept / decline / revoke), отделённое от создания учётки. Приём меняет членство (независимый агент → агент агентства) (ADR-0061). |
Каталог и шахматка
| Термин | Определение |
|---|---|
| Шахматка (chessboard) | Матрица объектов проекта: этажи × секции/подъезды с цветовой индикацией статусов. Также — сервис-владелец структуры проектов/объектов. |
| Проект (ЖК/отель) | Единица застройки застройщика: жилой комплекс, апарт-отель. Имеет здания/литеры, статусы строительства, декларации. |
| Здание / Литер / Корпус | Строение внутри проекта; содержит этажи и объекты. |
Объект недвижимости (PropertyObject; синонимы: Flat / Lot / Apartment) | Единица недвижимости: площадь (общая/жилая), этаж, комнатность, цена, статус. Каноническое имя — «Объект недвижимости» (PropertyObject) во всём ТЗ и коде (ADR-0058). |
| Статус объекта | Свободен → Резерв (таймер, 1 ч) → Бронь (по программе) → Продан; Скрыт — не отображается. |
Планировка (Layout) / Группа планировок (LayoutGroup) | Типовая планировка объекта и её группа; основа правил вознаграждений и эконом-модели по типам лотов. |
| Банк / Отельер | Справочники шахматки (Id, Название, Лого). Банк — участник сделки/эскроу; отельер — оператор апарт-отеля. |
| Публичный каталог | Денормализованная витрина объектов: лента, поиск, фильтры, карточки, ранжирование, пакеты продвижения. |
Продвижение / Пакет продвижения (PromotionPackage) | Правило приоритета показа для полиморфного таргета (проект / объект недвижимости / агент / пост) — монетизация; оплата пока не реализуется. Владелец — отдельный контекст promotion; consumers — catalog (приоритет в витрине) и news (промо-блоки) (ADR-0060). |
| Оверрайд | Локальная правка данных объекта/корпуса поверх данных источника (Talent Chessboard); владелец — контекст catalog. |
Инвест-аналитика и покупка
| Термин | Определение |
|---|---|
| История цен | Append-only лента изменений цены объекта (ClickHouse); источник графика роста. |
| Экономическая модель | Параметры расчёта доходности (рост цены, аренда/м², заполняемость, расходы, налоги) на уровне платформы (model_config), типа лота (lot_type_config) и помесячных оверрайдов. |
Серия инвестора (InvestorMonth) | Помесячный расчёт: цена, доход от роста, аренда, EBITDA, налоги, ROI — для графиков и сводки (AsideMetrics). |
| Программа покупки | Способ оплаты: 100% оплата (со скидкой), рассрочки (InstallmentPreset, milestone-платежи), ипотека (ставка/срок). Определяет график платежей. |
| Окупаемость (payback) | Срок возврата инвестиций объекта; показывается в карточке. |
CRM и сделки
| Термин | Определение |
|---|---|
| Лид | Активная связь «инвестор ↔ агент» (о ней не знает застройщик): карточка пути клиента (хотелки: бюджет/срочность/цели; события: просмотры, подборки, заявки). У пары одновременно только один активный лид; срок жизни ~месяц, продлевается. |
| Заявка на фиксацию | Запрос агента застройщику закрепить клиента (ФИО+телефон) за агентом. Статусы: ожидает / зафиксирован уникальный / зафиксирован не уникальный / отклонён. Дубли ищутся по ФИО/телефону (FTS). |
| Фиксация (фиксация-авторизация) | Одобренная застройщиком заявка — авторизация, а не сделка: подтверждает право агента вести клиента по объектам застройщика и основание комиссии, но сделку не создаёт (событие fixation-approved не несёт DealId). Одна одобренная фиксация авторизует много сделок пары «клиент × застройщик» (1:N, связь со стороны сделки). Активная фиксация на пару (агент+инвестор+застройщик) — одна. |
| Намерение бронирования (Booking Intent) | «Хотелка на конкретный объект» в рамках лида: какой объект инвестор готов купить/забронировать. Инициирует сам инвестор (InvestorAdded, подтверждено сразу) или агент, предложивший объект (AgentProposed, ждёт подтверждения инвестором — Flow B). На пару (лид, объект) — одно активное; из подтверждённого намерения + одобренной фиксации раскрывается сделка. Владелец — контекст crm (LeadBookingIntentEntity, дочернее лида). |
| Сделка (Deal) | Процесс покупки: инвестор + агент + застройщик + объект. Создаётся из лида по объекту сразу в заявке (Application, если выполнен гейт вовлечения застройщика) либо в черновике (Draft). Статусы: черновик / заявка / бронь / продажа / отказ. Владелец — контекст crm. |
| Draft-сделка (черновик сделки) | Предварительная сделка агента с инвестором по объекту, до вовлечения застройщика: видна агенту/инвестору/Менеджеру ПИН, но невидима застройщику (developer-канбан и статистика фильтруют Status != Draft); состав без SellManager, PaymentMethod может быть пуст. Переходит в Application через гейт вовлечения застройщика (подтверждённое намерение + одобренная фиксация + способ оплаты) — операция «вовлечь застройщика» (engage-developer). |
| Этап воронки (Step) | Позиция сделки на канбане. Системные группы этапов — SEED/enum (меняем только мы); настраиваемые этапы — создаёт застройщик, каждый привязан к группе. Доска одна. |
| Участник сделки (Member) | Пользователь в сделке с ролью: Investor, Agent, SellManager (менеджер застройщика); + Менеджер ПИН (авто). |
| Участник процесса | Обобщённая модель вовлечённости пользователя в процесс CRM (лид/фиксация/сделка): кто участвует и с каким правом. Единая модель участников/владения вместо плоского «участника сделки» (ADR-0071). |
| Исполнитель (Executor) | Участник процесса, фактически ведущий работу с клиентом (обычно агент). При co-broking может отличаться от ответственного (ADR-0071). |
| Ответственный (Responsible) | Участник процесса, за которым закреплено владение записью и итоговая подотчётность (комиссия, видимость руководителя/группы) — record-level владелец (ADR-0071). |
| Основной инвестор | Ключевой инвестор процесса при нескольких участниках-инвесторах; к нему привязываются фиксация, вознаграждение и Origin-снапшот (ADR-0071). |
| Origin-снапшот | Иммутабельный снимок происхождения процесса (кто/какое агентство/по какой реферальной связи начал) на момент старта; фиксирует условия для последующих начислений независимо от дальнейших изменений участников (ADR-0071). |
| Co-broking | Совместное ведение процесса двумя агентствами/агентами: разделение ролей «исполнитель/ответственный» и распределение вознаграждения между сторонами (ADR-0069). |
| Резерв | Краткая блокировка объекта (1 час, таймер) после заявки на бронирование. |
| Бронь | Подтверждённое бронирование по программе застройщика (бесплатная 4 ч / платная 10-50 т.р. на 10 дней и т.п.), с таймером и оплатой (US-INV-21). |
| Программа бронирования | Настройки застройщика: платность, сумма, длительность брони. |
| Эскроу | Счёт в банке сделки для расчётов по ДДУ; инвестор указывает номер, статус отслеживается. |
| ДДУ / ДКП | Тип сделки: договор долевого участия / купли-продажи. Влияет на этапы. |
| Таймлайн сделки | Лента событий сделки с датами и статусами (выполнено/в процессе/просрочено). |
| Чат сделки | Групповой чат участников сделки в собственном мини-мессенджере PIN (SignalR realtime, ADR-0055); события-карточки (целевые действия, инфо). |
Вовлечение и контент
| Термин | Определение |
|---|---|
| Избранное | Отметки объектов пользователя ИЛИ гостевой сессии + заметка (≤4000 символов). При авторизации — слияние по выбранной стратегии. |
| Подборка (Selection) | Именованный набор объектов с владельцем и публичной ссылкой; создаётся вручную или из избранного; для поста создаётся иммутабельная копия. |
| Пост / Новость | Блочный контент (текст / галерея / блок-подборка — typed jsonb) с категориями по типам авторов; история изменений — полными snapshot-ами. |
| Сессия | Гостевая/пользовательская сессия с anonymous_id; связывает действия до и после входа. Поля CreatedAt/LastActivityAt/Status; закрывается polling-worker-ом при неактивности 10–15 мин с событием session-ended (ADR-0056). |
| Просмотр лота (LotView) | Запись открытия объекта: CreatedAt/LastActivityAt; длительность = delta; закрывается тем же polling-ом с событием lot-view-ended. |
| Статистика просмотров лота (LotViewStats) | Агрегат по объекту: сколько раз и как долго просматривался (ViewsCount, TotalDuration, LastViewedAt). |
Статистика для застройщика (dev-stats) | ClickHouse-аналитика внимания к недвижимости застройщика: кто/сколько/как долго/как часто смотрит проекты/здания/планировки/группы/объекты; фильтры дата+застройщик(+проект…); глубина 3 года (ADR-0057). |
| Трекинг действий | События пользователя: просмотры (с длительностью), фильтры, избранное, подборки — пробрасываются в карточку лида. |
| Реферальная ссылка | Ссылка пользователя (много, по каналам) для приглашения; фиксируется cookie 30 дней (referralUrl). |
| Реферальная связь | Привязка «кто привёл» для будущих выплат; создаётся по правилам (Имя пустое / регистрация < 4 ч / владелец-агент). |
| Заявка на презентацию / консультацию | Лид-форма (ФИО+телефон [+дата/время, объект, подборка]) из каталога или подборки; создаёт лида по правилам реферальной привязки. |
Инвестор-собственник и вознаграждения
| Термин | Определение |
|---|---|
| Собственник (Owner) | Владелец купленного объекта. Инвестор сопоставляется с OwnerEntity по номеру телефона (id совпадают). |
| Объект инвестора | Купленный объект в портфеле: цены покупки/продажи, доход, история цен. Появляется после завершения сделки в CRM. |
| Правило вознаграждения | Настройка застройщика: % комиссии от базовой (до ремонта/скидки) или конечной цены; условия по типу объекта / Layout / LayoutGroup / комнатности / площади. |
| Комиссионная политика агентства | Распределение комиссии внутри агентства на агентов; платёжные поручения, история выплат. Статусы комиссии: подтверждено / ожидает подтверждения. |
| Ставка реферального вознаграждения | Величина (% или сумма) вознаграждения за реферальную связь/сделку; задаётся в scope с наследованием по иерархии — см. Scoped-ставки (ADR-0068). |
| Scoped-ставки | Ставки вознаграждения, назначаемые в scope (платформа → застройщик → проект → планировка) с наследованием; при расчёте действует наиболее специфичная (ADR-0068). |
| Условия по застройщику / проекту / планировке | Уровни применимости правил и ставок вознаграждения; чем уже уровень, тем выше приоритет при выборе ставки для начисления. |
| Акция ставки | Временное промо-условие поверх базовых scoped-ставок: повышенная/специальная ставка на период. |
| agent-boost | Персональная надбавка к ставке конкретного агента (бустер вознаграждения) на период/условие. |
| Реферальное начисление | Рассчитанная к выплате сумма по реферальной связи/сделке согласно применимой ставке; становится доступной только через гейт получения денег. |
| Удержание ПИН | Доля платформы ПИН, удерживаемая из вознаграждения/поступления перед выплатой агенту/агентству. |
| Акт поступления средств | Документ-факт поступления денег (от застройщика/по сделке); триггер разблокировки начислений и выплат. |
| Гейт получения денег | Условие-предохранитель: начисление доступно к выплате только после подтверждённого поступления средств (акта); до этого — заморожено. |
| Кошелёк (wallet) | Счёт пользователя/агентства в контексте wallet: баланс начислений (доступное/замороженное), история операций и выплат. |
Справочники (handbook)
| Термин | Определение |
|---|---|
| Справочник | Мастер-данные общего пользования (банки, отельеры, типы, статусы и пр.), которыми контекст handbook владеет как единым источником истины. |
| Snapshot справочника | Иммутабельный снимок значения справочника на момент использования (в сделке/акте/начислении): фиксирует название/атрибуты, чтобы последующее изменение справочника не переписывало историю. |
| Реплика справочника | Локальная read-only копия справочника в контексте-потребителе, синхронизируемая событиями handbook; используется для отображения/фильтров без обращения к владельцу. |
Календарь и записи (calendar)
| Термин | Определение |
|---|---|
| Слот доступности | Интервал времени, в который исполнитель (агент/консультант) доступен для записи; основа расписания в контексте calendar. |
| Запись (Appointment) | Забронированный слот встречи (консультация/показ) с участниками, временем и статусом; создаётся из лид-формы или вручную. |
| Показ | Тип записи — очный/онлайн показ объекта недвижимости инвестору; привязан к объекту/проекту. |
| Дедлайн брони | Крайний срок подтверждения/оплаты брони; по его наступлении бронь снимается и объект освобождается — контролируется таймерами/календарём. |
| AutoConfirm | Режим автоматического подтверждения записи в свободный слот без ручного согласования исполнителем. |
| cutoff | Минимальный зазор до начала слота, после которого запись/перенос/отмена уже недоступны (порог отсечки). |
Технические термины
| Термин | Определение |
|---|---|
| Talent Identity / Talent Chessboard / Talent Owners | Внешние сервисы компании Talent — источники данных (Kafka/API) о компаниях-застройщиках и их пользователях, объектах недвижимости, собственниках. |
Talent.Common.* | Shared SDK (.NET 9): базовые сущности/агрегаты/репозитории/CQRS/Kafka/outbox — см. docs/11-backend-sdk/. |
Конверт RestApiResponse | Стандартная обёртка ответов .NET API (+RequestTraceModel). |
| anonymous_id | Идентификатор гостевой сессии для избранного/просмотров/трекинга до авторизации. |
Обратные ссылки
Автоссылки: где используется этот документ.
- API (1): POST /api/public/crm/payment-schedule — Серверный график платежей (витрина)
- index.md (11): Документация PIN, Calendar Service, Chessboard Service (Pin.Chessboard), CRM Service, DevStats Service (Pin.DevStats), Messenger Service, News Service (Pin.News), Profile Service (Pin.Profile), Referral Service, Rewards Service, Support Service
- registries (1): Реестр сущностей PIN
Связанные документы
- technical-assignment.md — нормализованное ТЗ по контекстам.
- service-boundaries.md — карта контекстов и владение данными.
- prototype-mapping.md — навигация «UI-поверхность/возможность → контекст → UC/US → ТЗ».