rez_core 4.0.167 → 4.0.171

package/src/module/workflow-schedule/docs/CLAUDE_CODE_PROMPT.md

@@ -0,0 +1,362 @@
+# Prompt for Claude Code: Workflow Schedule Module Implementation
+
+## Project Context
+
+**Project Path**: `/Users/debrajdas/WORKSPACE/001_RZ/PROJECTS/ETHER/250218_nodejs_core`  
+**Framework**: NestJS with TypeORM  
+**Database**: MySQL  
+**Task**: Implement complete workflow schedule module with Bull queue
+
+---
+
+## Implementation Request
+
+I need you to implement a complete scheduled workflow system in my NestJS project. This will extend the existing workflow module to support time-based workflow execution using cron schedules.
+
+### Target Location
+Create all files in: `src/module/workflow-schedule/`
+
+---
+
+## Required Files and Implementation
+
+### 1. Module Structure
+
+Create the following directory structure:
+```
+src/module/workflow-schedule/
+├── workflow-schedule.module.ts
+├── workflow-schedule.service.ts
+├── workflow-schedule.controller.ts
+├── constants/
+│   └── schedule.constants.ts
+├── dto/
+│   ├── create-schedule.dto.ts
+│   ├── update-schedule.dto.ts
+│   └── get-execution-logs.dto.ts
+├── entities/
+│   ├── scheduled-workflow.entity.ts
+│   └── workflow-execution-log.entity.ts
+├── interfaces/
+│   └── schedule-job-data.interface.ts
+├── processors/
+│   └── schedule.processor.ts
+└── tests/
+    └── workflow-schedule.service.spec.ts
+```
+
+### 2. Database Migrations
+
+Create in: `src/migrations/`
+
+**Migration 1**: Add `workflow_type` column to workflows table
+- Column: `workflow_type ENUM('trigger', 'schedule') DEFAULT 'trigger'`
+
+**Migration 2**: Create `scheduled_workflows` table with:
+- id, workflow_id (FK), schedule_expression, timezone
+- is_active, last_executed_at, next_execution_at, execution_count
+- start_date, end_date, created_at, updated_at
+- Indexes: (next_execution_at, is_active), (workflow_id)
+
+**Migration 3**: Create `workflow_execution_logs` table with:
+- id, workflow_id (FK), execution_type, status
+- started_at, completed_at, records_processed, records_failed
+- error_message, job_id, execution_data (JSON)
+- Indexes: (workflow_id, status), (started_at), (execution_type)
+
+### 3. Configuration
+
+Create: `src/config/bull.config.ts`
+- Export `getBullConfig()` function returning BullModuleOptions
+- Read from env: REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_DB
+- Configure: retry strategy, job options, queue settings
+
+---
+
+## Detailed Requirements
+
+### Entities
+
+**scheduled-workflow.entity.ts**:
+- TypeORM entity for `scheduled_workflows` table
+- Relations: `@ManyToOne(() => Workflow)`
+- Proper column decorators with snake_case naming
+- Indexes using @Index decorator
+
+**workflow-execution-log.entity.ts**:
+- TypeORM entity for `workflow_execution_logs` table
+- Enums: ExecutionType (trigger/schedule/manual), ExecutionStatus (running/success/failed/partial_success)
+- Computed properties: `durationMs()`, `successRate()`
+
+### DTOs
+
+**create-schedule.dto.ts**:
+```typescript
+- workflowId: number (required)
+- scheduleExpression: string (required, cron format validation)
+- timezone: string (optional, IANA format, default: 'UTC')
+- startDate: string (optional, ISO date)
+- endDate: string (optional, ISO date)
+- isActive: boolean (optional, default: true)
+```
+
+**update-schedule.dto.ts**:
+- All fields optional from CreateScheduleDto
+
+**get-execution-logs.dto.ts**:
+```typescript
+- status: ExecutionStatus (optional)
+- executionType: ExecutionType (optional)
+- limit: number (optional, default: 50, max: 500)
+- offset: number (optional, default: 0)
+```
+
+Use `class-validator` decorators for all validation.
+
+### Service (workflow-schedule.service.ts)
+
+Implement these methods:
+
+1. **scheduleWorkflow(dto: CreateScheduleDto): Promise<ScheduledWorkflow>**
+   - Validate cron expression using cron-parser
+   - Validate timezone using moment-timezone
+   - Calculate next execution time
+   - Create schedule in database
+   - Add job to Bull queue if active
+
+2. **updateSchedule(id: number, dto: UpdateScheduleDto): Promise<ScheduledWorkflow>**
+   - Find schedule or throw NotFoundException
+   - Validate updates
+   - Recalculate next execution
+   - Update Bull queue job
+
+3. **deleteSchedule(id: number): Promise<void>**
+   - Remove from database
+   - Remove job from Bull queue
+
+4. **pauseSchedule(id: number): Promise<ScheduledWorkflow>**
+   - Set isActive = false
+   - Remove job from queue
+
+5. **resumeSchedule(id: number): Promise<ScheduledWorkflow>**
+   - Set isActive = true
+   - Recalculate next execution
+   - Add job back to queue
+
+6. **triggerSchedule(id: number): Promise<WorkflowExecutionLog>**
+   - Create execution log with type 'manual'
+   - Add high-priority job to queue
+
+7. **getExecutionLogs(scheduleId, query): Promise<{logs, total}>**
+   - Query with filters (status, executionType)
+   - Pagination (limit, offset)
+   - Order by startedAt DESC
+
+8. **getScheduledJobs(): Promise<ScheduledWorkflow[]>**
+   - Return all active schedules with relations
+
+9. **getScheduleById(id): Promise<ScheduledWorkflow>**
+   - Find with relations or throw NotFoundException
+
+### Controller (workflow-schedule.controller.ts)
+
+REST API endpoints with Swagger decorators:
+
+```
+POST   /workflow-schedule           - create()
+GET    /workflow-schedule           - getAll()
+GET    /workflow-schedule/:id       - getById()
+PUT    /workflow-schedule/:id       - update()
+DELETE /workflow-schedule/:id       - delete()
+POST   /workflow-schedule/:id/pause - pause()
+POST   /workflow-schedule/:id/resume - resume()
+POST   /workflow-schedule/:id/trigger - trigger()
+GET    /workflow-schedule/:id/logs  - getLogs()
+```
+
+Add @ApiTags, @ApiOperation, @ApiResponse decorators.
+
+### Processor (schedule.processor.ts)
+
+Bull queue processor with:
+
+**@Process() handleScheduledJob(job: Job<ScheduleJobData>)**:
+1. Create execution log (status: 'running')
+2. Verify schedule is still active and hasn't ended
+3. Get workflow configuration
+4. Query records matching workflow criteria
+5. Process in batches of 100 records
+6. Execute actions for each record:
+   - sendEmail(config, record)
+   - updateRecord(config, record)
+   - createTask(config, record)
+   - sendNotification(config, record)
+7. Handle template variables: `{{record.field}}`, `{{current_date}}`
+8. Update execution log with results
+9. Update schedule (last_executed_at, execution_count, next_execution_at)
+10. Schedule next job
+
+**Error handling**:
+- Try/catch around entire process
+- Log errors to execution log
+- Retry with exponential backoff (3 attempts)
+
+**Lifecycle hooks**:
+- @OnQueueActive() - Log job start
+- @OnQueueCompleted() - Log success
+- @OnQueueFailed() - Log failure
+
+### Constants (schedule.constants.ts)
+
+```typescript
+export const SCHEDULE_QUEUE_NAME = 'workflow-schedule';
+export const MAX_BATCH_SIZE = 100;
+export const EXECUTION_TIMEOUT_MS = 30 * 60 * 1000;
+
+export const DEFAULT_JOB_OPTIONS = {
+  attempts: 3,
+  backoff: { type: 'exponential', delay: 5000 },
+  removeOnComplete: false,
+  removeOnFail: false,
+};
+
+export const COMMON_CRON_EXPRESSIONS = {
+  EVERY_MINUTE: '* * * * *',
+  EVERY_HOUR: '0 * * * *',
+  EVERY_DAY_9AM: '0 9 * * *',
+  EVERY_MONDAY_9AM: '0 9 * * 1',
+  // ... etc
+};
+```
+
+### Interfaces (schedule-job-data.interface.ts)
+
+```typescript
+export interface ScheduleJobData {
+  scheduleId: number;
+  workflowId: number;
+  workflowName: string;
+  scheduledAt: Date;
+  attempt: number;
+}
+
+export interface WorkflowExecutionResult {
+  success: boolean;
+  recordsProcessed: number;
+  recordsFailed: number;
+  errorMessage?: string;
+  executionData?: Record<string, any>;
+}
+```
+
+### Module (workflow-schedule.module.ts)
+
+```typescript
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([ScheduledWorkflow, WorkflowExecutionLog]),
+    BullModule.registerQueue({ name: SCHEDULE_QUEUE_NAME }),
+    WorkflowModule,
+  ],
+  controllers: [WorkflowScheduleController],
+  providers: [WorkflowScheduleService, ScheduleProcessor],
+  exports: [WorkflowScheduleService],
+})
+export class WorkflowScheduleModule {}
+```
+
+---
+
+## Additional Requirements
+
+### Update app.module.ts
+
+Add imports:
+```typescript
+import { BullModule } from '@nestjs/bull';
+import { WorkflowScheduleModule } from './module/workflow-schedule/workflow-schedule.module';
+import { getBullConfig } from './config/bull.config';
+```
+
+Add to imports array:
+```typescript
+BullModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: getBullConfig,
+}),
+WorkflowScheduleModule,
+```
+
+### Tests
+
+Create comprehensive unit tests in `workflow-schedule.service.spec.ts`:
+- Test all service methods
+- Mock TypeORM repositories
+- Mock Bull queue
+- Test validation (invalid cron, invalid timezone)
+- Test error cases (not found, etc.)
+
+---
+
+## Code Quality Requirements
+
+1. **TypeScript**: Use strict types, no `any` unless necessary
+2. **Error Handling**: Proper exceptions (NotFoundException, BadRequestException)
+3. **Validation**: Use class-validator decorators
+4. **Documentation**: JSDoc comments for all public methods
+5. **Naming**: camelCase for variables, PascalCase for classes
+6. **Async/Await**: Use async/await, not .then()
+7. **Imports**: Organized and clean
+8. **Logging**: Use Logger from @nestjs/common
+
+---
+
+## Dependencies (already in package.json, but for reference)
+
+```
+@nestjs/bull
+bull
+ioredis
+cron-parser
+moment-timezone
+class-validator
+class-transformer
+```
+
+---
+
+## Expected Behavior
+
+After implementation:
+- ✅ Can create schedules via REST API
+- ✅ Schedules execute automatically at cron time
+- ✅ Can pause/resume schedules
+- ✅ Can manually trigger execution
+- ✅ Execution logs are created with detailed metrics
+- ✅ Failed jobs retry 3 times with exponential backoff
+- ✅ Records processed in batches of 100
+- ✅ Template variables work correctly
+
+---
+
+## Notes
+
+- Assume existing Workflow entity exists at `src/module/workflow/entities/workflow.entity.ts`
+- Assume WorkflowService exists and has necessary methods
+- Use proper TypeORM relationships and cascades
+- Follow NestJS best practices
+- Make code production-ready
+
+---
+
+## Please Implement
+
+Create all the files listed above with complete, working code. Ensure:
+1. All TypeScript types are correct
+2. All decorators are properly used
+3. Error handling is comprehensive
+4. Code follows NestJS conventions
+5. Everything is well-documented
+
+Start with the entities and migrations, then services, then controller, then processor.

