clean up

docs/implementation-summaries/CATALOGUE_DUAL_IDENTIFIERS.md

@@ -1,358 +0,0 @@
-# Catalogue Dual Identifier System
-
-## Overview
-The catalogue system uses a dual identifier approach to provide both technical uniqueness and business readability:
-
-- **`catalogue_id`**: Technical UUID for system operations
-- **`catalogue_code`**: Business-readable code for human use
-
-## Identifier Types
-
-### 1. Catalogue ID (Technical)
-- **Format**: UUID4 (e.g., `550e8400-e29b-41d4-a716-446655440000`)
-- **Purpose**: Primary key for database operations
-- **Generation**: Auto-generated if not provided
-- **Usage**: API operations, database joins, system references
-
-### 2. Catalogue Code (Business)
-- **Format**: `BBB-CCC-NNNNNN` (e.g., `LOR-SHA-000001`)
-- **Purpose**: Human-readable identifier for business operations
-- **Generation**: Auto-generated based on brand + category + sequence
-- **Usage**: Reports, labels, business communications
-
-## Generation Rules
-
-### Catalogue ID Generation
-```python
-# Auto-generated UUID4
-catalogue_id = str(uuid4())
-# Result: "550e8400-e29b-41d4-a716-446655440000"
-```
-
-### Catalogue Code Generation
-```python
-# Format: BRAND(3)-CATEGORY(3)-SEQUENCE(6)
-brand_code = normalize_text_for_code("LOREAL", 3)      # "LOR"
-category_code = normalize_text_for_code("SHAMPOO", 3)  # "SHA"
-sequence = get_next_sequence("catalogue_code_seq")     # 1
-catalogue_code = f"{brand_code}-{category_code}-{sequence:06d}"
-# Result: "LOR-SHA-000001"
-```
-
-## Brand & Category Code Mapping
-
-### Brand Codes (Examples)
-| Brand Name | Code | Example |
-|------------|------|---------|
-| LOREAL | LOR | LOR-SHA-000001 |
-| MATRIX | MAT | MAT-CON-000001 |
-| SCHWARZKOPF | SCH | SCH-COL-000001 |
-| WELLA | WEL | WEL-MAS-000001 |
-| REDKEN | RED | RED-GEL-000001 |
-| TIGI | TIG | TIG-SPR-000001 |
-| PAUL_MITCHELL | PAU | PAU-OIL-000001 |
-| KERASTASE | KER | KER-SER-000001 |
-| OLAPLEX | OLA | OLA-TRE-000001 |
-| MOROCCANOIL | MOR | MOR-OIL-000001 |
-
-### Category Codes (Examples)
-| Category Name | Code | Example |
-|---------------|------|---------|
-| SHAMPOO | SHA | LOR-SHA-000001 |
-| CONDITIONER | CON | MAT-CON-000001 |
-| HAIR_MASK | HAI | WEL-HAI-000001 |
-| HAIR_COLOR | COL | SCH-COL-000001 |
-| STYLING_GEL | STY | RED-STY-000001 |
-| HAIR_SPRAY | SPR | TIG-SPR-000001 |
-| HAIR_OIL | OIL | PAU-OIL-000001 |
-| HAIR_SERUM | SER | KER-SER-000001 |
-
-## API Usage Examples
-
-### 1. Full Auto-Generation (Both IDs)
-```bash
-curl -X 'POST' \
-  'http://127.0.0.1:8000/catalogue/catalogues' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "catalogue_name": "L'\''Oreal Professional Shampoo",
-    "catalogue_type": "Product",
-    "brand": "LOREAL",
-    "category": "SHAMPOO",
-    "description": "Professional grade shampoo"
-  }'
-```
-
-**Response:**
-```json
-{
-  "data": {
-    "catalogue_id": "550e8400-e29b-41d4-a716-446655440000",
-    "catalogue_code": "LOR-SHA-000001",
-    "catalogue_name": "L'Oreal Professional Shampoo",
-    "catalogue_type": "Product",
-    "brand": "LOREAL",
-    "category": "SHAMPOO"
-  }
-}
-```
-
-### 2. Manual ID, Auto Code
-```bash
-curl -X 'POST' \
-  'http://127.0.0.1:8000/catalogue/catalogues' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "catalogue_id": "custom-loreal-shampoo-001",
-    "catalogue_name": "L'\''Oreal Serie Expert",
-    "catalogue_type": "Product",
-    "brand": "LOREAL",
-    "category": "SHAMPOO"
-  }'
-```
-
-**Response:**
-```json
-{
-  "data": {
-    "catalogue_id": "custom-loreal-shampoo-001",
-    "catalogue_code": "LOR-SHA-000002",
-    "catalogue_name": "L'Oreal Serie Expert",
-    "catalogue_type": "Product"
-  }
-}
-```
-
-### 3. Both Manual (Override)
-```bash
-curl -X 'POST' \
-  'http://127.0.0.1:8000/catalogue/catalogues' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "catalogue_id": "manual-id-123",
-    "catalogue_code": "CUSTOM-CODE-001",
-    "catalogue_name": "Custom Product",
-    "catalogue_type": "Product",
-    "brand": "OTHER",
-    "category": "OTHER"
-  }'
-```
-
-**Response:**
-```json
-{
-  "data": {
-    "catalogue_id": "manual-id-123",
-    "catalogue_code": "CUSTOM-CODE-001",
-    "catalogue_name": "Custom Product",
-    "catalogue_type": "Product"
-  }
-}
-```
-
-## Database Storage
-
-### MongoDB Document
-```json
-{
-  "_id": ObjectId("..."),
-  "catalogue_id": "550e8400-e29b-41d4-a716-446655440000",
-  "catalogue_code": "LOR-SHA-000001",
-  "catalogue_name": "L'Oreal Professional Shampoo",
-  "catalogue_type": "Product",
-  "brand": "LOREAL",
-  "category": "SHAMPOO",
-  "identifiers": {
-    "sku": "LOR-SHA-500ML",
-    "ean_code": "1234567890123"
-  },
-  "pricing": {
-    "mrp": 1000.00,
-    "retail_price": 850.00
-  }
-}
-```
-
-### PostgreSQL Record
-```sql
-INSERT INTO catalogue_ref (
-  catalogue_id,
-  catalogue_code,
-  catalogue_type,
-  catalogue_name,
-  sku,
-  mrp,
-  base_price,
-  status,
-  created_at
-) VALUES (
-  '550e8400-e29b-41d4-a716-446655440000',
-  'LOR-SHA-000001',
-  'Product',
-  'L''Oreal Professional Shampoo',
-  'LOR-SHA-500ML',
-  1000.00,
-  850.00,
-  'Active',
-  NOW()
-);
-```
-
-## Query Examples
-
-### By Catalogue ID (Technical)
-```bash
-# Get catalogue by UUID
-GET /catalogue/550e8400-e29b-41d4-a716-446655440000
-
-# Update catalogue by UUID
-PUT /catalogue/550e8400-e29b-41d4-a716-446655440000
-```
-
-### By Catalogue Code (Business)
-```bash
-# List catalogues by code pattern
-POST /catalogue/list
-{
-  "filters": {
-    "catalogue_code": {"$regex": "^LOR-SHA-"}
-  }
-}
-
-# Search by code prefix
-POST /catalogue/list
-{
-  "filters": {
-    "catalogue_code": {"$regex": "^LOR-"}
-  }
-}
-```
-
-### PostgreSQL Queries
-```sql
--- Find by catalogue code
-SELECT * FROM catalogue_ref 
-WHERE catalogue_code = 'LOR-SHA-000001';
-
--- Find all L'Oreal shampoos
-SELECT * FROM catalogue_ref 
-WHERE catalogue_code LIKE 'LOR-SHA-%';
-
--- Join with purchase orders using catalogue_id
-SELECT cr.catalogue_code, cr.catalogue_name, po.po_no
-FROM catalogue_ref cr
-JOIN scm_po_item poi ON cr.catalogue_id = poi.catalogue_id
-JOIN scm_po po ON poi.po_id = po.po_id;
-```
-
-## Use Cases
-
-### Technical Operations (catalogue_id)
-- **API Endpoints**: Primary identifier for REST operations
-- **Database Joins**: Foreign key relationships
-- **System Integration**: Microservice communication
-- **Caching**: Cache keys and lookups
-
-### Business Operations (catalogue_code)
-- **Reports**: Human-readable product codes
-- **Labels**: Product labeling and packaging
-- **Communication**: Business discussions and documentation
-- **Search**: User-friendly search and filtering
-
-## Benefits of Dual System
-
-### Technical Benefits
-1. **UUID Uniqueness**: Guaranteed global uniqueness
-2. **Performance**: Efficient database operations
-3. **Security**: Non-guessable identifiers
-4. **Scalability**: No collision concerns
-
-### Business Benefits
-1. **Readability**: Easy to understand and communicate
-2. **Organization**: Logical grouping by brand/category
-3. **Sorting**: Natural alphabetical sorting
-4. **Recognition**: Quick visual identification
-
-### Combined Benefits
-1. **Flexibility**: Choose appropriate ID for context
-2. **Migration**: Easy data migration between systems
-3. **Integration**: Support both technical and business needs
-4. **Reporting**: Technical accuracy with business clarity
-
-## Sequence Management
-
-### MongoDB Sequences
-```javascript
-// Sequence document in MongoDB
-{
-  "_id": "catalogue_code_seq",
-  "value": 1234
-}
-
-// Atomic increment
-db.sequences.findOneAndUpdate(
-  {"_id": "catalogue_code_seq"},
-  {"$inc": {"value": 1}},
-  {"upsert": true, "returnNewDocument": true}
-)
-```
-
-### Year-Based Sequences (Future Enhancement)
-```python
-# Potential enhancement: Year-based sequences
-def generate_yearly_code(brand, category, year=None):
-    year = year or datetime.now().year
-    seq = get_next_sequence(f"catalogue_code_seq_{year}")
-    return f"{brand_code}-{category_code}-{year}-{seq:06d}"
-    # Result: "LOR-SHA-2024-000001"
-```
-
-## Validation Rules
-
-### Catalogue ID Validation
-- Must be valid UUID format if provided
-- Auto-generated if not provided
-- Must be unique across all catalogues
-
-### Catalogue Code Validation
-- Must follow BBB-CCC-NNNNNN format if provided
-- Auto-generated if brand and category provided
-- Must be unique across all catalogues
-- Brand must be from valid brand list
-- Category must be from valid category list
-
-## Error Handling
-
-### Duplicate ID Errors
-```json
-{
-  "detail": "Catalogue ID already exists: 550e8400-e29b-41d4-a716-446655440000"
-}
-```
-
-### Duplicate Code Errors
-```json
-{
-  "detail": "Catalogue code already exists: LOR-SHA-000001"
-}
-```
-
-### Invalid Brand/Category
-```json
-{
-  "detail": "Invalid brand: FAKE_BRAND. Valid brands: LOREAL, MATRIX, ..."
-}
-```
-
-## Summary
-
-The dual identifier system provides:
-
-✅ **Technical Efficiency**: UUID for system operations  
-✅ **Business Clarity**: Readable codes for human use  
-✅ **Auto-Generation**: Both IDs generated automatically  
-✅ **Manual Override**: Custom IDs when needed  
-✅ **Validation**: Ensures uniqueness and format compliance  
-✅ **Flexibility**: Choose appropriate ID for each use case  
-
-This approach satisfies both technical requirements (unique, efficient identifiers) and business needs (readable, meaningful codes) in a single, cohesive system.

docs/implementation-summaries/CATALOGUE_SYNC_IMPLEMENTATION.md

@@ -1,327 +0,0 @@
-# Catalogue MongoDB-PostgreSQL Synchronization
-
-## Overview
-Complete implementation of dual-database synchronization for catalogue data. Maintains MongoDB as the primary source of truth while keeping a PostgreSQL reference table in sync for relational queries and reporting.
-
-## Architecture
-
-### Dual Database Strategy
-- **MongoDB**: Primary storage with full catalogue documents
-- **PostgreSQL**: Reference table (`catalogue_ref`) with essential fields for joins and reporting
-
-### Sync Flow
-```
-MongoDB CRUD Operation → PostgreSQL Sync → Response
-     ↓                        ↓
-Primary Data            Reference Data
-(Complete)              (Essential Fields)
-```
-
-## Database Schema
-
-### MongoDB Collection: `scm_catalogue`
-Complete catalogue documents with nested structures:
-- Full product information
-- Pricing levels and commission rules
-- Media and attributes
-- Metadata and audit trails
-
-### PostgreSQL Table: `catalogue_ref`
-```sql
-CREATE TABLE IF NOT EXISTS public.catalogue_ref (
-    catalogue_id text NOT NULL,
-    catalogue_code text,
-    catalogue_type text NOT NULL,
-    catalogue_name text NOT NULL,
-    sku text,
-    barcode_number text,
-    hsn_code text,
-    gst_rate numeric(5,2),
-    mrp numeric(12,2),
-    base_price numeric(12,2),
-    track_inventory boolean DEFAULT false,
-    batch_managed boolean DEFAULT false,
-    status text NOT NULL,
-    created_at timestamp without time zone NOT NULL,
-    merchant_id text[] DEFAULT '{}',
-    CONSTRAINT catalogue_ref_pkey PRIMARY KEY (catalogue_id)
-);
-```
-
-## Implementation Components
-
-### 1. PostgreSQL Model (`catalogue_ref_model.py`)
-```python
-class CatalogueRef(Base):
-    __tablename__ = 'catalogue_ref'
-    
-    catalogue_id = Column(Text, primary_key=True)
-    catalogue_code = Column(Text)
-    catalogue_type = Column(Text, nullable=False)
-    catalogue_name = Column(Text, nullable=False)
-    sku = Column(Text)
-    barcode_number = Column(Text)
-    hsn_code = Column(Text)
-    gst_rate = Column(Numeric(5, 2))
-    mrp = Column(Numeric(12, 2))
-    base_price = Column(Numeric(12, 2))
-    track_inventory = Column(Boolean, default=False)
-    batch_managed = Column(Boolean, default=False)
-    status = Column(Text, nullable=False)
-    created_at = Column(TIMESTAMP, nullable=False)
-    merchant_id = Column(ARRAY(Text))
-```
-
-### 2. Sync Service (`sync_service.py`)
-Handles all PostgreSQL operations:
-- **Data Extraction**: Converts MongoDB documents to PostgreSQL format
-- **CRUD Operations**: Create, update, delete reference records
-- **Status Management**: Sync activation/deactivation
-- **Merchant Management**: Add/remove merchants from catalogue access
-
-### 3. Enhanced Catalogue Service
-Updated to include PostgreSQL sync:
-- **Dual Operations**: MongoDB + PostgreSQL in single transaction
-- **Error Handling**: Continues on sync failures (logs errors)
-- **Optional Sync**: Works with or without PostgreSQL connection
-
-## Sync Operations
-
-### Create Catalogue
-```python
-# MongoDB Operation
-catalogue = await mongo_collection.insert_one(catalogue_data)
-
-# PostgreSQL Sync
-if sync_service:
-    await sync_service.create_catalogue_ref(catalogue_model)
-```
-
-### Update Catalogue
-```python
-# MongoDB Operation  
-await mongo_collection.update_one(filter, update_data)
-
-# PostgreSQL Sync
-updated_doc = await mongo_collection.find_one(filter)
-await sync_service.update_catalogue_ref(catalogue_id, updated_doc)
-```
-
-### Delete Catalogue
-```python
-# MongoDB Operation
-await mongo_collection.delete_one(filter)
-
-# PostgreSQL Sync
-await sync_service.delete_catalogue_ref(catalogue_id)
-```
-
-### Status Changes
-```python
-# MongoDB Operation
-await mongo_collection.update_one(filter, {"$set": {"meta.status": status}})
-
-# PostgreSQL Sync
-await sync_service.sync_catalogue_status(catalogue_id, status)
-```
-
-## Data Mapping
-
-### Field Extraction Rules
-| MongoDB Field | PostgreSQL Field | Extraction Logic |
-|---------------|------------------|------------------|
-| `catalogue_id` | `catalogue_id` | Direct copy |
-| `catalogue_code` | `catalogue_code` | Direct copy |
-| `identifiers.sku` | `sku` | Nested field extraction |
-| `identifiers.barcode_number` | `barcode_number` | Nested field extraction |
-| `pricing.mrp` | `mrp` | Nested field, convert to Decimal |
-| `pricing.retail_price` | `base_price` | Nested field, fallback to sale_price |
-| `tax.gst_rate` | `gst_rate` | Nested field, convert to Decimal |
-| `tax.hsn_code` | `hsn_code` | Nested field extraction |
-| `inventory.track_inventory` | `track_inventory` | Nested field, default False |
-| `procurement.batch_managed` | `batch_managed` | Derived from batch_managed presence |
-| `meta.status` | `status` | Nested field, default "Active" |
-| `meta.created_at` | `created_at` | Nested field extraction |
-
-## Error Handling
-
-### Sync Failure Strategy
-- **Primary Operation**: Always completes (MongoDB)
-- **Sync Failure**: Logged but doesn't fail main operation
-- **Monitoring**: Structured logging for sync errors
-- **Recovery**: Manual sync tools for fixing inconsistencies
-
-### Example Error Handling
-```python
-try:
-    # MongoDB operation (primary)
-    await mongo_collection.insert_one(data)
-    
-    # PostgreSQL sync (secondary)
-    if sync_service:
-        await sync_service.create_catalogue_ref(catalogue)
-        
-except Exception as sync_error:
-    logger.error(f"PostgreSQL sync failed: {sync_error}")
-    # Continue - don't fail the main operation
-```
-
-## API Integration
-
-### Controller Updates
-All catalogue modification endpoints now include PostgreSQL session:
-
-```python
-@router.post("/catalogues")
-async def create_catalogue(
-    data: Catalogue,
-    db: AsyncIOMotorDatabase = Depends(get_database),
-    pg_session: AsyncSession = Depends(get_pg_session),
-):
-    service = CatalogueService(db, pg_session)
-    return await service.create_catalogue_item(data, user_id)
-```
-
-### Affected Endpoints
-- `POST /catalogue/catalogues` - Create catalogue
-- `PUT /catalogue/{catalogue_id}` - Update catalogue  
-- `DELETE /catalogue/` - Delete catalogue
-- `POST /catalogue/{catalogue_id}/activate` - Activate catalogue
-- `POST /catalogue/{catalogue_id}/deactivate` - Deactivate catalogue
-
-## Benefits
-
-### Performance Benefits
-- **Fast Joins**: PostgreSQL reference table enables efficient joins with PO/GRN tables
-- **Reporting**: SQL queries for analytics and reporting
-- **Filtering**: Efficient filtering on indexed PostgreSQL fields
-- **Aggregations**: SQL aggregations for business intelligence
-
-### Data Consistency
-- **Single Source**: MongoDB remains authoritative
-- **Eventual Consistency**: PostgreSQL syncs asynchronously
-- **Error Recovery**: Sync failures don't affect primary operations
-- **Monitoring**: Comprehensive logging for sync status
-
-### Integration Benefits
-- **Purchase Orders**: Can join with `catalogue_ref` for SKU validation
-- **Inventory**: Track inventory flags in PostgreSQL
-- **Reporting**: SQL-based reports with catalogue data
-- **Analytics**: Business intelligence queries
-
-## Usage Examples
-
-### Create Catalogue with Auto-Sync
-```bash
-curl -X 'POST' \
-  'http://127.0.0.1:8000/catalogue/catalogues' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "catalogue_name": "L'\''Oreal Professional Shampoo",
-    "catalogue_type": "Product",
-    "brand": "LOREAL",
-    "category": "SHAMPOO",
-    "identifiers": {
-      "sku": "LOR-SHA-500ML",
-      "barcode_number": "1234567890"
-    },
-    "pricing": {
-      "mrp": 1000.00,
-      "retail_price": 850.00
-    },
-    "tax": {
-      "gst_rate": 18.0,
-      "hsn_code": "33051000"
-    }
-  }'
-```
-
-**Result**: 
-- MongoDB: Complete catalogue document
-- PostgreSQL: Reference record with essential fields
-
-### Query PostgreSQL Reference
-```sql
--- Find catalogues by brand and status
-SELECT catalogue_id, catalogue_name, sku, mrp, status
-FROM catalogue_ref 
-WHERE catalogue_code LIKE 'LOR-%' 
-  AND status = 'Active'
-  AND track_inventory = true;
-
--- Join with purchase orders
-SELECT cr.catalogue_name, cr.sku, po.po_no, poi.ord_qty
-FROM catalogue_ref cr
-JOIN scm_po_item poi ON cr.catalogue_id = poi.catalogue_id
-JOIN scm_po po ON poi.po_id = po.po_id
-WHERE cr.status = 'Active';
-```
-
-## Monitoring and Maintenance
-
-### Sync Status Monitoring
-- **Success Logs**: Successful sync operations
-- **Error Logs**: Failed sync attempts with details
-- **Metrics**: Sync success/failure rates
-- **Alerts**: Critical sync failures
-
-### Data Consistency Checks
-```sql
--- Find catalogues in MongoDB but not PostgreSQL
--- (Requires application-level query)
-
--- Find orphaned PostgreSQL records
-SELECT catalogue_id, catalogue_name 
-FROM catalogue_ref 
-WHERE catalogue_id NOT IN (
-  -- MongoDB catalogue IDs would need to be provided
-);
-```
-
-### Recovery Procedures
-1. **Identify Inconsistencies**: Compare MongoDB vs PostgreSQL
-2. **Bulk Sync**: Re-sync missing or outdated records
-3. **Cleanup**: Remove orphaned PostgreSQL records
-4. **Validation**: Verify data consistency post-recovery
-
-## Testing
-
-### Test Coverage
-- **Unit Tests**: Sync service methods
-- **Integration Tests**: End-to-end CRUD with sync
-- **Error Tests**: Sync failure scenarios
-- **Performance Tests**: Sync operation timing
-
-### Test Script
-Run `test_catalogue_sync.py` to verify:
-- Data extraction logic
-- PostgreSQL schema compatibility
-- Sync operation flow
-- Error handling
-
-## Future Enhancements
-
-### Potential Improvements
-1. **Batch Sync**: Bulk sync operations for performance
-2. **Conflict Resolution**: Handle concurrent updates
-3. **Sync Queue**: Asynchronous sync with retry logic
-4. **Data Validation**: Cross-database consistency checks
-5. **Sync Metrics**: Detailed performance monitoring
-
-### Scalability Considerations
-- **Connection Pooling**: Efficient PostgreSQL connections
-- **Async Operations**: Non-blocking sync operations
-- **Error Recovery**: Automatic retry mechanisms
-- **Monitoring**: Real-time sync health monitoring
-
-## Summary
-
-The catalogue synchronization system provides:
-- ✅ **Dual Database Support**: MongoDB + PostgreSQL
-- ✅ **Automatic Sync**: Transparent sync on all CRUD operations
-- ✅ **Error Resilience**: Continues on sync failures
-- ✅ **Performance**: Efficient PostgreSQL queries for reporting
-- ✅ **Consistency**: MongoDB as single source of truth
-- ✅ **Monitoring**: Comprehensive logging and error tracking
-
-This implementation enables the best of both worlds: MongoDB's flexibility for complex catalogue data and PostgreSQL's power for relational queries and reporting.

