bellsystems-cp/CRM_STATUS_SYSTEM_PLAN.md

CRM Customer Status System — Implementation Plan

Context

This project is a Vue/React + FastAPI + Firestore admin console located at C:\development\bellsystems-cp.

The frontend lives in frontend/src/ and the backend in backend/. The CRM module is at frontend/src/crm/ and backend/crm/.

Currently, customers have two flat boolean flags on their Firestore document:

• negotiating: bool
• has_problem: bool

These need to be replaced with a richer, structured system as described below.

---

1. Target Data Model

1A. On the Customer Document (customers/{id})

Remove negotiating and has_problem. Add the following:

relationship_status: string
  — one of: "lead" | "prospect" | "active" | "inactive" | "churned"
  — default: "lead"

technical_issues: array of {
  active: bool,
  opened_date: Firestore Timestamp,
  resolved_date: Firestore Timestamp | null,
  note: string,
  opened_by: string,       ← display name or user ID of staff member
  resolved_by: string | null
}

install_support: array of {
  active: bool,
  opened_date: Firestore Timestamp,
  resolved_date: Firestore Timestamp | null,
  note: string,
  opened_by: string,
  resolved_by: string | null
}

transaction_history: array of {
  date: Firestore Timestamp,
  flow: string,            ← "invoice" | "payment" | "refund" | "credit"
  payment_type: string | null,  ← "cash" | "bank_transfer" | "card" | "paypal" — null for invoices
  category: string,        ← "full_payment" | "advance" | "installment"
  amount: number,
  currency: string,        ← default "EUR"
  invoice_ref: string | null,
  order_ref: string | null,    ← references an order document ID, nullable
  recorded_by: string,
  note: string
}

1B. Orders Subcollection (customers/{id}/orders/{order_id})

Orders live exclusively as a subcollection under each customer. There is no top-level orders collection. The existing top-level orders collection in Firestore and its corresponding backend routes should be removed entirely and replaced with subcollection-based routes under /crm/customers/{customer_id}/orders/.

If cross-customer order querying is ever needed in the future, use Firestore's native collectionGroup("orders") query — no top-level mirror collection is required.

Each order document carries the following fields:

order_number: string          ← e.g. "ORD-2026-041"  (already exists — keep)
title: string                 ← NEW: human-readable name e.g. "3x Wall Mount Units - Athens Office"
created_by: string            ← NEW: staff user ID or display name

status: string                ← REPLACE existing OrderStatus enum with new values:
  — "negotiating" | "awaiting_quotation" | "awaiting_customer_confirmation"
  | "awaiting_fulfilment" | "awaiting_payment" | "manufacturing"
  | "shipped" | "installed" | "declined" | "complete"

status_updated_date: Firestore Timestamp   ← NEW
status_updated_by: string                  ← NEW

payment_status: object {                   ← NEW — replaces the flat PaymentStatus enum
  required_amount: number,
  received_amount: number,       ← computed from transaction_history where order_ref matches
  balance_due: number,           ← computed: required_amount - received_amount
  advance_required: bool,
  advance_amount: number | null,
  payment_complete: bool
}

timeline: array of {            ← NEW — order event log
  date: Firestore Timestamp,
  type: string,  ← "quote_request" | "quote_sent" | "quote_accepted" | "quote_declined"
                    | "mfg_started" | "mfg_complete" | "order_shipped" | "installed"
                    | "payment_received" | "invoice_sent" | "note"
  note: string,
  updated_by: string
}

---

2. Backend Changes

2A. backend/crm/models.py

• Remove negotiating: bool and has_problem: bool from CustomerCreate and CustomerUpdate.
• Add relationship_status: Optional[str] = "lead" to CustomerCreate and CustomerUpdate.
• Add technical_issues: List[dict] = [] to CustomerCreate and CustomerUpdate.
• Add install_support: List[dict] = [] to CustomerCreate and CustomerUpdate.
• Add transaction_history: List[dict] = [] to CustomerCreate and CustomerUpdate.
• Add proper Pydantic models for each of the above array item shapes:
  • TechnicalIssue model
  • InstallSupportEntry model
  • TransactionEntry model
