369 lines
14 KiB
Python
369 lines
14 KiB
Python
# ================================================================
|
|
# services/procurement/app/schemas/procurement_schemas.py
|
|
# ================================================================
|
|
"""
|
|
Procurement Schemas - Request/response models for procurement plans
|
|
Migrated from Orders Service with additions for local production support
|
|
"""
|
|
|
|
import uuid
|
|
from datetime import datetime, date
|
|
from decimal import Decimal
|
|
from typing import Optional, List, Dict, Any
|
|
from pydantic import BaseModel, Field, ConfigDict
|
|
|
|
|
|
# ================================================================
|
|
# BASE SCHEMAS
|
|
# ================================================================
|
|
|
|
class ProcurementBase(BaseModel):
|
|
"""Base schema for procurement entities"""
|
|
model_config = ConfigDict(from_attributes=True, str_strip_whitespace=True)
|
|
|
|
|
|
# ================================================================
|
|
# PROCUREMENT REQUIREMENT SCHEMAS
|
|
# ================================================================
|
|
|
|
class ProcurementRequirementBase(ProcurementBase):
|
|
"""Base procurement requirement schema"""
|
|
product_id: uuid.UUID
|
|
product_name: str = Field(..., min_length=1, max_length=200)
|
|
product_sku: Optional[str] = Field(None, max_length=100)
|
|
product_category: Optional[str] = Field(None, max_length=100)
|
|
product_type: str = Field(default="ingredient", max_length=50)
|
|
|
|
required_quantity: Decimal = Field(..., gt=0)
|
|
unit_of_measure: str = Field(..., min_length=1, max_length=50)
|
|
safety_stock_quantity: Decimal = Field(default=Decimal("0.000"), ge=0)
|
|
total_quantity_needed: Decimal = Field(..., gt=0)
|
|
|
|
current_stock_level: Decimal = Field(default=Decimal("0.000"), ge=0)
|
|
reserved_stock: Decimal = Field(default=Decimal("0.000"), ge=0)
|
|
available_stock: Decimal = Field(default=Decimal("0.000"), ge=0)
|
|
net_requirement: Decimal = Field(..., ge=0)
|
|
|
|
order_demand: Decimal = Field(default=Decimal("0.000"), ge=0)
|
|
production_demand: Decimal = Field(default=Decimal("0.000"), ge=0)
|
|
forecast_demand: Decimal = Field(default=Decimal("0.000"), ge=0)
|
|
buffer_demand: Decimal = Field(default=Decimal("0.000"), ge=0)
|
|
|
|
required_by_date: date
|
|
lead_time_buffer_days: int = Field(default=1, ge=0)
|
|
suggested_order_date: date
|
|
latest_order_date: date
|
|
|
|
priority: str = Field(default="normal", pattern="^(critical|high|normal|low)$")
|
|
risk_level: str = Field(default="low", pattern="^(low|medium|high|critical)$")
|
|
|
|
preferred_supplier_id: Optional[uuid.UUID] = None
|
|
backup_supplier_id: Optional[uuid.UUID] = None
|
|
supplier_name: Optional[str] = Field(None, max_length=200)
|
|
supplier_lead_time_days: Optional[int] = Field(None, ge=0)
|
|
minimum_order_quantity: Optional[Decimal] = Field(None, ge=0)
|
|
|
|
estimated_unit_cost: Optional[Decimal] = Field(None, ge=0)
|
|
estimated_total_cost: Optional[Decimal] = Field(None, ge=0)
|
|
last_purchase_cost: Optional[Decimal] = Field(None, ge=0)
|
|
|
|
|
|
class ProcurementRequirementCreate(ProcurementRequirementBase):
|
|
"""Schema for creating procurement requirements"""
|
|
special_requirements: Optional[str] = None
|
|
storage_requirements: Optional[str] = Field(None, max_length=200)
|
|
shelf_life_days: Optional[int] = Field(None, gt=0)
|
|
quality_specifications: Optional[Dict[str, Any]] = None
|
|
procurement_notes: Optional[str] = None
|
|
|
|
# Smart procurement calculation metadata
|
|
calculation_method: Optional[str] = Field(None, max_length=100)
|
|
ai_suggested_quantity: Optional[Decimal] = Field(None, ge=0)
|
|
adjusted_quantity: Optional[Decimal] = Field(None, ge=0)
|
|
adjustment_reason: Optional[str] = None
|
|
price_tier_applied: Optional[Dict[str, Any]] = None
|
|
supplier_minimum_applied: bool = False
|
|
storage_limit_applied: bool = False
|
|
reorder_rule_applied: bool = False
|
|
|
|
# NEW: Local production support fields
|
|
is_locally_produced: bool = False
|
|
recipe_id: Optional[uuid.UUID] = None
|
|
parent_requirement_id: Optional[uuid.UUID] = None
|
|
bom_explosion_level: int = Field(default=0, ge=0)
|
|
|
|
|
|
class ProcurementRequirementUpdate(ProcurementBase):
|
|
"""Schema for updating procurement requirements"""
|
|
status: Optional[str] = Field(None, pattern="^(pending|approved|ordered|partially_received|received|cancelled)$")
|
|
priority: Optional[str] = Field(None, pattern="^(critical|high|normal|low)$")
|
|
|
|
approved_quantity: Optional[Decimal] = Field(None, ge=0)
|
|
approved_cost: Optional[Decimal] = Field(None, ge=0)
|
|
|
|
purchase_order_id: Optional[uuid.UUID] = None
|
|
purchase_order_number: Optional[str] = Field(None, max_length=50)
|
|
ordered_quantity: Optional[Decimal] = Field(None, ge=0)
|
|
|
|
expected_delivery_date: Optional[date] = None
|
|
actual_delivery_date: Optional[date] = None
|
|
received_quantity: Optional[Decimal] = Field(None, ge=0)
|
|
delivery_status: Optional[str] = Field(None, pattern="^(pending|in_transit|delivered|delayed|cancelled)$")
|
|
|
|
procurement_notes: Optional[str] = None
|
|
|
|
|
|
class ProcurementRequirementResponse(ProcurementRequirementBase):
|
|
"""Schema for procurement requirement responses"""
|
|
id: uuid.UUID
|
|
plan_id: uuid.UUID
|
|
requirement_number: str
|
|
|
|
status: str
|
|
created_at: datetime
|
|
updated_at: datetime
|
|
|
|
purchase_order_id: Optional[uuid.UUID] = None
|
|
purchase_order_number: Optional[str] = None
|
|
ordered_quantity: Decimal
|
|
ordered_at: Optional[datetime] = None
|
|
|
|
expected_delivery_date: Optional[date] = None
|
|
actual_delivery_date: Optional[date] = None
|
|
received_quantity: Decimal
|
|
delivery_status: str
|
|
|
|
fulfillment_rate: Optional[Decimal] = None
|
|
on_time_delivery: Optional[bool] = None
|
|
quality_rating: Optional[Decimal] = None
|
|
|
|
approved_quantity: Optional[Decimal] = None
|
|
approved_cost: Optional[Decimal] = None
|
|
approved_at: Optional[datetime] = None
|
|
approved_by: Optional[uuid.UUID] = None
|
|
|
|
special_requirements: Optional[str] = None
|
|
storage_requirements: Optional[str] = None
|
|
shelf_life_days: Optional[int] = None
|
|
quality_specifications: Optional[Dict[str, Any]] = None
|
|
procurement_notes: Optional[str] = None
|
|
|
|
# Smart procurement calculation metadata
|
|
calculation_method: Optional[str] = None
|
|
ai_suggested_quantity: Optional[Decimal] = None
|
|
adjusted_quantity: Optional[Decimal] = None
|
|
adjustment_reason: Optional[str] = None
|
|
price_tier_applied: Optional[Dict[str, Any]] = None
|
|
supplier_minimum_applied: bool = False
|
|
storage_limit_applied: bool = False
|
|
reorder_rule_applied: bool = False
|
|
|
|
# NEW: Local production support fields
|
|
is_locally_produced: bool = False
|
|
recipe_id: Optional[uuid.UUID] = None
|
|
parent_requirement_id: Optional[uuid.UUID] = None
|
|
bom_explosion_level: int = 0
|
|
|
|
|
|
# ================================================================
|
|
# PROCUREMENT PLAN SCHEMAS
|
|
# ================================================================
|
|
|
|
class ProcurementPlanBase(ProcurementBase):
|
|
"""Base procurement plan schema"""
|
|
plan_date: date
|
|
plan_period_start: date
|
|
plan_period_end: date
|
|
planning_horizon_days: int = Field(default=14, gt=0)
|
|
|
|
plan_type: str = Field(default="regular", pattern="^(regular|emergency|seasonal|urgent)$")
|
|
priority: str = Field(default="normal", pattern="^(critical|high|normal|low)$")
|
|
|
|
business_model: Optional[str] = Field(None, pattern="^(individual_bakery|central_bakery)$")
|
|
procurement_strategy: str = Field(default="just_in_time", pattern="^(just_in_time|bulk|mixed|bulk_order)$")
|
|
|
|
safety_stock_buffer: Decimal = Field(default=Decimal("20.00"), ge=0, le=100)
|
|
supply_risk_level: str = Field(default="low", pattern="^(low|medium|high|critical)$")
|
|
demand_forecast_confidence: Optional[Decimal] = Field(None, ge=1, le=10)
|
|
seasonality_adjustment: Decimal = Field(default=Decimal("0.00"))
|
|
|
|
special_requirements: Optional[str] = None
|
|
|
|
|
|
class ProcurementPlanCreate(ProcurementPlanBase):
|
|
"""Schema for creating procurement plans"""
|
|
tenant_id: uuid.UUID
|
|
requirements: Optional[List[ProcurementRequirementCreate]] = []
|
|
|
|
|
|
class ProcurementPlanUpdate(ProcurementBase):
|
|
"""Schema for updating procurement plans"""
|
|
status: Optional[str] = Field(None, pattern="^(draft|pending_approval|approved|in_execution|completed|cancelled)$")
|
|
priority: Optional[str] = Field(None, pattern="^(critical|high|normal|low)$")
|
|
|
|
approved_at: Optional[datetime] = None
|
|
approved_by: Optional[uuid.UUID] = None
|
|
execution_started_at: Optional[datetime] = None
|
|
execution_completed_at: Optional[datetime] = None
|
|
|
|
special_requirements: Optional[str] = None
|
|
seasonal_adjustments: Optional[Dict[str, Any]] = None
|
|
|
|
|
|
class ProcurementPlanResponse(ProcurementPlanBase):
|
|
"""Schema for procurement plan responses"""
|
|
id: uuid.UUID
|
|
tenant_id: uuid.UUID
|
|
plan_number: str
|
|
status: str
|
|
|
|
total_requirements: int
|
|
total_estimated_cost: Decimal
|
|
total_approved_cost: Decimal
|
|
cost_variance: Decimal
|
|
|
|
total_demand_orders: int
|
|
total_demand_quantity: Decimal
|
|
total_production_requirements: Decimal
|
|
|
|
primary_suppliers_count: int
|
|
backup_suppliers_count: int
|
|
supplier_diversification_score: Optional[Decimal] = None
|
|
|
|
approved_at: Optional[datetime] = None
|
|
approved_by: Optional[uuid.UUID] = None
|
|
execution_started_at: Optional[datetime] = None
|
|
execution_completed_at: Optional[datetime] = None
|
|
|
|
fulfillment_rate: Optional[Decimal] = None
|
|
on_time_delivery_rate: Optional[Decimal] = None
|
|
cost_accuracy: Optional[Decimal] = None
|
|
quality_score: Optional[Decimal] = None
|
|
|
|
created_at: datetime
|
|
updated_at: datetime
|
|
created_by: Optional[uuid.UUID] = None
|
|
updated_by: Optional[uuid.UUID] = None
|
|
|
|
# NEW: Track forecast and production schedule links
|
|
forecast_id: Optional[uuid.UUID] = None
|
|
production_schedule_id: Optional[uuid.UUID] = None
|
|
|
|
requirements: List[ProcurementRequirementResponse] = []
|
|
|
|
|
|
# ================================================================
|
|
# SUMMARY SCHEMAS
|
|
# ================================================================
|
|
|
|
class ProcurementSummary(ProcurementBase):
|
|
"""Summary of procurement plans"""
|
|
total_plans: int
|
|
active_plans: int
|
|
total_requirements: int
|
|
pending_requirements: int
|
|
critical_requirements: int
|
|
|
|
total_estimated_cost: Decimal
|
|
total_approved_cost: Decimal
|
|
cost_variance: Decimal
|
|
|
|
average_fulfillment_rate: Optional[Decimal] = None
|
|
average_on_time_delivery: Optional[Decimal] = None
|
|
|
|
top_suppliers: List[Dict[str, Any]] = []
|
|
critical_items: List[Dict[str, Any]] = []
|
|
|
|
|
|
class DashboardData(ProcurementBase):
|
|
"""Dashboard data for procurement overview"""
|
|
current_plan: Optional[ProcurementPlanResponse] = None
|
|
summary: ProcurementSummary
|
|
|
|
upcoming_deliveries: List[Dict[str, Any]] = []
|
|
overdue_requirements: List[Dict[str, Any]] = []
|
|
low_stock_alerts: List[Dict[str, Any]] = []
|
|
|
|
performance_metrics: Dict[str, Any] = {}
|
|
|
|
|
|
# ================================================================
|
|
# REQUEST SCHEMAS
|
|
# ================================================================
|
|
|
|
class GeneratePlanRequest(ProcurementBase):
|
|
"""Request to generate procurement plan"""
|
|
plan_date: Optional[date] = None
|
|
force_regenerate: bool = False
|
|
planning_horizon_days: int = Field(default=14, gt=0, le=30)
|
|
include_safety_stock: bool = True
|
|
safety_stock_percentage: Decimal = Field(default=Decimal("20.00"), ge=0, le=100)
|
|
|
|
|
|
class AutoGenerateProcurementRequest(ProcurementBase):
|
|
"""
|
|
Request to auto-generate procurement plan (called by Orchestrator)
|
|
|
|
This is the main entry point for orchestrated procurement planning.
|
|
The Orchestrator calls Forecasting Service first, then passes forecast data here.
|
|
|
|
NEW: Accepts cached data snapshots from Orchestrator to eliminate duplicate API calls.
|
|
"""
|
|
forecast_data: Dict[str, Any] = Field(..., description="Forecast data from Forecasting Service")
|
|
production_schedule_id: Optional[uuid.UUID] = Field(None, description="Production schedule ID if available")
|
|
target_date: Optional[date] = Field(None, description="Target date for the plan")
|
|
planning_horizon_days: int = Field(default=14, gt=0, le=30)
|
|
safety_stock_percentage: Decimal = Field(default=Decimal("20.00"), ge=0, le=100)
|
|
auto_create_pos: bool = Field(True, description="Automatically create purchase orders")
|
|
auto_approve_pos: bool = Field(False, description="Auto-approve qualifying purchase orders")
|
|
|
|
# NEW: Cached data from Orchestrator
|
|
inventory_data: Optional[Dict[str, Any]] = Field(None, description="Cached inventory snapshot from Orchestrator")
|
|
suppliers_data: Optional[Dict[str, Any]] = Field(None, description="Cached suppliers snapshot from Orchestrator")
|
|
recipes_data: Optional[Dict[str, Any]] = Field(None, description="Cached recipes snapshot from Orchestrator")
|
|
|
|
|
|
class ForecastRequest(ProcurementBase):
|
|
"""Request parameters for demand forecasting"""
|
|
target_date: date
|
|
horizon_days: int = Field(default=1, gt=0, le=7)
|
|
include_confidence_intervals: bool = True
|
|
product_ids: Optional[List[uuid.UUID]] = None
|
|
|
|
|
|
# ================================================================
|
|
# RESPONSE SCHEMAS
|
|
# ================================================================
|
|
|
|
class GeneratePlanResponse(ProcurementBase):
|
|
"""Response from plan generation"""
|
|
success: bool
|
|
message: str
|
|
plan: Optional[ProcurementPlanResponse] = None
|
|
warnings: List[str] = []
|
|
errors: List[str] = []
|
|
|
|
|
|
class AutoGenerateProcurementResponse(ProcurementBase):
|
|
"""Response from auto-generate procurement (called by Orchestrator)"""
|
|
success: bool
|
|
message: str
|
|
plan_id: Optional[uuid.UUID] = None
|
|
plan_number: Optional[str] = None
|
|
requirements_created: int = 0
|
|
purchase_orders_created: int = 0
|
|
purchase_orders_auto_approved: int = 0
|
|
total_estimated_cost: Decimal = Decimal("0")
|
|
warnings: List[str] = []
|
|
errors: List[str] = []
|
|
created_pos: List[Dict[str, Any]] = []
|
|
|
|
|
|
class PaginatedProcurementPlans(ProcurementBase):
|
|
"""Paginated list of procurement plans"""
|
|
plans: List[ProcurementPlanResponse]
|
|
total: int
|
|
page: int
|
|
limit: int
|
|
has_more: bool
|