Документация: этапы по фазам, решения D-026…D-033

- Новый порядок этапов (D-026): фаза 1 — концепт на dev без внешних сервисов (1b сайт, 1c вход, 1d ключи, 1e счёт и демо-оплата, 1f демо-выдача, 1g продления, 1h рефералы); фаза 2 — Telegram; фаза 3 — ALTCHA, ЮKassa, почта, Twenty, Chatwoot, Umami, выдача через API и публичный запуск; фаза 4 — звёзды и эквайринги. - Решения: демо-оплата по списку IP (D-027), выдача ключей через адаптер manual/demo/api (D-028), страницы сайта из блоков Payload (D-029), пересборка через revalidatePath (D-030), RU-адрес у mass (D-031), счётчик свободных серверов (D-032), переводы на 5 языков в каждом этапе (D-033). - Тексты описывают работающий продукт; Вейликс — выделенный IP на общем сервере; Telegram поддержки — @veilix_support; сроки ответа не обещаем; VPN-серверы не ведут журналов. - Ссылки на этапы во всех документах, Q-12 решён (ЮKassa для RUB), R-19 (библиотеки для headless Chromium) сделано. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 03:48:10 +02:00
1 parent 0cad9bae18
commit 515acfb69d
@@ -1,6 +1,6 @@
 # D-016. Платёжные системы по валютам; автосписания — Stripe

-Статус: принято, 20.10.2026. Провайдеры для RUB и криптовалюты выбираются на этапе 4 (Q-12).
+Статус: принято, 20.10.2026. Провайдеры (Q-12): RUB — ЮKassa, только пополнения (этап 3b); криптовалюта — этап 4b.

 ## Решение

@@ -8,8 +8,8 @@
 2. USD — Stripe (карты, сохранение карты, автосписания на переменную сумму, без Stripe Subscriptions) и криптовалюта.
 3. RUB — процессинги, принимающие карты РФ (вероятно, KZ и TR), только пополнения, без автосписаний. ЮKassa — опционально, только пополнения.
 4. Пользователи с картами РФ продлевают ключи с баланса; напоминание — за 3 дня.
-5. Оплата внутри Telegram (Stars) — решаем на этапе 3.
+5. Оплата внутри Telegram (Stars) — решаем на этапе 4a.

 ## Последствия

-На этапе 1 работает только `manual`. Модель данных готова к любому набору провайдеров.
+В фазе 1 работают `manual` и `demo` ([D-027](D-027-demo-payments.md)). Модель данных готова к любому набору провайдеров.
@@ -1,6 +1,6 @@
 # D-017. Статические маркетинговые страницы с пересборкой по событию

-Статус: принято, 20.10.2026.
+Статус: принято, 20.10.2026. Пункт 2 уточнён в [D-030](D-030-revalidate-path.md).

 ## Решение

@@ -10,4 +10,4 @@

 ## Последствия

-До этапа 2 заявки видны в админке Payload и приходят письмом на почту поддержки.
+Подключаются на этапах 3d (Twenty) и 3e (Chatwoot); до них формы — только интерфейс ([D-026](D-026-stage-order.md)).
@@ -1,6 +1,6 @@
 # D-020. Модели ключей dedicated и mass

-Статус: принято, 20.10.2026.
+Статус: принято, 20.10.2026. Уточнено в [D-028](D-028-provisioning-adapter.md) и [D-031](D-031-mass-ru-address.md).

 ## Решение

@@ -9,8 +9,8 @@
 3. Тип ключа определяется полем `type` тарифа.
 4. Подключения гибкие: у ключа любой набор подключений разных видов, поэтому ручная выдача на этапе 1 покрывает любой вариант.
 5. Оплаченный период начинается с момента выдачи ключа.
-6. На этапе 1 WG-конфиги mass — те, что добавил администратор, по странам. Нужна другая страна — через поддержку. Автоматически — на этапе 5.
+6. На этапе 1 WG-конфиги mass — те, что добавил администратор, по странам. Нужна другая страна — через поддержку. Автоматически — на этапе 3g.

 ## Последствия

