Храним корзину на сервере
После запуска отправьте исходную строку Telegram.WebApp.initData на свой сервер, проверьте её подпись и срок действия, затем создайте сессию. Сервер находит корзину по владельцу из сессии. Если у магазина уже есть аккаунты, используйте подтверждённую привязку Telegram ID к аккаунту. Пример есть в руководстве по авторизации Mini App.
В
cartsхраните ID корзины, владельца и номер ревизии. Сервер должен однозначно выбирать активную корзину владельца.В
cart_itemsхраните ID корзины, ID товарного варианта и количество. ОграничениеUNIQUE(cart_id, variant_id)оставляет одну строку для каждого варианта.В
ordersхраните владельца, ID и ревизию исходной корзины, итог и статус. Вorder_itemsсохраните снимок названия, цены и количества, чтобы изменения каталога не переписывали старый заказ.
При открытии приложения загрузите корзину с сервера. Браузер может показать ранее загруженный список, пока идёт запрос. Возможность оформить заказ определяет сервер. Добавление товара само по себе не резервирует остаток.
Добавляем товар и меняем количество
Карточка товара отправляет ID варианта и итоговое количество. Кнопки «+» и «−» меняют это число, а «Удалить» устанавливает ноль. Например, если в корзине две пачки, «+» отправляет три. Повтор той же команды не прибавит четвёртую.
PUT /api/carts/c42/items/tea-250
Content-Type: application/json
{ "quantity": 3, "revision": 7 }
Проверьте владельца корзины и допустимый диапазон целого количества. Для ненулевого количества проверьте доступность варианта для продажи. В транзакции заблокируйте строку корзины и сравните ревизию из запроса с текущей. Если ревизии совпадают, обновите позицию и увеличьте номер ревизии при фактическом изменении. Верните корзину с пересчитанной суммой.
Обрабатывайте запросы от кнопок последовательно. Если корзину уже изменили в другом окне, верните 409 с актуальным состоянием. Клиент показывает новые данные и даёт пользователю продолжить с них. После таймаута сначала перечитайте корзину, чтобы увидеть, успело ли сохраниться изменение.
Показываем сумму перед оформлением
Перед оформлением запросите у сервера расчёт для текущей ревизии. Покажите позиции, цену за единицу, сумму и способ получения. Денежные значения в этом примере хранятся целыми числами в копейках.
Сохраните на сервере короткоживущий расчёт с ID, привязкой к корзине и ревизии и ценами по позициям. По нажатию «Оформить» клиент отправляет ID корзины, ревизию и ID расчёта. Если предусмотрены варианты доставки или промокод, включите их в расчёт и повышайте ревизию при их изменении. В примере способ получения фиксированный.
POST /api/carts/c42/checkout
Content-Type: application/json
{ "revision": 8, "quote_id": "q9f8a" }
Разместите страницу и API на одном HTTPS-origin. При входе через cookie-сессию включите CSRF-защиту изменяющих запросов. При повторе запроса сохраняйте те же ревизию и ID расчёта.
Проверяем цены и остатки в транзакции
Схема рассчитана на БД с блокировками строк, например MySQL с InnoDB. Все операции, меняющие корзину, начинают с блокировки её строки. Изменения цен и остатков записываются в те же товарные строки, которые блокирует оформление.
Найдите принадлежащую пользователю корзину и заблокируйте её строку через
SELECT … FOR UPDATEвнутри транзакции.Сначала найдите заказ по паре
(cart_id, cart_revision). Если заказ уже существует и ID расчёта совпадает, верните его. Для той же ревизии с другим ID расчёта верните конфликт. Сделайте это до проверки срока расчёта и актуальности ревизии.Проверьте, что корзина активна и непуста, ревизия актуальна, а расчёт относится к ней и ещё действует. Заблокируйте товарные варианты в одном порядке, например по ID. Сверьте доступный остаток с количеством в корзине и текущую цену каждой позиции с расчётом, который видел покупатель.
Если товар закончился, снят с продажи или изменился в цене, завершите операцию без записи заказа и списания. Верните
409с причиной. Клиент заново загружает корзину и расчёт, а покупатель подтверждает новую сумму.Если проверки прошли, уменьшите доступный остаток, создайте заказ со снимком позиций и очистите корзину, увеличив её ревизию. Зафиксируйте все изменения одной транзакцией. Уведомление отправляйте после фиксации, используя ID созданного заказа.
Ограничение UNIQUE(cart_id, cart_revision) закрепляет правило «одна ревизия — один заказ» в БД. Сохраняйте строку корзины и ссылку на неё, пока нужны повторы. Придерживайтесь общего порядка блокировок и предусмотрите ограниченный повтор всей транзакции при взаимной блокировке.
Такой заказ фиксирует покупку с самовывозом. Если добавите онлайн-оплату, храните её состояние отдельно и меняйте его после серверного подтверждения платёжного события.
Обрабатываем повторное нажатие и потерю связи
Пока идёт запрос, отключите кнопку «Оформить». Если ответ потерялся или сервер вернул временную ошибку, предложите повторить тот же запрос. Сервер может вернуть 201 при создании и 200 при повторе с тем же ID заказа. Если сессия истекла, сначала восстановите вход.
Если Mini App закрыли посреди запроса, покажите недавние заказы из серверного списка. Для перехода из сообщения с номером заказа используйте прямую ссылку с параметром startapp.
Собираем рабочее ядро корзины на Laravel
Для примера возьмём новый Laravel-проект с MySQL/InnoDB или PostgreSQL и одним магазином. Подключите вход по initData из руководства об авторизации: он сохраняет в сессии mini_user_id и mini_expires_at. Ниже одна активная корзина на Telegram ID, самовывоз и цены в копейках. Сохранение корзины, расчёт и оформление используют одну БД.
Создайте миграцию php artisan make:migration create_shop_tables. Следующий код — импорты и тело её метода up(). Имена таблиц рассчитаны на учебный проект: перед переносом в существующий магазин согласуйте их с его моделями. Товары не удаляются физически, а снимаются с продажи через active.
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
Schema::create('variants', function (Blueprint $t) {
$t->id(); $t->string('title'); $t->unsignedInteger('price_minor');
$t->unsignedInteger('stock'); $t->boolean('active')->default(true);
});
Schema::create('carts', function (Blueprint $t) {
$t->id(); $t->unsignedBigInteger('telegram_user_id')->unique();
$t->unsignedInteger('revision')->default(1);
});
Schema::create('cart_items', function (Blueprint $t) {
$t->foreignId('cart_id')->constrained('carts');
$t->foreignId('variant_id')->constrained('variants');
$t->unsignedInteger('quantity'); $t->primary(['cart_id', 'variant_id']);
});
Schema::create('cart_quotes', function (Blueprint $t) {
$t->string('id', 32)->primary(); $t->foreignId('cart_id')->constrained('carts');
$t->unsignedInteger('revision'); $t->json('items'); $t->unsignedBigInteger('expires_at');
});
Schema::create('orders', function (Blueprint $t) {
$t->id(); $t->string('public_id', 24)->unique(); $t->unsignedBigInteger('telegram_user_id');
$t->foreignId('cart_id')->constrained('carts'); $t->unsignedInteger('cart_revision');
$t->string('quote_id', 32); $t->unsignedBigInteger('total_minor'); $t->string('status');
$t->unique(['cart_id', 'cart_revision']);
});
Schema::create('order_items', function (Blueprint $t) {
$t->foreignId('order_id')->constrained('orders');
$t->foreignId('variant_id')->constrained('variants');
$t->string('title'); $t->unsignedInteger('price_minor'); $t->unsignedInteger('quantity');
$t->primary(['order_id', 'variant_id']);
});
После php artisan migrate добавьте через php artisan tinker тестовый товар: DB::table('variants')->insert(['title' => 'Зелёный чай', 'price_minor' => 45000, 'stock' => 2, 'active' => true]);. Запомните его ID. Сервис ниже возвращает состав корзины и проверяет заказ внутри транзакции. Даже если ошибка обнаружится на второй позиции, списание первой откатится.
<?php
namespace App\Services;
use Illuminate\Support\Facades\DB;
final class ShopCart
{
private function lockedCart(int $owner): object
{
DB::table('carts')->insertOrIgnore([
'telegram_user_id' => $owner, 'revision' => 1,
]);
return DB::table('carts')->where('telegram_user_id', $owner)
->lockForUpdate()->first();
}
private function lines(int $cartId): array
{
return DB::table('cart_items as i')->join('variants as v', 'v.id', '=', 'i.variant_id')
->where('i.cart_id', $cartId)->orderBy('v.id')
->get(['v.id', 'v.title', 'v.price_minor', 'i.quantity'])
->map(fn ($r) => [
'variant_id' => (int) $r->id, 'title' => $r->title,
'price_minor' => (int) $r->price_minor, 'quantity' => (int) $r->quantity,
])->all();
}
public function read(int $owner): array
{
return DB::transaction(function () use ($owner) {
$cart = $this->lockedCart($owner);
return ['revision' => (int) $cart->revision, 'items' => $this->lines($cart->id)];
}, 3);
}
public function quantity(int $owner, int $variantId, int $quantity, int $revision): array
{
return DB::transaction(function () use ($owner, $variantId, $quantity, $revision) {
$cart = $this->lockedCart($owner);
abort_unless((int) $cart->revision === $revision, 409, 'Корзина изменилась');
if ($quantity > 0) {
$variant = DB::table('variants')->where('id', $variantId)->lockForUpdate()->first();
abort_unless($variant && $variant->active, 409, 'Товар недоступен');
}
$query = DB::table('cart_items')->where('cart_id', $cart->id)->where('variant_id', $variantId);
$old = (int) ($query->value('quantity') ?? 0);
if ($old !== $quantity) {
if ($quantity === 0) {
$query->delete();
} else {
DB::table('cart_items')->updateOrInsert(
['cart_id' => $cart->id, 'variant_id' => $variantId], ['quantity' => $quantity]
);
}
DB::table('carts')->where('id', $cart->id)->increment('revision');
}
return ['revision' => $revision + (int) ($old !== $quantity), 'items' => $this->lines($cart->id)];
}, 3);
}
public function quote(int $owner, int $revision): array
{
return DB::transaction(function () use ($owner, $revision) {
$cart = $this->lockedCart($owner);
abort_unless((int) $cart->revision === $revision, 409, 'Корзина изменилась');
$items = $this->lines($cart->id);
abort_if($items === [], 409, 'Корзина пуста');
$id = bin2hex(random_bytes(16));
$total = array_sum(array_map(fn ($i) => $i['price_minor'] * $i['quantity'], $items));
$expires = time() + 300;
DB::table('cart_quotes')->insert([
'id' => $id, 'cart_id' => $cart->id, 'revision' => $revision,
'items' => json_encode($items, JSON_THROW_ON_ERROR), 'expires_at' => $expires,
]);
return ['quote_id' => $id, 'revision' => $revision, 'items' => $items,
'total_minor' => $total, 'expires_at' => $expires];
}, 3);
}
public function checkout(int $owner, int $revision, string $quoteId): array
{
return DB::transaction(function () use ($owner, $revision, $quoteId) {
$cart = $this->lockedCart($owner);
$existing = DB::table('orders')->where('cart_id', $cart->id)
->where('cart_revision', $revision)->first();
if ($existing) {
abort_unless($existing->quote_id === $quoteId, 409, 'Другой расчёт');
return ['public_id' => $existing->public_id, 'created' => false];
}
abort_unless((int) $cart->revision === $revision, 409, 'Корзина изменилась');
$quote = DB::table('cart_quotes')->where('id', $quoteId)->where('cart_id', $cart->id)
->where('revision', $revision)->first();
abort_unless($quote && (int) $quote->expires_at > time(), 409, 'Обновите расчёт');
$items = json_decode($quote->items, true, 32, JSON_THROW_ON_ERROR);
$current = DB::table('cart_items')->where('cart_id', $cart->id)
->orderBy('variant_id')->get();
abort_unless(count($items) > 0 && count($items) === $current->count(), 409);
$total = 0;
foreach ($items as $index => $item) {
$line = $current[$index];
abort_unless((int) $line->variant_id === $item['variant_id']
&& (int) $line->quantity === $item['quantity'], 409, 'Состав изменился');
$variant = DB::table('variants')->where('id', $item['variant_id'])->lockForUpdate()->first();
abort_unless($variant && $variant->active && (int) $variant->stock >= $item['quantity'],
409, 'Недостаточно товара');
abort_unless((int) $variant->price_minor === $item['price_minor'], 409, 'Цена изменилась');
DB::table('variants')->where('id', $variant->id)->decrement('stock', $item['quantity']);
$total += $item['price_minor'] * $item['quantity'];
}
$publicId = bin2hex(random_bytes(12));
$orderId = DB::table('orders')->insertGetId([
'public_id' => $publicId, 'telegram_user_id' => $owner,
'cart_id' => $cart->id, 'cart_revision' => $revision, 'quote_id' => $quoteId,
'total_minor' => $total, 'status' => 'created',
]);
foreach ($items as $item) {
DB::table('order_items')->insert(['order_id' => $orderId] + $item);
}
DB::table('cart_items')->where('cart_id', $cart->id)->delete();
DB::table('carts')->where('id', $cart->id)->increment('revision');
return ['public_id' => $publicId, 'created' => true];
}, 3);
}
}
Добавьте маршруты в routes/web.php, где уже действуют сессии и CSRF-защита. В этом варианте URL начинается с /mini/cart, а корзина выбирается по сессии; передавать её ID из браузера не требуется. На 409 клиент заново вызывает GET и показывает актуальный состав. Операции изменения количества посылайте последовательно, с ревизией последнего ответа.
use App\Services\ShopCart;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
$cartOwner = static function (Request $request): int {
abort_unless(is_int($request->session()->get('mini_user_id'))
&& (int) $request->session()->get('mini_expires_at', 0) > time(), 401);
return $request->session()->get('mini_user_id');
};
Route::prefix('mini/cart')->middleware('throttle:60,1')->group(function () use ($cartOwner) {
Route::get('/', fn (Request $r, ShopCart $cart) => response()->json(
$cart->read($cartOwner($r))
)->header('Cache-Control', 'private, no-store'));
Route::put('/items/{variant}', function (Request $r, ShopCart $cart, string $variant) use ($cartOwner) {
$owner = $cartOwner($r);
$v = $r->validate(['quantity' => 'required|integer|min:0|max:99',
'revision' => 'required|integer|min:1']);
return response()->json($cart->quantity($owner,
(int) $variant, (int) $v['quantity'], (int) $v['revision']))->header('Cache-Control', 'no-store');
})->whereNumber('variant');
Route::post('/quote', function (Request $r, ShopCart $cart) use ($cartOwner) {
$owner = $cartOwner($r);
$v = $r->validate(['revision' => 'required|integer|min:1']);
return response()->json($cart->quote($owner, (int) $v['revision']))->header('Cache-Control', 'no-store');
});
Route::post('/checkout', function (Request $r, ShopCart $cart) use ($cartOwner) {
$owner = $cartOwner($r);
$v = $r->validate(['revision' => 'required|integer|min:1',
'quote_id' => ['required', 'regex:/\A[a-f0-9]{32}\z/']]);
$result = $cart->checkout($owner, (int) $v['revision'], $v['quote_id']);
return response()->json($result, $result['created'] ? 201 : 200)->header('Cache-Control', 'no-store');
});
});
После успешного loginMiniApp() выполните последовательность ниже на странице приложения. Метатег CSRF должен содержать новый токен, возвращённый входом. Подставьте ID добавленного товара вместо 1. В интерфейсе между расчётом и оформлением покажите покупателю offer.items и offer.total_minor; здесь остановка перед последней командой позволяет проверить результат в консоли.
async function cartRequest(path, method = 'GET', body) {
const response = await fetch('/mini/cart' + path, {
method, credentials: 'same-origin',
headers: {'Accept': 'application/json', 'Content-Type': 'application/json',
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content},
...(body === undefined ? {} : {body: JSON.stringify(body)})
});
if (!response.ok) throw new Error('Запрос корзины: ' + response.status);
return response.json();
}
const initial = await cartRequest('');
const changed = await cartRequest('/items/1', 'PUT', {quantity: 1, revision: initial.revision});
const offer = await cartRequest('/quote', 'POST', {revision: changed.revision});
console.log(offer); // Покажите эти цены покупателю до следующего действия.
const checkoutBody = {revision: offer.revision, quote_id: offer.quote_id};
// Выполнить после подтверждения покупателем:
const order = await cartRequest('/checkout', 'POST', checkoutBody);
const repeated = await cartRequest('/checkout', 'POST', checkoutBody);
console.assert(order.public_id === repeated.public_id);
В БД должен появиться один заказ, а запас уменьшиться на единицу. Повтор с прежним расчётом вернёт тот же заказ даже после истечения срока расчёта. Попробуйте изменить цену до оформления: получите 409, заказ не появится. Уведомление о заказе подключайте через отдельную исходящую очередь; HTTP-вызова Telegram внутри транзакции здесь нет. Для восстановления после закрытия Mini App добавьте список своих заказов с тем же ограничением по владельцу.
Проверяем сценарии магазина
Закройте Mini App с двумя позициями и откройте снова с того же аккаунта. Корзина загрузится с сервера. С другого аккаунта откроется его собственная корзина.
Измените цену или остаток между расчётом и нажатием «Оформить». Сервер вернёт конфликт, остатки и число заказов останутся прежними.
Отправьте два одинаковых запроса параллельно и повторите один после имитации таймаута. Все успешные ответы содержат один ID заказа, остаток уменьшится один раз.
Два покупателя оформляют последнюю пачку одновременно. Один заказ сохраняется, второй покупатель получает сообщение о недостаточном остатке.