feat: Add scripts for managing merchant settings data

- Created `export_sample_data.py` to export merchant settings to JSON format.
- Developed `manage_db.py` for database initialization and verification commands.
- Implemented `sample_records.py` for inserting, viewing, and clearing sample merchant settings data.

DATABASE_SCHEMA.py

@@ -0,0 +1,119 @@
+"""
+Database Schema Documentation
+Shows the structure of the merchant_settings collection.
+"""
+
+MERCHANT_SETTINGS_SCHEMA = {
+    "collection": "scm_merchant_settings",
+    "description": "Merchant-specific configuration settings",
+    
+    "indexes": [
+        {"name": "merchant_id_unique", "type": "unique", "fields": ["merchant_id"], "description": "Ensures one settings record per merchant"},
+        {"name": "is_active_index", "type": "single", "fields": ["is_active"], "description": "Quick filtering by active status"},
+        {"name": "active_merchant_index", "type": "compound", "fields": ["is_active", "merchant_id"], "description": "Combined active merchant queries"},
+        {"name": "created_at_index", "type": "single", "fields": ["created_at"], "description": "Sorting by creation time"},
+        {"name": "updated_at_index", "type": "single", "fields": ["updated_at"], "description": "Sorting by update time"},
+        {"name": "created_by_index", "type": "single", "fields": ["created_by"], "description": "Audit queries by creator"},
+        {"name": "updated_by_index", "type": "single", "fields": ["updated_by"], "description": "Audit queries by updater"},
+        {"name": "audit_created_index", "type": "compound", "fields": ["created_by", "created_at"], "description": "Audit trail queries"},
+        {"name": "notifications_index", "type": "compound", "fields": ["email_notifications", "sms_notifications", "is_active"], "description": "Notification preference queries"},
+        {"name": "inventory_settings_index", "type": "compound", "fields": ["auto_allocate_stock", "enable_backorder", "auto_reorder", "is_active"], "description": "Inventory configuration queries"}
+    ],
+    
+    "validation": {
+        "required_fields": ["merchant_id", "created_by", "created_at", "is_active"],
+        "field_types": {
+            "merchant_id": "string",
+            "auto_allocate_stock": "bool",
+            "credit_limit": "double|null (>= 0)",
+            "payment_terms_days": "int (0-365)",
+            "low_stock_threshold": "int (>= 0)",
+            "enable_backorder": "bool",
+            "auto_reorder": "bool",
+            "email_notifications": "bool",
+            "sms_notifications": "bool",
+            "low_stock_alerts": "bool",
+            "order_status_updates": "bool",
+            "operating_hours": "object|null",
+            "default_markup_percentage": "double|null (0-1000)",
+            "allow_discount": "bool",
+            "max_discount_percentage": "double|null (0-100)",
+            "tax_settings": "object|null",
+            "is_active": "bool",
+            "created_by": "string",
+            "created_at": "date",
+            "updated_by": "string|null",
+            "updated_at": "date|null",
+            "custom_fields": "object|null"
+        }
+    },
+    
+    "example_document": {
+        "merchant_id": "mch_01HZQX5K3N2P8R6T4V9W",
+        "auto_allocate_stock": True,
+        "credit_limit": 500000.0,
+        "payment_terms_days": 30,
+        "low_stock_threshold": 10,
+        "enable_backorder": False,
+        "auto_reorder": True,
+        "email_notifications": True,
+        "sms_notifications": False,
+        "low_stock_alerts": True,
+        "order_status_updates": True,
+        "operating_hours": {
+            "monday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+            "tuesday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+            "wednesday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+            "thursday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+            "friday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+            "saturday": {"is_open": True, "open_time": "09:00", "close_time": "14:00"},
+            "sunday": {"is_open": False}
+        },
+        "default_markup_percentage": 25.0,
+        "allow_discount": True,
+        "max_discount_percentage": 10.0,
+        "tax_settings": {
+            "gst_rate": 18.0,
+            "inclusive_pricing": True,
+            "tax_exemption": False
+        },
+        "is_active": True,
+        "created_by": "admin_001",
+        "created_at": "2024-11-30T12:00:00Z",
+        "updated_by": "admin_001", 
+        "updated_at": "2024-11-30T15:30:00Z",
+        "custom_fields": {
+            "region": "Mumbai",
+            "category": "premium"
+        }
+    }
+}
+
+def print_schema_info():
+    """Print formatted schema information."""
+    schema = MERCHANT_SETTINGS_SCHEMA
+    
+    print("=" * 60)
+    print(f"MongoDB Collection: {schema['collection']}")
+    print(f"Description: {schema['description']}")
+    print("=" * 60)
+    
+    print("\n📊 INDEXES:")
+    for idx in schema['indexes']:
+        print(f"  • {idx['name']} ({idx['type']})")
+        print(f"    Fields: {idx['fields']}")
+        print(f"    Purpose: {idx['description']}")
+        print()
+    
+    print("🔒 VALIDATION RULES:")
+    print(f"  Required Fields: {', '.join(schema['validation']['required_fields'])}")
+    print("\n  Field Types:")
+    for field, field_type in schema['validation']['field_types'].items():
+        print(f"    • {field}: {field_type}")
+    
+    print("\n📄 EXAMPLE DOCUMENT:")
+    import json
+    print(json.dumps(schema['example_document'], indent=2))
+
+if __name__ == "__main__":
+    print_schema_info()

HIERARCHICAL_DATA_STRUCTURE.md

@@ -0,0 +1,300 @@
+# Hierarchical Merchant Data Structure
+
+This document describes the complete hierarchical merchant ecosystem created for the SCM system.
+
+## Data Collections Created
+
+### 1. scm_merchants
+**Parent Company → CNF → Distributors → Salons hierarchy**
+
+#### Parent Company (1)
+- **Cuatro Beauty Limited** (`company_cuatro_beauty_ltd`)
+  - Type: `parent_company`
+  - Code: `CUATRO-HQ`
+  - Location: Mumbai, Maharashtra
+  - GST: `27AAPCU0939F1ZV`
+
+#### CNFs (3) - Regional Distribution Centers
+- **North India Beauty Hub CNF** (`cnf_north_india_hub`)
+  - Parent: `company_cuatro_beauty_ltd`
+  - Code: `CNF-NORTH-001`
+  - Location: Gurgaon, Haryana
+  
+- **South India Beauty Hub CNF** (`cnf_south_india_hub`)
+  - Parent: `company_cuatro_beauty_ltd`
+  - Code: `CNF-SOUTH-001`
+  - Location: Chennai, Tamil Nadu
+  
+- **West India Beauty Hub CNF** (`cnf_west_india_hub`)
+  - Parent: `company_cuatro_beauty_ltd`
+  - Code: `CNF-WEST-001`
+  - Location: Mumbai, Maharashtra
+
+#### Distributors (6) - Regional Distribution Partners
+**North India CNF Distributors:**
+- **Delhi Premium Beauty Distributors** (`dist_delhi_premium`)
+  - Parent: `cnf_north_india_hub`
+  - Code: `DIST-DEL-001`
+  - Location: New Delhi
+  
+- **Punjab Beauty Wholesale Hub** (`dist_punjab_wholesale`)
+  - Parent: `cnf_north_india_hub`
+  - Code: `DIST-PB-001`
+  - Location: Ludhiana, Punjab
+
+**South India CNF Distributors:**
+- **Chennai Elite Beauty Distribution** (`dist_chennai_elite`)
+  - Parent: `cnf_south_india_hub`
+  - Code: `DIST-CHN-001`
+  - Location: Chennai, Tamil Nadu
+  
+- **Bangalore Metro Beauty Supplies** (`dist_bangalore_metro`)
+  - Parent: `cnf_south_india_hub`
+  - Code: `DIST-BLR-001`
+  - Location: Bangalore, Karnataka
+
+**West India CNF Distributors:**
+- **Mumbai Central Beauty Distribution** (`dist_mumbai_central`)
+  - Parent: `cnf_west_india_hub`
+  - Code: `DIST-MUM-001`
+  - Location: Mumbai, Maharashtra
+  
+- **Pune Premium Beauty Hub** (`dist_pune_premium`)
+  - Parent: `cnf_west_india_hub`
+  - Code: `DIST-PUN-001`
+  - Location: Pune, Maharashtra
+
+#### Salons (9) - End Customers
+**Delhi Distributor Salons:**
+- **Connaught Place Luxury Salon** (`salon_delhi_cp_luxury`)
+  - Parent: `dist_delhi_premium`
+  - Code: `SALON-DEL-001`
+  
+- **Khan Market Beauty Studio** (`salon_delhi_khan_market`)
+  - Parent: `dist_delhi_premium`
+  - Code: `SALON-DEL-002`
+
+**Punjab Distributor Salons:**
+- **Model Town Beauty Parlour** (`salon_ludhiana_model_town`)
+  - Parent: `dist_punjab_wholesale`
+  - Code: `SALON-LDH-001`
+
+**Chennai Distributor Salons:**
+- **T.Nagar Glamour Studio** (`salon_chennai_tnagar`)
+  - Parent: `dist_chennai_elite`
+  - Code: `SALON-CHN-001`
+  
+- **Express Avenue Beauty Lounge** (`salon_chennai_express_avenue`)
+  - Parent: `dist_chennai_elite`
+  - Code: `SALON-CHN-002`
+
+**Bangalore Distributor Salons:**
+- **Brigade Road Style Studio** (`salon_bangalore_brigade_road`)
+  - Parent: `dist_bangalore_metro`
+  - Code: `SALON-BLR-001`
+
+**Mumbai Distributor Salons:**
+- **Linking Road Fashion Salon** (`salon_mumbai_linking_road`)
+  - Parent: `dist_mumbai_central`
+  - Code: `SALON-MUM-001`
+  
+- **Colaba Causeway Beauty Hub** (`salon_mumbai_colaba`)
+  - Parent: `dist_mumbai_central`
+  - Code: `SALON-MUM-002`
+
+**Pune Distributor Salons:**
+- **Koregaon Park Elite Salon** (`salon_pune_koregaon_park`)
+  - Parent: `dist_pune_premium`
+  - Code: `SALON-PUN-001`
+
+### 2. scm_access_roles (6 Roles)
+
+#### Role Hierarchy & Permissions
+- **Super Administrator** (`role_super_admin`)
+  - Full system access
+  - All permissions including DELETE operations
+  
+- **Company Administrator** (`role_company_admin`)
+  - Company-wide management
+  - No DELETE permissions for security
+  
+- **CNF Manager** (`role_cnf_manager`)
+  - Regional operations management
+  - Can create distributors
+  
+- **Distributor Manager** (`role_distributor_manager`)
+  - Local distribution operations
+  - Can create salons
+  
+- **Salon Owner** (`role_salon_owner`)
+  - Salon management and operations
+  - Can place orders
+  
+- **Salon Staff** (`role_salon_staff`)
+  - Basic operations only
+  - Read-only access
+
+### 3. scm_system_users (20 Users)
+
+#### Administrative Users
+- **Super Admin**: `superadmin` / `SuperAdmin@123`
+- **Company Admin**: `companyadmin` / `CompanyAdmin@123`
+
+#### CNF Managers
+- **North**: `cnfmanager_north` / `CNFManager@123` (Rajesh Kumar)
+- **South**: `cnfmanager_south` / `CNFManager@123` (Suresh Reddy)  
+- **West**: `cnfmanager_west` / `CNFManager@123` (Amit Sharma)
+
+#### Distributor Managers
+- **Delhi**: `distmanager_delhi` / `DistManager@123` (Vikram Singh)
+- **Punjab**: `distmanager_punjab` / `DistManager@123` (Hardeep Singh)
+- **Chennai**: `distmanager_chennai` / `DistManager@123` (Ramesh Kumar)
+- **Bangalore**: `distmanager_bangalore` / `DistManager@123` (Srinivas Rao)
+- **Mumbai**: `distmanager_mumbai` / `DistManager@123` (Rohit Patil)
+- **Pune**: `distmanager_pune` / `DistManager@123` (Pradeep Joshi)
+
+#### Salon Owners (9 users with role `role_salon_owner`)
+- Individual credentials: `SalonOwner@123`
+
+### 4. scm_merchant_settings (19 Settings)
+
+#### Settings by Merchant Type
+
+**Parent Company Settings:**
+- No credit limit
+- 0% markup (cost price)
+- No discounts allowed
+- Business hours: Mon-Fri 9:00-18:00
+
+**CNF Settings:**
+- Credit Limit: ₹1 Crore
+- Payment Terms: 90 days
+- Markup: 5%
+- Max Discount: 2%
+- Operating Hours: Mon-Sat 7:00-19:00
+
+**Distributor Settings:**
+- Credit Limit: ₹20L-50L (based on region)
+- Payment Terms: 60 days
+- Markup: 15%
+- Max Discount: 7%
+- Operating Hours: Mon-Sat 8:00-18:00
+
+**Salon Settings:**
+- Credit Limit: ₹2L-8L (based on category)
+- Payment Terms: 15-30 days
+- Markup: 25-35% (based on category)
+- Max Discount: 15-20%
+- Operating Hours: Mon-Sun 9:00-22:00
+
+## Hierarchy Visualization
+
+```
+Cuatro Beauty Limited (Parent Company)
+├── North India CNF
+│   ├── Delhi Premium Distributors
+│   │   ├── CP Luxury Salon
+│   │   └── Khan Market Beauty Studio
+│   └── Punjab Wholesale Hub
+│       └── Model Town Beauty Parlour
+├── South India CNF
+│   ├── Chennai Elite Distribution
+│   │   ├── T.Nagar Glamour Studio
+│   │   └── Express Avenue Beauty Lounge
+│   └── Bangalore Metro Supplies
+│       └── Brigade Road Style Studio
+└── West India CNF
+    ├── Mumbai Central Distribution
+    │   ├── Linking Road Fashion Salon
+    │   └── Colaba Causeway Beauty Hub
+    └── Pune Premium Hub
+        └── Koregaon Park Elite Salon
+```
+
+## Usage Examples
+
+### API Testing with Hierarchy Data
+
+1. **Start FastAPI Server:**
+   ```bash
+   uvicorn app.main:app --reload
+   ```
+
+2. **Access API Documentation:**
+   ```
+   http://localhost:8000/docs
+   ```
+
+3. **Test Merchant Hierarchy Endpoints:**
+   - Get all merchants: `GET /merchants/`
+   - Get CNF merchants: `GET /merchants/?merchant_type=cnf`
+   - Get child merchants: `GET /merchants/children/{parent_merchant_id}`
+   - Get merchant settings: `GET /merchant-settings/{merchant_id}`
+
+### Database Queries
+
+**Get complete hierarchy for a CNF:**
+```javascript
+db.scm_merchants.find({"parent_merchant_id": "cnf_north_india_hub"})
+```
+
+**Get all salons under a specific distributor:**
+```javascript
+db.scm_merchants.find({
+  "parent_merchant_id": "dist_delhi_premium",
+  "merchant_type": "salon"
+})
+```
+
+**Get users by role:**
+```javascript
+db.scm_system_users.find({"role_id": "role_cnf_manager"})
+```
+
+## Business Logic Implementation
+
+### Credit Limits by Type
+- **Parent Company**: No limit (unlimited)
+- **CNF**: ₹1 Crore (high volume wholesale)
+- **Distributor**: ₹20L-50L (regional wholesale)
+- **Salon**: ₹2L-8L (retail based on category)
+
+### Markup Strategy
+- **Parent Company**: 0% (cost price)
+- **CNF**: 5% (minimal margin for operations)
+- **Distributor**: 15% (wholesale margin)
+- **Salon**: 25-35% (retail margin based on premium level)
+
+### Operating Hours
+- **Corporate**: Business hours (9-6)
+- **CNF**: Extended hours (7-7) for operations
+- **Distributor**: Business hours (8-6)
+- **Salon**: Customer hours (9-10 PM, 7 days)
+
+## Data Management Commands
+
+```bash
+# Create complete hierarchy
+python3 create_hierarchy.py create
+
+# Verify created data
+python3 create_hierarchy.py verify
+
+# Show help
+python3 create_hierarchy.py help
+```
+
+## Security & Authentication
+
+- **Password Hashing**: SHA256 (production should use bcrypt)
+- **Role-Based Access**: Hierarchical permissions
+- **Merchant Isolation**: Users can only access their merchant and children
+- **API Authentication**: JWT token-based (implement as needed)
+
+## Next Steps
+
+1. **API Integration Testing**: Test all endpoints with hierarchical data
+2. **Business Logic Validation**: Verify credit limits and permissions
+3. **Reporting Queries**: Implement hierarchy-aware reporting
+4. **Data Relationships**: Add foreign key validation in application layer
+5. **Performance Optimization**: Add database indexes for hierarchy queries

