# SEO Farm UI / UX Spec

## 1. Назначение документа

Этот документ описывает обязательный UI/UX-набор для MVP SEO Farm.

Он не описывает визуальный дизайн в пикселях. Его задача — зафиксировать:

- какие экраны нужны;
- какие элементы управления нужны;
- какие состояния должны быть предусмотрены;
- что пользователь должен видеть перед каждым важным действием;
- где нужны проверки, подтверждения и diff;
- как не превратить процесс обратно в ручную таблицу и хаос.

Task manager пока не проектируем. Он будет отдельным слоем после базового UI/UX.

## 2. Главный UX-принцип

SEO Farm — рабочий инструмент, не лендинг и не чат с моделью.

Пользователь должен видеть:

```text
что найдено
что предложено
почему предложено
что выбрано
что изменится
что ещё опасно
что будет применено
```

Все изменения должны проходить через рабочую копию:

```text
original project
  -> original snapshot
  -> working draft
  -> pending changes
  -> final validation
  -> diff
  -> manual Apply
```

Target project нельзя менять молча.

## 3. Базовая структура интерфейса

Рекомендуемый layout:

```text
Top Bar
  - project switcher
  - current project path
  - run status
  - global actions

Left Navigation
  - Project Dashboard
  - Scan / Baseline Audit
  - Pages / Source
  - Seeds
  - Wordstat
  - Keyword Cleaning
  - Keyword Map
  - Optimization Plan
  - Rewrite
  - Media SEO
  - Final Validation
  - Apply / Export
  - History / Reports

Main Workspace
  - current screen content

Right Inspector
  - selected item details
  - reasons
  - warnings
  - actions

Bottom / Side Run Panel
  - running tasks
  - logs
  - retries
  - errors
```

Левая навигация должна показывать статус этапов:

```text
not_started
running
needs_review
has_errors
approved
applied
```

## 4. Глобальные UI-элементы

### 4.1. Project Switcher

Нужен всегда в верхней панели.

Показывает:

- название проекта;
- `targetProjectPath`;
- дату последнего scan;
- статус последнего run.

Действия:

- открыть другой проект;
- создать проект;
- открыть папку проекта;
- запустить повторный scan.

### 4.2. Pipeline Stepper

Глобальный индикатор этапов:

```text
Scan
Audit
Pages
Seeds
Wordstat
Cleaning
Map
Plan
Rewrite
Media
Final Validation
Apply
```

Назначение:

- показать, где пользователь находится;
- показать, что уже готово;
- показать, что заблокировано;
- не дать перейти к apply без Final Validation.

### 4.3. Run Status Panel

Панель фоновых задач.

Нужна для:

- project scan;
- baseline audit;
- `codex exec`;
- Wordstat collection;
- keyword classification;
- ru-text;
- validation;
- export.

Состояния:

```text
queued
running
done
failed
cancelled
needs_retry
```

Минимальные действия:

- view log;
- retry;
- cancel, если задача ещё безопасно отменяется;
- copy error.

### 4.4. Pending Changes Drawer

Критически важный элемент.

Показывает все изменения, которые уже лежат в working draft, но ещё не применены:

- visible text;
- `title`;
- `description`;
- headings;
- `alt/title/aria`;
- captions;
- filename rename plan;
- changed files.

Должен быть доступен с любого экрана после появления first draft.

Нельзя делать Apply, если pending changes скрыты от пользователя.

### 4.5. Diff Viewer

Обязателен для:

- текстов секций;
- title/description;
- headings;
- alt/caption;
- filename rename.

Минимальные режимы:

```text
side-by-side
inline
changed-only
all-fields
```

Поля diff:

```text
field
source file
selector / media id
before
after
status
warnings
```

### 4.6. Status Badges

Единый набор статусов:

```text
ok
warning
error
needs_review
approved
ignored
applied
```

Для ключей:

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

Для media:

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

## 5. Основные экраны

### 5.1. Projects / Create Project

Цель: создать SEO-проект и указать источник сайта.

Обязательные элементы:

