# SEO Farm Implementation Guardrails

## 1. Зачем этот документ

Этот файл фиксирует порядок разработки и технические ограничения, чтобы user flow, backend pipeline и инструменты не начали спорить друг с другом.

Главная идея:

```text
UI показывает понятный SEO-процесс.
Backend внутри выполняет строгую техническую последовательность.
Инструменты не смешивают зоны ответственности.
Target project меняется только после ручного Apply.
```

## 2. User Flow vs Backend Pipeline

Для пользователя первый смысловой шаг после создания проекта — “Проанализировать проект”.

В UI это один сценарий:

```text
Create Project
  -> Analyze Project
  -> Baseline Audit Result
```

Но backend не может делать audit без технической подготовки. Внутренний порядок должен быть таким:

```text
1. validate targetProjectPath
2. scan filesystem
3. filter ignored folders/files
4. detect candidate files
5. parse HTML/MD/text/CSS references
6. build projectIndex
7. map pages
8. map sections
9. map media assets
10. create source mapping
11. run baseline audit
12. save scan + audit result
13. return UI-ready report
```

Для будущих источников backend должен мыслить не только `targetProjectPath`, а `project source`:

```text
MVP:
  local_folder -> targetProjectPath

Later:
  git_repo
  zip_upload
  site_crawl
```

Нельзя делать:

```text
Baseline Audit
  -> потом parse
```

Правильно:

```text
Scan / Parse / Map
  -> Baseline Audit
```

В UI слово “parse” лучше не выносить отдельным этапом. Это внутренняя операция.

## 3. Строгий MVP Pipeline

```text
Project Setup
  input: project name, project source
  output: project record

Project Scan
  input: project source
  output: projectIndex

Baseline Audit
  input: projectIndex
  output: audit report, page/media/source issues

Page Workspace
  input: selected page/group
  output: originalText, workingText, sectionMap

Meaning Extraction
  input: originalText, sectionMap, meta/headings/media context
  output: section meanings, seed queries, competing intents

Seed Review
  input: proposed seeds
  output: approved seeds

Wordstat Collection
  input: approved seeds
  output: raw Wordstat results, ВЧ/СЧ/НЧ groups

Keyword Cleaning
  input: raw Wordstat results
  output: approved keyword decisions

Keyword Map
  input: approved keywords, section meanings, current text
  output: approved keyword-to-section map

Optimization Plan
  input: keyword map, audit, current workingText, design limits
  output: approved edit plan

Rewrite Workspace
  input: approved edit plan
  output: edited workingText

Media SEO
  input: media map, section context, keyword map
  output: approved alt/title/aria/caption/filename suggestions

Final Validation
  input: workingText, keyword map, media map, approved media changes
  output: validation report

Apply / Export
  input: approved text/media changes
  output: changeset, updated target project, reports/export
```

## 4. Tool Boundaries

### 4.1. `checkOverseo`

Отвечает за SEO-перебор:

```text
- точные вхождения;
- soft forms;
- перетошнота;
- заспамленность;
- повторы рядом;
- повторяющиеся биграммы/триграммы;
- перебор ключа в title/description/h1/h2;
- keyword stuffing в alt/filename;
- конфликт ключа со смыслом секции.
```

Не отвечает за:

```text
- стиль бренда;
- красивость текста;
- смысловую редактуру;
- выбор ключей из Wordstat.
```

### 4.2. `ru-text`

Отвечает за редакторский фильтр после SEO-правок:

```text
- тон;
- читаемость;
- канцелярит;
- мутные формулировки;
- редакторские и типографические проблемы.
```

Не отвечает за:

```text
- сбор ключей;
- частотность;
- Wordstat;
- карту ключей;
- SEO-плотность.
```

### 4.3. `keywordService`

Отвечает за чистку Wordstat-результатов:

```text
- нормализация запросов;
- дедупликация;
- project blacklist;
- мусорные интенты;
- группировка близких запросов;
- Codex-классификация спорных запросов;
- user approval.
```

Это не `stopword`-инструмент и не удаление слов из текста.

### 4.4. Wordstat MCP

Wordstat MCP — только “рука в Wordstat”.

Он:

```text
- получает seed;
- возвращает запросы и частотность;
- сохраняет raw data.
```

Он не:

```text
- решает, что использовать;
- пишет текст;
- строит карту ключей;
- проверяет переспам.
```

### 4.5. Codex Exec

Codex через `codex exec` используется для смысловых задач:

```text
- выделить темы;
- предложить seed queries;
- классифицировать спорные ключи;
- предложить keyword map;
- сформировать optimization plan;
- предложить варианты правки;
- предложить alt/caption/filename.
```

Codex не должен напрямую менять target project до `Apply`.

## 5. Apply Safety Rules

До ручного Apply target project считается read-only.

Разрешённые изменения после approval:

```text
- visible text;
- title;
- description;
- headings;
- alt/title/aria;
- captions;
- approved filenames.
```

