@nextsparkjs/theme-crm 0.1.0-beta.1

package/pendings.md

@@ -0,0 +1,205 @@
+# CRM Theme - Phase 3 Pending Items
+
+> **Status**: Deferred - Not working on this phase yet
+> **Last Updated**: 2024-11-28
+
+## Overview
+
+This document tracks pending UI/UX components and customizations needed for the CRM theme to be production-ready. These items are deferred after completing:
+- Phase 1: SQL migrations corrections
+- Phase 2: Permission validation with generic UI
+
+---
+
+## 1. Custom Components (Priority: High)
+
+### 1.1 Pipeline Kanban Board
+- [ ] Create `components/PipelineBoard.tsx` - Drag & drop board for opportunities
+- [ ] Show opportunities grouped by pipeline stages
+- [ ] Display deal value, probability, and close date on cards
+- [ ] Support drag between stages with `opportunities.move_stage` permission
+- [ ] Show pipeline value totals per stage
+- [ ] Add quick actions: edit, view activities, mark as won/lost
+
+### 1.2 Lead Conversion Flow
+- [ ] Create `components/LeadConversionModal.tsx`
+- [ ] Wizard-style flow: Lead → Contact + Company + Opportunity
+- [ ] Pre-fill data from lead
+- [ ] Require `leads.convert` permission
+- [ ] Track conversion in lead record
+
+### 1.3 Activity Timeline
+- [ ] Create `components/ActivityTimeline.tsx`
+- [ ] Polymorphic timeline for any entity (lead, contact, company, opportunity)
+- [ ] Show activities, notes, and system events
+- [ ] Support quick activity creation
+- [ ] Filter by activity type
+
+### 1.4 Contact/Company 360 View
+- [ ] Create `components/EntityDetailView.tsx`
+- [ ] Show related entities (contacts for company, opportunities, activities)
+- [ ] Quick access to communication history
+- [ ] Display key metrics and scores
+
+---
+
+## 2. Dashboard Widgets (Priority: High)
+
+### 2.1 Sales Dashboard
+- [ ] Pipeline funnel visualization
+- [ ] Revenue forecast chart
+- [ ] Won/Lost ratio
+- [ ] Top opportunities list
+- [ ] Activities due today
+
+### 2.2 Marketing Dashboard
+- [ ] Campaign performance metrics
+- [ ] Lead source breakdown
+- [ ] Conversion rates by source
+- [ ] ROI calculations
+
+### 2.3 Team Performance (owner/admin only)
+- [ ] Sales rep leaderboard
+- [ ] Activity completion rates
+- [ ] Opportunity by rep
+- [ ] Pipeline coverage
+
+---
+
+## 3. Template Overrides (Priority: Medium)
+
+### 3.1 Entity List Views
+- [ ] `templates/app/dashboard/(main)/leads/page.tsx`
+  - Custom columns: score badge, source icon, status chip
+  - Quick convert action
+
+- [ ] `templates/app/dashboard/(main)/opportunities/page.tsx`
+  - Toggle between list and Kanban view
+  - Quick stage change
+
+- [ ] `templates/app/dashboard/(main)/activities/page.tsx`
+  - Calendar view option
+  - Due date highlighting
+
+### 3.2 Entity Detail Views
+- [ ] `templates/app/dashboard/(main)/[entity]/[id]/page.tsx`
+  - Related entities sidebar
+  - Activity timeline
+  - Quick actions based on entity type
+
+### 3.3 Entity Create/Edit Forms
+- [ ] Lead form with score calculator
+- [ ] Opportunity form with pipeline/stage selector
+- [ ] Activity form with entity picker
+
+---
+
+## 4. Settings Pages (Priority: Medium)
+
+### 4.1 Pipeline Configuration
+- [ ] `templates/app/dashboard/settings/pipelines/page.tsx`
+- [ ] CRUD for pipelines (owner only)
+- [ ] Stage editor with drag reorder
+- [ ] Probability per stage configuration
+- [ ] Default pipeline selection
+
+### 4.2 Product Catalog
+- [ ] `templates/app/dashboard/settings/products/page.tsx`
+- [ ] Product CRUD (owner only)
+- [ ] Categories and pricing tiers
+- [ ] Product-opportunity association
+
+### 4.3 Import/Export
+- [ ] Bulk import wizard for leads, contacts, companies
+- [ ] CSV/Excel template downloads
+- [ ] Field mapping UI
+- [ ] Requires `bulk.import` permission
+
+---
+
+## 5. Reports (Priority: Low)
+
+### 5.1 Sales Reports
+- [ ] Pipeline analysis report
+- [ ] Win/loss analysis
+- [ ] Sales cycle duration
+- [ ] Requires `reports.sales` permission
+
+### 5.2 Marketing Reports
+- [ ] Campaign ROI
+- [ ] Lead source analysis
+- [ ] Conversion funnel
+- [ ] Requires `reports.marketing` permission
+
+### 5.3 Export Functionality
+- [ ] PDF export for reports
+- [ ] Excel export for data
+- [ ] Requires `reports.export` permission
+
+---
+
+## 6. Mobile Optimizations (Priority: Low)
+
+- [ ] Mobile-friendly pipeline view
+- [ ] Swipe actions for activities
+- [ ] Quick call/email actions
+- [ ] Offline activity logging
+
+---
+
+## 7. Integrations (Priority: Future)
+
+- [ ] Email integration (Gmail, Outlook)
+- [ ] Calendar sync
+- [ ] Phone/VoIP integration
+- [ ] Social media enrichment
+
+---
+
+## Technical Notes
+
+### Component Structure
+```
+contents/themes/crm/
+├── components/
+│   ├── PipelineBoard.tsx
+│   ├── LeadConversionModal.tsx
+│   ├── ActivityTimeline.tsx
+│   ├── EntityDetailView.tsx
+│   └── widgets/
+│       ├── SalesDashboard.tsx
+│       ├── MarketingDashboard.tsx
+│       └── TeamPerformance.tsx
+├── templates/
+│   └── app/
+│       └── dashboard/
+│           ├── (main)/
+│           │   ├── leads/
+│           │   ├── opportunities/
+│           │   └── activities/
+│           └── settings/
+│               ├── pipelines/
+│               └── products/
+└── styles/
+    ├── globals.css
+    └── components.css
+```
+
+### Permission Gates Required
+All custom components must use `PermissionGate` for:
+- `leads.convert`
+- `opportunities.move_stage`
+- `opportunities.close`
+- `activities.complete`
+- `campaigns.launch`
+- `campaigns.pause`
+- `reports.*`
+- `bulk.*`
+- `settings.pipelines`
+- `settings.products`
+
+### Design Guidelines
+- Use CRM theme colors (teal/cyan primary)
+- Professional, data-centric aesthetic
+- Consistent with existing dashboard patterns
+- Follow shadcn/ui component patterns

