dt-common-device 3.0.9 → 3.0.11

package/src/docs/Alert.model.md

@@ -1,319 +0,0 @@
-# Alert Model Documentation
-
-This document describes the Mongoose implementation of the Alert model, which was converted from a Prisma schema to provide comprehensive alert management functionality.
-
-## Overview
-
-The Alert model provides a complete alert management system with the following features:
-
-- **Alert Management**: Create, read, update, and delete alerts
-- **Severity Levels**: Assign severity levels (INFO, LOW, MEDIUM, HIGH, CRITICAL)
-- **Categories**: Categorize alerts (DEVICE_OFFLINE, DEVICE_BATTERY_LOW, etc.)
-- **Entity References**: Link alerts to various entities (DEVICE, HUB, etc.)
-- **Read Status**: Track read/unread status
-- **Active Status**: Activate/deactivate alerts
-- **Snooze Functionality**: Temporarily suppress alerts until a specified date
-- **Soft Deletion**: Support for soft deletion with recovery capability
-- **Statistics**: Comprehensive alert statistics and reporting
-
-## Model Structure
-
-### Core Fields
-
-| Field         | Type          | Required | Description                           |
-| ------------- | ------------- | -------- | ------------------------------------- |
-| `_id`         | String        | Yes      | MongoDB ObjectId (auto-generated)     |
-| `category`    | AlertCategory | Yes      | Alert category (DEVICE_OFFLINE, etc.) |
-| `propertyId`  | String        | Yes      | Property UUID reference               |
-| `title`       | String        | Yes      | Alert title                           |
-| `description` | String        | Yes      | Alert description                     |
-| `entityId`    | String        | No       | Generic entity reference UUID         |
-| `entityType`  | EntityType    | Yes      | Entity type (DEVICE, HUB, etc.)       |
-| `severity`    | AlertSeverity | Yes      | Alert severity (default: MEDIUM)      |
-| `isRead`      | Boolean       | Yes      | Read status flag (default: false)     |
-| `isActive`    | Boolean       | Yes      | Active status flag (default: true)    |
-| `isDeleted`   | Boolean       | Yes      | Soft deletion flag (default: false)   |
-| `snoozeUntil` | Date          | No       | Snooze expiration date                |
-| `createdBy`   | String        | No       | User UUID who created the alert       |
-| `updatedBy`   | String        | No       | User UUID who last updated            |
-| `createdAt`   | Date          | Yes      | Creation timestamp                    |
-| `updatedAt`   | Date          | Yes      | Last update timestamp                 |
-
-### Enums
-
-#### AlertCategory
-
-```typescript
-enum AlertCategory {
-  READINESS = "READINESS",
-  OPERATIONS = "OPERATIONS",
-  SECURITY = "SECURITY",
-  ENERGY = "ENERGY",
-  OTHER = "OTHER",
-}
-```
-
-#### AlertSeverity
-
-```typescript
-enum AlertSeverity {
-  INFO = "INFO",
-  LOW = "LOW",
-  MEDIUM = "MEDIUM",
-  HIGH = "HIGH",
-  CRITICAL = "CRITICAL",
-}
-```
-
-#### EntityType
-
-```typescript
-enum EntityType {
-  DEVICE = "DEVICE",
-  COLLECTION = "COLLECTION",
-  USER = "USER",
-  INTEGRATION = "INTEGRATION",
-  PROPERTY = "PROPERTY",
-  HUB = "HUB",
-  SCHEDULE = "SCHEDULE",
-  ALERT = "ALERT",
-  OTHER = "OTHER",
-}
-```
-
-## Usage Examples
-
-### Basic CRUD Operations
-
-#### Creating an Alert
-
-```typescript
-import { AlertService } from "../services/Alert.service";
-import {
-  AlertCategory,
-  EntityType,
-  AlertSeverity,
-} from "../../../types/alert.types";
-
-const alertService = new AlertService();
-
-const newAlert = await alertService.createAlert({
-  category: AlertCategory.READINESS,
-  propertyId: "property-uuid",
-  title: "Device Offline",
-  description: "Device has been offline for more than 5 minutes",
-  entityId: "device-uuid",
-  entityType: EntityType.DEVICE,
-  severity: AlertSeverity.HIGH,
-  createdBy: "user-uuid",
-});
-```
-
-#### Getting Alerts
-
-```typescript
-// Get all alerts for a property
-const propertyAlerts = await alertService.getAlertsByProperty("property-uuid");
-
-// Get alerts by severity
-const criticalAlerts = await alertService.getAlertsBySeverity(
-  AlertSeverity.CRITICAL
-);
-
-// Get unread alerts
-const unreadAlerts = await alertService.getUnreadAlerts();
-
-// Get alerts with filters
-const filteredAlerts = await alertService.getAlerts({
-  propertyId: "property-uuid",
-  severity: AlertSeverity.HIGH,
-  isActive: true,
-  limit: 10,
-  skip: 0,
-});
-```
-
-#### Updating an Alert
-
-```typescript
-// Mark alert as read
-await alertService.markAsRead(alertId, "user-uuid");
-
-// Snooze alert for 24 hours
-const snoozeUntil = new Date(Date.now() + 24 * 60 * 60 * 1000);
-await alertService.snoozeAlert(alertId, snoozeUntil, "user-uuid");
-
-// Deactivate alert
-await alertService.deactivateAlert(alertId, "user-uuid");
-
-// Update alert details
-await alertService.updateAlert(alertId, {
-  title: "Updated Alert Title",
-  description: "Updated description",
-  updatedBy: "user-uuid",
-});
-```
-
-### Advanced Operations
-
-#### Snooze Management
-
-```typescript
-// Snooze an alert until tomorrow
-const tomorrow = new Date();
-tomorrow.setDate(tomorrow.getDate() + 1);
-await alertService.snoozeAlert(alertId, tomorrow, "user-uuid");
-
-// Remove snooze
-await alertService.unsnoozeAlert(alertId, "user-uuid");
-
-// Get expired snooze alerts
-const expiredAlerts = await alertService.getExpiredSnoozeAlerts();
-```
-
-#### Alert Statistics
-
-```typescript
-// Get overall statistics
-const stats = await alertService.getAlertStatistics();
-
-// Get property-specific statistics
-const propertyStats = await alertService.getAlertStatistics("property-uuid");
-
-console.log(`Total alerts: ${stats.total}`);
-console.log(`Active alerts: ${stats.active}`);
-console.log(`Unread alerts: ${stats.unread}`);
-console.log(`Snoozed alerts: ${stats.snoozed}`);
-console.log(`Critical alerts: ${stats.bySeverity.CRITICAL}`);
-console.log(`Readiness alerts: ${stats.byCategory.READINESS}`);
-```
-
-#### Repository Pattern Usage
-
-For more advanced data access patterns, use the repository:
-
-```typescript
-import { AlertRepository } from "../repository/Alert.repository";
-
-const alertRepo = new AlertRepository();
-
-// Bulk operations
-await alertRepo.bulkUpdate(["alert1", "alert2"], {
-  isRead: true,
-  updatedBy: "user-uuid",
-});
-
-// Count alerts
-const count = await alertRepo.count({
-  propertyId: "property-uuid",
-  severity: AlertSeverity.HIGH,
-});
-
-// Advanced filtering with sorting
-const alerts = await alertRepo.findAll({
-  propertyId: "property-uuid",
-  sort: { severity: -1, createdAt: -1 },
-  limit: 50,
-});
-```
-
-## Business Rules
-
-### Severity Assignment
-
-Default severity is automatically determined based on the alert category:
-
-| Category   | Default Severity |
-| ---------- | ---------------- |
-| READINESS  | HIGH             |
-| OPERATIONS | MEDIUM           |
-| SECURITY   | CRITICAL         |
-| ENERGY     | MEDIUM           |
-| OTHER      | LOW              |
-
-### Snooze Validation
-
-- Snooze dates must be in the future
-- Attempting to set a past snooze date will throw an error
-- Expired snooze alerts are automatically detected
-
-### Critical Alert Protection
-
-- Critical alerts cannot be deleted (soft or hard delete)
-- Attempting to delete a critical alert will throw an error
-
-### Monitoring and Logging
-
-The service automatically logs important events:
-
-- Unread alerts count
-- Critical alerts count
-- High severity alerts count
-- Expired snooze alerts
-
-## Indexes
-
-The model includes the following indexes for optimal performance:
-
-- `propertyId` (single field)
-- `entityId` (single field)
-- `entityType` (single field)
-- `severity` (single field)
-- `isRead` (single field)
-- `isActive` (single field)
-- `createdAt` (single field)
-- `{ propertyId: 1, isActive: 1, isRead: 1 }` (compound)
-- `{ entityId: 1, entityType: 1 }` (compound)
-
-## Middleware
-
-The model includes pre-save and pre-update middleware that automatically:
-
-- Updates the `updatedAt` timestamp on save
-- Updates the `updatedAt` timestamp on update operations
-
-## Virtual Fields
-
-- `isSnoozed`: Returns `true` if the alert is currently snoozed
-- `isSnoozeExpired`: Returns `true` if the alert snooze has expired
-
-## Error Handling
-
-All operations include comprehensive error handling with descriptive error messages. The service and repository layers wrap database operations in try-catch blocks and provide meaningful error messages.
-
-Common error scenarios:
-
-- **Invalid snooze date**: "Snooze date must be in the future"
-- **Critical alert deletion**: "Cannot delete critical alerts"
-- **Missing required fields**: "Alert title must be at least 3 characters long"
-- **Invalid filters**: "Limit must be between 1 and 100"
-
-## Best Practices
-
-1. **Use Appropriate Severity**: Choose severity levels based on business impact
-2. **Set Meaningful Titles**: Use descriptive titles for better alert identification
-3. **Use Snooze Wisely**: Only snooze alerts when appropriate, not as a permanent solution
-4. **Monitor Statistics**: Regularly check alert statistics for insights
-5. **Handle Expired Snoozes**: Implement processes to handle expired snooze alerts
-6. **Use Categories**: Properly categorize alerts for better organization
-7. **Set Entity References**: Link alerts to specific entities when possible
-8. **Use Soft Deletion**: Always use soft deletion for audit trails
-9. **Validate Input**: Always validate alert data before creation
-10. **Monitor Critical Alerts**: Implement immediate notification for critical alerts
-
-## Migration from Prisma
-
-This Mongoose model maintains full compatibility with the original Prisma schema:
-
-- All fields and types are preserved
-- Indexes match the Prisma schema
-- Relationships are maintained through foreign key references
-- Collection name matches Prisma (`dt_alerts`)
-
-The model provides additional features beyond the Prisma schema:
-
-- Instance methods for common operations
-- Static methods for complex queries
-- Virtual fields for computed properties
-- Comprehensive business logic validation
-- Built-in monitoring and logging