• Update OrderStatus enum with the new values: negotiating, awaiting_quotation, awaiting_customer_confirmation, awaiting_fulfilment, awaiting_payment, manufacturing, shipped, installed, declined, complete
• Replace the flat PaymentStatus enum on OrderCreate / OrderUpdate with a new OrderPaymentStatus Pydantic model matching the structure above.
• Add title: Optional[str], created_by: Optional[str], status_updated_date: Optional[str], status_updated_by: Optional[str], and timeline: List[dict] = [] to OrderCreate and OrderUpdate.

2B. backend/crm/customers_router.py

• Update any route that reads/writes negotiating or has_problem to use the new fields.
• Add new dedicated endpoints:

POST   /crm/customers/{id}/technical-issues
  — body: { note: str, opened_by: str }
  — appends a new active issue to the array

PATCH  /crm/customers/{id}/technical-issues/{index}/resolve
  — body: { resolved_by: str }
  — sets active=false and resolved_date=now on the item at that index

POST   /crm/customers/{id}/install-support
  — same pattern as technical-issues above

PATCH  /crm/customers/{id}/install-support/{index}/resolve
  — same as technical-issues resolve

POST   /crm/customers/{id}/transactions
  — body: TransactionEntry (see model above)
  — appends to transaction_history

PATCH  /crm/customers/{id}/relationship-status
  — body: { status: str }
  — updates relationship_status field

2C. backend/crm/orders_router.py

• Remove all top-level /crm/orders/ routes entirely.
• Re-implement all order CRUD under /crm/customers/{customer_id}/orders/:

GET    /crm/customers/{customer_id}/orders/
POST   /crm/customers/{customer_id}/orders/
GET    /crm/customers/{customer_id}/orders/{order_id}
PATCH  /crm/customers/{customer_id}/orders/{order_id}
DELETE /crm/customers/{customer_id}/orders/{order_id}

• Add endpoint to append a timeline event:

POST   /crm/customers/{customer_id}/orders/{order_id}/timeline
  — body: { type: str, note: str, updated_by: str }
  — appends to the timeline array and updates status_updated_date + status_updated_by

• Add endpoint to update payment status:

PATCH  /crm/customers/{customer_id}/orders/{order_id}/payment-status
  — body: OrderPaymentStatus fields (partial update allowed)

• Add a dedicated "Init Negotiations" endpoint:

POST   /crm/customers/{customer_id}/orders/init-negotiations
  — body: { title: str, note: str, date: datetime, created_by: str }
  — creates a new order with status="negotiating", auto-fills all other fields
  — simultaneously updates the customer's relationship_status to "active"
    (only if currently "lead" or "prospect" — do not downgrade an already "active" customer)
  — returns the newly created order document

---

3. Frontend Changes

3A. frontend/src/crm/customers/CustomerList.jsx

• When Notes: Quick filter is set, replace the negotiating and has_problem boolean badge display in the Status column with:
  • A relationship status chip (color-coded pill: lead=grey, prospect=blue, active=green, inactive=amber, churned=soft red)
  • A small red dot / warning icon if technical_issues.some(i => i.active) is true, under a new "Support" column. Add this column to the list of arrangeable and toggleable columns.
  • A small amber dot / support icon if install_support.some(i => i.active) is true, under the same "Support" column.
  • These are derived from the arrays — do not store a separate boolean on the document.
• When Notes: Expanded filter is set, replace the negotiating and has_problem verbose displays with the active order status (if any) in this format: "<Status Label> — <Date> — <Note>" e.g. "Negotiating — 24.03.26 — Customer requested a more affordable quotation"

3B. frontend/src/crm/customers/CustomerDetail.jsx

The customer detail page currently has a tab structure: Overview, Orders, Quotations, Communication, Files & Media, Devices.

Make the following changes:

Whole page

• On the top of the page where we display the name, organization and full address, change it to: Line 1: Full Title + Name + Surname Line 2: Organization · City (city only, not full address)

