feat: 支持登录、个人信息存储

2026-04-05 13:37:58 +08:00
parent e438f6fce4
commit b732e4d8f8
23 changed files with 3572 additions and 144 deletions
--- a/QUICK_REFERENCE.md
+++ b/QUICK_REFERENCE.md
@@ -0,0 +1,196 @@
+# QUICK REFERENCE - Game Points/Score System
+
+## 🎮 What is the "Currency"?
+**LIVES** - Not traditional points/coins, but a renewable "health" resource.
+
+## 📊 Lives Management
+```
+Storage Key:        "game_lives" (localStorage)
+Default:            10
+Min Value:          0
+Max Value:          ∞ (no limit)
+
+Methods:
+├─ getLives()           → Returns current lives
+├─ setLives(n)          → Set specific value
+├─ consumeLife()        → Deduct 1 life
+├─ addLife()            → Add 1 life
+├─ hasLives()           → Check if > 0
+└─ resetLives()         → Reset to 10
+```
+
+## 🎯 How Lives Are Spent
+| Action | Cost | Where |
+|--------|------|-------|
+| Unlock Clue 2 | 1 Life | PageLevel → onUnlockClue(2) |
+| Unlock Clue 3 | 1 Life | PageLevel → onUnlockClue(3) |
+| **TOTAL PER LEVEL** | **0-2 Lives** | Depends on player choice |
+
+## 🏆 How Lives Are Earned
+| Action | Reward | Where |
+|--------|--------|-------|
+| Complete a Level | +1 Life | PageLevel → showSuccess() |
+| Wrong Answer | 0 | No penalty |
+| Time Up | 0 | No penalty |
+
+## 📈 Level Progression
+```
+Storage Key:     "game_progress" (localStorage)
+Structure:
+{
+  currentLevelIndex: number,      // 0-based, current level
+  maxUnlockedLevelIndex: number   // 0-based, highest reached
+}
+
+Default:         { currentLevelIndex: 0, maxUnlockedLevelIndex: 0 }
+```
+
+### Progression Rules:
+1. **Level 1 always unlocked** - Start here
+2. **Beat Level N** → currentLevel becomes N+1
+3. **Beat Level N** → maxUnlocked becomes max(maxUnlocked, N)
+4. **Can replay earlier levels** - But always progress forward
+
+### Methods:
+```
+getCurrentLevelIndex()          → Get current (0-based)
+setCurrentLevelIndex(n)         → Jump to level
+getMaxUnlockedLevelIndex()      → Get highest reached
+isLevelUnlocked(n)              → Check if playable
+onLevelCompleted(n)             → Save win + progress
+resetProgress()                 → Reset to level 1
+```
+
+## 🎨 Level Data (from API)
+**Endpoint:** `https://ilookai.cn/api/v1/wechat-game/levels`
+
+```typescript
+ApiLevelData {
+    id: string,          // UUID
+    level: number,       // Level number (1-based display)
+    imageUrl: string,    // Main puzzle image
+    hint1: string,       // Free clue
+    hint2: string,       // Costs 1 life
+    hint3: string,       // Costs 1 life
+    answer: string,      // The answer (case-sensitive, trimmed)
+    sortOrder: number    // Sort order
+}
+```
+
+## ⏱️ Gameplay Mechanics
+
+### Time Limit
+- **Duration:** 60 seconds per level
+- **On Timeout:** Play fail sound, game doesn't end
+- **After Timeout:** Can still submit answers
+
+### Input System
+- **Type:** Single text box (not per-character)
+- **Processing:** Trimmed, case-sensitive comparison
+- **Max Length:** Based on answer length
+
+### Win Condition
+```
+input.trim() === answer
+↓
+Play success sound → Stop timer → Award +1 life 
+→ Show PassModal → Save progress
+```
+
+### Lose Condition
+```
+input.trim() !== answer
+↓
+Play fail sound → Vibrate → Show toast
+→ Lives unchanged → Can retry
+```
+
+## 🎁 Rewards & Penalties
+| Event | Lives Change | Other Effects |
+|-------|--------------|---------------|
+| Correct Answer | +1 | Play success sound, show modal |
+| Wrong Answer | 0 | Play fail sound, vibrate, toast |
+| Unlock Clue | -1 | Show clue content |
+| Time Up | 0 | Play fail sound, countdown stops |
+| Level Complete | Already +1ed | Save progress, move to next |
+
+## 🔄 Economy Balance
+```
+Starting Inventory:    10 lives
+
+Without Hints:         +1 life/level   → Infinite
+With 1 Hint/Level:     0 lives/level   → Stable
+With 2 Hints/Level:    -1 life/level   → Finite (10-20 levels)
+
+Net Formula:           newLives = oldLives - hintsUsed + 1 (on win)
+```
+
+## 📡 API Integration
+```
+LevelDataManager {
+    API_URL: "https://ilookai.cn/api/v1/wechat-game/levels"
+    TIMEOUT: 8000ms
+    RETRY_COUNT: 2
+    
+    Calls:
+    ├─ initialize()          → Load all level metadata + image for level 1
+    ├─ ensureLevelReady(n)   → Load specific level image
+    ├─ preloadNextLevel(n)   → Silently preload level n+1
+    └─ getLevelConfig(n)     → Get cached level data
+}
+```
+
+## 📁 Storage Schema
+```
+localStorage: {
+    "game_lives": "10",
+    "game_progress": "{\"currentLevelIndex\":0,\"maxUnlockedLevelIndex\":0}"
+}
+```
+
+## 🌐 WeChat Integration
+```
+Features Used:
+├─ WxSDK.initShare()       → Enable sharing
+├─ WxSDK.shareAppMessage() → Share to friend with level query param
+├─ WxSDK.vibrateLong()     → 400ms vibration on error
+└─ WxSDK.vibrateShort()    → 15ms vibration on click
+```
+
+## 🔑 Key Files
+```
+StorageManager.ts         → Lives & progress persistence
+LevelDataManager.ts       → API & image loading
+PageLevel.ts              → Main game logic
+PageLoading.ts            → App initialization
+PassModal.ts              → Victory screen
+ViewManager.ts            → Page navigation
+WxSDK.ts                  → WeChat APIs
+```
+
+## ⚙️ Constants
+```
+DEFAULT_LIVES               10
+MIN_LIVES                   0
+LEVEL_TIME_LIMIT            60 seconds
+LIFE_PER_HINT               1
+LIFE_PER_WIN                1
+API_TIMEOUT                 8000ms
+API_RETRY_COUNT             2
+
+Game Title                  "写英语" (Write English)
+Share Query Format          "level=<levelIndex>"
+```
+
+## 🚨 No Implementation For:
+- User Authentication (wx.login)
+- Backend Progress Save
+- Ads/Monetization
+- Leaderboards
+- Analytics
+- Premium Life Refills
+- Difficulty Levels
+
+---
+
+**In Summary:** Players earn/spend LIVES by unlocking clues (-1 each) or winning levels (+1 each). Progress is saved locally with streak tracking. The economy encourages players to solve without hints to maximize lives.