Merge pull request #29 from 3252a8/dev

PayKilla provider, Telegram anti-flood, install wizard and Remnashop migration (test)

.dockerignore

@@ -12,9 +12,17 @@ scratch/
 .claude/
 *.local.*
 node_modules/
-docker-compose-dev.yml
+frontend/node_modules/
+docs-site/node_modules/
+docs-site/.astro/
+docs-site/dist/
+docs-site/public/demo/runtime/
+docs-site/src/content/docs/
+frontend-nginx-dist/
+deploy/compose/docker-compose-dev.yml
 data/*
 !data/tariffs.example.json
+!data/locales-overrides.example.json
 
 
 # CI
@@ -24,8 +32,7 @@ data/*
 
 # Docker
 docker-compose.yml
-Dockerfile
-.docker
+deploy/compose/*.yml
 .dockerignore
 tmp/
 
@@ -33,6 +40,45 @@ tmp/
 bot/app/web/templates/subscription_webapp.css
 bot/app/web/templates/subscription_webapp.js
 bot/app/web/templates/subscription_webapp.min.*.js
+bot/app/web/templates/subscription_webapp.*.css
+bot/app/web/templates/subscription_webapp.min.*.js.br
+bot/app/web/templates/subscription_webapp.min.*.js.gz
+bot/app/web/templates/subscription_webapp.*.css.br
+bot/app/web/templates/subscription_webapp.*.css.gz
+bot/app/web/templates/subscription_webapp_admin.css
+bot/app/web/templates/subscription_webapp_admin.js
+bot/app/web/templates/subscription_webapp_admin.min.*.js
+bot/app/web/templates/subscription_webapp_admin.*.css
+bot/app/web/templates/subscription_webapp_admin.min.*.js.br
+bot/app/web/templates/subscription_webapp_admin.min.*.js.gz
+bot/app/web/templates/subscription_webapp_admin.*.css.br
+bot/app/web/templates/subscription_webapp_admin.*.css.gz
+bot/app/web/templates/subscription_webapp_docs_demo.css
+bot/app/web/templates/subscription_webapp_docs_demo.js
+bot/app/web/templates/subscription_webapp_docs_demo.*.css
+bot/app/web/templates/subscription_webapp_docs_demo.*.css.br
+bot/app/web/templates/subscription_webapp_docs_demo.*.css.gz
+backend/bot/app/web/templates/subscription_webapp.css
+backend/bot/app/web/templates/subscription_webapp.js
+backend/bot/app/web/templates/subscription_webapp.min.*.js
+backend/bot/app/web/templates/subscription_webapp.*.css
+backend/bot/app/web/templates/subscription_webapp.min.*.js.br
+backend/bot/app/web/templates/subscription_webapp.min.*.js.gz
+backend/bot/app/web/templates/subscription_webapp.*.css.br
+backend/bot/app/web/templates/subscription_webapp.*.css.gz
+backend/bot/app/web/templates/subscription_webapp_admin.css
+backend/bot/app/web/templates/subscription_webapp_admin.js
+backend/bot/app/web/templates/subscription_webapp_admin.min.*.js
+backend/bot/app/web/templates/subscription_webapp_admin.*.css
+backend/bot/app/web/templates/subscription_webapp_admin.min.*.js.br
+backend/bot/app/web/templates/subscription_webapp_admin.min.*.js.gz
+backend/bot/app/web/templates/subscription_webapp_admin.*.css.br
+backend/bot/app/web/templates/subscription_webapp_admin.*.css.gz
+backend/bot/app/web/templates/subscription_webapp_docs_demo.css
+backend/bot/app/web/templates/subscription_webapp_docs_demo.js
+backend/bot/app/web/templates/subscription_webapp_docs_demo.*.css
+backend/bot/app/web/templates/subscription_webapp_docs_demo.*.css.br
+backend/bot/app/web/templates/subscription_webapp_docs_demo.*.css.gz
 
 # Byte-compiled / optimized / DLL files
 **/__pycache__/

.env.example

@@ -1,223 +1,89 @@
-# Telegram Bot Token and Admin IDs
-BOT_TOKEN=your_bot_token_here                                                 # Telegram bot token
-ADMIN_IDS=comma_separated_admin_ids                                           # Your telegram ID
+# Minimal bootstrap env.
+# Most product settings are configured later in Web App admin:
+# Admin -> System -> Settings, Admin -> System -> Tariffs, Admin -> Appearance.
+# Full reference: docs/env-vars.md
 
-# PostgreSQL Database Connection Settings
-POSTGRES_USER=                                                               # Required: database user name
-POSTGRES_PASSWORD=                                                           # Required: database password
-POSTGRES_HOST=remnawave-minishop-db                                           # Database container name
-POSTGRES_PORT=5432                                                            # Port
-POSTGRES_DB=postgres                                                          # Database name
+# Telegram bot token from @BotFather.
+# Example: 1234567890:AA...
+BOT_TOKEN=your_bot_token_here
 
-# Localization and Display
-DEFAULT_LANGUAGE="ru"                                                         # or "en"
-DEFAULT_CURRENCY_SYMBOL="RUB"                                                 # e.g., RUB, USD, EUR
+# Telegram numeric user IDs allowed to open the admin panel.
+# Use commas for several admins, for example: 123456789,987654321
+ADMIN_IDS=123456789
 
-# External Links
-SUPPORT_LINK=https://t.me/your_support_link                                   # Link to the support chat
-SERVER_STATUS_URL=https://status.yourdomain.tld/status/your_service           # Link to the server status page
-TERMS_OF_SERVICE_URL=https://example.com/tos                                  # Link to the terms of service
-PRIVACY_POLICY_URL=https://example.com/privacy                                # Link to the privacy policy
-USER_AGREEMENT_URL=https://example.com/user-agreement                          # Link to the user agreement
-SUBSCRIPTION_MINI_APP_URL=                                                    # Public URL of the subscription Mini App, e.g. https://app.yourdomain.tld/
-START_COMMAND_DESCRIPTION=                                                    # Description of the /start command
-DISABLE_WELCOME_MESSAGE=                                                      # Disable the welcome message
-MY_DEVICES_SECTION_ENABLED=False                                              # Enable the My Devices section in the subscription menu
-USER_HWID_DEVICE_LIMIT=0                                                      # Default HWID/device limit for panel users (0 = unlimited)
-
-# Required channel subscription
-REQUIRED_CHANNEL_ID=                                                          # Telegram channel ID (e.g. -1001234567890) the user must join
-REQUIRED_CHANNEL_LINK=https://t.me/your_channel                               # Optional: public link/invite button text opens
-
-# Webhook Base URL (used for Telegram and payment providers)
+# Public HTTPS base URL of the backend webhook server.
+# Telegram, payment providers and Remnawave call webhook endpoints under this domain.
+# This is usually the backend/API domain, not the Mini App frontend domain.
+# Example: https://bot.yourdomain.tld
 WEBHOOK_BASE_URL=https://webhooks.yourdomain.tld
-TRUSTED_PROXIES=127.0.0.1,::1                                                 # Reverse proxies trusted for X-Forwarded-For
 
-# Subscription Mini App (same container, separate port)
-WEBAPP_ENABLED=True                                                           # Run Mini App HTTP server
-WEBAPP_SERVER_HOST=0.0.0.0                                                    # Internal listen host
-WEBAPP_SERVER_PORT=8081                                                       # Internal/published Mini App port
-WEBAPP_TITLE="/minishop"                                                   # Mini App title
-WEBAPP_PRIMARY_COLOR="#00fe7a"                                                # Main UI color
-WEBAPP_LOGO_URL=                                                                    # Optional logo URL; if empty the emoji below is used
-WEBAPP_LOGO_EMOJI="🫥"                                                              # Emoji logo fallback shown in the header and login screen
-WEBAPP_SESSION_SECRET=                                                        # Optional: HMAC secret for webapp sessions; generated if empty
-WEBHOOK_SECRET_TOKEN=                                                         # Optional: Telegram webhook secret token; generated if empty
-WEBAPP_SESSION_TTL_SECONDS=86400                                              # Web App session lifetime (24h)
-WEBAPP_AUTH_MAX_AGE_SECONDS=86400                                             # Max Telegram initData age
-WEBAPP_LOGIN_TOKEN_TTL_SECONDS=600                                            # External browser login link lifetime
-TELEGRAM_OAUTH_CLIENT_ID=                                                     # Telegram Web Login Client ID from BotFather; defaults to bot ID from BOT_TOKEN
-TELEGRAM_OAUTH_CLIENT_SECRET=                                                 # Optional Telegram Web Login Client Secret; reserved for full OIDC code flow
-TELEGRAM_OAUTH_REQUEST_ACCESS=write                                           # Optional comma-separated permissions: write,phone; empty = OpenID profile only
+# PostgreSQL user created by Docker Compose and used by the backend.
+POSTGRES_USER=remnawave_minishop
 
-# Email login and account linking via SMTP (Brevo SMTP relay defaults)
-SMTP_HOST=smtp-relay.brevo.com                                               # SMTP server
-SMTP_PORT=587                                                                # Brevo recommends 587 with STARTTLS
-SMTP_FALLBACK_PORTS=2525,465                                                 # Tried after SMTP_PORT; 465 uses SSL automatically
-SMTP_TIMEOUT_SECONDS=30                                                      # Per SMTP connection/send attempt timeout
-SMTP_USERNAME=                                                               # Brevo SMTP login
-SMTP_PASSWORD=                                                               # Brevo SMTP key/password
-SMTP_FROM_EMAIL=                                                             # Verified sender email
-SMTP_FROM_NAME=                                                              # Optional sender name
-SMTP_STARTTLS=True                                                           # Use STARTTLS on SMTP_PORT
-SMTP_USE_SSL=False                                                           # Use SSL wrapper, usually only for port 465
-EMAIL_CODE_TTL_SECONDS=600                                                   # Email verification code lifetime
-EMAIL_CODE_RESEND_SECONDS=60                                                 # Minimum delay between code sends
-EMAIL_CODE_MAX_ATTEMPTS=5                                                    # Max attempts per code
-BRUTE_FORCE_MAX_FAILURES=5                                                   # Max failed code attempts in the throttle window
-BRUTE_FORCE_WINDOW_SECONDS=900                                               # Rolling window used to count failures
-BRUTE_FORCE_LOCK_SECONDS=1800                                                # Temporary lockout duration after too many failures
+# PostgreSQL password. Change it before production deploy.
+POSTGRES_PASSWORD=change_me
 
-# Payment Method Toggles
-YOOKASSA_ENABLED=True                                                         # Turn on YOOKASSA
-FREEKASSA_ENABLED=True                                                        # Turn on FreeKassa
-STARS_ENABLED=True                                                            # Turn on STARS
-CRYPTOPAY_ENABLED=True                                                        # Turn on CRYPTOPAY
-PLATEGA_ENABLED=False                                                         # Turn on PLATEGA
-SEVERPAY_ENABLED=False                                                        # Turn on SeverPay
-# Order of payment methods (top to bottom). Supported: severpay, freekassa, platega, yookassa, stars, cryptopay
-PAYMENT_METHODS_ORDER=severpay,yookassa,cryptopay,freekassa,platega,stars
+# PostgreSQL database name created by Docker Compose.
+POSTGRES_DB=remnawave_minishop
 
-# YooKassa Payment Gateway Configuration
-YOOKASSA_SHOP_ID=your_shop_id                                                 # Your store ID in YooKassa
-YOOKASSA_SECRET_KEY=your_secret_key                                           # Your secret key for YooKassa
-YOOKASSA_RETURN_URL=https://t.me/your_bot                                     # URL to which the user will be returned after payment  
-YOOKASSA_DEFAULT_RECEIPT_EMAIL=your_email@example.com                         # Default email for sending receipts
-YOOKASSA_VAT_CODE=1                                                           # VAT code
-YOOKASSA_AUTOPAYMENTS_ENABLED=False                                           # Auto-renew toggle
-YOOKASSA_AUTOPAYMENTS_REQUIRE_CARD_BINDING=True                               # Force automatic card binding when autopay is enabled (set to False to show the save-card checkbox)
+# Enables the Web App and the Web App admin panel.
+# Keep True for the first setup. If set to False, the admin UI is unavailable
+# until you change it back to True in .env and restart the app.
+WEBAPP_ENABLED=True
 
-# Nalogo (self-employed receipts)
-NALOGO_INN=your_inn                                                           # INN for nalog.ru
-NALOGO_PASSWORD=your_nalogo_password                                          # Password for nalog.ru
-NALOGO_RECEIPT_NAME_SUBSCRIPTION=subscription {months} months                 # Receipt name for time-based subscriptions ({months} = duration)
-NALOGO_RECEIPT_NAME_TRAFFIC=traffic package {gb} GB                           # Receipt name for traffic packages ({gb} = traffic amount)
+# Stable secret for Web App sessions.
+# Generate with: openssl rand -hex 32
+# If empty, sessions are invalidated on every restart.
+WEBAPP_SESSION_SECRET=
 
-# FreeKassa Payment Gateway Configuration
-FREEKASSA_MERCHANT_ID=your_shop_id                                            # Your shop ID in FreeKassa
-FREEKASSA_API_KEY=your_api_key                                                # API key for REST requests
-FREEKASSA_SECOND_SECRET=your_second_secret                                    # Secret word #2 (used to verify notifications)
-FREEKASSA_PAYMENT_IP=                                                         # Public IP address reported to FreeKassa
-FREEKASSA_PAYMENT_METHOD_ID=44                                                # Payment method ID, you can get it from https://merchant.freekassa.net/settings/currencies
-FREEKASSA_TRUSTED_IPS=168.119.157.136,168.119.60.227,178.154.197.79,51.250.54.238 # FreeKassa webhook source IP allowlist
+# Stable Telegram webhook secret_token.
+# Generate with: openssl rand -hex 32
+# If empty, a new token can be generated on process start.
+WEBHOOK_SECRET_TOKEN=
 
-# CryptoBot Payment Gateway Configuration
-CRYPTOPAY_TOKEN=                                                              # API token for CryptoPay
-CRYPTOPAY_NETWORK=mainnet                                                     # Network (mainnet or testnet)
-CRYPTOPAY_CURRENCY_TYPE=fiat                                                  # Currency type (fiat or crypto)
-CRYPTOPAY_ASSET=RUB                                                           # Asset, e.g., RUB, BTC, USDT
+# Public HTTPS URL of the Mini App frontend, with trailing slash.
+# This URL is opened by Telegram buttons and BotFather Mini App settings.
+# Do not put /api or webhook paths here.
+# Example: https://app.yourdomain.tld/
+SUBSCRIPTION_MINI_APP_URL=https://app.yourdomain.tld/
 
-# Platega Payment Gateway Configuration
-PLATEGA_BASE_URL=https://app.platega.io                                       # Base API URL
-PLATEGA_MERCHANT_ID=                                                          # Your MerchantId from Platega
-PLATEGA_SECRET=                                                               # API secret from Platega
-PLATEGA_PAYMENT_METHOD=2                                                      # Legacy method ID; fallback for the SBP button when PLATEGA_SBP_METHOD stays default
-PLATEGA_SBP_ENABLED=False                                                     # Show a separate "Pay via SBP" Platega button
-PLATEGA_CRYPTO_ENABLED=False                                                  # Show a separate "Pay with crypto" Platega button
-PLATEGA_SBP_METHOD=2                                                          # Platega method ID for SBP QR (default 2)
-PLATEGA_CRYPTO_METHOD=13                                                      # Platega method ID for crypto (default 13)
-PLATEGA_RETURN_URL=                                                           # Optional: redirect after successful payment (defaults to bot link)
-PLATEGA_FAILED_URL=                                                           # Optional: redirect after failed/cancelled payment (defaults to return URL)
+# Remnawave panel API URL. Usually the panel domain plus /api.
+# Example: https://panel.yourdomain.tld/api
+PANEL_API_URL=https://panel.yourdomain.tld/api
 
-# SeverPay Payment Gateway Configuration
-SEVERPAY_BASE_URL=https://severpay.io/api/merchant                            # Base API URL
-SEVERPAY_MID=                                                                 # Your MID from SeverPay
-SEVERPAY_TOKEN=                                                               # API token/secret for signing requests
-SEVERPAY_RETURN_URL=                                                          # Optional: redirect URL after payment (defaults to bot link)
-SEVERPAY_LIFETIME_MINUTES=                                                    # Optional: payment link lifetime in minutes (30-4320, leave empty for default)
+# Remnawave API key with permissions to manage users, subscriptions and squads.
+# Keep this secret. It can be overridden later in the admin panel if needed.
+PANEL_API_KEY=
 
-# Subscription Options. Specify cost parameters or payment links here.
-1_MONTH_ENABLED=True
-RUB_PRICE_1_MONTH=150
-STARS_PRICE_1_MONTH=0
+# Shared secret for validating incoming Remnawave webhooks.
+# Create or set this secret in Remnawave Panel, then paste the same value here
+# or into Admin -> System -> Settings -> Remnawave Panel.
+# In Remnawave Panel, set WEBHOOK_URL to WEBHOOK_BASE_URL + /webhook/panel,
+# for example: https://app.example.com/webhook/panel
+PANEL_WEBHOOK_SECRET=
 
-3_MONTHS_ENABLED=True
-RUB_PRICE_3_MONTHS=300
-STARS_PRICE_3_MONTHS=0
-
-6_MONTHS_ENABLED=True
-RUB_PRICE_6_MONTHS=500
-STARS_PRICE_6_MONTHS=0
-
-12_MONTHS_ENABLED=True
-RUB_PRICE_12_MONTHS=900
-STARS_PRICE_12_MONTHS=0
-
-# Traffic Packages (enables traffic sale mode when set)
-TRAFFIC_PACKAGES=10:199,50:799                                                # Format: "<GB>:<price>", comma-separated
-STARS_TRAFFIC_PACKAGES=10:2500                                                # Optional: traffic packages priced in Stars
-TARIFFS_CONFIG_PATH=data/tariffs.json                                         # Optional Tariffs 2.0 JSON config. If missing, legacy .env pricing is used.
-NEWT_ID=                                                                      # Optional: local docker-compose-dev.yml Newt tunnel id
-NEWT_SECRET=                                                                  # Optional: local docker-compose-dev.yml Newt tunnel secret
-TARIFF_TRAFFIC_WARNING_LEVELS=85,90,95                                        # Tariffs 2.0 traffic warning levels, percent used
-
-# Subscription Notifications
-SUBSCRIPTION_NOTIFICATIONS_ENABLED=True                                       # Enable subscription
-SUBSCRIPTION_NOTIFY_ON_EXPIRE=True                                            # Notify on subscription
-SUBSCRIPTION_NOTIFY_AFTER_EXPIRE=True                                         # Notify after
-SUBSCRIPTION_NOTIFY_DAYS_BEFORE=3                                             # Days before expiration to notify
-
-
-REFERRAL_ONE_BONUS_PER_REFEREE=False                                          # Give a bonus only once per referee
-REFERRAL_WELCOME_BONUS_DAYS=3                                                 # Welcome bonus for newly registered user from referral link
-LEGACY_REFS=true                                                              # Allow ref_<tg_id> links. Leave unset/true unless you want to disable old links
-# Referral Bonus Days
-# Bonus for the inviting user
-REFERRAL_BONUS_DAYS_1_MONTH=3
-REFERRAL_BONUS_DAYS_3_MONTHS=7
-REFERRAL_BONUS_DAYS_6_MONTHS=15
-REFERRAL_BONUS_DAYS_12_MONTHS=30
-# Invited User Bonus
-REFEREE_BONUS_DAYS_1_MONTH=1
-REFEREE_BONUS_DAYS_3_MONTHS=3
-REFEREE_BONUS_DAYS_6_MONTHS=7
-REFEREE_BONUS_DAYS_12_MONTHS=15
-
-# Panel API Configuration
-PANEL_API_URL=http://your_panel_api_url/api                                   # URL of the panel API
-PANEL_API_KEY=your_panel_api_key                                              # Panel API key
-PANEL_WEBHOOK_SECRET=                                                         # secret used to verify panel webhook signatures
-
-# User traffic limits (applied for all users)
-# 0 means unlimited
-USER_TRAFFIC_LIMIT_GB=0                                                       # Traffic limit for users (0 unlimited)
-USER_TRAFFIC_STRATEGY="NO_RESET"                                              # Traffic reset strategy (NO_RESET, WEEK, MONTH)
-
-# Default Internal Squads for Users (Optional, comma-separated UUIDs)
-USER_SQUAD_UUIDS=uuid1,uuid2,uuid3
-# Default External Squad for Users (Optional, single UUID)
-USER_EXTERNAL_SQUAD_UUID=                                                     # Optional: UUID from Remnawave External Squads to auto-link new panel users
-
-# Trial Settings
-TRIAL_ENABLED=True                                                            # Enable the trial period
-TRIAL_DURATION_DAYS=5                                                         # Duration of the trial period in days
-TRIAL_TRAFFIC_LIMIT_GB=0                                                      # Traffic limit for the trial period (0 = unlimited)
-TRIAL_TRAFFIC_STRATEGY="NO_RESET"                                             # Traffic reset strategy for the trial period (NO_RESET, WEEK, MONTH)
-
-# Connection link handling (happ crypt4)
-CRYPT4_ENABLED=False                                                          # Enable happ crypt4 encryption for subscription URLs
-CRYPT4_REDIRECT_URL=                                                          # Base redirect to wrap the connect button, e.g. https://redir.example.com?url=
-
-# Web Server Settings (for handling webhooks)
-WEB_SERVER_HOST="0.0.0.0"
+# Host port that publishes the backend webhook server from Docker Compose.
+# Your reverse proxy should route WEBHOOK_BASE_URL traffic to this port.
 WEB_SERVER_PORT=8080
 
-# Admin Panel Log Pagination
-LOGS_PAGE_SIZE=10                                                             # Number of events in the log
-LOG_LEVEL=INFO                                                                # Global log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+# Host port that publishes the frontend nginx from Docker Compose.
+# Your reverse proxy should route SUBSCRIPTION_MINI_APP_URL traffic to this port.
+FRONTEND_PORT=8082
 
-# Admin Logging Configuration
-LOG_CHAT_ID=-1001234567890                                                    # Telegram chat/group ID for admin notifications
-LOG_THREAD_ID=                                                                # Optional: Thread ID for supergroup messages
-LOG_NEW_USERS=True                                                            # Log new user registrations
-LOG_PAYMENTS=True                                                             # Log payments
-LOG_PROMO_ACTIVATIONS=True                                                    # Log promo code activations
-LOG_TRIAL_ACTIVATIONS=True                                                    # Log trial activations
-LOG_SUSPICIOUS_ACTIVITY=True                                                  # Log suspicious activity
-LOG_ADMIN_ACTIONS=True                                                        # Log actions from users listed in ADMIN_IDS
+# Reverse proxy IPs/CIDRs trusted for X-Forwarded-For.
+# Keep loopback and private network ranges so payment provider IP allowlists
+# see the original webhook sender behind Docker/LAN/Kubernetes proxies.
+TRUSTED_PROXIES=127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7
 
-# Embedded mode thumbnails. Please don't touch this if you don't know what it is.
-INLINE_REFERRAL_THUMBNAIL_URL=https://cdn-icons-png.flaticon.com/512/1077/1077114.png
-INLINE_USER_STATS_THUMBNAIL_URL=https://cdn-icons-png.flaticon.com/512/681/681494.png
-INLINE_FINANCIAL_STATS_THUMBNAIL_URL=https://cdn-icons-png.flaticon.com/512/2769/2769339.png
-INLINE_SYSTEM_STATS_THUMBNAIL_URL=https://cdn-icons-png.flaticon.com/512/2920/2920277.png
+# ─── Anonymous install telemetry (opt-out) ──────────────────────────────
+# Once a day the worker sends a single anonymous "heartbeat" so the project
+# maintainer can see how many installs are active and which versions/OSes are
+# used. It contains an opaque random install id and coarse facts only:
+# version, official/custom image provenance, OS/arch, Python version, language,
+# enabled payment providers and a user-count RANGE (e.g. "51-200"). No bot
+# token, domain, user data or any personal information is ever sent.
+# Full details: docs/configuration/telemetry.md
+#
+# Set to False to disable, or toggle it any time in Admin -> System ->
+# "Anonymous install analytics" (applies without a restart).
+TELEMETRY_ENABLED=True

.gitattributes

@@ -0,0 +1,9 @@
+.gitattributes text eol=lf
+*.sh text eol=lf
+.github/workflows/*.yml text eol=lf
+deploy/docker/frontend/*.sh text eol=lf
+frontend/src/*.js text eol=lf
+frontend/src/**/*.js text eol=lf
+frontend/src/**/*.svelte text eol=lf
+frontend/scripts/*.mjs text eol=lf
+frontend/scripts/**/*.mjs text eol=lf

.github/workflows/_docker-build-push.yml

