# Глобальный план проекта WG Paid

Версия: **20260711-123348 UTC**

Это immutable timestamped-версия глобального roadmap.

## Статусы

- `[x]` — завершено и принято.
- `[~]` — реализовано частично или требует production-включения.
- `[ ]` — не выполнено.
- `[!]` — активный блокер.

## Текущая позиция

- Runtime-фаза MGTS подтверждена через:
  `STEP_050H2_SALVAGE_COUNTER_STATE_AFTER_GUARD_TEST`.
- Документационный baseline подтверждён через:
  `STEP_050H3C2_SALVAGE_EVIDENCE_PLAN_LINK_CONTRACT`.
- Следующий runtime-step:
  `STEP_050I_ENABLE_EMERGENCY_COMMIT_AND_THRESHOLD_DRYRUN_ONLY`.
- Активных production-блокеров сейчас нет.
- Реальный emergency HMN refresh пока не разрешён.
- Direct failopen выключен.

# Направление A. Автономный MGTS VPN runtime

Цель: MGTS-площадка самостоятельно обслуживает клиентский трафик,
распределяет клиентов по VPN-слотам и восстанавливает egress без
зависимости от пользовательского веб-интерфейса.

## A1. Базовая площадка и сеть

- [x] Proxmox `pve-wg-paid` развёрнут.
- [x] VM100 core OpenWRT развёрнута.
- [x] VM101 edge OpenWRT развёрнута.
- [x] VM105 control panel развёрнута.
- [x] Статический WAN `95.165.105.4` настроен.
- [x] DNS `wg-studio.secret-studio.ru` используется.
- [x] Admin WG endpoint `:51820` работает.
- [x] Paid WG endpoint `:51830` работает.
- [x] Автозапуск VM100 и VM101 настроен.

## A2. WG Paid и пять egress-слотов

- [x] `wg_paid` создан на VM100.
- [x] Пять тестовых peers cs1..cs5 созданы.
- [x] Пять DSCP-классов доказаны реальным трафиком.
- [x] Mapping cs1..cs5 → marks 0x201..0x205 доказан.
- [x] Tables 201..205 имеют default routes.
- [x] vpn1..vpn5 проходят strict-проверки.
- [x] Selector на VM100 работает.
- [x] Mapper на VM101 работает.
- [x] Конфигурация переживает service restart.
- [ ] Полный reboot/failover test всей площадки.
- [ ] Длительный soak test под production-нагрузкой.

## A3. Slot health и repair

- [x] Health watcher установлен и healthy.
- [x] Dispatcher/adapter repair path работает.
- [x] Реальный repair vpn2 доказан.
- [x] Старый endpoint записывается в quarantine.
- [x] Daily repair counter увеличивается.
- [x] Planner исключает quarantined endpoint.
- [x] STEP_050E salvaged через STEP_050E2.
- [x] Production counter подтверждён равным 1.
- [x] Quarantine содержит не менее двух записей.

## A4. Emergency HMN refresh

- [x] Emergency-refresh skeleton установлен.
- [x] Decision-only hook установлен, enabled и running.
- [x] Below-threshold dry-run работает.
- [x] Threshold `would_run_emergency_refresh` доказан.
- [x] Commit guard корректно запрещает commit.
- [x] STEP_050G salvaged через STEP_050G2.
- [x] STEP_050H salvaged через STEP_050H2.
- [ ] STEP_050I:
      разрешить только commit-decision/threshold dry-run.
- [ ] Reviewed-step реального HMN refresh.
- [ ] Проверка нового server pool.
- [ ] Валидация pool новее quarantine timestamp.
- [ ] Top5 rebuild после успешного refresh.
- [ ] Контролируемый rebalance apply.
- [ ] Проверка возврата в NORMAL.

## A5. Degraded и аварийные состояния

- [ ] Реализовать `DEGRADED_NO_FRESH_POOL`.
- [ ] Добавить операторскую сигнализацию.
- [ ] Реализовать `VPN_EXHAUSTED`.
- [ ] Определить timeout и retry policy.
- [ ] Direct failopen — отдельный крайний этап.
- [ ] Автоматический возврат из direct failopen.
- [ ] External HMN access recovery strategies:
  - last-known pool probe;
  - reserve WG tunnel в Деденево;
  - другой клиент/site;
  - другой known-good egress;
  - manual operator rescue.

