+    class MultiFileInput(forms.ClearableFileInput):

+        allow_multiple_selected = True

+

+    photos = forms.FileField(required=False, widget=MultiFileInput, help_text="Optional: upload photos of scrap")

+    <form method="post" enctype="multipart/form-data" action="{% url 'public_frontend:pickup_request' %}" class="bg-white rounded-lg shadow-md p-4 grid gap-4">

+        <label class="block text-sm font-medium mb-1">Photos (optional)</label>

+        <input type="file" name="photos" multiple accept="image/*" class="w-full border rounded px-3 py-2">

+      </div>

+      <div>

+          <td class="px-4 py-2">{{ m.get_category_display }}</td>

+<form method="post" enctype="multipart/form-data" class="bg-white rounded shadow p-4 grid gap-4">

+    <label class="block text-sm font-medium mb-1">Photos (optional)</label>

+    <input type="file" name="photos" multiple accept="image/*" class="w-full border rounded px-3 py-2">

+  </div>

+  <div>

+from recycle_core.controllers.pickup_request import (

+    PickupRequestController,

+    PickupRequestData,

+)

+    form = PickupRequestForm(request.POST or None, request.FILES or None)

+            ctrl = PickupRequestController()

+            data = PickupRequestData(

+                name=form.cleaned_data.get("name"),

+                email=form.cleaned_data.get("email", ""),

+                phone=form.cleaned_data.get("phone", ""),

+                address=form.cleaned_data.get("address", ""),

+                materials=form.cleaned_data.get("materials", ""),

+                preferred_at=form.cleaned_data.get("preferred_at"),

+                files=request.FILES.getlist("photos") if hasattr(request, "FILES") and "photos" in request.FILES else [],

+            result = ctrl.submit(data)

+            if result.ok:

+                messages.success(request, "Thanks! Your pickup request was submitted.")

+                return redirect("public_frontend:home")

+            else:

+                messages.error(request, result.error or "Unable to submit your request.")

+    list_display = ("name", "code", "get_category_display", "organization", "default_unit")

+    class MaterialImageInline(admin.TabularInline):

+        model = models.MaterialImage

+        extra = 1

+    inlines = [MaterialImageInline]

+from __future__ import annotations

+

+from __future__ import annotations

+

+from dataclasses import dataclass

+from typing import Iterable, List, Optional

+from django.contrib.contenttypes.models import ContentType

+from django.utils import timezone

+

+from orgs.models import Organization

+from recycle_core.models import Document

+

+

+@dataclass

+class PickupRequestData:

+    organization: Organization

+    name: str

+    email: str = ""

+    phone: str = ""

+    address: str = ""

+    materials: str = ""

+    preferred_at: Optional[timezone.datetime] = None

+    files: Optional[Iterable] = None  # iterable of UploadedFile

+

+

+@dataclass

+class PickupRequestResult:

+    ok: bool

+    lead_id: Optional[int] = None

+    error: Optional[str] = None

+    document_ids: List[int] = None

+

+

+class PickupRequestController:

+    """Application layer controller for the fast-path pickup request.

+

+    - Creates a Lead scoped to an Organization

+    - Stores any uploaded photos/documents as Document records attached to the Lead

+    """

+

+    def submit(self, data: PickupRequestData) -> PickupRequestResult:

+        from public_frontend.models import Lead  # import locally to avoid circular imports

+

+        try:

+            # Prepare message body for staff

+            message = (

+                f"Pickup Request\n"

+                f"Address: {data.address}\n"

+                f"Preferred: {data.preferred_at or ''}\n"

+                f"Materials: {data.materials or ''}"

+            )

+

+            lead = Lead.objects.create(

+                organization=data.organization,

+                name=data.name,

+                email=data.email or "",

+                phone=data.phone or "",

+                subject="Pickup Request",

+                message=message,

+                source="pickup_request",

+            )

+

+            # Attach uploaded files as Documents linked to the Lead

+            doc_ids: List[int] = []

+            if data.files:

+                ct = ContentType.objects.get_for_model(Lead)

+                for idx, f in enumerate(data.files):

+                    doc = Document.objects.create(

+                        organization=data.organization,

+                        file=f,

+                        kind="pickup_request",

+                        content_type=ct,

+                        object_id=lead.id,

+                        uploaded_by=None,

+                    )

+                    doc_ids.append(doc.id)

+

+            return PickupRequestResult(ok=True, lead_id=lead.id, document_ids=doc_ids)

+

+        except Exception as e:

+            return PickupRequestResult(ok=False, error=str(e), document_ids=[])

+

+from django.core.exceptions import ValidationError

+    MaterialImage,

+class MultiFileInput(forms.ClearableFileInput):

+    allow_multiple_selected = True

+

+

+class MultiImageField(forms.Field):

+    widget = MultiFileInput

+

+    def __init__(self, *args, **kwargs):

+        kwargs.setdefault("required", False)

+        super().__init__(*args, **kwargs)

+

+    def to_python(self, data):

+        return data

+

+    def validate(self, value):

+        # Basic required check; skip per-file validation here

+        if self.required and not value:

+            raise ValidationError("This field is required.")

+

+

+    images = MultiImageField(help_text="Upload one or more sample images (optional)")

+

+        fields = ["organization", "category", "name", "code", "default_unit", "images"]

+

+    def save(self, commit=True):

+        instance = super().save(commit=commit)

+        files = self.files.getlist("images") if hasattr(self, "files") else []

+        if commit and files:

+            # Instance has a PK; we can create images now

+            order_start = instance.images.count()

+            for i, f in enumerate(files):

+                MaterialImage.objects.create(material=instance, image=f, display_order=order_start + i)

+        else:

+            # Defer image saving until caller completes save

+            self._pending_images = files

+        return instance

+

+    def save_images(self, instance: Material | None = None):

+        """Persist any pending images after the Material has been saved."""

+        if not hasattr(self, "_pending_images"):

+            return

+        target = instance or getattr(self, "instance", None)

+        if not target or not getattr(target, "pk", None):

+            return

+        order_start = target.images.count()

+        for i, f in enumerate(self._pending_images or []):

+            MaterialImage.objects.create(material=target, image=f, display_order=order_start + i)

+        # Clear pending list

+        self._pending_images = []

+        parser.add_argument("--reset", action="store_true", help="Delete existing data for the target orgs before seeding")

+        # Optionally reset existing demo data (scoped to the selected orgs)

+        if options.get("reset"):

+            from recycle_core.models import (

+                ScrapAward,

+                ScrapBid,

+                ScrapListingInvite,

+                ScrapListingItem,

+                ScrapListing,

+                WeighLine,

+                WeighTicket,

+                PickupItem,

+                PickupOrder,

+                InvoiceLine,

+                Invoice,

+                Payment,

+                Payout,

+                ServiceAgreement,

+                CustomerSite,

+                Customer,

+                PriceListItem,

+                PriceList,

+                Material,

+                MaterialCategory,

+                ProvidedService,

+            )

+

+            def _wipe_for(o: Organization):

+                # Marketplace

+                ScrapAward.objects.filter(listing__organization=o).delete()

+                ScrapBid.objects.filter(listing__organization=o).delete()

+                ScrapListingInvite.objects.filter(listing__organization=o).delete()

+                ScrapListingItem.objects.filter(listing__organization=o).delete()

+                ScrapListing.objects.filter(organization=o).delete()

+

+                # Operations

+                WeighLine.objects.filter(ticket__pickup__organization=o).delete()

+                WeighTicket.objects.filter(pickup__organization=o).delete()

+                PickupItem.objects.filter(pickup__organization=o).delete()

+                PickupOrder.objects.filter(organization=o).delete()

+

+                # Billing

+                InvoiceLine.objects.filter(invoice__organization=o).delete()

+                Payment.objects.filter(invoice__organization=o).delete()

+                Invoice.objects.filter(organization=o).delete()

+                Payout.objects.filter(organization=o).delete()

+

+                # Customers and agreements

+                ServiceAgreement.objects.filter(customer__organization=o).delete()

+                CustomerSite.objects.filter(customer__organization=o).delete()

+                Customer.objects.filter(organization=o).delete()

+

+                # Pricing

+                PriceListItem.objects.filter(price_list__organization=o).delete()

+                PriceList.objects.filter(organization=o).delete()

+

+                # Inventory and services

+                Material.objects.filter(organization=o).delete()

+                ProvidedService.objects.filter(organization=o).delete()

+                MaterialCategory.objects.filter(organization=o).delete()

+

+            _wipe_for(org)

+            _wipe_for(bidder_org)

+            self.stdout.write(self.style.WARNING("Existing data removed for selected orgs (reset)."))

+

+        pet, _ = Material.objects.get_or_create(organization=org, category="Plastics", name="PET", defaults={"default_unit": Material.UNIT_KG})

+        hdpe, _ = Material.objects.get_or_create(organization=org, category="Plastics", name="HDPE", defaults={"default_unit": Material.UNIT_KG})

+        can, _ = Material.objects.get_or_create(organization=org, category="Metals", name="Aluminum Can", defaults={"default_unit": Material.UNIT_KG})

+        cardboard, _ = Material.objects.get_or_create(organization=org, category="Paper", name="Cardboard", defaults={"default_unit": Material.UNIT_KG})

+# Generated by Django 4.2.24 on 2025-09-22 09:17

+

+from django.db import migrations, models

+

+

+class Migration(migrations.Migration):

+

+    dependencies = [

+        ('recycle_core', '0005_providedservice_is_enabled'),

+    ]

+

+    operations = [

+        migrations.AlterField(

+            model_name='materialcategory',

+            name='name',

+            field=models.CharField(choices=[('Plastics', 'Plastics'), ('Metals', 'Metals'), ('Paper', 'Paper'), ('Glass', 'Glass'), ('Electronics', 'Electronics'), ('Wood', 'Wood'), ('Rubber', 'Rubber'), ('Textiles', 'Textiles'), ('Organic', 'Organic'), ('Mixed', 'Mixed')], max_length=255),

+        ),

+    ]

+# Generated by Django 4.2.24 on 2025-09-22 09:23

+

+from django.db import migrations, models

+

+

+class Migration(migrations.Migration):

+

+    dependencies = [

+        ('recycle_core', '0006_alter_materialcategory_name'),

+    ]

+

+    operations = [

+        migrations.AlterField(

+            model_name='material',

+            name='category',

+            field=models.CharField(choices=[('Plastics', 'Plastics'), ('Metals', 'Metals'), ('Paper', 'Paper'), ('Glass', 'Glass'), ('Electronics', 'Electronics'), ('Wood', 'Wood'), ('Rubber', 'Rubber'), ('Textiles', 'Textiles'), ('Organic', 'Organic'), ('Mixed', 'Mixed')], max_length=64),

+        ),

+    ]

+# Generated by Django 4.2.24 on 2025-09-22 09:28

+

+from django.db import migrations, models

+import django.db.models.deletion

+

+

+class Migration(migrations.Migration):

+

+    dependencies = [

+        ('recycle_core', '0007_alter_material_category'),

+    ]

+

+    operations = [

+        migrations.CreateModel(

+            name='MaterialImage',

+            fields=[

+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),

+                ('created_at', models.DateTimeField(auto_now_add=True)),

+                ('updated_at', models.DateTimeField(auto_now=True)),

+                ('image', models.ImageField(upload_to='materials/%Y/%m/')),

+                ('caption', models.CharField(blank=True, max_length=255)),

+                ('display_order', models.PositiveIntegerField(default=0)),

+                ('material', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='images', to='recycle_core.material')),

+            ],

+            options={

+                'ordering': ['display_order', 'id'],

+            },

+        ),

