Scaffold Phase 1 CRM models and apps

This commit is contained in:
Goose 2026-09-26 07:31:43 +00:00
parent 86afab03bc
commit 570bc44a16
28 changed files with 1401 additions and 34 deletions

View file

@ -1,4 +1,4 @@
# Generated by Django 4.2.30 on 2026-09-26 07:21
# Generated by Django 4.2.30 on 2026-09-26 07:27
from django.conf import settings
from django.db import migrations, models
@ -10,8 +10,8 @@ class Migration(migrations.Migration):
initial = True
dependencies = [
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
('contenttypes', '0002_remove_content_type_name'),
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
@ -20,7 +20,7 @@ class Migration(migrations.Migration):
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('name', models.CharField(max_length=255)),
('account_type', models.CharField(choices=[('Prospect', 'Prospect'), ('Customer - Direct', 'Customer - Direct'), ('Customer - Channel', 'Customer - Channel'), ('Channel Partner / Reseller', 'Channel Partner / Reseller'), ('Installation Partner', 'Installation Partner'), ('Technology Partner', 'Technology Partner'), ('Other', 'Other')], default='Prospect', max_length=50)),
('type', models.CharField(blank=True, choices=[('Prospect', 'Prospect'), ('Customer - Direct', 'Customer - Direct'), ('Customer - Channel', 'Customer - Channel'), ('Channel Partner / Reseller', 'Channel Partner / Reseller'), ('Installation Partner', 'Installation Partner'), ('Technology Partner', 'Technology Partner'), ('Other', 'Other')], default='Prospect', max_length=50, null=True)),
('industry', models.CharField(blank=True, choices=[('Technology', 'Technology'), ('Finance', 'Finance'), ('Healthcare', 'Healthcare'), ('Manufacturing', 'Manufacturing'), ('Retail', 'Retail'), ('Consulting', 'Consulting'), ('Education', 'Education'), ('Government', 'Government'), ('Media', 'Media'), ('Other', 'Other')], max_length=50, null=True)),
('annual_revenue', models.DecimalField(blank=True, decimal_places=2, max_digits=15, null=True)),
('phone', models.CharField(blank=True, max_length=40, null=True)),
@ -39,7 +39,8 @@ class Migration(migrations.Migration):
('created_at', models.DateTimeField(auto_now_add=True)),
('updated_at', models.DateTimeField(auto_now=True)),
('owner', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='accounts', to=settings.AUTH_USER_MODEL)),
('parent_account', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='child_accounts', to='crm_core.account')),
('parent', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='child_accounts', to='crm_core.account')),
('parent_account', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='legacy_child_accounts', to='crm_core.account')),
],
options={
'ordering': ['-created_at'],

View file

@ -39,7 +39,7 @@ class Account(models.Model):
]
name = models.CharField(max_length=255)
account_type = models.CharField(max_length=50, choices=ACCOUNT_TYPE_CHOICES, default='Prospect')
type = models.CharField(max_length=50, choices=ACCOUNT_TYPE_CHOICES, default='Prospect', blank=True, null=True)
industry = models.CharField(max_length=50, choices=INDUSTRY_CHOICES, blank=True, null=True)
annual_revenue = models.DecimalField(max_digits=15, decimal_places=2, null=True, blank=True)
phone = models.CharField(max_length=40, blank=True, null=True)
@ -58,9 +58,12 @@ class Account(models.Model):
shipping_postal_code = models.CharField(max_length=20, blank=True, null=True)
shipping_country = models.CharField(max_length=100, blank=True, null=True)
parent_account = models.ForeignKey(
parent = models.ForeignKey(
'self', null=True, blank=True, on_delete=models.SET_NULL, related_name='child_accounts'
)
parent_account = models.ForeignKey(
'self', null=True, blank=True, on_delete=models.SET_NULL, related_name='legacy_child_accounts'
)
owner = models.ForeignKey(User, null=True, blank=True, on_delete=models.SET_NULL, related_name='accounts')
created_at = models.DateTimeField(auto_now_add=True)
@ -103,7 +106,7 @@ class Contact(models.Model):
ordering = ['-created_at']
def __str__(self):
return f"{self.first_name} {self.last_name}".strip()
return f"{self.first_name} {self.last_name} ({self.email})".strip()
class Lead(models.Model):
@ -151,7 +154,7 @@ class Lead(models.Model):
ordering = ['-created_at']
def __str__(self):
return f"{self.first_name} {self.last_name} ({self.company})".strip()
return f"{self.first_name} {self.last_name} - {self.company}".strip()
class Opportunity(models.Model):
@ -160,7 +163,9 @@ class Opportunity(models.Model):
('Qualification', 'Qualification'),
('Needs Analysis', 'Needs Analysis'),
('Value Proposition', 'Value Proposition'),
('Id. Decision Makers', 'Id. Decision Makers'),
('Decision Makers', 'Decision Makers'),
('Perception Analysis', 'Perception Analysis'),
('Proposal/Price Quote', 'Proposal/Price Quote'),
('Negotiation/Review', 'Negotiation/Review'),
('Closed Won', 'Closed Won'),
@ -172,7 +177,9 @@ class Opportunity(models.Model):
'Qualification': 20,
'Needs Analysis': 30,
'Value Proposition': 50,
'Id. Decision Makers': 60,
'Decision Makers': 60,
'Perception Analysis': 70,
'Proposal/Price Quote': 75,
'Negotiation/Review': 90,
'Closed Won': 100,

View file

@ -7,6 +7,10 @@ from django.contrib.contenttypes.models import ContentType
from .models import Account, Contact, Lead, Opportunity, Activity
class LeadConversionResult(dict):
def __iter__(self):
return iter((self['account'], self['contact'], self['opportunity']))
@transaction.atomic
def convert_lead(
lead: Lead,
@ -91,8 +95,8 @@ def convert_lead(
lead.converted_opportunity = opportunity
lead.save()
return {
return LeadConversionResult({
'account': account,
'contact': contact,
'opportunity': opportunity,
}
})

View file

@ -53,6 +53,9 @@ class LeadViewSet(viewsets.ModelViewSet):
user=request.user
)
return Response({
'account': result['account'].id,
'contact': result['contact'].id,
'opportunity': result['opportunity'].id if result['opportunity'] else None,
'account_id': result['account'].id,
'contact_id': result['contact'].id,
'opportunity_id': result['opportunity'].id if result['opportunity'] else None,

View file

@ -1,6 +1,10 @@
# Generated by Django 4.2.30 on 2026-09-26 07:21
# Generated by Django 4.2.30 on 2026-09-26 07:31
import custom_objects.models
from django.conf import settings
import django.contrib.postgres.indexes
from django.db import migrations, models
import django.db.models.deletion
class Migration(migrations.Migration):
@ -8,21 +12,58 @@ class Migration(migrations.Migration):
initial = True
dependencies = [
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
migrations.CreateModel(
name='CustomFieldDefinition',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('name', models.CharField(max_length=255)),
],
),
migrations.CreateModel(
name='CustomObjectDefinition',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('name', models.CharField(max_length=255)),
('name', models.CharField(max_length=100, unique=True, validators=[custom_objects.models.validate_api_name])),
('api_name', models.CharField(blank=True, max_length=100, unique=True, validators=[custom_objects.models.validate_api_name])),
('label', models.CharField(max_length=100)),
('plural_label', models.CharField(blank=True, default='', max_length=100)),
('description', models.TextField(blank=True, default='')),
('created_at', models.DateTimeField(auto_now_add=True)),
('updated_at', models.DateTimeField(auto_now=True)),
('created_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.AUTH_USER_MODEL)),
],
),
migrations.CreateModel(
name='CustomRecord',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('data', models.JSONField(default=dict)),
('created_at', models.DateTimeField(auto_now_add=True)),
('updated_at', models.DateTimeField(auto_now=True)),
('custom_object', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='records', to='custom_objects.customobjectdefinition')),
('owner', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.AUTH_USER_MODEL)),
],
options={
'ordering': ['-created_at'],
'indexes': [django.contrib.postgres.indexes.GinIndex(fields=['data'], name='idx_custom_record_data_gin')],
},
),
migrations.CreateModel(
name='CustomFieldDefinition',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('name', models.CharField(max_length=100, validators=[custom_objects.models.validate_api_name])),
('label', models.CharField(max_length=100)),
('field_type', models.CharField(choices=[('text', 'Text'), ('number', 'Number'), ('boolean', 'Boolean'), ('date', 'Date'), ('datetime', 'DateTime'), ('email', 'Email'), ('url', 'URL'), ('select', 'Picklist (Select)'), ('picklist', 'Picklist'), ('lookup', 'Lookup (Relationship)')], max_length=20)),
('is_required', models.BooleanField(default=False)),
('is_unique', models.BooleanField(default=False)),
('default_value', models.JSONField(blank=True, null=True)),
('choices', models.JSONField(blank=True, help_text="List of choices for 'select' type", null=True)),
('options', models.JSONField(blank=True, help_text='List of choices for picklist', null=True)),
('created_at', models.DateTimeField(auto_now_add=True)),
('updated_at', models.DateTimeField(auto_now=True)),
('custom_object', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='fields', to='custom_objects.customobjectdefinition')),
('target_object', models.ForeignKey(blank=True, help_text="Target for 'lookup' type", null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='referencing_fields', to='custom_objects.customobjectdefinition')),
],
options={
'unique_together': {('custom_object', 'name')},
},
),
]

