docs/security/TAXONOMY_API_COMPLETE_GUIDE.md

# Complete Taxonomy API Implementation Guide

## Overview

This document provides a comprehensive guide to the taxonomy management system implementation based on the complete JSON structure. The system supports all taxonomy categories including product, employee, customer, and operational taxonomies with full CRUD operations and performance optimization through projection lists.

## Supported Taxonomy Categories

Based on the provided JSON structure, the system supports the following taxonomy categories:

### Product Taxonomies
- **brands**: Product brands (e.g., "L'Oréal Professional", "Schwarzkopf", "Kerastase")
- **categories**: Product categories (e.g., "Hair", "Skin", "Nails", "Spa", "Makeup")
- **lines**: Product lines (e.g., "Hair Care", "Hair Styling", "Facials")
- **classes**: Product classes (e.g., "Premium", "Luxury", "Basic", "VIP")
- **subcategories**: Hierarchical subcategories mapped to parent categories

### Employee Taxonomies
- **job_role**: Employee job roles (e.g., "Senior Stylist", "Director", "Massage therapist")
- **specializations**: Employee specializations (e.g., "Hairdresser", "Nail technician", "Esthetician")
- **languages**: Supported languages (e.g., "English", "Hindi", "Tamil")

### Customer Taxonomies
- **customer_group**: Customer groups (e.g., "VIP", "Regular", "Premium", "Enterprise", "Gold")

### Operational Taxonomies

#### POS & Payment
- **pos_tender_modes**: POS tender modes (e.g., "Cash", "Credit Card", "Debit Card", "Mobile Payment")
- **payment_types**: Payment types (e.g., "Cash and Carry", "Credit")
- **payment_methods**: Payment methods (e.g., "Bank Transfer", "Cash", "Cheque")

#### Asset & Inventory
- **asset_location**: Asset locations (e.g., "Store Floor", "Warehouse", "Back Office")
- **asset_category**: Asset categories (e.g., "Electronics", "Furniture", "Equipment")
- **stock_bin_location**: Stock bin locations (e.g., "A1-01", "B2-15", "C3-07", "Receiving")

#### Business Structure
- **branch_types**: Branch types (e.g., "Flagship", "Outlet", "Pop-up", "Franchise")
- **expense_types**: Expense types (e.g., "Travel", "Office Supplies")

### UOM Conversions
- **uom_conversions**: Unit of measurement conversions with base UOM and conversion factors

## API Endpoints

### Base URL
```
/taxonomy
```

### Authentication
All endpoints require JWT authentication with merchant_id in the token metadata.

---

## 1. Create or Update Taxonomy

**Endpoint:** `POST /taxonomy/`

**Description:** Create new taxonomy data or update existing data for a merchant. Supports all taxonomy categories and uses MongoDB addToSet operations to prevent duplicates.

### Request Body

```json
{
  "brands": ["L'Oréal Professional", "Schwarzkopf", "Kerastase", "Olaplex"],
  "categories": ["Hair", "Skin", "Nails", "Spa", "Makeup", "Foot"],
  "lines": ["Hair Care", "Hair Styling", "Facials", "Body Treatments"],
  "classes": ["Premium", "Luxury", "Basic", "VIP"],
  "subcategories": {
    "Hair": ["Hair Cut", "Hair Color", "Hair Spa", "Keratin Treatment"],
    "Skin": ["Clean-up", "Facial", "De-Tan", "Peel Treatments"],
    "Nails": ["Manicure", "Pedicure", "Nail Art", "Gel Polish"],
    "Spa": ["Head Massage", "Full Body Massage", "Aromatherapy"],
    "Makeup": ["Bridal Makeup", "Party Makeup"]
  },
  "job_role": ["Senior Stylist", "Director", "Massage therapist", "Esthetician"],
  "specializations": ["Hairdresser", "Nail technician", "Massage therapist", "Esthetician"],
  "languages": ["English", "Hindi", "Tamil"],
  "customer_group": ["VIP", "Regular", "Premium", "Enterprise", "Gold"],
  "pos_tender_modes": ["Cash", "Credit Card", "Debit Card", "Mobile Payment"],
  "payment_types": ["Cash and Carry", "Credit"],
  "payment_methods": ["Bank Transfer", "Cash", "Cheque"],
  "asset_location": ["Store Floor", "Warehouse", "Back Office"],
  "asset_category": ["Electronics", "Furniture", "Equipment"],
  "stock_bin_location": ["A1-01", "B2-15", "C3-07", "Receiving"],
  "branch_types": ["Flagship", "Outlet", "Pop-up", "Franchise"],
  "expense_types": ["Travel", "Office Supplies"],
  "uom_conversions": [
    {
      "base_uom": "g",
      "conversions": [
        {
          "alt_uom": "kg",
          "factor": 1000.0,
          "description": "1 kg = 1000 g"
        }
      ]
    },
    {
      "base_uom": "ml",
      "conversions": [
        {
          "alt_uom": "L",
          "factor": 1000.0,
          "description": "1 L = 1000 ml"
        },
        {
          "alt_uom": "bottle",
          "factor": 650.0,
          "description": "650 ml bottle"
        }
      ]
    }
  ],
  "is_delete": false
}
```

