# Схема генерации контента в postbird (порт из filament-sprm)

Дата: 2026-07-30

## Цель

Перенести в postbird схему генерации контента, которая работает в filament-sprm:
настройки генерации редактируются в админке (промпты, модель, температура), модель
можно менять без деплоя, провайдера — тоже, а джоба генерации перестаёт быть
контейнером для захардкоженных промптов.

## Что есть сейчас

`app/Jobs/GenerateTextJob.php` (~240 строк) содержит в себе всё:

- модель `gpt-4.1` захардкожена в двух местах (`generateKeywords` и основная генерация);
- системные промпты и промпты ключевиков/текста — строками в коде;
- поиск трастовых ссылок (`getTrustedLinksByTopicAndCity`, `detectTopicAndCity`) —
  вместе с определением тематики по подстрокам «эскорт», «казино»;
- чистка HTML (`strip_tags` с фиксированным списком тегов), извлечение H1 и тела;
- ретраев на уровне запроса нет — только `$tries = 3` у самой джобы, то есть
  повторяется вся генерация целиком, включая уже сделанные запросы.

Пакета `spatie/laravel-settings` в проекте нет. Filament — v3 (в filament-sprm v4+,
поэтому код страницы настроек переносится не дословно: там `Filament\Schemas`,
здесь `Filament\Forms`).

Специфика postbird, которой нет в sprm и которую надо сохранить: трастовые ссылки из
`storage/app/trusted_links`, обязательная вставка ссылки проекта с анкором, язык
берётся из `ProjectLink`, новостной стиль текста.

## Принятые решения

1. **Выбор провайдера — через имя модели.** Модель пишется как `gpt-4.1` (дефолтный
   OpenAI-клиент) или `xai:grok-4`, `deepseek:deepseek-chat`, `openrouter:...`
   (провайдер из `config/ai.php`). Отдельного селекта провайдера и отдельных классов
   сервисов на провайдера нет: все они говорят по OpenAI-протоколу, различаются
   только base_uri и ключом. Новый провайдер = строка в конфиге.
2. **Два уровня настроек:** глобальные (страница настроек) + переопределение на
   уровне проекта (своя модель и свой промпт текста). Пусто на проекте = глобальное
   значение. Уровня отдельного текста нет — тексты создаются пачками, руками их
   промпты никто править не будет.
3. **Лёгкий слой сервисов** вместо полного порта из sprm: один `AiService` без
   интерфейса и фабрики. Интерфейс с фабрикой в sprm нужен был для схемы «селект
   провайдера + класс на провайдера», которую мы не берём.

## Архитектура

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

`config/ai.php` — порт 1:1 из filament-sprm:

```php
return [
    'providers' => [
        'xai' => [
            'label' => 'xAI (Grok)',
            'base_uri' => env('XAI_BASE_URL', 'api.x.ai/v1'),
            'api_key' => env('XAI_API_KEY'),
        ],
        'deepseek' => [...],
        'openrouter' => [...],
    ],
];
```

В `.env.example` добавляются `XAI_API_KEY`, `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`
(и опциональные `*_BASE_URL`).

### `App\Services\Ai\AiClients`

Порт 1:1 из filament-sprm. Отвечает на один вопрос: какому клиенту уходит запрос.

- `for(?string $model): ClientContract` — клиент для модели. Нет префикса или префикс
  не назван в `config('ai.providers')` → дефолтный клиент из `openai-php/laravel`
  (резолвится как `app(ClientContract::class)`, не через фасад `OpenAI`).
- `modelName(?string $model): ?string` — имя модели без префикса провайдера.
- `providerOf(?string $model): ?string` — провайдер модели или `null`.
- `labels(): array` — ключ провайдера → человекочитаемая метка (для подсказки в форме).

Клиенты провайдеров кэшируются в свойстве. Отсутствие ключа у провайдера →
`RuntimeException` с внятным текстом.

### `App\Services\Ai\AiService`

Единственный класс, который знает, как разговаривать с моделью.

- `chat(string $system, string $prompt, ?float $temperature = null, ?string $model = null): string`
  — всегда стримингом (`createStreamed`), так как тексты длинные и на нестриминговом
  запросе легко словить таймаут; ретраи 3 раза с экспоненциальной паузой (1с, 2с, 4с),
  только на 429 / 5xx / connection / timeout, иначе сразу `AiException`.
