{
  "feature": "proposals-quotations",
  "version": "1.0.0",
  "description": "Creation, management, and approval workflow for investment proposals and quotations delivered to clients",
  "category": "data",
  "tags": [
    "proposals",
    "quotations",
    "document-generation",
    "client-communication"
  ],
  "actors": [
    {
      "id": "portfolio_manager",
      "name": "Portfolio Manager",
      "type": "human",
      "role": "Portfolio Manager"
    },
    {
      "id": "pm_assistant",
      "name": "PM Assistant",
      "type": "human",
      "role": "PM Assistant"
    },
    {
      "id": "client",
      "name": "Client",
      "type": "human",
      "role": "Client"
    }
  ],
  "fields": [
    {
      "name": "proposal_id",
      "type": "number",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Proposal ID required"
        }
      ],
      "label": "Proposal Id"
    },
    {
      "name": "crm_number",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "CRM number required"
        },
        {
          "type": "pattern",
          "message": "Invalid CRM format",
          "value": "^[A-Z0-9]{6,}$"
        }
      ],
      "label": "Crm Number"
    },
    {
      "name": "proposal_name",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Proposal name required"
        },
        {
          "type": "maxLength",
          "message": "Max 255 characters",
          "value": 255
        }
      ],
      "label": "Proposal Name"
    },
    {
      "name": "client_id",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Client ID required"
        }
      ],
      "label": "Client Id"
    },
    {
      "name": "first_name",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "First name required"
        }
      ],
      "label": "First Name"
    },
    {
      "name": "last_name",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Last name required"
        }
      ],
      "label": "Last Name"
    },
    {
      "name": "email",
      "type": "email",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Email required"
        },
        {
          "type": "email",
          "message": "Valid email required"
        }
      ],
      "label": "Email"
    },
    {
      "name": "mobile_phone",
      "type": "phone",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Phone required"
        },
        {
          "type": "phone",
          "message": "Valid phone required"
        }
      ],
      "label": "Mobile Phone"
    },
    {
      "name": "identification_number",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "ID number required"
        }
      ],
      "label": "Identification Number"
    },
    {
      "name": "passport_number",
      "type": "text",
      "required": false,
      "validation": [],
      "label": "Passport Number"
    },
    {
      "name": "portfolio_manager_id",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "PM ID required"
        }
      ],
      "label": "Portfolio Manager Id"
    },
    {
      "name": "portfolio_manager_name",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "PM name required"
        }
      ],
      "label": "Portfolio Manager Name"
    },
    {
      "name": "relationship_team_id",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Team ID required"
        }
      ],
      "label": "Relationship Team Id"
    },
    {
      "name": "product_id",
      "type": "number",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Product ID required"
        }
      ],
      "label": "Product Id"
    },
    {
      "name": "product_name",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Product name required"
        }
      ],
      "label": "Product Name"
    },
    {
      "name": "asset_manager_id",
      "type": "number",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Asset manager ID required"
        }
      ],
      "label": "Asset Manager Id"
    },
    {
      "name": "document_id",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Document ID required"
        }
      ],
      "label": "Document Id"
    },
    {
      "name": "document_name",
      "type": "text",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Document name required"
        }
      ],
      "label": "Document Name"
    },
    {
      "name": "status",
      "type": "select",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Status required"
        }
      ],
      "options": [
        {
          "value": "pending",
          "label": "Pending"
        },
        {
          "value": "accepted",
          "label": "Accepted"
        },
        {
          "value": "declined",
          "label": "Declined"
        },
        {
          "value": "expired",
          "label": "Expired"
        },
        {
          "value": "closed",
          "label": "Closed"
        }
      ],
      "label": "Status"
    },
    {
      "name": "client_comment",
      "type": "rich_text",
      "required": false,
      "validation": [
        {
          "type": "maxLength",
          "message": "Max 2000 characters",
          "value": 2000
        }
      ],
      "label": "Client Comment"
    },
    {
      "name": "created_at",
      "type": "datetime",
      "required": true,
      "validation": [
        {
          "type": "required",
          "message": "Created date required"
        }
      ],
      "label": "Created At"
    }
  ],
  "rules": {
    "validation": [
      "Client email must be valid",
      "Client ID required",
      "Product and asset manager must exist",
      "Document required"
    ],
    "permissions": [
      "Client views their proposals",
      "PM creates and manages proposals",
      "PM Assistant supports proposal creation",
      "Client accepts or declines"
    ]
  },
  "states": {
    "field": "status",
    "values": [
      {
        "name": "pending",
        "label": "Pending",
        "initial": true
      },
      {
        "name": "accepted",
        "label": "Accepted",
        "terminal": true
      },
      {
        "name": "declined",
        "label": "Declined",
        "terminal": true
      },
      {
        "name": "expired",
        "label": "Expired",
        "terminal": true
      },
      {
        "name": "closed",
        "label": "Closed",
        "terminal": true
      }
    ]
  },
  "outcomes": {
    "get_current_proposal": {
      "priority": 5,
      "given": [
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Client"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "proposal.retrieved",
          "payload": [
            "proposal_id"
          ]
        }
      ],
      "result": "Returns latest proposal"
    },
    "get_client_proposals": {
      "priority": 6,
      "given": [
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Client"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "proposals.list_retrieved",
          "payload": [
            "client_id"
          ]
        }
      ],
      "result": "Returns all client proposals"
    },
    "get_proposals_for_review": {
      "priority": 7,
      "given": [
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Client"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "eq",
          "value": "pending"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "pending_proposals.retrieved",
          "payload": [
            "client_id"
          ]
        }
      ],
      "result": "Returns pending proposals"
    },
    "get_proposal_with_document": {
      "priority": 8,
      "given": [
        {
          "field": "proposal_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Client"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "proposal_document.retrieved",
          "payload": [
            "proposal_id"
          ]
        }
      ],
      "result": "Returns proposal with document"
    },
    "accept_proposal": {
      "priority": 1,
      "given": [
        {
          "field": "proposal_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "eq",
          "value": "pending"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Client"
        }
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "pending",
          "to": "accepted"
        },
        {
          "action": "set_field",
          "target": "client_action_at",
          "value": "now"
        },
        {
          "action": "set_field",
          "target": "client_comment",
          "value": "from_input"
        },
        {
          "action": "emit_event",
          "event": "proposal.accepted",
          "payload": [
            "proposal_id"
          ]
        }
      ],
      "result": "Proposal accepted"
    },
    "decline_proposal": {
      "priority": 2,
      "given": [
        {
          "field": "proposal_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "eq",
          "value": "pending"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Client"
        }
      ],
      "then": [
        {
          "action": "transition_state",
          "field": "status",
          "from": "pending",
          "to": "declined"
        },
        {
          "action": "set_field",
          "target": "client_action_at",
          "value": "now"
        },
        {
          "action": "set_field",
          "target": "client_comment",
          "value": "from_input"
        },
        {
          "action": "emit_event",
          "event": "proposal.declined",
          "payload": [
            "proposal_id"
          ]
        }
      ],
      "result": "Proposal declined"
    },
    "get_proposal_document": {
      "priority": 20,
      "given": [
        {
          "field": "proposal_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "document_id",
          "source": "db",
          "operator": "exists"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Client"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "document.downloaded",
          "payload": [
            "proposal_id"
          ]
        }
      ],
      "result": "Returns PDF document"
    },
    "generate_mandate_pdf": {
      "priority": 21,
      "given": [
        {
          "field": "onboarding_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Client"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "mandate.generated",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "Returns mandate PDF"
    },
    "complete_onboarding_workflow": {
      "priority": 22,
      "given": [
        {
          "field": "onboarding_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "in",
          "value": [
            "approved",
            "waiting_signature"
          ]
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "eq",
          "value": "Client"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "mandate_signing.initiated",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "eSignature service signing initiated"
    },
    "handle_mandate_signed": {
      "priority": 23,
      "given": [
        {
          "field": "onboarding_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "envelope_status",
          "source": "input",
          "operator": "eq",
          "value": "completed"
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "signed_mandate_doc_job_id",
          "value": "from_envelope"
        },
        {
          "action": "emit_event",
          "event": "mandate.signed",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "Mandate signed"
    },
    "create_proposal": {
      "priority": 30,
      "given": [
        {
          "field": "document_file",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "client_information.identification_number",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "mandate_details.product_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "in",
          "value": [
            "Portfolio Manager",
            "PM Assistant"
          ]
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "validation.duplicate_check",
          "payload": [
            "identification_number"
          ]
        }
      ],
      "result": "Validation performed"
    },
    "create_proposal_success": {
      "priority": 31,
      "given": [
        {
          "field": "document_file",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "client_information",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "mandate_details",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "client_information.identification_number",
          "source": "db",
          "operator": "not_exists"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "in",
          "value": [
            "Portfolio Manager",
            "PM Assistant"
          ]
        }
      ],
      "then": [
        {
          "action": "create_record",
          "type": "proposal",
          "target": "proposal",
          "fields": [
            "crm_number",
            "client_information",
            "status=pending"
          ]
        },
        {
          "action": "emit_event",
          "event": "proposal.created",
          "payload": [
            "proposal_id"
          ]
        }
      ],
      "result": "Proposal created"
    },
    "get_pm_proposals": {
      "priority": 40,
      "given": [
        {
          "field": "client.role",
          "source": "session",
          "operator": "in",
          "value": [
            "Portfolio Manager",
            "PM Assistant"
          ]
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "pm_proposals.list_retrieved",
          "payload": [
            "portfolio_manager_id"
          ]
        }
      ],
      "result": "Returns PM proposals"
    },
    "get_proposal_by_id": {
      "priority": 41,
      "given": [
        {
          "field": "proposal_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "in",
          "value": [
            "Portfolio Manager",
            "PM Assistant"
          ]
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "proposal.retrieved",
          "payload": [
            "proposal_id"
          ]
        }
      ],
      "result": "Returns proposal details"
    },
    "update_proposal": {
      "priority": 42,
      "given": [
        {
          "field": "proposal_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "in",
          "value": [
            "pending"
          ]
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "in",
          "value": [
            "Portfolio Manager",
            "PM Assistant"
          ]
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "updated_at",
          "value": "now"
        },
        {
          "action": "emit_event",
          "event": "proposal.updated",
          "payload": [
            "proposal_id"
          ]
        }
      ],
      "result": "Proposal updated"
    },
    "create_direct_onboarding": {
      "priority": 50,
      "given": [
        {
          "field": "client_information",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "mandate_details",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "in",
          "value": [
            "Portfolio Manager",
            "PM Assistant"
          ]
        }
      ],
      "then": [
        {
          "action": "create_record",
          "type": "onboarding",
          "target": "onboarding",
          "fields": [
            "client_information",
            "mandate_details"
          ]
        },
        {
          "action": "emit_event",
          "event": "onboarding.created",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "Onboarding created"
    },
    "start_onboarding_for_proposal": {
      "priority": 51,
      "given": [
        {
          "field": "proposal_id",
          "source": "input",
          "operator": "exists"
        },
        {
          "field": "status",
          "source": "db",
          "operator": "eq",
          "value": "accepted"
        },
        {
          "field": "client.role",
          "source": "session",
          "operator": "in",
          "value": [
            "Portfolio Manager",
            "PM Assistant"
          ]
        }
      ],
      "then": [
        {
          "action": "create_record",
          "type": "onboarding",
          "target": "onboarding",
          "fields": [
            "proposal_id",
            "client_information"
          ]
        },
        {
          "action": "emit_event",
          "event": "onboarding.created",
          "payload": [
            "onboarding_id"
          ]
        }
      ],
      "result": "Onboarding from proposal"
    },
    "get_pm_onboardings": {
      "priority": 60,
      "given": [
        {
          "field": "client.role",
          "source": "session",
          "operator": "in",
          "value": [
            "Portfolio Manager",
            "PM Assistant"
          ]
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "pm_onboardings.list_retrieved",
          "payload": [
            "portfolio_manager_id"
          ]
        }
      ],
      "result": "Returns PM onboardings"
    }
  },
  "errors": [
    {
      "code": "PROPOSAL_NOT_FOUND",
      "status": 404,
      "message": "Proposal not found"
    },
    {
      "code": "INVALID_STATUS_TRANSITION",
      "status": 400,
      "message": "Invalid status transition"
    },
    {
      "code": "DUPLICATE_CLIENT",
      "status": 409,
      "message": "Client already exists"
    },
    {
      "code": "MISSING_CLIENT_INFO",
      "status": 400,
      "message": "Client information missing"
    },
    {
      "code": "DOCUMENT_UPLOAD_FAILED",
      "status": 500,
      "message": "Document upload failed"
    },
    {
      "code": "DOCUMENT_NOT_FOUND",
      "status": 404,
      "message": "Document not found"
    },
    {
      "code": "INVALID_EMAIL",
      "status": 400,
      "message": "Invalid email"
    },
    {
      "code": "INVALID_PHONE",
      "status": 400,
      "message": "Invalid phone"
    },
    {
      "code": "UNAUTHORIZED_ACCESS",
      "status": 403,
      "message": "Unauthorized"
    },
    {
      "code": "PDF_GENERATION_FAILED",
      "status": 500,
      "message": "PDF generation failed"
    },
    {
      "code": "DOCU_SIGN_INTEGRATION_ERROR",
      "status": 500,
      "message": "eSignature service error"
    }
  ],
  "events": [
    {
      "name": "proposal.created",
      "description": "Proposal created",
      "payload": [
        "proposal_id"
      ]
    },
    {
      "name": "proposal.retrieved",
      "description": "Proposal retrieved",
      "payload": [
        "proposal_id"
      ]
    },
    {
      "name": "proposals.list_retrieved",
      "description": "Proposals list retrieved",
      "payload": [
        "client_id"
      ]
    },
    {
      "name": "proposal_document.retrieved",
      "description": "Proposal document retrieved",
      "payload": [
        "proposal_id"
      ]
    },
    {
      "name": "pending_proposals.retrieved",
      "description": "Pending proposals retrieved",
      "payload": [
        "client_id"
      ]
    },
    {
      "name": "proposal.accepted",
      "description": "Proposal accepted",
      "payload": [
        "proposal_id"
      ]
    },
    {
      "name": "proposal.declined",
      "description": "Proposal declined",
      "payload": [
        "proposal_id"
      ]
    },
    {
      "name": "document.downloaded",
      "description": "Document downloaded",
      "payload": [
        "proposal_id"
      ]
    },
    {
      "name": "mandate.generated",
      "description": "Mandate generated",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "mandate_signing.initiated",
      "description": "Signing initiated",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "mandate.signed",
      "description": "Mandate signed",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "proposal.updated",
      "description": "Proposal updated",
      "payload": [
        "proposal_id"
      ]
    },
    {
      "name": "onboarding.created",
      "description": "Onboarding created",
      "payload": [
        "onboarding_id"
      ]
    },
    {
      "name": "pm_proposals.list_retrieved",
      "description": "PM proposals retrieved",
      "payload": [
        "portfolio_manager_id"
      ]
    },
    {
      "name": "pm_onboardings.list_retrieved",
      "description": "PM onboardings retrieved",
      "payload": [
        "portfolio_manager_id"
      ]
    },
    {
      "name": "validation.duplicate_check",
      "description": "Duplicate check performed",
      "payload": [
        "identification_number"
      ]
    }
  ],
  "related": [
    {
      "feature": "client-onboarding",
      "type": "required"
    },
    {
      "feature": "advisor-onboarding",
      "type": "optional"
    },
    {
      "feature": "user-auth",
      "type": "required"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_proposals_quotations",
        "description": "Creation, management, and approval workflow for investment proposals and quotations delivered to clients",
        "success_metrics": [
          {
            "metric": "data_accuracy",
            "target": "100%",
            "measurement": "Records matching source of truth"
          },
          {
            "metric": "duplicate_rate",
            "target": "0%",
            "measurement": "Duplicate records detected post-creation"
          }
        ],
        "constraints": [
          {
            "type": "performance",
            "description": "Data consistency must be maintained across concurrent operations",
            "negotiable": false
          }
        ]
      }
    ],
    "autonomy": {
      "level": "supervised",
      "human_checkpoints": [
        "before transitioning to a terminal state"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "get_current_proposal",
          "permission": "autonomous"
        },
        {
          "action": "get_client_proposals",
          "permission": "autonomous"
        },
        {
          "action": "get_proposals_for_review",
          "permission": "autonomous"
        },
        {
          "action": "get_proposal_with_document",
          "permission": "autonomous"
        },
        {
          "action": "accept_proposal",
          "permission": "autonomous"
        },
        {
          "action": "decline_proposal",
          "permission": "autonomous"
        },
        {
          "action": "get_proposal_document",
          "permission": "autonomous"
        },
        {
          "action": "generate_mandate_pdf",
          "permission": "autonomous"
        },
        {
          "action": "complete_onboarding_workflow",
          "permission": "autonomous"
        },
        {
          "action": "handle_mandate_signed",
          "permission": "autonomous"
        },
        {
          "action": "create_proposal",
          "permission": "supervised"
        },
        {
          "action": "create_proposal_success",
          "permission": "supervised"
        },
        {
          "action": "get_pm_proposals",
          "permission": "autonomous"
        },
        {
          "action": "get_proposal_by_id",
          "permission": "autonomous"
        },
        {
          "action": "update_proposal",
          "permission": "supervised"
        },
        {
          "action": "create_direct_onboarding",
          "permission": "supervised"
        },
        {
          "action": "start_onboarding_for_proposal",
          "permission": "autonomous"
        },
        {
          "action": "get_pm_onboardings",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "data_integrity",
        "over": "performance",
        "reason": "data consistency must be maintained across all operations"
      }
    ],
    "coordination": {
      "protocol": "orchestrated",
      "consumes": [
        {
          "capability": "client_onboarding",
          "from": "client-onboarding",
          "fallback": "degrade"
        },
        {
          "capability": "user_auth",
          "from": "user-auth",
          "fallback": "degrade"
        }
      ]
    }
  },
  "extensions": {
    "email-notification": "Email notifications",
    "esignature-integration": "eSignature service integration",
    "pdf-generation": "PDF generation"
  },
  "ui_hints": {
    "document_preview": true,
    "client_comment_section": true,
    "status_timeline": true,
    "document_download": true
  }
}