docs/implementation-summaries/CATALOGUE_VALIDATION_SUMMARY.md

@@ -1,125 +0,0 @@
-# Catalogue Schema Validation Updates - Industry Standards
-
-## Overview
-Updated the catalogue schema (`app/catalogues/schemas/schema.py`) to follow industry-standard validation practices with comprehensive field validation, cross-field validation, and proper error handling.
-
-## Key Improvements
-
-### 1. **Enum-Based Validation**
-- `CatalogueType`: Product, Service, Package
-- `CatalogueStatus`: Active, Inactive, Draft, Discontinued  
-- `Currency`: INR, USD, EUR
-- `CommissionType`: Percent, Flat
-- `UnitOfMeasure`: PCS, KG, GRAM, LITER, ML, etc.
-
-### 2. **Regex Pattern Validation**
-- **SKU**: `^[A-Z0-9\-_]{3,50}$` (3-50 alphanumeric, hyphens, underscores)
-- **EAN Code**: `^\d{8}|\d{13}$` (EAN-8 or EAN-13 format)
-- **Barcode**: `^[A-Z0-9\-_]{3,50}$` (alphanumeric with hyphens/underscores)
-- **HSN Code**: `^\d{4,8}$` (4-8 digit HSN codes)
-- **Catalogue Code**: `^[A-Z]{3}-[A-Z]{3}-\d{6}$` (BBB-CCC-NNNNNN format)
-- **HTTPS URLs**: `^https://.+` (secure URLs only)
-
-### 3. **Field Constraints**
-- **String Length**: Min/max length validation with whitespace stripping
-- **Numeric Ranges**: Proper bounds for prices (0-999999.99), percentages (0-100%), quantities
-- **Required Fields**: Contextual requirements based on catalogue type
-
-### 4. **Cross-Field Validation**
-- **Product Requirements**: Products must have identifiers with SKU
-- **Service Requirements**: Services should have descriptions
-- **Pricing Consistency**: MRP validation, margin limits
-- **Inventory Logic**: Reorder level vs safety stock vs max stock validation
-- **Commission Logic**: Type and value required when enabled
-- **Timestamp Logic**: Updated timestamp must be after created timestamp
-- **Optional Sections**: Attributes and Media are completely optional for all catalogue types
-
-### 5. **Industry-Standard GST Rates**
-- Validates against standard Indian GST rates: [0, 0.25, 3, 5, 12, 18, 28]
-- Prevents invalid GST rate entries
-
-### 6. **Enhanced Security**
-- **HTTPS-Only URLs**: All image and document URLs must use HTTPS
-- **Input Sanitization**: Automatic whitespace stripping and case normalization
-- **Field Length Limits**: Prevents oversized inputs
-
-### 7. **API Standards Compliance**
-- **Projection List Support**: All list endpoints support field projection for performance
-- **Filter Validation**: Validates allowed filter fields for each endpoint type
-- **Pagination Limits**: Proper bounds on skip/limit parameters
-- **Error Messages**: Descriptive validation error messages
-
-## Updated Models
-
-### Core Models
-1. **Identifier** - SKU, EAN, barcode validation
-2. **Attributes** - Product attribute constraints
-3. **PricingLevel** - Price and margin validation
-4. **Pricing** - Currency and pricing level validation
-5. **Commission** - Commission type and value validation
-6. **Loyalty** - Points and redemption validation
-7. **Procurement** - Batch management and lead time validation
-8. **InventoryLevel** - Stock level relationship validation
-9. **Inventory** - Unit of measure and level validation
-10. **Tax** - HSN code and GST rate validation
-11. **Media** - HTTPS URL validation for images
-12. **Meta** - Status and timestamp validation
-13. **Catalogue** - Main model with comprehensive cross-field validation
-
-### Request Schemas
-1. **CatalogueListFilter** - Standard list endpoint with projection support
-2. **CatalogueDetailsRequest** - Details endpoint with projection
-3. **CatalogueLazyFetchFilter** - Performance-optimized lazy loading
-4. **MerchantCatalogueListFilter** - Hybrid MongoDB + PostgreSQL queries
-
-## Benefits
-
-### Performance
-- **50-90% payload reduction** with projection lists
-- **Optimized queries** with proper filtering validation
-- **Reduced bandwidth** usage
-
-### Data Quality
-- **Consistent data formats** across all catalogue items
-- **Validated business rules** prevent invalid data entry
-- **Standardized codes** (SKU, HSN, catalogue codes)
-- **Flexible structure** with optional attributes and media sections
-
-### Security
-- **HTTPS-only URLs** for all media and documents
-- **Input validation** prevents injection attacks
-- **Field length limits** prevent buffer overflow
-
-### Developer Experience
-- **Clear error messages** for validation failures
-- **Comprehensive examples** in schema documentation
-- **Type safety** with Pydantic models
-
-## API Endpoint Compliance
-
-All catalogue list endpoints now follow the mandatory API standards:
-
-```python
-# POST /catalogue/list
-{
-    "filters": {"catalogue_type": "Product", "brand": "L'Oréal"},
-    "skip": 0,
-    "limit": 50,
-    "projection_list": ["catalogue_id", "catalogue_name", "pricing.mrp"]
-}
-```
-
-## Migration Notes
-
-- **Backward Compatibility**: Legacy fields maintained for smooth migration
-- **Gradual Adoption**: New validation can be enabled incrementally
-- **Data Cleanup**: Existing data should be validated against new rules
-
-## Testing Recommendations
-
-1. **Unit Tests**: Validate each field constraint and cross-field validation
-2. **Integration Tests**: Test projection list functionality
-3. **Performance Tests**: Measure query performance with projections
-4. **Data Migration Tests**: Validate existing data against new schema
-
-This update brings the catalogue schema in line with industry best practices for API design, data validation, and performance optimization.

docs/implementation-summaries/CRITICAL_FIX_TRAILING_NEWLINE.md

@@ -1,119 +0,0 @@
-# 🎯 CRITICAL FIX: Trailing Newline in Database Name
-
-## Issue Identified
-
-Your deployment environment variable `DB_NAME` (or `POSTGRES_DB`) has a **trailing newline character**:
-
-```
-database "cuatrolabs\n" does not exist
-                    ^^
-```
-
-This is why the connection was failing!
-
-## Root Cause
-
-Environment variables in your deployment platform likely have trailing whitespace or newlines. This commonly happens when:
-- Copy-pasting values with extra whitespace
-- Using multi-line input fields
-- Programmatically setting variables with `\n` included
-
-## Fix Applied
-
-Added `.strip()` to all PostgreSQL environment variables in `app/core/config.py`:
-
-```python
-# Before (BROKEN)
-POSTGRES_DB: str = os.getenv("POSTGRES_DB") or os.getenv("DB_NAME") or "cuatrolabs"
-
-# After (FIXED)
-POSTGRES_DB: str = (os.getenv("POSTGRES_DB") or os.getenv("DB_NAME") or "cuatrolabs").strip()
-```
-
-This removes:
-- Leading/trailing spaces
-- Newline characters (`\n`)
-- Carriage returns (`\r`)
-- Tabs (`\t`)
-
-## All Variables Cleaned
-
-✅ `POSTGRES_HOST` / `DB_HOST`
-✅ `POSTGRES_PORT` / `DB_PORT`
-✅ `POSTGRES_DB` / `DB_NAME` ← **This was the problem!**
-✅ `POSTGRES_USER` / `DB_USER`
-✅ `POSTGRES_PASSWORD` / `DB_PASSWORD`
-✅ `POSTGRES_SSL_MODE` / `DB_SSLMODE`
-✅ `POSTGRES_URI`
-
-## What Will Happen Now
-
-### Before (Failed)
-```
-database "cuatrolabs\n" does not exist
-```
-
-### After (Success)
-```
-[POSTGRES] ✅ Connection successful after 1 attempt(s)
-```
-
-## Action Required
-
-1. **Redeploy** your application with the updated code
-2. The `.strip()` will automatically clean the variables
-3. Connection should succeed immediately
-
-## Optional: Clean Your Environment Variables
-
-While `.strip()` fixes the issue, you should also clean your deployment environment variables:
-
-### Check These Variables
-
-In your deployment platform, verify these don't have trailing spaces/newlines:
-- `DB_NAME` → Should be exactly: `cuatrolabs` (no extra characters)
-- `DB_HOST` → Should be exactly: `ep-sweet-surf-a1qeduoy.ap-southeast-1.aws.neon.tech`
-- `DB_USER` → Should be exactly: `trans_owner`
-- `DB_PORT` → Should be exactly: `5432`
-
-### How to Check
-
-In your deployment platform's environment variable editor:
-1. Click on each variable
-2. Look for any trailing spaces or newlines
-3. Delete them if present
-4. Save
-
-## Testing
-
-The fix is already applied. When you redeploy, you should see:
-
-```
-[CONFIG] Built POSTGRES_URI from components
-[CONFIG]   Protocol: postgresql+asyncpg
-[CONFIG]   User: trans_owner
-[CONFIG]   Host: ep-sweet-surf-a1qeduoy.ap-southeast-1.aws.neon.tech
-[CONFIG]   Port: 5432
-[CONFIG]   Database: cuatrolabs  ← No more \n!
-[CONFIG]   Password: SET
-[CONFIG]   SSL Mode: require
-
-[POSTGRES] Attempting to connect (max retries: 30)...
-[POSTGRES] ✅ Connection successful after 1 attempt(s)
-```
-
-## Why This Wasn't Caught Earlier
-
-- Local `.env` file doesn't have trailing newlines
-- Tests passed locally
-- Only appeared in deployment environment
-- Error message showed the invisible `\n` character
-
-## Summary
-
-✅ **Problem**: `DB_NAME` had trailing newline (`"cuatrolabs\n"`)
-✅ **Solution**: Added `.strip()` to all environment variables
-✅ **Status**: Fixed and ready to deploy
-✅ **Next Step**: Redeploy and verify connection success
-
-The connection will now work correctly! 🎉

docs/implementation-summaries/EMPLOYEE_ENDPOINTS_IMPLEMENTATION_SUMMARY.md

@@ -1,341 +0,0 @@
-# Employee API Endpoints - Implementation Summary
-
-## Overview
-
-Successfully implemented **33 comprehensive employee management endpoints** covering the complete employee lifecycle from onboarding to offboarding.
-
-## Implementation Status: ✅ COMPLETE
-
-All requested endpoints have been implemented and verified.
-
----
-
-## Endpoints by Category
-
-### ✅ Core CRUD (6 endpoints)
-- `POST /employees` - Create employee
-- `POST /employees/list` - List employees with projection support
-- `GET /employees/{user_id}` - Get employee by ID
-- `GET /employees/code/{employee_code}` - Get employee by code
-- `PUT /employees/{user_id}` - Update employee
-- `DELETE /employees/{user_id}` - Soft delete employee
-
-### ✅ Onboarding (1 endpoint)
-- `POST /employees/{user_id}/onboarding/start` - Start onboarding process
-
-### ✅ Roles & Hierarchy (4 endpoints)
-- `PUT /employees/{user_id}/roles` - Update employee roles
-- `PUT /employees/{user_id}/manager` - Update employee manager
-- `GET /employees/{user_id}/reports` - Get direct reports
-- `GET /employees/{user_id}/hierarchy` - Get management chain
-
-### ✅ Mobile & Location (3 endpoints)
-- `PUT /employees/{user_id}/app-access` - Update app access settings
-- `PUT /employees/{user_id}/location` - Update location settings
-- `PATCH /employees/{user_id}/location-consent` - Update location consent (legacy)
-
-### ✅ System Access (3 endpoints)
-- `PUT /employees/{user_id}/system-access/enable` - Enable system access
-- `PUT /employees/{user_id}/system-access/disable` - Disable system access
-- `GET /employees/{user_id}/system-access/status` - Get access status
-
-### ✅ Documents & Compliance (4 endpoints)
-- `POST /employees/{user_id}/documents` - Add document
-- `GET /employees/{user_id}/documents` - Get all documents
-- `DELETE /employees/{user_id}/documents/{doc_type}` - Delete document
-- `POST /employees/{user_id}/documents/verify` - Verify document
-
-### ✅ Security & Devices (3 endpoints)
-- `GET /employees/{user_id}/devices` - List bound devices
-- `POST /employees/{user_id}/devices/block` - Block device
-- `POST /employees/{user_id}/sessions/logout-all` - Logout all sessions
-
-### ✅ Status & Offboarding (4 endpoints)
-- `PATCH /employees/{user_id}/status` - Update status
-- `POST /employees/{user_id}/suspend` - Suspend employee
-- `POST /employees/{user_id}/terminate` - Terminate employee
-- `POST /employees/{user_id}/offboarding/complete` - Complete offboarding
-
-### ✅ Self-Service (2 endpoints)
-- `GET /employees/me` - Get my profile
-- `GET /employees/me/team` - Get my team
-
-### 🚧 Audit (2 endpoints - Placeholders)
-- `GET /employees/{user_id}/audit-logs` - Get audit logs
-- `GET /employees/{user_id}/audit-logs/export` - Export audit logs
-
-### ✅ Dashboard (1 endpoint)
-- `GET /employees/info/widgets` - Get dashboard widgets
-
----
-
-## Key Features Implemented
-
-### 1. Comprehensive Validation
-- Employee code uniqueness
-- Email/phone uniqueness among active employees
-- Manager hierarchy rules enforcement
-- Age requirements (minimum 18 years)
-- 2FA enforcement for Admin/Finance/HR roles
-- Location tracking consent requirements
-
-### 2. Audit Trail
-- All mutation endpoints require `x-user-id` header
-- Tracks who made changes and when
-- Metadata fields for suspension/termination reasons
-
-### 3. Soft Delete Pattern
-- Employees are never hard-deleted
-- Status set to 'terminated' instead
-- Prevents deletion of employees with active reports
-
-### 4. Projection Support
-- `/employees/list` endpoint supports field projection
-- Reduces payload size by 50-90%
-- Follows API standards for all microservices
-
-### 5. Self-Service Capabilities
-- Employees can view their own profile
-- Managers can view their team
-- Supports mobile app integration
-
-### 6. Security Features
-- Device binding and blocking
-- Session management (logout all)
-- 2FA enforcement for sensitive roles
-- System access enable/disable
-
-### 7. Document Management
-- Support for multiple document types (PAN, Aadhaar, etc.)
-- Document verification workflow
-- HTTPS URL validation for document storage
-
-### 8. Location Tracking Compliance
-- Explicit consent tracking with timestamp
-- IP address and device tracking for consent
-- Background tracking opt-in
-- Geofencing support
-- Configurable retention periods
-
----
-
-## Business Rules Enforced
-
-### Manager Hierarchy
-- ASM → RSM
-- BDE → ASM or RSM
-- Trainer → ASM, RSM, or Head_Trainer
-- Field_Sales → ASM, RSM, or BDE
-
-### Status Transitions
-- onboarding → active (activation)
-- active → inactive (temporary leave)
-- active → suspended (disciplinary)
-- active/inactive/suspended → terminated (termination)
-
-### Required Fields by Role
-- RSM/ASM: Must have region assigned
-- ASM/BDE/Trainer/Field_Sales: Must have manager
-- Admin/Finance/HR: Must have 2FA enabled
-
-### Location Tracking
-- Requires mobile app access
-- Background tracking requires location consent
-- Consent timestamp automatically recorded
-
----
-
-## API Standards Compliance
-
-✅ **Projection List Support**
-- Implemented on `/employees/list` endpoint
-- Uses MongoDB projection for performance
-- Returns raw dict when projection used
-
-✅ **POST Method for List Endpoints**
-- `/employees/list` uses POST method
-- Supports complex filter criteria in request body
-
-✅ **Consistent Error Handling**
-- 400 for validation errors
-- 404 for not found
-- 500 for server errors
-
-✅ **Audit Trail**
-- `x-user-id` header on all mutation endpoints
-- Tracks created_by, updated_by, created_at, updated_at
-
-✅ **Soft Delete Pattern**
-- DELETE endpoint sets status to terminated
-- Prevents data loss
-- Maintains referential integrity
-
----
-
-## File Changes
-
-### Modified Files
-1. `cuatrolabs-scm-ms/app/employees/controllers/router.py`
-   - Added 20 new endpoint functions
-   - Added imports for LocationSettingsSchema, IDDocumentSchema, AppAccessSchema
-   - Organized endpoints by category with clear section headers
-
-### New Files
-1. `cuatrolabs-scm-ms/EMPLOYEE_API_ENDPOINTS.md`
-   - Complete API reference documentation
-   - Request/response examples
-   - Business rules and validations
-
-2. `cuatrolabs-scm-ms/EMPLOYEE_ENDPOINTS_IMPLEMENTATION_SUMMARY.md`
-   - This file - implementation summary
-
-3. `cuatrolabs-scm-ms/test_employee_endpoints.py`
-   - Verification script to check all endpoints are registered
-   - Categorizes endpoints by function
-   - Validates expected endpoints exist
-
----
-
-## Testing Results
-
-```
-✅ All 33 endpoints successfully registered
-✅ No syntax errors
-✅ No import errors
-✅ Proper categorization
-✅ Consistent naming conventions
-```
-
----
-
-## Next Steps & Recommendations
-
-### Immediate
-1. ✅ All core endpoints implemented
-2. ✅ Validation rules enforced
-3. ✅ Audit trail in place
-
-### Short Term
-1. 🚧 Implement actual audit log collection
-   - Create separate audit_logs collection
-   - Track all employee changes
-   - Support filtering and export
-
-2. 🚧 Integrate session management with auth service
-   - Implement token invalidation
-   - Support logout-all functionality
-
-3. 📝 Add comprehensive unit tests
-   - Test all validation rules
-   - Test manager hierarchy enforcement
-   - Test status transitions
-
-### Medium Term
-1. 📝 Add rate limiting for sensitive operations
-   - Suspend/terminate endpoints
-   - Document verification
-   - Device blocking
-
-2. 📝 Implement webhook notifications
-   - Status changes
-   - Document verification
-   - Offboarding completion
-
-3. 📝 Add bulk operations support
-   - Bulk employee creation
-   - Bulk status updates
-   - Bulk role assignments
-
-### Long Term
-1. 📝 Advanced analytics endpoints
-   - Employee turnover metrics
-   - Onboarding completion rates
-   - Team performance metrics
-
-2. 📝 Integration with external systems
-   - HRMS integration
-   - Payroll integration
-   - Background verification services
-
----
-
-## Usage Examples
-
-### Create Employee
-```bash
-curl -X POST http://localhost:8000/employees \
-  -H "Content-Type: application/json" \
-  -H "x-user-id: admin_001" \
-  -d '{
-    "employee_code": "EMP-MUM-001",
-    "first_name": "Rajesh",
-    "last_name": "Kumar",
-    "email": "rajesh.kumar@company.com",
-    "phone": "+919876543210",
-    "designation": "ASM",
-    "manager_id": "usr_RSM_001",
-    "base_city": "Mumbai",
-    "base_state": "Maharashtra",
-    "region": "Western",
-    "doj": "2023-01-10",
-    "emergency_contact": {
-      "name": "Priya Kumar",
-      "relation": "Spouse",
-      "phone": "+919876543211"
-    },
-    "created_by": "admin_001"
-  }'
-```
-
-### List Employees with Projection
-```bash
-curl -X POST http://localhost:8000/employees/list \
-  -H "Content-Type: application/json" \
-  -d '{
-    "designation": "ASM",
-    "status": "active",
-    "region": "Western",
-    "skip": 0,
-    "limit": 100,
-    "projection_list": ["user_id", "employee_code", "first_name", "email"]
-  }'
-```
-
-### Update Employee Roles
-```bash
-curl -X PUT http://localhost:8000/employees/usr_123/roles \
-  -H "Content-Type: application/json" \
-  -H "x-user-id: admin_001" \
-  -d '{
-    "roles": ["field_sales", "order_create", "merchant_view"]
-  }'
-```
-
-### Suspend Employee
-```bash
-curl -X POST http://localhost:8000/employees/usr_123/suspend \
-  -H "x-user-id: admin_001" \
-  -d "reason=Policy violation"
-```
-
-### Get My Team
-```bash
-curl -X GET http://localhost:8000/employees/me/team \
-  -H "x-user-id: usr_manager_001"
-```
-
----
-
-## Conclusion
-
-All requested employee API endpoints have been successfully implemented with:
-- ✅ 33 total endpoints covering complete employee lifecycle
-- ✅ Comprehensive validation and business rules
-- ✅ Audit trail and compliance features
-- ✅ API standards compliance (projection support, POST for lists)
-- ✅ Security features (device management, session control)
-- ✅ Self-service capabilities
-- ✅ Document management and verification
-- ✅ Location tracking with consent management
-
-The implementation is production-ready with clear documentation and follows established patterns from other modules in the SCM microservice.

docs/implementation-summaries/EMPLOYEE_SYNC_INTEGRATION_SUMMARY.md

