# Task D.5.4: Lead / Enquiry Workspace Separation UI Foundation

## Status

Planned

## Objective

Separate the user-facing CRM workspace between Lead and Enquiry.

This task makes Lead and Enquiry visible as different working areas while preserving existing enquiry, quotation, dashboard, and reporting behavior.

Business boundary:

```txt
Lead = Marketing-owned source record
Enquiry = Sales execution workspace
```

This task focuses on UI routing, navigation, data-source separation, and safe compatibility wiring.

---

## Mandatory Review

Review before implementation:

* `AGENTS.md`
* `docs/standards/project-foundations.md`
* `docs/standards/task-catalog.md`
* `docs/adr/0018-lead-enquiry-domain-separation.md`
* `docs/implementation/task-d5-lead-enquiry-domain-separation.md`
* `docs/implementation/task-d51-lead-foundation-stabilization.md`
* `docs/implementation/task-d52-lead-domain-service-api-foundation.md`
* `docs/implementation/task-d53-lead-assignment-create-enquiry-foundation.md`
* `docs/security/crm-authorization-boundaries.md`
* Existing CRM navigation/sidebar configuration
* Existing enquiry list/detail/form UI
* Existing lead API routes
* Existing enquiry API routes

---

## Existing Foundation

Already available:

```txt
crm_leads
crm_enquiries
crm_enquiries.lead_id

/api/crm/leads
/api/crm/leads/[id]
/api/crm/leads/[id]/followups
/api/crm/leads/[id]/assign

existing enquiry APIs
existing quotation APIs
```

Do not recreate:

```txt
tables
migrations
seed data
service foundation
assignment service
```

---

## Workspace Rules

### Lead Workspace

Audience:

```txt
Marketing
Marketing Manager
CRM Manager
Admin
```

Purpose:

```txt
capture lead
qualify lead
record awareness/status/lost reason
assign lead to sales
view linked enquiry result
```

Source:

```txt
crm_leads
/api/crm/leads
```

---

### Enquiry Workspace

Audience:

```txt
Sales
Sales Manager
CRM Manager
Admin
```

Purpose:

```txt
work assigned opportunity
prepare for quotation
track sales execution
continue existing enquiry lifecycle
```

Source:

```txt
crm_enquiries
existing /api/crm/enquiries
```

---

## Scope D5.4.1 Navigation Separation

Update CRM navigation so Lead and Enquiry are separate menu items.

Add:

```txt
CRM > Leads
CRM > Enquiries
```

Rules:

* Lead menu uses lead permission/scope
* Enquiry menu keeps existing permission/scope
* Do not rename Enquiry menu globally if it breaks existing routes
* Do not remove old enquiry route yet

Suggested routes:

```txt
/dashboard/crm/leads
/dashboard/crm/leads/[id]

/dashboard/crm/enquiries
/dashboard/crm/enquiries/[id]
```

If project uses another route prefix, follow existing app route convention.

---

## Scope D5.4.2 Lead List Page

Create Lead list page using `/api/crm/leads`.

Required columns:

```txt
Lead Code
Customer
Project Name
Status
Awareness
Estimated Value
Suggested Sales Owner
Assigned Sales Owner
Created Date
```

Required actions:

```txt
View
Edit
Assign
Delete
```

Rules:

* Assign action appears only when user has assignment permission
* Delete action appears only when user has delete permission
* No direct enquiry mutation from Lead list
* Use existing shadcn/table/list conventions
* Use design tokens only
* Follow existing CRM page layout pattern

---

## Scope D5.4.3 Lead Detail Page

Create Lead detail page using `/api/crm/leads/[id]`.

Sections:

```txt
Lead Summary
Customer Information
Qualification Information
Follow-up History
Assignment Information
Linked Enquiries
Audit-safe Activity View
```

Actions:

```txt
Edit Lead
Assign Lead
Create Follow-up
Delete Lead
Open Linked Enquiry
```

Rules:

* Assignment creates or reuses enquiry through `/api/crm/leads/[id]/assign`
* After assignment, show linked enquiry
* Marketing can see assignment result but must not edit enquiry unless permitted
* Follow-up history uses D.5.2 audit-backed implementation until future ADR decides final persistence

---

## Scope D5.4.4 Lead Create / Edit Form

Create or adapt Lead form components.

Required fields:

```txt
Customer
Contact
Project Name
Project Location
Description
Product Type
Priority
Estimated Value
Awareness
Status
Lost Reason
Notes
```

