Add new alert architecture
This commit is contained in:
Urtzi Alfaro
@@ -1,248 +0,0 @@
|
||||
# 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
|
||||
@@ -5,7 +5,7 @@
|
||||
Orders Service Database Configuration
|
||||
"""
|
||||
|
||||
from sqlalchemy import create_engine
|
||||
from sqlalchemy import create_engine, text
|
||||
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
|
||||
from sqlalchemy.orm import sessionmaker, DeclarativeBase
|
||||
import structlog
|
||||
@@ -72,7 +72,7 @@ async def get_db_health() -> bool:
|
||||
"""Check database health"""
|
||||
try:
|
||||
async with async_engine.begin() as conn:
|
||||
await conn.execute("SELECT 1")
|
||||
await conn.execute(text("SELECT 1"))
|
||||
return True
|
||||
except Exception as e:
|
||||
logger.error("Database health check failed", error=str(e))
|
||||
|
||||
Reference in New Issue
Block a user