Запрещено без отдельного подтверждения:

```text
- менять layout;
- менять CSS/JS-логику;
- рефакторить код сайта;
- удалять файлы;
- менять структуру приложения SEO Farm;
- публиковать на хостинг.
```

Перед Apply UI обязан показать:

```text
- affected files;
- text diff;
- media diff;
- filename rename plan;
- validation status;
- changeset summary.
```

Apply должен идти транзакционно:

```text
1. build changeset
2. run dry-run
3. backup affected files to object storage
4. apply text/media/filename changes through backend
5. verify references and rename results
6. rollback if any critical step fails
```

## 5.1. Repeated Scan / Reconcile Rules

Повторный scan не должен перетирать уже принятые решения.

Правильно:

```text
new scan
  -> create scan_version
  -> create page/section/media versions
  -> run reconcile
  -> preserve stable logical IDs
  -> show review summary to user
```

Стабильные идентификаторы:

```text
page_id
section_id
media_id
```

Текущий `DOM selector` — это версия привязки, а не identity.

Статусы reconcile:

```text
matched
changed
new
orphaned
conflicted
```

Решения пользователя должны ссылаться на logical IDs:

```text
- keyword decisions
- drafts
- media approvals
- changesets
```

## 6. Storage Risks

Нельзя хранить всё только в памяти.

Минимально нужно:

```text
Postgres:
  - projects
  - project_sources
  - scan_versions
  - pages / page_versions
  - sections / section_versions
  - media_assets / media_versions
  - runs
  - seeds
  - wordstat_jobs / wordstat_results
  - keyword_decisions
  - keyword_map_items
  - drafts / draft_items
  - validations / validation_issues
  - changesets / changeset_items

Object Storage:
  - raw Wordstat dumps
  - originalText snapshots
  - workingText drafts
  - reports
  - previews / video frames
  - backups
  - exports
```

Правило:

```text
Postgres = source of truth
Object Storage = heavy artifacts
YAML/JSON/Markdown = export/debug only
```

Риск:

```text
Если workingText не отделить от originalText,
модельная ошибка может испортить исходник без понятного отката.
```

MVP может хранить одну активную рабочую версию на секцию, но scan versions, snapshots и changesets должны быть полноценными уже с первого релиза.

## 7. Development Risk Checklist

### 7.1. Pipeline risks

- Audit запущен до parse/map.
- UI показывает parse как отдельную пользовательскую задачу.
- Project scan требует ручного выбора файлов.
- Многостраничный сайт превращается в ручной список `index.html`.
- Повторный scan затирает уже утверждённые решения без предупреждения.
- Решения по секции привязаны только к текущему selector и теряются после перестройки DOM.

### 7.2. Model risks

- Codex меняет target project до Apply.
- Prompt не ограничивает зону правок.
- Model output невалидный JSON, а backend применяет его без проверки.
- Модель смешивает SEO-правки с редизайном или рефакторингом кода.

### 7.3. Keyword risks

- Wordstat results считаются готовой keyword map.
- Keyword Cleaning превращается в ручную таблицу без assisted classification.
- ВЧ-запросы насильно пихаются в каждую секцию.
- `article`-ключи запихиваются в главную страницу вместо будущих материалов.
- Нет user approval перед использованием ключей.

### 7.4. Text quality risks

- `checkOverseo` пытается оценивать тон вместо переспама.
- `ru-text` используется как SEO-решатель вместо редакторского фильтра.
- Проверка длины игнорирует дизайн-блоки.
- Правки раздувают текст и ломают визуальную секцию.

### 7.5. Media SEO risks

- Alt набивается ключами без связи с изображением.
- Decorative media получают SEO-alt.
- Видео обрабатывается как `<img alt="">`, хотя у video нет обычного alt.
- Filename меняется без обновления ссылок в HTML/CSS/srcset.
- Rename plan применяется без diff.

### 7.6. Apply/export risks

- Apply происходит без changeset.
- Apply происходит без dry-run и backup.
- Rename/update references падает посередине без rollback.
- Export не включает отчёты.
- После apply невозможно понять, какие SEO-решения были приняты.
- Автопубликация появляется раньше ручного контроля.

## 8. Recommended Development Order

Чтобы не собрать хаос, реализация должна идти так:

```text
1. Project storage + Postgres + Object Storage
2. Project setup screen
3. project source validation
4. project scan
5. scan_versions + reconcile
6. projectIndex
7. baseline audit
8. page workspace with originalText/workingText
9. CodexExecProvider
10. meaning extraction
11. seed review
12. Wordstat MCP integration
13. keywordService
14. keyword map
15. optimization plan
16. rewrite workspace
17. media SEO
18. checkOverseo
19. ru-text
20. final validation report
21. diff + changeset
22. apply with dry-run/backup/rollback
23. export/history
```

Нельзя начинать с rewrite UI до появления `originalText/workingText`, иначе легко получить приложение, которое красиво пишет текст, но не умеет безопасно применять изменения.
