# Task 018b — Entity Profiles & Smart Segments

**Status:** done  
**Phase:** Core CRM enhancement (post v1.0)

## Objective

Turn imported market data into actionable CRM profiles and improve segment creation with database-driven filters and usable static segments.

## Scope delivered

### Part 1 — Company profile (`/market/companies/[id]`)

Sections: basic info, linked people, contact points, service matches, campaign history, inbox replies, leads, opportunities, activities timeline.

Quick actions: add to static segment, create lead, create task, campaign placeholder.

### Part 2 — Person profile (`/market/people/[id]`)

New detail page with basic info, contacts, campaigns, replies, leads/opps, activities.

People table: name → profile; company → company profile when `companyId` exists.

### Part 3 — Contact points (`/market/contact-points`)

Columns: type, value, linked company/person (resolved from `entityType` + `entityId`), entity type, verified, confidence, campaign/reply counts.

### Part 4 — Smart segment filters

`GET /api/segments/filter-options?targetType=companies|people|contact_points`

Segment form: dropdowns from API; optional `q`; `minLeadScore`; hasEmail/hasMobile as true/false/any.

### Part 5 — Static segments

`type: static` on create/edit; filters hidden; `static-segment-manager` on detail.

`POST` / `DELETE` `/api/segments/[id]/members` with `{ ids: [...] }`.

`getSegmentMembers`: static → `staticIds`; dynamic → filters.

### Part 6 — Bulk add to segment

Row checkboxes + “select page” on companies, people, contact-points tables.

`Add to Segment` modal → static segments matching `targetType` via `GET /api/segments/static-list`.

### Part 7 — Lead / task quick actions

`entity-quick-actions.tsx` — minimal forms calling existing `POST /api/leads` and `POST /api/tasks`.

### Part 8 — Documentation

Updated: `docs/01-architecture.md`, `03-api-specification.md`, `04-ui-pages.md`, `07-leads-pipeline.md`, `14-roadmap.md`, `16-changelog.md`, `13-decisions-log.md`, `tasks/README.md`.

## Key files

| Area | Path |
|------|------|
| Market service | `src/server/services/market.service.ts` |
| Segment service | `src/server/services/segment.service.ts` |
| Company profile | `src/app/market/companies/[id]/page.tsx` |
| Person profile | `src/app/market/people/[id]/page.tsx` |
| Shared UI | `src/components/market/*`, `src/components/segments/*` |
| APIs | `src/app/api/market/people/[id]`, `src/app/api/segments/filter-options`, `static-list`, `[id]/members` |

## Acceptance criteria

- [x] `npm run lint` passes
- [x] `npm run build` passes
- [x] Company detail actionable with related records
- [x] Person detail exists
- [x] Contact points show ownership
- [x] Segment form uses filter-options
- [x] Static segments + member add/remove
- [x] Bulk add to static segment
- [x] Lead/task quick actions
- [x] Docs and changelog updated

## How to test

### Static segment creation

1. Go to `/segments/new`.
2. Set **type** = static, choose **targetType** (e.g. companies).
3. Save — filters section should be hidden on edit/detail.
4. On segment detail, use **إضافة أعضاء** — search, checkbox select, add.

### Bulk add to segment

1. Open `/market/companies` (or people / contact-points).
2. Select rows (or “select page”).
3. Click **إضافة إلى شريحة**.
4. Pick a static segment with matching targetType.
5. Confirm — `POST /api/segments/:id/members` appends IDs.

### Profiles & quick actions

1. Open a company from `/market/companies` → verify sections load.
2. Use **إنشاء Lead** / **إنشاء مهمة** — check `/leads` and `/tasks`.
3. Open person from people table → same checks.

## Known limitations

- “Start campaign with this company” is a placeholder only.
- Static segment member removal UI on detail is add-focused; use API `DELETE` for bulk remove if needed.
- `companies` optional search in people filter-options may be limited; free-text `q` still available.
- Campaign/reply counts on contact points depend on existing campaign/inbox data.
- Dynamic segments cannot receive manual members (by design).