package/src/module/workflow-schedule/docs/RUN_CLAUDE_CODE.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+
+# Claude Code Implementation Script
+# Use this to implement the workflow schedule module using Claude Code
+
+echo "╔══════════════════════════════════════════════════════════════════╗"
+echo "║                                                                  ║"
+echo "║       Claude Code - Workflow Schedule Implementation            ║"
+echo "║                                                                  ║"
+echo "╚══════════════════════════════════════════════════════════════════╝"
+echo ""
+
+PROJECT_PATH="/Users/debrajdas/WORKSPACE/001_RZ/PROJECTS/ETHER/250218_nodejs_core"
+
+echo "🎯 Target Project: $PROJECT_PATH"
+echo ""
+
+# Check if Claude Code is installed
+if ! command -v claude-code &> /dev/null; then
+    echo "❌ Claude Code is not installed"
+    echo ""
+    echo "Install it with:"
+    echo "  npm install -g @anthropic-ai/claude-code"
+    echo ""
+    echo "Or visit: https://docs.claude.com/claude-code"
+    exit 1
+fi
+
+echo "✅ Claude Code is installed"
+echo ""
+
+# Check if project exists
+if [ ! -d "$PROJECT_PATH" ]; then
+    echo "❌ Project not found at: $PROJECT_PATH"
+    exit 1
+fi
+
+echo "✅ Project found"
+echo ""
+
+cd "$PROJECT_PATH"
+
+echo "🚀 Starting Claude Code..."
+echo ""
+echo "📋 Prompt loaded from: CLAUDE_CODE_PROMPT.md"
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Get the directory where this script is located
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+# Run Claude Code with the prompt
+claude-code --prompt "$(cat "$SCRIPT_DIR/CLAUDE_CODE_PROMPT.md")"
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "✅ Claude Code session complete!"
+echo ""
+echo "📋 Next Steps:"
+echo "   1. Review the generated files"
+echo "   2. Install dependencies: npm install @nestjs/bull bull ioredis cron-parser moment-timezone"
+echo "   3. Setup Redis: docker run -d -p 6379:6379 --name redis redis:alpine"
+echo "   4. Update .env with Redis configuration"
+echo "   5. Run migrations: npm run migration:run"
+echo "   6. Start app: npm run start:dev"
+echo ""

