Техническое задание PIN — нормализованная структура
Нормализованное представление исходных требований по 21 bounded contexts. Источники: корневой
ТехЗадание.md (основной, референс), фиче-матрицы ТехЗадание/
(вторичный референс: роли/фичи/воронки). Навигация «UI-поверхность/возможность → контекст → ТЗ» —
prototype-mapping.md. Детальные тех задания — в docs/06-services/<context>/.
Что строим
PIN — платформа недвижимости (и одновременно риэлторское агентство): каталог объектов застройщиков
(шахматка), инвест-аналитика доходности, воронка «реферальная ссылка → лид → фиксация → бронь → сделка →
объект у собственника», кабинеты застройщика/агентства/инвестора, коммуникации (чаты сделок, уведомления).
Микросервисы + событийная архитектура (Kafka) на DDD, PostgreSQL/ClickHouse, поверх shared SDK
Talent.Common.* (.NET 9). Мессенджер — собственный мини-мессенджер (ADR-0055).
Контексты и покрытие исходного ТЗ
| Контекст | Разделы ТехЗадание.md (строки) | Акценты реализации | Детальное ТЗ |
|---|---|---|---|
identity | Сервис авторизации + детали (27–73); категории новостей по типам (47–53) | СМС/2FA/пин-вход (18+ операций); компании, роли, scope-права | 06-services/identity/ |
profile | ЛК пользователя + верификация инвестора (75–99) | ЛК, персоны, документы, верификация инвестора | 06-services/profile/ |
chessboard | Шахматка + структура данных + API (123–161) | Структура проектов/зданий/объектов; sync Talent Chessboard | 06-services/chessboard/ |
catalog | Публичный каталог (189–199) + 9 UC инвестора (163–175) | Публичная витрина: лоты, оверрайды, ранжирование | 06-services/catalog/ |
invest-analytics | Аналитика/история цен (203–208) | Эконом-модель, серии инвестора, ClickHouse-история цен | 06-services/invest-analytics/ |
rewards | Вознаграждения агентов (177–187); комиссионная политика агентства (матрица «Агенство») | Комиссии агентов, комиссионная политика агентства | 06-services/rewards/ |
referral | Реферальная/партнёрская система (319–347) | Реферальные ссылки/связи (11+4 операций), правила привязки | 06-services/referral/ |
crm | CRM (369–463) + Бронирование (465–473) + Фиксация (475–495) + ЛК застройщика (101–105) + ЛК агента (107–119) + US «Сделка» (589–660 и матрицы) | Сделки/этапы/участники, bookings/requests/purchase-config | 06-services/crm/ |
investor-owner | Сервис инвестора-собственника (227–237) | Портфель собственника; sync Talent Owners | 06-services/investor-owner/ |
news | Сервис новостей (213–223) | Ленты, посты, категории, комментарии | 06-services/news/ |
favorites | Сервис избранного (241–247) | Избранное: сервер + слияние гостевой сессии | 06-services/favorites/ |
selections | Сервис подборок (277–283) | Подборки, публичные ссылки, snapshot для постов | 06-services/selections/ |
user-activity | Сессии (263–273) + История просмотров (253–261) + Отслеживание действий (359–361) — объединены (ADR-0054) | Сессии, история просмотров, трекинг действий | 06-services/user-activity/ |
messenger | Мессенджер (287–309) + Контакты (313–315) | Собственный мини-мессенджер (SignalR, ADR-0055) | 06-services/messenger/ |
notifications | Сервис уведомлений (349–351) | Уведомления, шаблоны, каналы, настройки | 06-services/notifications/ |
support | Роль «Служба заботы» (только матрицы) | Тикеты, арбитраж, база знаний | 06-services/support/ |
dev-stats | Статистика просмотров для застройщика (указание владельца, ADR-0057): кто/сколько/как долго/как часто смотрит проекты/здания/планировки/группы/объекты; фильтры дата+застройщик(+проект, опц. здание/планировка/группа/объект); 3 года | ClickHouse facts + rollups; consumer user-activity | 06-services/dev-stats/ |
handbook | Нормативные справочники (эмерджентный; ADR-0063) | Реплики стран/регионов/городов/валют/языков; ACL над talent...handbook; публичный lookup + internal resolve + топики pin.handbook.* | 06-services/handbook/ |
calendar | Запись на показ/консультацию/встречу и слоты доступности (эмерджентный; ADR-0064) | Расписание агента/консультанта ПИН, слоты самозаписи с витрины, жизненный цикл записи (подтверждение/отмена/перенос/исход); лиды/сделки остаются в crm | 06-services/calendar/ |
wallet | Внутренние балансы вознаграждений (эмерджентный; ADR-0065) | Ledger-модель: раздельные балансы получателя (агент/партнёр/агентство/ПИН), журнал изменений | 06-services/wallet/ |
Сквозные сценарии: UC-1/UC-2(+2a)/UC-3(+3a) (497–583) + воронки из матриц — 02-architecture/scenarios/.
Ролевая модель (сводная)
8 ролей: Инвестор, Агент/Брокер, Агентство (руководитель), Девелопер (менеджер застройщика),
Менеджер ПИН, Служба заботы, Администратор, Гость + внутренние роли компаний (агентство:
руководитель/старший менеджер/…; девелопер: администратор проекта/менеджер продаж/маркетолог; забота:
наблюдатель/оператор/супервизор). Реализация — Scoped-RBAC + record-level (см. 06-services/identity/).
«СуперАгент» из матриц — не роль (дубль Агента).
Принятые решения по открытым вопросам исходного ТЗ
| # | Открытый вопрос (источник) | Решение | Где зафиксировано |
|---|---|---|---|
| 1 | Каталог permissions «реши сам» (ТЗ.md:55,73) | Полный каталог permissions по фичам/ролям проектируется в identity | identity/domain/permission.md |
| 2 | Куда вынести администраторов (ТЗ.md:68) | Отдельная admin-система за пределами основной Identity; в ТЗ — граница и интеграционные точки | ADR-0053 |
| 3 | Сессии vs история просмотров vs трекинг — сервис или модуль (ТЗ.md:267) | Один контекст user-activity с модулями sessions/views/actions | ADR-0054 |
| 4 | Слияние избранного при авторизации (ТЗ.md:247) | 3 стратегии (device-wins / account-wins / merge) + рекомендация merge | favorites/README.md |
| 5 | Оркестратор чата и сделок — модуль или микросервис (ТЗ.md:301) | Модуль CRM + события; messenger потребляет | ADR-0055 |
| 6 | Транспорт чатов | Собственный мини-мессенджер (PostgreSQL + SignalR realtime из SDK); чаты сделок — по событиям CRM | ADR-0055 |
| 7 | Две воронки брони: инвестор- vs агент-инициатор (матрицы) | Единый flow с двумя точками входа; сделку создаёт агент (или менеджер ПИН); таймеры — параметры программы бронирования | 02-architecture/scenarios/, crm/README.md |
| 8 | Tenancy-модель PIN | TenantId = CompanyId; инвестор — вне tenant (nullable) | ADR-0052 |
| 9 | Эквайринг/платежи (ТЗ.md:455) | Структуры сделки/оплат проектируются; интеграция платежей — отложена | crm/ («реализация отложена») |
| 10 | Ранжирование новостей (ТЗ.md:219) и монетизация продвижения (ТЗ.md:195) | Спроектировать модели; реализация отложена | news/, catalog/ |
| 11 | Нагрузка/сложность (указание владельца) | Simplicity-first: до 1 млн пользователей (≤20k агентов/менеджеров), 1–10k одновременно активных → PostgreSQL-only для sessions/favorites/selections (без Redis); закрытие сессий/просмотров — LastActivityAt + polling-delta 10–15 мин → Kafka session-ended/lot-view-ended + агрегаты по лоту | ADR-0056 |
| 12 | Статистика для застройщиков (указание владельца) | Контекст dev-stats на ClickHouse: facts просмотров (PARTITION BY месяц; ORDER BY = иерархия фильтров Developer→Project→Building→LayoutGroup→Layout→Lot→ViewedAt; TTL 3 года) + дневные rollup-ы; API метрик/графиков с фильтрами дата+сам застройщик(+проект, опц. уровни ниже) | ADR-0057 |
| 13 | Справочники (страны/регионы/города/валюты/языки) — дублировать в каждом сервисе или выделить | Отдельный контекст handbook как ACL-реплика внешнего talent...handbook: публичный lookup + internal resolve для write-path + топики pin.handbook.* для локальных реплик потребителей | ADR-0063 |
| 14 | Запись на показ/консультацию и слоты доступности | Отдельный контекст calendar: расписание агента/консультанта ПИН, слоты самозаписи с витрины, жизненный цикл записи (подтверждение/отмена/перенос/исход); лиды/сделки остаются в crm (узнаёт по событиям) | ADR-0064 |
| 15 | Где учитывать причитающиеся вознаграждения | Контекст wallet (первый ledger платформы): внутренние балансы + журнал; раздельные балансы одного получателя (агентские комиссии / реферальная программа / удержание агентства / доход и транзит ПИН) | ADR-0065 |
| 16 | Удержание ПИН и реферальные ставки (финансовый контур rewards) | Удержание платформы и реферальные ставки — конфигурируемые параметры финансового контура rewards | ADR-0066 |
| 17 | Когда начисляется вознаграждение | Гейт получения денег: начисление в wallet по акту поступления средств, а не по факту достижения этапа сделки | ADR-0067 |
| 18 | Ставки комиссий/рефералов — глобальные или контекстные | Scoped + time-bounded конфигурация ставок: по scope (платформа/агентство/проект) и периоду действия | ADR-0068 |
| 19 | Несколько агентов в одной сделке | Co-broking: расщепление комиссии между несколькими агентами (дизайн, v-next) | ADR-0069 |
| 20 | Агент состоит более чем в одном агентстве | Мульти-агентство: членства агента + контекст активного агентства | ADR-0070 |
| 21 | Кому принадлежат процессы CRM и как моделируются участники | Владение процессами CRM компанией + единая record-level модель участников | ADR-0071 |
| 22 | Что происходит при увольнении/исключении агента | Каскад доступа: отзыв прав, переназначение владения, судьба фиксаций/броней/сделок | ADR-0072 |
Расхождения источников (сводная таблица)
| Тема | ТЗ.md | Матрицы (ТехЗадание/) | Прототип | Принято |
|---|---|---|---|---|
| Роли | per-company ACL/RBAC, инвестор, админ «сбоку» | «8 ролей», Служба заботы, Менеджер ПИН, Агентство | роли сделки SellManager/Investor/Agent | 8 ролей + внутренние роли компаний; роли сделки — из Workflows |
| Таймер брони | Резерв 1 час; бронь по программе (4 ч / 10 дней) | 72 часа | — | Таймеры = параметры программы бронирования застройщика |
| Инициатор брони | Инвестор отправляет заявку; сделку создаёт агент | UC: инвестор бронирует сам (9 этапов) | кнопка «Забронировать» (форма ФИО+телефон) | Обе точки входа; создание сделки — агент/менеджер ПИН |
| US-нумерация | US-INV без 21; US-DEV 01–05 | +US-INV-21, +US-DEV-06..08, +US-MGR-01..06 | — | Полный набор из матриц |
| Аналитика доходности | «история изменения цен» (ClickHouse) | калькуляторы/ROI/PDF | полная эконом-модель + серии, юр/физ + УСН/ОСНО | Обе части в invest-analytics; расчёт серверный |
| Программы покупки | способ оплаты влияет на этапы | ипотека/рассрочка в фичах | 100%/5 рассрочек/ипотека, график платежей на клиенте | Серверный расчёт в crm (booking) |
| Мессенджер | собственный сервис, TPH-события | чаты/ВКС/шаблоны | — | Собственный мини-мессенджер (SignalR); чаты сделок по событиям CRM |
| Избранное | user+session, заметки, слияние | заметки/экспорт PDF | только localStorage | Бэкенд-сервис + миграция + слияние |
Нефункциональные рамки (ADR-0056)
До 1 000 000 пользователей всего (≤20 000 агентов/менеджеров/менеджеров застройщиков; остальные — инвесторы); одновременно активных 1 000–10 000. Не усложнять: без микрооптимизаций и сложных паттернов «на вырост»; PostgreSQL — основная СУБД (Redis не используется в sessions/favorites/selections; ClickHouse — история цен в invest-analytics и view-статистика застройщиков в dev-stats, ADR-0057). Обязательный трекинг: длительность сессий, длительность и число просмотров каждого лота (механизм — ADR-0056 п.3); глубина статистики для застройщиков — 3 года.
Требования к оформлению детальных ТЗ
Каждый метод (endpoint/consumer/producer) — по CQRS с полными входами/выходами (поле, тип, описание,
ограничения, валидация) и алгоритмом 8 шагов (01-engineering-rules/algorithm-documentation-rules.md);
каждая сущность — по колонкам (типы, PK/FK/constraints; jsonb/VO/EF owned types строго типизированы);
события — IKafkaEvent + outbox; диаграммы mermaid обязательны; принцип «один дом + ссылка».
Шаблоны — docs/99-templates/; реальный SDK — docs/11-backend-sdk/.
Traceability
Полнота покрытия проверяется на каждом батче: каждый раздел/абзац ТехЗадание.md (строки 27–660) и каждая
строка рабочих листов матриц (Лист1, US Сделка, ролевые листы) должны иметь соответствие в детальных ТЗ.
Навигация «возможность → контекст → ТЗ» ведётся в prototype-mapping.md.
Обратные ссылки
Автоссылки: где используется этот документ.
- Домен (CQRS) (2): Entity / Aggregate: BookingProgramEntity, Entity / Aggregate: PostReaction + проекция PostRankingSignals (Design)
- Use Cases (3): UC-FAV-002. Авторизация → слияние гостевого и аккаунтного избранного (3 стратегии), UC-PRF-004. Создание шаблона реквизитов и его использование в бронировании (CRM), US-реестр блока «Сделка» (US-INV / US-AGT / US-DEV / US-MGR)
- scenarios (1): Кросс-сервисные сценарии PIN (OVR)
- index.md (13): Документация PIN, Calendar Service, Chessboard Service (Pin.Chessboard), CRM Service, DevStats Service (Pin.DevStats), Messenger Service, News Service (Pin.News), Notifications Service, Profile Service (Pin.Profile), Referral Service, Rewards Service, Support Service (+1)
- glossary.md (1): Глоссарий PIN
- registries (1): Реестры PIN (registries)
- service-boundaries.md (1): Границы сервисов PIN