# Stage Transition History

## Overview

Every time an item moves from one stage to another, a PipelineStageTransition record is created. Stores itemId, fromStageId, toStageId, movedByUserId, and createdAt timestamp. These records are append-only (immutable). Used for KPI calculation such as cycle time, stage duration, and conversion rate.

## Business Purpose

Provide an audit trail for all pipeline movements. Enable analytics including average days per stage, conversion rates, and bottleneck detection. Support compliance requirements for traceability of workflow changes.

## Process Flow

```mermaid
flowchart TD
    A[MovePipelineItem Command] --> B{Same PipelineStage?}
    B -->|Yes| C[Return SAME_STAGE — No Transition Recorded]
    B -->|No| D[Create PipelineStageTransition Record]
    D --> E[Record fromStage, toStage, user, timestamp]
    E --> F[Transition Available for Query]
    F --> G[Analytics: Cycle Time]
    F --> H[Analytics: Conversion Rate]
    F --> I[Audit Trail]
```

## Scenario Patterns

- An operator drags an item from one stage to the next — a transition record is created with the operator's userId and current timestamp
- A manager reviews how long items stay in each stage by querying transition timestamps and computing durations
- Calculate conversion rate from the first stage to the last by counting transitions through each stage

## Test Cases

- Moving item between stages creates a transition record
- Transition records are immutable — cannot be updated or deleted
- Transition includes movedBy user ID and timestamp
- Moving to the same stage is rejected with SAME_STAGE — no transition recorded
- Querying transitions by item returns results ordered by createdAt

## Reference Links

- [Odoo CRM Pipeline Analysis](https://www.odoo.com/documentation/19.0/applications/sales/crm.html)