-Автоматическая выдача (этап 5) создаёт те же подключения, что сейчас добавляет администратор.
+Автоматическая выдача (этап 3g) создаёт те же подключения, что сейчас добавляет администратор.
@@ -0,0 +1,26 @@
+# D-026. Порядок этапов: сначала концепт на dev с демо-режимами
+
+Статус: принято, 22.10.2026. Заменяет порядок этапов 1b–1h и 2–5 из этапа 0.
+
+## Контекст
+
+В прежнем плане внешние сервисы (почта, CRM, платёжные системы, Telegram) появлялись вперемешку с основным функционалом, а продукт целиком можно было проверить только перед запуском. Этапы были крупными.
+
+## Решение
+
+1. Фаза 1 — концепт без внешних сервисов, на dev: сайт, вход, ключи, оплата, выдача, продления, рефералы. Оплата и выдача ключей работают в демо-режимах ([D-027](D-027-demo-payments.md), [D-028](D-028-provisioning-adapter.md)), письма пишутся в журнал.
+2. Фаза 2 — Telegram: MiniApp, основной бот, связь аккаунтов.
+3. Фаза 3 — реальные сервисы по очереди: ALTCHA, ЮKassa, отправка почты, Twenty, Chatwoot, Umami, выдача ключей через API. Последний этап — публичный запуск в prod.
+4. Фаза 4 — звёзды Telegram, западные эквайринги, криптовалюта.
+5. Этапы мелкие: у каждого — результат, который пользователь проверяет сам. Каждый этап делается сразу на 5 языках ([D-033](D-033-translations.md)).
+6. Тексты описывают работающий продукт, а не ограничения текущего этапа: концепт проверяется закрыто, а к публичному запуску всё обещанное работает.
+
+## Рассмотренные варианты
+
+Прежний порядок: сайт, вход, биллинг, ключи, кабинет, рефералы, запуск, затем поддержка, Telegram, платёжные системы и автоматизация.
+
+## Последствия
+
+1. Prod появляется только на этапе 3h, до этого всё работает на dev.
+2. ALTCHA и лимиты nginx — на этапе 3a. Формы до этапов 3d и 3e — только интерфейс, без отправки.
+3. Кабинет делается по частям в этапах, которым нужны его страницы: вход (1c), ключи (1d), покупка и счёт (1e), продления (1g), рефералы (1h).
@@ -0,0 +1,20 @@
+# D-027. Платёжная система «Демо»
+
+Статус: принято, 22.10.2026.
+
+## Контекст
+
+Путь покупки и продления нужно проверить целиком до подключения эквайрингов. Ручной платёж из админки этого не даёт: пользователь не проходит оплату сам.
+
+## Решение
+
+1. Адаптер `demo` в `core/payments/` с тем же интерфейсом, что у настоящих провайдеров, и возможностями «сохранение карты» и «автосписание».
+2. Оплата заказа и пополнение ведут на нашу страницу демо-оплаты с кнопками «Оплатить» и «Отклонить». Результат проводится через `processPayment`, как у настоящей системы.
+3. Демо-привязка карты сохраняет способ оплаты «Демо-карта ···· 4242». Автопродление списывает с неё; неуспешное списание включается в админке — так проверяются повторы и льготный период.
+4. Система видна только запросам с IP из списка в её настройках; пустой список — не видна никому. К пользователю не привязана: до регистрации пользователя ещё нет.
+5. Работает в dev и в prod. `manual` остаётся для администраторов.
+
+## Последствия
+
+1. Покупка, пополнение, привязка карты и продления проверяются без эквайринга.
+2. В prod демо-оплата доступна только с разрешённых IP: ошибка в списке IP дала бы ключи без оплаты, поэтому список проверяется при запуске (этап 3h).
@@ -0,0 +1,23 @@
+# D-028. Выдача ключей через адаптер: ручная, демо, API
+
+Статус: принято, 22.10.2026. Уточняет [D-020](D-020-key-models.md).
+
+## Контекст
+
+Настоящий API выдачи появится позже (этап 3g), а путь «оплатил — получил ключ» нужно проверить уже в концепте.
+
+## Решение
+
+1. Выдача ключа и подключений идёт через адаптер в `core/provisioning/` с единым интерфейсом: выдать ключ, создать WG-конфиг (для устройства, у mass — для страны), отключить подключения ключа.
+2. `manual` — подключения добавляет администратор в админке, как в [D-020](D-020-key-models.md).
+3. `demo` — эмулятор:
+   a. при оплате ключ выдаётся сам: ссылка Happ и подключение к RU-адресу;
+   b. WG-конфиг создаётся по запросу из кабинета;
+   c. данные правдоподобные, но фиктивные: адреса из тестовых диапазонов;
+   d. локация «Установим за 24 часа» выдаётся с задержкой, чтобы было видно состояние «готовится».
+4. `api` — настоящий API выдачи (этап 3g) встаёт на место `demo` без переделки кабинета.
+5. Режим выдачи — настройка сайта.
+
+## Последствия
+
+Администратор в любом режиме может создать ключ и подключения руками.
@@ -0,0 +1,24 @@
+# D-029. Контент страниц сайта — в Payload, страницы из блоков
+
+Статус: принято, 22.10.2026. Уточняет [D-006](D-006-localization.md): тексты страниц — контент, а не интерфейс.
+
+## Контекст
+
+По [06-i18n.md](../06-i18n.md), раздел 7.1, тексты макетов ложились бы в сообщения next-intl, и заголовок главной правился бы только выкладкой. Весь контент должен храниться в CMS.
+
+## Решение
+
+1. Коллекция `pages` (сайт): адрес, заголовок, SEO, блоки; черновики и версии Payload. Порядок и состав секций меняются в админке.
+2. Блоки повторяют секции макетов и общие для обоих брендов. Блок, который показывает данные, рисуется по бренду: у dedicated — выбор локации, у mass — планы.
+3. Тарифы, локации и FAQ остаются отдельными коллекциями. Числа в текстах блоков — подстановки из данных (число стран, устройств, цены), поэтому тексты не расходятся с данными.
+4. В next-intl остаётся только интерфейс: навигация, кнопки, подписи полей и статусов, сообщения форм, страница 404.
+5. Так устроен официальный шаблон Payload (website template).
+
+## Рассмотренные варианты
+
+1. Тексты страниц в next-intl — правка только выкладкой.
+2. Фиксированные поля под каждую страницу — нельзя менять состав и порядок секций.
+
+## Последствия
+
+Правка текста страницы — в админке, страница пересобирается по событию ([D-030](D-030-revalidate-path.md)). Переводы текстов страниц хранятся в Payload.
@@ -0,0 +1,22 @@
+# D-030. Пересборка маркетинговых страниц через `revalidatePath`
+
+Статус: принято, 22.10.2026. Уточняет [D-017](D-017-static-pages.md), пункт 2: пересборка не по тегам.
+
+## Контекст
+
+Страницы читают Payload через Local API, а не через `fetch`, поэтому теги кэша им дала бы только `unstable_cache`. В Next 16 она заменена новой моделью Cache Components (`use cache`), которая меняет рендеринг всего приложения: кабинета, next-intl, оболочек из этапа 1a.
+
+## Решение
+
+1. Хуки Payload после изменения контента сайта (страницы, FAQ, тарифы, локации, страны, сайты, домены, валюты) вызывают `revalidatePath` для layout маркетинговых страниц. Все маркетинговые страницы помечаются устаревшими и пересобираются при следующем заходе.
+2. Запасной вариант — обновление раз в 5 минут — остаётся.
+3. Cache Components рассматриваем вместе с переходом на Payload 4 ([D-002](D-002-payload-version.md)).
+
+## Рассмотренные варианты
+
+1. Теги через `unstable_cache` — заменённый API.
+2. Cache Components сейчас — переделка всего приложения ради точечной пересборки.
+
+## Последствия
+
+Правка в одном бренде пересобирает страницы обоих брендов: около 160 страниц (бренды × языки × валюты × страницы), лениво, при заходе. Нагрузка незаметна.
@@ -0,0 +1,13 @@
+# D-031. RU-адрес в ключах mass
+
+Статус: принято, 22.10.2026. Уточняет [D-020](D-020-key-models.md), пункт 2.
+
+## Решение
+
+1. В ключ mass, как и в ключ dedicated, входит RU-адрес: прямое соединение и мост в обе стороны.
+2. RU-адрес — не локация и не страна тарифа: в число стран он не входит. На сайте mass — «30 стран и российский адрес».
+3. Подключения к RU-адресу (`connections.isRu`) есть у обоих брендов; адаптер выдачи ([D-028](D-028-provisioning-adapter.md)) создаёт их для каждого ключа.
+
+## Последствия
+
+Тексты макетов mass про российский адрес остаются; «включая российскую локацию» заменяется на «и российский адрес».
@@ -0,0 +1,13 @@
+# D-032. Счётчик свободных серверов на сайте
+
+Статус: принято, 22.10.2026.
+
+## Решение
+
+1. Поле локации «Свободных серверов» показывается на сайте рядом со статусом, если оно заполнено: «Серверы в наличии · 12». Пусто — только статус.
+2. До выдачи через API (этап 3g) число вводится вручную. Правка в админке пересобирает страницы за секунды ([D-030](D-030-revalidate-path.md)), поэтому запрос из браузера не нужен.
+3. Когда числа начнут меняться автоматически и часто, добавим обновление из браузера: статичная страница плюс запрос свежих значений.
+
+## Рассмотренные варианты
+
+Показывать только статус — макеты сайта счётчика не показывают, а ручное число может устареть.
@@ -0,0 +1,12 @@
+# D-033. Переводы на 5 языков в каждом этапе
+
+Статус: принято, 22.10.2026. Заменяет пакетный перевод перед запуском ([06-i18n.md](../06-i18n.md), раздел 7).
+
+## Решение
+
+1. Каждый этап делает интерфейс и контент сразу на 5 языках: RU и EN — из макетов и словаря `i18n.js`, de, fr, es — перевод Claude с глоссарием ([06-i18n.md](../06-i18n.md), раздел 8).
+2. Финальная проверка переводов и непереведённых ключей — на публичном запуске (этап 3h).
+
+## Последствия
+
+Глоссарий получает колонки de, fr, es на этапе 1b. Английский запасной вариант остаётся на случай, когда перевода нет.
@@ -9,7 +9,7 @@
 | [D-003](D-003-hosting.md) | Без Docker: всё на хосте, процессы под systemd | принято |
 | [D-004](D-004-environments.md) | Dev и prod на одном сервере под разными пользователями | принято |
 | [D-005](D-005-multitenancy.md) | Сайты — тенанты, домены в базе, маршрутизация по Host | принято, уточнено в D-022 |
