GET /api/v1/pin-manager/calendar/appointments — Записи к консультантам ПИН (read-only)
Назначение
Отдаёт менеджеру ПИН записи инвесторов к инвест-консультантам компании ПИН: поток самозаписи на
консультации, статусы ожидания/подтверждения и исходы встреч
(UC-OVR-002).
По этой выборке менеджер контролирует скорость реакции консультантов (Pending с дедлайном), долю неявок и
загрузку. Выборка строго read-only: решения по записи принимает консультант-участник через agent-область.
| Поле | Значение |
|---|
| Сервис/контекст | calendar |
| API area | pin-manager |
| Feature group | pin-calendar |
| Статус | draft |
| Документ | docs/06-services/calendar/api/pin-manager/list-appointments.md |
Актор и доступ
| Проверка | Значение |
|---|
| Actor type | User (менеджер / руководитель ПИН — сотрудник компании ПИН) |
| Auth policy / Permissions | calendar.team.view (назначено в scope компании ПИН) |
| Scope (RBAC) | организация: компания ПИН |
| Record-level | не применяется — видны записи ко всем консультантам компании ПИН |
| Tenant isolation | TenantId из токена (tenant_id) = компания ПИН; записи к агентам агентств этой областью недоступны (ADR-0052) |
| Audit | read-sensitive: актор и фильтры фиксируются в trace; Comment в логи не пишется |
HTTP-контракт
| Поле | Значение |
|---|
| Method | GET |
| Route | /api/v1/pin-manager/calendar/appointments |
| Success status | 200 |
| Idempotency header | нет (безопасное чтение) |
| Correlation | сквозной trace через заголовок traceparent |
Входные данные / параметры запроса
Все фильтры комбинируются по «И».
| Поле | Источник | Тип | Обязательность | Валидация / Ограничения | Безопасность |
|---|
TenantId | токен (tenant_id) | Guid | Да | Required (= компания ПИН); не принимается из query | Tenant isolation |
From | query | DateTimeOffset | Да | UTC; окно по StartAt записи | — |
To | query | DateTimeOffset | Да | UTC; To > From; To − From ≤ 92 дня | — |
ConsultantUserId | query | Guid? | Нет | записи к конкретному консультанту (фильтр по агенту записи); пользователь вне компании ПИН → пустая выборка (fail-closed) | — |
Status | query | AppointmentStatus? | Нет | enum-строка Pending/Confirmed/Declined/Cancelled/Expired/Completed/NoShow | — |
Kind | query | EventKind? | Нет | enum-строка Showing/Consultation | — |
Page / PageSize | query | int | Нет | Page ≥ 1; PageSize 1..500, default 200 | — |
Модель ответа — страница TeamAppointmentModel
Модель и все её поля — по дому list-team-appointments.md:
AgentUserId/AgentDisplayName строки — консультант ПИН. Сортировка — StartAt по убыванию, затем Id.
Алгоритм
- Контекст и доступ. Актор — сотрудник компании ПИН с
calendar.team.view; нет права или актор не из
компании ПИН → FORBIDDEN. TenantId берётся из токена.
- Проверка входа.
From/To заданы, To > From, окно ≤ 92 дней; enum-значения допустимы; paging в
границах — иначе VALIDATION_FAILED.
- Что читаем. Страница записей
TenantId = компания ПИН, StartAt ∈ [From, To) с наложением
фильтров ConsultantUserId/Status/Kind по «И»; сортировка StartAt убыв., Id; display-имена
консультантов и инвесторов — из реплики identity одним заходом.
- Результат. Страница
TeamAppointmentModel → HTTP 200; пустая выборка — 200 с Items = [].
Данные — из source of truth calendar, актуальны на момент чтения.
Ошибки и failure modes
| Код | HTTP status | Условие | Сообщение | Retry |
|---|
VALIDATION_FAILED | 400 | From/To отсутствуют; To ≤ From; окно > 92 дней; enum вне значений; paging вне границ | «Некорректные параметры выборки» | no retry |
UNAUTHORIZED | 401 | нет/просрочен JWT | — | no retry |
FORBIDDEN | 403 | нет права calendar.team.view в scope компании ПИН / актор не сотрудник ПИН | — | no retry |
Совместимость и наблюдаемость
- Контракт модели — по дому list-team-appointments.md; правила
additive/breaking — там же.
- Logs: актор, фильтры,
TotalCount (без Comment и display-имён клиентов); metrics:
calendar_api_request_duration_seconds{route}; traces — сквозной traceparent.
Acceptance Criteria
- AC-1 (поток консультаций). Дано: записи инвесторов к двум консультантам ПИН в окне. Когда:
GET с
From/To. Тогда: 200, записи обоих консультантов с display-именами участников.
- AC-2 (контроль реакции). Дано:
Status = Pending. Тогда: только ожидающие решения записи с
PendingExpiresAt — менеджер видит, какие обращения рискуют истечь.
- AC-3 (неявки). Дано:
Status = NoShow. Тогда: только записи с зафиксированной неявкой.
- AC-4 (не сотрудник ПИН). Дано: руководитель агентства. Тогда:
403 FORBIDDEN (его команда —
agency-область).
- AC-5 (чужой tenant). Дано:
ConsultantUserId агента стороннего агентства. Тогда: 200,
Items = [].
Обратные ссылки
Автоссылки: где используется этот документ.
Связанные документы