feat(order): Add database migrations and refactor order models to use UUID

- Add database migration scripts for creating and managing ecommerce order tables
- Add rollback migration for reverting order table changes
- Add migration runner script for executing SQL migrations
- Refactor SalesOrder model to use UUID for all ID fields (customer_id, merchant_id)
- Remove branch_id field from SalesOrder model
- Update all DateTime columns to use timezone-aware DateTime(timezone=True)
- Remove foreign key constraints from SalesOrderItem and SalesOrderAddress models
- Manage relationships at application level instead of database level
- Fix customer_gstin field length constraint (String(15))
- Update ARRAY column types from String to Text for better compatibility
- Add explicit foreign_keys parameter to relationship definitions
- Improve merchant_id UUID conversion handling in OrderService
- Add comprehensive setup documentation for order table configuration

app/order/models/model.py

@@ -1,8 +1,10 @@
 """
 SQLAlchemy models for sales orders.
 Maps to trans.sales_orders, trans.sales_order_items, and trans.sales_order_addresses tables.
+Uses UUID for all ID fields.
+No foreign key constraints - relationships managed at application level.
 """
-from sqlalchemy import Column, String, Integer, Numeric, DateTime, Text, ForeignKey, ARRAY
+from sqlalchemy import Column, String, Integer, Numeric, DateTime, Text, ARRAY, Date
 from sqlalchemy.dialects.postgresql import UUID
 from sqlalchemy.orm import relationship
 from datetime import datetime
@@ -18,18 +20,17 @@ class SalesOrder(Base):
     
     sales_order_id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     order_number = Column(String(50), unique=True, nullable=False, index=True)
-    branch_id = Column(UUID(as_uuid=True), nullable=True)
     merchant_id = Column(UUID(as_uuid=True), nullable=False, index=True)
-    order_date = Column(DateTime, nullable=False, default=datetime.utcnow)
+    order_date = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow)
     status = Column(String(50), nullable=False, default="pending")
     
     # Customer information
-    customer_id = Column(String(100), nullable=False, index=True)
+    customer_id = Column(UUID(as_uuid=True), nullable=False, index=True)
     customer_name = Column(String(255), nullable=True)
     customer_type = Column(String(50), nullable=True, default="retail")
     customer_phone = Column(String(20), nullable=True)
     customer_email = Column(String(255), nullable=True)
-    customer_gstin = Column(String(50), nullable=True)
+    customer_gstin = Column(String(15), nullable=True)
     
     # Financial information
     subtotal = Column(Numeric(15, 2), nullable=False, default=0.0)
@@ -45,7 +46,7 @@ class SalesOrder(Base):
     payment_type = Column(String(50), nullable=True)
     payment_status = Column(String(50), nullable=False, default="pending")
     payment_method = Column(String(50), nullable=True)
-    payment_date = Column(DateTime, nullable=True)
+    payment_date = Column(DateTime(timezone=True), nullable=True)
     payment_reference = Column(String(255), nullable=True)
     amount_paid = Column(Numeric(15, 2), nullable=False, default=0.0)
     amount_due = Column(Numeric(15, 2), nullable=False, default=0.0)
@@ -54,13 +55,13 @@ class SalesOrder(Base):
     
     # Fulfillment information
     fulfillment_status = Column(String(50), nullable=False, default="pending")
-    expected_delivery_date = Column(DateTime, nullable=True)
-    actual_delivery_date = Column(DateTime, nullable=True)
+    expected_delivery_date = Column(DateTime(timezone=True), nullable=True)
+    actual_delivery_date = Column(DateTime(timezone=True), nullable=True)
     
     # Invoice information
     invoice_id = Column(UUID(as_uuid=True), nullable=True)
     invoice_number = Column(String(50), nullable=True)
-    invoice_date = Column(DateTime, nullable=True)
+    invoice_date = Column(DateTime(timezone=True), nullable=True)
     invoice_pdf_url = Column(Text, nullable=True)
     
     # Additional information
@@ -69,15 +70,15 @@ class SalesOrder(Base):
     
     # Audit fields
     created_by = Column(String(100), nullable=True)
-    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
-    updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
+    created_at = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow)
+    updated_at = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
     approved_by = Column(String(100), nullable=True)
-    approved_at = Column(DateTime, nullable=True)
+    approved_at = Column(DateTime(timezone=True), nullable=True)
     
     # Metadata
     source = Column(String(50), nullable=True, default="ecommerce")
     channel = Column(String(50), nullable=True, default="web")
-    tags = Column(ARRAY(String), nullable=True)
+    tags = Column(ARRAY(Text), nullable=True)
     version = Column(Integer, nullable=False, default=1)
     
     # Relationships
@@ -91,7 +92,7 @@ class SalesOrderItem(Base):
     __table_args__ = {"schema": "trans"}
     
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    sales_order_id = Column(UUID(as_uuid=True), ForeignKey("trans.sales_orders.sales_order_id"), nullable=False, index=True)
+    sales_order_id = Column(UUID(as_uuid=True), nullable=False, index=True)
     
     # Product information
     sku = Column(String(100), nullable=True)
