agent-ecosystem/landing/docs/ARCHITECTURE_GUARDRAILS.md
iliya e6e89d4ebc fix(tests): improve messageId generation for legacy inbox rows
- Enhanced tests to ensure consistent messageId generation for legacy inbox rows lacking a messageId.
- Updated test descriptions for better clarity regarding the new messageId handling.
- Adjusted test expectations to align with the updated behavior of relaying legacy inbox rows with generated messageIds.
2026-03-23 16:31:37 +02:00

3.5 KiB
Raw Permalink Blame History

Архитектурные инварианты (Landing)

Этот файл — про правила, которые защищают лендинг от “тихой деградации” (SEO/SSG/перф/поддерживаемость). Если правило нарушается — это не вкусовщина, это потенциальный регресс.

1) SSG — не обсуждается

  • Лендинг деплоится как статик. Мы не рассчитываем на backend на каждый запрос.
  • Любые идеи “а давайте по IP определим язык/страницу” — это отдельная задача (edge/runtime), не часть текущего лендинга.

2) Контент и i18n — два слоя

  • Микрокопирайт (кнопки/лейблы/мелкие подписи) — landing/locales/*.
  • Контент секций (FAQ, список фич, провайдеры, тексты блоков) — landing/content/{locale}.* с одинаковой структурой.
  • Стабильные id:
    • id элементов (FAQ/фичи/провайдеры) не меняем.
    • Меняем текст — да. Меняем id — только если сознательно ломаем совместимость и понимаем последствия.

3) Store-лимиты (чтобы не раздуть проект)

Pinia используем только там, где реально есть общий state:

  • theme (dark/light)
  • locale (выбранный язык)
  • download (os/arch/preferredMacArch/selectedAsset)

Всё остальное — props + данные/контент. Никаких “store для секции Features”.

4) Источник правды по URL (i18n + SSG + sitemap)

Один источник правды:

  • список поддерживаемых локалей
  • список страниц, которые должны существовать
  • правила генерации i18n-роутов

Из этого должны получаться:

  • пререндер-роуты для SSG
  • sitemap
  • корректные alternate/canonical

5) Downloads — ответственность и процесс обновления

  • Есть один способ обновлять релизы/ссылки, понятный команде.
  • Если используем статичный landing/data/downloads.ts:
    • обновление версии/URL/sha/размера — часть релиз-процесса
    • перед деплоем прогоняем быструю проверку ссылок (хотя бы HEAD/GET на 200)

6) Аналитика и согласие

  • По умолчанию не отправляем аналитику до пользовательского действия, если проекту нужен consent (зависит от политики/юрисдикции).
  • Никаких персональных данных, никаких “текстов транскрипций”, никаких ключей.

7) Минимальные бюджеты качества

  • Главная страница: Lighthouse без красных метрик (LCP/CLS).
  • A11y: клавиатура/фокус/label/alt — не “по настроению”, а обязательный критерий готовности.