# 🏰 Шашки Рояль

> Русские шашки. Играй онлайн против реальных соперников.
> Mobile-first PWA, устанавливается на Android как приложение.

[![Vite](https://img.shields.io/badge/Vite-7-646CFF?logo=vite)](https://vitejs.dev/)
[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react)](https://react.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript)](https://www.typescriptlang.org/)
[![Supabase](https://img.shields.io/badge/Supabase-Backend-3ECF8E?logo=supabase)](https://supabase.com/)
[![PWA](https://img.shields.io/badge/PWA-Ready-5A0FC8)](https://web.dev/progressive-web-apps/)

---

## ✨ Возможности

- 🎲 **Русские шашки** — все правила (обязательное взятие, мультивзятие, дамка)
- 👥 **Онлайн PvP** через 6-значный код комнаты
- ⚡ **Realtime sync** через Supabase Realtime + polling fallback
- 🔒 **Server-side анти-чит** — сервер сам пересчитывает доску, подделать невозможно
- 📱 **PWA** — устанавливается на Android/iOS
- 🤖 **Локальная игра** против другого человека на одном устройстве
- 🌍 **Русский интерфейс** (готова инфраструктура для UZ)
- 💰 **Внутриигровая экономика** (Chips, ставки — виртуальная валюта без вывода)

---

## 🚀 Quick Start

### 1. Установка

```bash
git clone <repo-url> shashki-royale
cd shashki-royale
yarn install --ignore-engines
```

> ⚠️ `--ignore-engines` нужен, если у тебя Node 20 (Capacitor хочет 22+).

### 2. Настройка Supabase

1. Создай проект на [supabase.com](https://supabase.com/) (или используй существующий)
2. Скопируй `.env.example` → `.env`:
   ```bash
   cp .env.example .env
   ```
3. Заполни `.env` своими значениями:
   ```env
   VITE_SUPABASE_URL=https://YOUR-PROJECT.supabase.co
   VITE_SUPABASE_ANON_KEY=sb_publishable_...
   ```
4. Примени SQL миграции из `supabase/migrations/` через Dashboard → SQL Editor.
   Подробнее → [supabase/README.md](./supabase/README.md)

### 3. Запуск

```bash
yarn dev        # dev сервер на http://localhost:5173
yarn build      # production build → dist/
yarn preview    # запустить production build локально
yarn typecheck  # проверка TypeScript
yarn lint       # ESLint
yarn test       # 80+ unit/integration тестов
```

---

## 📁 Структура проекта

```
shashki-royale/
├── public/                 # Статические файлы (manifest, иконки, sw.js)
│   ├── _headers            # Cloudflare Pages / Netlify HTTP headers
│   ├── _redirects          # SPA fallback
│   ├── icon/               # PWA иконки 192/512/maskable
│   ├── site.webmanifest    # PWA manifest
│   └── sw.js               # Service Worker (offline + cache)
├── src/
│   ├── game/               # 🎯 Rule engine русских шашек
│   │   ├── rules.ts            # Генерация ходов, validation
│   │   ├── applyMove.ts        # Применение хода к доске
│   │   ├── gameLogic.ts        # State machine + chain captures
│   │   ├── checkWin.ts         # Проверка выигрыша
│   │   ├── boardValidator.ts   # Sanity-валидация incoming board
│   │   └── initialBoard.ts     # Стартовая расстановка 12/12
│   ├── services/           # 🔌 API слой
│   │   ├── gameRooms.ts        # Create/Join/Update игры
│   │   ├── profiles.ts         # Профили игроков
│   │   └── stakes.ts           # Ставки и экономика
│   ├── pages/              # 📄 Страницы (React Router)
│   │   ├── Home.tsx, Lobby.tsx, LocalGame.tsx, OnlineGame.tsx
│   │   └── auth/, ProfilePage.tsx, WalletPage.tsx
│   ├── components/         # ⚛️ UI компоненты + shadcn/ui
│   ├── hooks/              # React hooks (usePlayerId, useAudio, ...)
│   ├── lib/                # Supabase client, storage, sounds
│   └── locales/            # i18n RU
├── supabase/
│   ├── migrations/         # ⚡ SQL миграции (применять по порядку)
│   └── README.md           # Инструкция по применению
├── e2e/                    # Playwright тесты
├── vercel.json             # Конфиг Vercel
├── netlify.toml            # Конфиг Netlify
├── wrangler.toml           # Конфиг Cloudflare Pages
└── .env.example            # Шаблон env-переменных
```

---

## 🔧 Backend (Supabase)

Используется **Supabase** для:
- Хранения игр (`games`, `moves`)
- Realtime sync ходов
- RLS для безопасности (только участник комнаты может ходить)
- RPC функции для **server-side анти-чит**:
  - `apply_move_v2` — пересчитывает доску из присланных steps[] (защита от подделки)
  - `apply_move_safe` — CAS защита от stale moves
  - `heartbeat_game` — детект выхода соперника
  - `cleanup_stale_rooms` — авто-очистка зависших комнат

📖 Подробнее: [supabase/README.md](./supabase/README.md)

---

## 🌐 Деплой

Проект **не привязан к Hercules** и работает на любой статической платформе.

### Cloudflare Pages

1. Зайди в [Cloudflare Pages](https://pages.cloudflare.com/)
2. Connect to Git → выбери репозиторий
3. **Build settings:**
   - Framework preset: `Vite`
   - Build command: `yarn build`
   - Build output directory: `dist`
   - Node version: `20`
4. **Environment variables:**
   - `VITE_SUPABASE_URL`
   - `VITE_SUPABASE_ANON_KEY`
5. Deploy.

(SPA fallback и headers уже настроены через `public/_redirects` и `public/_headers`.)

### Vercel

1. Зайди в [Vercel Dashboard](https://vercel.com/) → Import Project
2. Framework: Vite (определится автоматически)
3. Env variables: те же два
4. Deploy.

(Конфиг `vercel.json` уже в репозитории.)

### Netlify

1. Зайди в [Netlify](https://app.netlify.com/) → New site from Git
2. Framework: автоопределение
3. Env variables: те же два
4. Deploy.

(Конфиг `netlify.toml` уже в репозитории.)

### Локальный preview production-сборки

```bash
yarn build
yarn preview
# http://localhost:4173
```

---

## 📱 Установка как PWA на Android

1. Открой задеплоенный сайт в **Chrome** на Android
2. Меню (⋮) → **Установить приложение**
3. Иконка появится на главном экране
4. Открывается в полноэкранном режиме

### APK через PWABuilder

1. Зайди на [pwabuilder.com](https://www.pwabuilder.com/)
2. Введи URL задеплоенного сайта
3. Package for stores → Android → Download
4. Готово — APK для Google Play

---

## 🔒 Безопасность

- ✅ `service_role` ключ НЕ должен попадать в клиент. Используй только `anon` ключ.
- ✅ Строгие RLS policies — только участник комнаты может ходить
- ✅ Серверная валидация хода через `apply_move_v2` RPC
- ✅ `audit_logs` фиксирует все подозрительные события
- ✅ Атомарный join комнаты (нет TOCTOU race)
- ✅ CAS защита `move_number` от stale UPDATE
- ✅ Sanity-валидация incoming board на клиенте

📖 Полный security аудит: [PRODUCTION_AUDIT_REPORT.md](./PRODUCTION_AUDIT_REPORT.md)

---

## 🧪 Тесты

```bash
yarn test          # 80+ unit/integration тестов
yarn test:watch    # watch режим
yarn e2e           # Playwright (требует запущенный dev server)
```

**Покрытие:**
- Rule engine: начальная расстановка, обычные ходы, обязательное взятие, мультивзятие, дамка, промоция, win conditions
- Services: extractRoomCode, MoveStep contract
- Auth: signUp/signIn validation
- Board validator: sanity + plausible transitions

---

## 🛠 Скрипты

| Скрипт | Что делает |
|---|---|
| `yarn dev` | Dev сервер на 5173 с HMR |
| `yarn build` | TypeScript check + production build |
| `yarn preview` | Запустить production build |
| `yarn typecheck` | Только TypeScript check |
| `yarn lint` | ESLint |
| `yarn test` | Vitest unit tests |
| `yarn e2e` | Playwright E2E |
| `yarn prettier-fix` | Форматирование кода |

---

## 📜 Лицензия

MIT — см. [LICENSE](./LICENSE)

---

## 🤝 Contributing

PR welcome. Прежде чем коммитить:
```bash
yarn typecheck && yarn lint && yarn test
```

Все три должны быть зелёными.

---

**Made with 🎲 for the love of Russian checkers**