## A6. Allocator и реальные клиенты

- [~] Контракт allocator и dry-run логика подготовлены.
- [ ] Production allocator включён.
- [ ] Балансировка новых клиентов по пяти слотам.
- [ ] Политика перераспределения существующих клиентов.
- [ ] Ограничения вместимости слота.
- [ ] Миграция клиентов с домашней площадки.
- [ ] Первый production-клиент на MGTS.
- [ ] Массовый onboarding.
- [ ] Production metrics и capacity planning.

# Направление B. VM121 — backend и пользовательский веб-контур

Цель: управлять клиентами, подписками, выдачей доступов и
пользовательским взаимодействием.

## B1. Backend и база

- [x] VM121 `wg-access-dev` развёрнута.
- [x] Docker backend и PostgreSQL работают.
- [x] Health endpoint работает.
- [x] Создание пользователей/peers/subscriptions реализовано.
- [x] Enable/disable peer jobs реализованы.
- [x] Agent/reconcile с VM100 работает.
- [x] Cancel subscription реализован.
- [x] Expire subscription реализован.
- [x] Expiration maintenance endpoint реализован.
- [x] Expiration systemd timer работает.
- [x] Pending jobs контролируются.
- [~] Backup/restore базы проверялся на отдельных checkpoint,
      но требуется финальный production runbook.
- [ ] Production migration/versioning базы.
- [ ] Полный audit trail.

## B2. Пользовательский доступ

- [ ] Регистрация и аутентификация клиента.
- [ ] Защищённая пользовательская сессия.
- [ ] Выдача invite.
- [ ] Активация invite.
- [ ] Генерация WireGuard-конфигурации.
- [ ] Выдача QR-кода.
- [ ] Повторное скачивание конфигурации.
- [ ] Отзыв и перевыпуск конфигурации.
- [ ] Личный кабинет клиента.
- [ ] Просмотр срока подписки.
- [ ] Управление устройствами клиента.

## B3. Административный интерфейс

- [ ] Список клиентов.
- [ ] Список подписок.
- [ ] Список peers и активных слотов.
- [ ] Ручное enable/disable.
- [ ] Просмотр jobs и ошибок reconcile.
- [ ] Управление тарифами.
- [ ] Просмотр платежей.
- [ ] Просмотр runtime health MGTS.
- [ ] Управление аварийными состояниями.
- [ ] Audit log действий администратора.

## B4. Production security и эксплуатация

- [ ] Финальная схема секретов.
- [ ] Rotation ключей.
- [ ] Ограничение административных endpoints.
- [ ] Rate limiting.
- [ ] Backup policy.
- [ ] Restore drill.
- [ ] Централизованные логи.
- [ ] Метрики и alerting.
- [ ] Privacy/data-retention policy.
- [ ] Production deployment pipeline.

# Направление C. ЮKassa и платёжный контур

Цель: связать подтверждённую оплату с подпиской и доступом WireGuard.

## C1. Платёжная модель

- [ ] Зафиксировать тарифы.
- [ ] Зафиксировать расчётный период.
- [ ] Определить trial/grace period.
- [ ] Определить правила продления.
- [ ] Определить правила отмены.
- [ ] Определить правила возврата.

## C2. Интеграция ЮKassa

- [ ] Создание платежа.
- [ ] Idempotency key.
- [ ] Redirect/confirmation flow.
- [ ] Webhook endpoint.
- [ ] Проверка подлинности webhook.
- [ ] Идемпотентная обработка webhook.
- [ ] Связь payment → subscription.
- [ ] Успешная оплата → peer enable.
- [ ] Просрочка → peer disable.
- [ ] Возврат → корректировка подписки.
- [ ] Retry и reconciliation платежей.

## C3. Касса и документы

- [ ] Зафиксировать схему онлайн-кассы.
- [ ] Определить фискальные позиции.
- [ ] Настроить чеки прихода.
- [ ] Настроить чеки возврата.
- [ ] Сопоставить чек и payment.
- [ ] Хранить платёжные идентификаторы.
- [ ] End-to-end тест оплаты и чека.

