Requests & Work Summaries

The Requests & Work Summaries submodule manages project request workflows, approval processes, and work summary documentation within the admin projects system.

🎯 Overview

This submodule handles the complete lifecycle of project requests, approvals, and work summaries, including submission, review, approval workflows, and communication coordination.

🔧 Service Methods

Request Management

addRequest()

Creates new project requests with validation, team assignment, and notification triggers.

Key Features:

• Request validation and business rule enforcement
• Automatic team assignment and routing
• Priority-based request categorization
• Integration with communication system

getRequest()

Retrieves detailed request information including status, communications, and approval history.

Key Features:

• Comprehensive request data aggregation
• Communication history integration
• Status tracking and timeline information
• Role-based data filtering

updateRequest()

Updates existing request information, status, and associated metadata.

Key Features:

• Request modification with validation
• Status progression management
• Activity logging and audit trails
• Notification triggers for updates

cancelRequest()

Cancels pending requests with proper validation and cleanup processes.

Key Features:

• Request cancellation with authorization checks
• Related data cleanup and status updates
• Notification of stakeholders
• Activity logging for audit purposes

Approval Workflows

addApproval()

Creates approval requests with routing, escalation, and notification management.

Key Features:

• Approval workflow initialization
• Automatic reviewer assignment
• Escalation rules and timelines
• Integration with project management system

getApproval()

Retrieves comprehensive approval information including review status and decisions.

Key Features:

• Approval data aggregation
• Review history and decision tracking
• Communication integration
• Timeline and milestone information

cancelApproval()

Cancels pending approval requests with proper authorization and cleanup.

Key Features:

• Approval cancellation with validation
• Stakeholder notification management
• Related workflow cleanup
• Audit trail maintenance

Work Summary Management

addWorkSummary()

Creates detailed work summaries with attachments, progress tracking, and reporting.

Key Features:

• Work summary creation with rich content support
• File attachment management
• Progress tracking and milestone documentation
• Integration with project timelines

getWorkSummary()

Retrieves comprehensive work summary information including attachments and history.

Key Features:

• Work summary data aggregation
• File attachment retrieval
• Version history tracking
• Progress analytics integration

deleteWorkSummary()

Removes work summaries with proper authorization and cleanup processes.

Key Features:

• Work summary deletion with validation
• File cleanup and attachment management
• Related data consistency maintenance
• Activity logging for audit trails

Communication Management

reply()

Handles replies to requests, approvals, and work summaries with threading and notifications.

Key Features:

• Threaded communication management
• Notification triggers and routing
• File attachment support
• Activity tracking and audit logging

myRequest()

Retrieves user-specific request information with filtering and pagination.

Key Features:

• User-specific request filtering
• Role-based data access
• Pagination and sorting support
• Status-based filtering options

🔐 Authorization Framework

Role Requirements

All request and work summary operations require appropriate PROJECT_ROLES permissions:

• Admin: Full request and approval management access
• Account Manager: Account-specific request oversight
• Fulfillment Specialist: Request execution and work summary creation
• Team Lead: Team-based request coordination and approval

Permission Validation

• Request Access: Validates user access to specific requests
• Approval Authority: Ensures proper authorization for approval decisions
• Work Summary Rights: Validates creation and modification permissions
• Communication Access: Role-based filtering of request communications

🏗️ Technical Architecture

Database Collections

• _projects-tasks: Core request, approval, and work summary storage
• _communications: Request communication and threading management
• _activity: Comprehensive activity logging and audit trails
• _store.orders: Order and subscription integration
• _users: Team member and role information

Workflow Integration

• Activity Logging: Uses createActivity utility for comprehensive audit trails
• Socket Integration: Real-time notifications via socketEmit utility
• Team Assignment: Dynamic team assignment and workload distribution
• File Management: Attachment handling and storage management

Request Categories

The service supports various request and approval types:

• Onboarding Issues: Client onboarding problem resolution
• Subscription Past Due: Payment and billing issue handling
• General Requests: Standard project request management
• Approval Workflows: Multi-stage approval processes
• Setup Requirements: Project setup and configuration requests

📊 Data Processing

Request Lifecycle

1. Submission: Request creation with validation and routing
2. Assignment: Automatic team assignment based on criteria
3. Processing: Work execution and progress tracking
4. Review: Quality assurance and approval workflows
5. Completion: Final validation and closure processes

Approval Workflows

• Multi-stage Approval: Support for complex approval hierarchies
• Escalation Rules: Automatic escalation based on timelines
• Decision Tracking: Comprehensive approval decision history
• Notification Management: Automated stakeholder notifications

🔄 Integration Points

External Systems

• Communication System: Message threading and notification delivery
• File Storage: Attachment management and retrieval
• Activity System: Comprehensive audit trail integration
• Notification System: Real-time and email notification delivery

Internal Services

• Order Management: Integration with store order system
• User Management: Team assignment and role validation
• Project System: Integration with project lifecycle management
• Analytics System: Request and approval metrics tracking

📈 Business Logic

Request Processing Flow

graph TD
    A[Request Submission] --> B[Validation & Authorization]
    B --> C[Team Assignment]
    C --> D[Processing & Updates]
    D --> E{Requires Approval?}
    E -->|Yes| F[Approval Workflow]
    E -->|No| G[Direct Processing]
    F --> H[Review & Decision]
    G --> I[Completion]
    H --> I

Work Summary Workflow

• Creation: Work summary initialization with project context
• Documentation: Progress tracking and milestone documentation
• Review: Quality assurance and approval processes
• Integration: Integration with project timelines and reporting

🛡️ Security Features

Data Protection

• Input Validation: Comprehensive input sanitization and validation
• Role-based Access: Granular permission checking for all operations
• Audit Logging: Complete audit trails for compliance and tracking
• File Security: Secure attachment handling and access control

Authorization Checks

• Request Access: Validates user access to specific requests
• Modification Rights: Ensures proper permissions for updates
• Communication Rights: Role-based filtering of request communications
• Approval Authority: Validates approval and decision-making permissions

📝 Usage Examples

Creating a Project Request

await addRequest({
  title: 'Website Setup Request',
  description: 'Client needs website configuration',
  orderId: 'order_123',
  type: 'setup',
  dashclicks: userRoles,
  userId: 'user_456',
});

Managing Work Summaries

await addWorkSummary({
  orderId: 'order_123',
  summary: 'Completed initial setup phase',
  attachments: ['file1.pdf', 'file2.jpg'],
  dashclicks: userRoles,
});

Processing Approvals

await addApproval({
  requestId: 'req_123',
  approvalType: 'setup_completion',
  reviewers: ['manager_1', 'lead_2'],
  dashclicks: userRoles,
});

⚠️ Important Notes

• Request Types: Different request types have specific validation and routing rules
• Team Assignment: Automatic team assignment based on request type and workload
• Approval Hierarchies: Complex approval workflows may require multiple stages
• Communication Threading: All request communications maintain proper threading
• File Management: Attachments require proper storage and access control
• Activity Tracking: All operations generate comprehensive audit trail entries
• Role Dependencies: Operations require appropriate PROJECT_ROLES permissions