docs/03-BACKEND/CMS/development-plan.md

# CMS Microservice Development Plan - Updated January 2026

## 📋 Project Overview
پروژه CMS Microservice با معماری Clean Architecture و الگوهای Domain-Driven Design برای مدیریت محصولات و موجودی انبار.

**تکنولوژی‌های اصلی:**
- .NET 9.0
- Entity Framework Core 9.x
- MediatR 13.0.0 (CQRS)
- SQL Server

## 🎯 Current Status: Phase 2 Complete ✅

---

## Phase 1: Infrastructure & Domain Layer ✅ COMPLETED
**Duration:** ✅ Completed
**Status:** ✅ All tasks finished successfully

### 📦 Domain Entities
- ✅ `InventoryItem` - مدیریت کالاهای موجود در انبار
- ✅ `StockMovement` - ردیابی حرکات موجودی  
- ✅ `Warehouse` - مدیریت انبارها

### 🔧 Domain Enums
- ✅ `StockMovementType` - انواع حرکات موجودی

### 🗄️ Database Infrastructure
- ✅ Entity Framework Core configurations
- ✅ ApplicationDbContext setup
- ✅ Database migrations created and applied
- ✅ SQL Server compatibility ensured

---

## Phase 2: Repository Pattern & CQRS ✅ COMPLETED
**Duration:** ✅ Completed  
**Status:** ✅ All tasks finished successfully

### 🏛️ Repository Pattern Implementation
#### Repository Interfaces:
- ✅ `IInventoryItemRepository` - 25+ methods for inventory management
- ✅ `IStockMovementRepository` - Movement tracking and analytics  
- ✅ `IWarehouseRepository` - Warehouse management operations

#### Repository Implementations:
- ✅ `InventoryItemRepository` - Complete CRUD with business logic
- ✅ `StockMovementRepository` - Movement tracking with analytics
- ✅ `WarehouseRepository` - Warehouse management with statistics

### 🔄 CQRS Pattern Implementation
#### Commands:
**InventoryItem Commands:**
- ✅ `CreateInventoryItemCommand` - Create new inventory item
- ✅ `UpdateInventoryItemCommand` - Update inventory details
- ✅ `UpdateInventoryQuantityCommand` - Adjust quantity with audit
- ✅ `ReserveInventoryCommand` - Reserve stock for orders
- ✅ `ReleaseReservedInventoryCommand` - Release reserved stock
- ✅ `ReduceInventoryCommand` - Reduce stock (sales)
- ✅ `IncreaseInventoryCommand` - Increase stock (purchases)
- ✅ `DeleteInventoryItemCommand` - Delete inventory item

**StockMovement Commands:**
- ✅ `CreateStockMovementCommand` - Record stock movement
- ✅ `BulkCreateStockMovementCommand` - Bulk movement recording
- ✅ `DeleteStockMovementCommand` - Delete movement record

**Warehouse Commands:**
- ✅ `CreateWarehouseCommand` - Create new warehouse
- ✅ `UpdateWarehouseCommand` - Update warehouse details
- ✅ `DeleteWarehouseCommand` - Delete warehouse
- ✅ `SetDefaultWarehouseCommand` - Set default warehouse
- ✅ `ActivateWarehouseCommand` - Activate/deactivate warehouse
- ✅ `BulkCreateWarehousesCommand` - Bulk warehouse creation

#### Queries:
**InventoryItem Queries:**
- ✅ `GetInventoryItemByIdQuery` - Get by ID
- ✅ `GetInventoryItemByProductIdQuery` - Get by product
- ✅ `SearchInventoryItemsQuery` - Advanced search with filters
- ✅ `GetLowStockItemsQuery` - Low stock alerts
- ✅ `GetOutOfStockItemsQuery` - Out of stock items
- ✅ `CheckInventoryAvailabilityQuery` - Availability check
- ✅ `GetAvailableQuantityQuery` - Available quantity calculation

