365 lines
14 KiB
Plaintext
365 lines
14 KiB
Plaintext
================================================================================
|
|
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
|
|
================================================================================
|