+    ]

+    # Limit to a curated, preset set of category names

+    CATEGORY_CHOICES = (

+        ("Plastics", "Plastics"),

+        ("Metals", "Metals"),

+        ("Paper", "Paper"),

+        ("Glass", "Glass"),

+        ("Electronics", "Electronics"),

+        ("Wood", "Wood"),

+        ("Rubber", "Rubber"),

+        ("Textiles", "Textiles"),

+        ("Organic", "Organic"),

+        ("Mixed", "Mixed"),

+    )

+    name = models.CharField(max_length=255, choices=CATEGORY_CHOICES)

+    # Preset category choices (no FK)

+    CATEGORY_CHOICES = MaterialCategory.CATEGORY_CHOICES

+    category = models.CharField(max_length=64, choices=CATEGORY_CHOICES)

+class MaterialImage(TimestampedModel):

+    material = models.ForeignKey(Material, on_delete=models.CASCADE, related_name="images")

+    image = models.ImageField(upload_to="materials/%Y/%m/")

+    caption = models.CharField(max_length=255, blank=True)

+    display_order = models.PositiveIntegerField(default=0)

+

+    class Meta:

+        ordering = ["display_order", "id"]

+

+    def __str__(self) -> str:

+        return self.caption or f"MaterialImage #{self.id}"