@@ -0,0 +1,138 @@
+name: Docker build & push (reusable)
+
+# Reusable workflow that builds the three image targets defined in
+# deploy/docker/Dockerfile (backend, worker, frontend) and optionally pushes
+# them to the selected registries under the repository owner's namespace.
+#
+# Called by:
+#   - docker-dev.yml      (tag_mode: dev,     push: true)  on pushes to dev
+#   - docker-release.yml  (tag_mode: release, push: true)  on release tags
+#   - ci.yml              (tag_mode: dev,     push: false) on pull requests
+
+on:
+  workflow_call:
+    inputs:
+      push:
+        description: "Push the built images to the registries"
+        type: boolean
+        default: true
+      tag_mode:
+        description: "Tagging strategy: 'dev' or 'release'"
+        type: string
+        required: true
+      publish_dockerhub:
+        description: "Include Docker Hub tags and login when pushing"
+        type: boolean
+        default: true
+
+# No permissions block here on purpose: a reusable workflow cannot request more
+# than its caller grants, so the token scope is set by each caller
+# (docker-dev.yml / docker-release.yml grant packages: write to push; ci.yml
+# only needs contents: read for a no-push build).
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: backend
+            image: remnawave-minishop-backend
+          - target: worker
+            image: remnawave-minishop-worker
+          - target: frontend
+            image: remnawave-minishop-frontend
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full history + tags: the Dockerfile's version-builder stage runs
+          # `git describe --tags` against the copied .git tree.
+          fetch-depth: 0
+
+      - name: Resolve release version
+        id: version
+        if: inputs.tag_mode == 'release'
+        run: |
+          # On a tag push github.ref_name is the tag (e.g. v3.4.5); for a
+          # manual workflow_dispatch on a branch, fall back to the latest tag.
+          if [ "${{ github.ref_type }}" = "tag" ]; then
+            raw="${{ github.ref_name }}"
+          else
+            raw="$(git describe --tags --abbrev=0 2>/dev/null)"
+          fi
+          version="${raw#v}"
+          if [ -z "$version" ]; then
+            echo "::error::No git tag found to derive the release version from"
+            exit 1
+          fi
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "Release version: ${version}"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        if: inputs.push
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Log in to Docker Hub
+        if: inputs.push && inputs.publish_dockerhub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Resolve image namespaces
+        id: image_namespaces
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+        run: |
+          github_owner="${{ github.repository_owner }}"
+          echo "github_owner=${github_owner,,}" >> "$GITHUB_OUTPUT"
+          dockerhub_owner="${github_owner,,}"
+          if [ "${{ inputs.push }}" = "true" ] && [ "${{ inputs.publish_dockerhub }}" = "true" ]; then
+            if [ -z "$DOCKERHUB_USERNAME" ]; then
+              echo "::error::DOCKERHUB_USERNAME secret is required for Docker Hub publishing"
+              exit 1
+            fi
+            dockerhub_owner="${DOCKERHUB_USERNAME,,}"
+          fi
+          echo "dockerhub_owner=$dockerhub_owner" >> "$GITHUB_OUTPUT"
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            name=${{ steps.image_namespaces.outputs.dockerhub_owner }}/${{ matrix.image }},enable=${{ inputs.push && inputs.publish_dockerhub }}
+            name=ghcr.io/${{ steps.image_namespaces.outputs.github_owner }}/${{ matrix.image }},enable=true
+          tags: |
+            type=raw,value=dev,enable=${{ inputs.tag_mode == 'dev' }}
+            type=raw,value=latest,enable=${{ inputs.tag_mode == 'release' }}
+            type=raw,value=${{ steps.version.outputs.version }},enable=${{ inputs.tag_mode == 'release' }}
+
+      - name: Build${{ inputs.push && ' & push' || '' }} ${{ matrix.image }}
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: deploy/docker/Dockerfile
+          target: ${{ matrix.target }}
+          platforms: linux/amd64
+          push: ${{ inputs.push }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          # The Dockerfile's version-builder appends a "-<branch>" suffix to the
+          # internal version string for non-main builds. Force "main" on release
+          # (the ref is the tag, not a branch) so release images stay un-suffixed.
+          build-args: |
+            GITHUB_REF_NAME=${{ inputs.tag_mode == 'release' && 'main' || github.ref_name }}
+            REMNAWAVE_MINISHOP_BUILD_PROVENANCE=${{ github.repository == '3252a8/remnawave-minishop' && 'official' || 'custom' }}
+          cache-from: type=gha,scope=${{ matrix.target }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.target }}
+          provenance: false

.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: PR checks
+
+# Runs on pull requests into main (typically from dev) and into dev (typically
+# from feature/* branches): lint + format checks, a demo settings-manifest
+# drift guard, and a no-push image build to prove the Docker images still build.
+
+on:
+  pull_request:
+    branches: [main, dev]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint & format
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install "ruff>=0.8.0"
+
+      - name: Ruff lint (Python)
+        run: ruff check .
+
+      - name: Ruff format check (Python)
+        run: ruff format --check .
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend deps
+        run: npm ci
+        working-directory: frontend
+
+      - name: ESLint (frontend)
+        run: npm run lint
+        working-directory: frontend
+
+      - name: Prettier check (frontend)
+        run: npm run format:check
+        working-directory: frontend
+
+  demo-manifest:
+    name: Demo settings manifest in sync
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: backend/requirements.txt
+
+      - name: Install backend deps + pytest
+        run: pip install -r backend/requirements.txt pytest
+
+      # Fails if admin_settings_manifest.py changed without regenerating the
+      # demo snapshot. Fix: `python scripts/export_settings_manifest.py` then
+      # `npx --prefix frontend prettier --write \
+      #   src/lib/webapp/settingsManifest.generated.json`, and commit the result.
+      - name: Check demo settings manifest is in sync
+        run: python -m pytest tests/test_settings_manifest_demo_sync.py -q
+
+  build:
+    name: Docker build
+    uses: ./.github/workflows/_docker-build-push.yml
+    with:
+      push: false
+      tag_mode: dev

.github/workflows/dependency-review.yml

@@ -0,0 +1,27 @@
+name: Dependency review
+
+# On PRs into main/dev, flag any newly added dependency that has a known
+# vulnerability or an incompatible license before it gets merged.
+
+on:
+  pull_request:
+    branches: [main, dev]
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Dependency review
+        uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high
+          comment-summary-in-pr: on-failure

.github/workflows/docker-dev.yml

@@ -0,0 +1,26 @@
+name: Dev images
+
+# On every push to the dev branch, build all three images and push them to
+# GHCR tagged `dev`. Docker Hub dev images are published by GitLab CI.
+
+on:
+  push:
+    branches: [dev]
+  workflow_dispatch:
+
+concurrency:
+  group: docker-dev-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-push:
+    uses: ./.github/workflows/_docker-build-push.yml
+    with:
+      push: true
+      tag_mode: dev
+      publish_dockerhub: false
+    secrets: inherit

.github/workflows/docker-release.yml

@@ -0,0 +1,28 @@
+name: Release images
+
+# Build all three images and push them to ghcr.io and Docker Hub tagged
+# `latest` and the release version (the pushed tag with its leading `v`
+# stripped, e.g. v3.4.5 -> 3.4.5). Triggered only when a new v* tag is pushed,
+# so images are built once per release rather than on every commit to main.
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+concurrency:
+  group: docker-release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-push:
+    uses: ./.github/workflows/_docker-build-push.yml
+    with:
+      push: true
+      tag_mode: release
+    secrets: inherit

.github/workflows/security.yml

@@ -0,0 +1,96 @@
+name: Security
+
+# Audits the full dependency set (pip-audit, npm audit) and runs a Trivy
+# filesystem scan (dependencies + Dockerfile/IaC misconfig). Trivy results are
+# uploaded to the Security -> Code scanning tab.
+#
+# pip-audit / npm audit are informational (continue-on-error): they surface
+# upstream/transitive advisories that aren't necessarily fixable in a given PR,
+# so they report in the logs without blocking merges. The PR gate for newly
+# introduced vulnerable deps is dependency-review.yml.
+
+on:
+  pull_request:
+    branches: [main, dev]
+  push:
+    branches: [main, dev]
+  schedule:
+    - cron: "27 4 * * 1" # weekly, Monday 04:27 UTC
+  workflow_dispatch:
+
+concurrency:
+  group: security-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  python-audit:
+    name: pip-audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install pip-audit
+        run: pip install pip-audit
+
+      - name: Audit Python dependencies
+        continue-on-error: true
+        run: pip-audit -r backend/requirements.txt
+
+  npm-audit:
+    name: npm audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend deps
+        run: npm ci
+        working-directory: frontend
+
+      - name: Audit npm dependencies
+        continue-on-error: true
+        run: npm audit --audit-level=high
+        working-directory: frontend
+
+  trivy:
+    name: Trivy filesystem scan
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run Trivy
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          scan-type: fs
+          scan-ref: .
+          format: sarif
+          output: trivy-results.sarif
+          severity: CRITICAL,HIGH
+          ignore-unfixed: true
+
+      - name: Upload Trivy results
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: trivy-results.sarif
+          category: trivy-fs

.gitignore

@@ -5,15 +5,63 @@ bot_database.sqlite3
 .env
 .env.*
 !.env.example
+docker-compose-dev.yml
 scratch_*.py
+scratch/
 *.local.*
 node_modules/
 .git/
 
+# Documentation site build artifacts
+docs-site/.astro/
+docs-site/dist/
+docs-site/public/demo/runtime/
+docs-site/src/content/docs/
+frontend-nginx-dist/
+
 # WebApp build artifacts (regenerated by `npm run build:webapp` / Docker build)
 bot/app/web/templates/subscription_webapp.css
 bot/app/web/templates/subscription_webapp.js
 bot/app/web/templates/subscription_webapp.min.*.js
+bot/app/web/templates/subscription_webapp.*.css
+bot/app/web/templates/subscription_webapp.min.*.js.br
+bot/app/web/templates/subscription_webapp.min.*.js.gz
+bot/app/web/templates/subscription_webapp.*.css.br
+bot/app/web/templates/subscription_webapp.*.css.gz
+bot/app/web/templates/subscription_webapp_admin.css
+bot/app/web/templates/subscription_webapp_admin.js
+bot/app/web/templates/subscription_webapp_admin.min.*.js
+bot/app/web/templates/subscription_webapp_admin.*.css
+bot/app/web/templates/subscription_webapp_admin.min.*.js.br
+bot/app/web/templates/subscription_webapp_admin.min.*.js.gz
+bot/app/web/templates/subscription_webapp_admin.*.css.br
+bot/app/web/templates/subscription_webapp_admin.*.css.gz
+bot/app/web/templates/subscription_webapp_docs_demo.css
+bot/app/web/templates/subscription_webapp_docs_demo.js
+bot/app/web/templates/subscription_webapp_docs_demo.*.css
+bot/app/web/templates/subscription_webapp_docs_demo.*.css.br
+bot/app/web/templates/subscription_webapp_docs_demo.*.css.gz
+backend/bot/app/web/templates/subscription_webapp.css
+backend/bot/app/web/templates/subscription_webapp.js
+backend/bot/app/web/templates/subscription_webapp.min.*.js
+backend/bot/app/web/templates/subscription_webapp.*.css
+backend/bot/app/web/templates/subscription_webapp.min.*.js.br
+backend/bot/app/web/templates/subscription_webapp.min.*.js.gz
+backend/bot/app/web/templates/subscription_webapp.*.css.br
+backend/bot/app/web/templates/subscription_webapp.*.css.gz
+backend/bot/app/web/templates/subscription_webapp_admin.css
+backend/bot/app/web/templates/subscription_webapp_admin.js
+backend/bot/app/web/templates/subscription_webapp_admin.min.*.js
+backend/bot/app/web/templates/subscription_webapp_admin.*.css
+backend/bot/app/web/templates/subscription_webapp_admin.min.*.js.br
+backend/bot/app/web/templates/subscription_webapp_admin.min.*.js.gz
+backend/bot/app/web/templates/subscription_webapp_admin.*.css.br
+backend/bot/app/web/templates/subscription_webapp_admin.*.css.gz
+backend/bot/app/web/templates/subscription_webapp_docs_demo.css
+backend/bot/app/web/templates/subscription_webapp_docs_demo.js
+backend/bot/app/web/templates/subscription_webapp_docs_demo.*.css
+backend/bot/app/web/templates/subscription_webapp_docs_demo.*.css.br
+backend/bot/app/web/templates/subscription_webapp_docs_demo.*.css.gz
 tmp
 .claude
 
