Перейти к содержанию
31 минута чтения
Тема: Практика Mini Apps · PHP · Черновики

Как сохранять черновик формы в Telegram Mini App

Для примера пользователь заполняет заявку на консультацию: выбирает тему и подробно описывает вопрос. Он закрывает Mini App, а позже продолжает на том же или другом устройстве. Сделаем рабочую форму с серверным черновиком на PHP: автосохранение, проверка версии, повтор после потери ответа и очистка при оформлении заявки. JavaScript понадобится только для интерфейса Mini App.

Где хранить черновик

Вариант

Когда подходит

Что учитывать

localStorage

Небольшая несекретная форма на одном устройстве.

Привязан к origin и окружению браузера. Пользователь или клиент могут очистить данные; это не резервная копия.

Telegram DeviceStorage

Локальный черновик в поддерживающем клиенте Telegram.

Bot API 9.0+, до 5 МБ на пользователя у бота. Данные остаются на устройстве.

Telegram CloudStorage

Короткий черновик, который нужно открыть на другом устройстве.

Bot API 6.9+, до 1024 ключей; значение до 4096 символов. Нет прикладного контроля версий между устройствами.

Сервер приложения

Длинная заявка, файлы, несколько устройств, аудит изменений.

Нужны авторизация, срок хранения, обработка конфликтов и удаление по правилам продукта.

Ограничения и методы приведены в документации CloudStorage и DeviceStorage. Ни один вариант черновика не подтверждает подлинность формы: при отправке сервер заново проверяет пользователя и поля.

Для основной реализации выберем собственный PHP-сервер: это позволяет хранить до 10000 символов вопроса и проверять версии между устройствами. CloudStorage ниже останется альтернативой для коротких несекретных черновиков. Переключать хранилище незаметно после ошибки нельзя: пользователь должен понимать, где сохранены данные.

Задайте формат, срок жизни и ключ

Сервер выдаёт draftId, целочисленную revision, state, fields и expiresAt. Пользователь не выбирает владельца: user_id получаем только после проверки initData. draftId связывает черновик с заявкой, revision защищает от перезаписи, operationId отличает повтор одного запроса от новой правки.

Восстановленная форма содержит вопрос о переносе базы; после отправки показан номер 42 и кнопка новой заявки, старый черновик очищен.
Восстановленная форма содержит вопрос о переносе базы; после отправки показан номер 42 и кнопка новой заявки, старый черновик очищен.
Фрагменты HTML-формы статьи с демонстрационными данными: восстановленный черновик, затем статус и кнопка после отправки. Нижняя памятка формы опущена; API Telegram и сервер здесь не вызываются.

Черновик живёт семь дней после последнего сохранения. После отправки состояние становится submitted, поля черновика очищаются, applicationId сохраняется. При следующем открытии показываем номер принятой заявки, а не предлагаем отправить старый текст ещё раз. Новая заявка начинается отдельной кнопкой.

Не включайте токены, платёжные реквизиты и полное initData в fields. Вложения потребуют отдельной загрузки с проверкой типа, размера и владельца; здесь форма текстовая. Заявка, черновик и журнал повторов имеют разные сроки хранения: завершённая заявка может оставаться в рабочей системе, а текст черновика удаляется.

Структура проекта
public/form.html
public/api.php
common.php
values.php
auth.php
drafts.php
schema.sql
init.php
Окружение процесса · значения-примеры
APP_DB=/private/form-drafts.sqlite
BOT_TOKEN=TOKEN_FROM_BOTFATHER

Нужны PHP 8.3+, mbstring, PDO и pdo_sqlite; Composer не требуется. Публичный корень — только public, база лежит вне него. Задайте переменные процессу PHP-FPM. Для учебного примера используем одну базу на одном сервере; при переносе на MySQL адаптируйте транзакции и блокировки, не копируйте BEGIN IMMEDIATE.

