ï»¿

Your IP : 216.73.217.78

Current File : /home/seto/indexator.pm/indexator_prd_mvp.md

# PRD — Indexator MVP

## 1. Общее описание

**Название проекта:** Indexator
**Версия документа:** MVP / v1
**Технологический стек:** отдельный домен, чистый PHP, SQLite, парольная админка

### Идея продукта
Indexator — это веб-инструмент для массовой проверки индексации URL-страниц в Google на основе:
- списка URL,
- загруженного файла со списком URL,
- XML sitemap по ссылке.

Система импортирует URL, выполняет проверку для каждого URL через поисковый запрос вида `site:{url}`, анализирует SERP-ответ и определяет, найден ли в выдаче **именно проверяемый URL**. На выходе пользователь получает:
- количество проиндексированных URL,
- количество не проиндексированных URL,
- список не проиндексированных URL,
- экспорт результатов.

Sitemap в рамках MVP рассматривается **только как источник URL**, а не как объект проверки индексации.

---

## 2. Проблема

SEO-специалистам и владельцам сайтов нужно быстро понимать:
- какие страницы из sitemap или списка URL присутствуют в индексе Google,
- какие страницы не попали в индекс,
- сколько страниц в целом индексируется,
- какие страницы нужно отправить на дополнительную проверку или доработку.

Ручная проверка URL через Google занимает много времени и неудобна для больших наборов страниц.

---

## 3. Цели продукта

### Бизнес-цели
- Дать простой внутренний инструмент для массовой проверки индексации URL.
- Упростить работу с URL из sitemap.
- Быстро получать список URL, которые предположительно не индексируются.

### Пользовательские цели
Пользователь должен иметь возможность:
1. Загрузить URL любым из поддерживаемых способов.
2. Запустить проверку индексации.
3. Увидеть точное количество URL со статусами `indexed` и `not_indexed`.
4. Скачать список не проиндексированных URL.
5. Перепроверить URL позже.

---

## 4. Не-цели MVP

В MVP **не входят**:
- интеграция с Google Search Console API,
- определение официального статуса индексации от Google,
- анализ canonical,
- анализ robots meta / x-robots-tag,
- анализ причин неиндексации,
- multi-user система,
- роли и права доступа,
- публичный доступ к инструменту,
- сложная аналитика и графики,
- проверка sitemap как отдельной индексируемой сущности.

---

## 5. Пользователи

### Основной пользователь
- SEO-специалист
- владелец сайта
- контент-менеджер
- технический специалист

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

---

## 6. Основные пользовательские сценарии

### Сценарий 1. Проверка списка URL
1. Пользователь входит в админку.
2. Создает проект.
3. Вставляет список URL вручную или загружает TXT/CSV.
4. Система валидирует и сохраняет URL.
5. Пользователь запускает проверку.
6. Система проверяет каждый URL.
7. Пользователь видит статистику и список неиндексированных URL.

### Сценарий 2. Проверка sitemap
1. Пользователь входит в админку.
2. Создает проект.
3. Указывает URL XML sitemap.
4. Система загружает sitemap.
5. Если sitemap является sitemap index, система раскрывает дочерние sitemap.
6. Система извлекает URL и сохраняет их в проект.
7. Пользователь запускает проверку.
8. Пользователь получает результаты и экспорт.

### Сценарий 3. Повторная проверка
1. Пользователь открывает проект.
2. Выбирает действие:
- перепроверить все URL,
- перепроверить только `not_indexed`,
- перепроверить выбранные URL.
3. Система создает новые задачи проверки.
4. Пользователь получает обновленные статусы.

---

## 7. Определение индексации URL в MVP

### Продуктовое определение
В MVP URL считается **проиндексированным**, если:
1. выполняется запрос `site:{url}`;
2. в органических результатах SERP найден **exact normalized match** проверяемого URL.

URL считается **не проиндексированным**, если:
1. exact normalized match не найден;
2. даже если по префиксу были найдены другие URL.

### Пример
Проверяем URL:
- `https://domain.com/es`

SERP возвращает:
- `https://domain.com/es/page.html`
- `https://domain.com/es/about`

Но не возвращает:
- `https://domain.com/es`
- `https://domain.com/es/`

Итог:
- `https://domain.com/es` получает статус `not_indexed`.

### Допустимая нормализация для матчинга
Считать совпадением:
- `https://domain.com/es`
- `https://domain.com/es/`

Не считать совпадением автоматически:
- `http://domain.com/es`
- `https://www.domain.com/es`
- `https://domain.com/es/page.html`
- canonical URL другой формы

### Ограничение метода
Метод основан на проверке через `site:` и анализе SERP и является **эвристикой**, а не официальным подтверждением индексации со стороны Google.

