# A3 Integration-Tooling — дизайн интеграции

**Дата:** 2026-05-17
**Раздел карты:** A3 «Программирование — интеграции (API, вебхуки)»
**Параллель:** A6 architecture-tooling (17.05.2026), D3 audit-security (17.05.2026)
**Ветка:** `feat/a3-integration-tooling` (rebased на origin/main `1313d89`, CLAUDE.md v2.8)

## 1. Проблема

Раздел A3 карты `docs/automation-graph.html` пуст — 0 узлов в `NODE_SECTION`
(строки 1868-1911, ни одного значения `'A3'`). Интеграционная работа физически
идёт — REST-эндпоинты (deals/lookup/billing/admin), webhook-приём
(HMAC + per-token rate-limit), ~5 внешних API (Unisender Go / Yandex Cloud /
Yandex 360 / JivoSite / Sentry) — но инструментами разделов A1/A5/A7/A8/E7.
Ни один инструмент не классифицирован как A3. Состояние — как у A6 до 17.05.
(строки 1868-1911 в оригинальном форке — после ребейза локализовать Grep'ом по `'A3'` в `NODE_SECTION`).

## 2. Цель и scope

Наполнить раздел A3 карты — параллельно A6/D3.

**Scope = формализация инструментов**, не их применение. A6-прецедент: поставил
adr-kit, но не аудировал весь код; создал ADR-000/001/002 + одну C4-диаграмму как
smoke.

**Вне scope:** полная OpenAPI-спека REST API проекта; рефактор webhook-кода;
mock-инфраструктура внешних API в тестах (Microcks отклонён — требует
Docker/JVM+Mongo, несовместим с native-Windows-no-Docker стеком проекта).

## 3. Состав узлов A3 (7)

### 3.1. Новые узлы карты (2)

| Узел (id карты) | Что | Установка | Tooling-реестр |
|---|---|---|---|
| **api-docs agent** (`ag_apidocs`, claude-flow) | генерация OpenAPI-спеки REST API, pattern learning | 0 — агент уже доступен в сессии | **нет номера** — claude-flow sub-агент; реестр Прил. Н — plugin-grain (как 11 уже существующих agent-узлов карты, ни один не имеет Tooling-номера) |
| **openapi-mcp-server** (`mcp_openapi`, npm, stdio MCP) | отдаёт OpenAPI-спеку как MCP-ресурс/тулы; introspection своей и чужих API | `npm i` + запись в `.mcp.json` | **#47**, Tooling §4.22 |

### 3.2. Кросс-реф вторичным тегом A3 (5 — первично остаются в своих разделах)

| Узел | Первичный раздел | Роль в A3 |
|---|---|---|
| `context7` | E7 | актуальная дока внешних API при интеграции |
| `mcp_boost` / Boost #10 | A1 | серверные REST-эндпоинты, HTTP-клиент, Sanctum-auth |
| `ag_pest` / Pest 4 #18 | A5 | contract/integration-тесты эндпоинтов и вебхук-приёма |
| `mcp_semgrep` / Semgrep #25 | A8 | безопасность интеграций (hardcoded webhook URL, API-key leak) |
| `mcp_sentry` / Sentry MCP #34 | A7 | runtime-ошибки вебхук-хендлеров и внешних вызовов |

## 4. Правка модели карты (`docs/automation-graph.html`)

Развилка: `NODE_SECTION` строго 1:1 (узел → один раздел), кросс-реф 5
существующих узлов в A3 механически невозможен. Решение — аддитивный слой:

- **Новый объект `NODE_SECTION_SECONDARY`** (`NODE_SECTION` 1:1 не трогается):

  ```js
  const NODE_SECTION_SECONDARY = {
    mcp_boost: ['A3'], context7: ['A3'], ag_pest: ['A3'],
    mcp_semgrep: ['A3'], mcp_sentry: ['A3'],
  };
  ```

- **Цикл `SECTION_NODES`** (строка ~1915): узел добавляется в первичный раздел
  И в каждый раздел из `NODE_SECTION_SECONDARY`.
- **Панель «Разделы»** — узел показывается под всеми своими разделами.
- **Паспорт узла, строка «Раздел»** (`#ld-section`, строка 147): формат
  `A1 (+A3)` для кросс-реф узлов.
- **2 новых объекта `NODES`:** `ag_apidocs` (group `agents`), `mcp_openapi`
  (group `mcp`) + позиционирование `pos()`.
- **`NODE_SECTION`:** `ag_apidocs: 'A3', mcp_openapi: 'A3'` (первичный раздел).
- **`NODE_TIMELINE`:** `ag_apidocs` / `mcp_openapi` — `since: '17.05.2026'`.
- **Рёбра (~2-3):** новые узлы → governing-правила, напр.
  `E('psr_v1', 'mcp_openapi', 'R10.1 блок 3:\nintegration-tooling')`.
- **Счётчики:** 116→118 узлов, +3 ребра. Новых конфликтов не ожидается.

## 5. Нормативка (4 файла — как A6/D3)

| Файл | Правка | Версия |
|---|---|---|
| Tooling Прил. Н | §4.22 (новый) — #47 openapi-mcp-server; §0 счётчик 46→47; 9-я off-phase подкатегория **integration-tooling** | v2.8→v2.9 |
| PSR_v1 | R10.1 Блок 3 (MCP-серверы) +1 строка openapi-mcp; integration-tooling — не UI → вне R6/R14 | v3.8→v3.9 |
| Pravila | §13.2 +абзац «Off-phase integration-tooling» | v1.22→v1.23 |
| CLAUDE.md | §3 title 46→47; §3.3 +строка #47 (+упоминание api-docs agent); §1 row 2b 46→47; §3.3 footer; §0 cross-refs; §6 +абзац A3 | v2.8→v2.9 |

CLAUDE.md — через `/claude-md-management:claude-md-improver` (§5 п.10). Кросс-реф
5 существующих инструментов — **только map-модель**; в нормативный реестр не
попадает (инструменты уже зарегистрированы по своей идентичности).

## 6. Smoke / верификация

- Аудит установки openapi-mcp: точное имя npm-пакета (кандидат
  `ivo-toby/mcp-openapi-server`), native-Windows совместимость, stdio-режим
  (без port-conflict), кириллица в пути (квирк #26).
- Smoke: openapi-mcp поднят на тестовой спеке (PONG-эквивалент) + dispatch
  api-docs agent на одну группу эндпоинтов (deals API) → стартовый
  OpenAPI-скелет как proof. Полную спеку не генерируем.
- Регрессия `quick` (lint/format/type-check) перед коммитом нормативки.
- Визуальный smoke карты: открыть `automation-graph.html` — 118 узлов,
  0 JS-ошибок, панель «Разделы» показывает A3 с 7 узлами.
- `git` без bypass хуков.

## 7. Нумерация (риск реализовался — закрыт)

Ветка `feat/a3-integration-tooling` исходно форкнулась от D3-эры (`7c12b74`). За это время в origin/main влиты C9 (#41 CCPM / #42 product-management), deptrac (#43), A4 (#44/#45/#46). Риск из исходной редакции §7 материализовался. Закрыт ребейзом feat/a3 на актуальный origin/main `1313d89`: openapi-mcp-server подтверждён как **#47**, Tooling **§4.22**, integration-tooling — **9-я** off-phase подкатегория. Остаточный риск: если ещё одна интеграция (напр. A11) смёрджится в main раньше A3 — финально сверить счётчик Tooling §0 перед коммитом нормативки (план Task 10 Step 2).

## 8. Ветка и артефакты

- Ветка `feat/a3-integration-tooling` rebased на origin/main `1313d89`.
- Spec: этот файл.
- План: `docs/superpowers/plans/2026-05-17-a3-integration-tooling-integration.md`.
- Merge: `git push origin feat/a3-integration-tooling:main` после D3 (ветка A3
  содержит D3-коммиты как предков — корректный порядок merge).
