docs: Add comprehensive frontend/backend API alignment analysis
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.
This commit is contained in:
Claude
241
FRONTEND_API_ANALYSIS_SUMMARY.md
Normal file
241
FRONTEND_API_ANALYSIS_SUMMARY.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# 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`
|
||||
|
||||
1741
FRONTEND_API_TYPES_ANALYSIS.md
Normal file
1741
FRONTEND_API_TYPES_ANALYSIS.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user