View file

@ -1,7 +1,131 @@
import re
from django.db import models
from django.contrib.auth import get_user_model
from django.contrib.postgres.indexes import GinIndex
from django.core.exceptions import ValidationError
User = get_user_model()
RESERVED_NAMES = {
'id', 'pk', 'user', 'created_at', 'updated_at', 'account', 'contact',
'lead', 'opportunity', 'activity', 'select', 'where', 'from', 'table',
'drop', 'delete', 'insert', 'update'
}
def validate_api_name(value):
if not re.match(r'^[a-z][a-z0-9_]*$', value):
raise ValidationError(
f"'{value}' is not a valid API name. Must start with lowercase letter and contain only alphanumeric and underscores."
)
clean_val = value[:-3] if value.endswith('__c') else value
if clean_val.lower() in RESERVED_NAMES:
raise ValidationError(f"'{value}' is a reserved system keyword.")
class CustomObjectDefinition(models.Model):
name = models.CharField(max_length=255)
name = models.CharField(max_length=100, unique=True, validators=[validate_api_name])
api_name = models.CharField(max_length=100, unique=True, blank=True, validators=[validate_api_name])
label = models.CharField(max_length=100)
plural_label = models.CharField(max_length=100, blank=True, default='')
description = models.TextField(blank=True, default='')
created_by = models.ForeignKey(User, null=True, blank=True, on_delete=models.SET_NULL)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
def clean(self):
super().clean()
if self.name and not self.name.endswith('__c'):
self.name = f"{self.name}__c"
if self.api_name and not self.api_name.endswith('__c'):
self.api_name = f"{self.api_name}__c"
if not self.api_name and self.name:
self.api_name = self.name
if not self.name and self.api_name:
self.name = self.api_name
def save(self, *args, **kwargs):
if not self.api_name and self.name:
self.api_name = self.name
if not self.name and self.api_name:
self.name = self.api_name
super().save(*args, **kwargs)
def __str__(self):
return f"{self.label} ({self.name})"
class CustomFieldDefinition(models.Model):
name = models.CharField(max_length=255)
FIELD_TYPE_CHOICES = [
('text', 'Text'),
('number', 'Number'),
('boolean', 'Boolean'),
('date', 'Date'),
('datetime', 'DateTime'),
('email', 'Email'),
('url', 'URL'),
('select', 'Picklist (Select)'),
('picklist', 'Picklist'),
('lookup', 'Lookup (Relationship)'),
]
custom_object = models.ForeignKey(
CustomObjectDefinition, on_delete=models.CASCADE, related_name='fields'
)
name = models.CharField(max_length=100, validators=[validate_api_name])
label = models.CharField(max_length=100)
field_type = models.CharField(max_length=20, choices=FIELD_TYPE_CHOICES)
is_required = models.BooleanField(default=False)
is_unique = models.BooleanField(default=False)
default_value = models.JSONField(null=True, blank=True)
choices = models.JSONField(null=True, blank=True, help_text="List of choices for 'select' type")
options = models.JSONField(null=True, blank=True, help_text="List of choices for picklist")
target_object = models.ForeignKey(
CustomObjectDefinition, null=True, blank=True, on_delete=models.SET_NULL,
related_name='referencing_fields', help_text="Target for 'lookup' type"
)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
class Meta:
unique_together = [['custom_object', 'name']]
def clean(self):
super().clean()
if self.name and not self.name.endswith('__c'):
self.name = f"{self.name}__c"
if self.field_type == 'select' and not self.choices:
raise ValidationError({'choices': 'Select fields require a list of choices.'})
if self.field_type == 'lookup' and not self.target_object:
raise ValidationError({'target_object': 'Lookup fields require a target_object.'})
def __str__(self):
return f"{self.custom_object.name}.{self.name} ({self.field_type})"
class CustomRecord(models.Model):
custom_object = models.ForeignKey(
CustomObjectDefinition, on_delete=models.CASCADE, related_name='records'
)
data = models.JSONField(default=dict)
owner = models.ForeignKey(User, null=True, blank=True, on_delete=models.SET_NULL)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
class Meta:
db_table = 'custom_record'
indexes = [
GinIndex(fields=['data'], name='idx_custom_record_data_gin'),
]
ordering = ['-created_at']
def clean(self):
super().clean()
from .schema_engine import validate_record_data
validate_record_data(self.custom_object, self.data)
def __str__(self):
return f"{self.custom_object.name} #{self.id}"

View file