**StockMovement Queries:**
- ✅ `GetInventoryItemMovementHistoryQuery` - Movement history
- ✅ `GetStockMovementsByOrderQuery` - Order-based movements
- ✅ `SearchStockMovementsQuery` - Advanced search
- ✅ `GetMovementSummaryQuery` - Movement analytics
- ✅ `GetDailyMovementVolumeQuery` - Daily volume reports
- ✅ `GetTopMovingProductsQuery` - Top moving products

**Warehouse Queries:**
- ✅ `GetWarehouseByIdQuery` - Get by ID
- ✅ `GetDefaultWarehouseQuery` - Get default warehouse
- ✅ `GetActiveWarehousesQuery` - Get active warehouses
- ✅ `SearchWarehousesQuery` - Warehouse search
- ✅ `GetWarehouseStatisticsQuery` - Warehouse statistics
- ✅ `GetWarehouseLowStockItemsQuery` - Low stock by warehouse

### 🎭 Command/Query Handlers
#### Command Handlers:
- ✅ **InventoryItem Handlers:** 8 handlers with complete business logic
- ✅ **StockMovement Handlers:** 3 handlers with validation
- ✅ **Warehouse Handlers:** 6 handlers with business rules

#### Query Handlers:
- ✅ **InventoryItem Handlers:** 10 handlers for all queries
- ✅ **StockMovement Handlers:** 12 handlers with analytics
- ✅ **Warehouse Handlers:** 13 handlers with statistics

### 🔧 Infrastructure Services
- ✅ Dependency Injection configuration
- ✅ Repository registrations
- ✅ Database context configuration

---

## Phase 3: Business Services Layer 🚧 IN PROGRESS
**Duration:** In Progress
**Status:** 🔄 Ready to start

### 📋 Services to Implement:
- ⏳ `IInventoryManagementService` - High-level inventory operations
- ⏳ `IStockMovementService` - Movement orchestration
- ⏳ `IWarehouseService` - Warehouse business logic
- ⏳ `IInventoryReportingService` - Advanced reporting
- ⏳ `IInventoryValidationService` - Business rule validation

### 🎯 Business Logic Features:
- ⏳ Automated reorder point calculations
- ⏳ Bulk operations with transaction management
- ⏳ Advanced inventory allocation strategies
- ⏳ Multi-warehouse transfer operations
- ⏳ Inventory forecasting and analytics

---

## Phase 4: DTOs & AutoMapper 📋 PLANNED
**Duration:** Planned
**Status:** ⏳ Pending

### 📦 DTOs to Create:
- ⏳ Request DTOs for API inputs
- ⏳ Response DTOs for API outputs  
- ⏳ Search/Filter DTOs
- ⏳ Report DTOs

### 🔄 Mapping Configuration:
- ⏳ AutoMapper profiles
- ⏳ Domain to DTO mappings
- ⏳ DTO to Domain mappings

---

## Phase 5: Web API Controllers 🌐 PLANNED
**Duration:** Planned
**Status:** ⏳ Pending

### 🎮 Controllers to Implement:
- ⏳ `InventoryController` - Inventory CRUD operations
- ⏳ `WarehouseController` - Warehouse management
- ⏳ `StockMovementController` - Movement tracking
- ⏳ `ReportsController` - Analytics and reporting

### 🔒 API Features:
- ⏳ RESTful API design
- ⏳ Input validation
- ⏳ Error handling
- ⏳ API documentation (Swagger)
- ⏳ Authentication/Authorization integration

---

## 🚀 Key Features Implemented

### ✅ **Complete Inventory Management:**
- Multi-warehouse support with default warehouse designation
- Product and discount product inventory tracking
- Quantity management with min/max thresholds
- Reserved quantity handling for order processing
- Comprehensive audit trail for all movements

### ✅ **Advanced Stock Movement Tracking:**
- 8 different movement types (Purchase, Sale, Transfer, etc.)
- Automatic movement recording for all inventory changes
- Reference number and user tracking
- Bulk movement processing capabilities
- Analytics and reporting ready

