# Project Contact Management - Product Requirements Document

## Executive Summary

This PRD outlines the requirements for adding comprehensive contact management capabilities to ERPNext's Project DocType through the hybrowlabs_customization app. The feature enables projects to maintain multiple contact types linked to the associated customer, with automatic Contact creation and specified communication preferences for each contact.

## Core Components

### DocTypes

| DocType | Type | Purpose | Key Fields |
|---------|------|---------|------------|
| Project Contact | Child Table | Store project-specific contact information | contact_type, contact, role, is_primary |
| Project | Master | Enhanced with contact management | project_contacts (Table field) |
| Contact | Master | Enhanced for project linkage | project_links (auto-created) |

### Relationships
```
Customer ──1:N──> Project ──1:N──> Project Contact ──N:1──> Contact
                      │                                         │
                      └─────────── Customer Linkage ──────────┘
```

## Functional Requirements

### 1. Communication Preferences Management
- **Document Requests**: Receive requests for project documentation and deliverables
- **Weekly Update**: Receive weekly project status and progress reports
- **Daily Update**: Receive daily status updates and activity logs
- **Delivery Note**: Receive delivery notes and shipment notifications
- **Sales Invoice**: Receive sales invoices and billing information
- Each contact can have multiple preferences selected via checkboxes
- All preferences are unchecked by default when contacts are auto-fetched

### 2. Contact Management Interface
- Add/Edit/Remove contacts directly from Project form
- Select communication preferences via checkboxes for each contact
- Contact role/designation specification
- Email/Phone validation
- All communication checkboxes unchecked by default

### 3. Automatic Contact Population and Creation
- **On Project Creation**: Automatically fetch and populate all existing contacts linked to the selected Customer
- **Default Values**: All communication preference checkboxes unchecked initially
- **Manual Addition**: Users can add new contacts beyond those auto-fetched
- **New Contact Creation**: When manually adding contacts, create new Contact record if not existing
- **Link Management**: Maintain automatic linking between Contact and Customer
- **Duplicate Prevention**: Check existing contacts by email to prevent duplicates
- **Update Behavior**: Update existing contacts when same email is used

## Technical Specifications

### 1. Project Contact Child Table Structure

**Purpose**: Store project-specific contact information as a child table within the Project DocType.

**Required Fields**:
- **Contact Link** (Reference): Auto-populated link to Contact DocType (read-only)
- **First Name** (Text): Contact's first name (required)
- **Last Name** (Text): Contact's last name (optional)
- **Email** (Email): Contact's email address (required)
- **Phone** (Text): Contact's phone number (optional)
- **Role/Designation** (Text): Contact's role in the organization

**Communication Preference Checkboxes**:
- **Document Requests** (Checkbox): Include in document request communications
- **Weekly Update** (Checkbox): Include in weekly update communications
- **Daily Update** (Checkbox): Include in daily update communications
- **Delivery Note** (Checkbox): Include in delivery note communications
- **Sales Invoice** (Checkbox): Include in sales invoice communications

**Additional Fields**:
- **Status** (Dropdown): Active/Inactive

### 2. Project DocType Enhancement

**New Section**: "Project Contacts" section to be added to the Project form
**Location**: After the Users section in the Project form
**Type**: Collapsible section containing the Project Contact child table

### 3. Business Logic and Automation

**Initial Contact Population**:
- When a new project is created with a Customer selected, automatically fetch all contacts linked to that Customer
- Populate the Project Contacts table with these existing contacts
- All communication preference checkboxes remain unchecked by default for auto-fetched contacts
- Users can then selectively check preferences for each contact based on project needs

**Manual Contact Addition Process**:
- Users can manually add new contacts beyond those auto-fetched
- When a project contact is manually added, system checks if Contact exists in Contact DocType
- If new, automatically creates Contact record; if existing, links to it
- Each contact is automatically linked to the project's customer
- Contact link field is auto-populated after creation

**Validation Rules**:
- Email format must be valid
- Required fields must be filled before saving
- Contact status defaults to "Active"
- All communication checkboxes unchecked by default
- At least one communication preference should be selected for active contacts (warning, not error)

