bakery-admin/bakery-ia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1a9839240ec5aa419a451582fb58a03cd122124b
bakery-ia/services/orders
History
Urtzi Alfaro 90100a66c6 Delete legacy alerts
2025-08-22 15:31:52 +02:00
..
app
Delete legacy alerts
2025-08-22 15:31:52 +02:00
Dockerfile
Add more services
2025-08-21 20:28:14 +02:00
README.md
Add more services
2025-08-21 20:28:14 +02:00
requirements.txt
Add more services
2025-08-21 20:28:14 +02:00

README.md

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

# 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

# Run tests
pytest

# Run with coverage
pytest --cov=app

Docker

# 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