Quotation Workflows

1. Feature Descripción General

The quotation system enables itemized cost breakdowns with multi-level approvals, margin application, and client transparency. Following the strategic decision from Sprint 5-6 mesa de trabajo, quotations are itemized (not global totals) to provide client traceability, protect Algesta’s competitive advantage by hiding provider costs, and enable flexible margin application per item or category. The workflow spans from agent-created item structures through provider pricing, agent inflation (margin), multi-level client approval, and rejection/rework cycles, with Completo audit trails and notification integration at each step.

2. Business Context

Clients required detailed cost breakdowns to understand what they’re paying for and validate reasonableness, while Algesta needed to protect provider pricing (competitive intelligence) and apply margins for profitability. The previous global quotation model lacked transparency and made cost validation difficult. Itemized quotations address both needs: clients see “what + how much,” providers get fair compensation, and Algesta maintains pricing control through inflation while preserving competitive positioning by not exposing provider costs to clients.

3. Strategic Decision: Itemized Quotation (Sprint 5-6 Mesa de Trabajo)

Rationale

Requisitos:

Client traceability: “I want to know what I’m paying for”
Cost validation: Ability to challenge specific line items
Competitive advantage: Don’t expose provider costs to clients

Solution: Itemized Quotation with Inflation

Structure:

Agent Creates Items: Materials, labor, transport, parts, equipment
Provider Prices Items: Unit price per item
Agent Reviews/Adjusts: Can modify items before inflation
Agent Applies Margin: Percentage or manual per item
Client Sees Final Prices: Provider costs hidden, only final prices visible

Impact:

Transparency for clients (itemized breakdown)
Profitability for Algesta (controlled margins)
Fair compensation for providers (no undercutting)
Competitive protection (provider costs not visible to clients)

4. Quotation Workflow

flowchart TD
    A[Provider Selected] --> B[Agent Creates Item Structure]
    B --> C[Define Items: Materials, Labor, Transport, Parts, Equipment]
    C --> D[Send to Provider for Pricing]
    D --> E[Provider Fills Unit Prices]
    E --> F{Provider Submits Quotation}
    F --> G[Agent Reviews Quotation]
    G --> H{Items Acceptable?}
    H -->|No| I[Agent Adjusts Items]
    I --> C
    H -->|Yes| J[Agent Applies Margin]
    J --> K[Calculate Inflated Prices]
    K --> L[Preview: Original vs Final]
    L --> M{Agent Approves Inflation?}
    M -->|No| J
    M -->|Yes| N[Send to Client for Approval]
    N --> O{Multi-Level Approval}
    O --> P[Requester Reviews]
    P --> Q{Requester Approves?}
    Q -->|No| R[Rejection with Reason]
    Q -->|Yes| S[Approver 1 Reviews]
    S --> T{Approver 1 Approves?}
    T -->|No| R
    T -->|Yes| U[Approver 2 Reviews]
    U --> V{Approver 2 Approves?}
    V -->|No| R
    V -->|Yes| W[Quotation Approved]
    R --> X[Notify Provider for Revision]
    X --> E
    W --> Y[Proceed to Contract Signing]

5. User Stories by Sprint

Sprint 5: Quotation Reports and Basic Structure

US-S5-010: Provider Submits Quotation

Descripción: As a provider, I want to submit a quotation after being selected so the order can proceed
Acceptance Criteria:
- Quotation form with: total cost, estimated duration, breakdown (materials, labor, other), comments
- Quotation submitted to agent for review
- State changes to “CotizacionEnviada”
- Agent receives notification
Estado: ✅ Completo
Implementación:
- algesta-ms-orders-nestjs/src/application/handlers/commands/send-quote.handler.ts - Send quotation
- algesta-ms-orders-nestjs/src/shared/dtos/send-quote.dto.ts - Quotation DTO
API: POST /api/orders/:id/quotation - Submit quotation

US-S5-011: Client Approves Quotation