**Integration Behavior**:
- All project contacts are automatically linked to the project's customer
- Communication preferences managed via checkboxes for targeted communications
- System can filter contacts based on checked preferences for bulk communications
- Existing contacts are updated rather than duplicated when same email is used
- Customer contact changes don't automatically sync to existing projects (snapshot approach)

## Workflow Diagram

```
Create New Project
       │
       ▼
Select Customer
       │
       ▼
Auto-fetch All Customer Contacts
       │
       ▼
Populate Project Contacts Table
(All Comm Checkboxes: Unchecked)
       │
       ├─────────────────────┐
       ▼                     ▼
User Reviews Contacts    User Adds New Contact
       │                     │
       ▼                     ▼
Select Comm Preferences  Enter Contact Details
       │                     │
       ▼                     ▼
Check Relevant Boxes     Select Comm Preferences
(Doc Req/Updates/etc)    (Doc Req/Updates/etc)
       │                     │
       │                     ▼
       │                Check Duplicate Email
       │                     │
       │                 ┌───▼───┐
       │                 │EXISTS?│
       │                 └───┬───┘
       │                     │
       │             ┌───────▼───────▼───┐
       │             │YES            NO   │
       │             │Link           Create│
       │             │Existing       New  │
       │             │Contact        Contact│
       │             └───────┬───────────┘
       │                     │
       └─────────────────────┼
                             ▼
                    Save Project with Contacts
```

## Use Case Diagram

```
                    Project Manager
                         │
    ┌────────────────────┼────────────────────┐
    │                    │                    │
    ▼                    ▼                    ▼
Add Contact         Edit Contact      Remove Contact
    │                    │                    │
    ▼                    ▼                    ▼
Create Contact      Update Contact    Unlink Contact
    │                    │                    │
    └────────────────────┼────────────────────┘
                         │
                         ▼
              Link Contact to Customer
                         │
           ┌─────────────┼─────────────┐
           │             │             │
           ▼             ▼             ▼
    Customer Rep    Finance Team    Leadership
```

## Sequence Diagram

```
Project Form    Project.py    Contact DocType    Customer
     │              │               │              │
     │──Add Contact─►│               │              │
     │              │──Validate─────►│              │
     │              │◄─Valid────────│              │
     │              │──Check Existing│              │
     │              │    Contact     │              │
     │              │◄─Not Found─────│              │
     │              │──Create New────►│              │
     │              │    Contact     │              │
     │              │◄─Contact ID────│              │
     │              │──Link to───────┼─────────────►│
     │              │   Customer     │              │
     │              │◄─Link Success──┼──────────────│
     │              │──Save Project──│              │
     │◄─Success─────│                │              │
```

## Data Storage Requirements

### 1. New Child Table: Project Contact
- Child table linked to Project DocType
- Stores all contact information for project stakeholders
- Maintains relationship with Contact and Customer DocTypes

### 2. Key Relationships
- One Project can have multiple Project Contacts
- Each Project Contact creates/links to one Contact record
- All Project Contacts inherit the Customer link from their parent Project
- Contact DocType maintains dynamic links to Customer

## UI/UX Specifications

### 1. Project Form Layout

**Contact Section Position**: After "Users" section, before "Notes" section

**Section Structure**:
```
┌─ Project Contacts ────────────────────────────────────┐
│                                                       │
│ [+ Add Row]                                           │
│                                                       │
│ ┌─ Contact Table ─────────────────────────────────────────────────────────────┐│
│ │ Name      │ Email       │ Doc Req │ Weekly │ Daily │ Del Note │ Invoice │││
│ │ John Doe  │ john@ex...  │    ✓    │   ✓    │   ✗   │    ✗     │    ✓    │││
│ │ Jane Smith│ jane@ex...  │    ✗    │   ✓    │   ✓   │    ✓     │    ✗    │││
│ │ Bob Wilson│ bob@ex...   │    ✓    │   ✗    │   ✓   │    ✗     │    ✗    │││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│                                                       │
│ ┌─ Quick Add Contact ──────────────────────────────────┐│
│ │ First Name: [________] Last Name: [________]         ││
│ │ Email: [________________] Phone: [_____________]     ││
│ │ Role: [___________]                                  ││
│ │ Communication Preferences:                           ││
│ │ [ ] Document Requests  [ ] Weekly Update             ││
│ │ [ ] Daily Update      [ ] Delivery Note              ││
│ │ [ ] Sales Invoice                                    ││
│ │                        [Add Contact]                 ││
│ └─────────────────────────────────────────────────────┘│
└───────────────────────────────────────────────────────┘
```

