用 WebViewGold 发布的 Web 应用专用 CLAUDE.md 模板

# CLAUDE.md

## Project
- Next.js (App Router), TypeScript, Tailwind. Supabase for auth and Postgres. Stripe for web checkout.
- Deployed on Vercel at https://app.example.com. Every production deploy is live in the native apps immediately.
- Commands: npm run dev, npm run lint, npm run test, npm run build. Run lint and tests before reporting done.

## Native app context (read this first)
- This web app is also published as iOS and Android apps built with WebViewGold, a native WebView wrapper.
  The apps load https://app.example.com in a WKWebView / Android WebView. There is no separate mobile codebase.
- The apps send a custom user agent that contains the token WebViewGoldApp.
  Use isNativeApp() from src/lib/native.ts to branch. Never duplicate the user agent check.
- Native features are triggered by navigating to a URL scheme: window.location.href = "scheme://...".
  Results come back as injected global JavaScript variables or as calls to global functions.
  Full reference: https://www.webviewgold.com/llms-full.txt. Read the relevant section before adding a feature.
- Only call a scheme when isNativeApp() is true. In browsers use the web equivalent or hide the control.
- On iOS, several scheme calls in one script run must be combined: multiapicall://getonesignalplayerid,getappversion

## WebViewGold bridge used in this project
- Push permission: registerpush:// (shows the system prompt). Status: checkNativePushPermissions:// then read
  window.nativePushEnabled after a short delay. System settings: settingsapp://
- Push user ID: getonesignalplayerid:// then read window.onesignalplayerid; store it on the user profile.
- Local notification: sendlocalpushmsg://push.send?s=SECONDS=msg!MESSAGE&!#TITLE&!#URL
  Cancel all: sendlocalpushmsg://push.send.cancel
- Biometrics: bioauth:// then the wrapper calls window.onBioAuthSuccess(), window.onBioAuthFailure(code, message)
  or window.onBioAuthUnavailable(). Treat success as a UI gate only; the server session stays the source of truth.
- Scanner: qrcode:// opens the native scanner and loads the scanned URL in the app.
  barcodescanner:// then read window.barcodescanresult.
- Share sheet: shareapp://message?=TEXT&url=URL (URL-encode both values).
- Haptics: lighthaptic://, heavyhaptic://, successhaptic://, warninghaptic://, errorhaptic:// (mediumhaptic:// is iOS only).
- Downloads: savethisimage://?url=IMAGE_URL saves to the photo library; links ending in .pdf, .docx, .xlsx or .mp3
  download natively.
- Purchases: revenuecat://purchase?external_id=USER_ID&product=PRODUCT_ID. Entitlements arrive through the
  RevenueCat webhook at /api/webhooks/revenuecat and are stored in the subscriptions table.
- App version: getappversion:// then read window.versionNumber. Rating prompt: rateapp://

## Store rules (never break these)
- Apple 4.2: the app must do more than the website. Push, offline handling and the share sheet must keep working.
- Apple 4.8: a third-party login exists, so Sign in with Apple stays available and equally prominent.
- Apple 5.1.1 and Google Play: /privacy must describe real data practices; Delete account stays in settings and works.
- Apple 3.1.1 and Google Play billing: inside the native app, digital goods go through revenuecat://, never Stripe.
  Never render external payment links or web prices when isNativeApp() is true.
- Apple 2.3: no beta labels, no coming-soon screens, no placeholder content in production.
- Apple 4.0: safe-area padding on fixed bars, 44 px tap targets, no horizontal overflow at 320 px width.
- Never add Download our app banners, builder badges or cookie walls.

## Conventions
- Mobile first. Verify every UI change at 320 px, 390 px and at iPad width.
- Every data fetch has loading, empty and error states with a retry action.
- Secrets stay server-side. The client bundle must never contain a service-role key or a webhook secret.
- Routes the native apps and store listings depend on: /, /login, /privacy, /terms, /delete-account, /settings.
  Changing or removing one of them requires a note in docs/native-app.md.