-| [D-006](D-006-localization.md) | Переводы: поля Payload и next-intl; 5 языков | принято, уточнено в D-023 |
+| [D-006](D-006-localization.md) | Переводы: поля Payload и next-intl; 5 языков | принято, уточнено в D-023 и D-029 |
 | [D-007](D-007-language-detection.md) | Определение языка; MaxMind через nginx | принято, уточнено в D-024 |
 | [D-008](D-008-uuid.md) | UUID и случайные публичные коды | принято |
 | [D-009](D-009-billing-model.md) | Заказы, платежи, движения по счёту; всё через баланс | принято |
@@ -20,12 +20,20 @@
 | [D-014](D-014-email.md) | Почта: шаблоны в Payload, переключаемый транспорт, без listmonk | принято |
 | [D-015](D-015-telegram-bots.md) | Боты на grammY без n8n; два бота на бренд | принято |
 | [D-016](D-016-payments.md) | Платёжные системы по валютам; автосписания — Stripe | принято |
-| [D-017](D-017-static-pages.md) | Статические маркетинговые страницы с пересборкой по событию | принято |
+| [D-017](D-017-static-pages.md) | Статические маркетинговые страницы с пересборкой по событию | принято, уточнено в D-030 |
 | [D-018](D-018-analytics.md) | Umami на этом сервере и баннер cookies | принято |
 | [D-019](D-019-external-services.md) | Chatwoot и Twenty CRM на отдельном VPS | принято |
