New enterprise feature

services/demo_session/README.md

@@ -23,13 +23,92 @@ The **Demo Session Service** creates ephemeral, isolated demo environments for s
 - **Suppliers** - 5+ sample supplier profiles
 - **Team Members** - Sample staff with different roles
 
-### Demo Scenarios
-- **Standard Bakery** - Small neighborhood bakery (1 location)
-- **Multi-Location** - Bakery chain (3 locations)
-- **High-Volume** - Large production bakery
-- **Custom Scenario** - Configurable for specific prospects
-- **Spanish Locale** - Madrid-based bakery examples
-- **Feature Showcase** - Highlight specific capabilities
+### Demo Scenarios (Two-Tier Architecture)
+
+**Professional Tier** (Single Bakery)
+- **Individual Bakery** - Standalone neighborhood bakery
+- **Central Production** - Central production facility (Obrador)
+- **Complete Workflow** - From raw materials to finished products
+- **Full Features** - Inventory, recipes, production, procurement, forecasting, sales
+- **Template-Based Cloning** - Instant duplication from pre-seeded parent template
+- **Data Volume**: ~3,000 records (inventory, recipes, production, orders, sales, forecasts)
+
+**Enterprise Tier** (Multi-Location Chain)
+- **Parent Obrador** - Central production facility (supplies children)
+- **3 Retail Outlets** - Madrid Centro, Barcelona Gràcia, Valencia Ruzafa
+- **Distribution Network** - VRP-optimized delivery routes (Mon/Wed/Fri)
+- **Hierarchical Structure** - Parent produces, children sell finished products only
+- **Cross-Location Analytics** - Aggregate forecasting, distribution planning
+- **Advanced Features** - Enterprise dashboard, multi-location inventory, route optimization
+- **Data Volume**: ~10,000 records (parent + 3 children + distribution history)
+
+### Demo Seeding Architecture
+
+**Two-Phase Template System**
+
+Phase 1: **Parent Template Creation** (Kubernetes Init Jobs)
+- 15 parent seed jobs create base template data for both Professional and Enterprise parent tenants
+- Execution order controlled by Helm hook weights (10-15)
+- Jobs run once during cluster initialization/upgrade
+- Professional parent: `a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6` (Individual Bakery)
+- Enterprise parent: `c3d4e5f6-a7b8-49c0-d1e2-f3a4b5c6d7e8` (Obrador Madrid)
+
+Parent Seeds (Hook Weight 10-15):
+1. Tenants (weight 10) - Base tenant configuration
+2. Subscription Plans (weight 11) - Professional/Enterprise tier definitions
+3. Tenant Members (weight 12) - Admin users and roles
+4. Suppliers (weight 12) - Raw material providers
+5. Inventory Products (weight 13) - Raw ingredients + finished products
+6. Recipes (weight 13) - Production formulas and BOMs
+7. Equipment (weight 13) - Ovens, mixers, packaging machines
+8. Quality Templates (weight 13) - QA checkpoints
+9. Stock (weight 14) - Initial inventory levels
+10. Production Batches (weight 14) - Historical production runs
+11. POS Configs (weight 14) - Point-of-sale settings
+12. Forecasts (weight 14) - Demand predictions
+13. Procurement Plans (weight 14) - Supplier ordering strategies
+14. Purchase Orders (weight 14) - Historical procurement
+15. Orders, Customers, Sales, Orchestration Runs, AI Models, Alerts (weight 15)
+
+Phase 2: **Child Retail Template Seeding** (Kubernetes Jobs, Hook Weight 50-57)
+- 8 child seed jobs create retail outlet data for 3 enterprise child tenants
+- Executes AFTER all parent seeds complete
+- Creates retail-specific data (finished products only, no raw ingredients)
+- Child tenants:
+  - `d4e5f6a7-b8c9-40d1-e2f3-a4b5c6d7e8f9` (Madrid Centro)
+  - `e5f6a7b8-c9d0-41e2-f3a4-b5c6d7e8f9a0` (Barcelona Gràcia)
+  - `f6a7b8c9-d0e1-42f3-a4b5-c6d7e8f9a0b1` (Valencia Ruzafa)
+
+Child Retail Seeds (Hook Weight 50-57):
+1. Inventory Retail (weight 50) - Finished products catalog
+2. Stock Retail (weight 51) - Retail inventory levels
+3. Orders Retail (weight 52) - Customer orders
+4. Customers Retail (weight 53) - Retail customer database
+5. Sales Retail (weight 54) - Sales transactions
+6. Forecasts Retail (weight 55) - Store-level demand forecasts
+7. Alerts Retail (weight 56) - Stockout/low-stock alerts
+8. Distribution History (weight 57) - 30 days of Obrador→retail deliveries
+
+**ID Transformation Pattern**
+- **XOR Transformation**: `tenant_specific_id = UUID(int=tenant_id_int ^ base_id_int)`
+- Ensures deterministic, unique IDs across parent and child tenants
+- Maintains referential integrity for related records
+- Used for: inventory products, recipes, equipment, batches, etc.
+
+**Temporal Consistency**
+- **BASE_REFERENCE_DATE**: January 8, 2025, 06:00 UTC
+- All demo data anchored to this reference point
+- Ensures consistent time-based queries and dashboards
+- Historical data: 30-90 days before BASE_REFERENCE_DATE
+- Future forecasts: 14-30 days after BASE_REFERENCE_DATE
+
+**Runtime Cloning** (CloneOrchestrator)
+- When a demo session is created, CloneOrchestrator duplicates template data
+- New tenant ID generated for the demo session
+- All related records cloned with updated tenant_id
+- XOR transformation applied to maintain relationships
+- Typical clone time: 2-5 seconds for Professional, 8-15 seconds for Enterprise
+- Isolated demo environment - changes don't affect template
 
 ### Session Management
 - **Auto-Expiration** - Automatic cleanup after expiry