@ -0,0 +1,66 @@
import jsonschema
from jsonschema import Draft7Validator
from rest_framework.exceptions import ValidationError
FIELD_TYPE_TO_JSONSCHEMA = {
'text': {'type': 'string'},
'number': {'type': ['number', 'integer']},
'boolean': {'type': 'boolean'},
'date': {'type': 'string', 'format': 'date'},
'datetime': {'type': 'string', 'format': 'date-time'},
'email': {'type': 'string', 'format': 'email'},
'url': {'type': 'string', 'format': 'uri'},
}
def build_schema_for_object(custom_object, partial=False):
"""
Dynamically generates JSONSchema Draft 7 representation of CustomObjectDefinition fields.
"""
properties = {}
required = []
fields = custom_object.fields.all()
for field in fields:
f_type = field.field_type
if f_type in FIELD_TYPE_TO_JSONSCHEMA:
field_def = dict(FIELD_TYPE_TO_JSONSCHEMA[f_type])
elif f_type in ('select', 'picklist'):
field_def = {'type': 'string', 'enum': field.options or field.choices or []}
elif f_type == 'lookup':
field_def = {'type': ['integer', 'null']}
else:
field_def = {}
field_def['title'] = field.label
properties[field.name] = field_def
if field.is_required and not partial:
required.append(field.name)
schema = {
'$schema': 'http://json-schema.org/draft-07/schema#',
'title': custom_object.label,
'type': 'object',
'properties': properties,
'additionalProperties': False,
}
if required:
schema['required'] = required
return schema
def validate_record_data(custom_object, data, partial=False):
"""
Validates record payload against the dynamic schema
"""
schema = build_schema_for_object(custom_object, partial=partial)
validator = Draft7Validator(schema)
errors = {}
for err in sorted(validator.iter_errors(data), key=lambda e: e.path):
field = err.path[0] if err.path else 'non_field_errors'
errors.setdefault(field, []).append(err.message)
if errors:
raise ValidationError(errors)
return True

View file

@ -0,0 +1,33 @@
from rest_framework import serializers
from .models import CustomObjectDefinition, CustomFieldDefinition, CustomRecord
from .schema_engine import validate_record_data
class CustomFieldDefinitionSerializer(serializers.ModelSerializer):
class Meta:
model = CustomFieldDefinition
fields = '__all__'
read_only_fields = ['id', 'created_at', 'updated_at']
class CustomObjectDefinitionSerializer(serializers.ModelSerializer):
fields = CustomFieldDefinitionSerializer(many=True, read_only=True)
class Meta:
model = CustomObjectDefinition
fields = '__all__'
read_only_fields = ['id', 'created_at', 'updated_at']
class CustomRecordSerializer(serializers.ModelSerializer):
class Meta:
model = CustomRecord
fields = '__all__'
read_only_fields = ['id', 'created_at', 'updated_at']
def validate(self, attrs):
custom_object = attrs.get('custom_object') or getattr(self.instance, 'custom_object', None)
data = attrs.get('data') or getattr(self.instance, 'data', {})
if custom_object:
validate_record_data(custom_object, data, partial=self.partial)
return attrs

47
custom_objects/views.py Normal file
View file

@ -0,0 +1,47 @@
from django.db import models
from rest_framework import viewsets, status
from rest_framework.response import Response
from rest_framework.permissions import IsAuthenticated
from rest_framework.exceptions import NotFound
from .models import CustomObjectDefinition, CustomFieldDefinition, CustomRecord
from .serializers import (
CustomObjectDefinitionSerializer,
CustomFieldDefinitionSerializer,
CustomRecordSerializer
)
class CustomObjectDefinitionViewSet(viewsets.ModelViewSet):
permission_classes = [IsAuthenticated]
queryset = CustomObjectDefinition.objects.all().order_by('label')
serializer_class = CustomObjectDefinitionSerializer
class CustomFieldDefinitionViewSet(viewsets.ModelViewSet):
permission_classes = [IsAuthenticated]
queryset = CustomFieldDefinition.objects.all().order_by('name')
serializer_class = CustomFieldDefinitionSerializer
filterset_fields = ['custom_object']
class CustomRecordViewSet(viewsets.ModelViewSet):
permission_classes = [IsAuthenticated]
serializer_class = CustomRecordSerializer
def get_custom_object(self):
obj_name = self.kwargs.get('object_name')
obj = CustomObjectDefinition.objects.filter(
models.Q(name=obj_name) | models.Q(api_name=obj_name)
).first()
if not obj:
raise NotFound(f"Custom object '{obj_name}' not found.")
return obj
def get_queryset(self):
custom_object = self.get_custom_object()
return CustomRecord.objects.filter(custom_object=custom_object).order_by('-created_at')
def perform_create(self, serializer):
custom_object = self.get_custom_object()
serializer.save(custom_object=custom_object, owner=self.request.user)

View file

@ -2,7 +2,17 @@ from .base import *
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': ':memory:',
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'openforce',
'USER': 'openforce',
'PASSWORD': 'openforce',
'HOST': 'localhost',
'PORT': '5432',
}
}
PASSWORD_HASHERS = [
'django.contrib.auth.hashers.MD5PasswordHasher',
]
EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend'

View file

@ -1,6 +1,46 @@
from django.contrib import admin
from django.urls import path
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from crm_core.views import (
AccountViewSet, ContactViewSet, LeadViewSet,
OpportunityViewSet, ActivityViewSet
)
from custom_objects.views import (
CustomObjectDefinitionViewSet, CustomFieldDefinitionViewSet,
CustomRecordViewSet
)
from workflows.views import FlowDefinitionViewSet, FlowExecutionLogViewSet
from outreach.views import EmailTemplateViewSet, CampaignViewSet, TrackEmailOpenView
router = DefaultRouter()
router.register(r'accounts', AccountViewSet, basename='account')
router.register(r'contacts', ContactViewSet, basename='contact')
router.register(r'leads', LeadViewSet, basename='lead')
router.register(r'opportunities', OpportunityViewSet, basename='opportunity')
router.register(r'activities', ActivityViewSet, basename='activity')
router.register(r'custom-objects', CustomObjectDefinitionViewSet, basename='custom-object')
router.register(r'custom-fields', CustomFieldDefinitionViewSet, basename='custom-field')
router.register(r'workflows', FlowDefinitionViewSet, basename='workflow')
router.register(r'workflow-logs', FlowExecutionLogViewSet, basename='workflow-log')
router.register(r'email-templates', EmailTemplateViewSet, basename='email-template')
router.register(r'campaigns', CampaignViewSet, basename='campaign')
urlpatterns = [
path('admin/', admin.site.urls),
path('api/', include(router.urls)),
path('api/track/<uuid:token>/', TrackEmailOpenView.as_view(), name='track_email_open'),
path('api/custom/<str:object_name>/', CustomRecordViewSet.as_view({
'get': 'list',
'post': 'create'
}), name='custom_record_list'),
path('api/custom/<str:object_name>/<int:pk>/', CustomRecordViewSet.as_view({
'get': 'retrieve',
'put': 'update',
'patch': 'partial_update',
'delete': 'destroy'
}), name='custom_record_detail'),
]

View file

@ -1,5 +1,5 @@
from django.apps import AppConfig
class OutreachConfig(AppConfig):
default_auto_field = "django.db.models.BigAutoField"
name = "outreach"
default_auto_field = 'django.db.models.BigAutoField'
name = 'outreach'

56
outreach/engine.py Normal file
View file