### Response

```json
{
  "success": true,
  "message": "Taxonomy operation completed successfully",
  "data": {
    "taxonomy_id": "uuid-string",
    "operation": "create",
    "merchant_id": "company_cuatro_beauty_ltd",
    "modified_count": 1
  },
  "timestamp": "2025-12-12T10:30:00Z"
}
```

---

## 2. List Taxonomy Data

**Endpoint:** `POST /taxonomy/list`

**Description:** List taxonomy data with optional projection and filtering. Follows SCM API standards with projection_list support for performance optimization.

### Request Body Examples

#### Complete Data (No Projection)
```json
{
  "taxonomy_type": null,
  "projection_list": null
}
```

#### With Projection (Performance Optimized)
```json
{
  "taxonomy_type": null,
  "projection_list": ["merchant_id", "brands", "categories", "job_role", "created_at"]
}
```

#### Filtered by Taxonomy Type
```json
{
  "taxonomy_type": "brands",
  "projection_list": null
}
```

#### Combined Projection + Filtering
```json
{
  "taxonomy_type": "categories",
  "projection_list": ["merchant_id", "categories", "created_at"]
}
```

### Response Examples

#### Complete Data Response
```json
{
  "success": true,
  "message": "Taxonomy data retrieved successfully",
  "data": {
    "id": "uuid-string",
    "merchant_id": "company_cuatro_beauty_ltd",
    "taxonomies": {
      "brands": ["L'Oréal Professional", "Schwarzkopf", "Kerastase"],
      "categories": ["Hair", "Skin", "Nails", "Spa", "Makeup"],
      "lines": ["Hair Care", "Hair Styling", "Facials"],
      "classes": ["Premium", "Luxury", "Basic", "VIP"],
      "subcategories": {
        "Hair": ["Hair Cut", "Hair Color", "Hair Spa"],
        "Skin": ["Clean-up", "Facial", "De-Tan"]
      },
      "job_role": ["Senior Stylist", "Director"],
      "specializations": ["Hairdresser", "Nail technician"],
      "languages": ["English", "Hindi", "Tamil"],
      "customer_group": ["VIP", "Regular", "Premium"],
      "pos_tender_modes": ["Cash", "Credit Card", "Debit Card"],
      "payment_types": ["Cash and Carry", "Credit"],
      "payment_methods": ["Bank Transfer", "Cash", "Cheque"],
      "asset_location": ["Store Floor", "Warehouse", "Back Office"],
      "asset_category": ["Electronics", "Furniture", "Equipment"],
      "stock_bin_location": ["A1-01", "B2-15", "C3-07"],
      "branch_types": ["Flagship", "Outlet", "Pop-up", "Franchise"],
      "expense_types": ["Travel", "Office Supplies"],
      "uom_conversions": [...]
    },
    "created_at": "2025-08-19T09:50:11.927Z",
    "updated_at": "2025-12-12T06:31:08.509Z"
  },
  "metadata": {
    "merchant_id": "company_cuatro_beauty_ltd",
    "taxonomy_type": null,
    "projection_applied": false,
    "timestamp": "2025-12-12T10:30:00Z"
  }
}
```

#### Projected Data Response
```json
{
  "success": true,
  "message": "Taxonomy data retrieved successfully",
  "data": [
    {
      "merchant_id": "company_cuatro_beauty_ltd",
      "brands": ["L'Oréal Professional", "Schwarzkopf", "Kerastase"],
      "categories": ["Hair", "Skin", "Nails", "Spa", "Makeup"],
      "job_role": ["Senior Stylist", "Director"],
      "created_at": "2025-08-19T09:50:11.927Z"
    }
  ],
  "metadata": {
    "merchant_id": "company_cuatro_beauty_ltd",
    "taxonomy_type": null,
    "projection_applied": true,
    "timestamp": "2025-12-12T10:30:00Z"
  }
}
```

