Chessboard API — реестр операций областей Developers и Admin

Индекс HTTP-операций контекста chessboard (Pin.Chessboard.Api) для областей developers (менеджер застройщика, scope своей компании) и admin (администратор платформы, ADR-0053). Public/Agents-области (лента, карточки, шахматка) — отдельные документы этого же каталога (будущие). Дом полей сущностей — ../domain/.

Metadata

Поле	Значение
Сервис/контекст	chessboard (Pin.Chessboard)
Статус	draft
Owning team	PIN Platform Core
Область действия	API areas developers, admin

Общие правила областей

Область developers (менеджер застройщика)

Правило	Значение
Actor type	User — сотрудник компании-застройщика (developer-manager)
Аутентификация	JWT identity; claims: sub = UserId, tenant_id = CompanyId
Tenant isolation	TenantId = CompanyId = DeveloperId (ADR-0052); выборки и мутации автоматически ограничены tenant-ом актора — чужие проекты/здания/объекты недвижимости недостижимы (404, не 403 — существование чужих записей не раскрывается)
Permissions	chessboard.projects.manage, chessboard.buildings.manage, chessboard.property-objects.manage, chessboard.layouts.manage, chessboard.references.lookup — каталог и scope-назначения в ../../identity/domain/permission.md
Scope (RBAC)	Организация (Organization(CompanyId)); scope «группа проектов/проект» — сужение через role assignments identity
Sync-guard	Реплика-поля Talent (SyncSource = TalentChessboard) через API не меняются — инварианты *-SyncOwnedFields (INV-DEV-3, INV-PRJ-9, INV-BLD-7, INV-LAY-6)
Статусы объектов недвижимости	Developers API меняет только Free ↔ Hidden (INV-CHS-001); Reserved/Booked/Sold — исключительно события CRM
Route prefix	/api/v1/developers/…

Область admin (администратор платформы, ADR-0053)

Правило	Значение
Actor type	Администратор платформы через admin API (m2m-токен, audience pin.chessboard.admin), id админа для аудита — в X-Admin-User-Id
Permissions	chessboard.banks.manage, chessboard.hoteliers.manage
Tenant isolation	Не применяется — справочники Bank/Hotelier платформенные, не привязаны к застройщику (ADR-0052 п.3)
Audit	Обязателен: CreatedByUserId/UpdatedByUserId/DeletedByUserId = id админа из X-Admin-User-Id
Route prefix	/api/v1/admin/…

Сквозные соглашения областей (идемпотентность, публикация событий, согласованность)

Правило	Значение
Идемпотентность create	POST-создание принимает опциональный Idempotency-Key; повтор с тем же ключом и телом возвращает первый результат без повторного создания и без повторного события; тот же ключ с иным телом → IDEMPOTENCY_KEY_MISMATCH (409). Массовый upsert объектов недвижимости — ключ обязателен.
Идемпотентность update/archive	PUT/DELETE идемпотентны по природе: правка — сверка доменной версии (CHESSBOARD_CONCURRENCY_CONFLICT при расхождении), архив — по достигнутому состоянию DeletedAt != null (повтор — no-op).
Публикация событий	Каждая мутация публикует snapshot-событие pin.chessboard.*-upserted.v1 (key = Id агрегата) в том же согласованном изменении (outbox); ответ 2xx не ждёт доставки. Порядок, версии и дедуп потребителя — ../README.md, «Гарантии Событий И Согласованность». Справочники Bank/Hotelier событий не публикуют (ADR-0056).
Согласованность для клиента	Изменение видно в кабинете застройщика / admin-выборках сразу (read-after-write); реплики соседей и публичная витрина — в пределах SLO применения событий; денормализованные агрегаты проекта — после project-aggregates-recalc (debounce 30 с).

Реестр операций — область developers

Проекты (feature group projects, permission chessboard.projects.manage)

#	Операция	HTTP	Route	Документ
1	searchProjects	GET	/api/v1/developers/projects	developers-search-projects.md
2	getProject	GET	/api/v1/developers/projects/{projectId}	developers-get-project.md
3	createProject	POST	/api/v1/developers/projects	developers-create-project.md
4	updateProject	PUT	/api/v1/developers/projects/{projectId}	developers-update-project.md
5	publishProject	POST	/api/v1/developers/projects/{projectId}/publish	developers-publish-project.md
6	unpublishProject	POST	/api/v1/developers/projects/{projectId}/unpublish	developers-unpublish-project.md

Здания (feature group buildings, permission chessboard.buildings.manage)

#	Операция	HTTP	Route	Документ
7	searchBuildings	GET	/api/v1/developers/projects/{projectId}/buildings	developers-search-buildings.md
8	getBuilding	GET	/api/v1/developers/buildings/{buildingId}	developers-get-building.md
9	createBuilding	POST	/api/v1/developers/projects/{projectId}/buildings	developers-create-building.md
10	updateBuilding	PUT	/api/v1/developers/buildings/{buildingId}	developers-update-building.md
11	setBuildingStatus	POST	/api/v1/developers/buildings/{buildingId}/status	developers-set-building-status.md

Объекты/объекты недвижимости (feature group propertyObjects, permission chessboard.property-objects.manage)