@@ -1,204 +0,0 @@
-# Employee Sync Integration Summary
-
-## Task 11: Integrate employee sync triggers into API endpoints
-
-### Implementation Completed ✅
-
-This document summarizes the implementation of employee sync triggers in the SCM microservice API endpoints.
-
-## Changes Made
-
-### 1. Main Application (app/main.py)
-
-#### Added Employee Sync Service Import
-```python
-from app.sync.employees.service import EmployeeSyncService
-```
-
-#### Added Global Service Instance
-```python
-employee_sync_service: EmployeeSyncService = None
-```
-
-#### Initialized Service on Startup
-- Added employee sync service initialization in `startup_event()`
-- Configured with same settings as merchant and catalogue sync services
-- Started background workers for async processing
-- Added graceful error handling if PostgreSQL is unavailable
-
-#### Added Shutdown Handler
-- Added employee sync worker shutdown in `shutdown_event()`
-- Ensures graceful cleanup of background tasks
-
-#### Added Helper Function
-```python
-def get_employee_sync_service() -> EmployeeSyncService:
-    """Get the employee sync service instance."""
-    return employee_sync_service
-```
-
-### 2. Employee Router (app/employees/controllers/router.py)
-
-#### Added Sync Trigger Function
-```python
-def _trigger_employee_sync(employee_id: str, operation: str = "update") -> None:
-    """
-    Trigger employee sync to PostgreSQL (fire and forget).
-    
-    This is a non-blocking operation that queues the employee for sync.
-    Any errors are logged but do not affect the API response.
-    """
-```
-
-Features:
-- Non-blocking (fire and forget) operation
-- Uses asyncio.create_task for async execution
-- Handles missing service gracefully
-- Logs errors without affecting API response
-- Prevents circular dependency with lazy import
-
-#### Integrated Sync into POST /employees
-- Added sync trigger after successful employee creation
-- Passes `operation="create"` parameter
-- Uses `result.user_id` as employee identifier
-
-#### Integrated Sync into PUT /employees/{user_id}
-- Added sync trigger after successful employee update
-- Passes `operation="update"` parameter
-- Uses `user_id` parameter as employee identifier
-
-### 3. Integration Tests (tests/test_employee_sync_integration.py)
-
-Created comprehensive test suite with 6 tests:
-
-1. **test_employee_sync_service_initialized**
-   - Verifies service is accessible via helper function
-   - Handles case where PostgreSQL is unavailable
-
-2. **test_create_employee_triggers_sync**
-   - Verifies POST endpoint triggers sync
-   - Confirms operation="create" is passed
-   - Validates correct employee_id is used
-
-3. **test_update_employee_triggers_sync**
-   - Verifies PUT endpoint triggers sync
-   - Confirms operation="update" is passed
-   - Validates correct employee_id is used
-
-4. **test_sync_is_non_blocking**
-   - Verifies sync returns immediately
-   - Confirms fire-and-forget pattern
-   - Ensures API is not blocked by slow sync
-
-5. **test_sync_error_does_not_affect_api**
-   - Verifies sync errors are caught
-   - Confirms API continues to work
-   - Validates error isolation
-
-6. **test_sync_when_service_not_available**
-   - Verifies graceful handling when service is None
-   - Confirms no exceptions are raised
-   - Validates fallback behavior
-
-**All tests passed successfully! ✅**
-
-## Requirements Validation
-
-### Requirement 4.7: POST /employees triggers sync ✅
-- Implemented in `create_employee()` endpoint
-- Triggers sync after successful creation
-- Non-blocking operation
-- Error handling prevents API failures
-
-### Requirement 4.8: PUT /employees/{user_id} triggers sync ✅
-- Implemented in `update_employee()` endpoint
-- Triggers sync after successful update
-- Non-blocking operation
-- Error handling prevents API failures
-
-### Requirement 12.1: Async execution ✅
-- Uses `asyncio.create_task()` for fire-and-forget
-- Does not await sync completion
-- Returns immediately to client
-
-### Requirement 12.2: Non-blocking API response ✅
-- Sync triggered after MongoDB operation completes
-- API returns success without waiting for sync
-- Verified by test_sync_is_non_blocking
-
-### Additional Requirements Met
-
-- **Error Isolation**: Sync errors do not affect API (try/except in trigger function)
-- **Service Availability**: Gracefully handles missing PostgreSQL/sync service
-- **Logging**: All sync operations and errors are logged
-- **Consistency**: Follows same pattern as merchant and catalogue sync
-- **Testing**: Comprehensive integration test coverage
-
-## Architecture
-
-```
-API Request → Employee Service → MongoDB
-                    ↓
-              API Response (immediate)
-                    ↓
-         _trigger_employee_sync() (fire & forget)
-                    ↓
-         EmployeeSyncService.sync_employee()
-                    ↓
-              Async Queue
-                    ↓
-         Background Workers (5 workers)
-                    ↓
-              PostgreSQL
-```
-
-## Configuration
-
-The employee sync service uses the same configuration as other sync services:
-
-- `SYNC_QUEUE_MAX_SIZE`: Maximum queue size (default: 1000)
-- `SYNC_WORKER_COUNT`: Number of background workers (default: 5)
-- `SYNC_RETRY_MAX_ATTEMPTS`: Maximum retry attempts (default: 3)
-- `SYNC_QUEUE_WARNING_THRESHOLD`: Warning threshold (default: 500)
-- `SYNC_QUEUE_CRITICAL_THRESHOLD`: Critical threshold (default: 800)
-
-## Verification
-
-### Code Quality
-- ✅ No diagnostic errors in main.py
-- ✅ No diagnostic errors in router.py
-- ✅ Follows existing patterns (merchant/catalogue sync)
-- ✅ Proper error handling
-- ✅ Comprehensive logging
-
-### Testing
-- ✅ 6/6 integration tests passing
-- ✅ Service initialization tested
-- ✅ Create endpoint sync tested
-- ✅ Update endpoint sync tested
-- ✅ Non-blocking behavior tested
-- ✅ Error handling tested
-- ✅ Service unavailability tested
-
-### Requirements
-- ✅ Requirement 4.7 (POST sync trigger)
-- ✅ Requirement 4.8 (PUT sync trigger)
-- ✅ Requirement 12.1 (Async execution)
-- ✅ Requirement 12.2 (Non-blocking)
-
-## Next Steps
-
-The employee sync integration is complete and ready for use. The next tasks in the implementation plan are:
-
-- Task 12: Implement error handling and retry logic (already implemented in sync service)
-- Task 13-15: Implement bulk sync operations
-- Task 16: Implement monitoring and alerting
-- Task 17: Add configuration management
-
-## Notes
-
-- The implementation follows the exact same pattern as merchant and catalogue sync
-- All sync operations are logged for monitoring and debugging
-- The system gracefully handles PostgreSQL unavailability
-- Background workers process sync queue asynchronously
-- Retry logic with exponential backoff is already implemented in the sync service

docs/implementation-summaries/FINAL_CONFIG_SUMMARY.md

@@ -1,137 +0,0 @@
-# PostgreSQL Connection - Final Configuration Summary
-
-## ✅ Configuration Updated to Match Working TMS Pattern
-
-Your `app/core/config.py` has been updated to **exactly match** the working pattern from `insightfy-bloom-ms-tms/settings.py`.
-
-## Key Changes
-
-### 1. Connection String Formation (Exact TMS Pattern)
-
-```python
-# Check if all required components are present (TMS pattern)
-if all([POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_HOST, POSTGRES_DB]):
-    protocol = os.getenv("DB_PROTOCOL", "postgresql+asyncpg")
-    
-    # Build URI with URL-encoded password
-    POSTGRES_URI = f"{protocol}://{POSTGRES_USER}:{quote_plus(POSTGRES_PASSWORD)}@{POSTGRES_HOST}:{POSTGRES_PORT}/{POSTGRES_DB}"
-else:
-    POSTGRES_URI = None
-    # Raise error with helpful diagnostics
-```
-
-### 2. Dual Variable Support
-
-Supports both naming conventions:
-- `POSTGRES_*` variables (primary)
-- `DB_*` variables (fallback)
-
-```python
-POSTGRES_HOST = os.getenv("POSTGRES_HOST") or os.getenv("DB_HOST") or "localhost"
-POSTGRES_USER = os.getenv("POSTGRES_USER") or os.getenv("DB_USER") or "postgres"
-# ... etc
-```
-
-### 3. URL Encoding
-
-Uses `quote_plus()` for password encoding (critical for special characters):
-```python
-quote_plus(POSTGRES_PASSWORD)
-```
-
-## What Will Happen in Deployment
-
-### Scenario 1: Using POSTGRES_URI (Local .env)
-```
-[CONFIG] Using provided POSTGRES_URI
-```
-
-### Scenario 2: Using DB_* Variables (Deployment)
-```
-[CONFIG] Built POSTGRES_URI from components
-[CONFIG]   Protocol: postgresql+asyncpg
-[CONFIG]   User: trans_owner
-[CONFIG]   Host: ep-sweet-surf-a1qeduoy.ap-southeast-1.aws.neon.tech
-[CONFIG]   Port: 5432
-[CONFIG]   Database: cuatrolabs
-[CONFIG]   Password: SET
-[CONFIG]   SSL Mode: require
-```
-
-Then connection attempt:
-```
-======================================================================
-[POSTGRES] Starting Database Connection
-======================================================================
-[POSTGRES] Connection String: postgresql+asyncpg://trans_owner:***@ep-sweet-surf-a1qeduoy...
-[POSTGRES] Host: ep-sweet-surf-a1qeduoy.ap-southeast-1.aws.neon.tech
-[POSTGRES] Port: 5432
-[POSTGRES] Database: cuatrolabs
-[POSTGRES] SSL Mode: require
-======================================================================
-
-[POSTGRES] Attempting to connect (max retries: 30)...
-[POSTGRES] ✅ Connection successful after 1 attempt(s)
-```
-
-## Deployment Environment Variables
-
-Your deployment needs these variables set:
-
-**Option 1: Single URI (Recommended)**
-```bash
-POSTGRES_URI=postgresql+asyncpg://trans_owner:BookMyService7@ep-sweet-surf-a1qeduoy.ap-southeast-1.aws.neon.tech:5432/cuatrolabs
-```
-
-**Option 2: Individual Components (Current)**
-```bash
-DB_PROTOCOL=postgresql+asyncpg
-DB_USER=trans_owner
-DB_PASSWORD=BookMyService7
-DB_HOST=ep-sweet-surf-a1qeduoy.ap-southeast-1.aws.neon.tech
-DB_PORT=5432
-DB_NAME=cuatrolabs
-DB_SSLMODE=require
-```
-
-Both options will now work correctly!
-
-## Error Handling
-
-If variables are missing, you'll see:
-```
-[CONFIG] ERROR: Cannot build POSTGRES_URI - missing required components
-[CONFIG]   POSTGRES_USER: MISSING
-[CONFIG]   POSTGRES_PASSWORD: SET
-[CONFIG]   POSTGRES_HOST: SET
-[CONFIG]   POSTGRES_DB: MISSING
-
-[CONFIG] Checking alternative env vars:
-[CONFIG]   DB_USER: trans_owner
-[CONFIG]   DB_PASSWORD: SET
-[CONFIG]   DB_HOST: ep-sweet-surf-a1qeduoy.ap-southeast-1.aws.neon.tech
-[CONFIG]   DB_NAME: cuatrolabs
-```
-
-This makes it immediately clear which variables need to be set.
-
-## Next Steps
-
-1. **Commit and push** the updated code
-2. **Redeploy** your application
-3. **Check startup logs** for the configuration messages
-4. **Verify connection** success message
-
-The configuration now exactly matches your working TMS service and should connect successfully!
-
-## Differences from Previous Implementation
-
-| Aspect | Before | Now (TMS Pattern) |
-|--------|--------|-------------------|
-| Validation | After building URI | Before building URI with `all()` |
-| Password encoding | Conditional | Always use `quote_plus()` |
-| Error handling | Generic | Detailed with component status |
-| Variable check | Simple if/else | `all([...])` pattern |
-| Protocol support | Hardcoded | From `DB_PROTOCOL` env var |
-
-All changes align with the proven working pattern from your TMS service.

docs/implementation-summaries/IMPLEMENTATION_SUMMARY.md

@@ -1,235 +0,0 @@
-# SCM Microservice - Complete Implementation Summary
-
-## Overview
-Complete end-to-end implementation of Purchase Orders (PO), Goods Received Notes (GRN), and Return Merchandise Authorization (RMA) modules for the Supply Chain Management system.
-
-## Implementation Details
-
-### 1. Purchase Orders (PO) Module
-
-**Files Created:**
-- `app/schemas/purchase_order_schema.py` - Pydantic schemas
-- `app/services/purchase_order_service.py` - Business logic
-- `app/routers/purchase_order_router.py` - API endpoints
-
-**Features:**
-- ✅ Complete PO lifecycle: Draft → Submitted → Confirmed → Dispatched → Closed
-- ✅ Merchant hierarchy validation (buyer must be child of supplier)
-- ✅ Actions: Accept, Partial Accept, Reject, Cancel
-- ✅ Financial calculations with GST breakdown (CGST/SGST/IGST)
-- ✅ Auto-generated PO numbers with merchant prefix
-- ✅ Item-level tracking with quantities and pricing
-- ✅ Payment terms and delivery dates
-- ✅ Audit trail (created_by, timestamps, approval tracking)
-
-**API Endpoints:**
-- `POST /purchase-orders` - Create PO
-- `GET /purchase-orders/{po_id}` - Get PO
-- `PUT /purchase-orders/{po_id}` - Update PO
-- `POST /purchase-orders/{po_id}/submit` - Submit for approval
-- `POST /purchase-orders/{po_id}/action` - Accept/Reject/Cancel
-- `GET /purchase-orders` - List with filters
-- `DELETE /purchase-orders/{po_id}` - Cancel PO
-
-**Business Rules:**
-- Validates merchant hierarchy (to_merchant must be parent of from_merchant)
-- Supplier must be active
-- Only draft/submitted POs can be updated
-- Partial acceptance allows quantity modifications
-- Automatic totals calculation on item changes
-
-### 2. Goods Received Note (GRN) Module
-
-**Files Created:**
-- `app/schemas/grn_schema.py` - Pydantic schemas
-- `app/services/grn_service.py` - Business logic
-- `app/routers/grn_router.py` - API endpoints
-
-**Features:**
-- ✅ Receipt tracking for purchase orders
-- ✅ Automatic discrepancy detection (expected vs received)
-- ✅ Item condition tracking (good, damaged, defective, expired)
-- ✅ Serial/batch number scanning and validation
-- ✅ Photo evidence attachment for discrepancies
-- ✅ Automatic inventory ledger updates
-- ✅ Carrier and shipment tracking
-- ✅ Resolution workflow for discrepancies
-
-**API Endpoints:**
-- `POST /grn` - Create GRN
-- `GET /grn/{grn_id}` - Get GRN
-- `PUT /grn/{grn_id}` - Update GRN
-- `POST /grn/{grn_id}/resolve` - Resolve discrepancies
-- `GET /grn` - List with filters
-
-**Business Rules:**
-- Validates PO exists and is in correct status (confirmed/partial/dispatched)
-- Automatically calculates discrepancies
-- Updates inventory ledger for accepted items only
-- Closes PO when fully received
-- Supports partial receipts with multiple GRNs per PO
-- Quarantines damaged/defective items
-
-### 3. Return Merchandise Authorization (RMA) Module
-
-**Files Created:**
-- `app/schemas/rma_schema.py` - Pydantic schemas
-- `app/services/rma_service.py` - Business logic
-- `app/routers/rma_router.py` - API endpoints
-
-**Features:**
-- ✅ Complete return workflow: Requested → Approved → Picked → Inspected → Closed
-- ✅ Return reasons (defective, damaged, wrong_item, quality_issue, etc.)
-- ✅ Actions: Refund, Replace, Store Credit, Repair
-- ✅ Pickup scheduling with carrier integration
-- ✅ Inspection workflow with approval/rejection
-- ✅ Credit note generation
-- ✅ Inventory updates for returned items
-- ✅ Serial number validation against original order
-
-**API Endpoints:**
-- `POST /rma` - Create RMA
-- `GET /rma/{rma_id}` - Get RMA
-- `PUT /rma/{rma_id}` - Update RMA
-- `POST /rma/{rma_id}/approve` - Approve/Reject
-- `POST /rma/{rma_id}/pickup` - Schedule pickup
-- `POST /rma/{rma_id}/inspect` - Perform inspection
-- `GET /rma` - List with filters
-- `DELETE /rma/{rma_id}` - Cancel RMA
-
-**Business Rules:**
-- Validates items are from the original order
-- Enforces return window policies
-- Supports partial approvals
-- Validates serial numbers against inventory
-- Updates inventory ledger on inspection approval
-- Closes RMA after refund/replacement processing
-
-### 4. Database Collections
-
-**New Collections Added:**
-- `scm_purchase_orders` - Purchase orders
-- `scm_grn` - Goods received notes
-- `scm_rma` - Return merchandise authorizations
-- `scm_inventory_ledger` - Inventory transactions
-- `scm_qr_scans` - QR/serial scan logs
-- `scm_shipments` - Shipment tracking
-- `scm_invoices` - Invoice records
-- `scm_credit_notes` - Credit notes
-
-### 5. Integration Points
-
-**Existing Integrations:**
-- Merchant hierarchy validation
-- Sales order linkage for RMA
-- Employee tracking for actions
-
-**Future Integrations:**
-- Carrier APIs (DTDC, etc.) for AWB generation and tracking
-- Payment gateway for refunds
-- QR scanning service for serial validation
-- Notification service for status updates
-- Analytics service for reporting
-
-### 6. Workflow Example
-
-Complete supply chain flow:
-
-```
-1. retail creates PO → distributor
-2. distributor accepts PO
-3. distributor dispatches goods
-4. retail receives goods (creates GRN)
-5. GRN shows discrepancies (short-shipped/damaged)
-6. retail resolves discrepancy (accepts with credit note)
-7. retail sells to customer (Sales Order)
-8. Customer requests return (creates RMA)
-9. retail approves RMA
-10. Pickup scheduled
-11. Items inspected
-12. Refund processed, RMA closed
-```
-
-See `examples/po_grn_rma_workflow.py` for complete working example.
-
-### 7. Key Features Implemented
-
-**Validation & Business Logic:**
-- ✅ Merchant hierarchy validation
-- ✅ Status-based workflow enforcement
-- ✅ Quantity and pricing calculations
-- ✅ GST calculations (CGST/SGST/IGST)
-- ✅ Discrepancy detection and tracking
-- ✅ Serial/batch number tracking
-- ✅ Idempotency support
-
-**Audit & Traceability:**
-- ✅ Complete audit trail (created_by, updated_by, timestamps)
-- ✅ Status history tracking
-- ✅ Action logging (approvals, rejections, resolutions)
-- ✅ Serial number traceability
-- ✅ Photo evidence for discrepancies
-
-**Inventory Management:**
-- ✅ Automatic inventory ledger updates
-- ✅ Batch and serial tracking
-- ✅ Condition-based inventory (good/damaged/defective)
-- ✅ Return inventory processing
-
-### 8. Testing
-
-**Test Files:**
-- `examples/quick_start.py` - Merchant hierarchy setup
-- `examples/po_grn_rma_workflow.py` - Complete workflow test
-
-**To Test:**
-```bash
-# Start server
-uvicorn app.main:app --reload --port 9292
-
-# Run workflow test
-python3 examples/po_grn_rma_workflow.py
-```
-
-### 9. API Documentation
-
-Once server is running, access interactive documentation:
-- Swagger UI: http://localhost:9292/docs
-- ReDoc: http://localhost:9292/redoc
-
-### 10. Production Readiness Checklist
-
-**Completed:**
-- ✅ Pydantic v2 schemas with validation
-- ✅ Async database operations
-- ✅ Error handling and logging
-- ✅ Status-based workflow enforcement
-- ✅ Business rule validation
-- ✅ Audit trail tracking
-
-**Recommended Enhancements:**
-- [ ] Add authentication/authorization middleware
-- [ ] Implement rate limiting
-- [ ] Add caching for frequently accessed data
-- [ ] Implement event bus for inter-service communication
-- [ ] Add comprehensive unit and integration tests
-- [ ] Implement carrier API integrations
-- [ ] Add QR scanning service integration
-- [ ] Implement notification service
-- [ ] Add analytics and reporting endpoints
-- [ ] Implement file upload for attachments
-- [ ] Add webhook support for external systems
-
-## Summary
-
-Successfully implemented complete Purchase Order, GRN, and RMA modules with:
-- **3 new modules** (PO, GRN, RMA)
-- **9 new schemas** with comprehensive validation
-- **3 new services** with business logic
-- **3 new routers** with 20+ API endpoints
-- **8 new database collections**
-- **Complete workflow** from purchase to returns
-- **Full audit trail** and traceability
-- **Production-ready** code with error handling
-
-All modules follow the specification requirements for the Company → ncnf → cnf → distributor → retail hierarchy with proper validation, tracking, and integration points.

docs/implementation-summaries/INVENTORY_CONTROL_API_IMPLEMENTATION.md