- Температура **не отправляется** для моделей `gpt-5*`, `o1*`, `o3*`, `o4*` — они
  принимают только значение по умолчанию и падают на любом другом.
- `generateKeywords(string $topic, string $language): string` — промпт из настроек,
  подстановка переменных, `shuffle` результата. При ошибке возвращает `$topic`
  (текущее поведение джобы сохраняем: генерация текста из-за ключевиков не падает).
  Использует `keywordsModel`, если он задан, иначе `contentModel`.
- `generateContent(array $variables, ?string $customPrompt = null): string` — берёт
  промпт проекта или глобальный, подставляет переменные, зовёт `chat()`, чистит HTML.
- `cleanHtmlResponse(string $content, string $allowedTags = '<h1><h2><h3><h4><p><ul><ol><li><br><a>'): string`
  — срезает ```` ```html ````-обёртку и лишние теги (перенос текущей логики).
- `extractTitle(string $html): string` — H1 или `'SEO Текст'` (текущий fallback
  postbird; в sprm здесь исключение — намеренно не меняем поведение).
- `extractBody(string $html): string` — HTML без H1.
- `replaceVariables(string $template, array $variables): string` — `{key}` → значение.

Пустой ответ модели → `AiException` (сейчас `RuntimeException` в джобе).

### `App\Exceptions\AiException`

Отдельный тип, чтобы джоба и будущие вызовы отличали сбой модели от прочих ошибок.

### `App\Settings\GenerationSettings`

Группа `generation`, поля:

| Поле | Тип | Назначение |
| --- | --- | --- |
| `contentModel` | string | Модель генерации текста |
| `keywordsModel` | ?string | Модель ключевиков; пусто = `contentModel` |
| `temperature` | float | Температура; игнорируется для reasoning-моделей |
| `systemPromptContent` | string | System для генерации текста |
| `systemPromptKeywords` | string | System для ключевиков |
| `textPrompt` | string | Промпт генерации текста |
| `keywordsPrompt` | string | Промпт генерации ключевиков |
| `trustedLinksEnabled` | bool | Вставлять ли трастовые ссылки |
| `trustedLinksCount` | int | Сколько ссылок вставлять |

Метод `getAvailableVariables(): array` — список переменных с описаниями, из него
строится подсказка под полями формы (как в sprm).

Миграция `database/settings/2026_07_30_..._create_generation_settings.php` кладёт
дефолтами **текущие промпты из `GenerateTextJob` дословно**, `contentModel = 'gpt-4.1'`,
`keywordsModel = null`, `temperature = 1.0` (сейчас параметр не передаётся вовсе, а
дефолт OpenAI — 1.0; так поведение не меняется), `trustedLinksEnabled = true`,
`trustedLinksCount = 2`. После миграции генерация работает ровно как до неё.

### `App\Filament\Pages\ManageGenerationSettings`

`Filament\Pages\SettingsPage` из `filament/spatie-laravel-settings-plugin` (ветка ^3.0
под Filament v3). Форма — `Filament\Forms\Components\Tabs` с вкладками:

1. **AI** — `contentModel`, `keywordsModel`, `temperature`. В helper-тексте: формат
   `provider:model` и список настроенных провайдеров из `AiClients::labels()`.
2. **Системные промпты** — `systemPromptContent`, `systemPromptKeywords`.
3. **Текст** — `textPrompt` (textarea на 15 строк) + подсказка с переменными.
4. **Ключевые слова** — `keywordsPrompt` + подсказка с переменными.
5. **Трастовые ссылки** — `trustedLinksEnabled`, `trustedLinksCount`.

Навигация: группа «Контент», иконка `heroicon-o-sparkles`. Каталог
`app/Filament/Pages` создаётся впервые — панель его уже сканирует
(`discoverPages` в `AdminPanelProvider`).

### Переопределение на проекте

Миграция `projects`: `ai_model` (nullable string), `text_prompt` (nullable text).
Оба поля добавляются в `$fillable` модели `Project`.

В `ProjectResource` — свёрнутая секция «Генерация» на всю ширину: `TextInput` модели
(placeholder = текущее глобальное значение) и `Textarea` промпта с той же подсказкой
по переменным. Пусто = глобальная настройка.

### `App\Services\TrustedLinksResolver`

Забирает из джобы `detectTopicAndCity()` и `getTrustedLinksByTopicAndCity()`. Логика
поиска файлов не меняется: `{topic}-{city}-{lang}.txt` → `{topic}-{lang}.txt` →
`{topic}.txt` → `general-{lang}.txt` → `general.txt` в `storage/app/trusted_links`.

Публичный метод `resolve(string $topic, string $language, int $count): array` —
уникальные ссылки, из них до `$count` случайных. Метод
`block(string $topic, string $language, int $count): string` собирает готовый блок
`- <a href='...'>...</a>` для подстановки в `{trusted_links}`. При
`trustedLinksEnabled = false` джоба подставляет пустую строку.

### Переменные промпта

**Текст:** `{topic}` `{keywords}` `{length}` `{language}` `{link_url}` `{link_anchor}`
`{trusted_links}` `{project}`

**Ключевые слова:** `{topic}` `{language}`

### `GenerateTextJob` после рефакторинга

```
handle():
  найти Text с project и link           → нет: лог, выход
  статус не pending/error               → лог, выход
  нет project или link                  → статус error, выход
  keywords = AiService::generateKeywords(project.topic, link.language)
  сохранить keywords
  variables = [topic, keywords, length, language, link_url, link_anchor,
               trusted_links, project]
  content = AiService::generateContent(variables, project.text_prompt)
            модель: project.ai_model ?: settings.contentModel
  title = extractTitle(content); body = extractBody(content)
  обновить title/body_html/status=generated/generated_at/error_message=null
  project.checkAndUpdateGenerationStatus()
  catch Throwable: статус error + error_message, лог, throw (ретраи очереди)
