arm-core/openspec/specs/directory-policy/spec.md

directory-policy Specification

Purpose

Политика видимости справочников поверх прав: что именно из ГК/ЮЛ/ГСК видит пользователь, определяется данными о его филиале, а не кодом роли (§10.1 05-domain-rules.md).

Requirements

Requirement: Область видимости вычисляется из филиала пользователя

Для каждого запроса ядро SHALL вычислять область видимости из Principal: если regional_office.is_head_office = true — вся система; иначе — ГК с company_group.base_regional_office_id = app_user.regional_office_id, их ЮЛ и ГСК/ГСЗ, а также монозаёмщики с legal_entity.regional_office_id = app_user.regional_office_id. Код роли (role.code) MUST NOT участвовать в вычислении; business_segment в Срезе 1 не используется (ASSUMPTION(OQ-86)).

Scenario: Пользователь филиала видит только своё

• WHEN есть ГК А (филиал X) и ГК Б (филиал Y), пользователь KA_RF филиала X запрашивает список ГК
• THEN в ответе только ГК А, total = 1

Scenario: Пользователь ГО видит всё

• WHEN пользователь с is_head_office = true запрашивает список ГК
• THEN в ответе обе ГК

Requirement: Объект вне видимости неотличим от несуществующего

Чтение, изменение и любые операции над ГК/ЮЛ/ГСК вне области видимости SHALL возвращать 404 с тем же телом, что и для несуществующего идентификатора; 403 для этого случая MUST NOT использоваться.

Scenario: Чужая ГК по id

• WHEN пользователь филиала X запрашивает GET /directories/company-groups/{id} ГК Б
• THEN ответ 404, текст совпадает с ответом на случайный uuid

Requirement: Политика применяется до прав на изменение

Проверка права (require) и проверка видимости SHALL выполняться обе; порядок: право → видимость → операция. Создание ГК пользователем филиала SHALL привязывать её к его филиалу, если base_regional_office_id не указан; указание чужого филиала пользователем филиала → 422 OFFICE_NOT_ALLOWED.

Scenario: Создание ГК из филиала

• WHEN пользователь филиала X с DIRECTORY_EDIT создаёт ГК без филиала
• THEN у ГК base_regional_office_id = X, и она видна создателю

Requirement: Видимость консолидаций и редактируемость версии

Консолидация и её версии SHALL быть видимы тем же пользователям, что и её ГК (company_group); чужие и несуществующие — 404 с одинаковым телом (код NOT_FOUND, сообщение CONSOLIDATION_NOT_FOUND / VERSION_NOT_FOUND; так устроены все 404 этого среза: NotFoundError несёт только текст сообщения). Правка версии (периметр, ручная смена статуса, сопоставление контрагента) SHALL проходить проверки в порядке: право → видимость → статус версии ∈ {INITIATED, DOCUMENTS_PROCESSING, DATA_CORRECTION} (иначе 409 VERSION_NOT_EDITABLE) → активная consolidation_lock есть (иначе 409 LOCK_REQUIRED) и принадлежит пользователю (иначе 409 LOCKED_BY_OTHER с владельцем). Проверка реализуется чистой функцией в domain/policy.py без обращения к коду роли. Чтение (карточка, свод, чек-лист, экспорт, кандидаты) и загрузка/подтверждение документов от статуса блокировки MUST NOT зависеть. Зоны ответственности не учитываются (ASSUMPTION(OQ-86)).

Scenario: Чужая блокировка

• WHEN версию держит А, Б с CONSOLIDATION_EDIT вызывает PUT …/members
• THEN 409 LOCKED_BY_OTHER, detail.locked_by = A

Scenario: Аннулированная версия

• WHEN версия в CANCELLED, владелец прежней блокировки вызывает POST …/osv/entries/{id}/counterparty
• THEN 409 VERSION_NOT_EDITABLE

Scenario: Куратор ГО читает

• WHEN curator_go (только CONSOLIDATION_VIEW) запрашивает свод версии любого филиала
• THEN 200