sync-contracts-prompt

Промт для актуализации контрактов в vault

Запускается из директории obsidian_erp/ в Claude Code. Скопировать всё, что ниже разделителя ===PROMPT===, и вставить как первое сообщение в новой сессии Claude Code.

---

=PROMPT=

Задача: синхронизировать 03-Services/ и 09-Frontend Specs/ с реальным кодом

Vault obsidian_erp — единственный источник правды по контрактам. Он отстал от кода. Нужно пройти по всем активным репозиториям, сравнить реальные контракты в коде с тем, что лежит в vault, и актуализировать vault так, чтобы в 03-Services/ были описаны все REST-эндпоинты / Kafka-события / таблицы БД из кода, а в 09-Frontend Specs/ — все экраны/роуты из фронтов.

Это разовая «зачистка», после которой vault = код.

0. Контекст

• Все репозитории — sibling-папки рядом с vault: ../erp-*, ../quartz-*, ../ai-photo-*.
• Полный список и пути: 07-Tasks/Repositories.md (прочитай его первым делом).
• Соглашения по структуре документации: CLAUDE.md в корне vault.
• Бэк-сервисы — Java + Spring Boot, фронты — React (Vite/Tauri), BFF — Node.js + Fastify + TS.

1. Mapping «репо → папка в vault»

Бэкенд-сервисы → 03-Services/{Service Name}/

Репозиторий	Папка в vault
erp-auth-service	03-Services/Auth Service/
erp-user-service	03-Services/User Service/
erp-store-service	03-Services/Store Service/
erp-catalog-service	03-Services/Catalog Service/
erp-warehouse-service	03-Services/Warehouse Service/
erp-order-service	03-Services/Order Service/
erp-aggregator-service	03-Services/Aggregator Service/
erp-customer-service	03-Services/Customer Service/
erp-paykeeper-adapter	03-Services/Paykeeper Adapter/
erp-loyalty-service	если код пустой — пропустить, оставить заглушку
ai-photo-studio-backend	03-Services/Photo Studio Service/
erp-openclaw-skills	03-Services/OpenClaw Agent/ (MCP-tools = REST-подобные контракты skills)

BFF → 03-Services/ (как API для своего фронта)

Репо/часть	Папка в vault
erp-admin/bff/	создать 03-Services/Admin BFF/ если её нет, иначе обновить
erp-pos-desktop/ (если есть BFF-слой)	03-Services/POS BFF/
erp-admin/bff/src/routes/agent.ts (WS-shim)	упомянуть в 03-Services/Admin BFF/API.md секцией WS endpoints

Фронты → 09-Frontend Specs/{Продукт}/

Репозиторий / часть	Папка в vault
erp-admin/web/	09-Frontend Specs/Админка Франшизы/
erp-pos-desktop/src/	09-Frontend Specs/POS/
erp-kds/src/	09-Frontend Specs/KDS/
ai-photo-studio-frontend/	09-Frontend Specs/AI Студия/
erp-pos/	заморожен (см. Repositories.md) — пропустить, ничего не обновлять

2. Что искать в коде (по типу репо)

Бэкенд-сервис (Java + Spring Boot)

Контракты, которые должны быть в 03-Services/{Service}/:

Файл vault	Источник в коде
API.md	@RestController + @RequestMapping + @GetMapping/@PostMapping/... — собрать все методы, путь, входной DTO, выходной DTO, требуемая роль/permission (@PreAuthorize или фильтры)
Events.md	Kafka — все @KafkaListener (consumers) и публикации через KafkaTemplate / Outbox (producers); топики, payload-DTO, consumer group
Data Model.md	Liquibase changelogs (src/main/resources/db/changelog/) и JPA @Entity — все таблицы, поля, FK, индексы; ER-диаграмма в Mermaid
Overview.md	application.yml (порт, зависимости — Postgres/Redis/Kafka/S3), README, pom.xml (стек, версии); ответственность сервиса = пересечение entity + endpoint groups

Перепроверь port, tech_stack, database, redis, s3 во frontmatter — они должны соответствовать application.yml.

BFF (Node.js + Fastify + TS)

Файл vault	Источник
API.md	роуты Fastify (app.get, app.post или плагины маршрутов) — все REST + WS endpoints, входные/выходные схемы (часто Zod / JSON schema)
Events.md	если BFF потребляет Kafka / SSE — описать; иначе раздел «События не публикуются»
Overview.md	какие микросервисы агрегирует, какой клиент обслуживает, конфиг

Фронт (React)

Для каждого роута (React Router <Route path=...> или Tauri-аналоги) — отдельный файл .md в 09-Frontend Specs/{Продукт}/ (по экрану или по логической группе экранов). В файле:

• route и api во frontmatter / в шапке
• Что видит пользователь, ключевые компоненты, состояния (loading/empty/error)
• Колонки таблиц, поля форм, действия, валидации, permission-гейты
• Ссылки [[wikilinks]] на связанные экраны и на эндпоинты в 03-Services/