### 2. Child Table View Configuration

**Editable Fields**: All fields and checkboxes editable inline except `contact`
**Read-only Fields**: `contact` (auto-populated after save)
**Required Fields**: `first_name`, `email_id`
**Optional Fields**: `phone`, `last_name`, `role`, all communication checkboxes
**Checkbox Fields**: Document Requests, Weekly Update, Daily Update, Delivery Note, Sales Invoice

### 3. Form Validations

**Client-side**:
- Email format validation
- Required field validation
- Warning if no communication preferences selected

**Server-side**:
- Email uniqueness check
- Customer existence validation
- Contact creation/update logic
- Bulk communication filtering based on checkbox selections

## Validation Rules and Business Logic

### 1. Contact Validation Rules

| Rule | Description | Implementation |
|------|-------------|----------------|
| Email Format | Valid email address required | `validate_email_address()` |
| Email Uniqueness | No duplicate emails per project | Database constraint |
| Primary Contact Limit | One primary contact per contact type | Python validation |
| Customer Required | Project must have customer for contact linking | Conditional requirement |
| Contact Type Required | Must select valid contact type | Required field |

### 2. Business Logic Rules

**Contact Creation Logic**:
1. Check if contact exists by email address
2. If exists, update and link to customer
3. If not exists, create new contact
4. Always ensure customer linkage
5. Maintain contact-project relationship

**Primary Contact Logic**:
1. Only one primary contact per contact type allowed
2. If setting new primary, remove primary flag from others
3. Default to primary if first contact of that type

**Customer Linking Logic**:
1. Auto-link all project contacts to project customer
2. Create Dynamic Link entry in Contact
3. Update customer contact list
4. Maintain referential integrity

## Integration Points

### 1. Customer Module Integration
- **Dynamic Links**: Contacts linked via Dynamic Link DocType
- **Customer Dashboard**: Show project contacts in customer view
- **Contact Management**: Unified contact management across modules

### 2. Communication Integration  
- **Email Integration**: Use project contacts for project communications
- **Notification System**: Send notifications to relevant contact types
- **Communication Thread**: Link communications to appropriate contacts

### 3. CRM Integration
- **Lead Conversion**: Convert project contacts to leads if needed
- **Opportunity Tracking**: Link opportunities to project contacts
- **Sales Pipeline**: Include project contacts in sales processes

### 4. Project Management Integration
- **Task Assignment**: Assign tasks to project contacts
- **Progress Updates**: Send updates to "Daily update" contacts
- **Escalation Matrix**: Use "Leadership" contacts for escalations
- **Billing Notifications**: Send invoices to "Billing and accounts" contacts

## Reports and Analytics

### 1. Project Contact Report
**Type**: Query Report
**Filters**: Project, Customer, Contact Type, Date Range
**Columns**: Project, Contact Name, Type, Email, Phone, Role, Status

### 2. Contact Distribution Dashboard
**Type**: Dashboard
**Widgets**: 
- Contact Type Distribution (Pie Chart)
- Active vs Inactive Contacts (Bar Chart)
- Projects per Customer Contact (Line Chart)

### 3. Communication Analytics
**Type**: Script Report  
**Metrics**: 
- Email frequency per contact type
- Response rates by contact
- Escalation patterns

## Permissions Structure

### 1. Project Contact Permissions

| Role | Create | Read | Write | Delete |
|------|--------|------|-------|--------|
| Projects Manager | ✓ | ✓ | ✓ | ✓ |
| Projects User | ✓ | ✓ | ✓ | ✗ |
| Employee | ✗ | ✓ | ✗ | ✗ |
| Customer | ✗ | ✓ | ✗ | ✗ |

### 2. Data Access Rules

**Customer-based Access**:
- Users can only access contacts for customers they have permissions for
- Customer contacts visible based on customer permissions
- Project-specific contact access based on project permissions

**Role-based Restrictions**:
- Projects Manager: Full access to all project contacts
- Projects User: Read/write access to assigned projects only
- Employee: Read-only access to public project contacts
- Customer: Read-only access to own customer contacts