236 lines
4.6 KiB
Markdown
236 lines
4.6 KiB
Markdown
# 📋 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
|