---

## 8. Scope MVP

### Входит в MVP
- парольная админка;
- список проектов;
- создание проекта;
- импорт URL:
- вручную,
- через TXT/CSV,
- через XML sitemap URL;
- поддержка `sitemapindex`;
- поддержка `.xml.gz`;
- дедупликация URL;
- хранение URL в SQLite;
- фоновая очередь проверки;
- проверка через запрос `site:{url}`;
- анализ только organic results;
- exact normalized match;
- статусы URL;
- фильтры в таблице;
- экспорт CSV;
- summary block по проекту.

### Не входит в MVP
- анализ причин неиндексации;
- интеграция с GSC;
- автоматические уведомления;
- графики динамики;
- API для внешних клиентов;
- многопользовательский режим.

---

## 9. Функциональные требования

### 9.1. Авторизация
Система должна:
- предоставлять страницу логина;
- пускать в админку по одному паролю;
- хранить пароль в виде `password_hash`;
- использовать PHP session;
- поддерживать logout;
- ограничивать brute-force попытки входа.

### 9.2. Управление проектами
Система должна позволять:
- создать проект;
- просмотреть список проектов;
- открыть проект;
- удалить проект.

У проекта должны быть поля:
- `id`
- `name`
- `domain`
- `source_type`
- `source_reference`
- `status`
- `created_at`
- `updated_at`

### 9.3. Импорт URL
Система должна поддерживать импорт из:
1. текстового поля;
2. TXT/CSV файла;
3. XML sitemap по URL.

Система должна:
- валидировать URL;
- отклонять невалидные строки;
- удалять дубли;
- сохранять отчет импорта:
- imported,
- duplicates,
- invalid,
- skipped.

### 9.4. Обработка sitemap
Система должна:
- загружать XML sitemap;
- поддерживать обычный `urlset`;
- поддерживать `sitemapindex`;
- рекурсивно раскрывать дочерние sitemap;
- поддерживать `.xml.gz`;
- извлекать URL и сохранять их в проект.

### 9.5. Проверка URL
Система должна:
- создавать задачу проверки для каждого URL;
- формировать поисковый запрос `site:{url}`;
- получать SERP-ответ от выбранного search provider;
- анализировать organic results;
- искать exact normalized match;
- записывать статус URL.

### 9.6. Статусы URL
Поддерживаемые статусы:
- `pending`
- `indexed`
- `not_indexed`
- `error`

### 9.7. Просмотр результатов
На странице проекта должны отображаться:
- total URLs
- indexed
- not indexed
- error
- pending
- checked %
- indexation rate %

Таблица URL должна содержать минимум:
- URL
- status
- matched result URL
- last checked at
- source type
- created at
- last error message

### 9.8. Фильтрация и поиск
Пользователь должен иметь возможность:
- фильтровать по статусам;
- искать по URL;
- открывать только `not_indexed`.

### 9.9. Перепроверка
Система должна поддерживать:
- перепроверить все URL;
- перепроверить только `not_indexed`;
- перепроверить выбранные URL.

### 9.10. Экспорт
Система должна поддерживать экспорт в CSV:
- всех URL;
- только `indexed`;
- только `not_indexed`;
- только `error`.

---

## 10. Нефункциональные требования

### Производительность
- система должна уметь обрабатывать большие списки URL без выполнения всей работы в одном HTTP-запросе;
- проверка должна выполняться батчами;
- UI не должен зависать на больших проектах.

### Надежность
- каждая проверка должна быть независимой;
- ошибка по одному URL не должна ломать весь проект;
- задачи должны быть перезапускаемыми.

### Безопасность
- закрытая админка;
- защита от brute force;
- CSRF-защита для форм;
- проект должен быть закрыт от индексации поисковиками.

### Простота деплоя
- система должна разворачиваться на обычном VPS;
- не должна требовать тяжелого окружения;
- должна работать на чистом PHP + SQLite.

---

## 11. Архитектурные решения

### Backend
- чистый PHP без фреймворка;
- SQLite как основная БД;
- cron/worker для фоновой обработки;
- отдельный слой провайдера поисковых запросов.

### Рекомендация
Заложить интерфейс провайдера, например:
- `SearchProviderInterface`

Чтобы позже можно было заменить источник SERP без переписывания бизнес-логики.

### Очередь
Рекомендуется очередь задач в SQLite:
- таблица задач;
- worker запускается cron-ом;
- worker берет ограниченный батч URL;
- обрабатывает;
- обновляет статусы.

---

## 12. Рекомендуемая модель данных

