# Task 018 — CRM Foundation Hardening

## Objective

Strengthen CRM data quality, relationships, channel-aware segments, email validation, global send deduplication, activity timeline, and maintenance backfill before sequences/WhatsApp/large outreach.

## Status

**Completed** — Phase 1 foundation hardening implemented.

## Delivered

### Part 1 — Unified CRM Relationships
- `src/server/services/crm-linking.service.ts`
- Person `companyId` and ContactPoint `companyId` / `personId` indexes (existing)
- Linking helpers used by maintenance backfill

### Part 2 — Import Data Cleaning
- `src/lib/import-contact-rules.ts`
- Simple import skips companies/people without communication channels
- Email classification on contact point create
- Extended import stats counters

### Part 3 — Email Validation
- `src/lib/email-validation.ts`
- ContactPoint fields: `emailValidationStatus`, `emailValidationReason`, `emailValidatedAt`
- Campaign `sendOnlyValidEmails` (default true)
- `EmailValidationBadge` UI component

### Part 4 — Communication Channel Segments
- Segment `targetChannel`: email | mobile | whatsapp | any (default `any`)
- Segment form channel selector + email preview stats
- Channel filters in `member-email-resolve.ts` / `channel-dedup.ts`

### Part 5 — Segment Deduplication
- Email + mobile dedup keys via `channel-dedup.ts`
- Preview stats: raw, unique, duplicates removed

### Part 6 — Global Send Deduplication
- `email_send_history` collection + `EmailSendHistoryModel`
- System settings: `duplicateWindowDays` (7), `duplicateAction` (warn)
- Campaign send duplicate check modal before batch send
- History recorded on successful campaign send

### Part 7 — Activity Timeline
- `src/server/services/activity.service.ts`
- `GET /api/timeline`
- `ActivityTimeline` component on company, person, lead, campaign pages

### Part 8 — Maintenance Tool
- `POST /api/admin/maintenance/backfill-crm-foundation`
- Settings → Maintenance UI

### Part 9 — Documentation
- Updated schema, API, campaign, settings docs and changelog

## Acceptance

- [x] lint + build pass
- [x] Backward compatible defaults (`targetChannel: any`, existing segments/campaigns)
- [x] Import, segments, campaigns, inbox preserved