# Task: Workflow Engine Module

**Status:** Not Started
**Priority:** P0 (Critical - Core Infrastructure)
**Estimated Effort:** 10-14 days
**Dependencies:** TASK-BE-001 (Database), TASK-BE-002 (Auth)
**Owner:** Backend Team

---

## 📋 Overview

สร้าง Unified Workflow Engine ที่ใช้ DSL-based configuration สำหรับจัดการ Workflow ของ Correspondences, RFAs, และ Circulations

---

## Objectives

- ✅ DSL Parser และ Validator
- ✅ State Machine Management
- ✅ Workflow Instance Lifecycle
- ✅ Transition Execution
- ✅ History Tracking
- ✅ Notification Integration

---

## 📝 Acceptance Criteria

1. **Definition Management:**

   - ✅ Create/Update workflow from JSON DSL
   - ✅ Validate DSL syntax และ Logic
   - ✅ Version management
   - ✅ Activate/Deactivate definitions

2. **Instance Management:**

   - ✅ Create instance from definition
   - ✅ Execute transitions
   - ✅ Check guards (permissions, validations)
   - ✅ Trigger effects (notifications, updates)
   - ✅ Track history

3. **Integration:**
   - ✅ Used by Correspondence module
   - ✅ Used by RFA module
   - ✅ Used by Circulation module
   - ✅ Notification service integration

---

## 🛠️ Implementation Steps

### 1. Entities

```typescript
// File: backend/src/modules/workflow-engine/entities/workflow-definition.entity.ts
@Entity('workflow_definitions')
export class WorkflowDefinition {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ length: 100 })
  name: string;

  @Column()
  version: number;

  @Column({ length: 50 })
  entity_type: string; // 'correspondence', 'rfa', 'circulation'

  @Column({ type: 'json' })
  definition: WorkflowDSL; // JSON DSL

  @Column({ default: true })
  is_active: boolean;

  @CreateDateColumn()
  created_at: Date;

  @Index(['name', 'version'], { unique: true })
  _nameVersionIndex: void;
}
```

```typescript
// File: backend/src/modules/workflow-engine/entities/workflow-instance.entity.ts
@Entity('workflow_instances')
export class WorkflowInstance {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  definition_id: number;

  @Column({ length: 50 })
  entity_type: string;

  @Column()
  entity_id: number;

  @Column({ length: 50 })
  current_state: string;

  @Column({ type: 'json', nullable: true })
  context: any; // Runtime data

  @CreateDateColumn()
  started_at: Date;

  @Column({ type: 'timestamp', nullable: true })
  completed_at: Date;

  @ManyToOne(() => WorkflowDefinition)
  @JoinColumn({ name: 'definition_id' })
  definition: WorkflowDefinition;

  @OneToMany(() => WorkflowHistory, (history) => history.instance)
  history: WorkflowHistory[];
}
```

```typescript
// File: backend/src/modules/workflow-engine/entities/workflow-history.entity.ts
@Entity('workflow_history')
export class WorkflowHistory {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  instance_id: number;

  @Column({ length: 50, nullable: true })
  from_state: string;

  @Column({ length: 50 })
  to_state: string;

  @Column({ length: 50 })
  action: string;

  @Column()
  actor_id: number;

  @Column({ type: 'json', nullable: true })
  metadata: any;

  @CreateDateColumn()
  transitioned_at: Date;

  @ManyToOne(() => WorkflowInstance, (instance) => instance.history)
  @JoinColumn({ name: 'instance_id' })
  instance: WorkflowInstance;

  @ManyToOne(() => User)
  @JoinColumn({ name: 'actor_id' })
  actor: User;
}
```

### 2. DSL Types

```typescript
// File: backend/src/modules/workflow-engine/types/workflow-dsl.type.ts
export interface WorkflowDSL {
  name: string;
  version: number;
  entity_type: string;
  states: WorkflowState[];
  transitions: WorkflowTransition[];
}

export interface WorkflowState {
  name: string;
  type: 'initial' | 'intermediate' | 'final';
  allowed_transitions: string[];
}

export interface WorkflowTransition {
  action: string;
  from: string;
  to: string;
  guards?: Guard[];
  effects?: Effect[];
}

export interface Guard {
  type: 'permission' | 'validation' | 'condition';
  permission?: string;
  rules?: string[];
  condition?: string;
}

export interface Effect {
  type: 'notification' | 'update_entity' | 'create_log';
  template?: string;
  recipients?: string[];
  field?: string;
  value?: any;
}
```

