# SEO Farm User Flow

## 1. Главный принцип

SEO Farm работает как проектный сервис, а не как одноразовая форма.

```text
Пользователь создаёт проект
  -> приложение сканирует сайт
  -> делает baseline audit
  -> пользователь выбирает страницы
  -> система помогает собрать ключи
  -> система предлагает карту ключей
  -> пользователь правит тексты в working copy
  -> checkOverseo ловит переспам
  -> ru-text и редакторские проверки ловят плохой тон
  -> пользователь применяет изменения
  -> история работы сохраняется
```

MVP работает с уже существующим кодом/страницей/текстом. Создание текстов с нуля — отдельный будущий режим.

## 2. Project Lifecycle

### 2.1. Create Project

Пользователь создаёт проект и выбирает папку сайта:

```text
source.type = local_folder
targetProjectPath = C:/path/to/site
```

Пользователь не выбирает вручную `index.html`, `css`, `images` и другие файлы. Приложение само сканирует проект.

На этом шаге сохраняется:

```text
project
  - id
  - name
  - source.type
  - targetProjectPath
  - createdAt
  - updatedAt
  - lastRunAt
```

### 2.2. Project Scan

Приложение сканирует папку проекта и строит `projectIndex`.

Для пользователя это часть одного действия “Проанализировать проект”. Внутри backend обязан соблюдать порядок:

```text
scan filesystem
  -> parse candidate files
  -> create scan_version
  -> build projectIndex
  -> map pages/sections/media
  -> reconcile with previous scan_version
  -> run baseline audit
  -> show audit result in UI
```

Baseline audit не может выполняться до parse/map, но пользователь не должен отдельно управлять техническим парсингом.

`projectIndex` содержит:

```text
projectIndex
  - pages
  - html files
  - markdown/text files
  - css files
  - images
  - videos
  - possible entry points
  - ignored files
```

Repeated scan не должен молча перетирать старые решения. Новый scan обязан:

```text
- создать новый scan_version
- попытаться сматчить page/section/media с прошлой версией
- сохранить stable IDs
- показать reconcile summary: matched/changed/new/orphaned/conflicted
```

Пользователь видит найденные страницы и может:

- выбрать страницу для работы;
- исключить технические/лишние файлы;
- переименовать страницу в UI;
- запустить повторный scan.

### 2.3. Project Dashboard

После scan пользователь попадает в dashboard проекта:

```text
Dashboard
  - список страниц
  - статус baseline audit
  - последние SEO runs
  - незавершённые working drafts
  - последние changesets
  - exports
```

## 3. Baseline Audit

Baseline audit — первый смысловой шаг пользователя после создания проекта.

Технически audit использует parse/scan, но в UI пользователь видит именно “Аудит проекта/страницы”.

Проверяется:

```text
page structure:
  - title
  - description
  - h1/h2
  - heading order

content:
  - видимый текст
  - секции
  - desktop/adaptive дубли
  - потенциальные смысловые блоки

media:
  - img/picture/srcset
  - video/poster/source
  - alt/title/aria
  - filename

technical:
  - missing meta
  - empty headings
  - empty alt
  - duplicate alt
  - obvious weak filenames
```

Результат:

```text
baselineAudit
  - project-level issues
  - page-level issues
  - media issues
  - source mapping
```

## 4. Page Workspace

Пользователь выбирает страницу или текстовый источник из проекта.

Для страницы создаются:

```text
originalText
  - неизменённый снимок текста из target project

workingText
  - рабочая копия для SEO-правок

sectionMap
  - sectionId
  - DOM selector
  - source file
  - original text
  - working text
  - context
```

Codex и пользователь работают только с `workingText`.

Target project не изменяется до ручного `Apply`.

## 5. Meaning Extraction

Codex через `codex exec` анализирует выбранную страницу:

```text
input:
  - originalText
  - sectionMap
  - title/description/h1/h2
  - media context

output:
  - primary_intent
  - section meanings
  - product entities
  - likely seed queries
  - possible competing intents
```

Пользователь видит смысловую карту и может поправить:

- главный смысл;
- смысл секции;
- неверно выделенные сущности;
- лишние seed-запросы.

## 6. Seed Review

UI показывает seed-запросы:

```text
seed
  - phrase
  - source section
  - reason
  - confidence
  - selected true/false
```

Пользователь:

- включает/выключает seeds;
- добавляет свои;
- объединяет похожие;
- помечает приоритет.

После утверждения seeds идут в Wordstat.

## 7. Wordstat Collection

Wordstat MCP — рука в Wordstat.

Для выбранных seeds собираются:

```text
wordstat result
  - seed phrase
  - related query
  - frequency
  - frequency group: high / mid / low
  - dynamics
  - region if available
```

UI должен позволять:

- запускать сбор по одному seed;
- запускать batch;
- видеть raw results;
- повторять сбор;
- сохранять результаты в истории проекта.

## 8. Keyword Cleaning

Это assisted workflow, не ручная таблица с нуля.

`keywordService` делает:

```text
1. normalize
2. remove duplicates
3. apply project blacklist
4. mark obvious trash
5. group close phrases
6. send ambiguous phrases to Codex classification
7. return suggested statuses
```

Статусы:

```text
use
support
article
risky
trash
```

UI:

```text
Keyword Cleaning screen
  - таблица ключей
  - частотность
  - seed source
  - proposed status
  - reason
  - confidence
  - bulk actions
  - filters: high/mid/low/use/trash/risky
```

Пользователь утверждает результат галками и массовыми действиями.

## 9. Keyword Map

Keyword Map не должен быть ручной дрочней.

Система предлагает карту:

```text
keyword -> section
keyword -> role
keyword -> limit
keyword -> soft_forms
```