@@ -1,174 +0,0 @@
-# Inventory Control API Implementation Summary
-
-## 📦 Overview
-
-This document summarizes the implementation of Stock Take & Stock Adjustment APIs that fully comply with the provided API specification. The implementation follows the orchestration-only pattern, delegating actual inventory mutations to existing stored procedures.
-
-## ✅ Implementation Status
-
-### Stock Take APIs - **COMPLETE**
-
-| Endpoint | Method | Status | Description |
-|----------|--------|--------|-------------|
-| `/inventory/stock-take` | POST | ✅ | Create stock takes (bulk entries) |
-| `/inventory/stock-take/list` | POST | ✅ | List with projection support |
-| `/inventory/stock-take/{id}` | GET | ✅ | Get stock take details |
-| `/inventory/stock-take/{id}/apply` | POST | ✅ | Apply variance to inventory |
-
-### Stock Adjustment APIs - **COMPLETE**
-
-| Endpoint | Method | Status | Description |
-|----------|--------|--------|-------------|
-| `/inventory/adjustments` | POST | ✅ | Create adjustments (bulk entries) |
-| `/inventory/adjustments/list` | POST | ✅ | List with projection support |
-| `/inventory/adjustments/{id}` | GET | ✅ | Get adjustment details |
-| `/inventory/adjustments/{id}/approve` | POST | ✅ | Approve adjustment |
-| `/inventory/adjustments/{id}/reject` | POST | ✅ | Reject adjustment |
-
-## 🔧 Key Features Implemented
-
-### 1. Bulk Operations Support
-- **Stock Take**: Multiple SKUs per request via `entries[]` array
-- **Stock Adjustment**: Multiple SKUs per request via `entries[]` array
-- Automatic system quantity lookup from stock snapshot
-- Variance calculation (physical - system)
-
-### 2. Projection List Support (API Standard Compliance)
-- All list endpoints support `projection_list` parameter
-- 50-90% payload reduction possible
-- Raw dict return when projection used, full model otherwise
-- Follows MongoDB-style projection pattern
-
-### 3. Status Flow Management
-- **Stock Take**: RECORDED → APPLIED (immutable)
-- **Stock Adjustment**: PENDING → APPROVED/REJECTED → APPLIED (immutable)
-- Proper validation of status transitions
-
-### 4. Orchestration-Only Pattern
-- ❌ No direct writes to stock tables
-- ❌ No direct writes to ledger tables  
-- ✅ Calls existing stored procedures for inventory mutations
-- ✅ API layer handles workflow orchestration only
-
-## 📊 Database Tables
-
-### Tables Written To (Orchestration)
-- `scm_stock_take` - Stock take records
-- `scm_stock_adjustment` - Adjustment records
-
-### Tables Updated Via Stored Procedures
-- `scm_stock_ledger` - Immutable transaction log
-- `scm_stock` - Derived stock snapshot
-
-## 🚀 Request/Response Examples
-
-### Create Stock Take (Bulk)
-```json
-POST /inventory/stock-take
-{
-  "warehouse_id": "warehouse_123",
-  "entries": [
-    {
-      "sku": "SHMP-500-ALOE",
-      "batch_no": "BATCH-20240101", 
-      "physical_qty": 95,
-      "remarks": "Shelf count"
-    }
-  ]
-}
-```
-
-### Create Stock Adjustment (Bulk)
-```json
-POST /inventory/adjustments
-{
-  "warehouse_id": "warehouse_123",
-  "entries": [
-    {
-      "sku": "SHMP-500-ALOE",
-      "batch_no": "BATCH-20240101",
-      "adjustment_type": "DAMAGE",
-      "qty": 5,
-      "reason": "Broken bottles"
-    }
-  ]
-}
-```
-
-### List with Projection
-```json
-POST /inventory/stock-take/list
-{
-  "filters": {
-    "warehouse_id": "warehouse_123",
-    "status": "recorded"
-  },
-  "projection_list": ["stock_take_id", "sku", "variance_qty", "status"]
-}
-```
-
-## 🔄 Integration Points
-
-### Existing Stored Procedures
-- Stock ledger procedures are called during:
-  - Stock Take: `POST /{id}/apply` 
-  - Stock Adjustment: `POST /{id}/approve`
-- Procedures handle:
-  - Ledger entry creation
-  - Stock snapshot updates
-  - Transaction atomicity
-
-### Legacy Support
-- Single-entry schemas maintained for backward compatibility
-- `CreateStockTakeRequestSingle`
-- `CreateStockAdjustmentRequestSingle`
-
-## 📁 File Structure
-
-```
-app/inventory/
-├── stock_take/
-│   ├── controllers/router.py     # API endpoints
-│   ├── services/service.py       # Business logic
-│   ├── schemas/schema.py         # Request/response models
-│   └── models/model.py           # DB model imports
-├── adjustments/
-│   ├── controllers/router.py     # API endpoints  
-│   ├── services/service.py       # Business logic
-│   ├── schemas/schema.py         # Request/response models
-│   └── models/model.py           # DB model imports & enums
-└── models/inventory_model.py     # PostgreSQL table definitions
-```
-
-## 🎯 Compliance Checklist
-
-- ✅ **POST Method**: All list endpoints use POST
-- ✅ **Projection Support**: Optional `projection_list` parameter
-- ✅ **Bulk Operations**: Multiple entries per request
-- ✅ **Status Flows**: Proper lifecycle management
-- ✅ **Orchestration Only**: No direct DB mutations
-- ✅ **Stored Procedure Integration**: Existing procedures called
-- ✅ **Error Handling**: Comprehensive validation & error responses
-- ✅ **Logging**: Structured logging throughout
-- ✅ **Type Safety**: Full Pydantic model validation
-
-## 🧪 Testing
-
-Run the validation script:
-```bash
-cd cuatrolabs-scm-ms
-python3 test_inventory_apis.py
-```
-
-## 🚀 Next Steps
-
-1. **Integration Testing**: Test with actual stored procedures
-2. **Authentication**: Add user context from auth middleware  
-3. **Performance Testing**: Validate projection performance gains
-4. **Documentation**: Update OpenAPI specs
-5. **Monitoring**: Add metrics for inventory operations
-
----
-
-**Implementation Complete** ✨  
-All APIs match the provided specification and are ready for integration testing.

docs/implementation-summaries/INVENTORY_CONTROL_IMPLEMENTATION.md

@@ -1,259 +0,0 @@
-# Inventory Control APIs Implementation - PostgreSQL
-
-## Overview
-
-Successfully implemented Stock Adjustment and Stock Take APIs for the SCM system using **PostgreSQL** following the exact specifications. The implementation maintains strict adherence to ledger integrity and auditability requirements, consistent with the purchase orders and receipts pattern.
-
-## 🏗️ Architecture
-
-### Core Principles Implemented
-- **Immutable Ledger**: `scm_stock_ledger` table is append-only, single source of truth
-- **Derived Snapshots**: `scm_stock` table is calculated from ledger, never directly edited
-- **Approval Workflow**: Adjustments above threshold require approval before application
-- **Audit Trail**: Complete tracking of all inventory movements with PostgreSQL ACID compliance
-
-### PostgreSQL Tables
-- `scm_stock_adjustment` - Stock adjustment records with UUID primary keys
-- `scm_stock_take` - Physical count records with variance calculations
-- `scm_stock_ledger` - Immutable transaction log with foreign key relationships
-- `scm_stock` - Derived stock snapshots with constraints and triggers
-
-## 📦 Modules Created
-
-### 1. Stock Adjustments (`app/inventory/adjustments/`)
-```
-adjustments/
-├── models/model.py          # StockAdjustmentModel, enums
-├── schemas/schema.py        # Request/response schemas with projection support
-├── services/service.py      # Business logic and database operations
-└── controllers/router.py    # FastAPI endpoints
-```
-
-### 2. Stock Take (`app/inventory/stock_take/`)
-```
-stock_take/
-├── models/model.py          # StockTakeModel, enums
-├── services/service.py      # Business logic and database operations
-└── controllers/router.py    # FastAPI endpoints
-```
-
-### 3. Ledger Models (`app/inventory/ledger/models/`)
-```
-ledger/models/
-└── model.py                 # StockLedgerModel, StockSnapshotModel
-```
-
-## 🔌 API Endpoints
-
-### Stock Adjustments
-- `POST /inventory/adjustments/` - Create adjustment
-- `POST /inventory/adjustments/{id}/approve` - Approve pending adjustment
-- `GET /inventory/adjustments/{id}` - Get adjustment details
-- `POST /inventory/adjustments/list` - List with projection support
-
-### Stock Take
-- `POST /inventory/stock-take/` - Record physical count
-- `POST /inventory/stock-take/{id}/apply` - Apply variance
-- `GET /inventory/stock-take/{id}` - Get stock take details
-- `POST /inventory/stock-take/list` - List with projection support
-
-## 🔄 Data Flow Implementation
-
-### Stock Adjustment Flow
-1. **Create** → Validates stock availability for OUT adjustments
-2. **Approval** → Required if qty > threshold (10 units)
-3. **Apply** → Creates ledger entry + updates stock snapshot
-4. **Complete** → Marks adjustment as applied
-
-### Stock Take Flow
-1. **Record** → Saves physical count, calculates variance
-2. **Apply** → Creates internal adjustment for variance
-3. **Process** → Follows adjustment approval workflow
-4. **Complete** → Updates inventory via ledger
-
-## 🛡️ Business Rules Enforced
-
-### PostgreSQL Constraints
-- `CHECK` constraints ensure positive quantities
-- `FOREIGN KEY` relationships maintain referential integrity
-- `UNIQUE` constraints prevent duplicate entries
-- `NOT NULL` constraints enforce required fields
-
-### Validation Rules
-- Cannot adjust more than `qty_on_hand` (validated in service layer)
-- Expired batches cannot be adjusted IN
-- Batch required for batch-managed SKUs
-- Physical qty must be >= 0 (enforced by CHECK constraint)
-- Cannot apply stock take twice (status validation)
-
-### Approval Workflow
-- Adjustments > 10 units require approval
-- Auto-approval for smaller adjustments
-- Role-based access control implemented
-- PostgreSQL transactions ensure atomicity
-
-### Ledger Integrity
-- All entries are immutable (append-only table design)
-- Every adjustment generates ledger entry with UUID references
-- Stock snapshots derived from ledger via SQL operations
-- Complete audit trail maintained with PostgreSQL durability
-
-## 📊 Projection List Support
-
-Both list endpoints implement the mandatory projection list standard with **PostgreSQL-optimized queries**:
-
-```python
-# Example request with projection
-{
-  "filters": {"merchant_id": "merchant_123", "status": "pending"},
-  "skip": 0,
-  "limit": 50,
-  "projection_list": ["adjustment_id", "sku", "qty", "status", "created_at"]
-}
-```
-
-**PostgreSQL Implementation:**
-- Uses SQLAlchemy `select()` with specific column selection
-- Leverages PostgreSQL query optimization
-- Maintains consistent API contract (raw dict vs full model)
-- Supports complex filtering with `WHERE` clauses
-
-Benefits:
-- 50-90% payload reduction possible
-- Better performance (PostgreSQL query optimization)
-- Reduced network bandwidth
-- Flexible client-side field selection
-
-## 🔐 Access Control
-
-### Roles Implemented
-- `role_inventory_user` - Create adjustments/stock takes
-- `role_inventory_approver` - Approve adjustments
-- `role_audit_user` - View-only access
-
-### Permissions Matrix
-| Role | Create | Approve | View |
-|------|--------|---------|------|
-| inventory_user | ✅ | ❌ | ✅ |
-| inventory_approver | ✅ | ✅ | ✅ |
-| audit_user | ❌ | ❌ | ✅ |
-
-## 🧪 Error Handling
-
-### Validation Errors
-```json
-{
-  "error": "INVALID_ADJUSTMENT",
-  "message": "Adjustment qty exceeds available stock"
-}
-```
-
-### Authorization Errors
-```json
-{
-  "error": "ACCESS_DENIED", 
-  "message": "Approval role required"
-}
-```
-
-## 📈 Key Features
-
-### ✅ Implemented
-- Complete REST APIs with FastAPI
-- Pydantic schemas with validation
-- Service-layer business logic
-- MongoDB integration
-- Ledger posting logic
-- Stock snapshot updates
-- Role-based access control
-- Projection list support
-- Comprehensive error handling
-- Audit trail maintenance
-
-### ❌ Explicitly Excluded (Per Spec)
-- Pricing impact calculations
-- Accounting entries
-- Inventory valuation
-- Automatic approvals
-- Direct stock updates
-
-## 🚀 Integration
-
-### Main App Integration
-- Routers registered in `main.py`
-- Collections added to constants
-- Roles added to access control
-- All imports properly configured
-
-### Database Schema
-- **PostgreSQL tables** following PO/GRN pattern
-- **UUID primary keys** for distributed system compatibility
-- **Foreign key relationships** for data integrity
-- **SQLAlchemy ORM** for type safety and migrations
-- **ACID transactions** for consistency
-- **Concurrent operations** with PostgreSQL locking
-
-## 📝 Usage Examples
-
-### Create Stock Adjustment
-```json
-POST /inventory/adjustments/
-{
-  "merchant_id": "merchant_123",
-  "location_id": "location_456", 
-  "sku": "SKU001",
-  "batch_no": "BATCH001",
-  "adj_type": "damage",
-  "qty": 5,
-  "reason": "Damaged during handling",
-  "created_by": "user_123"
-}
-```
-
-### Record Stock Take
-```json
-POST /inventory/stock-take/
-{
-  "merchant_id": "merchant_123",
-  "location_id": "location_456",
-  "sku": "SKU001", 
-  "batch_no": "BATCH001",
-  "system_qty": 100,
-  "physical_qty": 95,
-  "created_by": "user_123"
-}
-```
-
-## ✅ Validation Status
-
-All Python files compile successfully with PostgreSQL implementation:
-- ✅ **PostgreSQL models** compile without errors
-- ✅ **SQLAlchemy schemas** validate correctly  
-- ✅ **Services** implement PostgreSQL business logic
-- ✅ **Controllers** expose proper endpoints
-- ✅ **Main app integration** with table creation
-- ✅ **Database migrations** ready for deployment
-
-## 🎯 Deliverables Completed
-
-- ✅ REST APIs with proper HTTP methods
-- ✅ Pydantic schemas with validation
-- ✅ Service-layer business logic
-- ✅ Ledger posting mechanisms
-- ✅ Stock snapshot updaters
-- ✅ Unit-testable code structure
-- ✅ Role-based access control
-- ✅ Projection list support
-- ✅ Comprehensive error handling
-
-## 🔄 Migration Summary
-
-**Successfully migrated from MongoDB to PostgreSQL:**
-- ✅ Replaced MongoDB collections with PostgreSQL tables
-- ✅ Updated services to use SQLAlchemy async sessions
-- ✅ Maintained exact same API contracts
-- ✅ Preserved all business logic and validation rules
-- ✅ Enhanced with PostgreSQL constraints and relationships
-- ✅ Follows established PO/GRN PostgreSQL patterns
-
-The implementation is **production-ready** and follows all specified requirements for ledger integrity and auditability using **PostgreSQL ACID transactions** and **relational data integrity**.

docs/implementation-summaries/INVENTORY_MIGRATION_SUMMARY.md

@@ -1,190 +0,0 @@
-# Inventory Migration Summary
-
-## Migration Completed: December 19, 2025
-
-### Overview
-Successfully added `inventory` JSONB column to PostgreSQL `trans.catalogue_ref` table and migrated all inventory data from MongoDB.
-
-## Database Status
-
-### MongoDB
-- **Total Catalogues**: 50
-- **With Inventory Data**: 50 (100%)
-- **Structure**: Multi-level inventory (ncnf, cnf, distributor, retail)
-- **Status**: ✅ Complete
-
-### PostgreSQL
-- **Total Catalogues**: 50
-- **With Inventory Data**: 50 (100%)
-- **Column Type**: JSONB
-- **Index**: GIN index on inventory column
-- **Status**: ✅ Complete
-
-## Migration Details
-
-### Schema Changes
-```sql
--- Added inventory column
-ALTER TABLE trans.catalogue_ref 
-ADD COLUMN inventory JSONB;
-
--- Added GIN index for fast JSON queries
-CREATE INDEX idx_catalogue_ref_inventory 
-ON trans.catalogue_ref USING GIN (inventory);
-
--- Added documentation
-COMMENT ON COLUMN trans.catalogue_ref.inventory IS 
-'Multi-level inventory configuration with ncnf, cnf, distributor, and retail levels';
-```
-
-### Data Structure
-```json
-{
-  "unit": "PCS",
-  "levels": {
-    "ncnf": {
-      "reorder_level": 500,
-      "reorder_quantity": 1000,
-      "safety_stock": 200,
-      "lead_time_days": 10,
-      "max_stock_level": 5000
-    },
-    "cnf": {
-      "reorder_level": 200,
-      "reorder_quantity": 500,
-      "safety_stock": 100,
-      "lead_time_days": 7,
-      "max_stock_level": 2000
-    },
-    "distributor": {
-      "reorder_level": 50,
-      "reorder_quantity": 100,
-      "safety_stock": 20,
-      "lead_time_days": 5,
-      "max_stock_level": 500
-    },
-    "retail": {
-      "reorder_level": 10,
-      "reorder_quantity": 20,
-      "safety_stock": 5,
-      "lead_time_days": 3,
-      "max_stock_level": 100
-    }
-  }
-}
-```
-
-## JSONB Query Examples
-
-### Basic Queries
-```sql
--- Get unit type
-SELECT catalogue_code, inventory->>'unit' as unit
-FROM trans.catalogue_ref 
-WHERE inventory->>'unit' = 'PCS';
-
--- Get retail reorder level
-SELECT catalogue_code, 
-       inventory->'levels'->'retail'->>'reorder_level' as retail_reorder
-FROM trans.catalogue_ref 
-WHERE inventory->'levels'->'retail' IS NOT NULL;
-
--- Filter by inventory level
-SELECT catalogue_code, catalogue_name
-FROM trans.catalogue_ref 
-WHERE (inventory->'levels'->'retail'->>'reorder_level')::int > 10;
-```
-
-### Complex Queries
-```sql
--- Get all catalogues with low retail stock levels
-SELECT catalogue_code, catalogue_name,
-       inventory->'levels'->'retail'->>'reorder_level' as reorder,
-       inventory->'levels'->'retail'->>'max_stock_level' as max_stock
-FROM trans.catalogue_ref 
-WHERE (inventory->'levels'->'retail'->>'reorder_level')::int < 15
-  AND 'company_cuatro_beauty_ltd' = ANY(merchant_id);
-
--- Check inventory configuration completeness
-SELECT catalogue_code,
-       jsonb_object_keys(inventory->'levels') as level_name
-FROM trans.catalogue_ref 
-WHERE inventory IS NOT NULL;
-```
-
-## Performance Benefits
-
-### GIN Index
-- **Fast JSON queries**: O(log n) lookup time
-- **Efficient filtering**: On nested JSON properties
-- **Optimized storage**: JSONB binary format
-
-### Query Performance
-- Basic JSON queries: ~1-5ms
-- Complex nested queries: ~5-15ms
-- Full table scans avoided with GIN index
-
-## Migration Statistics
-
-- **Records Migrated**: 50/50 (100%)
-- **Failed Migrations**: 0
-- **Data Integrity**: ✅ Perfect
-- **Sync Status**: ✅ MongoDB ↔ PostgreSQL
-
-## Files Created
-
-1. `migration_add_inventory_column.sql` - SQL migration script
-2. `migration_add_inventory_column.py` - Python migration script
-3. `simple_verification.py` - Verification script
-4. `INVENTORY_MIGRATION_SUMMARY.md` - This document
-
-## Next Steps
-
-### Immediate
-- ✅ Inventory data available in PostgreSQL
-- ✅ Fast JSONB queries enabled
-- ✅ Ready for inventory management features
-
-### Future Enhancements
-- Add inventory tracking endpoints
-- Implement stock level alerts
-- Create inventory reports
-- Build reorder automation
-
-## Verification Commands
-
-```bash
-# Check MongoDB count
-python3 -c "
-import asyncio
-from motor.motor_asyncio import AsyncIOMotorClient
-from dotenv import load_dotenv
-import os
-
-async def check():
-    load_dotenv()
-    client = AsyncIOMotorClient(os.getenv('MONGODB_URI'))
-    db = client[os.getenv('MONGODB_DB_NAME', 'cuatrolabs')]
-    count = await db.catalogues.count_documents({'merchant_id': 'company_cuatro_beauty_ltd'})
-    print(f'MongoDB: {count} catalogues')
-    client.close()
-
-asyncio.run(check())
-"
-
-# Run verification script
-python3 simple_verification.py
-```
-
-## Success Criteria
-
-- [x] Inventory column added to PostgreSQL
-- [x] GIN index created successfully
-- [x] All 50 records migrated
-- [x] Data integrity verified
-- [x] JSONB queries working
-- [x] MongoDB-PostgreSQL sync maintained
-
-## Status: ✅ COMPLETE
-
-Migration completed successfully with 100% data integrity and full JSONB query support.

docs/implementation-summaries/MERCHANT_API_SUMMARY.md

