📙 Work Summaries

📖 Overview

The Work Summaries service manages weekly work summaries that document work performed, progress made, and deliverables provided during each week of service. These summaries provide transparency to clients about ongoing service delivery.

Source Files:

• Service: internal/api/v1/projects/services/work-summary.service.js
• Controller: internal/api/v1/projects/controllers/work-summary.controller.js

Key Capabilities:

• Retrieve single work summary with full communication thread
• Support cursor-based pagination for infinite scroll
• Filter by client dashboard scopes
• Enrich with order/product context
• Apply launch date filtering for historical summaries
• Remove brand references from content

🗄️ Collections Used

projects.tasks

• Operations: Read
• Model: shared/models/projects-tasks.js
• Usage Context: Work summaries stored as special task type

Key Fields for Work Summaries:

{
  _id: ObjectId,
  type: 'work_summary',       // Special task type
  account_id: ObjectId,
  parent_account: ObjectId,
  order_id: ObjectId,
  title: String,
  status: String,
  creator: String,
  first_communication_id: ObjectId,
  last_communication_id: ObjectId,
  created_at: Date,
  updated_at: Date
}

communications

• Operations: Read
• Usage Context: Stores actual work summary content as messages

_store.orders

• Operations: Read
• Usage Context: Product/subscription context

_accounts

• Operations: Read
• Usage Context: Client account information

🔧 Business Logic & Functions

Service Layer

getWorkSummary(options)

Purpose: Retrieves a single work summary with full communication thread, applying brand filtering and access controls.

Parameters:

• taskId (ObjectId) - Work summary task ID
• accountId (ObjectId) - Parent account ID
• limit (Number) - Communications per page
• after (ObjectId, optional) - Cursor for pagination
• dashboardPreferences (Object, optional) - Client dashboard settings

Returns: Work summary object with communications

{
  id: ObjectId,
  title: String,
  type: 'work_summary',
  status: String,
  creator: String,
  account_id: ObjectId,
  parent_account: ObjectId,
  order_id: ObjectId,
  subaccount: { ... },
  order: { ... },
  product: {
    id: ObjectId,
    name: String,
    nickname: String,
    image: String
  },
  communications: {
    data: [
      {
        id: ObjectId,
        body: String,        // Brand references removed
        type: String,
        attachments: Array,
        sent_by: {
          id: ObjectId,
          name: String,
          image: String,
          dashclicks: { projects: { role: String } }
        },
        createdAt: Date
      }
    ],
    has_more: Boolean
  },
  created_at: Date,
  updated_at: Date
}

Business Logic Flow:

1. Access Control Setup:

   const options = {
     _id: taskId,
     parent_account: accountId,
     type: 'work_summary',
     created_at: { $gte: CLIENT_WORK_SUMMARY_LAUNCH_DATE },
   };
   
   if (dashboardPreferences?.allow_client_dashboard || dashboardPreferences?.sso) {
     options.account_id = { $in: dashboardPreferences.sub_account_ids };
     options.parent_account = dashboardPreferences.parent_account;
   }

2. Launch Date Filtering: Only summaries after CLIENT_WORK_SUMMARY_LAUNCH_DATE visible to clients

3. Product Type Filtering: Only managed services excluding 'site' and 'listings'

4. Brand Reference Removal: Uses MongoDB $function to sanitize content:

   body: {
     $function: {
       body: "function(body) {
         if (!body) return body;
         return body
           .replace(/\\s*(dash[\\s-]?clicks?)\\s*/gi, ' ')
           .replace(/\\s+/g, ' ')
           .trim();
       }",
       args: ['$body'],
       lang: 'js'
     }
   }

   Removes "DashClicks", "Dash Clicks", "dash-clicks" variations

5. Communication Pagination:

   • Cursor-based with after parameter
   • Returns has_more flag for infinite scroll
   • Sorts by createdAt ascending for chronological reading

6. User Role Enrichment: Includes sender's project role for context

Key Business Rules:

• ✅ Launch Date Cutoff: Historical summaries before launch date hidden from clients
• ✅ Managed Services Only: Excludes site and listings products
• ✅ Brand Sanitization: Automatic removal of brand references from content
• ✅ Active Orders Only: Only summaries for active managed subscriptions

🔄 Data Flow

flowchart TD
    A[GET /work-summary/:id] --> B{Dashboard Type?}
    B -->|Agency| C[Filter: parent_account = agency]
    B -->|Client| D[Filter: account_id in allowed list]
    C --> E[Apply Launch Date Filter]
    D --> E
    E --> F[Lookup Account + Order]
    F --> G[Validate Order + Subscription]
    G --> H{Valid?}
    H -->|No| I[Return Empty]
    H -->|Yes| J[Fetch Communications]
    J --> K[Remove Brand References]
    K --> L[Enrich with User Data]
    L --> M[Apply Pagination]
    M --> N[Return Work Summary]

🔀 Integration Points

Internal Dependencies

• MANAGED_SUBSCRIPTIONS - Service type list
• CLIENT_WORK_SUMMARY_LAUNCH_DATE - Feature launch constant
• catchAsync() - Error handling
• Projects Tasks - Stored as special task type
• Communications - Message storage

🧪 Edge Cases & Special Handling

Case: Pre-Launch Work Summary

Condition: Summary created before CLIENT_WORK_SUMMARY_LAUNCH_DATE

Handling:

created_at: {
  $gte: CLIENT_WORK_SUMMARY_LAUNCH_DATE;
}

Hidden from results automatically.

Case: Brand Name in Content

Condition: Communication body contains "DashClicks" or variations

Handling: JavaScript function removes all variations:

• "DashClicks" → removed
• "Dash Clicks" → removed
• "dash-clicks" → removed
• Multiple spaces collapsed to single space

Case: Missing Communications

Condition: No communications exist for work summary

Handling:

communications: {
  data: [],
  has_more: false
}

Gracefully returns empty array.

⚠️ Important Notes

• 📅 Launch Date Enforcement: CLIENT_WORK_SUMMARY_LAUNCH_DATE constant controls historical visibility
• 🏷️ Brand Sanitization: Automatic removal prevents white-label exposure
• 📊 Task Type: Work summaries are special type: 'work_summary' tasks
• 🔍 Service Filtering: Only covers managed services (excludes site/listings)
• 💬 Communication Thread: Uses same communication system as regular tasks

🔗 Related Documentation

• Task Management - Related task system
• Activity - Work summaries appear in activity timeline
• Projects Module Overview - Parent module

---

Last Updated: 2025-10-08
Service Files: services/work-summary.service.js, controllers/work-summary.controller.js
Primary Functions: 1 service function, 1 controller endpoint