# Configurable Stages

## Overview

Stages are ordered steps within a pipeline. Each stage has a name, position (integer for ordering), category (NOT_STARTED/IN_PROGRESS/DONE/CANCELED), and optional color. Stages are per-pipeline, not global. Position determines visual ordering in the pipeline view.

Stage mutation is guarded at the pipeline level: all four stage-mutating commands (create/update/delete/reorder) are rejected with PIPELINE_LOCKED on a locked (managed) pipeline, and new stages cannot be added to an ARCHIVED pipeline (PIPELINE_ARCHIVED).

## Business Purpose

Let teams define their own workflow steps without code changes. Support reordering stages as processes evolve. Categorize stages for cross-pipeline reporting — all "DONE" stages count as completed regardless of their display name.

## Process Flow

```mermaid
flowchart TD
    A[Select Pipeline] --> B[Create PipelineStage]
    B --> C{Valid?}
    C -->|Yes| D[Save PipelineStage with Position]
    C -->|No| E[Return Validation Error]
    D --> F[PipelineStage Available on Pipeline]
    F --> G[Reorder Stages]
    F --> H[Update Name/Category/Color]
    F --> I[Delete PipelineStage]
    I --> J{Items in PipelineStage?}
    J -->|Yes| K[Block Deletion]
    J -->|No| L[Remove PipelineStage]
```

## Scenario Patterns

- Add a "Review" stage between "In Progress" and "Done" by assigning an intermediate position value
- Remove an unused stage that has no items assigned to it
- Reorder stages by updating position values to reflect a revised process
- Mark a stage as category DONE so it counts toward completion metrics in cross-pipeline reports

## Test Cases

- Creating stage with valid name and position succeeds
- PipelineStage name must be unique within the same pipeline
- Deleting a stage that has any items (regardless of lifecycle) fails with a constraint error
- PipelineStage-mutating commands are rejected on a locked pipeline
- Reordering stages updates position values correctly
- PipelineStage category must be one of NOT_STARTED, IN_PROGRESS, DONE, or CANCELED

## Reference Links

- [Odoo Project Stages](https://www.odoo.com/documentation/19.0/applications/services/project.html)