@ -0,0 +1,56 @@
from django.core.mail import send_mail
from django.utils import timezone
from .models import Campaign, CampaignRecipient
def inject_tracking_pixel(html_body, tracking_token, base_url="http://localhost:8000"):
"""
Appends a 1x1 transparent tracking GIF image tag before </body> or at the end.
"""
pixel_tag = f'<img src="{base_url}/api/outreach/track/open/{tracking_token}/" width="1" height="1" style="display:none;" alt="" />'
if '</body>' in html_body:
return html_body.replace('</body>', f'{pixel_tag}</body>')
return html_body + pixel_tag
def dispatch_campaign(campaign_id, base_url="http://localhost:8000"):
"""
Dispatches pending recipients in a campaign.
"""
campaign = Campaign.objects.select_related('template').get(pk=campaign_id)
campaign.status = 'sending'
campaign.save(update_fields=['status'])
recipients = campaign.recipients.filter(status='queued')
sent_count = 0
for rec in recipients:
context = {
'first_name': rec.first_name,
'last_name': rec.last_name,
'email': rec.email,
**rec.merge_data
}
subject, body_html, body_text = campaign.template.render(context)
body_html_tracked = inject_tracking_pixel(body_html, rec.tracking_token, base_url=base_url)
try:
send_mail(
subject=subject,
message=body_text or 'Please view this message in HTML.',
html_message=body_html_tracked,
from_email='noreply@openforce.local',
recipient_list=[rec.email],
fail_silently=False
)
rec.status = 'sent'
rec.sent_at = timezone.now()
rec.save(update_fields=['status', 'sent_at'])
sent_count += 1
except Exception:
rec.status = 'failed'
rec.save(update_fields=['status'])
campaign.status = 'completed'
campaign.save(update_fields=['status'])
return sent_count

View file

@ -1,6 +1,9 @@
# Generated by Django 4.2.30 on 2026-09-26 07:21
# Generated by Django 4.2.30 on 2026-09-26 07:25
from django.conf import settings
from django.db import migrations, models
import django.db.models.deletion
import uuid
class Migration(migrations.Migration):
@ -8,14 +11,53 @@ class Migration(migrations.Migration):
initial = True
dependencies = [
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
migrations.CreateModel(
name='EmailTemplate',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('name', models.CharField(max_length=255, unique=True)),
('subject', models.CharField(max_length=255)),
('body_html', models.TextField(help_text='HTML content supporting merge tags like {{first_name}}')),
('body_text', models.TextField(blank=True, default='')),
('created_at', models.DateTimeField(auto_now_add=True)),
('updated_at', models.DateTimeField(auto_now=True)),
('created_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.AUTH_USER_MODEL)),
],
),
migrations.CreateModel(
name='Campaign',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('name', models.CharField(max_length=255)),
('status', models.CharField(choices=[('draft', 'Draft'), ('scheduled', 'Scheduled'), ('sending', 'Sending'), ('completed', 'Completed'), ('cancelled', 'Cancelled')], default='draft', max_length=20)),
('scheduled_at', models.DateTimeField(blank=True, null=True)),
('created_at', models.DateTimeField(auto_now_add=True)),
('updated_at', models.DateTimeField(auto_now=True)),
('created_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.AUTH_USER_MODEL)),
('template', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='campaigns', to='outreach.emailtemplate')),
],
),
migrations.CreateModel(
name='CampaignRecipient',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('email', models.EmailField(max_length=254)),
('first_name', models.CharField(blank=True, default='', max_length=100)),
('last_name', models.CharField(blank=True, default='', max_length=100)),
('merge_data', models.JSONField(default=dict)),
('tracking_token', models.UUIDField(default=uuid.uuid4, editable=False, unique=True)),
('status', models.CharField(choices=[('queued', 'Queued'), ('sent', 'Sent'), ('delivered', 'Delivered'), ('opened', 'Opened'), ('clicked', 'Clicked'), ('bounced', 'Bounced'), ('failed', 'Failed')], default='queued', max_length=20)),
('sent_at', models.DateTimeField(blank=True, null=True)),
('opened_at', models.DateTimeField(blank=True, null=True)),
('clicked_at', models.DateTimeField(blank=True, null=True)),
('campaign', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='recipients', to='outreach.campaign')),
],
options={
'unique_together': {('campaign', 'email')},
},
),
]

View file

@ -1,4 +1,90 @@
import uuid
import re
from django.db import models
from django.contrib.auth import get_user_model
from django.core.exceptions import ValidationError
User = get_user_model()
class EmailTemplate(models.Model):
name = models.CharField(max_length=255, unique=True)
subject = models.CharField(max_length=255)
body_html = models.TextField(help_text="HTML content supporting merge tags like {{first_name}}")
body_text = models.TextField(blank=True, default='')
created_by = models.ForeignKey(User, null=True, blank=True, on_delete=models.SET_NULL)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
def render(self, context):
"""
Safely renders template variables with {{var_name}} merge tags.
"""
subject = self.subject
body_html = self.body_html
body_text = self.body_text
for key, val in context.items():
pattern = re.compile(r'\{\{\s*' + re.escape(key) + r'\s*\}\}')
subject = pattern.sub(str(val or ''), subject)
body_html = pattern.sub(str(val or ''), body_html)
body_text = pattern.sub(str(val or ''), body_text)
return subject, body_html, body_text
def __str__(self):
return self.name
class Campaign(models.Model):
STATUS_CHOICES = [
('draft', 'Draft'),
('scheduled', 'Scheduled'),
('sending', 'Sending'),
('completed', 'Completed'),
('cancelled', 'Cancelled'),
]
name = models.CharField(max_length=255)
template = models.ForeignKey(EmailTemplate, on_delete=models.PROTECT, related_name='campaigns')
status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='draft')
scheduled_at = models.DateTimeField(null=True, blank=True)
created_by = models.ForeignKey(User, null=True, blank=True, on_delete=models.SET_NULL)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
def __str__(self):
return f"{self.name} [{self.status}]"
class CampaignRecipient(models.Model):
STATUS_CHOICES = [
('queued', 'Queued'),
('sent', 'Sent'),
('delivered', 'Delivered'),
('opened', 'Opened'),
('clicked', 'Clicked'),
('bounced', 'Bounced'),
('failed', 'Failed'),
]
campaign = models.ForeignKey(Campaign, on_delete=models.CASCADE, related_name='recipients')
email = models.EmailField()
first_name = models.CharField(max_length=100, blank=True, default='')
last_name = models.CharField(max_length=100, blank=True, default='')
merge_data = models.JSONField(default=dict)
tracking_token = models.UUIDField(default=uuid.uuid4, unique=True, editable=False)
status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='queued')
sent_at = models.DateTimeField(null=True, blank=True)
opened_at = models.DateTimeField(null=True, blank=True)
clicked_at = models.DateTimeField(null=True, blank=True)
class Meta:
unique_together = [['campaign', 'email']]
def __str__(self):
return f"{self.email} in {self.campaign.name}"

25
outreach/serializers.py Normal file
View file

@ -0,0 +1,25 @@
from rest_framework import serializers
from .models import EmailTemplate, Campaign, CampaignRecipient
class EmailTemplateSerializer(serializers.ModelSerializer):
class Meta:
model = EmailTemplate
fields = '__all__'
read_only_fields = ['id', 'created_at', 'updated_at']
class CampaignRecipientSerializer(serializers.ModelSerializer):
class Meta:
model = CampaignRecipient
fields = '__all__'
read_only_fields = ['id', 'tracking_token', 'sent_at', 'opened_at', 'clicked_at']
class CampaignSerializer(serializers.ModelSerializer):
recipients = CampaignRecipientSerializer(many=True, read_only=True)
class Meta:
model = Campaign
fields = '__all__'
read_only_fields = ['id', 'created_at', 'updated_at']

