openforce/docs/STANDARD_CRM_SCHEMA_SPEC.md

9.5 KiB

OpenForce Standard CRM Schema Specification & Field Dictionary

Target Entities: Account, Contact, Lead, Opportunity, and Activity

This document defines the production field dictionary, constraint rules, indexing strategies, and lifecycle conversion dynamics for OpenForce's Phase 1 standard objects, benchmarking Salesforce standard fields, Twenty CRM, and SuiteCRM.


1. Account (Standard Object)

Represents a business organization, partner, or enterprise client.

Fields & Constraints

Field Name Type Constraints Description
id UUID Primary Key, default uuid.uuid4 Global unique identifier
name String(255) Required, indexed Company or organization legal/trading name
account_type Enum / String(50) Choices: Customer, Prospect, Partner, Competitor, Vendor, Other Relationship type
industry Enum / String(100) Choices: Technology, Finance, Healthcare, Manufacturing, Retail, Services, Other Sector categorization
annual_revenue Decimal(18, 2) Nullable, default None Annual estimated or reported turnover
employees_count Integer Nullable, min 0 Total workforce count
website URLField Nullable, max_length 255 Corporate website URL
phone String(40) Nullable Primary corporate telephone number
billing_address JSONB Schema: {street, city, state, postal_code, country} Structured billing address
shipping_address JSONB Schema: {street, city, state, postal_code, country} Structured shipping/logistics address
parent_account ForeignKey(Account) Nullable, on_delete=SET_NULL, related_name=child_accounts Corporate hierarchy/subsidiary tree
owner ForeignKey(User) Nullable, on_delete=SET_NULL, related_name=accounts Account executive / sales rep owner
created_at DateTime Auto now add, indexed Creation timestamp
updated_at DateTime Auto now, indexed Last updated timestamp

2. Contact (Standard Object)

Represents an individual person associated with an Account.

Fields & Constraints

Field Name Type Constraints Description
id UUID Primary Key Global unique identifier
account ForeignKey(Account) Nullable, on_delete=CASCADE, related_name=contacts, indexed Linked company/account
first_name String(100) Required Individual's given name
last_name String(100) Required, indexed Individual's family / surname
email EmailField Indexed, nullable Primary email address
phone String(40) Nullable Direct business telephone
mobile_phone String(40) Nullable Mobile/cellular telephone
title String(128) Nullable Job title / professional role (e.g. VP Engineering)
department String(128) Nullable Department within organization
is_primary Boolean Default False Primary contact flag for the parent Account
do_not_call Boolean Default False Compliance flag for outbound calling
email_opt_out Boolean Default False, indexed Unsubscribe flag for automated outreach campaigns
owner ForeignKey(User) Nullable, on_delete=SET_NULL, related_name=contacts Relationship manager
created_at DateTime Auto now add Creation timestamp
updated_at DateTime Auto now Last updated timestamp

3. Lead (Standard Object)

Represents an unqualified prospect or inbound marketing inquiry.

Fields & Constraints

Field Name Type Constraints Description
id UUID Primary Key Global unique identifier
first_name String(100) Required Prospect given name
last_name String(100) Required, indexed Prospect family name
company String(255) Required, indexed Organization name provided by prospect
email EmailField Indexed, nullable Prospect email address
phone String(40) Nullable Phone number
lead_source Enum / String(64) Choices: Inbound Web, Referral, Conference, Cold Outreach, Partner, Other Acquisition origin
status Enum / String(50) Choices: New, Contacted, Working, Qualified, Unqualified Lead lifecycle status
lead_score Integer Default 0, indexed Heuristic engagement score (0-100)
is_converted Boolean Default False, indexed True if converted to Account/Contact/Opp
converted_at DateTime Nullable Conversion timestamp
converted_account ForeignKey(Account) Nullable, on_delete=SET_NULL Account generated during conversion
converted_contact ForeignKey(Contact) Nullable, on_delete=SET_NULL Contact generated during conversion
converted_opportunity ForeignKey(Opportunity) Nullable, on_delete=SET_NULL Deal created during conversion
owner ForeignKey(User) Nullable, on_delete=SET_NULL, related_name=leads Sales development representative
created_at DateTime Auto now add Creation timestamp
updated_at DateTime Auto now Last updated timestamp

