panel/CONTACTS_SYSTEM_README.md

# Contacts Management System

## Overview

A comprehensive contacts management system has been implemented to replace the simple text field for project contacts. This system allows you to:

- **Create and manage a centralized contact database**
- **Link multiple contacts to each project**
- **Categorize contacts** (Project contacts, Contractors, Offices, Suppliers, etc.)
- **Track contact details** (name, phone, email, company, position)
- **Set primary contacts** for projects
- **Search and filter** contacts easily

## What Was Implemented

### 1. Database Schema

**New Tables:**

- **`contacts`** - Stores all contact information
  - `contact_id` (Primary Key)
  - `name`, `phone`, `email`, `company`, `position`
  - `contact_type` (project/contractor/office/supplier/other)
  - `notes`, `is_active`
  - `created_at`, `updated_at`

- **`project_contacts`** - Junction table linking projects to contacts (many-to-many)
  - `project_id`, `contact_id` (Composite Primary Key)
  - `relationship_type`, `is_primary`
  - `added_at`, `added_by`

### 2. API Endpoints

- **`GET /api/contacts`** - List all contacts (with filters)
- **`POST /api/contacts`** - Create new contact
- **`GET /api/contacts/[id]`** - Get contact details
- **`PUT /api/contacts/[id]`** - Update contact
- **`DELETE /api/contacts/[id]`** - Delete contact (soft/hard)
- **`GET /api/projects/[id]/contacts`** - Get project's contacts
- **`POST /api/projects/[id]/contacts`** - Link contact to project
- **`DELETE /api/projects/[id]/contacts`** - Unlink contact from project
- **`PATCH /api/projects/[id]/contacts`** - Set primary contact

### 3. UI Components

- **`ContactForm`** - Create/edit contact form
- **`/contacts` page** - Full contacts management interface with:
  - Statistics dashboard
  - Search and filtering
  - Contact cards with quick actions
  - CRUD operations
- **`ProjectContactSelector`** - Multi-contact selector for projects
  - View linked contacts
  - Add/remove contacts
  - Set primary contact
  - Real-time search

### 4. Integration

- **Navigation** - "Kontakty" link added to main navigation
- **ProjectForm** - Contact text field replaced with `ProjectContactSelector`
- **Translations** - Polish translations added to i18n
- **Query Functions** - Comprehensive database query functions in `src/lib/queries/contacts.js`

## How to Use

### Initial Setup

1. **Run the migration script** to create the new tables:
   ```bash
   node migrate-contacts.mjs
   ```

2. **Start your development server**:
   ```bash
   npm run dev
   ```

3. **Visit** `http://localhost:3000/contacts` to start adding contacts

### Managing Contacts

1. **Create Contacts**:
   - Go to `/contacts`
   - Click "Dodaj kontakt"
   - Fill in contact details
   - Select contact type (Project/Contractor/Office/Supplier/Other)

2. **Link Contacts to Projects**:
   - Edit any project
   - In the "Kontakty do projektu" section
   - Click "+ Dodaj kontakt"
   - Search and add contacts
   - Set one as primary if needed

3. **View Contact Details**:
   - Contacts page shows all contacts with:
     - Contact information (phone, email, company)
     - Number of linked projects
     - Contact type badges
   - Edit or delete contacts as needed

### Contact Types

- **Kontakt projektowy (Project)** - Project-specific contacts
- **Wykonawca (Contractor)** - Construction contractors
- **Urząd (Office)** - Government offices, municipalities
- **Dostawca (Supplier)** - Material suppliers, vendors
- **Inny (Other)** - Any other type of contact

### Features

- **Search** - Search by name, phone, email, or company
- **Filter** - Filter by contact type
- **Statistics** - See breakdown of contacts by type
- **Multiple Contacts per Project** - Link as many contacts as needed
- **Primary Contact** - Mark one contact as primary for each project
- **Bidirectional Links** - See which projects a contact is linked to
- **Soft Delete** - Deleted contacts are marked inactive, not removed

## Database Migration Notes

- The **old `contact` text field** in the `projects` table is still present
- It hasn't been removed for backward compatibility
- You can manually migrate old contact data by:
  1. Creating contacts from the old text data
  2. Linking them to the appropriate projects
  3. The old field will remain for reference

## File Structure

```
src/
├── app/
│   ├── api/
│   │   ├── contacts/
│   │   │   ├── route.js              # List/Create contacts
│   │   │   └── [id]/
│   │   │       └── route.js          # Get/Update/Delete contact
│   │   └── projects/
│   │       └── [id]/
│   │           └── contacts/
│   │               └── route.js      # Link/unlink contacts to project
│   └── contacts/
│       └── page.js                   # Contacts management page
├── components/
│   ├── ContactForm.js                # Contact form component
│   └── ProjectContactSelector.js    # Project contact selector
└── lib/
    ├── queries/
    │   └── contacts.js               # Database query functions
    └── init-db.js                    # Database schema with new tables
```

## Future Enhancements

Potential improvements you could add:

- Contact import/export (CSV, Excel)
- Contact groups or tags
- Contact activity history
- Email integration
- Contact notes and history
- Duplicate contact detection
- Contact merge functionality
- Advanced relationship types
- Contact sharing between projects
- Contact reminders/follow-ups

## Support

The old contact text field remains in the database, so no existing data is lost. You can gradually migrate to the new system at your own pace.

Enjoy your new contacts management system! 🎉