TorbatYar/docs/crm-phase-6-3.md

# Phase 6.3 — Enterprise Sales Collaboration Platform

| Field | Value |
| --- | --- |
| Status | Complete |
| Module | crm |
| Version | 0.6.3.0 |
| Database | `crm_db` |
| Migration | `0004_phase_63_collaboration` |
| Depends On | Phase 6.2 |

## Goal

Implement Sales CRM **collaboration** features only: activities, tasks, meetings, calls, email metadata, unified timeline, comments/mentions, bookmarks/favorites, sales team membership, and collaboration audit.

Out of scope: Workflow, Automation, Customer360, Marketing, Helpdesk, Communication Platform, Notification delivery, AI, Analytics.

## Collaboration Architecture

```
API → Activity / Task / Meeting / Call / Email / Timeline / Comment / Mention / Bookmark / Team Services
    → Validators
    → Tenant repositories
    → Independent aggregates (UUID refs)
    → Immutable timeline + publish-only events
```

Email and notification preferences store CRM metadata only; delivery remains outside CRM.

## Timeline Model

`sales_timeline` (immutable) + `timeline_events` link rows.

| Field | Notes |
| --- | --- |
| event_type | lead/contact/org/opportunity/activity/meeting/call/email/task/note/attachment/comment/mention |
| entity_type / entity_id | Primary subject |
| related_* ids | Opportunity / lead / contact / organization |
| occurred_at, payload, is_immutable | Always locked after write |

## Activity Model

Expanded `sales_activities` plus lookups:

- `activity_types`, `activity_statuses`, `activity_priorities`
- `activity_participants`, `activity_reminders`

Types: call, meeting, task, email, follow_up, visit, demo, presentation, negotiation, custom, note, other.

Fields: subject, description, owner, status, priority, due/completed, related lead/contact/org/opportunity.

## Meeting Model

`meetings` + `meeting_attendees`: start/end, location, online URL, agenda, notes, outcome, CRM entity links.

## Call Model

`call_logs` + `call_outcomes`: inbound/outbound, duration, outcome, recording_ref, notes; **opportunity_id required**.

## Comment Model

`comments` (threaded via `parent_comment_id`, pinned, soft delete) + `comment_versions` + `mentions` (unread + notification event flag).

## Business Rules

1. Timeline entries immutable
2. Activity history auditable (`sales_collaboration_audit`)
3. Comments versioned on edit
4. Meetings linked to CRM entities (UUID refs)
5. Calls linked to opportunities (required)
6. Email stores metadata only (no delivery)
7. Everything tenant-aware

## Validation Rules

| Validator | Rules |
| --- | --- |
| Activity | subject required; complete only if not completed/cancelled |
| Meeting | end_at > start_at |
| Task | title required; complete once |
| Call | opportunity required; duration ≥ 0 |
| Timeline | reject mutations when `is_immutable` |
| Comment | non-empty body; bookmark entity limited to lead/contact/org/opportunity |

## Events

| Event | When |
| --- | --- |
| `crm.activity.created` | Activity created |
| `crm.task.completed` | Task completed |
| `crm.meeting.finished` | Meeting finished |
| `crm.call.logged` | Call logged |
| `crm.timeline.updated` | Timeline entry appended |
| `crm.comment.created` | Comment created |
| `crm.mention.created` | @user mention created |

## Permissions

- `crm.activities.*`
- `crm.tasks.*`
- `crm.meetings.*`
- `crm.calls.*`
- `crm.timeline.*`
- `crm.comments.*`
- `crm.mentions.*`
- `crm.team.*`

## API Endpoints

| Area | Paths |
| --- | --- |
| Activities | `/api/v1/activities` (+ participants, reminders) |
| Tasks | `/api/v1/tasks`, checklist, complete |
| Meetings | `/api/v1/meetings`, attendees, finish |
| Calls | `/api/v1/calls` |
| Email metadata | `/api/v1/email-threads`, `/emails` |
| Timeline | `/api/v1/timeline`, `/timeline/opportunities/{id}` |
| Comments / Mentions | `/api/v1/comments`, `/mentions/unread`, `/mentions/{id}/read` |
| Bookmarks / Favorites | `/api/v1/bookmarks`, `/favorites` |
| Team | `/api/v1/team-roles`, `/team-members`, `/team-assignments` |
| Preferences | `/api/v1/collaboration-preferences/{user_id}` |

## Migration Summary

- Revision: `0004_phase_63_collaboration` (down: `0003_phase_62_sales_engine`)
- Additive `create_all` for collaboration tables
- `sales_activities` model expanded (priority + entity refs)

## Tests Executed

Model, repository, service, API, timeline, activity, meeting, task, call, permission, migration, audit, tenant isolation, documentation validation.

## Known Limitations

- Timeline writers for lead/contact/org create paths are available via `TimelineService.append` but not yet auto-wired into every Phase 6.1 mutation (collaboration/activity/task/meeting/call/comment emit today)
- Email/opened/clicked are CRM metadata flags — Notification Service owns delivery
- Recording and meeting URLs are references only

## CRM Completion Status

Phases **6.0 + 6.1 + 6.2 + 6.3** complete → **CRM Core Platform** ready for Sales CRM use within stated boundaries.

## Next

Do not auto-start further modules. Scope next CRM slice explicitly in `docs/next-steps.md`.

## Related Documents

- [Progress](progress.md)
- [Phase 6.0](crm-phase-6-0.md)
- [Phase 6.1](crm-phase-6-1.md)
- [Phase 6.2](crm-phase-6-2.md)
- [Module Registry](module-registry.md#crm)