Stages

📖 Overview

internal/api/v1/crm/services/stage.service.js focuses on per-stage operations: listing stage+automation payloads, adding or updating stage definitions, ensuring stage-level safety during deletions, and aggregating deal totals when bulk edits run. The controllers authorize requests; this service validates pipeline access, interacts with the pipeline model helpers, recalculates deal counts, and formats responses for the dashboard.

🗄️ Collections Used

📚 Full Schema: See Database Collections Documentation

crm.pipeline

• Operations: Fetch pipeline, call helper methods (getStagesWithAutomations, addStage, updateStages, removeStage)
• Model: shared/models/pipeline.js
• Usage Context: Guarantees account ownership before mutating stages

crm.pipeline.stages

• Operations: Read/write via pipeline helper responses
• Model: shared/models/pipeline-stage.js
• Usage Context: Holds stage metadata, automation references, and ordering

crm.deals

• Operations: Aggregations during bulk updates to compute counts and totals per stage
• Model: shared/models/deal.js
• Usage Context: Determines whether stages contain deals (deletion guard) and returns currency-adjusted totals

🔄 Data Flow

flowchart TD
    A[Stage request] --> B{Validate pipeline + account}
    B -->|invalid| Z[400 INVALID_PIPELINE]
    B --> C[pipeline helper (get/add/update/remove)]
    C --> D[cleanRecord + hydrate automations]
    D --> E[Optional deal aggregation]
    E --> F[CurrencyUtil.convert totals]
    F --> G[Response]

    subgraph Delete Guard
        H[Delete request] --> I[Find deals in stage]
        I -->|has deals| Y[400 STAGE_NOT_EMPTY]
        I -->|empty| J[pipeline.removeStage]
        J --> G
    end

🔧 Business Logic & Functions

---

Stage Retrieval

getStage({ id, account_id })

• Loads pipeline stages and automations via getStagesWithAutomations, converts each to plain objects with cleanRecord, and returns the hydrated list.
• Returns a guarded error if no stages exist (a data anomaly) to prompt support intervention.

getOneStage({ id, stage_id, account_id })

• Retrieves a single stage with its automations for edit forms; sanitizes the payload before returning and throws RESOURCE_NOT_FOUND when ids are invalid.

---

Creation & Updates

postStage({ id, account_id, uid, body })

• Validates pipeline scope and delegates to pipeline.addStage, returning the cleaned stage plus hydrated automations.

putStage({ id, account_id, uid, dealFilter, dealQuery, body, currencyCode })

• Performs bulk stage updates (rename, reorder, automation edits). After pipeline mutation it aggregates deals within the pipeline to calculate per-stage counts and currency-converted totals.

updateOneStage({ id, stage_id, account_id, uid, body })

• Updates a single stage via pipeline.updateStage, handles automation validation errors, and returns the cleaned stage.

---

Deletion

deleteOneStage({ id, stage_id, account_id })

• Blocks deletion when any deals remain in the stage, returning STAGE_NOT_EMPTY with actionable guidance.
• Executes pipeline.removeStage once safe, responding with SUCCESS or RESOURCE_NOT_FOUND when the stage is missing.

🔀 Integration Points

Internal Dependencies

• pipeline model helpers for all stage CRUD
• generateFilterObj to align stage bulk updates with deal filters from the UI
• CurrencyUtil for summarizing deal totals in the account currency
• stageUtils.cleanRecord to remove Mongo internals from responses
• logger to capture pipeline helper errors

External Services

• None—stage service only touches Mongo collections and shared utilities.

🧪 Edge Cases & Special Handling

• Pipeline ownership: Every entry point validates _id + account_id before running helpers.
• Bulk update filters: When deal filters include search terms, the service rebuilds regex matchers to align with deal list behaviour.
• Currency totals: Deal totals are recalculated after every bulk update so UI widgets remain accurate.
• Automation validation: INVALID_AUTOMATION_UPDATE bubbles through untouched so the UI can refresh stale payloads.

⚠️ Important Notes

• 🧱 Stage deletions are irreversible—ensure clients warn users before calling deleteOneStage.
• 🔁 Always refresh pipeline data after bulk updates; ordering and totals may shift.
• 🔐 Respect visibility rules upstream. Stage service assumes the controller already validated user scope.

🔗 Related Documentation

• 🔄 Pipelines
• 💼 Deals
• 🤖 Automation