Spec-Driven Development (SDD) — Design Document

Problem

• API-контракт между фронтом и бэком описан в разрозненных markdown-файлах
• Zod-схемы на фронте живут отдельно от бэкенда — нет единого источника правды
• Нет автоматической валидации соответствия кода спецификации
• Документация (ADR, гайды, UI, help) разбросана по разным репозиториям

Solution

Единый documentation hub в отдельном репозитории partizap-docs/ с OpenAPI spec как источником правды для API и VitePress как платформой для всей документации.

Architecture

Repository

• URL: https://gitlab.partizap.ru/root/partizap-docs
• Локально: partizap/dev/partizap-docs/ (рядом с backend, frontend, nginx)

Structure

partizap-docs/
├── specs/
│   └── openapi.yaml                 # OpenAPI 3.1 — единый контракт API
├── docs/
│   ├── api/                         # API reference (рендерится из openapi.yaml)
│   ├── dev/                         # Внутренняя dev-документация
│   │   ├── adr/                     # Architecture Decision Records
│   │   ├── architecture.md
│   │   └── runbook.md
│   ├── guides/                      # Гайды для партнёров / интеграторов
│   ├── help/                        # Продуктовая документация (FAQ, инструкции)
│   └── ui/                          # UI-документация
│       ├── components/              # Описание компонентов (props, usage, примеры)
│       ├── design-tokens.md         # Цвета, типографика, spacing
│       ├── layouts.md               # Лейауты и паттерны
│       └── patterns.md              # UX-паттерны (формы, фильтры, модалки)
├── .vitepress/
│   └── config.ts                    # Навигация, sidebar, плагины
├── package.json
└── .gitlab-ci.yml

Tech Stack

Component	Tool	Reason
Doc site	VitePress	Vue-экосистема (как фронт), лёгкий, markdown
API docs	vitepress-openapi	Рендерит OpenAPI прямо в VitePress
Spec linting	@redocly/cli	Валидация openapi.yaml в CI
Deploy	Статика на nginx	Уже есть инфра, zero cost

SDD Workflow

Принцип

Спеку всегда предлагает бэкенд. Фронтенд — потребитель.

Если фронтендеру нужен новый эндпоинт — он создаёт задачу бэкендеру, а не правит спеку сам.

Scenario A: Backend — новый/изменённый API

Рабочие директории: partizap-backend/ + partizap-docs/

1. Описываешь фичу словами
2. Claude обновляет partizap-docs/specs/openapi.yaml
3. Ты ревьюишь diff в openapi.yaml
4. Claude реализует эндпоинт в partizap-backend/
   ├─ Action класс
   ├─ route в routes.php
   └─ тесты
5. Коммит в оба репозитория

Scenario B: Frontend — реализация по спеке

Рабочие директории: partizap-frontend/ + partizap-docs/

1. Фронтендер читает обновлённый openapi.yaml
2. Claude реализует клиентскую часть в partizap-frontend/
   ├─ Zod-схема (если новые типы)
   ├─ API-вызов в entity/feature
   └─ UI-компонент
3. При необходимости обновляет partizap-docs/docs/ui/

Scenario C: Frontend — чисто UI задача (без API)

Рабочие директории: partizap-frontend/ + partizap-docs/

1. Claude обновляет partizap-docs/docs/ui/ (описание компонента)
2. Claude реализует в partizap-frontend/

Summary Table

Тип изменения	Кто правит спеку	Репозитории	SDD?
Новый эндпоинт	Бэкендер	docs + backend	Да
Изменение ответа API	Бэкендер	docs + backend	Да
Новый UI-компонент	—	docs (ui/) + frontend	Нет
Смена дизайна/layout	—	docs (ui/) + frontend	Нет
Новое поле в форме, уходящее в API	Бэкендер	docs + backend → frontend	Да
Рефакторинг фронт-кода	—	frontend only	Нет
Продуктовый гайд / FAQ	—	docs (help/) only	Нет

CLAUDE.md Integration

В CLAUDE.md бэкенда добавить:

## API Spec (SDD)
- Единый источник правды: ../partizap-docs/specs/openapi.yaml
- Перед созданием/изменением API — сначала обнови спеку в partizap-docs
- После изменения спеки — коммит в partizap-docs

В CLAUDE.md фронта добавить:

## API Spec (SDD)
- Единый источник правды: ../partizap-docs/specs/openapi.yaml
- Читай спеку перед реализацией API-вызовов
- Не правь openapi.yaml — это ответственность бэкенда
- При изменении UI-компонентов — обновляй ../partizap-docs/docs/ui/

Deploy

CI/CD (partizap-docs/.gitlab-ci.yml)

stages:
  - lint
  - build
  - deploy

lint:spec:
  stage: lint
  script:
    - npx @redocly/cli lint specs/openapi.yaml

build:docs:
  stage: build
  script:
    - npm ci && npm run build
  artifacts:
    paths: [.vitepress/dist]

deploy:docs:
  stage: deploy
  script:
    - scp -r .vitepress/dist/* server:/var/www/docs/
  only: [main]

Nginx

В https://gitlab.partizap.ru/d_vyaznikov/nginx добавить server block:

server {
    server_name docs.partizap.ru;
    root /var/www/docs;

    location / {
        # Пока за cookie-auth (как dev.partizap.ru)
        # Потом: /help/ и /api/ — публичные, /dev/ — за auth
        try_files $uri $uri/ /index.html;
    }
}

Access Control (future)

• Сейчас: всё за nginx cookie-auth
• Потом: публичные секции (/help/, /api/, /guides/) открыты, /dev/ за auth

Code Generation (hybrid approach)

What	How	When
TypeScript types	openapi-typescript (auto)	CI или pre-commit hook
Zod schemas	Claude вручную по спеке	При реализации фичи на фронте
API client calls	Claude вручную по спеке	При реализации фичи на фронте
Backend Action code	Claude вручную по спеке	При реализации фичи на бэке

Автогенерация TypeScript типов гарантирует соответствие спеке. Zod-схемы и бизнес-логика — Claude, т.к. требуют контекст.

Migration Plan

1. Создать репозиторий https://gitlab.partizap.ru/root/partizap-docs
2. Инициализировать VitePress + vitepress-openapi
3. Написать первичный openapi.yaml по существующим 99 эндпоинтам (можно итеративно)
4. Перенести ADR из partizap-backend/approved/partizap_ADR/ → docs/dev/adr/
5. Перенести RUNBOOK из dev/docs/RUNBOOK.md → docs/dev/runbook.md
6. Настроить CI/CD + nginx server block
7. Обновить CLAUDE.md в обоих репозиториях
8. Начать работать по SDD-workflow