```

`$tries = 3` и `$backoff` у джобы остаются: ретраи `AiService` покрывают сбой
отдельного запроса, ретраи очереди — сбой джобы целиком (например, падение БД).

## Тестирование

`tests/Unit` и `tests/Feature` сейчас пустые — заводим. Тесты не ходят в API:

- `AiService::replaceVariables()` — подстановка, отсутствующие ключи не ломают шаблон.
- `AiService::cleanHtmlResponse()` — снятие ```` ```html ````, вырезание `<strong>`,
  `<em>`, `<script>`.
- `AiService::extractTitle()` / `extractBody()` — H1 есть / H1 нет (fallback) / тело
  без H1.
- `AiClients::providerOf()` / `modelName()` — `xai:grok-4` → `xai` + `grok-4`;
  `gpt-4.1` → `null` + `gpt-4.1`; `foo:bar` (нет такого провайдера) → `null` + `foo:bar`.
- `TrustedLinksResolver` — приоритет файлов и лимит количества на временных файлах в
  `storage/app/trusted_links` (создаются и удаляются в тесте).

## Порядок работ

1. Пакеты: `spatie/laravel-settings`, `filament/spatie-laravel-settings-plugin:^3.0`,
   публикация конфига и миграции spatie.
2. `config/ai.php` + `.env.example` + `AiClients` + тесты на роутинг.
3. `GenerationSettings` + миграция настроек с текущими дефолтами.
4. `AiException` + `AiService` + юнит-тесты на чистые методы.
5. `TrustedLinksResolver` + тесты.
6. Рефакторинг `GenerateTextJob` на `AiService` и `TrustedLinksResolver`.
7. `ManageGenerationSettings`.
8. Миграция `projects` + поля в модели и `ProjectResource`.

Шаги 2–5 не затрагивают существующее поведение; поведение меняется только на шаге 6,
и меняется на эквивалентное — дефолты настроек равны текущим захардкоженным строкам.

## Не входит в объём

- Переопределение промпта на уровне отдельного `Text`.
- Structured outputs (`chatJson`), vision, генерация лендингов и термов — в postbird
  нет соответствующих сущностей.
- Настройка разрешённых HTML-тегов, числа ретраев и таймаутов через UI — остаются в
  коде/конфиге.
- Замена `GenerateTextsJob`, планировщика постинга и прочего вокруг генерации.

## Замечания

- В форме проекта `text_length` подписан «Длина (символы)», а в промпт уходит как
  «слов». Подпись не трогаем — отдельная правка по желанию.
- `Text::$fillable` не содержит `keywords`, хотя колонка есть; в джобе поле
  присваивается напрямую. При рефакторинге сохраняем прямое присваивание, чтобы не
  расширять массовое заполнение без нужды.