package/src/module/workflow-schedule/dto/create-schedule.dto.ts

@@ -0,0 +1,147 @@
+import {
+  IsNotEmpty,
+  IsString,
+  IsNumber,
+  IsOptional,
+  IsBoolean,
+  IsObject,
+  IsArray,
+  ValidateNested,
+  IsDateString,
+  Matches,
+  Min,
+  Max,
+} from 'class-validator';
+import { Type } from 'class-transformer';
+
+/**
+ * DTO for retry configuration
+ */
+export class RetryConfigDto {
+  @IsNumber()
+  @Min(0)
+  @Max(10)
+  maxRetries: number;
+
+  @IsNumber()
+  @Min(1000)
+  retryDelay: number;
+
+  @IsNumber()
+  @Min(1)
+  @Max(10)
+  backoffMultiplier: number;
+}
+
+/**
+ * DTO for workflow action configuration
+ */
+export class WorkflowActionDto {
+  @IsString()
+  @IsNotEmpty()
+  actionType: string;
+
+  @IsObject()
+  @IsNotEmpty()
+  actionConfig: Record<string, any>;
+
+  @IsString()
+  @IsOptional()
+  targetEntityType?: string;
+
+  @IsObject()
+  @IsOptional()
+  filterCriteria?: Record<string, any>;
+}
+
+/**
+ * DTO for creating a scheduled workflow
+ */
+export class CreateScheduleDto {
+  @IsNumber()
+  @IsNotEmpty()
+  workflow_id: number;
+
+  @IsString()
+  @IsOptional()
+  workflow_name?: string;
+
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+
+  @IsString()
+  @IsOptional()
+  description?: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @Matches(
+    /^(\*|([0-5]?\d)) (\*|([01]?\d|2[0-3])) (\*|([01]?\d|2\d|3[01])) (\*|([1-9]|1[0-2])) (\*|([0-6]))$/,
+    {
+      message:
+        'Invalid cron expression format. Expected format: "minute hour day month weekday"',
+    },
+  )
+  cron_expression: string;
+
+  @IsString()
+  @IsNotEmpty()
+  timezone: string;
+
+  @IsDateString()
+  @IsOptional()
+  start_date?: string;
+
+  @IsDateString()
+  @IsOptional()
+  end_date?: string;
+
+  @IsNumber()
+  @IsOptional()
+  @Min(1)
+  max_executions?: number;
+
+  @ValidateNested()
+  @Type(() => RetryConfigDto)
+  @IsOptional()
+  retry_config?: RetryConfigDto;
+
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => WorkflowActionDto)
+  @IsOptional()
+  actions?: WorkflowActionDto[];
+
+  @IsObject()
+  @IsOptional()
+  metadata?: Record<string, any>;
+
+  @IsBoolean()
+  @IsOptional()
+  is_enabled?: boolean;
+
+  @IsNumber()
+  @IsOptional()
+  organization_id?: number;
+
+  @IsNumber()
+  @IsOptional()
+  enterprise_id?: number;
+
+  @IsString()
+  @IsOptional()
+  level_id?: string;
+
+  @IsString()
+  @IsOptional()
+  level_type?: string;
+
+  @IsString()
+  @IsOptional()
+  appcode?: string;
+
+  @IsString()
+  @IsOptional()
+  status?: string;
+}