Descripción: As a client, I want to review and approve the quotation so work can begin
Acceptance Criteria:
- Client receives email with quotation link
- View quotation details (cost breakdown, timeline)
- Approve or reject with comments
- If approved, state changes to “CotizacionAprobada”
- If rejected, state changes to “CotizacionRechazada”
- Provider notified of decision
Estado: ✅ Completo
Implementación:
- algesta-dashboard-react/src/Funcionalidades/clients/api/quotation-accept.ts - Approval API
API:
- POST /api/orders/:id/approve-quotation - Approve quotation
- POST /api/orders/:id/reject-quotation - Reject quotation

Sprint 6: Itemized Structure

US-S6-020: Agent Creates Itemized Structure

Descripción: As an agent, I want to create an itemized quotation structure for providers to fill
Acceptance Criteria:
- Create items with: Descripción, quantity, unit, category
- Categories: MATERIAL, LABOR, TRANSPORT, PART, EQUIPMENT, OTHER
- Add/remove items dynamically
- Send structure to provider
- Provider fills unit prices
- System calculates subtotals automatically
Estado: ✅ Completo
Implementación:
- algesta-ms-provider-nestjs/src/application/handlers/commands/auction/create-dynamic-items.handler.ts - Create items
API: POST /api/auctions/:auctionId/items - Create items structure

US-S6-021: Provider Prices Items

Descripción: As a provider, I want to fill unit prices for each item in the quotation structure
Acceptance Criteria:
- View items with: Descripción, quantity, unit
- Enter unit price for each item
- System calculates subtotal (quantity × unit price)
- System calculates grand total
- Save draft and continue later
- Submit when Completo
Estado: ✅ Completo
Implementación:
- Provider portal UI for item pricing
API: POST /api/auctions/:auctionId/offers/:offerId/items - Price items

Sprint 7-8: Inflation and Multi-Level Approval

US-S8-030: Agent Applies Margin (Inflation)

Descripción: As an agent, I want to apply a margin to provider’s quotation before sending to client
Acceptance Criteria:
- View provider’s itemized quotation
- Apply percentage margin (e.g., 15%) to all items
- OR apply manual adjustment per item
- Preview: original unit price, margin, final unit price
- Calculate final subtotals and grand total
- Save inflated quotation
- Client sees only final prices (provider costs hidden)
Estado: ✅ Completo
Implementación:
- algesta-ms-provider-nestjs/src/application/handlers/commands/auction/create-offer-inflation.handler.ts - Apply inflation
- algesta-dashboard-react/src/Funcionalidades/marketplace/auction/hooks/use-inflate-quotation-state.ts - Inflation UI
API: POST /api/auctions/:auctionId/offers/:offerId/inflate - Apply margin

US-S8-031: Multi-Level Approval

Descripción: As a client admin, I want quotations to require multiple approvers for compliance
Acceptance Criteria:
- Configure approval levels: Requester, Approver 1, Approver 2
- Quotation sent to Requester first
- If Requester approves, sent to Approver 1
- If Approver 1 approves, sent to Approver 2
- Only after all approvers approve, quotation is fully approved
- Any approver can reject, triggering rework
- Approval chain tracked in order history
Estado: 🟡 En Progreso (basic approval implemented, multi-level Pendiente refinement)
API:
- POST /api/orders/:id/approve-quotation?approver=requester - Requester approval
- POST /api/orders/:id/approve-quotation?approver=approver1 - Approver 1 approval
- POST /api/orders/:id/approve-quotation?approver=approver2 - Approver 2 approval

6. Quotation Data Model

Quotation Structure

Field	Type	Description
`_id`	ObjectId	Unique identifier
`orderId`	ObjectId	Related order
`providerId`	ObjectId	Provider who submitted
`items`	Array	Itemized breakdown
`totalCost`	Number	Grand total (sum of items)
`estimatedDuration`	Number	Days to Completo
`comments`	String	Provider notes
`Estado`	Enum	DRAFT, SUBMITTED, APPROVED, REJECTED
`inflationApplied`	Boolean	Whether margin applied
`inflationPercentage`	Number	Overall margin %
`submittedAt`	Date	When submitted
`approvedAt`	Date	When approved
`approvalChain`	Array	Multi-level approval tracking