@@ -1,135 +0,0 @@
-# Merchant API - Complete Endpoint Summary
-
-## Base URL: `/api/v1`
-
-## ✅ MERCHANT CORE (CRUD + VIEW)
-
-| Method | Endpoint | Purpose | Status |
-|--------|----------|---------|--------|
-| POST | `/merchants` | Create merchant (Draft) | ✅ Implemented |
-| GET | `/merchants/{merchant_id}` | View merchant profile | ✅ Implemented |
-| PUT | `/merchants/{merchant_id}` | Update merchant profile | ✅ Implemented |
-| POST | `/merchants/list` | List merchants (filters + projection) | ✅ Implemented |
-| DELETE | `/merchants/{merchant_id}` | Soft delete merchant | ✅ Implemented |
-| GET | `/merchants/{merchant_id}/children` | Get child merchants | ✅ Implemented |
-| GET | `/merchants/{merchant_id}/hierarchy` | Get merchant hierarchy | ✅ Implemented |
-
-## ✅ KYC & COMPLIANCE
-
-| Method | Endpoint | Purpose | Status |
-|--------|----------|---------|--------|
-| POST | `/merchants/{merchant_id}/kyc` | Upload KYC | ✅ **NEW** |
-| PUT | `/merchants/{merchant_id}/kyc` | Update KYC | ✅ **NEW** |
-| POST | `/merchants/{merchant_id}/submit` | Submit for verification | ✅ **NEW** |
-| POST | `/merchants/{merchant_id}/approve` | Approve merchant | ✅ **NEW** |
-| POST | `/merchants/{merchant_id}/reject` | Reject merchant | ✅ **NEW** |
-
-## ✅ BULK OPERATIONS
-
-| Method | Endpoint | Purpose | Status |
-|--------|----------|---------|--------|
-| POST | `/merchants/bulk-upload` | Bulk merchant creation | ✅ **NEW** |
-
-## Sample Merchant Document
-
-```json
-{
-  "_id": {"$oid": "6929fd805b6e93f6f31a6ef7"},
-  "merchant_id": "mch_Tl6fTpA4Bbzv7rAFLyDwgA",
-  "merchant_type": "ncnf",
-  "parent_merchant_id": null,
-  "merchant_code": "ncnf-INDIA-001",
-  "merchant_name": "National Distribution Center India",
-  "contact": {
-    "phone": "+919876543210",
-    "email": "national@distribution.com",
-    "address_line1": "Plot 123, Industrial Area",
-    "address_line2": "Phase 1",
-    "city": "Mumbai",
-    "state": "Maharashtra",
-    "pincode": "400001",
-    "country": "India"
-  },
-  "geo_location": null,
-  "kyc": {
-    "gst_number": "27AAPFU0939F1ZV",
-    "pan_number": "AAPFU0939F",
-    "business_certificate_url": "https://storage.example.com/ncnf_cert.pdf",
-    "bank_account_number": "1234567890123",
-    "bank_ifsc": "HDFC0001234",
-    "cancelled_cheque_url": "https://storage.example.com/ncnf_cheque.jpg"
-  },
-  "settings": {
-    "pricing_inherited": false,
-    "inventory_inherited": false,
-    "auto_allocate_stock": true,
-    "allowed_payment_modes": ["PREPAID", "COD"],
-    "credit_limit": 10000000
-  },
-  "status": "active",
-  "created_by": "system_admin",
-  "created_at": "2025-11-28T19:52:32.917061",
-  "updated_at": "2025-11-28T19:52:54.820663",
-  "metadata": {
-    "approved_by": "admin_001",
-    "approved_at": "2025-11-28T20:00:00.000000",
-    "approval_reason": "All documents verified"
-  }
-}
-```
-
-## Key Features
-
-### 1. Projection List Support
-All list endpoints support field projection for optimized responses:
-
-```json
-{
-  "projection_list": ["merchant_id", "merchant_name", "merchant_type", "status"]
-}
-```
-
-### 2. Merchant Status Workflow
-```
-draft → submitted → active
-  ↓         ↓
-rejected  rejected
-```
-
-### 3. KYC Requirements
-
-**cnf/distributor:**
-- GST Number ✓
-- PAN Number ✓
-- Bank Account ✓
-- Bank IFSC ✓
-
-**retail:**
-- PAN Number ✓ (minimum)
-- GST (optional)
-- Bank details (optional)
-
-### 4. Bulk Upload
-- Process multiple merchants in one request
-- Skip errors option for partial success
-- Detailed results for each merchant
-
-## Testing
-
-```bash
-# Test KYC & Workflow endpoints
-./test_merchant_kyc_workflow.sh
-```
-
-## Documentation
-
-- **Full API Docs:** `MERCHANT_KYC_WORKFLOW.md`
-- **API Standards:** `API_STANDARDS.md`
-- **Projection Guide:** `PROJECTION_LIST_IMPLEMENTATION.md`
-
-## Implementation Files
-
-- **Router:** `app/merchants/controllers/router.py`
-- **Service:** `app/merchants/services/service.py`
-- **Schemas:** `app/merchants/schemas/schema.py`
-- **Model:** `app/merchants/models/model.py`

docs/implementation-summaries/MERCHANT_CATALOGUE_LIST_IMPLEMENTATION.md

@@ -1,316 +0,0 @@
-# Merchant Catalogue List Implementation
-
-## Overview
-
-The Merchant Catalogue List feature provides a high-performance API endpoint to fetch catalogue items with real-time inventory data for a specific merchant. This implementation joins PostgreSQL `catalogue_ref` and `scm_stock` tables to provide comprehensive product and inventory information.
-
-## API Endpoint
-
-```
-POST /catalogue/merchant-catalogue/list
-```
-
-## Features
-
-### ✅ **API Standards Compliance**
-- Follows mandatory projection list support pattern
-- POST method for list operations
-- Standardized request/response format
-- Consistent error handling
-
-### ✅ **Security & Data Isolation**
-- Merchant-level data filtering using JWT `merchant_id`
-- Prevents cross-merchant data access
-- Secure authentication required
-
-### ✅ **Performance Optimization**
-- PostgreSQL native queries with JOINs
-- Optional projection list (50-90% payload reduction)
-- Efficient pagination with skip/limit
-- Stock quantity aggregation across locations
-
-### ✅ **Flexible Filtering**
-- Status filtering (Active/Inactive)
-- Catalogue type filtering (Product/Service)
-- Name-based search (ILIKE pattern matching)
-- SKU-based search
-- Inventory tracking filter
-
-## Request Schema
-
-```python
-class MerchantCatalogueListFilter(BaseModel):
-    filters: Optional[Dict[str, Any]] = Field(None, description="Filter criteria")
-    skip: Optional[int] = Field(0, ge=0, description="Number of records to skip")
-    limit: Optional[int] = Field(10, ge=1, le=100, description="Maximum records to return")
-    catalogue_type: Optional[str] = Field(None, description="Product/Service filter")
-    projection_list: Optional[List[str]] = Field(
-        None, 
-        description="List of fields to include in response"
-    )
-```
-
-## Response Format
-
-```json
-{
-  "data": [
-    {
-      "catalogue_id": "cat-001",
-      "catalogue_code": "HAIR-SHAMPOO-001",
-      "catalogue_type": "Product",
-      "catalogue_name": "Premium Hair Shampoo",
-      "sku": "SKU-SHAMPOO-001",
-      "barcode_number": "1234567890123",
-      "hsn_code": "33051000",
-      "gst_rate": 18.0,
-      "mrp": 299.00,
-      "base_price": 250.00,
-      "track_inventory": true,
-      "batch_managed": false,
-      "status": "Active",
-      "created_at": "2024-01-15T10:30:00Z",
-      "qty_on_hand": 150.0,
-      "qty_reserved": 15.0,
-      "qty_available": 135.0
-    }
-  ],
-  "count": 25,
-  "status": "Success",
-  "skip": 0,
-  "limit": 10
-}
-```
-
-## Usage Examples
-
-### Basic Request
-```bash
-curl -X POST http://localhost:8000/catalogue/merchant-catalogue/list \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
-  -d '{
-    "filters": {},
-    "skip": 0,
-    "limit": 10
-  }'
-```
-
-### Optimized with Projection List
-```bash
-curl -X POST http://localhost:8000/catalogue/merchant-catalogue/list \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
-  -d '{
-    "projection_list": ["catalogue_id", "catalogue_name", "sku", "qty_on_hand"],
-    "limit": 20
-  }'
-```
-
-### Filtered Request
-```bash
-curl -X POST http://localhost:8000/catalogue/merchant-catalogue/list \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
-  -d '{
-    "filters": {
-      "status": "Active",
-      "catalogue_name": "Hair"
-    },
-    "catalogue_type": "Product",
-    "skip": 0,
-    "limit": 10
-  }'
-```
-
-## Database Schema
-
-### Tables Involved
-
-#### `trans.catalogue_ref`
-- Primary catalogue information
-- Merchant associations via `merchant_id` array
-- Product metadata (SKU, pricing, tax info)
-
-#### `scm_stock`
-- Real-time inventory data
-- Location-wise stock quantities
-- Batch and expiry information
-
-### SQL Query Structure
-```sql
-SELECT 
-    cr.catalogue_id, cr.catalogue_name, cr.sku,
-    COALESCE(SUM(s.qty_on_hand), 0) as qty_on_hand,
-    COALESCE(SUM(s.qty_reserved), 0) as qty_reserved,
-    COALESCE(SUM(s.qty_available), 0) as qty_available
-FROM trans.catalogue_ref cr
-LEFT JOIN scm_stock s ON cr.sku = s.sku AND s.merchant_id = :merchant_id
-WHERE :merchant_id = ANY(cr.merchant_id)
-GROUP BY cr.catalogue_id, cr.catalogue_name, cr.sku
-ORDER BY cr.created_at DESC
-LIMIT :limit OFFSET :skip
-```
-
-## Implementation Details
-
-### Controller Layer
-- **File**: `app/catalogues/controllers/router.py`
-- **Method**: `merchant_catalogue_list()`
-- **Route**: `POST /catalogue/merchant-catalogue/list`
-
-### Service Layer
-- **File**: `app/catalogues/services/service.py`
-- **Method**: `list_merchant_catalogue_items()`
-- **Features**: PostgreSQL JOIN, aggregation, projection
-
-### Schema Layer
-- **File**: `app/catalogues/schemas/schema.py`
-- **Class**: `MerchantCatalogueListFilter`
-- **Validation**: Pydantic with field constraints
-
-## Available Filters
-
-| Filter | Type | Description | Example |
-|--------|------|-------------|---------|
-| `status` | string | Active/Inactive | `{"status": "Active"}` |
-| `catalogue_name` | string | Name search (ILIKE) | `{"catalogue_name": "Hair"}` |
-| `sku` | string | SKU search (ILIKE) | `{"sku": "SHAMPOO"}` |
-| `track_inventory` | boolean | Inventory tracking flag | `{"track_inventory": true}` |
-
-## Projection Fields
-
-Common projection combinations for performance:
-
-### Minimal (List View)
-```json
-["catalogue_id", "catalogue_name", "sku", "status"]
-```
-
-### With Inventory
-```json
-["catalogue_id", "catalogue_name", "sku", "qty_on_hand", "qty_available"]
-```
-
-### With Pricing
-```json
-["catalogue_id", "catalogue_name", "sku", "mrp", "base_price", "gst_rate"]
-```
-
-### Full Product Info
-```json
-[
-  "catalogue_id", "catalogue_name", "sku", "catalogue_type",
-  "mrp", "base_price", "qty_on_hand", "qty_available", "status"
-]
-```
-
-## Testing
-
-### Test Scripts Available
-
-1. **Database Service Tests**: `test_merchant_catalogue_list.py`
-   - Tests service layer functionality
-   - Database integration testing
-   - Projection and filtering validation
-
-2. **HTTP API Tests**: `test_merchant_catalogue_api.py`
-   - End-to-end API testing
-   - HTTP status code validation
-   - Response format verification
-
-3. **curl Tests**: `test_merchant_catalogue_curl.sh`
-   - Manual API testing
-   - Example request formats
-   - Error handling demonstration
-
-### Running Tests
-
-```bash
-# Run all tests
-./run_merchant_catalogue_tests.sh
-
-# Run specific tests
-python3 test_merchant_catalogue_list.py
-python3 test_merchant_catalogue_api.py
-./test_merchant_catalogue_curl.sh
-```
-
-## Performance Benefits
-
-### Projection List Impact
-- **Without projection**: Full object ~2KB per item
-- **With projection**: Minimal fields ~200B per item
-- **Savings**: Up to 90% payload reduction
-
-### Database Optimization
-- Single JOIN query vs multiple round trips
-- PostgreSQL native aggregation
-- Efficient pagination with LIMIT/OFFSET
-
-## Error Handling
-
-### Common Error Scenarios
-
-| Status Code | Scenario | Response |
-|-------------|----------|----------|
-| 400 | Missing merchant_id | `{"detail": "Merchant ID is required"}` |
-| 401 | Invalid JWT token | `{"detail": "Authentication required"}` |
-| 422 | Invalid payload | `{"detail": "Validation error"}` |
-| 500 | Database error | `{"detail": "Internal server error"}` |
-
-## Security Considerations
-
-1. **Merchant Isolation**: Data filtered by JWT `merchant_id`
-2. **Authentication**: JWT token required for all requests
-3. **Authorization**: Only merchant's own data accessible
-4. **Input Validation**: All inputs validated via Pydantic schemas
-
-## Future Enhancements
-
-### Potential Improvements
-- [ ] Redis caching for frequently accessed data
-- [ ] Elasticsearch integration for advanced search
-- [ ] Real-time inventory updates via WebSocket
-- [ ] Bulk operations support
-- [ ] Export functionality (CSV/Excel)
-
-### Performance Monitoring
-- [ ] Query execution time logging
-- [ ] Payload size monitoring
-- [ ] Cache hit rate tracking
-- [ ] API usage analytics
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Empty Results**
-   - Check merchant_id in JWT token
-   - Verify catalogue_ref has merchant association
-   - Check filter criteria
-
-2. **Performance Issues**
-   - Use projection_list for large datasets
-   - Implement appropriate database indexes
-   - Monitor query execution plans
-
-3. **Authentication Errors**
-   - Verify JWT token format
-   - Check token expiration
-   - Validate merchant_id claim
-
-## Related Documentation
-
-- [API Standards](./API_STANDARDS.md)
-- [Projection List Implementation](./PROJECTION_LIST_IMPLEMENTATION.md)
-- [Authentication Guide](./AUTHENTICATION.md)
-- [Database Schema](./DATABASE_SCHEMA.md)
-
----
-
-**Implementation Status**: ✅ Complete and Ready for Production
-
-**Last Updated**: December 2024
-
-**Maintainer**: SCM Development Team

docs/implementation-summaries/PRICING_LEVELS_COMPLETE_SOLUTION.md

@@ -1,295 +0,0 @@
-# Complete Pricing Levels Solution
-
-## Overview
-
-This document describes the complete solution for handling pricing_levels in SCM catalogues, including migration of existing records and automatic generation for catalogues without pricing_levels.
-
-## Problem Statement
-
-Some catalogues in the SCM system don't have `pricing_levels` data, which is needed for multi-level pricing support. The solution generates pricing_levels based on MRP with specific margins:
-
-- **ncnf**: MRP - 12%
-- **cnf**: MRP - 6%
-- **distributor**: MRP - 10%
-- **retail**: MRP - 20%
-
-## Solution Components
-
-### 1. Migration Scripts
-
-#### A. Generate Missing Pricing Levels (`migration_generate_missing_pricing_levels.py`)
-- Finds catalogues without pricing_levels but with MRP
-- Generates pricing_levels using the specified margin structure
-- Updates MongoDB documents with the new pricing data
-- Includes preview mode and comprehensive logging
-
-**Usage:**
-```bash
-# Preview what would be updated
-python migration_generate_missing_pricing_levels.py --preview
-
-# Execute the migration
-python migration_generate_missing_pricing_levels.py
-```
-
-#### B. Add PostgreSQL Column (`migration_add_pricing_levels_column.py`)
-- Adds `pricing_levels` JSON column to PostgreSQL tables
-- Creates performance indexes for JSON queries
-- Handles existing table structures gracefully
-
-**Usage:**
-```bash
-python migration_add_pricing_levels_column.py
-```
-
-### 2. Enhanced Sync Handler
-
-The sync handler (`app/sync/catalogues/handler.py`) now includes:
-
-#### Automatic Generation
-- Detects catalogues without pricing_levels during sync
-- Generates pricing_levels on-the-fly based on available MRP
-- Logs generation activities for monitoring
-
-#### Pricing Calculation Logic
-```python
-# Margin structure
-PRICING_MARGINS = {
-    "ncnf": {"discount_pct": 12, "trade_margin": 15, "retail_margin": 25, "max_discount_pct": 5},
-    "cnf": {"discount_pct": 6, "trade_margin": 18, "retail_margin": 28, "max_discount_pct": 8},
-    "distributor": {"discount_pct": 10, "trade_margin": 20, "retail_margin": 30, "max_discount_pct": 15},
-    "retail": {"discount_pct": 20, "trade_margin": 25, "retail_margin": 35, "max_discount_pct": 20}
-}
-```
-
-#### Price Calculation Formula
-```python
-selling_price = mrp * (100 - discount_pct) / 100
-purchase_price = selling_price * 0.70  # 70% of selling price
-retail_price = selling_price
-```
-
-### 3. Validation Scripts
-
-#### A. Migration Validation (`validate_pricing_levels_migration.py`)
-- Validates pricing_levels structure and calculations
-- Checks that all required levels are present
-- Verifies price relationships and calculations
-- Shows sample pricing_levels for review
-
-**Usage:**
-```bash
-# Full validation
-python validate_pricing_levels_migration.py
-
-# Show samples only
-python validate_pricing_levels_migration.py --samples
-```
-
-#### B. Complete Flow Test (`test_complete_pricing_levels_flow.py`)
-- Tests the entire pricing_levels flow end-to-end
-- Validates sync handler generation
-- Verifies PostgreSQL storage
-- Tests different catalogue scenarios
-
-**Usage:**
-```bash
-python test_complete_pricing_levels_flow.py
-```
-
-### 4. Database Schema Updates
-
-#### PostgreSQL Table Structure
-```sql
-ALTER TABLE trans.catalogue_ref 
-ADD COLUMN pricing_levels JSON;
-
--- Performance indexes
-CREATE INDEX idx_catalogue_ref_pricing_levels_currency 
-ON trans.catalogue_ref USING GIN ((pricing_levels->>'currency'));
-
-CREATE INDEX idx_catalogue_ref_pricing_levels_mrp 
-ON trans.catalogue_ref USING BTREE (CAST(pricing_levels->>'mrp' AS NUMERIC));
-```
-
-#### SQLAlchemy Model Update
-```python
-class CatalogueRef(Base):
-    # ... existing columns ...
-    pricing_levels = Column(JSON)
-```
-
-## Generated Pricing Levels Structure
-
-```json
-{
-  "currency": "INR",
-  "mrp": 500,
-  "levels": {
-    "ncnf": {
-      "purchase_price": 308.00,
-      "trade_margin": 15,
-      "selling_price": 440.00,
-      "retail_price": 440.00,
-      "retail_margin": 25,
-      "max_discount_pct": 5
-    },
-    "cnf": {
-      "purchase_price": 329.00,
-      "trade_margin": 18,
-      "selling_price": 470.00,
-      "retail_price": 470.00,
-      "retail_margin": 28,
-      "max_discount_pct": 8
-    },
-    "distributor": {
-      "purchase_price": 315.00,
-      "trade_margin": 20,
-      "selling_price": 450.00,
-      "retail_price": 450.00,
-      "retail_margin": 30,
-      "max_discount_pct": 15
-    },
-    "retail": {
-      "purchase_price": 280.00,
-      "trade_margin": 25,
-      "selling_price": 400.00,
-      "retail_price": 400.00,
-      "retail_margin": 35,
-      "max_discount_pct": 20
-    }
-  }
-}
-```
-
-## Deployment Steps
-
-### 1. Pre-Migration
-```bash
-# 1. Backup databases
-mongodump --db scm_db --collection catalogues
-pg_dump -t trans.catalogue_ref > catalogue_ref_backup.sql
-
-# 2. Preview migration impact
-python migration_generate_missing_pricing_levels.py --preview
-```
-
-### 2. Execute Migration
-```bash
-# 1. Add PostgreSQL column
-python migration_add_pricing_levels_column.py
-
-# 2. Generate missing pricing_levels in MongoDB
-python migration_generate_missing_pricing_levels.py
-
-# 3. Validate results
-python validate_pricing_levels_migration.py
-```
-
-### 3. Deploy Code
-```bash
-# Deploy updated sync handler and models
-# The sync process will now automatically handle pricing_levels
-```
-
-### 4. Post-Migration Validation
-```bash
-# Run complete flow test
-python test_complete_pricing_levels_flow.py
-
-# Check sync logs for automatic generation
-tail -f /var/log/scm/sync.log | grep "pricing_levels"
-```
-
-## Monitoring and Maintenance
-
-### Log Monitoring
-The system logs pricing_levels generation activities:
-```
-INFO: Generated pricing_levels for catalogue ABC123 with MRP ₹500
-DEBUG: Catalogue upserted to PostgreSQL with pricing_levels
-```
-
-### Performance Queries
-```sql
--- Count catalogues with pricing_levels
-SELECT COUNT(1) FROM trans.catalogue_ref WHERE pricing_levels IS NOT NULL;
-
--- Find catalogues by currency
-SELECT catalogue_id, catalogue_name 
-FROM trans.catalogue_ref 
-WHERE pricing_levels->>'currency' = 'INR';
-
--- Query by MRP range
-SELECT catalogue_id, catalogue_name, pricing_levels->>'mrp' as mrp
-FROM trans.catalogue_ref 
-WHERE CAST(pricing_levels->>'mrp' AS NUMERIC) BETWEEN 100 AND 500;
-```
-
-### Health Checks
-```bash
-# Regular validation
-python validate_pricing_levels_migration.py
-
-# Check for catalogues without pricing_levels
-python -c "
-import asyncio
-from migration_generate_missing_pricing_levels import find_catalogues_without_pricing_levels
-asyncio.run(find_catalogues_without_pricing_levels())
-"
-```
-
-## Benefits
-
-1. **Automatic Generation**: No manual intervention needed for new catalogues
-2. **Consistent Pricing**: Standardized margin structure across all levels
-3. **Performance**: JSON indexes enable fast pricing queries
-4. **Backward Compatibility**: Existing catalogues continue to work
-5. **Monitoring**: Comprehensive logging for tracking generation activities
-6. **Validation**: Built-in validation ensures data integrity
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Missing MRP**: Catalogues without MRP cannot generate pricing_levels
-   - Solution: Ensure MRP is set in either `pricing.mrp` or top-level `mrp`
-
-2. **Invalid JSON**: Corrupted pricing_levels data
-   - Solution: Re-run migration or use validation script to identify issues
-
-3. **Sync Failures**: PostgreSQL column missing
-   - Solution: Run `migration_add_pricing_levels_column.py`
-
-### Recovery Procedures
-
-1. **Regenerate Pricing Levels**:
-   ```bash
-   # Remove existing pricing_levels and regenerate
-   python -c "
-   import asyncio
-   from motor.motor_asyncio import AsyncIOMotorClient
-   async def reset():
-       client = AsyncIOMotorClient('mongodb://localhost:27017')
-       db = client.scm_db
-       await db.catalogues.update_many({}, {'$unset': {'pricing_levels': 1}})
-   asyncio.run(reset())
-   "
-   python migration_generate_missing_pricing_levels.py
-   ```
-
-2. **Resync to PostgreSQL**:
-   ```bash
-   # Trigger resync for specific catalogues
-   python -c "
-   # Use sync service to resync catalogues
-   "
-   ```
-
-## Future Enhancements
-
-1. **Dynamic Margins**: Support for merchant-specific margin configurations
-2. **Currency Support**: Multi-currency pricing levels
-3. **Bulk Updates**: API endpoints for bulk pricing updates
-4. **Price History**: Track pricing changes over time
-5. **Validation Rules**: Business rule validation for pricing consistency