• Remove the horizontal separation line after the title and before the tabs.

• On the top right side, there is an Edit Customer button. To its left, add 3 new buttons in this order (left → right): Init Negotiations, Record Issue/Support, Record Payment, then the existing Edit button. All 4 buttons are the same size. Add solid single-color icons to each.

  "Init Negotiations" button (blue/indigo accent):

  • Opens a mini modal.
  • Fields: Date (defaults to NOW), Title (text input, required), Note (textarea, optional).
  • Auto-filled server-side: status = "negotiating", created_by = current user, status_updated_date = now, status_updated_by = current user, payment_status defaults to zeroed object.
  • On confirm: calls POST /crm/customers/{id}/orders/init-negotiations.
  • After success: refreshes customer data and orders list. The customer's relationship_status is set to "active" server-side — no separate frontend call needed.
  • This is a fast-entry shortcut only. All subsequent edits to this order happen via the Orders tab.

  "Record Issue/Support" button (amber/orange accent):

  • Opens a mini modal.
  • At the top: a 2-button toggle selector (not a dropdown) to choose: Technical Issue | Install Support.
  • Fields: Date (defaults to NOW), Note (textarea, required).
  • On confirm: calls POST /crm/customers/{id}/technical-issues or POST /crm/customers/{id}/install-support depending on selection.

  "Record Payment" button (green accent):

  • Opens a mini modal.
  • Fields: Date (defaults to NOW), Payment Type (cash | bank transfer | card | paypal), Category (full payment | advance | installment), Amount (number), Currency (defaults to EUR), Invoice Ref (searchable over the customer's invoices, optional), Order Ref (searchable/selectable from the customer's orders, optional), Note (textarea, optional).
  • On confirm: calls POST /crm/customers/{id}/transactions.

Overview Tab

• The main hero section gets a complete overhaul — start fresh:
  • Row 1 — Relationship Status selector: The 5 statuses (lead | prospect | active | inactive | churned) as styled pill/tab buttons in a row. Current status is highlighted with a glow effect. Color-code using global CSS variables (add to index.css if not already present). Clicking a status immediately calls PATCH /crm/customers/{id}/relationship-status.
  • Row 2 — Customer info: All fields except Name and Organization (shown in page header). Include language, religion, tags, etc.
  • Row 3 — Contacts: All contact entries (phone, email, WhatsApp, etc.).
  • Row 4 — Notes: Responsive column grid. 1 column below 1100px, 2 columns 1100–2000px, 3 columns above 2000px. Masonry/wrap layout with no gaps between note cards.
• Move the Latest Orders section to just below the hero section, before Latest Communications. Hide this section entirely if no orders exist for this customer.
• For all other sections (Latest Communications, Latest Quotations, Devices): hide each section entirely if it has no data. Show dynamically when data exists.

New "Support" Tab (add to TABS array, after Overview)

Two full-width section cards:

Technical Issues Card

• Header shows active count badge (e.g. "2 active")
• All issues listed, newest first (active and resolved)
• Each row: colored status dot, opened date, note, opened_by — "Resolve" button if active
• If more than 5 items: list is scrollable (fixed max-height), does not expand the page
• "Report New Issue" button → small inline form with note field + submit

Install Support Card

• Identical structure to Technical Issues card
• Same scrollable behavior if more than 5 items

New "Financials" Tab (add to TABS array, after Support)

Two sections:

Active Order Payment Status (shown only if an active order exists)

• required_amount, received_amount, balance_due
• Advance required indicator + advance amount if applicable
• Payment complete indicator

Transaction History

• Ledger table: Date | Flow | Amount | Currency | Method | Category | Order Ref | Invoice Ref | Note | Recorded By | Actions
• "Add Transaction" button → modal with all TransactionEntry fields
• Totals row: Total Invoiced vs Total Paid vs Outstanding Balance
• Each row: right-aligned Actions button (consistent with other tables in the project) with options: Edit (opens edit form) and Delete (requires confirmation dialog)

