# Уникальность текстов, трастовые ссылки в БД и сервис постинга

Дата: 2026-10-01
База: `main` после fast-forward из `feature/generation-settings` (AiService, GenerationSettings).
Ветка: `feature/content-uniqueness`.

## Цель

1. Тексты одного проекта должны заметно отличаться друг от друга по структуре, подаче и лексике.
2. Всё, что сейчас захардкожено (трастовые ссылки в `.txt`, URL сервиса постинга, теги,
   заголовок по умолчанию), редактируется в админке и хранится в БД.
3. Состояние сервиса постинга видно в админке, а при его падении публикации не сжигают попытки.
4. Всё, что связано с «Кракеном», удаляется.

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

- Один `textPrompt` в «новостном стиле» на все тексты → одинаковая структура.
- Ключевики генерируются на каждый текст заново по одной и той же теме → 6–7 почти одинаковых слов.
- Температура одним числом.
- Трастовые ссылки — `storage/app/trusted_links/*.txt`, тематика угадывается по словам «эскорт»/«казино»
  в теме проекта, выбор `array_rand`.
- `http://127.0.0.1:8001` захардкожен в `PostTextToSiteJob` и `CheckSiteJob`.
- Теги `<h1><h2>…<a>` и заголовок «SEO Текст» захардкожены в `AiService`.
- `app/Console/Commands/InsertKrakenLinks.php` — вставка жёсткого маркера в тексты.

Вне цели: ротация моделей (явно отказались), сущность «Вставки» (не делаем).

## Схема данных

### Новые таблицы

**`prompt_templates`** — пул шаблонов текстового промпта.
`id, name varchar(255), body text, weight unsigned smallint default 1, is_active bool default true, timestamps`.

**`prompt_modifiers`** — персоны и углы подачи.
`id, type enum('persona','angle'), body text, weight unsigned smallint default 1, is_active bool default true, timestamps`,
индекс `(type, is_active)`.

**`project_keywords`** — банк ключевых слов проекта.
`id, project_id FK cascade, language varchar(8), keyword varchar(255), used_count unsigned int default 0, timestamps`,
unique `(project_id, language, keyword)`.

**`trusted_link_groups`**
`id, name varchar(255), topic varchar(64), city varchar(64) null, language varchar(8) null, is_active bool default true, timestamps`,
индекс `(topic, city, language)`. `language = null` — подходит для любого языка.

**`trusted_links`**
`id, trusted_link_group_id FK cascade, url text, url_hash char(64), anchor varchar(255) null, weight unsigned smallint default 1, is_active bool default true, used_count unsigned int default 0, timestamps`,
unique `(trusted_link_group_id, url_hash)`. `url_hash = sha256(url)` — потому что уникальный индекс по
`text` в MySQL невозможен; хеш заполняет модель в `saving`.

**`project_trusted_link_group`** — pivot `project_id, trusted_link_group_id`, оба FK cascade, PK по паре.

**`text_trusted_link`** — какие ссылки ушли в какой текст.
`text_id FK cascade, trusted_link_id FK cascade, created_at`, PK по паре.

### Изменения существующих таблиц

`projects`: `trusted_links_count unsigned tinyint null` — пусто = глобальная настройка.

`texts`:
- `prompt_template_id` FK → `prompt_templates` null, nullOnDelete;
- `persona_id`, `angle_id` FK → `prompt_modifiers` null, nullOnDelete;
- `similarity decimal(5,2) null` — максимальная похожесть на тексты проекта, %;
- `similar_text_id` FK → `texts` null, nullOnDelete;
- `generation_attempts unsigned tinyint default 1`.

### Перенос `.txt` в БД

Миграция данных читает `storage/app/trusted_links/*.txt`. Имя файла разбирается так:
первый сегмент — тема, последний сегмент длиной 2 символа — язык, всё между — город
(`escort-dubai-en` → escort / dubai / en, `casino-ru` → casino / — / ru, `general` → general / — / —).
На каждый файл создаётся группа `name = имя файла`, ссылки вставляются пачками с дедупликацией по хешу.
Если файлов нет, миграция ничего не делает. `down()` удаляет только созданные ею группы (по имени).
Файлы не удаляются: их можно убрать вручную, когда всё проверено.

> Замечание: файл `escort-kiev-ua.txt` использует язык `ua`, а у ссылок проекта язык `uk`. Сейчас этот
> файл не находится никогда. Переносим как есть (`ua`), а язык группы правится в админке.

## Настройки

### GenerationSettings — новые и изменённые поля

