9.5 KiB
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/:
- Validation: Verify
lead.is_converted == False. - Atomic Transaction (
transaction.atomic):- Locate or create
Accountmatchinglead.company. - Create
Contactwithfirst_name,last_name,email,phone, linked toAccount. - If requested, create
Opportunitywithname=f"{lead.company} - New Deal",stage="Prospecting", linked toAccountandContact. - Update
Lead:is_converted = Trueconverted_at = timezone.now()converted_account = accountconverted_contact = contactconverted_opportunity = opportunity
- Re-link all related polymorphic
TasksandActivitiesfrom(Lead, lead.id)to(Contact, contact.id)or(Account, account.id).
- Locate or create