- project name input;
- source type selector: `local_folder` for MVP;
- `targetProjectPath` picker;
- path validation result;
- ignored folders preview: `.git`, `node_modules`, `dist`;
- create project button;
- recent projects list.

Нельзя:

- заставлять пользователя выбирать `index.html`, `css`, `images` руками;
- начинать SEO-cycle без валидного source config.

Состояния:

```text
empty
invalid_path
path_not_accessible
project_created
scan_required
```

### 5.2. Project Dashboard

Цель: показать состояние проекта и быстрый вход в текущую работу.

Обязательные блоки:

- project summary;
- last scan;
- baseline audit status;
- pages count;
- media count;
- pending changes count;
- last runs;
- last changesets;
- latest exports.

Основные действия:

- Analyze Project;
- Continue Draft;
- Open Baseline Audit;
- Open Pending Changes;
- Export latest applied version.

### 5.3. Scan / Baseline Audit

Для пользователя это один сценарий: “Проанализировать проект”.

Backend внутри делает:

```text
scan
  -> parse
  -> map
  -> baseline audit
```

UI показывает не технический parse, а понятный прогресс:

```text
Scanning files
Reading pages
Mapping sections
Checking SEO structure
Checking media
Building report
```

Экран результата:

- found pages;
- found text sections;
- found media;
- missing title/description;
- heading issues;
- media issues;
- duplicate/empty alt;
- weak filenames;
- source mapping warnings.

Нужные компоненты:

- issue summary cards;
- issue table;
- page tree;
- media issue list;
- severity filters;
- open page action.

### 5.4. Pages / Source Workspace

Цель: выбрать страницу или группу страниц и увидеть исходную структуру.

Обязательные элементы:

- page list / page tree;
- section list;
- source file path;
- DOM selector;
- original text preview;
- working text preview;
- meta fields;
- media attached to section;
- design length hints.

Основной UX:

```text
левая колонка: страницы и секции
центр: original / working text
правая колонка: details, warnings, actions
```

Действия:

- create working draft;
- reset working draft;
- mark section ignored;
- open section in Rewrite;
- open section keywords.

### 5.5. Meaning Extraction

Цель: получить смысловую карту страницы и seed-запросы.

Обязательные элементы:

- primary intent card;
- section meaning cards;
- product entities;
- possible competing intents;
- proposed seed queries;
- confidence/reason field;
- approve/edit controls.

Важно:

- seed-запросы должны быть связаны с конкретным смыслом/секцией;
- пользователь должен видеть, откуда seed взялся;
- модель не должна придумывать SEO-направления, которых нет в тексте.

### 5.6. Seeds

Цель: утвердить seed-запросы перед Wordstat.

Компоненты:

- seeds table;
- selected checkbox;
- source section;
- reason;
- confidence;
- priority;
- manual add;
- merge similar;
- send to Wordstat.

Фильтры:

- selected;
- unselected;
- low confidence;
- manual;
- by section.

### 5.7. Wordstat

Цель: собрать реальные запросы и частотность.

Компоненты:

- seed queue;
- run by seed;
- batch run;
- raw results table;
- frequency;
- frequency group: high / mid / low;
- dynamics;
- region;
- source seed;
- raw response link.

Состояния:

```text
not_collected
collecting
collected
partial_failed
rate_limited
needs_retry
```

Важно:

Wordstat не принимает SEO-решения. Он только приносит данные.

### 5.8. Keyword Cleaning

Цель: быстро очистить Wordstat-результаты от мусора.

Компоненты:

- keyword table;
- phrase;
- frequency;
- source seed;
- proposed status;
- reason;
- confidence;
- duplicate group;
- intent tag;
- bulk actions.

Статусы:

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

Фильтры:

- high/mid/low;
- use/support/article/risky/trash;
- low confidence;
- needs review;
- by seed;
- by section candidate.

Действия:

- approve selected;
- mark trash;
- mark article backlog;
- send ambiguous to Codex classification;
- add to blacklist;
- undo last bulk action.

### 5.9. Keyword Map

