Palizh — B2B-платформа (проект)

Документация и аналитика проекта запуска оптовой платформы palizh.com (репозиторий аналитики) отделена от репозитория разработки.

Где что хранится

Репозиторий	URL / remote	Что это
Аналитика (этот репозиторий)	github.com/1dotblack/palizh-analytics • origin	ЧТЗ, Инфарх, понимание задачи, интервью, продуктовые OpenAPI (openapi_client_mvp.yaml, openapi_1c_inbound_mvp.yaml, объединённые и post-MVP: openapi_mvp_merged.yaml, openapi_mvp_post_mvp.yaml), копии интеграционных файлов из GitLab (синхронизировать после правок там)
Разработка (код)	gitlab.com/nutnet/palizh • remote gitlab в локальной копии	Laravel backend, SPA frontend, Docker, CI; канон текстов: docs/public-http-openapi.yaml, docs/1c-http-openapi.yaml, docs/incoming-hooks.md; реализация публичного API — Laravel Sanctum (SPA + cookie/CSRF, при необходимости Bearer token), см. Техстек_общий.md

После git fetch gitlab имеет смысл приводить три артефакта из этого репо в соответствие с GitLab: Техническая часть/public-http-openapi.yaml, Техническая часть/1c-http-openapi.yaml + входящие/1c-http-openapi.yaml, входящие/incoming-hooks.md.

Структура папок

Папка	Назначение
ЧТЗ	Технические задания (один файл на блок). В корне — Оглавление.md со списком ЧТЗ и ссылками
Понимание задачи	Текущее понимание в Понимание_задачи.md; обновляется по ходу проекта. В архив/ — стартовая версия для истории
Интервью и встречи	В Саммари/ — обработанные интервью (саммари и итоги); в корне — списки тем, реестры, справочные материалы. В План Интервью/ — планы и структуры интервью. В папке транскриптов (Транскрайб) — сырые расшифровки; обрабатывает субагент @agent-transcript. Запись интервью/ (видео/аудио) в Git не входит — см. .gitignore; файлы держите локально или в облаке
USCases	uscases/README.md — роли, сквозные MVP-сценарии, потоки для дизайна; при смене ЧТЗ/Инфарх обновляйте связанные сценарии
входящие/	Материалы по 1С → платформа (incoming-hooks.md), при необходимости дубль 1c-http-openapi.yaml; сводка путей — OpenAPI_индекс.md
План проекта	План по ролям, этапам и срокам (Гант, вехи)
Инфарх	Информационная архитектура сайта (структура страниц, Mermaid-диаграммы). В папке: диаграмма структуры, структура страниц — дерево и зоны, видение и границы, состав и задачи страниц, обучение и образовательные активности
Примеры документов/	PDF/DOCX и др. образцы для проектирования выдачи в ЛК — только локально, не в Git; перечень в Реестр документов для проектирования
Техническая часть	Техническая архитектура и техстек (Laravel + Vue 3 / Nuxt 4 + PostgreSQL + Redis; публичный API в коде — Sanctum, см. Техстек, Backend): Архитектура платформы, Frontend, Мобильное приложение — сравнение подходов, Интеграция с 1С, 1С Contract Matrix, Order Lifecycle Contract, Document Delivery Contract, Admin Role And Routing Matrix, OpenAPI MVP: Auth And Onboarding, OpenAPI MVP: Catalog And Product, OpenAPI MVP: Cart Checkout Orders, OpenAPI: индекс спецификаций: канон разработки (из GitLab docs/): public-http-openapi.yaml, 1c-http-openapi.yaml + входящие/incoming-hooks.md — в аналитике копии; продуктовые: openapi_client_mvp.yaml, openapi_1c_inbound_mvp.yaml, openapi_mvp_merged.yaml, openapi_mvp_post_mvp.yaml — Форма претензии: UI/API и др. Текущие базовые принципы: 1С — источник для ЛК-документов и статусов заказа; в ЛК используется единая шкала из 6 статусов заказа, а доставка раскрывается через детали заказа.

Уточнение описания и дальнейшая проработка:

Артефакт	Назначение
Реестр открытых вопросов	Сводный список открытых вопросов по ЧТЗ для планирования интервью и чатов с клиентом
Реестр документов для проектирования	Список документов, образцы которых нужно собрать от заказчика для проектирования обмена с 1С и отображения в ЛК (связь с ЧТЗ 02, 05, 09)
Карта заинтересованных сторон	Роли и контакты; с кем уточнять темы для интервью
Вопросы клиенту по процессу заказа	Детальные вопросы по процессу заказа (после интервью 1)
План интервью: блоки и даты	Какие блоки обсуждать, с кем, связь с ЧТЗ
Матрица статусов и источников	Сводная таблица по объектам, статусам и источникам данных (1С, платформа, ТК)
Сводка по онбордингу и идентификаторам	Поток онбординга, GUID заявки, флаг активности в 1С, связь с учётными записями в ЛК

Отдельно технические артефакты (для подготовки к реализации и согласования со службой ИТ заказчика) лежат в папке Техническая часть/.

Агенты и правила

• Основной агент-аналитик: .cursor/rules/project-analyst.mdc — описывает структуру папок, правила обновления ЧТЗ/Инфарх/плана интервью и общий контекст проекта.
• Агент по транскриптам: .cursor/rules/agent-transcript.mdc — отвечает за обработку интервью (Транскрайб → Саммари) и обновление связанных документов.
• Агент-дизайнер: .cursor/rules/agent-designer.mdc — анализирует инфарх и макеты Figma, даёт рекомендации по структуре и интерфейсам.
• Агент-аудитор: .cursor/rules/agent-auditor.mdc — проверяет целостность и согласованность ЧТЗ, техчасти, инфарха и реестров, формирует отчёты-аудиты.

