POST /api/investors/me/pin-code/clear — Удаление пин-кода (clearPinCode)
Назначение
Удалить пин-код быстрого входа текущего пользователя. Вызывается аутентифицированным пользователем из
личного кабинета; тела запроса нет. После удаления вход возвращается к паролю/СМС (hasPinCode = false).
Операция естественно идемпотентна: повторное удаление уже пустого пин-кода успешно.
| Поле | Значение |
|---|
| Сервис/контекст | identity |
| API area | public |
| Feature group | security |
| Статус | approved |
| Документ | docs/06-services/identity/api/investor/clear-pin-code.md |
Актор и доступ
| Проверка | Значение |
|---|
| Actor type | User (Bearer JWT) |
| Auth policy / Permissions | authenticated; permission identity.security.manage-self |
| Scope (RBAC) | self |
| Record-level | только собственная запись (UserId из sub) |
| Tenant isolation | не применяется (ADR-0052) |
| Audit | security-change: событие UserSecurityChangedEvent (PinCodeCleared) |
HTTP-контракт
| Поле | Значение |
|---|
| Method | POST |
| Route | /api/investors/me/pin-code/clear |
| Success status | 200 |
| Idempotency header | не применяется — операция естественно идемпотентна (повторное удаление пустого пин-кода = 200) |
| Correlation | сквозной trace через traceparent |
Входные данные / параметры запроса
Body отсутствует.
| Поле | Источник | Тип | Обязательность | Валидация / Ограничения | Безопасность |
|---|
UserId | identity claims (sub) | Guid | Да | валидный JWT | 401 без токена |
Модель ответа ClearPinCodeCommandResult
| Поле | Тип | Обязательность | Источник | Masking | Описание |
|---|
investorId | string (Guid) | Да | UserEntity.Id | — | Идентификатор пользователя. |
Алгоритм
Получить пользователя-актора (UserId из токена); он должен быть Active, иначе IDENTITY_USER_BLOCKED.
Очистить пин-код (PinCodeHash = null); если пин-кода не было — no-op без ошибки (идемпотентность). При
фактическом изменении фиксируется доменное событие UserSecurityChangedEvent (вид PinCodeCleared) для
аудита. Ответ — investorId, HTTP 200.
Ошибки и failure modes
| Код | HTTP status | Условие | Сообщение | Retry |
|---|
| — (auth) | 401 | Нет/просрочен JWT | клиент выполняет re-login | re-login |
IDENTITY_USER_BLOCKED | 400 | Status != Active | «Учётная запись заблокирована» | no retry |
Acceptance Criteria
- Given активный пользователь с установленным пин-кодом, When clear-pin-code, Then
PinCodeHash = null, поднимается UserSecurityChangedEvent (PinCodeCleared), ответ 200 {investorId};
дальнейший вход по пин-коду недоступен (hasPinCode = false).
- Given пин-код не задан, When повторный clear-pin-code, Then
200 без ошибки и без события
(идемпотентный no-op).
- Given
Status != Active, When clear-pin-code, Then IDENTITY_USER_BLOCKED (400).
Совместимость и наблюдаемость
- Операция идемпотентна.
- Logs:
UserId; metrics: identity_pin_code_clear_total; traces — OTel.
Обратные ссылки
Автоссылки: где используется этот документ.
Связанные документы