diff --git a/README.md b/README.md index 2f3e452..c08ef39 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ - **[format-html](./format-html/SKILL.md)** — форматирование и исправление сырой HTML-разметки (отступы в 4 пробела, выравнивание структуры, закрытие тегов). - **[html-to-scss](./html-to-scss/SKILL.md)** — генерация структуры SCSS по методологии БЭМ на основе переданной HTML-разметки. +- **[backend-integration-guide](./backend-integration-guide/SKILL.md)** — генерация краткой инструкции по интеграции вёрстки для бэкенда/CMS по git-коммиту. ## Установка diff --git a/backend-integration-guide/SKILL.md b/backend-integration-guide/SKILL.md new file mode 100644 index 0000000..3fbcab0 --- /dev/null +++ b/backend-integration-guide/SKILL.md @@ -0,0 +1,145 @@ +--- +name: backend-integration-guide +description: Generate a concise backend integration guide from a git commit, range, or branch (defaults to the latest commit when none is given). Use when the user asks for integration instructions for backend/CMS developers. Outputs a Russian plain-text guide in chat. +license: MIT +metadata: + author: Valentin Silyutin + version: "1.0.0" +--- + +# Backend Integration Guide Generation Instructions + +Analyze the changes of a git commit (or range/branch; with no input, the latest commit) and produce **a short Russian guide for the backend/CMS developer**, describing what changed in the markup and data that matters to them. + +## Output Rules + +- **Language:** the whole guide is written in **Russian**. Only code, paths, selectors, commands and API identifiers stay as-is. +- **Plain text, no markup:** print the guide as plain text without any Markdown formatting — no `#` headings, no `**bold**`, no backtick fences. Section titles are plain lines, list items start with `- `, JSON is shown with indentation. The output is pasted into a Planfix visual editor that does not parse Markdown or HTML. +- **Plain human Russian:** write simple, natural sentences. Describe the action in words, not with arrows or jargon. Say «в блок `.catalog-list` добавить класс `.catalog-list_category`», not «`.catalog-list → .catalog-list_category`». Avoid канцелярит («точки монтирования», «статичная разметка»): use «компоненты», «разметка фильтра» и т. п. +- **Do not list nested content.** If a block is added or removed as a whole, its inner elements and nested blocks are obvious — do not enumerate them. +- **Destination:** print the guide **in the chat only**. Do **not** create or modify any files. +- **Concise:** one line per meaningful change. Do not retell the diff. +- **Report changes only:** never write about what stayed the same — unchanged pages, sections, assets or fields are simply not mentioned. +- **Never invent:** only mention classes, fields, requests, assets and variables that actually appear in the analyzed changes. If something is absent, do not mention it. + +## 1. Determine the Range + +Resolve the input into a `BASE` and `TARGET` revision: + +- **No argument**: `BASE=HEAD^`, `TARGET=HEAD` (the latest commit). +- **Single hash ``**: `BASE=^`, `TARGET=`. +- **Range `..`**: `BASE=`, `TARGET=`. +- **Branch ``** (including `origin/`): `BASE=$(git merge-base HEAD )`, `TARGET=`. + +Get the task number and title from the commit subject (format `#<номер задачи> <описание>`): + +``` +git log -1 --format=%s +``` + +## 2. What Changed + +Only `src/**` and `html/**` carry integration-relevant changes. Ignore: + +- `www/**` — the build output, not tracked in git; never treat it as the markup source (that is `html/**`). +- `*_index.scss`, `*_index.js`, `src/scripts/mocks/handlers/_index.js`. +- The preview sitemap page listing links to all preview pages ("Карта сайта"), if the project has one; it is not part of the CMS integration. Do not confuse it with a regular `index` page. +- Formatting-only changes with no semantic difference. + +Detect each category independently: + +### HTML markup — source of truth is `html/**`, NOT `src/templates/**` + +The folder `html/` contains the built HTML used precisely to see markup changes. `src/templates/**` (Nunjucks) may change while the resulting HTML stays the same. + +Use whitespace-insensitive diff to drop indentation noise: + +``` +git diff -w --ignore-blank-lines BASE TARGET -- html/ +``` + +- If `html/**` has real changes → list them per page under **«Изменения по HTML»**. +- Otherwise → omit the markup section entirely. + +When describing a changed HTML page (any `html/**/*.html`, including fragments such as `header/`, `footer/`, `layout/`): +- new / changed / removed blocks and elements — by BEM class, as a plain sentence; +- new states (modifiers), new target pages; +- **ignore plain URL values** (`href`, `data-infinite`, `data-request`, etc.): the backend uses its own addresses, so do not report them. + +### Initial page state — `src/json/**` and template globals + +Data that must already be on the page at load time — a global object emitted by a template and read by JS (`window.*`, `STATE_*`, etc.). + +`src/json/**` files are fixtures: at build time they only become Nunjucks variables used to generate HTML. If such data is used **only to render HTML in Nunjucks**, do not report it. + +Report data only when it reaches the JS/Vue layer, because that is the backend contract: + +- a global object emitted by a template and read by JS (`window.*`, `STATE_*`, etc.); +- a direct import of JSON into the code. + +Search for such globals directly in the templates (e.g. `STATE_FILTER` in `_catalog.njk`), **even when `src/json/**` did not change**. + +Show the expected structure as a **raw JSON example**, not as a prose field list. + +### AJAX requests — `src/scripts/**` + +Only report a change here when the **data exchange contract with the backend changed**. Determine that contract from whatever the project uses, and show its structure as a **raw JSON example**: + +- a shared request helper (`src/scripts/utils/request.js` or a similarly named module) — reference it and list its response formats; +- mocks (`src/scripts/mocks/**`) — use them as the request/response contract, but note that they are **dev-only** (never loaded in production, see `src/scripts/main.js`) and do **not** require a JS rebuild; +- an explicit `fetch`/`axios` call. + +- Do not describe internal JS logic, refactors, stores, components or composables — the backend only needs to know whether JS changed (see «Пересобрать JS» in the build list). +- **Do not report URLs, HTTP methods or header values** — the backend sets them. At most, mention that the update is an AJAX request and that extra headers can be passed if such an option exists. + +### Assets — `src/images/**`, `src/fonts/**`, `src/videos/**` + +- new icons in `src/images/required/icons/**` (SVG sprite); +- new design images in `src/images/required/**`, content images in `src/images/examples/**`, fonts and videos — list the new files; +- lazy-loading requirements (`loading="lazy"`, `.lazyload` + `data-background`). + +## 3. Build List + +Derive the build list from which source folders changed. Emit only relevant items, as a plain list (no todo checkboxes): + +- `src/styles/**` `*.scss` changed → **Пересобрать CSS** +- `src/scripts/**` `*.js`/`*.vue` changed **excluding `src/scripts/mocks/**`** → **Пересобрать JS** +- `src/images/required/icons/**` changed → **Пересобрать иконки** + +The backend rebuilds assets with `yarn build` and copies the result to their side. + +## 4. Output Template + +Plain-text layout, no Markdown. No title line; the guide starts with the first section. + +``` +Сборка +- Пересобрать CSS +- Пересобрать JS +- Пересобрать иконки + +Изменения по HTML +catalog.html +- <что изменилось: блоки, классы, структура> + +Данные при загрузке страницы + + +AJAX-запросы + + +Ассеты +- <новые иконки / изображения / шрифты / видео> +``` + +- Emit a section only if it has content; sections without changes are omitted entirely (including «Ассеты», when there are no new files). +- If no integration is needed at all (only internal refactor works with no markup/data change), output a single line: `Интеграция не требуется — <короткая причина>`. + +## 5. Workflow + +1. Parse the input (hash / range / branch; if nothing is given — the latest commit, `BASE=HEAD^`, `TARGET=HEAD`) and resolve `BASE` and `TARGET`. +2. Read the commit subject for the task number and title. +3. If project conventions are unclear (request helper path, the sitemap page, subfolders in `html/`), consult `AGENTS.md` / `README.md` — every project has them. +4. Run the whitespace-insensitive diff for `html/**` and the diff for `src/**`. +5. Categorize the changes into: HTML, initial page state, AJAX requests contract, assets, build steps. +6. Print the Russian plain-text guide in chat using the template above.