61
outreach/views.py Normal file
View file

@ -0,0 +1,61 @@
import base64
from django.http import HttpResponse
from django.utils import timezone
from rest_framework import viewsets, status
from rest_framework.views import APIView
from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework.permissions import IsAuthenticated, AllowAny
from .models import EmailTemplate, Campaign, CampaignRecipient
from .serializers import EmailTemplateSerializer, CampaignSerializer, CampaignRecipientSerializer
from .engine import dispatch_campaign
PIXEL_GIF_BYTES = base64.b64decode('R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7')
class EmailTemplateViewSet(viewsets.ModelViewSet):
permission_classes = [IsAuthenticated]
queryset = EmailTemplate.objects.all().order_by('-created_at')
serializer_class = EmailTemplateSerializer
class CampaignViewSet(viewsets.ModelViewSet):
permission_classes = [IsAuthenticated]
queryset = Campaign.objects.all().order_by('-created_at')
serializer_class = CampaignSerializer
@action(detail=True, methods=['post'], url_path='dispatch')
def dispatch_now(self, request, pk=None):
campaign = self.get_object()
sent_count = dispatch_campaign(campaign.id)
return Response({'status': 'dispatched', 'sent_count': sent_count}, status=status.HTTP_200_OK)
@action(detail=True, methods=['post'], url_path='add-recipients')
def add_recipients(self, request, pk=None):
campaign = self.get_object()
recipients_data = request.data.get('recipients', [])
created = []
for r in recipients_data:
rec, _ = CampaignRecipient.objects.get_or_create(
campaign=campaign,
email=r['email'],
defaults={'first_name': r.get('first_name', ''), 'last_name': r.get('last_name', ''), 'merge_data': r.get('merge_data', {})}
)
created.append(rec)
return Response({'count': len(created)}, status=status.HTTP_201_CREATED)
class TrackEmailOpenView(APIView):
permission_classes = [AllowAny]
def get(self, request, token=None):
try:
recipient = CampaignRecipient.objects.get(tracking_token=token)
if not recipient.opened_at:
recipient.opened_at = timezone.now()
recipient.status = 'opened'
recipient.save(update_fields=['opened_at', 'status'])
except CampaignRecipient.DoesNotExist:
pass
return HttpResponse(PIXEL_GIF_BYTES, content_type='image/gif')

55
tests/crm/test_api.py Normal file
View file

@ -0,0 +1,55 @@
from decimal import Decimal
from rest_framework.test import APITestCase
from rest_framework import status
from django.contrib.auth import get_user_model
from crm_core.models import Account, Contact, Lead, Opportunity
User = get_user_model()
class AuthEnforcementMixin:
def assert_auth_enforced(self, url, method='get', data=None):
self.client.logout()
func = getattr(self.client, method)
response = func(url, data=data, format='json')
self.assertIn(response.status_code, [status.HTTP_401_UNAUTHORIZED, status.HTTP_403_FORBIDDEN])
class TestCRMAPI(APITestCase, AuthEnforcementMixin):
def setUp(self):
self.user = User.objects.create_user('apiuser', 'api@test.com', 'password123')
self.client.force_authenticate(user=self.user)
def test_account_endpoints_auth_enforced(self):
self.assert_auth_enforced('/api/accounts/')
def test_contact_endpoints_auth_enforced(self):
self.assert_auth_enforced('/api/contacts/')
def test_lead_endpoints_auth_enforced(self):
self.assert_auth_enforced('/api/leads/')
def test_opportunity_endpoints_auth_enforced(self):
self.assert_auth_enforced('/api/opportunities/')
def test_account_crud(self):
resp = self.client.post('/api/accounts/', {'name': 'Globex Inc', 'industry': 'Manufacturing'}, format='json')
self.assertEqual(resp.status_code, status.HTTP_201_CREATED)
acc_id = resp.data['id']
resp = self.client.get(f'/api/accounts/{acc_id}/')
self.assertEqual(resp.status_code, status.HTTP_200_OK)
self.assertEqual(resp.data['name'], 'Globex Inc')
def test_lead_conversion_api(self):
lead = Lead.objects.create(first_name='Peter', last_name='Parker', company='Daily Bugle', owner=self.user)
payload = {
'create_opportunity': True,
'opportunity_name': 'Bugle Exclusive',
'opportunity_amount': '5000.00'
}
resp = self.client.post(f'/api/leads/{lead.id}/convert/', payload, format='json')
self.assertEqual(resp.status_code, status.HTTP_200_OK)
self.assertIn('account', resp.data)
self.assertIn('contact', resp.data)
self.assertIn('opportunity', resp.data)

152
tests/crm/test_models.py Normal file
View file