## C4. Пользовательский платёжный UX

- [ ] Страница выбора тарифа.
- [ ] Страница оплаты.
- [ ] Статус платежа.
- [ ] История платежей.
- [ ] Продление подписки.
- [ ] Уведомление об окончании.
- [ ] Уведомление об ошибке оплаты.

# Направление D. Операторская инфраструктура и сохранение контекста

- [x] VM130 `router-ops` развёрнута.
- [x] Access inventory создан.
- [x] Канонический nested SSH к MGTS VM100/VM101 зафиксирован.
- [x] Актуальная timestamped XS Map опубликована.
- [x] Локальный архитектурный план опубликован.
- [x] Evidence chain G → G2 → H → H2 закреплена.
- [x] STEP_050H3D — глобальный план создан;
      станет завершённым после link-contract validation.
- [x] Контракт четырёх обязательных ссылок внедрён этим шагом.
- [ ] Автоматически включать три постоянные ссылки
      во все будущие STEP scripts.
- [ ] Автоматически переиздавать локальный план после milestone.
- [ ] Переиздавать XS Map при изменении доступа.
- [ ] Переиздавать global plan после существенного этапа.
- [ ] Финальные snapshots VM100/VM101/VM121.
- [ ] Disaster-recovery runbooks.
- [ ] Регулярные restore drills.

# Ближайшая последовательность

1. [x] Опубликовать этот глобальный план.
2. [ ] Вернуться к
   `STEP_050I_ENABLE_EMERGENCY_COMMIT_AND_THRESHOLD_DRYRUN_ONLY`.
3. [ ] Выполнить reviewed real emergency-refresh step.
4. [ ] Завершить degraded-state machine.
5. [ ] Сделать checkpoint snapshots.
6. [ ] Включить production allocator.
7. [ ] Начать onboarding реальных клиентов.
8. [ ] Реализовать пользовательский web-контур.
9. [ ] Интегрировать ЮKassa.
10. [ ] Провести end-to-end production test.

# Definition of Done проекта

Проект считается production-ready, когда:

- MGTS runtime автономно обслуживает и восстанавливает пять VPN-слотов;
- allocator распределяет реальных клиентов;
- VM121 выдаёт клиенту invite, конфигурацию и личный кабинет;
- подтверждённая оплата создаёт или продлевает подписку;
- просрочка корректно отключает доступ;
- есть backup/restore, audit, monitoring и operator runbooks;
- проверены reboot, outage, exhausted pool и восстановление;
- все изменения имеют timestamped reports и четыре обязательные ссылки.

# Правило обновления

После существенного milestone:

1. Этот файл не перезаписывается.
2. Создаётся новая timestamped-папка.
3. Выполненные пункты отмечаются.
4. Новые этапы разрешено добавлять.
5. В каждом последующем отчёте публикуются:
   - current report;
   - local architecture plan;
   - XS Map;
   - global project plan.

# Четыре обязательные ссылки

- CURRENT REPORT:
  https://helena-background-beam-harry.trycloudflare.com/r/e94a0859747d7b96f29c7fdafc2d0351ba603bb0a7e9e5a4/20260711-123348_step050h3d_publish_global_project_plan/
- LOCAL ARCHITECTURE PLAN:
  https://helena-background-beam-harry.trycloudflare.com/r/e94a0859747d7b96f29c7fdafc2d0351ba603bb0a7e9e5a4/20260711-122923_local_architecture_plan_hmn_egress_recovery_evidence_bound_salvage/
- XS MAP:
  https://helena-background-beam-harry.trycloudflare.com/r/e94a0859747d7b96f29c7fdafc2d0351ba603bb0a7e9e5a4/20260711-120734_xs_map_audit_repair_publish/
- GLOBAL PROJECT PLAN:
  https://helena-background-beam-harry.trycloudflare.com/r/e94a0859747d7b96f29c7fdafc2d0351ba603bb0a7e9e5a4/20260711-123348_global_project_plan_wg_paid/