320 lines
7.0 KiB
Markdown
320 lines
7.0 KiB
Markdown
# Quality App v2 - Quick Reference Guide
|
||
|
||
## 📂 Complete File Listing
|
||
|
||
### Python Application Files (~865 lines)
|
||
|
||
#### Core Application
|
||
- `app/__init__.py` (120 lines) - App factory, blueprint registration
|
||
- `app/config.py` (70 lines) - Configuration management
|
||
- `app/auth.py` (90 lines) - Authentication utilities
|
||
- `app/database.py` (100 lines) - Database connection pooling
|
||
- `app/routes.py` (70 lines) - Main routes (login, dashboard)
|
||
|
||
#### Modules
|
||
- `app/modules/quality/routes.py` (40 lines) - Quality module routes
|
||
- `app/modules/settings/routes.py` (50 lines) - Settings module routes
|
||
- `app/models/__init__.py` - Model package (expandable)
|
||
|
||
#### Entry Points
|
||
- `run.py` (20 lines) - Development server
|
||
- `wsgi.py` (10 lines) - Production WSGI entry
|
||
- `gunicorn.conf.py` (20 lines) - Gunicorn configuration
|
||
- `init_db.py` (150 lines) - Database initialization
|
||
|
||
### HTML Templates (~1200 lines)
|
||
|
||
#### Base Templates
|
||
- `app/templates/base.html` (110 lines) - Main layout template
|
||
- `app/templates/login.html` (40 lines) - Login page
|
||
|
||
#### Main Pages
|
||
- `app/templates/dashboard.html` (90 lines) - Dashboard with modules
|
||
- `app/templates/profile.html` (60 lines) - User profile
|
||
|
||
#### Error Pages
|
||
- `app/templates/errors/404.html` (20 lines) - Page not found
|
||
- `app/templates/errors/500.html` (20 lines) - Server error
|
||
- `app/templates/errors/403.html` (20 lines) - Access forbidden
|
||
|
||
#### Quality Module Templates
|
||
- `app/templates/modules/quality/index.html` (60 lines)
|
||
- `app/templates/modules/quality/inspections.html` (80 lines)
|
||
- `app/templates/modules/quality/reports.html` (70 lines)
|
||
|
||
#### Settings Module Templates
|
||
- `app/templates/modules/settings/index.html` (50 lines)
|
||
- `app/templates/modules/settings/general.html` (60 lines)
|
||
- `app/templates/modules/settings/users.html` (80 lines)
|
||
- `app/templates/modules/settings/database.html` (60 lines)
|
||
|
||
### Stylesheets (~600 lines)
|
||
|
||
- `app/static/css/base.css` (400 lines) - Global styles, responsive design
|
||
- `app/static/css/login.css` (200 lines) - Login page styling
|
||
|
||
### JavaScript (~150 lines)
|
||
|
||
- `app/static/js/base.js` (150 lines) - Utilities, Bootstrap init, theme toggle
|
||
|
||
### Docker & Deployment
|
||
|
||
- `Dockerfile` - Python 3.11 slim, production optimized
|
||
- `docker-compose.yml` - MariaDB + Flask services
|
||
- `docker-entrypoint.sh` - Container startup script
|
||
- `.dockerignore` - Docker build optimization
|
||
|
||
### Configuration & Documentation
|
||
|
||
- `requirements.txt` - Python dependencies
|
||
- `.env.example` - Environment variables template
|
||
- `.gitignore` - Git ignore rules
|
||
- `README.md` - Deployment and setup guide
|
||
- `ARCHITECTURE.md` - Technical architecture guide
|
||
- `PROJECT_SUMMARY.md` - Project overview
|
||
- `QUICK_REFERENCE.md` - This file
|
||
|
||
---
|
||
|
||
## 🚀 Quick Commands
|
||
|
||
### Deployment
|
||
```bash
|
||
# One-command deploy
|
||
./quick-deploy.sh
|
||
|
||
# Manual deployment
|
||
docker-compose up -d
|
||
|
||
# Check status
|
||
docker-compose ps
|
||
|
||
# View logs
|
||
docker-compose logs -f app
|
||
```
|
||
|
||
### Database
|
||
```bash
|
||
# Initialize database
|
||
docker-compose exec app python init_db.py
|
||
|
||
# Backup database
|
||
docker-compose exec mariadb mariadb-dump -u quality_user -p quality_db > backup.sql
|
||
|
||
# Access MariaDB CLI
|
||
docker-compose exec mariadb mariadb -u quality_user -p
|
||
```
|
||
|
||
### Development
|
||
```bash
|
||
# Local setup
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
pip install -r requirements.txt
|
||
python init_db.py
|
||
python run.py
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 Default Credentials
|
||
|
||
**CHANGE IMMEDIATELY AFTER FIRST LOGIN!**
|
||
|
||
- Username: `admin`
|
||
- Password: `admin123`
|
||
|
||
---
|
||
|
||
## 📱 Access Points
|
||
|
||
- **Application**: `http://localhost:8080`
|
||
- **Database**: `localhost:3306` (MariaDB)
|
||
- **User**: `quality_user`
|
||
|
||
---
|
||
|
||
## 📋 Module Features
|
||
|
||
### Quality Module
|
||
✅ Inspection management
|
||
✅ Quality reports
|
||
✅ Status tracking
|
||
✅ Notes and comments
|
||
|
||
### Settings Module
|
||
✅ General settings
|
||
✅ User management
|
||
✅ Database configuration
|
||
✅ Application preferences
|
||
|
||
---
|
||
|
||
## 🗄️ Database Tables
|
||
|
||
1. **users** - User accounts
|
||
- Fields: id, username, email, full_name, role, is_active, timestamps
|
||
|
||
2. **user_credentials** - Password management
|
||
- Fields: id, user_id, password_hash, timestamps
|
||
|
||
3. **quality_inspections** - Quality records
|
||
- Fields: id, type, status, inspector_id, date, notes, timestamps
|
||
|
||
4. **application_settings** - Configuration
|
||
- Fields: id, key, value, type, timestamps
|
||
|
||
---
|
||
|
||
## 🔧 Environment Variables
|
||
|
||
```ini
|
||
# Flask
|
||
FLASK_ENV=production
|
||
FLASK_DEBUG=False
|
||
SECRET_KEY=your-secret-key
|
||
|
||
# Database
|
||
DB_HOST=mariadb
|
||
DB_PORT=3306
|
||
DB_USER=quality_user
|
||
DB_PASSWORD=your-password
|
||
DB_NAME=quality_db
|
||
|
||
# Application
|
||
APP_PORT=8080
|
||
APP_HOST=0.0.0.0
|
||
LOG_LEVEL=INFO
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Application Structure
|
||
|
||
```
|
||
Request
|
||
↓
|
||
Authentication Check
|
||
↓
|
||
Route Handler (Flask Blueprint)
|
||
↓
|
||
Business Logic (auth.py)
|
||
↓
|
||
Database Query (database.py)
|
||
↓
|
||
Template Rendering
|
||
↓
|
||
Response (HTML/JSON)
|
||
```
|
||
|
||
---
|
||
|
||
## 🛡️ Security Features
|
||
|
||
- ✅ Password hashing (SHA256)
|
||
- ✅ Session management
|
||
- ✅ SQL injection prevention
|
||
- ✅ CSRF protection
|
||
- ✅ Connection pooling
|
||
- ✅ Error handling
|
||
|
||
---
|
||
|
||
## 📈 Performance
|
||
|
||
- Connection pooling: 10 connections
|
||
- Worker processes: CPU count × 2 + 1
|
||
- Worker timeout: 60 seconds
|
||
- Max content length: 100MB
|
||
|
||
---
|
||
|
||
## 📚 Documentation Files
|
||
|
||
1. **README.md** - Deployment, setup, troubleshooting
|
||
2. **ARCHITECTURE.md** - Technical deep dive, patterns, scalability
|
||
3. **PROJECT_SUMMARY.md** - Overview, features, statistics
|
||
4. **QUICK_REFERENCE.md** - This file
|
||
|
||
---
|
||
|
||
## ⚡ Performance Tips
|
||
|
||
1. Use Docker for consistent deployments
|
||
2. Keep database indexes optimized
|
||
3. Monitor logs for errors
|
||
4. Regular backups of data
|
||
5. Update Python dependencies regularly
|
||
|
||
---
|
||
|
||
## 🔄 Workflow
|
||
|
||
### Development
|
||
1. Make code changes
|
||
2. Test locally with `python run.py`
|
||
3. Check database migrations
|
||
4. Verify Docker build
|
||
|
||
### Staging
|
||
1. Build Docker image
|
||
2. Run `docker-compose up`
|
||
3. Test all features
|
||
4. Check performance
|
||
|
||
### Production
|
||
1. Update .env with production values
|
||
2. Run `./quick-deploy.sh`
|
||
3. Verify health checks
|
||
4. Monitor logs
|
||
5. Regular backups
|
||
|
||
---
|
||
|
||
## 🐛 Troubleshooting
|
||
|
||
| Issue | Solution |
|
||
|-------|----------|
|
||
| DB connection failed | Check if mariadb service is running: `docker-compose ps` |
|
||
| Port already in use | Change APP_PORT in .env and restart |
|
||
| Template not found | Verify file path in `app/templates/` |
|
||
| Import error | Install requirements: `pip install -r requirements.txt` |
|
||
| Database empty | Run: `docker-compose exec app python init_db.py` |
|
||
|
||
---
|
||
|
||
## 🎯 Next Features to Add
|
||
|
||
- [ ] Advanced search and filtering
|
||
- [ ] Data export (Excel/PDF)
|
||
- [ ] Email notifications
|
||
- [ ] API endpoints
|
||
- [ ] User activity logging
|
||
- [ ] Two-factor authentication
|
||
- [ ] Dashboard customization
|
||
- [ ] Batch operations
|
||
- [ ] Data validation rules
|
||
- [ ] Audit trail
|
||
|
||
---
|
||
|
||
## 📞 Support
|
||
|
||
- Flask docs: https://flask.palletsprojects.com/
|
||
- MariaDB docs: https://mariadb.com/kb/
|
||
- Docker docs: https://docs.docker.com/
|
||
|
||
---
|
||
|
||
## 📝 Notes
|
||
|
||
- Database initializes automatically on first run
|
||
- Logs are rotated (10 files × 10MB)
|
||
- All timestamps in UTC
|
||
- UTF-8 support for international characters
|
||
- Production-ready with Gunicorn
|
||
|
||
---
|
||
|
||
**Quality App v2** - Built for Scale, Designed for Extension
|