BoxTier Basketball Receipt

RankBall

一款 React + Vite MVP，可将朋友间的篮球比赛登记为今日对局，并在赛后经双方球队确认，记录战绩和段位。

运行

npm install
npm run dev

即使没有 .env，也会以 localStorage 演示模式运行。

Supabase

已配置 Vite 读取 Vercel/Next 风格的 NEXT_PUBLIC_* 环境变量。

NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=...

要使用 Supabase 持久化存储，请按顺序应用 supabase/migrations。Supabase 环境配置完成后，如果远程加载失败，应用不会回退到 localStorage 演示状态，而是保留远程 shell/error 状态。

Supabase CLI migration

Production DB migration 尽可能通过 Supabase CLI 应用。

supabase --version
$env:SUPABASE_ACCESS_TOKEN="..."
$env:SUPABASE_DB_PASSWORD="..."
supabase link --project-ref olzxextphxpniwiiwwda --password $env:SUPABASE_DB_PASSWORD
supabase db push --linked --dry-run
supabase db push --linked

如果设置了 DATABASE_URL，无需 link 即可应用。

supabase db push --db-url "$env:DATABASE_URL" --dry-run
supabase db push --db-url "$env:DATABASE_URL"

应用到 Production 后，检查 schema health。

Invoke-RestMethod -Method Post -Uri "https://boxtier.kr/api/system/schema-health" -Headers @{ Authorization = "Bearer $env:CRON_SECRET" }

部署前验证可通过一条命令执行。

npm run verify:release -- --confirm-production=olzxextphxpniwiiwwda

verify:release 会在 production build 后，基于远程 Supabase/Auth 执行完整 backend simulation 和 schema health 检查。如果没有与 production ref 完全一致的 --confirm-production=<project-ref> CLI flag，则会在调用 API/Auth 前停止。需要 SUPABASE_SERVICE_ROLE_KEY、测试 Auth 环境变量和 CRON_SECRET。如果退出代码不为 0，请勿部署。

simulation 会在运行前将 environment、直接 Supabase project ref、远程 API host/ref 输出到 stderr。每个 process 的完整 flow 重复上限为 1 次；仅在 cleanup 失败时，自动重试最多 1 次。外部 runner 即使重新运行独立 process，也必须将调用次数限制为 1 次。--safety-check-only 只验证 target guard，不会调用 DB/API。

仅供测试的 Supabase 需要同时设置 test URL、publishable key 和 service-role key。使用远程 test API 时，还要通过 --remote-project-ref=<test-ref> 指定与实际部署目标相同的 ref。如果直接 ref 与远程 ref 不同，则不会运行。

远程 DB 上请勿使用 supabase db reset --linked、DROP TABLE、TRUNCATE 或批量 DELETE。

环境变量

名称	位置	用途
VITE_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_URL	浏览器/服务器	Supabase project URL
VITE_SUPABASE_PUBLISHABLE_KEY / NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY / VITE_SUPABASE_ANON_KEY	浏览器	Supabase anon/publishable key
SUPABASE_SERVICE_ROLE_KEY	仅限服务器/脚本	server action、seed、simulation
VITE_ENABLE_SERVER_ACTIONS	浏览器	启用 server action
VITE_DEMO_LOGIN	浏览器	允许在 localhost 使用测试登录 UI
RANKBALL_SEED_REAL_TEST_AUTH / RANKBALL_SEED_AUTH_ONLY	脚本	将测试账号创建为 Supabase Auth user，并关联到现有 profile
RANKBALL_TEST_PASSWORD / VITE_TEST_AUTH_PASSWORD	脚本/浏览器	测试账号 password Auth 使用的密码
RANKBALL_TEST_AUTH_EMAIL_DOMAIN / VITE_TEST_AUTH_EMAIL_DOMAIN	脚本/浏览器	测试账号 email domain。默认值为 rankball.test
VITE_ASSET_BASE_URL / VITE_PUBLIC_ASSET_BASE_URL	浏览器	远程 asset base URL
VITE_NAVER_MAP_CLIENT_ID / VITE_NAVER_MAP_NCP_KEY_ID	浏览器/服务器备用	Naver map/geocode client id
NAVER_MAP_CLIENT_SECRET / NAVER_MAP_NCP_KEY / NAVER_MAP_NCP_CLIENT_SECRET	仅限服务器	Naver geocode 备用 secret
DISCORD_CLIENT_ID / DISCORD_CLIENT_SECRET / DISCORD_REDIRECT_URI	仅限服务器	Discord OAuth
DISCORD_BOT_TOKEN / DISCORD_GUILD_ID / DISCORD_GUILD_IDS	仅限服务器	Discord DM worker
DISCORD_PUBLIC_KEY	仅限服务器	Discord interaction signature 验证
DISCORD_CHAT_BRIDGE_SECRET / DISCORD_CHAT_BRIDGE_URL	bridge worker	将 Discord 房间聊天转发到 Web API
DISCORD_CHAT_BRIDGE_REQUEST_TIMEOUT_MS / DISCORD_CHAT_BRIDGE_MAX_DELIVERY_ATTEMPTS	bridge worker	转发 timeout 和重试次数。默认值为 10000、4
CRON_SECRET	仅限服务器/脚本	worker、maintenance、schema-health
SUPABASE_ACCESS_TOKEN	仅限 CLI	Supabase Management API 身份验证
SUPABASE_DB_PASSWORD	仅限 CLI	supabase link、supabase db push --linked 使用的远程 DB 密码
SUPABASE_PROJECT_ID	仅限 CLI/CI	Supabase project ref。当前 production ref：olzxextphxpniwiiwwda
DATABASE_URL	仅限 CLI/服务器	supabase db push --db-url 或直接连接 Postgres
RANKBALL_SIM_BASE_URL / RANKBALL_SIM_SECRET / RANKBALL_SIM_TIMEOUT_MS / RANKBALL_SIM_CLEANUP_TIMEOUT_MS	脚本	backend simulation
RANKBALL_SIM_REMOTE_PROJECT_REF	脚本	远程 test API 使用的 Supabase project ref。优先使用 --remote-project-ref
RANKBALL_SIM_REPEAT / RANKBALL_SIM_MAX_RETRIES	脚本	完整 flow 重复上限 1，cleanup 重试上限 1

Discord 방 채팅 bridge

상시 실행 환경에서 아래 명령을 실행합니다. Gateway worker는 heartbeat ACK 누락 시 재연결하고, 가능한 세션은 resume하며, 웹 API의 timeout·429·5xx를 제한 횟수만큼 재시도합니다.

npm run discord:room-chat-bridge

운영에서는 DISCORD_CHAT_BRIDGE_SECRET을 별도로 설정합니다. CRON_SECRET fallback은 기존 배포 호환용입니다.

Vercel

Framework preset은 Vite, build command는 npm run build, output directory는 dist입니다.