При изменении структуры проекта, техстека или правил работы агентов нужно обновлять как соответствующие .cursor/rules/*.mdc, так и этот README.md, чтобы сохранять полный контекст для передачи проекта.

Удалённый репозиторий в облаке (основной)

Обычный основной remote — origin на хостинге (GitHub, GitLab, Bitbucket и т.д.): от него клонируют, на него пушат, открывают pull/merge request.

Текущий репозиторий проекта: github.com/1dotblack/palizh-analytics (git clone https://github.com/1dotblack/palizh-analytics.git). В локальной копии для origin может быть задан pushurl на SSH (git@github.com:1dotblack/palizh-analytics.git), чтобы push шёл по ключу.

Командная копия на GitLab (Nutnet) — документацию и код удобно смотреть в веб‑интерфейсе и вести merge request оттуда: gitlab.com/nutnet/palizh. В этой локальной рабочей копии для GitLab добавлен второй remote с именем gitlab (https://gitlab.com/nutnet/palizh.git). Просмотр файлов без клона — через Repository → файлы или ветку в UI.

Подключить gitlab, если делаете с нуля:

git remote add gitlab https://gitlab.com/nutnet/palizh.git
# предпочтительно для постоянной работы — SSH (нужен ключ в GitLab):
# git remote set-url gitlab git@gitlab.com:nutnet/palizh.git

Подтянуть или отправить изменения на GitLab:

git fetch gitlab
git pull gitlab main          # если основная ветка называется main
git push gitlab main          # отправить вашу локальную main на GitLab

Имена веток (main, master) проверьте в веб‑интерфейсе проекта GitLab после первого fetch. Если история GitLab уже расходится с GitHub‑origin, перед первым push имеет смысл спланировать объединение (merge/rebase или единственный канонический remote — по договорённости команды).

Подключить облако к уже существующей копии с историей:

1. Создайте пустой репозиторий на хостинге (без README/LICENSE, если не хотите ручной разбор первого коммита).
2. Добавьте origin и отправьте ветки (подставьте свой URL — SSH или HTTPS):

git remote add origin git@github.com:<организация>/<репозиторий>.git
# или: git remote add origin https://github.com/<организация>/<репозиторий>.git

git push -u origin main
git push -u origin --all    # опционально: все локальные ветки
git push -u origin --tags   # опционально: теги

3. Дальше: git pull / git push как обычно. В этой копии включено push.autoSetupRemote для новых веток.

Pull requests в режиме draft на GitHub — через веб-интерфейс или gh pr create --draft после gh auth login.

---

Локальный bare (резерв, remote bare)

Раньше в качестве «удалённого» использовался голый репозиторий на диске — история и ветки дублируются локально. В текущей рабочей копии он переименован в remote bare (пример пути: /Users/alexandermireshkin/Documents/GitHub/Palizh.git), чтобы освободить имя origin под облако.

Что	Значение
origin	Основной URL GitHub после шагов выше (git remote -v)
gitlab	Репозиторий команды nutnet/palizh для fetch/push и просмотра документации в GitLab
bare	Опционально: локальный путь к .git bare-каталогу для резервного git push bare <ветка>

Клон с другой машины: предпочтительно git clone <url-облака>. Клон из bare — только если есть доступ к тому же диску: git clone /путь/к/Palizh.git.

Документация ↔ код на GitLab (nutnet/palizh)

Канон для файлов под gitlab/.../docs/: текст правят в GitLab и копируют в аналитику (Техническая часть/, входящие/) после git fetch gitlab:

• docs/public-http-openapi.yaml → Техническая часть/public-http-openapi.yaml
• docs/1c-http-openapi.yaml → Техническая часть/1c-http-openapi.yaml и входящие/1c-http-openapi.yaml (должны совпадать)
• docs/incoming-hooks.md → входящие/incoming-hooks.md

На своей машине после git fetch gitlab имеет смысл:

Шаг	Действие
1	Сверить указанные копии с gitlab/main (или целевая ветка): git show gitlab/main:docs/....
2	public-http-openapi.yaml ↔ модуль backend/app/Modules/Api/ на стенде (спека может описывать API раньше, чем добавлены все Route).
3	incoming-hooks.md и openapi_1c_inbound_mvp.yaml ↔ backend/app/Modules/Exchange/ (POST …/exchange/, код ответа успеха 202, обработчики событий).
4	Переменные окружения (без секретов), CI/CD, ADR — см. Инфраструктура_и_CI-CD.md.

Продуктовые спеки в аналитике (openapi_client_mvp.yaml и объединённые артефакты) нужно выравнивать с каноном стенда (public-http-openapi.yaml) по решению продукта, но не заменять одну другой без явного решения — см. OpenAPI_индекс.md.

Проверки на ошибки: две копии 1c-http-openapi.yaml обязаны совпадать; в incoming-hooks.md строки вида // в блоках примеров не являются JSON и не использовать как копипасту без правки; комментарии в примерах JSON — по правилам в самом документе; связка Ensi ↔ Глоссарий; имя Транскрайб в путях; merge_openapi_mvp.rb не трогает public-http и 1c-http — только ручное копирование из GitLab.

---

Работа в Cursor на другом компьютере

1. Синхронизируй папку проекта: git clone с URL облачного репозитория (или копия с носителя) — в ней должны быть все документы и папка .cursor/rules/.
2. Открой папку проекта в Cursor (File → Open Folder).
3. Правила подхватятся автоматически: основной контекст — правило «Аналитик проекта» (project-analyst.mdc). Для обработки транскриптов открой файл в папке Транскрайб или в чате вызови правило @agent-transcript.
4. При изменении структуры папок или процессов предложи и внеси правки в .cursor/rules/, чтобы контекст оставался актуальным.