### 3. DSL Parser

```typescript
// File: backend/src/modules/workflow-engine/services/dsl-parser.service.ts
@Injectable()
export class DslParserService {
  parseDefinition(dsl: WorkflowDSL): ParsedWorkflow {
    this.validateStructure(dsl);
    this.validateStates(dsl);
    this.validateTransitions(dsl);

    return {
      states: this.parseStates(dsl.states),
      transitions: this.parseTransitions(dsl.transitions),
      stateMap: this.buildStateMap(dsl.states),
    };
  }

  private validateStructure(dsl: WorkflowDSL): void {
    if (!dsl.name || !dsl.states || !dsl.transitions) {
      throw new BadRequestException('Invalid DSL structure');
    }
  }

  private validateStates(dsl: WorkflowDSL): void {
    const initialStates = dsl.states.filter((s) => s.type === 'initial');
    if (initialStates.length !== 1) {
      throw new BadRequestException('Must have exactly one initial state');
    }

    const finalStates = dsl.states.filter((s) => s.type === 'final');
    if (finalStates.length === 0) {
      throw new BadRequestException('Must have at least one final state');
    }
  }

  private validateTransitions(dsl: WorkflowDSL): void {
    const stateNames = new Set(dsl.states.map((s) => s.name));

    for (const transition of dsl.transitions) {
      if (!stateNames.has(transition.from)) {
        throw new BadRequestException(`Unknown state: ${transition.from}`);
      }
      if (!stateNames.has(transition.to)) {
        throw new BadRequestException(`Unknown state: ${transition.to}`);
      }
    }
  }

  getInitialState(dsl: WorkflowDSL): string {
    const initialState = dsl.states.find((s) => s.type === 'initial');
    return initialState.name;
  }

  buildStateMap(states: WorkflowState[]): Map<string, WorkflowState> {
    return new Map(states.map((s) => [s.name, s]));
  }
}
```

### 4. Workflow Engine Service

```typescript
// File: backend/src/modules/workflow-engine/services/workflow-engine.service.ts
@Injectable()
export class WorkflowEngineService {
  constructor(
    @InjectRepository(WorkflowDefinition)
    private defRepo: Repository<WorkflowDefinition>,
    @InjectRepository(WorkflowInstance)
    private instanceRepo: Repository<WorkflowInstance>,
    @InjectRepository(WorkflowHistory)
    private historyRepo: Repository<WorkflowHistory>,
    private dslParser: DslParserService,
    private guardExecutor: GuardExecutorService,
    private effectExecutor: EffectExecutorService,
    private dataSource: DataSource
  ) {}

  async createInstance(
    definitionName: string,
    entityType: string,
    entityId: number,
    manager?: EntityManager
  ): Promise<WorkflowInstance> {
    const repo = manager || this.instanceRepo;

    //Get active definition
    const definition = await this.defRepo.findOne({
      where: { name: definitionName, entity_type: entityType, is_active: true },
      order: { version: 'DESC' },
    });

    if (!definition) {
      throw new NotFoundException(
        `Workflow definition not found: ${definitionName}`
      );
    }

    // Get initial state
    const initialState = this.dslParser.getInitialState(definition.definition);

    // Create instance
    const instance = repo.create({
      definition_id: definition.id,
      entity_type: entityType,
      entity_id: entityId,
      current_state: initialState,
      context: {},
    });

    return repo.save(instance);
  }

  async executeTransition(
    instanceId: number,
    action: string,
    actorId: number
  ): Promise<void> {
    return this.dataSource.transaction(async (manager) => {
      // 1. Get instance
      const instance = await manager.findOne(WorkflowInstance, {
        where: { id: instanceId },
        relations: ['definition'],
      });

      if (!instance) {
        throw new NotFoundException(
          `Workflow instance not found: ${instanceId}`
        );
      }

      // 2. Find transition
      const dsl = instance.definition.definition;
      const transition = dsl.transitions.find(
        (t) => t.action === action && t.from === instance.current_state
      );

      if (!transition) {
        throw new BadRequestException(
          `Invalid transition: ${action} from ${instance.current_state}`
        );
      }

      // 3. Execute guards
      await this.guardExecutor.checkGuards(transition.guards, {
        actorId,
        instance,
      });

      // 4. Update state
      const fromState = instance.current_state;
      instance.current_state = transition.to;

      // Check if reached final state
      const toStateConfig = dsl.states.find((s) => s.name === transition.to);
      if (toStateConfig.type === 'final') {
        instance.completed_at = new Date();
      }

      await manager.save(instance);

      // 5. Record history
      await manager.save(WorkflowHistory, {
        instance_id: instanceId,
        from_state: fromState,
        to_state: transition.to,
        action,
        actor_id: actorId,
        metadata: {},
      });

      // 6. Execute effects
      await this.effectExecutor.executeEffects(transition.effects, {
        instance,
        actorId,
        manager,
      });
    });
  }

  async getInstanceHistory(instanceId: number): Promise<WorkflowHistory[]> {
    return this.historyRepo.find({
      where: { instance_id: instanceId },
      relations: ['actor'],
      order: { transitioned_at: 'ASC' },
    });
  }

  async getCurrentState(entityType: string, entityId: number): Promise<string> {
    const instance = await this.instanceRepo.findOne({
      where: { entity_type: entityType, entity_id: entityId },
      order: { started_at: 'DESC' },
    });

    return instance?.current_state || null;
  }
}
```

