# Правила подготовки материалов ТСЖ Портала для ИИ Эти правила применяются к статьям (`article`), новостям (`news`) и судебной практике (`court_case`), создаваемым или изменяемым через REST API и MCP. Документация API: ## 1. Перед созданием 1. Выполнить поиск по ключевым словам, точному заголовку и близким формулировкам. Не создавать дубликат существующего материала. 2. Правильно выбрать тип: статья — `article`, новость — `news`, судебный акт — `court_case`. 3. Если пользователь явно не потребовал немедленную публикацию, создавать материал со статусом `draft`. 4. Не придумывать категорию, автора, источники, номер дела, суд или дату решения. Если данных нет, оставить необязательное поле пустым. ## 2. Заголовок, анонс и текст - Заголовок должен точно описывать тему и не состоять из общих слов или рекламных обещаний. - `excerpt` — самостоятельный краткий анонс. Он не должен дословно повторять заголовок, весь первый абзац или единственную фразу материала. Если отдельного анонса нет, поле лучше оставить пустым. - `content` для статьи и новости обязателен. Использовать простую семантическую HTML-разметку: абзацы, подзаголовки, списки, таблицы и ссылки. - Запрещены исполняемый код, обработчики событий, формы, iframe и опасные URL. API дополнительно очищает HTML. - Не повторять заголовок или один абзац много раз для искусственного увеличения объёма. - Не утверждать, что материал защищён регистрацией или подпиской, если на сайте фактически не реализовано такое ограничение доступа. ## 3. Достоверность и источники - Не выдумывать нормы права, реквизиты документов, цитаты, ссылки и судебные дела. - Для юридических утверждений по возможности указывать первичные источники: официальный НПА, карточку суда, ведомство или официальный документ. - Все использованные веб-источники передавать в `source_urls`. - Для новости проверять актуальность и дату события. Для судебной практики точно заполнять `case_number`, `court_name` и `decision_date`, если они известны. - Если факт не проверен, не представлять его как установленный. ## 4. Статусы и доступ - `draft` — безопасный черновик, не виден обычным посетителям. - `published` — публичный материал. Устанавливать только по прямому поручению пользователя или после явного редакционного подтверждения. - `archived` — мягкое удаление. Запись и журнал действий сохраняются. - Текст «доступно зарегистрированным пользователям» сам по себе не ограничивает доступ. Для реального закрытого материала нужен отдельный механизм авторизации читателей. ## 5. Изменение без потери чужой работы 1. Перед PATCH получить свежий материал через `get_material` или `GET /api/v1/materials/{type}/{id}`. 2. Передавать `expected_version`. 3. При HTTP 409 заново прочитать материал и применить только запрошенные пользователем изменения. 4. Не возвращать прежний статус, категорию или другие поля, если их параллельно изменил другой редактор. ## 6. SEO, индексация и метаданные Отдельных полей `tags`, `keywords`, `meta_title` и `og_image` у статей и новостей **нет**. Поисковая и социальная разметка собирается на стороне сайта из обычных полей материала. ### Что реально влияет на SEO | Поле / механизм | Эффект | |---|---| | `title` | ``, `og:title`, `headline` в Schema.org | | `excerpt` | `meta description`, `og:description`; если пусто — берётся обрезка `content` | | `category_id` | рубрика на странице, «похожие» материалы, хвост `meta keywords`, `articleSection` в JSON-LD | | `author` | мета author и автор в Schema.org | | `slug` | канонический URL `/article.php?slug=...` | | `status=published` | публичная страница + попадание в `/sitemap.xml` | | `featured` | выделение в списках портала, не отдельный SEO-тег | | `source_urls` | редакционная прозрачность; в `<head>` как keywords не уходят | Автоматически на странице материала выводятся: `canonical`, `robots` (`index, follow` для опубликованного), Open Graph, Twitter Card, JSON-LD `Article` и хлебные крошки (`includes/seo.php`, `article.php`). ### Правила для ИИ при публикации 1. Для публикуемого материала **всегда указывать `category_id`**, если рубрика известна. Без категории страница показывает «Общие вопросы», слабее связывается с разделом и не попадает в фильтр рубрики. 2. Типовые категории: `1` Управление ТСЖ (`management`), `2` Финансы и учет (`finance`), `3` Техническое обслуживание (`maintenance`), `4` Правовые вопросы (`legal`), `5` Документооборот (`documents`). Юридические разборы — обычно `4`. 3. `excerpt` писать как самостоятельный анонс на 1–2 предложения (примерно до 160 символов по смыслу): именно он чаще всего становится description в выдаче и превью в соцсетях. 4. Не пытаться передать через API несуществующие `tags` / `keywords` / `seo_*` — они будут проигнорированы или вызовут ошибку валидации. 5. Не набивать текст и заголовок повторами ради «ключевых слов». Достаточно точного заголовка, нормального анонса и уместных терминов в тексте. 6. После публикации проверить: публичный URL открывается, в `<head>` есть description/canonical/og, материал есть в `https://tsj.lawday.ru/sitemap.xml`. 7. Черновики (`draft`) в карту сайта не попадают и не должны индексироваться как публичные страницы. ### Индексация на портале - Карта сайта: `https://tsj.lawday.ru/sitemap.xml` (динамически из `sitemap.php`). - `robots.txt` в репозитории указывает на эту карту и закрывает `/admin/`, `/api/` и служебные каталоги. - RSS-лента пока не реализована (на странице «О портале» — «Скоро»). Не ссылайтесь на несуществующий feed. ## 7. Обязательная проверка после записи 1. Проверить HTTP-код и `success`/`isError` в ответе. 2. Повторно прочитать материал и сравнить заголовок, текст, статус, категорию, источники и `version`. 3. Проверить поиск по характерному слову из заголовка. 4. Для `draft` убедиться, что публичная страница недоступна; для `published` — что она открывается и визуально выглядит корректно; для SEO дополнительно проверить description, категорию и наличие URL в sitemap. 5. Проверить, что анонс не дублирует основной текст, ссылки работают, а HTML не повреждён очисткой. 6. При существенном изменении проверить журнал через `?events=1`. ## 8. Короткая инструкция для нового ИИ-чата ```text Работай с материалами ТСЖ Портала по правилам: https://tsj.lawday.ru/apidocs.php#guidelines Перед созданием ищи дубликаты. Создавай draft, если публикация явно не поручена. Не выдумывай факты и источники. Не дублируй заголовок, анонс и текст. Для публикации указывай category_id и осмысленный excerpt (это description для SEO). Не передавай несуществующие tags/keywords — у статей их нет в API. Перед изменением получай свежую version и используй expected_version. После записи повторно прочитай материал, проверь поиск, публичную видимость и sitemap. ``` ## 9. Локальный конвейер черновиков Если работа ведётся внутри репозитория, сырые идеи сначала сохраняются в `content-drafts/inbox`, а не в базе сайта. Далее файл последовательно перемещается в `working`, `ready` и `published`. Запись в портале создаётся только по отдельному поручению и после проверок из раздела 7. Структура и шаблон описаны в `content-drafts/README.md`.