MERCHANT_SETTINGS_README.md

@@ -165,8 +165,75 @@ PATCH /merchant-settings/mch_123/operating-hours
 - Extensible for future requirements
 - Follows microservice patterns
 
+## Database Setup
+
+### Collection Structure
+- **Collection Name**: `scm_merchant_settings`
+- **Database**: MongoDB with schema validation
+- **Indexes**: 11 optimized indexes for performance
+
+### Initialize Database
+Run the database initialization script to create the collection and indexes:
+
+```bash
+# Initialize database structure
+python3 manage_db.py init-db
+
+# Verify database setup
+python3 manage_db.py verify-db
+```
+
+### Collection Features
+- **Schema Validation**: MongoDB validates all documents against the defined schema
+- **Unique Constraint**: Only one settings record per merchant (`merchant_id_unique` index)
+- **Performance Indexes**: Optimized for common query patterns
+- **Audit Trail**: Tracks creation and update history with user information
+
+### Key Indexes
+- `merchant_id_unique` - Ensures one settings per merchant
+- `is_active_index` - Fast filtering by active status
+- `active_merchant_index` - Combined queries for active merchants
+- `notifications_index` - Notification preference queries
+- `inventory_settings_index` - Inventory configuration queries
+- `audit_created_index` - Audit trail queries
+
 ## Testing
 - Use the FastAPI docs at `/docs` to test endpoints
 - Ensure MongoDB is running and connected
+- Initialize database: `python3 manage_db.py init-db`
 - Create a merchant first before creating settings
-- Test with valid JWT tokens for authentication
+- Test with valid JWT tokens for authentication
+
+## Database Commands
+```bash
+# Initialize database collections and indexes
+python3 manage_db.py init-db
+
+# Verify database structure
+python3 manage_db.py verify-db
+
+# View database schema documentation
+python3 DATABASE_SCHEMA.py
+```
+
+## Sample Data Management
+```bash
+# Insert sample merchant settings records (5 realistic examples)
+python3 sample_records.py insert
+
+# View sample records in terminal
+python3 sample_records.py view
+
+# Export sample data to JSON file
+python3 export_sample_data.py
+
+# Clear all sample data
+python3 sample_records.py clear
+```
+
+### Sample Records Include:
+1. **Premium Salon (Mumbai)** - High-end salon with full features
+2. **Distributor (Delhi)** - Wholesale distributor with large credit limit
+3. **Standard Salon (Bangalore)** - Regular salon with standard settings
+4. **CNF (Chennai)** - Carrying & Forwarding agent with enterprise settings
+5. **Budget Salon (Pune)** - Small salon with basic configuration (inactive for testing)

SAMPLE_RECORDS.md

@@ -0,0 +1,176 @@
+# Sample Merchant Settings Records
+
+This document shows the 5 sample merchant settings records that have been created for testing and demonstration.
+
+## Quick Summary
+
+| Merchant ID | Type | Region | Credit Limit | Status | Category |
+|-------------|------|--------|--------------|--------|----------|
+| mch_salon_mumbai_001 | Salon | Mumbai | ₹2,50,000 | 🟢 Active | Premium |
+| mch_distributor_delhi_001 | Distributor | Delhi | ₹20,00,000 | 🟢 Active | Wholesale |
+| mch_salon_bangalore_002 | Salon | Bangalore | ₹1,50,000 | 🟢 Active | Standard |
+| mch_cnf_chennai_001 | CNF | Chennai | ₹50,00,000 | 🟢 Active | Enterprise |
+| mch_salon_pune_003 | Salon | Pune | ₹1,00,000 | 🔴 Inactive | Budget |
+
+## Detailed Record Examples
+
+### 1. Premium Salon (Mumbai) - `mch_salon_mumbai_001`
+```json
+{
+  "merchant_id": "mch_salon_mumbai_001",
+  "auto_allocate_stock": true,
+  "credit_limit": 250000.0,
+  "payment_terms_days": 15,
+  "low_stock_threshold": 5,
+  "enable_backorder": false,
+  "auto_reorder": true,
+  "email_notifications": true,
+  "sms_notifications": true,
+  "low_stock_alerts": true,
+  "order_status_updates": true,
+  "operating_hours": {
+    "monday": {"is_open": true, "open_time": "10:00", "close_time": "20:00"},
+    "friday": {"is_open": true, "open_time": "10:00", "close_time": "21:00"},
+    "saturday": {"is_open": true, "open_time": "09:00", "close_time": "22:00"},
+    "sunday": {"is_open": true, "open_time": "11:00", "close_time": "20:00"}
+  },
+  "default_markup_percentage": 30.0,
+  "allow_discount": true,
+  "max_discount_percentage": 15.0,
+  "tax_settings": {
+    "gst_rate": 18.0,
+    "inclusive_pricing": true,
+    "tax_exemption": false
+  },
+  "custom_fields": {
+    "region": "Mumbai",
+    "category": "premium",
+    "loyalty_program": true,
+    "online_booking": true
+  }
+}
+```
+
+### 2. Wholesale Distributor (Delhi) - `mch_distributor_delhi_001`
+```json
+{
+  "merchant_id": "mch_distributor_delhi_001",
+  "auto_allocate_stock": false,
+  "credit_limit": 2000000.0,
+  "payment_terms_days": 45,
+  "low_stock_threshold": 50,
+  "enable_backorder": true,
+  "auto_reorder": false,
+  "email_notifications": true,
+  "sms_notifications": false,
+  "operating_hours": {
+    "monday": {"is_open": true, "open_time": "08:00", "close_time": "18:00"},
+    "saturday": {"is_open": true, "open_time": "09:00", "close_time": "16:00"},
+    "sunday": {"is_open": false}
+  },
+  "default_markup_percentage": 12.0,
+  "allow_discount": true,
+  "max_discount_percentage": 5.0,
+  "tax_settings": {
+    "gst_rate": 18.0,
+    "inclusive_pricing": false,
+    "tax_exemption": false
+  },
+  "custom_fields": {
+    "region": "North India",
+    "category": "wholesale",
+    "warehouse_count": 3,
+    "delivery_zones": ["Delhi", "Gurgaon", "Noida", "Faridabad"]
+  }
+}
+```
+
+### 3. CNF Enterprise (Chennai) - `mch_cnf_chennai_001`
+```json
+{
+  "merchant_id": "mch_cnf_chennai_001",
+  "auto_allocate_stock": false,
+  "credit_limit": 5000000.0,
+  "payment_terms_days": 60,
+  "low_stock_threshold": 100,
+  "enable_backorder": true,
+  "auto_reorder": true,
+  "email_notifications": true,
+  "sms_notifications": false,
+  "operating_hours": {
+    "monday": {"is_open": true, "open_time": "07:00", "close_time": "19:00"},
+    "sunday": {"is_open": false}
+  },
+  "default_markup_percentage": 8.0,
+  "allow_discount": true,
+  "max_discount_percentage": 3.0,
+  "tax_settings": {
+    "gst_rate": 18.0,
+    "inclusive_pricing": false,
+    "tax_exemption": false
+  },
+  "custom_fields": {
+    "region": "South India",
+    "category": "cnf",
+    "warehouse_capacity": "50000 sqft",
+    "distribution_network": ["Chennai", "Coimbatore", "Madurai", "Trichy"],
+    "cold_storage": true
+  }
+}
+```
+
+## Business Logic Variations
+
+### Auto Stock Allocation
+- **Enabled**: Salons (for quick service)
+- **Disabled**: Distributors/CNF (for manual control)
+
+### Credit Limits by Type
+- **Salon**: ₹1,00,000 - ₹2,50,000
+- **Distributor**: ₹20,00,000
+- **CNF**: ₹50,00,000
+
+### Payment Terms
+- **Salon**: 15-30 days (quick turnover)
+- **Distributor**: 45 days (standard B2B)
+- **CNF**: 60 days (enterprise terms)
+
+### Operating Hours
+- **Salons**: Customer-facing hours (9 AM - 9 PM, open on weekends)
+- **Distributors**: Business hours (8 AM - 6 PM, limited weekends)
+- **CNF**: Extended business hours (7 AM - 7 PM, no Sunday)
+
+### Markup Percentages
+- **CNF**: 8% (wholesale)
+- **Distributor**: 12% (distribution)
+- **Salon**: 22-30% (retail)
+
+### Notification Preferences
+- **All**: Email notifications enabled
+- **Salons**: SMS enabled for customer-facing operations
+- **B2B**: SMS disabled to reduce noise
+
+## API Testing Examples
+
+Use these merchant IDs to test the merchant settings API endpoints:
+
+```bash
+# Get active salon settings
+GET /merchant-settings/mch_salon_mumbai_001
+
+# Get distributor settings  
+GET /merchant-settings/mch_distributor_delhi_001
+
+# Get inactive salon (for testing edge cases)
+GET /merchant-settings/mch_salon_pune_003
+
+# List active settings only
+GET /merchant-settings?status=active
+
+# Update notification preferences
+PATCH /merchant-settings/mch_salon_bangalore_002/notifications
+{
+  "email_notifications": false,
+  "sms_notifications": true
+}
+```

UI_API_INTEGRATION_PROMPT.md