QuotationItem Sub-Documento

Field	Type	Description
`Descripción`	String	Item Descripción
`quantity`	Number	Quantity required
`unit`	String	Unit of measurement (e.g., unit, m², hour, kg)
`category`	Enum	MATERIAL, LABOR, TRANSPORT, PART, EQUIPMENT, OTHER
`providerUnitPrice`	Number	Price from provider (hidden from client)
`inflatedUnitPrice`	Number	Price shown to client (providerUnitPrice + margin)
`margin`	Number	Algesta margin (amount or percentage)
`subtotal`	Number	quantity × inflatedUnitPrice

Approval Sub-Documento

Field	Type	Description
`approverId`	ObjectId	User who approved/rejected
`approverRole`	Enum	REQUESTER, APPROVER1, APPROVER2
`decision`	Enum	APPROVED, REJECTED
`timestamp`	Date	When decision made
`comments`	String	Approval/rejection reason

7. Item Categories

Category	Description	Examples
MATERIAL	Physical materials used	Pipes, cables, insulation, paint, cement
LABOR	Human work hours	Technician hours, specialist hours
TRANSPORT	Transportation costs	Freight, delivery, equipment rental
PART	Replacement parts	Valves, switches, motors, bearings
EQUIPMENT	Equipment rental	Crane, scaffolding, compressor
OTHER	Miscellaneous	Permits, insurance, disposal fees

8. Approval Levels

Three-Tier Approval Model

stateDiagram-v2
    [*] --> PendingRequester: Quotation sent to client
    PendingRequester --> RequesterApproved: Requester approves
    PendingRequester --> Rejected: Requester rejects
    RequesterApproved --> PendingApprover1: Sent to Approver 1
    PendingApprover1 --> Approver1Approved: Approver 1 approves
    PendingApprover1 --> Rejected: Approver 1 rejects
    Approver1Approved --> PendingApprover2: Sent to Approver 2
    PendingApprover2 --> FullyApproved: Approver 2 approves
    PendingApprover2 --> Rejected: Approver 2 rejects
    FullyApproved --> [*]
    Rejected --> ProviderRevision: Provider revises quotation
    ProviderRevision --> PendingRequester: Resubmit

Approval Roles

Role	Description	Permissions
Requester	User who initiated the order	Review quotation, approve/reject
Approver 1	First-level manager	Review if requester approved, approve/reject
Approver 2	Second-level manager (CFO, Operaciones Director)	Final approval, approve/reject

Note: Multi-level approval is configurable per client. Some clients require all 3 levels, others may require only 2 or 1.

9. Inflation/Margin Application

Margin Calculation

interface InflationOptions {
  method: 'percentage' | 'manual';
  percentage?: number; // e.g., 15 for 15%
  manualAdjustments?: Map<itemId, marginAmount>;
}

function applyInflation(items: QuotationItem[], options: InflationOptions): QuotationItem[] {
  return items.map(item => {
    let margin: number;

    if (options.method === 'percentage') {
      margin = item.providerUnitPrice * (options.percentage / 100);
    } else {
      margin = options.manualAdjustments.get(item._id) || 0;
    }

    return {
      ...item,
      margin: margin,
      inflatedUnitPrice: item.providerUnitPrice + margin,
      subtotal: item.quantity * (item.providerUnitPrice + margin)
    };
  });
}

Inflation Métodos

Automatic Percentage: Apply fixed % to all items (e.g., 15%)
Manual Per Item: Adjust margin for each item individually
Category-Based: Different % per category (e.g., 20% for materials, 10% for labor)
Hybrid: Automatic % as baseline, manual adjustments for specific items

10. Client View

What Client Sees

Quotation for Order ORD-2025-001
Provider: [Provider Name]
Date: 2025-01-15

Items:
| Category | Description | Qty | Unit | Unit Price | Subtotal |
|----------|-------------|-----|------|------------|----------|
| Material | PVC Pipe 2" | 10 | m | $12.50 | $125.00 |
| Labor | Technician Hour | 8 | hour | $45.00 | $360.00 |
| Transport | Freight | 1 | trip | $50.00 | $50.00 |
| Part | Ball Valve 2" | 2 | unit | $35.00 | $70.00 |

