US-реестр контекста handbook (US-HND)
Назначение
Реестр user stories контекста handbook — поддержка нормативных справочников платформы (страны, регионы,
города, валюты, языки) администратором платформы. Ключевая забота администратора — вывести устаревшее или
дублирующее значение из оборота, не сломав существующие ссылки: справочник реплицируется из внешнего
talent.microservices.handbook (PIN его не редактирует, INV-HND-1), а единственный ручной write-путь —
soft-архив/восстановление записи, компенсирующий delete-gap источника
(ADR-0063 п.5). Каждая story
ссылается на покрывающие документы: домены (../domain/), API-методы, use case
UC-HND-001 и события re-publish (../events/).
Metadata
| Поле | Значение |
|---|---|
| ID-диапазон | US-HND-01..08 |
| Контекст | handbook (не tenanted — платформенные данные; source of truth — Talent Handbook) |
| Статус | draft |
| Правило покрытия | Каждая story обязана иметь ≥ 1 покрывающий домен-документ и ≥ 1 операционный документ (api / UC / событие) |
Карта покрытия (обзор)
Роль: Администратор платформы (US-HND-01..08)
Администратор действует через отдельную admin-систему вне основной Identity
(ADR-0053) с permission
handbook.entries.manage в scope платформы; справочник не tenanted.
| № | User Story | Покрытие: домен | Покрытие: API / UC / события |
|---|---|---|---|
| US-HND-01 | Как Администратор, я хочу заархивировать устаревшую или дублирующую запись справочника (страна/регион/город/валюта/язык), чтобы она перестала предлагаться пользователям, но существующие ссылки на неё остались валидными. | ../domain/country.md — IsArchived, INV-HND-5 LookupVisibility; аналогично ../domain/city.md / ../domain/region.md / ../domain/currency.md / ../domain/language.md | ../api/admin/archive-restore-entry.md (archive); UC-HND-001; событие {x}-upserted (IsArchived = true) → pin.handbook.*.v1 |
| US-HND-02 | Как Администратор, я хочу восстановить ошибочно заархивированную запись, чтобы вернуть её в публичный lookup. | ../domain/country.md — IsArchived → false, INV-HND-2 UniqueIsoAmongActive (guard при restore) | ../api/admin/archive-restore-entry.md (restore); UC-HND-001 A1; событие {x}-upserted (IsArchived = false) |
| US-HND-03 | Как Администратор, я хочу быть уверен, что архив записи не ломает исторические ссылки в сервисах (id в документах и событиях по-прежнему резолвится), чтобы старые сделки/адреса/денежные контракты оставались полными. | ../domain/snapshots.md — snapshot строится и для архивной записи; INV-HND-5 (resolve отдаёт архивные) | ../api/internal/resolve-references.md (batch-resolve, включая архивные); UC-HND-001 AC6 |
| US-HND-04 | Как Администратор, я хочу видеть состояние синка (чекпоинты по типам записей, лаг, DLQ), чтобы отличать «запись действительно ушла из источника» от «реплика просто отстала» до принятия решения об архиве. | ../domain/talent-replica.md — HandbookSyncState (AggregateType + ExternalId, LastEventAt) | ../api/admin/get-sync-state.md; UC-HND-001 шаг 2 / A4 |
| US-HND-05 | Как Администратор, я хочу, чтобы повторный архив уже архивной (или повторный restore уже активной) записи был идемпотентным no-op, чтобы двойное нажатие не плодило лишние события. | ../domain/country.md — идемпотентность admin-команды (состояние-цель) | ../api/admin/archive-restore-entry.md (Changed = false); UC-HND-001 AC2 |
| US-HND-06 | Как Администратор, я хочу получать предупреждение при восстановлении записи, которой, вероятно, уже нет в источнике (NotSeenInLastResync), чтобы понимать, что ближайший reconciliation снова предложит её в архив. | ../domain/talent-replica.md — сверка с окном последней пересинхронизации; ../background/talent-initial-import.md — reconciliation | ../api/admin/archive-restore-entry.md (Warning = NotSeenInLastResync); UC-HND-001 |
| US-HND-07 | Как Администратор, я хочу, чтобы при попытке восстановить запись с ISO-кодом, уже занятым активной записью, операция отклонялась с понятной ошибкой, чтобы не создавать конфликт уникальности кодов. | ../domain/country.md / ../domain/currency.md — INV-HND-2 (уникальность ISO среди неархивных) | ../api/admin/archive-restore-entry.md (HANDBOOK_SYNC_ISO_CONFLICT); UC-HND-001 A3 |
| US-HND-08 | Как Администратор, я хочу, чтобы источник оставался главнее моего локального архива (пришёл upsert из Talent → авто-restore записи с предупреждением), чтобы архив в PIN не «прибивал» запись, живую в источнике. | ../domain/talent-replica.md — приоритет источника, авто-restore + warn-метрика (ADR-0063 п.5) | ../consumers/talent-handbook-sync.md; UC-HND-001 A2 |
Зафиксированные ограничения покрытия
Часть ожиданий пользователя относится к записи справочных данных и не покрывается US администратора — это осознанные границы контекста (README, ADR-0063):
| Ожидание | Почему не US администратора | Где решается |
|---|---|---|
| «Завести недостающую страну/город/валюту» | PIN не владеет справочными данными (INV-HND-1) — только реплика | Правка в источнике talent.microservices.handbook → синк донесёт |
| «Переименовать значение» | Реплика-поля правит только синк источника | Переименование в источнике → {x}-upserted |
| «Удалить запись физически» | Физических удалений нет вообще — delete-gap закрыт soft-архивом | US-HND-01 (архив) |
| «Мультиязычные имена справочника» | Источник ведёт названия одноязычно; мультиязычности в v1 нет | Вне scope v1 (ADR-0063 п.3) |
Интеграционные ожидания US-блока handbook
Строгая согласованность гарантируется внутри одной операции handbook (переключение IsArchived +
запись outbox-события — атомарно); согласование локальных реплик потребителей — eventual (секунды).
| US-кластер | Синхронно (в ответе операции) | Асинхронно (событие → консюмер) | Что видит пользователь до доставки |
|---|---|---|---|
| US-HND-01/02 (архив/restore) | IsArchived переключён; публичный lookup сразу отражает состояние | {x}-upserted → pin.handbook.*.v1 (compacted, key = id) → chessboard помечает строку локальной реплики | Значение уходит/возвращается в lookup сразу; фильтры витрины chessboard — с задержкой (секунды) |
| US-HND-03 (ссылки живы) | resolve отдаёт запись по id в любом состоянии | — (архив не каскадирует: архив страны не архивирует её города) | Исторические документы/события полны; согласованность витрин — забота потребителей |
| US-HND-08 (источник главнее) | — | upsert из Talent → авто-restore + warn-метрика → re-publish {x}-upserted | Администратор видит warn на дашборде; повторный архив бессмыслен, пока запись жива в источнике |
Компенсация delete-gap, reconciliation-отчёт и правила синка — ../background/talent-initial-import.md, ../domain/talent-replica.md; события re-publish — контракт per-key, at-least-once.
Обратные ссылки
Автоссылки: где используется этот документ.
- registries (1): Реестр use cases и user stories PIN
Связанные документы
- Домены: ../domain/country.md, ../domain/region.md, ../domain/city.md, ../domain/currency.md, ../domain/language.md, ../domain/snapshots.md, ../domain/talent-replica.md.
- API: ../api/admin/archive-restore-entry.md, ../api/admin/get-sync-state.md, ../api/internal/resolve-references.md, ../api/public/lookup-references.md.
- Use case: UC-HND-001; README контекста ../README.md.
- ADR: 0063 (репликация, delete-gap, soft-архив), 0053 (admin-система).