package/src/module/workflow-schedule/dto/get-execution-logs.dto.ts

@@ -0,0 +1,119 @@
+import {
+  IsNotEmpty,
+  IsString,
+  IsNumber,
+  IsOptional,
+  IsDateString,
+  IsArray,
+  Min,
+  IsBoolean,
+  IsObject,
+} from 'class-validator';
+
+/**
+ * DTO for querying workflow execution logs
+ */
+export class GetExecutionLogsDto {
+  @IsNumber()
+  @IsOptional()
+  schedule_id?: number;
+
+  @IsNumber()
+  @IsOptional()
+  workflow_id?: number;
+
+  @IsString()
+  @IsOptional()
+  execution_status?: string;
+
+  @IsArray()
+  @IsString({ each: true })
+  @IsOptional()
+  execution_statuses?: string[];
+
+  @IsString()
+  @IsOptional()
+  triggered_by?: string;
+
+  @IsNumber()
+  @IsOptional()
+  triggered_by_user_id?: number;
+
+  @IsDateString()
+  @IsOptional()
+  start_date?: string;
+
+  @IsDateString()
+  @IsOptional()
+  end_date?: string;
+
+  @IsNumber()
+  @IsOptional()
+  @Min(1)
+  page?: number;
+
+  @IsNumber()
+  @IsOptional()
+  @Min(1)
+  size?: number;
+
+  @IsString()
+  @IsOptional()
+  sortBy?: string;
+
+  @IsString()
+  @IsOptional()
+  sortOrder?: 'ASC' | 'DESC';
+
+  @IsNumber()
+  @IsOptional()
+  organization_id?: number;
+
+  @IsNumber()
+  @IsOptional()
+  enterprise_id?: number;
+}
+
+/**
+ * DTO for manual trigger execution
+ */
+export class ManualTriggerDto {
+  @IsNumber()
+  @IsNotEmpty()
+  schedule_id: number;
+
+  @IsNumber()
+  @IsNotEmpty()
+  user_id: number;
+
+  @IsObject()
+  @IsOptional()
+  metadata?: Record<string, any>;
+}
+
+/**
+ * DTO for pause/resume schedule
+ */
+export class ToggleScheduleDto {
+  @IsNumber()
+  @IsNotEmpty()
+  schedule_id: number;
+
+  @IsBoolean()
+  @IsNotEmpty()
+  is_paused: boolean;
+}
+
+/**
+ * Response DTO for execution log statistics
+ */
+export class ExecutionLogStatsDto {
+  total_executions: number;
+  successful_executions: number;
+  failed_executions: number;
+  pending_executions: number;
+  running_executions: number;
+  average_duration_ms: number;
+  total_records_processed: number;
+  success_rate_percentage: number;
+}