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/`