rez_core 4.0.222 → 5.0.0

package/src/module/workflow-schedule/MULTI_PROJECT_GUIDE.md

@@ -1,196 +1,196 @@
-# Multi-Project Configuration Guide
-
-## Overview
-This `workflow-schedule` module is designed to be used as a **shared package** across multiple NestJS projects. You can control whether the cron processor runs in each project independently.
-
-## Problem Scenario
-You have multiple servers importing this module:
-- **Server 1 (Scheduler Server)** - Should run the cron processor ✅
-- **Server 2 (API Server)** - Should NOT run cron, but can create/manage schedules ❌
-- **Server 3 (Worker Server)** - Should NOT run cron, but can create/manage schedules ❌
-
-## Solution
-
-### Server 1: Enable Cron Processor (Scheduler Server)
-
-```typescript
-// app.module.ts
-import { WorkflowScheduleModule } from './module/workflow-schedule/workflow-schedule.module';
-
-@Module({
-  imports: [
-    BullModule.forRootAsync(bullConfigFactory),
-    // ✅ Enable processor - this server will execute scheduled workflows
-    WorkflowScheduleModule.forRoot({ enableProcessor: true }),
-    WorkflowAutomationModule,
-    // ... other modules
-  ],
-})
-export class AppModule {}
-```
-
-### Server 2 & 3: Disable Cron Processor (API/Worker Servers)
-
-```typescript
-// app.module.ts
-import { WorkflowScheduleModule } from './module/workflow-schedule/workflow-schedule.module';
-
-@Module({
-  imports: [
-    BullModule.forRootAsync(bullConfigFactory),
-    // ❌ Disable processor - this server will NOT execute cron jobs
-    WorkflowScheduleModule.forRoot({ enableProcessor: false }),
-    WorkflowAutomationModule,
-    // ... other modules
-  ],
-})
-export class AppModule {}
-```
-
-## What Each Configuration Does
-
-### With `enableProcessor: true`
-- ✅ `WorkflowScheduleService` is available (create/manage schedules)
-- ✅ `ScheduleProcessor` is registered (listens to Bull queue)
-- ✅ **Cron jobs WILL execute** on this server
-- ✅ REST API endpoints are available
-- ✅ Can trigger manual executions
-
-### With `enableProcessor: false`
-- ✅ `WorkflowScheduleService` is available (create/manage schedules)
-- ❌ `ScheduleProcessor` is NOT registered
-- ❌ **Cron jobs will NOT execute** on this server
-- ✅ REST API endpoints are available
-- ✅ Can trigger manual executions
-- ⚠️ Scheduled workflows will be executed by the server with `enableProcessor: true`
-
-## Environment-Based Configuration
-
-For better control, use environment variables:
-
-```typescript
-// app.module.ts
-import { WorkflowScheduleModule } from './module/workflow-schedule/workflow-schedule.module';
-
-@Module({
-  imports: [
-    BullModule.forRootAsync(bullConfigFactory),
-    WorkflowScheduleModule.forRoot({
-      enableProcessor: process.env.ENABLE_WORKFLOW_SCHEDULER === 'true',
-    }),
-    WorkflowAutomationModule,
-  ],
-})
-export class AppModule {}
-```
-
-Then in each project's `.env` file:
-
-**Server 1 (Scheduler Server):**
-```env
-ENABLE_WORKFLOW_SCHEDULER=true
-```
-
-**Server 2 & 3:**
-```env
-ENABLE_WORKFLOW_SCHEDULER=false
-```
-
-## Default Behavior
-
-If you call `WorkflowScheduleModule.forRoot()` without options, the processor is **ENABLED by default**:
-
-```typescript
-// This is equivalent to { enableProcessor: true }
-WorkflowScheduleModule.forRoot()
-```
-
-## Architecture Considerations
-
-### Recommended Setup for High Availability
-
-1. **Dedicated Scheduler Server** (Server 1)
-   - `enableProcessor: true`
-   - Runs cron processor
-   - Handles scheduled workflow executions
-   - Monitor with PM2/Forever for auto-restart
-
-2. **API Servers** (Server 2, 3, ...)
-   - `enableProcessor: false`
-   - Handle HTTP requests
-   - Create/update/delete schedules
-   - Schedules are executed by Server 1
-
-### Redis Requirement
-
-All servers must connect to the **same Redis instance**:
-- Server 1 adds jobs to the queue
-- Servers 2 & 3 can also add jobs (manual triggers)
-- Only Server 1 (with processor enabled) will consume/execute jobs
-
-```typescript
-// bull.config.ts (same across all servers)
-export const bullConfigFactory = {
-  useFactory: () => ({
-    redis: {
-      host: process.env.REDIS_HOST || 'localhost',
-      port: parseInt(process.env.REDIS_PORT) || 6379,
-      password: process.env.REDIS_PASSWORD,
-    },
-  }),
-};
-```
-
-## Testing
-
-### Test Processor is Disabled
-
-Start your server with `enableProcessor: false` and check logs. You should NOT see:
-```
-[ScheduleProcessor] Processing job {jobId}
-```
-
-### Test Processor is Enabled
-
-Start your server with `enableProcessor: true` and:
-1. Create a schedule with `is_enabled: true`
-2. Check logs for processor activity
-3. Verify jobs execute on schedule
-
-## Migration from Old Setup
-
-If you previously imported the module directly:
-
-**Before:**
-```typescript
-imports: [
-  WorkflowScheduleModule, // ❌ Old way
-]
-```
-
-**After:**
-```typescript
-imports: [
-  WorkflowScheduleModule.forRoot({ enableProcessor: true }), // ✅ New way
-]
-```
-
-## Troubleshooting
-
-### Issue: Cron runs on multiple servers
-
-**Cause:** Multiple servers have `enableProcessor: true`
-
-**Solution:** Set `enableProcessor: false` on all servers except one
-
-### Issue: Cron doesn't run on any server
-
-**Cause:** All servers have `enableProcessor: false`
-
-**Solution:** Set `enableProcessor: true` on at least one server
-
-### Issue: "Cannot find module WorkflowScheduleModule"
-
-**Cause:** Wrong import after refactor
-
-**Solution:** Ensure you're importing from the correct path and using `.forRoot()`
+# Multi-Project Configuration Guide
+
+## Overview
+This `workflow-schedule` module is designed to be used as a **shared package** across multiple NestJS projects. You can control whether the cron processor runs in each project independently.
+
+## Problem Scenario
+You have multiple servers importing this module:
+- **Server 1 (Scheduler Server)** - Should run the cron processor ✅
+- **Server 2 (API Server)** - Should NOT run cron, but can create/manage schedules ❌
+- **Server 3 (Worker Server)** - Should NOT run cron, but can create/manage schedules ❌
+
+## Solution
+
+### Server 1: Enable Cron Processor (Scheduler Server)
+
+```typescript
+// app.module.ts
+import { WorkflowScheduleModule } from './module/workflow-schedule/workflow-schedule.module';
+
+@Module({
+  imports: [
+    BullModule.forRootAsync(bullConfigFactory),
+    // ✅ Enable processor - this server will execute scheduled workflows
+    WorkflowScheduleModule.forRoot({ enableProcessor: true }),
+    WorkflowAutomationModule,
+    // ... other modules
+  ],
+})
+export class AppModule {}
+```
+
+### Server 2 & 3: Disable Cron Processor (API/Worker Servers)
+
+```typescript
+// app.module.ts
+import { WorkflowScheduleModule } from './module/workflow-schedule/workflow-schedule.module';
+
+@Module({
+  imports: [
+    BullModule.forRootAsync(bullConfigFactory),
+    // ❌ Disable processor - this server will NOT execute cron jobs
+    WorkflowScheduleModule.forRoot({ enableProcessor: false }),
+    WorkflowAutomationModule,
+    // ... other modules
+  ],
+})
+export class AppModule {}
+```
+
+## What Each Configuration Does
+
+### With `enableProcessor: true`
+- ✅ `WorkflowScheduleService` is available (create/manage schedules)
+- ✅ `ScheduleProcessor` is registered (listens to Bull queue)
+- ✅ **Cron jobs WILL execute** on this server
+- ✅ REST API endpoints are available
+- ✅ Can trigger manual executions
+
+### With `enableProcessor: false`
+- ✅ `WorkflowScheduleService` is available (create/manage schedules)
+- ❌ `ScheduleProcessor` is NOT registered
+- ❌ **Cron jobs will NOT execute** on this server
+- ✅ REST API endpoints are available
+- ✅ Can trigger manual executions
+- ⚠️ Scheduled workflows will be executed by the server with `enableProcessor: true`
+
+## Environment-Based Configuration
+
+For better control, use environment variables:
+
+```typescript
+// app.module.ts
+import { WorkflowScheduleModule } from './module/workflow-schedule/workflow-schedule.module';
+
+@Module({
+  imports: [
+    BullModule.forRootAsync(bullConfigFactory),
+    WorkflowScheduleModule.forRoot({
+      enableProcessor: process.env.ENABLE_WORKFLOW_SCHEDULER === 'true',
+    }),
+    WorkflowAutomationModule,
+  ],
+})
+export class AppModule {}
+```
+
+Then in each project's `.env` file:
+
+**Server 1 (Scheduler Server):**
+```env
+ENABLE_WORKFLOW_SCHEDULER=true
+```
+
+**Server 2 & 3:**
+```env
+ENABLE_WORKFLOW_SCHEDULER=false
+```
+
+## Default Behavior
+
+If you call `WorkflowScheduleModule.forRoot()` without options, the processor is **ENABLED by default**:
+
+```typescript
+// This is equivalent to { enableProcessor: true }
+WorkflowScheduleModule.forRoot()
+```
+
+## Architecture Considerations
+
+### Recommended Setup for High Availability
+
+1. **Dedicated Scheduler Server** (Server 1)
+   - `enableProcessor: true`
+   - Runs cron processor
+   - Handles scheduled workflow executions
+   - Monitor with PM2/Forever for auto-restart
+
+2. **API Servers** (Server 2, 3, ...)
+   - `enableProcessor: false`
+   - Handle HTTP requests
+   - Create/update/delete schedules
+   - Schedules are executed by Server 1
+
+### Redis Requirement
+
+All servers must connect to the **same Redis instance**:
+- Server 1 adds jobs to the queue
+- Servers 2 & 3 can also add jobs (manual triggers)
+- Only Server 1 (with processor enabled) will consume/execute jobs
+
+```typescript
+// bull.config.ts (same across all servers)
+export const bullConfigFactory = {
+  useFactory: () => ({
+    redis: {
+      host: process.env.REDIS_HOST || 'localhost',
+      port: parseInt(process.env.REDIS_PORT) || 6379,
+      password: process.env.REDIS_PASSWORD,
+    },
+  }),
+};
+```
+
+## Testing
+
+### Test Processor is Disabled
+
+Start your server with `enableProcessor: false` and check logs. You should NOT see:
+```
+[ScheduleProcessor] Processing job {jobId}
+```
+
+### Test Processor is Enabled
+
+Start your server with `enableProcessor: true` and:
+1. Create a schedule with `is_enabled: true`
+2. Check logs for processor activity
+3. Verify jobs execute on schedule
+
+## Migration from Old Setup
+
+If you previously imported the module directly:
+
+**Before:**
+```typescript
+imports: [
+  WorkflowScheduleModule, // ❌ Old way
+]
+```
+
+**After:**
+```typescript
+imports: [
+  WorkflowScheduleModule.forRoot({ enableProcessor: true }), // ✅ New way
+]
+```
+
+## Troubleshooting
+
+### Issue: Cron runs on multiple servers
+
+**Cause:** Multiple servers have `enableProcessor: true`
+
+**Solution:** Set `enableProcessor: false` on all servers except one
+
+### Issue: Cron doesn't run on any server
+
+**Cause:** All servers have `enableProcessor: false`
+
+**Solution:** Set `enableProcessor: true` on at least one server
+
+### Issue: "Cannot find module WorkflowScheduleModule"
+
+**Cause:** Wrong import after refactor
+
+**Solution:** Ensure you're importing from the correct path and using `.forRoot()`