Rules:

* Use master options for awareness, status, lost reason
* No hardcoded labels
* Product type must use existing option/source convention
* Validate with D.5.2 lead schemas
* On create, call `POST /api/crm/leads`
* On edit, call `PATCH /api/crm/leads/[id]`

---

## Scope D5.4.5 Lead Assignment UI

Create assignment dialog or sheet.

Input:

```txt
Sales Owner
Assignment Remark
```

Behavior:

```txt
POST /api/crm/leads/[id]/assign
```

After success:

```txt
show enquiry code
show Open Enquiry action
refresh lead detail
refresh lead list
```

Rules:

* Sales owner list must use assignable sales members only
* If API returns existing enquiry, show reuse message instead of duplicate-created message
* Do not create enquiry client-side
* Do not mutate `crm_enquiries` directly from UI

---

## Scope D5.4.6 Enquiry UI Compatibility

Keep current enquiry UI operational.

Add optional linked-lead display if `lead_id` exists:

```txt
Source Lead
Lead Code
Open Lead
```

Rules:

* Do not rewrite enquiry workflow
* Do not change quotation conversion behavior
* Do not change dashboard/report queries
* Do not remove `pipeline_stage`
* Existing enquiry list/detail must still work

---

## Scope D5.4.7 Permission / Visibility Handling

UI must respect backend permissions but not replace backend enforcement.

Lead UI:

```txt
crm.lead.read
crm.lead.create
crm.lead.update
crm.lead.delete
crm.lead.assign
```

Enquiry UI:

```txt
existing enquiry permissions
```

Rules:

* Hide unauthorized actions
* Handle 403 gracefully
* Do not check role strings directly if access helpers exist
* Follow existing CRM access resolver/client conventions

---

## Scope D5.4.8 Empty / Loading / Error States

Implement consistent states:

```txt
loading
empty
not authorized
not found
server error
validation error
```

Messaging:

* Lead empty state should guide Marketing to create first Lead
* Enquiry empty state should remain sales-oriented
* Assignment success should clearly identify created/reused enquiry

---

## Scope D5.4.9 Documentation

Create:

```txt
docs/implementation/task-d54-lead-enquiry-workspace-separation-ui-foundation.md
```

Document:

```txt
routes added
components added
APIs consumed
permission mapping
compatibility notes
known limitations
```

---

## Deliverables

New or updated pages:

```txt
src/app/**/crm/leads/page.tsx
src/app/**/crm/leads/[id]/page.tsx
```

New or updated components:

```txt
src/features/crm/leads/components/lead-list.tsx
src/features/crm/leads/components/lead-form.tsx
src/features/crm/leads/components/lead-detail.tsx
src/features/crm/leads/components/lead-assignment-dialog.tsx
src/features/crm/leads/components/lead-followup-panel.tsx
```

Updated:

```txt
CRM navigation/sidebar
Enquiry detail optional Source Lead display
```

Documentation:

```txt
docs/implementation/task-d54-lead-enquiry-workspace-separation-ui-foundation.md
```

---

## Explicit Non-Scope

Do not:

* create new tables
* create migrations
* change lead assignment service behavior
* change enquiry service behavior beyond read-only linked lead display
* change quotation flow
* change approval flow
* change dashboard datasets
* change reports
* implement won/lost synchronization
* replace audit-backed lead follow-up persistence
* migrate historical enquiry records into leads

These belong to later D.5 phases.

---

## Verification

Run:

```txt
npm exec tsc --noEmit
```

Optional if project supports:

```txt
npm run lint
npm run build
```

Manual verification:

```txt
Lead menu appears for permitted users
Lead menu hidden or blocked for unauthorized users
Lead list loads from /api/crm/leads
Lead create works
Lead edit works
Lead detail works
Lead assign creates or reuses enquiry
Linked enquiry opens from lead detail
Existing enquiry page still works
Existing quotation flow still works
Dashboard still works
Reports still work
```

---

## Definition of Done

Task is complete when:

* Lead and Enquiry appear as separate workspaces
* Lead UI uses Lead APIs
* Enquiry UI remains compatible
* Lead assignment UI creates or reuses enquiry through API
* Linked enquiry is visible from Lead detail
* Existing enquiry, quotation, dashboard, and reporting flows remain unchanged

Result:

```txt
Lead Workspace = Established
Enquiry Workspace = Preserved
Lead / Enquiry UI Boundary = Established
Ready for D.5.5 Opportunity / Sales Workspace Refinement
```