Grand Total: $605.00
Estimated Duration: 2 days

What Client DOES NOT See:

Provider’s original unit prices (e.g., PVC Pipe was $10, Algesta added $2.50 margin)
Algesta’s margin percentage
Provider’s profit margin

Rationale: Protects Algesta’s competitive advantage and provider pricing

11. Rejection and Rework Flow

sequenceDiagram
    participant Client
    participant Gateway
    participant OrdersMS
    participant ProviderMS
    participant NotificationsMS
    participant Provider

    Client->>Gateway: POST /api/orders/:id/reject-quotation
    Gateway->>OrdersMS: RejectQuotationCommand
    OrdersMS->>OrdersMS: Update state to CotizacionRechazada
    OrdersMS->>OrdersMS: Create OrderHistory record
    OrdersMS->>NotificationsMS: Notify agent and provider
    NotificationsMS->>Provider: Email: "Quotation rejected: [reason]"

    Provider->>ProviderMS: Review rejection reason
    Provider->>ProviderMS: Adjust items/prices
    Provider->>Gateway: POST /api/orders/:id/quotation (revised)
    Gateway->>OrdersMS: SendQuoteCommand
    OrdersMS->>OrdersMS: Update state to CotizacionEnviada
    OrdersMS->>NotificationsMS: Notify agent (revised quotation)

    Note over OrdersMS,Client: Agent reviews, applies inflation, sends to client again

    Client->>Gateway: POST /api/orders/:id/approve-quotation
    Gateway->>OrdersMS: ApproveQuotationCommand
    OrdersMS->>OrdersMS: Update state to CotizacionAprobada
    OrdersMS->>NotificationsMS: Notify all parties

12. API Endpoints Resumen

Endpoint	Método	Description	Actor	Sprint
`/api/orders/:id/quotation`	POST	Submit quotation	Provider	S5
`/api/orders/:id/approve-quotation`	POST	Approve quotation	Client	S5
`/api/orders/:id/reject-quotation`	POST	Reject quotation	Client	S5
`/api/auctions/:auctionId/items`	POST	Create items structure	Agent	S6
`/api/auctions/:auctionId/offers/:offerId/items`	POST	Price items	Provider	S6
`/api/auctions/:auctionId/offers/:offerId/inflate`	POST	Apply margin	Agent	S8
`/api/orders/:id/quotation/:quotationId`	GET	Get quotation details	Agent/Client	S5
`/api/orders/:id/quotation/:quotationId/pdf`	GET	Export quotation to PDF	Client	S7

13. Integration Points

Orders Service: Quotation lifecycle tied to order states
Provider Service: Provider quotation submission
Notifications Service: Email notifications for submissions, approvals, rejections
DocuSign: Contract signing after quotation approval

14. Pruebas Evidence

From Pruebas notes:

Sprint 5: Quotation submission and approval flows validated
Sprint 6: Itemized structure creation and pricing validated
Sprint 8: Inflation flow tested (bugs identified and being addressed)

15. Known Issues and Future Enhancements

🟧 Critical Issues

Quotation Inflation Flow Bugs: Edge cases in margin calculation identified in Sprint 8 review

🟨 Essential Improvements

Quotation Templates: Pre-defined item templates for common service types
Automatic Margin Rules: Configure default margins per category or client
Historical Pricing Analysis: Help agents validate offer reasonableness based on past quotations

🟩 Post-MVP

Dynamic Pricing: Adjust margins based on market conditions, provider performance
Quotation Comparison: Compare multiple revised quotations side-by-side
Client Budget Tracking: Alert if quotation exceeds client’s pre-approved budget

16. Referencias Cruzadas

Sprint Documentoation

Sprint 5, 6, 8 Documentoation - see docs/Sprint_5.md, Sprint_6.md, Sprint_8.md in project Repositorio

Last Updated: 2025-11-20 | Next Review: End of Guarantee Phase