dt-common-device 1.3.0 → 2.0.0

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

@@ -0,0 +1,386 @@
+# Issue Model Documentation
+
+This document describes the Mongoose implementation of the Issue model, which was converted from a Prisma schema to provide comprehensive issue tracking functionality.
+
+## Overview
+
+The Issue model provides a complete issue tracking system with the following features:
+
+- **Issue Management**: Create, read, update, and delete issues
+- **Status Tracking**: Track issue status from OPEN to CLOSED
+- **Priority Levels**: Assign priority levels (LOW, MEDIUM, HIGH, CRITICAL)
+- **Categories**: Categorize issues (TECHNICAL, OPERATIONAL, etc.)
+- **Entity References**: Link issues to various entities (DEVICE, HUB, etc.)
+- **Assignment**: Assign issues to users for resolution
+- **Comments**: Add, update, and remove comments on issues
+- **Due Dates**: Set and track due dates for issues
+- **Soft Deletion**: Support for soft deletion with recovery capability
+- **Search**: Full-text search across issue titles and descriptions
+- **Statistics**: Comprehensive issue statistics and reporting
+
+## Model Structure
+
+### Core Fields
+
+| Field         | Type           | Required | Description                                   |
+| ------------- | -------------- | -------- | --------------------------------------------- |
+| `_id`         | String         | Yes      | MongoDB ObjectId (auto-generated)             |
+| `category`    | IssueCategory  | Yes      | Issue category (TECHNICAL, OPERATIONAL, etc.) |
+| `propertyId`  | String         | Yes      | Property UUID reference                       |
+| `title`       | String         | Yes      | Issue title                                   |
+| `description` | String         | Yes      | Issue description                             |
+| `entityId`    | String         | No       | Generic entity reference UUID                 |
+| `entityType`  | EntityType     | Yes      | Entity type (DEVICE, HUB, etc.)               |
+| `priority`    | IssuePriority  | Yes      | Issue priority (default: MEDIUM)              |
+| `status`      | IssueStatus    | Yes      | Issue status (default: OPEN)                  |
+| `assignedTo`  | String         | No       | User UUID assigned to resolve                 |
+| `resolvedBy`  | String         | No       | User UUID who resolved the issue              |
+| `resolvedAt`  | Date           | No       | Resolution timestamp                          |
+| `dueDate`     | Date           | No       | Due date for resolution                       |
+| `isDeleted`   | Boolean        | Yes      | Soft deletion flag (default: false)           |
+| `createdBy`   | String         | Yes      | User UUID who created the issue               |
+| `updatedBy`   | String         | No       | User UUID who last updated                    |
+| `createdAt`   | Date           | Yes      | Creation timestamp                            |
+| `updatedAt`   | Date           | Yes      | Last update timestamp                         |
+| `comments`    | IssueComment[] | No       | Array of comments                             |
+
+### Enums
+
+#### IssueCategory
+
+```typescript
+enum IssueCategory {
+  READINESS = "READINESS",
+  OPERATIONS = "OPERATIONS",
+  SECURITY = "SECURITY",
+  ENERGY = "ENERGY",
+  OTHER = "OTHER",
+}
+```
+
+#### IssuePriority
+
+```typescript
+enum IssuePriority {
+  LOW = "LOW",
+  MEDIUM = "MEDIUM",
+  HIGH = "HIGH",
+  CRITICAL = "CRITICAL",
+}
+```
+
+#### IssueStatus
+
+```typescript
+enum IssueStatus {
+  OPEN = "OPEN",
+  IN_PROGRESS = "IN_PROGRESS",
+  RESOLVED = "RESOLVED",
+  CLOSED = "CLOSED",
+}
+```
+
+#### EntityType
+
+```typescript
+enum EntityType {
+  DEVICE = "DEVICE",
+  COLLECTION = "COLLECTION",
+  USER = "USER",
+  INTEGRATION = "INTEGRATION",
+  PROPERTY = "PROPERTY",
+  HUB = "HUB",
+  SCHEDULE = "SCHEDULE",
+  ALERT = "ALERT",
+  OTHER = "OTHER",
+}
+```
+
+### Comment Structure
+
+```typescript
+interface IssueComment {
+  id: string;
+  userId: string;
+  content: string;
+  createdAt: Date;
+  updatedAt?: Date;
+}
+```
+
+## Usage Examples
+
+### Basic CRUD Operations
+
+#### Creating an Issue
+
+```typescript
+import { IssueService } from "../services/Issue.service";
+import {
+  IssueCategory,
+  EntityType,
+  IssuePriority,
+} from "../../../types/issue.types";
+
+const issueService = new IssueService();
+
+const newIssue = await issueService.createIssue({
+  category: IssueCategory.READINESS,
+  propertyId: "property-uuid",
+  title: "Device connectivity issue",
+  description: "Device is not responding to commands",
+  entityId: "device-uuid",
+  entityType: EntityType.DEVICE,
+  priority: IssuePriority.HIGH,
+  createdBy: "user-uuid",
+  dueDate: new Date("2024-01-15"),
+});
+```
+
+#### Getting Issues
+
+```typescript
+// Get all issues for a property
+const propertyIssues = await issueService.getIssuesByProperty("property-uuid");
+
+// Get issues assigned to a user
+const assignedIssues = await issueService.getIssuesByAssignee("user-uuid");
+
+// Get issues by status
+const openIssues = await issueService.getIssuesByStatus(IssueStatus.OPEN);
+
+// Get issues with filters
+const filteredIssues = await issueService.getIssues({
+  propertyId: "property-uuid",
+  status: IssueStatus.IN_PROGRESS,
+  priority: IssuePriority.HIGH,
+  limit: 10,
+  skip: 0,
+});
+```
+
+#### Updating an Issue
+
+```typescript
+// Update issue status
+await issueService.updateIssue(issueId, {
+  status: IssueStatus.IN_PROGRESS,
+  updatedBy: "user-uuid",
+});
+
+// Assign issue to user
+await issueService.assignIssue(issueId, "assignee-uuid", "assigned-by-uuid");
+
+// Resolve issue
+await issueService.resolveIssue(
+  issueId,
+  "resolved-by-uuid",
+  "Issue resolved successfully"
+);
+
+// Close issue
+await issueService.closeIssue(issueId, "closed-by-uuid");
+```
+
+#### Adding Comments
+
+```typescript
+// Add a comment
+await issueService.addComment(issueId, {
+  userId: "user-uuid",
+  content: "Investigation in progress",
+});
+
+// Update a comment
+await issueService.updateComment(
+  issueId,
+  commentId,
+  "Updated content",
+  "user-uuid"
+);
+
+// Remove a comment
+await issueService.removeComment(issueId, commentId);
+```
+
+### Advanced Operations
+
+#### Search Issues
+
+```typescript
+// Search by text
+const searchResults = await issueService.searchIssues("connectivity", {
+  propertyId: "property-uuid",
+  limit: 20,
+});
+```
+
+#### Get Statistics
+
+```typescript
+// Get overall statistics
+const stats = await issueService.getIssueStatistics();
+
+// Get property-specific statistics
+const propertyStats = await issueService.getIssueStatistics("property-uuid");
+
+console.log(`Total issues: ${stats.total}`);
+console.log(`Open issues: ${stats.open}`);
+console.log(`Overdue issues: ${stats.overdue}`);
+console.log(`High priority: ${stats.byPriority.HIGH}`);
+console.log(`Readiness issues: ${stats.byCategory.READINESS}`);
+```
+
+#### Find Overdue Issues
+
+```typescript
+// Get all overdue issues
+const overdueIssues = await issueService.getOverdueIssues();
+
+// Get upcoming issues (due within 7 days)
+const upcomingIssues = await issueService.getUpcomingIssues(7);
+```
+
+#### Repository Pattern Usage
+
+For more advanced data access patterns, use the repository:
+
+```typescript
+import { IssueRepository } from "../repository/Issue.repository";
+
+const issueRepo = new IssueRepository();
+
+// Bulk operations
+await issueRepo.bulkUpdate(["issue1", "issue2"], {
+  status: IssueStatus.CLOSED,
+  updatedBy: "user-uuid",
+});
+
+// Count issues
+const count = await issueRepo.count({
+  propertyId: "property-uuid",
+  status: IssueStatus.OPEN,
+});
+
+// Advanced filtering with sorting
+const issues = await issueRepo.findAll({
+  propertyId: "property-uuid",
+  sort: { priority: -1, createdAt: -1 },
+  limit: 50,
+});
+```
+
+## Business Rules
+
+### Status Transitions
+
+Issues follow a specific status flow:
+
+1. **OPEN** → **IN_PROGRESS** (requires assignment)
+2. **IN_PROGRESS** → **RESOLVED** (requires resolution note)
+3. **RESOLVED** → **CLOSED** (final state)
+4. **RESOLVED** → **OPEN** (reopen allowed)
+5. **CLOSED** → **OPEN** (reopen allowed)
+
+### Assignment Requirements
+
+- Issues must be assigned before moving to IN_PROGRESS status
+- Only assigned issues can be moved to IN_PROGRESS
+- Unassigned issues remain in OPEN status
+
+### Resolution Requirements
+
+- Issues must have a resolution note when moved to RESOLVED status
+- Resolution automatically sets the `resolvedAt` timestamp
+- Resolution automatically sets the `resolvedBy` user
+
+### Overdue Calculation
+
+Issues are considered overdue based on priority:
+
+| Priority | Overdue After |
+| -------- | ------------- |
+| LOW      | 14 days       |
+| MEDIUM   | 7 days        |
+| HIGH     | 3 days        |
+| CRITICAL | 1 day         |
+
+### Priority Management
+
+- Priority can be changed at any time
+- Priority changes are logged for audit purposes
+- Critical priority issues get special handling
+
+## Indexes
+
+The model includes the following indexes for optimal performance:
+
+- `propertyId` (single field)
+- `assignedTo` (single field)
+- `entityId` (single field)
+- `entityType` (single field)
+- `status` (single field)
+- `priority` (single field)
+- `createdAt` (single field)
+- `{ propertyId: 1, status: 1, priority: 1 }` (compound)
+- `{ assignedTo: 1, status: 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
+- Validates status transitions
+- Validates assignment requirements
+
+## Virtual Fields
+
+- `isOverdue`: Returns `true` if the issue is overdue
+- `timeToResolution`: Calculates time to resolution (if resolved)
+- `isAssigned`: Returns `true` if the issue is assigned
+
+## 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 status transition**: "Cannot transition from OPEN to RESOLVED"
+- **Missing assignment**: "Issue must be assigned before moving to IN_PROGRESS"
+- **Missing resolution**: "Resolution note is required when resolving an issue"
+- **Invalid due date**: "Due date must be in the future"
+- **Missing required fields**: "Issue title must be at least 3 characters long"
+
+## Best Practices
+
+1. **Set Realistic Due Dates**: Set achievable due dates for better tracking
+2. **Use Appropriate Categories**: Properly categorize issues for better organization
+3. **Assign Issues Promptly**: Assign issues to appropriate users quickly
+4. **Add Meaningful Comments**: Use comments to track progress and communication
+5. **Monitor Overdue Issues**: Regularly check for overdue issues
+6. **Use Priority Wisely**: Don't overuse high/critical priority
+7. **Provide Resolution Notes**: Always include detailed resolution notes
+8. **Use Soft Deletion**: Always use soft deletion for audit trails
+9. **Validate Input**: Always validate issue data before creation
+10. **Monitor Statistics**: Regularly check issue statistics for insights
+
+## 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_issues`)
+
+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
+- Comment management system
+- Overdue calculation logic