NODEDC_SEO/seo_mode/seo_mode/SEO-farm/USER_FLOW.md

SEO Farm User Flow

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

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

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

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

2. Project Lifecycle

2.1. Create Project

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

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

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

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

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

2.2. Project Scan

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

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

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 содержит:

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

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

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

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

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

2.3. Project Dashboard

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

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

3. Baseline Audit

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

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

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

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

Результат:

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

4. Page Workspace

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

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

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 анализирует выбранную страницу:

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-запросы:

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

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

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

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

7. Wordstat Collection

Wordstat MCP — рука в Wordstat.

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

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 делает:

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

Статусы:

use
support
article
risky
trash

UI:

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

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

9. Keyword Map

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

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

keyword -> section
keyword -> role
keyword -> limit
keyword -> soft_forms

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

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

Роли:

primary
secondary
supporting
do_not_use_on_page
article_backlog

UI:

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

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

10. Optimization Plan

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

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 показывает:

left:
  - originalText
  - current workingText

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

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

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

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

12. Media SEO

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

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

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

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

status:
  ok
  missing
  weak
  duplicate
  decorative
  needs-human

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

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

Правило:

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

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

13. Final Validation

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

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 — ручной шаг.

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

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 должен получать жёсткое ограничение:

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:

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

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

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

16. Project History

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

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

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

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

17. Local Storage

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

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

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

Правило:

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

18. Main UI Navigation

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.

Актуальный пошаговый план, статусы и критерии готовности ведутся в Ops-карточках проекта NDC PLATFORM.