@@ -32,4 +80,4 @@ locales/en_backup.json
 db/models_old.py
 data/*
 !data/tariffs.example.json
-docker-compose-dev.yml
+!data/locales-overrides.example.json

.gitlab-ci.yml

@@ -0,0 +1,72 @@
+stages:
+  - docker
+
+workflow:
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "dev"'
+    - when: never
+
+variables:
+  DOCKER_BUILDKIT: "1"
+  DOCKER_DRIVER: overlay2
+  DOCKER_HOST: tcp://docker:2375
+  DOCKER_TLS_CERTDIR: ""
+  GIT_DEPTH: "0"
+
+docker-dev:
+  stage: docker
+  image: docker:27.5.1
+  services:
+    - name: docker:27.5.1-dind
+      alias: docker
+  interruptible: true
+  parallel:
+    matrix:
+      - TARGET: backend
+        IMAGE: remnawave-minishop-backend
+      - TARGET: worker
+        IMAGE: remnawave-minishop-worker
+      - TARGET: frontend
+        IMAGE: remnawave-minishop-frontend
+  before_script:
+    - apk add --no-cache git
+    - test -n "$DOCKERHUB_USERNAME"
+    - test -n "$DOCKERHUB_TOKEN"
+    - echo "$DOCKERHUB_TOKEN" | docker login --username "$DOCKERHUB_USERNAME" --password-stdin
+    - docker buildx create --name gitlab-builder --driver docker-container --use
+    - docker buildx inspect --bootstrap
+  script:
+    - git fetch origin dev --tags
+    - |
+      if [ "$(git rev-parse HEAD)" != "$(git rev-parse origin/dev)" ]; then
+        echo "A newer dev commit exists; skipping Docker Hub build for $IMAGE."
+        exit 0
+      fi
+    - |
+      provenance="${REMNAWAVE_MINISHOP_BUILD_PROVENANCE:-}"
+      if [ -z "$provenance" ]; then
+        dockerhub_owner="$(printf '%s' "${DOCKERHUB_USERNAME:-}" | tr '[:upper:]' '[:lower:]')"
+        if [ "${CI_PROJECT_PATH:-}" = "3252a8/remnawave-minishop" ] || [ "$dockerhub_owner" = "3252a8" ]; then
+          provenance="official"
+        else
+          provenance="custom"
+        fi
+      fi
+      docker buildx build \
+        --load \
+        --platform linux/amd64 \
+        --file deploy/docker/Dockerfile \
+        --target "$TARGET" \
+        --build-arg "CI_COMMIT_REF_NAME=$CI_COMMIT_REF_NAME" \
+        --build-arg "REMNAWAVE_MINISHOP_BUILD_PROVENANCE=$provenance" \
+        --build-arg "BUILDKIT_INLINE_CACHE=1" \
+        --cache-from "type=registry,ref=$DOCKERHUB_USERNAME/$IMAGE:dev" \
+        --tag "$DOCKERHUB_USERNAME/$IMAGE:dev" \
+        .
+    - git fetch origin dev --tags
+    - |
+      if [ "$(git rev-parse HEAD)" != "$(git rev-parse origin/dev)" ]; then
+        echo "A newer dev commit exists; skipping Docker Hub push for $IMAGE."
+        exit 0
+      fi
+    - docker push "$DOCKERHUB_USERNAME/$IMAGE:dev"

Caddyfile

@@ -1,10 +0,0 @@
-# Replace the example domains below with your real webhook and Mini App hostnames.
-webhook.domain.com {
-	encode zstd gzip
-	reverse_proxy remnawave-minishop:{$WEB_SERVER_PORT:8080}
-}
-
-app.domain.com {
-	encode zstd gzip
-	reverse_proxy remnawave-minishop:{$WEBAPP_SERVER_PORT:8081}
-}

Dockerfile

@@ -1,96 +0,0 @@
-FROM python:3.12-slim AS python-builder
-
-WORKDIR /app
-
-COPY requirements.txt .
-
-RUN --mount=type=cache,target=/root/.cache/pip \
-    pip install --no-cache-dir -r requirements.txt
-
-
-FROM node:22-slim AS webapp-builder
-
-WORKDIR /webapp
-
-COPY package.json package-lock.json* ./
-RUN --mount=type=cache,target=/root/.npm \
-    if [ -f package-lock.json ]; then npm ci; else npm install; fi
-
-COPY bot/app/web/frontend ./bot/app/web/frontend
-COPY bot/app/web/templates ./bot/app/web/templates
-COPY scripts/build_subscription_webapp_js.mjs ./scripts/build_subscription_webapp_js.mjs
-
-RUN npm run build:webapp
-
-
-FROM python:3.12-slim
-
-WORKDIR /app
-
-ARG APP_VERSION=""
-ARG APP_REVISION=""
-
-LABEL org.opencontainers.image.source="https://github.com/3252a8/remnawave-minishop" \
-      org.opencontainers.image.version="${APP_VERSION}" \
-      org.opencontainers.image.revision="${APP_REVISION}"
-
-RUN useradd -u 10001 -m appuser
-
-COPY --from=python-builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
-
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
-    --mount=type=cache,target=/var/lib/apt,sharing=locked \
-    apt-get update && \
-    apt-get install -y --no-install-recommends git
-
-COPY . .
-
-# Replace template assets with freshly built ones
-RUN rm -f bot/app/web/templates/subscription_webapp.css \
-          bot/app/web/templates/subscription_webapp.js \
-          bot/app/web/templates/subscription_webapp.min.*.js
-COPY --from=webapp-builder /webapp/bot/app/web/templates/subscription_webapp.css \
-                           bot/app/web/templates/subscription_webapp.css
-COPY --from=webapp-builder /webapp/bot/app/web/templates/subscription_webapp.js \
-                           bot/app/web/templates/subscription_webapp.js
-COPY --from=webapp-builder /webapp/bot/app/web/templates/subscription_webapp.min.*.js \
-                           bot/app/web/templates/
-
-RUN set -eux; \
-    if [ -n "$APP_VERSION" ]; then \
-      printf '%s\n' "$APP_VERSION" > .build-version; \
-    elif [ -d .git ]; then \
-      tag="$(git describe --tags --abbrev=0 2>/dev/null || true)"; \
-      sha="$(git rev-parse --short HEAD 2>/dev/null || true)"; \
-      dirty=""; \
-      if ! git diff --quiet --ignore-submodules HEAD 2>/dev/null; then dirty="-dirty"; fi; \
-      if [ -n "$tag" ] && [ -n "$sha" ]; then \
-        count="$(git rev-list "${tag}..HEAD" --count 2>/dev/null || true)"; \
-        if [ -n "$count" ] && [ "$count" != "0" ]; then \
-          printf '%s+%s.g%s%s\n' "$tag" "$count" "$sha" "$dirty" > .build-version; \
-        else \
-          printf '%s%s\n' "$tag" "$dirty" > .build-version; \
-        fi; \
-      elif [ -n "$sha" ]; then \
-        printf 'dev+g%s%s\n' "$sha" "$dirty" > .build-version; \
-      else \
-        printf 'dev+container\n' > .build-version; \
-      fi; \
-    else \
-      printf 'dev+container\n' > .build-version; \
-    fi; \
-    if [ -n "$APP_REVISION" ]; then \
-      printf '%s\n' "$APP_REVISION" > .build-revision; \
-    elif [ -d .git ]; then \
-      git rev-parse HEAD > .build-revision 2>/dev/null || printf 'unknown\n' > .build-revision; \
-    else \
-      printf 'unknown\n' > .build-revision; \
-    fi; \
-    apt-get purge -y --auto-remove git; \
-    rm -rf .git /root/.cache
-
-RUN mkdir -p /app/logs /app/data && chown -R appuser:appuser /app/logs /app/data
-
-USER appuser
-
-CMD ["python", "main.py"]

LICENSE

@@ -1,7 +1,21 @@
-Copyright 2025 machka-pasla
+MIT License
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Copyright (c) 2025-2026 machka-pasla, 3252a8 and other contributors
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,8 +1,10 @@
 # Remnawave Minishop
 
-Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи и управления подписками Remnawave. Бот обрабатывает регистрацию, оплату, продление, пробный период, промокоды, рефералов и поддержку в чате. Web App показывает ссылку подключения, срок действия, трафик, оплату, устройства и вход по Telegram Mini Apps `initData`, Telegram OAuth / OpenID Connect и одноразовому email-коду.
+![Remnawave Minishop](docs/remnawave-minishop.webp)
 
-Проект является переработанным форком [kavore/remnawave-tg-shop](https://github.com/kavore/remnawave-tg-shop). Для переноса данных из прежнего стека используйте [инструкцию по миграции](docs/migration-to-minishop.md).
+Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи и управления подписками панели [Remnawave](https://docs.rw/). Бот обрабатывает регистрацию, оплату, продление, пробный период, промокоды, рефералов и поддержку в чате. Web App показывает ссылку подключения, срок действия, трафик, оплату, устройства и вход по Telegram Mini Apps `initData`, Telegram OAuth / OpenID Connect и одноразовому email-коду.
+
+Проект является переработанным форком [kavore/remnawave-tg-shop](https://github.com/kavore/remnawave-tg-shop). Для переноса данных из прежнего стека и других ботов используйте [раздел миграций](docs/migrations/index.md).
 
 ## Возможности
 
@@ -12,8 +14,10 @@ Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи
 - просмотр статуса подписки, даты окончания, ссылки подключения и трафика;
 - покупка подписок, пакетов трафика, обычная и premium-докупка трафика, докупка устройств по настроенному каталогу тарифов;
 - Web App / Mini App с входом через Telegram или email;
+- встроенные инструкции установки в Mini App: личный экран `/install` и публичная ссылка `/s/<token>` для передачи инструкции;
 - пробный период, промокоды и реферальная программа;
-- оплата через YooKassa, FreeKassa, Platega, SeverPay, CryptoPay и Telegram Stars;
+- оплата через YooKassa, FreeKassa, Platega, SeverPay, Wata, CryptoPay, Heleket, PayKilla и Telegram Stars;
+- тикеты поддержки в Web App и внешняя ссылка на поддержку;
 - раздел "Мои устройства" при включенном `MY_DEVICES_SECTION_ENABLED`.
 
 Для администраторов:
@@ -21,18 +25,26 @@ Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи
 - админ-панель для пользователей из `ADMIN_IDS` (только при входе через Telegram, не для аккаунтов только с email);
 - статистика пользователей, подписок, платежей и синхронизации с Remnawave;
 - список пользователей с поиском, фильтрами и колонкой premium-трафика;
-- блокировка пользователей, рассылки, промокоды, логи действий и настройка разрешенных параметров приложения поверх `.env`;
-- редактор JSON-каталога тарифов с period/traffic-моделями, Internal Squads, premium-сквадами и HWID-пакетами;
+- блокировка пользователей, поддержка через тикеты, рассылки, промокоды, логи действий и настройка разрешенных параметров приложения поверх `.env`;
+- редактор JSON-каталога тарифов с моделями на срок/по трафику, Internal Squads, premium-сквадами и HWID-пакетами;
+- настройки инструкций подключения: чтение конфига Subscription Page из Remnawave Panel, опциональное JSON-переопределение и переключатель поведения кнопок бота;
 - ручная синхронизация пользователей и подписок с панелью.
 
 ## Документация
 
-- [Настройка окружения](docs/configuration.md) - основные переменные `.env`, платежи, Remnawave, пробный период, SMTP для email-входа и секреты.
-- [Тарифы](docs/tariffs.md) - каталог тарифов, period- и traffic-модели, обычные и premium-докупки, premium-сквады, смена тарифа, HWID-лимиты и обработка трафика.
-- [Админ-панель](docs/admin.md) - права доступа, настройки, редактор тарифов, premium-сквады и сохранение JSON-каталога.
-- [Web App / Mini App](docs/webapp.md) - отдельный порт, домен, Telegram OAuth, email-вход и реферальные ссылки.
-- [Развертывание](docs/deployment.md) - Docker Compose, reverse proxy, Nginx, Caddy, вебхуки, запуск из образа и обновление версии (`IMAGE_TAG`).
-- [Миграция с remnawave-tg-shop](docs/migration-to-minishop.md) - перенос данных из прежнего стека.
+- [Входная страница документации](docs/index.md) - маршрут по установке, настройке, платежам, админке и диагностике.
+- [Развертывание](docs/getting-started/deployment.md) - Docker Compose, Caddy, Nginx, Pangolin/Newt и запуск без обратного прокси.
+- [Настройка окружения](docs/getting-started/configuration.md) - bootstrap `.env` и рекомендуемая настройка через Web App админку.
+- [Переменные `.env`](docs/configuration/env-vars.md) - полный справочник всех env-ключей по разделам.
+- [Бэкапы и восстановление](docs/features/backups.md) - автоматические архивы, Telegram-отправка и restore через админку.
+- [Тарифы](docs/features/tariffs.md) - каталог тарифов, модели на срок и по трафику, обычные и premium-докупки, premium-сквады, смена тарифа, HWID-лимиты и обработка трафика.
+- [Админ-панель](docs/features/admin-panel.md) - права доступа, настройки, редактор тарифов, premium-сквады и сохранение JSON-каталога.
+- [Веб-приложение / Mini App](docs/features/web-app.md) - отдельный порт, домен, инструкции установки и реферальные ссылки.
+- [Telegram-авторизация](docs/features/telegram-auth.md) и [вход по email](docs/features/email-login.md) - настройка BotFather/OAuth и SMTP-логина.
+- [Поддержка пользователей / тикеты](docs/features/support.md) - тикеты в Mini App, входящий список админки, уведомления, лимиты и внешняя ссылка поддержки.
+- [Темы Web App](docs/features/webapp-themes.md) - кастомные темы, настройка внешнего вида, логотипы, CSS/ассеты и пайплайн создания новой темы.
+- [Миграции](docs/migrations/index.md) - готовые сценарии переноса с `remnawave-tg-shop` и Remnashop.
+- [Миграция с remnawave-tg-shop](docs/migrations/remnawave-tg-shop.md) и [Remnashop](docs/migrations/remnashop.md) - сценарии через общий install wizard.
 
 ## Совместимость
 
@@ -40,13 +52,13 @@ Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи
 
 ## Стек
 
-Сборка и runtime задаются **Dockerfile** и **docker-compose.yml**; точные версии пакетов — в **requirements.txt** и **package.json**.
+Сборка и runtime задаются **deploy/docker/Dockerfile** и **docker-compose.yml**; точные версии пакетов — в **backend/requirements.txt** и **frontend/package.json**.
 
 | Слой | Технологии |
 | --- | --- |
 | Backend | Python **3.12**, [aiogram](https://docs.aiogram.dev/) 3.x (Telegram), **aiohttp** (HTTP и Web App), **SQLAlchemy** 2 async, **asyncpg**, **Pydantic** / pydantic-settings, **httpx**, платёжные SDK (в т.ч. YooKassa, aiocryptopay), **PyJWT** |
-| Данные | **PostgreSQL** **17** (сервис `remnawave-minishop-db` в Compose) |
-| Сборка Web App | **Node.js** **22**, **Svelte** **5**, **Vite**, **Tailwind CSS** 4; артефакты попадают в шаблоны `bot/app/web/templates/` |
+| Данные | **PostgreSQL** **17** (сервис `postgres` в Compose) и **Redis** **7** (сервис `redis`) |
+| Сборка Web App | **Node.js** **22**, **Svelte** **5**, **Vite**, **Tailwind CSS** 4; артефакты попадают в шаблоны `backend/bot/app/web/templates/` |
 
 Локальная разработка без Docker возможна при установленных Python 3.12, PostgreSQL и (для пересборки фронта) Node 22; типичный сценарий — всё через Compose.
 
@@ -57,7 +69,7 @@ Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи
 - Docker и Docker Compose;
 - рабочая панель Remnawave версии **`> 2.7.0`** (см. раздел «Совместимость»);
 - токен Telegram-бота;
-- параметры хотя бы одного платежного провайдера.
+- публичные домены для webhook и Mini App.
 
 ```bash
 git clone https://github.com/3252a8/remnawave-minishop
@@ -65,7 +77,7 @@ cd remnawave-minishop
 cp .env.example .env
 nano .env
 docker compose up -d --build
-docker compose logs -f remnawave-minishop
+docker compose logs -f backend worker frontend
 ```
 
 Минимально заполните в `.env`:
@@ -73,17 +85,27 @@ docker compose logs -f remnawave-minishop
 - `BOT_TOKEN` - токен Telegram-бота;
 - `ADMIN_IDS` - Telegram ID администраторов через запятую;
 - `WEBHOOK_BASE_URL` - публичный URL вебхуков;
+- `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` - доступы PostgreSQL;
+- `WEBAPP_ENABLED=True` - включает Web App и админку для первого входа;
+- `WEBAPP_SESSION_SECRET`, `WEBHOOK_SECRET_TOKEN` - стабильные секреты;
+- `SUBSCRIPTION_MINI_APP_URL` - публичный HTTPS URL Mini App/frontend, например `https://app.domain.com/`;
 - `PANEL_API_URL`, `PANEL_API_KEY`, `PANEL_WEBHOOK_SECRET` - доступ к Remnawave;
-- `USER_SQUAD_UUIDS` - Internal Squads для пользователей;
-- настройки платежного провайдера;
-- `SUBSCRIPTION_MINI_APP_URL`, если используется Web App.
+- `TRUSTED_PROXIES` - оставьте дефолт для Docker/Caddy/Nginx/Newt или укажите IP/CIDR своего reverse proxy, чтобы IP allowlist платежных webhook видел реального провайдера;
+- остальные настройки удобнее задать в Web App админке.
 
-Для каталога тарифов используется `TARIFFS_CONFIG_PATH` со значением по умолчанию `data/tariffs.json`. Пример формата лежит в [data/tariffs.example.json](data/tariffs.example.json), подробности - в [docs/tariffs.md](docs/tariffs.md).
+В Remnawave Panel укажите `WEBHOOK_URL` как публичный адрес Minishop с путем `/webhook/panel`, например `https://app.example.com/webhook/panel`. Секрет вебхука задается в самой Remnawave Panel; это же значение вставьте в `PANEL_WEBHOOK_SECRET` в `.env` или в **Система -> Настройки -> Remnawave Panel** в админке.
 
-Если в Docker Compose включаете bind mount `./data:/app/data`, заранее создайте каталог и отдайте его пользователю контейнера. Это нужно для сохранения `data/tariffs.json`, кеша логотипа Web App и animated emoji:
+После первого входа в админку настройте тарифы, платежные провайдеры, внешний вид, поддержку, уведомления и инструкции подключения через UI. Инструкции установки включены по умолчанию, читают Subscription Page config из Remnawave Panel и при проблемах с конфигом откатываются к обычной ссылке подключения. Полный справочник env-переменных: [docs/configuration/env-vars.md](docs/configuration/env-vars.md).
+
+Для каталога тарифов используется `TARIFFS_CONFIG_PATH` со значением по умолчанию `data/tariffs.json`. Пример формата лежит в [data/tariffs.example.json](data/tariffs.example.json), подробности - в [docs/features/tariffs.md](docs/features/tariffs.md).
+
+В Docker этот файл должен быть доступен не только `backend` и `worker`, но и одноразовому сервису `migrate`: мигратор читает каталог тарифов при привязке существующих подписок к тарифу по умолчанию. В текущих compose-файлах весь `/app/data` уже смонтирован в `migrate`, `backend` и `worker`; если переносите compose вручную, сохраните одинаковый mount для всех трех сервисов.
+
+В compose-примерах `/app/data` монтируется из папки `./data` рядом с `docker-compose.yml`. Заранее создайте каталог и отдайте его пользователю контейнера. Это нужно для сохранения `data/tariffs.json`, каталога тем `data/themes` и кеша логотипа Web App:
 
 ```bash
-mkdir -p data/webapp-logo data/webapp-emoji
+mkdir -p data/themes data/webapp-logo data/tariffs
+touch data/locales-overrides.json
 chown -R 10001:10001 data
 chmod -R u+rwX data
 ```
@@ -95,15 +117,37 @@ chmod -R u+rwX data
 docker compose up -d --build
 
 # Логи приложения
-docker compose logs -f remnawave-minishop
+docker compose logs -f backend worker frontend
 
-# Запуск с Caddy
-docker compose -f docker-compose-caddy.yml up -d --build
+# Рекомендуемый продакшен-вариант с Caddy
+cd deploy/examples/caddy      # или nginx, newt, no-proxy
+cp .env.example .env
+nano .env
+docker compose up -d
 
-# Запуск из готового образа
-IMAGE_TAG=3.1.0 docker compose -f docker-compose-remote-server.yml up -d
+# Запуск из готового образа с конкретным тегом
+IMAGE_TAG=3.1.0 docker compose up -d
 ```
 
-## Поддержка
+Для продакшен-запуска удобнее брать готовые папки из [`deploy/examples`](deploy/examples), а читать каноничные инструкции в [docs/getting-started/deployment.md](docs/getting-started/deployment.md). Предпочтительный вариант для обычного публичного сервера - Caddy: он сам выпускает и продлевает HTTPS-сертификаты. В папках рядом с compose лежат только конфиги и короткие ссылки на документацию.
+
+Имена образов для релизов:
+
+- `ghcr.io/3252a8/remnawave-minishop-backend`
+- `ghcr.io/3252a8/remnawave-minishop-worker`
+- `ghcr.io/3252a8/remnawave-minishop-frontend`
+- `docker.io/3252a8/remnawave-minishop-backend`
+- `docker.io/3252a8/remnawave-minishop-worker`
+- `docker.io/3252a8/remnawave-minishop-frontend`
+
+Сборка и публикация сразу в GHCR и Docker Hub:
+
+```bash
+docker login ghcr.io
+docker login docker.io
+IMAGE_TAG=v3.4.3 bash scripts/docker-build-push-images.sh
+```
+
+## Поддержать проект
 
 - Crypto: `USDT/Other ERC-20 0xeD506D44aae634fEc0E01C8835744fBedb7B2a44 (Ethereum/Polygon/Gnosis)`

backend/app_logging.py

@@ -0,0 +1,12 @@
+import logging
+import os
+import sys
+
+
+def configure_logging() -> None:
+    level = getattr(logging, os.getenv("LOG_LEVEL", "INFO").upper(), logging.INFO)
+    logging.basicConfig(
+        level=level,
+        stream=sys.stdout,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )

backend/bot/app/controllers/dispatcher_controller.py

@@ -6,19 +6,29 @@ from aiogram.enums import ParseMode
 from aiogram.fsm.storage.memory import MemoryStorage
 from sqlalchemy.orm import sessionmaker
 
+try:
+    from aiogram.fsm.storage.redis import RedisStorage
+except ModuleNotFoundError:  # pragma: no cover - dependency is installed in Docker image
+    RedisStorage = None  # type: ignore[assignment]
+
 from bot.middlewares.action_logger_middleware import ActionLoggerMiddleware
 from bot.middlewares.ban_check_middleware import BanCheckMiddleware
 from bot.middlewares.channel_subscription import ChannelSubscriptionMiddleware
 from bot.middlewares.db_session import DBSessionMiddleware
 from bot.middlewares.i18n import I18nMiddleware, get_i18n_instance
 from bot.middlewares.profile_sync import ProfileSyncMiddleware
+from bot.middlewares.update_antiflood import UpdateAntiFloodMiddleware
 from config.settings import Settings
 
 
 def build_dispatcher(
     settings: Settings, async_session_factory: sessionmaker
 ) -> tuple[Dispatcher, Bot, Dict]:
-    storage = MemoryStorage()
+    storage = (
+        RedisStorage.from_url(settings.REDIS_URL)
+        if settings.REDIS_URL and RedisStorage is not None
+        else MemoryStorage()
+    )
     default_props = DefaultBotProperties(parse_mode=ParseMode.HTML)
     bot = Bot(token=settings.BOT_TOKEN, default=default_props)
 
@@ -29,6 +39,7 @@ def build_dispatcher(
     dp["i18n_instance"] = i18n_instance
     dp["async_session_factory"] = async_session_factory
 
+    dp.update.outer_middleware(UpdateAntiFloodMiddleware(settings=settings))
     dp.update.outer_middleware(DBSessionMiddleware(async_session_factory))
     dp.update.outer_middleware(I18nMiddleware(i18n=i18n_instance, settings=settings))
     dp.update.outer_middleware(ProfileSyncMiddleware())

backend/bot/app/factories/build_services.py

@@ -0,0 +1,93 @@
+from aiogram import Bot
+from sqlalchemy.orm import sessionmaker
+
+from bot.middlewares.i18n import JsonI18n
+from bot.payment_providers import (
+    ServiceFactoryContext,
+    build_provider_configs,
+    build_provider_services,
+)
+from bot.services.email_auth_service import EmailAuthService
+from bot.services.lknpd_service import LknpdService
+from bot.services.notification_service import NotificationService
+from bot.services.panel_api_service import PanelApiService
+from bot.services.panel_dry_run_api_service import PanelDryRunApiService
+from bot.services.panel_webhook_service import PanelWebhookService
+from bot.services.promo_code_service import PromoCodeService
+from bot.services.referral_service import ReferralService
+from bot.services.subscription_service import SubscriptionService
+from bot.services.support_service import SupportService
+from config.settings import Settings
+
+
+def build_core_services(
+    settings: Settings,
+    bot: Bot,
+    async_session_factory: sessionmaker,
+    i18n: JsonI18n,
+    bot_username_for_default_return: str,
+):
+    panel_service = (
+        PanelDryRunApiService(settings)
+        if bool(getattr(settings, "panel_dry_run_enabled", False))
+        else PanelApiService(settings)
+    )
+    subscription_service = SubscriptionService(settings, panel_service, bot, i18n)
+    referral_service = ReferralService(settings, subscription_service, bot, i18n)
+    promo_code_service = PromoCodeService(settings, subscription_service, bot, i18n)
+    email_auth_service = EmailAuthService(settings, i18n)
+    notification_service = NotificationService(
+        bot,
+        settings,
+        i18n,
+        session_factory=async_session_factory,
+        email_auth_service=email_auth_service,
+        bot_username=bot_username_for_default_return,
+    )
+    support_service = SupportService(
+        async_session_factory,
+        settings,
+        bot,
+        i18n,
+        notification_service,
+        email_auth_service,
+    )
+    panel_webhook_service = PanelWebhookService(
+        bot, settings, i18n, async_session_factory, panel_service
+    )
+    provider_configs = build_provider_configs()
+    payment_services = build_provider_services(
+        ServiceFactoryContext(
+            settings=settings,
+            bot=bot,
+            async_session_factory=async_session_factory,
+            i18n=i18n,
+            bot_username_for_default_return=bot_username_for_default_return,
+            subscription_service=subscription_service,
+            referral_service=referral_service,
+            provider_configs=provider_configs,
+        )
+    )
+    lknpd_service = LknpdService(
+        settings.LKNPD_INN,
+        settings.LKNPD_PASSWORD,
+        api_url=settings.LKNPD_API_URL,
+    )
+
+    # These attachments are critical for auto-renew and panel pre-expiry hooks.
+    subscription_service.yookassa_service = payment_services.get("yookassa_service")
+    panel_webhook_service.subscription_service = subscription_service
+
+    services = {
+        "panel_service": panel_service,
+        "subscription_service": subscription_service,
+        "referral_service": referral_service,
+        "promo_code_service": promo_code_service,
+        "notification_service": notification_service,
+        "email_auth_service": email_auth_service,
+        "support_service": support_service,
+        "panel_webhook_service": panel_webhook_service,
+        "lknpd_service": lknpd_service,
+    }
+    services.update(payment_services)
+    return services

backend/bot/app/web/admin_api.py

@@ -6,8 +6,10 @@ from bot.app.web.admin_api_impl import (
     _runtime as _runtime,
     ads as _ads,
     auth as _auth,
+    backups as _backups,
     broadcast as _broadcast,
     common as _common,
+    health as _health,
     logs as _logs,
     panel as _panel,
     payments as _payments,
@@ -15,8 +17,11 @@ from bot.app.web.admin_api_impl import (
     routes as _routes,
     settings as _settings,
     stats as _stats,
+    support as _support,
     sync as _sync,
     tariffs as _tariffs,
+    themes as _themes,
+    translations as _translations,
     users as _users,
 )
 
@@ -24,16 +29,21 @@ _MODULES = (
     _runtime,
     _auth,
     _common,
+    _health,
     _stats,
     _users,
     _payments,
     _promos,
     _logs,
+    _support,
     _broadcast,
     _sync,
     _ads,
+    _backups,
     _settings,
     _tariffs,
+    _themes,
+    _translations,
     _panel,
     _routes,
 )

backend/bot/app/web/admin_api_impl/_runtime.py

@@ -28,6 +28,7 @@ from sqlalchemy.orm import sessionmaker
 from bot.app.web.admin_settings_manifest import (
     manifest_payload,
 )
+from bot.infra.webhook_queue import enqueue_webhook_event
 from bot.services.referral_service import ReferralService
 from bot.services.settings_override_service import (
     current_value,
@@ -36,10 +37,11 @@ from bot.services.settings_override_service import (
 from bot.utils import MessageContent, send_message_via_queue
 from bot.utils.message_queue import get_queue_manager
 from config.settings import Settings
-from config.tariffs_config import TariffsConfig
+from config.tariffs_config import TariffsConfig, default_payment_currency_code_for_settings
 from db.dal import (
     ad_dal,
     app_settings_dal,
+    locale_overrides_dal,
     message_log_dal,
     panel_sync_dal,
     payment_dal,

backend/bot/app/web/admin_api_impl/backups.py

@@ -0,0 +1,181 @@
+# ruff: noqa: F401,F403,F405,I001
+from ._runtime import *  # noqa: F403,F405
+
+import secrets
+import subprocess
+
+from bot.infra.redis import redis_lock
+from bot.services.backup_restore_service import (
+    BACKUP_UPLOAD_MAX_BYTES,
+    BackupArchiveError,
+    BackupArchiveInfo,
+    BackupRestoreError,
+    BackupRestoreService,
+)
+from bot.services.backup_worker import BackupWorker
+
+
+def _backup_archive_payload(archive) -> Dict[str, Any]:
+    return archive.to_payload()
+
+
+async def _read_uploaded_backup_file(request: web.Request) -> BackupArchiveInfo:
+    settings: Settings = request.app["settings"]
+    service = BackupRestoreService(settings)
+    backup_dir = service.backup_dir()
+    temp_path: Optional[Path] = None
+
+    reader = await request.multipart()
+    try:
+        async for part in reader:
+            if part.name != "file":
+                continue
+
+            original_filename = part.filename or "backup.zip"
+            temp_path = backup_dir / f".upload-{secrets.token_urlsafe(12)}.zip.tmp"
+            size = 0
+            with temp_path.open("wb") as handle:
+                while True:
+                    chunk = await part.read_chunk(size=1024 * 1024)
+                    if not chunk:
+                        break
+                    size += len(chunk)
+                    if size > BACKUP_UPLOAD_MAX_BYTES:
+                        raise BackupArchiveError("Backup archive is too large")
+                    handle.write(chunk)
+            if size <= 0:
+                raise BackupArchiveError("Uploaded archive is empty")
+            archive = service.import_uploaded_archive(temp_path, original_filename)
+            temp_path = None
+            return archive
+    finally:
+        if temp_path is not None and temp_path.exists():
+            try:
+                temp_path.unlink()
+            except OSError:
+                logger.warning("Failed to remove temporary backup upload %s", temp_path)
+
+    raise BackupArchiveError("file field is required")
+
+
+async def admin_backups_list_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    settings: Settings = request.app["settings"]
+    try:
+        service = BackupRestoreService(settings)
+        archives = service.list_archives()
+    except OSError as exc:
+        logger.exception("Failed to list backup archives")
+        return _error(500, "backup_list_failed", str(exc))
+    return _ok(
+        {
+            "backup_dir": str(service.backup_dir()),
+            "archives": [_backup_archive_payload(archive) for archive in archives],
+        }
+    )
+
+
+async def admin_backups_upload_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    content_type = (request.headers.get("Content-Type") or "").lower()
+    if not content_type.startswith("multipart/form-data"):
+        return _error(400, "invalid_backup_archive", "multipart file upload is required")
+    try:
+        archive = await _read_uploaded_backup_file(request)
+    except BackupArchiveError as exc:
+        return _error(400, "invalid_backup_archive", str(exc))
+    except OSError as exc:
+        logger.exception("Failed to save uploaded backup archive")
+        return _error(500, "backup_upload_failed", str(exc))
+    return _ok({"archive": _backup_archive_payload(archive)})
+
+
+async def admin_backups_create_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    settings: Settings = request.app["settings"]
+    bot = request.app["bot"]
+    session_factory = request.app.get("async_session_factory")
+    worker = BackupWorker(settings, bot, session_factory=session_factory)
+
+    ttl_seconds = max(
+        60,
+        int(
+            max(
+                getattr(settings, "BACKUP_LOCK_TTL_SECONDS", 7200) or 7200,
+                getattr(settings, "BACKUP_PG_DUMP_TIMEOUT_SECONDS", 1800) or 1800,
+            )
+        ),
+    )
+    try:
+        async with redis_lock(settings, "backup-worker", ttl_seconds=ttl_seconds) as acquired:
+            if not acquired:
+                return _error(409, "backup_create_busy", "Backup or restore is already running")
+            await worker.refresh_settings()
+            result = await worker.create_and_send_backup(backup_type="manual")
+            archive = BackupRestoreService(settings).inspect_archive(result.archive_path)
+    except BackupArchiveError as exc:
+        return _error(400, "invalid_backup_archive", str(exc))
+    except (OSError, RuntimeError, subprocess.SubprocessError, TimeoutError) as exc:
+        logger.exception("Manual backup creation failed")
+        return _error(500, "backup_create_failed", str(exc))
+    except Exception as exc:
+        logger.exception("Manual backup creation failed")
+        return _error(500, "backup_create_failed", str(exc))
+
+    return _ok(
+        {
+            "result": result.to_payload(),
+            "archive": _backup_archive_payload(archive),
+        }
+    )
+
+
+async def admin_backups_restore_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    settings: Settings = request.app["settings"]
+    payload = await _read_json(request)
+
+    archive_name = str(payload.get("archive_name") or "").strip()
+    restore_database = bool(payload.get("restore_database"))
+    restore_compose = bool(payload.get("restore_compose"))
+    confirm = bool(payload.get("confirm"))
+    if not confirm:
+        return _error(400, "restore_confirmation_required")
+
+    service = BackupRestoreService(settings)
+    ttl_seconds = max(
+        60,
+        int(
+            max(
+                getattr(settings, "BACKUP_LOCK_TTL_SECONDS", 7200) or 7200,
+                getattr(settings, "BACKUP_PG_RESTORE_TIMEOUT_SECONDS", 1800) or 1800,
+            )
+        ),
+    )
+    try:
+        async with redis_lock(settings, "backup-worker", ttl_seconds=ttl_seconds) as acquired:
+            if not acquired:
+                return _error(409, "backup_restore_busy", "Backup or restore is already running")
+            result = await service.restore_archive(
+                archive_name,
+                restore_database=restore_database,
+                restore_compose=restore_compose,
+            )
+    except BackupArchiveError as exc:
+        return _error(400, "invalid_backup_archive", str(exc))
+    except BackupRestoreError as exc:
+        logger.exception("Backup restore failed")
+        return _error(500, "backup_restore_failed", str(exc))
+    except (OSError, subprocess.SubprocessError, TimeoutError) as exc:
+        logger.exception("Backup restore failed")
+        return _error(500, "backup_restore_failed", str(exc))
+    finally:
+        try:
+            from db import database_setup
+
+            if restore_database and database_setup.async_engine is not None:
+                await database_setup.async_engine.dispose()
+        except Exception:
+            logger.exception("Failed to dispose DB engine after backup restore")
+
+    return _ok({"result": result.to_payload()})

backend/bot/app/web/admin_api_impl/broadcast.py

@@ -0,0 +1,242 @@
+# ruff: noqa: F401,F403,F405,I001
+from ._runtime import *  # noqa: F403,F405
+from .common import _panel_user_connection_activity
+
+import asyncio
+from collections import defaultdict
+
+from bot.utils.ttl_cache import AsyncTTLCache
+
+
+BROADCAST_TARGET_ACTIVE_NEVER_CONNECTED = "active_never_connected"
+BROADCAST_TARGETS = {
+    "all",
+    "active",
+    "inactive",
+    "expired",
+    "never",
+    BROADCAST_TARGET_ACTIVE_NEVER_CONNECTED,
+}
+PANEL_ACTIVITY_LOOKUP_CONCURRENCY = 10
+_ADMIN_BROADCAST_AUDIENCE_COUNT_CACHES: Dict[tuple[int, int], AsyncTTLCache] = {}
+
+
+def _resolve_panel_service(request: web.Request) -> Any:
+    subscription_service = request.app.get("subscription_service")
+    return getattr(subscription_service, "panel_service", None)
+
+
+async def _active_subscription_panel_uuids_by_user(
+    session: AsyncSession,
+) -> Dict[int, List[str]]:
+    now = datetime.now(timezone.utc)
+    stmt = (
+        select(Subscription.user_id, Subscription.panel_user_uuid)
+        .join(User, Subscription.user_id == User.user_id)
+        .where(
+            User.is_banned == False,
+            Subscription.is_active == True,
+            Subscription.end_date > now,
+            Subscription.panel_user_uuid.is_not(None),
+            Subscription.panel_user_uuid != "",
+        )
+        .order_by(Subscription.user_id.asc(), Subscription.end_date.desc())
+    )
+    result = await session.execute(stmt)
+
+    grouped: Dict[int, List[str]] = defaultdict(list)
+    seen: Dict[int, set[str]] = defaultdict(set)
+    for user_id, panel_uuid in result.all():
+        user_id_int = int(user_id)
+        panel_uuid_str = str(panel_uuid or "").strip()
+        if panel_uuid_str and panel_uuid_str not in seen[user_id_int]:
+            grouped[user_id_int].append(panel_uuid_str)
+            seen[user_id_int].add(panel_uuid_str)
+    return dict(grouped)
+
+
+async def _panel_connection_status(panel_service: Any, panel_uuid: str) -> str:
+    try:
+        panel_user = await panel_service.get_user_by_uuid(panel_uuid)
+    except Exception as exc:
+        logger.warning("Failed to fetch panel user activity uuid=%s: %s", panel_uuid, exc)
+        return "unknown"
+    activity = _panel_user_connection_activity(panel_user)
+    return str(activity.get("status") or "unknown")
+
+
+async def _user_ids_with_active_subscription_never_connected(
+    session: AsyncSession,
+    panel_service: Any,
+) -> List[int]:
+    panel_uuids_by_user = await _active_subscription_panel_uuids_by_user(session)
+    semaphore = asyncio.Semaphore(PANEL_ACTIVITY_LOOKUP_CONCURRENCY)
+
+    async def lookup(panel_uuid: str) -> str:
+        async with semaphore:
+            return await _panel_connection_status(panel_service, panel_uuid)
+
+    panel_uuids = list(
+        dict.fromkeys(
+            panel_uuid
+            for user_panel_uuids in panel_uuids_by_user.values()
+            for panel_uuid in user_panel_uuids
+        )
+    )
+    statuses_by_uuid = dict(
+        zip(
+            panel_uuids,
+            await asyncio.gather(*(lookup(uuid) for uuid in panel_uuids)),
+        )
+    )
+
+    user_ids: List[int] = []
+    for user_id, panel_uuids in panel_uuids_by_user.items():
+        statuses = [statuses_by_uuid.get(panel_uuid, "unknown") for panel_uuid in panel_uuids]
+        if statuses and all(status == "never" for status in statuses):
+            user_ids.append(user_id)
+    return user_ids
+
+
+def _admin_broadcast_audience_counts_cache(settings: Settings) -> Optional[AsyncTTLCache]:
+    ttl_seconds = int(
+        getattr(settings, "ADMIN_BROADCAST_AUDIENCE_COUNTS_CACHE_TTL_SECONDS", 30) or 0
+    )
+    if ttl_seconds <= 0:
+        return None
+    cache_key = (id(settings), ttl_seconds)
+    cache = _ADMIN_BROADCAST_AUDIENCE_COUNT_CACHES.get(cache_key)
+    if cache is None:
+        cache = AsyncTTLCache(
+            ttl_seconds=ttl_seconds,
+            settings=settings,
+            namespace="admin:broadcast_audience_counts",
+        )
+        _ADMIN_BROADCAST_AUDIENCE_COUNT_CACHES[cache_key] = cache
+    return cache
+
+
+async def _load_broadcast_audience_counts(
+    settings: Settings,
+    async_session_factory: sessionmaker,
+    panel_service: Any,
+) -> Dict[str, Optional[int]]:
+    cache = _admin_broadcast_audience_counts_cache(settings)
+    if cache is None:
+        return await _load_broadcast_audience_counts_uncached(
+            async_session_factory,
+            panel_service,
+        )
+    cache_key = "with-panel" if panel_service is not None else "without-panel"
+    return await cache.get_or_load(
+        cache_key,
+        lambda: _load_broadcast_audience_counts_uncached(
+            async_session_factory,
+            panel_service,
+        ),
+    )
+
+
+async def _load_broadcast_audience_counts_uncached(
+    async_session_factory: sessionmaker,
+    panel_service: Any,
+) -> Dict[str, Optional[int]]:
+    async with async_session_factory() as session:
+        counts: Dict[str, Optional[int]] = {
+            "all": await user_dal.count_all_active_users_for_broadcast(session),
+            "active": await user_dal.count_users_with_active_subscription_for_broadcast(session),
+            "inactive": await user_dal.count_users_without_active_subscription_for_broadcast(
+                session
+            ),
+            "expired": await user_dal.count_users_with_expired_subscription_for_broadcast(session),
+            "never": await user_dal.count_users_without_any_subscription_for_broadcast(session),
+            BROADCAST_TARGET_ACTIVE_NEVER_CONNECTED: None,
+        }
+        if panel_service is not None:
+            counts[BROADCAST_TARGET_ACTIVE_NEVER_CONNECTED] = len(
+                await _user_ids_with_active_subscription_never_connected(
+                    session,
+                    panel_service,
+                )
+            )
+    return counts
+
+
+async def admin_broadcast_route(request: web.Request) -> web.Response:
+    actor_id = _require_admin_user_id(request)
+    payload = await _read_json(request)
+    text = str(payload.get("text") or "").strip()
+    target = str(payload.get("target") or "all").strip().lower()
+    if not text:
+        return _error(400, "empty_text")
+    if target not in BROADCAST_TARGETS:
+        target = "all"
+
+    queue_manager = get_queue_manager()
+    if not queue_manager:
+        return _error(503, "queue_unavailable")
+
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+    async with async_session_factory() as session:
+        if target == BROADCAST_TARGET_ACTIVE_NEVER_CONNECTED:
+            panel_service = _resolve_panel_service(request)
+            if panel_service is None:
+                return _error(503, "panel_service_unavailable")
+            user_ids = await _user_ids_with_active_subscription_never_connected(
+                session,
+                panel_service,
+            )
+        elif target == "active":
+            user_ids = await user_dal.get_user_ids_with_active_subscription(session)
+        elif target == "inactive":
+            user_ids = await user_dal.get_user_ids_without_active_subscription(session)
+        elif target == "expired":
+            user_ids = await user_dal.get_user_ids_with_expired_subscription(session)
+        elif target == "never":
+            user_ids = await user_dal.get_user_ids_without_any_subscription(session)
+        else:
+            user_ids = await user_dal.get_all_active_user_ids_for_broadcast(session)
+
+        sent = 0
+        failed = 0
+        for uid in user_ids:
+            try:
+                await send_message_via_queue(
+                    queue_manager,
+                    int(uid),
+                    MessageContent(content_type="text", text=text),
+                    parse_mode="HTML",
+                    disable_web_page_preview=True,
+                )
+                sent += 1
+            except Exception as exc:
+                failed += 1
+                logger.debug("Broadcast queue failed for %s: %s", uid, exc)
+
+        await message_log_dal.create_message_log(
+            session,
+            {
+                "user_id": actor_id,
+                "event_type": "admin_broadcast_webapp",
+                "content": f"target={target} sent={sent} failed={failed} text={text[:120]}",
+                "is_admin_event": True,
+            },
+        )
+
+    return _ok({"queued": sent, "failed": failed, "target": target})
+
+
+async def admin_broadcast_audience_counts_route(request: web.Request) -> web.Response:
+    """Return how many users each broadcast audience currently resolves to."""
+    _require_admin_user_id(request)
+
+    settings: Settings = request.app["settings"]
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+    panel_service = _resolve_panel_service(request)
+    counts = await _load_broadcast_audience_counts(
+        settings,
+        async_session_factory,
+        panel_service,
+    )
+
+    return _ok({"counts": counts})

backend/bot/app/web/admin_api_impl/common.py

@@ -22,6 +22,175 @@ async def _read_json(request: web.Request) -> Dict[str, Any]:
         return {}
 
 
+_PANEL_LAST_CONNECTED_KEYS = (
+    "onlineAt",
+    "online_at",
+    "lastSeenAt",
+    "last_seen_at",
+    "lastConnectedAt",
+    "last_connected_at",
+    "lastConnectionAt",
+    "last_connection_at",
+)
+_PANEL_CONNECTION_MARKER_KEYS = (
+    *_PANEL_LAST_CONNECTED_KEYS,
+    "firstConnectedAt",
+    "first_connected_at",
+    "lastConnectedNodeUuid",
+    "last_connected_node_uuid",
+)
+_PANEL_CONNECTION_MARKER_OBJECT_KEYS = ("lastConnectedNode", "last_connected_node")
+_PANEL_TRAFFIC_OBJECT_KEYS = ("userTraffic", "user_traffic", "traffic", "trafficStats")
+_PANEL_TRAFFIC_USED_KEYS = (
+    "lifetimeUsedTrafficBytes",
+    "lifetime_used_traffic_bytes",
+    "usedTrafficBytes",
+    "used_traffic_bytes",
+    "trafficUsedBytes",
+    "traffic_used_bytes",
+    "downloadBytes",
+    "download_bytes",
+    "uploadBytes",
+    "upload_bytes",
+)
+
+
+def _panel_user_payload(panel_user_data: Any) -> Dict[str, Any]:
+    if not isinstance(panel_user_data, dict):
+        return {}
+    response = panel_user_data.get("response")
+    if isinstance(response, dict) and not any(
+        key in panel_user_data
+        for key in ("uuid", "shortUuid", "subscriptionUrl", "userTraffic", "status")
+    ):
+        return response
+    return panel_user_data
+
+
+def _coerce_panel_datetime(value: Any) -> Optional[str]:
+    if value is None or value is False:
+        return None
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, (int, float)):
+        if value <= 0:
+            return None
+        seconds = float(value) / 1000.0 if value > 10_000_000_000 else float(value)
+        try:
+            return datetime.fromtimestamp(seconds, tz=timezone.utc).isoformat()
+        except (OSError, OverflowError, ValueError):
+            return None
+    text = str(value).strip()
+    if not text or text.lower() in {"0", "null", "none", "never"}:
+        return None
+    if text.isdigit():
+        return _coerce_panel_datetime(int(text))
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed.isoformat()
+
+
+def _coerce_panel_int(value: Any) -> Optional[int]:
+    try:
+        if value is None or value == "":
+            return None
+        return int(float(value))
+    except (TypeError, ValueError):
+        return None
+
+
+def _panel_nested_dicts(panel_user: Dict[str, Any], keys: Tuple[str, ...]) -> List[Dict[str, Any]]:
+    out: List[Dict[str, Any]] = []
+    for key in keys:
+        value = panel_user.get(key)
+        if isinstance(value, dict):
+            out.append(value)
+    return out
+
+
+def _panel_user_connection_containers(panel_user: Dict[str, Any]) -> List[Dict[str, Any]]:
+    traffic_containers = _panel_nested_dicts(panel_user, _PANEL_TRAFFIC_OBJECT_KEYS)
+    marker_containers = _panel_nested_dicts(
+        panel_user,
+        _PANEL_CONNECTION_MARKER_OBJECT_KEYS,
+    )
+    for traffic_container in traffic_containers:
+        marker_containers.extend(
+            _panel_nested_dicts(traffic_container, _PANEL_CONNECTION_MARKER_OBJECT_KEYS)
+        )
+    return [panel_user, *traffic_containers, *marker_containers]
+
+
+def _panel_user_last_connected_at(panel_user_data: Any) -> Optional[str]:
+    panel_user = _panel_user_payload(panel_user_data)
+    if not panel_user:
+        return None
+    for container in _panel_user_connection_containers(panel_user):
+        for key in _PANEL_LAST_CONNECTED_KEYS:
+            connected_at = _coerce_panel_datetime(container.get(key))
+            if connected_at:
+                return connected_at
+    return None
+
+
+def _panel_user_positive_traffic_bytes(panel_user: Dict[str, Any]) -> bool:
+    containers = [panel_user, *_panel_nested_dicts(panel_user, _PANEL_TRAFFIC_OBJECT_KEYS)]
+    for container in containers:
+        for key in _PANEL_TRAFFIC_USED_KEYS:
+            value = _coerce_panel_int(container.get(key))
+            if value is not None and value > 0:
+                return True
+    return False
+
+
+def _panel_user_has_connection_marker(panel_user: Dict[str, Any]) -> bool:
+    for container in _panel_user_connection_containers(panel_user):
+        for key in _PANEL_CONNECTION_MARKER_KEYS:
+            if key in container:
+                return True
+    for container in [panel_user, *_panel_nested_dicts(panel_user, _PANEL_TRAFFIC_OBJECT_KEYS)]:
+        for key in _PANEL_CONNECTION_MARKER_OBJECT_KEYS:
+            if key in container:
+                return True
+    return False
+
+
+def _panel_user_has_connected_marker_value(panel_user: Dict[str, Any]) -> bool:
+    for container in _panel_user_connection_containers(panel_user):
+        for key in (*_PANEL_LAST_CONNECTED_KEYS, "firstConnectedAt", "first_connected_at"):
+            if _coerce_panel_datetime(container.get(key)):
+                return True
+        for key in ("lastConnectedNodeUuid", "last_connected_node_uuid"):
+            if str(container.get(key) or "").strip():
+                return True
+    for container in [panel_user, *_panel_nested_dicts(panel_user, _PANEL_TRAFFIC_OBJECT_KEYS)]:
+        for key in _PANEL_CONNECTION_MARKER_OBJECT_KEYS:
+            marker = container.get(key)
+            if isinstance(marker, dict) and any(
+                str(value or "").strip() for value in marker.values()
+            ):
+                return True
+            if marker and not isinstance(marker, dict):
+                return True
+    return False
+
+
+def _panel_user_connection_activity(panel_user_data: Any) -> Dict[str, Any]:
+    panel_user = _panel_user_payload(panel_user_data)
+    last_connected_at = _panel_user_last_connected_at(panel_user)
+    if not panel_user:
+        return {"status": "unknown", "last_connected_at": None}
+    if last_connected_at or _panel_user_positive_traffic_bytes(panel_user):
+        return {"status": "connected", "last_connected_at": last_connected_at}
+    if _panel_user_has_connected_marker_value(panel_user):
+        return {"status": "connected", "last_connected_at": last_connected_at}
+    if _panel_user_has_connection_marker(panel_user):
+        return {"status": "never", "last_connected_at": None}
+    return {"status": "unknown", "last_connected_at": None}
+
+
 def _serialize_user(user: User) -> Dict[str, Any]:
     return {
         "user_id": int(user.user_id),
@@ -94,6 +263,9 @@ def _serialize_subscription(sub: Subscription) -> Dict[str, Any]:
     regular_unlimited_override = bool(getattr(sub, "regular_unlimited_override", False))
     premium_unlimited_override = bool(getattr(sub, "premium_unlimited_override", False))
     premium_limit_bytes = _premium_limit_bytes_from_subscription(sub)
+    provider = sub.provider
+    is_trial = str(provider or "").strip().lower() == "trial"
+    display_label = "Trial" if is_trial else sub.tariff_key
     return {
         "subscription_id": int(sub.subscription_id),
         "panel_user_uuid": sub.panel_user_uuid,
@@ -117,9 +289,13 @@ def _serialize_subscription(sub: Subscription) -> Dict[str, Any]:
         "regular_unlimited_override": regular_unlimited_override,
         "premium_unlimited_override": premium_unlimited_override,
         "premium_is_limited": bool(sub.premium_is_limited),
+        "hwid_device_limit": getattr(sub, "hwid_device_limit", None),
+        "extra_hwid_devices": int(getattr(sub, "extra_hwid_devices", 0) or 0),
         "tariff_key": sub.tariff_key,
+        "display_label": display_label,
+        "is_trial": is_trial,
         "auto_renew_enabled": bool(sub.auto_renew_enabled),
-        "provider": sub.provider,
+        "provider": provider,
         "is_throttled": bool(sub.is_throttled),
     }
 
@@ -143,12 +319,18 @@ def _payment_traffic_gb_split(payment: Payment) -> Tuple[Optional[float], Option
     return None, None
 
 
-def _payment_user_display_label(loaded_user: Any, payment_user_id: int) -> str:
-    """Human-facing name for payments tables: TG profile name, else email, else user id."""
-    if loaded_user is None:
-        return str(payment_user_id)
+def _user_display_label(
+    loaded_user: Any,
+    fallback_user_id: Optional[int],
+    *,
+    first_name: Optional[str] = None,
+    last_name: Optional[str] = None,
+    username: Optional[str] = None,
+    email: Optional[str] = None,
+) -> Optional[str]:
+    """Human-facing name: TG profile name, else email, else user id."""
     tid = getattr(loaded_user, "telegram_id", None)
-    if tid is not None:
+    if loaded_user is not None and tid is not None:
         fn = (getattr(loaded_user, "first_name", None) or "").strip()
         ln = (getattr(loaded_user, "last_name", None) or "").strip()
         full = f"{fn} {ln}".strip()
@@ -157,10 +339,30 @@ def _payment_user_display_label(loaded_user: Any, payment_user_id: int) -> str:
         un = (getattr(loaded_user, "username", None) or "").strip()
         if un:
             return un if un.startswith("@") else f"@{un}"
-        return str(payment_user_id)
-    email = (getattr(loaded_user, "email", None) or "").strip()
-    if email:
-        return email
+    elif loaded_user is not None:
+        email = (getattr(loaded_user, "email", None) or "").strip()
+        if email:
+            return email
+    fn = (first_name or "").strip()
+    ln = (last_name or "").strip()
+    full = f"{fn} {ln}".strip()
+    if full:
+        return full
+    un = (username or "").strip()
+    if un:
+        return un if un.startswith("@") else f"@{un}"
+    email_value = (email or "").strip()
+    if email_value:
+        return email_value
+    if fallback_user_id is None:
+        return None
+    return str(fallback_user_id)
+
+
+def _payment_user_display_label(loaded_user: Any, payment_user_id: int) -> str:
+    label = _user_display_label(loaded_user, payment_user_id)
+    if label:
+        return label
     return str(payment_user_id)
 
 
@@ -229,15 +431,27 @@ def _serialize_ad(campaign: AdCampaign, totals: Optional[Dict[str, Any]] = None)
 
 
 def _serialize_log(entry: MessageLog) -> Dict[str, Any]:
+    author_user = entry.__dict__.get("author_user")
+    target_user = entry.__dict__.get("target_user")
+    user_id = int(entry.user_id) if entry.user_id is not None else None
+    target_user_id = int(entry.target_user_id) if entry.target_user_id is not None else None
     return {
         "log_id": int(entry.log_id),
-        "user_id": int(entry.user_id) if entry.user_id else None,
+        "user_id": user_id,
+        "user_label": _user_display_label(
+            author_user,
+            user_id,
+            first_name=entry.telegram_first_name,
+            username=entry.telegram_username,
+        ),
         "telegram_username": entry.telegram_username,
         "telegram_first_name": entry.telegram_first_name,
+        "email": getattr(author_user, "email", None),
         "event_type": entry.event_type,
         "content": entry.content,
         "is_admin_event": bool(entry.is_admin_event),
-        "target_user_id": int(entry.target_user_id) if entry.target_user_id else None,
+        "target_user_id": target_user_id,
+        "target_user_label": _user_display_label(target_user, target_user_id),
         "timestamp": entry.timestamp.isoformat() if entry.timestamp else None,
     }
 
@@ -270,6 +484,10 @@ def _write_tariffs_config_file(path: Path, config: TariffsConfig) -> None:
         path.write_text(payload, encoding="utf-8")
 
 
+def _webapp_themes_catalog_payload(config: Any) -> Dict[str, Any]:
+    return config.model_dump(mode="json", exclude_none=True)
+
+
 def _panel_node_uuid_key(node: Dict[str, Any]) -> str:
     uid = node.get("nodeUuid") or node.get("node_uuid") or node.get("uuid") or node.get("id")
     return str(uid).strip().lower() if uid else ""

backend/bot/app/web/admin_api_impl/health.py

@@ -0,0 +1,19 @@
+# ruff: noqa: F401,F403,F405,I001
+from datetime import datetime, timezone
+
+from ._runtime import *  # noqa: F403,F405
+from .auth import _require_admin_user_id
+from .common import _ok
+from bot.services.config_health_service import collect_config_alerts
+
+
+async def admin_health_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    refresh = str(request.query.get("refresh", "")).strip().lower() in {"1", "true", "yes"}
+    alerts = await collect_config_alerts(request, refresh=refresh)
+    return _ok(
+        {
+            "alerts": alerts,
+            "checked_at": datetime.now(timezone.utc).isoformat(),
+        }
+    )

backend/bot/app/web/admin_api_impl/payments.py

@@ -32,6 +32,35 @@ async def admin_payments_list_route(request: web.Request) -> web.Response:
     )
 
 
+async def admin_payment_detail_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+
+    try:
+        payment_id = int(request.match_info["payment_id"])
+    except (TypeError, ValueError):
+        return _error(400, "invalid_payment", "Invalid payment id")
+
+    async with async_session_factory() as session:
+        payment = await payment_dal.get_payment_by_db_id(session, payment_id)
+        if not payment:
+            return _error(404, "not_found", "Payment not found")
+
+        payload = _serialize_payment(payment)
+        payload.update(
+            {
+                "yookassa_payment_id": payment.yookassa_payment_id,
+                "idempotence_key": payment.idempotence_key,
+                "promo_code": (
+                    payment.promo_code_used.code if payment.promo_code_used is not None else None
+                ),
+                "updated_at": payment.updated_at.isoformat() if payment.updated_at else None,
+            }
+        )
+
+    return _ok({"payment": payload})
+
+
 async def admin_payments_export_route(request: web.Request) -> web.Response:
     _require_admin_user_id(request)
     async_session_factory: sessionmaker = request.app["async_session_factory"]

backend/bot/app/web/admin_api_impl/routes.py

@@ -6,15 +6,21 @@ def setup_admin_routes(app: web.Application) -> None:
     router = app.router
     router.add_get("/api/admin/me", admin_me_route)
     router.add_get("/api/admin/stats", admin_stats_route)
+    router.add_get("/api/admin/health", admin_health_route)
 
     router.add_get("/api/admin/users", admin_users_list_route)
     router.add_get("/api/admin/users/{user_id:-?\\d+}", admin_user_detail_route)
+    router.add_get("/api/admin/users/{user_id:-?\\d+}/referrals", admin_user_referrals_route)
     router.add_get("/api/admin/users/{user_id:-?\\d+}/avatar", admin_user_avatar_route)
     router.add_post("/api/admin/users/{user_id:-?\\d+}/ban", admin_user_ban_route)
     router.add_post("/api/admin/users/{user_id:-?\\d+}/message", admin_user_message_route)
     router.add_post(
         "/api/admin/users/{user_id:-?\\d+}/message/preview", admin_user_message_preview_route
     )
+    router.add_post(
+        "/api/admin/users/{user_id:-?\\d+}/telegram-profile-link",
+        admin_user_telegram_profile_link_route,
+    )
     router.add_post("/api/admin/users/{user_id:-?\\d+}/reset-trial", admin_user_reset_trial_route)
     router.add_post("/api/admin/users/{user_id:-?\\d+}/extend", admin_user_extend_route)
     router.add_post(
@@ -25,6 +31,10 @@ def setup_admin_routes(app: web.Application) -> None:
         "/api/admin/users/{user_id:-?\\d+}/regular-traffic-override",
         admin_user_regular_traffic_override_route,
     )
+    router.add_post(
+        "/api/admin/users/{user_id:-?\\d+}/hwid-device-limit",
+        admin_user_hwid_device_limit_route,
+    )
     router.add_post(
         "/api/admin/users/{user_id:-?\\d+}/traffic-grant",
         admin_user_traffic_grant_route,
@@ -32,6 +42,7 @@ def setup_admin_routes(app: web.Application) -> None:
     router.add_delete("/api/admin/users/{user_id:-?\\d+}", admin_user_delete_route)
 
     router.add_get("/api/admin/payments", admin_payments_list_route)
+    router.add_get("/api/admin/payments/{payment_id:\\d+}", admin_payment_detail_route)
     router.add_get("/api/admin/payments/export.csv", admin_payments_export_route)
 
     router.add_get("/api/admin/promos", admin_promos_list_route)
@@ -41,6 +52,17 @@ def setup_admin_routes(app: web.Application) -> None:
 
     router.add_get("/api/admin/logs", admin_logs_route)
 
+    router.add_get("/api/admin/support/tickets", admin_support_tickets_route)
+    router.add_get("/api/admin/support/tickets/{id:\\d+}", admin_support_ticket_detail_route)
+    router.add_post(
+        "/api/admin/support/tickets/{id:\\d+}/messages",
+        admin_support_ticket_reply_route,
+    )
+    router.add_patch("/api/admin/support/tickets/{id:\\d+}", admin_support_ticket_patch_route)
+    router.add_post("/api/admin/support/tickets/{id:\\d+}/read", admin_support_ticket_read_route)
+    router.add_get("/api/admin/support/stats", admin_support_stats_route)
+
+    router.add_get("/api/admin/broadcast/audience-counts", admin_broadcast_audience_counts_route)
     router.add_post("/api/admin/broadcast", admin_broadcast_route)
     router.add_post("/api/admin/sync", admin_sync_route)
 
@@ -51,7 +73,17 @@ def setup_admin_routes(app: web.Application) -> None:
 
     router.add_get("/api/admin/settings", admin_settings_get_route)
     router.add_patch("/api/admin/settings", admin_settings_patch_route)
+    router.add_get("/api/admin/translations", admin_translations_get_route)
+    router.add_patch("/api/admin/translations", admin_translations_patch_route)
 
     router.add_get("/api/admin/tariffs", admin_tariffs_get_route)
     router.add_put("/api/admin/tariffs", admin_tariffs_save_route)
+    router.add_get("/api/admin/themes", admin_themes_get_route)
+    router.add_put("/api/admin/themes", admin_themes_save_route)
+    router.add_post("/api/admin/appearance/logo", admin_appearance_logo_upload_route)
+    router.add_post("/api/admin/appearance/favicon", admin_appearance_favicon_upload_route)
+    router.add_get("/api/admin/backups", admin_backups_list_route)
+    router.add_post("/api/admin/backups/create", admin_backups_create_route)
+    router.add_post("/api/admin/backups/upload", admin_backups_upload_route)
+    router.add_post("/api/admin/backups/restore", admin_backups_restore_route)
     router.add_get("/api/admin/panel/internal-squads", admin_panel_internal_squads_route)

backend/bot/app/web/admin_api_impl/settings.py

@@ -1,5 +1,11 @@
 # ruff: noqa: F401,F403,F405,I001
 from ._runtime import *  # noqa: F403,F405
+from .webapp_runtime import refresh_webapp_runtime_after_settings_change
+
+from config.subscription_guides_config import (
+    SubscriptionGuidesConfigError,
+    subscription_guides_admin_config_json,
+)
 
 
 async def admin_settings_get_route(request: web.Request) -> web.Response:
@@ -13,6 +19,7 @@ async def admin_settings_get_route(request: web.Request) -> web.Response:
     overrides_by_key = {entry["key"]: entry for entry in overrides}
 
     fields = manifest_payload()
+    webhook_base_url = str(settings.WEBHOOK_BASE_URL or "").strip().rstrip("/")
     sections: Dict[str, Dict[str, Any]] = {}
     for field in fields:
         key = field["key"]
@@ -26,14 +33,35 @@ async def admin_settings_get_route(request: web.Request) -> web.Response:
         override = overrides_by_key.get(key)
         value = current_value(settings, key)
         is_secret = bool(field.get("secret"))
+        overridden = bool(override)
+        source = None
+        read_error = None
+        if key == "SUBSCRIPTION_PAGE_CONFIG_JSON":
+            try:
+                value, source = subscription_guides_admin_config_json(settings)
+                overridden = source == "admin_json"
+            except SubscriptionGuidesConfigError as exc:
+                read_error = str(exc)
         response_field = {
             **field,
             "value": "" if is_secret else value,
-            "overridden": bool(override),
+            "overridden": overridden,
             "updated_at": override.get("updated_at") if override else None,
         }
+        if source:
+            response_field["source"] = source
+        if read_error:
+            response_field["read_error"] = read_error
         if is_secret:
             response_field["has_value"] = bool(value)
+        webhook_path = str(response_field.get("webhook_path") or "").strip()
+        if webhook_path:
+            if not webhook_path.startswith("/"):
+                webhook_path = f"/{webhook_path}"
+            response_field["webhook_path"] = webhook_path
+            response_field["webhook_base_url_configured"] = bool(webhook_base_url)
+            if webhook_base_url:
+                response_field["webhook_url"] = f"{webhook_base_url}{webhook_path}"
         sections[section_id]["fields"].append(response_field)
 
     ordered_sections = sorted(sections.values(), key=lambda s: s["order"])
@@ -51,6 +79,13 @@ async def admin_settings_patch_route(request: web.Request) -> web.Response:
         return _error(400, "invalid_updates")
     if not isinstance(deletes, list):
         return _error(400, "invalid_deletes")
+    if (
+        "SUBSCRIPTION_PAGE_CONFIG_JSON" in updates
+        and not str(updates.get("SUBSCRIPTION_PAGE_CONFIG_JSON") or "").strip()
+    ):
+        updates = dict(updates)
+        updates.pop("SUBSCRIPTION_PAGE_CONFIG_JSON", None)
+        deletes = [*deletes, "SUBSCRIPTION_PAGE_CONFIG_JSON"]
 
     result = await update_overrides(
         settings,
@@ -65,10 +100,6 @@ async def admin_settings_patch_route(request: web.Request) -> web.Response:
             status=400,
         )
 
-    # Bust the public webapp settings cache so users see new values immediately.
-    cache = request.app.get("webapp_settings_cache")
-    if isinstance(cache, dict):
-        cache["ts"] = 0.0
-        cache["data"] = {}
+    await refresh_webapp_runtime_after_settings_change(request, updates=updates, deletes=deletes)
 
     return _ok({"applied": result.get("applied", 0), "reverted": result.get("reverted", 0)})

backend/bot/app/web/admin_api_impl/stats.py

@@ -0,0 +1,168 @@
+# ruff: noqa: F401,F403,F405,I001
+import asyncio
+
+from ._runtime import *  # noqa: F403,F405
+from .auth import _require_admin_user_id
+from .common import _ok, _serialize_payment
+from bot.utils.ttl_cache import AsyncTTLCache
+
+_ADMIN_PANEL_STATS_CACHES: Dict[tuple[int, int], AsyncTTLCache] = {}
+_ADMIN_DB_STATS_CACHES: Dict[tuple[int, int], AsyncTTLCache] = {}
+
+
+async def admin_me_route(request: web.Request) -> web.Response:
+    user_id = _require_admin_user_id(request)
+    settings: Settings = request.app["settings"]
+    return _ok({}, user_id=user_id, admin_ids=list(settings.ADMIN_IDS or []))
+
+
+async def admin_stats_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    settings: Settings = request.app["settings"]
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+
+    payload = dict(await _load_admin_db_stats(settings, async_session_factory))
+
+    panel_service = request.app.get("panel_service")
+    if panel_service is not None:
+        payload["panel"] = await _load_admin_panel_stats(request, settings, panel_service)
+
+    queue_manager = get_queue_manager()
+    if queue_manager:
+        try:
+            payload["queue"] = queue_manager.get_queue_stats()
+        except Exception:  # pragma: no cover - defensive
+            payload["queue"] = None
+
+    payload["currency_symbol"] = default_payment_currency_code_for_settings(settings)
+    return _ok(payload)
+
+
+async def _load_admin_db_stats(
+    settings: Settings,
+    async_session_factory: sessionmaker,
+) -> Dict[str, Any]:
+    cache = _admin_db_stats_cache(settings)
+    if cache is None:
+        return await _load_admin_db_stats_uncached(async_session_factory)
+    return await cache.get_or_load(
+        "db",
+        lambda: _load_admin_db_stats_uncached(async_session_factory),
+    )
+
+
+async def _load_admin_db_stats_uncached(async_session_factory: sessionmaker) -> Dict[str, Any]:
+    async with async_session_factory() as session:
+        user_stats = await user_dal.get_enhanced_user_statistics(session)
+        financial_stats = await payment_dal.get_financial_statistics(session)
+        sync_status = await panel_sync_dal.get_panel_sync_status(session)
+        recent_payments = await payment_dal.get_recent_payment_logs_with_user(session, limit=10)
+
+    return {
+        "users": user_stats,
+        "financial": financial_stats,
+        "panel_sync": {
+            "status": sync_status.status if sync_status else "never_run",
+            "last_sync_time": sync_status.last_sync_time.isoformat()
+            if sync_status and sync_status.last_sync_time
+            else None,
+            "details": sync_status.details if sync_status else None,
+            "users_processed": sync_status.users_processed_from_panel if sync_status else 0,
+            "subscriptions_synced": sync_status.subscriptions_synced if sync_status else 0,
+        },
+        "recent_payments": [_serialize_payment(p) for p in recent_payments],
+    }
+
+
+def _admin_db_stats_cache(settings: Settings) -> Optional[AsyncTTLCache]:
+    ttl_seconds = int(getattr(settings, "ADMIN_DB_STATS_CACHE_TTL_SECONDS", 5) or 0)
+    if ttl_seconds <= 0:
+        return None
+    cache_key = (id(settings), ttl_seconds)
+    cache = _ADMIN_DB_STATS_CACHES.get(cache_key)
+    if cache is None:
+        cache = AsyncTTLCache(
+            ttl_seconds=ttl_seconds,
+            settings=settings,
+            namespace="admin:db_stats",
+        )
+        _ADMIN_DB_STATS_CACHES[cache_key] = cache
+    return cache
+
+
+async def _load_admin_panel_stats(
+    request: web.Request,
+    settings: Settings,
+    panel_service,
+) -> Dict[str, Any]:
+    cache = _admin_panel_stats_cache(settings)
+    if cache is None:
+        return await _load_admin_panel_stats_uncached(panel_service)
+    return await cache.get_or_load("panel", lambda: _load_admin_panel_stats_uncached(panel_service))
+
+
+def _admin_panel_stats_cache(settings: Settings) -> Optional[AsyncTTLCache]:
+    ttl_seconds = int(getattr(settings, "ADMIN_PANEL_STATS_CACHE_TTL_SECONDS", 15) or 0)
+    if ttl_seconds <= 0:
+        return None
+    cache_key = (id(settings), ttl_seconds)
+    cache = _ADMIN_PANEL_STATS_CACHES.get(cache_key)
+    if cache is None:
+        cache = AsyncTTLCache(
+            ttl_seconds=ttl_seconds,
+            settings=settings,
+            namespace="admin:panel_stats",
+        )
+        _ADMIN_PANEL_STATS_CACHES[cache_key] = cache
+    return cache
+
+
+async def _load_admin_panel_stats_uncached(panel_service) -> Dict[str, Any]:
+    try:
+        today = datetime.now(timezone.utc).date()
+        start_d = today - timedelta(days=7)
+        system, bandwidth, nodes, nodes_bw, lookups = await asyncio.gather(
+            _safe_panel_call(panel_service.get_system_stats(), "system stats"),
+            _safe_panel_call(panel_service.get_bandwidth_stats(), "bandwidth stats"),
+            _safe_panel_call(panel_service.get_nodes_statistics(), "nodes stats"),
+            _safe_panel_call(
+                panel_service.get_nodes_bandwidth_usage(
+                    start=start_d.isoformat(),
+                    end=today.isoformat(),
+                    top_nodes_limit=64,
+                ),
+                "nodes bandwidth range",
+            ),
+            _safe_panel_call(panel_service.get_nodes_online_lookups(), "nodes online lookups"),
+        )
+
+        panel_body: Dict[str, Any] = {
+            "system": system or {},
+            "bandwidth": bandwidth or {},
+            "nodes": nodes or {},
+            "nodes_bandwidth": nodes_bw or {},
+        }
+        if isinstance(lookups, dict):
+            try:
+                online_map = _panel_nodes_online_by_uuid(panel_body.get("nodes"))
+                for k, v in lookups.get("byUuid", {}).items():
+                    online_map[k] = v
+                _enrich_bandwidth_nodes_with_online(
+                    panel_body.get("nodes_bandwidth"),
+                    online_map,
+                    lookups.get("byName") or {},
+                )
+            except Exception as exc_merge:  # pragma: no cover
+                logger.debug("Panel nodes online merge skipped: %s", exc_merge)
+        return panel_body
+    except Exception as exc:
+        logger.debug("Panel stats unavailable: %s", exc)
+        return {"error": "unavailable"}
+
+
+async def _safe_panel_call(awaitable, label: str) -> Any:
+    try:
+        return await awaitable
+    except Exception as exc:  # pragma: no cover - optional panel endpoints
+        logger.debug("Panel %s unavailable: %s", label, exc)
+        return None

backend/bot/app/web/admin_api_impl/support.py

@@ -0,0 +1,251 @@
+# ruff: noqa: F401,F403,F405,I001
+from ._runtime import *  # noqa: F403,F405
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, constr, field_validator
+
+from bot.services.support_service import TicketNotFound
+from db.dal import support_dal, user_dal
+from db.models import SupportTicket, SupportTicketMessage
+
+
+class AdminTicketReplyPayload(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    body: constr(min_length=1, max_length=4000)
+    is_internal_note: bool = False
+
+    @field_validator("body")
+    @classmethod
+    def _strip_body(cls, value: str) -> str:
+        stripped = value.strip()
+        if not stripped:
+            raise ValueError("empty_text")
+        return stripped
+
+
+class AdminTicketPatchPayload(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    status: Optional[Literal["open", "awaiting_user", "awaiting_admin", "resolved", "closed"]] = (
+        None
+    )
+    priority: Optional[Literal["low", "normal", "high", "urgent"]] = None
+    category: Optional[Literal["billing", "technical", "account", "other"]] = None
+    assigned_admin_id: Optional[int] = None
+
+
+def _validate_model_payload(model_cls, payload: Dict[str, Any]):
+    try:
+        return model_cls.model_validate(payload), None
+    except ValidationError:
+        return None, _error(400, "invalid_request", "Invalid request")
+
+
+def _support_ticket_payload(ticket: SupportTicket) -> Dict[str, Any]:
+    return {
+        "ticket_id": ticket.ticket_id,
+        "user_id": ticket.user_id,
+        "subject": ticket.subject,
+        "category": ticket.category,
+        "priority": ticket.priority,
+        "status": ticket.status,
+        "assigned_admin_id": ticket.assigned_admin_id,
+        "last_message_at": ticket.last_message_at.isoformat() if ticket.last_message_at else None,
+        "last_message_role": ticket.last_message_role,
+        "unread_user_count": int(ticket.unread_user_count or 0),
+        "unread_admin_count": int(ticket.unread_admin_count or 0),
+        "created_at": ticket.created_at.isoformat() if ticket.created_at else None,
+        "updated_at": ticket.updated_at.isoformat() if ticket.updated_at else None,
+        "closed_at": ticket.closed_at.isoformat() if ticket.closed_at else None,
+    }
+
+
+def _user_display_name(user) -> Optional[str]:
+    if not user:
+        return None
+    name = " ".join(
+        part.strip() for part in [user.first_name, user.last_name] if part and part.strip()
+    ).strip()
+    return name or user.username or user.email or str(user.user_id)
+
+
+def _support_message_payload(
+    message: SupportTicketMessage,
+    *,
+    authors: Optional[Dict[int, Any]] = None,
+) -> Dict[str, Any]:
+    author = authors.get(message.author_user_id) if authors and message.author_user_id else None
+    return {
+        "message_id": message.message_id,
+        "ticket_id": message.ticket_id,
+        "author_role": message.author_role,
+        "author_user_id": message.author_user_id,
+        "author_name": _user_display_name(author),
+        "body": message.body,
+        "is_internal_note": bool(message.is_internal_note),
+        "created_at": message.created_at.isoformat() if message.created_at else None,
+        "read_by_user_at": message.read_by_user_at.isoformat() if message.read_by_user_at else None,
+        "read_by_admin_at": message.read_by_admin_at.isoformat()
+        if message.read_by_admin_at
+        else None,
+    }
+
+
+def _admin_support_user_payload(user) -> Dict[str, Any]:
+    if not user:
+        return {}
+    return {
+        "user_id": user.user_id,
+        "telegram_id": user.telegram_id,
+        "username": user.username,
+        "first_name": user.first_name,
+        "last_name": user.last_name,
+        "email": user.email,
+        "telegram_photo_url": user.telegram_photo_url,
+        "is_banned": bool(user.is_banned),
+        "registration_date": user.registration_date.isoformat() if user.registration_date else None,
+    }
+
+
+def _support_limit_offset(request: web.Request) -> tuple[int, int]:
+    limit = max(1, min(100, int(request.query.get("limit", 25) or 25)))
+    offset = max(0, int(request.query.get("offset", 0) or 0))
+    return limit, offset
+
+
+async def admin_support_tickets_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    limit, offset = _support_limit_offset(request)
+    assigned_raw = request.query.get("assigned")
+    assigned_admin_id = None
+    if assigned_raw and assigned_raw not in {"all", "any"}:
+        assigned_admin_id = int(assigned_raw)
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+    async with async_session_factory() as session:
+        tickets = await support_dal.list_admin_tickets(
+            session,
+            status=request.query.get("status") or None,
+            priority=request.query.get("priority") or None,
+            category=request.query.get("category") or None,
+            assigned_admin_id=assigned_admin_id,
+            search=request.query.get("search") or None,
+            sort=request.query.get("sort") or "updated_desc",
+            limit=limit,
+            offset=offset,
+        )
+    return web.json_response(
+        {
+            "ok": True,
+            "tickets": [
+                {
+                    **_support_ticket_payload(ticket),
+                    "user": _admin_support_user_payload(getattr(ticket, "user", None)),
+                }
+                for ticket in tickets
+            ],
+        }
+    )
+
+
+async def admin_support_ticket_detail_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    ticket_id = int(request.match_info["id"])
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+    service = request.app["support_service"]
+    async with async_session_factory() as session:
+        ticket, messages = await support_dal.get_ticket(session, ticket_id, include_internal=True)
+        if not ticket:
+            return _error(404, "not_found", "Ticket not found")
+        user = await user_dal.get_user_by_id(session, ticket.user_id)
+        snapshot = await service.build_user_snapshot(user, session=session) if user else {}
+        author_ids = {m.author_user_id for m in messages if m.author_user_id is not None}
+        authors = {}
+        for author_id in author_ids:
+            author = await user_dal.get_user_by_id(session, author_id)
+            if author:
+                authors[author_id] = author
+    return web.json_response(
+        {
+            "ok": True,
+            "ticket": {
+                **_support_ticket_payload(ticket),
+                "user": _admin_support_user_payload(user),
+            },
+            "messages": [_support_message_payload(m, authors=authors) for m in messages],
+            "user_snapshot": snapshot,
+        }
+    )
+
+
+async def admin_support_ticket_reply_route(request: web.Request) -> web.Response:
+    admin_id = _require_admin_user_id(request)
+    ticket_id = int(request.match_info["id"])
+    payload, error = _validate_model_payload(AdminTicketReplyPayload, await _read_json(request))
+    if error:
+        return error
+    try:
+        ticket, message = await request.app["support_service"].reply_as_admin(
+            admin_id,
+            ticket_id,
+            payload.body,
+            is_internal_note=payload.is_internal_note,
+        )
+    except TicketNotFound:
+        return _error(404, "not_found", "Ticket not found")
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+    async with async_session_factory() as session:
+        admin = await user_dal.get_user_by_id(session, admin_id)
+    return web.json_response(
+        {
+            "ok": True,
+            "ticket": _support_ticket_payload(ticket),
+            "message": _support_message_payload(
+                message, authors={admin_id: admin} if admin else {}
+            ),
+        }
+    )
+
+
+async def admin_support_ticket_patch_route(request: web.Request) -> web.Response:
+    admin_id = _require_admin_user_id(request)
+    ticket_id = int(request.match_info["id"])
+    payload, error = _validate_model_payload(AdminTicketPatchPayload, await _read_json(request))
+    if error:
+        return error
+    updates = payload.model_dump(exclude_unset=True)
+    try:
+        if updates.get("status") == "closed":
+            ticket = await request.app["support_service"].close_ticket(admin_id, ticket_id)
+            updates.pop("status", None)
+            if updates:
+                ticket = await request.app["support_service"]._update_and_audit(
+                    admin_id,
+                    ticket_id,
+                    **updates,
+                )
+        else:
+            ticket = await request.app["support_service"]._update_and_audit(
+                admin_id,
+                ticket_id,
+                **updates,
+            )
+    except TicketNotFound:
+        return _error(404, "not_found", "Ticket not found")
+    return web.json_response({"ok": True, "ticket": _support_ticket_payload(ticket)})
+
+
+async def admin_support_ticket_read_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    ticket_id = int(request.match_info["id"])
+    await request.app["support_service"].mark_read_as_admin(ticket_id)
+    return web.json_response({"ok": True})
+
+
+async def admin_support_stats_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+    async with async_session_factory() as session:
+        stats = await support_dal.admin_stats(session)
+    return web.json_response({"ok": True, "stats": stats})

backend/bot/app/web/admin_api_impl/sync.py

@@ -0,0 +1,16 @@
+# ruff: noqa: F401,F403,F405,I001
+from ._runtime import *  # noqa: F403,F405
+
+
+async def admin_sync_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    settings: Settings = request.app["settings"]
+    queued = await enqueue_webhook_event(
+        settings,
+        "panel_sync",
+        {"requested_by": _require_admin_user_id(request)},
+        event_id=None,
+    )
+    if queued:
+        return _ok({"result": {"status": "queued"}})
+    return _error(503, "queue_unavailable")

backend/bot/app/web/admin_api_impl/tariffs.py

@@ -0,0 +1,114 @@
+# ruff: noqa: F401,F403,F405,I001
+from ._runtime import *  # noqa: F403,F405
+from .webapp_runtime import refresh_webapp_runtime_after_settings_change
+
+
+async def admin_tariffs_get_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    settings: Settings = request.app["settings"]
+    path = _tariffs_config_path(settings)
+
+    try:
+        config = settings.tariffs_config
+    except Exception as exc:
+        logger.warning("Invalid tariffs config requested from admin UI: %s", exc)
+        return _error(400, "invalid_tariffs_config", str(exc))
+
+    if config is None:
+        return _ok(
+            {
+                "exists": path.exists(),
+                "path": str(path),
+                "catalog": {
+                    "default_tariff": "",
+                    "default_currency": "rub",
+                    "topup_packages_default": {"rub": [], "stars": []},
+                    "tariffs": [],
+                },
+                "provider_currency_support": _provider_currency_support_payload(
+                    settings,
+                    request.app,
+                ),
+            }
+        )
+
+    return _ok(
+        {
+            "exists": True,
+            "path": str(path),
+            "catalog": _tariffs_config_payload(config),
+            "provider_currency_support": _provider_currency_support_payload(settings, request.app),
+        }
+    )
+
+
+async def admin_tariffs_save_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    settings: Settings = request.app["settings"]
+    payload = await _read_json(request)
+    catalog = payload.get("catalog") if "catalog" in payload else payload
+    if not isinstance(catalog, dict):
+        return _error(400, "invalid_payload", "catalog must be an object")
+
+    try:
+        config = TariffsConfig.model_validate(catalog)
+    except (ValidationError, ValueError) as exc:
+        return _error(400, "invalid_tariffs_config", str(exc))
+
+    path = _tariffs_config_path(settings)
+    try:
+        _write_tariffs_config_file(path, config)
+    except OSError as exc:
+        logger.exception("Failed to write tariffs config to %s", path)
+        return _error(500, "write_failed", str(exc))
+
+    await refresh_webapp_runtime_after_settings_change(request, updates={}, deletes=[])
+
+    return _ok(
+        {
+            "exists": True,
+            "path": str(path),
+            "catalog": _tariffs_config_payload(config),
+            "provider_currency_support": _provider_currency_support_payload(settings, request.app),
+        }
+    )
+
+
+def _provider_currency_support_payload(
+    settings: Settings,
+    app: web.Application,
+) -> List[Dict[str, Any]]:
+    from bot.payment_providers import iter_provider_specs, resolve_provider_presentation
+
+    default_currency = default_payment_currency_code_for_settings(settings)
+    providers: List[Dict[str, Any]] = []
+    for spec in iter_provider_specs():
+        presentation = resolve_provider_presentation(spec, settings)
+        supported = spec.supported_currency_codes(settings)
+        providers.append(
+            {
+                "id": spec.id,
+                "provider_key": spec.provider_key,
+                "label": presentation.webapp_label or spec.label,
+                "telegram_label": presentation.telegram_label,
+                "icon": presentation.webapp_icon,
+                "enabled": spec.is_effectively_enabled(settings),
+                "configured": spec.is_service_configured(app),
+                "admin_only": spec.is_admin_only_enabled(settings),
+                "price_source": spec.price_source,
+                "currencies": list(supported) if supported is not None else None,
+                "accepts_any_currency": supported is None,
+                "supports_default_currency": spec.is_usable_for_payment_currency(
+                    settings,
+                    default_currency,
+                ),
+                "directly_supports_default_currency": spec.supports_currency(
+                    settings,
+                    default_currency,
+                ),
+                "default_currency": default_currency,
+                "note": spec.currency_support_note,
+                "docs_url": spec.currency_support_url,
+            }
+        )
+    return providers

backend/bot/app/web/admin_api_impl/themes.py

@@ -0,0 +1,465 @@
+# ruff: noqa: F401,F403,F405,I001
+from ._runtime import *  # noqa: F403,F405
+from .webapp_runtime import refresh_webapp_runtime_after_settings_change
+
+import asyncio
+import hashlib
+import ipaddress
+import shutil
+import re
+import socket
+
+from aiohttp import ClientSession, ClientTimeout
+from PIL import Image, ImageOps, UnidentifiedImageError
+
+from config.webapp_themes_config import (
+    WebappThemesConfig,
+    ensure_webapp_core_themes,
+    resolved_webapp_themes_catalog,
+    write_webapp_theme_dir,
+)
+
+
+WEBAPP_LOGO_MAX_BYTES = 2 * 1024 * 1024
+WEBAPP_UPLOADED_LOGO_DIR = Path(__file__).resolve().parents[5] / "data" / "webapp-logo" / "uploads"
+WEBAPP_UPLOADED_LOGO_PATH = "/webapp-uploaded-logo"
+WEBAPP_FAVICON_DIR = Path(__file__).resolve().parents[5] / "data" / "webapp-logo" / "favicons"
+WEBAPP_FAVICON_PATH = "/webapp-favicon"
+WEBAPP_FAVICON_SIZES = (16, 32, 48, 180, 192, 512)
+WEBAPP_LOGO_UPLOAD_CONTENT_TYPES = {
+    ".gif": "image/gif",
+    ".ico": "image/x-icon",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+    ".webp": "image/webp",
+}
+
+
+def _theme_payload_for_version_compare(theme: Any) -> Dict[str, Any]:
+    if hasattr(theme, "model_dump"):
+        data = theme.model_dump(mode="json", exclude_none=True)
+    elif isinstance(theme, dict):
+        data = dict(theme)
+    else:
+        data = {}
+    data.pop("assets_version", None)
+    data.pop("default", None)
+    return data
+
+
+def _bump_theme_asset_versions(
+    config: WebappThemesConfig,
+    previous: WebappThemesConfig,
+) -> WebappThemesConfig:
+    previous_by_key = {theme.key: theme for theme in previous.themes}
+    default_changed = config.default_theme != previous.default_theme
+    data = config.model_dump(mode="json", exclude_none=True)
+    for theme in data.get("themes", []):
+        if not isinstance(theme, dict):
+            continue
+        if not str(theme.get("css_file") or "").strip():
+            continue
+        key = str(theme.get("key") or "")
+        previous_theme = previous_by_key.get(key)
+        previous_version = int(getattr(previous_theme, "assets_version", 0) or 0)
+        current_version = int(theme.get("assets_version") or 1)
+        theme_changed = previous_theme is None or _theme_payload_for_version_compare(
+            theme
+        ) != _theme_payload_for_version_compare(previous_theme)
+        if theme_changed or (default_changed and key == config.default_theme):
+            theme["assets_version"] = max(previous_version + 1, current_version, 1)
+        elif previous_version > current_version:
+            theme["assets_version"] = previous_version
+    return WebappThemesConfig.model_validate(data)
+
+
+def _detect_logo_extension(
+    body: bytes, content_type: str = "", filename: str = ""
+) -> Optional[str]:
+    content_type = (content_type or "").split(";", 1)[0].strip().lower()
+    suffix = Path(filename or "").suffix.lower()
+    if content_type == "image/png" or body.startswith(b"\x89PNG\r\n\x1a\n"):
+        return ".png"
+    if content_type == "image/jpeg" or body.startswith(b"\xff\xd8\xff"):
+        return ".jpg"
+    if content_type == "image/gif" or body.startswith((b"GIF87a", b"GIF89a")):
+        return ".gif"
+    if content_type == "image/webp" or (
+        len(body) > 12 and body[:4] == b"RIFF" and body[8:12] == b"WEBP"
+    ):
+        return ".webp"
+    if content_type in {"image/svg+xml", "image/svg"} or suffix == ".svg":
+        head = body[:512].lstrip().lower()
+        if head.startswith(b"<svg") or b"<svg" in head:
+            return ".svg"
+    if content_type == "image/x-icon" or suffix == ".ico":
+        if body.startswith(b"\x00\x00\x01\x00"):
+            return ".ico"
+    return suffix if suffix in WEBAPP_LOGO_UPLOAD_CONTENT_TYPES else None
+
+
+def _write_uploaded_logo(body: bytes, content_type: str = "", filename: str = "") -> str:
+    if not body or len(body) > WEBAPP_LOGO_MAX_BYTES:
+        raise ValueError("logo must be a non-empty image up to 2 MiB")
+    ext = _detect_logo_extension(body, content_type, filename)
+    if ext not in WEBAPP_LOGO_UPLOAD_CONTENT_TYPES:
+        raise ValueError("unsupported image type")
+    digest = hashlib.sha256(body).hexdigest()[:16]
+    safe_name = f"logo-{digest}{ext}"
+    WEBAPP_UPLOADED_LOGO_DIR.mkdir(parents=True, exist_ok=True)
+    (WEBAPP_UPLOADED_LOGO_DIR / safe_name).write_bytes(body)
+    return f"{WEBAPP_UPLOADED_LOGO_PATH}/{safe_name}"
+
+
+def _uploaded_logo_filename(url: str) -> Optional[str]:
+    parsed = urlsplit(str(url or ""))
+    path = parsed.path if parsed.scheme or parsed.netloc else str(url or "")
+    prefix = f"{WEBAPP_UPLOADED_LOGO_PATH}/"
+    if not path.startswith(prefix):
+        return None
+    filename = path.removeprefix(prefix)
+    if re.fullmatch(r"logo-[0-9a-f]{16}\.(?:gif|ico|jpe?g|png|svg|webp)", filename):
+        return filename
+    return None
+
+
+def _favicon_digest(url: str) -> Optional[str]:
+    parsed = urlsplit(str(url or ""))
+    path = parsed.path if parsed.scheme or parsed.netloc else str(url or "")
+    match = re.fullmatch(
+        rf"{re.escape(WEBAPP_FAVICON_PATH)}/([0-9a-f]{{16}})/(?:[A-Za-z0-9_.-]+)",
+        path,
+    )
+    return match.group(1) if match else None
+
+
+def prune_unused_appearance_assets(settings: Settings) -> None:
+    keep_logos = {
+        filename
+        for filename in [
+            _uploaded_logo_filename(getattr(settings, "WEBAPP_LOGO_URL", "")),
+        ]
+        if filename
+    }
+    keep_favicons = {
+        digest
+        for digest in [
+            _favicon_digest(getattr(settings, "WEBAPP_FAVICON_URL", "")),
+            _favicon_digest(getattr(settings, "WEBAPP_LOGO_FAVICON_URL", "")),
+        ]
+        if digest
+    }
+
+    for path in WEBAPP_UPLOADED_LOGO_DIR.glob("logo-*"):
+        if path.is_file() and path.name not in keep_logos:
+            try:
+                path.unlink()
+            except OSError:
+                logger.warning("Failed to remove unused webapp logo %s", path, exc_info=True)
+
+    for path in WEBAPP_FAVICON_DIR.glob("*"):
+        if (
+            path.is_dir()
+            and re.fullmatch(r"[0-9a-f]{16}", path.name)
+            and path.name not in keep_favicons
+        ):
+            try:
+                shutil.rmtree(path)
+            except OSError:
+                logger.warning("Failed to remove unused webapp favicon set %s", path, exc_info=True)
+
+
+async def _persist_appearance_upload(
+    request: web.Request,
+    updates: Dict[str, Any],
+    actor_id: int,
+) -> bool:
+    settings: Settings = request.app["settings"]
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+    result = await update_overrides(
+        settings,
+        async_session_factory,
+        updates=updates,
+        deletes=[],
+        actor_id=actor_id,
+    )
+    if not result.get("ok"):
+        logger.warning("Failed to persist uploaded appearance asset settings: %s", result)
+        return False
+
+    await refresh_webapp_runtime_after_settings_change(request, updates=updates, deletes=[])
+    return True
+
+
+def _image_to_square_icon(source: Image.Image, size: int) -> Image.Image:
+    fitted = source.copy()
+    fitted.thumbnail((size, size), Image.Resampling.LANCZOS)
+    canvas = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    left = (size - fitted.width) // 2
+    top = (size - fitted.height) // 2
+    canvas.alpha_composite(fitted, (left, top))
+    return canvas
+
+
+def _write_favicon_set(body: bytes, content_type: str = "", filename: str = "") -> Dict[str, Any]:
+    if not body or len(body) > WEBAPP_LOGO_MAX_BYTES:
+        raise ValueError("favicon source must be a non-empty image up to 2 MiB")
+
+    ext = _detect_logo_extension(body, content_type, filename)
+    digest = hashlib.sha256(body).hexdigest()[:16]
+    target_dir = WEBAPP_FAVICON_DIR / digest
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    if ext == ".svg":
+        safe_name = "favicon.svg"
+        (target_dir / safe_name).write_bytes(body)
+        return {
+            "favicon_url": f"{WEBAPP_FAVICON_PATH}/{digest}/{safe_name}",
+            "variants": {"svg": f"{WEBAPP_FAVICON_PATH}/{digest}/{safe_name}"},
+        }
+
+    try:
+        with Image.open(io.BytesIO(body)) as image:
+            image.seek(0)
+            source = ImageOps.exif_transpose(image).convert("RGBA")
+    except (OSError, UnidentifiedImageError, ValueError) as exc:
+        raise ValueError("favicon source must be a raster image") from exc
+
+    if source.width < 1 or source.height < 1 or source.width > 8192 or source.height > 8192:
+        raise ValueError("favicon source dimensions are not supported")
+
+    variants: Dict[str, str] = {}
+    png_icons: Dict[int, Image.Image] = {}
+    for size in WEBAPP_FAVICON_SIZES:
+        icon = _image_to_square_icon(source, size)
+        png_icons[size] = icon
+        filename = f"icon-{size}.png"
+        icon.save(target_dir / filename, format="PNG", optimize=True)
+        variants[f"{size}"] = f"{WEBAPP_FAVICON_PATH}/{digest}/{filename}"
+
+    png_icons[180].save(target_dir / "apple-touch-icon.png", format="PNG", optimize=True)
+    variants["apple_touch"] = f"{WEBAPP_FAVICON_PATH}/{digest}/apple-touch-icon.png"
+    png_icons[32].save(
+        target_dir / "favicon.ico",
+        format="ICO",
+        sizes=[(16, 16), (32, 32), (48, 48)],
+    )
+    variants["ico"] = f"{WEBAPP_FAVICON_PATH}/{digest}/favicon.ico"
+    return {
+        "favicon_url": variants["180"],
+        "variants": variants,
+    }
+
+
+async def _read_uploaded_logo_file(request: web.Request) -> tuple[bytes, str, str]:
+    reader = await request.multipart()
+    async for part in reader:
+        if part.name != "file":
+            continue
+        body = bytearray()
+        while True:
+            chunk = await part.read_chunk(size=64 * 1024)
+            if not chunk:
+                break
+            body.extend(chunk)
+            if len(body) > WEBAPP_LOGO_MAX_BYTES:
+                raise ValueError("logo must be up to 2 MiB")
+        return bytes(body), part.headers.get("Content-Type", ""), part.filename or ""
+    raise ValueError("file field is required")
+
+
+async def _hostname_resolves_to_public_address(hostname: str) -> bool:
+    if not hostname:
+        return False
+    try:
+        ip_obj = ipaddress.ip_address(hostname)
+        return not (
+            ip_obj.is_private
+            or ip_obj.is_loopback
+            or ip_obj.is_link_local
+            or ip_obj.is_unspecified
+            or ip_obj.is_reserved
+        )
+    except ValueError:
+        pass
+
+    loop = asyncio.get_running_loop()
+    try:
+        resolved = await loop.getaddrinfo(hostname, None, type=socket.SOCK_STREAM)
+    except Exception:
+        return False
+
+    found_public_ip = False
+    for entry in resolved:
+        sockaddr = entry[4]
+        candidate = sockaddr[0] if sockaddr else ""
+        try:
+            ip_obj = ipaddress.ip_address(candidate)
+        except ValueError:
+            continue
+        if (
+            ip_obj.is_private
+            or ip_obj.is_loopback
+            or ip_obj.is_link_local
+            or ip_obj.is_unspecified
+            or ip_obj.is_reserved
+        ):
+            return False
+        found_public_ip = True
+    return found_public_ip
+
+
+async def _fetch_logo_from_url(url: str) -> tuple[bytes, str, str]:
+    parsed = urlsplit(url)
+    if parsed.scheme != "https" or not parsed.hostname:
+        raise ValueError("only https image URLs are supported")
+    if not await _hostname_resolves_to_public_address(parsed.hostname):
+        raise ValueError("logo URL must resolve to a public address")
+
+    timeout = ClientTimeout(total=5)
+    async with ClientSession(timeout=timeout, headers={"User-Agent": "Mozilla/5.0"}) as session:
+        async with session.get(
+            url,
+            allow_redirects=False,
+            headers={"Accept": "image/avif,image/webp,image/svg+xml,image/png,image/*,*/*;q=0.8"},
+        ) as response:
+            if response.status != 200:
+                raise ValueError(f"logo URL returned HTTP {response.status}")
+            content_type = (
+                (response.headers.get("Content-Type") or "").split(";", 1)[0].strip().lower()
+            )
+            if content_type and not content_type.startswith("image/"):
+                raise ValueError("logo URL returned non-image content")
+            body = bytearray()
+            async for chunk in response.content.iter_chunked(64 * 1024):
+                body.extend(chunk)
+                if len(body) > WEBAPP_LOGO_MAX_BYTES:
+                    raise ValueError("logo must be up to 2 MiB")
+            return bytes(body), content_type, Path(parsed.path).name
+
+
+async def admin_appearance_logo_upload_route(request: web.Request) -> web.Response:
+    actor_id = _require_admin_user_id(request)
+    content_type = (request.headers.get("Content-Type") or "").lower()
+    try:
+        if content_type.startswith("multipart/form-data"):
+            body, detected_content_type, filename = await _read_uploaded_logo_file(request)
+        else:
+            payload = await _read_json(request)
+            source_url = str(payload.get("url") or "").strip()
+            if not source_url:
+                return _error(400, "invalid_payload", "url or file is required")
+            body, detected_content_type, filename = await _fetch_logo_from_url(source_url)
+        logo_url = _write_uploaded_logo(body, detected_content_type, filename)
+        try:
+            favicon_payload = _write_favicon_set(body, detected_content_type, filename)
+        except ValueError:
+            favicon_payload = {}
+    except ValueError as exc:
+        return _error(400, "invalid_logo", str(exc))
+    except OSError as exc:
+        logger.exception("Failed to save uploaded webapp logo")
+        return _error(500, "write_failed", str(exc))
+    persisted = await _persist_appearance_upload(
+        request,
+        {
+            "WEBAPP_LOGO_URL": logo_url,
+            **(
+                {"WEBAPP_LOGO_FAVICON_URL": favicon_payload["favicon_url"]}
+                if favicon_payload.get("favicon_url")
+                else {}
+            ),
+        },
+        actor_id,
+    )
+
+    return _ok({"logo_url": logo_url, "persisted": persisted, **favicon_payload})
+
+
+async def admin_appearance_favicon_upload_route(request: web.Request) -> web.Response:
+    actor_id = _require_admin_user_id(request)
+    content_type = (request.headers.get("Content-Type") or "").lower()
+    try:
+        if content_type.startswith("multipart/form-data"):
+            body, detected_content_type, filename = await _read_uploaded_logo_file(request)
+        else:
+            payload = await _read_json(request)
+            source_url = str(payload.get("url") or "").strip()
+            if not source_url:
+                return _error(400, "invalid_payload", "url or file is required")
+            body, detected_content_type, filename = await _fetch_logo_from_url(source_url)
+        favicon_payload = _write_favicon_set(body, detected_content_type, filename)
+    except ValueError as exc:
+        return _error(400, "invalid_favicon", str(exc))
+    except OSError as exc:
+        logger.exception("Failed to save uploaded webapp favicon")
+        return _error(500, "write_failed", str(exc))
+    persisted = await _persist_appearance_upload(
+        request,
+        {
+            "WEBAPP_FAVICON_URL": favicon_payload["favicon_url"],
+            "WEBAPP_FAVICON_USE_CUSTOM": True,
+        },
+        actor_id,
+    )
+
+    return _ok({"persisted": persisted, **favicon_payload})
+
+
+async def admin_themes_get_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    settings: Settings = request.app["settings"]
+    primary = settings.WEBAPP_PRIMARY_COLOR or "#00fe7a"
+    catalog = resolved_webapp_themes_catalog(
+        primary_accent=primary,
+        env_default_theme=settings.WEBAPP_DEFAULT_THEME,
+        theme_dir=settings.WEBAPP_THEMES_DIR,
+    )
+
+    return _ok(
+        {
+            "exists": Path(settings.WEBAPP_THEMES_DIR).expanduser().exists(),
+            "themes_dir": str(Path(settings.WEBAPP_THEMES_DIR).expanduser()),
+            "catalog": _webapp_themes_catalog_payload(catalog),
+        }
+    )
+
+
+async def admin_themes_save_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    settings: Settings = request.app["settings"]
+    previous_config = resolved_webapp_themes_catalog(
+        primary_accent=settings.WEBAPP_PRIMARY_COLOR or "#00fe7a",
+        env_default_theme=settings.WEBAPP_DEFAULT_THEME,
+        theme_dir=settings.WEBAPP_THEMES_DIR,
+    )
+    payload = await _read_json(request)
+    catalog = payload.get("catalog") if "catalog" in payload else payload
+    if not isinstance(catalog, dict):
+        return _error(400, "invalid_payload", "catalog must be an object")
+
+    try:
+        config = WebappThemesConfig.model_validate(catalog)
+    except (ValidationError, ValueError) as exc:
+        return _error(400, "invalid_webapp_themes_config", str(exc))
+
+    config, _changed = ensure_webapp_core_themes(config, settings.WEBAPP_PRIMARY_COLOR or "#00fe7a")
+    config = _bump_theme_asset_versions(config, previous_config)
+
+    try:
+        write_webapp_theme_dir(settings.WEBAPP_THEMES_DIR, config, delete_missing=True)
+    except OSError as exc:
+        logger.exception("Failed to write webapp themes to %s", settings.WEBAPP_THEMES_DIR)
+        return _error(500, "write_failed", str(exc))
+
+    await refresh_webapp_runtime_after_settings_change(request, updates={}, deletes=[])
+
+    return _ok(
+        {
+            "exists": True,
+            "themes_dir": str(Path(settings.WEBAPP_THEMES_DIR).expanduser()),
+            "catalog": _webapp_themes_catalog_payload(config),
+        }
+    )

