================================================================================
                    MEMESTUDIO PROJECT EXPLORATION COMPLETE
================================================================================

PROJECT: Meme Studio - 谐音梗小游戏运营平台 (Homophone Pun Game Admin Platform)
DATE: April 6, 2026
STATUS: ✅ THOROUGHLY ANALYZED

================================================================================
                            QUICK FACTS
================================================================================

Framework:              Next.js 14.2.28 (App Router)
Backend Language:       TypeScript
Database:              MySQL + Prisma ORM v6.5.0
Authentication:        Better Auth v1.2.7 (email/password)
Session Duration:      7 days
Cloud Storage:         Tencent COS (with STS temp credentials)
UI Framework:          shadcn/ui + Tailwind CSS
State Management:      TanStack React Query
Deployment:            PM2 on Linux server (119.91.211.52)
Reverse Proxy:         Behind /studio basePath

================================================================================
                        DATABASE MODELS (7 Total)
================================================================================

1. User              - Admin/portal users (Better Auth)
2. Session           - Auth sessions (7-day expiry, Better Auth)
3. Account           - Auth accounts with password hashing
4. Verification      - Email verification tokens
5. Level             - Game levels (image, answer, 3 hints, sortOrder)
6. WxUser            - WeChat mini-program users (openid, points)
7. WxUserLevelProgress - User level completion tracking

================================================================================
                        API ENDPOINTS (14 Total)
================================================================================

AUTHENTICATION (Better Auth - Catch-all)
  • POST /api/auth/[...all]  - All auth routes

LEVELS (4 endpoints)
  • GET    /api/levels              - List all levels
  • POST   /api/levels              - Create level
  • PUT    /api/levels              - Update level
  • DELETE /api/levels?id=...       - Delete level
  • PUT    /api/levels/reorder      - Batch reorder (transaction)

USERS (4 endpoints)
  • GET    /api/users               - List admin users
  • POST   /api/users               - Create user
  • PUT    /api/users               - Update user/password
  • DELETE /api/users?id=...        - Delete user

WECHAT USERS (3 endpoints)
  • GET    /api/wx-users?search=...&page=... - List with pagination
  • GET    /api/wx-users/[id]               - Get user + progress
  • DELETE /api/wx-users/level-progress     - Batch delete progress

CLOUD STORAGE (1 endpoint)
  • GET    /api/cos/temp-key        - Get 30-min COS credentials

================================================================================
                        PROTECTED PAGES (3)
================================================================================

1. /levels          - Drag-and-drop level management (add/edit/delete)
2. /users           - Admin user management
3. /wx-users        - WeChat user viewing + progress history

Public Pages: /login (before auth)

================================================================================
                        KEY LIBRARIES & UTILITIES
================================================================================

lib/auth.ts              - Better Auth configuration
lib/auth-client.ts       - Client-side auth hooks (useSession, signIn, signOut)
lib/prisma.ts            - Prisma singleton pattern
lib/api.ts               - apiFetch() helper (auto-adds basePath)
lib/cos.ts               - Tencent COS utilities (getTempKey, getBucketName)
lib/utils.ts             - Tailwind CSS cn() utility

================================================================================
                        AUTHENTICATION FLOW
================================================================================

1. User visits /login
2. Enters email/password
3. POST /api/auth/sign-in (Better Auth)
4. Session created in DB, cookie set (7 days)
5. Middleware checks cookie on page navigation
6. If valid cookie → Allow access
7. If missing/invalid → Redirect to login
8. All API calls validate session before proceeding

Session Token Cookies:
  - HTTP:  "better-auth.session_token"
  - HTTPS: "__Secure-better-auth.session_token"

================================================================================
                        CRITICAL CONFIGURATION NOTES
================================================================================

⚠️ BASEPATH HANDLING (Next.js 14)
   - request.nextUrl.pathname EXCLUDES basePath
   - Middleware checks "/levels", not "/studio/levels"
   - apiFetch() automatically prepends basePath
   - DO NOT manually add "/studio" to routes

