task-d.5.5
This commit is contained in:
phaichayon
432
plans/task-d.5.5.md
Normal file
432
plans/task-d.5.5.md
Normal file
@@ -0,0 +1,432 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user