sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

revamping documentation

Browse Source
This commit is contained in:
Samir Boulahtit
2025-11-17 22:59:42 +01:00
parent bbd64a6f21
commit 807033be16
107 changed files with 11973 additions and 28413 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1005
docs/development/database-seeder/DATABASE_INIT_GUIDE.md Normal file
View File

File diff suppressed because it is too large Load Diff

247
docs/development/database-seeder/DATABASE_QUICK_REFERENCE_GUIDE.md Normal file
View File

@@ -0,0 +1,247 @@
# Database Commands - Quick Reference
## 🚀 Common Workflows
### First-Time Development Setup
```bash
make migrate-up # Apply migrations
make init-prod # Create admin user
make seed-demo # Add demo data
make dev # Start developing
```
### First-Time Production Setup
```bash
# 1. Configure .env
ENVIRONMENT=production
ADMIN_EMAIL=admin@yourcompany.com
ADMIN_PASSWORD=SecurePassword123!
# 2. Initialize
make migrate-up
make init-prod
# 3. Create vendors via admin panel
```
### Daily Development
```bash
make dev # Start server
make seed-demo-reset # Fresh demo data
make test # Run tests
```
---
## 📋 Command Reference
### Database Migrations
```bash
make migrate-create message="add_feature" # Create migration
make migrate-up # Apply migrations
make migrate-down # Rollback last
make migrate-status # Check status
```
### Initialization
```bash
make init-prod # Create admin + settings (SAFE for production)
```
### Demo Data (Development Only)
```bash
make seed-demo # 3 vendors + data
make seed-demo-minimal # 1 vendor only
make seed-demo-reset # DELETE ALL + reseed (DANGEROUS!)
```
### Complete Workflows
```bash
make db-setup # migrate + init + seed
make db-reset # rollback + migrate + reset
```
---
## ⚙️ Configuration (.env)
### Required Settings
```bash
ENVIRONMENT=development # development/staging/production
DATABASE_URL=sqlite:///./wizamart.db
# Admin credentials (CHANGE IN PRODUCTION!)
ADMIN_EMAIL=admin@wizamart.com
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123
```
### Demo Data Controls
```bash
SEED_DEMO_VENDORS=3 # How many vendors
SEED_CUSTOMERS_PER_VENDOR=15 # Customers per vendor
SEED_PRODUCTS_PER_VENDOR=20 # Products per vendor
```
### Using Settings in Code
```python
from app.core.config import settings
# Environment checks
if settings.is_production:
# Production code
# Access configuration
email = settings.admin_email
db_url = settings.database_url
```
---
## 🔐 Default Credentials
### Admin (After init-prod)
```
URL: http://localhost:8000/admin/login
Username: admin
Password: admin123 (CHANGE IN PRODUCTION!)
```
### Demo Vendors (After seed-demo)
```
Vendor 1: vendor1@example.com / password123
Vendor 2: vendor2@example.com / password123
Vendor 3: vendor3@example.com / password123
```
⚠️ **All demo passwords are INSECURE - for development only!**
---
## 📊 What Each Command Creates
### `make init-prod`
✅ Platform admin user
✅ Admin settings
✅ Role templates
✅ RBAC schema verification
**Safe for production**: YES
**Contains fake data**: NO
### `make seed-demo`
✅ 3 demo vendors
✅ Demo vendor users
✅ ~45 customers (15 per vendor)
✅ ~60 products (20 per vendor)
✅ Vendor themes
✅ Custom domains
**Safe for production**: NO
**Contains fake data**: YES - ALL OF IT
### `make seed-demo-minimal`
✅ 1 demo vendor
✅ 1 demo vendor user
✅ ~15 customers
✅ ~20 products
✅ Vendor theme
✅ Custom domain
**Safe for production**: NO
**Contains fake data**: YES
---
## 🚨 Safety Features
### Production Warnings
```bash
# Automatically warns if:
⚠️ Using default admin password
⚠️ Using default JWT secret
⚠️ Debug mode enabled in production
⚠️ ALLOWED_HOSTS is wildcard
```
### Environment Protection
```bash
# seed_demo.py refuses to run if:
ENVIRONMENT=production
Error: Cannot run demo seeding in production!
```
### Reset Confirmation
```bash
make seed-demo-reset
# Requires typing: DELETE ALL DATA
```
---
## 🔍 Verification Commands
### Check Database State
```python
# Quick check
python -c "
from app.core.database import SessionLocal
from models.database.vendor import Vendor
db = SessionLocal()
print(f'Vendors: {db.query(Vendor).count()}')
db.close()
"
```
### View Settings
```python
# Check configuration
python -c "
from app.core.config import settings, print_environment_info
print_environment_info()
"
```
### Validate Production
```python
# Check production security
python -c "
from app.core.config import validate_production_settings
warnings = validate_production_settings()
if warnings:
for w in warnings: print(w)
else:
print('✅ Production configuration is secure')
"
```
---
## 🆘 Common Issues
### "Admin already exists"
✅ **Normal!** init_production.py is idempotent (safe to run multiple times)
### "Table doesn't exist"
❌ Run migrations first: `make migrate-up`
### "Cannot run in production"
✅ **Correct behavior!** seed_demo.py blocks production usage
### "Default password warning"
⚠️ Update `.env` with secure password in production
---
## 📚 More Help
```bash
make help # All commands
make help-db # Database-specific help
```
**Documentation**:
- `DATABASE_INIT_GUIDE.md` - Detailed guide
- `MIGRATION_GUIDE.md` - Migration from old system
- `README.md` - Project overview