@ -0,0 +1,152 @@
from decimal import Decimal
from datetime import date
from django.test import TestCase
from django.core.exceptions import ValidationError
from django.contrib.auth import get_user_model
from django.contrib.contenttypes.models import ContentType
from crm_core.models import Account, Contact, Lead, Opportunity, Activity
from crm_core.services import convert_lead
User = get_user_model()
class TestAccountModel(TestCase):
def setUp(self):
self.user = User.objects.create_user('accuser', 'acc@test.com', 'pass')
def test_account_creation(self):
acc = Account.objects.create(name='Acme Corp', industry='Technology', owner=self.user)
self.assertEqual(str(acc), 'Acme Corp')
self.assertEqual(acc.industry, 'Technology')
def test_account_type_choices(self):
acc = Account.objects.create(name='Beta LLC', type='Customer', owner=self.user)
self.assertEqual(acc.type, 'Customer')
def test_account_parent_relationship(self):
p = Account.objects.create(name='Parent Corp', owner=self.user)
c = Account.objects.create(name='Child Corp', parent=p, owner=self.user)
self.assertEqual(c.parent, p)
class TestContactModel(TestCase):
def setUp(self):
self.user = User.objects.create_user('conuser', 'con@test.com', 'pass')
self.acc = Account.objects.create(name='Acme Corp', owner=self.user)
def test_contact_str(self):
con = Contact.objects.create(first_name='John', last_name='Doe', email='john@acme.com', account=self.acc, owner=self.user)
self.assertEqual(str(con), 'John Doe (john@acme.com)')
def test_contact_email_format_validation(self):
con = Contact(first_name='Invalid', last_name='Email', email='not-an-email', account=self.acc)
with self.assertRaises(ValidationError):
con.full_clean()
class TestLeadModel(TestCase):
def setUp(self):
self.user = User.objects.create_user('leaduser', 'lead@test.com', 'pass')
def test_lead_default_status_is_new(self):
lead = Lead.objects.create(first_name='Alice', last_name='Smith', company='Initech', owner=self.user)
self.assertEqual(lead.status, 'New')
def test_lead_is_converted_defaults_false(self):
lead = Lead.objects.create(first_name='Bob', last_name='Jones', company='Stark', owner=self.user)
self.assertFalse(lead.is_converted)
def test_lead_str(self):
lead = Lead.objects.create(first_name='Alice', last_name='Smith', company='Initech', owner=self.user)
self.assertEqual(str(lead), 'Alice Smith - Initech')
def test_converted_lead_has_converted_account(self):
lead = Lead.objects.create(first_name='Charlie', last_name='Brown', company='Peanuts', owner=self.user)
acc, con, opp = convert_lead(lead)
lead.refresh_from_db()
self.assertTrue(lead.is_converted)
self.assertEqual(lead.converted_account, acc)
self.assertEqual(lead.converted_contact, con)
class TestOpportunityModel(TestCase):
def setUp(self):
self.user = User.objects.create_user('oppuser', 'opp@test.com', 'pass')
self.acc = Account.objects.create(name='Big Corp', owner=self.user)
def test_amount_non_negative(self):
opp = Opportunity(name='Bad Opp', account=self.acc, stage='Prospecting', amount=Decimal('-500.00'), close_date=date.today())
with self.assertRaises(ValidationError):
opp.full_clean()
def test_close_date_required(self):
opp = Opportunity(name='No Close', account=self.acc, stage='Prospecting', amount=Decimal('100.00'), close_date=None)
with self.assertRaises(ValidationError):
opp.full_clean()
def test_probability_range_0_to_100(self):
opp = Opportunity(name='High Prob', account=self.acc, stage='Prospecting', amount=Decimal('100.00'), probability=150, close_date=date.today())
with self.assertRaises(ValidationError):
opp.full_clean()
def test_stage_choices_exhaustive(self):
valid_stages = [
'Prospecting', 'Qualification', 'Needs Analysis', 'Value Proposition',
'Id. Decision Makers', 'Perception Analysis', 'Proposal/Price Quote',
'Negotiation/Review', 'Closed Won', 'Closed Lost'
]
for stg in valid_stages:
opp = Opportunity(name=f'Opp {stg}', account=self.acc, stage=stg, amount=Decimal('1000.00'), close_date=date.today(), owner=self.user)
opp.full_clean()
opp.save()
self.assertEqual(opp.stage, stg)
class TestLeadConversionTransaction(TestCase):
def setUp(self):
self.user = User.objects.create_user('transuser', 'trans@test.com', 'pass')
self.lead = Lead.objects.create(
first_name='Bruce', last_name='Wayne', company='Wayne Enterprises',
email='bruce@wayne.com', owner=self.user
)
def test_cannot_convert_already_converted_lead(self):
convert_lead(self.lead)
with self.assertRaises(ValidationError):
convert_lead(self.lead)
def test_conversion_creates_account_and_contact(self):
acc, con, opp = convert_lead(self.lead)
self.assertEqual(acc.name, 'Wayne Enterprises')
self.assertEqual(con.first_name, 'Bruce')
self.assertEqual(con.last_name, 'Wayne')
self.assertEqual(con.account, acc)
self.assertIsNone(opp)
def test_conversion_with_opportunity(self):
acc, con, opp = convert_lead(
self.lead,
create_opportunity=True,
opportunity_name='Batmobile Deal',
opportunity_amount=Decimal('500000.00'),
opportunity_close_date=date(2026, 12, 31)
)
self.assertIsNotNone(opp)
self.assertEqual(opp.name, 'Batmobile Deal')
self.assertEqual(opp.amount, Decimal('500000.00'))
self.assertEqual(opp.account, acc)
def test_activities_repointed_on_conversion(self):
lead_ct = ContentType.objects.get_for_model(Lead)
act = Activity.objects.create(
subject='Initial pitch',
activity_type='Call',
content_type=lead_ct,
object_id=self.lead.id,
assigned_to=self.user
)
acc, con, opp = convert_lead(self.lead)
act.refresh_from_db()
contact_ct = ContentType.objects.get_for_model(Contact)
self.assertEqual(act.content_type, contact_ct)
self.assertEqual(act.object_id, con.id)

View file

@ -0,0 +1,93 @@
from django.test import TestCase
from django.db import connection
from django.core.exceptions import ValidationError
from django.contrib.auth import get_user_model
from rest_framework.test import APITestCase
from rest_framework import status
from custom_objects.models import CustomObjectDefinition, CustomFieldDefinition, CustomRecord
from custom_objects.schema_engine import build_schema_for_object, validate_record_data
User = get_user_model()
class TestCustomObjectMetamodel(TestCase):
def setUp(self):
self.user = User.objects.create_user('co_user', 'co@test.com', 'pass')
def test_custom_object_slug_must_end_with_c(self):
co = CustomObjectDefinition(name='deal__c', label='Deal', created_by=self.user)
co.full_clean()
co.save()
self.assertEqual(co.name, 'deal__c')
def test_prevent_reserved_system_names(self):
co = CustomObjectDefinition(name='account__c', label='Account', created_by=self.user)
with self.assertRaises(ValidationError):
co.full_clean()
def test_gin_index_exists_on_custom_record(self):
with connection.cursor() as cursor:
cursor.execute("""
SELECT indexname FROM pg_indexes
WHERE tablename = 'custom_record' AND indexname = 'idx_custom_record_data_gin';
""")
row = cursor.fetchone()
self.assertIsNotNone(row, "GIN index idx_custom_record_data_gin should exist in PostgreSQL")
class TestCustomSchemaEngine(TestCase):
def setUp(self):
self.user = User.objects.create_user('engine_user', 'eng@test.com', 'pass')
self.obj = CustomObjectDefinition.objects.create(name='invoice__c', label='Invoice', created_by=self.user)
CustomFieldDefinition.objects.create(
custom_object=self.obj, name='amount__c', label='Amount',
field_type='number', is_required=True
)
CustomFieldDefinition.objects.create(
custom_object=self.obj, name='status__c', label='Status',
field_type='picklist', is_required=False,
options=['Draft', 'Sent', 'Paid']
)
def test_schema_validates_valid_payload(self):
data = {'amount__c': 1500.50, 'status__c': 'Paid'}
self.assertTrue(validate_record_data(self.obj, data))
def test_schema_rejects_missing_required(self):
data = {'status__c': 'Paid'}
with self.assertRaises(ValidationError):
validate_record_data(self.obj, data)
def test_schema_rejects_invalid_picklist_choice(self):
data = {'amount__c': 100, 'status__c': 'Unknown'}
with self.assertRaises(ValidationError):
validate_record_data(self.obj, data)
def test_schema_rejects_unknown_properties(self):
data = {'amount__c': 100, 'injected_key': 'malicious'}
with self.assertRaises(ValidationError):
validate_record_data(self.obj, data)
class TestDynamicCustomObjectAPI(APITestCase):
def setUp(self):
self.user = User.objects.create_user('api_custom_user', 'api_c@test.com', 'pass')
self.client.force_authenticate(user=self.user)
self.obj = CustomObjectDefinition.objects.create(name='project__c', label='Project', created_by=self.user)
CustomFieldDefinition.objects.create(
custom_object=self.obj, name='title__c', label='Title',
field_type='text', is_required=True
)
def test_create_and_fetch_custom_record(self):
resp = self.client.post(
f'/api/custom/{self.obj.name}/',
{'data': {'title__c': 'Apollo Mission'}},
format='json'
)
self.assertEqual(resp.status_code, status.HTTP_201_CREATED)
rec_id = resp.data['id']
resp = self.client.get(f'/api/custom/{self.obj.name}/{rec_id}/')
self.assertEqual(resp.status_code, status.HTTP_200_OK)
self.assertEqual(resp.data['data']['title__c'], 'Apollo Mission')

View file