+

+

+

+  {% if item %}

+  {% with imgs=item.images.all %}

+  {% if imgs %}

+  <div class="mb-4">

+    <h2 class="text-lg font-medium mb-2">Existing Images</h2>

+    <div class="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 gap-3">

+      {% for im in imgs %}

+        <div class="border rounded p-2 bg-white flex flex-col items-center gap-2">

+          <img src="{{ im.image.url }}" alt="{{ im.caption|default:'Material image' }}" class="w-28 h-28 object-cover rounded" />

+          {% if im.caption %}

+            <div class="text-xs text-gray-600 text-center">{{ im.caption }}</div>

+          {% endif %}

+        </div>

+      {% endfor %}

+    </div>

+  </div>

+  {% endif %}

+  {% endwith %}

+  {% endif %}

+

+  <form method="post" enctype="multipart/form-data">

+            <td class="px-4 py-2">{{ m.get_category_display }}</td>

+from django.core.files.uploadedfile import SimpleUploadedFile

+from orgs.models import Organization

+from public_frontend.models import Lead

+from .models import Document

+from .controllers.pickup_request import PickupRequestController, PickupRequestData

+

+

+class PickupRequestControllerTests(TestCase):

+    def setUp(self) -> None:

+        self.org = Organization.objects.create(name="Test Org", code="TEST")

