From 4b46936d0b387a7b5ca7028df0d776bddbbe9ca4 Mon Sep 17 00:00:00 2001 From: DCCONSTRUCTIONS Date: Thu, 2 Jul 2026 13:48:04 +0300 Subject: [PATCH] docs: refresh SEO farm architecture notes --- .../SEO-farm/IMPLEMENTATION_GUARDRAILS.md | 43 +- seo_mode/seo_mode/SEO-farm/README.md | 3 +- .../SEO-farm/SEO_FARM_ARCHITECTURE.md | 20 +- seo_mode/seo_mode/SEO-farm/SEO_FARM_BRIEF.md | 25 +- seo_mode/seo_mode/SEO-farm/TASK_MANAGER.md | 1050 ----------------- seo_mode/seo_mode/SEO-farm/UI_UX_SPEC.md | 17 +- seo_mode/seo_mode/SEO-farm/USER_FLOW.md | 2 +- 7 files changed, 69 insertions(+), 1091 deletions(-) delete mode 100644 seo_mode/seo_mode/SEO-farm/TASK_MANAGER.md diff --git a/seo_mode/seo_mode/SEO-farm/IMPLEMENTATION_GUARDRAILS.md b/seo_mode/seo_mode/SEO-farm/IMPLEMENTATION_GUARDRAILS.md index 11de3f6..5602594 100644 --- a/seo_mode/seo_mode/SEO-farm/IMPLEMENTATION_GUARDRAILS.md +++ b/seo_mode/seo_mode/SEO-farm/IMPLEMENTATION_GUARDRAILS.md @@ -126,9 +126,9 @@ Final Validation input: workingText, keyword map, media map, approved media changes output: validation report -Apply / Export +Patch / Export input: approved text/media changes - output: changeset, updated target project, reports/export + output: patch artifact, changeset manifest, reports/export ``` ## 4. Tool Boundaries @@ -231,11 +231,23 @@ Codex через `codex exec` используется для смысловых - предложить alt/caption/filename. ``` -Codex не должен напрямую менять target project до `Apply`. +Codex не должен напрямую менять target project. Любая правка проходит через patch artifact. -## 5. Apply Safety Rules +## 5. Patch Safety Rules -До ручного Apply target project считается read-only. +Исходники сайта всегда считаются read-only для редактора SEO Mode. + +Рабочий контур: + +```text +original source + -> original snapshot + -> editor draft + -> patch artifact near imported source / project storage + -> explicit production patch-run after user confirmation +``` + +Временные черновики, которые видит только редактор, живут в draft storage. Публикуемый результат должен материализоваться как отдельный patch artifact, а не как незаметное изменение source files. Разрешённые изменения после approval: @@ -260,7 +272,7 @@ Codex не должен напрямую менять target project до `Apply - публиковать на хостинг. ``` -Перед Apply UI обязан показать: +Перед production patch-run UI обязан показать: ```text - affected files; @@ -268,18 +280,21 @@ Codex не должен напрямую менять target project до `Apply - media diff; - filename rename plan; - validation status; -- changeset summary. +- patch artifact path/name; +- changeset summary; +- patch-run command/status. ``` -Apply должен идти транзакционно: +Production patch-run должен идти транзакционно: ```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 +1. build patch artifact +2. build changeset manifest +3. run dry-run against copied/current source tree +4. backup affected files to object storage +5. run patch script against source tree only after explicit user confirmation +6. verify references and rename results +7. rollback if any critical step fails ``` ## 5.1. Repeated Scan / Reconcile Rules diff --git a/seo_mode/seo_mode/SEO-farm/README.md b/seo_mode/seo_mode/SEO-farm/README.md index 318e8b9..0eaa149 100644 --- a/seo_mode/seo_mode/SEO-farm/README.md +++ b/seo_mode/seo_mode/SEO-farm/README.md @@ -31,9 +31,10 @@ - `USER_FLOW.md` — пользовательский сценарий. - `IMPLEMENTATION_GUARDRAILS.md` — pipeline, границы инструментов и риски. - `UI_UX_SPEC.md` — UI/UX экраны, состояния и safety-паттерны. -- `TASK_MANAGER.md` — поэтапный план реализации. - `CHECK_OVERSEO_SPEC.md` — спецификация локальной проверки переспама. +Актуальные задачи, статусы и следующий маршрут ведутся в Ops-карточках проекта `NDC PLATFORM`. + ## Зафиксированные архитектурные решения - `Postgres` — основной источник истины. diff --git a/seo_mode/seo_mode/SEO-farm/SEO_FARM_ARCHITECTURE.md b/seo_mode/seo_mode/SEO-farm/SEO_FARM_ARCHITECTURE.md index 715a575..2ca0b18 100644 --- a/seo_mode/seo_mode/SEO-farm/SEO_FARM_ARCHITECTURE.md +++ b/seo_mode/seo_mode/SEO-farm/SEO_FARM_ARCHITECTURE.md @@ -191,10 +191,10 @@ For MVP we start with `local_folder`, but the application should keep the source 18. UI shows report and diff | v -19. User applies changes to target project +19. User materializes approved patch artifact | v -20. User can export archive/reports +20. User runs production patch-run or exports archive/reports ``` MVP works with existing code/text only: @@ -298,11 +298,12 @@ app/ -> ru-text status -> media SEO status - Apply / Export + Patch / Export -> affected files - -> changeset + -> patch artifact + -> changeset manifest -> manual approval - -> apply to target project + -> production patch-run -> zip target project -> export reports @@ -795,14 +796,12 @@ extract text v changeset | + +-- patch artifact near imported source / project storage +-- dry-run +-- backup affected files to object storage - +-- apply through backend + +-- explicit production patch-run +-- verify references/renames +-- rollback on failure - | - v - apply to target project ``` MVP stores one `workingText` draft per source/section. Full draft versioning and rollback history are future enhancements. @@ -816,7 +815,8 @@ Related local docs: - `CHECK_OVERSEO_SPEC.md` - `IMPLEMENTATION_GUARDRAILS.md` - `UI_UX_SPEC.md` -- `TASK_MANAGER.md` + +Актуальные задачи и статусы разработки ведутся в Ops-карточках проекта `NDC PLATFORM`. - Codex exec: https://developers.openai.com/codex/noninteractive - Codex with ChatGPT plan: https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan diff --git a/seo_mode/seo_mode/SEO-farm/SEO_FARM_BRIEF.md b/seo_mode/seo_mode/SEO-farm/SEO_FARM_BRIEF.md index f1f72ab..4f0d72e 100644 --- a/seo_mode/seo_mode/SEO-farm/SEO_FARM_BRIEF.md +++ b/seo_mode/seo_mode/SEO-farm/SEO_FARM_BRIEF.md @@ -302,28 +302,30 @@ Codex получает структурированное задание: Важно: `Apply` нельзя делать после media-правок без повторной финальной проверки. -### 3.14. Apply / Export +### 3.14. Patch / Export -Перед применением UI показывает: +Перед materialize/production patch-run UI показывает: - affected files; - affected sections; - text diff; - media diff; - filename rename plan; +- patch artifact path/name; - validation status. -Пользователь нажимает `Apply to target project`. После apply создаётся changeset и сохраняется история. +Пользователь подтверждает создание patch artifact. Исходники сайта при этом не меняются. Production меняется только отдельным явным patch-run шагом, когда пользователь подтверждает, что выбранный patch можно запускать по source tree. -Безопасный apply-пайплайн: +Безопасный patch-пайплайн: ```text -1. собрать changeset -2. сделать dry-run -3. сохранить backup affected files в object storage -4. применить изменения через backend -5. проверить rename/update references -6. если что-то упало, выполнить rollback +1. собрать patch artifact +2. собрать changeset manifest +3. сделать dry-run против текущего source tree +4. сохранить backup affected files в object storage +5. запустить patch script только после явного подтверждения production patch-run +6. проверить rename/update references +7. если что-то упало, выполнить rollback ``` Export: @@ -1018,4 +1020,5 @@ Media SEO не даёт забыть alt, poster, видео-контекст и - `CHECK_OVERSEO_SPEC.md` — спецификация локального анти-переспам инструмента. - `IMPLEMENTATION_GUARDRAILS.md` — порядок backend pipeline, границы инструментов и риски разработки. - `UI_UX_SPEC.md` — обязательные UI/UX-экраны, компоненты, состояния и safety-паттерны. -- `TASK_MANAGER.md` — поэтапный план реализации с подзадачами и критериями готовности. + +Актуальные задачи, статусы и критерии следующего этапа ведутся в Ops-карточках проекта `NDC PLATFORM`. diff --git a/seo_mode/seo_mode/SEO-farm/TASK_MANAGER.md b/seo_mode/seo_mode/SEO-farm/TASK_MANAGER.md deleted file mode 100644 index 459021e..0000000 --- a/seo_mode/seo_mode/SEO-farm/TASK_MANAGER.md +++ /dev/null @@ -1,1050 +0,0 @@ -# SEO Farm Task Manager - -## 1. Назначение - -Этот документ — рабочий маршрут реализации SEO Farm. - -Цель: не пытаться собрать весь продукт сразу, а идти по этапам, где каждый этап имеет: - -- понятную задачу; -- подзадачи; -- зависимости; -- критерии готовности; -- ссылки на документы; -- минимальный проверяемый результат. - -Статусы для работы: - -```text -not_started -in_progress -blocked -needs_review -done -``` - -## 1.1. Текущий статус реализации - -Дата сверки: 2026-06-24. - -Готово в коде: - -- `Project Bootstrap`: React/Vite UI, Node.js backend, TypeScript, health endpoint. -- `Local Storage / Project Model`: Postgres, MinIO, migrations, project/source/scan/page/media/run tables. -- `Project Setup UI`: создание проекта, импорт папки, drag-and-drop, список проектов, rename/copy/delete. -- `Project Scan / Project Index`: scan папки, stable pages/media, repeated scan, `project-index.json` в MinIO. -- `Baseline Audit`: title/description/H1/headings/visible text/media ALT/filename, page tree, severity filters, media issue list, UI-список ошибок по выбранным страницам. -- `Page Workspace / Draft Model`: preview страницы, ошибки выбранной страницы, логические секции, section editor, save/reset, сохранение draft в Postgres + MinIO без изменения исходного проекта. - -Следующий рабочий этап: - -- Довести `Page Workspace / Draft Model` до полноценного редакторского сценария: клик по preview/DOM-блоку, diff preview, design length hints. - -Осознанный backlog перед расширением scan/audit: - -- Полноценное наполнение `sections/section_versions`. -- Явный список ignored files в `projectIndex`. -- Метаданные `possible entry points` в `projectIndex`: все HTML уже анализируются, это отдельная пометка потенциальных входных страниц, а не ограничение scan. -- Реальная логика `orphaned/conflicted` при repeated scan. -- Визуальная полировка severity filters / media issue list / page tree после стабилизации дизайна. -- Preview/marker backlog после MVP: если сайт полностью собирает или перерисовывает DOM через JS, `data-seo-target-id` может потеряться — нужен `MutationObserver` или Playwright snapshot layer. -- Preview/marker backlog после MVP: canvas/video/сторонние iframe/CSS pseudo-elements нельзя надёжно отметить DOM-точкой; для них нужна привязка к контейнеру или список ошибок рядом с viewer. -- Preview/marker backlog после MVP: сайты с `fetch('/api/...')`, авторизацией, service worker и боевой backend-логикой могут не повторяться в preview на 100%; для SEO-фермы MVP фокусируется на визуальном DOM и полях правки. - -## 2. Главный порядок реализации - -Базовый порядок нельзя ломать: - -```text -Project Storage --> Project Setup --> Project Scan --> Baseline Audit --> Page Workspace --> CodexExecProvider --> Meaning Extraction --> Seeds --> Wordstat --> Keyword Cleaning --> Keyword Map --> Optimization Plan --> Rewrite --> Media SEO --> Final Validation --> Apply / Export --> History / Reports -``` - -Причина: если начать с rewrite или AI-правок до storage/original/working/diff, приложение быстро станет небезопасным. - -## 3. Документы-источники - -- `SEO_FARM_BRIEF.md` — общее ТЗ, цели продукта, MVP scope. -- `SEO_FARM_ARCHITECTURE.md` — архитектура, модули, storage, backend/frontend слои. -- `USER_FLOW.md` — пользовательский сценарий. -- `IMPLEMENTATION_GUARDRAILS.md` — backend pipeline, риски и ограничения. -- `CHECK_OVERSEO_SPEC.md` — спецификация локальной проверки переспама. -- `UI_UX_SPEC.md` — UI/UX-экраны, компоненты, состояния, safety-паттерны. - -## 4. Milestone 0: Project Bootstrap - -Статус: `done` - -### Цель - -Подготовить техническую основу проекта, чтобы дальше не смешивать UI, backend, data и docs. - -### Подзадачи - -- Инициализировать git. -- Инициализировать Vite + React. -- Добавить локальный Node backend. -- Выбрать Express или Fastify. -- Добавить TypeScript, если решаем делать типизированно. -- Поднять локальную инфраструктуру для разработки: - -```text -Postgres -MinIO -``` - -- Добавить `docker-compose.yml` или аналогичный local infra bootstrap. -- Настроить базовую структуру папок: - -```text -app/ -server/ -tools/ -data/ -docs/ -``` - -- Добавить `.gitignore`. -- Добавить `.env.example`. -- Добавить README с командой запуска. - -### Критерий готовности - -- UI запускается локально. -- Backend запускается локально. -- Postgres и MinIO поднимаются локально. -- Есть health endpoint. -- Есть понятная структура проекта. -- Секреты не попадают в git. - -### Документы - -- `SEO_FARM_ARCHITECTURE.md` → Backend Modules, Storage Layout. -- `UI_UX_SPEC.md` → базовая структура интерфейса. - -## 5. Milestone 1: Local Storage / Project Model - -Статус: `done` - -### Цель - -Сделать проектную модель и storage layer, чтобы приложение было сервисом с историей, версиями scan и подготовкой к hosted-режиму. - -### Текущая реализация - -Готово: - -- Postgres migrations; -- MinIO/S3-compatible `StorageProvider`; -- `projects`, `project_sources`, `scan_versions`, `pages`, `page_versions`, `media_assets`, `media_versions`, `runs`; -- таблицы будущих этапов: sections, seeds, wordstat, keyword decisions, drafts, validations, changesets, exports; -- baseline audit хранится в `runs` с `run_type = baseline_audit`, отдельная таблица `audits` пока не нужна; -- `project_sources.type` поддерживает `local_folder`, `browser_folder`, `git_repo`, `zip_upload`, `site_crawl`. - -### Подзадачи - -- Подключить Postgres. -- Подключить MinIO или другой S3-compatible object storage для local/dev. -- Создать таблицы: - -```text -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 -optimization_plans -audits -drafts -draft_items -validations -validation_issues -changesets -changeset_items -exports -``` - -- Сделать `dbService`. -- Сделать `storageProvider`. -- Сделать `projectStorage`. -- Сделать локальный object storage layout: - -```text -projects/ - project-id/ - scans/ - raw/ - snapshots/ - reports/ - backups/ - exports/ -``` - -- Реализовать create/read/update project. -- Реализовать create/read/update project source. -- Хранить `targetProjectPath`. -- Зафиксировать правило: - -```text -Postgres = source of truth -Object storage = artifacts -YAML/JSON/MD = export/debug only -``` - -### Критерий готовности - -- Можно создать проект. -- Проект сохраняется после перезапуска приложения. -- У проекта есть `targetProjectPath`. -- Можно получить список проектов. -- Нет ручного выбора отдельных файлов вместо папки проекта. -- Есть storage provider, который потом можно переключить с MinIO на S3 без смены бизнес-логики. - -### Документы - -- `SEO_FARM_ARCHITECTURE.md` → Storage Layout. -- `USER_FLOW.md` → Project Lifecycle. -- `IMPLEMENTATION_GUARDRAILS.md` → Storage Risks. - -## 6. Milestone 2: Project Setup UI - -Статус: `done` - -### Цель - -Сделать экран создания и открытия проекта. - -### Текущая реализация - -Готово: - -- project name input с автозаполнением по имени выбранной папки; -- импорт папки через browser folder picker; -- drag-and-drop папки; -- ручной абсолютный путь для dev/local режима; -- recent/list projects; -- rename/copy/delete project; -- защита от совпадения названий; -- базовый dashboard в карточке проекта. - -### Подзадачи - -- Экран `Projects / Create Project`. -- Project name input. -- `targetProjectPath` input/picker. -- Path validation. -- Recent projects list. -- Project switcher в top bar. -- Project Dashboard skeleton. - -### Критерий готовности - -- Пользователь создаёт проект из UI. -- Видит путь к target project. -- Видит статус: `scan_required`. -- Не выбирает руками `index.html`, `css`, `images`. - -### Документы - -- `UI_UX_SPEC.md` → 5.1, 5.2. -- `USER_FLOW.md` → Create Project. - -## 7. Milestone 3: Project Scan / Project Index - -Статус: `needs_review` - -### Цель - -Сканировать папку target project, построить `projectIndex` и подготовить reconcile для repeated scan. - -### Текущая реализация - -Готово для текущего MVP-среза: - -- scan импортированной папки из MinIO/browser folder source; -- scan локальной папки через dev/local path; -- HTML pages; -- media/assets; -- stable `pages` и `media_assets`; -- `page_versions` и `media_versions`; -- `scan_versions`; -- `project-index.json` в MinIO; -- repeated scan с `new/matched/changed`; -- сохранение выбора страниц между scan через stable page IDs; -- UI summary по scan result. - -Backlog этого milestone: - -- записывать в `projectIndex` отдельный список ignored files; -- вычислять metadata `possible entry points` для подсказок, не ограничивая scan только `index.html`; -- наполнять `sections/section_versions`; -- реализовать `orphaned/conflicted`; -- расширить parsing для MD/text как отдельных источников. - -### Backend-порядок - -```text -validate targetProjectPath --> scan filesystem --> filter ignored folders/files --> detect candidate files --> parse HTML/MD/text/CSS references --> create scan_version --> build projectIndex --> map pages --> map sections --> map media assets --> reconcile with previous scan_version --> save scan result -``` - -### Подзадачи - -- `projectScanService`. -- Ignore rules: `.git`, `node_modules`, `dist`, build output. -- Найти HTML/MD/text. -- Найти CSS. -- Найти images/video. -- Найти metadata `possible entry points` для подсказок, не ограничивая scan только `index.html`. -- Сохранить `project-index.json`. -- Записать scan_version в Postgres. -- Сохранить raw artifacts в object storage. -- Добавить reconcile statuses: - -```text -matched -changed -new -orphaned -conflicted -``` - -- Привязать решения к stable IDs, а не только к selector. -- UI progress для scan. - -### Критерий готовности - -- На тестовом проекте строится `projectIndex`. -- Видны страницы, секции, медиа. -- Повторный scan не ломает проект и не затирает approvals молча. -- UI показывает scan result. - -### Документы - -- `IMPLEMENTATION_GUARDRAILS.md` → User Flow vs Backend Pipeline. -- `USER_FLOW.md` → Project Scan. -- `UI_UX_SPEC.md` → Scan / Baseline Audit. - -## 8. Milestone 4: Baseline Audit - -Статус: `needs_review` - -### Цель - -Сделать первый смысловой пользовательский этап: аудит проекта/страницы. - -### Текущая реализация - -Готово для текущего MVP-среза: - -- audit запускается после scan/map; -- результат сохраняется в `runs` как `baseline_audit`; -- проверки `title`, `description`, `H1`, heading order, visible text; -- media checks: missing/duplicate/weak ALT, video poster, weak filename; -- duplicate title/description; -- UI summary по выбранным страницам; -- список ошибок сгруппирован по выбранным страницам в порядке page list; -- severity filters по выбранным страницам; -- отдельный media issue list по выбранным страницам и текущему severity filter; -- page tree по путям HTML-страниц; -- показ пачками: ещё 8 / все / свернуть; -- справка по severity и причинам. - -Backlog этого milestone: - -- визуальная полировка severity filters / media issue list / page tree после стабилизации дизайна; -- desktop/adaptive duplicate analysis на уровне секций; -- более глубокий `picture/srcset/source` анализ. - -### Подзадачи - -- `seoAuditService`. -- Проверить: - -```text -title -description -h1/h2 -heading order -visible text -sections -desktop/adaptive duplicates -media objects -alt/title/aria -filename -empty/weak SEO zones -``` - -- UI summary cards. -- Issues table. -- Severity filters. -- Page tree. -- Media issue list. - -### Критерий готовности - -- Пользователь нажимает `Analyze Project`. -- Backend делает scan/parse/map/audit. -- UI показывает понятный baseline audit. -- Пользователь не управляет parse отдельно. - -### Документы - -- `USER_FLOW.md` → Baseline Audit. -- `UI_UX_SPEC.md` → 5.3. -- `IMPLEMENTATION_GUARDRAILS.md` → Pipeline risks. - -## 9. Milestone 5: Page Workspace / Draft Model - -Статус: `needs_review` - -### Цель - -Создать безопасную рабочую область страницы: `originalText` и `workingText`. - -### Текущая реализация - -Готово для текущего MVP-среза: - -- `pageWorkspaceService`; -- создание active draft для страницы из последней успешной `page_version`; -- чтение исходного HTML из `browser_folder`/MinIO или `local_folder`; -- `originalText` snapshot в MinIO; -- `workingText` draft в Postgres и working snapshot в MinIO при сохранении; -- базовый `sectionMap` из title, description и логических HTML-блоков (`section/article/header/main` или fallback по heading-группам); -- preview страницы в sandboxed iframe без выполнения скриптов; -- список ошибок выбранной страницы рядом с preview; -- UI Pages / Source внутри карточки проекта; -- section editor: original read-only + working textarea для выбранной секции; -- save working draft; -- reset section; -- reset working draft к original; -- исходный target project не меняется до будущего Apply. - -Backlog этого milestone: - -- клик по rendered preview/DOM-блоку с переходом к секции; -- diff preview `originalText` vs `workingText`; -- design length hints; -- более точные DOM selectors и наполнение `sections/section_versions`; -- отдельный экран/маршрут Pages / Source, когда UI будет разрастаться. - -### Подзадачи - -- `pageWorkspaceService`. -- Создать `originalText` snapshot. -- Создать `workingText` draft. -- Создать `sectionMap`. -- UI Pages / Source. -- Section list. -- Original preview. -- Working preview. -- Design length hints. -- Reset working draft. - -### Критерий готовности - -- Original нельзя редактировать. -- Working можно редактировать. -- Target project не меняется. -- Draft сохраняется после перезапуска. - -### Документы - -- `USER_FLOW.md` → Page Workspace. -- `UI_UX_SPEC.md` → 5.4. -- `IMPLEMENTATION_GUARDRAILS.md` → Storage Risks. - -## 10. Milestone 6: Model Provider / Codex Exec - -Статус: `not_started` - -### Цель - -Подключить модель через `codex exec`, но архитектурно оставить возможность сменить provider. - -### Подзадачи - -- Интерфейс `ModelProvider`. -- `CodexExecProvider`. -- Запуск через backend task runner. -- Передача prompt. -- Получение stdout/stderr. -- Timeout. -- Error handling. -- Лог run. -- Structured JSON output validation. - -### Критерий готовности - -- Backend может запустить `codex exec`. -- UI видит run status. -- Ошибка модели не ломает проект. -- Результат сохраняется как run. -- Codex не меняет target project напрямую. - -### Документы - -- `SEO_FARM_ARCHITECTURE.md` → Model Provider Abstraction. -- `IMPLEMENTATION_GUARDRAILS.md` → Model risks. - -## 11. Milestone 7: Meaning Extraction / Seeds - -Статус: `not_started` - -### Цель - -Извлечь смысл страницы/секций и seed-запросы из уже существующего текста. - -### Подзадачи - -- Prompt для Meaning Extraction. -- Input: - -```text -originalText -sectionMap -title/description/h1/h2 -media context -``` - -- Output: - -```text -primary_intent -section meanings -product entities -seed queries -competing intents -``` - -- UI Meaning Extraction. -- UI Seeds. -- Seed approval. -- Manual seed add. -- Merge similar seeds. - -### Критерий готовности - -- Seeds связаны с секциями. -- Видна причина seed. -- Пользователь утверждает seeds перед Wordstat. -- Модель не придумывает новый смысл страницы. - -### Документы - -- `USER_FLOW.md` → Meaning Extraction, Seed Review. -- `UI_UX_SPEC.md` → 5.5, 5.6. - -## 12. Milestone 8: Wordstat MCP - -Статус: `not_started` - -### Цель - -Подключить Wordstat MCP как инструмент сбора данных. - -### Подзадачи - -- `wordstatService`. -- Настройка MCP-KV Wordstat. -- Запуск по одному seed. -- Batch run. -- Сохранение raw result. -- Таблица Wordstat. -- Частотность. -- Группы ВЧ/СЧ/НЧ. -- Retry/partial failure states. - -### Критерий готовности - -- По утверждённым seeds собираются Wordstat results. -- Raw data сохраняется. -- Wordstat не принимает SEO-решения. -- UI показывает частотность и source seed. - -### Документы - -- `SEO_FARM_ARCHITECTURE.md` → Wordstat Flow. -- `USER_FLOW.md` → Wordstat Collection. -- `UI_UX_SPEC.md` → 5.7. - -## 13. Milestone 9: Keyword Cleaning - -Статус: `not_started` - -### Цель - -Очистить Wordstat-результаты от мусора с помощью правил, Codex-классификации и ручного утверждения. - -### Подзадачи - -- `keywordService`. -- Normalize. -- Deduplicate. -- Project blacklist. -- Negative intents. -- Group close phrases. -- Mark obvious trash. -- Codex classification for ambiguous phrases. -- UI Keyword Cleaning. -- Bulk actions. -- Undo last bulk action. - -### Критерий готовности - -- У каждого ключа есть proposed status. -- Пользователь может утвердить статус. -- Есть `use/support/article/risky/trash`. -- Мусорные ключи не попадают дальше в map. - -### Документы - -- `SEO_FARM_ARCHITECTURE.md` → Keyword Cleaning Logic. -- `IMPLEMENTATION_GUARDRAILS.md` → Keyword risks. -- `UI_UX_SPEC.md` → 5.8. - -## 14. Milestone 10: Keyword Map - -Статус: `not_started` - -### Цель - -Разложить утверждённые ключи по страницам и секциям без ручной работы с нуля. - -### Подзадачи - -- `keywordMapService`. -- Prompt для keyword-to-section map. -- Roles: - -```text -primary -secondary -supporting -do_not_use_on_page -article_backlog -``` - -- Soft forms. -- Exact limits. -- Section warnings. -- UI Keyword Map. -- Approve/edit suggestions. - -### Критерий готовности - -- Модель предлагает карту. -- Пользователь редактирует и утверждает. -- Видно, почему ключ назначен секции. -- Видно, какие ключи нельзя использовать. - -### Документы - -- `USER_FLOW.md` → Keyword Map. -- `UI_UX_SPEC.md` → 5.9. - -## 15. Milestone 11: Optimization Plan - -Статус: `not_started` - -### Цель - -До переписывания показать, что именно будет меняться. - -### Подзадачи - -- `optimizationPlanService`. -- Sections to edit. -- Sections to leave unchanged. -- Keywords to add/reduce. -- Media SEO tasks. -- Length risks. -- Tone risks. -- UI plan approval. - -### Критерий готовности - -- Пользователь видит план до rewrite. -- Без approval нельзя перейти к rewrite. -- В плане есть text и media tasks. - -### Документы - -- `USER_FLOW.md` → Optimization Plan. -- `UI_UX_SPEC.md` → 5.10. - -## 16. Milestone 12: Rewrite Workspace - -Статус: `not_started` - -### Цель - -Редактировать `workingText` безопасно: вручную и через Codex variants. - -### Подзадачи - -- UI Rewrite Workspace. -- Original locked view. -- Working editor. -- Keyword counters. -- Length indicator. -- Codex variants. -- Accept variant. -- Merge variant. -- Manual edit. -- Reset section. -- Save draft. - -### Критерий готовности - -- Пользователь может переписать одну секцию. -- Видит original и working рядом. -- Keyword counters работают. -- Target project не меняется. -- Изменения попадают в pending changes. - -### Документы - -- `USER_FLOW.md` → Rewrite Workspace. -- `UI_UX_SPEC.md` → 5.11. - -## 17. Milestone 13: Media SEO - -Статус: `not_started` - -### Цель - -Проверить и поправить media SEO: изображения, видео, alt, подписи, filename. - -### Подзадачи - -- `mediaAuditService`. -- Найти media. -- Media table/grid. -- Preview. -- Current/proposed alt. -- Current/proposed filename. -- Decorative toggle. -- Needs-human flag. -- Caption editor. -- Video context. -- Rename plan. - -### Критерий готовности - -- Media элементы видны в UI. -- Можно предложить и утвердить alt/caption/filename. -- Decorative media не получают SEO-alt. -- Rename plan виден до apply. -- Media-правки попадают в pending changes. - -### Документы - -- `USER_FLOW.md` → Media SEO. -- `UI_UX_SPEC.md` → 5.12. -- `IMPLEMENTATION_GUARDRAILS.md` → Media SEO risks. - -## 18. Milestone 14: checkOverseo - -Статус: `not_started` - -### Цель - -Сделать локальную проверку переспама и перетошноты. - -### Подзадачи - -- Реализовать `checkOverseo`. -- Text normalizer. -- Tokenizer. -- Keyword counter. -- Nausea analyzer. -- Water analyzer. -- Proximity analyzer. -- Scope analyzer. -- Report builder. -- Проверка scopes: - -```text -page -section -title -description -heading -alt -filename -``` - -### Критерий готовности - -- Есть отчёт по переспаму. -- Есть section-level warnings. -- Проверяются alt/filename. -- Text.ru API не подключается. - -### Документы - -- `CHECK_OVERSEO_SPEC.md`. -- `IMPLEMENTATION_GUARDRAILS.md` → Tool Boundaries. - -## 19. Milestone 15: ru-text Integration - -Статус: `not_started` - -### Цель - -Подключить ru-text как редакторский фильтр качества SEO-правок. - -### Подзадачи - -- `ruTextService`. -- Запуск ru-text. -- Парсинг результата. -- UI warnings. -- Связать warning с section/field. - -### Критерий готовности - -- ru-text запускается по working text. -- Предупреждения видны в Final Validation. -- ru-text не принимает SEO-решения. - -### Документы - -- `SEO_FARM_BRIEF.md` → Редактор SEO-правок. -- `IMPLEMENTATION_GUARDRAILS.md` → Tool Boundaries. - -## 20. Milestone 16: Final Validation - -Статус: `not_started` - -### Цель - -Проверить текстовые и media-правки перед Apply. - -### Подзадачи - -- `validationService`. -- Собрать results: - -```text -checkOverseo -ru-text -structure checks -competing meaning checks -design length checks -media checks -pending changes -``` - -- Hard errors. -- Soft warnings. -- Validation summary. -- Jump to issue. -- Rerun validation. - -### Критерий готовности - -- Нельзя сделать Apply без Final Validation. -- Hard errors блокируют Apply. -- Soft warnings можно принять вручную. -- Validation учитывает text и media. - -### Документы - -- `USER_FLOW.md` → Final Validation. -- `UI_UX_SPEC.md` → 5.13. - -## 21. Milestone 17: Diff / Pending Changes / Changeset - -Статус: `not_started` - -### Цель - -Показать пользователю всё, что будет изменено. - -### Подзадачи - -- Pending Changes Drawer. -- Diff Viewer. -- Changes table. -- Text diff. -- Meta diff. -- Media diff. -- Filename rename diff. -- Changeset summary. - -### Критерий готовности - -- Пользователь видит `before -> after`. -- Видит affected files. -- Видит affected sections/media. -- Apply невозможен без changeset. - -### Документы - -- `UI_UX_SPEC.md` → Pending Changes Drawer, Diff Viewer, Apply / Export. -- `IMPLEMENTATION_GUARDRAILS.md` → Apply Safety Rules. - -## 22. Milestone 18: Apply / Export - -Статус: `not_started` - -### Цель - -Безопасно применить утверждённые изменения к target project и выгрузить результат. - -### Подзадачи - -- `changesetService`. -- `applyService`. -- `exportService`. -- Dry-run before apply. -- Backup affected files to object storage. -- Apply text/meta/media changes. -- Apply filename rename plan. -- Update references. -- Rollback on failure. -- Save changeset. -- Export zip. -- Export reports. -- Export keyword map. - -### Критерий готовности - -- Target project меняется только после manual Apply. -- Changeset сохраняется. -- Есть backup и rollback path. -- Export создаётся. -- Можно понять, что именно было применено. -- Автопубликации нет. - -### Документы - -- `USER_FLOW.md` → Apply Changes, Export. -- `UI_UX_SPEC.md` → 5.14. -- `IMPLEMENTATION_GUARDRAILS.md` → Apply/export risks. - -## 23. Milestone 19: History / Reports - -Статус: `not_started` - -### Цель - -Дать пользователю вернуться к проекту и понять, что уже было сделано. - -### Подзадачи - -- Run timeline. -- Scan history. -- Baseline audit history. -- Wordstat collections. -- Keyword decisions. -- Keyword maps. -- Optimization plans. -- Rewrite history. -- Validation reports. -- Changesets. -- Exports. - -### Критерий готовности - -- После перезапуска видна история проекта. -- Видны последние runs. -- Видны changesets. -- Видны exports. - -### Документы - -- `USER_FLOW.md` → Project History. -- `UI_UX_SPEC.md` → 5.15. - -## 24. First Vertical Slice - -Статус: `not_started` - -### Цель - -Собрать самый маленький рабочий end-to-end сценарий. - -### Сценарий - -```text -Create one project --> choose source.type = local_folder --> scan targetProjectPath through source adapter --> baseline audit --> select one page --> create working draft --> extract meanings/seeds --> approve seeds --> collect Wordstat for one seed --> clean keywords --> create keyword map for one section --> create optimization plan --> rewrite one section --> edit one related media alt --> final validation --> diff --> apply --> export report -``` - -### Критерий успеха - -- Один SEO-cycle проходит от проекта до apply. -- Target project не меняется до apply. -- Видны pending changes. -- Есть changeset. -- Есть отчёт. - -Если этот slice работает, можно расширять на много страниц, несколько секций, сложные медиа и историю версий. - -## 25. Не делать до первого vertical slice - -- Task manager UI. -- Яндекс Метрика / Вебмастер. -- Автопостинг. -- Облако. -- Многопользовательский режим. -- Полная версионность drafts. -- Codex skills UI. -- Advanced analytics. - -Эти задачи не должны блокировать MVP. diff --git a/seo_mode/seo_mode/SEO-farm/UI_UX_SPEC.md b/seo_mode/seo_mode/SEO-farm/UI_UX_SPEC.md index 2eefe0f..025f199 100644 --- a/seo_mode/seo_mode/SEO-farm/UI_UX_SPEC.md +++ b/seo_mode/seo_mode/SEO-farm/UI_UX_SPEC.md @@ -694,9 +694,9 @@ Soft warnings: - low confidence classification; - stylistic warning. -### 5.14. Apply / Export +### 5.14. Patch / Export -Цель: показать все изменения и применить их только после подтверждения. +Цель: показать все изменения, материализовать patch artifact и запускать production patch-run только после отдельного подтверждения. Обязательные элементы: @@ -708,12 +708,14 @@ Soft warnings: - media diff; - filename rename plan; - validation status; +- patch artifact path/name; - changeset summary; - confirmation checkbox; -- Apply button; +- Build Patch button; +- Run Patch button; - Export button. -Apply должен быть заблокирован, если: +Build Patch должен быть заблокирован, если: - нет финальной проверки; - есть hard errors; @@ -721,6 +723,13 @@ Apply должен быть заблокирован, если: - pending changes пустые; - пользователь не подтвердил changeset. +Run Patch должен быть заблокирован, если: + +- patch artifact не создан; +- dry-run не прошёл; +- пользователь не подтвердил production patch-run; +- source tree изменился после dry-run. + Export: - zip target project; diff --git a/seo_mode/seo_mode/SEO-farm/USER_FLOW.md b/seo_mode/seo_mode/SEO-farm/USER_FLOW.md index ccaa14e..560e480 100644 --- a/seo_mode/seo_mode/SEO-farm/USER_FLOW.md +++ b/seo_mode/seo_mode/SEO-farm/USER_FLOW.md @@ -639,4 +639,4 @@ Projects UI/UX-набор обязательных экранов, компонентов и состояний вынесен в `UI_UX_SPEC.md`. -Пошаговый план реализации с критериями готовности вынесен в `TASK_MANAGER.md`. +Актуальный пошаговый план, статусы и критерии готовности ведутся в Ops-карточках проекта `NDC PLATFORM`.