| Поле | Тип | Дефолт | Смысл |
|---|---|---|---|
| `temperature` → `temperatureMin`, `temperatureMax` | float | 0.8 / 1.1 | на каждый запрос случайное значение из диапазона |
| `topPMin`, `topPMax` | float | 0.9 / 1.0 | то же для top_p |
| `lengthVariancePercent` | int | 20 | `{length}` = `text_length ± N%` |
| `h2Min`, `h2Max` | int | 3 / 6 | `{h2_count}` |
| `listProbability` | int, % | 60 | добавить ли в `{structure}` требование списка |
| `faqProbability` | int, % | 30 | добавить ли FAQ-блок |
| `keywordsBankSize` | int | 80 | сколько ключей генерировать в банк |
| `keywordsPerTextMin`, `keywordsPerTextMax` | int | 5 / 8 | сколько ключей отдавать тексту |
| `dedupEnabled` | bool | true | |
| `dedupThreshold` | int, % | 30 | порог похожести |
| `dedupCompareLast` | int | 200 | с каким количеством последних текстов проекта сравнивать |
| `dedupMaxAttempts` | int | 2 | сколько дополнительных перегенераций |
| `allowedTags` | string | `<h1><h2><h3><h4><p><ul><ol><li><br><a>` | теги после чистки |
| `defaultTitle` | string | `SEO Текст` | заголовок, если в ответе нет H1 |

Миграция настроек переносит текущее значение `temperature` в оба поля диапазона.

`keywordsPrompt` теперь генерирует банк и получает переменную `{count}`. Если значение равно старому
дефолту, миграция заменяет его на новый (с `{count}`). Если пользователь его менял, значение не трогается,
а `{count}` просто не будет подставлен.

`textPrompt` остаётся запасным промптом: он используется, когда нет ни одного активного шаблона.

Новые переменные текстового промпта: `{persona}`, `{angle}`, `{structure}`, `{h2_count}`.
`{length}` теперь варьируется. Подсказка переменных в формах обновляется через
`GenerationSettings::getAvailableVariables()`.

### PostingSettings (новая группа `posting`)

`serviceUrl` (`http://127.0.0.1:8001`), `timeout` (10), `healthTimeout` (5).
Отдельная страница «Сервис постинга» в новой группе навигации «Постинг».

## Компоненты

### Выбор по весу — `App\Support\WeightedRandom`

`pick(Collection $items, string $weightKey = 'weight'): ?Model` — один элемент с вероятностью,
пропорциональной весу. Вес ≤ 0 не выбирается. Используется для шаблонов и модификаторов.
Генератор случайных чисел подменяется в тестах (`random_int` через замыкание).

### `App\Services\Generation\PromptComposer`

`compose(Project $project, ProjectLink $link, string $keywords, string $trustedLinksBlock, int $trustedLinksCount, array $exclude = []): ComposedPrompt`

`ComposedPrompt` (readonly DTO) содержит: `template` (строка шаблона), `variables` (массив),
`templateId`, `personaId`, `angleId`.

Порядок выбора шаблона:
1. `project->text_prompt`, если задан (`templateId = null`);
2. иначе случайный по весу активный `PromptTemplate`, кроме `$exclude['template']`, если есть альтернатива;
3. иначе `settings->textPrompt`.

Персона и угол выбираются так же (с исключением использованных при перегенерации). Если активных нет,
переменная пустая.

`{structure}` собирается из настроек в виде нескольких строк:
`Используй {h2_count} подзаголовков H2.`, при выпадении — `Добавь маркированный список.`,
при выпадении — `В конце добавь блок FAQ из 3–5 вопросов с ответами.`.

### `App\Services\Generation\KeywordBank`

`take(Project $project, string $language): string`
- если банк проекта для языка пуст, вызывает `AiService::generateKeywordBank($topic, $language, $count)`
  и сохраняет уникальные непустые ключи (lowercase, trim);
- берёт `rand(min, max)` ключей: сортировка по `used_count`, при равенстве случайно;
- инкрементирует `used_count` у выданных и возвращает их через запятую в случайном порядке;
- если генерация банка упала и банк пуст, возвращает тему проекта (как сейчас).

`regenerate(Project $project, string $language): int` — удалить банк языка и сгенерировать заново.

`AiService::generateKeywords()` заменяется на `generateKeywordBank(topic, language, count): array<string>`.
Ответ разбирается по запятым и переводам строк, без нумерации.

### `App\Services\TrustedLinksResolver` (переписан на БД)

`pick(Project $project, string $language, int $count): Collection<TrustedLink>`
1. Только группы, выбранные в настройках проекта: активные с `language = $language` или `null`;
   если таких нет — все выбранные активные. Без выбранных групп ссылок нет — подбора по теме больше нет.
