dt-common-device 1.3.0 → 2.0.0

package/src/device/local/models/Issue.model.ts

@@ -0,0 +1,350 @@
+import mongoose, { Schema, Model } from "mongoose";
+import {
+  IssuesCategory,
+  EntityType,
+  IssueStatus,
+  IssuePriority,
+  IssueComment,
+  IssueDocument as IIssueDocument,
+  CreateIssueData,
+  UpdateIssueData,
+  AddCommentData,
+} from "../../../types/issue.types";
+
+// Comment sub-schema
+const CommentSchema = new Schema<IssueComment>(
+  {
+    id: { type: String, required: true },
+    userId: { type: String, required: true },
+    content: { type: String, required: true },
+    createdAt: { type: Date, default: Date.now },
+    updatedAt: { type: Date },
+  },
+  { _id: false }
+);
+
+// Interface for instance methods
+interface IIssueMethods {
+  addComment(commentData: AddCommentData): void;
+  updateComment(commentId: string, content: string, userId: string): boolean;
+  removeComment(commentId: string): boolean;
+  resolve(resolvedBy: string): void;
+  reopen(updatedBy: string): void;
+  assign(userId: string, assignedBy: string): void;
+  unassign(unassignedBy: string): void;
+}
+
+// Interface for static methods
+interface IIssueModel extends Model<IIssueDocument, {}, IIssueMethods> {
+  findByProperty(
+    propertyId: string,
+    includeDeleted?: boolean
+  ): Promise<IIssueDocument[]>;
+  findByAssignee(
+    assignedTo: string,
+    includeDeleted?: boolean
+  ): Promise<IIssueDocument[]>;
+  findByEntity(
+    entityId: string,
+    entityType: EntityType,
+    includeDeleted?: boolean
+  ): Promise<IIssueDocument[]>;
+  findByStatus(
+    status: IssueStatus,
+    includeDeleted?: boolean
+  ): Promise<IIssueDocument[]>;
+  findByPriority(
+    priority: IssuePriority,
+    includeDeleted?: boolean
+  ): Promise<IIssueDocument[]>;
+  findOverdue(includeDeleted?: boolean): Promise<IIssueDocument[]>;
+  findUpcoming(
+    days?: number,
+    includeDeleted?: boolean
+  ): Promise<IIssueDocument[]>;
+}
+
+// Main Issue schema
+const IssueSchema = new Schema<IIssueDocument, IIssueModel, IIssueMethods>(
+  {
+    category: {
+      type: String,
+      enum: Object.values(IssuesCategory),
+      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,
+    },
+    status: {
+      type: String,
+      enum: Object.values(IssueStatus),
+      default: IssueStatus.PENDING,
+      index: true,
+    },
+    priority: {
+      type: String,
+      enum: Object.values(IssuePriority),
+      default: IssuePriority.MEDIUM,
+    },
+    assignedTo: {
+      type: String,
+      index: true,
+    },
+    createdBy: {
+      type: String,
+      required: true,
+    },
+    updatedBy: {
+      type: String,
+    },
+    isDeleted: {
+      type: Boolean,
+      default: false,
+    },
+    createdAt: {
+      type: Date,
+      default: Date.now,
+    },
+    updatedAt: {
+      type: Date,
+      default: Date.now,
+    },
+    resolvedAt: {
+      type: Date,
+    },
+    dueDate: {
+      type: Date,
+    },
+    comments: {
+      type: [CommentSchema],
+      default: [],
+    },
+  },
+  {
+    timestamps: true,
+    collection: "dt_issues",
+  }
+);
+
+IssueSchema.index({ propertyId: 1, status: 1 });
+IssueSchema.index({ assignedTo: 1, status: 1 });
+IssueSchema.index({ entityId: 1, entityType: 1 });
+
+// Pre-save middleware to update the updatedAt field
+IssueSchema.pre("save", function (next) {
+  this.updatedAt = new Date();
+  next();
+});
+
+// Pre-update middleware to update the updatedAt field
+IssueSchema.pre(
+  ["updateOne", "findOneAndUpdate", "updateMany"],
+  function (next) {
+    this.set({ updatedAt: new Date() });
+    next();
+  }
+);
+
+// Instance methods
+IssueSchema.methods.addComment = function (commentData: AddCommentData): void {
+  const comment: IssueComment = {
+    id: new mongoose.Types.ObjectId().toString(),
+    userId: commentData.userId,
+    content: commentData.content,
+    createdAt: new Date(),
+  };
+
+  if (!this.comments) {
+    this.comments = [];
+  }
+
+  this.comments.push(comment);
+};
+
+IssueSchema.methods.updateComment = function (
+  commentId: string,
+  content: string,
+  userId: string
+): boolean {
+  if (!this.comments) return false;
+
+  const comment = this.comments.find((c: IssueComment) => c.id === commentId);
+  if (comment) {
+    comment.content = content;
+    comment.updatedAt = new Date();
+    return true;
+  }
+  return false;
+};
+
+IssueSchema.methods.removeComment = function (commentId: string): boolean {
+  if (!this.comments) return false;
+
+  const initialLength = this.comments.length;
+  this.comments = this.comments.filter((c: IssueComment) => c.id !== commentId);
+  return this.comments.length < initialLength;
+};
+
+IssueSchema.methods.resolve = function (resolvedBy: string): void {
+  this.status = IssueStatus.RESOLVED;
+  this.resolvedAt = new Date();
+  this.updatedBy = resolvedBy;
+};
+
+IssueSchema.methods.reopen = function (updatedBy: string): void {
+  this.status = IssueStatus.PENDING;
+  this.resolvedAt = undefined;
+  this.updatedBy = updatedBy;
+};
+
+IssueSchema.methods.assign = function (
+  userId: string,
+  assignedBy: string
+): void {
+  this.assignedTo = userId;
+  this.updatedBy = assignedBy;
+};
+
+IssueSchema.methods.unassign = function (unassignedBy: string): void {
+  this.assignedTo = undefined;
+  this.updatedBy = unassignedBy;
+};
+
+// Static methods
+IssueSchema.statics.findByProperty = function (
+  propertyId: string,
+  includeDeleted = false
+) {
+  const query: any = { propertyId };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ createdAt: -1 });
+};
+
+IssueSchema.statics.findByAssignee = function (
+  assignedTo: string,
+  includeDeleted = false
+) {
+  const query: any = { assignedTo };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ priority: -1, createdAt: -1 });
+};
+
+IssueSchema.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 });
+};
+
+IssueSchema.statics.findByStatus = function (
+  status: IssueStatus,
+  includeDeleted = false
+) {
+  const query: any = { status };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ priority: -1, createdAt: -1 });
+};
+
+IssueSchema.statics.findByPriority = function (
+  priority: IssuePriority,
+  includeDeleted = false
+) {
+  const query: any = { priority };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ createdAt: -1 });
+};
+
+IssueSchema.statics.findOverdue = function (includeDeleted = false) {
+  const query: any = {
+    dueDate: { $lt: new Date() },
+    status: {
+      $nin: [IssueStatus.RESOLVED, IssueStatus.CLOSED, IssueStatus.CANCELLED],
+    },
+  };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ dueDate: 1 });
+};
+
+IssueSchema.statics.findUpcoming = function (
+  days: number = 7,
+  includeDeleted = false
+) {
+  const futureDate = new Date();
+  futureDate.setDate(futureDate.getDate() + days);
+
+  const query: any = {
+    dueDate: { $gte: new Date(), $lte: futureDate },
+    status: {
+      $nin: [IssueStatus.RESOLVED, IssueStatus.CLOSED, IssueStatus.CANCELLED],
+    },
+  };
+  if (!includeDeleted) {
+    query.isDeleted = false;
+  }
+  return this.find(query).sort({ dueDate: 1 });
+};
+
+// Virtual for soft delete
+IssueSchema.virtual("isActive").get(function () {
+  return !this.isDeleted;
+});
+
+// Ensure virtuals are serialized
+IssueSchema.set("toJSON", { virtuals: true });
+IssueSchema.set("toObject", { virtuals: true });
+
+// Create and export the model
+export const IssueModel = mongoose.model<IIssueDocument, IIssueModel>(
+  "Issue",
+  IssueSchema
+);
+
+// Export the schema for potential reuse
+export { IssueSchema };
+
+// Export types for external use
+export type {
+  IIssueDocument,
+  CreateIssueData,
+  UpdateIssueData,
+  AddCommentData,
+  IIssueMethods,
+  IIssueModel,
+};

package/src/device/local/models/README.md

@@ -0,0 +1,312 @@
+# 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)