backend/bot/app/web/admin_api_impl/translations.py

@@ -0,0 +1,146 @@
+# ruff: noqa: F401,F403,F405,I001
+from ._runtime import *  # noqa: F403,F405
+
+from bot.middlewares.i18n import JsonI18n, locale_language_options, resolve_locale_key
+from bot.services.locale_override_service import (
+    LOCALE_OVERRIDES_PATH,
+    audience_for_locale_key,
+    group_id_for_locale_key,
+    locale_group_catalog,
+    load_locale_overrides,
+    update_locale_overrides,
+)
+
+
+def _locale_languages(
+    i18n: JsonI18n,
+    overrides: Optional[List[Dict[str, Any]]] = None,
+) -> List[Dict[str, Any]]:
+    base_languages = set((i18n.base_locales_data or {}).keys())
+    override_languages = {str(entry.get("lang") or "") for entry in overrides or []}
+    override_languages.update((i18n.locale_overrides or {}).keys())
+    return locale_language_options(
+        base_languages | override_languages,
+        base_languages=base_languages,
+    )
+
+
+def _locale_override_meta_map(overrides: List[Dict[str, Any]]) -> Dict[Tuple[str, str], Dict]:
+    result: Dict[Tuple[str, str], Dict] = {}
+    for entry in overrides:
+        lang = str(entry.get("lang") or "")
+        raw_key = str(entry.get("key") or "")
+        key = resolve_locale_key(raw_key)
+        if lang and key:
+            if raw_key != key and (lang, key) in result:
+                continue
+            result[(lang, key)] = entry
+    return result
+
+
+def _admin_translations_payload(
+    i18n: JsonI18n,
+    overrides: List[Dict[str, Any]],
+) -> Dict[str, Any]:
+    base_data = i18n.base_locales_data or i18n.locales_data or {}
+    effective_data = i18n.locales_data or {}
+    override_meta = _locale_override_meta_map(overrides)
+    language_items = _locale_languages(i18n, overrides)
+    languages = [item["code"] for item in language_items]
+    all_keys = sorted(
+        {key for messages in base_data.values() for key in messages.keys()}
+        | {key for _, key in override_meta.keys()}
+    )
+
+    groups_by_id = {
+        group["id"]: {
+            **group,
+            "items": [],
+        }
+        for group in locale_group_catalog()
+    }
+
+    for key in all_keys:
+        values: Dict[str, Dict[str, Any]] = {}
+        for lang in languages:
+            meta = override_meta.get((lang, key))
+            fallback_base = base_data.get(i18n.default_lang, {}).get(key, "")
+            values[lang] = {
+                "base": base_data.get(lang, {}).get(key, ""),
+                "fallback": fallback_base,
+                "effective": effective_data.get(lang, {}).get(key, ""),
+                "override": meta.get("value") if meta else "",
+                "overridden": bool(meta),
+                "updated_at": meta.get("updated_at") if meta else None,
+                "updated_by": meta.get("updated_by") if meta else None,
+            }
+        group_id = group_id_for_locale_key(key)
+        groups_by_id.setdefault(
+            group_id,
+            {"id": group_id, "title": group_id, "description": "", "items": []},
+        )
+        groups_by_id[group_id]["items"].append(
+            {
+                "key": key,
+                "audience": audience_for_locale_key(key),
+                "values": values,
+            }
+        )
+
+    groups = [group for group in groups_by_id.values() if group["items"]]
+    return {
+        "languages": language_items,
+        "groups": groups,
+        "path": str(LOCALE_OVERRIDES_PATH),
+        "override_count": len(overrides),
+    }
+
+
+async def admin_translations_get_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    i18n: Optional[JsonI18n] = request.app.get("i18n")
+    if i18n is None:
+        return _error(503, "i18n_unavailable")
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+
+    await load_locale_overrides(i18n, async_session_factory)
+    async with async_session_factory() as session:
+        overrides = await locale_overrides_dal.get_overrides_with_meta(session)
+
+    return _ok(_admin_translations_payload(i18n, overrides))
+
+
+async def admin_translations_patch_route(request: web.Request) -> web.Response:
+    actor_id = _require_admin_user_id(request)
+    i18n: Optional[JsonI18n] = request.app.get("i18n")
+    if i18n is None:
+        return _error(503, "i18n_unavailable")
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+    payload = await _read_json(request)
+    updates = payload.get("updates") or {}
+    deletes = payload.get("deletes") or []
+    if not isinstance(updates, dict):
+        return _error(400, "invalid_updates")
+    if not isinstance(deletes, list):
+        return _error(400, "invalid_deletes")
+
+    result = await update_locale_overrides(
+        i18n,
+        async_session_factory,
+        updates=updates,
+        deletes=deletes,
+        actor_id=actor_id,
+    )
+    if not result.get("ok"):
+        return web.json_response(
+            {"ok": False, "error": "validation_failed", "errors": result.get("errors", {})},
+            status=400,
+        )
+
+    return _ok(
+        {
+            "applied": result.get("applied", 0),
+            "reverted": result.get("reverted", 0),
+            "file_written": result.get("file_written", False),
+        }
+    )