2. Среди активных ссылок этих групп выбираются `$count` с наименьшим `used_count / weight`,
   при равенстве случайно (`ORDER BY used_count / GREATEST(weight, 1), RAND()`).

Переход: миграция `assign_trusted_link_groups_to_projects` через `LegacyGroupAssigner` один раз
назначает проектам без групп те группы, которые им давал старый подбор по файлам
(`{тема}-{город}-{язык}` → `{тема}-{язык}` → `{тема}` → `general-{язык}` → `general`, тема и город —
по словам «эскорт»/«проститут»/«казино» в теме проекта). Поведение существующих проектов не меняется.

`block(Collection $links): string` — формат прежний; если у ссылки есть анкор, он идёт в текст тега.
`markUsed(Text $text, Collection $links): void` — запись в `text_trusted_link` + инкремент `used_count`.
Вызывается только после успешного сохранения текста.

### `App\Services\Generation\SimilarityChecker`

`shingles(string $html): array<int, true>` — strip_tags, `mb_strtolower`, слова через `preg_split('/[^\p{L}\p{N}]+/u')`,
шинглы из 3 слов, ключ — `crc32`.
`mostSimilar(Text $text, string $html): array{similarity: float, text_id: ?int}` — Жаккар против
`dedupCompareLast` последних текстов проекта с непустым `body_html` (кроме самого текста).

### `GenerateTextJob` — новый порядок

1. Проверки статуса и связей (как сейчас).
2. `keywords = KeywordBank::take(...)`, сохраняются в `text->keywords`.
3. `count = project->trusted_links_count ?? settings->trustedLinksCount` (0, если ссылки выключены);
   `links = resolver->pick(...)`.
4. Цикл до `1 + dedupMaxAttempts` попыток:
   `compose` (исключая шаблон/персону/угол прошлой попытки) → `AiService::generateContent` → `SimilarityChecker`.
   Если дубли выключены или похожесть ниже порога — стоп. Запоминается лучшая (наименее похожая) попытка.
5. Сохраняются title/body, `prompt_template_id`, `persona_id`, `angle_id`, `similarity`,
   `similar_text_id`, `generation_attempts`, статус `generated`.
6. `resolver->markUsed($text, $links)`.

Ошибки AI обрабатываются как сейчас (статус `error`, исключение пробрасывается для ретраев очереди).

### `AiService`

- `chat()` берёт температуру и top_p случайно из диапазонов (если не переданы явно). Для reasoning-моделей
  не отправляет ни то, ни другое.
- `cleanHtmlResponse()` по умолчанию берёт `settings->allowedTags`, `extractTitle()` — `settings->defaultTitle`.

### Сервис постинга

**`App\Services\Posting\PostingServiceClient`** — единая точка вызова FastAPI:
`publish(array $payload): Response`, `check(array $payload): Response`, `health(): PostingServiceStatus`.
URL и таймауты берутся из `PostingSettings`. `PostTextToSiteJob` и `CheckSiteJob` переходят на клиент.

**`PostingServiceStatus`** (readonly DTO): `online`, `latencyMs`, `activeTasks ?int`, `uptimeSeconds ?int`,
`error ?string`, `checkedAt`.

**`App\Services\Posting\PostingServiceMonitor`**
- `refresh(): PostingServiceStatus` — вызывает `health()`, кладёт результат в кеш `posting_service:status` на 10 минут;
- `status(): ?PostingServiceStatus` — последнее значение из кеша;
- `isAvailable(): bool` — если кеш свежее 2 минут, отвечает по нему, иначе делает `refresh()`.

**Команда `posting:health`** — `refresh()`, запускается по расписанию каждую минуту.

**Защита от простоя:**
- `postings:dispatch` ничего не диспатчит, если `!isAvailable()` (посты остаются `pending` и будут подхвачены позже), и пишет warning в лог;
- `PostTextToSiteJob` в начале `handle()`: если `!isAvailable()`, делает `release(120)` без пометки сайта ошибкой.

**`/health` в `scripts/app.py`** возвращает `{"status":"ok","active_tasks":N,"uptime_seconds":S}`.
`active_tasks` — счётчик под `threading.Lock`: инкремент при `submit`, декремент в `finally`
фоновых функций. Старые клиенты, которые смотрят только на `status`, продолжают работать.

**Виджет `PostingServiceWidget`** (дашборд, наверху): online/offline с цветом, время ответа, активные задачи,
uptime, «последняя проверка N сек назад», количество `text_site` в `sending`, ошибки `text_site` за 24 ч,
кнопка «Проверить сейчас» (`refresh()`). Он же выводится на странице настроек сервиса постинга.

## Админка (Filament v3)

