🧭 Правила параллельной разработки

⚠️ Критично. Нарушение этих правил дважды роняло демо-прод и создавало битые merge'и и двойные alembic-головы. Читать перед тем, как запускать несколько сессий/ потоков на Capital.

Железное правило: параллелить по СЕРВИСАМ-репозиториям, НЕ по слоям

Работать в разных компонентных репозиториях одновременно - можно. Резать одну фичу одного сервиса на параллельные слои (identity / ledger / design / cards в одном и том же cabinet/) - нельзя. Внутри одного сервиса - последовательно.

Почему (боль CEO 2026-09-16)

Работали в 6 worktree ОДНОГО головного capital, нарезав фичу кабинета на слои. Все слои физически в одних файлах (cabinet/app/main.py, shared/models.py, migrations/) → гарантированные конфликты: задача #32 сделана дважды, битый merge, 2 alembic-головы. Вывод закреплён как правило.

⚠️ Отдельная ловушка: папка capital-ledger в дереве работала как worktree головного, а НЕ как компонентный репо. Не путать worktree головного с настоящим клоном компонентного репозитория.

Правильная раздача потоков

Поток	Репозиторий	Что делает
🅰	`capital-portal` (=cabinet)	клиентский кабинет
🅱	`capital-ledger` (=backoffice)	операторский back-office
🅲	`capital-kyc`	KYC-мост
🅳	`capital-kb` / `capital-support`	документация / инциденты

Два потока в разных репо из этой таблицы - безопасно. Два потока в одном репо - последовательно.

Три железных запрета

🚫 shared/models.py + migrations/ правит ОДИН поток за раз. Общая схема - единственный источник; параллельные правки дают конфликтующие миграции и несколько alembic-голов. Если фиче нужна правка модели - она забирает «замок» на схему на это время.
🚫 Деплой - ТОЛЬКО из головного capital, одной рукой. Не деплоить параллельно из разных сессий (дважды 15.09 параллельные сессии роняли демо).
🚫 Не резать одну фичу одного сервиса на параллельные слои. Слои одного сервиса = одни файлы = конфликты.

Subtree-workflow (головной ↔ компонентные)

Компонентные репо выделены git subtree split с сохранением истории.

# Подтянуть изменения компонента в головной:
git subtree pull -P backoffice git@github.com:CryGor11/capital-ledger.git main
git subtree pull -P cabinet    git@github.com:CryGor11/capital-portal.git main
git subtree pull -P shared     git@github.com:CryGor11/capital-shared.git main
# Отправить правку, сделанную прямо в головном, обратно в компонент:
git subtree push -P <папка> <repo> main

Ветки в компонентах: feature/* / hotfix/* → PR → merge в main компонента → subtree pull в головной. Команды продублированы в README головного capital.

Alembic при слиянии

Слияние двух веток, каждая со своей миграцией, даёт 2 heads. Свести merge- миграцией (alembic merge <rev1> <rev2>), чтобы на проде остался один head. Прецедент: a9e2c4b6d8f1 свёл f3a9d6e2b8c4 + dc9106c1f206. Детали - runbooks/MIGRATIONS.md.

Владение демо-продом

app.algorys.cc закреплён за одной веткой кабинета за раз. Остальные ветки тестируются на отдельном stage-контейнере, не на демо-проде.

Порядок слияния зависимых веток

Когда несколько веток кабинета накопились - сливать в порядке зависимостей (например security → identity → ledger-model), с security-review каждой money/auth- critical ветки и stage-проверкой перед продом.

Чеклист перед запуском параллельной работы

[ ] Каждый поток - в СВОЁМ компонентном репо (не worktree головного, не слой одного сервиса)?
[ ] Никто, кроме одного потока, не трогает shared/models.py + migrations/?
[ ] Деплой запускает только один (из головного)?
[ ] Демо-прод не занят чужой веткой?