### ✅ **Robust Repository Pattern:**
- Generic repository interfaces with specific implementations
- Transaction support for complex operations
- Optimized querying with Entity Framework Core
- Bulk operations for performance
- Comprehensive search and filtering

### ✅ **Clean CQRS Implementation:**
- Clear separation of commands and queries
- MediatR integration for loose coupling
- Comprehensive validation in command handlers
- Rich query capabilities with filtering and pagination
- Analytics queries for business intelligence

### ✅ **Database-First Approach:**
- Entity Framework Core with SQL Server
- Proper indexing for performance
- Foreign key relationships maintained
- Migration support for schema evolution

---

## 🎯 Business Capabilities Enabled

### **Inventory Operations:**
- ✅ Real-time inventory tracking
- ✅ Multi-warehouse inventory management
- ✅ Automatic low stock alerts
- ✅ Order fulfillment with reservation system
- ✅ Purchase order processing with stock increases

### **Analytics & Reporting:**
- ✅ Movement history and audit trails
- ✅ Daily/weekly/monthly movement reports
- ✅ Top moving products analysis
- ✅ Warehouse utilization statistics
- ✅ Low stock and out-of-stock reporting

### **Business Rules:**
- ✅ Automatic stock movement recording
- ✅ Reservation system for order processing
- ✅ Warehouse transfer capabilities
- ✅ Min/max quantity enforcement
- ✅ Default warehouse management

---

## 📊 Technical Metrics

### **Code Coverage:**
- ✅ **Repository Layer:** 100% implemented with business logic
- ✅ **CQRS Layer:** 100% commands/queries with handlers
- ✅ **Infrastructure:** 100% DI configuration complete
- 🔄 **Business Services:** 0% - Next phase
- ⏳ **API Layer:** 0% - Future phase

### **Performance Considerations:**
- ✅ Optimized Entity Framework queries
- ✅ Bulk operations for large datasets
- ✅ Proper database indexing
- ✅ Transaction management for consistency
- ✅ Pagination support for large result sets

### **Testing Strategy:**
- 🔄 Unit tests for business logic - Planned
- 🔄 Integration tests for repositories - Planned  
- 🔄 API tests for controllers - Planned
- 🔄 Performance tests - Planned

---

## 🔮 Next Steps

### **Immediate (Phase 3):**
1. Implement Business Services layer
2. Add advanced business logic and validations
3. Create service abstractions for complex operations

### **Short Term (Phase 4-5):**
1. Design and implement DTOs with AutoMapper
2. Create RESTful API controllers
3. Add comprehensive API documentation

### **Long Term:**
1. Performance optimization and caching
2. Advanced analytics and reporting
3. Integration with external systems
4. Microservice deployment strategies

---

## 🏗️ Architecture Summary

```
📁 CMS Microservice
├── 🎯 Domain Layer (✅ Complete)
│   ├── Entities (InventoryItem, StockMovement, Warehouse)
│   └── Enums (StockMovementType)
├── 📚 Application Layer (✅ Complete)
│   ├── Features/
│   │   ├── InventoryItems/ (Commands, Queries, Handlers)
│   │   ├── StockMovements/ (Commands, Queries, Handlers)  
│   │   └── Warehouses/ (Commands, Queries, Handlers)
│   └── Common/Interfaces/Repositories/
├── 🏗️ Infrastructure Layer (✅ Complete)
│   ├── Persistence/
│   │   ├── Context/ (ApplicationDbContext)
│   │   ├── Configurations/ (EF Core configs)
│   │   ├── Repositories/ (Repository implementations)
│   │   └── Migrations/ (Database migrations)
│   └── DependencyInjection
└── 🌐 API Layer (⏳ Planned)
    ├── Controllers/ (REST APIs)
    ├── DTOs/ (Data Transfer Objects)
    └── Mapping/ (AutoMapper profiles)
```

**Project Status:** 50% Complete - Ready for Business Services Implementation 🚀