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

SEO Farm UI / UX Spec

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

not_started
running
needs_review
has_errors
approved
applied

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

4.1. Project Switcher

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

Показывает:

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

Действия:

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

4.2. Pipeline Stepper

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

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.

Состояния:

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.

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

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

Поля diff:

field
source file
selector / media id
before
after
status
warnings

4.6. Status Badges

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

ok
warning
error
needs_review
approved
ignored
applied

Для ключей:

use
support
article
risky
trash

Для media:

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.

Состояния:

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 внутри делает:

scan
  -> parse
  -> map
  -> baseline audit

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

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:

левая колонка: страницы и секции
центр: 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.

Состояния:

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.

Статусы:

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

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

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

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

Layout:

левая колонка: страницы/секции
центр: 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:

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:

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.

Статусы:

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. Patch / Export

Цель: показать все изменения, материализовать patch artifact и запускать production patch-run только после отдельного подтверждения.

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

• affected files;
• affected sections;
• affected media;
• text diff;
• meta diff;
• media diff;
• filename rename plan;
• validation status;
• patch artifact path/name;
• changeset summary;
• confirmation checkbox;
• Build Patch button;
• Run Patch button;
• Export button.

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

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

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

• patch artifact не создан;
• dry-run не прошёл;
• пользователь не подтвердил production patch-run;
• source tree изменился после dry-run.

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

Колонки:

phrase
frequency
frequency_group
source_seed
proposed_status
approved_status
intent
section_candidate
confidence
reason
actions

6.2. Section Table

Колонки:

page
section_id
selector
meaning
original_length
working_length
assigned_primary
assigned_secondary_count
warnings
status

6.3. Media Table

Колонки:

preview
file
type
section
current_alt
proposed_alt
filename_status
seo_status
needs_human
actions

6.4. Changes Table

Колонки:

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

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

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 должен включать:

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-сценарий

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

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, дальше можно наращивать сложность.