#	Операция	HTTP	Route	Документ
12	searchPropertyObjects	GET	/api/v1/developers/projects/{projectId}/property-objects	developers-search-property-objects.md
13	getPropertyObject	GET	/api/v1/developers/property-objects/{propertyObjectId}	developers-get-property-object.md
14	createPropertyObject	POST	/api/v1/developers/buildings/{buildingId}/property-objects	developers-create-property-object.md
15	updatePropertyObject	PUT	/api/v1/developers/property-objects/{propertyObjectId}	developers-update-property-object.md
16	bulkUpsertPropertyObjects	POST	/api/v1/developers/buildings/{buildingId}/property-objects/bulk	developers-bulk-upsert-property-objects.md
17	changePropertyObjectPrice	POST	/api/v1/developers/property-objects/{propertyObjectId}/price	developers-change-property-object-price.md
18	hidePropertyObject	POST	/api/v1/developers/property-objects/{propertyObjectId}/hide	developers-hide-property-object.md
19	unhidePropertyObject	POST	/api/v1/developers/property-objects/{propertyObjectId}/unhide	developers-unhide-property-object.md

Планировки и группы (feature group layouts, permission chessboard.layouts.manage)

#	Операция	HTTP	Route	Документ
20	listLayouts	GET	/api/v1/developers/projects/{projectId}/layouts	developers-list-layouts.md
21	createLayout	POST	/api/v1/developers/projects/{projectId}/layouts	developers-create-layout.md
22	updateLayout	PUT	/api/v1/developers/layouts/{layoutId}	developers-update-layout.md
23	archiveLayout	POST	/api/v1/developers/layouts/{layoutId}/archive	developers-archive-layout.md
24	listLayoutGroups	GET	/api/v1/developers/projects/{projectId}/layout-groups	developers-list-layout-groups.md
25	createLayoutGroup	POST	/api/v1/developers/projects/{projectId}/layout-groups	developers-create-layout-group.md
26	updateLayoutGroup	PUT	/api/v1/developers/layout-groups/{layoutGroupId}	developers-update-layout-group.md
27	archiveLayoutGroup	POST	/api/v1/developers/layout-groups/{layoutGroupId}/archive	developers-archive-layout-group.md

Lookup справочников (feature group references, permission chessboard.references.lookup)

#	Операция	HTTP	Route	Документ
28	lookupBanks	GET	/api/v1/developers/lookup/banks	developers-references-lookup.md
29	lookupBankById	GET	/api/v1/developers/lookup/banks/{bankId}	developers-references-lookup.md
30	lookupHoteliers	GET	/api/v1/developers/lookup/hoteliers	developers-references-lookup.md
31	lookupHotelierById	GET	/api/v1/developers/lookup/hoteliers/{hotelierId}	developers-references-lookup.md

Lookup-методы продублированы в Agents API теми же запросами — маршруты /api/v1/agents/lookup/…, различие только в policy (агентские permissions); отдельно не документируются.

Реестр операций — область admin

#	Операция	HTTP	Route	Документ
32	createBank	POST	/api/v1/admin/banks	admin-banks-crud.md
33	searchBanks	GET	/api/v1/admin/banks	admin-banks-crud.md
34	getBank	GET	/api/v1/admin/banks/{bankId}	admin-banks-crud.md
35	updateBank	PUT	/api/v1/admin/banks/{bankId}	admin-banks-crud.md
36	deleteBank	DELETE	/api/v1/admin/banks/{bankId}	admin-banks-crud.md
37	lookupBanks (admin)	GET	/api/v1/admin/lookup/banks (+/{bankId})	admin-banks-crud.md
38	createHotelier	POST	/api/v1/admin/hoteliers	admin-hoteliers-crud.md
39	searchHoteliers	GET	/api/v1/admin/hoteliers	admin-hoteliers-crud.md
40	getHotelier	GET	/api/v1/admin/hoteliers/{hotelierId}	admin-hoteliers-crud.md
41	updateHotelier	PUT	/api/v1/admin/hoteliers/{hotelierId}	admin-hoteliers-crud.md
42	deleteHotelier	DELETE	/api/v1/admin/hoteliers/{hotelierId}	admin-hoteliers-crud.md
43	lookupHoteliers (admin)	GET	/api/v1/admin/lookup/hoteliers (+/{hotelierId})	admin-hoteliers-crud.md

Справочники Bank/Hotelier — простые справочные сущности одной формы (Id, Название, Лого), поэтому их CRUD-группы описаны одним файлом на справочник (полный алгоритм — на каждую операцию внутри файла); lookup четырёх операций developers-области — одним файлом (однотипные read-only запросы).

Сквозные ошибки области (не повторяются в каждом файле)

Код	HTTP status	Условие
ValidationError	400	Нарушение format/min/max/pattern/enum
UNAUTHORIZED	401	Нет/просрочен JWT (developers) или m2m-токен (admin)
FORBIDDEN	403	Нет требуемого permission в scope
CHESSBOARD_CONCURRENCY_CONFLICT	409	Несовпадение доменной версии сущности (конкурентная правка)
IDEMPOTENCY_KEY_MISMATCH	409	Тот же Idempotency-Key переиспользован с иным телом запроса (операции с idempotency-заголовком)

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

• Домены: developer · project · building · propertyObject · layout · layout-group · bank · hotelier · reference-data.
• ADR: ADR-0052 (tenancy TenantId = CompanyId), ADR-0053 (админ-доступ, m2m), ADR-0056 (simplicity-first).
• Обзор сервиса: ../README.md.