#### Filtered by Type Response
```json
{
  "success": true,
  "message": "Taxonomy data retrieved successfully",
  "data": [
    {
      "id": "uuid-string",
      "merchant_id": "company_cuatro_beauty_ltd",
      "taxonomy_type": "brands",
      "data": ["L'Oréal Professional", "Schwarzkopf", "Kerastase", "Olaplex"],
      "created_at": "2025-08-19T09:50:11.927Z",
      "updated_at": "2025-12-12T06:31:08.509Z"
    }
  ],
  "metadata": {
    "merchant_id": "company_cuatro_beauty_ltd",
    "taxonomy_type": "brands",
    "projection_applied": false,
    "timestamp": "2025-12-12T10:30:00Z"
  }
}
```

---

## 3. Get Taxonomy by ID

**Endpoint:** `GET /taxonomy/{taxonomy_id}`

**Description:** Retrieve a specific taxonomy document by its unique identifier.

### Response
```json
{
  "success": true,
  "message": "Taxonomy document retrieved successfully",
  "data": {
    "id": "uuid-string",
    "merchant_id": "company_cuatro_beauty_ltd",
    "brands": ["L'Oréal Professional", "Schwarzkopf"],
    "categories": ["Hair", "Skin", "Nails"],
    // ... all taxonomy fields
    "created_at": "2025-08-19T09:50:11.927Z",
    "updated_at": "2025-12-12T06:31:08.509Z"
  },
  "metadata": {
    "taxonomy_id": "uuid-string",
    "merchant_id": "company_cuatro_beauty_ltd",
    "timestamp": "2025-12-12T10:30:00Z"
  }
}
```

---

## 4. Delete Taxonomy Values

**Endpoint:** `POST /taxonomy/`

**Description:** Delete specific values from taxonomy fields using the `is_delete` flag.

### Request Body
```json
{
  "brands": ["Brand to Delete", "Another Brand"],
  "categories": ["Category to Remove"],
  "expense_types": ["Expense Type to Remove"],
  "is_delete": true
}
```

### Response
```json
{
  "success": true,
  "message": "Taxonomy delete completed successfully",
  "data": {
    "taxonomy_id": "uuid-string",
    "operation": "delete",
    "merchant_id": "company_cuatro_beauty_ltd",
    "modified_count": 1
  },
  "timestamp": "2025-12-12T10:30:00Z"
}
```

---

## 5. Delete Entire Taxonomy

**Endpoint:** `DELETE /taxonomy/{taxonomy_id}`

**Description:** Delete an entire taxonomy document.

### Response
```json
{
  "success": true,
  "message": "Taxonomy entry deleted successfully",
  "data": {
    "taxonomy_id": "uuid-string",
    "merchant_id": "company_cuatro_beauty_ltd",
    "deleted_by": "user_id"
  }
}
```

---

## 6. UOM Conversions Management

### Delete UOM Conversions

**Endpoint:** `DELETE /taxonomy/uom-conversions/{base_uom}`

**Description:** Delete UOM conversion entries. Can delete entire UOM group or specific conversion.

#### Delete Entire UOM Group
```json
{
  "alt_uom": null
}
```

#### Delete Specific Conversion
```json
{
  "alt_uom": "kg"
}
```

### Response
```json
{
  "success": true,
  "message": "UOM conversion deleted successfully",
  "data": {
    "base_uom": "g",
    "alt_uom": "kg",
    "merchant_id": "company_cuatro_beauty_ltd",
    "modified_count": 1,
    "deleted_by": "user_id"
  }
}
```

---

## Performance Optimization

### Projection List Benefits

Using projection lists can provide significant performance improvements:

- **Payload Size Reduction**: 50-90% reduction in response size
- **Network Bandwidth**: Reduced data transfer
- **Database I/O**: Less data read from MongoDB
- **Client Processing**: Faster JSON parsing

### Example Performance Comparison

```bash
# Full data query (all fields)
POST /taxonomy/list
{
  "projection_list": null
}
# Response size: ~15KB

# Projected query (3 fields only)
POST /taxonomy/list
{
  "projection_list": ["merchant_id", "brands", "categories"]
}
# Response size: ~2KB (87% reduction)
```

---

## Error Handling

### Common Error Responses