values.php проверяет типы на границе JSON и БД. Некорректные данные прерывают операцию; они не должны превращаться в ложный успешный результат.

PHP · values.php
<?php

declare(strict_types=1);

/**
 * @return array<string,mixed>
 */
function objectValue(mixed $value): array
{
    if (!is_array($value)) {
        throw new InvalidArgumentException('Expected object');
    }
    $result = [];
    foreach ($value as $key => $item) {
        if (!is_string($key)) {
            throw new InvalidArgumentException('Expected object keys');
        }
        $result[$key] = $item;
    }
    return $result;
}

function stringValue(mixed $value): string
{
    if (!is_string($value)) {
        throw new InvalidArgumentException('Expected string');
    }
    return $value;
}

function intValue(mixed $value): int
{
    if (!is_int($value) && !is_string($value)) {
        throw new InvalidArgumentException('Expected integer');
    }
    $integer = filter_var($value, FILTER_VALIDATE_INT);
    if ($integer === false) {
        throw new InvalidArgumentException('Invalid integer');
    }
    return $integer;
}
PHP · common.php
<?php

declare(strict_types=1);
require_once __DIR__.'/values.php';

function envRequired(string $name): string
{
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException('Missing environment: '.$name);
    }
    return $value;
}

function database(): PDO
{
    $db = new PDO('sqlite:'.envRequired('APP_DB'), null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
    $db->exec('PRAGMA busy_timeout=5000');
    return $db;
}
SQL · schema.sql
CREATE TABLE IF NOT EXISTS drafts (
    user_id INTEGER PRIMARY KEY,
    draft_id TEXT NOT NULL UNIQUE,
    revision INTEGER NOT NULL,
    state TEXT NOT NULL,
    fields TEXT NOT NULL,
    expires_at INTEGER NOT NULL,
    application_id INTEGER
);
CREATE TABLE IF NOT EXISTS applications (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    draft_id TEXT NOT NULL,
    fields TEXT NOT NULL,
    created_at INTEGER NOT NULL,
    UNIQUE(user_id,draft_id)
);
CREATE TABLE IF NOT EXISTS operations (
    user_id INTEGER NOT NULL,
    operation_id TEXT NOT NULL,
    request_hash TEXT NOT NULL,
    response TEXT NOT NULL,
    PRIMARY KEY(user_id,operation_id)
);
PHP · init.php
<?php

declare(strict_types=1);
require __DIR__.'/common.php';
$sql = file_get_contents(__DIR__.'/schema.sql');
if ($sql === false) {
    throw new RuntimeException('Schema missing');
}
database()->exec($sql);
echo "Database ready\n";

Восстановление и последовательное автосохранение

Основное сохранение выполняется на PHP. currentDraft получает запись текущего пользователя; mutateDraft проверяет исходную версию и записывает результат операции. Повтор того же operationId с тем же содержимым возвращает ранее сохранённый ответ. Тот же ключ с другим текстом получает конфликт.

PHP · drafts.php
<?php

declare(strict_types=1);

final class DraftConflict extends RuntimeException
{
}

/**
 * @param array<string,mixed> $input
 * @return array{topic:string,question:string}
 */
function draftFields(array $input): array
{
    if (!in_array($input['topic'] ?? null, ['consultation','migration'], true)
        || !is_string($input['question'] ?? null) || mb_strlen($input['question']) > 10000) {
        throw new InvalidArgumentException('Выберите тему и ограничьте вопрос 10000 символами');
    }
    return ['topic' => $input['topic'],'question' => $input['question']];
}

/**
 * @return array<string,mixed>
 */
function currentDraft(PDO $db, int $userId): array
{
    $q = $db->prepare('SELECT * FROM drafts WHERE user_id=?');
    $q->execute([$userId]);
    $row = $q->fetch(PDO::FETCH_ASSOC);
    if (!$row) {
        $db->prepare("INSERT INTO drafts(user_id,draft_id,revision,state,fields,expires_at) VALUES(?,?,0,'editing',?,?)")
            ->execute([$userId,bin2hex(random_bytes(16)),json_encode(['topic' => 'consultation','question' => ''], JSON_THROW_ON_ERROR),time() + 604800]);
        $q->execute([$userId]);
        $row = $q->fetch(PDO::FETCH_ASSOC);
    }
    $row = objectValue($row);
    if ($row['state'] === 'editing' && intValue($row['expires_at']) < time()) {
        $db->prepare("UPDATE drafts SET state='expired',fields='{}',revision=revision+1 WHERE user_id=?")->execute([$userId]);
        $q->execute([$userId]);
        $row = objectValue($q->fetch(PDO::FETCH_ASSOC));
    }
    return ['draftId' => $row['draft_id'],'revision' => intValue($row['revision']),'state' => $row['state'],
        'fields' => objectValue(json_decode(stringValue($row['fields']), true, 16, JSON_THROW_ON_ERROR)),'expiresAt' => intValue($row['expires_at']),
        'applicationId' => $row['application_id'] === null ? null : intValue($row['application_id'])];
}

/**
 * @param array<string,mixed> $request
 * @return array<string,mixed>
 */
function mutateDraft(PDO $db, int $userId, array $request): array
{
    $operation = $request['operationId'] ?? '';
    $action = $request['action'] ?? '';
    if (!is_string($operation) || !preg_match('/^[0-9a-f-]{36}$/D', $operation)
        || !in_array($action, ['save','submit','new'], true)
        || !is_string($request['draftId'] ?? null) || !is_int($request['revision'] ?? null)) {
        throw new InvalidArgumentException('Некорректная операция');
    }
    $fields = $action === 'new' ? [] : draftFields(is_array($request['fields'] ?? null) ? objectValue($request['fields']) : []);
    $hash = hash('sha256', json_encode([$action,$request['draftId'],$request['revision'],$fields], JSON_THROW_ON_ERROR));
    $db->exec('BEGIN IMMEDIATE');
    try {
        $q = $db->prepare('SELECT * FROM operations WHERE user_id=? AND operation_id=?');
        $q->execute([$userId,$operation]);
        $previous = $q->fetch(PDO::FETCH_ASSOC);
        if (is_array($previous)) {
            if (!hash_equals(stringValue($previous['request_hash']), $hash)) {
                throw new DraftConflict('Ключ уже использован с другими данными');
            }
            $result = objectValue(json_decode(stringValue($previous['response']), true, 32, JSON_THROW_ON_ERROR));
            $db->exec('COMMIT');
            return $result;
        }
        $draft = currentDraft($db, $userId);
        if ($draft['draftId'] !== $request['draftId'] || $draft['revision'] !== $request['revision']) {
            throw new DraftConflict('Форма изменена на другом устройстве');
        }
        if ($action === 'new') {
            if ($draft['state'] === 'editing') {
                throw new DraftConflict('Сначала завершите текущую заявку');
            }
            $db->prepare("UPDATE drafts SET draft_id=?,revision=0,state='editing',fields=?,expires_at=?,application_id=NULL WHERE user_id=?")
                ->execute([bin2hex(random_bytes(16)),json_encode(['topic' => 'consultation','question' => ''], JSON_THROW_ON_ERROR),time() + 604800,$userId]);
        } else {
            if ($draft['state'] !== 'editing') {
                throw new DraftConflict('Черновик уже закрыт или просрочен');
            }
            if ($action === 'submit' && mb_strlen(trim($fields['question'] ?? '')) < 10) {
                throw new InvalidArgumentException('Опишите вопрос: минимум 10 символов');
            }
            $body = json_encode($fields, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
            $applicationId = null;
            if ($action === 'submit') {
                $db->prepare('INSERT INTO applications(user_id,draft_id,fields,created_at) VALUES(?,?,?,?)')->execute([$userId,$draft['draftId'],$body,time()]);
                $applicationId = (int)$db->lastInsertId();
            }
            $db->prepare('UPDATE drafts SET fields=?,revision=revision+1,state=?,expires_at=?,application_id=? WHERE user_id=?')
                ->execute([$action === 'submit' ? '{}' : $body,$action === 'submit' ? 'submitted' : 'editing',time() + 604800,$applicationId,$userId]);
        }
        $result = currentDraft($db, $userId);
        $db->prepare('INSERT INTO operations(user_id,operation_id,request_hash,response) VALUES(?,?,?,?)')
            ->execute([$userId,$operation,$hash,json_encode($result, JSON_THROW_ON_ERROR)]);
        $db->exec('COMMIT');
        return $result;
    } catch (Throwable $error) {
        $db->exec('ROLLBACK');
        throw $error;
    }
}

BEGIN IMMEDIATE сериализует короткие записи SQLite. Проверка revision, создание заявки, очистка черновика и сохранение результата операции выполняются в одной транзакции. Если второй телефон отправит старую revision, он получит 409 и не затрёт первый. Повтор submit после потерянного ответа вернёт тот же applicationId.

После submitted поздний save отклоняется. Кнопка новой заявки разрешена только для закрытого или просроченного черновика. Благодаря отдельному draftId старая операция не относится к новой форме даже при одинаковой revision=0. Не заменяйте эти проверки одним updatedAt: часы на устройствах могут различаться.

Валидация сохранения допускает пустой вопрос, а отправка требует минимум десять символов. Поэтому человек может начать форму и сохранить неполный текст. Ограничения и перечень тем проверяются на сервере, даже если браузер уже показывает select и maxlength.

Подключите модуль к существующей форме

Сначала проверим исходные данные Telegram, затем подключим API. Пример использует заголовок X-Telegram-Init-Data и не создаёт cookie-сессию. initData не пишется в БД или журнал; сервер проверяет подпись и срок. После часа открытое окно попросит переоткрыть Mini App. Для более длинных сессий выдавайте собственную сессию после проверки, как в руководстве по авторизации.

PHP · auth.php
<?php

declare(strict_types=1);

function telegramUser(string $raw, string $botToken, int $now): int
{
    if ($raw === '' || strlen($raw) > 16384) {
        throw new RuntimeException('Invalid initData');
    }
    $fields = [];
    foreach (explode('&', $raw) as $pair) {
        [$key,$value] = array_pad(explode('=', $pair, 2), 2, '');
        $key = urldecode($key);
        $value = urldecode($value);
        if ($key === '' || array_key_exists($key, $fields)) {
            throw new RuntimeException('Duplicate field');
        }
        $fields[$key] = $value;
    }
    $hash = $fields['hash'] ?? '';
    unset($fields['hash']);
    if (!preg_match('/^[a-f0-9]{64}$/D', $hash)) {
        throw new RuntimeException('Invalid hash');
    }
    ksort($fields, SORT_STRING);
    $lines = [];
    foreach ($fields as $key => $value) {
        $lines[] = $key.'='.$value;
    }
    $secret = hash_hmac('sha256', $botToken, 'WebAppData', true);
    if (!hash_equals(hash_hmac('sha256', implode("\n", $lines), $secret), $hash)) {
        throw new RuntimeException('Bad signature');
    }
    $date = filter_var($fields['auth_date'] ?? '', FILTER_VALIDATE_INT);
    if ($date === false || $date > $now + 30 || $date < $now - 3600) {
        throw new RuntimeException('Expired initData');
    }
    $user = json_decode($fields['user'] ?? '', true, 16, JSON_THROW_ON_ERROR);
    if (!is_array($user) || !is_int($user['id'] ?? null) || $user['id'] <= 0) {
        throw new RuntimeException('Missing user');
    }
    return $user['id'];
}
PHP · public/api.php
<?php

declare(strict_types=1);
require dirname(__DIR__).'/common.php';
require dirname(__DIR__).'/auth.php';
require dirname(__DIR__).'/drafts.php';
header('Content-Type: application/json; charset=utf-8');
header('Cache-Control: no-store');
/**
 * @param array<string,mixed> $body
 */
function respond(int $status, array $body): never
{
    http_response_code($status);
    echo json_encode($body, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
    exit;
}
try {
    $userId = telegramUser(stringValue($_SERVER['HTTP_X_TELEGRAM_INIT_DATA'] ?? ''), envRequired('BOT_TOKEN'), time());
} catch (Throwable) {
    respond(401, ['error' => 'Откройте Mini App заново в Telegram']);
}
try {
    $db = database();
    $method = $_SERVER['REQUEST_METHOD'] ?? '';
    if ($method === 'GET') {
        // Первый GET может создать пустой черновик; короткая блокировка исключает гонку.
        $db->exec('BEGIN IMMEDIATE');
        try {
            $result = currentDraft($db, $userId);
            $db->exec('COMMIT');
        } catch (Throwable $error) {
            $db->exec('ROLLBACK');
            throw $error;
        }
        respond(200, $result);
    }
    if ($method !== 'POST') {
        respond(405, ['error' => 'Метод не поддерживается']);
    }
    $raw = file_get_contents('php://input', false, null, 0, 65537);
    if (!is_string($raw) || strlen($raw) > 65536) {
        respond(413, ['error' => 'Слишком большой запрос']);
    }
    $body = json_decode($raw, true, 32, JSON_THROW_ON_ERROR);
    if (!is_array($body)) {
        respond(422, ['error' => 'Ожидается объект JSON']);
    }
    respond(200, mutateDraft($db, $userId, objectValue($body)));
} catch (DraftConflict $error) {
    respond(409, ['error' => $error->getMessage()]);
} catch (InvalidArgumentException|JsonException $error) {
    respond(422, ['error' => 'Проверьте формат и поля заявки']);
} catch (Throwable) {
    respond(503,['error' => 'Не удалось подтвердить сохранение']);
}

Код отклоняет повторяющиеся поля query string, неверную подпись и старый auth_date. В HMAC проверке исключается hash; алгоритм с исключением ещё и signature относится к другой, Ed25519-проверке третьей стороной. Не смешивайте эти два режима.

HTML и JavaScript · public/form.html
<!doctype html>
<html lang="ru"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>Заявка на консультацию</title>
<script src="https://telegram.org/js/telegram-web-app.js"></script>
<style>
*{box-sizing:border-box}body{margin:0;padding:22px;font:16px/1.5 system-ui;background:var(--tg-theme-bg-color,#f4f7fb);color:var(--tg-theme-text-color,#17212b)}main{max-width:560px;margin:auto}h1{font-size:25px;margin:0 0 12px}label{display:block;margin:18px 0 7px}select,textarea,button{width:100%;font:inherit;padding:12px;border-radius:10px;border:1px solid #aab8ca}textarea{min-height:180px;resize:vertical}button{margin-top:12px;background:var(--tg-theme-button-color,#2869b0);color:var(--tg-theme-button-text-color,#fff);border:0}button:disabled{opacity:.55}#status{position:sticky;top:0;padding:12px;background:var(--tg-theme-secondary-bg-color,#e4edf8);border-radius:10px}small{display:block;margin-top:12px;color:#68798e}
</style></head><body><main>
<h1>Заявка на консультацию</h1>
<p id="status" role="status">Загружаем черновик…</p>
<label for="topic">Тема</label><select id="topic" disabled><option value="consultation">Консультация</option><option value="migration">Перенос данных</option></select>
<label for="question">Ваш вопрос</label><textarea id="question" maxlength="10000" disabled></textarea>
<button id="save" disabled>Сохранить черновик</button>
<button id="submit" disabled>Отправить заявку</button>
<button id="retry" hidden>Повторить неподтверждённую операцию</button>
<button id="reload" hidden>Загрузить серверную версию</button>
<button id="new" hidden>Новая заявка</button>
<small>Черновик хранится семь дней после последнего сохранения. Перед закрытием дождитесь подтверждения.</small>
</main><script type="module">
const tg=window.Telegram?.WebApp;
const el=id=>document.getElementById(id);
const status=text=>{el('status').textContent=text;};
let draft, timer, pending=null, busy=false, dirty=false, ready=false;
const fields=()=>({topic:el('topic').value,question:el('question').value});
function controls(){
  const locked=!ready||busy||!!pending||draft?.state!=='editing';
  for(const id of ['topic','question','save','submit'])el(id).disabled=locked;
  el('retry').hidden=!pending;el('new').hidden=!draft||draft.state==='editing';
  el('new').disabled=busy||!!pending;
}
async function api(body){
  const response=await fetch('./api.php',{
    method:body?'POST':'GET',headers:{'Content-Type':'application/json','X-Telegram-Init-Data':tg?.initData??''},
    body:body?JSON.stringify(body):undefined,signal:AbortSignal.timeout(15000)
  });
  const result=await response.json();
  if(!response.ok)throw Object.assign(new Error(result.error||'Ошибка сервера'),{status:response.status});
  if(!result.draftId||!Number.isInteger(result.revision))throw new Error('Неожиданный ответ сервера');
  return result;
}
function display(){
  el('topic').value=draft.fields.topic||'consultation';el('question').value=draft.fields.question||'';
  status(draft.state==='submitted'?'Заявка №'+draft.applicationId+' принята. Черновик очищен.':
    draft.state==='expired'?'Срок хранения истёк. Начните новую заявку.':
    draft.fields.question?'Черновик восстановлен':'Можно начать заполнение');
}
async function load(){
  ready=false;controls();
  try{draft=await api();pending=null;dirty=false;ready=true;display();el('reload').hidden=true;}
  catch(error){status(error.message);el('reload').hidden=false;}
  controls();
}
async function send(action){
  clearTimeout(timer);if(busy)return;
  if(!pending){
    if(!ready)return;
    pending={action,operationId:crypto.randomUUID(),draftId:draft.draftId,revision:draft.revision,
      ...(action==='new'?{}:{fields:fields()})};
  }
  busy=true;controls();status('Сохраняем…');
  try{
    const sent=pending;draft=await api(sent);pending=null;dirty=false;ready=true;
    display();if(draft.state==='editing'&&sent.action==='save')status('Черновик сохранён');
    el('reload').hidden=true;
  }catch(error){
    status(error.message+(error.status===409?' Скопируйте свой текст перед загрузкой серверной версии.':''));
    if(error.status===409||error.status===401){pending=null;ready=false;el('reload').hidden=false;}
    else if(error.status===422){pending=null;}
    // При таймауте/503 payload и operationId сохраняются, поля заблокированы.
  }finally{busy=false;controls();}
}
for(const id of ['topic','question'])el(id).addEventListener('input',()=>{
  dirty=true;status('Есть несохранённые изменения');clearTimeout(timer);
  timer=setTimeout(()=>send('save'),800);
});
el('save').onclick=()=>send('save');el('submit').onclick=()=>send('submit');
el('retry').onclick=()=>send(pending.action);el('new').onclick=()=>send('new');
el('reload').onclick=()=>{if(!dirty||confirm('Загрузить серверную версию? Сначала скопируйте свой текст.'))load();};
if(tg?.initData){tg.ready();load();}else status('Откройте форму через меню Telegram-бота.');
</script></body></html>

Форма ставит таймер на 800 мс после ввода. Во время запроса поля временно блокируются, поэтому завершение старой записи не затрёт новые символы. Это простой учебный вариант: в сложной форме можно разрешить дальнейший ввод, но тогда нужен отдельный снимок отправленной версии и последовательная очередь.

При таймауте или 503 сохраняется тот же payload и operationId, а интерфейс предлагает повтор. При 409 текст остаётся на экране: пользователь может скопировать его перед загрузкой серверной версии. Не перезагружайте форму автоматически в обработчике конфликта. При 422 исправьте поля и отправьте новую операцию.

Bash · создать базу формы
php init.php

Разместите public на HTTPS-домене и задайте адрес form.html в меню Mini App тестового бота. Открытие обычной вкладкой без Telegram должно показать подсказку, а GET api.php без initData — 401. Откройте форму через бота, введите вопрос, дождитесь «Черновик сохранён», закройте и откройте её снова. Для первого опыта не нужен реальный клиент или платёж.

Очищайте черновик после подтверждения заявки

В этом примере кнопка «Отправить заявку» вызывает action=submit с последними полями и текущей revision. Код PHP создаёт applications, очищает drafts.fields и сохраняет номер заявки атомарно. Отдельный DELETE после ответа не нужен: он оставил бы окно, в котором заявка уже принята, а черновик ещё активен.

При неизвестном результате интерфейс блокирует редактирование отправленного снимка и повторяет тот же ключ. Если пользователь закрыл окно, следующий GET вернёт submitted и номер заявки. В браузере не хранится отдельная копия, способная вновь загрузиться поверх закрытого черновика.

SQL · проверить результат заявки
SELECT id,user_id,draft_id,created_at FROM applications ORDER BY id DESC LIMIT 5;
SELECT user_id,draft_id,revision,state,application_id,fields FROM drafts;

После одного успешного submit ожидается одна строка applications, состояние submitted, пустые поля черновика и application_id этой строки. Повтор той же операции не увеличивает количество заявок. Новый operationId со старым draftId и revision даёт 409: повтор нельзя превращать в новую заявку просто сменой ключа.

Отправку сообщения в Telegram выполняйте отдельно после commit через очередь. Ошибка sendMessage не должна откатывать принятую заявку или возвращать клиенту «не отправлено». В интерфейсе источником успеха служит номер сохранённой заявки, а доставка уведомления — отдельный статус.

Несколько устройств: когда нужен свой сервер

В примере все операции живут в одном public/api.php. GET возвращает текущий черновик, POST принимает action=save, submit или new. Это маршруты приложения, не Telegram Bot API. Обеим операциям нужна подтверждённая личность; переданный в JSON user_id не используется.

Для двух устройств выполните тест: откройте форму на обоих с revision=0, сохраните текст на первом, затем попробуйте сохранить на втором. Второй должен получить 409 и сохранить введённый текст на экране. Нажатие «Загрузить серверную версию» после копирования текста покажет уже сохранённую запись.

Очистку просроченных черновиков запускайте и фоново, чтобы они не ждали следующего GET. Не удаляйте журнал operations одновременно с черновиком: он нужен для повторов. В рабочей системе храните в журнале только минимальный результат операции, без полного текста, и задайте горизонт повторов. Здесь response содержит снимок для прозрачного учебного поведения — это дополнительная копия текста, для которой тоже нужен срок удаления.

До публичного запуска добавьте лимит запросов по подтверждённому user_id, мониторинг 409/503 и ограничение размера тела на веб-сервере. Для cookie-сессии потребуется CSRF-защита; для текущего заголовочного протокола не открывайте разрешающий произвольные origin CORS. Настройку уведомления через BotGate держите только на сервере.

Когда достаточно CloudStorage

Если серверный черновик пока избыточен, используйте этот отдельный адаптер для короткой несекретной формы. Он не является второй копией основного сценария: выберите одно хранилище. CloudStorage не заменит серверную проверку при окончательном оформлении заявки.

Подключите telegram-web-app.js на странице Mini App, затем используйте адаптер ниже. Ключ состоит из допустимых букв, цифр, подчёркиваний и дефисов. Успех записи определяется callback, а не фактом вызова setItem. При отсутствии поддержки показываем явное ограничение.

JavaScript · cloud-draft.mjs
export function cloudStore(tg, key = 'consultation_draft_v1') {
  if (!tg?.isVersionAtLeast('6.9') || !tg.CloudStorage) {
    throw new Error('CloudStorage недоступен: обновите Telegram');
  }
  let uncertain = false;
  function call(method, ...args) {
    if (uncertain) return Promise.reject(new Error('Перезапустите форму после сбоя хранения'));
    return new Promise((resolve, reject) => {
      let settled = false;
      const timer = setTimeout(() => {
        settled = true; uncertain = true;
        reject(new Error('Нет подтверждения хранения. Не закрывайте форму'));
      }, 10000);
      const done = (error, value) => {
        if (settled) return;
        settled = true; clearTimeout(timer);
        if (error || (method !== 'getItem' && value !== true)) {
          reject(new Error('Хранилище не подтвердило операцию'));
        } else resolve(value);
      };
      try { tg.CloudStorage[method](key, ...args, done); }
      catch (error) { clearTimeout(timer); settled = true; reject(error); }
    });
  }
  return {
    read: () => call('getItem'),
    write: value => {
      if (value.length > 4096) return Promise.reject(new Error('Черновик слишком большой'));
      return call('setItem', value);
    },
    remove: () => call('removeItem')
  };
}

После таймаута адаптер блокирует новые операции до перезапуска: старый setItem ещё мог выполняться, и следующий запрос не должен обгонять его. Скопируйте введённый текст перед перезапуском. Для прозрачного продолжения при таких сбоях нужен серверный вариант с версиями и идемпотентными операциями.

JavaScript · минимальное использование адаптера
import {cloudStore} from './cloud-draft.mjs';
const store = cloudStore(window.Telegram.WebApp);
const raw = await store.read();
// Перед применением проверьте schema, срок и типы полей.
const draft = raw ? JSON.parse(raw) : null;
await store.write(JSON.stringify({schema:1, updatedAt:Date.now(), fields:{question:'Тестовый вопрос'}}));
// Вызывать только после подтверждённого принятия сервером:
// await store.remove();

Для этой альтернативы сериализуйте записи, сохраняйте после паузы во вводе и показывайте успех только после callback. Перед очисткой дождитесь последней записи. Два одновременно открытых устройства всё равно могут перезаписать друг друга: серверная revision в основном примере решает именно эту проблему. Для localStorage действует то же требование явного успеха плюс риск очистки WebView на устройстве.

Проверки перед запуском

  • Введите текст, дождитесь «Черновик сохранён», закройте Mini App и откройте снова: поля восстановились.

  • При медленном сохранении поля временно заблокированы; после успешного ответа снова доступны. Новая правка должна отправляться уже с полученной revision.

  • Отказ хранилища и превышение размера показывают ошибку. Неподдерживаемый клиент не получает ложный статус успеха.

  • Некорректный JSON и недопустимые поля дают 422; истёкший черновик закрывается по сроку хранения.

  • Ошибка до сохранения заявки не очищает серверный черновик. При потерянном ответе повтор той же операции возвращает сохранённый результат; принятие заявки и очистка выполняются атомарно.

  • Потерянный ответ оформления и повторное открытие возвращают номер прежней заявки.

  • Два устройства в серверном варианте получают конфликт revision, поздняя запись не воскрешает закрытый черновик.

Проверьте Android, iOS и Desktop отдельно: доступность API не заменяет проверку жизненного цикла WebView. BotGate можно использовать для сообщения о принятой заявке, но хранение черновика выполняет Mini App или ваш сервер, а не Telegram-транспорт сервиса.

Проверьте и отказ доступа: изменённый user в initData, неверный hash и просроченный auth_date должны дать 401 до чтения чужой формы. Подмена draftId в JSON при корректном пользователе должна дать конфликт, а не доступ к чужому черновику. После новой заявки повтор старого запроса может вернуть старый результат из журнала, но не должен изменить новую форму.