backend/bot/app/web/admin_api_impl/users.py

@@ -1,9 +1,34 @@
 # ruff: noqa: F401,F403,F405,I001
 from ._runtime import *  # noqa: F403,F405
+from .auth import _require_admin_user_id
+from .common import (
+    _build_admin_webapp_referral_link,
+    _error,
+    _ok,
+    _panel_user_connection_activity,
+    _premium_traffic_list_payload,
+    _read_json,
+    _serialize_payment,
+    _serialize_subscription,
+    _serialize_user,
+)
+
+import hashlib
+from html import escape as html_escape
+
+from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup
+from sqlalchemy.orm import aliased
+
+from bot.app.web.webapp.cache_helpers import invalidate_webapp_user_caches
+from bot.infra.redis import cache_delete_pattern, redis_key
+from bot.utils.ttl_cache import AsyncTTLCache
+
+_ADMIN_USERS_LIST_CACHES: Dict[tuple[int, int], AsyncTTLCache] = {}
 
 
 async def admin_users_list_route(request: web.Request) -> web.Response:
     _require_admin_user_id(request)
+    settings: Settings = request.app["settings"]
     async_session_factory: sessionmaker = request.app["async_session_factory"]
 
     page = max(0, int(request.query.get("page", 0) or 0))
@@ -14,6 +39,79 @@ async def admin_users_list_route(request: web.Request) -> web.Response:
     premium_traffic = (request.query.get("premium_traffic") or "all").lower()
     sort_value = (request.query.get("sort") or "registered_desc").lower()
 
