---
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 `<hash>`**: `BASE=<hash>^`, `TARGET=<hash>`.
- **Range `<from>..<to>`**: `BASE=<from>`, `TARGET=<to>`.
- **Branch `<branch>`** (including `origin/<branch>`): `BASE=$(git merge-base HEAD <branch>)`, `TARGET=<branch>`.

Get the task number and title from the commit subject (format `#<номер задачи> <описание>`):

```
git log -1 --format=%s <TARGET>
```

## 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
- <что изменилось: блоки, классы, структура>

Данные при загрузке страницы
<JSON-пример структуры>

AJAX-запросы
<JSON-пример контракта ответа, если он изменился>

Ассеты
- <новые иконки / изображения / шрифты / видео>
```

- 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.