4. Opportunity (Standard Object)

Represents a prospective deal or revenue-generating engagement in the sales pipeline.

Fields & Constraints

Field Name Type Constraints Description
id UUID Primary Key Global unique identifier
name String(255) Required, indexed Deal name (e.g. "Acme Corp - 50 Seat License")
account ForeignKey(Account) Required, on_delete=CASCADE, related_name=opportunities Associated client account
primary_contact ForeignKey(Contact) Nullable, on_delete=SET_NULL Lead champion / signatory contact
amount Decimal(18, 2) Default 0.00, indexed Total deal value in base currency
stage Enum / String(50) Indexed Pipeline stage (see Stage Dictionary below)
probability Integer Min 0, Max 100 Percentage probability of winning (stage-derived default)
expected_revenue Decimal(18, 2) Computed (amount * probability / 100) Weighted pipeline revenue
close_date Date Required, indexed Anticipated or actual transaction close date
lead_source Enum / String(64) Nullable Origination channel
deal_type Enum / String(50) Choices: New Business, Existing Business - Expansion, Renewal Commercial categorization
next_step String(255) Nullable Immediate operational action step
owner ForeignKey(User) Nullable, on_delete=SET_NULL, related_name=opportunities Deal lead
created_at DateTime Auto now add Creation timestamp
updated_at DateTime Auto now Last updated timestamp

Opportunity Stage & Probability Matrix

Stage Name Default Probability Forecast Category Description
Prospecting 10% Pipeline Initial contact made, interest identified
Qualification 20% Pipeline BANT (Budget, Authority, Need, Timeline) assessed
Needs Analysis 40% Pipeline Deep technical & requirements discovery
Proposal / Quote 60% Best Case Formal quote or proposal delivered
Negotiation / Review 80% Commit Legal, procurement, and terms discussion
Closed Won 100% Closed Executed agreement, deal won
Closed Lost 0% Omitted Deal abandoned or lost to competitor

5. Unified Activity & Task Model

Tracks all activities, calls, emails, and to-dos against standard and custom entities.

Activity / Task Schema

Field Name Type Constraints Description
id UUID Primary Key Global unique identifier
subject String(255) Required Activity headline / task title
activity_type Enum / String(32) Choices: Task, Call, Meeting, Email, Note Classification of interaction
status Enum / String(32) Choices: Not Started, In Progress, Completed, Deferred Execution status
priority Enum / String(20) Choices: High, Normal, Low Urgency tier
due_date DateTime Nullable, indexed Target completion or occurrence time
description TextField Nullable Body notes or meeting transcript
content_type ForeignKey(ContentType) Indexed Generic relation to any Django model
object_id String(64) Indexed ID of target entity (Account, Contact, Lead, etc.)
content_object GenericForeignKey Resolves (content_type, object_id) Polymorphic target link
assigned_to ForeignKey(User) Nullable, on_delete=SET_NULL Action assignee
completed_at DateTime Nullable Actual completion timestamp

6. Lead Conversion Pipeline Mechanics

When a user or automated flow invokes POST /api/leads/{id}/convert/:

  1. Validation: Verify lead.is_converted == False.
  2. Atomic Transaction (transaction.atomic):
    • Locate or create Account matching lead.company.
    • Create Contact with first_name, last_name, email, phone, linked to Account.
    • If requested, create Opportunity with name=f"{lead.company} - New Deal", stage="Prospecting", linked to Account and Contact.
    • Update Lead:
      • is_converted = True
      • converted_at = timezone.now()
      • converted_account = account
      • converted_contact = contact
      • converted_opportunity = opportunity
    • Re-link all related polymorphic Tasks and Activities from (Lead, lead.id) to (Contact, contact.id) or (Account, account.id).