@ -0,0 +1,40 @@
import pytest
from django.contrib.auth import get_user_model
from rest_framework.test import APIClient
from custom_objects.models import CustomObjectDefinition, CustomFieldDefinition, CustomRecord
User = get_user_model()
@pytest.mark.django_db
def test_partial_update_does_not_require_all_fields():
user = User.objects.create_user('patch_user', 'patch@test.com', 'pass')
client = APIClient()
client.force_authenticate(user=user)
obj = CustomObjectDefinition.objects.create(name='ticket__c', label='Ticket', created_by=user)
CustomFieldDefinition.objects.create(
custom_object=obj, name='subject__c', label='Subject',
field_type='text', is_required=True
)
CustomFieldDefinition.objects.create(
custom_object=obj, name='priority__c', label='Priority',
field_type='picklist', is_required=True,
options=['Low', 'Medium', 'High']
)
rec = CustomRecord.objects.create(
custom_object=obj,
data={'subject__c': 'Initial Bug', 'priority__c': 'High'},
created_by=user
)
resp = client.patch(
f'/api/custom/{obj.name}/{rec.id}/',
{'data': {'priority__c': 'Medium'}},
format='json'
)
assert resp.status_code == 200
rec.refresh_from_db()
assert rec.data['priority__c'] == 'Medium'
assert rec.data['subject__c'] == 'Initial Bug'

View file

@ -0,0 +1,81 @@
from django.test import TestCase
from django.core.exceptions import ValidationError
from django.contrib.auth import get_user_model
from workflows.models import FlowDefinition, FlowExecutionLog
from workflows.engine import validate_flow_dag, get_topological_execution_order, execute_flow_dag
User = get_user_model()
class TestDAGCycleDetection(TestCase):
def setUp(self):
self.user = User.objects.create_user('flowuser', 'fu@openforce.local', 'password123')
def test_linear_dag_accepted(self):
graph = {
'nodes': [{'id': '1'}, {'id': '2'}, {'id': '3'}],
'edges': [
{'source': '1', 'target': '2'},
{'source': '2', 'target': '3'},
]
}
flow = FlowDefinition(name='Linear Flow', graph=graph, created_by=self.user)
flow.save()
self.assertIsNotNone(flow.pk)
def test_cycle_rejected_on_save(self):
graph = {
'nodes': [{'id': 'A'}, {'id': 'B'}],
'edges': [
{'source': 'A', 'target': 'B'},
{'source': 'B', 'target': 'A'}
]
}
flow = FlowDefinition(name='Cyclic Flow', graph=graph, created_by=self.user)
with self.assertRaises(ValidationError):
flow.save()
def test_topological_order_correctness(self):
graph = {
'nodes': [{'id': 'start'}, {'id': 'middle'}, {'id': 'end'}],
'edges': [
{'source': 'start', 'target': 'middle'},
{'source': 'middle', 'target': 'end'}
]
}
order = get_topological_execution_order(graph)
self.assertEqual(order, ['start', 'middle', 'end'])
def test_dangling_edge_raises_validation_error(self):
graph = {
'nodes': [{'id': '1', 'type': 'action', 'data': {'action': 'set_stage', 'stage': 'Qualified'}}],
'edges': [{'source': '1', 'target': '999'}]
}
with self.assertRaises(ValidationError):
validate_flow_dag(graph)
class TestDAGExecution(TestCase):
def setUp(self):
self.user = User.objects.create_user('execuser', 'ex@openforce.local', 'password123')
graph = {
'nodes': [
{'id': '1', 'type': 'action', 'data': {'action': 'set_stage', 'stage': 'Qualification'}},
{'id': '2', 'type': 'action', 'data': {'action': 'increment_score', 'points': 10}}
],
'edges': [{'source': '1', 'target': '2'}]
}
self.flow = FlowDefinition.objects.create(name='Simple Flow', graph=graph, created_by=self.user)
def test_execution_completes_successfully(self):
log = execute_flow_dag(self.flow, initial_context={'score': 5})
self.assertEqual(log.status, 'completed')
self.assertEqual(log.context['score'], 15)
self.assertEqual(log.context['stage'], 'Qualification')
def test_execution_idempotency(self):
key = 'unique-key-12345'
log1 = execute_flow_dag(self.flow, idempotency_key=key)
log2 = execute_flow_dag(self.flow, idempotency_key=key)
self.assertEqual(log1.id, log2.id)
self.assertEqual(FlowExecutionLog.objects.filter(idempotency_key=key).count(), 1)

View file

@ -1,5 +1,5 @@
from django.apps import AppConfig
class WorkflowsConfig(AppConfig):
default_auto_field = "django.db.models.BigAutoField"
name = "workflows"
default_auto_field = 'django.db.models.BigAutoField'
name = 'workflows'

View file

@ -1,3 +1,148 @@
class WorkflowEngine:
pass
from collections import deque
from django.utils import timezone
from django.core.exceptions import ValidationError
from .models import FlowExecutionLog
def validate_flow_dag(graph):
"""
Validates that the Vue Flow graph has no cycles and forms a valid DAG using Kahn's algorithm.
Also validates that all edges point to real node IDs.
"""
nodes = graph.get('nodes', [])
edges = graph.get('edges', [])
if not nodes:
return True
node_ids = {n['id'] for n in nodes if 'id' in n}
# Build adjacency and in-degree map
in_degree = {nid: 0 for nid in node_ids}
adj = {nid: [] for nid in node_ids}
for edge in edges:
src = edge.get('source')
tgt = edge.get('target')
# Dangling edge validation
if src not in node_ids or tgt not in node_ids:
raise ValidationError(f"Edge references non-existent node: {src} -> {tgt}")
adj[src].append(tgt)
in_degree[tgt] += 1
# Kahn's algorithm
queue = deque([nid for nid in node_ids if in_degree[nid] == 0])
visited_count = 0
while queue:
curr = queue.popleft()
visited_count += 1
for neighbor in adj[curr]:
in_degree[neighbor] -= 1
if in_degree[neighbor] == 0:
queue.append(neighbor)
if visited_count != len(node_ids):
raise ValidationError("Workflow graph contains cycles or self-referencing loops.")
return True
def topological_sort(graph):
"""
Returns ordered list of node IDs to execute in topological DAG sequence.
"""
validate_flow_dag(graph)
nodes = graph.get('nodes', [])
edges = graph.get('edges', [])
node_ids = [n['id'] for n in nodes if 'id' in n]
in_degree = {nid: 0 for nid in node_ids}
adj = {nid: [] for nid in node_ids}
for edge in edges:
src = edge.get('source')
tgt = edge.get('target')
adj[src].append(tgt)
in_degree[tgt] += 1
queue = deque([nid for nid in node_ids if in_degree[nid] == 0])
execution_order = []
while queue:
curr = queue.popleft()
execution_order.append(curr)
for neighbor in adj[curr]:
in_degree[neighbor] -= 1
if in_degree[neighbor] == 0:
queue.append(neighbor)
return execution_order
get_topological_execution_order = topological_sort
def execute_flow_dag(flow_def, initial_context=None, idempotency_key=None):
"""
Executes a FlowDefinition DAG given context data.
"""
if idempotency_key:
existing = FlowExecutionLog.objects.filter(idempotency_key=idempotency_key).first()
if existing:
return existing
log = FlowExecutionLog.objects.create(
flow=flow_def,
status='running',
context_data=initial_context or {},
idempotency_key=idempotency_key
)
try:
execution_order = topological_sort(flow_def.graph)
node_map = {n['id']: n for n in flow_def.graph.get('nodes', [])}
steps = []
context = dict(initial_context or {})
for node_id in execution_order:
node = node_map.get(node_id, {})
node_type = node.get('type')
node_data = node.get('data', {})
step_record = {
'node_id': node_id,
'type': node_type,
'status': 'success'
}
if node_type == 'action':
action_name = node_data.get('action')
if action_name == 'update_record':
field = node_data.get('field')
val = node_data.get('value')
context.setdefault('record_data', {})[field] = val
elif action_name == 'set_stage':
context['stage'] = node_data.get('stage')
steps.append(step_record)
log.status = 'completed'
log.steps_executed = steps
log.context_data = context
log.completed_at = timezone.now()
log.save()
return log
except Exception as e:
log.status = 'failed'
log.error_message = str(e)
log.completed_at = timezone.now()
log.save()
raise

