docs: add Salesforce Object Manager benchmark specification and introspection roadmap
Some checks failed
Build, Test, and Deploy / build-and-deploy (push) Failing after 30s
Some checks failed
Build, Test, and Deploy / build-and-deploy (push) Failing after 30s
This commit is contained in:
parent
57ad45e884
commit
d73b435ec6
1 changed files with 334 additions and 0 deletions
334
docs/OBJECT_MANAGER_SPEC.md
Normal file
334
docs/OBJECT_MANAGER_SPEC.md
Normal file
|
|
@ -0,0 +1,334 @@
|
|||
# OpenForce Object Manager Architecture & Specification
|
||||
|
||||
## 1. Executive Summary & Objective
|
||||
|
||||
In Salesforce, the **Object Manager** (`Setup -> Object Manager`) serves as the administrative cockpit for managing the data dictionary, data relationships, and presentation layers across the CRM. Users do not merely see custom objects; they inspect, configure, and customize **both Standard Built-In Objects** (`Account`, `Contact`, `Lead`, `Opportunity`, `Activity`, `Campaign`) and **Dynamic Custom Objects** (`__c`).
|
||||
|
||||
Within an object's detail view, the **Fields & Relationships** section provides a unified catalog of every attribute that can exist on a record:
|
||||
- **Standard Fields** (e.g., `first_name`, `amount`, `close_date`, `expected_revenue`, `billing_street`) created by the core system engine.
|
||||
- **Custom Fields** (suffixed with `__c`, e.g., `arr__c`, `sla_expiration_date__c`, `tier__c`) provisioned dynamically by CRM administrators.
|
||||
|
||||
This specification details the research benchmarks, backend introspection architecture, API contracts, Vue 3 Lightning UX implementation, and sprint rollout plan to achieve full Salesforce Object Manager parity in OpenForce.
|
||||
|
||||
---
|
||||
|
||||
## 2. Salesforce Object Manager Benchmark Analysis
|
||||
|
||||
### 2.1 The Two-Tier Navigation Model
|
||||
In Salesforce Setup, the Object Manager implements a strict hierarchy:
|
||||
1. **Object Catalog (Level 1)**:
|
||||
- Displays all registered objects in a searchable, filterable grid.
|
||||
- Columns: `Label` (e.g., "Account"), `API Name` (e.g., "Account" vs "Invoice__c"), `Type` (`Standard Object` vs `Custom Object`), `Description`, `Last Modified`.
|
||||
- Actions: Filter by Object Type (All / Standard / Custom), Global Search, and "Create Custom Object".
|
||||
2. **Object Detail & Subsystem Sidebar (Level 2)**:
|
||||
- Left Navigation Menu:
|
||||
- **Details**: Label, Plural Label, API Name, Record Count, Sharing Model, Deployment Status.
|
||||
- **Fields & Relationships**: The central schema view showing every standard and custom field.
|
||||
- **Page Layouts**: Drag-and-drop assignment of fields to visual sections.
|
||||
- **Validation Rules**: Formula-based validations before commit.
|
||||
- **Triggers / Flows**: Associated automation routines.
|
||||
|
||||
### 2.2 Fields & Relationships Grid Specification
|
||||
The Fields & Relationships table in Salesforce has strict visual and behavioral conventions:
|
||||
| Column Header | Description | Example Standard Field | Example Custom Field |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Field Label** | Human-readable presentation label | `Expected Revenue` | `ARR Tier` |
|
||||
| **Field Name (API)** | Exact programmatic identifier | `expected_revenue` | `arr_tier__c` |
|
||||
| **Data Type** | Specific CRM type descriptor | `Currency(18, 2)` | `Picklist` |
|
||||
| **Type Pill / Badge** | Clear visual category indicator | `Standard` (slate badge) | `Custom` (indigo badge) |
|
||||
| **Controlling / Lookup** | Referenced entity if relational | `-` | `Account` (Lookup) |
|
||||
| **Indexed** | Database query acceleration indicator | `Yes` (Primary / Foreign key) | `Indexed (JSONB GIN)` |
|
||||
| **Required** | Nullability / constraint enforcement | `False` | `True` |
|
||||
| **Actions** | Permitted mutations | *Read-Only* (standard fields cannot be dropped or altered in core type) | `Edit`, `Delete` dropdown |
|
||||
|
||||
### 2.3 Field Data Type Taxonomy Mapping
|
||||
To deliver authentic Salesforce parity while staying native to Django and PostgreSQL:
|
||||
| OpenForce / SF Type | Django Internal Field Type | DB Representation | Validation / Semantics |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Text** | `CharField`, `SlugField` | `varchar(n)` / jsonb string | Length limit, trimmed string |
|
||||
| **Text Area (Long)**| `TextField` | `text` / jsonb string | Multiline string |
|
||||
| **Number** | `IntegerField`, `PositiveIntegerField` | `int4`, `int8` | Signed integer range |
|
||||
| **Currency** | `DecimalField` | `numeric(max_digits, decimal_places)` | Formatted currency with precision |
|
||||
| **Percent** | `DecimalField`, `IntegerField` | `numeric` / `int4` | 0-100 percentage display |
|
||||
| **Date** | `DateField` | `date` (YYYY-MM-DD) | Date picker parsing |
|
||||
| **Date/Time** | `DateTimeField` | `timestamptz` | ISO 8601 UTC timestamp |
|
||||
| **Checkbox** | `BooleanField` | `boolean` | True / False toggle |
|
||||
| **Picklist** | `CharField(choices=...)` | `varchar` with choice enum | Defined enumeration values |
|
||||
| **Lookup Relationship** | `ForeignKey` | `bigint REFERENCES` or UUID | Relational pointer to target object |
|
||||
| **Generic Lookup** | `GenericForeignKey` | `content_type_id` + `object_id` | Polymorphic relationship (e.g. Activity parent) |
|
||||
| **Autonumber / ID** | `BigAutoField`, `UUIDField` | `int8 serial` / `uuid` | System immutable identifier |
|
||||
|
||||
---
|
||||
|
||||
## 3. Backend Introspection Architecture
|
||||
|
||||
### 3.1 Design Principles
|
||||
1. **Zero Duplication**: Never manually hand-code static field dictionaries for standard models. Standard schema must be dynamically introspected directly from Django's `Model._meta.get_fields()`. Any model migration or field update automatically reflects in the Object Manager.
|
||||
2. **Unified Representation**: Standard Django ORM fields and dynamic `CustomFieldDefinition` records must resolve into a single uniform DTO (Data Transfer Object) contract consumed by the frontend.
|
||||
3. **Security & Information Hiding**: Sensitive system attributes (`password`, auth tokens, session markers) must be strictly omitted. Only approved business CRM models are inspectable.
|
||||
4. **Tenant Isolation**: Model introspection reports canonical schema metadata, while custom field definitions (`CustomFieldDefinition`) respect tenant isolation scopes.
|
||||
|
||||
### 3.2 Target Models for Standard Introspection
|
||||
The following standard models in `crm_core` and `outreach` are exposed to the Object Manager:
|
||||
- `Account` (`crm_core.models.Account`)
|
||||
- `Contact` (`crm_core.models.Contact`)
|
||||
- `Lead` (`crm_core.models.Lead`)
|
||||
- `Opportunity` (`crm_core.models.Opportunity`)
|
||||
- `Activity` (`crm_core.models.Activity`)
|
||||
- `Campaign` (`outreach.models.Campaign`)
|
||||
|
||||
### 3.3 Dynamic Model Introspection Service
|
||||
A dedicated service `crm_core/introspection.py` handles parsing model metadata:
|
||||
|
||||
```python
|
||||
# crm_core/introspection.py
|
||||
from django.apps import apps
|
||||
from django.db import models
|
||||
from custom_objects.models import CustomFieldDefinition
|
||||
|
||||
STANDARD_OBJECT_REGISTRY = {
|
||||
"Account": ("crm_core", "Account"),
|
||||
"Contact": ("crm_core", "Contact"),
|
||||
"Lead": ("crm_core", "Lead"),
|
||||
"Opportunity": ("crm_core", "Opportunity"),
|
||||
"Activity": ("crm_core", "Activity"),
|
||||
"Campaign": ("outreach", "Campaign"),
|
||||
}
|
||||
|
||||
EXCLUDED_FIELDS = {
|
||||
"custom_fields", # JSONB container itself is not displayed as a business field
|
||||
"password",
|
||||
"is_superuser",
|
||||
"is_staff",
|
||||
}
|
||||
|
||||
DJANGO_TYPE_MAP = {
|
||||
"CharField": "Text",
|
||||
"TextField": "Text Area (Long)",
|
||||
"IntegerField": "Number",
|
||||
"PositiveIntegerField": "Number",
|
||||
"BigAutoField": "AutoNumber",
|
||||
"DecimalField": "Currency",
|
||||
"BooleanField": "Checkbox",
|
||||
"DateField": "Date",
|
||||
"DateTimeField": "Date/Time",
|
||||
"ForeignKey": "Lookup",
|
||||
"GenericForeignKey": "Generic Lookup",
|
||||
"EmailField": "Email",
|
||||
"URLField": "URL",
|
||||
}
|
||||
|
||||
def map_field_type(field):
|
||||
if getattr(field, "choices", None):
|
||||
return "Picklist"
|
||||
internal_type = field.get_internal_type() if hasattr(field, "get_internal_type") else type(field).__name__
|
||||
return DJANGO_TYPE_MAP.get(internal_type, internal_type)
|
||||
|
||||
def introspect_standard_fields(model_name: str):
|
||||
if model_name not in STANDARD_OBJECT_REGISTRY:
|
||||
raise ValueError(f"Unknown standard object: {model_name}")
|
||||
|
||||
app_label, cls_name = STANDARD_OBJECT_REGISTRY[model_name]
|
||||
model = apps.get_model(app_label, cls_name)
|
||||
|
||||
fields = []
|
||||
for field in model._meta.get_fields():
|
||||
# Exclude reverse relations and internal containers
|
||||
if field.auto_created and not field.concrete:
|
||||
continue
|
||||
if field.name in EXCLUDED_FIELDS:
|
||||
continue
|
||||
|
||||
data_type = map_field_type(field)
|
||||
choices = [c[0] for c in field.choices] if getattr(field, "choices", None) else []
|
||||
related_to = None
|
||||
if field.is_relation and getattr(field, "related_model", None):
|
||||
related_to = field.related_model.__name__
|
||||
|
||||
fields.append({
|
||||
"name": field.name,
|
||||
"label": str(getattr(field, "verbose_name", field.name)).title(),
|
||||
"data_type": data_type,
|
||||
"is_custom": False,
|
||||
"is_required": not getattr(field, "blank", True) and not getattr(field, "null", True),
|
||||
"is_unique": getattr(field, "unique", False),
|
||||
"is_indexed": getattr(field, "db_index", False) or getattr(field, "primary_key", False) or field.is_relation,
|
||||
"help_text": str(getattr(field, "help_text", "")),
|
||||
"choices": choices,
|
||||
"related_to": related_to,
|
||||
"max_length": getattr(field, "max_length", None),
|
||||
"editable": field.name not in ["id", "created_at", "updated_at"],
|
||||
})
|
||||
return fields
|
||||
```
|
||||
|
||||
### 3.4 REST API Endpoint Specification
|
||||
We expose standard introspection alongside custom fields through clean RESTful endpoints:
|
||||
|
||||
#### Endpoint 1: Standard Object Schema Introspection
|
||||
`GET /api/schema/objects/{entity_name}/fields/`
|
||||
- **Authentication**: Session / Token (Requires authenticated user)
|
||||
- **Parameters**: `entity_name` (e.g. `Account`, `Contact`, `Lead`, `Opportunity`, `Activity`)
|
||||
- **Response**:
|
||||
```json
|
||||
{
|
||||
"entity_name": "Opportunity",
|
||||
"label": "Opportunity",
|
||||
"is_custom": false,
|
||||
"standard_fields": [
|
||||
{
|
||||
"name": "id",
|
||||
"label": "ID",
|
||||
"data_type": "AutoNumber",
|
||||
"is_custom": false,
|
||||
"is_required": false,
|
||||
"is_unique": true,
|
||||
"is_indexed": true,
|
||||
"choices": [],
|
||||
"related_to": null,
|
||||
"editable": false
|
||||
},
|
||||
{
|
||||
"name": "name",
|
||||
"label": "Name",
|
||||
"data_type": "Text",
|
||||
"is_custom": false,
|
||||
"is_required": true,
|
||||
"is_unique": false,
|
||||
"is_indexed": false,
|
||||
"choices": [],
|
||||
"related_to": null,
|
||||
"editable": true
|
||||
},
|
||||
{
|
||||
"name": "amount",
|
||||
"label": "Amount",
|
||||
"data_type": "Currency",
|
||||
"is_custom": false,
|
||||
"is_required": false,
|
||||
"is_unique": false,
|
||||
"is_indexed": false,
|
||||
"choices": [],
|
||||
"related_to": null,
|
||||
"editable": true
|
||||
},
|
||||
{
|
||||
"name": "expected_revenue",
|
||||
"label": "Expected Revenue",
|
||||
"data_type": "Currency",
|
||||
"is_custom": false,
|
||||
"is_required": false,
|
||||
"is_unique": false,
|
||||
"is_indexed": false,
|
||||
"choices": [],
|
||||
"related_to": null,
|
||||
"editable": true
|
||||
},
|
||||
{
|
||||
"name": "stage",
|
||||
"label": "Stage",
|
||||
"data_type": "Picklist",
|
||||
"is_custom": false,
|
||||
"is_required": true,
|
||||
"is_unique": false,
|
||||
"is_indexed": false,
|
||||
"choices": [
|
||||
"Prospecting",
|
||||
"Qualification",
|
||||
"Needs Analysis",
|
||||
"Value Proposition",
|
||||
"Id. Decision Makers",
|
||||
"Decision Makers",
|
||||
"Perception Analysis",
|
||||
"Proposal/Price Quote",
|
||||
"Negotiation/Review",
|
||||
"Closed Won",
|
||||
"Closed Lost"
|
||||
],
|
||||
"related_to": null,
|
||||
"editable": true
|
||||
},
|
||||
{
|
||||
"name": "account",
|
||||
"label": "Account",
|
||||
"data_type": "Lookup",
|
||||
"is_custom": false,
|
||||
"is_required": true,
|
||||
"is_unique": false,
|
||||
"is_indexed": true,
|
||||
"choices": [],
|
||||
"related_to": "Account",
|
||||
"editable": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Endpoint 2: Unified Fields Retrieval for Object Manager
|
||||
`GET /api/custom-fields/?entity_name={entity_name}` or unified `/api/schema/objects/{entity_name}/all-fields/`
|
||||
- Merges introspected standard fields with stored `CustomFieldDefinition` records.
|
||||
- Custom field attributes include: `id`, `name` (e.g. `arr__c`), `label`, `field_type`, `is_custom: true`, `required`, `choices`, `related_to`.
|
||||
- Resulting unified list is sorted deterministically: Standard fields first, then Custom fields alphabetically, or sortable by any column in the UI.
|
||||
|
||||
---
|
||||
|
||||
## 4. Frontend UI/UX Specification (`CustomObjectsView.vue`)
|
||||
|
||||
### 4.1 Master-Detail Layout Structure
|
||||
The Object Manager in `frontend/src/views/CustomObjectsView.vue` features a dual-pane Lightning interface:
|
||||
1. **Left Sidebar (Object Selector)**:
|
||||
- Search input filter for quickly locating objects.
|
||||
- Segmented section for **Standard Objects** (`Account`, `Contact`, `Lead`, `Opportunity`, `Activity`, `Campaign`).
|
||||
- Segmented section for **Custom Objects** (`*__c`).
|
||||
- Pill counters showing count of custom fields attached to each object.
|
||||
- Button to "Create Custom Object".
|
||||
2. **Main Detail Pane**:
|
||||
- **Header Card**:
|
||||
- Object Icon (standard entity icons: Accounts 🏢, Contacts 👤, Leads 🎯, Opportunities 💼, Activities 📅, Custom 📦).
|
||||
- Object Label & API Name badge (`Account` vs `Invoice__c`).
|
||||
- Metadata summary: Type badge (`Standard Object` vs `Custom Object`), Description, Total Fields Count.
|
||||
- **Tabs**:
|
||||
- **Fields & Relationships** (Default active tab).
|
||||
- **Object Details** (Record counts, storage, settings).
|
||||
- **Flows & Triggers** (Automations associated with this object).
|
||||
|
||||
### 4.2 Unified Fields Table Features
|
||||
- **Table Columns**:
|
||||
1. `Field Label`: Bold title (e.g. **Expected Revenue**).
|
||||
2. `API Name`: Monospace font tag (`expected_revenue` or `deal_score__c`).
|
||||
3. `Data Type`: Formatted type badge (`Text(255)`, `Currency`, `Picklist`, `Lookup(Account)`).
|
||||
4. `Origin / Badge`:
|
||||
- Standard: Slate/gray badge `Standard`.
|
||||
- Custom: Blue/indigo badge `Custom`.
|
||||
5. `Required`: Checkmark `✓` or dash `-`.
|
||||
6. `Indexed`: Indicator if field is a PK, FK, or JSONB GIN indexed.
|
||||
7. `Actions`:
|
||||
- Standard Fields: Lock icon or "Standard Field (System Managed)".
|
||||
- Custom Fields: Action buttons for `Edit` and `Delete` with confirmation modal.
|
||||
- **Search & Filter Controls**:
|
||||
- Quick search bar: instantly filters fields across label, API name, or data type.
|
||||
- Filter pills: `All Fields`, `Standard Only`, `Custom Only`.
|
||||
- **"New Custom Field" Modal**:
|
||||
- Accessible on both standard objects and custom objects.
|
||||
- Generates valid `__c` API names with preview.
|
||||
- Field type selector: Text, Number, Currency, Date, DateTime, Boolean, Picklist.
|
||||
|
||||
---
|
||||
|
||||
## 5. Sprint Implementation Plan
|
||||
|
||||
| Phase | Milestone | Owner | Deliverables | Status |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **Sprint 4.4A** | **Schema Introspection Engine** | Bumble & Comb | • Create `crm_core/introspection.py`<br>• Map all 6 core models to Salesforce types<br>• Expose `GET /api/schema/objects/{entity}/fields/`<br>• Backend unit tests in `tests/test_introspection.py` | **Ready for Dev** |
|
||||
| **Sprint 4.4B** | **Store & State Integration** | Goose | • Update `frontend/src/stores/crm.js`<br>• Add `fetchObjectSchema(entityName)`<br>• Merge standard & custom fields in pinia state | **Pending 4.4A** |
|
||||
| **Sprint 4.4C** | **Unified Fields UI in Object Manager** | Goose | • Refactor `CustomObjectsView.vue`<br>• Implement Salesforce-style fields table<br>• Add Type Pills, Search & Filters, and Read-Only locks | **Pending 4.4B** |
|
||||
| **Sprint 4.4D** | **Regression Testing & Deployment** | Goose & Comb | • Frontend Vitest / Cypress tests<br>• Validate `crm.ch4t.buzz` live deployment<br>• CI/CD pipeline verification | **Final Signoff** |
|
||||
|
||||
---
|
||||
|
||||
## 6. Technical Safeguards & Edge Cases
|
||||
|
||||
1. **Foreign Key Reverse Lookups**: Reverse relations (e.g. `contact_set`, `activity_set`) must be excluded from the basic fields list to avoid cluttering the attribute editor; they belong in a dedicated "Related Lists" tab.
|
||||
2. **GenericForeignKeys**: The `parent` field in `Activity` uses `content_type` and `object_id`. The introspection engine gracefully maps this as `Generic Lookup` pointing to multiple target entities.
|
||||
3. **Immutability of Standard Fields**: Standard fields must be strictly protected from deletion or arbitrary rename requests. The UI will disable edit/delete actions, and backend mutation APIs will reject any field payload lacking the `__c` custom field convention.
|
||||
4. **Field Name Collisions**: Ensure the custom field creation validator rejects custom field names that collide with existing standard fields (e.g. preventing a custom field named `name__c` on Account if it violates ambiguity rules).
|
||||
Loading…
Reference in a new issue