feat: 支持批量上传关卡
This commit is contained in:
richarjiang
364
EXPLORATION_SUMMARY.txt
Normal file
364
EXPLORATION_SUMMARY.txt
Normal file
@@ -0,0 +1,364 @@
|
||||
================================================================================
|
||||
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
|
||||
================================================================================
|
||||
Reference in New Issue
Block a user