Новая группа навигации **«Генерация»**: «Настройки генерации» (переезжает), «Шаблоны промптов»,
«Персоны и углы», «Трастовые ссылки».

- **PromptTemplateResource** — CRUD; таблица: название, вес, активность (toggle), сколько текстов использовали шаблон.
  Подсказка по переменным в форме. Действие «Дублировать».
- **PromptModifierResource** — CRUD; вкладки «Персоны» / «Углы» по `type`, вес, активность.
- **TrustedLinkGroupResource** — CRUD групп (название, тема, город, язык, активность); в таблице количество
  активных ссылок и сумма использований.
  - RelationManager «Ссылки»: url, анкор, вес, активность, `used_count`, массовые вкл/выкл/удаление.
  - Действие «Импорт»: textarea (строка = `url` или `url;анкор` / `url,анкор`) и/или загрузка `.txt/.csv`.
    Невалидные URL пропускаются, дубли внутри группы — тоже. Итог в уведомлении: добавлено / дублей / невалидных.
  - Использование: у каждой ссылки `used_count`, число текстов и действие «Тексты» (модалка со списком текстов из `text_trusted_link`).
- **ProjectResource** — секция «Трастовые ссылки»: multi-select групп, `trusted_links_count`
  (placeholder — глобальное значение). RelationManager «Ключевые слова»: ключ, язык, использований,
  ручное добавление/удаление, действие «Перегенерировать банк» (выбор языка).
- **Тексты** (TextResource и TextsRelationManager): колонка «Похожесть, %» (зелёный < порог/2,
  жёлтый < порог, красный ≥ порог), фильтр «Похожие (≥ порога)», колонка шаблона. При просмотре
  видно шаблон, персону, угол, попытки и трастовые ссылки.
- **ManageGenerationSettings** — новые вкладки «Уникальность» (диапазоны температуры/top_p, длина, структура),
  «Дубли», «Ключевые слова» (+ размеры банка), «Вывод» (теги, заголовок). Подсказка во вкладке
  «Трастовые ссылки» теперь ведёт на ресурс групп.
- **ManagePostingSettings** — URL, таймауты и виджет состояния.

### Стартовые данные

Сидер `GenerationContentSeeder` (вызывается из миграции данных, чтобы попасть на прод без ручного шага;
идемпотентен — вставляет, только если соответствующая таблица пуста):
- 7 шаблонов: новость, обзор, гайд, FAQ, история, сравнение, интервью. Все используют
  `{keywords} {length} {structure} {persona} {angle} {link_url} {link_anchor} {trusted_links} {trusted_links_count} {language}`;
- 10 персон и 15 углов.

## Удаление «Кракена»

Удаляется `app/Console/Commands/InsertKrakenLinks.php`. Других упоминаний в коде нет
(проверено `grep -ri kraken`).

## Тесты

Подход прежний: `DatabaseTransactions` на локальной MySQL, без сети, `GenerationSettings::fake()`, `Http::fake()`.

- `WeightedRandom` — распределение, нулевые веса, пустой набор.
- `PromptComposer` — приоритет промпта проекта, исключение прошлой попытки, `{structure}` при вероятностях 0/100, диапазон `{length}`.
- `KeywordBank` — заполнение пустого банка, выдача наименее использованных, откат на тему при ошибке AI, `regenerate`.
- `TrustedLinksResolver` — группы проекта vs fallback-цепочка, фильтр по языку, `used_count/weight`, `markUsed`.
  Старый `TrustedLinksResolverTest` (файловый) переписывается.
- `SimilarityChecker` — идентичные / разные / частично совпадающие тексты, сравнение только внутри проекта.
- `GenerateTextJob` — обновление существующих тестов + перегенерация при дубле, выбор лучшей попытки, сохранение мета-полей, `markUsed` только при успехе.
- `AiService` — диапазоны температуры/top_p, настраиваемые теги и заголовок.
- `PostingServiceMonitor`/`PostingServiceClient` — online/offline/таймаут, кеш, `isAvailable`.
- `PostTextToSiteJob` — release при offline, URL из настроек; `postings:dispatch` — пропуск при offline.
- Миграция `.txt` → БД — разбор имён файлов (unit на парсер имени).
- Filament: импорт ссылок (добавлено/дубли/невалидные), сохранение групп в проекте, новые вкладки настроек.

## Риски

- `ORDER BY used_count / weight, RAND()` по одной группе (до ~1000 ссылок) — дёшево. Если групп станет
  на порядки больше, понадобится индекс по `(trusted_link_group_id, is_active, used_count)`; он добавляется сразу.
- Сравнение похожести — до 200 текстов × ~1000 слов в памяти воркера, это миллисекунды.
- Изменение формы ответа `/health` обратно совместимо.
