ecoloop/README.md

Ecoloop Backend

Ecoloop is a Django + DRF backend for recycling businesses and factories to manage pickups, pricing, invoices/payouts, and a bidding marketplace for scrap lots. It supports multi-organization setups, JWT auth, and a Tailwind-powered UI layer.

Quick Start

• Requirements: Python 3.11, Postgres, Node (for Tailwind in dev)
• Environment: copy .env and set SECRET_KEY, DEBUG, DB_*, ALLOWED_HOSTS
• Run (Docker): docker-compose up --build (web on http://localhost:8024)
• Run (local):
  • python manage.py migrate
  • python manage.py runserver
  • Optional demo: python manage.py seed_ecoloop
• API docs: Swagger UI at /api/schema/swagger-ui/

Project Scopes (Summary)

• Core operations: customers, sites, service agreements, materials, units; pickup lifecycle (request → schedule/assign → collect → weigh ticket → complete).
• Pricing & finance: org/customer price lists (buy/sell), invoice generation from weigh tickets, payments, and payouts for buy-priced materials.
• Bidding marketplace: factories post scrap listings (open/invite-only), recyclers bid with min-increment/reserve; award creates a pickup order.
• Users & portal: roles (owner, manager, driver, customer, auditor); JWT auth; customer/driver-facing endpoints for assignments and status.
• Compliance & docs: upload/attach documents (proofs, photos, certificates); audit logs for key state changes.
• Reporting: benefit leaderboards and volume/revenue summaries (period filters).
• Multi-org & locale: organization scoping, currency codes (THB/USD), units (kg/lb); env-driven config.

Key Commands

• python manage.py migrate — apply DB migrations
• python manage.py seed_ecoloop — seed demo org, users, materials, pickup, weigh ticket, invoice, listing/bid
• python manage.py ecoloop_auto_close_award — auto-close/award expired listings

Multisite (Local Testing)

• Purpose: Serve multiple sites on one codebase using Django Sites.
• Config:
  • Enabled in ecoloop/settings.py via django.contrib.sites and SITE_ID.
  • .env includes defaults for local hosts: ALLOWED_HOSTS=localhost,127.0.0.1,.lvh.me
  • .env CSRF for Docker port: CSRF_TRUSTED_ORIGINS=http://localhost:8024,http://*.lvh.me:8024
• Run:
  • python manage.py migrate (applies Sites tables)
  • In Admin → Sites, add domains like alpha.lvh.me and beta.lvh.me.
  • Visit http://alpha.lvh.me:8024 and http://beta.lvh.me:8024.
  • Attach site-specific content in apps (e.g., CMS) by filtering on get_current_site(request) or adding a ForeignKey to Site.

Structure

• ecoloop/ settings and URLs; api/ public endpoints; recycle_core/ domain models/APIs
• Assets: templates/, static/, media/; Entrypoints: manage.py, docker-compose.yml, Dockerfile

System Features & Use Cases

Core Features

• Materials: Master data with categories, units, and images; org‑scoped.
• Customers & Sites: Accounts with multiple pickup locations and contacts.
• Pickups: Lifecycle from request → schedule/assign → collect → weigh → invoice.
• Weigh Tickets: Gross/tare/net with per‑material lines; optional finalize; audit trail.
• Pricing: Org/customer price lists with buy/sell directions per material/unit.
• Billing: Invoices from weigh tickets, payments tracking, and customer payouts from buy prices.
• Marketplace: Scrap listings (open/invite‑only), bids, reserve/min‑increment, awarding creates a pickup.
• Documents: File uploads attached to any record (leads, tickets, invoices, etc.).
• Audit Logs: Structured entries for key actions (assignment, status change, award, invoice generation).
• Leaderboard: User‑to‑user benefit scoring and rankings.

Operational Flows

• Request Intake: Public “Pickup Request” creates a Lead and optional attached Documents.
• Scheduling: Manager assigns a driver and sets pickup status/schedule.
• Collection: Driver updates statuses (en_route, collecting, at_facility).
• Weighing: Create WeighTicket and WeighLines per material; optional finalize.
• Invoicing: Generate invoice from tickets; sell lines to customer, buy‑price payouts to customer.
• Completion: Mark pickup completed; reconcile statuses and financials.

Marketplace

• Listings: Title/description, auction type (open/sealed), reserve, min increment, time window.
• Visibility: Public or invite‑only via ScrapListingInvite.
• Bidding: Validates status/time window, invite list, min increment, bidder org/role.
• Awarding: Manual via API/action or auto (ecoloop_auto_close_award); accepts top qualifying bid, rejects others, creates a PickupOrder.

Pricing & Finance

• Price Lists: Org‑level with currency; customer can reference a list.
• Sell vs Buy: Sell determines invoice lines; Buy determines Payout to customer.
• Invoice Lifecycle: Draft/Issued/Paid/Void; due date; payments tracked.
• Regeneration: Rebuild draft invoice lines if ticket lines/prices change (before issuing).

Compliance & Carbon

• Documents: Attach proofs, photos, and certificates to any object via generic relation.
• Audit Trail: AuditLog records important actions and metadata.
• Emission Factors: Per material/unit kgCO2e, configurable per org with effective dates.

Users & Access

• Roles: Owner/Manager/Driver/Customer/Auditor via UserProfile per organization.
• Auth: JWT via Djoser (/auth/), optional social auth (Google/LINE/Facebook).
• Multisite: Django Sites; map domains to orgs via OrganizationSite.

API & Admin

• REST API: DRF viewsets for core/billing/marketplace under /api/, filterable, with custom actions:
  • pickups/{id}/assign, pickups/{id}/set_status
  • weigh-tickets/{id}/generate_invoice
  • scrap-listings/{id}/open, scrap-listings/{id}/close, scrap-awards/award-listing/
• Matching & Leaderboard:
  • profiles/match/, opportunities/recommend/
  • leaderboard/ (public), leaderboard/me/ (auth)
• Admin UI: /webadmin/… routes for orgs, billing, recycle core, CMS, settings.
• API Docs: Swagger at /api/schema/swagger-ui/.

Typical Use Cases

• Factory Pickup

  • Staff submits Pickup Request (lead + photos).
  • Manager creates PickupOrder, assigns driver, schedules.
  • Driver collects and records WeighTicket with material lines.
  • Invoicing generates sell lines; system issues payout when buy prices exist.
  • Finance records Payment; pickup moves to invoiced/completed.

• Marketplace Sale

  • Factory posts ScrapListing with estimated quantities and a bidding window.
  • Invites recyclers or opens publicly; bidders place ScrapBids.
  • On close/expiry, award highest valid bid (reserve honored); PickupOrder auto‑created.
  • Proceed with weighing and invoicing as standard.

• Price Review & Adjustments

  • Update PriceListItem sell/buy rates by material/unit.
  • Regenerate draft invoices when ticket lines change before issuing.

• Compliance & Reporting

  • Upload certificates/photos as Documents linked to tickets/invoices.
  • Review AuditLog for status changes and financial actions.
  • Use leaderboard and summaries for engagement and impact reporting.

API Quick Links

• Docs: /api/schema/swagger-ui/ (interactive), /api/schema/redoc/
• Auth (Djoser + JWT):
  • POST /auth/jwt/create/ (get token)
  • POST /auth/users/ (register), GET /auth/users/me/
• Public API:
  • Profiles: GET/POST /api/profiles/, GET /api/profiles/match/
  • Opportunities: GET/POST /api/opportunities/, GET /api/opportunities/recommend/
  • Leaderboard: GET /api/leaderboard/, GET /api/leaderboard/me/
• Core domain:
  • Orgs: /api/organizations/
  • Materials: /api/material-categories/, /api/materials/
  • Pricing: /api/price-lists/, /api/price-list-items/
  • Customers: /api/customers/, /api/customer-sites/, /api/service-agreements/
  • Pickups: /api/pickups/ (actions: POST /api/pickups/{id}/assign/, POST /api/pickups/{id}/set_status/)
  • Weighing: /api/weigh-tickets/ (action: POST /api/weigh-tickets/{id}/generate_invoice/), /api/weigh-lines/
  • Documents & Audit: /api/documents/, /api/audit-logs/
• Billing:
  • Invoices: /api/invoices/, lines: /api/invoice-lines/
  • Payments: /api/payments/, Payouts: /api/payouts/
• Marketplace:
  • Listings: /api/scrap-listings/ (actions: POST /api/scrap-listings/{id}/open/, POST /api/scrap-listings/{id}/close/)
  • Items: /api/scrap-listing-items/
  • Bids: /api/scrap-bids/ (action: POST /api/scrap-bids/{id}/retract/)
  • Award: POST /api/scrap-awards/award-listing/
  • Invites: /api/scrap-listing-invites/

Verification Checklists

Auth & Setup

• Configure .env and run DB: docker-compose up --build or python manage.py migrate && runserver.
• Optional: seed demo data: python manage.py seed_ecoloop (creates users manager/manager123, driver/driver123, buyer/buyer123).
• Obtain JWT: POST /auth/jwt/create/ with seeded credentials, use Authorization: Bearer <token> for protected endpoints.

Pickup Lifecycle

• Create customer/site/material (if not seeded): POST /api/customers/, /api/customer-sites/, /api/materials/.
• Create pickup: POST /api/pickups/ with organization, customer, site.
• Assign driver: POST /api/pickups/{id}/assign/ {"driver_id": <user_id>}; confirm status scheduled.
• Update statuses: POST /api/pickups/{id}/set_status/ → en_route → collecting → at_facility.
• Add weigh ticket: POST /api/weigh-tickets/ + lines via /api/weigh-lines/.
• Generate invoice: POST /api/weigh-tickets/{id}/generate_invoice/; verify invoice under /api/invoices/ and any payout under /api/payouts/.
• Complete pickup: POST /api/pickups/{id}/set_status/ {"status": "completed"}.

Marketplace Flow

• Create listing: POST /api/scrap-listings/ (status defaults to draft).
• Open listing: POST /api/scrap-listings/{id}/open/; optionally add invites via /api/scrap-listing-invites/.
• Place bid: POST /api/scrap-bids/ with listing, bidder_org, price_total (ensure role and invite if private).
• Close or auto-close: POST /api/scrap-listings/{id}/close/ or run python manage.py ecoloop_auto_close_award.
• Award: POST /api/scrap-awards/award-listing/ {"listing_id": <id>}; verify pickup created and proceed with weighing/invoicing.

Billing & Pricing

• Ensure price list with sell/buy items exists: /api/price-lists/, /api/price-list-items/.
• After invoice generation, create payment: POST /api/payments/ {"invoice": <id>, "amount": ...}.
• Regenerate draft invoice when needed: use business flow that keeps status draft, then rebuild lines (see service regenerate_invoice_for_pickup).

Documents & Audit

• Submit public pickup request (UI) to create Lead and auto‑attach uploaded files as Documents.
• Or directly upload: POST /api/documents/ with file and content object.
• Review audit entries: GET /api/audit-logs/ after actions like assign, set_status, generate_invoice, award.