+        self.ctrl = PickupRequestController()

+

+    def test_submit_without_files_creates_lead_only(self):

+        data = PickupRequestData(

+            organization=self.org,

+            name="Alice",

+            email="alice@example.com",

+            phone="+1 555 0000",

+            address="123 Road",

+            materials="PET bottles",

+            preferred_at=None,

+            files=[],

+        )

+

+        result = self.ctrl.submit(data)

+        self.assertTrue(result.ok)

+        self.assertIsNotNone(result.lead_id)

+        self.assertEqual(result.document_ids, [])

+

+        lead = Lead.objects.get(pk=result.lead_id)

+        self.assertEqual(lead.organization, self.org)

+        self.assertEqual(lead.name, "Alice")

+        self.assertEqual(lead.subject, "Pickup Request")

+        self.assertEqual(lead.source, "pickup_request")

+

+        self.assertEqual(Document.objects.filter(object_id=lead.id).count(), 0)

+

+    def test_submit_with_files_creates_documents(self):

+        file1 = SimpleUploadedFile("photo1.jpg", b"fakejpegdata1", content_type="image/jpeg")

+        file2 = SimpleUploadedFile("photo2.jpg", b"fakejpegdata2", content_type="image/jpeg")

+

+        data = PickupRequestData(

+            organization=self.org,

+            name="Bob",

+            email="bob@example.com",

+            phone="+1 555 1111",

+            address="456 Avenue",

+            materials="Aluminum cans",

+            preferred_at=None,

+            files=[file1, file2],

+        )

