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