Перейти к основному содержимому

GET /api/investors/me/referral-links — Список моих реферальных ссылок (getMyReferralLinks)

Назначение​

Постраничный список собственных реферальных ссылок текущего пользователя с числом регистраций по каждой (registrationsCount). Основная таблица страницы /profile/partner (управление каналами: создать/изменить/удалить, метрики). Общий конверт и paging-модели — README.md.

Metadata​

ПолеЗначение
Сервис/контекстreferral
API areapublic
Feature groupreferral-links
Статусapproved
Документdocs/06-services/referral/api/public/get-my-referral-links.md

Актор и доступ​

ПроверкаЗначение
Actor typeUser
Auth policy / Permissionsauthenticated; permission referral.links.view-self
Scope (RBAC)self
Record-levelфильтр OwnerUserId == UserId — чужие ссылки в выборку не попадают

HTTP-контракт​

ПолеЗначение
MethodGET
Route/api/investors/me/referral-links
Success status200
Correlationсквозной trace через заголовок traceparent

Входные данные / параметры запроса​

ПолеИсточникТипОбязательностьВалидация / ОграниченияБезопасность
UserIdidentity claims (sub)GuidДавалидный токен401 при отсутствии
OffsetqueryintДаmin 0, max 2147483647—
TakequeryintДаmin 1, max 1000ограничение размера выдачи

Модель ответа GetMyReferralLinksQueryResult​

ПолеТипОбязательностьИсточникMaskingОписание
pageReferralLinkListItemPagingResultДаprojection—Страница: meta (total/take/offset — README.md) + items.

Модель ReferralLinkListItem (дом item-модели)​

ПолеТипОбязательностьИсточникMaskingОписание
idstring (Guid)ДаReferralLinkEntity.Id—Идентификатор ссылки.
urlstringДаReferralLinkEntity.Url—Slug.
descriptionstring?НетReferralLinkEntity.Description—Описание.
channelstring (enum ReferralChannel)ДаReferralLinkEntity.Channel—Канал распространения (дом enum — referral-link.md).
visitsCountlongДаReferralLinkEntity.VisitsCount—Число переходов по ссылке.
createdAtstring (ISO 8601)ДаReferralLinkEntity.CreatedAt—Момент создания.
registrationsCountnumber (int)Даcomputed (производный — referral-link.md)—Число регистраций по ссылке.

Предусловия и постусловия​

  • Предусловия. Пользователь авторизован. registrationsCount производный (COUNT по журналу, referral-link.md) — свеж с точностью до лага привязки (< 1 мин, README.md).
  • Постусловия. Состояние не меняется (чтение); события не публикуются; VisitsCount не растёт.

Алгоритм​

Тривиальное фильтрованное чтение. Пользователь авторизован, требуется permission referral.links.view-self (иначе FORBIDDEN); paging-параметры проверяются на диапазон (иначе ValidationError). Возвращается страница собственных не удалённых ссылок владельца (OwnerUserId == UserId, DeletedAt пусто), упорядоченная по дате создания (свежие сверху), при равенстве CreatedAt — по Id (детерминированный tie-break: одна и та же ссылка не пропадает и не дублируется между соседними страницами при Offset/Take-пагинации). Для каждой ссылки подставляется число регистраций (registrationsCount), недостающее значение трактуется как 0. meta содержит полное число записей под фильтром, размер и смещение страницы. Смещение за пределы выборки (Offset >= meta.total) — не ошибка: items пуст, meta.total актуален. Soft-deleted ссылки в выборку не попадают (в отличие от статистики канала). Чтение не блокирует конкурентную привязку — для registrationsCount допустимо расхождение на единицы (eventually consistent).

Критерии приёмки​

  • Given владелец с несколькими не удалёнными ссылками, When запрос первой страницы, Then 200, items упорядочены по createdAt desc, у каждой ссылки заполнен registrationsCount, meta.total = число всех не удалённых ссылок владельца.
  • Given ссылка без регистраций, When запрос, Then её registrationsCount = 0.
  • Given Offset больше meta.total, When запрос, Then 200 с пустым items и корректным meta.total (не 404).
  • Given Take вне 1..1000 или Offset < 0, When запрос, Then ValidationError (400).
  • Given отсутствует/невалиден токен, When запрос, Then 401.
  • Given soft-deleted ссылка владельца, When запрос, Then она в выборку не входит.
  • Given у владельца несколько ссылок с одинаковым createdAt, When последовательный обход страниц (Offset += Take), Then каждая ссылка встречается ровно один раз (tie-break по Id): без пропусков и дублей на границах страниц.

Ошибки и failure modes​

КодHTTP statusУсловиеСообщениеRetry
— (auth)401Нет/невалиден токен«Требуется авторизация»re-login
ValidationError400Offset/Take вне диапазонаперечень полейисправить

Совместимость и наблюдаемость​

  • Контракт стабилен. Новые optional поля item-а — additive; удаление/переименование/смена типа полей — breaking (migration + rollout).
  • Logs: UserId, размер страницы (take/offset) — без PII; metrics: referral_my_links_requests_total, histogram referral_stats_query_duration_seconds (стоимость — COUNT регистраций на страницу); traces — сквозной trace через traceparent. Dashboard — referral-overview; алерт на p95 > 300 мс (SLO public API, README.md).

Обратные ссылки​

Автоссылки: где используется этот документ.

Связанные документы​