#### Validation Error
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid projection fields: invalid_field",
    "details": {
      "invalid_fields": ["invalid_field"],
      "valid_fields": ["brands", "categories", "job_role", ...]
    }
  }
}
```

#### Access Denied
```json
{
  "success": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied for merchant data",
    "details": {
      "merchant_id": "company_cuatro_beauty_ltd",
      "user_id": "user_id"
    }
  }
}
```

#### Not Found
```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Taxonomy document not found",
    "details": {
      "taxonomy_id": "uuid-string",
      "merchant_id": "company_cuatro_beauty_ltd"
    }
  }
}
```

---

## Usage Examples

### 1. Create Complete Taxonomy for Beauty retail

```bash
curl -X POST "https://api.example.com/taxonomy/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brands": ["L'\''Oréal Professional", "Schwarzkopf", "Kerastase"],
    "categories": ["Hair", "Skin", "Nails", "Spa", "Makeup"],
    "subcategories": {
      "Hair": ["Hair Cut", "Hair Color", "Hair Spa"],
      "Skin": ["Clean-up", "Facial", "De-Tan"],
      "Nails": ["Manicure", "Pedicure", "Nail Art"]
    },
    "job_role": ["Senior Stylist", "Director", "Massage therapist"],
    "specializations": ["Hairdresser", "Nail technician", "Esthetician"],
    "languages": ["English", "Hindi", "Tamil"],
    "customer_group": ["VIP", "Regular", "Premium"],
    "pos_tender_modes": ["Cash", "Credit Card", "Mobile Payment"],
    "branch_types": ["Flagship", "Outlet"],
    "expense_types": ["Travel", "Office Supplies"]
  }'
```

### 2. Get Optimized Data for Mobile App

```bash
curl -X POST "https://api.example.com/taxonomy/list" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projection_list": ["brands", "categories", "customer_group"]
  }'
```

### 3. Get Only Service Categories

```bash
curl -X POST "https://api.example.com/taxonomy/list" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "taxonomy_type": "categories"
  }'
```

### 4. Update Expense Types

```bash
curl -X POST "https://api.example.com/taxonomy/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expense_types": ["Marketing", "Training", "Equipment Maintenance"]
  }'
```

---

## Best Practices

### 1. Use Projection Lists
Always use projection lists when you don't need all taxonomy data:
```json
{
  "projection_list": ["brands", "categories", "job_role"]
}
```

### 2. Filter by Taxonomy Type
When working with specific taxonomy categories:
```json
{
  "taxonomy_type": "brands"
}
```

### 3. Combine Projection and Filtering
For maximum performance optimization:
```json
{
  "taxonomy_type": "categories",
  "projection_list": ["merchant_id", "categories", "created_at"]
}
```

### 4. Batch Updates
Group related updates in single requests:
```json
{
  "brands": ["New Brand 1", "New Brand 2"],
  "categories": ["New Category"],
  "expense_types": ["New Expense Type"]
}
```

### 5. Use Meaningful Descriptions for UOM
Always provide clear descriptions for UOM conversions:
```json
{
  "alt_uom": "bottle",
  "factor": 650.0,
  "description": "650 ml bottle (standard retail size)"
}
```

---

## Integration Examples

### Frontend Integration (React)

```javascript
// Fetch taxonomy data for dropdown
const fetchTaxonomyData = async (fields) => {
  const response = await fetch('/api/taxonomy/list', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      projection_list: fields
    })
  });
  
  const data = await response.json();
  return data.data[0]; // Projected data
};

// Usage
const taxonomyData = await fetchTaxonomyData(['brands', 'categories']);
```

### Mobile App Integration (Flutter/Dart)

```dart
Future<Map<String, dynamic>> getTaxonomyData(List<String> fields) async {
  final response = await http.post(
    Uri.parse('$baseUrl/taxonomy/list'),
    headers: {
      'Authorization': 'Bearer $token',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'projection_list': fields,
    }),
  );
  
  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    return data['data'][0];
  }
  throw Exception('Failed to load taxonomy data');
}
```

---

## Monitoring and Analytics

The taxonomy system provides comprehensive monitoring capabilities:

### Health Check
```bash
GET /taxonomy/health
```

### Monitoring Dashboard
```bash
GET /taxonomy/monitoring
```

### Key Metrics Tracked
- Operation counts (create, update, delete, list)
- Performance metrics (response times, payload sizes)
- Error rates and types
- Projection usage statistics
- Most requested taxonomy types

---

This complete implementation provides a robust, scalable, and performant taxonomy management system that handles all the categories from your JSON structure while following SCM API standards and best practices.