⚠️ BETTER AUTH CONFIGURATION
   - BETTER_AUTH_URL must be origin ONLY (no path)
   - ✅ Correct:   "https://domain.com"
   - ❌ Wrong:     "https://domain.com/studio"
   - basePath in config must be "/api/auth" (not "/studio/api/auth")

⚠️ ENVIRONMENT VARIABLES CRITICAL
   - DATABASE_URL:        MySQL connection string
   - BETTER_AUTH_SECRET:  32+ character random string
   - BETTER_AUTH_URL:     Origin only, NO path component
   - NEXT_PUBLIC_APP_URL: Same as BETTER_AUTH_URL
   - NEXT_PUBLIC_BASE_PATH: "/studio"

⚠️ IMAGE UPLOAD FLOW
   - Frontend requests temp credentials: GET /api/cos/temp-key
   - Frontend uploads directly to COS (not through backend)
   - Backend stores URL in database only
   - Credentials valid for 30 minutes
   - Restricted to "mini_game/images/*" path prefix

================================================================================
                        PROJECT STRUCTURE OVERVIEW
================================================================================

app/
  ├── (auth)/                    - Route group: login page (no sidebar)
  ├── (dashboard)/               - Route group: protected pages (with sidebar)
  │   ├── levels/page.tsx        - Level management UI
  │   ├── users/page.tsx         - User management UI
  │   └── wx-users/page.tsx      - WeChat users UI
  └── api/                       - All API routes (protected)

lib/
  ├── auth.ts                    - Better Auth config
  ├── auth-client.ts             - Client hooks
  ├── prisma.ts                  - Singleton
  ├── cos.ts                     - COS utilities
  ├── api.ts                     - apiFetch wrapper
  └── utils.ts                   - Tailwind utilities

components/
  ├── layout/                    - Header, sidebar
  ├── levels/                    - Level components
  ├── users/                     - User components
  ├── wx-users/                  - WeChat user components
  └── ui/                        - shadcn/ui components

prisma/
  └── schema.prisma              - Database schema (7 models)

types/
  └── index.ts                   - TypeScript interfaces

================================================================================
                        SECURITY FEATURES
================================================================================

