START HERE — что искать, что читать, что править
Для ИИ-агента, которого запустил сотрудник. Прочитать целиком до первой правки. Жёсткие правила проекта — в AGENTS.md, они главнее этого файла. Иерархия системы описана в docs/README.md, раздел «Система сверху вниз»: стратегический → функциональный → описательный. Здесь — маршрут: куда идти за ответом и куда класть изменения.
0. ПЕРВЫМ ДЕЛОМ — проверить сообщения из Телеграма
Ты не видишь Телеграм. Но каждое сообщение системе, которое уходит владельцу, пишется строкой в журнал на S3. В начале каждой сессии читай его:
ssh s3-int tail -30 /var/log/gwptd-telegram-sent.log
Это последние 30 сообщений: что система сообщала владельцу. Там протухшие сборы,
упавшие сервисы, расхождения s2↔s3. Формат: дата [хост] OK/FAIL текст.
Журнал пуст → «пуст». Но НЕ пропускай: сбор однажды стоял двое суток, владелец знал, а агент нет — потому что не посмотрел.
С 2026-07-29 идёт пробный период: над кодом работают несколько человек и их
агенты. Точка отсечки — тег trial-start-2026-07-29. Всё, что появилось после
неё, видно так:
git log --oneline trial-start-2026-07-29..HEAD
git diff --stat trial-start-2026-07-29..HEAD
1. Порядок поиска — три источника, именно в этом порядке
- Память —
mcp__vestige-s3__search(на рабочей машине владельца ещё иmcp__vestige__search). Там состояние контуров, принятые решения и корни багов прошлых сессий. Половина задач уже разобрана — не начинай с нуля. - Код через индекс —
mcp__mcp-gwptd__rag_search. Индекс привязан к SHA;mcp__mcp-gwptd__repo_statusпокажет живой SHA на S3 и отставание индекса. Не гадать по памяти о содержимом файла — смотреть код. - Файлы — обычное чтение, когда уже знаешь путь.
Не нашёл в первых двух — спроси владельца, прежде чем искать в интернете.
Нашёл важное (решение, корень бага, неочевидный факт) — сразу сохрани через
mcp__vestige-s3__smart_ingest. Контекст сессии обрезается, память нет.
2. Два контура — сначала пойми, в каком ты
Читать docs/ui/TWO-STACKS.md — это первое, если задача про маршруты, вход, пользователей или сбор данных.
| Прежний контур | Новейший контур | |
|---|---|---|
| Адрес | mp.hyp.ru/admin | mp.hyp.ru/new и next.mp.hyp.ru |
| Сервер | S2 | S3 |
| Ветка | master | next/spec-platform ← работаем здесь |
| Данные | legacy-база напрямую | gwptd_kernel через Data API |
| Статус | заморожен, держим для сверки | целевой |
Почти вся работа — в next/spec-platform. Прежний контур не развиваем и не
«чиним»: он эталон чисел на время обкатки.
⛔ Ветки не сливать. В next удалено 12 blade-шаблонов страниц старого
/new — раскатка next на S2 сломает прежний интерфейс. Слияние возможно
только после вывода прежнего контура из эксплуатации.
3. Куда класть изменения — по типу задачи
| Задача | Где править | Чем проверить |
|---|---|---|
| Страница, колонки, фильтры, меню нового интерфейса | specs/pages/*.yaml, specs/grids/*.yaml; общее дерево меню — app/Services/SpecPlatform/PrimaryNavigationCatalog.php | php vendor/phpunit/phpunit/phpunit tests/Feature/Filament |
| Экран, которому не хватает универсального движка | app/Filament/Pages/*ApiPage.php | тот же |
| Новый показатель/отчёт из kernel | data_api/routers/reports/… | python3 -m pytest data_api/tests |
| Новый endpoint маркетплейса | specs/products/<mp>.<endpoint>.yaml, движок marketplace-collector-v3/spec_runtime/ | python3 -m pytest marketplace-collector-v3/tests |
| Бизнес-расчёт (рейтинг, оборачиваемость, отгрузка) | marketplace-collector-v3/kernel/etl/build_*.py | тесты в marketplace-collector-v3/tests |
| Логика отгрузки в интерфейсе | app/Filament/Pages/ShipmentCalcApiPage.php, data_api/routers/reports/shipment/ | data_api/tests/test_shipment_* |
| Доступы, роли | app/Models/User.php, app/Services/Access/ | tests/Feature/BusinessAccessTest.php |
Формулы не менять, не прочитав docs/domain/ — там
DO-NOT-REGRESS.md (решения, которые выглядят как баг, но приняты сознательно)
и STATUS-SEMANTICS.md. Код — реализация правил, канон живёт там.
Ключевое из канона: оценка модели считается только от реальных продаж — выкуплено минус возвраты. Заказы, спрос и корзины в числитель не идут. Никогда не переводить рейтинг/оборачиваемость на заказы.
4. Чего не делать без слова владельца
- S2 (прод) — только чтение. Никаких деплоев, миграций, правок контейнеров, cron и данных. Диагностика и копирование эталонных данных на S3 — можно.
- Деплой S3 — только
ssh s3-int /usr/local/sbin/gwptd-next-deploy --expected-sha <40 hex>. SHA обязан быть полным, 40 символов, и уже запушенным в origin. Обёртка держит блокировку, откат и переиндексацию — ручнойgit pull,docker compose up,bash deploy.sh,artisan migrateих обходят. - Cron не править руками. Источник расписания —
marketplace-collector-v3/scripts/crontab.s3-next.txt. - Секреты не коммитить и не передавать в командной строке или в чате.
- Синхронизация пользователей S2↔S3 не выключена, а обезврежена — не путать.
На s2 каждые 10 минут идёт
sync_users_peer.py … --protect B --apply. Флаг--protect Bне даёт ей писать на s3, и на 03.08 она делает ноль изменений (created/updated/assignments_replaced = 0). Но режим у неё именноapply: расхождение сторон она применит. Флаг--protectне снимать и расписание не трогать без явного решения владельца — раньше эта синхронизация затирала роли.
Сомневаешься — спроси. Здесь дешевле подождать, чем откатывать прод.
5. Как проверять свою работу
# Documentation
python3 scripts/docs/check_doc_links.py
# PHP (каталога vendor/bin здесь нет — вызывать бинарники напрямую)
php vendor/phpunit/phpunit/phpunit tests/Feature/Filament/ИмяТеста.php
php vendor/laravel/pint/builds/pint --dirty # форматирование перед коммитом
# Python
python3 -m pytest data_api/tests -q
python3 -m pytest marketplace-collector-v3/tests -q
python3 scripts/docs/check_doc_links.py — ссылки разрешаются относительно
каталога файла, где стоят; глазом этот класс не проверяется.
Полный набор PHP-тестов красный по причинам, не связанным с текущей работой:
31 ошибка, 14 падений из 240. Это записано как F-94.
Рабочий набор — Filament, 76 зелёных: php vendor/phpunit/phpunit/phpunit tests/Feature/Filament.
Каждое изменение поведения — новым или обновлённым тестом. Тесты из tests/ не
удалять.
6. Грабли, на которые тут наступают
- exFAT. Репозиторий лежит на внешнем диске, macOS плодит рядом файлы
._*, и pytest на них падает с UnicodeDecodeError. Перед каждым прогоном:find . -name '._*' -not -path './vendor/*' -delete - Права после деплоя S3. Часть команд деплоя идёт от root и создаёт в
storage/newфайлы с владельцем root; PHP-FPM работает от uid 82 и получает 500 на каждый запрос. После деплоя проверятьfind /opt/gwptd-analytics/repo/storage/new -uid 0 | wc -l→ не 0, лечитьchown -R 82:gwptd. Профилактика:docker exec -u www-data, не простоdocker exec. - Код запечён в образы. Правка файла на хосте S2/S3 ничего не меняет без пересборки. Исключение — nginx-конфиг, он примонтирован.
- SSH на S2 — пользователь
deploy, не root;/rootнедоступен, бэкапы класть в/home/deploy. - Остатки 1С — всегда последний общий срез
fact_supplier_stock_price. Срез «по каждой модели» для суточного снимка наличия неверен всегда: выбывшие товары подтягивают старый ненулевой снимок и дают фантомный остаток.
7. Запушил — выложи
next/spec-platform — основная ветка, всё сделанное живёт в ней. Но одного
push недостаточно.
Индекс mcp-gwptd привязан к тому, что выложено на S3, а не к тому, что
лежит на GitHub. Смысл этого индекса — давать быструю и точную справку по
коду; отставший индекс отвечает про код, которого на сервере нет, и делает это
уверенно. Это хуже, чем отсутствие индекса.
Поэтому пока checkout отстаёт от origin, переиндексатор отказывается
работать: каждые 15 минут mcp-reindex-auto.service падает и шлёт владельцу
алерт в Telegram. За сутки незакрытого отставания — больше сотни сообщений.
# состояние: нужны in_sync=true, index_stale=false, lag_commits=0
mcp__mcp-gwptd__repo_status
Алерт не глушить и порог не поднимать. Он и есть то, что держит справку честной. Правильная реакция на него — выложить, а не приглушить.
Деплой сам переиндексирует индекс, отдельного действия не нужно.
8. Коммиты
- Ветка
next/spec-platform, коммитить часто и мелко. - Сообщение:
тип(область): что сделанов первой строке, дальше почему — причина ценнее пересказа диффа. Примеры вgit log. - Перед коммитом обновить документацию, если изменилось поведение или структура.
git push --force— только по согласованию.
Куда дальше
| Файл | Когда читать |
|---|---|
| AGENTS.md | всегда первым: правила, границы, что заморожено |
| docs/README.md | вход в документацию и в иерархию: раздел «Система сверху вниз» (стратегический → функциональный → описательный); три рода — порождаемое, канон, архив; от рода зависит, можно ли править руками |
| docs/backend/generated/COLUMN-REGISTRY.md + scripts/docs/generate_column_registry.py | точный список колонок, источников и писателей; читать при проверке схемы и происхождения поля |
| docs/remediation/HANDOFF-2026-08-12-goldapple-i-dobor.md | ЧИТАТЬ ПЕРВЫМ, если работа про Золотое яблоко, рейтинг или добор истории: одно поле держало взаперти весь маркетплейс; три вопроса владельцу с числами; что оказалось НЕ дефектом и что починить нельзя |
| docs/remediation/HANDOFF-2026-08-12-1c-i-priyom.md | ЧИТАТЬ ПЕРВЫМ, если работа про 1С, приём или сторожей: задвоена таблица движений 1С и ждёт решения владельца; семь таблиц — не пустота, а дыра; шесть ошибок сессии с тем, чем каждая ловится |
| docs/remediation/HANDOFF-2026-08-12.md | ЧИТАТЬ ПЕРВЫМ, если работа про остатки, доступы или выкладку: ведёт вторая сессия с тем же именем. ⚠️ Две сессии в одной папке — передачи РАЗВЕДЕНЫ по файлам намеренно, не сливать |
| docs/remediation/HANDOFF-2026-08-10-vecher.md | ЧИТАТЬ ПЕРВЫМ: отгрузки в /new починены и выложены, Wildberries добран после трёх суток тишины; там же почему отгрузки пока достовернее делать в /admin и что осталось открытым |
| docs/remediation/HANDOFF-2026-08-10-noch.md | первым утром 10.08: интерфейс готов и не выложен — одна команда закрывает всё, и она требует решения владельца |
| docs/remediation/HANDOFF-2026-08-10.md | первым в новой сессии: старый интерфейс скрыт и как его вернуть, что видит менеджер, реестр заглушек, разбор потери данных, почему выкладка роняет службу |
| docs/remediation/HANDOFF-2026-08-09.md | первым в новой сессии: разворот блобов приёма в колонки — состояние, чем мерить, три перегородки, почему сторож бывает ложно зелёным, что идёт у роя прямо сейчас |
| docs/remediation/HANDOFF-2026-08-04.md | первым в новой сессии: состояние работ |
| docs/remediation/PLAN-SVEDENIE-2026-08-03.md | что осталось сделать, что ждёт решения владельца, что заблокировано |
| docs/remediation/PLAN-POCHINKI-2026-08-15.md | читать при ЛЮБОЙ тревоге о свежести или V3 collector PARTIAL: что из ночных тревог чинится и с чего начинать, а что не чинится вовсе; у каждой работы «чего НЕ выводить» — там записаны выводы, на которые уже потрачено время |
| docs/remediation/POSTDEPLOY-CHECKLIST.md | девять post-deploy проверок; читать сразу после выкладки на S3 |
| docs/remediation/OWNER-DECISIONS-PENDING.md | 16 незакрытых решений; читать перед действием, требующим выбора владельца |
| docs/domain/DO-NOT-REGRESS.md | до любой правки бизнес-формул |
| docs/domain/METHOD-TABLE-REVIEW.md | порядок проверки таблицы; читать перед исследованием данных или постановкой такой проверки агенту |
| docs/backend/generated/ENDPOINTS-CATALOG.md | что и откуда собирается: 81 файл описаний (свыше 125 адресов API — 27 описаний это обёртки), окна, лимиты |
| scripts/docs/check_doc_links.py | машинная проверка локальных ссылок; читать при изменении Markdown-навигации |
| marketplace-collector-v3/scripts/check_intake_schema_contract.py | проверка ProductSpec против intake-схемы; читать для отдельного DB-зависимого прогона |
| marketplace-collector-v3/tests/test_returns_sign_invariant.py | тест знака возвратов с двумя известными xfail; читать при изменении returns ETL |
| docs/ui/TWO-STACKS.md | маршруты, вход, пользователи, коллекторы |
| docs/ui/README.md | как устроен интерфейс, каталог страниц |
| CLAUDE.md | legacy-слой Laravel, таблицы, инфраструктура |
| README.md | обзор проекта |