Orders Tab (existing — update in place)

• Each order card/row shows:
  • title as primary heading
  • status with human-readable label and color coding (see Section 4)
  • payment_status summary: required / received / balance due
  • "View Timeline" toggle: expands a vertical event log below the order card
  • "Add Timeline Event" button: small inline form with type dropdown + note field
• Update all API calls to use /crm/customers/{customer_id}/orders/ routes.

3C. frontend/src/crm/customers/CustomerForm.jsx

• Remove negotiating and has_problem fields.
• Add relationship_status dropdown (default: "lead").
• No issue/transaction forms needed here — managed from the detail page.

3D. frontend/src/crm/orders/OrderForm.jsx and OrderDetail.jsx

• Update status dropdown with new values and labels:
  • negotiating → "Negotiating"
  • awaiting_quotation → "Awaiting Quotation"
  • awaiting_customer_confirmation → "Awaiting Customer Confirmation"
  • awaiting_fulfilment → "Awaiting Fulfilment"
  • awaiting_payment → "Awaiting Payment"
  • manufacturing → "Manufacturing"
  • shipped → "Shipped"
  • installed → "Installed"
  • declined → "Declined"
  • complete → "Complete"
• Add title input field (required).
• Replace flat payment_status enum with the new payment_status object fields.
• Add Timeline section to OrderDetail.jsx: vertical event log + add-entry inline form.
• Update all API calls to use /crm/customers/{customer_id}/orders/ routes.

---

4. Status Color Coding Reference

Define all as CSS variables in index.css and use consistently across all views:

Relationship Status

Status	Color
lead	grey / muted
prospect	blue
active	green
inactive	amber
churned	dark or soft red

Order Status

Status	Color
negotiating	blue
awaiting_quotation	purple
awaiting_customer_confirmation	indigo
awaiting_fulfilment	amber
awaiting_payment	orange
manufacturing	cyan
shipped	teal
installed	green
declined	red
complete	muted/grey

Issue / Support Flags

State	Color
active issue	red
active support	amber
resolved	muted/grey

---

5. Migration Notes

• The old negotiating and has_problem fields will remain in Firestore until the migration script is run. The backend should read both old and new fields during the transition period, preferring the new structure if present.
• A one-time migration script (backend/migrate_customer_flags.py) should:
  1. Read all customer documents
  2. If negotiating: true → create an order in the customer's orders subcollection with status = "negotiating" and set relationship_status = "active" on the customer
  3. If has_problem: true → append one entry to technical_issues with active: true, opened_date: customer.updated_at, note: "Migrated from legacy has_problem flag", opened_by: "system"
  4. Remove negotiating and has_problem from the customer document
• Do not run the migration script until all frontend and backend changes are deployed and tested.

---

6. File Summary — What to Touch

backend/crm/models.py                  ← model updates (primary changes)
backend/crm/customers_router.py        ← new endpoints + field updates
backend/crm/orders_router.py           ← remove top-level routes, re-implement as subcollection,
                                          add timeline + payment-status + init-negotiations endpoints
backend/migrate_customer_flags.py      ← NEW one-time migration script

frontend/src/index.css                         ← add CSS variables for all new status colors
frontend/src/crm/customers/CustomerList.jsx    ← relationship status chip + support flag dots column
frontend/src/crm/customers/CustomerDetail.jsx  ← page header, 3 new quick-entry buttons + modals,
                                                  Overview tab overhaul, new Support tab,
                                                  new Financials tab, Orders tab updates
frontend/src/crm/customers/CustomerForm.jsx    ← remove old flags, add relationship_status
frontend/src/crm/orders/OrderForm.jsx          ← new status values, title field, payment_status,
                                                  updated API route paths
frontend/src/crm/orders/OrderDetail.jsx        ← timeline section, updated status/payment,
                                                  updated API route paths

---

7. Do NOT Change (out of scope)

• Quotations system — leave as-is
• Communications / inbox — leave as-is
• Files & Media tab — leave as-is
• Devices tab — leave as-is
• Any other module outside crm/