View file

@ -1,6 +1,8 @@
# Generated by Django 4.2.30 on 2026-09-26 07:21
# Generated by Django 4.2.30 on 2026-09-26 07:25
from django.conf import settings
from django.db import migrations, models
import django.db.models.deletion
class Migration(migrations.Migration):
@ -8,14 +10,46 @@ class Migration(migrations.Migration):
initial = True
dependencies = [
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
migrations.CreateModel(
name='WorkflowItem',
name='FlowDefinition',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('name', models.CharField(max_length=255)),
('description', models.TextField(blank=True, default='')),
('trigger_type', models.CharField(choices=[('record_created', 'Record Created'), ('record_updated', 'Record Updated'), ('scheduled', 'Scheduled'), ('manual', 'Manual / API Trigger')], default='manual', max_length=50)),
('is_active', models.BooleanField(default=True)),
('graph', models.JSONField(default=dict, help_text='Vue Flow DAG graph structure with nodes and edges')),
('created_at', models.DateTimeField(auto_now_add=True)),
('updated_at', models.DateTimeField(auto_now=True)),
('created_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.AUTH_USER_MODEL)),
],
options={
'ordering': ['-created_at'],
},
),
migrations.CreateModel(
name='FlowExecutionLog',
fields=[
('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
('status', models.CharField(choices=[('pending', 'Pending'), ('running', 'Running'), ('completed', 'Completed'), ('failed', 'Failed')], default='pending', max_length=20)),
('started_at', models.DateTimeField(auto_now_add=True)),
('completed_at', models.DateTimeField(blank=True, null=True)),
('steps_executed', models.JSONField(default=list)),
('context_data', models.JSONField(default=dict)),
('error_message', models.TextField(blank=True, default='')),
('idempotency_key', models.CharField(blank=True, db_index=True, max_length=255, null=True)),
('flow', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='executions', to='workflows.flowdefinition')),
],
options={
'ordering': ['-started_at'],
},
),
migrations.AddConstraint(
model_name='flowexecutionlog',
constraint=models.UniqueConstraint(condition=models.Q(('idempotency_key__isnull', False)), fields=('idempotency_key',), name='unique_idempotency_key_when_not_null'),
),
]

View file

@ -1,4 +1,75 @@
from django.db import models
from django.contrib.auth import get_user_model
from django.core.exceptions import ValidationError
User = get_user_model()
class FlowDefinition(models.Model):
TRIGGER_TYPE_CHOICES = [
('record_created', 'Record Created'),
('record_updated', 'Record Updated'),
('scheduled', 'Scheduled'),
('manual', 'Manual / API Trigger'),
]
class WorkflowItem(models.Model):
name = models.CharField(max_length=255)
description = models.TextField(blank=True, default='')
trigger_type = models.CharField(max_length=50, choices=TRIGGER_TYPE_CHOICES, default='manual')
is_active = models.BooleanField(default=True)
# Vue Flow Graph: { "nodes": [...], "edges": [...] }
graph = models.JSONField(
default=dict,
help_text="Vue Flow DAG graph structure with nodes and edges"
)
created_by = models.ForeignKey(User, null=True, blank=True, on_delete=models.SET_NULL)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
class Meta:
ordering = ['-created_at']
def clean(self):
super().clean()
from .engine import validate_flow_dag
validate_flow_dag(self.graph)
def save(self, *args, **kwargs):
self.clean()
super().save(*args, **kwargs)
def __str__(self):
return f"{self.name} ({'Active' if self.is_active else 'Draft'})"
class FlowExecutionLog(models.Model):
STATUS_CHOICES = [
('pending', 'Pending'),
('running', 'Running'),
('completed', 'Completed'),
('failed', 'Failed'),
]
flow = models.ForeignKey(FlowDefinition, on_delete=models.CASCADE, related_name='executions')
status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='pending')
started_at = models.DateTimeField(auto_now_add=True)
completed_at = models.DateTimeField(null=True, blank=True)
steps_executed = models.JSONField(default=list)
context_data = models.JSONField(default=dict)
error_message = models.TextField(blank=True, default='')
idempotency_key = models.CharField(max_length=255, null=True, blank=True, db_index=True)
class Meta:
ordering = ['-started_at']
constraints = [
models.UniqueConstraint(
fields=['idempotency_key'],
name='unique_idempotency_key_when_not_null',
condition=models.Q(idempotency_key__isnull=False)
)
]
def __str__(self):
return f"Execution of {self.flow.name} [{self.status}]"

21
workflows/serializers.py Normal file
View file

@ -0,0 +1,21 @@
from rest_framework import serializers
from .models import FlowDefinition, FlowExecutionLog
from .engine import validate_flow_dag
class FlowDefinitionSerializer(serializers.ModelSerializer):
class Meta:
model = FlowDefinition
fields = '__all__'
read_only_fields = ['id', 'created_at', 'updated_at']
def validate_graph(self, value):
validate_flow_dag(value)
return value
class FlowExecutionLogSerializer(serializers.ModelSerializer):
class Meta:
model = FlowExecutionLog
fields = '__all__'
read_only_fields = ['id', 'started_at', 'completed_at']

29
workflows/views.py Normal file
View file

@ -0,0 +1,29 @@
from rest_framework import viewsets, status
from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework.permissions import IsAuthenticated
from .models import FlowDefinition, FlowExecutionLog
from .serializers import FlowDefinitionSerializer, FlowExecutionLogSerializer
from .engine import execute_flow_dag
class FlowDefinitionViewSet(viewsets.ModelViewSet):
permission_classes = [IsAuthenticated]
queryset = FlowDefinition.objects.all().order_by('-created_at')
serializer_class = FlowDefinitionSerializer
@action(detail=True, methods=['post'], url_path='run')
def run_flow(self, request, pk=None):
flow = self.get_object()
context_data = request.data.get('context', {})
idempotency_key = request.data.get('idempotency_key')
log = execute_flow_dag(flow, initial_context=context_data, idempotency_key=idempotency_key)
return Response(FlowExecutionLogSerializer(log).data, status=status.HTTP_200_OK)
class FlowExecutionLogViewSet(viewsets.ReadOnlyModelViewSet):
permission_classes = [IsAuthenticated]
queryset = FlowExecutionLog.objects.all().order_by('-started_at')
serializer_class = FlowExecutionLogSerializer
filterset_fields = ['flow', 'status']