docs: add seed scripts audit and Makefile refactoring documentation
- Create comprehensive seed scripts audit document - Inventory of all seed/create scripts - Analysis of current vs intended workflow - Identification of duplicates and orphaned scripts - Refactoring recommendations - Create Makefile refactoring completion document - Summary of architecture decisions - Before/after comparison - Updated workflows for production and development - Script classification (production, demo, utility, test) - New developer onboarding workflow - Production deployment workflow Documentation provides clear guidance on: - Which scripts to run in production vs development - How init-prod differs from seed-demo - When to use utility commands - Proper setup workflow for new developers
This commit is contained in:
240
docs/development/seed-scripts-audit.md
Normal file
240
docs/development/seed-scripts-audit.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# Seed Scripts Audit & Refactoring Plan
|
||||
|
||||
**Date:** 2025-12-01
|
||||
**Status:** ✅ REFACTORING COMPLETE
|
||||
|
||||
**Implementation:** See `makefile-refactoring-complete.md` for details
|
||||
|
||||
## Current State Analysis
|
||||
|
||||
### 📊 Inventory of Seed Scripts
|
||||
|
||||
| Script | Purpose | In Makefile? | Issues |
|
||||
|--------|---------|--------------|--------|
|
||||
| `seed_demo.py` | Create companies, vendors, customers, products | ✅ Yes | ❌ Missing inventory creation |
|
||||
| `create_default_content_pages.py` | Create platform CMS pages (about, faq, etc.) | ✅ Yes (`create-cms-defaults`) | ✅ Good |
|
||||
| `create_inventory.py` | Create inventory for products | ❌ **NO** | ⚠️ Should be in seed_demo |
|
||||
| `create_landing_page.py` | Create landing pages for vendors | ❌ **NO** | ⚠️ Should be in seed_demo |
|
||||
| `create_platform_pages.py` | Create platform pages | ❌ **NO** | 🔴 **DUPLICATE** of create_default_content_pages |
|
||||
| `init_production.py` | Create admin user + platform alerts | ✅ Yes (`init-prod`) | ✅ Good |
|
||||
| `init_log_settings.py` | Initialize log settings | ❌ NO | ⚠️ Should be in init_production? |
|
||||
|
||||
### 🎯 Intended Database Setup Flow (from Makefile)
|
||||
|
||||
```bash
|
||||
make db-setup
|
||||
↓
|
||||
1. migrate-up # Run Alembic migrations
|
||||
2. init-prod # Create admin user + alerts
|
||||
3. create-cms-defaults # Create default content pages
|
||||
4. seed-demo # Create demo companies/vendors/data
|
||||
```
|
||||
|
||||
## 🔴 Problems Identified
|
||||
|
||||
### 1. **Missing Functionality in seed_demo.py**
|
||||
`seed_demo.py` creates products but NOT inventory:
|
||||
- ❌ Products are created without inventory records
|
||||
- ❌ Vendors can't manage stock
|
||||
- ❌ Separate `create_inventory.py` script exists but not integrated
|
||||
|
||||
### 2. **Duplicate Scripts**
|
||||
- `create_platform_pages.py` duplicates `create_default_content_pages.py`
|
||||
- Both create platform-level content pages
|
||||
- Causes confusion about which to use
|
||||
|
||||
### 3. **Orphaned Scripts (Not in Makefile)**
|
||||
Scripts that exist but aren't part of the standard workflow:
|
||||
- `create_inventory.py` - Should be integrated into seed_demo
|
||||
- `create_landing_page.py` - Should be integrated into seed_demo
|
||||
- `create_platform_pages.py` - Should be deleted (duplicate)
|
||||
- `init_log_settings.py` - Should be in init_production or separate command
|
||||
|
||||
### 4. **Missing Landing Pages in seed_demo**
|
||||
The seed creates vendors but not their landing pages:
|
||||
- Vendors have no homepage
|
||||
- Manual script required (`create_landing_page.py`)
|
||||
- Should be automatic in demo seeding
|
||||
|
||||
## ✅ Proposed Refactoring Plan
|
||||
|
||||
### Phase 1: Consolidate seed_demo.py (HIGH PRIORITY)
|
||||
|
||||
**Update `seed_demo.py` to include:**
|
||||
```python
|
||||
def seed_demo_data(db: Session, auth_manager: AuthManager):
|
||||
# Step 1-3: Existing (environment, admin, reset)
|
||||
# Step 4: Create companies ✅ DONE
|
||||
# Step 5: Create vendors ✅ DONE
|
||||
# Step 6: Create customers ✅ DONE
|
||||
# Step 7: Create products ✅ DONE
|
||||
# Step 8: Create inventory ❌ ADD THIS
|
||||
# Step 9: Create landing pages ❌ ADD THIS
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ One command seeds everything
|
||||
- ✅ Consistent demo environment
|
||||
- ✅ Vendors immediately usable
|
||||
|
||||
### Phase 2: Clean Up Duplicate Scripts
|
||||
|
||||
**Delete:**
|
||||
- ❌ `create_platform_pages.py` (duplicate of create_default_content_pages.py)
|
||||
|
||||
**Keep:**
|
||||
- ✅ `create_default_content_pages.py` (used in Makefile)
|
||||
|
||||
### Phase 3: Integrate or Document Orphaned Scripts
|
||||
|
||||
**Option A: Integrate into seed_demo**
|
||||
```python
|
||||
# In seed_demo.py
|
||||
def create_demo_inventory(db, vendors):
|
||||
"""Create inventory for all products"""
|
||||
# Move logic from create_inventory.py
|
||||
|
||||
def create_demo_landing_pages(db, vendors):
|
||||
"""Create landing pages for vendors"""
|
||||
# Move logic from create_landing_page.py
|
||||
```
|
||||
|
||||
**Option B: Make them utility scripts**
|
||||
Move to `scripts/utils/` and document:
|
||||
```bash
|
||||
# For one-off tasks
|
||||
python scripts/utils/create_inventory.py
|
||||
python scripts/utils/create_landing_page.py [vendor_subdomain]
|
||||
```
|
||||
|
||||
### Phase 4: Update Makefile
|
||||
|
||||
**Add new commands:**
|
||||
```makefile
|
||||
# Full setup with inventory
|
||||
seed-demo-full:
|
||||
$(PYTHON) scripts/seed_demo.py --include-inventory --include-landing
|
||||
|
||||
# Utility commands (if keeping separate)
|
||||
create-inventory:
|
||||
$(PYTHON) scripts/create_inventory.py
|
||||
|
||||
init-logging:
|
||||
$(PYTHON) scripts/init_log_settings.py
|
||||
```
|
||||
|
||||
## 📋 Recommended File Structure
|
||||
|
||||
```
|
||||
scripts/
|
||||
├── Core Setup (Run in Order)
|
||||
│ ├── init_production.py # 1. Create admin + platform config
|
||||
│ ├── init_log_settings.py # 2. Configure logging (or merge into init_production)
|
||||
│ └── seed_demo.py # 3. Seed demo data (EVERYTHING)
|
||||
│
|
||||
├── CMS Setup
|
||||
│ └── create_default_content_pages.py # Platform CMS defaults
|
||||
│
|
||||
├── Utilities (One-off/Manual)
|
||||
│ ├── create_inventory.py # ⚠️ Should be in seed_demo
|
||||
│ ├── create_landing_page.py # ⚠️ Should be in seed_demo
|
||||
│ ├── backup_database.py
|
||||
│ └── verify_setup.py
|
||||
│
|
||||
├── Testing
|
||||
│ ├── test_auth_complete.py
|
||||
│ ├── test_vendor_management.py
|
||||
│ └── test_logging_system.py
|
||||
│
|
||||
├── Diagnostics
|
||||
│ ├── route_diagnostics.py
|
||||
│ ├── show_structure.py
|
||||
│ └── validate_architecture.py
|
||||
│
|
||||
└── TO DELETE
|
||||
└── create_platform_pages.py # 🔴 DUPLICATE
|
||||
```
|
||||
|
||||
## 🎯 Implementation Priority
|
||||
|
||||
### Immediate (Do Now)
|
||||
1. ✅ **Add inventory creation to seed_demo.py**
|
||||
- Move logic from `create_inventory.py`
|
||||
- Create `create_demo_inventory()` function
|
||||
|
||||
2. ✅ **Add landing page creation to seed_demo.py**
|
||||
- Move logic from `create_landing_page.py`
|
||||
- Create `create_demo_landing_pages()` function
|
||||
|
||||
3. ❌ **Delete `create_platform_pages.py`**
|
||||
- It's a duplicate
|
||||
|
||||
### Soon (This Week)
|
||||
4. ⚠️ **Decide on `init_log_settings.py`**
|
||||
- Merge into `init_production.py`, OR
|
||||
- Add to Makefile as separate step
|
||||
|
||||
5. ⚠️ **Update Makefile documentation**
|
||||
- Document all seed commands
|
||||
- Update help text
|
||||
|
||||
### Later (Nice to Have)
|
||||
6. 📝 **Create `scripts/utils/` directory**
|
||||
- Move utility scripts
|
||||
- Update documentation
|
||||
|
||||
7. 📝 **Add --options to seed_demo.py**
|
||||
```bash
|
||||
python scripts/seed_demo.py --skip-inventory
|
||||
python scripts/seed_demo.py --minimal
|
||||
python scripts/seed_demo.py --help
|
||||
```
|
||||
|
||||
## 🚀 Expected Result After Refactoring
|
||||
|
||||
**Single Command Setup:**
|
||||
```bash
|
||||
# Developer onboarding
|
||||
make db-setup
|
||||
|
||||
# What happens:
|
||||
# 1. ✅ Migrations applied
|
||||
# 2. ✅ Admin user created
|
||||
# 3. ✅ Platform CMS pages created
|
||||
# 4. ✅ 3 demo companies created
|
||||
# 5. ✅ 3 demo vendors created (1 per company)
|
||||
# 6. ✅ 15 customers per vendor
|
||||
# 7. ✅ 20 products per vendor
|
||||
# 8. ✅ Inventory for all products ← NEW
|
||||
# 9. ✅ Landing pages for all vendors ← NEW
|
||||
# 10. ✅ Ready to code!
|
||||
```
|
||||
|
||||
**Result:**
|
||||
- 🎯 Consistent, reproducible demo environment
|
||||
- 🎯 No manual steps required
|
||||
- 🎯 New developers up and running in seconds
|
||||
- 🎯 All features immediately testable
|
||||
|
||||
## 📝 Questions to Answer
|
||||
|
||||
1. **Should init_log_settings be part of init_production?**
|
||||
- Pro: One less manual step
|
||||
- Con: Logging is separate concern
|
||||
|
||||
2. **Keep create_inventory.py as utility or delete?**
|
||||
- If integrated into seed_demo, do we need the standalone script?
|
||||
- Use case: Fix inventory for existing vendors?
|
||||
|
||||
3. **Keep create_landing_page.py as utility or delete?**
|
||||
- If integrated into seed_demo, do we need the standalone script?
|
||||
- Use case: Create landing page for new vendor post-seed?
|
||||
|
||||
## 🎬 Next Actions
|
||||
|
||||
- [ ] Review this audit with team
|
||||
- [ ] Decide on orphaned scripts
|
||||
- [ ] Implement Phase 1 (add inventory + landing to seed_demo)
|
||||
- [ ] Delete create_platform_pages.py
|
||||
- [ ] Update Makefile
|
||||
- [ ] Update developer documentation
|
||||
Reference in New Issue
Block a user