Шаблоны документации

Стандарты и шаблоны для создания документации в проекте integ-core.

---

Общие правила

Язык

• Основной язык: Русский
• Код и примеры: Английский (названия переменных, функций)
• Комментарии в коде: Могут быть на русском для пояснений

Форматирование

• Используй --- для разделения крупных секций
• Используй таблицы для справочной информации
• Используй блоки кода с указанием языка: ```typescript
• Используй эмодзи для статусов: ✅ ❌ ⚠️ только в таблицах и чеклистах

Структура файла

# Заголовок

Краткое описание (1-2 предложения).

---

## Секция 1

Контент...

---

## Секция 2

Контент...

---

## Связанные документы

- [Название](./path.md) — описание

Обязательные секции

Каждый документ должен заканчиваться секцией "Связанные документы" со ссылками на релевантные материалы.

---

Шаблон: Документация интеграции

Файл: integrations/{name}/README.md

# {Name} Integration

{Краткое описание интеграции в 1-2 предложения. Какие системы связывает.}

## Что делает интеграция

1. **{Действие 1}** — краткое описание
2. **{Действие 2}** — краткое описание
3. **{Действие 3}** — краткое описание

---

## Быстрый старт

\`\`\`bash
# Локальная разработка
pnpm start {name}

# Деплой
pnpm deploy:dev
\`\`\`

---

## API Endpoints

### POST /webhook/:action

{Описание основного endpoint}

**Параметры:**

| Параметр | Тип    | Обязательный | Описание |
| -------- | ------ | ------------ | -------- |
| `action` | string | Да           | Тип действия |

**Пример:**

\`\`\`bash
curl -X POST https://integ.happ.tools/{name}/webhook/call-originate \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+380991234567"}'
\`\`\`

### {Другие endpoints}

{Описание каждого endpoint по шаблону выше}

---

## Handlers

| Handler | Endpoint | Описание |
| ------- | -------- | -------- |
| `callOriginateHandler` | `POST /webhook/call-originate` | Инициация звонка |
| `callEventsHandler` | `POST /webhook/call-events` | События от VA |
| `agentInitHandler` | `POST /webhook/agent-init` | Контекст для агента |
| `agentPostcallHandler` | `POST /webhook/agent-postcall` | AI анализ + CRM |

---

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

\`\`\`
src/
├── index.ts              # Entry point (createIntegration)
├── types.ts              # TypeScript типы
├── handlers/
│   ├── index.ts          # Barrel export
│   ├── call-originate.ts
│   ├── call-events.ts
│   ├── agent-init.ts
│   └── agent-postcall.ts
└── migrations/
    └── index.ts          # MIGRATIONS array
\`\`\`

---

## Переменные окружения

### Cloudflare Bindings

| Binding | Тип | Описание |
| ------- | --- | -------- |
| `INTEG_DB` | D1 | База данных |
| `INTEG_KV` | KV | Кэш |

### Секреты (D1 creds)

| Переменная | Обязательная | Описание |
| ---------- | ------------ | -------- |
| `{SECRET_1}` | Да | Описание |
| `{SECRET_2}` | Нет | Описание |

---

## Troubleshooting

### {Типичная ошибка 1}

**Симптом:** {Что видит пользователь}

**Причина:** {Почему это происходит}

**Решение:**
1. Шаг 1
2. Шаг 2

### {Типичная ошибка 2}

{Аналогично}

---

## Связанные документы

- [INTEGRATION_CHECKLIST](../../docs/INTEGRATION_CHECKLIST.md) — чеклист создания
- [SECRETS](../../docs/SECRETS.md) — управление секретами
- [HANDLERS_REFERENCE](../../docs/ai/HANDLERS_REFERENCE.md) — паттерны handlers

---

Шаблон: Документация пакета

Файл: packages/{name}/README.md

# @happ-integ/{name}

{Краткое описание пакета в 1-2 предложения.}

## Установка

\`\`\`bash
pnpm add @happ-integ/{name}
\`\`\`

---

## Быстрый старт

\`\`\`typescript
import { {MainClass} } from "@happ-integ/{name}";

const client = new {MainClass}({
  // конфигурация
});

await client.{mainMethod}();
\`\`\`

---

## API Reference

### {MainClass}

#### Конструктор

\`\`\`typescript
new {MainClass}(options: {MainClass}Options)
\`\`\`

**Параметры:**

| Параметр | Тип | Обязательный | Описание |
| -------- | --- | ------------ | -------- |
| `option1` | string | Да | Описание |
| `option2` | number | Нет | Описание (default: 10) |

#### Методы

##### `.{method1}()`

{Описание метода}

\`\`\`typescript
await client.{method1}(param1: string): Promise<Result>
\`\`\`

**Параметры:**

| Параметр | Тип | Описание |
| -------- | --- | -------- |
| `param1` | string | Описание |

**Возвращает:** `Promise<Result>`

**Пример:**

\`\`\`typescript
const result = await client.{method1}("value");
console.log(result);
\`\`\`

##### `.{method2}()`

{Аналогично}

---

## Примеры использования

### {Сценарий 1}

\`\`\`typescript
// Пример кода для сценария 1
\`\`\`

### {Сценарий 2}

\`\`\`typescript
// Пример кода для сценария 2
\`\`\`

---

## Конфигурация

| Опция | Тип | Default | Описание |
| ----- | --- | ------- | -------- |
| `option1` | string | - | Описание |
| `option2` | number | `10` | Описание |

---

## Связанные документы

- [PACKAGE_CHECKLIST](../../docs/PACKAGE_CHECKLIST.md) — создание пакетов
- [{Related Package}](../{related}/README.md) — связанный пакет

---

Шаблон: README интеграции (минимальный)

Для простых интеграций без сложной логики:

# {Name} Integration

{Описание в 1 предложение.}

## Endpoints

| Method | Path | Описание |
| ------ | ---- | -------- |
| POST | `/webhook/call-originate` | Инициация звонка |
| POST | `/webhook/agent-init` | Контекст для агента |
| GET | `/health` | Health check |

## Handlers

| Handler | Описание |
| ------- | -------- |
| `callOriginateHandler` | Инициация звонка |
| `agentInitHandler` | Контекст для агента |

## Секреты

| Переменная | Описание |
| ---------- | -------- |
| `{SECRET}` | Описание |

## Связанные документы

- [INTEGRATION_CHECKLIST](../../docs/INTEGRATION_CHECKLIST.md)

---

Навигация в документации

Категории документов

Категория	Аудитория	Документы
Быстрый старт	Новички	QUICK_START, SETUP
Ежедневная работа	Интеграторы	DEVELOPMENT, CODE_RULES, SCRIPTS
Создание	Разработчики	INTEGRATION_CHECKLIST, PACKAGE_CHECKLIST
Архитектура	Архитекторы	ARCHITECTURE, DATABASE, SECRETS
DevOps	DevOps	CI_CD, PRODUCTION, MONITORING
Справочник	Все	ERRORS, TROUBLESHOOTING, ai/*

Порядок чтения для новичка

1. QUICK_START.md — общее понимание за 5 минут
2. ARCHITECTURE.md — как устроена система
3. DEVELOPMENT.md — настройка локального окружения
4. CODE_RULES.md — стандарты кода
5. INTEGRATION_CHECKLIST.md — создание первой интеграции

Порядок чтения для опытного разработчика

1. CODE_RULES.md — стандарты проекта
2. ai/HANDLERS_REFERENCE.md — паттерны handlers
3. DATABASE.md — работа с D1
4. SECRETS.md — работа с credentials

---

Чеклист перед публикацией документа

• [ ] Заголовок отражает содержание
• [ ] Есть краткое описание в начале
• [ ] Секции разделены ---
• [ ] Код примеры работают и актуальны
• [ ] Таблицы используются для справочной информации
• [ ] Есть секция "Связанные документы"
• [ ] Проверены все ссылки
• [ ] Нет опечаток

---

Связанные документы

• CODE_RULES — стандарты кода
• INTEGRATION_CHECKLIST — создание интеграций
• PACKAGE_CHECKLIST — создание пакетов