meraproject/openspec/changes/project-members-write/proposal.md

Proposal: Project Members Write

Расширить services/user-reader (Labor API) эндпоинтами записи составов проектов в Merakomis MySQL с паритетом PHP UI.

Why

Внешние приложения (мессенджер, HR-интеграции) уже читают сотрудников и часы через user-reader, но не могут управлять составом команд проектов — кто в каком проекте, с какой ролью и разделом. Сейчас это возможно только через CMS (cookie-сессия). Запись составов через тот же API-ключ и модель X-Acting-Emp-Id замыкает цикл интеграции: внешняя система → Merakomis БД без дублирования логики в PHP.

What Changes

• Write: PUT /api/project-members — upsert участника команды (добавить или обновить по паре project_id + emp_id)
• Read (вспомогательные):
  • GET /api/project-sections?project_id=… — допустимые разделы проекта (tMerakomisProjectSection)
  • GET /api/member-roles — справочник ролей в команде (порт eMemberRole)
• Permissions: расширить GET /api/labor/permissions полем can_write_member (порт Rules::isRwMember)
• Identity: тот же паттерн, что у табеля — X-Api-Key + обязательный X-Acting-Emp-Id на write-маршрутах
• Документация: DEVELOPERS.md, docs/user-reader-api.md

Capabilities

New Capabilities

• project-members-write: запись и валидация участников команд (tMerakomisTeamMember), права isRwMember, upsert по unique (team, emp)
• project-members-read: вспомогательные read-эндпоинты для UI интеграции (project-sections, member-roles)

Modified Capabilities

• (нет — openspec/specs/ пуст, labor-write не затрагиваем на уровне требований)

Non-goals

• Полная синхронизация «снимок всего состава» (PUT /sync) — отдельный change при необходимости
• Delta-выгрузка изменений составов (/project-members/delta)
• CRUD проектов, разделов справочника tMerakomisDSection, флаг is_all_emp / массовое добавление всех сотрудников
• Login Merakomis в Labor API
• Удаление записи из БД — только деактивация через active: false (как в CMS switcher)

Impact

Область	Изменения
services/user-reader/app/	новые модули project_members_write.py, project_members_read.py; расширение labor_permissions.py, merakomis_schema.py
services/user-reader/app/main.py	подключение роутеров
DEVELOPERS.md, docs/user-reader-api.md	новые эндпоинты, сценарии, матрица доступа
MySQL	запись в tMerakomisTeamMember; чтение tMerakomisProjectSection, tMerakomisProject, tMerakomisTeam
PHP CMS	без изменений; user-reader пишет в те же таблицы