diff --git a/docs/OBJECT_MANAGER_SPEC.md b/docs/OBJECT_MANAGER_SPEC.md new file mode 100644 index 0000000..1138243 --- /dev/null +++ b/docs/OBJECT_MANAGER_SPEC.md @@ -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`
• Map all 6 core models to Salesforce types
• Expose `GET /api/schema/objects/{entity}/fields/`
• Backend unit tests in `tests/test_introspection.py` | **Ready for Dev** | +| **Sprint 4.4B** | **Store & State Integration** | Goose | • Update `frontend/src/stores/crm.js`
• Add `fetchObjectSchema(entityName)`
• Merge standard & custom fields in pinia state | **Pending 4.4A** | +| **Sprint 4.4C** | **Unified Fields UI in Object Manager** | Goose | • Refactor `CustomObjectsView.vue`
• Implement Salesforce-style fields table
• Add Type Pills, Search & Filters, and Read-Only locks | **Pending 4.4B** | +| **Sprint 4.4D** | **Regression Testing & Deployment** | Goose & Comb | • Frontend Vitest / Cypress tests
• Validate `crm.ch4t.buzz` live deployment
• 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).