Deals

📖 Overview

internal/api/v1/crm/services/deal.service.js manages every interaction a deal has with a pipeline. It validates pipeline scope, enforces owner/follower visibility, calculates totals with currency conversion, applies tag and DND rules, and orchestrates automation skip/retry flows. Controllers only validate payloads—this service runs all Mongo aggregations, expansion helpers, JSON export, and audit handling.

🗄️ Collections Used

📚 Full Schema: See Database Collections Documentation

crm.deals

• Operations: Heavy read/write, aggregations, CSV export source
• Model: shared/models/deal.js
• Usage Context: Stores deal core data, attachments, automation state, visibility flags

crm.pipeline

• Operations: Lookups and helper methods (getDeals, addDeal, updateDeals)
• Model: shared/models/pipeline.js
• Usage Context: Validates account scope and delegates stage-aware mutations

crm.pipeline.stages

• Operations: Aggregated for stage sorting and stats
• Model: shared/models/pipeline-stage.js
• Usage Context: Provides ordering when sorting by stage name

crm.automations

• Operations: Read during automation skip/retry validation
• Model: shared/models/automation.js
• Usage Context: Ensures overrides target a stage+pipeline automation that exists

crm.automation.logs

• Operations: Lookups to confirm retry eligibility
• Model: shared/models/automation-log.js
• Usage Context: Guards retryAutomationDeal so only failed runs can be retried

crm.dnd

• Operations: Read while hydrating deals
• Model: shared/models/dnd.js
• Usage Context: Marks deals with contact-level email/SMS suppression status

🔄 Data Flow

flowchart TD
    A[Request] --> B{Validate pipeline + access}
    B -->|invalid| Z[400 INVALID_PIPELINE]
    B --> C[generateFilterObj + build query]
    C --> D[Deal.aggregate/search]
    D --> E[setPromises]
    E --> F[expandDeals]
    F --> G[CurrencyUtil.convert]
    G --> H[Attach DND + format attachments]
    H --> I[Response]

    subgraph Mutations
        J[Payload] --> K[validateTags + defaults]
        K --> L[pipeline.addDeal/updateDeals]
        L --> M[expandDeals + CurrencyUtil]
        M --> I
    end

    subgraph Automation Overrides
        N[Skip/Retry request] --> O[Find deal scoped to owner visibility]
        O --> P[Fetch automation + logs]
        P --> Q[Update skip_automations / retry_automations sets]
        Q --> I
    end

    subgraph Export
        R[Export request] --> S[Deal.aggregate + mapFields]
        S --> T[json2csv]
        T --> U[CSV download]
    end

🔧 Business Logic & Functions

---

Listing & Export

searchDeal({ id, account_id, uid, page, limit, q, expand, sortField, sortOrder, filter, is_owner, currencyCode, auth })

• Aggregates deal ids with regex search across core and additional_info values, respecting owner/follower visibility rules.
• Applies pagination and custom stage sorting, hydrates results with setPromises/expandDeals, and converts currency into the account’s preferred unit.
• Returns pagination metadata plus optional expanded associations when expand=true.

getDeal({ id, account_id, uid, page, limit, account, filter, q, sortField, sortOrder, auth, stage_id, currencyCode })

• Delegates to pipeline.getDeals, allowing stage filters and reusable pagination.
• After expansion, converts totals via CurrencyUtil, formats attachments, and surfaces original value/currency for UI diffs.

exportDeal({ id, account_id, uid, q, sortField, sortOrder, filter, expand, is_owner, currencyCode, auth })

• Reuses search filters, then maps expanded deals through mapFields to align with account CSV configuration.
• Streams data through json2csv and returns the raw CSV buffer for controller delivery.

---

Creation & Bulk Mutations

postDeal({ id, account_id, uid, auth, currencyCode, body })

• Validates tag ids, applies defaults (status, currency, owner), and stores total contract value.
• Persists via pipeline.addDeal, expands the result, and converts value into the caller’s currency context.

putDeal({ id, account_id, uid, body, expand, is_owner, auth })

• Performs bulk updates across multiple deals using pipeline helpers, enforcing visibility rules when the caller is not the owner.
• Supports inline expansion of returned deals when expand=true.

updateOneDeal({ id, deal_id, account_id, uid, body, auth, currencyCode })

• Updates a single deal, recalculates totals, remaps custom fields, and returns an expanded payload with converted currency and attachment metadata.

deleteDeal, deleteMultiDeal, deleteOneDeal

• Support pipeline-scoped bulk deletion (deleteDeal), filter-driven mass deletion (deleteMultiDeal), and single deal removal (deleteOneDeal).
• All variants validate pipeline ownership, respect all bulk semantics, and clean references/attachments before returning SUCCESS.

---

Attachments & Metadata

putAttachmentsDeal({ id, deal_id, account_id, auth, body })

• Uses pipeline helper updateDealAttachment to append attachments, returning the updated array.
• Relies on upstream upload middleware—service only persists metadata.

deleteAttachmentDeal({ id, deal_id, attachmentId, account_id, auth })

• Validates deal ownership then removes the embedded attachment document before saving.

---

Automation Overrides

skipAutomationDeal({ id, deal, automation, auth })

• Confirms pipeline scope, visibility, and stage-level ownership before adding the automation id to skip_automations and pruning any pending retries.

retryAutomationDeal({ id, deal, automation, auth })

• Repeats the validation chain, ensures an automation log exists marking the automation as failed, then queues a retry by updating retry_automations.

---

🔀 Integration Points

Internal Dependencies

• pipeline.getDeals, pipeline.addDeal, pipeline.updateDeals, pipeline.updateDealAttachment
• generateFilterObj for advanced filter DSL → Mongo selectors
• dealUtils (setPromises, expandDeals, mapFields, validateTags, checkCsv)
• CurrencyUtil for live conversion and currency metadata
• json2csv for export formatting and logger for error capture

External Services

• None directly. File uploads/cleanup are handled upstream; exports are streamed back to the client.

🧪 Edge Cases & Special Handling

• Owner visibility: Non-owners can only see deals when visibility is all or they are listed as owner/follower; enforcement is consistent across search, list, delete, and automation overrides.
• Custom field search: Search pipelines unwrap additional_info to allow regex queries across dynamic fields.
• DND overlay: During expansion, the service resolves DND flags across related contacts and surfaces an { email, phone } lockout object.
• Contract totals: total_deal_value multiplies value × contract length, ensuring reports respect recurring revenue.
• Automation safety: Skip/retry paths validate both stage ownership and prior automation state to prevent accidental replays.

⚠️ Important Notes

• 🚨 Always validate tags via validateTags before persisting—invalid ids return INVALID_TAGS from the service.
• 💰 Currency conversions require BASE_CURRENCY; missing env configuration will trigger conversion failures.
• 📤 CSV exports stream raw text—controllers must set headers (text/csv) before piping back to clients.

🔗 Related Documentation

• 🔄 Pipelines
• ⚙️ Stages
• 🤖 Automation
• 🔖 Tags