237 lines
7.9 KiB
Markdown
237 lines
7.9 KiB
Markdown
# 📚 MemeStudio Documentation Index
|
|
|
|
Welcome! This project has been thoroughly explored and documented. Here's where to find everything:
|
|
|
|
## 📋 Documentation Files
|
|
|
|
### 1. **EXPLORATION_SUMMARY.txt** ⭐ START HERE
|
|
**Best for:** Quick overview and reference
|
|
- Executive summary in text format
|
|
- Quick facts, statistics, and tech stack
|
|
- Critical configuration notes
|
|
- What's missing and recommendations
|
|
- **Read time:** 5-10 minutes
|
|
|
|
### 2. **QUICK_REFERENCE.md** 🚀 MOST USEFUL
|
|
**Best for:** Quick lookups during development
|
|
- Visual architecture diagram
|
|
- Database models quick table
|
|
- Complete API endpoints list
|
|
- Environment variables reference
|
|
- Common tasks/gotchas
|
|
- **Read time:** 10 minutes
|
|
- **Use case:** Pin this on your desktop!
|
|
|
|
### 3. **PROJECT_ANALYSIS.md** 📖 COMPREHENSIVE
|
|
**Best for:** Deep understanding and reference
|
|
- 14 detailed sections
|
|
- Complete API route documentation (with examples)
|
|
- Full Prisma schema breakdown
|
|
- Authentication flow explanation
|
|
- Middleware and library details
|
|
- Deployment configuration
|
|
- Patterns and conventions
|
|
- Critical gotchas and important notes
|
|
- **Read time:** 30-45 minutes
|
|
- **Use case:** Bookmark for detailed reference
|
|
|
|
### 4. **EXPLORATION_MANIFEST.md** 🔍 DETAILED REPORT
|
|
**Best for:** Understanding what was analyzed
|
|
- Complete files analyzed checklist
|
|
- Analysis summary with statistics
|
|
- Key findings (architecture, database, API patterns, security)
|
|
- Technology stack complete breakdown
|
|
- Development commands
|
|
- Project health indicators
|
|
- Next steps for development
|
|
- **Read time:** 15-20 minutes
|
|
- **Use case:** Reference for future development roadmap
|
|
|
|
## 🎯 Quick Navigation by Task
|
|
|
|
### "I want to understand the project quickly"
|
|
→ Read: **EXPLORATION_SUMMARY.txt** (5 min)
|
|
|
|
### "I need to add a new API endpoint"
|
|
→ Read: **QUICK_REFERENCE.md** → "Common Tasks" section
|
|
→ Reference: **PROJECT_ANALYSIS.md** → "Section 11: Existing Patterns"
|
|
|
|
### "I need to understand the database"
|
|
→ Read: **QUICK_REFERENCE.md** → Database Models table
|
|
→ Reference: **PROJECT_ANALYSIS.md** → "Section 4: Database Schema"
|
|
|
|
### "I need to modify authentication"
|
|
→ Read: **QUICK_REFERENCE.md** → Authentication Flow
|
|
→ Reference: **PROJECT_ANALYSIS.md** → "Section 6: Middleware & Auth"
|
|
|
|
### "I need to deploy this"
|
|
→ Read: **PROJECT_ANALYSIS.md** → "Section 10: Deployment"
|
|
→ Reference: **QUICK_REFERENCE.md** → "🚀 DEPLOYMENT"
|
|
|
|
### "I want to add sharing/invite feature"
|
|
→ Read: **PROJECT_ANALYSIS.md** → "Section 13: Absence of Share/Invite"
|
|
→ Reference: **EXPLORATION_MANIFEST.md** → "Next Steps for Development"
|
|
|
|
### "I need to understand the current API"
|
|
→ Reference: **PROJECT_ANALYSIS.md** → "Section 5: API Routes"
|
|
→ Quick lookup: **QUICK_REFERENCE.md** → "API ENDPOINTS"
|
|
|
|
## 📊 Project Overview
|
|
|
|
| Item | Details |
|
|
|------|---------|
|
|
| **Framework** | Next.js 14.2.28 (App Router) |
|
|
| **Backend** | TypeScript + Better Auth |
|
|
| **Database** | MySQL + Prisma ORM |
|
|
| **Deployment** | PM2 on Linux server |
|
|
| **Auth** | Email/password, 7-day sessions |
|
|
| **Cloud Storage** | Tencent COS |
|
|
| **API Endpoints** | 14 total (protected) |
|
|
| **Database Models** | 7 (Better Auth + custom) |
|
|
| **Protected Pages** | 3 (levels, users, wx-users) |
|
|
| **Status** | Production-ready ✅ |
|
|
|
|
## 🔑 Key Features
|
|
|
|
✅ Admin platform for game level management
|
|
✅ User management (admin accounts)
|
|
✅ WeChat mini-program user tracking
|
|
✅ Drag-and-drop level reordering
|
|
✅ Image upload to Tencent COS
|
|
✅ Role-free authentication (all users = admin)
|
|
✅ Transactional database operations
|
|
|
|
❌ **Missing:** Share/invite system, permission system, audit logging
|
|
|
|
## ⚠️ Critical Notes
|
|
|
|
### basePath Handling
|
|
- Application served at `/studio`
|
|
- `apiFetch()` auto-prepends basePath
|
|
- Middleware checks WITHOUT basePath (Next.js 14)
|
|
- Don't manually add `/studio` to routes!
|
|
|
|
### Better Auth Configuration
|
|
- ⚠️ `BETTER_AUTH_URL` must NOT have path component
|
|
- ❌ Wrong: `https://domain.com/studio`
|
|
- ✅ Right: `https://domain.com`
|
|
|
|
### Environment Variables Required
|
|
```
|
|
DATABASE_URL # MySQL connection
|
|
BETTER_AUTH_SECRET # 32+ random chars
|
|
BETTER_AUTH_URL # Origin only
|
|
NEXT_PUBLIC_APP_URL # Same as BETTER_AUTH_URL
|
|
NEXT_PUBLIC_BASE_PATH # /studio
|
|
ADMIN_EMAIL # For seed
|
|
ADMIN_PASSWORD # For seed
|
|
COS_SECRET_ID # Tencent Cloud
|
|
COS_SECRET_KEY # Tencent Cloud
|
|
COS_BUCKET # Tencent Cloud
|
|
COS_REGION # Tencent Cloud
|
|
COS_APPID # Tencent Cloud
|
|
```
|
|
|
|
## 🏗️ Architecture Summary
|
|
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ Frontend (Next.js 14) │
|
|
│ React + Tailwind + shadcn/ui │
|
|
│ TanStack Query for state management │
|
|
└────────────────┬────────────────────────┘
|
|
│
|
|
┌───────▼────────┐
|
|
│ API Routes │
|
|
│ (Protected) │
|
|
└───────┬────────┘
|
|
│
|
|
┌────────────▼──────────────┐
|
|
│ Better Auth (7-day) │
|
|
│ Email/Password │
|
|
└────────────┬──────────────┘
|
|
│
|
|
┌────────▼──────────┐
|
|
│ MySQL Database │
|
|
│ (Prisma ORM) │
|
|
│ (7 models) │
|
|
└───────────────────┘
|
|
```
|
|
|
|
## 📞 File Sizes
|
|
|
|
| File | Size | Type |
|
|
|------|------|------|
|
|
| EXPLORATION_SUMMARY.txt | ~6 KB | Plain text |
|
|
| QUICK_REFERENCE.md | ~8 KB | Markdown |
|
|
| PROJECT_ANALYSIS.md | ~27 KB | Markdown |
|
|
| EXPLORATION_MANIFEST.md | ~8 KB | Markdown |
|
|
| CLAUDE.md | ~4 KB | Markdown (original) |
|
|
|
|
**Total documentation:** ~53 KB of comprehensive analysis
|
|
|
|
## 🎓 Learning Path
|
|
|
|
**For New Developers:**
|
|
1. Read EXPLORATION_SUMMARY.txt (quick overview)
|
|
2. Skim QUICK_REFERENCE.md (understand structure)
|
|
3. Read PROJECT_ANALYSIS.md Section 1-3 (framework & structure)
|
|
4. Read PROJECT_ANALYSIS.md Section 6 (authentication)
|
|
|
|
**For Adding Features:**
|
|
1. Check QUICK_REFERENCE.md "Common Tasks"
|
|
2. Reference PROJECT_ANALYSIS.md "Section 11: Patterns"
|
|
3. Look at existing similar code
|
|
4. Follow the established patterns
|
|
|
|
**For Deployment:**
|
|
1. Read PROJECT_ANALYSIS.md "Section 10: Deployment"
|
|
2. Check environment variables in EXPLORATION_SUMMARY.txt
|
|
3. Review the deploy.sh script
|
|
|
|
**For Database Changes:**
|
|
1. Read PROJECT_ANALYSIS.md "Section 4: Database Schema"
|
|
2. Understand existing relationships
|
|
3. Use Prisma migrations
|
|
4. Update types/index.ts
|
|
|
|
## ✅ Exploration Checklist
|
|
|
|
What was analyzed:
|
|
- ✅ Project structure and organization
|
|
- ✅ Next.js configuration
|
|
- ✅ All 7 Prisma database models
|
|
- ✅ All 14 API endpoints
|
|
- ✅ Authentication and middleware
|
|
- ✅ All utility libraries
|
|
- ✅ UI components and patterns
|
|
- ✅ Environment configuration
|
|
- ✅ Deployment setup
|
|
- ✅ Technology stack
|
|
- ✅ Security features
|
|
- ✅ Absence of sharing/invite logic
|
|
|
|
**Total files explored:** 30+
|
|
**Total lines of code reviewed:** 5000+
|
|
**Quality assessment:** ⭐⭐⭐⭐⭐ Excellent
|
|
|
|
## 🚀 Getting Started
|
|
|
|
1. **First time?** → Read EXPLORATION_SUMMARY.txt
|
|
2. **Adding code?** → Reference QUICK_REFERENCE.md
|
|
3. **Deep dive?** → Study PROJECT_ANALYSIS.md
|
|
4. **Planning changes?** → Check EXPLORATION_MANIFEST.md
|
|
|
|
## 💡 Tips
|
|
|
|
- Pin **QUICK_REFERENCE.md** on your desk (physical or digital)
|
|
- Reference **PROJECT_ANALYSIS.md** when making architectural decisions
|
|
- Use **EXPLORATION_MANIFEST.md** for planning roadmap
|
|
- Check **EXPLORATION_SUMMARY.txt** for quick facts
|
|
|
|
---
|
|
|
|
**Generated:** April 6, 2026
|
|
**Project:** MemeStudio - 谐音梗小游戏运营平台
|
|
**Status:** ✅ Thoroughly Explored and Documented
|