380
docs/development/database-seeder/DATABASE_SEEDER_DOCUMENTATION.md Normal file
View File

@@ -0,0 +1,380 @@
# Enhanced Database Seeder - Implementation Guide
## Overview
I've created a comprehensive database seeder for your Wizamart platform that significantly expands coverage beyond your original implementation. The new seeder creates realistic test data across all your database models.
## What's New
### Original Seeder Coverage
- ✓ Admin user
- ✓ 2 Vendors (TESTVENDOR, WIZAMART)
### Enhanced Seeder Coverage
- ✓ Admin user + multiple test users (vendors, customers)
- ✓ 3 Vendors with different themes and configurations
- ✓ Custom domains for vendors
- ✓ Vendor themes with different presets (modern, classic, vibrant)
- ✓ 5 Sample marketplace products
- ✓ Vendor-product relationships
- ✓ Multiple customers with addresses
- ✓ Sample orders with order items
- ✓ Import jobs
- ✓ Admin settings (platform configuration)
- ✓ Platform alerts (system monitoring)
## Files Created
1. **seed_database.py** - Enhanced seeder script (placed in /mnt/user-data/outputs/)
2. **makefile_additions.txt** - Commands to add to your Makefile
## Makefile Integration
Add these commands to your Makefile in the DATABASE section (after backup-db):
```makefile
seed:
@echo Seeding database with comprehensive test data...
$(PYTHON) scripts/seed_database.py
@echo Seeding completed successfully
seed-minimal:
@echo Seeding database with minimal data (admin + 1 vendor)...
$(PYTHON) scripts/seed_database.py --minimal
@echo Minimal seeding completed
seed-reset:
@echo WARNING: This will DELETE ALL existing data!
$(PYTHON) scripts/seed_database.py --reset
@echo Database reset and seeded
# Complete database setup (migrate + seed)
db-setup: migrate-up seed
@echo Database setup complete!
@echo Run 'make dev' to start development server
db-reset: migrate-down migrate-up seed-reset
@echo Database completely reset!
```
Add these help entries to the help section (under === DATABASE ===):
```makefile
@echo seed - Seed database with comprehensive test data
@echo seed-minimal - Seed minimal data (admin + 1 vendor)
@echo seed-reset - Reset and seed database (destructive!)
@echo db-setup - Complete database setup (migrate + seed)
@echo db-reset - Complete database reset
```
## Usage
### 1. Install the Seeder
Copy the seed_database.py file to your scripts directory:
```bash
cp seed_database.py scripts/seed_database.py
```
### 2. Run Seeding Commands
#### Option A: Full Comprehensive Seeding (Recommended for Development)
```bash
make seed
# or
python scripts/seed_database.py
```
This creates:
- 1 admin user
- 3 test users (2 vendors, 1 customer)
- 3 vendors (WIZAMART, FASHIONHUB, BOOKSTORE)
- 5 marketplace products
- 10 vendor-product links
- 4 customers
- 8 addresses
- 2 orders
- 2 import jobs
- 4 admin settings
- 2 platform alerts
#### Option B: Minimal Seeding (Quick Setup)
```bash
make seed-minimal
# or
python scripts/seed_database.py --minimal
```
This creates only:
- 1 admin user
- 1 vendor (WIZAMART)
#### Option C: Reset and Seed (Fresh Start)
```bash
make seed-reset
# or
python scripts/seed_database.py --reset
```
⚠️ **WARNING**: This DELETES ALL existing data!
#### Option D: Complete Database Setup (Migration + Seed)
```bash
make db-setup
```
This runs:
1. `make migrate-up` (apply migrations)
2. `make seed` (seed data)
## Test Data Details
### Users Created
| Username | Email | Password | Role |
|----------|-------|----------|------|
| admin | admin@wizamart.com | admin123 | admin |
| vendor1 | vendor1@example.com | password123 | vendor |
| vendor2 | vendor2@example.com | password123 | vendor |
| customer1 | customer1@example.com | password123 | customer |
### Vendors Created
| Code | Name | Subdomain | Theme | Custom Domain |
|------|------|-----------|-------|---------------|
| WIZAMART | WizaMart | wizamart | modern | wizamart.shop |
| FASHIONHUB | Fashion Hub | fashionhub | vibrant | fashionhub.store |
| BOOKSTORE | The Book Store | bookstore | classic | (none) |
### Products Created
1. **Wireless Bluetooth Headphones** - $149.99
- Brand: AudioTech
- GTIN: 1234567890123
2. **Smart Watch Pro** - $299.99
- Brand: TechWear
- GTIN: 1234567890124
3. **Portable Bluetooth Speaker** - $79.99
- Brand: AudioTech
- GTIN: 1234567890125
4. **Wireless Charging Pad** - $39.99
- Brand: ChargeMax
- GTIN: 1234567890126
5. **4K Webcam** - $129.99
- Brand: VisionTech
- GTIN: 1234567890127
### Theme Presets Available
The seeder includes 5 built-in theme presets:
1. **default** - Indigo and purple, Inter font
2. **modern** - Blue and cyan, Poppins font, transparent header
3. **classic** - Deep blue and purple, Georgia serif font
4. **vibrant** - Pink and orange, colorful background
5. **minimal** - Black and white, Helvetica font
## Features
### 1. Idempotent Operations
- Safe to run multiple times without --reset flag
- Checks for existing records before creating
- Reports what was created vs. what already existed
### 2. Comprehensive Coverage
- Tests all major database models
- Creates realistic relationships between entities
- Includes edge cases (pending orders, completed orders, etc.)
### 3. Better Output
- Beautiful formatted output with boxes and sections
- Color-coded success/info/error messages
- Detailed summary with database statistics
- Quick reference for login credentials and URLs
### 4. Command-Line Arguments
```bash
python scripts/seed_database.py [--reset] [--minimal]
--reset : Drop all data before seeding (destructive!)
--minimal : Create only essential data (admin + 1 vendor)
```
### 5. Proper Error Handling
- Verifies database is ready before seeding
- Rolls back on errors
- Provides helpful error messages
- Suggests solutions for common issues
## Testing Access
### Admin Panel
- URL: `http://localhost:8000/admin/login`
- Username: `admin`
- Password: `admin123`
### Vendor Shops
- WIZAMART: `http://localhost:8000/shop/WIZAMART`
- FASHIONHUB: `http://localhost:8000/shop/FASHIONHUB`
- BOOKSTORE: `http://localhost:8000/shop/BOOKSTORE`
### Theme Editors
- WIZAMART Theme: `http://localhost:8000/admin/vendors/WIZAMART/theme`
- FASHIONHUB Theme: `http://localhost:8000/admin/vendors/FASHIONHUB/theme`
- BOOKSTORE Theme: `http://localhost:8000/admin/vendors/BOOKSTORE/theme`
## Example Output
```
╔════════════════════════════════════════════════════════════════════╗
║ WIZAMART DATABASE SEEDER ║
╚════════════════════════════════════════════════════════════════════╝
STEP 1: Verifying database...
✓ Database tables verified
════════════════════════════════════════════════════════════════════════
COMPREHENSIVE SEEDING
════════════════════════════════════════════════════════════════════════
STEP 1: Creating users...
✓ Admin user created (ID: 1)
✓ User 'vendor1' created (ID: 2)
✓ User 'vendor2' created (ID: 3)
✓ User 'customer1' created (ID: 4)
STEP 2: Creating vendors...
✓ WIZAMART created (ID: 1)
✓ Theme 'modern' applied
✓ Custom domain 'wizamart.shop' added
✓ FASHIONHUB created (ID: 2)
✓ Theme 'vibrant' applied
✓ Custom domain 'fashionhub.store' added
✓ BOOKSTORE created (ID: 3)
✓ Theme 'classic' applied
...
════════════════════════════════════════════════════════════════════════
SEEDING SUMMARY
════════════════════════════════════════════════════════════════════════
📊 Database Statistics:
Users: 4
Vendors: 3
Vendor Themes: 3
Custom Domains: 2
Marketplace Products: 5
Vendor Products: 10
Customers: 4
Addresses: 8
Orders: 2
Order Items: 4
Import Jobs: 2
Admin Settings: 4
Platform Alerts: 2
```
## Configuration
You can customize the seeder by editing the configuration constants at the top of the file:
```python
# Admin credentials
DEFAULT_ADMIN_EMAIL = "admin@wizamart.com"
DEFAULT_ADMIN_USERNAME = "admin"
DEFAULT_ADMIN_PASSWORD = "admin123"
# Vendor configurations
VENDOR_CONFIGS = [...]
# Test users
TEST_USERS = [...]
# Sample products
SAMPLE_PRODUCTS = [...]
# Theme presets
THEME_PRESETS = {...}
```
## Migration Path from Old Seeder
If you're currently using the old seed_database.py:
1. Backup your current seeder:
```bash
mv scripts/seed_database.py scripts/seed_database.old.py
```
2. Install new seeder:
```bash
cp seed_database.py scripts/seed_database.py
```
3. Run with minimal flag first to test:
```bash
make seed-minimal
```
4. If satisfied, run full seeding:
```bash
make seed
```
## Troubleshooting
### Error: "Database not ready"
**Solution**: Run migrations first
```bash
make migrate-up
```
### Error: "Table doesn't exist"
**Solution**: Make sure all migrations are applied
```bash
alembic upgrade head
```
### Error: "Foreign key constraint failed"
**Solution**: Reset database and try again
```bash
make seed-reset
```
### Error: Import errors
**Solution**: Make sure you're in the project root and virtual environment is activated
```bash
source venv/bin/activate # Linux/Mac
venv\Scripts\activate # Windows
```
## Best Practices
1. **Development**: Use `make seed` for full test data
2. **Quick Testing**: Use `make seed-minimal` for fast setup
3. **Fresh Start**: Use `make seed-reset` when testing migrations
4. **Production**: Never run the seeder in production!
## Security Notes
⚠️ **IMPORTANT**:
- Default passwords are simple for development convenience
- Change ALL default passwords in production environments
- The admin password is intentionally weak for local development
- Never commit sensitive credentials to version control
## Future Enhancements
Consider adding:
- More diverse product categories
- Different vendor statuses (pending, suspended)
- Customer order history variations
- Failed import jobs
- More complex inventory scenarios
- Payment transactions
- Vendor subscriptions
- Product reviews and ratings

