# Orders Service

Customer orders and procurement planning service for the bakery management system.

## Overview

The Orders Service handles all order-related operations including:

- **Customer Management**: Complete customer lifecycle and relationship management
- **Order Processing**: End-to-end order management from creation to fulfillment
- **Procurement Planning**: Automated procurement requirement calculation and planning
- **Business Intelligence**: Order pattern analysis and business model detection
- **Dashboard Analytics**: Comprehensive reporting and metrics for order operations

## Features

### Core Capabilities
- Customer registration and management with detailed profiles
- Order creation, tracking, and status management
- Automated demand requirements calculation for production planning
- Procurement planning with supplier coordination
- Business model detection (individual bakery vs central bakery)
- Comprehensive dashboard with real-time metrics
- Integration with production, inventory, suppliers, and sales services

### API Endpoints

#### Dashboard & Analytics
- `GET /api/v1/tenants/{tenant_id}/orders/dashboard-summary` - Comprehensive dashboard data
- `GET /api/v1/tenants/{tenant_id}/orders/demand-requirements` - Demand analysis for production
- `GET /api/v1/tenants/{tenant_id}/orders/business-model` - Business model detection

#### Order Management
- `POST /api/v1/tenants/{tenant_id}/orders` - Create new customer order
- `GET /api/v1/tenants/{tenant_id}/orders` - List orders with filtering and pagination
- `GET /api/v1/tenants/{tenant_id}/orders/{order_id}` - Get order details with items
- `PUT /api/v1/tenants/{tenant_id}/orders/{order_id}/status` - Update order status

#### Customer Management
- `POST /api/v1/tenants/{tenant_id}/customers` - Create new customer
- `GET /api/v1/tenants/{tenant_id}/customers` - List customers with filtering
- `GET /api/v1/tenants/{tenant_id}/customers/{customer_id}` - Get customer details

#### Health & Status
- `GET /api/v1/tenants/{tenant_id}/orders/status` - Service status information

## Service Integration

### Shared Clients Used
- **InventoryServiceClient**: Stock levels, product availability validation
- **ProductionServiceClient**: Production notifications, capacity planning
- **SalesServiceClient**: Historical sales data for demand forecasting
- **NotificationServiceClient**: Customer notifications and alerts

### Authentication
Uses shared authentication patterns with tenant isolation:
- JWT token validation
- Tenant access verification
- User permission checks

## Configuration

Key configuration options in `app/core/config.py`:

### Order Processing
- `ORDER_PROCESSING_ENABLED`: Enable automatic order processing (default: true)
- `AUTO_APPROVE_ORDERS`: Automatically approve orders (default: false)
- `MAX_ORDER_ITEMS`: Maximum items per order (default: 50)

### Procurement Planning
- `PROCUREMENT_PLANNING_ENABLED`: Enable procurement planning (default: true)
- `PROCUREMENT_LEAD_TIME_DAYS`: Standard procurement lead time (default: 3)
- `DEMAND_FORECAST_DAYS`: Days for demand forecasting (default: 14)
- `SAFETY_STOCK_PERCENTAGE`: Safety stock buffer (default: 20%)

### Business Model Detection
- `ENABLE_BUSINESS_MODEL_DETECTION`: Enable automatic detection (default: true)
- `CENTRAL_BAKERY_ORDER_THRESHOLD`: Order threshold for central bakery (default: 20)
- `INDIVIDUAL_BAKERY_ORDER_THRESHOLD`: Order threshold for individual bakery (default: 5)

### Customer Management
- `CUSTOMER_VALIDATION_ENABLED`: Enable customer validation (default: true)
- `MAX_CUSTOMERS_PER_TENANT`: Maximum customers per tenant (default: 10000)
- `CUSTOMER_CREDIT_CHECK_ENABLED`: Enable credit checking (default: false)

### Order Validation
- `MIN_ORDER_VALUE`: Minimum order value (default: 0.0)
- `MAX_ORDER_VALUE`: Maximum order value (default: 100000.0)
- `VALIDATE_PRODUCT_AVAILABILITY`: Check product availability (default: true)

### Alert Thresholds
- `HIGH_VALUE_ORDER_THRESHOLD`: High-value order alert (default: 5000.0)
- `LARGE_QUANTITY_ORDER_THRESHOLD`: Large quantity alert (default: 100)
- `RUSH_ORDER_HOURS_THRESHOLD`: Rush order time threshold (default: 24)
- `PROCUREMENT_SHORTAGE_THRESHOLD`: Procurement shortage alert (default: 90%)

