# Task D.5.5: Opportunity / Sales Workspace Refinement

## Status

Planned

## Objective

Refine the Sales workspace so enquiries created from leads are presented and operated as Sales Opportunities, while preserving existing enquiry, quotation, dashboard, report, and approval compatibility.

Business boundary:

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

This task does not replace `crm_enquiries`. It improves the sales-facing workspace around it.

---

## 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-d52-lead-domain-service-api-foundation.md`
* `docs/implementation/task-d53-lead-assignment-create-enquiry-foundation.md`
* `docs/implementation/task-d54-lead-enquiry-workspace-separation-ui-foundation.md`
* `docs/security/crm-authorization-boundaries.md`
* existing enquiry API/service/UI
* existing quotation conversion flow

---

## Current Foundation

Already available:

```txt
crm_leads
crm_enquiries
crm_enquiries.lead_id

Lead UI
Enquiry UI
Lead Assignment API
Lead -> Enquiry creation
Source Lead display in Enquiry detail
```

Do not recreate:

```txt
tables
migrations
lead assignment service
lead APIs
enquiry APIs
quotation APIs
```

---

## Business Rule

After a Lead is assigned:

```txt
Lead
  -> creates / reuses Enquiry
  -> Enquiry becomes Sales Opportunity workspace
```

The DB object remains:

```txt
crm_enquiries
```

The sales-facing business wording may display as:

```txt
Opportunity
```

where appropriate.

---

## Scope D5.5.1 Sales Workspace Wording

Refine enquiry UI labels for sales-facing pages.

Recommended display naming:

```txt
Menu: Enquiries or Opportunities
Page title: Opportunities
Detail title: Opportunity Detail
Source label: Source Lead
```

Rules:

* Do not rename database tables
* Do not rename API paths in this task
* Do not break existing `/api/crm/enquiries`
* Avoid global find/replace that may break compatibility
* Keep technical names in code where already established unless safely isolated

---

## Scope D5.5.2 Opportunity List Refinement

Update existing enquiry list to better support Sales workflow.

Recommended columns:

```txt
Enquiry / Opportunity Code
Source Lead
Customer
Project Name
Product Type
Sales Owner
Status
Estimated Value
Chance %
Expected Close Date
Last Follow-up
Next Follow-up
Created Date
```

Recommended filters:

```txt
Sales Owner
Product Type
Status
Customer
Source Lead
Expected Close Date
```

Rules:

* Use existing enquiry API where possible
* Add only non-breaking response fields if needed
* Do not change dashboard/report query contracts
* Preserve current enquiry list behavior for records without `lead_id`

---

## Scope D5.5.3 Opportunity Detail Refinement

Update existing enquiry detail page to make sales execution clearer.

Sections:

```txt
Opportunity Summary
Source Lead
Customer / Contact
Requirement
Sales Qualification
Follow-up Timeline
Quotation Readiness
Linked Quotations
```

Actions:

```txt
Edit Opportunity
Create Follow-up
Create Quotation
Open Source Lead
```

Rules:

* `Source Lead` is read-only
* Marketing users may not get broader enquiry access from this block
* Quotation creation behavior must remain unchanged
* Enquiry records without `lead_id` must still render normally

---

## Scope D5.5.4 Sales Qualification Fields

Use existing enquiry fields:

```txt
requirement
estimatedValue
chancePercent
expectedCloseDate
competitor
priority
status
```

Refine UI grouping only.

Rules:

* Do not add new fields unless already present in schema
* Do not create migration
* Keep validation compatible with existing enquiry service
* Avoid changing required fields that could break legacy creation

---

## Scope D5.5.5 Source Lead Read Model

Enhance enquiry detail read model if needed to include minimal source lead data:

```ts
sourceLead?: {
  id: string;
  code: string;
  projectName?: string | null;
  status?: string | null;
  awareness?: string | null;
}
```

Rules:

* Only expose source lead if current user can access the enquiry
* Do not widen Lead permission from Enquiry page
* Do not make extra client-side calls if server-side enrichment already exists

---

## Scope D5.5.6 Follow-up Continuity

Keep existing enquiry follow-up architecture.

Rules:

* Sales follow-ups belong to enquiry/opportunity
* Lead follow-ups remain audit-backed from D.5.2 until future persistence decision
* Do not merge lead follow-up and enquiry follow-up timelines in this task
* Optional: show Source Lead activity as read-only if already available and safe

---

## Scope D5.5.7 Quotation Readiness Panel

Add a lightweight readiness panel on Opportunity detail.

Suggested checks:

```txt
Customer selected
Contact selected
Project name present
Product type present
Requirement present
Estimated value present
```

Output:

```txt
Ready to create quotation
Missing required information
```

Rules:

* Informational only
* Do not block quotation creation unless existing service already blocks it
* Do not change quotation service validation

---

## Scope D5.5.8 Permission Handling

Use existing enquiry permissions and CRM access boundaries.

Examples:

```txt
crm.enquiry.read
crm.enquiry.update
crm.enquiry.followup.create
crm.quotation.create
```

Rules:

* Do not check role strings directly
* Hide unauthorized actions
* Handle 403 gracefully
* Backend remains the source of truth

---

## Scope D5.5.9 Documentation

Create:

```txt
docs/implementation/task-d55-opportunity-sales-workspace-refinement.md
```

Document:

```txt
UI wording decisions
routes changed
components changed
API fields added
compatibility notes
known limitations
```

---

## Deliverables

Updated:

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

Updated or added components:

```txt
src/features/crm/enquiries/components/enquiry-list.tsx
src/features/crm/enquiries/components/enquiries-table.tsx
src/features/crm/enquiries/components/enquiry-detail.tsx
src/features/crm/enquiries/components/source-lead-card.tsx
src/features/crm/enquiries/components/quotation-readiness-panel.tsx
```

Optional updated API/read model:

```txt
src/features/crm/enquiries/api/types.ts
src/features/crm/enquiries/server/service.ts
```

Documentation:

```txt
docs/implementation/task-d55-opportunity-sales-workspace-refinement.md
```

---

## Explicit Non-Scope

Do not:

* create new tables
* create migrations
* rename `crm_enquiries`
* rename `/api/crm/enquiries`
* rewrite quotation conversion
* change approval workflow
* change dashboard datasets
* change reports
* implement won/lost synchronization
* migrate legacy enquiry records
* merge lead and enquiry follow-up persistence
* remove `crm_enquiries.pipeline_stage`

These belong to later phases.

---

## Verification

Run:

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

Optional:

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

Manual verification:

```txt
Opportunity/Enquiry list still loads
Records with lead_id show Source Lead
Records without lead_id still work
Opportunity detail shows sales execution sections
Create quotation still works
Existing enquiry follow-ups still work
Lead page still opens linked enquiry
Quotation page still works
Dashboard still works
Reports still work
```

---

## Definition of Done

Task is complete when:

* Sales workspace clearly represents assigned enquiries as opportunities
* Existing enquiry API compatibility remains intact
* Source Lead is visible from Opportunity detail
* Quotation readiness is visible but non-blocking
* Existing quotation, dashboard, report, and approval behavior remains unchanged

Result:

```txt
Opportunity Workspace = Refined
Sales Execution UX = Clarified
Lead / Enquiry Boundary = Preserved
Ready for D.5.6 Won / Lost Lifecycle Alignment
```