Codex использует:

- section meanings;
- primary_intent;
- keyword statuses;
- частотность;
- текущий текст секции;
- риск переспама.

Роли:

```text
primary
secondary
supporting
do_not_use_on_page
article_backlog
```

UI:

```text
Keyword Map screen
  - секции страницы слева
  - предложенные ключи справа
  - primary/secondary badges
  - soft_forms
  - exact_limit
  - warnings
  - approve/apply suggestions
```

Пользователь редактирует предложения, но не раскладывает всё с нуля.

## 10. Optimization Plan

Перед переписыванием система собирает план:

```text
optimizationPlan
  - sections to edit
  - sections to leave unchanged
  - keywords to add
  - keywords to reduce
  - media SEO tasks
  - length risks
  - tone risks
```

UI показывает план и просит подтверждение.

Без подтверждения plan не переходит в rewrite.

## 11. Rewrite Workspace

Пользователь выбирает секцию.

UI показывает:

```text
left:
  - originalText
  - current workingText

right:
  - assigned keywords
  - section meaning
  - limits
  - warnings
  - Codex variants
```

Codex предлагает варианты, но не меняет target project.

Пользователь может:

- принять вариант;
- смешать варианты;
- отредактировать руками;
- попросить другой тон;
- попросить ужать текст;
- отменить изменения в working draft.

## 12. Media SEO

Media SEO может идти как отдельный экран или как часть плана оптимизации.

Система находит:

```text
img
picture/source/srcset
video/source/poster
CSS background images
filename
alt/title/aria
captions/context
```

Для каждого media item:

```text
status:
  ok
  missing
  weak
  duplicate
  decorative
  needs-human
```

Codex может предложить:

- alt;
- caption;
- video description;
- filename suggestion.

Правило:

```text
ключ можно встроить в alt/filename/caption,
если он естественно описывает изображение и контекст секции.
```

Не набивать ключи без смысла.

## 13. Final Validation

После текстовых и media-правок запускаются:

```text
checkOverseo:
  - перетошнота
  - заспамленность
  - водность
  - повторы
  - proximity
  - keyword stuffing в alt/filename

ru-text:
  - тон
  - читаемость
  - канцелярит
  - typographic/editorial issues

structure checks:
  - title/description/h1/h2
  - section meaning conflict
  - design length limit

media checks:
  - missing/weak/duplicate alt
  - decorative media
  - video context
  - filename rename plan
```

UI показывает:

- общий статус;
- ошибки;
- предупреждения;
- diff `originalText` vs `workingText`;
- media diff;
- что нужно поправить до apply.

Важно: любые media-правки тоже проходят финальную проверку. Нельзя сделать Media SEO и сразу Apply без Final Validation.

## 14. Apply Changes

Apply — ручной шаг.

Перед применением:

```text
UI shows:
  - files affected
  - sections affected
  - text diff
  - media diff
  - filename rename plan
  - validation status
```

Пользователь нажимает `Apply to target project`.

Приложение:

- создаёт changeset;
- делает dry-run;
- сохраняет backup affected files;
- применяет изменения в target project;
- проверяет rename/update references;
- делает rollback, если критический шаг упал;
- сохраняет отчёт;
- сохраняет run history.

Codex должен получать жёсткое ограничение:

```text
Do not modify application code.
Only modify approved text/media fields in target project:
  - visible text
  - title/description
  - headings
  - alt/title/aria
  - captions
  - approved filenames
```

## 15. Export

После apply пользователь может сделать export:

```text
Export options:
  - zip target project
  - export reports
  - export keyword map
  - export changeset summary
```

Это нужно для ручной заливки на хостинг.

Автопубликации нет.

## 16. Project History

В проекте должна сохраняться история:

```text
history:
  - scans
  - baseline audits
  - Wordstat collections
  - keyword cleaning decisions
  - keyword maps
  - optimization plans
  - rewrites
  - validations
  - changesets
  - exports
```

Это нужно, чтобы:

- вернуться к работе позже;
- понять, что уже сделано;
- подключить Яндекс Метрику/Вебмастер в будущем;
- делать дальнейшие SEO-корректировки.

## 17. Local Storage

MVP локальный, но проектный.

Рекомендуемая модель:

```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
  - exports

Object storage:
  - raw dumps
  - reports
  - snapshots
  - previews / video frames
  - backups
  - export archives
```

Правило:

```text
Postgres = source of truth
Object storage = artifacts
YAML/JSON/MD = export/debug only
```

## 18. Main UI Navigation

```text
Projects
  -> Project Dashboard
    -> Scan / Baseline Audit
    -> Pages
    -> Seeds
    -> Wordstat
    -> Keyword Cleaning
    -> Keyword Map
    -> Optimization Plan
    -> Rewrite
    -> Media SEO
    -> Final Validation
    -> Apply / Export
    -> History / Reports
```

## 19. What Is Not MVP

- создание текстов с нуля;
- автопостинг;
- Яндекс Метрика / Вебмастер;
- полноценная версионность draft history;
- Codex skills;
- облачная версия;
- командная работа.

Эти слои можно добавить позже, когда базовый проектный SEO-цикл стабилен.

## 20. Related Development Guardrails

Технический порядок backend pipeline, зоны ответственности инструментов и риски разработки вынесены в `IMPLEMENTATION_GUARDRAILS.md`.

Важно: этот user flow описывает, как процесс видит пользователь. Внутренний порядок выполнения должен соответствовать guardrails.

UI/UX-набор обязательных экранов, компонентов и состояний вынесен в `UI_UX_SPEC.md`.

Пошаговый план реализации с критериями готовности вынесен в `TASK_MANAGER.md`.
