# Item Taxonomy

## Overview

Item Taxonomy organizes items using a structured, hierarchical classification system. Taxonomy nodes form a tree where each node can have a parent, creating multi-level classification (e.g., "Electronics > Computers > Laptops"). Items are linked to taxonomy nodes through a many-to-many relationship, allowing a single item to belong to multiple classification branches simultaneously (e.g., both "Electronics > Smartphones" and "Gift Ideas > Tech Gifts").

## Business Purpose

As item catalogs grow, a single flat category structure is insufficient. Item Taxonomy addresses this by:

- Enabling multi-dimensional item classification — an item can belong to multiple taxonomy branches
- Supporting hierarchical browsing and filtering of large item catalogs
- Enabling consistent item grouping for operations and reporting
- Organizing items for different audiences (internal operations, eCommerce, procurement)
- Providing a flexible foundation for future classification needs without restructuring existing data
- Stable node identification via globally unique code for API references and integrations

## Process Flow

```mermaid
flowchart TD
    A[Create Root Taxonomy Node] --> B[Create Child Node]
    B --> C{More Levels?}
    C -->|Yes| B
    C -->|No| D[Assign Items to Taxonomy Nodes]
    D --> E{Move Node?}
    E -->|Yes| F[Validate No Circular Reference]
    F --> G[Update Parent]
    G --> H[Children Move With Parent]
    E -->|No| I{Delete Node?}
    I -->|Yes| J{Has Children or Item Assignments?}
    J -->|Yes| K[Block Deletion]
    J -->|No| L[Delete Node]
    I -->|No| M[Node Active]
```

## Scenario Patterns

- **Initial Taxonomy Setup**: Administrator creates root nodes with unique codes (e.g., "electronics", "clothing") and populates child nodes for each classification branch
- **Deep Hierarchy**: "Clothing > Men > Outerwear > Jackets > Winter Jackets" — five levels deep for detailed classification
- **Multi-Classification**: A "Bluetooth Headset" item is assigned to both "Electronics > Audio" and "Accessories > Travel" taxonomy nodes simultaneously
- **Node Reparenting**: "Accessories" node moved from under "Clothing" to a root-level node, all child nodes and item assignments preserved
- **Taxonomy Standards**: "Electronics" node groups items such as laptops, monitors, and accessories under a common branch for operational consistency
- **Node Rename**: Administrator renames "Accessories" to "Travel Accessories" to better reflect the node's contents — child nodes and item assignments are unaffected
- **Node Merge**: Two similar nodes consolidated by moving item assignments from one to the other, then deleting the empty node
- **Reporting by Taxonomy**: Sales report grouped by top-level taxonomy node shows revenue breakdown across item groups (cross-module dependency: reporting/analytics module consumes taxonomy hierarchy)

## Test Cases

- Node code must be globally unique across all taxonomy nodes
- Node code is immutable after creation; only the display name can be updated
- Moving a node under its own descendant should fail (circular reference prevention)
- Deleting a node with child nodes should be blocked
- Deleting a node with assigned items should be blocked
- Root nodes have no parent (null parent reference)
- An item can be assigned to multiple taxonomy nodes
- Removing an item-taxonomy assignment does not affect the item or other assignments
- Duplicate item-taxonomy assignments (same item + same node) should be rejected
- Node tree depth should have a configurable maximum to prevent excessively deep hierarchies

## Reference Links

- [Akeneo Product Classification](https://docs.akeneo.com/serenity-2025-02/articles/manage-your-categories.html)
- [Salsify Taxonomy Management](https://www.salsify.com/resources/content/product-taxonomy-management)
- [Odoo Product Categories](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/inventory/product_management.html)