alla-allaos-fullstack/plans/task-d.5.4.md

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:

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:

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:

tables
migrations
seed data
service foundation
assignment service

---

Workspace Rules

Lead Workspace

Audience:

Marketing
Marketing Manager
CRM Manager
Admin

Purpose:

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

Source:

crm_leads
/api/crm/leads

---

Enquiry Workspace

Audience:

Sales
Sales Manager
CRM Manager
Admin

Purpose:

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

Source:

crm_enquiries
existing /api/crm/enquiries

---

Scope D5.4.1 Navigation Separation

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

Add:

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:

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

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

Required actions:

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:

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

Actions:

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:

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:

Sales Owner
Assignment Remark

Behavior:

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

After success:

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:

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:

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

Enquiry UI:

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:

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:

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

Document:

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

---

Deliverables

New or updated pages:

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

New or updated components:

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:

CRM navigation/sidebar
Enquiry detail optional Source Lead display

Documentation:

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:

npm exec tsc --noEmit

Optional if project supports:

npm run lint
npm run build

Manual verification:

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:

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