+    payload = await _load_admin_users_list_payload(
+        settings,
+        async_session_factory,
+        page=page,
+        page_size=page_size,
+        query=query,
+        filter_value=filter_value,
+        panel_status=panel_status,
+        premium_traffic=premium_traffic,
+        sort_value=sort_value,
+    )
+    return _ok(payload)
+
+
+async def _load_admin_users_list_payload(
+    settings: Settings,
+    async_session_factory: sessionmaker,
+    *,
+    page: int,
+    page_size: int,
+    query: str,
+    filter_value: str,
+    panel_status: str,
+    premium_traffic: str,
+    sort_value: str,
+) -> Dict[str, Any]:
+    cache = _admin_users_list_cache(settings)
+    cache_key = _admin_users_list_cache_key(
+        page=page,
+        page_size=page_size,
+        query=query,
+        filter_value=filter_value,
+        panel_status=panel_status,
+        premium_traffic=premium_traffic,
+        sort_value=sort_value,
+    )
+    if cache is None:
+        return await _load_admin_users_list_payload_uncached(
+            async_session_factory,
+            page=page,
+            page_size=page_size,
+            query=query,
+            filter_value=filter_value,
+            panel_status=panel_status,
+            premium_traffic=premium_traffic,
+            sort_value=sort_value,
+        )
+    return await cache.get_or_load(
+        cache_key,
+        lambda: _load_admin_users_list_payload_uncached(
+            async_session_factory,
+            page=page,
+            page_size=page_size,
+            query=query,
+            filter_value=filter_value,
+            panel_status=panel_status,
+            premium_traffic=premium_traffic,
+            sort_value=sort_value,
+        ),
+    )
+
+
+async def _load_admin_users_list_payload_uncached(
+    async_session_factory: sessionmaker,
+    *,
+    page: int,
+    page_size: int,
+    query: str,
+    filter_value: str,
+    panel_status: str,
+    premium_traffic: str,
+    sort_value: str,
+) -> Dict[str, Any]:
     async with async_session_factory() as session:
         users, total = await _filter_and_sort_users(
             session,
@@ -31,12 +129,15 @@ async def admin_users_list_route(request: web.Request) -> web.Response:
         active_subs = await _bulk_active_subscriptions_for_users(
             session, [u.user_id for u in users]
         )
+        payment_summaries = await _bulk_user_payment_summaries(session, [u.user_id for u in users])
+        referral_counts = await _bulk_user_referral_counts(session, [u.user_id for u in users])
 
     serialized = []
     for user in users:
         payload = _serialize_user(user)
         status_payload = statuses.get(user.user_id) or {"status": "bot_only", "end_date": None}
         payload["panel_status"] = status_payload.get("status")
+        payload["subscription_expires_at"] = status_payload.get("end_date")
         if status_payload.get("status") == "expired" and status_payload.get("end_date"):
             payload["panel_status_expired_at"] = status_payload["end_date"]
         payload["avatar_url"] = (
@@ -45,16 +146,65 @@ async def admin_users_list_route(request: web.Request) -> web.Response:
             else None
         )
         payload["premium_traffic"] = _premium_traffic_list_payload(active_subs.get(user.user_id))
+        payment_summary = payment_summaries.get(user.user_id) or {}
+        payload["payments_total_amount"] = float(payment_summary.get("total_amount") or 0)
+        payload["payments_count"] = int(payment_summary.get("count") or 0)
+        payload["payments_currency"] = payment_summary.get("currency")
+        payload["invited_users_count"] = int(referral_counts.get(user.user_id) or 0)
         serialized.append(payload)
 
-    return _ok(
-        {
-            "users": serialized,
-            "page": page,
-            "page_size": page_size,
-            "total": total,
-        }
-    )
+    return {
+        "users": serialized,
+        "page": page,
+        "page_size": page_size,
+        "total": total,
+    }
+
+
+def _admin_users_list_cache(settings: Settings) -> Optional[AsyncTTLCache]:
+    ttl_seconds = int(getattr(settings, "ADMIN_USERS_LIST_CACHE_TTL_SECONDS", 3) or 0)
+    if ttl_seconds <= 0:
+        return None
+    cache_key = (id(settings), ttl_seconds)
+    cache = _ADMIN_USERS_LIST_CACHES.get(cache_key)
+    if cache is None:
+        cache = AsyncTTLCache(
+            ttl_seconds=ttl_seconds,
+            settings=settings,
+            namespace="admin:users_list",
+        )
+        _ADMIN_USERS_LIST_CACHES[cache_key] = cache
+    return cache
+
+
+def _admin_users_list_cache_key(**params: Any) -> str:
+    raw = json.dumps(params, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+async def _invalidate_admin_users_list_cache(settings: Settings) -> None:
+    for settings_id, _ttl in tuple(_ADMIN_USERS_LIST_CACHES):
+        if settings_id == id(settings):
+            _ADMIN_USERS_LIST_CACHES[(settings_id, _ttl)].invalidate()
+    try:
+        await cache_delete_pattern(settings, redis_key(settings, "cache", "admin:users_list", "*"))
+    except Exception:
+        return
+
+
+async def _invalidate_after_admin_user_mutation(
+    settings: Settings,
+    user_id: Optional[int] = None,
+    *,
+    include_devices: bool = True,
+) -> None:
+    await _invalidate_admin_users_list_cache(settings)
+    if user_id is not None:
+        await invalidate_webapp_user_caches(
+            settings,
+            user_id,
+            include_devices=include_devices,
+        )
 
 
 async def _bulk_user_statuses(
@@ -115,6 +265,17 @@ async def _bulk_user_avatar_keys(session: AsyncSession, user_ids: List[int]) ->
     return {int(uid): (updated_at.isoformat() if updated_at else "") for uid, updated_at in rows}
 
 
+def _serialize_admin_user_with_avatar(user: User, avatar_keys: Dict[int, str]) -> Dict[str, Any]:
+    payload = _serialize_user(user)
+    user_id = int(user.user_id)
+    payload["avatar_url"] = (
+        f"/api/admin/users/{user_id}/avatar?v={avatar_keys[user_id]}"
+        if user_id in avatar_keys
+        else None
+    )
+    return payload
+
+
 async def admin_user_avatar_route(request: web.Request) -> web.Response:
     """Serve the cached Telegram avatar for any user (admin-only).
 
@@ -213,6 +374,88 @@ async def _bulk_active_subscriptions_for_users(
     return out
 
 
+def _user_payment_summary_sq():
+    return (
+        select(
+            Payment.user_id.label("user_id"),
+            sa_func.coalesce(sa_func.sum(Payment.amount), 0.0).label("payments_total_amount"),
+            sa_func.count(Payment.payment_id).label("payments_count"),
+        )
+        .where(Payment.status == "succeeded")
+        .group_by(Payment.user_id)
+        .subquery(name="user_payment_summary")
+    )
+
+
+def _user_referral_count_sq():
+    referred_user = aliased(User)
+    return (
+        select(
+            referred_user.referred_by_id.label("user_id"),
+            sa_func.count(referred_user.user_id).label("invited_users_count"),
+        )
+        .where(referred_user.referred_by_id.is_not(None))
+        .group_by(referred_user.referred_by_id)
+        .subquery(name="user_referral_count")
+    )
+
+
+def _user_subscription_expiry_sq():
+    return (
+        select(
+            Subscription.user_id.label("user_id"),
+            sa_func.max(Subscription.end_date).label("subscription_expires_at"),
+        )
+        .group_by(Subscription.user_id)
+        .subquery(name="user_subscription_expiry")
+    )
+
+
+async def _bulk_user_payment_summaries(
+    session: AsyncSession,
+    user_ids: List[int],
+) -> Dict[int, Dict[str, Any]]:
+    if not user_ids:
+        return {}
+
+    stmt = (
+        select(
+            Payment.user_id,
+            sa_func.coalesce(sa_func.sum(Payment.amount), 0.0),
+            sa_func.count(Payment.payment_id),
+            sa_func.max(Payment.currency),
+        )
+        .where(Payment.user_id.in_(user_ids), Payment.status == "succeeded")
+        .group_by(Payment.user_id)
+    )
+    rows = (await session.execute(stmt)).all()
+    return {
+        int(user_id): {
+            "total_amount": float(total_amount or 0),
+            "count": int(payments_count or 0),
+            "currency": currency,
+        }
+        for user_id, total_amount, payments_count, currency in rows
+    }
+
+
+async def _bulk_user_referral_counts(
+    session: AsyncSession,
+    user_ids: List[int],
+) -> Dict[int, int]:
+    if not user_ids:
+        return {}
+
+    referred_user = aliased(User)
+    stmt = (
+        select(referred_user.referred_by_id, sa_func.count(referred_user.user_id))
+        .where(referred_user.referred_by_id.in_(user_ids))
+        .group_by(referred_user.referred_by_id)
+    )
+    rows = (await session.execute(stmt)).all()
+    return {int(user_id): int(count or 0) for user_id, count in rows}
+
+
 async def _filter_and_sort_users(
     session: AsyncSession,
     *,
@@ -241,6 +484,13 @@ async def _filter_and_sort_users(
     ratio_expr = None
     plim_expr = None
     pu_expr = None
+    payment_summary_sq = None
+    payment_total_expr = None
+    payment_count_expr = None
+    referral_count_sq = None
+    referral_count_expr = None
+    subscription_expiry_sq = None
+    subscription_expires_expr = None
 
     if needs_premium_sq:
         sq = _ranked_active_subscriptions_sq(now)
@@ -261,6 +511,42 @@ async def _filter_and_sort_users(
             else_=cast(pu_expr, Float) / cast(plim_expr, Float),
         )
 
+    if sort_key in {
+        "payments_total_asc",
+        "payments_total_desc",
+        "payments_count_asc",
+        "payments_count_desc",
+    }:
+        payment_summary_sq = _user_payment_summary_sq()
+        stmt = stmt.outerjoin(payment_summary_sq, User.user_id == payment_summary_sq.c.user_id)
+        count_stmt = count_stmt.outerjoin(
+            payment_summary_sq,
+            User.user_id == payment_summary_sq.c.user_id,
+        )
+        payment_total_expr = sa_func.coalesce(payment_summary_sq.c.payments_total_amount, 0.0)
+        payment_count_expr = sa_func.coalesce(payment_summary_sq.c.payments_count, 0)
+
+    if sort_key in {"invited_users_count_asc", "invited_users_count_desc"}:
+        referral_count_sq = _user_referral_count_sq()
+        stmt = stmt.outerjoin(referral_count_sq, User.user_id == referral_count_sq.c.user_id)
+        count_stmt = count_stmt.outerjoin(
+            referral_count_sq,
+            User.user_id == referral_count_sq.c.user_id,
+        )
+        referral_count_expr = sa_func.coalesce(referral_count_sq.c.invited_users_count, 0)
+
+    if sort_key in {"subscription_expires_at_asc", "subscription_expires_at_desc"}:
+        subscription_expiry_sq = _user_subscription_expiry_sq()
+        stmt = stmt.outerjoin(
+            subscription_expiry_sq,
+            User.user_id == subscription_expiry_sq.c.user_id,
+        )
+        count_stmt = count_stmt.outerjoin(
+            subscription_expiry_sq,
+            User.user_id == subscription_expiry_sq.c.user_id,
+        )
+        subscription_expires_expr = subscription_expiry_sq.c.subscription_expires_at
+
     search_cond = _user_search_condition(query)
     if search_cond is not None:
         stmt = stmt.where(search_cond)
@@ -359,6 +645,22 @@ async def _filter_and_sort_users(
         stmt = stmt.order_by(ratio_expr.asc().nullslast(), User.user_id.asc())
     elif needs_premium_sq and ratio_expr is not None and sort_key == "premium_ratio_desc":
         stmt = stmt.order_by(ratio_expr.desc().nullslast(), User.user_id.desc())
+    elif payment_total_expr is not None and sort_key == "payments_total_asc":
+        stmt = stmt.order_by(payment_total_expr.asc(), User.user_id.asc())
+    elif payment_total_expr is not None and sort_key == "payments_total_desc":
+        stmt = stmt.order_by(payment_total_expr.desc(), User.user_id.desc())
+    elif payment_count_expr is not None and sort_key == "payments_count_asc":
+        stmt = stmt.order_by(payment_count_expr.asc(), User.user_id.asc())
+    elif payment_count_expr is not None and sort_key == "payments_count_desc":
+        stmt = stmt.order_by(payment_count_expr.desc(), User.user_id.desc())
+    elif referral_count_expr is not None and sort_key == "invited_users_count_asc":
+        stmt = stmt.order_by(referral_count_expr.asc(), User.user_id.asc())
+    elif referral_count_expr is not None and sort_key == "invited_users_count_desc":
+        stmt = stmt.order_by(referral_count_expr.desc(), User.user_id.desc())
+    elif subscription_expires_expr is not None and sort_key == "subscription_expires_at_asc":
+        stmt = stmt.order_by(subscription_expires_expr.asc().nullslast(), User.user_id.asc())
+    elif subscription_expires_expr is not None and sort_key == "subscription_expires_at_desc":
+        stmt = stmt.order_by(subscription_expires_expr.desc().nullslast(), User.user_id.desc())
     else:
         order = sort_map.get(sort_key, sort_map["registered_desc"])
         if isinstance(order, tuple):
@@ -387,9 +689,34 @@ def _user_panel_status_condition(panel_status: str):
             normalized_status == "active", blank_status & Subscription.is_active.is_(True)
         )
     elif status == "expired":
-        status_cond = or_(
-            normalized_status == "expired", blank_status & Subscription.is_active.is_(False)
+        now = datetime.now(timezone.utc)
+        expired_subs = aliased(Subscription)
+        active_subs = aliased(Subscription)
+        expired_status = sa_func.lower(sa_func.coalesce(expired_subs.status_from_panel, ""))
+        expired_blank_status = or_(
+            expired_subs.status_from_panel.is_(None),
+            expired_subs.status_from_panel == "",
         )
+        expired_condition = or_(
+            expired_status == "expired",
+            expired_blank_status & expired_subs.is_active.is_(False),
+            expired_subs.end_date <= now,
+        )
+        expired_exists = (
+            select(expired_subs.subscription_id)
+            .where(expired_subs.user_id == User.user_id, expired_condition)
+            .exists()
+        )
+        active_exists = (
+            select(active_subs.subscription_id)
+            .where(
+                active_subs.user_id == User.user_id,
+                active_subs.is_active.is_(True),
+                active_subs.end_date > now,
+            )
+            .exists()
+        )
+        return and_(expired_exists, ~active_exists)
     else:
         status_cond = normalized_status == "limited"
 
@@ -419,6 +746,24 @@ def _user_search_condition(query: str):
     return or_(*conditions)
 
 
+def _serialize_trial_summary(user: User, trial_subs: List[Subscription]) -> Dict[str, Any]:
+    first_trial_sub = trial_subs[0] if trial_subs else None
+    latest_trial_sub = trial_subs[-1] if trial_subs else None
+    first_start = getattr(first_trial_sub, "start_date", None)
+    latest_start = getattr(latest_trial_sub, "start_date", None)
+    latest_end = getattr(latest_trial_sub, "end_date", None)
+    reset_at = getattr(user, "trial_eligibility_reset_at", None)
+    return {
+        "used": bool(trial_subs),
+        "count": len(trial_subs),
+        "first_activated_at": first_start.isoformat() if first_start else None,
+        "latest_activated_at": latest_start.isoformat() if latest_start else None,
+        "latest_end_date": latest_end.isoformat() if latest_end else None,
+        "active": bool(latest_trial_sub and getattr(latest_trial_sub, "is_active", False)),
+        "last_reset_at": reset_at.isoformat() if reset_at else None,
+    }
+
+
 async def admin_user_detail_route(request: web.Request) -> web.Response:
     _require_admin_user_id(request)
     target_id = int(request.match_info["user_id"])
@@ -438,6 +783,15 @@ async def admin_user_detail_route(request: web.Request) -> web.Response:
             .limit(20)
         )
         latest_subs = (await session.execute(latest_subs_stmt)).scalars().all()
+        trial_subs_stmt = (
+            select(Subscription)
+            .where(
+                Subscription.user_id == target_id,
+                sa_func.lower(sa_func.coalesce(Subscription.provider, "")) == "trial",
+            )
+            .order_by(Subscription.start_date.asc().nullslast(), Subscription.end_date.asc())
+        )
+        trial_subs = (await session.execute(trial_subs_stmt)).scalars().all()
         total_paid = await payment_dal.get_user_total_paid(session, target_id)
         recent_payments_stmt = (
             select(Payment)
@@ -447,7 +801,12 @@ async def admin_user_detail_route(request: web.Request) -> web.Response:
         )
         recent_payments = (await session.execute(recent_payments_stmt)).scalars().all()
         log_count = await message_log_dal.count_user_message_logs(session, target_id)
-        avatar_keys = await _bulk_user_avatar_keys(session, [target_id])
+        inviter = await user_dal.get_referrer_for_user(session, user)
+        invitees_total = await user_dal.count_users_referred_by(session, target_id)
+        avatar_user_ids = [target_id]
+        if inviter is not None:
+            avatar_user_ids.append(int(inviter.user_id))
+        avatar_keys = await _bulk_user_avatar_keys(session, avatar_user_ids)
 
         # Referral links — both the bot deep-link and the webapp deep-link.
         referral_code: Optional[str] = None
@@ -478,7 +837,13 @@ async def admin_user_detail_route(request: web.Request) -> web.Response:
     # imports into their VPN client. May be missing if the user has never
     # been provisioned on the panel.
     subscription_url: Optional[str] = None
-    panel_uuid = getattr(user, "panel_user_uuid", None)
+    last_vpn_connected_at: Optional[str] = None
+    vpn_connection_status = "unknown"
+    panel_uuid = getattr(user, "panel_user_uuid", None) or getattr(
+        active_sub,
+        "panel_user_uuid",
+        None,
+    )
     if panel_uuid:
         subscription_service = request.app.get("subscription_service")
         panel_service = getattr(subscription_service, "panel_service", None)
@@ -487,45 +852,94 @@ async def admin_user_detail_route(request: web.Request) -> web.Response:
                 panel_data = await panel_service.get_user_by_uuid(panel_uuid)
                 if panel_data:
                     subscription_url = panel_data.get("subscriptionUrl") or None
+                    vpn_activity = _panel_user_connection_activity(panel_data)
+                    vpn_connection_status = str(vpn_activity.get("status") or "unknown")
+                    last_vpn_connected_at = vpn_activity.get("last_connected_at")
             except Exception as exc_panel:  # pragma: no cover
                 logger.warning(
-                    "Failed to fetch subscriptionUrl for user %s (uuid=%s): %s",
+                    "Failed to fetch panel details for user %s (uuid=%s): %s",
                     target_id,
                     panel_uuid,
                     exc_panel,
                 )
 
-    serialized_user = _serialize_user(user)
-    serialized_user["avatar_url"] = (
-        f"/api/admin/users/{target_id}/avatar?v={avatar_keys[target_id]}"
-        if target_id in avatar_keys
-        else None
+    serialized_user = _serialize_admin_user_with_avatar(user, avatar_keys)
+    serialized_inviter = (
+        _serialize_admin_user_with_avatar(inviter, avatar_keys) if inviter is not None else None
     )
+    trial_payload = _serialize_trial_summary(user, trial_subs)
 
     return _ok(
         {
             "user": serialized_user,
             "active_subscription": _serialize_subscription(active_sub) if active_sub else None,
             "subscriptions": [_serialize_subscription(s) for s in (latest_subs or [])],
+            "trial": trial_payload,
             "total_paid": float(total_paid),
             "recent_payments": [_serialize_payment(p) for p in recent_payments],
             "log_count": int(log_count or 0),
             "subscription_url": subscription_url,
+            "last_vpn_connected_at": last_vpn_connected_at,
+            "vpn_connection_status": vpn_connection_status,
             "referral": {
                 "code": referral_code,
                 "bot_link": referral_bot_link,
                 "webapp_link": referral_webapp_link,
+                "inviter": serialized_inviter,
+                "invitees_total": int(invitees_total or 0),
             },
         }
     )
 
 
+async def admin_user_referrals_route(request: web.Request) -> web.Response:
+    _require_admin_user_id(request)
+    target_id = int(request.match_info["user_id"])
+    page = max(0, int(request.query.get("page", 0) or 0))
+    page_size = min(100, max(1, int(request.query.get("page_size", 25) or 25)))
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+
+    async with async_session_factory() as session:
+        user = await user_dal.get_user_by_id(session, target_id)
+        if not user:
+            return _error(404, "not_found", "User not found")
+
+        inviter = await user_dal.get_referrer_for_user(session, user)
+        invitees_total = await user_dal.count_users_referred_by(session, target_id)
+        invitees = await user_dal.get_users_referred_by(
+            session,
+            target_id,
+            limit=page_size,
+            offset=page * page_size,
+        )
+        avatar_user_ids = [target_id, *(int(u.user_id) for u in invitees)]
+        if inviter is not None:
+            avatar_user_ids.append(int(inviter.user_id))
+        avatar_keys = await _bulk_user_avatar_keys(session, avatar_user_ids)
+
+    return _ok(
+        {
+            "user": _serialize_admin_user_with_avatar(user, avatar_keys),
+            "inviter": _serialize_admin_user_with_avatar(inviter, avatar_keys)
+            if inviter is not None
+            else None,
+            "invitees": [
+                _serialize_admin_user_with_avatar(invitee, avatar_keys) for invitee in invitees
+            ],
+            "total": int(invitees_total or 0),
+            "page": page,
+            "page_size": page_size,
+        }
+    )
+
+
 async def admin_user_ban_route(request: web.Request) -> web.Response:
     _require_admin_user_id(request)
     target_id = int(request.match_info["user_id"])
     payload = await _read_json(request)
     desired = bool(payload.get("banned"))
 
+    settings: Settings = request.app["settings"]
     async_session_factory: sessionmaker = request.app["async_session_factory"]
     async with async_session_factory() as session:
         user = await user_dal.get_user_by_id(session, target_id)
@@ -534,6 +948,7 @@ async def admin_user_ban_route(request: web.Request) -> web.Response:
         user.is_banned = bool(desired)
         await session.commit()
         await session.refresh(user)
+    await _invalidate_after_admin_user_mutation(settings, target_id)
     return _ok({"user": _serialize_user(user)})
 
 
@@ -624,36 +1039,180 @@ async def admin_user_message_preview_route(request: web.Request) -> web.Response
     return _ok({})
 
 
-async def admin_user_delete_route(request: web.Request) -> web.Response:
-    actor_id = _require_admin_user_id(request)
-    target_id = int(request.match_info["user_id"])
+def _admin_user_display_name_for_message(user: User) -> str:
+    full = " ".join(
+        part
+        for part in [getattr(user, "first_name", None), getattr(user, "last_name", None)]
+        if part
+    ).strip()
+    return (
+        full
+        or (f"@{user.username}" if getattr(user, "username", None) else None)
+        or getattr(user, "email", None)
+        or f"User #{user.user_id}"
+    )
 
+
+async def admin_user_telegram_profile_link_route(request: web.Request) -> web.Response:
+    actor_id = _require_admin_user_id(request)
+    admin_telegram_id = request.get("admin_telegram_id")
+    if not admin_telegram_id:
+        return _error(403, "admin_telegram_unavailable")
+
+    queue_manager = get_queue_manager()
+    if not queue_manager:
+        return _error(503, "queue_unavailable")
+
+    target_id = int(request.match_info["user_id"])
+    settings: Settings = request.app["settings"]
     async_session_factory: sessionmaker = request.app["async_session_factory"]
+
     async with async_session_factory() as session:
-        ok = await user_dal.delete_user_and_relations(session, target_id)
-        if not ok:
-            await session.rollback()
+        target_user = await user_dal.get_user_by_id(session, target_id)
+        if not target_user:
             return _error(404, "not_found")
+        if not target_user.telegram_id:
+            return _error(404, "no_telegram_account")
+
+        admin_user = await user_dal.get_user_by_id(session, actor_id)
+        lang = (
+            getattr(admin_user, "language_code", None)
+            or getattr(settings, "DEFAULT_LANGUAGE", None)
+            or "ru"
+        )
+
         await message_log_dal.create_message_log(
             session,
             {
                 "user_id": actor_id,
+                "event_type": "admin_profile_link_webapp",
+                "content": f"Requested Telegram profile link for user_id={target_id}",
+                "is_admin_event": True,
+                "target_user_id": target_id,
+            },
+        )
+        await session.commit()
+
+    i18n_instance = request.app.get("i18n")
+    translate = (
+        (lambda key, **kwargs: i18n_instance.gettext(lang, key, **kwargs))
+        if i18n_instance is not None
+        else (lambda key, **kwargs: key.format(**kwargs) if kwargs else key)
+    )
+    target_name = _admin_user_display_name_for_message(target_user)
+    telegram_id = int(target_user.telegram_id)
+    profile_url = f"tg://user?id={telegram_id}"
+    message_text = translate(
+        "admin_user_profile_link_message",
+        name=html_escape(target_name),
+        user_id=target_user.user_id,
+        telegram_id=telegram_id,
+    )
+    if message_text == "admin_user_profile_link_message":
+        message_text = (
+            f"Профиль пользователя: <b>{html_escape(target_name)}</b>\n"
+            f"User ID: <code>{target_user.user_id}</code>\n"
+            f"Telegram ID: <code>{telegram_id}</code>\n\n"
+            "Нажмите кнопку ниже, чтобы открыть профиль в Telegram."
+        )
+
+    button_text = translate("user_card_open_profile_button")
+    if button_text == "user_card_open_profile_button":
+        button_text = "👤 Открыть профиль"
+
+    markup = InlineKeyboardMarkup(
+        inline_keyboard=[[InlineKeyboardButton(text=button_text, url=profile_url)]]
+    )
+
+    try:
+        await send_message_via_queue(
+            queue_manager,
+            int(admin_telegram_id),
+            MessageContent(content_type="text", text=message_text),
+            parse_mode="HTML",
+            disable_web_page_preview=True,
+            reply_markup=markup,
+        )
+    except Exception as exc:
+        logger.warning("Admin profile link message enqueue failed: %s", exc)
+        return _error(502, "send_failed", str(exc))
+
+    return _ok({"queued": True})
+
+
+async def admin_user_delete_route(request: web.Request) -> web.Response:
+    actor_id = _require_admin_user_id(request)
+    target_id = int(request.match_info["user_id"])
+
+    settings: Settings = request.app["settings"]
+    panel_service = request.app.get("panel_service")
+    if panel_service is None:
+        subscription_service = request.app.get("subscription_service")
+        panel_service = getattr(subscription_service, "panel_service", None)
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+    async with async_session_factory() as session:
+        user = await user_dal.get_user_by_id(session, target_id)
+        if not user:
+            return _error(404, "not_found")
+
+        panel_user_uuids = await user_dal.get_panel_user_uuids_for_user(
+            session,
+            target_id,
+            user=user,
+        )
+        if panel_user_uuids and panel_service is None:
+            await session.rollback()
+            return _error(503, "panel_service_unavailable")
+
+        for panel_uuid in panel_user_uuids:
+            try:
+                panel_deleted = await panel_service.delete_user_from_panel(
+                    panel_uuid,
+                    log_response=False,
+                )
+            except Exception as exc:
+                logger.warning(
+                    "Admin webapp failed to delete panel user %s for user %s: %s",
+                    panel_uuid,
+                    target_id,
+                    exc,
+                )
+                await session.rollback()
+                return _error(502, "panel_delete_failed", str(exc))
+
+            if not panel_deleted:
+                await session.rollback()
+                return _error(
+                    502,
+                    "panel_delete_failed",
+                    f"Failed to delete panel user {panel_uuid}",
+                )
+
+        ok = await user_dal.delete_user_and_relations(session, target_id)
+        if not ok:
+            await session.rollback()
+            return _error(404, "not_found")
+        await message_log_dal.create_message_log_no_commit(
+            session,
+            {
+                "user_id": actor_id if actor_id != target_id else None,
                 "event_type": "admin_delete_user_webapp",
-                "content": f"Deleted user_id={target_id}",
+                "content": (
+                    f"Deleted user_id={target_id}; "
+                    f"panel_uuids={','.join(panel_user_uuids) or 'none'}"
+                ),
                 "is_admin_event": True,
             },
         )
         await session.commit()
+    await _invalidate_after_admin_user_mutation(settings, target_id)
     return _ok({})
 
 
 async def admin_user_reset_trial_route(request: web.Request) -> web.Response:
     actor_id = _require_admin_user_id(request)
     target_id = int(request.match_info["user_id"])
-    panel_service = request.app.get("panel_service")
-    subscription_service = request.app.get("subscription_service")
-    if panel_service is None or subscription_service is None:
-        return _error(503, "service_unavailable")
+    settings: Settings = request.app["settings"]
 
     async_session_factory: sessionmaker = request.app["async_session_factory"]
     async with async_session_factory() as session:
@@ -661,21 +1220,23 @@ async def admin_user_reset_trial_route(request: web.Request) -> web.Response:
         if not user:
             return _error(404, "not_found")
 
-        active = await subscription_dal.get_active_subscription_by_user_id(session, target_id)
-        if active:
-            await session.delete(active)
+        reset_at = await user_dal.mark_trial_eligibility_reset(session, target_id)
+        if reset_at is None:
+            await session.rollback()
+            return _error(404, "not_found")
 
-        await message_log_dal.create_message_log(
+        await message_log_dal.create_message_log_no_commit(
             session,
             {
                 "user_id": actor_id,
                 "event_type": "admin_reset_trial_webapp",
-                "content": f"Reset trial for user_id={target_id}",
+                "content": f"Reset trial eligibility for user_id={target_id}",
                 "is_admin_event": True,
                 "target_user_id": target_id,
             },
         )
         await session.commit()
+    await _invalidate_after_admin_user_mutation(settings, target_id)
     return _ok({})
 
 
@@ -683,6 +1244,7 @@ async def admin_user_premium_override_route(request: web.Request) -> web.Respons
     """Premium-squad traffic overrides only (unlimited toggle + bonus GB)."""
     actor_id = _require_admin_user_id(request)
     target_id = int(request.match_info["user_id"])
+    settings: Settings = request.app["settings"]
     payload = await _read_json(request)
     subscription_service = request.app.get("subscription_service")
 
@@ -734,13 +1296,15 @@ async def admin_user_premium_override_route(request: web.Request) -> web.Respons
             await session.commit()
             await session.refresh(active)
 
+    await _invalidate_after_admin_user_mutation(settings, target_id)
     return _ok({"subscription": _serialize_subscription(active)})
 
 
 async def admin_user_regular_traffic_override_route(request: web.Request) -> web.Response:
-    """Main (regular) traffic: unlimited-style ceiling + admin bonus GB."""
+    """Main (regular) traffic: native unlimited panel limit + admin bonus GB."""
     actor_id = _require_admin_user_id(request)
     target_id = int(request.match_info["user_id"])
+    settings: Settings = request.app["settings"]
     payload = await _read_json(request)
 
     unlimited = bool(payload.get("unlimited"))
@@ -791,6 +1355,79 @@ async def admin_user_regular_traffic_override_route(request: web.Request) -> web
         await session.commit()
         await session.refresh(active)
 
+    await _invalidate_after_admin_user_mutation(settings, target_id)
+    return _ok({"subscription": _serialize_subscription(active)})
+
+
+async def admin_user_hwid_device_limit_route(request: web.Request) -> web.Response:
+    """Override the user's base HWID device limit.
+
+    ``hwid_device_limit == 0`` means unlimited; ``NULL`` means the tariff/.env
+    default is used. Purchased extra devices remain tracked separately and are
+    added when syncing the effective panel limit.
+    """
+    actor_id = _require_admin_user_id(request)
+    target_id = int(request.match_info["user_id"])
+    settings: Settings = request.app["settings"]
+    payload = await _read_json(request)
+
+    unlimited = bool(payload.get("unlimited"))
+    use_default = bool(payload.get("use_default") or payload.get("reset_to_default"))
+    limit_raw = payload.get("hwid_device_limit", payload.get("limit"))
+
+    if unlimited:
+        hwid_device_limit: Optional[int] = 0
+    elif use_default or limit_raw is None or limit_raw == "":
+        hwid_device_limit = None
+    else:
+        try:
+            hwid_device_limit = int(limit_raw)
+        except (TypeError, ValueError):
+            return _error(
+                400,
+                "invalid_hwid_device_limit",
+                "hwid_device_limit must be a non-negative integer",
+            )
+        if hwid_device_limit < 0 or hwid_device_limit > 1_000_000:
+            return _error(
+                400,
+                "invalid_hwid_device_limit",
+                "hwid_device_limit must be an integer from 0 to 1000000",
+            )
+
+    subscription_service = request.app.get("subscription_service")
+
+    async_session_factory: sessionmaker = request.app["async_session_factory"]
+    async with async_session_factory() as session:
+        active = await subscription_dal.get_active_subscription_by_user_id(session, target_id)
+        if not active:
+            return _error(404, "no_active_subscription")
+
+        active.hwid_device_limit = hwid_device_limit
+
+        effective_limit = None
+        if subscription_service is not None:
+            effective_limit = await subscription_service.sync_hwid_device_limit_to_panel(
+                session, target_id
+            )
+
+        await message_log_dal.create_message_log(
+            session,
+            {
+                "user_id": actor_id,
+                "event_type": "admin_hwid_device_limit_webapp",
+                "content": (
+                    f"hwid_device_limit={hwid_device_limit!r} "
+                    f"effective_hwid_device_limit={effective_limit!r}"
+                ),
+                "is_admin_event": True,
+                "target_user_id": target_id,
+            },
+        )
+        await session.commit()
+        await session.refresh(active)
+
+    await _invalidate_after_admin_user_mutation(settings, target_id)
     return _ok({"subscription": _serialize_subscription(active)})
 
 
@@ -805,6 +1442,7 @@ async def admin_user_traffic_grant_route(request: web.Request) -> web.Response:
     """
     actor_id = _require_admin_user_id(request)
     target_id = int(request.match_info["user_id"])
+    settings: Settings = request.app["settings"]
     payload = await _read_json(request)
 
     kind = str(payload.get("kind") or "regular").strip().lower()
@@ -865,6 +1503,7 @@ async def admin_user_traffic_grant_route(request: web.Request) -> web.Response:
 
         refreshed = await subscription_dal.get_active_subscription_by_user_id(session, target_id)
 
+    await _invalidate_after_admin_user_mutation(settings, target_id)
     return _ok(
         {
             "subscription": _serialize_subscription(refreshed) if refreshed else None,
@@ -880,6 +1519,7 @@ async def admin_user_traffic_grant_route(request: web.Request) -> web.Response:
 async def admin_user_extend_route(request: web.Request) -> web.Response:
     actor_id = _require_admin_user_id(request)
     target_id = int(request.match_info["user_id"])
+    settings: Settings = request.app["settings"]
     payload = await _read_json(request)
     try:
         days = int(payload.get("days") or 0)
@@ -887,6 +1527,8 @@ async def admin_user_extend_route(request: web.Request) -> web.Response:
         return _error(400, "invalid_days")
     if days <= 0:
         return _error(400, "invalid_days")
+    extend_hwid_devices = payload.get("extend_hwid_devices")
+    extend_hwid_devices = True if extend_hwid_devices is None else bool(extend_hwid_devices)
 
     subscription_service = request.app.get("subscription_service")
     if subscription_service is None:
@@ -899,6 +1541,7 @@ async def admin_user_extend_route(request: web.Request) -> web.Response:
             target_id,
             days,
             "admin_extend_subscription_webapp",
+            extend_hwid_devices=extend_hwid_devices,
         )
         if not new_end:
             await session.rollback()
@@ -909,7 +1552,10 @@ async def admin_user_extend_route(request: web.Request) -> web.Response:
             {
                 "user_id": actor_id,
                 "event_type": "admin_extend_subscription_webapp",
-                "content": f"+{days}d -> {new_end.isoformat()}",
+                "content": (
+                    f"+{days}d -> {new_end.isoformat()} "
+                    f"(hwid={'yes' if extend_hwid_devices else 'no'})"
+                ),
                 "is_admin_event": True,
                 "target_user_id": target_id,
             },
@@ -918,6 +1564,7 @@ async def admin_user_extend_route(request: web.Request) -> web.Response:
 
         refreshed = await subscription_dal.get_active_subscription_by_user_id(session, target_id)
 
+    await _invalidate_after_admin_user_mutation(settings, target_id)
     return _ok(
         {
             "subscription": _serialize_subscription(refreshed) if refreshed else None,

backend/bot/app/web/admin_api_impl/webapp_runtime.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from bot.app.web.webapp.cache_helpers import (
+    invalidate_all_webapp_user_payloads,
+    reset_subscription_guides_cache,
+    reset_webapp_settings_cache,
+)
+
+WEBAPP_APPEARANCE_SETTING_KEYS = frozenset(
+    {
+        "WEBAPP_TITLE",
+        "WEBAPP_LOGO_URL",
+        "WEBAPP_FAVICON_URL",
+        "WEBAPP_FAVICON_USE_CUSTOM",
+        "WEBAPP_LOGO_FAVICON_URL",
+    }
+)
+
+WEBAPP_DEVICE_PAYLOAD_SETTING_KEYS = frozenset(
+    {
+        "MY_DEVICES_SECTION_ENABLED",
+        "USER_HWID_DEVICE_LIMIT",
+        "USER_TRAFFIC_LIMIT_GB",
+        "USER_TRAFFIC_STRATEGY",
+    }
+)
+
+
+def changed_setting_keys(
+    updates: Mapping[str, Any] | None = None,
+    deletes: Sequence[Any] | None = None,
+) -> set[str]:
+    keys = {str(key) for key in (updates or {}).keys()}
+    keys.update(str(key) for key in (deletes or []) if key is not None)
+    return keys
+
+
+async def refresh_webapp_runtime_after_settings_change(
+    request: Any,
+    *,
+    updates: Mapping[str, Any] | None = None,
+    deletes: Sequence[Any] | None = None,
+    include_user_payloads: bool = True,
+) -> None:
+    settings = request.app["settings"]
+    keys = changed_setting_keys(updates, deletes)
+
+    reset_webapp_settings_cache(request.app)
+    reset_subscription_guides_cache(request.app)
+
+    if include_user_payloads:
+        await invalidate_all_webapp_user_payloads(
+            settings,
+            include_devices=bool(keys & WEBAPP_DEVICE_PAYLOAD_SETTING_KEYS),
+        )
+
+    if keys & WEBAPP_APPEARANCE_SETTING_KEYS:
+        request.app["webapp_logo_cache"] = None
+        from bot.app.web.admin_api_impl.themes import prune_unused_appearance_assets
+
+        prune_unused_appearance_assets(settings)

backend/bot/app/web/subscription_webapp.py

@@ -11,9 +11,12 @@ from bot.app.web.webapp import (
     billing as _billing,
     common as _common,
     devices as _devices,
+    guides as _guides,
     payloads as _payloads,
     routes as _routes,
     serializers as _serializers,
+    support as _support,
+    telegram_notifications as _telegram_notifications,
 )
 
 _MODULES = (
@@ -23,9 +26,12 @@ _MODULES = (
     _assets,
     _auth,
     _account,
+    _telegram_notifications,
     _serializers,
     _billing,
     _devices,
+    _guides,
+    _support,
     _routes,
     _application,
 )

backend/bot/app/web/templates/open_app_gateway.html

@@ -0,0 +1,230 @@
+<!doctype html>
+<html lang="__LANG__">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link id="app-favicon" rel="icon" href="data:," sizes="any">
+    <title>__PAGE_TITLE__</title>
+    <style nonce="__NONCE__">
+      :root {
+        color-scheme: dark light;
+        --accent: #14b86f;
+        --accent-contrast: #03120b;
+        --bg: #0b1017;
+        --panel-3: #344052;
+        --border: #2d3847;
+        --text: #f7fafc;
+        --muted: #aeb8c5;
+        font-family:
+          Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
+          "Segoe UI", sans-serif;
+        background: var(--bg);
+        color: var(--text);
+      }
+
+      body {
+        min-height: 100dvh;
+        margin: 0;
+        display: grid;
+        place-items: center;
+        padding: 24px;
+        box-sizing: border-box;
+      }
+
+      main {
+        width: min(100%, 420px);
+        display: grid;
+        gap: 14px;
+        text-align: center;
+      }
+
+      h1 {
+        margin: 0;
+        font-size: 24px;
+        line-height: 1.2;
+      }
+
+      p {
+        margin: 0;
+        color: var(--muted);
+        font-size: 15px;
+        line-height: 1.55;
+      }
+
+      .actions {
+        display: grid;
+        gap: 10px;
+        margin-top: 4px;
+      }
+
+      .button {
+        display: inline-flex;
+        min-height: 46px;
+        align-items: center;
+        justify-content: center;
+        border: 1px solid transparent;
+        border-radius: 8px;
+        background: var(--accent);
+        color: var(--accent-contrast);
+        padding: 0 18px;
+        box-sizing: border-box;
+        font: inherit;
+        font-weight: 800;
+        text-decoration: none;
+        cursor: pointer;
+      }
+
+      .button.secondary {
+        border-color: var(--border);
+        background: transparent;
+        color: var(--text);
+      }
+
+      .button[aria-disabled="true"] {
+        pointer-events: none;
+        background: var(--panel-3);
+        color: var(--muted);
+      }
+
+      [hidden] {
+        display: none !important;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1 id="title"></h1>
+      <p id="status"></p>
+      <div class="actions">
+        <a id="open-link" class="button" href="#" rel="noreferrer"></a>
+        <button id="close-button" class="button secondary" type="button" hidden></button>
+      </div>
+    </main>
+    <script nonce="__NONCE__">
+      (() => {
+        const messages = __MESSAGES_JSON__;
+        const titleEl = document.getElementById("title");
+        const statusEl = document.getElementById("status");
+        const openLink = document.getElementById("open-link");
+        const closeButton = document.getElementById("close-button");
+        const params = new URLSearchParams(window.location.hash.replace(/^#/, ""));
+        const target = String(params.get("url") || "").trim();
+        const isUnsafe =
+          !target ||
+          hasControlChars(target) ||
+          /^(?:javascript|data|vbscript|https?):/i.test(target);
+        let attempted = false;
+        let pageLeft = false;
+        let state = "opening";
+        let closeAttemptTimer = null;
+        const CLOSE_ATTEMPT_DELAY_MS = 2500;
+
+        function hasControlChars(value) {
+          return Array.from(String(value || "")).some((char) => {
+            const code = char.charCodeAt(0);
+            return code <= 31 || code === 127;
+          });
+        }
+
+        function text(key, fallback) {
+          const value = messages && messages[key];
+          return typeof value === "string" && value ? value : fallback;
+        }
+
+        function tryCloseWindow() {
+          try {
+            window.close();
+          } catch (_error) {
+            void _error;
+          }
+        }
+
+        function render(nextState) {
+          state = nextState;
+          if (nextState === "unavailable") {
+            titleEl.textContent = text("unavailableTitle", "App link unavailable");
+            statusEl.textContent = text("unavailableHint", "Return to Telegram and try again.");
+            openLink.textContent = text("button", "Open app");
+            openLink.setAttribute("aria-disabled", "true");
+            openLink.removeAttribute("href");
+            closeButton.hidden = true;
+            return;
+          }
+
+          if (nextState === "done") {
+            titleEl.textContent = text("doneTitle", "Settings added");
+            statusEl.textContent = text("doneHint", "You can close this window.");
+            openLink.textContent = text("retryButton", "Open again");
+            openLink.removeAttribute("aria-disabled");
+            openLink.href = target;
+            closeButton.textContent = text("closeButton", "Close window");
+            closeButton.hidden = false;
+            return;
+          }
+
+          titleEl.textContent = text("title", "Opening app");
+          statusEl.textContent =
+            nextState === "manual"
+              ? text("manualHint", "If the app did not open automatically, tap the button below.")
+              : text("hint", "Opening the app on this device...");
+          openLink.textContent = text("button", "Open app");
+          openLink.removeAttribute("aria-disabled");
+          openLink.href = target;
+          closeButton.hidden = true;
+        }
+
+        function markDone() {
+          if (state === "done" || isUnsafe) return;
+          render("done");
+          if (closeAttemptTimer) window.clearTimeout(closeAttemptTimer);
+          closeAttemptTimer = window.setTimeout(() => {
+            if (pageLeft || document.hidden) tryCloseWindow();
+          }, CLOSE_ATTEMPT_DELAY_MS);
+        }
+
+        function notePageLeft() {
+          if (!attempted) return;
+          pageLeft = true;
+          window.setTimeout(markDone, 900);
+        }
+
+        function openTarget() {
+          if (isUnsafe) return;
+          attempted = true;
+          pageLeft = false;
+          render("opening");
+          window.location.href = target;
+          window.setTimeout(() => {
+            if (state === "opening" && !pageLeft) render("manual");
+          }, 1600);
+        }
+
+        if (isUnsafe) {
+          render("unavailable");
+          return;
+        }
+
+        openLink.addEventListener("click", (event) => {
+          event.preventDefault();
+          openTarget();
+        });
+        closeButton.addEventListener("click", () => {
+          tryCloseWindow();
+          render("done");
+        });
+        window.addEventListener("pagehide", notePageLeft);
+        document.addEventListener("visibilitychange", () => {
+          if (!attempted) return;
+          if (document.hidden) {
+            pageLeft = true;
+          } else if (pageLeft) {
+            markDone();
+          }
+        });
+
+        render("opening");
+        window.setTimeout(openTarget, 80);
+      })();
+    </script>
+  </body>
+</html>

backend/bot/app/web/templates/subscription_webapp.html

@@ -0,0 +1,73 @@
+<!doctype html>
+<html lang="ru">
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover"
+    />
+    <meta name="robots" content="noindex, nofollow" />
+    <meta name="theme-color" content="#03070b" />
+    <link id="app-favicon" rel="icon" href="/favicon.ico" sizes="any" />
+    <link rel="icon" type="image/png" sizes="192x192" href="/icon-192.png" />
+    <link rel="icon" type="image/png" sizes="512x512" href="/icon-512.png" />
+    <link
+      id="app-apple-touch-icon"
+      rel="apple-touch-icon"
+      sizes="180x180"
+      href="/apple-touch-icon.png"
+    />
+    <link
+      rel="apple-touch-icon-precomposed"
+      sizes="180x180"
+      href="/apple-touch-icon-precomposed.png"
+    />
+    <title>Subscription</title>
+    <link rel="stylesheet" href="/subscription_webapp.css" />
+    <style>
+      .app-boot-fallback {
+        min-height: 100dvh;
+        display: grid;
+        place-items: center;
+        padding: 24px;
+        background: #03070b;
+      }
+
+      .app-boot-fallback__spinner {
+        width: 28px;
+        height: 28px;
+        border: 2px solid rgba(242, 247, 244, 0.18);
+        border-top-color: #00fe7a;
+        border-radius: 999px;
+        animation: appBootSpin 0.8s linear infinite;
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        .app-boot-fallback__spinner {
+          animation: none;
+        }
+      }
+
+      @keyframes appBootSpin {
+        to {
+          transform: rotate(360deg);
+        }
+      }
+    </style>
+  </head>
+
+  <body>
+    <main id="app">
+      <div class="app-boot-fallback" role="status" aria-label="Загрузка">
+        <div class="app-boot-fallback__spinner" aria-hidden="true"></div>
+      </div>
+    </main>
+
+    <!-- WEBAPP_I18N_SCRIPT -->
+    <!-- WEBAPP_CONFIG_SCRIPT -->
+    <!-- WEBAPP_JS_SCRIPT -->
+    <!-- WEBAPP_DEV_MOCK_START -->
+    <script src="/subscription_webapp.js" defer></script>
+    <!-- WEBAPP_DEV_MOCK_END -->
+  </body>
+</html>

backend/bot/app/web/themes/ascii/theme.json

@@ -0,0 +1,17 @@
+{
+  "key": "ascii",
+  "names": {
+    "ru": "ASCII",
+    "en": "ASCII"
+  },
+  "enabled": true,
+  "default": false,
+  "use_primary_accent": false,
+  "use_in_admin": true,
+  "css_file": "style.css",
+  "assets_version": 7,
+  "tokens": {
+    "color_scheme": "dark",
+    "style_preset": "ascii"
+  }
+}

backend/bot/app/web/themes/dark/theme.json

@@ -0,0 +1,27 @@
+{
+  "key": "dark",
+  "names": {
+    "ru": "Темная",
+    "en": "Dark"
+  },
+  "enabled": true,
+  "default": true,
+  "use_primary_accent": true,
+  "use_in_admin": true,
+  "assets_version": 1,
+  "tokens": {
+    "color_scheme": "dark",
+    "bg": "#03070b",
+    "panel": "#111820",
+    "panel_2": "#0b1118",
+    "panel_3": "#17212b",
+    "border": "rgba(255, 255, 255, 0.12)",
+    "border_strong": "rgba(255, 255, 255, 0.2)",
+    "text": "#f2f7f4",
+    "muted": "#a9b4b0",
+    "dim": "#68736f",
+    "danger": "#ff6b6b",
+    "blue": "#2d9cff",
+    "radius": "8px"
+  }
+}

backend/bot/app/web/themes/light/style.css

@@ -0,0 +1,280 @@
+.theme-key-light {
+  color-scheme: light;
+  --accent: #047857;
+  --bg: #f7f8fb;
+  --panel: #ffffff;
+  --panel-2: #f1f5f9;
+  --panel-3: #e8edf3;
+  --border: rgba(15, 23, 42, 0.11);
+  --border-strong: rgba(15, 23, 42, 0.2);
+  --text: #0f172a;
+  --muted: #475569;
+  --dim: #64748b;
+  --danger: #dc2626;
+  --danger-text: #b91c1c;
+  --danger-soft: color-mix(in srgb, var(--danger) 9%, var(--panel));
+  --danger-border: color-mix(in srgb, var(--danger) 34%, var(--border));
+  --success: #16a34a;
+  --success-text: #166534;
+  --success-soft: color-mix(in srgb, var(--success) 10%, var(--panel));
+  --success-border: color-mix(in srgb, var(--success) 34%, var(--border));
+  --warning: #d97706;
+  --warning-text: #92400e;
+  --warning-soft: color-mix(in srgb, var(--warning) 11%, var(--panel));
+  --warning-border: color-mix(in srgb, var(--warning) 34%, var(--border));
+  --info: #2563eb;
+  --info-text: #1d4ed8;
+  --info-soft: color-mix(in srgb, var(--info) 9%, var(--panel));
+  --info-border: color-mix(in srgb, var(--info) 30%, var(--border));
+  --blue: #2563eb;
+  --radius: 8px;
+  --accent-contrast: #ffffff;
+  --surface-sheen: rgba(15, 23, 42, 0.035);
+  --surface-sheen-soft: rgba(15, 23, 42, 0.012);
+  --surface-hover: rgba(15, 23, 42, 0.045);
+  --surface-muted: rgba(15, 23, 42, 0.035);
+  --surface-subtle: rgba(15, 23, 42, 0.025);
+  --surface-subtle-border: rgba(15, 23, 42, 0.1);
+  --overlay-scrim: rgba(15, 23, 42, 0.34);
+  --nav-bg: rgba(255, 255, 255, 0.88);
+  --rail-bg: rgba(255, 255, 255, 0.72);
+  --shadow-soft: 0 6px 18px rgba(15, 23, 42, 0.06);
+  --shadow-strong: 0 18px 44px rgba(15, 23, 42, 0.12);
+  --shadow-popover: 0 14px 28px rgba(15, 23, 42, 0.12);
+  --inset-highlight: rgba(255, 255, 255, 0.75);
+  --admin-bg: #f7f8fb;
+  --admin-surface: #ffffff;
+  --admin-surface-2: #f1f5f9;
+  --admin-elev: #e8edf3;
+  --admin-border: rgba(15, 23, 42, 0.1);
+  --admin-border-strong: rgba(15, 23, 42, 0.18);
+  --admin-text: #0f172a;
+  --admin-muted: #64748b;
+  --admin-dim: #64748b;
+  --admin-chart-stroke: #065f46;
+  --admin-chart-fill: rgba(6, 95, 70, 0.22);
+}
+
+.theme-key-light .ui-spinner,
+.theme-key-light .brand-mark-spinner {
+  color: inherit;
+}
+
+.theme-key-light .telegram-button-spinner {
+  border-color: rgba(255, 255, 255, 0.35);
+  border-top-color: #ffffff;
+}
+
+.theme-key-light .btn-primary,
+.theme-key-light .admin-btn.admin-btn-primary,
+.theme-key-light .admin-extend-control .admin-btn.admin-btn-primary {
+  background: color-mix(in srgb, var(--accent) 50%, #000000);
+  border-color: color-mix(in srgb, var(--accent) 42%, #000000);
+  color: #ffffff;
+}
+
+.theme-key-light .btn-primary:hover:not(:disabled),
+.theme-key-light .admin-btn.admin-btn-primary:hover:not(:disabled),
+.theme-key-light .admin-extend-control .admin-btn.admin-btn-primary:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--accent) 52%, #000000);
+}
+
+.theme-key-light.app-shell {
+  background: var(--bg) !important;
+}
+
+.theme-key-light .phone-screen {
+  background: var(--bg);
+}
+
+/* Flatten Settings rows: no gradient sheen, no inset highlight that reads as a 3D bevel */
+.theme-key-light .settings-row {
+  background: var(--panel);
+  box-shadow: none;
+}
+
+.theme-key-light .settings-row-linked {
+  background: var(--success-soft);
+}
+
+/* Avatar/profile card: bigger lift, but rows below have an opaque background and
+   stack above, so the shadow stays visually under them instead of bleeding through. */
+.theme-key-light .settings-profile {
+  box-shadow:
+    0 10px 24px rgba(15, 23, 42, 0.10),
+    inset 0 1px 0 var(--inset-highlight);
+}
+
+.theme-key-light .settings-links-block {
+  position: relative;
+  z-index: 1;
+}
+
+/* New user-facing activation surfaces */
+.theme-key-light .trial-offer-card,
+.theme-key-light .trial-activation-card,
+.theme-key-light .activation-success-dialog {
+  border-color: color-mix(in srgb, var(--accent) 24%, var(--border));
+  background: #ffffff;
+  box-shadow: 0 12px 30px rgba(15, 23, 42, 0.08);
+}
+
+.theme-key-light .trial-card-head > svg,
+.theme-key-light .dialog-title-icon {
+  color: color-mix(in srgb, var(--accent) 54%, #000000);
+}
+
+.theme-key-light .trial-card-facts span,
+.theme-key-light .trial-activation-facts div {
+  border-color: rgba(15, 23, 42, 0.12);
+  background: rgba(15, 23, 42, 0.025);
+}
+
+/* Slightly stronger axis/grid contrast for the revenue chart on a light surface */
+.theme-key-light .admin-revenue-svg-frame {
+  background: #ffffff;
+}
+
+/* Bonus section: drop accent color from body strongs; only the bonus-system heading
+   and explicitly-accent card headings stay tinted — and they use the same darkened
+   accent technique as .btn-primary on light, so they remain readable on white. */
+.theme-key-light .bonus-card strong {
+  color: var(--text);
+}
+
+.theme-key-light .bonus-card-head strong,
+.theme-key-light .card-heading-accent {
+  color: color-mix(in srgb, var(--accent) 50%, #000000);
+}
+
+.theme-key-light .bonus-card-head > svg {
+  color: color-mix(in srgb, var(--accent) 50%, #000000);
+}
+
+/* Install guide theme surfaces */
+
+.theme-key-light .install-platform-trigger,
+.theme-key-light .install-app-button,
+.theme-key-light .install-step,
+.theme-key-light .install-subscription-card,
+.theme-key-light .install-qr-wrap {
+  background: #ffffff;
+  border-color: rgba(15, 23, 42, 0.12);
+  box-shadow: 0 8px 20px rgba(15, 23, 42, 0.055);
+}
+
+.theme-key-light .install-app-button.active {
+  border-color: color-mix(in srgb, var(--accent) 42%, var(--border));
+  background: color-mix(in srgb, var(--accent) 8%, #ffffff);
+  box-shadow: 0 10px 24px rgba(15, 23, 42, 0.08);
+}
+
+.theme-key-light .install-platform-trigger:focus-visible,
+.theme-key-light .install-platform-trigger[data-state="open"],
+.theme-key-light .install-app-button:focus-visible {
+  border-color: color-mix(in srgb, var(--accent) 48%, var(--border));
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 16%, transparent);
+}
+
+body:has(.theme-key-light) .install-platform-content {
+  background: #ffffff;
+  border-color: rgba(15, 23, 42, 0.14);
+  box-shadow: 0 14px 28px rgba(15, 23, 42, 0.12);
+}
+
+body:has(.theme-key-light) .install-platform-item[data-highlighted],
+body:has(.theme-key-light) .install-platform-item[data-selected] {
+  background: color-mix(in srgb, var(--accent) 9%, #ffffff);
+}
+
+.theme-key-light .install-step-icon,
+.theme-key-light .install-subscription-header-icon {
+  background: color-mix(in srgb, var(--accent) 8%, #ffffff);
+  color: color-mix(in srgb, var(--accent) 55%, #000000);
+}
+
+.theme-key-light .install-qr-divider {
+  color: rgba(15, 23, 42, 0.24);
+}
+
+.theme-key-light .install-feature-star.attention-dot {
+  background: #f59e0b;
+}
+
+.theme-key-light .install-loading .ui-spinner {
+  color: color-mix(in srgb, var(--accent) 55%, #000000);
+}
+
+/* Admin controls: range sliders and sortable rows */
+
+.theme-key-light .ui-range-input::before {
+  background: rgba(15, 23, 42, 0.12);
+}
+
+.theme-key-light .ui-range-input__range {
+  background: color-mix(in srgb, var(--accent) 70%, #0f172a);
+}
+
+.theme-key-light .ui-range-input__thumb {
+  border-color: color-mix(in srgb, var(--accent) 68%, #0f172a);
+  background: #ffffff;
+  box-shadow: 0 2px 8px rgba(15, 23, 42, 0.18);
+}
+
+.theme-key-light .ui-range-input__thumb:focus-visible {
+  box-shadow: 0 0 0 4px color-mix(in srgb, var(--accent) 18%, transparent);
+}
+
+.theme-key-light .ui-sortable-handle {
+  border-radius: 6px;
+  color: color-mix(in srgb, var(--admin-muted) 82%, var(--admin-text));
+}
+
+.theme-key-light .ui-sortable-handle:hover,
+.theme-key-light .ui-sortable-handle:focus-visible {
+  background: rgba(15, 23, 42, 0.055);
+  color: color-mix(in srgb, var(--accent) 58%, #0f172a);
+}
+
+.theme-key-light .ui-sortable {
+  --sortable-drop-line: color-mix(in srgb, var(--accent) 64%, #0f172a);
+}
+
+.theme-key-light .ui-sortable-item.is-drop-target {
+  background: color-mix(in srgb, var(--accent) 8%, #ffffff);
+  box-shadow:
+    inset 0 0 0 1px color-mix(in srgb, var(--accent) 26%, transparent),
+    0 10px 22px color-mix(in srgb, var(--accent) 7%, transparent);
+}
+
+.theme-key-light .ui-sortable-item.is-drop-target::before {
+  background: var(--sortable-drop-line);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 14%, transparent);
+}
+
+/* Admin health config alerts */
+
+.theme-key-light .admin-config-alerts {
+  border-color: color-mix(in srgb, var(--warning) 38%, var(--admin-border));
+  background: color-mix(in srgb, var(--warning) 9%, #ffffff);
+  box-shadow: 0 8px 20px rgba(15, 23, 42, 0.06);
+}
+
+.theme-key-light .admin-config-alerts-error {
+  border-color: color-mix(in srgb, var(--danger) 38%, var(--admin-border));
+  background: color-mix(in srgb, var(--danger) 8%, #ffffff);
+}
+
+.theme-key-light .admin-config-alert-link {
+  background: rgba(255, 255, 255, 0.58);
+}
+
+.theme-key-light .admin-config-alert-link:hover {
+  background: #ffffff;
+}
+
+/* Telegram notifications banner: keep the warm warning tint but swap the
+ * dark-theme inset bevel for the soft drop shadow the other light cards use. */
+.theme-key-light .telegram-notifications-card {
+  box-shadow: 0 8px 20px rgba(15, 23, 42, 0.07);
+}

backend/bot/app/web/themes/light/theme.json

@@ -0,0 +1,16 @@
+{
+  "key": "light",
+  "names": {
+    "ru": "Светлая",
+    "en": "Light"
+  },
+  "enabled": true,
+  "default": false,
+  "use_primary_accent": true,
+  "use_in_admin": true,
+  "css_file": "style.css",
+  "assets_version": 6,
+  "tokens": {
+    "color_scheme": "light"
+  }
+}