US-реестр блока «Сделка» (US-INV / US-AGT / US-DEV / US-MGR)
Назначение
Полный реестр user stories блока «Сделка» контекста crm — канонический дом US-идентификаторов платформы
PIN. Полный набор (включая US-INV-21 «Оплата», US-DEV-06..08 и US-MGR-01..06) — принятое решение по
расхождению нумерации (technical-assignment.md, таблица
расхождений). Каждая story даёт формулировку и ссылки на покрывающие документы: домены (существуют),
API-методы и события (будущие пути по конвенции ../api/<method>.md, ../events/<event>.md) и use cases этого
каталога.
Metadata
| Поле | Значение |
|---|---|
| ID-диапазоны | US-INV-01..23, US-AGT-01..08, US-DEV-01..08, US-MGR-01..06 |
| Контекст | crm (чат-stories — граница с messenger, ADR-0055) |
| Статус | draft |
| Правило покрытия | Каждая story обязана иметь ≥ 1 покрывающий домен-документ и ≥ 1 операционный документ (api/consumer/job/UC); отсутствие покрытия = дыра traceability |
Карта покрытия (обзор)
Роль: Инвестор (US-INV-01..23)
Инвестор видит лиды/сделки, в которых участвует, и ничего не знает о фиксациях (record-level — ../domain/deal.md, раздел «Безопасность»).
| № | User Story (формулировка источника) | Покрытие: домен | Покрытие: API / UC / события |
|---|---|---|---|
| US-INV-01 | Как Инвестор, я хочу видеть все свои сделки в одном списке, чтобы быстро находить нужную и отслеживать статусы (объект, статус, дата создания, сумма; фильтр по статусу: активные/завершённые/отменённые). | ../domain/deal.md — Status, Price, CreatedAt, индекс ix_deals_primary_investor_user_id | ../api/investor-list-deals.md; экран /profile/deals |
| US-INV-02 | Как Инвестор, я хочу открывать карточку сделки, чтобы видеть всю информацию по бронированию (объект недвижимости, финансовая сводка, таймлайн, вкладки Документы/Чат/Условия/О объекте недвижимости/О проекте). | ../domain/deal.md; ../domain/booking.md; ../domain/deal-timeline-event.md | ../api/investor-get-deal.md; display-данные объекта недвижимости/проекта — API catalog/chessboard |
| US-INV-03 | Как Инвестор, я хочу видеть текущий статус сделки (заявка, бронь, продажа, отказ), чтобы понимать, на каком этапе находится процесс. | ../domain/deal.md — enum DealStatus (5-е значение Completed = «продажа (завершена)», расхождение зафиксировано в README, решение 4) | ../api/investor-get-deal.md; авто-обновление — pin.crm.deal-stage-changed.v1 (../events/deal-stage-changed.md) |
| US-INV-04 | Как Инвестор, я хочу видеть дату и время последнего обновления сделки, чтобы понимать, когда были изменения. | ../domain/deal.md — UpdatedAt, индекс ix_deals_updated_at | ../api/investor-get-deal.md, ../api/investor-list-deals.md |
| US-INV-05 | Как Инвестор, я хочу видеть полную стоимость объекта недвижимости (цена за м² × площадь), чтобы знать итоговую цену объекта. | ../domain/deal.md — VO Money (Price, snapshot из chessboard на момент создания/смены объекта недвижимости) | ../api/investor-get-deal.md; источник цифр м²/площади — README контекста |
| US-INV-06 | Как Инвестор, я хочу видеть сумму платного бронирования и статус оплаты («Не оплачено» + кнопка «Оплатить» / «Оплачено» + дата), чтобы понимать, сколько внесено или требуется внести. | ../domain/booking.md — PaymentAmount, PaymentStatus, PaidAt | UC-BKG-004; ../api/investor-get-deal.md |
| US-INV-07 | Как Инвестор, я хочу видеть банк проведения сделки, чтобы знать, где открыт эскроу-счёт («Не указан», если банк не определён). | ../domain/deal.md — BankId (nullable, справочник банков chessboard) | ../api/investor-get-deal.md |
| US-INV-08 | Как Инвестор, я хочу видеть тип сделки (ДДУ, купля-продажа), чтобы понимать юридическую форму. | ../domain/deal.md — enum DealContractType (Ddu/Dkp) | ../api/investor-get-deal.md |
| US-INV-09 | Как Инвестор, я хочу видеть хронологию всех этапов сделки (таймлайн) с датами, сортировкой от старых к новым и иконкой статуса (выполнено/в процессе/просрочено). | ../domain/deal-timeline-event.md — enum TimelineItemStatus, OccurredAt, worker timeline-overdue | ../api/investor-get-deal-timeline.md; ../background/timeline-overdue-job.md |
| US-INV-10 | Как Инвестор, я хочу раскрывать условия бронирования при клике на событие «Создана заявка на бронирование», чтобы знать сроки (срок блокировки, порядок возврата). | ../domain/deal-timeline-event.md — payload TimelineBookingRequestedPayload; ../domain/booking.md — VO BookingProgramTerms (snapshot) | ../api/investor-get-deal-timeline.md; UC-BKG-001 |
| US-INV-11 | Как Инвестор, я хочу видеть уведомления о новых событиях в таймлайне (выделение + push/email), чтобы не пропустить важные этапы. | ../domain/deal-timeline-event.md — событие TimelineItemAdded | Консюмер crm-событий в ../../notifications/consumers/crm-events.md |
| US-INV-12 | Как Инвестор, я хочу загружать паспортные данные (скан паспорта, JPG/PDF) в сделку, чтобы выполнить требования девелопера; после загрузки — статус «Загружено»/«На проверке». | ../domain/deal-document.md — тип ClientPassport, статусы, INV-DOC-1/3 | ../api/investor-upload-deal-document.md |
| US-INV-13 | Как Инвестор, я хочу скачивать договоры и другие документы из сделки (список файлов с названиями и датами, кнопка «Скачать»). | ../domain/deal-document.md — FileId, FileName, UploadedAt; пресайн-ссылки storage | ../api/investor-download-deal-document.md |
| US-INV-14 | Как Инвестор, я хочу видеть статус каждого документа (загружено, на проверке, принято, отклонено) и причину отклонения; при смене статуса приходит уведомление. | ../domain/deal-document.md — enum DealDocumentStatus, RejectReason, INV-DOC-6 | pin.crm.document-status-changed.v1 (../events/document-status-changed.md) → notifications |
| US-INV-15 | Как Инвестор, я хочу общаться в чате сделки с агентом, девелопером и менеджером ПИН (участники добавлены автоматически; текст и файлы). | ../domain/deal.md — DealMemberEntity (авто-состав INV-DEAL-2), проекция ChatStatus | Чат — контекст messenger (ADR-0055), README контекста; синк участников — pin.crm.deal-created.v1, pin.crm.deal-members-changed.v1 |
| US-INV-16 | Как Инвестор, я хочу получать системные уведомления-карточки в чате («Загрузите скан паспорта» и т.п.) со ссылками на нужные действия. | ../domain/deal-document.md — RequestComment, DocumentRequestedEvent | pin.crm.document-requested.v1 (../events/document-requested.md), booking-события → консюмер messenger |
| US-INV-17 | Как Инвестор, я хочу прикреплять файлы в чате, чтобы отправлять сканы документов на проверку. | Вне crm: функциональность чата | README контекста; проверка документов — через ../domain/deal-document.md |
| US-INV-18 | Как Инвестор, я хочу ознакомиться с условиями сделки (платное бронирование, ДДУ, ипотека, рассрочка) и отметить «Ознакомлен». | ../domain/deal.md — TermsAcknowledgedAt; ../domain/purchase-program.md — условия способов оплаты; ../domain/booking-program.md | ../api/investor-acknowledge-terms.md; таймлайн-тип TermsAcknowledged |
| US-INV-19 | Как Инвестор, я хочу указать номер эскроу-счёта в карточке сделки; после ввода статус «Эскроу забронирован». | ../domain/deal.md — EscrowAccountNumber (Sensitive, маска ****NNNN), enum EscrowStatus | ../api/investor-provide-escrow.md; таймлайн-тип EscrowProvided (только маска) |
| US-INV-20 | Как Инвестор, я хочу видеть статус готовности договоров со стороны девелопера («Договоры подготовлены» / «Ожидание подготовки») с уведомлением и ссылкой на скачивание. | ../domain/deal.md — ContractsPreparedAt (INV-DEAL-7); ../domain/deal-document.md — тип SaleContract | ../api/developer-mark-contracts-prepared.md; таймлайн-тип ContractsPrepared; уведомление — notifications |
| US-INV-21 | Как Инвестор, я хочу оплатить платное бронирование прямо из карточки сделки, чтобы выполнить финансовое обязательство. | ../domain/booking.md — PaymentStatus, PaymentAmount, INV-BKG-4; ../domain/deal-document.md — тип BookingPaymentProof | UC-BKG-004; ../api/investor-attach-booking-payment-proof.md. Расхождение: критерий «платёжный шлюз (карта/СБП)» отложен решением 9 ТЗ (эквайринг не реализуется) — оплата вне платформы, чек прикрепляется, менеджер подтверждает |
| US-INV-22 | Как Инвестор, я хочу переключаться между вкладками карточки сделки («Ход сделки», «Документы», «Чат», «О объекте недвижимости», «О проекте») без перезагрузки. | UI-story (карточка сделки с вкладками); данные вкладок — ../domain/deal-timeline-event.md, ../domain/deal-document.md | ../api/investor-get-deal.md, ../api/investor-get-deal-timeline.md; «О объекте недвижимости»/«О проекте» — API catalog |
| US-INV-23 | Как Инвестор, я хочу перейти к полной карточке объекта недвижимости из сделки (кнопка «Перейти к объекту недвижимости»), чтобы посмотреть планировку и характеристики. | ../domain/deal.md — PropertyObjectId (логическая ссылка на chessboard) | Карточка объекта недвижимости — UC-CTL-008 |
Роль: Агент (US-AGT-01..08)
Record-level: агент видит сделки, где он активный участник (обычно Executor: ExecutorAgentUserId = actor);
руководитель/админ агентства — все сделки своего агентства (по членству активного Executor) с переключателем
«свои/все» (../domain/deal.md, Безопасность).
| № | User Story (формулировка источника) | Покрытие: домен | Покрытие: API / UC / события |
|---|---|---|---|
| US-AGT-01 | Как Агент, я хочу видеть все сделки своих клиентов в одном списке (только где агент ответственный; фильтры по клиенту, объекту, статусу; даты создания и обновления), чтобы контролировать статус бронирований. | ../domain/deal.md — ExecutorAgentUserId (текущий исполнитель), индекс ix_deals_executor_agent_user_id; воронка агентства — (origin_agency_company_id,origin_agent_user_id,status); поиск — DealSearchDocument (Elasticsearch) | ../api/agent-list-deals.md; канбан /crm |
| US-AGT-02 | Как Агент, я хочу открывать карточку сделки любого своего клиента (финансы, таймлайн, документы, чат), чтобы помогать на всех этапах. | ../domain/deal.md; ../domain/deal-timeline-event.md; ../domain/deal-document.md | ../api/agent-get-deal.md |
| US-AGT-03 | Как Агент, я хочу видеть финансовую сводку по сделке (стоимость, предоплата, банк) с предупреждением, если предоплата не внесена, чтобы консультировать клиента. | ../domain/deal.md — Price, BankId; ../domain/booking.md — PaymentStatus = Pending (предупреждение) | ../api/agent-get-deal.md |
| US-AGT-04 | Как Агент, я хочу видеть текущий статус сделки и напоминать клиенту о действиях (задержка документов/оплаты видна агенту). | ../domain/deal.md — Status; ../domain/deal-timeline-event.md — Overdue (worker timeline-overdue) | ../api/agent-get-deal.md; ../background/timeline-overdue-job.md |
| US-AGT-05 | Как Агент, я хочу видеть таймлайн сделки (этапы с датами; завершённые и требующие действий), чтобы отслеживать прогресс клиента. | ../domain/deal-timeline-event.md — TimelineItemStatus | ../api/agent-get-deal-timeline.md |
| US-AGT-06 | Как Агент, я хочу видеть статус загрузки документов клиентом с индикатором «Требуется загрузка», чтобы напоминать, если что-то не загружено. | ../domain/deal-document.md — статус Requested | ../api/agent-get-deal.md (вкладка «Документы») |
| US-AGT-07 | Как Агент, я хочу открывать чат сделки (клиент, агент, девелопер, менеджер ПИН добавлены автоматически), чтобы оперативно отвечать на вопросы. | ../domain/deal.md — DealMemberEntity, INV-DEAL-2/3 | messenger (ADR-0055); pin.crm.deal-members-changed.v1 (../events/deal-members-changed.md) |
| US-AGT-08 | Как Агент, я хочу получать уведомления о важных событиях в сделке (статус, оплата, документы) с указанием сделки и сути события. | События агрегатов: ../domain/deal.md, ../domain/booking.md, ../domain/deal-document.md | Консюмер pin.crm.* в ../../notifications/consumers/crm-events.md |
Роль: Девелопер (US-DEV-01..08)
Tenant isolation: менеджер застройщика видит только сделки своего TenantId = DeveloperCompanyId
(ADR-0052). US-DEV-06..08 присутствуют по полному набору US (расхождение нумерации — принят полный набор).
| № | User Story (формулировка источника) | Покрытие: домен | Покрытие: API / UC / события |
|---|---|---|---|
| US-DEV-01 | Как Девелопер, я хочу видеть все сделки по своим проектам в одном списке (фильтрация по проекту и статусу), чтобы контролировать заявки и бронирования. | ../domain/deal.md — TenantId, ProjectId, индекс (tenant_id,status,created_at) | ../api/developer-list-deals.md |
| US-DEV-02 | Как Девелопер, я хочу открывать карточку любой сделки своего тенанта (объект недвижимости, клиент, финансы, документы), чтобы отслеживать статус клиента. | ../domain/deal.md; ../domain/deal-document.md | ../api/developer-get-deal.md |
| US-DEV-03 | Как Девелопер, я хочу загружать подготовленные договоры в сделку, чтобы клиент мог их скачать (клиент получает уведомление о готовности). | ../domain/deal-document.md — типы BookingContract, SaleContract (загружает менеджер застройщика) | ../api/developer-upload-booking-contract.md, ../api/developer-upload-sale-contract.md; pin.crm.document-status-changed.v1 |
| US-DEV-04 | Как Девелопер, я хочу отмечать этап «Договоры подготовлены», когда договоры готовы (статус обновляется, клиент получает уведомление). | ../domain/deal.md — ContractsPreparedAt, порядок INV-DEAL-7 | ../api/developer-mark-contracts-prepared.md; таймлайн ContractsPrepared; notifications |
| US-DEV-05 | Как Девелопер, я хочу видеть статус загрузки документов клиентом (все документы и статусы; индикатор, если не загружено), чтобы знать, когда всё собрано. | ../domain/deal-document.md — статусы, индекс (deal_id,type) | ../api/developer-get-deal.md; подтверждение получения — ../api/developer-confirm-booking-documents.md, ../api/developer-confirm-contract-documents.md |
| US-DEV-06 | Как Девелопер, я хочу видеть статус эскроу-счёта клиента («Эскроу открыт/не открыт»; обновление через интеграцию с банком или вручную), чтобы понимать, открыт ли он. | ../domain/deal.md — EscrowStatus (None/Provided), EscrowAccountNumber (полный номер виден SellManager) | ../api/developer-get-deal.md. Расхождение: банковская интеграция не реализуется (решение 9 ТЗ) — статус проставляется вводом инвестора (US-INV-19) или вручную |
| US-DEV-07 | Как Девелопер, я хочу подписывать договоры со своей стороны и загружать подписанные версии (статус «Документы подписаны застройщиком»). | ../domain/deal-document.md — новая запись типа SaleContract (подписанная версия; история — append-only, INV-DOC-4) | ../api/developer-upload-sale-contract.md; pin.crm.document-status-changed.v1 |
| US-DEV-08 | Как Девелопер, я хочу открывать чат сделки (девелопер добавлен автоматически при создании сделки), чтобы отвечать на вопросы клиента и агента. | ../domain/deal.md — роль SellManager (авто-состав при создании из фиксации, INV-DEAL-2) | messenger (ADR-0055); pin.crm.deal-created.v1 (../events/deal-created.md) |
Роль: Менеджер ПИН (US-MGR-01..06)
Platform-scope permission (кросс-tenant видимость, ADR-0052); авто-участник сделок с ролью PinManager
(../domain/deal.md, enum ParticipantRole).
| № | User Story (формулировка источника) | Покрытие: домен | Покрытие: API / UC / события |
|---|---|---|---|
| US-MGR-01 | Как Менеджер ПИН, я хочу видеть все сделки платформы без ограничений (фильтрация по агенту, девелоперу, статусу, объекту), чтобы контролировать процесс и помогать. | ../domain/deal.md — Безопасность: сквозной platform-scope | ../api/pin-manager-list-deals.md |
| US-MGR-02 | Как Менеджер ПИН, я хочу открывать карточку любой сделки со всеми данными и возможностью вмешательства, чтобы помогать в сложных ситуациях. | ../domain/deal.md | ../api/pin-manager-get-deal.md; UC-CRM-006 |
| US-MGR-03 | Как Менеджер ПИН, я хочу изменять статус сделки вручную (при конфликтах или ошибках): доступны все статусы (заявка, бронь, продажа, отказ), при изменении добавляется комментарий и уведомляются участники. | ../domain/deal.md — DealStatus, guard-ы INV-DEAL-6..9 | UC-CRM-006; ../api/pin-manager-override-deal-status.md; pin.crm.deal-stage-changed.v1 |
| US-MGR-04 | Как Менеджер ПИН, я хочу видеть все документы по сделке (скачать и проверить), чтобы помогать клиенту и девелоперу с оформлением. | ../domain/deal-document.md — доступ PinManager к PII-типам | ../api/pin-manager-get-deal.md (вкладка «Документы») |
| US-MGR-05 | Как Менеджер ПИН, я хочу вручную подтверждать этапы (например, «Документы приняты»), если автоматическая проверка недоступна; при подтверждении добавляется событие в таймлайн. | ../domain/deal-timeline-event.md — тип ManualNote, INV-TLE-5; ../domain/deal.md — перевод на этап | UC-CRM-006; ../api/pin-manager-add-timeline-note.md |
| US-MGR-06 | Как Менеджер ПИН, я хочу участвовать в чате всех сделок (добавлен автоматически; сообщения и файлы), чтобы помогать решать спорные вопросы. | ../domain/deal.md — авто-PinManager (INV-DEAL-2/3) | messenger (ADR-0055); pin.crm.deal-members-changed.v1 |
Зафиксированные расхождения покрытия
| US | Расхождение | Принято |
|---|---|---|
| US-INV-03 | 4 статуса в US vs 5 в модели | Внутренний Completed = «продажа (завершена)» — README, решение 4 |
| US-INV-21 | Критерий «платёжный шлюз (карта/СБП)» | Эквайринг отложен (решение 9 ТЗ): оплата вне платформы, чек BookingPaymentProof + ручное подтверждение менеджером — UC-BKG-004 |
| US-DEV-06 | «обновление через интеграцию с банком» | Интеграция отложена; статус эскроу — ввод инвестора (US-INV-19) / вручную |
| US-INV-15/16/17, US-AGT-07, US-DEV-08, US-MGR-06 | Чат-функциональность | Владелец — messenger (ADR-0055); CRM поставляет события deal-created/deal-members-changed/document-requested/booking-* и проекцию ChatStatus |
Интеграционные ожидания US-блока «Сделка»
Часть US опирается на асинхронную доставку между crm и соседями (messenger, notifications,
chessboard, investor-owner, rewards); реализация обязана учитывать окно eventual-consistency и корректно
показывать промежуточное состояние. Строгая согласованность гарантируется только внутри одной операции
crm (агрегат + таймлайн + запись outbox — атомарно); между контекстами — eventual.
| US-кластер | Синхронно (в ответе операции) | Асинхронно (событие → консюмер) | Что видит пользователь до доставки |
|---|---|---|---|
| US-INV-15/16/17, US-AGT-07, US-DEV-08, US-MGR-06 (чат) | Сделка создана/обновлена; проекция ChatStatus = Pending/Provisioning | pin.crm.deal-created.v1 / pin.crm.deal-members-changed.v1 → messenger создаёт/синкает чат (ChatStatus → Ready, при сбое Failed + ретрай) | Карточка открыта, чат «создаётся»; сообщения доступны после Ready |
| US-INV-11, US-AGT-08, US-DEV-04, US-INV-20 (уведомления) | Событие таймлайна / этап записаны | TimelineItemAdded / pin.crm.document-status-changed.v1 / pin.crm.deal-stage-changed.v1 → notifications (push/email) | Событие уже в таймлайне; push/email — с задержкой (минуты) |
| US-INV-03/04 (статус/обновление) | Новый Status/UpdatedAt в карточке | pin.crm.deal-stage-changed.v1 → messenger (карточка в чат) | Статус актуален сразу; карточка в чате — асинхронно |
| Завершение (US-DEV-*, US-INV — инвестор-собственник) | Status = Completed в карточке | pin.crm.deal-completed.v1 → investor-owner (портфель) / rewards (комиссия) / chessboard (объект «Продан») | Сделка завершена; объект в портфеле, комиссия, «Продан» — с задержкой |
Ключи партиционирования, версии, гарантии доставки и идемпотентность консюмеров — в контрактах событий
(../events/); терминальные события (deal-completed/deal-cancelled) публикуются один раз на
DealId, консюмеры идемпотентны (first-seen по DealId).
Обратные ссылки
Автоссылки: где используется этот документ.
- Use Cases (17): UC-BKG-001. Инвестор инициирует бронирование с витрины, UC-BKG-002. Бронирование Резерв → Бронь, UC-BKG-003. Истечение резерва/брони и продление, UC-BKG-004. Оплата платного бронирования (чек + подтверждение), UC-CRM-001. Создание лида (заявка / реферал / вручную), UC-CRM-002. Агент создаёт сделку из лида (выбор объекта, гейт вовлечения застройщика), UC-CRM-003. Движение сделки по канбан-доске, UC-CRM-004. Документы сделки: запрос → загрузка → проверка → статусы, UC-CRM-005. Оформление сделки: договоры → эскроу → Росреестр → завершение, UC-CRM-006. Вмешательство Менеджера ПИН, UC-CRM-010. Назначение/снятие ответственного (куратора) процесса — ответственный ≠ исполнитель, UC-CRM-011. Лид с несколькими инвесторами: назначение основного инвестора (+5)
- registries (1): Реестр use cases и user stories PIN
Связанные документы
- Use cases контекста: UC-CRM-001 … UC-CRM-006, UC-BKG-001 … UC-BKG-004, UC-FIX-001 … UC-FIX-003.
- Домены: ../domain/ (10 документов); README контекста.
- Сквозные сценарии UC-1/2/3 — ../../architecture/scenarios/.