Initial commit - LEGO Instructions Manager v1.5.0
This commit is contained in:
235
QUICK_REFERENCE.md
Normal file
235
QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# 📋 LEGO Instructions Manager - Quick Reference
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Setup
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||||
pip install -r requirements.txt
|
||||
cp .env.example .env
|
||||
|
||||
# 2. Configure (edit .env)
|
||||
# Add your SECRET_KEY and optionally Brickset credentials
|
||||
|
||||
# 3. Initialize
|
||||
flask --app run.py init-db
|
||||
flask --app run.py create-admin
|
||||
|
||||
# 4. Run
|
||||
python run.py
|
||||
# Visit: http://localhost:5000
|
||||
```
|
||||
|
||||
## 📁 Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `run.py` | Application entry point |
|
||||
| `.env` | Configuration (SECRET_KEY, API keys) |
|
||||
| `requirements.txt` | Python dependencies |
|
||||
| `app/__init__.py` | Flask app factory |
|
||||
| `app/config.py` | App configuration |
|
||||
|
||||
## 🔑 Environment Variables
|
||||
|
||||
```env
|
||||
SECRET_KEY=your-secret-key-here
|
||||
DATABASE_URL=sqlite:///lego_instructions.db
|
||||
BRICKSET_API_KEY=your-api-key
|
||||
BRICKSET_USERNAME=your-username
|
||||
BRICKSET_PASSWORD=your-password
|
||||
```
|
||||
|
||||
## 🛠️ Flask Commands
|
||||
|
||||
```bash
|
||||
# Initialize database
|
||||
flask --app run.py init-db
|
||||
|
||||
# Create admin user
|
||||
flask --app run.py create-admin
|
||||
|
||||
# Flask shell
|
||||
flask --app run.py shell
|
||||
|
||||
# Database migrations
|
||||
flask --app run.py db init
|
||||
flask --app run.py db migrate -m "message"
|
||||
flask --app run.py db upgrade
|
||||
```
|
||||
|
||||
## 📂 Directory Structure
|
||||
|
||||
```
|
||||
app/
|
||||
├── models/ # Database models (User, Set, Instruction)
|
||||
├── routes/ # URL routes (auth, main, sets, instructions)
|
||||
├── services/ # Business logic (Brickset API, file handling)
|
||||
├── templates/ # HTML templates
|
||||
└── static/ # CSS, JS, uploads
|
||||
```
|
||||
|
||||
## 🌐 Main Routes
|
||||
|
||||
| Route | Purpose |
|
||||
|-------|---------|
|
||||
| `/` | Homepage |
|
||||
| `/auth/login` | Login page |
|
||||
| `/auth/register` | Registration |
|
||||
| `/dashboard` | User dashboard |
|
||||
| `/sets/` | List all sets |
|
||||
| `/sets/add` | Add new set |
|
||||
| `/sets/<id>` | View set details |
|
||||
| `/instructions/upload/<id>` | Upload instructions |
|
||||
|
||||
## 🔍 Common Tasks
|
||||
|
||||
### Add a New Set
|
||||
1. Navigate to `/sets/add`
|
||||
2. Search Brickset OR enter manually
|
||||
3. Click "Add Set"
|
||||
|
||||
### Upload Instructions
|
||||
1. Go to set detail page
|
||||
2. Click "Upload Instructions"
|
||||
3. Select files (PDF or images)
|
||||
4. Click "Upload"
|
||||
|
||||
### Search Sets
|
||||
1. Go to `/sets/`
|
||||
2. Use search bar for text search
|
||||
3. Use filters for theme/year
|
||||
4. Click column headers to sort
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Module Not Found
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Permission Denied
|
||||
```bash
|
||||
chmod -R 755 app/static/uploads
|
||||
```
|
||||
|
||||
### Database Locked
|
||||
```bash
|
||||
# Restart the application
|
||||
# Or switch to PostgreSQL
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
```python
|
||||
# In run.py, change:
|
||||
app.run(port=5001) # Use different port
|
||||
```
|
||||
|
||||
## 📊 Database Models
|
||||
|
||||
### User
|
||||
- username, email, password_hash
|
||||
- Relationships: sets, instructions
|
||||
|
||||
### Set
|
||||
- set_number, set_name, theme, year_released
|
||||
- piece_count, brickset_id, image_url
|
||||
|
||||
### Instruction
|
||||
- set_id, file_type, file_path, file_name
|
||||
- file_size, page_number
|
||||
|
||||
## 🔐 Security Features
|
||||
|
||||
- ✅ Password hashing (bcrypt)
|
||||
- ✅ CSRF protection
|
||||
- ✅ SQL injection prevention
|
||||
- ✅ XSS protection
|
||||
- ✅ Secure file uploads
|
||||
- ✅ Session management
|
||||
|
||||
## 📱 Tech Stack
|
||||
|
||||
- **Backend**: Flask 3.0, SQLAlchemy
|
||||
- **Frontend**: Bootstrap 5, jQuery
|
||||
- **Database**: SQLite (dev) / PostgreSQL (prod)
|
||||
- **Auth**: Flask-Login, bcrypt
|
||||
- **API**: Brickset API v3
|
||||
|
||||
## 🎨 Customization
|
||||
|
||||
### Change Colors
|
||||
Edit `app/static/css/style.css`:
|
||||
```css
|
||||
:root {
|
||||
--lego-red: #d11013;
|
||||
--lego-yellow: #ffd700;
|
||||
--lego-blue: #0055bf;
|
||||
}
|
||||
```
|
||||
|
||||
### Add Custom Routes
|
||||
1. Create route in `app/routes/`
|
||||
2. Register blueprint in `app/__init__.py`
|
||||
|
||||
### Modify Models
|
||||
1. Edit model in `app/models/`
|
||||
2. Create migration
|
||||
3. Apply migration
|
||||
|
||||
## 📦 Dependencies
|
||||
|
||||
Main packages:
|
||||
- Flask 3.0.0
|
||||
- Flask-SQLAlchemy 3.1.1
|
||||
- Flask-Login 0.6.3
|
||||
- Flask-Bcrypt 1.0.1
|
||||
- requests 2.31.0
|
||||
- Pillow 10.1.0
|
||||
|
||||
## 🔄 Update Workflow
|
||||
|
||||
```bash
|
||||
# Pull latest changes
|
||||
git pull origin main
|
||||
|
||||
# Update dependencies
|
||||
pip install -r requirements.txt --upgrade
|
||||
|
||||
# Apply database migrations
|
||||
flask --app run.py db upgrade
|
||||
|
||||
# Restart application
|
||||
python run.py
|
||||
```
|
||||
|
||||
## 📞 Help & Resources
|
||||
|
||||
- **README.md** - Full documentation
|
||||
- **SETUP_GUIDE.md** - Detailed setup
|
||||
- **PROJECT_SUMMARY.md** - Features & roadmap
|
||||
- **Brickset API**: https://brickset.com/article/52664
|
||||
|
||||
## ⚡ Performance Tips
|
||||
|
||||
1. Use PostgreSQL for production
|
||||
2. Enable gzip compression
|
||||
3. Set up CDN for static files
|
||||
4. Use Redis for caching
|
||||
5. Monitor upload folder size
|
||||
|
||||
## 🎯 Production Checklist
|
||||
|
||||
- [ ] Change SECRET_KEY
|
||||
- [ ] Use PostgreSQL
|
||||
- [ ] Set FLASK_ENV=production
|
||||
- [ ] Use gunicorn
|
||||
- [ ] Set up nginx
|
||||
- [ ] Enable HTTPS
|
||||
- [ ] Set up backups
|
||||
- [ ] Configure logging
|
||||
|
||||
---
|
||||
|
||||
**Quick Help**: For detailed information, see README.md and SETUP_GUIDE.md
|
||||
Reference in New Issue
Block a user