docs/implementation-summaries/PRICING_LEVELS_CORRECTED_STRUCTURE.md

@@ -1,232 +0,0 @@
-# Pricing Levels - Corrected Structure
-
-## Overview
-
-This document describes the corrected pricing_levels structure that has been implemented across MongoDB and PostgreSQL.
-
-## Corrected Structure
-
-The pricing_levels now contains only three essential fields per level:
-- `cost_price`: The cost price calculated as MRP minus the discount percentage
-- `trade_margin`: The trade margin percentage for this level
-- `max_discount_pct`: The maximum discount percentage allowed for this level
-
-## JSON Structure
-
-```json
-{
-  "currency": "INR",
-  "mrp": 500,
-  "levels": {
-    "ncnf": {
-      "cost_price": 440.00,
-      "trade_margin": 15,
-      "max_discount_pct": 5
-    },
-    "cnf": {
-      "cost_price": 470.00,
-      "trade_margin": 18,
-      "max_discount_pct": 8
-    },
-    "distributor": {
-      "cost_price": 450.00,
-      "trade_margin": 20,
-      "max_discount_pct": 15
-    },
-    "retail": {
-      "cost_price": 400.00,
-      "trade_margin": 25,
-      "max_discount_pct": 20
-    }
-  }
-}
-```
-
-## Pricing Level Margins
-
-| Level | Discount from MRP | Trade Margin | Max Discount |
-|-------|------------------|--------------|--------------|
-| ncnf | 12% | 15% | 5% |
-| cnf | 6% | 18% | 8% |
-| distributor | 10% | 20% | 15% |
-| retail | 20% | 25% | 20% |
-
-## Calculation Formula
-
-```
-cost_price = MRP × (100 - discount_pct) / 100
-```
-
-### Examples
-
-**Example 1: MRP = ₹500**
-- ncnf: ₹500 × (100 - 12) / 100 = ₹440.00
-- cnf: ₹500 × (100 - 6) / 100 = ₹470.00
-- distributor: ₹500 × (100 - 10) / 100 = ₹450.00
-- retail: ₹500 × (100 - 20) / 100 = ₹400.00
-
-**Example 2: MRP = ₹299**
-- ncnf: ₹299 × (100 - 12) / 100 = ₹263.12
-- cnf: ₹299 × (100 - 6) / 100 = ₹281.06
-- distributor: ₹299 × (100 - 10) / 100 = ₹269.10
-- retail: ₹299 × (100 - 20) / 100 = ₹239.20
-
-## Implementation Details
-
-### MongoDB Collection: `catalogues`
-
-The pricing_levels field is stored as a nested document within each catalogue:
-
-```javascript
-{
-  "catalogue_id": "CAT-001",
-  "catalogue_name": "Sample Product",
-  "pricing_levels": {
-    "currency": "INR",
-    "mrp": 500,
-    "levels": {
-      "ncnf": {
-        "cost_price": 440.00,
-        "trade_margin": 15,
-        "max_discount_pct": 5
-      },
-      // ... other levels
-    }
-  }
-}
-```
-
-### PostgreSQL Table: `trans.catalogue_ref`
-
-The pricing_levels field is stored as JSON:
-
-```sql
-CREATE TABLE trans.catalogue_ref (
-    catalogue_id TEXT PRIMARY KEY,
-    -- ... other columns ...
-    pricing_levels JSON
-);
-```
-
-## Schema Definition (Pydantic)
-
-```python
-class PricingLevel(BaseModel):
-    cost_price: Optional[float] = Field(None, ge=0, description="Cost price for this level (MRP - discount%)")
-    trade_margin: Optional[float] = Field(None, ge=0, description="Trade margin percentage")
-    max_discount_pct: Optional[float] = Field(None, ge=0, le=100, description="Maximum discount percentage allowed")
-
-class PricingLevels(BaseModel):
-    currency: str = Field("INR", description="Currency code")
-    mrp: Optional[float] = Field(None, ge=0, description="Maximum Retail Price")
-    levels: Optional[Dict[str, PricingLevel]] = Field(None, description="Pricing levels (ncnf, cnf, distributor, retail)")
-```
-
-## Migration Status
-
-✅ **Completed:**
-1. PostgreSQL table `trans.catalogue_ref` created with `pricing_levels` JSON column
-2. MongoDB migration script updated to generate corrected structure
-3. Sync handler updated to automatically generate pricing_levels with corrected structure
-4. Schema definitions updated to reflect corrected fields
-5. Validation scripts updated to check corrected structure
-
-## Usage Examples
-
-### Query by Cost Price Range (PostgreSQL)
-
-```sql
--- Find catalogues where retail cost price is between 200 and 400
-SELECT catalogue_id, catalogue_name, pricing_levels
-FROM trans.catalogue_ref
-WHERE CAST(pricing_levels->'levels'->'retail'->>'cost_price' AS NUMERIC) BETWEEN 200 AND 400;
-```
-
-### Query by Currency (PostgreSQL)
-
-```sql
--- Find all catalogues with INR pricing
-SELECT catalogue_id, catalogue_name, pricing_levels->>'mrp' as mrp
-FROM trans.catalogue_ref
-WHERE pricing_levels->>'currency' = 'INR';
-```
-
-### Query in MongoDB
-
-```javascript
-// Find catalogues where ncnf cost price is less than 300
-db.catalogues.find({
-  "pricing_levels.levels.ncnf.cost_price": { $lt: 300 }
-})
-
-// Find catalogues with specific trade margin
-db.catalogues.find({
-  "pricing_levels.levels.distributor.trade_margin": 20
-})
-```
-
-## API Response Example
-
-```json
-{
-  "status": "success",
-  "data": {
-    "catalogue_id": "CAT-001",
-    "catalogue_name": "Premium Hair Shampoo",
-    "catalogue_type": "Product",
-    "pricing_levels": {
-      "currency": "INR",
-      "mrp": 399,
-      "levels": {
-        "ncnf": {
-          "cost_price": 351.12,
-          "trade_margin": 15,
-          "max_discount_pct": 5
-        },
-        "cnf": {
-          "cost_price": 375.06,
-          "trade_margin": 18,
-          "max_discount_pct": 8
-        },
-        "distributor": {
-          "cost_price": 359.10,
-          "trade_margin": 20,
-          "max_discount_pct": 15
-        },
-        "retail": {
-          "cost_price": 319.20,
-          "trade_margin": 25,
-          "max_discount_pct": 20
-        }
-      }
-    }
-  }
-}
-```
-
-## Benefits of Corrected Structure
-
-1. **Simplified**: Only essential pricing fields are stored
-2. **Clear Semantics**: `cost_price` clearly indicates the base cost for each level
-3. **Consistent**: Same structure across all pricing levels
-4. **Efficient**: Smaller JSON payload, faster queries
-5. **Maintainable**: Easier to understand and update
-
-## Validation
-
-To validate the pricing_levels structure:
-
-```bash
-# Run validation script
-python validate_pricing_levels_migration.py
-
-# Expected output:
-# ✅ All pricing_levels are valid!
-```
-
-## Notes
-
-- All prices are stored with 2 decimal precision
-- Currency is currently fixed to "INR" but can be extended
-- The sync handler automatically generates pricing_levels for catalogues without them
-- Existing catalogues with old structure should be migrated using the migration script

docs/implementation-summaries/PRICING_LEVELS_SYNC_IMPLEMENTATION.md

@@ -1,187 +0,0 @@
-# Pricing Levels Sync Implementation
-
-## Overview
-
-This implementation ensures that the `pricing_levels` data from MongoDB catalogues is properly stored as JSON in PostgreSQL's `trans.catalogue_ref` table during the sync process.
-
-## Changes Made
-
-### 1. Updated Sync Models (`app/sync/catalogues/models.py`)
-
-Added `pricing_levels` field to the field mapping:
-
-```python
-CATALOGUE_FIELD_MAPPING = {
-    # ... existing fields ...
-    "pricing_levels": "pricing_levels"      # JSON
-}
-```
-
-### 2. Enhanced Sync Handler (`app/sync/catalogues/handler.py`)
-
-#### Added JSON Import
-```python
-import json
-```
-
-#### Updated `extract_nested_fields()` Method
-- Extracts `pricing_levels` as JSON from MongoDB document
-- Falls back to legacy `pricing` for MRP if `pricing_levels` MRP is not available
-- Preserves the complete pricing levels structure
-
-#### Enhanced `transform_field_value()` Method
-- Added special handling for `pricing_levels` field
-- Validates JSON structure
-- Handles string-to-JSON conversion if needed
-- Provides error logging for invalid JSON
-
-#### Updated `upsert_to_postgres()` Method
-- Automatically creates `pricing_levels` JSON column if it doesn't exist
-- Ensures backward compatibility with existing tables
-
-### 3. Updated SQLAlchemy Model (`app/catalogues/models/model.py`)
-
-Added `pricing_levels` column to the `CatalogueRef` model:
-
-```python
-from sqlalchemy import JSON  # Added JSON import
-
-class CatalogueRef(Base):
-    # ... existing columns ...
-    pricing_levels = Column(JSON)
-```
-
-### 4. Migration Scripts
-
-#### Python Migration (`migration_add_pricing_levels_column.py`)
-- Adds `pricing_levels` JSON column to existing tables
-- Creates performance indexes on JSON fields
-- Includes error handling and logging
-
-#### SQL Migration (`migration_add_pricing_levels_column.sql`)
-- Direct SQL commands for adding the column
-- Creates GIN and BTREE indexes for optimal query performance
-- Includes documentation comments
-
-### 5. Test Script (`test_pricing_levels_sync.py`)
-
-Comprehensive test that:
-- Creates test catalogue with pricing_levels in MongoDB
-- Tests the sync process
-- Validates data integrity in PostgreSQL
-- Verifies JSON structure and required fields
-- Cleans up test data
-
-## Pricing Levels Structure
-
-The `pricing_levels` field stores JSON data with this structure:
-
-```json
-{
-  "currency": "INR",
-  "mrp": 399,
-  "levels": {
-    "retail": {
-      "purchase_price": 260,
-      "trade_margin": 20,
-      "selling_price": 299,
-      "retail_price": 349,
-      "retail_margin": 30,
-      "max_discount_pct": 15
-    },
-    "distributor": {
-      "purchase_price": 230,
-      "trade_margin": 25,
-      "selling_price": 279,
-      "retail_price": 349,
-      "retail_margin": 30,
-      "max_discount_pct": 20
-    }
-  }
-}
-```
-
-## Database Indexes
-
-The following indexes are created for optimal query performance:
-
-1. **Currency Index**: `idx_catalogue_ref_pricing_levels_currency`
-   - GIN index on `pricing_levels->>'currency'`
-   - For filtering by currency
-
-2. **MRP Index**: `idx_catalogue_ref_pricing_levels_mrp`
-   - BTREE index on `CAST(pricing_levels->>'mrp' AS NUMERIC)`
-   - For range queries on MRP values
-
-3. **General JSON Index**: `idx_catalogue_ref_pricing_levels_gin`
-   - GIN index on entire `pricing_levels` JSON
-   - For complex JSON queries
-
-## Usage Examples
-
-### Query Catalogues with Specific Currency
-```sql
-SELECT catalogue_id, catalogue_name, pricing_levels
-FROM trans.catalogue_ref
-WHERE pricing_levels->>'currency' = 'INR';
-```
-
-### Query by MRP Range
-```sql
-SELECT catalogue_id, catalogue_name, pricing_levels
-FROM trans.catalogue_ref
-WHERE CAST(pricing_levels->>'mrp' AS NUMERIC) BETWEEN 100 AND 500;
-```
-
-### Query Specific Pricing Level
-```sql
-SELECT catalogue_id, catalogue_name,
-       pricing_levels->'levels'->'retail'->>'selling_price' as retail_price
-FROM trans.catalogue_ref
-WHERE pricing_levels->'levels' ? 'retail';
-```
-
-## Deployment Steps
-
-1. **Run Migration**:
-   ```bash
-   # Python migration
-   python migration_add_pricing_levels_column.py
-   
-   # OR SQL migration
-   psql -d your_database -f migration_add_pricing_levels_column.sql
-   ```
-
-2. **Test Sync Process**:
-   ```bash
-   python test_pricing_levels_sync.py
-   ```
-
-3. **Deploy Updated Code**:
-   - Deploy the updated sync handler and models
-   - Existing sync processes will automatically handle pricing_levels
-
-## Backward Compatibility
-
-- Existing catalogues without `pricing_levels` will continue to work
-- Legacy `pricing` field is still supported for MRP extraction
-- The sync process gracefully handles both old and new pricing structures
-- No breaking changes to existing APIs
-
-## Benefits
-
-1. **Enhanced Pricing Support**: Full support for multi-level pricing structures
-2. **Performance**: JSON indexes enable fast queries on pricing data
-3. **Flexibility**: Easy to add new pricing levels without schema changes
-4. **Data Integrity**: Proper validation and error handling
-5. **Backward Compatibility**: Seamless transition from legacy pricing
-
-## Monitoring
-
-The sync process includes comprehensive logging:
-- Successful pricing_levels extraction and storage
-- JSON validation errors
-- Database operation results
-- Performance metrics
-
-Check logs for entries with `entity_type: catalogue` and `pricing_levels` references.

docs/implementation-summaries/PROJECTION_LIST_IMPLEMENTATION.md

@@ -1,231 +0,0 @@
-# Projection List Implementation for SCM List Endpoints
-
-## Overview
-This document describes the implementation of projection list support for all list/fetch endpoints in the SCM microservice. The projection list feature allows clients to specify which fields they want to receive in the response, reducing payload size and improving performance.
-
-## Implementation Pattern
-
-### Request Schema
-All list request schemas now include an optional `projection_list` field:
-
-```python
-projection_list: Optional[List[str]] = Field(
-    None, 
-    description="List of fields to include in response (e.g., ['field1', 'field2'])"
-)
-```
-
-### Service Layer
-Services use MongoDB projection to fetch only requested fields:
-
-```python
-# Build projection dict for MongoDB
-projection_dict = None
-if projection_list:
-    projection_dict = {field: 1 for field in projection_list}
-    projection_dict["_id"] = 0  # Exclude MongoDB _id
-
-# Query with projection
-cursor = collection.find(query, projection_dict).skip(skip).limit(limit)
-
-# Return raw dict if projection, otherwise return Pydantic model
-if projection_list:
-    return documents  # List[Dict]
-else:
-    return [ResponseModel(**doc) for doc in documents]  # List[ResponseModel]
-```
-
-### Controller Layer
-Controllers pass projection_list to services and handle both dict and model responses:
-
-```python
-result = await Service.list_items(
-    filters=...,
-    projection_list=payload.projection_list
-)
-
-# If projection is used, return raw data
-if payload.projection_list:
-    return result
-else:
-    return [ResponseModel(**item) for item in result]
-```
-
-## Updated Endpoints
-
-### 1. Catalogues
-- **Endpoint**: `POST /catalogue/list`
-- **Schema**: `CatalogueListFilter`
-- **Service**: `CatalogueService.list_items()`
-- **Example**:
-  ```json
-  {
-    "filters": {"category": "Hair Care"},
-    "page": 1,
-    "page_size": 10,
-    "projection_list": ["catalogue_id", "catalogue_name", "pricing", "inventory"]
-  }
-  ```
-
-### 2. Employees
-- **Endpoint**: `POST /employees/list`
-- **Schema**: `EmployeeListRequest`
-- **Service**: `EmployeeService.list_employees()`
-- **Example**:
-  ```json
-  {
-    "designation": "ASM",
-    "status": "active",
-    "skip": 0,
-    "limit": 100,
-    "projection_list": ["user_id", "employee_code", "first_name", "last_name", "email", "phone"]
-  }
-  ```
-
-### 3. Merchants
-- **Endpoint**: `POST /merchants/list`
-- **Schema**: `MerchantListRequest`
-- **Service**: `MerchantService.list_merchants()`
-- **Example**:
-  ```json
-  {
-    "merchant_type": "distributor",
-    "status": "active",
-    "skip": 0,
-    "limit": 100,
-    "projection_list": ["merchant_id", "merchant_name", "merchant_type", "contact", "status"]
-  }
-  ```
-
-### 4. System Users
-- **Endpoint**: `POST /system-users/list`
-- **Schema**: `SystemUserListRequest`
-- **Service**: `SystemUserService.list_users()`
-- **Example**:
-  ```json
-  {
-    "page": 1,
-    "page_size": 20,
-    "is_active": true,
-    "projection_list": ["user_id", "username", "email", "full_name", "role_id"]
-  }
-  ```
-
-### 5. Sales Orders
-- **Endpoint**: `POST /sales/order/list`
-- **Schema**: `SalesOrderListRequest`
-- **Service**: `SalesOrderService.list_sales_orders()`
-- **Example**:
-  ```json
-  {
-    "filters": {"status": ["confirmed", "processing"]},
-    "pagination": {"page": 1, "limit": 20},
-    "sort": {"field": "order_date", "order": "desc"},
-    "projection_list": ["sales_order_id", "order_number", "customer", "summary", "status"]
-  }
-  ```
-
-### 6. RMA (Returns)
-- **Endpoint**: `POST /rma/list`
-- **Schema**: `RMAListRequest`
-- **Service**: `RMAService.list_rmas()`
-- **Example**:
-  ```json
-  {
-    "status": "requested",
-    "skip": 0,
-    "limit": 100,
-    "projection_list": ["rma_id", "related_order_id", "requestor_id", "status", "requested_action"]
-  }
-  ```
-
-### 7. GRN (Goods Received Notes)
-- **Endpoint**: `POST /grn/list`
-- **Schema**: `GRNListRequest`
-- **Service**: `GRNService.list_grns()`
-- **Example**:
-  ```json
-  {
-    "status": "completed",
-    "skip": 0,
-    "limit": 100,
-    "projection_list": ["grn_id", "po_id", "merchant_id", "status", "received_date"]
-  }
-  ```
-
-### 8. Merchant Settings
-- **Endpoint**: `POST /merchant-settings/list`
-- **Schema**: `MerchantSettingsListRequest`
-- **Service**: `MerchantSettingsService.list_merchant_settings()`
-- **Example**:
-  ```json
-  {
-    "status_filter": "active",
-    "skip": 0,
-    "limit": 100,
-    "projection_list": ["merchant_id", "business_settings", "inventory_settings", "is_active"]
-  }
-  ```
-
-## Benefits
-
-1. **Reduced Payload Size**: Clients can request only the fields they need, reducing network bandwidth
-2. **Improved Performance**: MongoDB projection reduces data transfer from database
-3. **Flexible API**: Clients can optimize their queries based on use case
-4. **Simplified API**: Single POST endpoint per resource with optional projection support
-
-## Usage Guidelines
-
-### When to Use Projection
-- **List views**: Request only fields needed for display (e.g., ID, name, status)
-- **Mobile apps**: Minimize data transfer for bandwidth-constrained environments
-- **Dashboard widgets**: Fetch only aggregated or summary fields
-- **Export operations**: Select specific fields for CSV/Excel exports
-
-### When NOT to Use Projection
-- **Detail views**: Fetch complete records for full detail pages
-- **Create/Update operations**: Always fetch complete records for editing
-- **Complex nested data**: Projection may not work well with deeply nested structures
-
-### Best Practices
-1. Always include the primary key field (e.g., `user_id`, `merchant_id`)
-2. Request related fields together (e.g., if requesting `first_name`, also request `last_name`)
-3. Test projection queries to ensure all required fields are included
-4. Document which fields are commonly used together in your API documentation
-
-## API Design
-
-- All list endpoints use POST method to support complex request bodies
-- Projection is optional - omit `projection_list` to get full objects
-- When projection is used, returns raw dictionaries for maximum flexibility
-- When projection is omitted, returns typed Pydantic models for validation
-
-## Testing
-
-Test projection with various field combinations:
-
-```bash
-# Test with projection
-curl -X POST http://localhost:8000/employees/list \
-  -H "Content-Type: application/json" \
-  -d '{
-    "skip": 0,
-    "limit": 10,
-    "projection_list": ["user_id", "first_name", "email"]
-  }'
-
-# Test without projection (returns full objects)
-curl -X POST http://localhost:8000/employees/list \
-  -H "Content-Type: application/json" \
-  -d '{
-    "skip": 0,
-    "limit": 10
-  }'
-```
-
-## Future Enhancements
-
-1. **Nested Field Projection**: Support dot notation for nested fields (e.g., `"contact.email"`)
-2. **Field Aliases**: Allow clients to rename fields in response
-3. **Computed Fields**: Support projection of calculated/derived fields
-4. **Projection Presets**: Define common projection patterns (e.g., "summary", "detail", "minimal")

docs/implementation-summaries/PURCHASES_MODULE_IMPLEMENTATION.md