+

+        result = self.ctrl.submit(data)

+        self.assertTrue(result.ok)

+        self.assertIsNotNone(result.lead_id)

+        self.assertEqual(len(result.document_ids), 2)

+

+        lead = Lead.objects.get(pk=result.lead_id)

+        docs = Document.objects.filter(object_id=lead.id).order_by("id")

+        self.assertEqual(docs.count(), 2)

+        for d in docs:

+            self.assertEqual(d.organization, self.org)

+            self.assertEqual(d.kind, "pickup_request")

+            self.assertEqual(d.content_object, lead)

+    mat_form = MaterialForm(request.POST or None, request.FILES or None)

+                # Save any uploaded images deferred by the form

+                try:

+                    mat_form.save_images(instance=obj)

+                except Exception:

+                    pass

+        category = filters.ChoiceFilter(choices=Material.CATEGORY_CHOICES)

+    base_mats = Material.objects.select_related("organization").order_by("organization_id", "name")

+        form = MaterialForm(request.POST, request.FILES, instance=item)

+django-extensions

+# Choose one of these for graph_models rendering

+# pygraphviz is preferred; alternatively install pydotplus and graphviz

+pygraphviz

+@startuml

+title Request Pickup (Fast Path)

+actor "Factory Officer" as FO

+participant "Public Site (FE)" as Web

+participant "Backend (Django)" as API

+actor "Staff (Web Admin)" as Staff

+actor Driver

+participant "Weigh Station" as Scale

+participant Billing

+

+FO -> Web: Open "Sell Scrap" (Request Pickup)

+Web --> FO: Show form (materials, qty, photos, address, time)

+FO -> Web: Submit form (+photos)

+Web -> API: POST /pickup-request

+API -> API: Create Lead (org, details)

+API --> Staff: Notify (inbox/email)

+Staff -> API: Create/attach Customer + Site

+Staff -> API: Create PickupOrder (status=requested)

+Staff -> API: Schedule + Assign Driver

+API --> FO: Confirmation (schedule)

+Driver -> FO: Arrive and collect

+Driver -> Scale: Weigh materials

+Scale -> API: Record WeighTicket + lines

+API -> Billing: Generate Invoice or Payout

+Billing --> FO: Invoice/Payout issued

+FO -> Billing: Pay / Receive funds

+API -> API: Mark Pickup completed

+@enduml

+

+@startuml

+title Get Bids (Marketplace Path)

+actor "Factory Officer" as FO

+participant "Public Site (FE)" as Web

+participant "Backend (Django)" as API

+actor "Staff (Web Admin)" as Staff

+actor "Recycler(s)" as Rec

+actor Driver

+participant "Weigh Station" as Scale

+participant Billing

+

+FO -> Web: "Sell Scrap" → Get Bids

+Web --> FO: Listing form (title, materials, qty, photos, reserve, ends)

+FO -> Web: Submit request

+Web -> API: POST listing-request

+API -> API: Create Draft ScrapListing (or Lead: listing_request)

+Staff -> API: Review + Publish (public or invite-only)

+API --> Rec: Listing visible / invites sent

+Rec -> API: Place Bid(s)

+Staff -> API: Close listing at end time

+Staff -> API: Award winning bid

+API -> API: Create PickupOrder from award

+Driver -> FO: Collect materials

+Driver -> Scale: Weigh materials

+Scale -> API: Record WeighTicket + lines

+API -> Billing: Generate Invoice or Payout

+Billing --> FO: Invoice/Payout issued

+API -> API: Mark Pickup completed

+@enduml

+