### 5. Guard Executor

```typescript
// File: backend/src/modules/workflow-engine/services/guard-executor.service.ts
@Injectable()
export class GuardExecutorService {
  constructor(private abilityFactory: AbilityFactory) {}

  async checkGuards(guards: Guard[], context: any): Promise<void> {
    if (!guards || guards.length === 0) {
      return;
    }

    for (const guard of guards) {
      await this.checkGuard(guard, context);
    }
  }

  private async checkGuard(guard: Guard, context: any): Promise<void> {
    switch (guard.type) {
      case 'permission':
        await this.checkPermission(guard.permission, context);
        break;

      case 'validation':
        await this.checkValidation(guard.rules, context);
        break;

      case 'condition':
        await this.checkCondition(guard.condition, context);
        break;

      default:
        throw new BadRequestException(`Unknown guard type: ${guard.type}`);
    }
  }

  private async checkPermission(
    permission: string,
    context: any
  ): Promise<void> {
    const ability = await this.abilityFactory.createForUser({
      user_id: context.actorId,
    });
    const [action, subject] = permission.split('.');

    if (!ability.can(action, subject)) {
      throw new ForbiddenException(`Permission denied: ${permission}`);
    }
  }

  private async checkValidation(rules: string[], context: any): Promise<void> {
    // Implement validation rules
    // e.g., "hasAttachment", "hasRecipient"
  }

  private async checkCondition(condition: string, context: any): Promise<void> {
    // Evaluate condition expression
    // e.g., "entity.status === 'draft'"
  }
}
```

---

## ✅ Testing & Verification

### 1. Unit Tests

```typescript
describe('WorkflowEngineService', () => {
  it('should create instance with initial state', async () => {
    const instance = await service.createInstance(
      'CORRESPONDENCE_ROUTING',
      'correspondence',
      1
    );

    expect(instance.current_state).toBe('DRAFT');
  });

  it('should execute valid transition', async () => {
    await service.executeTransition(instance.id, 'SUBMIT', userId);

    const updated = await instanceRepo.findOne(instance.id);
    expect(updated.current_state).toBe('SUBMITTED');
  });

  it('should reject invalid transition', async () => {
    await expect(
      service.executeTransition(instance.id, 'INVALID_ACTION', userId)
    ).rejects.toThrow('Invalid transition');
  });
});
```

---

## 📚 Related Documents

- [ADR-001: Unified Workflow Engine](../05-decisions/ADR-001-unified-workflow-engine.md)
- [Unified Workflow Requirements](../01-requirements/03.6-unified-workflow.md)

---

## 📦 Deliverables

- [ ] Workflow Entities (Definition, Instance, History)
- [ ] DSL Parser และ Validator
- [ ] WorkflowEngineService
- [ ] Guard Executor
- [ ] Effect Executor
- [ ] Example Workflow Definitions
- [ ] Unit Tests (90% coverage)
- [ ] Integration Tests
- [ ] Documentation

---

## 🚨 Risks & Mitigation

| Risk               | Impact   | Mitigation                              |
| ------------------ | -------- | --------------------------------------- |
| DSL parsing errors | High     | Comprehensive validation                |
| Guard failures     | Medium   | Clear error messages                    |
| State corruption   | Critical | Transaction-safe updates                |
| Performance issues | Medium   | Optimize DSL parsing, cache definitions |

---

## 📌 Notes

- DSL structure validated on save
- Workflow definitions versioned
- Guard checks before state changes
- History tracked for audit trail
- Effects executed after state update