### Payment and Pricing
- `PAYMENT_VALIDATION_ENABLED`: Enable payment validation (default: true)
- `DYNAMIC_PRICING_ENABLED`: Enable dynamic pricing (default: false)
- `DISCOUNT_ENABLED`: Enable discounts (default: true)
- `MAX_DISCOUNT_PERCENTAGE`: Maximum discount allowed (default: 50%)

### Delivery and Fulfillment
- `DELIVERY_TRACKING_ENABLED`: Enable delivery tracking (default: true)
- `DEFAULT_DELIVERY_WINDOW_HOURS`: Default delivery window (default: 48)
- `PICKUP_ENABLED`: Enable pickup orders (default: true)
- `DELIVERY_ENABLED`: Enable delivery orders (default: true)

## Database Models

### Customer
- Complete customer profile with contact information
- Business type classification (individual, business, central_bakery)
- Payment terms and credit management
- Order history and metrics tracking
- Delivery preferences and special requirements

### CustomerOrder
- Comprehensive order tracking from creation to delivery
- Status management with full audit trail
- Financial calculations including discounts and taxes
- Delivery scheduling and fulfillment tracking
- Business model detection and categorization
- Customer communication preferences

### OrderItem
- Detailed line item tracking with product specifications
- Customization and special instruction support
- Production requirement integration
- Cost tracking and margin analysis
- Quality control integration

### OrderStatusHistory
- Complete audit trail of order status changes
- Event tracking with detailed context
- User attribution and change reasons
- Customer notification tracking

### ProcurementPlan
- Master procurement planning with business model context
- Supplier diversification and risk assessment
- Performance tracking and cost analysis
- Integration with demand forecasting

### ProcurementRequirement
- Detailed procurement requirements per product/ingredient
- Current inventory level integration
- Supplier preference and lead time management
- Quality specifications and special requirements

### OrderAlert
- Comprehensive alert system for order issues
- Multiple severity levels with appropriate routing
- Business impact assessment
- Resolution tracking and performance metrics

## Business Logic

### Order Processing Flow
1. **Order Creation**: Validate customer, calculate totals, create order record
2. **Item Processing**: Create order items with specifications and requirements
3. **Status Tracking**: Maintain complete audit trail of status changes
4. **Customer Metrics**: Update customer statistics and relationship data
5. **Business Model Detection**: Analyze patterns to determine bakery type
6. **Alert Generation**: Check for high-value, rush, or large orders
7. **Service Integration**: Notify production and inventory services

### Procurement Planning
1. **Demand Analysis**: Aggregate orders by delivery date and products
2. **Inventory Integration**: Check current stock levels and reservations
3. **Requirement Calculation**: Calculate net procurement needs with safety buffer
4. **Supplier Coordination**: Match requirements with preferred suppliers
5. **Lead Time Planning**: Account for supplier lead times and delivery windows
6. **Risk Assessment**: Evaluate supply risks and backup options

### Business Model Detection
- **Individual Bakery**: Low order volume, direct customer sales, standard products
- **Central Bakery**: High volume, wholesale operations, bulk orders
- **Detection Factors**: Order frequency, quantity, customer types, sales channels

## Alert System

### Alert Types
- **High Value Orders**: Orders exceeding configured thresholds
- **Rush Orders**: Orders with tight delivery requirements
- **Large Quantity Orders**: Orders with unusually high item counts
- **Payment Issues**: Payment validation failures or credit problems
- **Procurement Shortages**: Insufficient inventory for order fulfillment
- **Customer Issues**: New customers, credit limit exceedances, special requirements

### Severity Levels
- **Critical**: WhatsApp + Email + Dashboard + SMS
- **High**: WhatsApp + Email + Dashboard
- **Medium**: Email + Dashboard
- **Low**: Dashboard only

## Development

### Setup
```bash
# Install dependencies
pip install -r requirements.txt

# Set up database
# Configure ORDERS_DATABASE_URL environment variable

# Run migrations
alembic upgrade head

# Start service
uvicorn app.main:app --reload
```

### Testing
```bash
# Run tests
pytest

# Run with coverage
pytest --cov=app
```

### Docker
```bash
# Build image
docker build -t orders-service .

# Run container
docker run -p 8000:8000 orders-service
```

## Deployment

The service is designed for containerized deployment with:
- Health checks at `/health`
- Structured logging
- Metrics collection
- Database migrations
- Service discovery integration

## Architecture

Follows Domain-Driven Microservices Architecture:
- Clean separation of concerns
- Repository pattern for data access
- Service layer for business logic
- API layer for external interface
- Shared infrastructure for cross-cutting concerns