Цель: разложить утверждённые ключи по страницам и секциям без ручной дрочни.

Главная логика:

```text
модель предлагает карту
пользователь утверждает/редактирует
```

Layout:

```text
левая колонка: страницы/секции
центр: assigned keywords
правая колонка: unassigned / risky / article backlog
```

Компоненты:

- section cards;
- primary keyword selector;
- secondary/supporting keyword chips;
- exact limit input;
- soft forms editor;
- warnings;
- unassigned keywords list;
- apply suggestions button.

Должно быть видно:

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

### 5.10. Optimization Plan

Цель: до переписывания показать, что именно система собирается менять.

Компоненты:

- sections to edit;
- sections to leave unchanged;
- keywords to add;
- keywords to reduce;
- media SEO tasks;
- length risks;
- tone risks;
- approval button.

Важно:

Без утверждения плана нельзя переходить к rewrite.

### 5.11. Rewrite Workspace

Цель: безопасно редактировать тексты в `workingText`.

Layout:

```text
left: originalText
center: workingText editor
right: keywords, limits, warnings, Codex variants
```

Обязательные элементы:

- original text locked view;
- working text editor;
- assigned keywords;
- keyword counters;
- exact limit warnings;
- design length indicator;
- Codex variant cards;
- accept variant;
- merge variant;
- manual edit;
- reset section;
- send to Media SEO / Final Validation queue.

Важно:

- Codex пишет только в working draft;
- originalText нельзя редактировать;
- target project не меняется.

### 5.12. Media SEO

Цель: проверить и поправить изображения, видео, alt, подписи, filename.

Layout:

```text
left: media list
center: preview / frames / context
right: alt/caption/filename editor + warnings
```

Компоненты:

- media table/grid;
- preview;
- file path;
- source references;
- current alt;
- proposed alt;
- current filename;
- proposed filename;
- related section;
- related keywords;
- decorative toggle;
- needs-human flag;
- video context field;
- caption editor;
- rename plan.

Статусы:

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

Правило:

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

### 5.13. Final Validation

Цель: проверить всё вместе перед Apply.

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

- text SEO;
- over-SEO;
- ru-text quality;
- competing meanings;
- design length;
- title/description/h1/h2;
- alt/filename stuffing;
- media issues;
- pending changes.

Компоненты:

- validation summary;
- errors;
- warnings;
- passed checks;
- grouped by page/section/media;
- jump to issue;
- rerun validation;
- mark warning accepted;
- block Apply on hard errors.

Hard errors:

- invalid target path;
- missing working draft;
- malformed model output;
- broken filename references;
- Apply without diff;
- critical validation failed.

Soft warnings:

- weak alt;
- long text;
- risky keyword;
- low confidence classification;
- stylistic warning.

### 5.14. Apply / Export

Цель: показать все изменения и применить их только после подтверждения.

Обязательные элементы:

- affected files;
- affected sections;
- affected media;
- text diff;
- meta diff;
- media diff;
- filename rename plan;
- validation status;
- changeset summary;
- confirmation checkbox;
- Apply button;
- Export button.

Apply должен быть заблокирован, если:

- нет финальной проверки;
- есть hard errors;
- diff не построен;
- pending changes пустые;
- пользователь не подтвердил changeset.

Export:

- zip target project;
- reports;
- keyword map;
- changeset summary.

### 5.15. History / Reports

Цель: сохранить проектную работу и дать вернуться позже.

Компоненты:

- run timeline;
- scan history;
- baseline audit history;
- Wordstat collections;
- keyword decisions;
- keyword maps;
- optimization plans;
- rewrite history;
- validation reports;
- changesets;
- exports.

MVP:

- хранить историю runs и changesets;
- показывать последние отчёты;
- не делать полноценную версионность всех drafts.

## 6. Обязательные таблицы

### 6.1. Keyword Table

Колонки:

```text
phrase
frequency
frequency_group
source_seed
proposed_status
approved_status
intent
section_candidate
confidence
reason
actions
```

### 6.2. Section Table

Колонки:

```text
page
section_id
selector
meaning
original_length
working_length
assigned_primary
assigned_secondary_count
warnings
status
```

### 6.3. Media Table

Колонки:

```text
preview
file
type
section
current_alt
proposed_alt
filename_status
seo_status
needs_human
actions
```

### 6.4. Changes Table

Колонки:

```text
field
file
selector_or_media_id
before
after
validation_status
approved
```

## 7. Обязательные редакторы

### 7.1. Text Editor

Нужен для `workingText`.

Требования:

- не редактировать originalText;
- показывать keyword counters;
- показывать length warnings;
- сохранять draft;
- поддерживать manual edit;
- поддерживать accept/merge Codex variant.

### 7.2. Meta Editor

Поля:

- title;
- description;
- h1;
- h2 map.

Должен показывать:

- before/after;
- length;
- keyword usage;
- duplicates.

### 7.3. Alt / Media Editor

Поля:

- alt;
- title;
- aria-label;
- caption;
- video description;
- proposed filename.

Должен показывать:

- preview;
- section context;
- related keywords;
- stuffing warning;
- decorative toggle.

## 8. Empty / Loading / Error States

Каждый экран должен иметь состояния:

```text
empty
loading
running
success
partial_success
needs_review
error
blocked
```

Примеры:

- Project без scan: показать кнопку Analyze Project.
- Wordstat без seeds: показать, что сначала нужно утвердить seeds.
- Keyword Map без cleaned keywords: заблокировать экран и объяснить почему.
- Apply без final validation: заблокировать Apply.
- Media без найденных медиа: показать empty state, не ошибку.

## 9. Confirmations

Подтверждение нужно для:

- reset working draft;
- bulk mark trash;
- apply changes;
- rename files;
- rerun scan, если есть pending changes;
- accept reconcile result after repeated scan;
- discard pending changes;
- export archive.

Confirmation должен показывать последствия, а не просто “Вы уверены?”.

## 10. UX-защита от хаоса

Нельзя:

- прятать pending changes;
- применять изменения без diff;
- смешивать original и working text;
- давать Wordstat-таблице выглядеть как готовое решение;
- заставлять пользователя вручную раскладывать все ключи с нуля;
- показывать model output без reasons/confidence;
- запускать Apply после Media SEO без Final Validation;
- делать ручной выбор файлов вместо project scan.

Нужно:

- показывать источник каждого предложения;
- показывать причину каждого risky/trash/article статуса;
- давать bulk actions с undo;
- сохранять run history;
- показывать, какой инструмент дал какой warning;
- отделять hard errors от soft warnings.

## 11. MVP UI Scope

MVP должен включать:

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

Можно упростить в первом проходе:

- один проект;
- одна выбранная страница;
- один working draft на секцию;
- простая таблица вместо сложного drag-and-drop;
- простой diff;
- простые reports.

Нельзя упростить:

- `targetProjectPath`;
- source type, currently `local_folder`;
- project scan;
- original vs working separation;
- user approval;
- Final Validation before Apply;
- changeset;
- pending changes visibility.

## 12. Не MVP

Пока не проектируем:

- task manager;
- контент-календарь;
- Яндекс Метрика / Вебмастер;
- автопостинг;
- многопользовательский режим;
- облачную версию;
- полноценную draft versioning;
- advanced analytics dashboard;
- Codex skills UI.

Эти вещи можно добавить после стабильного вертикального сценария.

## 13. Первый вертикальный UI-сценарий

Чтобы не строить всё сразу, первый рабочий проход должен быть таким:

```text
Create Project
  -> Analyze Project
  -> Baseline Audit
  -> Select one page
  -> Create working draft
  -> Extract meanings/seeds
  -> Approve seeds
  -> Wordstat collection
  -> Keyword Cleaning
  -> Keyword Map
  -> Optimization Plan
  -> Rewrite one section
  -> Media SEO for related media
  -> Final Validation
  -> Diff
  -> Apply
  -> Export report
```

Если этот проход работает end-to-end, дальше можно наращивать сложность.
