Модель данных

Зачем нужно

Документ описывает канонические сущности CRM: account, contacts, leads, deals, products, price plans, billing, balance, entitlement, support, payroll и audit.

Правила модели

• Каждая сущность имеет id, created_at, updated_at, если явно не указано иначе.
• Ссылки на соседние домены хранятся как external refs, а не FK.
• Финансовая история append-only: исправление через adjustment/refund, не через удаление.
• PII хранится минимально и маскируется в логах.
• Все финансовые и чувствительные ручные действия пишутся в audit.
• Покупатель, плательщик, получатель продукта и учебный субъект разделены. CRM не должна считать, что purchaser = payer = beneficiary = enrollment subject.

Коммерческие роли в покупке

Понятие	Назначение	Возможная ссылка
purchaser	пользователь, инициировавший покупку	user_id
payer	платёжный субъект или контакт оплаты	billing account / crm_person_link
beneficiary	получатель продукта	student_profile_id, user_id, family_group_id
enrollment subject	учебный субъект для LMS/competitions	student_profile_id или другой учебный subject

Покупатель и получатель могут совпадать, но не обязаны совпадать: взрослый может купить продукт ребёнку, ребёнок с linked user может купить продукт себе, а будущий семейный продукт может назначаться на family_group.

Клиентская карточка

crm_account

Клиентская единица.

Поле	Назначение
type	family, person, organization, lead
display_name	рабочее имя карточки
status	new, active, paused, archived, blocked
owner_user_id	ответственный менеджер
risk_flags	долг, спор, VIP, duplicate

crm_person_link

Связь account с человеком.

Роли: payer, student, parent, teacher, contact, guardian.

crm_contact

Контакт: email, phone, messenger, address. Контакт может быть связан с account или person link.

Products and pricing

CRM владеет коммерческой упаковкой обучения и событий. Продукт не равен LMS course, LMS roadmap topic, competition season или storefront catalog item.

product_type

Справочник типов коммерческой упаковки.

Примеры: course, mini_group, intensive, circle, individual, competition, training_set, consultation.

product

Коммерческая единица, которую можно продавать, включать в заказ и показывать на витрине через read-model.

Поле	Назначение
type_id	тип продукта
slug	стабильный ключ для CRM/storefront
title	коммерческое название
status	draft, active, paused, archived
target_domain	домен исполнения: lms, competitions, task-bank, manual
target_ref	ссылка на course, season, service или другой объект исполнения
roadmap_refs	LMS refs на roadmap program/module/topic/pathway, которые продукт помогает пройти
default_entitlement_policy	правило выдачи доступа

roadmap_refs не делают CRM владельцем учебной программы. CRM описывает коммерческий способ прохождения фрагмента roadmap, а LMS остаётся владельцем topic progress, completion, scheduled educational facts и evidence.

product_run

Конкретный запуск продукта: поток, сезон, набор, дата старта или окно набора.

Поле	Назначение
product_id	продукт
title	название запуска
starts_at, ends_at	период
capacity	ограничение мест
lms_delivery_refs	ссылки на LMS group/session/course version/track, если запуск календарный
status	planned, open, closed, running, finished, cancelled

product_run может указывать на LMS group, session, course version или track, но не хранит attendance, progress или completion.

price_plan

Правило цены для продукта или запуска.

Поле	Назначение
product_id, product_run_id	область применения
title	название тарифа
amount, currency	цена
billing_mode	one_time, subscription, installment, manual
status	draft, active, retired
valid_from, valid_to	период действия

Продажи

crm_lead

Потенциальный клиент.

Поле	Назначение
source	storefront, call, referral, manual, import
status	lead lifecycle
campaign_ref	кампания или UTM
payload	минимальный безопасный контекст

crm_deal

Продажная возможность.

crm_order

Оформленный заказ на продукт, услугу, олимпиаду или пакет. Order связывает deal, account, purchaser/payer, beneficiary и invoice.

Поле	Назначение
account_id	CRM account
deal_id	optional сделка
purchaser_user_id	identity user, инициировавший покупку, если известен
payer_person_link_id	CRM person link плательщика или контакт оплаты
beneficiary_type, beneficiary_ref	получатель продукта: student_profile, user, family_group, organization, manual
enrollment_subject_type, enrollment_subject_ref	учебный subject, если отличается от beneficiary
status	draft, confirmed, cancelled, fulfilled
amount_total, currency	price snapshot заказа

crm_order_item

Позиция заказа: product_id, optional product_run_id, price_plan_id, quantity, price snapshot, discount.

Биллинг

crm_invoice

Счёт к оплате.

Поле	Назначение
account_id	клиент
order_id	заказ
status	draft, issued, partially_paid, paid, overdue, cancelled, void
amount_total	сумма
amount_paid	оплачено
currency	валюта
due_at	срок оплаты

crm_payment

Факт платежа.

Правила:

• provider payment id уникален внутри provider;
• webhook idempotency key обязателен;
• successful payment создаёт balance entry;
• payment не редактируется после success, кроме ссылок на refund/metadata.

crm_refund

Возврат.

Возврат имеет причину, ссылку на payment, сумму, status и audit. Возврат может быть частичным.

crm_adjustment

Ручная финансовая корректировка: скидка, списание долга, перенос баланса, исправление ошибки.

crm_balance_entry

Append-only строка баланса.

Типы: invoice_debit, payment_credit, refund_debit, adjustment_credit, adjustment_debit, writeoff.

Entitlement

crm_entitlement

Операционное право доступа.

Поле	Назначение
account_id	клиент
purchaser_user_id	кто инициировал покупку, если известен
beneficiary_type, beneficiary_ref	получатель продукта: student_profile, user, family_group, organization, manual
enrollment_subject_type, enrollment_subject_ref	учебный subject для домена исполнения, если применимо
product_ref	продукт или offer
target_domain	lms, competitions, task-bank
target_ref	курс, сезон, набор или service access
status	pending, active, suspended, expired, revoked
source_type, source_id	invoice/payment/manual/order
starts_at, ends_at	период действия

Entitlement не является LMS enrollment. CRM принимает решение о доступе и публикует событие или command для домена-владельца.

crm_entitlement_consumption_log

Append-only журнал фактического потребления доступа, инициированного LMS, competitions или task-bank.

Поле	Назначение
entitlement_id	право доступа CRM
consumer_domain	домен, который сообщил потребление
consumer_ref	session, attendance, attempt, tour participation или другой объект
quantity	сколько списано
status	recorded, reverted
occurred_at	когда произошло потребление

Support и коммуникации

crm_interaction

Коммуникация: call, email, message, meeting, note.

crm_ticket

Обращение support/operations.

crm_note

Внутренняя заметка. Может иметь visibility: internal, support, finance, restricted.

Payroll

crm_teacher_rate

Ставка преподавателя с периодом действия и правилом расчёта.

crm_payable_activity

Факт, который может стать начислением: занятие, проверка, замена, консультация.

crm_payroll_period

Расчётный период.

crm_payroll_item

Строка начисления: activity, rate, amount, source snapshot.

crm_teacher_payout

Итоговая выплата преподавателю: status, approval, amount, adjustments.

Интеграции и audit

crm_sync_log

Журнал интеграционной обработки: source, event id, status, retry, error.

crm_audit_log

Аудит действий: actor, action, entity, before/after, request id.