-| [D-020](D-020-key-models.md) | Модели ключей dedicated и mass | принято |
+| [D-020](D-020-key-models.md) | Модели ключей dedicated и mass | принято, уточнено в D-028 и D-031 |
 | [D-021](D-021-admin-host.md) | Админка на plc.veilix.cc с доступом по IP | принято |
 | [D-022](D-022-proxy-routing.md) | Proxy: внутренние маршруты по хосту, домены из внутреннего эндпоинта | принято |
 | [D-023](D-023-site-locales.md) | Языки сайта — поле `sites.locales`, домены показывают их часть | принято |
 | [D-024](D-024-locale-redirect.md) | Перенаправление на выбранный язык | принято |
 | [D-025](D-025-referral-days.md) | Реферальный бонус — дни срока ключа, а не деньги | принято |
+| [D-026](D-026-stage-order.md) | Порядок этапов: сначала концепт на dev с демо-режимами | принято |
+| [D-027](D-027-demo-payments.md) | Платёжная система «Демо» | принято |
+| [D-028](D-028-provisioning-adapter.md) | Выдача ключей через адаптер: ручная, демо, API | принято |
+| [D-029](D-029-pages-blocks.md) | Контент страниц сайта — в Payload, страницы из блоков | принято |
+| [D-030](D-030-revalidate-path.md) | Пересборка маркетинговых страниц через `revalidatePath` | принято |
+| [D-031](D-031-mass-ru-address.md) | RU-адрес в ключах mass | принято |
+| [D-032](D-032-free-servers.md) | Счётчик свободных серверов на сайте | принято |
+| [D-033](D-033-translations.md) | Переводы на 5 языков в каждом этапе | принято |