Гайд фронтенд-разработчика по API arm-core (#55) #57

aep · 2026-10-07T18:08:58+03:00

aep commented

2026-10-07 18:08:58 +03:00

Closes #55

Что сделано

dev/frontend-api-guide.md — единая точка входа для фронта по API arm-core (состояние main f4a7806, после #46 и #47):
- §1 что изменилось 05–07.10.2026 и что сделать в клиенте (legal_entity_ids, самоописывающие ячейки, MemberOut.entity_type/osv_accounts, решения П-1/П-2/П-3, Срез 3b, границы #26, Swagger Authorize, Q1-эквивалентность, «Основной РФ» объектом);
- §2 подключение (env, dev-токен, Swagger, healthcheck, CORS, генерация типов);
- §3 общие правила: порядок проверок, три формы detail + исключение UploadResult, видимость, типы значений, страницы и лимиты, PATCH-семантика, лишние поля, перечисления с подписями UI;
- §4 права; §5 все 62 операции по областям (право, запрос, ответ, коды ошибок) и краткие схемы;
- §6 экраны → вызовы и «что перечитать после действия»; §7 скачивание файлов; §8 тонкости; §9 каталог доменных кодов с действиями UI;
- §10 известные ограничения; §11 что изменится (КПП, arm-core #45; SSO); §12 чек-лист клиента.
dev/api-contract-files-directories.md: is_head_office у филиала, outside_group/closed у ЮЛ (M-5 из arm-core#48), FILE_TOO_LARGE — настройка UPLOAD_MAX_BYTES (M-6), дочитывание ЮЛ модалки [42] по offset (M-7), филиал объектом (arm-core #47).
dev/README.md: ссылка на гайд (начинать с него) и на контракт файлов и справочников.

Сверка: OpenAPI выгружен из кода main, затем независимое ревью (opus) против api/src — 18 находок, все учтены (главная: PATCH ЮЛ с entity_type: null даёт 422 массивом, а не 500).

Находки

Маркер	Находка	Статус
O-1	CORS ядра без `expose_headers`: при фронте на другом источнике (dev `:3000` → `:8000`) JS не читает `Content-Disposition` у первички, CSV и xlsx; нужно `expose_headers=["Content-Disposition"]` в `arm-core/api/src/app.py:cors_options`	deferred (описано в гайде §7, §10 п. 9)
O-2	arm-core#48 O-2 («PATCH ЮЛ `entity_type: null` → 500») не воспроизводится: `LegalEntityUpdate._required_fields_are_not_null` отвечает 422 раньше `validate_inn`	deferred (поправить формулировку в arm-core#48)
O-3	Описания ошибок в OpenAPI неточны: загрузка — «VERSION_NOT_FOUND» (на деле `NOT_FOUND`), 422 `ENTITY_NOT_IN_PERIMETER` описан как `UploadResult`; у `PATCH …/statement` в 409 указан `NOTHING_TO_ACCEPT`, у акцепта в 422 — `INVALID_INN`/`UNKNOWN_CELL`/`DUPLICATE_CELL`	deferred
O-4	`dev/README.md` ссылается на несуществующий `../openspec/changes/slice-0-skeleton/design.md` (было до PR; родственно O-1 из arm-core#48)	deferred
O-5	`make check` в docs не запущен до конца: нет `jsonschema` в системном python (контракты PR не затрагивает)	deferred

Rulings I made

R-1: гайд — отдельный документ-точка входа поверх существующих контрактов (они остаются источником деталей), а не их слияние.
R-2: в §1 и §11 гайд описывает main arm-core на момент PR (#47 уже слит), КПП (#45) — как предстоящее изменение по утверждённой DBML v5.17.
R-3: в контракт файлов внесены docs-пункты M-5/M-6/M-7 из arm-core#48 (затрагивают фронт).

🤖 Generated with Claude Code

https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2

Closes #55 ## Что сделано - **`dev/frontend-api-guide.md`** — единая точка входа для фронта по API `arm-core` (состояние `main` f4a7806, после #46 и #47): - §1 что изменилось 05–07.10.2026 и что сделать в клиенте (legal_entity_ids, самоописывающие ячейки, MemberOut.entity_type/osv_accounts, решения П-1/П-2/П-3, Срез 3b, границы #26, Swagger Authorize, Q1-эквивалентность, «Основной РФ» объектом); - §2 подключение (env, dev-токен, Swagger, healthcheck, CORS, генерация типов); - §3 общие правила: порядок проверок, три формы `detail` + исключение `UploadResult`, видимость, типы значений, страницы и лимиты, PATCH-семантика, лишние поля, перечисления с подписями UI; - §4 права; §5 все 62 операции по областям (право, запрос, ответ, коды ошибок) и краткие схемы; - §6 экраны → вызовы и «что перечитать после действия»; §7 скачивание файлов; §8 тонкости; §9 каталог доменных кодов с действиями UI; - §10 известные ограничения; §11 что изменится (КПП, arm-core #45; SSO); §12 чек-лист клиента. - **`dev/api-contract-files-directories.md`**: `is_head_office` у филиала, `outside_group`/`closed` у ЮЛ (M-5 из arm-core#48), `FILE_TOO_LARGE` — настройка `UPLOAD_MAX_BYTES` (M-6), дочитывание ЮЛ модалки [42] по `offset` (M-7), филиал объектом (arm-core #47). - **`dev/README.md`**: ссылка на гайд (начинать с него) и на контракт файлов и справочников. Сверка: OpenAPI выгружен из кода `main`, затем независимое ревью (opus) против `api/src` — 18 находок, все учтены (главная: `PATCH` ЮЛ с `entity_type: null` даёт 422 массивом, а не 500). ## Находки | Маркер | Находка | Статус | |---|---|---| | O-1 | CORS ядра без `expose_headers`: при фронте на другом источнике (dev `:3000` → `:8000`) JS не читает `Content-Disposition` у первички, CSV и xlsx; нужно `expose_headers=["Content-Disposition"]` в `arm-core/api/src/app.py:cors_options` | deferred (описано в гайде §7, §10 п. 9) | | O-2 | arm-core#48 O-2 («PATCH ЮЛ `entity_type: null` → 500») не воспроизводится: `LegalEntityUpdate._required_fields_are_not_null` отвечает 422 раньше `validate_inn` | deferred (поправить формулировку в arm-core#48) | | O-3 | Описания ошибок в OpenAPI неточны: загрузка — «VERSION_NOT_FOUND» (на деле `NOT_FOUND`), 422 `ENTITY_NOT_IN_PERIMETER` описан как `UploadResult`; у `PATCH …/statement` в 409 указан `NOTHING_TO_ACCEPT`, у акцепта в 422 — `INVALID_INN`/`UNKNOWN_CELL`/`DUPLICATE_CELL` | deferred | | O-4 | `dev/README.md` ссылается на несуществующий `../openspec/changes/slice-0-skeleton/design.md` (было до PR; родственно O-1 из arm-core#48) | deferred | | O-5 | `make check` в docs не запущен до конца: нет `jsonschema` в системном python (контракты PR не затрагивает) | deferred | ## Rulings I made - R-1: гайд — отдельный документ-точка входа поверх существующих контрактов (они остаются источником деталей), а не их слияние. - R-2: в §1 и §11 гайд описывает `main` arm-core на момент PR (#47 уже слит), КПП (#45) — как предстоящее изменение по утверждённой DBML v5.17. - R-3: в контракт файлов внесены docs-пункты M-5/M-6/M-7 из arm-core#48 (затрагивают фронт). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2

aep added 1 commit 2026-10-07 18:09:00 +03:00

docs(dev): единый гайд фронтенд-разработчика по API arm-core (#55 ) 0e030bd5c4

dev/frontend-api-guide.md — точка входа для фронта: подключение, общие правила
(три формы detail, видимость, деньги строками, PATCH-семантика, лишние поля,
лимиты), все 62 операции по областям с правами и кодами ошибок, сценарии
экранов и что перечитывать после действий, скачивание файлов, каталог кодов,
известные ограничения, изменения 05–07.10.2026 и ближайшие (КПП, #45).
Сверено с OpenAPI и кодом arm-core main (f4a7806, после #46 и #47).

api-contract-files-directories.md: is_head_office у филиала, outside_group/closed
у ЮЛ (M-5), FILE_TOO_LARGE — настройка UPLOAD_MAX_BYTES (M-6), дочитывание ЮЛ
модалки [42] по offset (M-7), филиал объектом (arm-core #47).
README: ссылка на гайд и на контракт файлов и справочников.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2