# Triển khai VENO SDK

## Bản triển khai hiện tại

| Thành phần | Vị trí |
| --- | --- |
| Website / SDK / game mẫu | `/home/venogame.com/sdk` |
| Laravel Admin | `/home/venogame.com/.veno-sdk-admin` |
| Biến môi trường | `/home/venogame.com/.veno-sdk-admin/.env` (0600) |
| PHP CLI đúng phiên bản | `/usr/local/lsws/lsphp83/bin/php` |
| Database | `veno_sdk`, MariaDB 10.11 |
| Virtual host | `/usr/local/lsws/conf/vhosts/sdk.venogame.com/vhost.conf` |
| Cron | `/etc/cron.d/veno-sdk` |
| Bản sao trước triển khai | `/home/venogame.com/.veno-sdk-backups/` |
| Video và backup DB | Laravel `storage/app/private/` |
| Release game bất biến | `/home/venogame.com/.veno-sdk-game-releases/` |

Domain dùng chứng chỉ HTTPS sẵn có. Không thay PHP mặc định của hệ thống và không đổi cấu hình các game hiện hữu. SDK, config, registry và trang tài liệu là file tĩnh. Chỉ `/admin`, `/api`, `/livewire-*` và trang staging cần PHP.

## Đăng nhập

Mở `/admin`, dùng tài khoản riêng đã bàn giao. Lần đầu phải thiết lập ứng dụng xác thực TOTP và lưu recovery codes. Thay mật khẩu trong trang hồ sơ. Tạo editor, translator, viewer trong Control Center → Người dùng. Toàn bộ tài khoản Admin yêu cầu TOTP.

API token được hiển thị một lần, lưu bằng SHA-256, hết hạn 90 ngày; chọn phạm vi tối thiểu cho từng máy. Token video:work không thể sửa game. Mật khẩu dùng Argon2id. HTTP API yêu cầu HTTPS; giới hạn 120 request/phút/token. Mật khẩu sai 5 lần bị khóa 15 phút.

## Cấu hình

Control Center → Remote config: chọn tầng default, game hoặc target, lưu nháp, xem nội dung cũ/mới, nhập PUBLISH và xuất bản hoặc hẹn giờ. Dữ liệu được kiểm tra bằng cùng JSON Schema với CLI. File tạm được đổi tên nguyên tử; URL công khai được tải lại để so SHA-256. Rollback nạp một revision cũ vào bản nháp để xuất bản thành revision mới.

Địa chỉ config hiện tại là `https://sdk.venogame.com/config/v1/`. Đặc tả ban đầu dùng `config.venogame.com`; chưa tạo DNS cho domain đó. Runtime cho phép truyền `configBase` khi cần tách CDN. Admin nằm cùng domain tại `/admin`, không yêu cầu `admin.venogame.com`.

## Phát hành game bằng CLI

```powershell
$env:VENO_API_URL = 'https://sdk.venogame.com/api/v1'
$env:VENO_API_TOKEN = '<token có games:write, builds:write>'
npm run veno -- build --root=examples/tiles --target=web
npm run veno -- deploy --root=examples/tiles --env=prod
npm run veno -- deploy --root=examples/tiles --rollback=1.0.0
```

API kiểm tra ZIP, đường dẫn, đuôi file, dung lượng giải nén; từ chối PHP, traversal và tệp ngoài allowlist. Bản build lưu ngoài webroot, activate bằng symlink. Mỗi lần deploy có lịch sử. Game được phát hành dưới `/games/<id>/` trên domain SDK; ánh xạ subdomain game sản xuất là bước cấu hình hosting riêng.

## Quay video

Máy quay cần Node, Playwright Chromium và FFmpeg. Máy PHP nhận hàng đợi và giữ file; không render video.

```powershell
$env:VENO_API_TOKEN = '<token video:work>'
npm run veno -- record --worker
```

Heartbeat 30 giây; cron thu hồi việc mất heartbeat 5 phút; tối đa 3 lần thử. Upload từng phần 8 MB. MP4 được giữ ngoài webroot, link tải có chữ ký hết hạn 15 phút.

## Cập nhật SDK / Admin

Chạy typecheck, unit tests, build và E2E trước. Sao lưu DB trước migration. Script `scripts/package-deploy.py` tạo hai tar riêng, loại credential và runtime storage. `scripts/remote.py` đọc kết nối từ `.private/connection.json`; không nhúng mật khẩu SSH trong source. `scripts/deploy-server.sh` sao lưu web cũ, upload bundle và source Admin, chạy migration, cache và cron. Sau lần đầu, đánh dấu `.deployed` để giữ nguyên config/registry/bản dịch đã xuất từ Admin.

Môi trường khác: `cd admin && composer install --no-dev`, cấu hình `.env` theo `.env.example`, sinh APP_KEY, migrate, trỏ web server vào `public`. Schema nằm trong `admin/schemas` (được chép từ `schemas` lúc package). Giữ `APP_DEBUG=false`, chỉ public các asset và front controller.

Trình tự cài mới (PHP cần các extension MySQL, intl, mbstring, zip, bcmath và GD):

```bash
cd admin
cp .env.example .env
# Điền domain, DB và ba biến VENO_* trong .env trước khi tiếp tục.
composer install --no-dev --optimize-autoloader
php artisan key:generate
php artisan migrate --force
php artisan veno:owner admin@example.com
php artisan config:cache
php artisan view:cache
```

Lệnh tạo owner hỏi mật khẩu tương tác; không đặt mật khẩu vào lịch sử shell. Cấp quyền ghi cho user PHP vào `storage`, `bootstrap/cache`, thư mục release, config/registry/i18n công khai; thêm cron `schedule:run` mỗi phút. Chép nội dung `dist` vào `VENO_PUBLIC_PATH`, giữ front controller Laravel và các asset Filament. Script triển khai đi kèm được viết riêng cho VPS đã bàn giao; cần sửa đường dẫn và user hệ điều hành nếu dùng máy khác.

## Sao lưu và khôi phục

`veno:backup` chạy mỗi ngày 02:10 UTC, giữ 30 ngày trong `storage/app/private/backups`. Bản SQL gzip quyền 0600. Không có cấu hình kho sao lưu ngoài VPS trong thông tin bàn giao; cần thêm đích lưu ngoài máy chủ để chống mất toàn bộ VPS. Một bản snapshot bàn giao được tải về `.private/backups` trên máy phát triển.

```bash
cd /home/venogame.com/.veno-sdk-admin
/usr/local/lsws/lsphp83/bin/php artisan veno:backup
/usr/local/lsws/lsphp83/bin/php artisan veno:maintain
```

Để khôi phục, bật bảo trì Admin, giải nén SQL vào DB mục tiêu bằng thông tin từ `.env`, phục hồi `.env`/APP_KEY và thư mục private, chạy migrate/status, cache lại cấu hình, thử xuất config và tải video trước khi mở lại. Không dùng `migrate:fresh` trên production.

## Tích hợp bên ngoài còn cần tài khoản

Quảng cáo AdSense H5 cần publisher ID đã được duyệt. GA4 cần measurement ID. Consent TCF cần CMP do chủ tài khoản chọn và cấu hình trên trang game. SDK mặc định không gửi analytics và không bật quảng cáo khi thiếu consent/cấu hình. Không tự tạo tài khoản hoặc tự đồng ý điều khoản nhà cung cấp.

Adapter cổng game dùng SDK của cổng có sẵn; cần kiểm thử trong sandbox chính thức trước khi nộp. AdMob yêu cầu bridge native `Capacitor.Plugins.VenoAds`. CLI và SDK chưa được phát hành công khai lên npm.