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
• Phase 6.0
• Phase 6.1
• Phase 6.2
• Module Registry