248 lines
9.1 KiB
Markdown
248 lines
9.1 KiB
Markdown
# 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 |