✅ Session-Based Authentication
✅ Password Hashing (bcryptjs + better-auth/crypto)
✅ Cookie Validation (handles HTTP and HTTPS prefixes)
✅ Self-Delete Prevention (can't delete own account)
✅ Temporary COS Credentials (30-minute expiry)
✅ Session Expiration (7 days)
✅ Cascade Delete (sessions/accounts deleted with user)

❌ NOT IMPLEMENTED:
   - Role-based access control (all authenticated = full admin)
   - Permission system
   - Sharing/invite functionality
   - Rate limiting
   - Audit logging
   - Email verification (model exists, not used)

================================================================================
                        DEPLOYMENT CONFIGURATION
================================================================================

Server:             root@119.91.211.52
Installation Path:  /root/apps/meme-studio
Process Manager:    PM2
Staging:            Behind reverse proxy at /studio

Next.js Config:
  - output: 'standalone'        (single binary, bundles Next.js)
  - basePath: '/studio'         (app served at /studio)
  - Remote images: '*.myqcloud.com' (Tencent COS)

Deployment Steps:
  1. npm run build              (locally)
  2. ./deploy.sh                (builds, rsyncs, installs, restarts PM2)

Notes:
  - Prisma is devDependency but must be generated on server
  - Cross-platform binary targets: ["native", "rhel-openssl-3.0.x"]
  - production npm install uses --production (no devDeps)

================================================================================
                        TECHNOLOGY STACK COMPLETE
================================================================================

FRONTEND:
  - React 18.3.1
  - TypeScript 5.8.2
  - Next.js 14.2.28 (App Router)
  - Tailwind CSS 3.4.17
  - shadcn/ui (Radix UI based)
  - TanStack React Query 5.69.0
  - React Hook Form 7.54.2
  - Zod 3.24.2
  - @dnd-kit (drag-and-drop)
  - lucide-react (icons)

BACKEND:
  - Node.js (Next.js runtime)
  - Better Auth 1.2.7
  - Prisma 6.5.0
  - MySQL (database)
  - bcryptjs 3.0.2

DEPLOYMENT:
  - PM2 (process management)
  - rsync (file transfer)
  - SSH (remote access)

CLOUD:
  - Tencent COS (object storage)
  - Tencent COS STS (temporary credentials)

================================================================================
                        WHAT'S MISSING
================================================================================

❌ SHARE/INVITE SYSTEM
   - No share links or tokens
   - No invite functionality
   - No permission hierarchy
   - All authenticated users = full admin access

❌ ADVANCED FEATURES
   - No role-based access control
   - No audit logging
   - No soft deletes
   - No rate limiting
   - No two-factor authentication
   - Email verification model unused

❌ OPERATIONAL FEATURES
   - No backup/restore utilities
   - No analytics/reporting
   - No notification system
   - No scheduled tasks

================================================================================
                        RECOMMENDATIONS
================================================================================

If adding Sharing/Invite Feature:
  1. Create ShareToken model with expiry
  2. Add share generation endpoints
  3. Implement permission validation
  4. Add UI for share management
  5. Consider adding role system first

If adding Permissions:
  1. Add role field to User model (admin, editor, viewer)
  2. Add permission checks in all API routes
  3. Add UI for role assignment
  4. Update middleware for role-based access

If scaling further:
  1. Add audit logging
  2. Implement rate limiting
  3. Add caching layer (Redis)
  4. Setup database replication
  5. Implement API versioning

================================================================================
                        DOCUMENTATION FILES
================================================================================

Three comprehensive documentation files have been created:

1. PROJECT_ANALYSIS.md (27 KB)
   - 14 detailed sections
   - Complete API reference
   - Database schema breakdown
   - Auth flow explanation
   - Deployment guide
   - Common patterns
   - Gotchas and best practices

2. QUICK_REFERENCE.md (7.8 KB)
   - Visual architecture diagram
   - Quick lookup tables
   - Common tasks
   - Critical gotchas
   - Quick stats summary

3. EXPLORATION_MANIFEST.md (8.1 KB)
   - Files analyzed checklist
   - Key findings summary
   - Technology stacks
   - Health indicators
   - Next steps for development

All files located in: /Users/richard/Documents/code/xieyingeng/MemeStudio/

================================================================================
                        EXPLORATION STATISTICS
================================================================================

Files Analyzed:        30+
Total Lines Read:      5000+ lines of code
API Routes:            14 endpoints across 8 files
Components:            15+ React components
Utility Files:         6 core utilities
Database Models:       7 Prisma models
Frontend Pages:        4 main pages
UI Components:         10+ shadcn/ui components

Code Quality:          Excellent
  ✅ Well-organized structure
  ✅ Consistent naming
  ✅ Type-safe throughout
  ✅ Good error handling
  ✅ Clean component composition
  ✅ Proper auth patterns
  ✅ Transaction support

================================================================================
                        CONCLUSION
================================================================================

The MemeStudio project is a well-structured, production-ready admin platform
for managing game levels and tracking user progress. The codebase demonstrates:

✅ Best practices in Next.js 14 development
✅ Proper authentication implementation
✅ Clean API design patterns
✅ Good database schema design
✅ Solid TypeScript usage
✅ Proper deployment configuration

The main gap is the absence of a sharing/invite system and permission
hierarchy, which are not currently implemented. All authenticated users
have full admin access to all features.

Perfect starting point for adding collaborative features or expanding
the admin panel with more sophisticated access controls.

================================================================================
                        END OF EXPLORATION REPORT
================================================================================