### Таблица `projects`
- `id`
- `name`
- `domain`
- `source_type`
- `source_reference`
- `status`
- `created_at`
- `updated_at`

### Таблица `project_urls`
- `id`
- `project_id`
- `url`
- `normalized_url`
- `status`
- `matched_result_url`
- `last_checked_at`
- `last_error_message`
- `created_at`
- `updated_at`

### Таблица `url_checks`
- `id`
- `project_url_id`
- `query`
- `provider`
- `response_status`
- `results_count`
- `matched_result_url`
- `status`
- `raw_response_excerpt`
- `checked_at`

### Таблица `jobs`
- `id`
- `project_id`
- `project_url_id`
- `type`
- `status`
- `attempts`
- `payload`
- `scheduled_at`
- `started_at`
- `finished_at`
- `error_message`

### Таблица `auth_attempts`
- `id`
- `ip`
- `success`
- `created_at`

---

## 13. Логика проверки URL

### Шаги
1. Получить URL из очереди.
2. Сформировать запрос `site:{url}`.
3. Отправить запрос через провайдер SERP.
4. Получить SERP-ответ.
5. Выделить organic results.
6. Извлечь URL результатов.
7. Выполнить normalised exact match.
8. Если совпадение найдено — статус `indexed`.
9. Если совпадение не найдено — статус `not_indexed`.
10. Если произошла ошибка — статус `error`.
11. Сохранить запись в историю проверок.
12. Обновить агрегированные статусы проекта.

---

## 14. Правила нормализации URL

### Для хранения
- trim пробелов;
- host в lowercase;
- сохранять оригинальный URL отдельно;
- не убирать query params автоматически.

### Для exact normalized match
Считать совпадением только если:
- схема одинакова;
- host одинаковый;
- path одинаковый;
- trailing slash различается только в допустимой форме (`/es` = `/es/`).

Не считать совпадением:
- другой host;
- другой subdomain;
- другой path;
- дочерний path;
- другая схема.

---

## 15. UI / страницы админки

### 15.1. Login page
- пароль
- submit
- сообщение об ошибке

### 15.2. Projects list page
- список проектов
- кнопка Create project
- summary по каждому проекту
- delete project

### 15.3. Create project page
Поля:
- project name
- import mode:
- manual list
- file upload
- sitemap URL

### 15.4. Project details page
Блок summary:
- total URLs
- indexed
- not indexed
- errors
- pending
- checked %
- indexation rate %

Таблица URL:
- URL
- status
- matched result URL
- last checked at
- last error

Действия:
- run check
- recheck all
- recheck not indexed
- recheck selected
- export all
- export indexed
- export not indexed
- export errors

---

## 16. Ошибки и edge cases

Система должна корректно обрабатывать:
- невалидный sitemap URL;
- битый XML;
- недоступный sitemap;
- пустой sitemap;
- дубли URL;
- невалидные URL;
- таймауты провайдера;
- пустой SERP;
- rate limit провайдера;
- частично завершенные задания.

---

## 17. Метрики успеха MVP

MVP считается успешным, если пользователь может:
1. создать проект;
2. импортировать URL из списка, файла или sitemap;
3. запустить проверку;
4. получить число `indexed` и `not_indexed`;
5. скачать список `not_indexed`;
6. перепроверить URL позже.

### KPI продукта
- время создания проекта: < 3 минут;
- отсутствие падения UI на больших проектах;
- прозрачная статистика по статусам URL;
- быстрый экспорт неиндексированных URL.

---

## 18. Критерии приемки MVP

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

### Импорт URL
- ручной список импортируется;
- TXT/CSV импортируется;
- XML sitemap импортируется;
- sitemap index раскрывается;
- `.xml.gz` поддерживается;
- дубли не создают повторные записи.

### Проверка
- для каждого URL создается задача;
- система обрабатывает задачи в фоне;
- exact normalized match определяет статус;
- дочерние URL не считаются совпадением.

### Результаты
- статистика проекта отображается корректно;
- список `not_indexed` доступен в интерфейсе;
- экспорт CSV работает.

---

## 19. Рекомендации по следующей фазе

После MVP можно добавить:
- интеграцию с Google Search Console;
- проверку только новых URL;
- расписание автоперепроверок;
- email/Telegram уведомления;
- графики динамики;
- анализ canonical и redirect;
- причины неиндексации;
- multi-user режим.

---

## 20. Краткое итоговое решение

Indexator MVP — это закрытый PHP-инструмент на SQLite для массовой проверки URL из списка или sitemap, где индексация определяется через `site:{url}` и exact normalized match URL в organic results. Продукт должен показывать количество индексируемых URL, список неиндексируемых URL и позволять выгружать результаты в CSV.