064d67f099
Add the Sales CRM service through collaboration, sync architecture/registry docs, expose crm.torbatyar.ir, and include a production deploy script. Co-authored-by: Cursor <cursoragent@cursor.com>
154 lines
5.3 KiB
Markdown
154 lines
5.3 KiB
Markdown
# 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)
|