198
docs/development/database-seeder/MAKEFILE_DATABASE_SEEDER.md Normal file
View File

@@ -0,0 +1,198 @@
# Makefile Changes - Quick Reference
## Location 1: DATABASE Section (After line 78 - after backup-db)
Add these targets:
```makefile
seed:
@echo Seeding database with comprehensive test data...
$(PYTHON) scripts/seed_database.py
@echo Seeding completed successfully
seed-minimal:
@echo Seeding database with minimal data (admin + 1 vendor)...
$(PYTHON) scripts/seed_database.py --minimal
@echo Minimal seeding completed
seed-reset:
@echo WARNING: This will DELETE ALL existing data!
$(PYTHON) scripts/seed_database.py --reset
@echo Database reset and seeded
# Complete database setup (migrate + seed)
db-setup: migrate-up seed
@echo Database setup complete!
@echo Run 'make dev' to start development server
db-reset: migrate-down migrate-up seed-reset
@echo Database completely reset!
```
## Location 2: HELP Section (Around line 270 - in DATABASE help)
Replace:
```makefile
@echo === DATABASE ===
@echo migrate-create message="msg" - Create new migration
@echo migrate-up - Apply pending migrations
@echo migrate-down - Rollback last migration
@echo migrate-status - Show migration status
@echo backup-db - Backup database
@echo.
```
With:
```makefile
@echo === DATABASE ===
@echo migrate-create message="msg" - Create new migration
@echo migrate-up - Apply pending migrations
@echo migrate-down - Rollback last migration
@echo migrate-status - Show migration status
@echo backup-db - Backup database
@echo seed - Seed database with comprehensive test data
@echo seed-minimal - Seed minimal data (admin + 1 vendor)
@echo seed-reset - Reset and seed database (destructive!)
@echo db-setup - Complete database setup (migrate + seed)
@echo db-reset - Complete database reset
@echo.
```
## Location 3: DAILY WORKFLOW Help Section (Around line 305)
Replace:
```makefile
@echo === DAILY WORKFLOW ===
@echo make dev # Start development
@echo make migrate-create message="feature" # Create migration
@echo make migrate-up # Apply migration
@echo make test # Run tests
```
With:
```makefile
@echo === DAILY WORKFLOW ===
@echo make db-setup # Setup database with data
@echo make dev # Start development
@echo make migrate-create message="feature" # Create migration
@echo make migrate-up # Apply migration
@echo make seed # Seed test data
@echo make test # Run tests
```
## Location 4: help-db target (Around line 310)
Replace:
```makefile
help-db:
@echo === DATABASE COMMANDS ===
@echo migrate-create message="description" - Create auto-generated migration
@echo migrate-create-manual message="desc" - Create empty migration template
@echo migrate-up - Apply all pending migrations
@echo migrate-down - Rollback last migration
@echo migrate-status - Show current status and history
@echo backup-db - Create database backup
@echo.
@echo TYPICAL WORKFLOW:
@echo 1. Edit your SQLAlchemy models
@echo 2. make migrate-create message="add_new_feature"
@echo 3. Review the generated migration file
@echo 4. make migrate-up
```
With:
```makefile
help-db:
@echo === DATABASE COMMANDS ===
@echo migrate-create message="description" - Create auto-generated migration
@echo migrate-create-manual message="desc" - Create empty migration template
@echo migrate-up - Apply all pending migrations
@echo migrate-down - Rollback last migration
@echo migrate-status - Show current status and history
@echo backup-db - Create database backup
@echo seed - Seed comprehensive test data
@echo seed-minimal - Seed minimal data (admin + 1 vendor)
@echo seed-reset - Reset and seed (destructive!)
@echo db-setup - Complete database setup
@echo db-reset - Complete database reset
@echo.
@echo TYPICAL WORKFLOW:
@echo 1. make db-setup # First time setup
@echo 2. Edit your SQLAlchemy models
@echo 3. make migrate-create message="add_new_feature"
@echo 4. Review the generated migration file
@echo 5. make migrate-up
@echo 6. make seed # Refresh test data if needed
```
## Update .PHONY targets (Around line 2)
Replace:
```makefile
.PHONY: install install-dev install-docs install-all dev test test-coverage lint format check docker-build docker-up docker-down clean help
```
With:
```makefile
.PHONY: install install-dev install-docs install-all dev test test-coverage lint format check docker-build docker-up docker-down clean help seed seed-minimal seed-reset db-setup db-reset
```
## Quick Copy-Paste Version
If you want to add all commands at once, here's the complete DATABASE section replacement:
```makefile
# =============================================================================
# DATABASE MIGRATIONS
# =============================================================================
migrate-create:
@if "$(message)"=="" (echo Error: Please provide a message. Usage: make migrate-create message="your_description") else ($(PYTHON) -m alembic revision --autogenerate -m "$(message)")
migrate-create-manual:
@if "$(message)"=="" (echo Error: Please provide a message. Usage: make migrate-create-manual message="your_description") else ($(PYTHON) -m alembic revision -m "$(message)")
migrate-up:
@echo Running database migrations...
$(PYTHON) -m alembic upgrade head
@echo Migrations completed successfully
migrate-down:
@echo Rolling back last migration...
$(PYTHON) -m alembic downgrade -1
@echo Rollback completed
migrate-status:
@echo Current migration status:
$(PYTHON) -m alembic current
@echo.
@echo Migration history:
$(PYTHON) -m alembic history --verbose
backup-db:
@echo Creating database backup...
@$(PYTHON) scripts/backup_database.py
seed:
@echo Seeding database with comprehensive test data...
$(PYTHON) scripts/seed_database.py
@echo Seeding completed successfully
seed-minimal:
@echo Seeding database with minimal data (admin + 1 vendor)...
$(PYTHON) scripts/seed_database.py --minimal
@echo Minimal seeding completed
seed-reset:
@echo WARNING: This will DELETE ALL existing data!
$(PYTHON) scripts/seed_database.py --reset
@echo Database reset and seeded
# Complete database setup (migrate + seed)
db-setup: migrate-up seed
@echo Database setup complete!
@echo Run 'make dev' to start development server
db-reset: migrate-down migrate-up seed-reset
@echo Database completely reset!
```