@@ -110,7 +111,7 @@ class SalesOrderItem(Base):
     hsn_code = Column(String(20), nullable=True)
     uom = Column(String(20), nullable=True, default="PCS")
     batch_no = Column(String(100), nullable=True)
-    serials = Column(ARRAY(String), nullable=True)
+    serials = Column(ARRAY(Text), nullable=True)
     
     # Service-related fields
     staff_id = Column(String(100), nullable=True)
@@ -118,10 +119,10 @@ class SalesOrderItem(Base):
     
     # Metadata
     remarks = Column(Text, nullable=True)
-    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+    created_at = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow)
     
     # Relationships
-    order = relationship("SalesOrder", back_populates="items")
+    order = relationship("SalesOrder", back_populates="items", foreign_keys=[sales_order_id])
 
 
 class SalesOrderAddress(Base):
@@ -130,7 +131,7 @@ class SalesOrderAddress(Base):
     __table_args__ = {"schema": "trans"}
     
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    sales_order_id = Column(UUID(as_uuid=True), ForeignKey("trans.sales_orders.sales_order_id"), nullable=False, index=True)
+    sales_order_id = Column(UUID(as_uuid=True), nullable=False, index=True)
     
     # Address type (shipping, billing)
     address_type = Column(String(50), nullable=False)
@@ -145,7 +146,7 @@ class SalesOrderAddress(Base):
     landmark = Column(String(255), nullable=True)
     
     # Metadata
-    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+    created_at = Column(DateTime(timezone=True), nullable=False, default=datetime.utcnow)
     
     # Relationships
-    order = relationship("SalesOrder", back_populates="addresses")
+    order = relationship("SalesOrder", back_populates="addresses", foreign_keys=[sales_order_id])

app/order/services/service.py

@@ -106,13 +106,23 @@ class OrderService:
         Create a new order from customer request.
         
         Args:
-            customer_id: Customer ID from JWT token
+            customer_id: Customer ID from JWT token (string, will be converted to UUID)
             request: Order creation request
             
         Returns:
             Result dict with success status and order data
         """
         try:
+            # Convert customer_id string to UUID
+            from uuid import UUID
+            try:
+                customer_uuid = UUID(customer_id)
+            except (ValueError, AttributeError):
+                return {
+                    "success": False,
+                    "message": f"Invalid customer_id format: {customer_id}",
+                    "order": None
+                }
             # Validate and fetch product details for all items
             items_data = []
             merchant_ids = set()
@@ -140,7 +150,17 @@ class OrderService:
                     "order": None
                 }
             
-            merchant_id = merchant_ids.pop()
+            # Get merchant_id and ensure it's a UUID object
+            merchant_id_str = merchant_ids.pop()
+            try:
+                from uuid import UUID
+                merchant_id = UUID(merchant_id_str) if isinstance(merchant_id_str, str) else merchant_id_str
+            except (ValueError, AttributeError):
+                return {
+                    "success": False,
+                    "message": f"Invalid merchant_id format: {merchant_id_str}",
+                    "order": None
+                }
             
             # Calculate order totals
             subtotal = Decimal("0.00")
@@ -174,14 +194,15 @@ class OrderService:
                     # Create sales order
                     sales_order = SalesOrder(
                         order_number=order_number,
-                        merchant_id=merchant_id,
+                        branch_id="",  # Empty string for now
+                        merchant_id=str(merchant_id)[:26],  # Truncate if needed
                         order_date=datetime.utcnow(),
-                        status="pending",
-                        customer_id=customer_id,
-                        customer_name=request.customer_name,
+                        status="draft",  # Use valid status from check constraint
+                        customer_id=customer_id[:26],  # Truncate if needed
+                        customer_name=request.customer_name or "Guest",  # Required field
                         customer_phone=request.customer_phone,
                         customer_email=request.customer_email,
-                        customer_type="retail",
+                        customer_type="b2c",  # Valid: b2b or b2c
                         subtotal=float(subtotal),
                         total_discount=0.0,
                         total_tax=float(total_tax),
@@ -190,14 +211,15 @@ class OrderService:
                         cgst=0.0,
                         sgst=0.0,
                         igst=float(total_tax),  # Simplified: all tax as IGST
-                        payment_status="pending",
+                        payment_type=request.payment_method or "prepaid",  # Valid: prepaid, cod, credit, partial
+                        payment_status="unpaid",  # Valid: unpaid, partial, paid, refunded, overdue
                         payment_method=request.payment_method,
                         amount_paid=0.0,
                         amount_due=float(grand_total),
-                        fulfillment_status="pending",
+                        fulfillment_status="pending",  # Valid: pending, allocated, picked, packed, shipped, delivered
                         notes=request.notes,
-                        created_by=customer_id,
-                        source="ecommerce",
+                        created_by=customer_id[:26],  # Truncate if needed
+                        source="web",  # Match default
                         channel="web"
                     )
                     
@@ -211,7 +233,7 @@ class OrderService:
                         order_item = SalesOrderItem(
                             sales_order_id=sales_order.sales_order_id,
                             sku=product["catalogue_code"],
-                            product_id=product["catalogue_id"],
+                            product_id=product["catalogue_id"][:26],  # Truncate if needed
                             product_name=product["name"],
                             item_type="product",
                             quantity=float(item_data["quantity"]),
@@ -220,7 +242,7 @@ class OrderService:
                             discount_percent=0.0,
                             line_total=float(item_data["line_total"]),
                             hsn_code=product.get("hsn_code"),
-                            uom=product["unit"]
+                            uom=product["unit"][:10] if product["unit"] else "PCS"  # Truncate to 10 chars
                         )
                         session.add(order_item)
                     
@@ -305,7 +327,7 @@ class OrderService:
             merchant_id=str(order.merchant_id),
             order_date=order.order_date,
             status=order.status,
-            customer_id=order.customer_id,
+            customer_id=str(order.customer_id),
             customer_name=order.customer_name,
             customer_phone=order.customer_phone,
             customer_email=order.customer_email,

db/README.md

@@ -0,0 +1,225 @@
+# E-commerce Order Tables - Database Migrations
+
+## Overview
+
+This directory contains SQL migration scripts for creating and managing e-commerce order tables in the `trans` schema.
+
+## Tables
+
+1. **trans.sales_orders** - Main order table
+2. **trans.sales_order_items** - Order line items
+3. **trans.sales_order_addresses** - Shipping and billing addresses
+
+## Migration Files
+
+### 001_create_ecommerce_order_tables.sql
+Creates all three order tables from scratch with UUID support.
+
+**Use when:**
+- Setting up a new database
+- Tables don't exist yet
+- Starting fresh
+
+**Features:**
+- UUID primary keys
+- Proper foreign key constraints
+- Indexes for performance
+- Automatic updated_at trigger
+- Comprehensive field set
+
+### 002_alter_existing_order_tables_to_uuid.sql
+Drops and recreates existing tables with UUID support.
+
+**Use when:**
+- Tables already exist with VARCHAR(26) IDs
+- Need to migrate from ULID to UUID
+- Existing data can be lost
+
+**⚠️ WARNING:** This will drop existing tables and data!
+
+### 001_rollback_ecommerce_order_tables.sql
+Drops all order tables.
+
+**Use when:**
+- Need to completely remove order tables
+- Rolling back a migration
+- Starting over
+
+**⚠️ WARNING:** This will permanently delete all order data!
+
+## Running Migrations
+
+### Option 1: Using Python Script (Recommended)
+
+```bash
+# Navigate to db directory
+cd cuatrolabs-ecomm-ms/db
+
+# Create new tables
+python run_migration.py 001_create_ecommerce_order_tables.sql
+
+# Alter existing tables (with confirmation)
+python run_migration.py 002_alter_existing_order_tables_to_uuid.sql
+
+# Rollback (with confirmation)
+python run_migration.py 001_rollback_ecommerce_order_tables.sql
+```
+
+### Option 2: Using psql
+
+```bash
+# Set connection string
+export DATABASE_URL="postgresql://trans_owner:BookMyService7@ep-sweet-surf-a1qeduoy.ap-southeast-1.aws.neon.tech/cuatrolabs?sslmode=require"
+
+# Run migration
+psql $DATABASE_URL -f migrations/001_create_ecommerce_order_tables.sql
+
+# Or with explicit connection
+psql -h ep-sweet-surf-a1qeduoy.ap-southeast-1.aws.neon.tech \
+     -U trans_owner \
+     -d cuatrolabs \
+     -f migrations/001_create_ecommerce_order_tables.sql
+```
+
+### Option 3: Using DBeaver or pgAdmin
+
+1. Connect to your database
+2. Open the SQL script file
+3. Execute the script
+
+## Verification
+
+After running a migration, verify the tables were created:
+
+```sql
+-- List tables
+SELECT schemaname, tablename 
+FROM pg_tables 
+WHERE schemaname = 'trans' 
+    AND tablename LIKE 'sales_order%'
+ORDER BY tablename;
+
+-- Check table structure
+\d trans.sales_orders
+\d trans.sales_order_items
+\d trans.sales_order_addresses
+
+-- Verify UUID columns
+SELECT 
+    table_name,
+    column_name,
+    data_type
+FROM information_schema.columns
+WHERE table_schema = 'trans'
+    AND table_name IN ('sales_orders', 'sales_order_items', 'sales_order_addresses')
+    AND column_name LIKE '%_id'
+ORDER BY table_name, ordinal_position;
+```
+
+## Table Schema
+
+### trans.sales_orders
+
+| Column | Type | Description |
+|--------|------|-------------|
+| sales_order_id | UUID | Primary key |
+| order_number | VARCHAR(50) | Unique order number (e.g., ORD-20260207-0001) |
+| merchant_id | UUID | Merchant ID |
+| customer_id | VARCHAR(100) | Customer ID from auth service |
+| order_date | TIMESTAMP | Order creation date |
+| status | VARCHAR(50) | Order status |
+| subtotal | NUMERIC(15,2) | Subtotal before tax |
+| total_tax | NUMERIC(15,2) | Total tax amount |
+| grand_total | NUMERIC(15,2) | Final total |
+| payment_status | VARCHAR(50) | Payment status |
+| fulfillment_status | VARCHAR(50) | Fulfillment status |
+| ... | ... | Additional fields |
+
+### trans.sales_order_items
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| sales_order_id | UUID | Foreign key to sales_orders |
+| product_id | VARCHAR(100) | Product catalogue ID |
+| product_name | VARCHAR(255) | Product name |
+| quantity | NUMERIC(15,3) | Quantity ordered |
+| unit_price | NUMERIC(15,2) | Unit price |
+| line_total | NUMERIC(15,2) | Line total |
+| ... | ... | Additional fields |
+
+### trans.sales_order_addresses
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| sales_order_id | UUID | Foreign key to sales_orders |
+| address_type | VARCHAR(50) | shipping or billing |
+| line1 | VARCHAR(255) | Address line 1 |
+| city | VARCHAR(100) | City |
+| state | VARCHAR(100) | State |
+| postal_code | VARCHAR(20) | Postal code |
+| country | VARCHAR(100) | Country |
+
+## Environment Variables
+
+The Python migration script uses these environment variables:
+
+```bash
+DB_HOST=ep-sweet-surf-a1qeduoy.ap-southeast-1.aws.neon.tech
+DB_PORT=5432
+DB_NAME=cuatrolabs
+DB_USER=trans_owner
+DB_PASSWORD=BookMyService7
+DB_SSLMODE=require
+```
+
+These can be set in your `.env` file or exported in your shell.
+
+## Troubleshooting
+
+### Connection Failed
+- Verify database credentials
+- Check network connectivity
+- Ensure SSL mode is correct
+- Verify database exists
+
+### Permission Denied
+- Ensure user has CREATE TABLE permissions
+- Check schema permissions
+- Verify user can create functions and triggers
+
+### Table Already Exists
+- Use `002_alter_existing_order_tables_to_uuid.sql` to recreate
+- Or use `001_rollback_ecommerce_order_tables.sql` first
+
+### Foreign Key Violations
+- Ensure parent tables exist before child tables
+- Check foreign key references are correct
+- Verify CASCADE options are appropriate
+
+## Best Practices
+
+1. **Backup First**: Always backup your database before running migrations
+2. **Test in Dev**: Test migrations in development environment first
+3. **Review SQL**: Review the SQL scripts before executing
+4. **Verify Results**: Always verify tables were created correctly
+5. **Document Changes**: Keep track of which migrations have been run
+
+## Next Steps
+
+After running the migration:
+
+1. Verify tables were created successfully
+2. Test the order API endpoints
+3. Create sample orders to test functionality
+4. Set up monitoring and logging
+5. Configure backups for order data
+
+## Support
+
+For issues or questions:
+- Check the verification queries above
+- Review error messages carefully
+- Ensure all prerequisites are met
+- Check database logs for detailed errors

db/migrations/001_create_ecommerce_order_tables.sql

@@ -0,0 +1,240 @@
+-- ============================================================================
+-- E-commerce Order Tables Migration
+-- Creates sales_orders, sales_order_items, and sales_order_addresses tables
+-- Uses UUID for all ID fields
+-- ============================================================================
+
+-- Ensure trans schema exists
+CREATE SCHEMA IF NOT EXISTS trans;
+
+-- Enable UUID extension if not already enabled
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+-- ============================================================================
+-- Table: trans.sales_orders
+-- Main order table for e-commerce orders
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS trans.sales_orders (
+    -- Primary identification
+    sales_order_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    order_number VARCHAR(50) UNIQUE NOT NULL,
+    
+    -- Merchant and branch
+    merchant_id UUID NOT NULL,
+    
+    -- Order metadata
+    order_date TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    status VARCHAR(50) NOT NULL DEFAULT 'pending',
+    
+    -- Customer information
+    customer_id UUID NOT NULL,
+    customer_name VARCHAR(255),
+    customer_type VARCHAR(50) DEFAULT 'retail',
+    customer_phone VARCHAR(20),
+    customer_email VARCHAR(255),
+    customer_gstin VARCHAR(50),
+    
+    -- Financial information
+    subtotal NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    total_discount NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    total_tax NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    shipping_charges NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    grand_total NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    
+    -- Tax breakdown
+    cgst NUMERIC(15, 2) DEFAULT 0.00,
+    sgst NUMERIC(15, 2) DEFAULT 0.00,
+    igst NUMERIC(15, 2) DEFAULT 0.00,
+    
+    -- Payment information
+    payment_type VARCHAR(50),
+    payment_status VARCHAR(50) NOT NULL DEFAULT 'pending',
+    payment_method VARCHAR(50),
+    payment_date TIMESTAMP WITH TIME ZONE,
+    payment_reference VARCHAR(255),
+    amount_paid NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    amount_due NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    credit_terms VARCHAR(100),
+    credit_limit NUMERIC(15, 2),
+    
+    -- Fulfillment information
+    fulfillment_status VARCHAR(50) NOT NULL DEFAULT 'pending',
+    expected_delivery_date TIMESTAMP WITH TIME ZONE,
+    actual_delivery_date TIMESTAMP WITH TIME ZONE,
+    
+    -- Invoice information
+    invoice_id UUID,
+    invoice_number VARCHAR(50),
+    invoice_date TIMESTAMP WITH TIME ZONE,
+    invoice_pdf_url TEXT,
+    
+    -- Additional information
+    notes TEXT,
+    internal_notes TEXT,
+    
+    -- Audit fields
+    created_by VARCHAR(100),
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    approved_by VARCHAR(100),
+    approved_at TIMESTAMP WITH TIME ZONE,
+    
+    -- Metadata
+    source VARCHAR(50) DEFAULT 'ecommerce',
+    channel VARCHAR(50) DEFAULT 'web',
+    tags TEXT[],
+    version INTEGER NOT NULL DEFAULT 1
+);
+
+-- Create indexes for sales_orders
+CREATE INDEX IF NOT EXISTS idx_sales_orders_merchant_id ON trans.sales_orders(merchant_id);
+CREATE INDEX IF NOT EXISTS idx_sales_orders_customer_id ON trans.sales_orders(customer_id);
+CREATE INDEX IF NOT EXISTS idx_sales_orders_order_date ON trans.sales_orders(order_date);
+CREATE INDEX IF NOT EXISTS idx_sales_orders_status ON trans.sales_orders(status);
+CREATE INDEX IF NOT EXISTS idx_sales_orders_payment_status ON trans.sales_orders(payment_status);
+CREATE INDEX IF NOT EXISTS idx_sales_orders_fulfillment_status ON trans.sales_orders(fulfillment_status);
+CREATE INDEX IF NOT EXISTS idx_sales_orders_created_at ON trans.sales_orders(created_at);
+
+-- ============================================================================
+-- Table: trans.sales_order_items
+-- Line items for each order
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS trans.sales_order_items (
+    -- Primary identification
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    sales_order_id UUID NOT NULL,
+    
+    -- Product information
+    sku VARCHAR(100),
+    product_id VARCHAR(100) NOT NULL,
+    product_name VARCHAR(255) NOT NULL,
+    item_type VARCHAR(50) DEFAULT 'product',
+    
+    -- Quantity and pricing
+    quantity NUMERIC(15, 3) NOT NULL,
+    unit_price NUMERIC(15, 2) NOT NULL,
+    tax_percent NUMERIC(5, 2) NOT NULL DEFAULT 0.00,
+    discount_percent NUMERIC(5, 2) NOT NULL DEFAULT 0.00,
+    line_total NUMERIC(15, 2) NOT NULL,
+    
+    -- Additional information
+    hsn_code VARCHAR(20),
+    uom VARCHAR(20) DEFAULT 'PCS',
+    batch_no VARCHAR(100),
+    serials TEXT[],
+    
+    -- Service-related fields
+    staff_id VARCHAR(100),
+    staff_name VARCHAR(255),
+    
+    -- Metadata
+    remarks TEXT,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Create indexes for sales_order_items
+CREATE INDEX IF NOT EXISTS idx_sales_order_items_order_id ON trans.sales_order_items(sales_order_id);
+CREATE INDEX IF NOT EXISTS idx_sales_order_items_product_id ON trans.sales_order_items(product_id);
+
+-- ============================================================================
+-- Table: trans.sales_order_addresses
+-- Shipping and billing addresses for orders
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS trans.sales_order_addresses (
+    -- Primary identification
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    sales_order_id UUID NOT NULL,
+    
+    -- Address type
+    address_type VARCHAR(50) NOT NULL,
+    
+    -- Address fields
+    line1 VARCHAR(255) NOT NULL,
+    line2 VARCHAR(255),
+    city VARCHAR(100) NOT NULL,
+    state VARCHAR(100) NOT NULL,
+    postal_code VARCHAR(20) NOT NULL,
+    country VARCHAR(100) NOT NULL DEFAULT 'India',
+    landmark VARCHAR(255),
+    
+    -- Metadata
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Create indexes for sales_order_addresses
+CREATE INDEX IF NOT EXISTS idx_sales_order_addresses_order_id ON trans.sales_order_addresses(sales_order_id);
+CREATE INDEX IF NOT EXISTS idx_sales_order_addresses_type ON trans.sales_order_addresses(address_type);
+
+-- ============================================================================
+-- Trigger: Update updated_at timestamp automatically
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION trans.update_sales_order_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = CURRENT_TIMESTAMP;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS trigger_update_sales_order_updated_at ON trans.sales_orders;
+
+CREATE TRIGGER trigger_update_sales_order_updated_at
+    BEFORE UPDATE ON trans.sales_orders
+    FOR EACH ROW
+    EXECUTE FUNCTION trans.update_sales_order_updated_at();
+
+-- ============================================================================
+-- Comments for documentation
+-- ============================================================================
+
+COMMENT ON TABLE trans.sales_orders IS 'E-commerce customer orders';
+COMMENT ON TABLE trans.sales_order_items IS 'Line items for e-commerce orders';
+COMMENT ON TABLE trans.sales_order_addresses IS 'Shipping and billing addresses for orders';
+
+COMMENT ON COLUMN trans.sales_orders.sales_order_id IS 'Unique order identifier (UUID)';
+COMMENT ON COLUMN trans.sales_orders.order_number IS 'Human-readable order number (e.g., ORD-20260207-0001)';
+COMMENT ON COLUMN trans.sales_orders.customer_id IS 'Customer ID from auth service';
+COMMENT ON COLUMN trans.sales_orders.merchant_id IS 'Merchant ID - all items must be from same merchant';
+COMMENT ON COLUMN trans.sales_orders.source IS 'Order source: ecommerce, pos, etc.';
+COMMENT ON COLUMN trans.sales_orders.channel IS 'Order channel: web, mobile, etc.';
+
+-- ============================================================================
+-- Grant permissions (adjust as needed for your setup)
+-- ============================================================================
+
+-- Grant permissions to application user (adjust username as needed)
+-- GRANT SELECT, INSERT, UPDATE, DELETE ON trans.sales_orders TO your_app_user;
+-- GRANT SELECT, INSERT, UPDATE, DELETE ON trans.sales_order_items TO your_app_user;
+-- GRANT SELECT, INSERT, UPDATE, DELETE ON trans.sales_order_addresses TO your_app_user;
+
+-- ============================================================================
+-- Verification queries
+-- ============================================================================
+
+-- Verify tables were created
+SELECT 
+    schemaname, 
+    tablename, 
+    tableowner 
+FROM pg_tables 
+WHERE schemaname = 'trans' 
+    AND tablename IN ('sales_orders', 'sales_order_items', 'sales_order_addresses')
+ORDER BY tablename;
+
+-- Verify indexes were created
+SELECT 
+    schemaname,
+    tablename,
+    indexname
+FROM pg_indexes
+WHERE schemaname = 'trans'
+    AND tablename IN ('sales_orders', 'sales_order_items', 'sales_order_addresses')
+ORDER BY tablename, indexname;
+
+-- ============================================================================
+-- Migration complete
+-- ============================================================================

db/migrations/001_rollback_ecommerce_order_tables.sql

@@ -0,0 +1,22 @@
+-- ============================================================================
+-- Rollback E-commerce Order Tables Migration
+-- Drops sales_orders, sales_order_items, and sales_order_addresses tables
+-- ============================================================================
+
+-- Drop tables in reverse order (child tables first due to foreign keys)
+DROP TABLE IF EXISTS trans.sales_order_addresses CASCADE;
+DROP TABLE IF EXISTS trans.sales_order_items CASCADE;
+DROP TABLE IF EXISTS trans.sales_orders CASCADE;
+
+-- Drop trigger function
+DROP FUNCTION IF EXISTS trans.update_sales_order_updated_at() CASCADE;
+
+-- Verification
+SELECT 
+    schemaname, 
+    tablename 
+FROM pg_tables 
+WHERE schemaname = 'trans' 
+    AND tablename IN ('sales_orders', 'sales_order_items', 'sales_order_addresses');
+
+-- Should return no rows if rollback was successful

db/migrations/002_alter_existing_order_tables_to_uuid.sql

@@ -0,0 +1,218 @@
+-- ============================================================================
+-- Alter Existing Order Tables to Support UUID
+-- Modifies existing sales_orders tables to use UUID instead of VARCHAR(26)
+-- WARNING: This will drop and recreate foreign key constraints
+-- ============================================================================
+
+-- Enable UUID extension if not already enabled
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+BEGIN;
+
+-- ============================================================================
+-- Step 1: Drop existing tables
+-- ============================================================================
+
+-- Backup existing data (optional - uncomment if needed)
+-- CREATE TABLE trans.sales_orders_backup AS SELECT * FROM trans.sales_orders;
+
+-- Drop existing table and recreate with UUID
+-- Note: This will lose existing data. Use with caution!
+DROP TABLE IF EXISTS trans.sales_order_addresses CASCADE;
+DROP TABLE IF EXISTS trans.sales_order_items CASCADE;
+DROP TABLE IF EXISTS trans.sales_orders CASCADE;
+
+-- Recreate tables with UUID support
+CREATE TABLE trans.sales_orders (
+    -- Primary identification
+    sales_order_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    order_number VARCHAR(50) UNIQUE NOT NULL,
+    
+    -- Merchant and branch
+    merchant_id UUID NOT NULL,
+    
+    -- Order metadata
+    order_date TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    status VARCHAR(50) NOT NULL DEFAULT 'pending',
+    
+    -- Customer information
+    customer_id UUID NOT NULL,
+    customer_name VARCHAR(255),
+    customer_type VARCHAR(50) DEFAULT 'retail',
+    customer_phone VARCHAR(20),
+    customer_email VARCHAR(255),
+    customer_gstin VARCHAR(50),
+    
+    -- Financial information
+    subtotal NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    total_discount NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    total_tax NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    shipping_charges NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    grand_total NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    
+    -- Tax breakdown
+    cgst NUMERIC(15, 2) DEFAULT 0.00,
+    sgst NUMERIC(15, 2) DEFAULT 0.00,
+    igst NUMERIC(15, 2) DEFAULT 0.00,
+    
+    -- Payment information
+    payment_type VARCHAR(50),
+    payment_status VARCHAR(50) NOT NULL DEFAULT 'pending',
+    payment_method VARCHAR(50),
+    payment_date TIMESTAMP WITH TIME ZONE,
+    payment_reference VARCHAR(255),
+    amount_paid NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    amount_due NUMERIC(15, 2) NOT NULL DEFAULT 0.00,
+    credit_terms VARCHAR(100),
+    credit_limit NUMERIC(15, 2),
+    
+    -- Fulfillment information
+    fulfillment_status VARCHAR(50) NOT NULL DEFAULT 'pending',
+    expected_delivery_date TIMESTAMP WITH TIME ZONE,
+    actual_delivery_date TIMESTAMP WITH TIME ZONE,
+    
+    -- Invoice information
+    invoice_id UUID,
+    invoice_number VARCHAR(50),
+    invoice_date TIMESTAMP WITH TIME ZONE,
+    invoice_pdf_url TEXT,
+    
+    -- Additional information
+    notes TEXT,
+    internal_notes TEXT,
+    
+    -- Audit fields
+    created_by VARCHAR(100),
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    approved_by VARCHAR(100),
+    approved_at TIMESTAMP WITH TIME ZONE,
+    
+    -- Metadata
+    source VARCHAR(50) DEFAULT 'ecommerce',
+    channel VARCHAR(50) DEFAULT 'web',
+    tags TEXT[],
+    version INTEGER NOT NULL DEFAULT 1
+);
+
+-- ============================================================================
+-- Step 3: Recreate sales_order_items table
+-- ============================================================================
+
+CREATE TABLE trans.sales_order_items (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    sales_order_id UUID NOT NULL,
+    
+    -- Product information
+    sku VARCHAR(100),
+    product_id VARCHAR(100) NOT NULL,
+    product_name VARCHAR(255) NOT NULL,
+    item_type VARCHAR(50) DEFAULT 'product',
+    
+    -- Quantity and pricing
+    quantity NUMERIC(15, 3) NOT NULL,
+    unit_price NUMERIC(15, 2) NOT NULL,
+    tax_percent NUMERIC(5, 2) NOT NULL DEFAULT 0.00,
+    discount_percent NUMERIC(5, 2) NOT NULL DEFAULT 0.00,
+    line_total NUMERIC(15, 2) NOT NULL,
+    
+    -- Additional information
+    hsn_code VARCHAR(20),
+    uom VARCHAR(20) DEFAULT 'PCS',
+    batch_no VARCHAR(100),
+    serials TEXT[],
+    
+    -- Service-related fields
+    staff_id VARCHAR(100),
+    staff_name VARCHAR(255),
+    
+    -- Metadata
+    remarks TEXT,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- ============================================================================
+-- Step 4: Recreate sales_order_addresses table
+-- ============================================================================
+
+CREATE TABLE trans.sales_order_addresses (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    sales_order_id UUID NOT NULL,
+    
+    -- Address type
+    address_type VARCHAR(50) NOT NULL,
+    
+    -- Address fields
+    line1 VARCHAR(255) NOT NULL,
+    line2 VARCHAR(255),
+    city VARCHAR(100) NOT NULL,
+    state VARCHAR(100) NOT NULL,
+    postal_code VARCHAR(20) NOT NULL,
+    country VARCHAR(100) NOT NULL DEFAULT 'India',
+    landmark VARCHAR(255),
+    
+    -- Metadata
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- ============================================================================
+-- Step 5: Recreate indexes
+-- ============================================================================
+
+CREATE INDEX idx_sales_orders_merchant_id ON trans.sales_orders(merchant_id);
+CREATE INDEX idx_sales_orders_customer_id ON trans.sales_orders(customer_id);
+CREATE INDEX idx_sales_orders_order_date ON trans.sales_orders(order_date);
+CREATE INDEX idx_sales_orders_status ON trans.sales_orders(status);
+CREATE INDEX idx_sales_orders_payment_status ON trans.sales_orders(payment_status);
+CREATE INDEX idx_sales_orders_fulfillment_status ON trans.sales_orders(fulfillment_status);
+CREATE INDEX idx_sales_orders_created_at ON trans.sales_orders(created_at);
+
+CREATE INDEX idx_sales_order_items_order_id ON trans.sales_order_items(sales_order_id);
+CREATE INDEX idx_sales_order_items_product_id ON trans.sales_order_items(product_id);
+
+CREATE INDEX idx_sales_order_addresses_order_id ON trans.sales_order_addresses(sales_order_id);
+CREATE INDEX idx_sales_order_addresses_type ON trans.sales_order_addresses(address_type);
+
+-- ============================================================================
+-- Step 6: Recreate trigger
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION trans.update_sales_order_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = CURRENT_TIMESTAMP;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trigger_update_sales_order_updated_at
+    BEFORE UPDATE ON trans.sales_orders
+    FOR EACH ROW
+    EXECUTE FUNCTION trans.update_sales_order_updated_at();
+
+COMMIT;
+
+-- ============================================================================
+-- Verification
+-- ============================================================================
+
+-- Check table structure
+\d trans.sales_orders
+\d trans.sales_order_items
+\d trans.sales_order_addresses
+
+-- Verify UUID columns
+SELECT 
+    table_name,
+    column_name,
+    data_type,
+    character_maximum_length
+FROM information_schema.columns
+WHERE table_schema = 'trans'
+    AND table_name IN ('sales_orders', 'sales_order_items', 'sales_order_addresses')
+    AND column_name LIKE '%_id'
+ORDER BY table_name, ordinal_position;
+
+-- ============================================================================
+-- Migration complete
+-- ============================================================================

db/run_migration.py

@@ -0,0 +1,129 @@
+"""
+Run database migrations for e-commerce order tables.
+"""
+import os
+import sys
+import asyncpg
+from pathlib import Path
+
+# Database connection details
+DB_HOST = os.getenv("DB_HOST", "ep-sweet-surf-a1qeduoy.ap-southeast-1.aws.neon.tech")
+DB_PORT = int(os.getenv("DB_PORT", "5432"))
+DB_NAME = os.getenv("DB_NAME", "cuatrolabs")
+DB_USER = os.getenv("DB_USER", "trans_owner")
+DB_PASSWORD = os.getenv("DB_PASSWORD", "BookMyService7")
+DB_SSLMODE = os.getenv("DB_SSLMODE", "require")
+
+
+async def run_migration(migration_file: str):
+    """Run a SQL migration file"""
+    
+    # Read migration file
+    migration_path = Path(__file__).parent / "migrations" / migration_file
+    
+    if not migration_path.exists():
+        print(f"❌ Migration file not found: {migration_path}")
+        return False
+    
+    print(f"\n{'='*70}")
+    print(f"Running migration: {migration_file}")
+    print(f"{'='*70}\n")
+    
+    with open(migration_path, 'r') as f:
+        sql = f.read()
+    
+    # Connect to database
+    try:
+        conn = await asyncpg.connect(
+            host=DB_HOST,
+            port=DB_PORT,
+            database=DB_NAME,
+            user=DB_USER,
+            password=DB_PASSWORD,
+            ssl='require' if DB_SSLMODE == 'require' else None
+        )
+        
+        print(f"✅ Connected to database: {DB_NAME}")
+        
+        # Execute migration
+        await conn.execute(sql)
+        
+        print(f"✅ Migration executed successfully")
+        
+        # Verify tables
+        tables = await conn.fetch("""
+            SELECT schemaname, tablename 
+            FROM pg_tables 
+            WHERE schemaname = 'trans' 
+                AND tablename IN ('sales_orders', 'sales_order_items', 'sales_order_addresses')
+            ORDER BY tablename
+        """)
+        
+        if tables:
+            print(f"\n✅ Tables created:")
+            for table in tables:
+                print(f"   - {table['schemaname']}.{table['tablename']}")
+        
+        # Close connection
+        await conn.close()
+        
+        return True
+        
+    except Exception as e:
+        print(f"\n❌ Migration failed: {str(e)}")
+        return False
+
+
+async def main():
+    """Main function"""
+    
+    print("\n" + "="*70)
+    print("E-commerce Order Tables Migration")
+    print("="*70)
+    
+    if len(sys.argv) < 2:
+        print("\nUsage:")
+        print("  python run_migration.py <migration_file>")
+        print("\nAvailable migrations:")
+        print("  001_create_ecommerce_order_tables.sql       - Create new tables")
+        print("  002_alter_existing_order_tables_to_uuid.sql - Alter existing tables")
+        print("  001_rollback_ecommerce_order_tables.sql     - Rollback (drop tables)")
+        print("\nExample:")
+        print("  python run_migration.py 001_create_ecommerce_order_tables.sql")
+        return
+    
+    migration_file = sys.argv[1]
+    
+    # Confirm if rollback
+    if "rollback" in migration_file.lower():
+        print("\n⚠️  WARNING: This will DROP all order tables and data!")
+        confirm = input("Type 'yes' to confirm: ")
+        if confirm.lower() != 'yes':
+            print("❌ Migration cancelled")
+            return
+    
+    # Confirm if alter
+    if "alter" in migration_file.lower():
+        print("\n⚠️  WARNING: This will DROP and RECREATE tables (data will be lost)!")
+        confirm = input("Type 'yes' to confirm: ")
+        if confirm.lower() != 'yes':
+            print("❌ Migration cancelled")
+            return
+    
+    # Run migration
+    success = await run_migration(migration_file)
+    
+    if success:
+        print("\n" + "="*70)
+        print("✅ Migration completed successfully!")
+        print("="*70 + "\n")
+    else:
+        print("\n" + "="*70)
+        print("❌ Migration failed!")
+        print("="*70 + "\n")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())