@@ -0,0 +1,492 @@
+# UI API Integration Prompt Instructions
+
+## 🎯 **System Overview**
+You are building a UI for a hierarchical B2B beauty supply chain management system. The backend provides REST APIs for managing merchants in a 4-level hierarchy: **Parent Company → CNF → Distributors → Salons**.
+
+## 🏗️ **API Base Configuration**
+
+### Base URL & Authentication
+```javascript
+const API_BASE_URL = 'http://localhost:8000'
+const API_ENDPOINTS = {
+  merchants: '/merchants',
+  merchantSettings: '/merchant-settings',
+  users: '/system-users',
+  roles: '/access-roles',
+  auth: '/auth'
+}
+
+// JWT Token Authentication (implement as needed)
+const apiHeaders = {
+  'Content-Type': 'application/json',
+  'Authorization': `Bearer ${localStorage.getItem('authToken')}`
+}
+```
+
+### Test Credentials for Development
+```javascript
+const TEST_CREDENTIALS = {
+  superAdmin: { username: 'superadmin', password: 'SuperAdmin@123' },
+  companyAdmin: { username: 'companyadmin', password: 'CompanyAdmin@123' },
+  cnfManager: { username: 'cnfmanager_north', password: 'CNFManager@123' },
+  distManager: { username: 'distmanager_delhi', password: 'DistManager@123' },
+  salonOwner: { username: 'owner_cp_luxury', password: 'SalonOwner@123' }
+}
+```
+
+## 📱 **Core UI Components to Build**
+
+### 1. **Merchant Hierarchy Tree View**
+```javascript
+// GET /merchants - Fetch all merchants
+const fetchMerchantsHierarchy = async () => {
+  const response = await fetch(`${API_BASE_URL}/merchants`, {
+    headers: apiHeaders
+  })
+  const merchants = await response.json()
+  
+  // Build tree structure
+  return buildHierarchyTree(merchants)
+}
+
+// Expected merchant object structure:
+const merchantStructure = {
+  merchant_id: "string",
+  merchant_name: "string", 
+  merchant_type: "parent_company|cnf|distributor|salon",
+  merchant_code: "string",
+  parent_merchant_id: "string|null",
+  status: "active|inactive",
+  contact: {
+    phone: "string",
+    email: "string", 
+    address_line1: "string",
+    city: "string",
+    state: "string",
+    pincode: "string"
+  },
+  kyc: { /* GST, PAN details */ }
+}
+```
+
+### 2. **Merchant Management Dashboard**
+Create these UI sections:
+
+#### **A. Merchant List/Grid View**
+```javascript
+// API Calls:
+// GET /merchants?merchant_type=salon - Filter by type
+// GET /merchants?status=active - Filter by status  
+// GET /merchants/children/{parent_id} - Get child merchants
+
+const merchantListConfig = {
+  columns: [
+    { key: 'merchant_code', label: 'Code', sortable: true },
+    { key: 'merchant_name', label: 'Name', sortable: true },
+    { key: 'merchant_type', label: 'Type', filterable: true },
+    { key: 'contact.city', label: 'City' },
+    { key: 'status', label: 'Status', filterable: true },
+    { key: 'actions', label: 'Actions' }
+  ],
+  filters: ['merchant_type', 'status', 'city'],
+  actions: ['view', 'edit', 'settings', 'delete']
+}
+```
+
+#### **B. Merchant Creation Form**
+```javascript
+// POST /merchants - Create new merchant
+const createMerchantForm = {
+  fields: {
+    merchant_name: { type: 'text', required: true },
+    merchant_type: { 
+      type: 'select', 
+      options: ['cnf', 'distributor', 'salon'],
+      required: true 
+    },
+    parent_merchant_id: { 
+      type: 'autocomplete',
+      source: '/merchants', // Dynamic based on type
+      required: true 
+    },
+    contact: {
+      phone: { type: 'tel', required: true },
+      email: { type: 'email', required: true },
+      address_line1: { type: 'text', required: true },
+      city: { type: 'text', required: true },
+      state: { type: 'select', options: 'INDIAN_STATES' },
+      pincode: { type: 'text', pattern: '[0-9]{6}' }
+    },
+    kyc: {
+      gst_number: { type: 'text', pattern: 'GST_REGEX' },
+      pan_number: { type: 'text', pattern: 'PAN_REGEX' }
+    }
+  },
+  validation: 'client-side + server-side'
+}
+```
+
+### 3. **Merchant Settings Management**
+```javascript
+// GET /merchant-settings/{merchant_id} - Fetch settings
+// PUT /merchant-settings/{merchant_id} - Update settings
+
+const merchantSettingsForm = {
+  businessSettings: {
+    auto_allocate_stock: { type: 'toggle' },
+    credit_limit: { type: 'currency', min: 0 },
+    payment_terms_days: { type: 'number', min: 0, max: 365 }
+  },
+  inventorySettings: {
+    low_stock_threshold: { type: 'number', min: 1 },
+    enable_backorder: { type: 'toggle' },
+    auto_reorder: { type: 'toggle' }
+  },
+  notifications: {
+    email_notifications: { type: 'toggle' },
+    sms_notifications: { type: 'toggle' },
+    low_stock_alerts: { type: 'toggle' }
+  },
+  operatingHours: {
+    // Dynamic day-wise hour picker
+    format: { open_time: 'HH:mm', close_time: 'HH:mm', is_open: boolean }
+  },
+  pricing: {
+    default_markup_percentage: { type: 'percentage', min: 0, max: 100 },
+    allow_discount: { type: 'toggle' },
+    max_discount_percentage: { type: 'percentage', min: 0, max: 50 }
+  },
+  taxSettings: {
+    gst_rate: { type: 'percentage', default: 18 },
+    inclusive_pricing: { type: 'toggle' },
+    tax_exemption: { type: 'toggle' }
+  }
+}
+```
+
+### 4. **User & Role Management**
+```javascript
+// GET /access-roles - Fetch all roles
+// GET /system-users - Fetch all users
+// POST /system-users - Create user
+
+const userManagementConfig = {
+  userForm: {
+    username: { type: 'text', unique: true },
+    email: { type: 'email', unique: true },
+    full_name: { type: 'text' },
+    role_id: { 
+      type: 'select',
+      source: '/access-roles',
+      displayField: 'role_name'
+    },
+    merchant_id: {
+      type: 'autocomplete', 
+      source: '/merchants',
+      filter: 'based on role permissions'
+    },
+    password: { type: 'password', minLength: 8 }
+  },
+  roleBasedAccess: {
+    // Show/hide features based on user role
+    'role_super_admin': 'ALL_FEATURES',
+    'role_company_admin': 'EXCLUDE_DELETE_OPERATIONS', 
+    'role_cnf_manager': 'REGIONAL_SCOPE_ONLY',
+    'role_distributor_manager': 'LOCAL_SCOPE_ONLY',
+    'role_salon_owner': 'OWN_MERCHANT_ONLY'
+  }
+}
+```
+
+## 🔄 **Key API Integration Patterns**
+
+### 1. **Hierarchical Data Loading**
+```javascript
+// Pattern: Load parent first, then children on-demand
+const loadHierarchicalData = async (parentId = null) => {
+  if (!parentId) {
+    // Load root level (Parent Company + CNFs)
+    return await fetch(`${API_BASE_URL}/merchants?merchant_type=parent_company,cnf`)
+  } else {
+    // Load children of specific parent
+    return await fetch(`${API_BASE_URL}/merchants/children/${parentId}`)
+  }
+}
+
+// Tree expansion pattern
+const expandTreeNode = async (nodeId) => {
+  const children = await fetch(`${API_BASE_URL}/merchants/children/${nodeId}`)
+  // Update tree state with children
+}
+```
+
+### 2. **Context-Aware Form Fields**
+```javascript
+// Parent selection based on merchant type
+const getParentOptions = async (merchantType) => {
+  const parentTypes = {
+    'cnf': ['parent_company'],
+    'distributor': ['cnf'], 
+    'salon': ['distributor']
+  }
+  
+  const parentType = parentTypes[merchantType]?.[0]
+  if (parentType) {
+    return await fetch(`${API_BASE_URL}/merchants?merchant_type=${parentType}`)
+  }
+}
+
+// Settings defaults based on merchant type
+const getSettingsDefaults = (merchantType) => {
+  const defaults = {
+    'cnf': { credit_limit: 10000000, payment_terms_days: 90, markup: 5 },
+    'distributor': { credit_limit: 3000000, payment_terms_days: 60, markup: 15 },
+    'salon': { credit_limit: 500000, payment_terms_days: 30, markup: 30 }
+  }
+  return defaults[merchantType] || {}
+}
+```
+
+### 3. **Error Handling & Validation**
+```javascript
+const apiErrorHandler = (error) => {
+  const errorMessages = {
+    400: 'Invalid request data. Please check your input.',
+    401: 'Authentication required. Please login.',
+    403: 'You do not have permission for this action.',
+    404: 'Resource not found.',
+    409: 'Duplicate entry. This record already exists.',
+    422: 'Validation failed. Please check highlighted fields.',
+    500: 'Server error. Please try again later.'
+  }
+  
+  return errorMessages[error.status] || 'An unexpected error occurred.'
+}
+
+// Form validation
+const validateMerchantForm = (data) => {
+  const errors = {}
+  
+  if (!data.merchant_name?.trim()) {
+    errors.merchant_name = 'Merchant name is required'
+  }
+  
+  if (data.merchant_type === 'salon' && !data.parent_merchant_id) {
+    errors.parent_merchant_id = 'Parent distributor is required for salons'
+  }
+  
+  // GST validation for Indian businesses
+  if (data.kyc?.gst_number && !/^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$/.test(data.kyc.gst_number)) {
+    errors['kyc.gst_number'] = 'Invalid GST number format'
+  }
+  
+  return errors
+}
+```
+
+## 🎨 **UI/UX Implementation Guidelines**
+
+### 1. **Responsive Design Requirements**
+```css
+/* Mobile-first approach for merchant management */
+.merchant-card {
+  /* Stack vertically on mobile */
+  @media (max-width: 768px) {
+    flex-direction: column;
+  }
+}
+
+.merchant-hierarchy-tree {
+  /* Horizontal scroll on mobile */
+  @media (max-width: 768px) {
+    overflow-x: auto;
+    white-space: nowrap;
+  }
+}
+```
+
+### 2. **State Management Pattern**
+```javascript
+// Redux/Zustand store structure
+const merchantStore = {
+  state: {
+    merchants: [],
+    selectedMerchant: null,
+    hierarchyTree: {},
+    filters: { type: 'all', status: 'active' },
+    loading: false,
+    error: null
+  },
+  actions: {
+    fetchMerchants: async (filters) => { },
+    createMerchant: async (data) => { },
+    updateMerchant: async (id, data) => { },
+    deleteMerchant: async (id) => { },
+    setSelectedMerchant: (merchant) => { },
+    setFilters: (filters) => { }
+  }
+}
+```
+
+### 3. **Component Architecture**
+```javascript
+// Component hierarchy
+const ComponentStructure = {
+  'MerchantDashboard': {
+    'MerchantHierarchyTree': ['TreeNode', 'TreeNodeActions'],
+    'MerchantListView': ['MerchantCard', 'FilterBar', 'Pagination'],
+    'MerchantFormModal': ['FormFields', 'ValidationErrors'],
+    'MerchantSettingsPanel': ['SettingsSections', 'OperatingHours']
+  },
+  'UserManagement': {
+    'UserListView': ['UserCard', 'RoleFilter'],
+    'UserFormModal': ['UserForm', 'RoleSelector'],
+    'PermissionsMatrix': ['RolePermissions']
+  }
+}
+```
+
+## 📋 **Testing Checklist**
+
+### 1. **API Integration Tests**
+- [ ] Fetch merchants hierarchy successfully
+- [ ] Create merchant with valid parent relationship
+- [ ] Update merchant settings with validation
+- [ ] Handle API errors gracefully
+- [ ] Implement proper loading states
+
+### 2. **UI Functionality Tests**
+- [ ] Tree view expands/collapses correctly
+- [ ] Form validation works client-side
+- [ ] Filter/search functionality
+- [ ] Responsive design on mobile
+- [ ] Role-based feature visibility
+
+### 3. **Business Logic Tests**
+- [ ] CNF can only have Parent Company as parent
+- [ ] Distributor can only have CNF as parent
+- [ ] Salon can only have Distributor as parent
+- [ ] Credit limits are enforced based on merchant type
+- [ ] Operating hours format validation
+
+## 🚀 **Development Workflow**
+
+### 1. **Setup & Configuration**
+```bash
+# Start the API server
+uvicorn app.main:app --reload --port 8000
+
+# Access API documentation
+open http://localhost:8000/docs
+
+# Test API endpoints
+curl -X GET "http://localhost:8000/merchants" -H "Content-Type: application/json"
+```
+
+### 2. **Implementation Order**
+1. **Phase 1**: Basic merchant CRUD operations
+2. **Phase 2**: Hierarchy tree view and navigation
+3. **Phase 3**: Merchant settings management
+4. **Phase 4**: User and role management
+5. **Phase 5**: Advanced features (reports, analytics)
+
+### 3. **Data Flow Examples**
+```javascript
+// Example: Creating a new salon
+const createSalon = async (salonData) => {
+  // 1. Validate form data
+  const errors = validateMerchantForm(salonData)
+  if (Object.keys(errors).length > 0) {
+    return { success: false, errors }
+  }
+  
+  // 2. Call API
+  const response = await fetch(`${API_BASE_URL}/merchants`, {
+    method: 'POST',
+    headers: apiHeaders,
+    body: JSON.stringify({...salonData, merchant_type: 'salon'})
+  })
+  
+  // 3. Handle response
+  if (response.ok) {
+    const newSalon = await response.json()
+    // Update local state
+    addMerchantToStore(newSalon)
+    // Create default settings
+    await createDefaultSettings(newSalon.merchant_id)
+    return { success: true, data: newSalon }
+  } else {
+    const error = await response.json()
+    return { success: false, error: error.detail }
+  }
+}
+```
+
+## 🔧 **Common Implementation Patterns**
+
+### 1. **Autocomplete for Parent Selection**
+```javascript
+const ParentMerchantSelector = ({ merchantType, value, onChange }) => {
+  const [options, setOptions] = useState([])
+  
+  useEffect(() => {
+    const loadParentOptions = async () => {
+      const parentType = getParentType(merchantType)
+      const response = await fetch(`${API_BASE_URL}/merchants?merchant_type=${parentType}`)
+      setOptions(await response.json())
+    }
+    
+    if (merchantType) {
+      loadParentOptions()
+    }
+  }, [merchantType])
+  
+  return (
+    <Autocomplete
+      options={options}
+      getOptionLabel={(option) => `${option.merchant_name} (${option.merchant_code})`}
+      value={value}
+      onChange={onChange}
+      placeholder="Select parent merchant..."
+    />
+  )
+}
+```
+
+### 2. **Operating Hours Component**
+```javascript
+const OperatingHoursEditor = ({ value, onChange }) => {
+  const days = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday']
+  
+  return (
+    <div className="operating-hours-grid">
+      {days.map(day => (
+        <div key={day} className="day-row">
+          <label>{day.charAt(0).toUpperCase() + day.slice(1)}</label>
+          <input 
+            type="checkbox"
+            checked={value[day]?.is_open || false}
+            onChange={(e) => onChange(day, 'is_open', e.target.checked)}
+          />
+          {value[day]?.is_open && (
+            <>
+              <input 
+                type="time"
+                value={value[day]?.open_time || '09:00'}
+                onChange={(e) => onChange(day, 'open_time', e.target.value)}
+              />
+              <input 
+                type="time"
+                value={value[day]?.close_time || '18:00'} 
+                onChange={(e) => onChange(day, 'close_time', e.target.value)}
+              />
+            </>
+          )}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+This prompt provides comprehensive guidance for building a production-ready UI that integrates seamlessly with your hierarchical merchant API system.

app/constants/collections.py

@@ -7,6 +7,7 @@ SCM_MERCHANTS_COLLECTION = "scm_merchants"
 SCM_MERCHANT_SETTINGS_COLLECTION = "scm_merchant_settings"
 SCM_EMPLOYEES_COLLECTION = "scm_employees"
 SCM_ROLES_COLLECTION = "scm_roles"
+SCM_ACCESS_ROLES_COLLECTION = "scm_access_roles"
 SCM_AUTH_LOGS_COLLECTION = "scm_auth_logs"
 SCM_SYSTEM_USERS_COLLECTION = "scm_system_users"
 

app/db_init.py

@@ -0,0 +1,131 @@
+"""
+Database initialization script for SCM microservice.
+Creates all collections, indexes, and validation rules.
+"""
+import asyncio
+from motor.motor_asyncio import AsyncIOMotorClient
+from insightfy_utils.logging import get_logger
+from app.core.config import settings
+from app.db_init.merchant_settings_init import initialize_merchant_settings_database
+
+logger = get_logger(__name__)
+
+
+async def initialize_database():
+    """
+    Initialize the complete SCM database structure.
+    
+    This script creates:
+    - Collections with schema validation
+    - Performance indexes
+    - Default data (if needed)
+    """
+    client = None
+    try:
+        logger.info("Starting database initialization")
+        
+        # Connect to MongoDB
+        logger.info(f"Connecting to MongoDB: {settings.MONGODB_URI}")
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        
+        # Test connection
+        await client.admin.command('ping')
+        logger.info(f"Connected to database: {settings.MONGODB_DB_NAME}")
+        
+        # Initialize merchant settings
+        await initialize_merchant_settings_database(db)
+        
+        # Add other collection initializations here as needed
+        # await initialize_merchants_database(db)
+        # await initialize_employees_database(db)
+        # await initialize_orders_database(db)
+        
+        logger.info("Database initialization completed successfully")
+        
+    except Exception as e:
+        logger.error("Database initialization failed", exc_info=e)
+        raise
+    finally:
+        if client:
+            client.close()
+            logger.info("Database connection closed")
+
+
+async def verify_database_setup():
+    """
+    Verify that the database setup is correct.
+    """
+    client = None
+    try:
+        logger.info("Starting database verification")
+        
+        # Connect to MongoDB
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        
+        # Test connection
+        await client.admin.command('ping')
+        
+        # List all collections
+        collections = await db.list_collection_names()
+        logger.info(f"Found collections: {collections}")
+        
+        # Check merchant_settings collection
+        from app.constants.collections import SCM_MERCHANT_SETTINGS_COLLECTION
+        
+        if SCM_MERCHANT_SETTINGS_COLLECTION in collections:
+            collection = db[SCM_MERCHANT_SETTINGS_COLLECTION]
+            
+            # Check indexes
+            indexes = await collection.index_information()
+            logger.info(f"Merchant settings indexes: {list(indexes.keys())}")
+            
+            # Check collection stats
+            stats = await db.command("collStats", SCM_MERCHANT_SETTINGS_COLLECTION)
+            logger.info(f"Merchant settings collection stats:", extra={
+                "count": stats.get("count", 0),
+                "size": stats.get("size", 0),
+                "indexes": stats.get("nindexes", 0)
+            })
+            
+            logger.info("✅ Merchant settings collection is properly configured")
+        else:
+            logger.warning(f"❌ Collection {SCM_MERCHANT_SETTINGS_COLLECTION} not found")
+        
+        logger.info("Database verification completed")
+        
+    except Exception as e:
+        logger.error("Database verification failed", exc_info=e)
+        raise
+    finally:
+        if client:
+            client.close()
+
+
+if __name__ == "__main__":
+    import sys
+    
+    # Check command line arguments
+    if len(sys.argv) > 1:
+        command = sys.argv[1]
+        
+        if command == "init":
+            print("🚀 Initializing database...")
+            asyncio.run(initialize_database())
+            print("✅ Database initialization completed")
+            
+        elif command == "verify":
+            print("🔍 Verifying database setup...")
+            asyncio.run(verify_database_setup())
+            print("✅ Database verification completed")
+            
+        else:
+            print(f"Unknown command: {command}")
+            print("Usage: python db_init.py [init|verify]")
+            sys.exit(1)
+    else:
+        print("Usage:")
+        print("  python db_init.py init    - Initialize database structure")
+        print("  python db_init.py verify  - Verify database setup")
+        sys.exit(1)

app/db_init/__init__.py

@@ -0,0 +1,3 @@
+"""
+Database initialization package for SCM microservice.
+"""

app/db_init/merchant_settings_init.py

@@ -0,0 +1,303 @@
+"""
+Database initialization script for merchant settings collection.
+Creates collections, indexes, and validation rules.
+"""
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from pymongo import IndexModel, ASCENDING, TEXT
+from insightfy_utils.logging import get_logger
+
+from app.constants.collections import SCM_MERCHANT_SETTINGS_COLLECTION
+
+logger = get_logger(__name__)
+
+
+async def create_merchant_settings_collection(db: AsyncIOMotorDatabase):
+    """
+    Create the merchant_settings collection with proper indexes and validation.
+    
+    Args:
+        db: MongoDB database instance
+    """
+    try:
+        collection_name = SCM_MERCHANT_SETTINGS_COLLECTION
+        
+        # Check if collection already exists
+        if collection_name in await db.list_collection_names():
+            logger.info(f"Collection {collection_name} already exists")
+            return
+        
+        # Create collection with schema validation
+        validation_schema = {
+            "$jsonSchema": {
+                "bsonType": "object",
+                "required": ["merchant_id", "created_by", "created_at", "is_active"],
+                "properties": {
+                    "merchant_id": {
+                        "bsonType": "string",
+                        "description": "Unique merchant identifier - required"
+                    },
+                    "auto_allocate_stock": {
+                        "bsonType": "bool",
+                        "description": "Whether to automatically allocate stock on orders"
+                    },
+                    "credit_limit": {
+                        "bsonType": ["double", "null"],
+                        "minimum": 0,
+                        "description": "Credit limit in base currency"
+                    },
+                    "payment_terms_days": {
+                        "bsonType": "int",
+                        "minimum": 0,
+                        "maximum": 365,
+                        "description": "Payment terms in days"
+                    },
+                    "low_stock_threshold": {
+                        "bsonType": "int",
+                        "minimum": 0,
+                        "description": "Low stock alert threshold"
+                    },
+                    "enable_backorder": {
+                        "bsonType": "bool",
+                        "description": "Allow backorders when out of stock"
+                    },
+                    "auto_reorder": {
+                        "bsonType": "bool",
+                        "description": "Automatically create reorder when stock is low"
+                    },
+                    "email_notifications": {
+                        "bsonType": "bool",
+                        "description": "Enable email notifications"
+                    },
+                    "sms_notifications": {
+                        "bsonType": "bool",
+                        "description": "Enable SMS notifications"
+                    },
+                    "low_stock_alerts": {
+                        "bsonType": "bool",
+                        "description": "Enable low stock alerts"
+                    },
+                    "order_status_updates": {
+                        "bsonType": "bool",
+                        "description": "Send order status update notifications"
+                    },
+                    "operating_hours": {
+                        "bsonType": ["object", "null"],
+                        "description": "Operating hours configuration by day"
+                    },
+                    "default_markup_percentage": {
+                        "bsonType": ["double", "null"],
+                        "minimum": 0,
+                        "maximum": 1000,
+                        "description": "Default markup percentage"
+                    },
+                    "allow_discount": {
+                        "bsonType": "bool",
+                        "description": "Allow discounts on orders"
+                    },
+                    "max_discount_percentage": {
+                        "bsonType": ["double", "null"],
+                        "minimum": 0,
+                        "maximum": 100,
+                        "description": "Maximum discount percentage allowed"
+                    },
+                    "tax_settings": {
+                        "bsonType": ["object", "null"],
+                        "description": "Tax configuration"
+                    },
+                    "is_active": {
+                        "bsonType": "bool",
+                        "description": "Whether settings are active - required"
+                    },
+                    "created_by": {
+                        "bsonType": "string",
+                        "description": "User ID who created these settings - required"
+                    },
+                    "created_at": {
+                        "bsonType": "date",
+                        "description": "Creation timestamp - required"
+                    },
+                    "updated_by": {
+                        "bsonType": ["string", "null"],
+                        "description": "User ID who last updated these settings"
+                    },
+                    "updated_at": {
+                        "bsonType": ["date", "null"],
+                        "description": "Last update timestamp"
+                    },
+                    "custom_fields": {
+                        "bsonType": ["object", "null"],
+                        "description": "Custom configuration fields"
+                    }
+                }
+            }
+        }
+        
+        # Create collection with validation
+        await db.create_collection(
+            collection_name,
+            validator=validation_schema,
+            validationLevel="moderate",  # Allow updates that don't include all required fields
+            validationAction="error"     # Reject documents that don't match schema
+        )
+        
+        logger.info(f"Created collection {collection_name} with schema validation")
+        
+        # Create indexes for performance
+        indexes = [
+            # Unique index on merchant_id (one settings record per merchant)
+            IndexModel([("merchant_id", ASCENDING)], unique=True, name="merchant_id_unique"),
+            
+            # Index on is_active for filtering active/inactive settings
+            IndexModel([("is_active", ASCENDING)], name="is_active_index"),
+            
+            # Compound index for active settings queries
+            IndexModel([("is_active", ASCENDING), ("merchant_id", ASCENDING)], name="active_merchant_index"),
+            
+            # Index on created_at for sorting by creation time
+            IndexModel([("created_at", ASCENDING)], name="created_at_index"),
+            
+            # Index on updated_at for sorting by update time
+            IndexModel([("updated_at", ASCENDING)], name="updated_at_index"),
+            
+            # Index on created_by for audit queries
+            IndexModel([("created_by", ASCENDING)], name="created_by_index"),
+            
+            # Index on updated_by for audit queries
+            IndexModel([("updated_by", ASCENDING)], name="updated_by_index"),
+            
+            # Compound index for audit queries
+            IndexModel([("created_by", ASCENDING), ("created_at", ASCENDING)], name="audit_created_index"),
+            
+            # Index for notification settings queries
+            IndexModel([
+                ("email_notifications", ASCENDING),
+                ("sms_notifications", ASCENDING),
+                ("is_active", ASCENDING)
+            ], name="notifications_index"),
+            
+            # Index for inventory settings queries
+            IndexModel([
+                ("auto_allocate_stock", ASCENDING),
+                ("enable_backorder", ASCENDING),
+                ("auto_reorder", ASCENDING),
+                ("is_active", ASCENDING)
+            ], name="inventory_settings_index")
+        ]
+        
+        # Create all indexes
+        collection = db[collection_name]
+        await collection.create_indexes(indexes)
+        
+        logger.info(f"Created {len(indexes)} indexes for {collection_name}")
+        
+        # Log index information
+        index_info = await collection.index_information()
+        logger.info(f"Indexes created for {collection_name}:", extra={
+            "indexes": list(index_info.keys())
+        })
+        
+    except Exception as e:
+        logger.error(f"Error creating merchant_settings collection: {e}", exc_info=e)
+        raise
+
+
+async def initialize_merchant_settings_database(db: AsyncIOMotorDatabase):
+    """
+    Initialize the complete merchant settings database structure.
+    
+    Args:
+        db: MongoDB database instance
+    """
+    try:
+        logger.info("Initializing merchant settings database structure")
+        
+        # Create merchant settings collection
+        await create_merchant_settings_collection(db)
+        
+        # Add any default/sample data if needed (optional)
+        # await create_default_settings(db)
+        
+        logger.info("Merchant settings database initialization completed successfully")
+        
+    except Exception as e:
+        logger.error("Failed to initialize merchant settings database", exc_info=e)
+        raise
+
+
+async def create_default_settings(db: AsyncIOMotorDatabase):
+    """
+    Create default merchant settings for existing merchants (optional).
+    This can be used for migration purposes.
+    
+    Args:
+        db: MongoDB database instance
+    """
+    try:
+        from datetime import datetime
+        from app.constants.collections import SCM_MERCHANTS_COLLECTION
+        
+        collection = db[SCM_MERCHANT_SETTINGS_COLLECTION]
+        merchants_collection = db[SCM_MERCHANTS_COLLECTION]
+        
+        # Get merchants that don't have settings yet
+        merchants_without_settings = []
+        async for merchant in merchants_collection.find({"status": "active"}):
+            existing_settings = await collection.find_one({"merchant_id": merchant["merchant_id"]})
+            if not existing_settings:
+                merchants_without_settings.append(merchant)
+        
+        if not merchants_without_settings:
+            logger.info("All active merchants already have settings")
+            return
+        
+        # Create default settings for merchants without settings
+        default_settings_template = {
+            "auto_allocate_stock": False,
+            "credit_limit": None,
+            "payment_terms_days": 30,
+            "low_stock_threshold": 10,
+            "enable_backorder": False,
+            "auto_reorder": False,
+            "email_notifications": True,
+            "sms_notifications": False,
+            "low_stock_alerts": True,
+            "order_status_updates": True,
+            "operating_hours": {
+                "monday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+                "tuesday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+                "wednesday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+                "thursday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+                "friday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+                "saturday": {"is_open": True, "open_time": "09:00", "close_time": "14:00"},
+                "sunday": {"is_open": False}
+            },
+            "default_markup_percentage": None,
+            "allow_discount": True,
+            "max_discount_percentage": None,
+            "tax_settings": {
+                "gst_rate": 18.0,
+                "inclusive_pricing": True,
+                "tax_exemption": False
+            },
+            "is_active": True,
+            "created_by": "system_migration",
+            "created_at": datetime.utcnow(),
+            "updated_by": None,
+            "updated_at": None,
+            "custom_fields": None
+        }
+        
+        # Insert default settings for each merchant
+        settings_to_insert = []
+        for merchant in merchants_without_settings:
+            settings = default_settings_template.copy()
+            settings["merchant_id"] = merchant["merchant_id"]
+            settings_to_insert.append(settings)
+        
+        if settings_to_insert:
+            result = await collection.insert_many(settings_to_insert)
+            logger.info(f"Created default settings for {len(result.inserted_ids)} merchants")
+        
+    except Exception as e:
+        logger.error("Error creating default settings", exc_info=e)
+        raise

create_hierarchy.py

@@ -0,0 +1,1122 @@
+"""
+Hierarchical merchant data creation script.
+Creates a complete merchant ecosystem: Parent Company -> CNF -> Distributors -> Salons
+with corresponding users, roles, and settings.
+"""
+import asyncio
+from datetime import datetime, timedelta
+from motor.motor_asyncio import AsyncIOMotorClient
+from insightfy_utils.logging import get_logger
+import sys
+import os
+import hashlib
+import secrets
+
+# Add the current directory to Python path
+sys.path.insert(0, os.path.dirname(__file__))
+
+from app.core.config import settings
+from app.constants.collections import (
+    SCM_MERCHANTS_COLLECTION, 
+    SCM_MERCHANT_SETTINGS_COLLECTION,
+    SCM_SYSTEM_USERS_COLLECTION,
+    SCM_ACCESS_ROLES_COLLECTION
+)
+
+logger = get_logger(__name__)
+
+def generate_merchant_id(prefix: str) -> str:
+    """Generate a unique merchant ID with prefix."""
+    return f"{prefix}_{secrets.token_urlsafe(8)}"
+
+def generate_user_id() -> str:
+    """Generate a unique user ID."""
+    return f"user_{secrets.token_urlsafe(8)}"
+
+def hash_password(password: str) -> str:
+    """Hash password for storage."""
+    return hashlib.sha256(password.encode()).hexdigest()
+
+# Merchant hierarchy data
+MERCHANT_HIERARCHY = {
+    "parent_company": {
+        "merchant_id": "company_cuatro_beauty_ltd",
+        "merchant_type": "parent_company",
+        "merchant_code": "CUATRO-HQ",
+        "merchant_name": "Cuatro Beauty Limited",
+        "parent_merchant_id": None,
+        "contact": {
+            "phone": "+911234567890",
+            "email": "info@cuatrobeauty.com",
+            "address_line1": "Cuatro Beauty Tower, Business District",
+            "city": "Mumbai",
+            "state": "Maharashtra",
+            "pincode": "400001",
+            "country": "India"
+        },
+        "geo_location": {"lat": 19.0760, "lng": 72.8777},
+        "kyc": {
+            "gst_number": "27AAPCU0939F1ZV",
+            "pan_number": "AAPCU0939F",
+            "bank_account_number": "1234567890123456",
+            "bank_ifsc": "HDFC0001234"
+        },
+        "status": "active",
+        "created_by": "system_admin"
+    },
+    "cnfs": [
+        {
+            "merchant_id": "cnf_north_india_hub",
+            "merchant_type": "cnf",
+            "merchant_code": "CNF-NORTH-001",
+            "merchant_name": "North India Beauty Hub CNF",
+            "parent_merchant_id": "company_cuatro_beauty_ltd",
+            "contact": {
+                "phone": "+911987654321",
+                "email": "north@cuatrobeauty.com",
+                "address_line1": "Industrial Area Phase-1, Sector 58",
+                "city": "Gurgaon",
+                "state": "Haryana",
+                "pincode": "122001",
+                "country": "India"
+            },
+            "geo_location": {"lat": 28.4595, "lng": 77.0266},
+            "kyc": {
+                "gst_number": "06AAPCU0939F1ZW",
+                "pan_number": "AAPCU0939G",
+                "bank_account_number": "2345678901234567",
+                "bank_ifsc": "ICIC0001235"
+            },
+            "status": "active",
+            "created_by": "head_office"
+        },
+        {
+            "merchant_id": "cnf_south_india_hub",
+            "merchant_type": "cnf", 
+            "merchant_code": "CNF-SOUTH-001",
+            "merchant_name": "South India Beauty Hub CNF",
+            "parent_merchant_id": "company_cuatro_beauty_ltd",
+            "contact": {
+                "phone": "+914412345678",
+                "email": "south@cuatrobeauty.com",
+                "address_line1": "Ambattur Industrial Estate",
+                "city": "Chennai",
+                "state": "Tamil Nadu",
+                "pincode": "600058",
+                "country": "India"
+            },
+            "geo_location": {"lat": 13.0827, "lng": 80.2707},
+            "kyc": {
+                "gst_number": "33AAPCU0939F1ZX",
+                "pan_number": "AAPCU0939H",
+                "bank_account_number": "3456789012345678",
+                "bank_ifsc": "AXIS0001236"
+            },
+            "status": "active",
+            "created_by": "head_office"
+        },
+        {
+            "merchant_id": "cnf_west_india_hub",
+            "merchant_type": "cnf",
+            "merchant_code": "CNF-WEST-001", 
+            "merchant_name": "West India Beauty Hub CNF",
+            "parent_merchant_id": "company_cuatro_beauty_ltd",
+            "contact": {
+                "phone": "+912223456789",
+                "email": "west@cuatrobeauty.com",
+                "address_line1": "MIDC Industrial Area, Andheri East",
+                "city": "Mumbai",
+                "state": "Maharashtra", 
+                "pincode": "400093",
+                "country": "India"
+            },
+            "geo_location": {"lat": 19.1136, "lng": 72.8697},
+            "kyc": {
+                "gst_number": "27AAPCU0939F1ZY",
+                "pan_number": "AAPCU0939I",
+                "bank_account_number": "4567890123456789",
+                "bank_ifsc": "SBIN0001237"
+            },
+            "status": "active",
+            "created_by": "head_office"
+        }
+    ],
+    "distributors": [
+        # North India CNF Distributors
+        {
+            "merchant_id": "dist_delhi_premium",
+            "merchant_type": "distributor",
+            "merchant_code": "DIST-DEL-001",
+            "merchant_name": "Delhi Premium Beauty Distributors",
+            "parent_merchant_id": "cnf_north_india_hub",
+            "contact": {
+                "phone": "+911134567890",
+                "email": "delhi@premiumbeauty.com",
+                "address_line1": "Karol Bagh Market Complex",
+                "city": "New Delhi",
+                "state": "Delhi",
+                "pincode": "110005",
+                "country": "India"
+            },
+            "geo_location": {"lat": 28.6519, "lng": 77.1909},
+            "kyc": {
+                "gst_number": "07AAPDE0939F1ZA",
+                "pan_number": "AAPDE0939A",
+                "bank_account_number": "5678901234567890",
+                "bank_ifsc": "HDFC0002345"
+            },
+            "status": "active",
+            "created_by": "cnf_manager_north"
+        },
+        {
+            "merchant_id": "dist_punjab_wholesale",
+            "merchant_type": "distributor",
+            "merchant_code": "DIST-PB-001", 
+            "merchant_name": "Punjab Beauty Wholesale Hub",
+            "parent_merchant_id": "cnf_north_india_hub",
+            "contact": {
+                "phone": "+911614567890",
+                "email": "punjab@wholesalebeauty.com",
+                "address_line1": "Model Town Extension",
+                "city": "Ludhiana",
+                "state": "Punjab",
+                "pincode": "141002",
+                "country": "India"
+            },
+            "geo_location": {"lat": 30.9010, "lng": 75.8573},
+            "kyc": {
+                "gst_number": "03AAPPB0939F1ZB",
+                "pan_number": "AAPPB0939B",
+                "bank_account_number": "6789012345678901",
+                "bank_ifsc": "PUNB0003456"
+            },
+            "status": "active",
+            "created_by": "cnf_manager_north"
+        },
+        # South India CNF Distributors
+        {
+            "merchant_id": "dist_chennai_elite",
+            "merchant_type": "distributor",
+            "merchant_code": "DIST-CHN-001",
+            "merchant_name": "Chennai Elite Beauty Distribution",
+            "parent_merchant_id": "cnf_south_india_hub",
+            "contact": {
+                "phone": "+914425678901",
+                "email": "chennai@elitebeauty.com", 
+                "address_line1": "T. Nagar Commercial Complex",
+                "city": "Chennai",
+                "state": "Tamil Nadu",
+                "pincode": "600017",
+                "country": "India"
+            },
+            "geo_location": {"lat": 13.0418, "lng": 80.2341},
+            "kyc": {
+                "gst_number": "33AAPCH0939F1ZC",
+                "pan_number": "AAPCH0939C",
+                "bank_account_number": "7890123456789012",
+                "bank_ifsc": "ICIC0004567"
+            },
+            "status": "active",
+            "created_by": "cnf_manager_south"
+        },
+        {
+            "merchant_id": "dist_bangalore_metro",
+            "merchant_type": "distributor",
+            "merchant_code": "DIST-BLR-001",
+            "merchant_name": "Bangalore Metro Beauty Supplies",
+            "parent_merchant_id": "cnf_south_india_hub",
+            "contact": {
+                "phone": "+918036789012",
+                "email": "bangalore@metrobeauty.com",
+                "address_line1": "Commercial Street",
+                "city": "Bangalore", 
+                "state": "Karnataka",
+                "pincode": "560001",
+                "country": "India"
+            },
+            "geo_location": {"lat": 12.9716, "lng": 77.5946},
+            "kyc": {
+                "gst_number": "29AAPBL0939F1ZD",
+                "pan_number": "AAPBL0939D",
+                "bank_account_number": "8901234567890123",
+                "bank_ifsc": "AXIS0005678"
+            },
+            "status": "active",
+            "created_by": "cnf_manager_south"
+        },
+        # West India CNF Distributors
+        {
+            "merchant_id": "dist_mumbai_central",
+            "merchant_type": "distributor",
+            "merchant_code": "DIST-MUM-001",
+            "merchant_name": "Mumbai Central Beauty Distribution",
+            "parent_merchant_id": "cnf_west_india_hub",
+            "contact": {
+                "phone": "+912227890123",
+                "email": "mumbai@centralbeauty.com",
+                "address_line1": "Crawford Market Area",
+                "city": "Mumbai",
+                "state": "Maharashtra",
+                "pincode": "400001", 
+                "country": "India"
+            },
+            "geo_location": {"lat": 18.9388, "lng": 72.8261},
+            "kyc": {
+                "gst_number": "27AAPMM0939F1ZE",
+                "pan_number": "AAPMM0939E",
+                "bank_account_number": "9012345678901234",
+                "bank_ifsc": "SBIN0006789"
+            },
+            "status": "active",
+            "created_by": "cnf_manager_west"
+        },
+        {
+            "merchant_id": "dist_pune_premium",
+            "merchant_type": "distributor", 
+            "merchant_code": "DIST-PUN-001",
+            "merchant_name": "Pune Premium Beauty Hub",
+            "parent_merchant_id": "cnf_west_india_hub",
+            "contact": {
+                "phone": "+912038901234",
+                "email": "pune@premiumhub.com",
+                "address_line1": "FC Road Commercial Area",
+                "city": "Pune",
+                "state": "Maharashtra",
+                "pincode": "411004",
+                "country": "India"
+            },
+            "geo_location": {"lat": 18.5204, "lng": 73.8567},
+            "kyc": {
+                "gst_number": "27AAPPU0939F1ZF",
+                "pan_number": "AAPPU0939F",
+                "bank_account_number": "0123456789012345",
+                "bank_ifsc": "HDFC0007890"
+            },
+            "status": "active",
+            "created_by": "cnf_manager_west"
+        }
+    ],
+    "salons": [
+        # Delhi Distributor Salons
+        {
+            "merchant_id": "salon_delhi_cp_luxury",
+            "merchant_type": "salon",
+            "merchant_code": "SALON-DEL-001",
+            "merchant_name": "Connaught Place Luxury Salon",
+            "parent_merchant_id": "dist_delhi_premium",
+            "contact": {
+                "phone": "+911145678901",
+                "email": "cp@luxurysalon.com",
+                "address_line1": "Connaught Place, Block A",
+                "city": "New Delhi",
+                "state": "Delhi",
+                "pincode": "110001",
+                "country": "India"
+            },
+            "geo_location": {"lat": 28.6304, "lng": 77.2177},
+            "kyc": {"pan_number": "AALCP0939A"},
+            "status": "active",
+            "created_by": "dist_manager_delhi"
+        },
+        {
+            "merchant_id": "salon_delhi_khan_market",
+            "merchant_type": "salon",
+            "merchant_code": "SALON-DEL-002",
+            "merchant_name": "Khan Market Beauty Studio",
+            "parent_merchant_id": "dist_delhi_premium",
+            "contact": {
+                "phone": "+911156789012",
+                "email": "khan@beautystudio.com",
+                "address_line1": "Khan Market, Middle Lane",
+                "city": "New Delhi",
+                "state": "Delhi", 
+                "pincode": "110003",
+                "country": "India"
+            },
+            "geo_location": {"lat": 28.5982, "lng": 77.2294},
+            "kyc": {"pan_number": "AALKM0939B"},
+            "status": "active",
+            "created_by": "dist_manager_delhi"
+        },
+        # Punjab Distributor Salons
+        {
+            "merchant_id": "salon_ludhiana_model_town",
+            "merchant_type": "salon",
+            "merchant_code": "SALON-LDH-001",
+            "merchant_name": "Model Town Beauty Parlour",
+            "parent_merchant_id": "dist_punjab_wholesale",
+            "contact": {
+                "phone": "+911667890123",
+                "email": "model@beautyparour.com",
+                "address_line1": "Model Town Market",
+                "city": "Ludhiana",
+                "state": "Punjab",
+                "pincode": "141002",
+                "country": "India"
+            },
+            "geo_location": {"lat": 30.9000, "lng": 75.8500},
+            "kyc": {"pan_number": "AALMT0939C"},
+            "status": "active", 
+            "created_by": "dist_manager_punjab"
+        },
+        # Chennai Distributor Salons
+        {
+            "merchant_id": "salon_chennai_tnagar",
+            "merchant_type": "salon",
+            "merchant_code": "SALON-CHN-001", 
+            "merchant_name": "T.Nagar Glamour Studio",
+            "parent_merchant_id": "dist_chennai_elite",
+            "contact": {
+                "phone": "+914478901234",
+                "email": "tnagar@glamourstudio.com",
+                "address_line1": "Ranganathan Street",
+                "city": "Chennai",
+                "state": "Tamil Nadu",
+                "pincode": "600017",
+                "country": "India"
+            },
+            "geo_location": {"lat": 13.0435, "lng": 80.2349},
+            "kyc": {"pan_number": "AALTG0939D"},
+            "status": "active",
+            "created_by": "dist_manager_chennai"
+        },
+        {
+            "merchant_id": "salon_chennai_express_avenue",
+            "merchant_type": "salon",
+            "merchant_code": "SALON-CHN-002",
+            "merchant_name": "Express Avenue Beauty Lounge",
+            "parent_merchant_id": "dist_chennai_elite",
+            "contact": {
+                "phone": "+914489012345",
+                "email": "express@beautylounge.com",
+                "address_line1": "Express Avenue Mall, 2nd Floor", 
+                "city": "Chennai",
+                "state": "Tamil Nadu",
+                "pincode": "600002",
+                "country": "India"
+            },
+            "geo_location": {"lat": 13.0594, "lng": 80.2584},
+            "kyc": {"pan_number": "AALEAB0939E"},
+            "status": "active",
+            "created_by": "dist_manager_chennai"
+        },
+        # Bangalore Distributor Salons
+        {
+            "merchant_id": "salon_bangalore_brigade_road",
+            "merchant_type": "salon",
+            "merchant_code": "SALON-BLR-001",
+            "merchant_name": "Brigade Road Style Studio",
+            "parent_merchant_id": "dist_bangalore_metro",
+            "contact": {
+                "phone": "+918090123456",
+                "email": "brigade@stylestudio.com",
+                "address_line1": "Brigade Road",
+                "city": "Bangalore",
+                "state": "Karnataka",
+                "pincode": "560025",
+                "country": "India"
+            },
+            "geo_location": {"lat": 12.9738, "lng": 77.6071},
+            "kyc": {"pan_number": "AALBS0939F"},
+            "status": "active",
+            "created_by": "dist_manager_bangalore"
+        },
+        # Mumbai Distributor Salons
+        {
+            "merchant_id": "salon_mumbai_linking_road",
+            "merchant_type": "salon", 
+            "merchant_code": "SALON-MUM-001",
+            "merchant_name": "Linking Road Fashion Salon",
+            "parent_merchant_id": "dist_mumbai_central",
+            "contact": {
+                "phone": "+912201234567",
+                "email": "linking@fashionsalon.com",
+                "address_line1": "Linking Road, Bandra West",
+                "city": "Mumbai",
+                "state": "Maharashtra",
+                "pincode": "400050",
+                "country": "India"
+            },
+            "geo_location": {"lat": 19.0544, "lng": 72.8265},
+            "kyc": {"pan_number": "AALFS0939G"},
+            "status": "active",
+            "created_by": "dist_manager_mumbai"
+        },
+        {
+            "merchant_id": "salon_mumbai_colaba",
+            "merchant_type": "salon",
+            "merchant_code": "SALON-MUM-002", 
+            "merchant_name": "Colaba Causeway Beauty Hub",
+            "parent_merchant_id": "dist_mumbai_central",
+            "contact": {
+                "phone": "+912212345678",
+                "email": "colaba@beautyhub.com",
+                "address_line1": "Colaba Causeway",
+                "city": "Mumbai",
+                "state": "Maharashtra",
+                "pincode": "400005",
+                "country": "India"
+            },
+            "geo_location": {"lat": 18.9067, "lng": 72.8147},
+            "kyc": {"pan_number": "AALCB0939H"},
+            "status": "active",
+            "created_by": "dist_manager_mumbai"
+        },
+        # Pune Distributor Salons
+        {
+            "merchant_id": "salon_pune_koregaon_park",
+            "merchant_type": "salon",
+            "merchant_code": "SALON-PUN-001",
+            "merchant_name": "Koregaon Park Elite Salon",
+            "parent_merchant_id": "dist_pune_premium",
+            "contact": {
+                "phone": "+912023456789",
+                "email": "koregaon@elitesalon.com",
+                "address_line1": "Koregaon Park",
+                "city": "Pune",
+                "state": "Maharashtra",
+                "pincode": "411001",
+                "country": "India"
+            },
+            "geo_location": {"lat": 18.5362, "lng": 73.8850},
+            "kyc": {"pan_number": "AALES0939I"},
+            "status": "active",
+            "created_by": "dist_manager_pune"
+        }
+    ]
+}
+
+# Access roles data
+ACCESS_ROLES = [
+    {
+        "role_id": "role_super_admin",
+        "role_name": "Super Administrator",
+        "description": "Full system access with all permissions",
+        "permissions": [
+            "CREATE_MERCHANT", "READ_MERCHANT", "UPDATE_MERCHANT", "DELETE_MERCHANT",
+            "CREATE_MERCHANT_SETTING", "READ_MERCHANT_SETTING", "UPDATE_MERCHANT_SETTING", "DELETE_MERCHANT_SETTING",
+            "CREATE_USER", "READ_USER", "UPDATE_USER", "DELETE_USER",
+            "CREATE_ROLE", "READ_ROLE", "UPDATE_ROLE", "DELETE_ROLE",
+            "VIEW_REPORTS", "MANAGE_SYSTEM", "AUDIT_ACCESS"
+        ],
+        "is_active": True,
+        "created_by": "system",
+        "created_at": datetime.utcnow()
+    },
+    {
+        "role_id": "role_company_admin",
+        "role_name": "Company Administrator", 
+        "description": "Company-wide administrative access",
+        "permissions": [
+            "CREATE_MERCHANT", "READ_MERCHANT", "UPDATE_MERCHANT",
+            "CREATE_MERCHANT_SETTING", "READ_MERCHANT_SETTING", "UPDATE_MERCHANT_SETTING",
+            "CREATE_USER", "READ_USER", "UPDATE_USER",
+            "VIEW_REPORTS", "MANAGE_HIERARCHY"
+        ],
+        "is_active": True,
+        "created_by": "system",
+        "created_at": datetime.utcnow()
+    },
+    {
+        "role_id": "role_cnf_manager",
+        "role_name": "CNF Manager",
+        "description": "CNF operations management",
+        "permissions": [
+            "READ_MERCHANT", "UPDATE_MERCHANT",
+            "CREATE_MERCHANT_SETTING", "READ_MERCHANT_SETTING", "UPDATE_MERCHANT_SETTING",
+            "READ_USER", "CREATE_DISTRIBUTOR", "MANAGE_INVENTORY"
+        ],
+        "is_active": True,
+        "created_by": "system", 
+        "created_at": datetime.utcnow()
+    },
+    {
+        "role_id": "role_distributor_manager",
+        "role_name": "Distributor Manager",
+        "description": "Distributor operations management",
+        "permissions": [
+            "READ_MERCHANT", "UPDATE_MERCHANT",
+            "READ_MERCHANT_SETTING", "UPDATE_MERCHANT_SETTING",
+            "READ_USER", "CREATE_SALON", "MANAGE_ORDERS"
+        ],
+        "is_active": True,
+        "created_by": "system",
+        "created_at": datetime.utcnow()
+    },
+    {
+        "role_id": "role_salon_owner",
+        "role_name": "Salon Owner",
+        "description": "Salon operations management",
+        "permissions": [
+            "READ_MERCHANT", "UPDATE_MERCHANT",
+            "READ_MERCHANT_SETTING", "UPDATE_MERCHANT_SETTING",
+            "READ_USER", "PLACE_ORDERS", "VIEW_INVENTORY"
+        ],
+        "is_active": True,
+        "created_by": "system",
+        "created_at": datetime.utcnow()
+    },
+    {
+        "role_id": "role_salon_staff",
+        "role_name": "Salon Staff",
+        "description": "Basic salon operations",
+        "permissions": [
+            "READ_MERCHANT", "READ_MERCHANT_SETTING",
+            "READ_USER", "VIEW_INVENTORY", "BASIC_OPERATIONS"
+        ],
+        "is_active": True,
+        "created_by": "system",
+        "created_at": datetime.utcnow()
+    }
+]
+
+# System users data  
+def generate_system_users():
+    """Generate system users for each merchant."""
+    users = []
+    
+    # Super admin
+    users.append({
+        "user_id": "user_super_admin",
+        "username": "superadmin",
+        "email": "superadmin@cuatrobeauty.com",
+        "password_hash": hash_password("SuperAdmin@123"),
+        "full_name": "System Super Administrator",
+        "role_id": "role_super_admin",
+        "merchant_id": "company_cuatro_beauty_ltd",
+        "permissions": ACCESS_ROLES[0]["permissions"],
+        "is_active": True,
+        "last_login": None,
+        "created_by": "system",
+        "created_at": datetime.utcnow()
+    })
+    
+    # Company admin
+    users.append({
+        "user_id": "user_company_admin",
+        "username": "companyadmin",
+        "email": "admin@cuatrobeauty.com", 
+        "password_hash": hash_password("CompanyAdmin@123"),
+        "full_name": "Cuatro Beauty Administrator",
+        "role_id": "role_company_admin",
+        "merchant_id": "company_cuatro_beauty_ltd",
+        "permissions": ACCESS_ROLES[1]["permissions"],
+        "is_active": True,
+        "last_login": None,
+        "created_by": "user_super_admin",
+        "created_at": datetime.utcnow()
+    })
+    
+    # CNF Managers
+    cnf_managers = [
+        ("cnf_north_india_hub", "cnfmanager_north", "north.manager@cuatrobeauty.com", "Rajesh Kumar"),
+        ("cnf_south_india_hub", "cnfmanager_south", "south.manager@cuatrobeauty.com", "Suresh Reddy"),
+        ("cnf_west_india_hub", "cnfmanager_west", "west.manager@cuatrobeauty.com", "Amit Sharma")
+    ]
+    
+    for merchant_id, username, email, full_name in cnf_managers:
+        users.append({
+            "user_id": generate_user_id(),
+            "username": username,
+            "email": email,
+            "password_hash": hash_password("CNFManager@123"),
+            "full_name": full_name,
+            "role_id": "role_cnf_manager",
+            "merchant_id": merchant_id,
+            "permissions": ACCESS_ROLES[2]["permissions"],
+            "is_active": True,
+            "last_login": None,
+            "created_by": "user_company_admin",
+            "created_at": datetime.utcnow()
+        })
+    
+    # Distributor Managers
+    distributor_managers = [
+        ("dist_delhi_premium", "distmanager_delhi", "delhi.manager@premiumbeauty.com", "Vikram Singh"),
+        ("dist_punjab_wholesale", "distmanager_punjab", "punjab.manager@wholesalebeauty.com", "Hardeep Singh"),
+        ("dist_chennai_elite", "distmanager_chennai", "chennai.manager@elitebeauty.com", "Ramesh Kumar"),
+        ("dist_bangalore_metro", "distmanager_bangalore", "bangalore.manager@metrobeauty.com", "Srinivas Rao"),
+        ("dist_mumbai_central", "distmanager_mumbai", "mumbai.manager@centralbeauty.com", "Rohit Patil"),
+        ("dist_pune_premium", "distmanager_pune", "pune.manager@premiumhub.com", "Pradeep Joshi")
+    ]
+    
+    for merchant_id, username, email, full_name in distributor_managers:
+        users.append({
+            "user_id": generate_user_id(),
+            "username": username,
+            "email": email,
+            "password_hash": hash_password("DistManager@123"),
+            "full_name": full_name,
+            "role_id": "role_distributor_manager",
+            "merchant_id": merchant_id,
+            "permissions": ACCESS_ROLES[3]["permissions"],
+            "is_active": True,
+            "last_login": None,
+            "created_by": "user_company_admin",
+            "created_at": datetime.utcnow()
+        })
+    
+    # Salon Owners
+    salon_owners = [
+        ("salon_delhi_cp_luxury", "owner_cp_luxury", "owner@luxurysalon.com", "Meera Gupta"),
+        ("salon_delhi_khan_market", "owner_khan_market", "owner@beautystudio.com", "Priya Sharma"),
+        ("salon_ludhiana_model_town", "owner_model_town", "owner@beautyparour.com", "Simran Kaur"),
+        ("salon_chennai_tnagar", "owner_tnagar", "owner@glamourstudio.com", "Lakshmi Devi"),
+        ("salon_chennai_express_avenue", "owner_express_avenue", "owner@beautylounge.com", "Divya Raj"),
+        ("salon_bangalore_brigade_road", "owner_brigade_road", "owner@stylestudio.com", "Kavya Nair"),
+        ("salon_mumbai_linking_road", "owner_linking_road", "owner@fashionsalon.com", "Neha Desai"),
+        ("salon_mumbai_colaba", "owner_colaba", "owner@beautyhub.com", "Pooja Shah"),
+        ("salon_pune_koregaon_park", "owner_koregaon_park", "owner@elitesalon.com", "Shweta Kulkarni")
+    ]
+    
+    for merchant_id, username, email, full_name in salon_owners:
+        users.append({
+            "user_id": generate_user_id(),
+            "username": username,
+            "email": email,
+            "password_hash": hash_password("SalonOwner@123"),
+            "full_name": full_name,
+            "role_id": "role_salon_owner",
+            "merchant_id": merchant_id,
+            "permissions": ACCESS_ROLES[4]["permissions"],
+            "is_active": True,
+            "last_login": None,
+            "created_by": "user_company_admin",
+            "created_at": datetime.utcnow()
+        })
+    
+    return users
+
+# Merchant settings data based on merchant type
+def generate_merchant_settings():
+    """Generate settings for all merchants based on their type."""
+    settings = []
+    
+    # Company settings
+    settings.append({
+        "merchant_id": "company_cuatro_beauty_ltd",
+        "auto_allocate_stock": False,
+        "credit_limit": None,  # No credit limit for parent company
+        "payment_terms_days": 0,
+        "low_stock_threshold": 0,
+        "enable_backorder": False,
+        "auto_reorder": False,
+        "email_notifications": True,
+        "sms_notifications": False,
+        "low_stock_alerts": False,
+        "order_status_updates": True,
+        "operating_hours": {
+            "monday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+            "tuesday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+            "wednesday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+            "thursday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+            "friday": {"is_open": True, "open_time": "09:00", "close_time": "18:00"},
+            "saturday": {"is_open": False},
+            "sunday": {"is_open": False}
+        },
+        "default_markup_percentage": 0.0,
+        "allow_discount": False,
+        "max_discount_percentage": 0.0,
+        "tax_settings": {
+            "gst_rate": 18.0,
+            "inclusive_pricing": False,
+            "tax_exemption": False
+        },
+        "is_active": True,
+        "created_by": "user_super_admin",
+        "created_at": datetime.utcnow(),
+        "updated_by": None,
+        "updated_at": None,
+        "custom_fields": {
+            "region": "National",
+            "category": "parent_company",
+            "headquarters": True
+        }
+    })
+    
+    # CNF settings (high volume, enterprise)
+    cnf_merchants = ["cnf_north_india_hub", "cnf_south_india_hub", "cnf_west_india_hub"]
+    for merchant_id in cnf_merchants:
+        region = merchant_id.split('_')[1].title()
+        settings.append({
+            "merchant_id": merchant_id,
+            "auto_allocate_stock": False,
+            "credit_limit": 10000000.0,  # 1 Crore
+            "payment_terms_days": 90,
+            "low_stock_threshold": 500,
+            "enable_backorder": True,
+            "auto_reorder": True,
+            "email_notifications": True,
+            "sms_notifications": False,
+            "low_stock_alerts": True,
+            "order_status_updates": True,
+            "operating_hours": {
+                "monday": {"is_open": True, "open_time": "07:00", "close_time": "19:00"},
+                "tuesday": {"is_open": True, "open_time": "07:00", "close_time": "19:00"},
+                "wednesday": {"is_open": True, "open_time": "07:00", "close_time": "19:00"},
+                "thursday": {"is_open": True, "open_time": "07:00", "close_time": "19:00"},
+                "friday": {"is_open": True, "open_time": "07:00", "close_time": "19:00"},
+                "saturday": {"is_open": True, "open_time": "08:00", "close_time": "17:00"},
+                "sunday": {"is_open": False}
+            },
+            "default_markup_percentage": 5.0,
+            "allow_discount": True,
+            "max_discount_percentage": 2.0,
+            "tax_settings": {
+                "gst_rate": 18.0,
+                "inclusive_pricing": False,
+                "tax_exemption": False
+            },
+            "is_active": True,
+            "created_by": "user_company_admin",
+            "created_at": datetime.utcnow(),
+            "updated_by": None,
+            "updated_at": None,
+            "custom_fields": {
+                "region": f"{region} India",
+                "category": "cnf",
+                "warehouse_capacity": "100000 sqft",
+                "cold_storage": True
+            }
+        })
+    
+    # Distributor settings (medium volume, wholesale)
+    distributor_data = [
+        ("dist_delhi_premium", "Delhi", 3000000.0),
+        ("dist_punjab_wholesale", "Punjab", 2500000.0),
+        ("dist_chennai_elite", "Chennai", 3500000.0),
+        ("dist_bangalore_metro", "Bangalore", 4000000.0),
+        ("dist_mumbai_central", "Mumbai", 5000000.0),
+        ("dist_pune_premium", "Pune", 2000000.0)
+    ]
+    
+    for merchant_id, region, credit_limit in distributor_data:
+        settings.append({
+            "merchant_id": merchant_id,
+            "auto_allocate_stock": True,
+            "credit_limit": credit_limit,
+            "payment_terms_days": 60,
+            "low_stock_threshold": 100,
+            "enable_backorder": True,
+            "auto_reorder": True,
+            "email_notifications": True,
+            "sms_notifications": False,
+            "low_stock_alerts": True,
+            "order_status_updates": True,
+            "operating_hours": {
+                "monday": {"is_open": True, "open_time": "08:00", "close_time": "18:00"},
+                "tuesday": {"is_open": True, "open_time": "08:00", "close_time": "18:00"},
+                "wednesday": {"is_open": True, "open_time": "08:00", "close_time": "18:00"},
+                "thursday": {"is_open": True, "open_time": "08:00", "close_time": "18:00"},
+                "friday": {"is_open": True, "open_time": "08:00", "close_time": "18:00"},
+                "saturday": {"is_open": True, "open_time": "09:00", "close_time": "16:00"},
+                "sunday": {"is_open": False}
+            },
+            "default_markup_percentage": 15.0,
+            "allow_discount": True,
+            "max_discount_percentage": 7.0,
+            "tax_settings": {
+                "gst_rate": 18.0,
+                "inclusive_pricing": False,
+                "tax_exemption": False
+            },
+            "is_active": True,
+            "created_by": "user_company_admin",
+            "created_at": datetime.utcnow(),
+            "updated_by": None,
+            "updated_at": None,
+            "custom_fields": {
+                "region": region,
+                "category": "distributor",
+                "warehouse_count": 2
+            }
+        })
+    
+    # Salon settings (retail, customer-facing)
+    salon_data = [
+        ("salon_delhi_cp_luxury", "Delhi", 500000.0, "premium"),
+        ("salon_delhi_khan_market", "Delhi", 300000.0, "standard"),
+        ("salon_ludhiana_model_town", "Punjab", 200000.0, "standard"),
+        ("salon_chennai_tnagar", "Chennai", 400000.0, "premium"),
+        ("salon_chennai_express_avenue", "Chennai", 600000.0, "luxury"),
+        ("salon_bangalore_brigade_road", "Bangalore", 450000.0, "premium"),
+        ("salon_mumbai_linking_road", "Mumbai", 800000.0, "luxury"),
+        ("salon_mumbai_colaba", "Mumbai", 350000.0, "standard"),
+        ("salon_pune_koregaon_park", "Pune", 400000.0, "premium")
+    ]
+    
+    for merchant_id, region, credit_limit, category in salon_data:
+        # Premium/luxury salons have different settings
+        is_premium = category in ["premium", "luxury"]
+        
+        settings.append({
+            "merchant_id": merchant_id,
+            "auto_allocate_stock": True,
+            "credit_limit": credit_limit,
+            "payment_terms_days": 30 if is_premium else 15,
+            "low_stock_threshold": 10 if is_premium else 5,
+            "enable_backorder": False,
+            "auto_reorder": is_premium,
+            "email_notifications": True,
+            "sms_notifications": True,
+            "low_stock_alerts": True,
+            "order_status_updates": True,
+            "operating_hours": {
+                "monday": {"is_open": True, "open_time": "10:00", "close_time": "20:00"},
+                "tuesday": {"is_open": True, "open_time": "10:00", "close_time": "20:00"},
+                "wednesday": {"is_open": True, "open_time": "10:00", "close_time": "20:00"},
+                "thursday": {"is_open": True, "open_time": "10:00", "close_time": "20:00"},
+                "friday": {"is_open": True, "open_time": "10:00", "close_time": "21:00"},
+                "saturday": {"is_open": True, "open_time": "09:00", "close_time": "22:00"},
+                "sunday": {"is_open": True, "open_time": "11:00", "close_time": "20:00"}
+            },
+            "default_markup_percentage": 35.0 if is_premium else 25.0,
+            "allow_discount": True,
+            "max_discount_percentage": 20.0 if is_premium else 15.0,
+            "tax_settings": {
+                "gst_rate": 18.0,
+                "inclusive_pricing": True,
+                "tax_exemption": False
+            },
+            "is_active": True,
+            "created_by": "user_company_admin",
+            "created_at": datetime.utcnow(),
+            "updated_by": None,
+            "updated_at": None,
+            "custom_fields": {
+                "region": region,
+                "category": category,
+                "loyalty_program": is_premium,
+                "online_booking": is_premium
+            }
+        })
+    
+    return settings
+
+async def create_hierarchical_data():
+    """Create complete hierarchical merchant data."""
+    client = None
+    try:
+        print("🚀 Creating hierarchical merchant ecosystem...")
+        
+        # Connect to MongoDB
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        
+        # Test connection
+        await client.admin.command('ping')
+        print(f"✅ Connected to database: {settings.MONGODB_DB_NAME}")
+        
+        # Clear existing data (optional - comment out to preserve existing data)
+        print("🧹 Clearing existing hierarchical data...")
+        await db[SCM_ACCESS_ROLES_COLLECTION].delete_many({})
+        await db[SCM_SYSTEM_USERS_COLLECTION].delete_many({"username": {"$in": ["superadmin", "companyadmin", "cnfmanager_north", "cnfmanager_south", "cnfmanager_west"]}})
+        await db[SCM_MERCHANT_SETTINGS_COLLECTION].delete_many({})
+        await db[SCM_MERCHANTS_COLLECTION].delete_many({"merchant_code": {"$regex": "^(CUATRO|CNF|DIST|SALON)"}})
+        
+        # 1. Create Access Roles
+        print("👮 Creating access roles...")
+        await db[SCM_ACCESS_ROLES_COLLECTION].insert_many(ACCESS_ROLES)
+        print(f"✅ Created {len(ACCESS_ROLES)} access roles")
+        
+        # 2. Create Parent Company
+        print("🏢 Creating parent company...")
+        parent_company = MERCHANT_HIERARCHY["parent_company"].copy()
+        parent_company["created_at"] = datetime.utcnow()
+        await db[SCM_MERCHANTS_COLLECTION].insert_one(parent_company)
+        print(f"✅ Created parent company: {parent_company['merchant_name']}")
+        
+        # 3. Create CNFs
+        print("🏭 Creating CNFs...")
+        cnfs_created = 0
+        for cnf_data in MERCHANT_HIERARCHY["cnfs"]:
+            cnf = cnf_data.copy()
+            cnf["created_at"] = datetime.utcnow()
+            await db[SCM_MERCHANTS_COLLECTION].insert_one(cnf)
+            cnfs_created += 1
+        print(f"✅ Created {cnfs_created} CNFs")
+        
+        # 4. Create Distributors
+        print("📦 Creating distributors...")
+        distributors_created = 0
+        for dist_data in MERCHANT_HIERARCHY["distributors"]:
+            distributor = dist_data.copy()
+            distributor["created_at"] = datetime.utcnow()
+            await db[SCM_MERCHANTS_COLLECTION].insert_one(distributor)
+            distributors_created += 1
+        print(f"✅ Created {distributors_created} distributors")
+        
+        # 5. Create Salons
+        print("💄 Creating salons...")
+        salons_created = 0
+        for salon_data in MERCHANT_HIERARCHY["salons"]:
+            salon = salon_data.copy()
+            salon["created_at"] = datetime.utcnow()
+            await db[SCM_MERCHANTS_COLLECTION].insert_one(salon)
+            salons_created += 1
+        print(f"✅ Created {salons_created} salons")
+        
+        # 6. Create System Users
+        print("👤 Creating system users...")
+        users = generate_system_users()
+        await db[SCM_SYSTEM_USERS_COLLECTION].insert_many(users)
+        print(f"✅ Created {len(users)} system users")
+        
+        # 7. Create Merchant Settings
+        print("⚙️ Creating merchant settings...")
+        merchant_settings = generate_merchant_settings()
+        await db[SCM_MERCHANT_SETTINGS_COLLECTION].insert_many(merchant_settings)
+        print(f"✅ Created {len(merchant_settings)} merchant settings")
+        
+        # Summary
+        total_merchants = 1 + cnfs_created + distributors_created + salons_created
+        print(f"\n📊 Creation Summary:")
+        print(f"   • Parent Company: 1")
+        print(f"   • CNFs: {cnfs_created}")
+        print(f"   • Distributors: {distributors_created}")
+        print(f"   • Salons: {salons_created}")
+        print(f"   • Total Merchants: {total_merchants}")
+        print(f"   • System Users: {len(users)}")
+        print(f"   • Access Roles: {len(ACCESS_ROLES)}")
+        print(f"   • Merchant Settings: {len(merchant_settings)}")
+        
+        print(f"\n🔗 Hierarchy Structure:")
+        print("   Cuatro Beauty Ltd")
+        print("   ├── North India CNF")
+        print("   │   ├── Delhi Premium Distributors")
+        print("   │   │   ├── CP Luxury Salon")
+        print("   │   │   └── Khan Market Beauty Studio")
+        print("   │   └── Punjab Wholesale Hub")
+        print("   │       └── Model Town Beauty Parlour")
+        print("   ├── South India CNF")
+        print("   │   ├── Chennai Elite Distribution")
+        print("   │   │   ├── T.Nagar Glamour Studio")
+        print("   │   │   └── Express Avenue Beauty Lounge")
+        print("   │   └── Bangalore Metro Supplies")
+        print("   │       └── Brigade Road Style Studio")
+        print("   └── West India CNF")
+        print("       ├── Mumbai Central Distribution")
+        print("       │   ├── Linking Road Fashion Salon")
+        print("       │   └── Colaba Causeway Beauty Hub")
+        print("       └── Pune Premium Hub")
+        print("           └── Koregaon Park Elite Salon")
+        
+    except Exception as e:
+        print(f"❌ Error creating hierarchical data: {e}")
+        raise
+    finally:
+        if client:
+            client.close()
+
+async def verify_hierarchical_data():
+    """Verify the created hierarchical data."""
+    client = None
+    try:
+        print("🔍 Verifying hierarchical merchant data...")
+        
+        # Connect to MongoDB
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        
+        # Test connection
+        await client.admin.command('ping')
+        
+        # Check merchants by type
+        merchants_by_type = {}
+        async for merchant in db[SCM_MERCHANTS_COLLECTION].find({}):
+            merchant_type = merchant.get("merchant_type", "unknown")
+            if merchant_type not in merchants_by_type:
+                merchants_by_type[merchant_type] = []
+            merchants_by_type[merchant_type].append(merchant)
+        
+        print("\n📋 Merchants by Type:")
+        for merchant_type, merchants in merchants_by_type.items():
+            print(f"   {merchant_type.upper()}: {len(merchants)}")
+            for merchant in merchants:
+                parent = merchant.get("parent_merchant_id", "None")
+                print(f"     • {merchant['merchant_name']} (Parent: {parent})")
+        
+        # Check users by role
+        users_by_role = {}
+        async for user in db[SCM_SYSTEM_USERS_COLLECTION].find({}):
+            role_id = user.get("role_id", "unknown")
+            if role_id not in users_by_role:
+                users_by_role[role_id] = []
+            users_by_role[role_id].append(user)
+        
+        print(f"\n👥 Users by Role:")
+        for role_id, users in users_by_role.items():
+            print(f"   {role_id}: {len(users)}")
+            for user in users:
+                print(f"     • {user['full_name']} ({user['username']})")
+        
+        # Check settings
+        settings_count = await db[SCM_MERCHANT_SETTINGS_COLLECTION].count_documents({})
+        roles_count = await db[SCM_ACCESS_ROLES_COLLECTION].count_documents({})
+        
+        print(f"\n📊 Data Verification:")
+        print(f"   • Merchant Settings: {settings_count}")
+        print(f"   • Access Roles: {roles_count}")
+        
+        print(f"\n✅ Hierarchical data verification completed!")
+        
+    except Exception as e:
+        print(f"❌ Error verifying data: {e}")
+        raise
+    finally:
+        if client:
+            client.close()
+
+async def main():
+    """Main function to handle commands."""
+    if len(sys.argv) < 2:
+        print("Hierarchical Merchant Data Management")
+        print("=" * 45)
+        print()
+        print("Commands:")
+        print("  create    Create complete hierarchical merchant data")
+        print("  verify    Verify created hierarchical data")
+        print("  help      Show this help message")
+        print()
+        print("Examples:")
+        print("  python3 create_hierarchy.py create")
+        print("  python3 create_hierarchy.py verify")
+        return 1
+    
+    command = sys.argv[1].lower()
+    
+    try:
+        if command == "create":
+            await create_hierarchical_data()
+            print("\n✅ Hierarchical data creation completed!")
+            print("\nNext steps:")
+            print("1. Start the FastAPI server: uvicorn app.main:app --reload")
+            print("2. Visit http://localhost:8000/docs")
+            print("3. Test the API endpoints with the created data")
+            print("4. Login credentials:")
+            print("   • Super Admin: superadmin / SuperAdmin@123")
+            print("   • Company Admin: companyadmin / CompanyAdmin@123")
+            print("   • CNF Manager (North): cnfmanager_north / CNFManager@123")
+            
+        elif command == "verify":
+            await verify_hierarchical_data()
+            
+        elif command in ["help", "-h", "--help"]:
+            await main()  # Show help
+            
+        else:
+            print(f"❌ Unknown command: {command}")
+            await main()  # Show help
+            return 1
+            
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+    
+    return 0
+
+if __name__ == "__main__":
+    exit_code = asyncio.run(main())
+    sys.exit(exit_code)

export_sample_data.py

@@ -0,0 +1,96 @@
+"""
+Export sample merchant settings data to JSON format.
+"""
+import asyncio
+import json
+from datetime import datetime
+from motor.motor_asyncio import AsyncIOMotorClient
+import sys
+import os
+
+# Add the current directory to Python path
+sys.path.insert(0, os.path.dirname(__file__))
+
+from app.core.config import settings
+from app.constants.collections import SCM_MERCHANT_SETTINGS_COLLECTION
+
+
+def datetime_serializer(obj):
+    """JSON serializer for datetime objects."""
+    if isinstance(obj, datetime):
+        return obj.isoformat() + "Z"
+    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
+
+
+async def export_sample_data():
+    """Export sample data to JSON format."""
+    client = None
+    try:
+        print("📤 Exporting sample merchant settings data...")
+        
+        # Connect to MongoDB
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        
+        # Test connection
+        await client.admin.command('ping')
+        
+        collection = db[SCM_MERCHANT_SETTINGS_COLLECTION]
+        
+        # Fetch all records
+        records = []
+        async for record in collection.find({}).sort("created_at", 1):
+            # Remove MongoDB _id field
+            record.pop("_id", None)
+            records.append(record)
+        
+        if not records:
+            print("❌ No records found to export")
+            return
+        
+        # Create export data structure
+        export_data = {
+            "export_info": {
+                "timestamp": datetime.now().isoformat() + "Z",
+                "total_records": len(records),
+                "collection": SCM_MERCHANT_SETTINGS_COLLECTION,
+                "database": settings.MONGODB_DB_NAME
+            },
+            "sample_records": records
+        }
+        
+        # Export to JSON file
+        filename = f"merchant_settings_sample_data_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+        
+        with open(filename, 'w', encoding='utf-8') as f:
+            json.dump(export_data, f, indent=2, default=datetime_serializer, ensure_ascii=False)
+        
+        print(f"✅ Exported {len(records)} records to: {filename}")
+        
+        # Also print a summary to console
+        print("\n📊 Sample Records Summary:")
+        print("=" * 60)
+        
+        for i, record in enumerate(records, 1):
+            status = "🟢 Active" if record.get("is_active") else "🔴 Inactive"
+            merchant_id = record.get("merchant_id", "N/A")
+            credit_limit = record.get("credit_limit", 0)
+            region = record.get("custom_fields", {}).get("region", "N/A")
+            category = record.get("custom_fields", {}).get("category", "N/A")
+            
+            print(f"{i:2d}. {status} | {merchant_id}")
+            print(f"    Credit: ₹{credit_limit:,.2f} | Region: {region} | Category: {category}")
+        
+        print("\n" + "=" * 60)
+        print(f"📁 Full data exported to: {filename}")
+        
+    except Exception as e:
+        print(f"❌ Error exporting data: {e}")
+        raise
+    finally:
+        if client:
+            client.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(export_sample_data())

manage_db.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+SCM Database Management Script
+Provides easy commands to initialize and manage the database.
+"""
+import asyncio
+import sys
+import os
+
+# Add the current directory to Python path
+sys.path.insert(0, os.path.dirname(__file__))
+
+try:
+    from app.db_init.merchant_settings_init import initialize_merchant_settings_database
+    from motor.motor_asyncio import AsyncIOMotorClient
+    from insightfy_utils.logging import get_logger
+    from app.core.config import settings
+except ImportError as e:
+    print(f"❌ Import error: {e}")
+    print("Make sure you're running this from the project root and dependencies are installed.")
+    sys.exit(1)
+
+
+def print_help():
+    """Print usage information."""
+    print("SCM Database Management Script")
+    print("=" * 40)
+    print()
+    print("Commands:")
+    print("  init-db          Initialize database structure (collections, indexes)")
+    print("  verify-db        Verify database setup and configuration")
+    print("  help             Show this help message")
+    print()
+    print("Examples:")
+    print("  python manage_db.py init-db")
+    print("  python manage_db.py verify-db")
+
+
+async def initialize_database():
+    """Initialize the database structure."""
+    client = None
+    try:
+        logger = get_logger(__name__)
+        logger.info("Starting database initialization")
+        
+        # Connect to MongoDB
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        
+        # Test connection
+        await client.admin.command('ping')
+        print(f"✅ Connected to database: {settings.MONGODB_DB_NAME}")
+        
+        # Initialize merchant settings
+        await initialize_merchant_settings_database(db)
+        
+        print("✅ Database initialization completed successfully")
+        
+    except Exception as e:
+        print(f"❌ Database initialization failed: {e}")
+        raise
+    finally:
+        if client:
+            client.close()
+
+
+async def verify_database():
+    """Verify database setup."""
+    client = None
+    try:
+        logger = get_logger(__name__)
+        
+        # Connect to MongoDB
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        
+        # Test connection
+        await client.admin.command('ping')
+        print(f"✅ Connected to database: {settings.MONGODB_DB_NAME}")
+        
+        # List collections
+        collections = await db.list_collection_names()
+        print(f"📁 Collections found: {len(collections)}")
+        for collection in collections:
+            print(f"  - {collection}")
+        
+        # Check merchant settings collection specifically
+        from app.constants.collections import SCM_MERCHANT_SETTINGS_COLLECTION
+        
+        if SCM_MERCHANT_SETTINGS_COLLECTION in collections:
+            collection = db[SCM_MERCHANT_SETTINGS_COLLECTION]
+            indexes = await collection.index_information()
+            print(f"✅ {SCM_MERCHANT_SETTINGS_COLLECTION} has {len(indexes)} indexes:")
+            for index_name in indexes.keys():
+                print(f"  - {index_name}")
+        else:
+            print(f"❌ {SCM_MERCHANT_SETTINGS_COLLECTION} collection not found")
+        
+    except Exception as e:
+        print(f"❌ Database verification failed: {e}")
+        raise
+    finally:
+        if client:
+            client.close()
+
+
+async def main():
+    """Main function to handle commands."""
+    if len(sys.argv) < 2:
+        print_help()
+        return 1
+    
+    command = sys.argv[1].lower()
+    
+    try:
+        if command == "init-db":
+            print("🚀 Initializing SCM database structure...")
+            print("This will create collections, indexes, and validation rules.")
+            print()
+            
+            await initialize_database()
+            
+            print()
+            print("Next steps:")
+            print("1. Start the FastAPI server: uvicorn app.main:app --reload")
+            print("2. Visit http://localhost:8000/docs to test the API")
+            print("3. Use the merchant settings endpoints to create configurations")
+            
+        elif command == "verify-db":
+            print("🔍 Verifying SCM database setup...")
+            print()
+            
+            await verify_database()
+            
+        elif command in ["help", "-h", "--help"]:
+            print_help()
+            
+        else:
+            print(f"❌ Unknown command: {command}")
+            print()
+            print_help()
+            return 1
+            
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+    
+    return 0
+
+
+if __name__ == "__main__":
+    exit_code = asyncio.run(main())
+    sys.exit(exit_code)

sample_records.py

@@ -0,0 +1,518 @@
+"""
+Sample data insertion script for merchant settings.
+Creates realistic sample records for testing and demonstration.
+"""
+import asyncio
+from datetime import datetime, timedelta
+from motor.motor_asyncio import AsyncIOMotorClient
+from insightfy_utils.logging import get_logger
+import sys
+import os
+
+# Add the current directory to Python path
+sys.path.insert(0, os.path.dirname(__file__))
+
+from app.core.config import settings
+from app.constants.collections import SCM_MERCHANT_SETTINGS_COLLECTION, SCM_MERCHANTS_COLLECTION
+
+logger = get_logger(__name__)
+
+# Sample merchant settings data
+SAMPLE_SETTINGS = [
+    {
+        "merchant_id": "mch_salon_mumbai_001",
+        "auto_allocate_stock": True,
+        "credit_limit": 250000.0,
+        "payment_terms_days": 15,
+        "low_stock_threshold": 5,
+        "enable_backorder": False,
+        "auto_reorder": True,
+        "email_notifications": True,
+        "sms_notifications": True,
+        "low_stock_alerts": True,
+        "order_status_updates": True,
+        "operating_hours": {
+            "monday": {"is_open": True, "open_time": "10:00", "close_time": "20:00"},
+            "tuesday": {"is_open": True, "open_time": "10:00", "close_time": "20:00"},
+            "wednesday": {"is_open": True, "open_time": "10:00", "close_time": "20:00"},
+            "thursday": {"is_open": True, "open_time": "10:00", "close_time": "20:00"},
+            "friday": {"is_open": True, "open_time": "10:00", "close_time": "21:00"},
+            "saturday": {"is_open": True, "open_time": "09:00", "close_time": "22:00"},
+            "sunday": {"is_open": True, "open_time": "11:00", "close_time": "20:00"}
+        },
+        "default_markup_percentage": 30.0,
+        "allow_discount": True,
+        "max_discount_percentage": 15.0,
+        "tax_settings": {
+            "gst_rate": 18.0,
+            "inclusive_pricing": True,
+            "tax_exemption": False
+        },
+        "is_active": True,
+        "created_by": "admin_001",
+        "created_at": datetime.utcnow() - timedelta(days=30),
+        "updated_by": "admin_001",
+        "updated_at": datetime.utcnow() - timedelta(days=5),
+        "custom_fields": {
+            "region": "Mumbai",
+            "category": "premium",
+            "loyalty_program": True,
+            "online_booking": True
+        }
+    },
+    {
+        "merchant_id": "mch_distributor_delhi_001",
+        "auto_allocate_stock": False,
+        "credit_limit": 2000000.0,
+        "payment_terms_days": 45,
+        "low_stock_threshold": 50,
+        "enable_backorder": True,
+        "auto_reorder": False,
+        "email_notifications": True,
+        "sms_notifications": False,
+        "low_stock_alerts": True,
+        "order_status_updates": True,
+        "operating_hours": {
+            "monday": {"is_open": True, "open_time": "08:00", "close_time": "18:00"},
+            "tuesday": {"is_open": True, "open_time": "08:00", "close_time": "18:00"},
+            "wednesday": {"is_open": True, "open_time": "08:00", "close_time": "18:00"},
+            "thursday": {"is_open": True, "open_time": "08:00", "close_time": "18:00"},
+            "friday": {"is_open": True, "open_time": "08:00", "close_time": "18:00"},
+            "saturday": {"is_open": True, "open_time": "09:00", "close_time": "16:00"},
+            "sunday": {"is_open": False}
+        },
+        "default_markup_percentage": 12.0,
+        "allow_discount": True,
+        "max_discount_percentage": 5.0,
+        "tax_settings": {
+            "gst_rate": 18.0,
+            "inclusive_pricing": False,
+            "tax_exemption": False
+        },
+        "is_active": True,
+        "created_by": "system_admin",
+        "created_at": datetime.utcnow() - timedelta(days=60),
+        "updated_by": "manager_002",
+        "updated_at": datetime.utcnow() - timedelta(days=10),
+        "custom_fields": {
+            "region": "North India",
+            "category": "wholesale",
+            "warehouse_count": 3,
+            "delivery_zones": ["Delhi", "Gurgaon", "Noida", "Faridabad"]
+        }
+    },
+    {
+        "merchant_id": "mch_salon_bangalore_002",
+        "auto_allocate_stock": True,
+        "credit_limit": 150000.0,
+        "payment_terms_days": 30,
+        "low_stock_threshold": 8,
+        "enable_backorder": False,
+        "auto_reorder": True,
+        "email_notifications": True,
+        "sms_notifications": True,
+        "low_stock_alerts": True,
+        "order_status_updates": True,
+        "operating_hours": {
+            "monday": {"is_open": True, "open_time": "09:30", "close_time": "19:30"},
+            "tuesday": {"is_open": True, "open_time": "09:30", "close_time": "19:30"},
+            "wednesday": {"is_open": True, "open_time": "09:30", "close_time": "19:30"},
+            "thursday": {"is_open": True, "open_time": "09:30", "close_time": "19:30"},
+            "friday": {"is_open": True, "open_time": "09:30", "close_time": "20:00"},
+            "saturday": {"is_open": True, "open_time": "09:00", "close_time": "21:00"},
+            "sunday": {"is_open": True, "open_time": "10:00", "close_time": "19:00"}
+        },
+        "default_markup_percentage": 25.0,
+        "allow_discount": True,
+        "max_discount_percentage": 12.0,
+        "tax_settings": {
+            "gst_rate": 18.0,
+            "inclusive_pricing": True,
+            "tax_exemption": False
+        },
+        "is_active": True,
+        "created_by": "regional_manager",
+        "created_at": datetime.utcnow() - timedelta(days=45),
+        "updated_by": "store_manager_003",
+        "updated_at": datetime.utcnow() - timedelta(days=2),
+        "custom_fields": {
+            "region": "Bangalore",
+            "category": "standard",
+            "loyalty_program": False,
+            "online_booking": True,
+            "staff_count": 8
+        }
+    },
+    {
+        "merchant_id": "mch_cnf_chennai_001",
+        "auto_allocate_stock": False,
+        "credit_limit": 5000000.0,
+        "payment_terms_days": 60,
+        "low_stock_threshold": 100,
+        "enable_backorder": True,
+        "auto_reorder": True,
+        "email_notifications": True,
+        "sms_notifications": False,
+        "low_stock_alerts": True,
+        "order_status_updates": True,
+        "operating_hours": {
+            "monday": {"is_open": True, "open_time": "07:00", "close_time": "19:00"},
+            "tuesday": {"is_open": True, "open_time": "07:00", "close_time": "19:00"},
+            "wednesday": {"is_open": True, "open_time": "07:00", "close_time": "19:00"},
+            "thursday": {"is_open": True, "open_time": "07:00", "close_time": "19:00"},
+            "friday": {"is_open": True, "open_time": "07:00", "close_time": "19:00"},
+            "saturday": {"is_open": True, "open_time": "08:00", "close_time": "17:00"},
+            "sunday": {"is_open": False}
+        },
+        "default_markup_percentage": 8.0,
+        "allow_discount": True,
+        "max_discount_percentage": 3.0,
+        "tax_settings": {
+            "gst_rate": 18.0,
+            "inclusive_pricing": False,
+            "tax_exemption": False
+        },
+        "is_active": True,
+        "created_by": "head_office",
+        "created_at": datetime.utcnow() - timedelta(days=90),
+        "updated_by": "operations_manager",
+        "updated_at": datetime.utcnow() - timedelta(days=7),
+        "custom_fields": {
+            "region": "South India",
+            "category": "cnf",
+            "warehouse_capacity": "50000 sqft",
+            "distribution_network": ["Chennai", "Coimbatore", "Madurai", "Trichy"],
+            "cold_storage": True
+        }
+    },
+    {
+        "merchant_id": "mch_salon_pune_003",
+        "auto_allocate_stock": True,
+        "credit_limit": 100000.0,
+        "payment_terms_days": 20,
+        "low_stock_threshold": 6,
+        "enable_backorder": False,
+        "auto_reorder": False,
+        "email_notifications": True,
+        "sms_notifications": False,
+        "low_stock_alerts": True,
+        "order_status_updates": False,
+        "operating_hours": {
+            "monday": {"is_open": True, "open_time": "10:00", "close_time": "19:00"},
+            "tuesday": {"is_open": True, "open_time": "10:00", "close_time": "19:00"},
+            "wednesday": {"is_open": True, "open_time": "10:00", "close_time": "19:00"},
+            "thursday": {"is_open": True, "open_time": "10:00", "close_time": "19:00"},
+            "friday": {"is_open": True, "open_time": "10:00", "close_time": "20:00"},
+            "saturday": {"is_open": True, "open_time": "09:30", "close_time": "20:30"},
+            "sunday": {"is_open": False}
+        },
+        "default_markup_percentage": 22.0,
+        "allow_discount": False,
+        "max_discount_percentage": 0.0,
+        "tax_settings": {
+            "gst_rate": 18.0,
+            "inclusive_pricing": True,
+            "tax_exemption": False
+        },
+        "is_active": False,  # Inactive salon for testing
+        "created_by": "franchise_manager",
+        "created_at": datetime.utcnow() - timedelta(days=20),
+        "updated_by": "franchise_manager",
+        "updated_at": datetime.utcnow() - timedelta(days=1),
+        "custom_fields": {
+            "region": "Pune",
+            "category": "budget",
+            "loyalty_program": False,
+            "online_booking": False,
+            "closure_reason": "Temporarily closed for renovation"
+        }
+    }
+]
+
+
+async def create_sample_merchants():
+    """Create sample merchants if they don't exist."""
+    client = AsyncIOMotorClient(settings.MONGODB_URI)
+    db = client[settings.MONGODB_DB_NAME]
+    
+    sample_merchants = [
+        {
+            "merchant_id": "mch_salon_mumbai_001",
+            "merchant_type": "salon",
+            "merchant_code": "SAL-MUM-001",
+            "merchant_name": "Glamour Studio Mumbai",
+            "status": "active",
+            "created_by": "admin_001",
+            "created_at": datetime.utcnow() - timedelta(days=30)
+        },
+        {
+            "merchant_id": "mch_distributor_delhi_001",
+            "merchant_type": "distributor",
+            "merchant_code": "DIST-DEL-001",
+            "merchant_name": "Beauty Products Distributor Delhi",
+            "status": "active",
+            "created_by": "system_admin",
+            "created_at": datetime.utcnow() - timedelta(days=60)
+        },
+        {
+            "merchant_id": "mch_salon_bangalore_002",
+            "merchant_type": "salon",
+            "merchant_code": "SAL-BLR-002",
+            "merchant_name": "Trend Salon Bangalore",
+            "status": "active",
+            "created_by": "regional_manager",
+            "created_at": datetime.utcnow() - timedelta(days=45)
+        },
+        {
+            "merchant_id": "mch_cnf_chennai_001",
+            "merchant_type": "cnf",
+            "merchant_code": "CNF-CHN-001",
+            "merchant_name": "South India Beauty CNF",
+            "status": "active",
+            "created_by": "head_office",
+            "created_at": datetime.utcnow() - timedelta(days=90)
+        },
+        {
+            "merchant_id": "mch_salon_pune_003",
+            "merchant_type": "salon",
+            "merchant_code": "SAL-PUN-003",
+            "merchant_name": "Style Zone Pune",
+            "status": "active",
+            "created_by": "franchise_manager",
+            "created_at": datetime.utcnow() - timedelta(days=20)
+        }
+    ]
+    
+    merchants_collection = db[SCM_MERCHANTS_COLLECTION]
+    
+    for merchant in sample_merchants:
+        existing = await merchants_collection.find_one({"merchant_id": merchant["merchant_id"]})
+        if not existing:
+            await merchants_collection.insert_one(merchant)
+            print(f"✅ Created sample merchant: {merchant['merchant_name']}")
+        else:
+            print(f"⚠️  Merchant already exists: {merchant['merchant_name']}")
+    
+    client.close()
+
+
+async def insert_sample_settings():
+    """Insert sample merchant settings records."""
+    client = None
+    try:
+        print("🚀 Inserting sample merchant settings records...")
+        
+        # Connect to MongoDB
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        
+        # Test connection
+        await client.admin.command('ping')
+        print(f"✅ Connected to database: {settings.MONGODB_DB_NAME}")
+        
+        # Create sample merchants first
+        await create_sample_merchants()
+        
+        # Insert sample settings
+        collection = db[SCM_MERCHANT_SETTINGS_COLLECTION]
+        
+        inserted_count = 0
+        updated_count = 0
+        
+        for settings_data in SAMPLE_SETTINGS:
+            # Check if settings already exist for this merchant
+            existing = await collection.find_one({"merchant_id": settings_data["merchant_id"]})
+            
+            if existing:
+                # Update existing record
+                result = await collection.replace_one(
+                    {"merchant_id": settings_data["merchant_id"]},
+                    settings_data
+                )
+                if result.modified_count > 0:
+                    updated_count += 1
+                    print(f"🔄 Updated settings for: {settings_data['merchant_id']}")
+            else:
+                # Insert new record
+                await collection.insert_one(settings_data.copy())
+                inserted_count += 1
+                print(f"✅ Inserted settings for: {settings_data['merchant_id']}")
+        
+        print(f"\n📊 Sample Data Summary:")
+        print(f"   • Inserted: {inserted_count} new records")
+        print(f"   • Updated: {updated_count} existing records")
+        print(f"   • Total: {len(SAMPLE_SETTINGS)} sample records")
+        
+        # Show collection stats
+        total_count = await collection.count_documents({})
+        active_count = await collection.count_documents({"is_active": True})
+        inactive_count = await collection.count_documents({"is_active": False})
+        
+        print(f"\n📈 Collection Statistics:")
+        print(f"   • Total settings records: {total_count}")
+        print(f"   • Active settings: {active_count}")
+        print(f"   • Inactive settings: {inactive_count}")
+        
+    except Exception as e:
+        print(f"❌ Error inserting sample data: {e}")
+        raise
+    finally:
+        if client:
+            client.close()
+
+
+async def view_sample_records():
+    """View the inserted sample records."""
+    client = None
+    try:
+        print("🔍 Viewing sample merchant settings records...")
+        
+        # Connect to MongoDB
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        
+        # Test connection
+        await client.admin.command('ping')
+        
+        collection = db[SCM_MERCHANT_SETTINGS_COLLECTION]
+        
+        # Fetch all records
+        records = []
+        async for record in collection.find({}).sort("created_at", 1):
+            records.append(record)
+        
+        if not records:
+            print("❌ No records found. Run 'insert' command first.")
+            return
+        
+        print(f"\n📋 Found {len(records)} merchant settings records:")
+        print("=" * 80)
+        
+        for i, record in enumerate(records, 1):
+            status_icon = "🟢" if record.get("is_active") else "🔴"
+            print(f"\n{i}. {status_icon} {record['merchant_id']}")
+            print(f"   Credit Limit: ₹{record.get('credit_limit', 0):,.2f}")
+            print(f"   Payment Terms: {record.get('payment_terms_days', 0)} days")
+            print(f"   Stock Threshold: {record.get('low_stock_threshold', 0)} units")
+            print(f"   Auto Allocate: {'Yes' if record.get('auto_allocate_stock') else 'No'}")
+            print(f"   Email Alerts: {'Yes' if record.get('email_notifications') else 'No'}")
+            print(f"   SMS Alerts: {'Yes' if record.get('sms_notifications') else 'No'}")
+            
+            # Operating hours summary
+            operating_hours = record.get('operating_hours', {})
+            if operating_hours:
+                open_days = sum(1 for day_info in operating_hours.values() 
+                               if isinstance(day_info, dict) and day_info.get('is_open'))
+                print(f"   Operating Days: {open_days}/7 days")
+            
+            # Tax settings
+            tax_settings = record.get('tax_settings', {})
+            if tax_settings:
+                gst_rate = tax_settings.get('gst_rate', 0)
+                print(f"   GST Rate: {gst_rate}%")
+            
+            print(f"   Created: {record.get('created_at', 'N/A')}")
+            print(f"   Updated: {record.get('updated_at', 'N/A')}")
+            
+            # Custom fields
+            custom_fields = record.get('custom_fields', {})
+            if custom_fields:
+                region = custom_fields.get('region', 'N/A')
+                category = custom_fields.get('category', 'N/A')
+                print(f"   Region: {region} | Category: {category}")
+        
+        print("\n" + "=" * 80)
+        
+    except Exception as e:
+        print(f"❌ Error viewing records: {e}")
+        raise
+    finally:
+        if client:
+            client.close()
+
+
+async def clear_sample_data():
+    """Clear all sample merchant settings data."""
+    client = None
+    try:
+        print("🗑️  Clearing sample merchant settings data...")
+        
+        # Connect to MongoDB
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        
+        # Test connection
+        await client.admin.command('ping')
+        
+        collection = db[SCM_MERCHANT_SETTINGS_COLLECTION]
+        
+        # Count before deletion
+        before_count = await collection.count_documents({})
+        
+        # Delete all records
+        result = await collection.delete_many({})
+        
+        print(f"✅ Cleared {result.deleted_count} records (was {before_count})")
+        
+    except Exception as e:
+        print(f"❌ Error clearing data: {e}")
+        raise
+    finally:
+        if client:
+            client.close()
+
+
+async def main():
+    """Main function to handle commands."""
+    if len(sys.argv) < 2:
+        print("Sample Merchant Settings Data Management")
+        print("=" * 45)
+        print()
+        print("Commands:")
+        print("  insert    Insert sample merchant settings records")
+        print("  view      View existing sample records")
+        print("  clear     Clear all sample data")
+        print("  help      Show this help message")
+        print()
+        print("Examples:")
+        print("  python3 sample_records.py insert")
+        print("  python3 sample_records.py view")
+        return 1
+    
+    command = sys.argv[1].lower()
+    
+    try:
+        if command == "insert":
+            await insert_sample_settings()
+            print("\n✅ Sample data insertion completed!")
+            print("\nNext steps:")
+            print("1. Start the FastAPI server: uvicorn app.main:app --reload")
+            print("2. Visit http://localhost:8000/docs")
+            print("3. Test the merchant settings GET endpoints")
+            
+        elif command == "view":
+            await view_sample_records()
+            
+        elif command == "clear":
+            await clear_sample_data()
+            
+        elif command in ["help", "-h", "--help"]:
+            await main()  # Show help
+            
+        else:
+            print(f"❌ Unknown command: {command}")
+            await main()  # Show help
+            return 1
+            
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+    
+    return 0
+
+
+if __name__ == "__main__":
+    exit_code = asyncio.run(main())
+    sys.exit(exit_code)