GET /api/v1/companies/my — Просмотр своей компании

Операция чтения карточки компании (workspace) текущего пользователя: название, тип, статус, описание, реквизиты, настройки workspace. Основа экрана «Моя компания» ЛК застройщика/агентства/брокера/партнёра.

Назначение

Пользователь компании (агент, руководитель агентства, менеджер застройщика, сотрудник ПИН) открывает карточку своей организации. Owning-контекст — identity (дом полей — domain/company.md). Feature group — companies.

Metadata

Поле	Значение
Сервис/контекст	identity
API area	public
Feature group	companies
Статус	draft
Документ	docs/06-services/identity/api/company-user/get-my-company.md

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

Проверка	Значение
Actor type	User (пользователь с CompanyId != null; инвестор компании не имеет — 404)
Auth policy / Permissions	identity.companies.view (domain/permission.md)
Scope (RBAC)	организация: permission должен покрываться Active RoleAssignment со scope Platform или Organization(CompanyId)
Record-level	не применяется — доступ только к собственной компании (CompanyId из claims, id в route не принимается)
Tenant isolation	TenantId = CompanyId из JWT claims (ADR-0052); интерсептор INullableTenantedEntity не применяется к companies (platform-level таблица), изоляция — выборкой строго по CompanyId актора
Audit	none (чтение не-sensitive данных своей организации)

Только своя компания

CompanyId берётся из claim tenant_id, а не из route/query — id чужой компании в запросе игнорируется, эндпоинт всегда возвращает карточку компании актора.

HTTP-контракт

Поле	Значение
Method	GET
Route	/api/v1/companies/my
Success status	200
Idempotency header	не применяется (безопасный read)
Correlation	сквозной trace через заголовок traceparent

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

Поле	Источник	Тип	Обязательность	Валидация / Ограничения	Безопасность
UserId	identity claims (sub)	Guid	Да	Required	—
CompanyId	identity claims (tenant_id)	Guid	Да	Required; отсутствие claim (инвестор) → IDENTITY_COMPANY_NOT_FOUND	Tenant isolation — id из route/query не принимается

Body отсутствует.

Модель ответа GetMyCompanyQueryResult

Поле	Тип	Обязательность	Источник	Masking	Описание
Id	Guid	Да	CompanyEntity.Id	—	Идентификатор компании.
Type	string (enum CompanyType)	Да	CompanyEntity.Type	—	Developer / Agency / Broker / Partner / Pin.
Status	string (enum CompanyStatus)	Да	CompanyEntity.Status	—	Pending / Active / Suspended / Archived.
Name	string	Да	CompanyEntity.Name	—	Отображаемое название.
Slug	string	Да	CompanyEntity.Slug	—	URL-адрес workspace.
Description	string?	Нет	CompanyEntity.Description	—	Публичное описание.
LogoFileId	Guid?	Нет	CompanyEntity.LogoFileId	—	Id файла логотипа во внешнем storage.
Website	string?	Нет	CompanyEntity.Website	—	Сайт.
ContactEmail	string?	Нет	CompanyEntity.ContactEmail	—	Публичный email компании (не PII физлица).
ContactPhone	string?	Нет	CompanyEntity.ContactPhone	—	Публичный телефон компании.
Requisites	CompanyRequisitesModel	Нет	owned VO CompanyRequisites	—	Юрреквизиты (см. таблицу ниже).
WorkspaceSettings	CompanyWorkspaceSettingsModel	Да	jsonb CompanyWorkspaceSettingsDocument	—	Настройки workspace (см. ниже).
SyncSource	string (enum CompanySyncSource)	Да	CompanyEntity.SyncSource	—	Pin / TalentIdentity — фронт по нему делает реплика-поля read-only (INV-5 company.md).
CreatedAt	DateTimeOffset	Да	CompanyEntity.CreatedAt	—	Дата создания.
Version	long	Да	CompanyEntity.Version	—	Доменная версия (для optimistic UI).

CompanyRequisitesModel