package/src/docs/Alerts&IssuesModel.md

@@ -1,312 +0,0 @@
-# Local Device Models
-
-This directory contains Mongoose models for local device management, implementing Prisma schema compatibility.
-
-## Models
-
-### Alert Model (`Alert.model.ts`)
-
-A comprehensive alert management system with snooze functionality, severity levels, and read status tracking.
-
-**📖 [Detailed Documentation](./Alert.model.md)**
-
-#### Key Features
-
-- **Severity Management**: INFO, LOW, MEDIUM, HIGH, CRITICAL levels
-- **Snooze Functionality**: Temporarily suppress alerts until specified date
-- **Read Status**: Track read/unread status with automatic logging
-- **Category System**: READINESS, OPERATIONS, SECURITY, ENERGY, OTHER
-- **Entity References**: Link alerts to devices, hubs, and other entities
-- **Statistics**: Comprehensive alert statistics and monitoring
-
-#### Quick Example
-
-```typescript
-import { AlertService } from "../services/Alert.service";
-import {
-  AlertCategory,
-  AlertSeverity,
-  EntityType,
-} from "../../../types/alert.types";
-
-const alertService = new AlertService();
-
-// Create a critical alert
-const alert = await alertService.createAlert({
-  category: AlertCategory.READINESS,
-  propertyId: "property-123",
-  title: "Device Offline",
-  description: "Device has been offline for more than 5 minutes",
-  entityId: "device-456",
-  entityType: EntityType.DEVICE,
-  severity: AlertSeverity.HIGH,
-  createdBy: "user-789",
-});
-
-// Snooze for 24 hours
-await alertService.snoozeAlert(
-  alert._id,
-  new Date(Date.now() + 24 * 60 * 60 * 1000),
-  "user-789"
-);
-```
-
-### Issue Model (`Issue.model.ts`)
-
-A comprehensive issue tracking system with assignment, comments, and resolution workflow.
-
-**📖 [Detailed Documentation](./Issue.model.md)**
-
-#### Key Features
-
-- **Status Workflow**: OPEN → IN_PROGRESS → RESOLVED → CLOSED
-- **Assignment System**: Assign issues to users with validation
-- **Comment System**: Add, update, and remove comments on issues
-- **Priority Management**: LOW, MEDIUM, HIGH, CRITICAL with overdue calculation
-- **Due Date Tracking**: Set and monitor due dates with automatic overdue detection
-- **Search & Statistics**: Full-text search and comprehensive reporting
-
-#### Quick Example
-
-```typescript
-import { IssueService } from "../services/Issue.service";
-import {
-  IssueCategory,
-  IssuePriority,
-  EntityType,
-} from "../../../types/issue.types";
-
-const issueService = new IssueService();
-
-// Create an issue
-const issue = await issueService.createIssue({
-  category: IssueCategory.READINESS,
-  propertyId: "property-123",
-  title: "Device Connection Issue",
-  description: "Device is not responding to commands",
-  entityId: "device-456",
-  entityType: EntityType.DEVICE,
-  priority: IssuePriority.HIGH,
-  createdBy: "user-789",
-  dueDate: new Date("2024-01-15"),
-});
-
-// Assign and start progress
-await issueService.assignIssue(issue._id, "tech-user-123", "user-789");
-await issueService.updateIssue(issue._id, {
-  status: IssueStatus.IN_PROGRESS,
-  updatedBy: "tech-user-123",
-});
-
-// Add comment
-await issueService.addComment(issue._id, {
-  userId: "tech-user-123",
-  content: "Investigating the connection issue",
-});
-```
-
-## Architecture
-
-### Clean Architecture Pattern
-
-Both models follow a clean architecture pattern with clear separation of concerns:
-
-```
-Service Layer (Business Logic)
-    ↓
-Repository Layer (Data Access)
-    ↓
-Model Layer (Data Structure)
-```
-
-#### Service Layer
-
-- **Business Logic**: Validation, business rules, workflow management
-- **Error Handling**: Comprehensive error messages and validation
-- **Monitoring**: Built-in logging for important events
-- **Repository Usage**: All data access through repository layer
-
-#### Repository Layer
-
-- **Data Access**: CRUD operations with error handling
-- **Query Optimization**: Efficient filtering and sorting
-- **Bulk Operations**: Support for bulk updates and deletes
-- **Statistics**: Aggregation and reporting functions
-
-#### Model Layer
-
-- **Schema Definition**: Mongoose schemas with validation
-- **Instance Methods**: Common operations on individual documents
-- **Static Methods**: Complex queries and filtering
-- **Virtual Fields**: Computed properties
-- **Middleware**: Pre/post save hooks for automation
-
-## Common Patterns
-
-### Business Rules Implementation
-
-Both models implement business rules in the service layer:
-
-```typescript
-// Alert Service - Severity Assignment
-private determineDefaultSeverity(category: AlertCategory): AlertSeverity {
-  const categorySeverities: Record<AlertCategory, AlertSeverity> = {
-    [AlertCategory.READINESS]: AlertSeverity.HIGH,
-    [AlertCategory.SECURITY]: AlertSeverity.CRITICAL,
-    // ... more mappings
-  };
-  return categorySeverities[category] || AlertSeverity.MEDIUM;
-}
-
-// Issue Service - Status Transitions
-private validateStatusTransition(currentStatus: IssueStatus, newStatus: IssueStatus): void {
-  const validTransitions = {
-    [IssueStatus.OPEN]: [IssueStatus.IN_PROGRESS],
-    [IssueStatus.IN_PROGRESS]: [IssueStatus.RESOLVED],
-    [IssueStatus.RESOLVED]: [IssueStatus.CLOSED, IssueStatus.OPEN],
-    // ... more transitions
-  };
-  // Validation logic
-}
-```
-
-### Error Handling
-
-Consistent error handling across all layers:
-
-```typescript
-// Repository Layer
-try {
-  return await AlertModel.findById(id);
-} catch (error) {
-  throw new Error(
-    `Failed to find alert by ID: ${
-      error instanceof Error ? error.message : "Unknown error"
-    }`
-  );
-}
-
-// Service Layer
-if (!id) {
-  throw new Error("Alert ID is required");
-}
-```
-
-### Monitoring and Logging
-
-Built-in monitoring for important events:
-
-```typescript
-// Alert monitoring
-if (stats.bySeverity[AlertSeverity.CRITICAL] > 0) {
-  console.error(
-    `Alert: ${
-      stats.bySeverity[AlertSeverity.CRITICAL]
-    } critical alerts require immediate attention`
-  );
-}
-
-// Issue monitoring
-if (stats.overdue > 0) {
-  console.warn(`Alert: ${stats.overdue} overdue issues require attention`);
-}
-```
-
-## Best Practices
-
-### 1. **Use Service Layer for Business Logic**
-
-Always use the service layer for operations that involve business rules, validation, or workflow management.
-
-### 2. **Use Repository Layer for Data Access**
-
-Use the repository layer for direct data access operations, bulk operations, and complex queries.
-
-### 3. **Validate Input Data**
-
-Always validate input data before processing to ensure data integrity.
-
-### 4. **Handle Errors Gracefully**
-
-Use try-catch blocks and provide meaningful error messages for better debugging.
-
-### 5. **Use Soft Deletion**
-
-Always use soft deletion unless explicitly required to permanently remove data.
-
-### 6. **Monitor Important Events**
-
-Implement logging for critical events like overdue issues, critical alerts, and status changes.
-
-### 7. **Use TypeScript Interfaces**
-
-Leverage TypeScript interfaces for type safety and better development experience.
-
-### 8. **Follow Naming Conventions**
-
-Use consistent naming conventions across all layers for better maintainability.
-
-### 9. **Document Business Rules**
-
-Clearly document business rules and validation logic for future reference.
-
-### 10. **Test Business Logic**
-
-Write tests for business logic to ensure rules are correctly implemented.
-
-## Migration from Prisma
-
-Both models maintain full compatibility with their original Prisma schemas:
-
-- ✅ All fields and types preserved
-- ✅ Indexes match Prisma schema
-- ✅ Relationships maintained through foreign key references
-- ✅ Collection names match Prisma (`dt_alerts`, `dt_issues`)
-
-Additional features beyond Prisma:
-
-- ✅ Instance methods for common operations
-- ✅ Static methods for complex queries
-- ✅ Virtual fields for computed properties
-- ✅ Comprehensive business logic validation
-- ✅ Built-in monitoring and logging
-- ✅ Comment management system (Issues)
-- ✅ Snooze functionality (Alerts)
-- ✅ Overdue calculation logic (Issues)
-
-## Quick Start
-
-1. **Import Services**:
-
-   ```typescript
-   import { AlertService, IssueService } from "../services";
-   ```
-
-2. **Create Instances**:
-
-   ```typescript
-   const alertService = new AlertService();
-   const issueService = new IssueService();
-   ```
-
-3. **Use Business Logic**:
-
-   ```typescript
-   // Create alert with automatic severity assignment
-   const alert = await alertService.createAlert(alertData);
-
-   // Create issue with workflow validation
-   const issue = await issueService.createIssue(issueData);
-   ```
-
-4. **Monitor and Report**:
-   ```typescript
-   // Get statistics
-   const alertStats = await alertService.getAlertStatistics();
-   const issueStats = await issueService.getIssueStatistics();
-   ```
-
-For detailed usage examples and advanced features, refer to the individual model documentation:
-
-- [Alert Model Documentation](./Alert.model.md)
-- [Issue Model Documentation](./Issue.model.md)