@@ -1,272 +0,0 @@
-# SCM Purchases Module - Complete Implementation
-
-## Overview
-Complete implementation of the Purchases module for the SCM system, including Purchase Orders (PO) and Goods Receipt Notes (GRN) with full PostgreSQL support, async operations, and projection list compliance.
-
-## Architecture
-
-### Folder Structure
-```
-purchases/
-├── orders/                 # Purchase Orders (PO)
-│   ├── controllers/
-│   │   └── router.py      # FastAPI routes
-│   ├── services/
-│   │   └── service.py     # Business logic
-│   ├── models/
-│   │   └── model.py       # Model imports
-│   ├── schemas/
-│   │   └── schema.py      # Pydantic schemas
-│   └── __init__.py
-├── receipts/               # Goods Receipt Notes (GRN)
-│   ├── controllers/
-│   │   └── router.py      # FastAPI routes
-│   ├── services/
-│   │   └── service.py     # Business logic
-│   ├── models/
-│   │   └── model.py       # Model imports
-│   ├── schemas/
-│   │   └── schema.py      # Pydantic schemas
-│   └── __init__.py
-└── __init__.py
-```
-
-## Database Schema (PostgreSQL)
-
-### Purchase Orders
-- **scm_po**: PO header with buyer/supplier, dates, amounts, status
-- **scm_po_item**: PO line items with quantities, pricing
-- **scm_po_status_log**: Audit trail for status changes
-
-### Goods Receipt Notes
-- **scm_grn**: GRN header with receiver, supplier, location
-- **scm_grn_item**: GRN items with batch info, QC status
-- **scm_grn_issue**: Quality/quantity issues tracking
-
-## API Endpoints
-
-### Purchase Orders
-- `POST /purchases/orders` - Create PO
-- `GET /purchases/orders/{po_id}` - Get PO by ID
-- `POST /purchases/orders/list` - List POs with projection support ✅
-- `POST /purchases/orders/{po_id}/submit` - Submit for approval
-- `POST /purchases/orders/{po_id}/approve` - Approve PO
-- `POST /purchases/orders/{po_id}/cancel` - Cancel PO
-- `POST /purchases/orders/{po_id}/dispatch` - Mark as dispatched
-
-### Goods Receipt Notes
-- `POST /purchases/receipts` - Create GRN
-- `GET /purchases/receipts/{grn_id}` - Get GRN by ID
-- `POST /purchases/receipts/list` - List GRNs with projection support ✅
-- `POST /purchases/receipts/{grn_id}/accept` - Accept GRN
-- `POST /purchases/receipts/{grn_id}/reject` - Reject GRN
-- `POST /purchases/receipts/{grn_id}/close` - Close GRN
-- `POST /purchases/receipts/issues` - Add quality issues
-
-## Key Features
-
-### ✅ Projection List Support
-Both PO and GRN list endpoints implement the mandatory projection list standard:
-- Optional `projection_list` parameter in request schemas
-- PostgreSQL field selection for performance
-- Raw dict response when projection used
-- Full model response otherwise
-
-### ✅ Business Rules Enforcement
-- **PO Status Flow**: draft → submitted → approved → dispatched → partial_received → closed
-- **GRN Status Flow**: received → accepted/rejected → closed
-- **Quantity Validation**: acc_qty + rej_qty = recv_qty
-- **Business Logic**: Buyer-supplier transaction validation
-
-### ✅ Role-Based Access Control
-- `role_procurement_user` - Create/submit POs
-- `role_procurement_approver` - Approve POs
-- `role_warehouse_user` - Dispatch POs, close GRNs
-- `role_qc_user` - Accept/reject GRNs, report issues
-
-### ✅ Async PostgreSQL Operations
-- Full async/await support with SQLAlchemy
-- Connection pooling and proper session management
-- Transaction safety with rollback support
-- Performance optimized queries with selectinload
-
-### ✅ Comprehensive Logging
-- Structured logging with insightfy_utils
-- Performance metrics (duration tracking)
-- Business event logging
-- Error tracking with context
-
-### ✅ Data Validation
-- Pydantic schemas with field validation
-- Business rule validation in services
-- Referential integrity checks
-- Quantity and status transition validation
-
-## Status Lifecycles
-
-### Purchase Order States
-```
-draft → submitted → approved → dispatched → partial_received → closed
-  ↓         ↓         ↓           ↓              ↓
-cancelled cancelled cancelled cancelled    cancelled
-```
-
-### GRN States
-```
-received → accepted → closed
-    ↓         ↓
- rejected → closed
-```
-
-## Integration Points
-
-### Current Integrations
-- **Auth Service**: User authentication and role validation
-- **Centralized Models**: Uses `app.models.po_grn_model`
-- **PostgreSQL**: Async database operations
-
-### Future Integrations
-- **Merchant Service**: Validate can_transact_with relationships
-- **Catalogue Service**: SKU validation and batch rules
-- **Inventory Service**: Stock posting on GRN acceptance
-
-## Error Handling
-
-### Validation Errors (400)
-- Invalid status transitions
-- Quantity validation failures
-- Business rule violations
-- Duplicate PO/GRN numbers
-
-### Authorization Errors (403)
-- Insufficient role permissions
-- Access denied responses
-
-### Not Found Errors (404)
-- PO/GRN not found
-- Invalid references
-
-### Server Errors (500)
-- Database connection issues
-- Unexpected exceptions with logging
-
-## Performance Features
-
-### Database Optimization
-- Proper indexing on foreign keys
-- Selective field loading with projection
-- Pagination support
-- Connection pooling
-
-### Response Optimization
-- Field projection reduces payload by 50-90%
-- Async operations prevent blocking
-- Structured logging for monitoring
-- Efficient query patterns
-
-## Testing Considerations
-
-### Unit Tests Needed
-- Service layer business logic
-- Status transition validation
-- Quantity calculations
-- Error handling scenarios
-
-### Integration Tests Needed
-- Database operations
-- API endpoint responses
-- Authentication flows
-- Cross-service integrations
-
-## Deployment Notes
-
-### Environment Variables
-- PostgreSQL connection settings
-- Authentication service URLs
-- Logging configuration
-- Role definitions
-
-### Database Migration
-- Tables created via SQLAlchemy metadata
-- Indexes for performance
-- Foreign key constraints
-- Initial data seeding
-
-## Usage Examples
-
-### Create Purchase Order
-```python
-POST /purchases/orders
-{
-  // po_no is optional - auto-generated if not provided
-  "buyer_id": "merchant_123",
-  "buyer_type": "distributor", 
-  "supplier_id": "supplier_456",
-  "supplier_type": "manufacturer",
-  "items": [
-    {
-      "catalogue_id": "cat_789",
-      "sku": "SHAMPOO-500ML",
-      "ord_qty": 100,
-      "uom": "pieces",
-      "unit_price": 25.50
-    }
-  ],
-  "created_by": "user_123"
-}
-```
-
-### Auto-Generated Numbers
-- **PO Numbers**: Format `PO-YYYY-NNNNNN` (e.g., `PO-2024-000001`)
-- **GRN Numbers**: Format `GRN-YYYY-NNNNNN` (e.g., `GRN-2024-000001`)
-- Uses PostgreSQL sequences for thread-safe generation
-- Custom prefixes supported for special cases
-
-### List with Projection
-```python
-POST /purchases/orders/list
-{
-  "filters": {"status": ["approved", "dispatched"]},
-  "page": 1,
-  "page_size": 20,
-  "projection_list": ["po_id", "po_no", "status", "total_amt"]
-}
-```
-
-### Create GRN
-```python
-POST /purchases/receipts
-{
-  "grn_no": "GRN-2024-001",
-  "po_id": "po_uuid_here",
-  "receiver_id": "warehouse_123",
-  "supplier_id": "supplier_456",
-  "items": [
-    {
-      "po_item_id": "po_item_uuid",
-      "catalogue_id": "cat_789",
-      "sku": "SHAMPOO-500ML",
-      "recv_qty": 95,
-      "acc_qty": 90,
-      "rej_qty": 5,
-      "uom": "pieces",
-      "batch_no": "BATCH-2024-001"
-    }
-  ],
-  "created_by": "user_123"
-}
-```
-
-## Summary
-
-The Purchases module is now fully implemented with:
-- ✅ Complete PostgreSQL async operations
-- ✅ Projection list standard compliance
-- ✅ Role-based access control
-- ✅ Comprehensive business logic
-- ✅ Status lifecycle management
-- ✅ Error handling and logging
-- ✅ Performance optimization
-- ✅ Clean layered architecture
-
-The implementation follows all SCM standards and is ready for production use.

docs/implementation-summaries/SCM_POSTGRESQL_PO_GRN_IMPLEMENTATION.md

@@ -1,169 +0,0 @@
-# SCM PostgreSQL PO/GRN Implementation Summary
-
-## ✅ COMPLETED IMPLEMENTATION
-
-### 📦 Consolidated Schema Implementation
-- **Tables Created**: Following the consolidated schema with clean snake_case naming
-  - `scm_po` - Purchase Order header
-  - `scm_po_item` - Purchase Order line items
-  - `scm_po_status_log` - PO lifecycle audit trail
-  - `scm_grn` - Goods Receipt Note header
-  - `scm_grn_item` - GRN items with merged batch tracking
-  - `scm_grn_issue` - GRN discrepancies/QC issues
-
-### 🏗️ Architecture Components
-
-#### 1. **Models** (`app/models/po_grn_model.py`)
-- SQLAlchemy models with proper relationships
-- UUID primary keys for all tables
-- Proper foreign key constraints with CASCADE
-- Business rule validation ready
-- Audit fields (created_at, updated_at, created_by)
-
-#### 2. **Repository Layer** (`app/repositories/scm_po_grn_repository.py`)
-- `ScmPoRepository` - Purchase Order operations
-- `ScmGrnRepository` - Goods Receipt operations
-- **Projection List Support** - PostgreSQL column selection for performance
-- ACID transaction support
-- Auto-status updates based on receipt completion
-- Business rule validation (acc_qty + rej_qty = recv_qty)
-
-#### 3. **Service Layer** (`app/services/po_grn_service.py`)
-- `ScmPurchaseOrderService` - PO business logic
-- `ScmGoodsReceiptService` - GRN business logic
-- Auto-generation of PO/GRN numbers
-- Merchant hierarchy validation
-- Status workflow management
-
-#### 4. **Router Layer** (`app/routers/po_grn_router.py`)
-- RESTful endpoints following API standards
-- **POST method for list endpoints** (as per steering rules)
-- Projection list support for performance optimization
-- Comprehensive error handling and logging
-- Dashboard widget endpoints
-
-### 🔧 Key Features Implemented
-
-#### ✅ **API Standards Compliance**
-- **POST `/purchase-orders-pg/list`** - List POs with projection support
-- **POST `/purchase-orders-pg/grn/list`** - List GRNs with projection support
-- Optional `projection_list` parameter for 50-90% payload reduction
-- Consistent response format across all endpoints
-
-#### ✅ **Business Logic**
-- Auto-generation of PO/GRN numbers with merchant prefix
-- Status workflow: draft → submitted → approved → dispatched → partial_received → closed
-- Automatic PO status updates based on GRN receipts
-- Batch tracking with expiry date management
-- QC status tracking and issue management
-
-#### ✅ **Performance Optimizations**
-- PostgreSQL indexes on critical fields (buyer_id, supplier_id, status, sku, batch_no)
-- Connection pooling with proper timeout settings
-- Projection support for reduced network bandwidth
-- Efficient query patterns with proper joins
-
-#### ✅ **ACID Compliance**
-- Transactional integrity for PO creation with items
-- Status log audit trail for all changes
-- Proper rollback on errors
-- Consistent data state maintenance
-
-### 📊 Database Indexes Created
-```sql
--- Purchase Order indexes
-CREATE INDEX idx_scm_po_buyer ON scm_po (buyer_id);
-CREATE INDEX idx_scm_po_supplier ON scm_po (supplier_id);
-CREATE INDEX idx_scm_po_status ON scm_po (status);
-
--- PO Item indexes
-CREATE INDEX idx_po_item_po ON scm_po_item (po_id);
-
--- GRN indexes
-CREATE INDEX idx_grn_po ON scm_grn (po_id);
-
--- GRN Item indexes
-CREATE INDEX idx_grn_item_grn ON scm_grn_item (grn_id);
-CREATE INDEX idx_grn_item_po_item ON scm_grn_item (po_item_id);
-CREATE INDEX idx_grn_item_sku ON scm_grn_item (sku);
-CREATE INDEX idx_grn_item_batch ON scm_grn_item (batch_no);
-CREATE INDEX idx_grn_item_exp ON scm_grn_item (exp_dt);
-```
-
-### 🚀 API Endpoints Available
-
-#### Purchase Orders
-- `POST /purchase-orders-pg/order` - Create PO
-- `GET /purchase-orders-pg/order/{order_id}` - Get PO details
-- `PUT /purchase-orders-pg/order/{order_id}` - Update PO
-- `POST /purchase-orders-pg/order/{order_id}/submit` - Submit PO for approval
-- `POST /purchase-orders-pg/list` - List POs with projection support ⭐
-- `GET /purchase-orders-pg/order/{order_id}/receipts` - List GRNs for PO
-- `GET /purchase-orders-pg/info/widgets` - Dashboard widgets
-
-#### Goods Receipt Notes
-- `POST /purchase-orders-pg/grn` - Create GRN
-- `GET /purchase-orders-pg/grn/{grn_id}` - Get GRN details
-- `POST /purchase-orders-pg/grn/list` - List GRNs with projection support ⭐
-- `POST /purchase-orders-pg/grn/{grn_id}/items/{item_id}/batch` - Add issue to GRN item
-- `GET /purchase-orders-pg/grn/info/widgets` - GRN dashboard widgets
-
-### 🎯 Business Rules Implemented
-
-1. **PO Creation**:
-   - Auto-generates PO number: `PO-{merchant_id}-{YYYYMM}-{random}`
-   - Validates merchant hierarchy (buyer/supplier relationship)
-   - Creates audit log entry on status changes
-
-2. **GRN Processing**:
-   - Validates against existing PO
-   - Enforces: `acc_qty + rej_qty = recv_qty`
-   - Updates PO item received quantities
-   - Auto-updates PO status (partial_received/closed)
-   - Batch tracking with manufacturing/expiry dates
-
-3. **Status Workflow**:
-   - PO: draft → submitted → approved → dispatched → partial_received → closed → cancelled
-   - GRN: draft → received → partial_accept → accepted → rejected → closed
-
-### 📈 Performance Benefits
-
-- **50-90% payload reduction** with projection lists
-- **ACID transactions** for data consistency
-- **Connection pooling** for better resource utilization
-- **Indexed queries** for fast lookups
-- **Batch operations** for bulk processing
-
-### 🔄 Integration Points
-
-- **Auth Service**: JWT token validation for user context
-- **Catalogue Service**: SKU validation and product details
-- **Merchant Service**: Hierarchy validation (can_transact_with)
-- **Inventory Service**: Ready for stock ledger integration
-
-### 🧪 Testing Ready
-
-The implementation is ready for testing with:
-- Unit tests for business logic
-- Integration tests for database operations
-- API endpoint testing
-- Performance benchmarking
-
-### 🎉 Migration Complete
-
-✅ **MongoDB → PostgreSQL migration completed**
-✅ **TMS pattern implementation**
-✅ **API standards compliance**
-✅ **Projection list support**
-✅ **Business rules enforcement**
-✅ **ACID transaction support**
-
-The SCM microservice now has a robust, scalable PostgreSQL-based PO/GRN system that follows enterprise patterns and provides excellent performance with projection support.
-
-## Next Steps (Optional)
-
-1. **Inventory Integration**: Connect to stock ledger for real-time inventory updates
-2. **RMA Module**: Returns management against GRN items
-3. **Credit Notes**: GST-compliant credit note generation
-4. **Advanced Analytics**: Reporting and dashboard enhancements
-5. **Batch Expiry Alerts**: Automated notifications for expiring batches

docs/implementation-summaries/SOLUTION_SUMMARY.md

@@ -1,199 +0,0 @@
-# ✅ Enhanced retail Catalogue Implementation - COMPLETE
-
-## 🎯 **SOLUTION DELIVERED**
-
-Successfully implemented enhanced retail catalogue data with the exact structure you requested, including full projection list support and dual database synchronization.
-
-## 📊 **CURRENT STATUS**
-
-### **MongoDB (Primary Storage)**
-- ✅ **10 catalogues** with enhanced structure
-- ✅ **Multi-level pricing**: ncnf, cnf, distributor, retail
-- ✅ **Multi-level inventory**: Different configurations per merchant type
-- ✅ **Complete product data**: L'Oréal, Matrix, Schwarzkopf products
-
-### **PostgreSQL (Reference & Performance)**
-- ✅ **5 catalogues** fully synced with pricing JSON
-- ✅ **Enhanced pricing data** stored as JSON
-- ✅ **Essential fields** extracted for fast queries
-- ✅ **Merchant filtering** working correctly
-
-## 🏗️ **ARCHITECTURE IMPLEMENTED**
-
-### **1. Enhanced Data Structure**
-```json
-{
-  "pricing": {
-    "currency": "INR",
-    "mrp": 1850,
-    "levels": {
-      "ncnf": {"cost_price": 1628.0, "trade_margin": 12, "max_discount_pct": 0},
-      "cnf": {"cost_price": 1739.0, "trade_margin": 6, "max_discount_pct": 0},
-      "distributor": {"cost_price": 1665.0, "trade_margin": 10, "max_discount_pct": 0},
-      "retail": {"cost_price": 1480.0, "trade_margin": 20, "max_discount_pct": 0}
-    }
-  },
-  "inventory": {
-    "unit": "PCS",
-    "levels": {
-      "ncnf": {"reorder_level": 500, "reorder_quantity": 1000, "safety_stock": 200},
-      "cnf": {"reorder_level": 200, "reorder_quantity": 500, "safety_stock": 100},
-      "distributor": {"reorder_level": 50, "reorder_quantity": 100, "safety_stock": 20},
-      "retail": {"reorder_level": 10, "reorder_quantity": 20, "safety_stock": 5}
-    }
-  }
-}
-```
-
-### **2. API Endpoints with Projection Support**
-
-#### **Catalogue APIs**
-- ✅ `POST /catalogue/list` - List with projection
-- ✅ `POST /catalogue/lazy-fetch` - Lazy loading with projection
-- ✅ `POST /catalogue/merchant-catalogue/list` - Merchant-specific with projection
-- ✅ `GET /catalogue/{id}` - Single item with projection
-- ✅ `POST /catalogue/{id}/details` - POST method with projection
-
-#### **Inventory APIs**
-- ✅ `POST /inventory/stock/list` - Stock list with projection
-- ✅ `POST /inventory/stock/ledger/list` - Ledger with projection
-- ✅ `POST /inventory/stock/summary` - Summary with projection
-- ✅ `POST /inventory/stock/availability/check` - Availability check
-- ✅ `POST /inventory/stock/valuation` - Valuation with projection
-
-### **3. Performance Benefits**
-
-| Projection Type | Payload Size | Reduction |
-|----------------|--------------|-----------|
-| **Full Document** | ~2000+ bytes | 0% |
-| **Basic Info** | 132 bytes | **90%** |
-| **Pricing Only** | 497 bytes | **75%** |
-| **Inventory Only** | 671 bytes | **66%** |
-
-## 🔧 **SCRIPTS CREATED**
-
-### **Data Generation**
-- `create_enhanced_retail_catalogues.py` - Main data generator
-- `run_enhanced_catalogue_generation.py` - Simple runner
-- `enhanced_retail_catalogues_data.json` - Sample JSON data
-
-### **Database Management**
-- `fix_missing_postgres_records.py` - Sync missing records
-- `update_postgres_pricing.py` - Update pricing data
-- `check_postgres_duplicates.py` - Clean duplicates
-
-### **Testing & Verification**
-- `verify_enhanced_data.py` - Data structure verification
-- `test_enhanced_catalogue_apis.py` - API testing suite
-
-## 🎯 **API TESTING EXAMPLES**
-
-### **Catalogue List with Projection**
-```bash
-curl -X POST "http://localhost:8000/catalogue/list" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "filters": {"merchant_id": "company_cuatro_beauty_ltd"},
-    "projection_list": ["catalogue_id", "catalogue_name", "pricing"],
-    "limit": 5
-  }'
-```
-
-### **Inventory Stock List**
-```bash
-curl -X POST "http://localhost:8000/inventory/stock/list" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "filters": {},
-    "projection_list": ["sku", "qty_on_hand", "qty_available"],
-    "limit": 10
-  }'
-```
-
-### **Stock Availability Check**
-```bash
-curl -X POST "http://localhost:8000/inventory/stock/availability/check" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "items": [
-      {"sku": "LOR-ABS-REP-SHMP-300ML", "qty": 10, "location_id": "main_warehouse"}
-    ],
-    "projection_list": ["sku", "is_available", "total_available"]
-  }'
-```
-
-## 📋 **SAMPLE PRODUCTS CREATED**
-
-1. **L'Oréal Professional Absolut Repair Shampoo 300ML**
-   - SKU: `LOR-ABS-REP-SHMP-300ML`
-   - MRP: ₹1,850 | retail Cost: ₹1,480
-
-2. **L'Oréal Professional Serie Expert Vitamino Color Shampoo 500ML**
-   - SKU: `LOR-VIT-COL-SHMP-500ML`
-   - MRP: ₹2,450 | retail Cost: ₹1,960
-
-3. **Matrix Biolage Hydrasource Shampoo 400ML**
-   - SKU: `MTX-HYD-SRC-SHMP-400ML`
-   - MRP: ₹1,250 | retail Cost: ₹1,000
-
-4. **L'Oréal Professional Mythic Oil Nourishing Shampoo 250ML**
-   - SKU: `LOR-MYT-OIL-SHMP-250ML`
-   - MRP: ₹1,650 | retail Cost: ₹1,320
-
-5. **Schwarzkopf Professional BC Bonacure Repair Rescue Shampoo 250ML**
-   - SKU: `SCH-BC-REP-RES-SHMP-250ML`
-   - MRP: ₹1,450 | retail Cost: ₹1,160
-
-## 🔍 **DATABASE VERIFICATION**
-
-### **MongoDB Query**
-```javascript
-// Check enhanced structure
-db.scm_catalogue.findOne({
-  "merchant_id": "company_cuatro_beauty_ltd",
-  "pricing.levels": {"$exists": true}
-})
-```
-
-### **PostgreSQL Query**
-```sql
--- Check synced data with pricing
-SELECT catalogue_code, catalogue_name, 
-       pricing->>'currency' as currency,
-       (pricing->'levels'->>'retail')::jsonb->>'cost_price' as retail_cost_price
-FROM trans.catalogue_ref 
-WHERE 'company_cuatro_beauty_ltd' = ANY(merchant_id);
-```
-
-## 🎊 **BENEFITS ACHIEVED**
-
-### **Performance**
-- ✅ **50-90% payload reduction** with projection lists
-- ✅ **Faster API responses** with MongoDB projection
-- ✅ **Reduced bandwidth** for mobile clients
-- ✅ **Efficient PostgreSQL queries** for reporting
-
-### **Scalability**
-- ✅ **Multi-level pricing** supports different merchant types
-- ✅ **Flexible inventory** configurations per level
-- ✅ **Dual database** strategy for performance and flexibility
-- ✅ **Consistent API pattern** across all endpoints
-
-### **Developer Experience**
-- ✅ **Projection list support** on all list endpoints
-- ✅ **Comprehensive testing** scripts included
-- ✅ **Easy data generation** for development
-- ✅ **Complete documentation** and examples
-
-## 🚀 **READY FOR PRODUCTION**
-
-The enhanced retail catalogue system is now fully operational with:
-
-1. ✅ **Complete data structure** matching your requirements
-2. ✅ **Full projection list compliance** across all APIs
-3. ✅ **Dual database synchronization** working perfectly
-4. ✅ **Professional beauty products** data loaded
-5. ✅ **Comprehensive testing** suite available
-6. ✅ **Performance optimizations** delivering 50-90% payload reduction
-
-**Your enhanced catalogue and inventory system is ready to serve retail businesses with maximum efficiency and flexibility!** 🎉

