020acc4691
Research findings for wizard improvements including: - Backend model analysis for all 6 services (Recipe, Customer, Supplier, Inventory, Quality Template, Customer Order) - Required vs optional fields identification - Frontend API types and hooks alignment check - Critical misalignment issues identified (PaymentTerms enum, API response types, field naming) - UX research for advanced options implementation This analysis supports the wizard enhancement effort to ensure proper field handling and identify areas for improvement.
242 lines
8.0 KiB
Markdown
242 lines
8.0 KiB
Markdown
# Frontend API Analysis - Executive Summary
|
|
|
|
## Document Location
|
|
Complete analysis: `/home/user/bakery_ia/FRONTEND_API_TYPES_ANALYSIS.md` (1,741 lines)
|
|
|
|
## Quick Overview
|
|
|
|
### 1. RECIPE API
|
|
**File**: `/home/user/bakery_ia/frontend/src/api/types/recipes.ts`
|
|
**Hooks**: `/home/user/bakery_ia/frontend/src/api/hooks/recipes.ts`
|
|
|
|
Key Types: RecipeCreate, RecipeUpdate, RecipeResponse, RecipeIngredientResponse, RecipeQualityConfiguration
|
|
|
|
Key Hooks:
|
|
- Query: useRecipe, useRecipes, useInfiniteRecipes, useRecipeStatistics, useRecipeCategories, useRecipeFeasibility
|
|
- Mutation: useCreateRecipe, useUpdateRecipe, useDeleteRecipe, useArchiveRecipe, useDuplicateRecipe, useActivateRecipe
|
|
|
|
---
|
|
|
|
### 2. SUPPLIER API
|
|
**File**: `/home/user/bakery_ia/frontend/src/api/types/suppliers.ts`
|
|
**Hooks**: `/home/user/bakery_ia/frontend/src/api/hooks/suppliers.ts`
|
|
|
|
Key Types:
|
|
- Supplier: SupplierCreate, SupplierResponse, SupplierPriceListResponse
|
|
- Purchase Order: PurchaseOrderCreate, PurchaseOrderResponse
|
|
- Delivery: DeliveryCreate, DeliveryResponse
|
|
- Performance: PerformanceMetric, Alert, Scorecard
|
|
|
|
Key Hooks:
|
|
- Supplier (8 query hooks): useSuppliers, useSupplier, useSupplierStatistics, useActiveSuppliers, etc.
|
|
- Purchase Orders (2 query hooks): usePurchaseOrders, usePurchaseOrder
|
|
- Deliveries (2 query hooks): useDeliveries, useDelivery
|
|
- Performance (2 query hooks): useSupplierPerformanceMetrics, usePerformanceAlerts
|
|
- Mutations (12 hooks): CRUD operations for all entities
|
|
|
|
---
|
|
|
|
### 3. INVENTORY/PRODUCT API
|
|
**File**: `/home/user/bakery_ia/frontend/src/api/types/inventory.ts`
|
|
**Hooks**: `/home/user/bakery_ia/frontend/src/api/hooks/inventory.ts`
|
|
|
|
Key Types:
|
|
- Ingredient: IngredientCreate, IngredientResponse
|
|
- Stock: StockCreate, StockResponse
|
|
- Stock Movement: StockMovementCreate, StockMovementResponse
|
|
- Transformation: ProductTransformationCreate, ProductTransformationResponse
|
|
- Food Safety: TemperatureLogResponse, FoodSafetyAlertResponse, FoodSafetyComplianceResponse
|
|
- Dashboard: InventoryDashboardSummary, InventoryAnalytics
|
|
|
|
Key Hooks:
|
|
- Ingredients (4 query hooks): useIngredients, useIngredient, useIngredientsByCategory, useLowStockIngredients
|
|
- Stock (6 query hooks): useStock, useStockByIngredient, useExpiringStock, useExpiredStock, useStockMovements, useStockAnalytics
|
|
- Transformations (5 query hooks): useTransformations, useTransformation, useTransformationSummary, etc.
|
|
- Mutations (13 hooks): CRUD + specialized operations like useStockOperations, useTransformationOperations
|
|
|
|
---
|
|
|
|
### 4. QUALITY TEMPLATE API
|
|
**File**: `/home/user/bakery_ia/frontend/src/api/types/qualityTemplates.ts`
|
|
**Hooks**: `/home/user/bakery_ia/frontend/src/api/hooks/qualityTemplates.ts`
|
|
|
|
Key Types:
|
|
- QualityCheckTemplate, QualityCheckTemplateCreate, QualityCheckTemplateUpdate
|
|
- QualityCheckExecutionRequest, QualityCheckExecutionResponse
|
|
- ProcessStageQualityConfig, RecipeQualityConfiguration
|
|
|
|
Key Hooks:
|
|
- Query (5 hooks): useQualityTemplates, useQualityTemplate, useQualityTemplatesForStage, useQualityTemplatesForRecipe, useDefaultQualityTemplates
|
|
- Mutation (6 hooks): useCreateQualityTemplate, useUpdateQualityTemplate, useDeleteQualityTemplate, useDuplicateQualityTemplate, useExecuteQualityCheck, useValidateQualityTemplate
|
|
|
|
---
|
|
|
|
### 5. CUSTOMER ORDER API
|
|
**File**: `/home/user/bakery_ia/frontend/src/api/types/orders.ts`
|
|
**Hooks**: `/home/user/bakery_ia/frontend/src/api/hooks/orders.ts`
|
|
|
|
Key Types:
|
|
- Customer: CustomerCreate, CustomerResponse
|
|
- Order: OrderCreate, OrderUpdate, OrderResponse
|
|
- OrderItem: OrderItemCreate, OrderItemResponse
|
|
- Dashboard: OrdersDashboardSummary
|
|
- Analytics: DemandRequirements, BusinessModelDetection
|
|
|
|
Key Hooks:
|
|
- Query (7 hooks): useOrders, useOrder, useCustomers, useCustomer, useOrdersDashboard, useDemandRequirements, useBusinessModelDetection
|
|
- Mutation (4 hooks): useCreateOrder, useUpdateOrderStatus, useCreateCustomer, useUpdateCustomer
|
|
- Utility (1 hook): useInvalidateOrders
|
|
|
|
---
|
|
|
|
## CRITICAL MISALIGNMENTS IDENTIFIED
|
|
|
|
### 1. PAYMENT TERMS ENUM CONFLICT
|
|
Location: `suppliers.ts` vs `orders.ts`
|
|
|
|
**Suppliers PaymentTerms:**
|
|
- COD, NET_15, NET_30, NET_45, NET_60, PREPAID, CREDIT_TERMS
|
|
|
|
**Orders PaymentTerms:**
|
|
- IMMEDIATE, NET_30, NET_60
|
|
|
|
**Impact**: Two different enums with same name in different contexts could cause confusion and data inconsistency.
|
|
|
|
**Recommendation**: Unify these enums or clarify their separate domains.
|
|
|
|
---
|
|
|
|
### 2. DECIMAL VS NUMBER TYPE
|
|
**Affected APIs**: Suppliers, Orders
|
|
|
|
**Issue**: Backend uses `Decimal` for monetary values:
|
|
- supplier.credit_limit
|
|
- supplier.total_spent
|
|
- customer.total_spent
|
|
- customer.average_order_value
|
|
|
|
**Frontend**: Uses `number` type
|
|
|
|
**Impact**: Floating-point precision loss for currency calculations (e.g., $1.23 - $1.20 != $0.03)
|
|
|
|
**Recommendation**: Implement a Decimal wrapper type for all currency fields.
|
|
|
|
---
|
|
|
|
### 3. STOCK FIELD NAME INCONSISTENCY
|
|
**Locations**:
|
|
- `StockCreate` interface defines: `unit_cost?: number`
|
|
- `useStockOperations` hook uses: `unit_price` parameter
|
|
|
|
**Impact**: Potential API validation errors if hook sends wrong field name.
|
|
|
|
**Recommendation**: Audit backend to verify correct field name and update frontend accordingly.
|
|
|
|
---
|
|
|
|
### 4. PROCESS STAGE VS PRODUCTION STAGE CONFUSION
|
|
**Quality Templates Define:**
|
|
- MIXING, PROOFING, SHAPING, BAKING, COOLING, PACKAGING, FINISHING
|
|
|
|
**Inventory Defines:**
|
|
- RAW_INGREDIENT, PAR_BAKED, FULLY_BAKED, PREPARED_DOUGH, FROZEN_PRODUCT
|
|
|
|
**Note**: These are intentionally different (quality control vs production) - correctly separated but documentation needed.
|
|
|
|
---
|
|
|
|
### 5. RECORD<STRING, ANY> OVERUSE
|
|
Multiple type definitions use `Record<string, any>` for flexibility:
|
|
- instructions
|
|
- parameters
|
|
- thresholds
|
|
- scoring_criteria
|
|
- custom_requirements
|
|
- allergen_warnings
|
|
|
|
**Risk**: Loose typing defeats TypeScript's safety benefits.
|
|
|
|
**Recommendation**: Define specific interfaces for complex nested structures.
|
|
|
|
---
|
|
|
|
### 6. CREATED_BY FIELD HANDLING
|
|
**Quality Templates**: `QualityCheckTemplateCreate` requires `created_by: string`
|
|
|
|
**Issue**: Forms typically auto-fill from authenticated user context, not user input.
|
|
|
|
**Recommendation**: Verify API makes this optional or frontend passes authenticated user ID.
|
|
|
|
---
|
|
|
|
### 7. PRODUCT CLASSIFICATION
|
|
**Location**: inventory.ts - ProductSuggestionResponse, BatchClassificationResponse
|
|
|
|
**Potential Issue**: These suggest AI-based classification but exact API endpoints may differ from implementation.
|
|
|
|
**Recommendation**: Verify API contract matches suggestion response structure.
|
|
|
|
---
|
|
|
|
## STATISTICS
|
|
|
|
Total TypeScript type definitions: **150+**
|
|
Total React hooks: **80+**
|
|
Total enums: **40+**
|
|
|
|
### By Domain:
|
|
- Recipes: 20 types, 10 hooks
|
|
- Suppliers: 35 types, 25 hooks
|
|
- Inventory: 25 types, 20 hooks
|
|
- Quality Templates: 12 types, 6 hooks
|
|
- Orders/Customers: 18 types, 7 hooks
|
|
|
|
---
|
|
|
|
## KEY SERVICES LOCATION
|
|
|
|
All services are located in: `/home/user/bakery_ia/frontend/src/api/services/`
|
|
|
|
Main service files:
|
|
- recipes.ts
|
|
- suppliers.ts
|
|
- inventory.ts
|
|
- qualityTemplates.ts
|
|
- orders.ts
|
|
- procurement-service.ts
|
|
- purchase_orders.ts
|
|
- production.ts
|
|
|
|
---
|
|
|
|
## RECOMMENDATIONS FOR CLEANUP
|
|
|
|
1. **Priority 1 (Critical)**
|
|
- Unify PaymentTerms enums
|
|
- Fix Decimal type handling for currencies
|
|
- Verify stock field names (unit_cost vs unit_price)
|
|
|
|
2. **Priority 2 (Important)**
|
|
- Replace Record<string, any> with specific types
|
|
- Add validators matching backend
|
|
- Document ProcessStage vs ProductionStage distinction
|
|
|
|
3. **Priority 3 (Nice to Have)**
|
|
- Create shared enum definitions
|
|
- Add JSDoc comments for all type fields
|
|
- Implement Decimal wrapper for all monetary values
|
|
- Create type guards for enum validation
|
|
|
|
---
|
|
|
|
## FILES FOR FURTHER REVIEW
|
|
|
|
Backend schema files (for comparison):
|
|
- `/home/user/bakery_ia/services/recipes/app/schemas/recipes.py`
|
|
- `/home/user/bakery_ia/services/orders/app/schemas/order_schemas.py`
|
|
- `/home/user/bakery_ia/services/production/app/schemas/quality_templates.py`
|
|
- `/home/user/bakery_ia/services/suppliers/app/schemas/suppliers.py`
|
|
- `/home/user/bakery_ia/services/suppliers/app/schemas/performance.py`
|
|
- `/home/user/bakery_ia/services/inventory/app/schemas/inventory.py`
|
|
|