Поле	Тип	Обязательность	Источник	Masking	Описание
LegalName	string?	Нет	Requisites.LegalName	—	Юридическое имя.
Inn	string?	Нет	Requisites.Inn	—	ИНН (10/12 цифр).
Kpp	string?	Нет	Requisites.Kpp	—	КПП.
Ogrn	string?	Нет	Requisites.Ogrn	—	ОГРН/ОГРНИП.
LegalAddress	string?	Нет	Requisites.LegalAddress	—	Юридический адрес.

CompanyWorkspaceSettingsModel

Поле	Тип	Обязательность	Источник	Masking	Описание
DefaultRoleId	Guid?	Нет	jsonb DefaultRoleId	—	Роль по умолчанию для приглашённых.
FixationVisibility	string (enum FixationVisibilityMode)	Да	jsonb	—	OwnerOnly / OwnerAndManagers / WholeCompany.
AllowAgentSelfRegistration	bool	Да	jsonb	—	Разрешена ли саморегистрация агентов.
NewsCategoriesEnabled	IReadOnlyList<string>	Да	jsonb	—	Коды доступных категорий новостей.
Locale	string	Да	jsonb	—	BCP-47, дефолт ru-RU.

Алгоритм

1. Контекст и доступ. Операцию выполняет пользователь компании; CompanyId — из claim tenant_id; требуется право identity.companies.view в scope Organization(CompanyId) (алгоритм проверки — check-permission.md). У инвестора компании нет — отсутствие claim tenant_id → IDENTITY_COMPANY_NOT_FOUND; отказ прав → FORBIDDEN.
2. Что читаем. Карточку компании по CompanyId. Если компания не найдена или удалена → IDENTITY_COMPANY_NOT_FOUND. Других агрегатов не читаем.
3. Маппинг. Поле-в-поле по таблице модели ответа: скаляры — из CompanyEntity, Requisites — из owned VO, WorkspaceSettings — из jsonb-документа CompanyWorkspaceSettingsDocument (при версии документа старше текущей недостающие поля дозаполняются дефолтами, company.md «Правила версии»).
4. Результат. Карточка компании (200). Маскирование не требуется (PII физлиц нет). Актуальность — read-your-writes из основной БД (без реплик).

Диаграмма

Ошибки и failure modes

Код	HTTP status	Условие	Сообщение	Retry
IDENTITY_COMPANY_NOT_FOUND	404	Claim tenant_id отсутствует (инвестор) или компания не найдена/архивирована	«Компания не найдена»	no retry
FORBIDDEN	403	Нет identity.companies.view в покрывающем scope	«Недостаточно прав»	no retry
UNAUTHORIZED	401	Нет/просрочен access-токен	—	retry после refresh-token

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

• Новые optional поля ответа — additive; удаление/переименование/смена типа — breaking (migration + rollout).
• Logs: CompanyId, UserId, результат (без тела); metrics: identity_company_get_total{result}; traces: OTel, сквозной traceparent. Dashboard — identity-overview.

Acceptance Criteria

• Given пользователь компании с identity.companies.view и живой claim tenant_id, When GET /companies/my, Then 200 с карточкой своей компании; реквизиты и WorkspaceSettings заполнены (при отсутствии в источнике — null/дефолты); SyncSource отражает источник (по нему UI делает реплика-поля read-only).
• Given у актора нет claim tenant_id (инвестор), When GET /companies/my, Then IDENTITY_COMPANY_NOT_FOUND (404).
• Given актор аутентифицирован, но без identity.companies.view в покрывающем scope, When GET /companies/my, Then FORBIDDEN (403).
• Given компания актора удалена/архивирована, When GET /companies/my, Then IDENTITY_COMPANY_NOT_FOUND (404) — состояние архива неотличимо от отсутствия для пользователя.
• Given только что через update-my-company изменено Name, When тот же пользователь читает карточку, Then возвращается новое Name (чтение из основной БД, без реплик).
• Given в запросе присутствует id чужой компании в route/query, When GET, Then id игнорируется — возвращается только компания из claim tenant_id.

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

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

• API (2): Identity Company-User API — реестр методов и общие правила области, PUT /api/v1/companies/my — Обновление своей компании
• registries (1): Реестр API-методов PIN

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

• Сущность: domain/company.md; permissions: domain/permission.md.
• Мутация: update-my-company.md; проверка прав: check-permission.md.