dt-common-device 1.3.0 → 2.0.0

package/src/device/local/models/Alert.model.md

@@ -0,0 +1,319 @@
+# 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/device/local/models/Alert.model.ts

@@ -0,0 +1,283 @@
+import mongoose, { Schema, Model } from "mongoose";
+import {
+  AlertCategory,
+  AlertSeverity,
+  EntityType,
+  AlertDocument as IAlertDocument,
+  CreateAlertData,
+  UpdateAlertData,
+} from "../../../types/alert.types";
+
+// Interface for instance methods
+interface IAlertMethods {
+  markAsRead(updatedBy: string): void;
+  markAsUnread(updatedBy: string): void;
+  activate(updatedBy: string): void;
+  deactivate(updatedBy: string): void;
+  snooze(until: Date, updatedBy: string): void;
+  unsnooze(updatedBy: string): void;
+}
+
+// Interface for static methods
+interface IAlertModel extends Model<IAlertDocument, {}, IAlertMethods> {
+  findByProperty(
+    propertyId: string,
+    includeDeleted?: boolean
+  ): Promise<IAlertDocument[]>;
+  findByEntity(
+    entityId: string,
+    entityType: EntityType,
+    includeDeleted?: boolean
+  ): Promise<IAlertDocument[]>;
+  findByCategory(
+    category: AlertCategory,
+    includeDeleted?: boolean
+  ): Promise<IAlertDocument[]>;
+  findBySeverity(
+    severity: AlertSeverity,
+    includeDeleted?: boolean
+  ): Promise<IAlertDocument[]>;
+  findActive(includeDeleted?: boolean): Promise<IAlertDocument[]>;
+  findUnread(includeDeleted?: boolean): Promise<IAlertDocument[]>;
+  findSnoozed(includeDeleted?: boolean): Promise<IAlertDocument[]>;
+  findExpiredSnooze(includeDeleted?: boolean): Promise<IAlertDocument[]>;
+}
+
+// Main Alert schema
+const AlertSchema = new Schema<IAlertDocument, IAlertModel, IAlertMethods>(
+  {
+    category: {
+      type: String,
+      enum: Object.values(AlertCategory),
+      required: true,
+    },
+    propertyId: {
+      type: String,
+      required: true,
+      index: true,
+    },
+    title: {
+      type: String,
+      required: true,
+      trim: true,
+    },
+    description: {
+      type: String,
+      required: true,
+      trim: true,
+    },
+    entityId: {
+      type: String,
+      index: true,
+    },
+    entityType: {
+      type: String,
+      enum: Object.values(EntityType),
+      required: true,
+      index: true,
+    },
+    severity: {
+      type: String,
+      enum: Object.values(AlertSeverity),
+      default: AlertSeverity.MEDIUM,
+    },
+    isRead: {
+      type: Boolean,
+      default: false,
+      index: true,
+    },
+    isActive: {
+      type: Boolean,
+      default: true,
+      index: true,
+    },
+    isDeleted: {
+      type: Boolean,
+      default: false,
+    },
+    snoozeUntil: {
+      type: Date,
+    },
+    createdBy: {
+      type: String,
+    },
+    updatedBy: {
+      type: String,
+    },
+    createdAt: {
+      type: Date,
+      default: Date.now,
+    },
+    updatedAt: {
+      type: Date,
+      default: Date.now,
+    },
+  },
+  {
+    timestamps: true,
+    collection: "dt_alerts",
+  }
+);
+
+// Compound indexes to match Prisma schema
+AlertSchema.index({ propertyId: 1, isActive: 1, isRead: 1 });
+AlertSchema.index({ entityId: 1, entityType: 1 });
+AlertSchema.index({ createdAt: 1 });
+
+// Pre-save middleware to update the updatedAt field
+AlertSchema.pre("save", function (next) {
+  this.updatedAt = new Date();
+  next();
+});
+
+// Pre-update middleware to update the updatedAt field
+AlertSchema.pre(
+  ["updateOne", "findOneAndUpdate", "updateMany"],
+  function (next) {
+    this.set({ updatedAt: new Date() });
+    next();
+  }
+);
+
+// Instance methods
+AlertSchema.methods.markAsRead = function (updatedBy: string): void {
+  this.isRead = true;
+  this.updatedBy = updatedBy;
+};
+
+AlertSchema.methods.markAsUnread = function (updatedBy: string): void {
+  this.isRead = false;
+  this.updatedBy = updatedBy;
+};
+
+AlertSchema.methods.activate = function (updatedBy: string): void {
+  this.isActive = true;
+  this.updatedBy = updatedBy;
+};
+
+AlertSchema.methods.deactivate = function (updatedBy: string): void {
+  this.isActive = false;
+  this.updatedBy = updatedBy;
+};
+
+AlertSchema.methods.snooze = function (until: Date, updatedBy: string): void {
+  this.snoozeUntil = until;
+  this.updatedBy = updatedBy;
+};
+
+AlertSchema.methods.unsnooze = function (updatedBy: string): void {
+  this.snoozeUntil = undefined;
+  this.updatedBy = updatedBy;
+};
+
+// Static methods
+AlertSchema.statics.findByProperty = function (
+  propertyId: string,
+  includeDeleted = false
+) {
+  const query: any = { propertyId };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ createdAt: -1 });
+};
+
+AlertSchema.statics.findByEntity = function (
+  entityId: string,
+  entityType: EntityType,
+  includeDeleted = false
+) {
+  const query: any = { entityId, entityType };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ createdAt: -1 });
+};
+
+AlertSchema.statics.findByCategory = function (
+  category: AlertCategory,
+  includeDeleted = false
+) {
+  const query: any = { category };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ createdAt: -1 });
+};
+
+AlertSchema.statics.findBySeverity = function (
+  severity: AlertSeverity,
+  includeDeleted = false
+) {
+  const query: any = { severity };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ severity: -1, createdAt: -1 });
+};
+
+AlertSchema.statics.findActive = function (includeDeleted = false) {
+  const query: any = { isActive: true };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ severity: -1, createdAt: -1 });
+};
+
+AlertSchema.statics.findUnread = function (includeDeleted = false) {
+  const query: any = { isRead: false };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ severity: -1, createdAt: -1 });
+};
+
+AlertSchema.statics.findSnoozed = function (includeDeleted = false) {
+  const query: any = { snoozeUntil: { $exists: true, $ne: null } };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ snoozeUntil: 1 });
+};
+
+AlertSchema.statics.findExpiredSnooze = function (includeDeleted = false) {
+  const query: any = {
+    snoozeUntil: { $lt: new Date() },
+    isActive: true,
+  };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ snoozeUntil: 1 });
+};
+
+// Virtual for snooze status
+AlertSchema.virtual("isSnoozed").get(function () {
+  return this.snoozeUntil && this.snoozeUntil > new Date();
+});
+
+AlertSchema.virtual("isSnoozeExpired").get(function () {
+  return this.snoozeUntil && this.snoozeUntil <= new Date();
+});
+
+// Ensure virtuals are serialized
+AlertSchema.set("toJSON", { virtuals: true });
+AlertSchema.set("toObject", { virtuals: true });
+
+// Create and export the model
+export const AlertModel = mongoose.model<IAlertDocument, IAlertModel>(
+  "Alert",
+  AlertSchema
+);
+
+// Export the schema for potential reuse
+export { AlertSchema };
+
+// Export types for external use
+export type {
+  IAlertDocument,
+  CreateAlertData,
+  UpdateAlertData,
+  IAlertMethods,
+  IAlertModel,
+};