docs/implementation-summaries/SWAGGER_FIX_SUMMARY.md

@@ -1,93 +0,0 @@
-# Swagger/FastAPI OpenAPI Fix Summary
-
-## Issue Description
-The FastAPI Swagger documentation was failing to load with a 500 error on `/openapi.json` due to a Pydantic serialization error: "Unable to serialize unknown type: <class 'function'>".
-
-## Root Cause Analysis
-Through systematic testing of individual routers, the issue was identified in the **warehouse schemas** (`app/warehouses/schemas/schema.py`):
-
-1. **Problematic Code**: The schema was importing SQLAlchemy functions:
-   ```python
-   from sqlalchemy import false, true
-   ```
-
-2. **Usage in Examples**: These SQLAlchemy functions were used in Pydantic schema examples:
-   ```python
-   "capabilities": {
-       "can_receive": true,    # SQLAlchemy function, not boolean
-       "can_fulfil": true,     # SQLAlchemy function, not boolean
-       "can_sell": false,      # SQLAlchemy function, not boolean
-       ...
-   }
-   ```
-
-3. **Serialization Error**: When FastAPI tried to generate the OpenAPI schema, Pydantic couldn't serialize the SQLAlchemy function objects.
-
-## Solution Applied
-1. **Removed SQLAlchemy imports**:
-   ```python
-   # Before
-   from sqlalchemy import false, true
-   
-   # After
-   # Removed SQLAlchemy imports - using Python booleans instead
-   ```
-
-2. **Fixed boolean values in examples**:
-   ```python
-   # Before
-   "capabilities": {
-       "can_receive": true,
-       "can_fulfil": true,
-       "can_sell": false,
-       ...
-   }
-   
-   # After
-   "capabilities": {
-       "can_receive": True,
-       "can_fulfil": True,
-       "can_sell": False,
-       ...
-   }
-   ```
-
-## Employee System User Integration
-As part of the same session, successfully implemented the employee system user integration:
-
-### Added Fields
-- `is_system_user: bool` field to employee schemas and models
-- When `is_system_user=True`, automatically creates a system user in `SCM_SYSTEM_USERS` collection
-
-### Implementation Details
-- **Employee Schema**: Added `is_system_user` field to `EmployeeCreate`, `EmployeeUpdate`, and `EmployeeResponse`
-- **Employee Model**: Added `is_system_user` field to `EmployeeModel`
-- **Employee Service**: Added `_create_employee_system_user` method that:
-  - Generates username from employee code
-  - Creates temporary password
-  - Maps designation to role_id
-  - Stores employee metadata in system user record
-
-## Verification Results
-✅ **OpenAPI Schema Generation**: Successfully generates schema with 131 endpoints
-✅ **Employee Integration**: `is_system_user` field present in both create and response schemas
-✅ **Warehouse Fix**: Boolean values properly serialized
-✅ **All Routers**: All 15 routers now work correctly together
-
-## Files Modified
-1. `cuatrolabs-scm-ms/app/employees/schemas/schema.py` - Added `is_system_user` field
-2. `cuatrolabs-scm-ms/app/employees/models/model.py` - Added `is_system_user` field
-3. `cuatrolabs-scm-ms/app/employees/services/service.py` - Added system user creation logic
-4. `cuatrolabs-scm-ms/app/warehouses/schemas/schema.py` - Fixed SQLAlchemy boolean issue
-
-## Testing
-- Created comprehensive test script (`test_swagger_fix.py`)
-- Verified OpenAPI schema generation works
-- Confirmed all new fields are properly included
-- Validated boolean serialization fix
-
-## Impact
-- ✅ Swagger/FastAPI documentation now loads correctly
-- ✅ Employee system user integration fully functional
-- ✅ All API endpoints accessible via Swagger UI
-- ✅ No breaking changes to existing functionality

docs/implementation-summaries/TRADE_SALES_IMPLEMENTATION.md

@@ -1,415 +0,0 @@
-# Trade Sales (B2B) Implementation Guide
-
-## Overview
-
-The Trade Sales module handles B2B outbound sales operations where goods are sold between merchants (cnf → distributor → retail). This module implements the complete order-to-shipment execution flow with proper inventory management and audit trails.
-
-## Architecture
-
-### Module Structure
-```
-app/trade_sales/
-├── __init__.py
-├── controllers/
-│   ├── __init__.py
-│   └── router.py          # FastAPI routes
-├── services/
-│   ├── __init__.py
-│   └── service.py         # Business logic
-└── schemas/
-    ├── __init__.py
-    └── schema.py          # Pydantic models
-```
-
-### Database Models
-```
-app/models/
-└── trade_sales_model.py   # SQLAlchemy models
-```
-
-## Key Features
-
-### ✅ Implemented Features
-
-1. **Client Orders (Read-Only Views)**
-   - List client orders with projection support
-   - View detailed order information
-   - Filter by client, status, date range
-   - Derived status calculation (pending/partial/completed)
-
-2. **Order Execution**
-   - List orders ready for execution
-   - Execute orders with shipment creation
-   - Partial shipment support
-   - Stock validation and updates
-   - Batch tracking
-
-3. **Trade Shipments**
-   - List all shipments with projection support
-   - View detailed shipment information
-   - Track logistics details (transporter, LR, vehicle)
-   - Shipment status management
-
-4. **Stock Integration**
-   - Automatic stock reduction on shipment
-   - Stock ledger entries for audit
-   - Batch-wise inventory tracking
-   - Stock validation before shipment
-
-5. **API Standards Compliance**
-   - All list endpoints support projection
-   - POST method for list operations
-   - Consistent error handling
-   - Proper pagination
-
-### 🚧 Placeholder Features (Future Implementation)
-
-1. **Trade Invoices**
-   - Invoice generation from shipments
-   - Invoice list and detail views
-   - Payment tracking
-
-2. **Credit Notes**
-   - Credit note generation
-   - Return processing integration
-
-## Database Schema
-
-### Core Tables
-
-#### scm_trade_shipment
-```sql
-CREATE TABLE scm_trade_shipment (
-    shipment_id     UUID PRIMARY KEY,
-    shipment_no     VARCHAR(40) UNIQUE NOT NULL,
-    order_id        UUID NOT NULL REFERENCES scm_po(po_id),
-    supplier_id     VARCHAR(64) NOT NULL,  -- cnf merchant ID
-    client_id       VARCHAR(64) NOT NULL,  -- distributor merchant ID
-    warehouse_id    UUID NOT NULL,
-    status          VARCHAR(20) NOT NULL DEFAULT 'draft',
-    shipment_date   DATE NOT NULL,
-    transporter     VARCHAR(100),
-    lr_no           VARCHAR(50),
-    vehicle_no      VARCHAR(20),
-    created_by      VARCHAR(64),
-    created_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-    updated_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-```
-
-#### scm_trade_shipment_item
-```sql
-CREATE TABLE scm_trade_shipment_item (
-    item_id         UUID PRIMARY KEY,
-    shipment_id     UUID NOT NULL REFERENCES scm_trade_shipment(shipment_id),
-    po_item_id      UUID NOT NULL REFERENCES scm_po_item(po_item_id),
-    sku             VARCHAR(64) NOT NULL,
-    batch_no        VARCHAR(50) NOT NULL,
-    ordered_qty     NUMERIC(12,3) NOT NULL,
-    shipped_qty     NUMERIC(12,3) NOT NULL,
-    balance_qty     NUMERIC(12,3) NOT NULL
-);
-```
-
-### Views and Analytics
-
-#### v_order_execution_status
-Provides real-time order execution status with quantities and shipment counts.
-
-#### v_trade_sales_summary
-Aggregated trade sales metrics by client.
-
-#### get_trade_sales_analytics()
-Stored procedure for comprehensive trade sales analytics.
-
-## API Endpoints
-
-### Client Orders
-
-#### POST /trade-sales/client-orders/list
-List client orders with projection support.
-
-**Request:**
-```json
-{
-  "filters": {
-    "client_id": "DIST-BLR-001",
-    "status": "pending",
-    "order_date_from": "2024-01-01",
-    "order_date_to": "2024-12-31"
-  },
-  "skip": 0,
-  "limit": 100,
-  "projection_list": ["order_no", "client_id", "pending_qty", "status"]
-}
-```
-
-**Response:**
-```json
-{
-  "items": [
-    {
-      "order_no": "PO20241217001",
-      "client_id": "DIST-BLR-001",
-      "pending_qty": 150.0,
-      "status": "pending"
-    }
-  ],
-  "total": 1,
-  "skip": 0,
-  "limit": 100,
-  "has_more": false
-}
-```
-
-#### GET /trade-sales/client-orders/{order_id}
-Get detailed client order with items.
-
-### Order Execution
-
-#### POST /trade-sales/order-execution/list
-List orders ready for execution.
-
-#### GET /trade-sales/order-execution/{order_id}/detail
-Get order execution detail with stock availability.
-
-#### POST /trade-sales/order-execution/{order_id}/execute
-Execute order by creating shipment.
-
-**Request:**
-```json
-{
-  "warehouse_id": "uuid",
-  "items": [
-    {
-      "po_item_id": "uuid",
-      "sku": "SHMP-500",
-      "batch_no": "BATCH-001",
-      "shipped_qty": 90
-    }
-  ],
-  "shipment": {
-    "transporter": "VRL Logistics",
-    "lr_no": "LR-998877",
-    "vehicle_no": "KA01AB1234",
-    "shipment_date": "2024-12-17",
-    "remarks": "Partial shipment"
-  }
-}
-```
-
-### Trade Shipments
-
-#### POST /trade-sales/shipments/list
-List trade shipments with projection support.
-
-#### GET /trade-sales/shipments/{shipment_id}
-Get detailed shipment information.
-
-## Business Logic
-
-### Order Status Derivation
-```python
-if shipped_qty == 0:
-    status = "pending"
-elif shipped_qty < ordered_qty:
-    status = "partial"
-elif shipped_qty >= ordered_qty:
-    status = "completed"
-```
-
-### Stock Impact Flow
-1. **Order Execution** → Creates shipment record
-2. **Stock Service** → Reduces supplier inventory
-3. **Stock Ledger** → Creates audit trail
-4. **Buyer Inventory** → Updated via separate GRN process
-
-### Shipment Number Generation
-Format: `TS{YYYYMMDD}{NNNN}`
-- TS = Trade Sales prefix
-- YYYYMMDD = Shipment date
-- NNNN = Sequential number for the day
-
-## Integration Points
-
-### Stock Service Integration
-```python
-# Automatic stock reduction on shipment
-stock_transaction = StockTransaction(
-    merchant_id=supplier_id,
-    location_id=warehouse_id,
-    sku=sku,
-    batch_no=batch_no,
-    qty=-shipped_qty,  # Negative for outbound
-    txn_type=TransactionType.SALE_OUT,
-    ref_type=ReferenceType.SALE,
-    ref_id=shipment_id
-)
-```
-
-### PO/GRN Integration
-- **Client Orders** are read-only views of existing POs
-- **Shipment Items** reference PO items for traceability
-- **GRN Process** handles buyer inventory updates
-
-## Testing
-
-### Migration
-```bash
-# Run database migration
-python migration_trade_sales_tables.py
-
-# Rollback if needed
-python migration_trade_sales_tables.py rollback
-```
-
-### Sample Data
-```bash
-# Create sample data
-python examples/trade_sales/create_sample_trade_data.py
-
-# Clean up sample data
-python examples/trade_sales/create_sample_trade_data.py cleanup
-```
-
-### API Testing
-```bash
-# Test all APIs
-python examples/trade_sales/test_trade_sales_apis.py
-```
-
-## Performance Considerations
-
-### Projection List Benefits
-- **Payload Reduction**: 50-90% smaller responses
-- **Database Performance**: Reduced I/O with SQL SELECT optimization
-- **Network Efficiency**: Less bandwidth usage
-- **Client Flexibility**: Request only needed fields
-
-### Indexing Strategy
-```sql
--- Order lookup
-CREATE INDEX idx_trade_shipment_order_id ON scm_trade_shipment(order_id);
-
--- Client filtering
-CREATE INDEX idx_trade_shipment_client_id ON scm_trade_shipment(client_id);
-
--- Date range queries
-CREATE INDEX idx_trade_shipment_date ON scm_trade_shipment(shipment_date);
-
--- Status filtering
-CREATE INDEX idx_trade_shipment_status ON scm_trade_shipment(status);
-```
-
-## Security & Permissions
-
-### Role-Based Access
-- **cnf Admin**: Full access to all operations
-- **cnf Ops**: Execute orders, view shipments
-- **distributor**: Read-only access to own orders
-- **Finance**: Invoice and reporting access
-
-### Data Validation
-- Shipment quantities cannot exceed ordered quantities
-- Stock availability validation before shipment
-- Batch expiry date validation
-- Duplicate shipment number prevention
-
-## Monitoring & Logging
-
-### Key Metrics
-- Orders pending execution
-- Average shipment processing time
-- Stock accuracy after shipments
-- Client-wise shipment volumes
-
-### Audit Trail
-- All shipments are immutable after posting
-- Complete lineage: PO → Shipment → GRN → Invoice
-- Stock ledger provides full transaction history
-
-## Future Enhancements
-
-### Phase 2 Features
-1. **Trade Invoices**
-   - Automatic invoice generation from shipments
-   - Tax calculations and compliance
-   - Payment tracking integration
-
-2. **Credit Notes**
-   - Return processing workflow
-   - Credit note generation
-   - Adjustment handling
-
-3. **Advanced Analytics**
-   - Client performance dashboards
-   - Shipment efficiency metrics
-   - Inventory turnover analysis
-
-4. **Mobile Support**
-   - Mobile-optimized APIs
-   - Offline shipment creation
-   - Barcode scanning integration
-
-### Integration Roadmap
-1. **ERP Integration**: SAP/Oracle connector
-2. **Logistics Integration**: 3PL system connectivity
-3. **Payment Gateway**: Invoice payment processing
-4. **Notification System**: SMS/Email alerts
-
-## Troubleshooting
-
-### Common Issues
-
-#### Stock Validation Errors
-```
-Error: Cannot ship 100 units of SKU ABC. Available: 50
-```
-**Solution**: Check stock availability and adjust shipment quantities.
-
-#### Duplicate Shipment Numbers
-```
-Error: Shipment number TS20241217001 already exists
-```
-**Solution**: Shipment number generation handles this automatically.
-
-#### Missing PO Items
-```
-Error: Invalid PO item ID: uuid
-```
-**Solution**: Ensure PO items exist and are valid for the order.
-
-### Debug Queries
-
-#### Check Order Status
-```sql
-SELECT * FROM v_order_execution_status WHERE order_id = 'uuid';
-```
-
-#### Verify Stock Availability
-```sql
-SELECT sku, batch_no, qty_available 
-FROM scm_stock 
-WHERE merchant_id = 'cnf-ID' AND sku = 'SKU';
-```
-
-#### Trace Shipment History
-```sql
-SELECT ts.shipment_no, ts.shipment_date, tsi.sku, tsi.shipped_qty
-FROM scm_trade_shipment ts
-JOIN scm_trade_shipment_item tsi ON ts.shipment_id = tsi.shipment_id
-WHERE ts.order_id = 'uuid'
-ORDER BY ts.shipment_date;
-```
-
-## Conclusion
-
-The Trade Sales module provides a comprehensive B2B outbound sales solution with:
-- ✅ Complete order-to-shipment workflow
-- ✅ Proper inventory management
-- ✅ API standards compliance
-- ✅ Audit trail and traceability
-- ✅ Performance optimization
-- ✅ Extensible architecture
-
-The module is production-ready for the core functionality with clear paths for future enhancements.

docs/implementation-summaries/catalogue_api_examples.md

@@ -1,166 +0,0 @@
-# Catalogue API Examples with Auto-Generation
-
-## Create Catalogue with Auto-Generation
-
-### Example 1: Full Auto-Generation
-```bash
-curl -X 'POST' \
-  'http://127.0.0.1:8000/catalogue' \
-  -H 'accept: application/json' \
-  -H 'Authorization: Bearer YOUR_TOKEN' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "catalogue_name": "L'\''Oreal Professional Shampoo 500ml",
-    "catalogue_type": "Product",
-    "brand": "LOREAL",
-    "category": "SHAMPOO",
-    "description": "Professional grade shampoo for all hair types",
-    "identifiers": {
-      "sku": "LOR-SHA-500ML",
-      "ean_code": "1234567890123"
-    },
-    "attributes": {
-      "size": "500ml",
-      "hair_type": "all_types"
-    },
-    "pricing": {
-      "retail_price": 850.00,
-      "mrp": 1000.00,
-      "currency": "INR"
-    }
-  }'
-```
-
-**Expected Response:**
-- `catalogue_id`: Auto-generated UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`)
-- `catalogue_code`: Auto-generated code (e.g., `LOR-SHA-000001`)
-
-### Example 2: Manual ID, Auto Code
-```bash
-curl -X 'POST' \
-  'http://127.0.0.1:8000/catalogue' \
-  -H 'accept: application/json' \
-  -H 'Authorization: Bearer YOUR_TOKEN' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "catalogue_id": "custom-loreal-shampoo-001",
-    "catalogue_name": "L'\''Oreal Professionnel Serie Expert",
-    "catalogue_type": "Product", 
-    "brand": "LOREAL",
-    "category": "SHAMPOO",
-    "description": "Expert series professional shampoo"
-  }'
-```
-
-**Expected Response:**
-- `catalogue_id`: `custom-loreal-shampoo-001` (as provided)
-- `catalogue_code`: Auto-generated (e.g., `LOR-SHA-000002`)
-
-### Example 3: Complete Manual Override
-```bash
-curl -X 'POST' \
-  'http://127.0.0.1:8000/catalogue' \
-  -H 'accept: application/json' \
-  -H 'Authorization: Bearer YOUR_TOKEN' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "catalogue_id": "manual-id-123",
-    "catalogue_code": "CUSTOM-CODE-001",
-    "catalogue_name": "Custom Product",
-    "catalogue_type": "Product",
-    "brand": "OTHER",
-    "category": "OTHER"
-  }'
-```
-
-## Auto-Generation Rules
-
-### Catalogue ID Generation
-- **Format**: UUID4 (e.g., `550e8400-e29b-41d4-a716-446655440000`)
-- **When**: Generated if `catalogue_id` is not provided
-- **Uniqueness**: Guaranteed unique across all catalogues
-
-### Catalogue Code Generation  
-- **Format**: `BBB-CCC-NNNNNN` (e.g., `LOR-SHA-000001`)
-- **When**: Generated if `catalogue_code` is not provided AND both `brand` and `category` are provided
-- **Components**:
-  - `BBB`: 3-letter brand code (normalized)
-  - `CCC`: 3-letter category code (normalized)  
-  - `NNNNNN`: 6-digit sequence number (zero-padded)
-
-### Brand Codes (Examples)
-- `LOREAL` → `LOR`
-- `MATRIX` → `MAT`
-- `SCHWARZKOPF` → `SCH`
-- `WELLA` → `WEL`
-- `REDKEN` → `RED`
-- `TIGI` → `TIG`
-- `PAUL_MITCHELL` → `PAU`
-- `KERASTASE` → `KER`
-- `OLAPLEX` → `OLA`
-- `MOROCCANOIL` → `MOR`
-
-### Category Codes (Examples)
-- `SHAMPOO` → `SHA`
-- `CONDITIONER` → `CON`
-- `HAIR_MASK` → `HAI`
-- `HAIR_OIL` → `HAI`
-- `HAIR_SERUM` → `HAI`
-- `HAIR_COLOR` → `HAI`
-- `STYLING_GEL` → `STY`
-- `STYLING_CREAM` → `STY`
-- `HAIR_SPRAY` → `HAI`
-
-## Validation Rules
-
-### Valid Brands
-```
-LOREAL, MATRIX, SCHWARZKOPF, WELLA, REDKEN, TIGI, 
-PAUL_MITCHELL, KERASTASE, OLAPLEX, MOROCCANOIL, OTHER
-```
-
-### Valid Categories  
-```
-SHAMPOO, CONDITIONER, HAIR_MASK, HAIR_OIL, HAIR_SERUM,
-HAIR_COLOR, HAIR_BLEACH, DEVELOPER, STYLING_GEL, STYLING_CREAM,
-HAIR_SPRAY, MOUSSE, TOOLS, ACCESSORIES, OTHER
-```
-
-## Error Responses
-
-### Invalid Brand
-```json
-{
-  "detail": "Invalid brand: FAKE_BRAND"
-}
-```
-
-### Invalid Category
-```json
-{
-  "detail": "Invalid category: FAKE_CATEGORY"  
-}
-```
-
-### Duplicate Name
-```json
-{
-  "detail": "Catalogue item already exists"
-}
-```
-
-## Sequence Management
-
-- **Storage**: MongoDB `sequences` collection
-- **Thread-Safe**: Uses MongoDB's atomic `findOneAndUpdate` with `$inc`
-- **Auto-Initialize**: Sequences created automatically on first use
-- **Starting Value**: 1 (generates `000001`, `000002`, etc.)
-
-## Benefits
-
-1. **No Manual Numbering**: Eliminates duplicate code errors
-2. **Consistent Format**: Standardized across all catalogues  
-3. **Brand Recognition**: Codes include brand/category info
-4. **Scalable**: MongoDB atomic operations handle concurrency
-5. **Flexible**: Optional manual override for special cases
-6. **Searchable**: Structured codes enable easy filtering/searching