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:

   node migrate-contacts.mjs
   

2. Start your development server:

   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! 🎉