Если такой .md уже есть — обновить недостающее. Если экран в коде есть, а в vault его нет — создать. Если в vault есть файл, а в коде экрана уже нет — пометить status: removed во frontmatter и оставить запись (не удалять).

3. Алгоритм выполнения

Делегируй каждому репо отдельного sub-agent (subagent_type=Explore для инвентаризации, subagent_type=general-purpose для написания файлов в vault). По 3-4 агента параллельно — больше не запускай, иначе захлебнётся context.

Фаза 1. Инвентаризация (read-only, параллельно)

Для каждого репо запусти Explore-агента с задачей:

Собрать полный список контрактов в репозитории <path>:

• все REST-эндпоинты (method, path, controller-class, требуемая роль/permission)
• все Kafka-топики (producer/consumer, payload-class)
• все таблицы БД (имя, ключевые колонки, FK) — из Liquibase changelog
• все фронт-роуты (если фронт) — path + компонент Ответ — структурированный список (markdown-таблицы), не более 600 строк. Не открывать тесты.

Сохраняй ответы агентов в памяти сессии, не записывай в vault на этой фазе.

Фаза 2. Сравнение с vault (одна сессия)

Прочитай текущие 03-Services/{Service}/API.md, Events.md, Data Model.md, Overview.md и фронт-спеки 09-Frontend Specs/{Продукт}/*.md.

Для каждого сервиса/фронта составь diff-таблицу:

Контракт	В коде	В vault	Действие
POST /api/v1/foo	✓	✗	добавить в API.md
GET /api/v1/legacy	✗	✓	пометить deprecated в API.md
customer.created Kafka topic	✓	✗	добавить в Events.md
таблица audit_log	✓	✗	добавить в Data Model.md

Фаза 3. Обновление vault (последовательно по сервисам)

Для каждого сервиса/фронта по очереди:

1. Обнови API.md / Events.md / Data Model.md / Overview.md — добавь недостающее, обнови изменившееся, пометь удалённое из кода как deprecated (не удаляй).
2. Сохрани существующий стиль файла (frontmatter, Mermaid-диаграммы, callouts, wikilinks).
3. Подними updated: YYYY-MM-DD во frontmatter на сегодня (2026-05-13).
4. Если файла нет — создай его по шаблону аналогичного сервиса (см. 03-Services/User Service/ как эталон).

Для фронт-спек — то же, шаблон смотри в 09-Frontend Specs/Админка Франшизы/Каталог — Товары.md.

Фаза 4. Сводный отчёт

Выведи итоговую таблицу:

Сервис / Фронт	Добавлено	Обновлено	Помечено deprecated	Создано новых файлов
User Service	3 эндпоинта, 1 событие	2 файла	1 эндпоинт	0
…	…	…	…	…

И список открытых вопросов (если в коде что-то нашёл, но не понял к какой BR относится — выведи отдельным списком, не выдумывай).

4. Правила и ограничения

• Не трогай код в репозиториях — только чтение. Все правки — только в obsidian_erp/.
• Не удаляй информацию из vault. Устаревшее помечай deprecated / status: removed, а не стирай — нужна история.
• Сохраняй frontmatter, [[wikilinks]], Mermaid, callouts (> [!note], > [!important]).
• Не выдумывай контракты, которых нет в коде. Если эндпоинт описан в vault, но в коде его нет — пометь deprecated с заметкой «не найдено в коде на 2026-05-13».
• Источник правды для API — код, не Swagger. Если Swagger расходится с контроллером — верь контроллеру.
• Ролевая модель: для каждого эндпоинта в API.md укажи permission (например users.read), не enum-роль — enum роли удалён в BR 1.4.4 (05-Business/Roles.md).
• Не запускай update-docs скилл на каждом шаге — это разовый промт, который делает работу одним проходом сам.
• Не коммить изменения автоматически. По окончании — выведи список изменённых файлов; коммитить буду я вручную через /push-all.
• erp-pos — заморожен, пропустить. erp-openclaw-agent — superseded (ADR-022 rev 2), пропустить. erp-llm-gateway — отказан 2026-05-13, физически удалить (если ещё лежит локально — игнорировать).

5. Если что-то непонятно

• Если у сервиса в коде есть эндпоинт, но не ясно к какой BR он относится — добавь в API.md без ссылки на BR, и упомяни в финальном списке открытых вопросов.
• Если расходится модель ролей (например в коде @PreAuthorize("hasRole('CASHIER')") — это старый enum) — добавь в открытые вопросы, не переписывай код-логику в спеке.
• Если репо не существует локально (Repositories.md его упоминает, но ../<repo> отсутствует) — пометь в отчёте «репо отсутствует локально», пропусти.

Начинай с чтения 07-Tasks/Repositories.md и CLAUDE.md.

=PROMPT=

---

Как использовать

1. Открыть Claude Code в директории obsidian_erp/
2. Скопировать всё, что между ===PROMPT=== маркерами
3. Вставить как первое сообщение
4. Claude сам делегирует sub-agent’ам инвентаризацию и обновит vault
5. По окончании — посмотреть отчёт, проверить git diff, закоммитить вручную (/push-all)