package/permissions-matrix.md

@@ -0,0 +1,216 @@
+# CRM Theme - Permissions Matrix
+
+## Teams Mode: `single-tenant`
+
+One work team created at signup. Owner can invite multiple members.
+
+## Roles
+
+| Role | Description |
+|------|-------------|
+| owner | CRM Administrator - full control |
+| admin | Sales/Marketing Manager - team management + reports |
+| member | Sales/Marketing Rep - daily operations |
+| viewer | Read-only access to CRM data |
+
+---
+
+## Entity Permissions
+
+### Leads
+
+| Action | owner | admin | member | viewer |
+|--------|-------|-------|--------|--------|
+| create | ✅ | ✅ | ✅ | ❌ |
+| read | ✅ | ✅ | ✅ | ✅ |
+| list | ✅ | ✅ | ✅ | ✅ |
+| update | ✅ | ✅ | ✅ | ❌ |
+| delete | ✅ | ✅ | ❌ | ❌ |
+| assign | ✅ | ✅ | ❌ | ❌ |
+| import | ✅ | ✅ | ❌ | ❌ |
+| export | ✅ | ✅ | ❌ | ❌ |
+| convert | ✅ | ✅ | ✅ | ❌ |
+
+### Contacts
+
+| Action | owner | admin | member | viewer |
+|--------|-------|-------|--------|--------|
+| create | ✅ | ✅ | ✅ | ❌ |
+| read | ✅ | ✅ | ✅ | ✅ |
+| list | ✅ | ✅ | ✅ | ✅ |
+| update | ✅ | ✅ | ✅ | ❌ |
+| delete | ✅ | ✅ | ❌ | ❌ |
+| import | ✅ | ✅ | ❌ | ❌ |
+| export | ✅ | ✅ | ❌ | ❌ |
+
+### Companies
+
+| Action | owner | admin | member | viewer |
+|--------|-------|-------|--------|--------|
+| create | ✅ | ✅ | ✅ | ❌ |
+| read | ✅ | ✅ | ✅ | ✅ |
+| list | ✅ | ✅ | ✅ | ✅ |
+| update | ✅ | ✅ | ✅ | ❌ |
+| delete | ✅ | ✅ | ❌ | ❌ |
+| import | ✅ | ✅ | ❌ | ❌ |
+| export | ✅ | ✅ | ❌ | ❌ |
+
+### Opportunities
+
+| Action | owner | admin | member | viewer |
+|--------|-------|-------|--------|--------|
+| create | ✅ | ✅ | ✅ | ❌ |
+| read | ✅ | ✅ | ✅ | ✅ |
+| list | ✅ | ✅ | ✅ | ✅ |
+| update | ✅ | ✅ | ✅ | ❌ |
+| delete | ✅ | ✅ | ❌ | ❌ |
+| assign | ✅ | ✅ | ❌ | ❌ |
+| import | ✅ | ✅ | ❌ | ❌ |
+| export | ✅ | ✅ | ❌ | ❌ |
+| move_stage | ✅ | ✅ | ✅ | ❌ |
+| close | ✅ | ✅ | ✅ | ❌ |
+
+### Activities
+
+| Action | owner | admin | member | viewer |
+|--------|-------|-------|--------|--------|
+| create | ✅ | ✅ | ✅ | ❌ |
+| read | ✅ | ✅ | ✅ | ✅ |
+| list | ✅ | ✅ | ✅ | ✅ |
+| update | ✅ | ✅ | ✅ | ❌ |
+| delete | ✅ | ✅ | ✅ | ❌ |
+| assign | ✅ | ✅ | ❌ | ❌ |
+| complete | ✅ | ✅ | ✅ | ❌ |
+
+### Notes
+
+| Action | owner | admin | member | viewer |
+|--------|-------|-------|--------|--------|
+| create | ✅ | ✅ | ✅ | ❌ |
+| read | ✅ | ✅ | ✅ | ✅ |
+| list | ✅ | ✅ | ✅ | ✅ |
+| update | ✅ | ✅ | ✅ | ❌ |
+| delete | ✅ | ✅ | ✅ | ❌ |
+
+> Note: Private notes (`isPrivate: true`) are only visible to their creator.
+
+### Campaigns
+
+| Action | owner | admin | member | viewer |
+|--------|-------|-------|--------|--------|
+| create | ✅ | ✅ | ✅ | ❌ |
+| read | ✅ | ✅ | ✅ | ✅ |
+| list | ✅ | ✅ | ✅ | ✅ |
+| update | ✅ | ✅ | ✅ | ❌ |
+| delete | ✅ | ✅ | ✅ | ❌ |
+| launch | ✅ | ✅ | ❌ | ❌ |
+| pause | ✅ | ✅ | ❌ | ❌ |
+
+### Pipelines (Configuration)
+
+| Action | owner | admin | member | viewer |
+|--------|-------|-------|--------|--------|
+| create | ✅ | ❌ | ❌ | ❌ |
+| read | ✅ | ✅ | ✅ | ✅ |
+| list | ✅ | ✅ | ✅ | ✅ |
+| update | ✅ | ❌ | ❌ | ❌ |
+| delete | ✅ | ❌ | ❌ | ❌ |
+
+### Products (Configuration)
+
+| Action | owner | admin | member | viewer |
+|--------|-------|-------|--------|--------|
+| create | ✅ | ❌ | ❌ | ❌ |
+| read | ✅ | ✅ | ✅ | ✅ |
+| list | ✅ | ✅ | ✅ | ✅ |
+| update | ✅ | ❌ | ❌ | ❌ |
+| delete | ✅ | ❌ | ❌ | ❌ |
+
+---
+
+## Theme Features
+
+| Feature | owner | admin | member | viewer | Description |
+|---------|-------|-------|--------|--------|-------------|
+| `reports.sales` | ✅ | ✅ | ❌ | ❌ | Sales performance reports |
+| `reports.marketing` | ✅ | ✅ | ❌ | ❌ | Marketing campaign reports |
+| `reports.pipeline` | ✅ | ✅ | ❌ | ❌ | Pipeline analysis |
+| `reports.export` | ✅ | ✅ | ❌ | ❌ | Export reports |
+| `dashboard.forecasting` | ✅ | ✅ | ❌ | ❌ | Sales forecasting |
+| `dashboard.team_metrics` | ✅ | ✅ | ❌ | ❌ | Team performance KPIs |
+| `bulk.import` | ✅ | ✅ | ❌ | ❌ | Bulk data import |
+| `bulk.export` | ✅ | ✅ | ❌ | ❌ | Bulk data export |
+| `leads.convert` | ✅ | ✅ | ✅ | ❌ | Convert leads to contacts |
+| `settings.pipelines` | ✅ | ❌ | ❌ | ❌ | Pipeline configuration |
+| `settings.products` | ✅ | ❌ | ❌ | ❌ | Product catalog management |
+
+---
+
+## Team Permissions
+
+| Permission | owner | admin | member | viewer |
+|------------|-------|-------|--------|--------|
+| `teams.invite` | ✅ | ✅ | ❌ | ❌ |
+| `teams.remove_member` | ✅ | ✅ | ❌ | ❌ |
+| `teams.change_roles` | ✅ | ❌ | ❌ | ❌ |
+| `teams.settings` | ✅ | ❌ | ❌ | ❌ |
+
+---
+
+## Disabled Core Permissions
+
+- `teams.delete` - Cannot delete organization in single-tenant mode
+
+---
+
+## Test Scenarios
+
+### Owner (CRM Administrator)
+
+1. ✅ Full CRUD on all entities
+2. ✅ Can assign leads/opportunities
+3. ✅ Can convert leads
+4. ✅ Can access all reports
+5. ✅ Can see forecasting and team metrics
+6. ✅ Can bulk import/export
+7. ✅ Can manage pipelines and products
+8. ✅ Can invite all roles (admin, member, viewer)
+9. ✅ Can remove any member
+10. ✅ Can change member roles
+
+### Admin (Manager)
+
+1. ✅ Full CRUD on operational entities (leads, contacts, companies, opportunities)
+2. ✅ Can assign leads/opportunities
+3. ✅ Can convert leads
+4. ✅ Can access all reports
+5. ✅ Can see forecasting and team metrics
+6. ✅ Can bulk import/export
+7. ❌ Cannot manage pipelines
+8. ❌ Cannot manage products
+9. ✅ Can invite members and viewers
+10. ✅ Can remove members and viewers
+11. ❌ Cannot change roles
+
+### Member (Representative)
+
+1. ✅ Can create/update on operational entities
+2. ❌ Cannot delete leads, contacts, companies, opportunities
+3. ✅ Can delete own activities, notes, campaigns
+4. ✅ Can convert leads
+5. ❌ Cannot assign leads/opportunities
+6. ❌ Cannot access reports
+7. ❌ Cannot see forecasting
+8. ❌ Cannot bulk import/export
+9. ❌ Cannot manage pipelines/products
+10. ❌ Cannot invite members
+
+### Viewer
+
+1. ❌ Cannot create anything
+2. ✅ Can view all entities
+3. ❌ Cannot update anything
+4. ❌ Cannot delete anything
+5. ❌ Cannot access reports
+6. ❌ Cannot see forecasting
+