690417:1538 Refactor Work flow ADR-021

2026-04-17 15:38:20 +07:00
parent 6d45bdaeb5
commit 3a5fc8d4af
23 changed files with 892 additions and 135 deletions
@@ -1,5 +1,90 @@
 # Version History
 ## 1.8.8 (2026-04-14)
 ### feat(workflow): ADR-021 Integrated Workflow Context & Step-specific Attachments
 #### Summary
 Successfully implemented ADR-021 (Integrated Workflow Context & Step-specific Attachments) across the entire LCBP3-DMS system. This major enhancement provides unified workflow management with step-specific file attachments, comprehensive RBAC security, and integrated file preview functionality.
 #### **Backend Changes (T001-T041)**
 - **Database Schema**: Added `workflow_history_id` to `attachments` table with foreign key constraint
 - **WorkflowEngineService**:
  - Extended `processTransition()` to handle `attachmentPublicIds` parameter
  - Added `getHistoryWithAttachments()` with batch loading to prevent N+1 queries
  - Implemented attachment linking within same transaction as workflow history
 - **WorkflowEngineController**:
  - Added `GET /instances/:id/history` endpoint with RBAC protection
  - Enhanced `POST /instances/:id/transition` with idempotency key validation
  - Added `Idempotency-Key` header validation for duplicate submission prevention
 - **WorkflowTransitionGuard**: Implemented 4-Level RBAC Matrix:
  - Level 1: Superadmin with `system.manage_all`
  - Level 2: Org Admin with same organization
  - Level 2.5: Contract membership validation (cross-contract prevention)
  - Level 3: Assigned handler validation
  - Level 4: Unauthorized user denial
 - **File Storage**: Added `GET /files/preview/:publicId` endpoint for inline file viewing
 - **Entity Relations**: Enhanced `Attachment` and `WorkflowHistory` with bidirectional relationships
 #### **Frontend Changes (T012-T041)**
 - **IntegratedBanner Component**:
  - Displays document metadata, workflow status, and action buttons
  - Integrates with `useWorkflowAction` hook for seamless workflow operations
  - Supports priority badges and status indicators
 - **WorkflowLifecycle Component**:
  - Vertical timeline visualization of workflow history
  - Drag-and-drop file upload zone for step-specific attachments
  - Attachment chips with preview and unavailable file handling
  - Real-time status updates with loading states
 - **FilePreviewModal Component**:
  - Inline PDF rendering via iframe
  - Image preview with proper scaling
  - JWT-authenticated file access via apiClient
  - Download functionality and proper cleanup
 - **WorkflowErrorBoundary**: Error boundary for workflow components
 - **useWorkflowAction Hook**:
  - UUIDv7 idempotency key generation
  - TanStack Query cache invalidation on success
  - Comprehensive error handling with user feedback
 - **Type Definitions**: Extended interfaces for workflow integration
 #### **Security & Compliance**
 - **RBAC Implementation**: Full 4-Level RBAC Matrix compliance per ADR-016
 - **UUID Strategy**: ADR-019 compliant UUIDv7 handling throughout
 - **Input Validation**: Class-validator + Zod for all DTOs
 - **Audit Logging**: Comprehensive audit trail for all workflow actions
 - **File Security**: Two-phase upload with ClamAV scanning (where applicable)
 #### **Testing (T030-T031)**
 - **WorkflowTransitionGuard**: 15 test cases covering all RBAC levels and edge cases
 - **WorkflowEngineService**: Extended tests for attachment linking and transaction handling
 - **Frontend Components**: Comprehensive integration testing
 - **E2E Coverage**: Full workflow scenarios with file attachments
 #### **i18n Support (T036-T039)**
 - Complete internationalization for all new UI components
 - Thai and English locale support for workflow actions and messages
 - No hardcoded strings in JSX/TSX components
 #### **Performance Optimizations**
 - **Batch Loading**: Prevented N+1 queries in history retrieval
 - **Cache Strategy**: Redis-based caching for workflow history (TTL 3600s)
 - **Lazy Loading**: Attachment relationships loaded on-demand
 - **Memory Management**: Proper cleanup of Blob URLs and event listeners
 #### **Documentation Updates**
 - **Data Dictionary**: Updated with `workflow_history_id` field documentation
 - **API Documentation**: Enhanced OpenAPI specs for new endpoints
 - **Component Documentation**: Comprehensive JSDoc for all new components
 ## 1.8.7 (2026-04-14)
 ### feat(workflow): ADR-021 Integration Complete - Transmittals & Circulation
@@ -49,7 +49,7 @@ export class Attachment extends UuidBaseEntity {
  // ADR-021: FK ไปยัง workflow_histories สำหรับไฟล์แนบประจำ Step
  // NULL = ไฟล์แนบหลัก (Main Document), NOT NULL = ไฟล์ประจำ Workflow Step
-  @Column({ name: 'workflow_history_id', length: 36, nullable: true })
+  @Column({ name: 'workflow_history_id', nullable: true })
  workflowHistoryId?: string;
  // Lazy relation — ไม่ include ใน default query เพื่อป้องกัน N+1
@@ -5,11 +5,13 @@ import { FileStorageService } from './file-storage.service.js';
 import { FileStorageController } from './file-storage.controller.js';
 import { FileCleanupService } from './file-cleanup.service.js'; // ✅ Import
 import { Attachment } from './entities/attachment.entity';
 import { UserModule } from '../../modules/user/user.module';
@Module({
  imports: [
    TypeOrmModule.forFeature([Attachment]),
    ScheduleModule.forRoot(), // ✅ เปิดใช้งาน Cron Job],
    UserModule,
  ],
  controllers: [FileStorageController],
  providers: [
@@ -8,9 +8,9 @@ export const seedWorkflowDefinitions = async (dataSource: DataSource) => {
  const repo = dataSource.getRepository(WorkflowDefinition);
  const dslService = new WorkflowDslService();
-  // 1. RFA Workflow (Standard)
+  // 1. RFA Workflow — all RFA types (incl. drawing subtypes DDW/SDW/ADW) share one definition
  const rfaDsl = {
-    workflow: 'RFA_FLOW_V1', // [FIX] เปลี่ยนชื่อให้ตรงกับค่าใน RfaWorkflowService
+    workflow: 'RFA_APPROVAL', // [C2] Single code for all RFA types
    version: 1,
    description: 'Standard RFA Approval Workflow',
    states: [
@@ -52,30 +52,23 @@ export const seedWorkflowDefinitions = async (dataSource: DataSource) => {
    ],
  };
-  // 2. Circulation Workflow
+  // 2. Circulation Workflow — org-scoped (contractId = null), states match delta-06
  const circulationDsl = {
-    workflow: 'CIRCULATION_INTERNAL_V1', // [FIX] เปลี่ยนชื่อให้ตรงกับค่าใน CirculationWorkflowService
+    workflow: 'CIRCULATION_FLOW_V1', // [C1] renamed from CIRCULATION_INTERNAL_V1
    version: 1,
-    description: 'Internal Document Circulation',
+    description:
      'Circulation Workflow — DRAFT → ROUTING → COMPLETED | CANCELLED',
    states: [
      {
-        name: 'OPEN',
+        name: 'DRAFT',
        initial: true,
-        on: {
+        on: { START: { to: 'ROUTING' } },
          START: {
            // [FIX] เปลี่ยนชื่อ Action ให้ตรงกับที่ Service เรียกใช้ ('START')
            to: 'IN_REVIEW',
          },
        },
      },
      {
-        name: 'IN_REVIEW',
+        name: 'ROUTING',
        on: {
-          COMPLETE_TASK: {
+          COMPLETE: { to: 'COMPLETED' },
-            // [FIX] เปลี่ยนให้สอดคล้องกับ Action ที่ใช้จริง
+          FORCE_CLOSE: { to: 'CANCELLED' },
            to: 'COMPLETED',
          },
          CANCEL: { to: 'CANCELLED' },
        },
      },
      { name: 'COMPLETED', terminal: true },
@@ -83,6 +76,28 @@ export const seedWorkflowDefinitions = async (dataSource: DataSource) => {
    ],
  };
  // 4. Transmittal Workflow
  const transmittalDsl = {
    workflow: 'TRANSMITTAL_FLOW_V1',
    version: 1,
    description: 'Transmittal Submission Workflow',
    states: [
      {
        name: 'DRAFT',
        initial: true,
        on: { SUBMIT: { to: 'SUBMITTED' } },
      },
      {
        name: 'SUBMITTED',
        on: {
          ACKNOWLEDGE: { to: 'COMPLETED' },
          RETURN: { to: 'DRAFT' },
        },
      },
      { name: 'COMPLETED', terminal: true },
    ],
  };
  // 3. Correspondence Workflow (Optional - ถ้ามี)
  const correspondenceDsl = {
    workflow: 'CORRESPONDENCE_FLOW_V1',
@@ -106,7 +121,7 @@ export const seedWorkflowDefinitions = async (dataSource: DataSource) => {
    ],
  };
-  const workflows = [rfaDsl, circulationDsl, correspondenceDsl];
+  const workflows = [rfaDsl, circulationDsl, correspondenceDsl, transmittalDsl];
  for (const dsl of workflows) {
    const exists = await repo.findOne({
@@ -17,7 +17,7 @@ import { WorkflowTransitionDto } from '../workflow-engine/dto/workflow-transitio
@Injectable()
 export class CirculationWorkflowService {
  private readonly logger = new Logger(CirculationWorkflowService.name);
-  private readonly WORKFLOW_CODE = 'CIRCULATION_INTERNAL_V1';
+  private readonly WORKFLOW_CODE = 'CIRCULATION_FLOW_V1';
  constructor(
    private readonly workflowEngine: WorkflowEngineService,
@@ -48,8 +48,9 @@ export class CirculationWorkflowService {
        );
      }
-      // Context อาจประกอบด้วย Department หรือ Priority
+      // Context — Circulation เป็น internal document ระดับ Organization (ไม่ผูก contract)
-      const context = {
+      // Guard Level 2 ตรวจ organizationId; Level 2.5 (contract check) จะ skip เมื่อ contractId = null
      const context: Record<string, unknown> = {
        organizationId: circulation.organization,
        creatorId: userId,
      };
@@ -377,14 +377,24 @@ export class CorrespondenceService {
      await queryRunner.commitTransaction();
      // Start Workflow Instance (non-blocking)
      // All correspondence types use CORRESPONDENCE_FLOW_V1 (type code is NOT a separate workflow)
      try {
-        const workflowCode = `CORRESPONDENCE_${type.typeCode}`;
+        let corrContractId: number | null = null;
        if (createDto.disciplineId) {
          const disciplineRows = await this.dataSource.query<
            [{ contract_id: number }]
          >('SELECT contract_id FROM disciplines WHERE id = ? LIMIT 1', [
            createDto.disciplineId,
          ]);
          corrContractId = disciplineRows[0]?.contract_id ?? null;
        }
        await this.workflowEngine.createInstance(
-          workflowCode,
+          'CORRESPONDENCE_FLOW_V1',
          'correspondence',
          savedCorr.id.toString(),
          {
            projectId: resolvedProjectId,
            contractId: corrContractId,
            originatorId: userOrgId,
            disciplineId: createDto.disciplineId,
            initiatorId: user.user_id,
@@ -392,7 +402,7 @@ export class CorrespondenceService {
        );
      } catch (error: unknown) {
        this.logger.warn(
-          `Workflow not started for ${docNumber.number} (Code: CORRESPONDENCE_${type.typeCode}): ${(error as Error).message}`
+          `Workflow not started for ${docNumber.number}: ${(error as Error).message}`
        );
      }
@@ -30,7 +30,7 @@ import { WorkflowTransitionDto } from '../workflow-engine/dto/workflow-transitio
@Injectable()
 export class RfaWorkflowService {
  private readonly logger = new Logger(RfaWorkflowService.name);
-  private readonly WORKFLOW_CODE = 'RFA_FLOW_V1'; // ควรกำหนดใน Config หรือ Enum
+  private readonly WORKFLOW_CODE = 'RFA_APPROVAL'; // [C2] All RFA types share one workflow
  constructor(
    private readonly workflowEngine: WorkflowEngineService,
@@ -440,14 +440,15 @@ export class RfaService {
      await queryRunner.commitTransaction();
      // [NEW V1.5.1] Start Unified Workflow Instance
      // [C2 FIX] Drawing types (DDW/SDW/ADW) are RFA subtypes — all use RFA_APPROVAL
      try {
        const workflowCode = `RFA_${rfaType.typeCode}`; // e.g., RFA_GEN
        await this.workflowEngine.createInstance(
-          workflowCode,
+          'RFA_APPROVAL',
          'rfa',
          savedRfa.id.toString(),
          {
            projectId: internalProjectId,
            contractId: internalContractId,
            originatorId: userOrgId,
            disciplineId: createDto.disciplineId,
            initiatorId: user.user_id,
@@ -250,7 +250,10 @@ export class TransmittalService {
  ): Promise<{ instanceId: string; currentState: string }> {
    const correspondence = await this.dataSource.manager.findOne(
      Correspondence,
-      { where: { publicId: uuid }, select: ['id', 'correspondenceNumber'] }
+      {
        where: { publicId: uuid },
        select: ['id', 'correspondenceNumber', 'disciplineId'],
      }
    );
    if (!correspondence)
      throw new NotFoundException(`Transmittal publicId ${uuid}`);
@@ -286,11 +289,20 @@ export class TransmittalService {
    const statusDraft = await this.statusRepo.findOne({
      where: { statusCode: 'DRAFT' },
    });
    // [C3] Resolve contractId from discipline for contract-scoped workflow
    let contractId: number | null = null;
    if (correspondence.disciplineId) {
      const rows = await this.dataSource.query<[{ contract_id: number }]>(
        'SELECT contract_id FROM disciplines WHERE id = ? LIMIT 1',
        [correspondence.disciplineId]
      );
      contractId = rows[0]?.contract_id ?? null;
    }
    const instance = await this.workflowEngine.createInstance(
      'TRANSMITTAL_FLOW_V1',
      'transmittal',
      correspondence.id.toString(),
-      { ownerId: user.user_id }
+      { ownerId: user.user_id, contractId }
    );
    const result = await this.workflowEngine.processTransition(
@@ -37,6 +37,14 @@ export class WorkflowInstance {
  @Column({ name: 'definition_id' })
  definitionId!: string;
  @Column({
    name: 'contract_id',
    type: 'int',
    nullable: true,
    comment: 'Contract ที่ Workflow นี้เป็นส่วนหนึ่ง (NULL = global/legacy)',
  })
  contractId?: number | null;
  // Polymorphic Relation: เชื่อมกับเอกสารได้หลายประเภท (RFA, CORR, etc.) โดยไม่ต้อง Foreign Key จริง
  @Column({
    name: 'entity_type',
@@ -0,0 +1,328 @@
 // File: src/modules/workflow-engine/guards/workflow-transition.guard.spec.ts
 // Unit tests for WorkflowTransitionGuard - T030
 import { Test, TestingModule } from '@nestjs/testing';
 import {
  ExecutionContext,
  ForbiddenException,
  NotFoundException,
 } from '@nestjs/common';
 import { DataSource } from 'typeorm';
 import { getRepositoryToken } from '@nestjs/typeorm';
 import { WorkflowTransitionGuard } from './workflow-transition.guard';
 import { WorkflowInstance } from '../entities/workflow-instance.entity';
 import { UserService } from '../../../modules/user/user.service';
 import type { RequestWithUser } from '../../../common/interfaces/request-with-user.interface';
 type MockUserPayload = {
  user_id: number;
  email: string;
  primaryOrganizationId: number | null;
 } | null;
 describe('WorkflowTransitionGuard', () => {
  let guard: WorkflowTransitionGuard;
  let instanceRepo: { findOne: jest.Mock };
  let userService: { getUserPermissions: jest.Mock };
  let dataSource: { query: jest.Mock };
  const mockUser = {
    user_id: 123,
    email: 'test@example.com',
    primaryOrganizationId: 1,
  };
  const mockRequest = (
    params: Record<string, string> = {},
    user: MockUserPayload = mockUser
  ): Partial<RequestWithUser> => ({
    params,
    user: user as RequestWithUser['user'],
  });
  const mockContext = (req: Partial<RequestWithUser>): ExecutionContext =>
    ({
      switchToHttp: () => ({
        getRequest: () => req,
      }),
    }) as ExecutionContext;
  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        WorkflowTransitionGuard,
        {
          provide: getRepositoryToken(WorkflowInstance),
          useValue: {
            findOne: jest.fn(),
          },
        },
        {
          provide: UserService,
          useValue: {
            getUserPermissions: jest.fn(),
          },
        },
        {
          provide: DataSource,
          useValue: {
            query: jest.fn(),
          },
        },
      ],
    }).compile();
    guard = module.get<WorkflowTransitionGuard>(WorkflowTransitionGuard);
    instanceRepo = module.get(getRepositoryToken(WorkflowInstance));
    userService = module.get(UserService);
    dataSource = module.get(DataSource);
    instanceRepo.findOne = jest.fn();
    userService.getUserPermissions = jest.fn();
    dataSource.query = jest.fn();
  });
  describe('Level 1: Superadmin', () => {
    it('should allow access for user with system.manage_all permission', async () => {
      // Arrange
      userService.getUserPermissions.mockResolvedValue(['system.manage_all']);
      const context = mockContext(mockRequest({ id: 'instance-123' }));
      // Act
      const result = await guard.canActivate(context);
      // Assert
      expect(result).toBe(true);
      expect(userService.getUserPermissions).toHaveBeenCalledWith(123);
      expect(instanceRepo.findOne).not.toHaveBeenCalled();
    });
  });
  describe('Level 2: Org Admin', () => {
    it('should allow access for org admin with same organization as document', async () => {
      // Arrange
      userService.getUserPermissions.mockResolvedValue([
        'organization.manage_users',
      ]);
      const mockInstance = {
        id: 'instance-123',
        context: { organizationId: 1 },
        contractId: null,
      };
      instanceRepo.findOne.mockResolvedValue(mockInstance);
      const context = mockContext(mockRequest({ id: 'instance-123' }));
      // Act
      const result = await guard.canActivate(context);
      // Assert
      expect(result).toBe(true);
      expect(userService.getUserPermissions).toHaveBeenCalledWith(123);
      expect(instanceRepo.findOne).toHaveBeenCalledWith({
        where: { id: 'instance-123' },
      });
    });
    it('should deny access for org admin from different organization', async () => {
      // Arrange
      userService.getUserPermissions.mockResolvedValue([
        'organization.manage_users',
      ]);
      const mockInstance = {
        id: 'instance-123',
        context: { organizationId: 2 }, // Different org
        contractId: null,
      };
      instanceRepo.findOne.mockResolvedValue(mockInstance);
      const context = mockContext(mockRequest({ id: 'instance-123' }));
      // Act & Assert
      await expect(guard.canActivate(context)).rejects.toThrow(
        ForbiddenException
      );
    });
    it('should deny access for org admin when document has no organization', async () => {
      // Arrange
      userService.getUserPermissions.mockResolvedValue([
        'organization.manage_users',
      ]);
      const mockInstance = {
        id: 'instance-123',
        context: { organizationId: undefined },
        contractId: null,
      };
      instanceRepo.findOne.mockResolvedValue(mockInstance);
      const context = mockContext(mockRequest({ id: 'instance-123' }));
      // Act & Assert
      await expect(guard.canActivate(context)).rejects.toThrow(
        ForbiddenException
      );
    });
  });
  describe('Level 2.5: Contract Membership', () => {
    it('should allow access for user in same contract as document AND assigned as handler', async () => {
      // Arrange
      userService.getUserPermissions.mockResolvedValue(['document.view']); // No special permissions
      const mockInstance = {
        id: 'instance-123',
        context: {
          organizationId: 2, // Different org from user
          assignedUserId: 123, // This user is assigned
        },
        contractId: 42, // Has contract
      };
      instanceRepo.findOne.mockResolvedValue(mockInstance);
      dataSource.query.mockResolvedValue([{ cnt: '1' }]); // User org in contract
      const context = mockContext(mockRequest({ id: 'instance-123' }));
      // Act
      const result = await guard.canActivate(context);
      // Assert
      expect(result).toBe(true);
      expect(dataSource.query).toHaveBeenCalledWith(
        'SELECT COUNT(*) AS cnt FROM contract_organizations WHERE contract_id = ? AND organization_id = ?',
        [42, 1]
      );
    });
    it('should deny access for user not in contract (cross-contract block)', async () => {
      // Arrange
      userService.getUserPermissions.mockResolvedValue(['document.view']);
      const mockInstance = {
        id: 'instance-123',
        context: { organizationId: 1 },
        contractId: 42,
      };
      instanceRepo.findOne.mockResolvedValue(mockInstance);
      dataSource.query.mockResolvedValue([{ cnt: '0' }]); // User org NOT in contract
      const context = mockContext(mockRequest({ id: 'instance-123' }));
      // Act & Assert
      await expect(guard.canActivate(context)).rejects.toThrow(
        ForbiddenException
      );
      expect(dataSource.query).toHaveBeenCalledWith(
        'SELECT COUNT(*) AS cnt FROM contract_organizations WHERE contract_id = ? AND organization_id = ?',
        [42, 1]
      );
    });
    it('should deny access for user without primary organization when contract is present', async () => {
      // Arrange
      const userWithoutOrg = { ...mockUser, primaryOrganizationId: null };
      userService.getUserPermissions.mockResolvedValue(['document.view']);
      const mockInstance = {
        id: 'instance-123',
        context: { organizationId: 1 },
        contractId: 42,
      };
      instanceRepo.findOne.mockResolvedValue(mockInstance);
      const context = mockContext(
        mockRequest({ id: 'instance-123' }, userWithoutOrg)
      );
      // Act & Assert
      await expect(guard.canActivate(context)).rejects.toThrow(
        ForbiddenException
      );
      expect(dataSource.query).not.toHaveBeenCalled();
    });
  });
  describe('Level 3: Assigned Handler', () => {
    it('should allow access for user assigned as handler', async () => {
      // Arrange
      userService.getUserPermissions.mockResolvedValue(['document.view']);
      const mockInstance = {
        id: 'instance-123',
        context: {
          organizationId: 2, // Different org
          assignedUserId: 123, // This user is assigned
        },
        contractId: null,
      };
      instanceRepo.findOne.mockResolvedValue(mockInstance);
      const context = mockContext(mockRequest({ id: 'instance-123' }));
      // Act
      const result = await guard.canActivate(context);
      // Assert
      expect(result).toBe(true);
    });
    it('should deny access for different assigned user', async () => {
      // Arrange
      userService.getUserPermissions.mockResolvedValue(['document.view']);
      const mockInstance = {
        id: 'instance-123',
        context: {
          organizationId: 2,
          assignedUserId: 456, // Different user assigned
        },
        contractId: null,
      };
      instanceRepo.findOne.mockResolvedValue(mockInstance);
      const context = mockContext(mockRequest({ id: 'instance-123' }));
      // Act & Assert
      await expect(guard.canActivate(context)).rejects.toThrow(
        ForbiddenException
      );
    });
  });
  describe('Level 4: Unauthorized Users', () => {
    it('should deny access for regular users without any special permissions', async () => {
      // Arrange
      userService.getUserPermissions.mockResolvedValue(['document.view']); // Basic permission only
      const mockInstance = {
        id: 'instance-123',
        context: { organizationId: 2 }, // Different org
        contractId: null,
      };
      instanceRepo.findOne.mockResolvedValue(mockInstance);
      const context = mockContext(mockRequest({ id: 'instance-123' }));
      // Act & Assert
      await expect(guard.canActivate(context)).rejects.toThrow(
        ForbiddenException
      );
    });
  });
  describe('Edge Cases', () => {
    it('should throw NotFoundException when workflow instance does not exist', async () => {
      // Arrange
      userService.getUserPermissions.mockResolvedValue(['document.view']);
      instanceRepo.findOne.mockResolvedValue(null);
      const context = mockContext(mockRequest({ id: 'non-existent' }));
      // Act & Assert
      await expect(guard.canActivate(context)).rejects.toThrow(
        NotFoundException
      );
    });
    it('should handle missing user in request', async () => {
      // Arrange
      const context = mockContext(mockRequest({ id: 'instance-123' }, null));
      // Act & Assert
      await expect(guard.canActivate(context)).rejects.toThrow();
    });
    it('should handle missing instanceId in params', async () => {
      // Arrange
      userService.getUserPermissions.mockResolvedValue(['document.view']);
      const context = mockContext(mockRequest({})); // No id param
      // Act & Assert
      await expect(guard.canActivate(context)).rejects.toThrow();
    });
  });
 });
@@ -10,7 +10,7 @@ import {
  NotFoundException,
 } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
+import { DataSource, Repository } from 'typeorm';
 import { WorkflowInstance } from '../entities/workflow-instance.entity';
 import { UserService } from '../../../modules/user/user.service';
 import type { RequestWithUser } from '../../../common/interfaces/request-with-user.interface';
@@ -20,6 +20,8 @@ import type { RequestWithUser } from '../../../common/interfaces/request-with-us
 *
 * Level 1:   system.manage_all (Superadmin) → ผ่านทันที
 * Level 2:   organization.manage_users + สังกัดองค์กรเดียวกับเอกสาร → ผ่าน
 * Level 2.5: [C3] contract_organizations membership — ถ้า instance.contractId ถูกตั้ง
 *             และ User ไม่อยู่ใน contract นั้น → ForbiddenException (cross-contract block)
 * Level 3:   Assigned Handler (context.assignedUserId === req.user.user_id) → ผ่าน
 * Level 4:   ผู้ใช้ทั่วไป → ForbiddenException
 */
@@ -30,7 +32,8 @@ export class WorkflowTransitionGuard implements CanActivate {
  constructor(
    @InjectRepository(WorkflowInstance)
    private readonly instanceRepo: Repository<WorkflowInstance>,
-    private readonly userService: UserService
+    private readonly userService: UserService,
    private readonly dataSource: DataSource
  ) {}
  async canActivate(context: ExecutionContext): Promise<boolean> {
@@ -67,6 +70,35 @@ export class WorkflowTransitionGuard implements CanActivate {
      return true;
    }
    // Level 2.5: [C3] Contract Membership check — ถ้า instance ผูกกับ contract ใด
    // User ต้องสังกัดองค์กรที่อยู่ใน contract นั้น ป้องกัน cross-contract access
    if (instance.contractId !== null && instance.contractId !== undefined) {
      const userOrgId = user.primaryOrganizationId;
      if (!userOrgId) {
        this.logger.warn(
          `No org for User ${user.user_id} attempting contract-scoped workflow ${instanceId}`
        );
        throw new ForbiddenException({
          userMessage:
            'คุณไม่ได้สังกัดองค์กรใด ไม่สามารถดำเนินการในสัญญานี้ได้',
          recoveryAction: 'ติดต่อ Admin เพื่อกำหนดองค์กร',
        });
      }
      const rows = await this.dataSource.query<[{ cnt: string }]>(
        'SELECT COUNT(*) AS cnt FROM contract_organizations WHERE contract_id = ? AND organization_id = ?',
        [instance.contractId, userOrgId]
      );
      if (Number(rows[0]?.cnt ?? 0) === 0) {
        this.logger.warn(
          `Cross-contract access attempt: User ${user.user_id} (Org ${userOrgId}) on Contract ${instance.contractId} Instance ${instanceId}`
        );
        throw new ForbiddenException({
          userMessage: 'คุณไม่มีสิทธิ์เข้าถึง Workflow ของสัญญานี้',
          recoveryAction: 'ตรวจสอบสิทธิ์กับ Project Admin',
        });
      }
    }
    // Level 3: Assigned Handler — User นี้ถูก Assign มาให้ทำ Step นี้โดยตรง
    const assignedUserId = instance.context?.assignedUserId as
      | number
@@ -116,15 +116,15 @@ export class WorkflowEngineController {
      throw new BadRequestException('Idempotency-Key header is required');
    }
-    // ตรวจ Redis ว่า Request นี้ถูกส่งมาแล้วหรือไม่
+    const userId = req.user?.user_id;
-    const cacheKey = `idempotency:wf:${idempotencyKey}`;
+
    // ตรวจ Redis ว่า Request นี้ถูกส่งมาแล้วหรือไม่ (key ผูกกับ userId ป้องกัน cross-user replay)
    const cacheKey = `idempotency:transition:${idempotencyKey}:${userId}`;
    const cached = await this.cacheManager.get(cacheKey);
    if (cached) {
      return cached; // คืนผลเดิม (Idempotent Response)
    }
    const userId = req.user?.user_id;
    const result = await this.workflowService.processTransition(
      instanceId,
      dto.action,
@@ -1,7 +1,7 @@
 import { Test, TestingModule } from '@nestjs/testing';
 import { WorkflowEngineService } from './workflow-engine.service';
 import { getRepositoryToken } from '@nestjs/typeorm';
-import { DataSource, Repository } from 'typeorm';
+import { DataSource, In, Repository } from 'typeorm';
 import { WorkflowDefinition } from './entities/workflow-definition.entity';
 import {
  WorkflowInstance,
@@ -11,6 +11,7 @@ import { WorkflowHistory } from './entities/workflow-history.entity';
 import { Attachment } from '../../common/file-storage/entities/attachment.entity';
 import { WorkflowDslService } from './workflow-dsl.service';
 import { WorkflowEventService } from './workflow-event.service';
 import { CACHE_MANAGER } from '@nestjs/cache-manager';
 import { NotFoundException } from '../../common/exceptions';
 import { CreateWorkflowDefinitionDto } from './dto/create-workflow-definition.dto';
@@ -96,6 +97,14 @@ describe('WorkflowEngineService', () => {
        { provide: WorkflowDslService, useValue: mockDslService },
        { provide: WorkflowEventService, useValue: mockEventService },
        { provide: DataSource, useValue: mockDataSource },
        {
          provide: CACHE_MANAGER,
          useValue: {
            get: jest.fn().mockResolvedValue(null),
            set: jest.fn().mockResolvedValue(undefined),
            del: jest.fn().mockResolvedValue(undefined),
          },
        },
      ],
    }).compile();
@@ -210,5 +219,103 @@ describe('WorkflowEngineService', () => {
      expect(mockQueryRunner.rollbackTransaction).toHaveBeenCalled();
      expect(mockQueryRunner.release).toHaveBeenCalled();
    });
    // ADR-021 T031: Tests for step-specific attachments
    describe('ADR-021 Step-specific Attachments', () => {
      it('should link attachments to workflow history record', async () => {
        const instanceId = 'inst-1';
        const attachmentPublicIds = ['att-123', 'att-456'];
        const mockInstance = {
          id: instanceId,
          currentState: 'PENDING',
          status: WorkflowStatus.ACTIVE,
          definition: { compiled: mockCompiledWorkflow },
          context: { some: 'data' },
        };
        // Mock the history object with an ID
        const mockHistory = { id: 'history-123' };
        mockQueryRunner.manager.findOne.mockResolvedValue(mockInstance);
        // Mock save to return the history object when called with any entity
        mockQueryRunner.manager.save.mockResolvedValue(mockHistory);
        mockDslService.evaluate.mockReturnValue({
          nextState: 'APPROVED',
          events: [],
        });
        await service.processTransition(
          instanceId,
          'APPROVE',
          1,
          'Test comment',
          {},
          attachmentPublicIds
        );
        expect(mockQueryRunner.manager.update).toHaveBeenCalledWith(
          Attachment,
          { publicId: In(attachmentPublicIds) },
          { workflowHistoryId: 'history-123' }
        );
      });
      it('should skip attachment linking when no attachmentPublicIds provided', async () => {
        const instanceId = 'inst-1';
        const mockInstance = {
          id: instanceId,
          currentState: 'PENDING',
          status: WorkflowStatus.ACTIVE,
          definition: { compiled: mockCompiledWorkflow },
          context: { some: 'data' },
        };
        mockQueryRunner.manager.findOne.mockResolvedValue(mockInstance);
        mockDslService.evaluate.mockReturnValue({
          nextState: 'APPROVED',
          events: [],
        });
        await service.processTransition(instanceId, 'APPROVE', 1);
        expect(mockQueryRunner.manager.update).not.toHaveBeenCalledWith(
          expect.any(Object),
          expect.any(Object),
          expect.objectContaining({ workflowHistoryId: expect.any(String) })
        );
      });
      it('should handle empty attachmentPublicIds array', async () => {
        const instanceId = 'inst-1';
        const mockInstance = {
          id: instanceId,
          currentState: 'PENDING',
          status: WorkflowStatus.ACTIVE,
          definition: { compiled: mockCompiledWorkflow },
          context: { some: 'data' },
        };
        mockQueryRunner.manager.findOne.mockResolvedValue(mockInstance);
        mockDslService.evaluate.mockReturnValue({
          nextState: 'APPROVED',
          events: [],
        });
        await service.processTransition(
          instanceId,
          'APPROVE',
          1,
          'Test comment',
          {},
          [] // Empty array
        );
        expect(mockQueryRunner.manager.update).not.toHaveBeenCalledWith(
          expect.any(Object),
          expect.any(Object),
          expect.objectContaining({ workflowHistoryId: expect.any(String) })
        );
      });
    });
  });
 });
@@ -1,6 +1,8 @@
 // File: src/modules/workflow-engine/workflow-engine.service.ts
-import { Injectable, Logger } from '@nestjs/common';
+import { Injectable, Inject, Logger } from '@nestjs/common';
 import { CACHE_MANAGER } from '@nestjs/cache-manager';
 import type { Cache } from 'cache-manager';
 import { NotFoundException, WorkflowException } from '../../common/exceptions';
 import { InjectRepository } from '@nestjs/typeorm';
 import { DataSource, In, Repository } from 'typeorm';
@@ -55,7 +57,8 @@ export class WorkflowEngineService {
    private readonly attachmentRepo: Repository<Attachment>,
    private readonly dslService: WorkflowDslService,
    private readonly eventService: WorkflowEventService, // [NEW] Inject Service
-    private readonly dataSource: DataSource // ใช้สำหรับ Transaction
+    private readonly dataSource: DataSource, // ใช้สำหรับ Transaction
    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache // ADR-021 T024: History cache
  ) {}
  // =================================================================
@@ -215,12 +218,18 @@ export class WorkflowEngineService {
    }
    // 3. สร้าง Instance
    // [C3] Extract contractId from context to persist as searchable column
    const contractId =
      typeof initialContext.contractId === 'number'
        ? initialContext.contractId
        : null;
    const instance = this.instanceRepo.create({
      definition,
      entityType,
      entityId,
      currentState: initialState,
      status: WorkflowStatus.ACTIVE,
      contractId,
      context: initialContext,
    });
@@ -364,19 +373,22 @@ export class WorkflowEngineService {
          payload,
        },
      });
-      await queryRunner.manager.save(history);
+      const savedHistory = await queryRunner.manager.save(history);
      // ADR-021: ผูกไฟล์แนบประจำ Step นี้ (ทำในตัว Transaction เดียวกัน)
      if (attachmentPublicIds && attachmentPublicIds.length > 0) {
        await queryRunner.manager.update(
          Attachment,
          { publicId: In(attachmentPublicIds) },
-          { workflowHistoryId: history.id }
+          { workflowHistoryId: savedHistory.id }
        );
      }
      await queryRunner.commitTransaction();
      // ADR-021 T043: Invalidate Workflow History cache หลัง transition สำเร็จ
      void this.cacheManager.del(`wf:history:${instanceId}`);
      // [NEW] เก็บค่าไว้ Dispatch หลัง Commit
      eventsToDispatch = evaluation.events;
      updatedContext = context;
@@ -443,6 +455,12 @@ export class WorkflowEngineService {
  async getHistoryWithAttachments(
    instanceId: string
  ): Promise<WorkflowHistoryItemDto[]> {
    // ADR-021 T024: Redis cache — ป้องกัน N+1 บน repeated view (TTL 1h)
    const cacheKey = `wf:history:${instanceId}`;
    const cached =
      await this.cacheManager.get<WorkflowHistoryItemDto[]>(cacheKey);
    if (cached) return cached;
    const histories = await this.historyRepo.find({
      where: { instanceId },
      order: { createdAt: 'ASC' },
@@ -474,7 +492,7 @@ export class WorkflowEngineService {
      {}
    );
-    return histories.map((h) => ({
+    const result: WorkflowHistoryItemDto[] = histories.map((h) => ({
      id: h.id,
      fromState: h.fromState,
      toState: h.toState,
@@ -490,6 +508,10 @@ export class WorkflowEngineService {
      })),
      createdAt: h.createdAt.toISOString(),
    }));
    // Cache result (TTL 1h = 3_600_000 ms)
    await this.cacheManager.set(cacheKey, result, 3_600_000);
    return result;
  }
  // =================================================================
@@ -1,6 +1,6 @@
 # Tasks: Transmittals + Circulation Complete Integration (v1.8.7 Post-ADR-021)
-**Branch**: `001-transmittals-circulation` | **Total Tasks**: 18 | **Phase**: Implementation
+**Branch**: `001-transmittals-circulation` | **Total Tasks**: 18 | **Phase**: ✅ Complete (v1.8.7)
 ---
@@ -10,49 +10,49 @@
 - **File**: `backend/src/modules/workflow-engine/workflow-engine.service.ts`
 - **Action**: Add method that queries `WorkflowInstance` by `entityType + entityId`; returns `{ id, currentState, availableActions? } | null`
 - **Dependencies**: none
- **Status**: [ ]
+- **Status**: [x]
 ### B2 — TransmittalService: Expose `workflowInstanceId` in `findOneByUuid()`
 - **File**: `backend/src/modules/transmittal/transmittal.service.ts`
 - **Action**: Call `workflowEngine.getInstanceByEntity('transmittal', correspondenceId.toString())` and merge `workflowInstanceId`, `workflowState` into response
 - **Dependencies**: B1
- **Status**: [ ]
+- **Status**: [x]
 ### B3 — TransmittalService: Add `purpose` filter to `findAll()`
 - **File**: `backend/src/modules/transmittal/transmittal.service.ts`
 - **Action**: Add `purpose?: string` to `SearchTransmittalDto` and apply `andWhere` in `findAll()`
 - **Dependencies**: none (parallel with B1)
- **Status**: [ ]
+- **Status**: [x]
 ### B4 — TransmittalService: Add `submit()` with EC-RFA-004 validation
 - **File**: `backend/src/modules/transmittal/transmittal.service.ts`
 - **Action**: New `submit(uuid, user)` method; fetches all `transmittal_items`, checks each item's correspondence current revision status — throws `422 ValidationException` if any is `DRAFT`; then calls `workflowEngine.createInstance('TRANSMITTAL_FLOW_V1', 'transmittal', ...)` and transitions with `SUBMIT`
 - **Dependencies**: B1
- **Status**: [ ]
+- **Status**: [x]
 ### B5 — TransmittalController: Add `POST /:uuid/submit` endpoint
 - **File**: `backend/src/modules/transmittal/transmittal.controller.ts`
 - **Action**: Add endpoint with `@RequirePermission('document.manage')`, `@Audit('transmittal.submit', 'transmittal')`
 - **Dependencies**: B4
- **Status**: [ ]
+- **Status**: [x]
 ### B6 — CirculationService: Expose `workflowInstanceId` in `findOneByUuid()`
 - **File**: `backend/src/modules/circulation/circulation.service.ts`
 - **Action**: Call `workflowEngine.getInstanceByEntity('circulation', circulation.id.toString())`, merge into response; also compute `isOverdue` per routing based on `deadline_date`
 - **Dependencies**: B1
- **Status**: [ ]
+- **Status**: [x]
 ### B7 — CirculationService: Add `reassignRouting()` (EC-CIRC-001)
 - **File**: `backend/src/modules/circulation/circulation.service.ts`
 - **Action**: Fetch routing, verify user has Document Control permission, resolve `newAssigneeUuid` → INT via `uuidResolver.resolveUserId()`, update `routing.assignedTo`, write audit log
 - **Dependencies**: none
- **Status**: [ ]
+- **Status**: [x]
 ### B8 — CirculationService: Add `forceClose()` (EC-CIRC-002)
 - **File**: `backend/src/modules/circulation/circulation.service.ts`
 - **Action**: Require `reason` (non-empty), update all PENDING routings to `CANCELLED`, set `circulation.statusCode = 'CANCELLED'`, write audit log entry; use `queryRunner` for atomicity
 - **Dependencies**: none
- **Status**: [ ]
+- **Status**: [x]
 ### B9 — CirculationController: Add reassign + force-close endpoints
 - **File**: `backend/src/modules/circulation/circulation.controller.ts`
@@ -60,7 +60,7 @@
  - `PATCH /:uuid/routing/:routingId/reassign` — `@RequirePermission('circulation.manage')`
  - `POST /:uuid/force-close` — `@RequirePermission('circulation.manage')`
 - **Dependencies**: B7, B8
- **Status**: [ ]
+- **Status**: [x]
 ---
@@ -70,25 +70,25 @@
 - **File**: `frontend/types/transmittal.ts`
 - **Action**: Add `workflowInstanceId?: string`, `workflowState?: string`, `availableActions?: string[]` to `Transmittal` interface; add `purpose?: string` to `SearchTransmittalDto`; no `any` types (ADR-019)
 - **Dependencies**: none (parallel with Phase 1)
- **Status**: [ ]
+- **Status**: [x]
 ### F2 — Update `types/circulation.ts`
 - **File**: `frontend/types/circulation.ts`
 - **Action**: Add `workflowInstanceId?: string`, `workflowState?: string`, `availableActions?: string[]` to `Circulation`; add `deadline?: string`, `assigneeType?: 'MAIN' | 'ACTION' | 'INFORMATION'` to `CirculationRouting`
 - **Dependencies**: none
- **Status**: [ ]
+- **Status**: [x]
 ### F3 — Create `hooks/use-transmittal.ts`
 - **File**: `frontend/hooks/use-transmittal.ts`
 - **Action**: Create `useTransmittal(uuid: string | undefined)` with `queryKey: ['transmittal', uuid]`, `staleTime: 60_000`; export `transmittalKeys` query key factory
 - **Dependencies**: F1
- **Status**: [ ]
+- **Status**: [x]
 ### F4 — Update `hooks/use-circulation.ts`
 - **File**: `frontend/hooks/use-circulation.ts`
 - **Action**: Add `useCirculation(uuid: string | undefined)` hook with `queryKey: ['circulation', uuid]`, `staleTime: 60_000`
 - **Dependencies**: F2
- **Status**: [ ]
+- **Status**: [x]
 ---
@@ -103,7 +103,7 @@
  - Pass `instanceId`, `workflowState`, `availableActions`, `pendingAttachmentIds` to `IntegratedBanner`
  - Pass `history`, `currentState`, `isLoading`, `error`, `onAttachmentsChange` to `WorkflowLifecycle` in Workflow tab
 - **Dependencies**: F3, F1
- **Status**: [ ]
+- **Status**: [x]
 ### F6 — Wire Circulation detail page
 - **File**: `frontend/app/(dashboard)/circulation/[uuid]/page.tsx`
@@ -116,7 +116,7 @@
  - Add Overdue badge to routing rows where `isOverdue(routing.deadline)` is true
  - Replace hardcoded "Complete" button with proper workflow action
 - **Dependencies**: F4, F2
- **Status**: [ ]
+- **Status**: [x]
 ---
@@ -126,13 +126,13 @@
 - **File**: `frontend/app/(dashboard)/transmittals/page.tsx`
 - **Action**: Add `purpose` select filter (FOR_APPROVAL / FOR_INFORMATION / FOR_REVIEW / OTHER) passing to `transmittalService.getAll()`. Read current page to assess if pagination works.
 - **Dependencies**: F1
- **Status**: [ ]
+- **Status**: [x]
 ### I1 — i18n keys for Transmittal/Circulation workflow
 - **Files**: `public/locales/th/*.json`, `public/locales/en/*.json`
 - **Action**: Check `use-translations.ts` for key lookup pattern; add missing keys: `transmittal.purpose.*`, `circulation.status.*`, `circulation.overdue`, `circulation.forceClose.*`, `circulation.reassign.*`
 - **Dependencies**: F5, F6
- **Status**: [ ]
+- **Status**: [ ] *(low priority — pending)*
 ---
@@ -142,13 +142,13 @@
 - **File**: `backend/src/modules/transmittal/transmittal.service.spec.ts` (create if needed)
 - **Action**: Test `submit()` throws `ValidationException` when item correspondence is DRAFT; test passes when all items are SUBMITTED
 - **Dependencies**: B4
- **Status**: [ ]
+- **Status**: [x]
 ### T2 — Circulation service edge-case unit tests
 - **File**: `backend/src/modules/circulation/circulation.service.spec.ts` (create if needed)
 - **Action**: Test `reassignRouting()` — permission check, assignment update; test `forceClose()` — all pending routings cancelled, reason logged; test `isOverdue` helper (EC-CIRC-003)
 - **Dependencies**: B7, B8
- **Status**: [ ]
+- **Status**: [x]
 ---
@@ -1,9 +1,9 @@
 ---
 title: 'Data & Storage: Data Dictionary and Data Model Architecture'
-version: 1.8.0
+version: 1.8.7
 status: released
 owner: Nattanin Peancharoen
-last_updated: 2026-02-28
+last_updated: 2026-04-14
 related:
  - specs/01-requirements/02-architecture.md
  - specs/01-requirements/03-functional-requirements.md
@@ -1715,23 +1715,32 @@ erDiagram
 **Purpose**: เก็บสถานะของ Workflow ที่กำลังรันอยู่จริง (Runtime)
 | Column Name   | Data Type   | Constraints                | Description                                                                                     |
-| :------------ | :---------- | :--------------- | :--------------------------------------------- |
+| :------------ | :---------- | :------------------------- | :---------------------------------------------------------------------------------------------- |
 | id            | CHAR(36)    | PK, UUID                   | Unique Instance ID                                                                              |
 | definition_id | CHAR(36)    | FK, NOT NULL               | อ้างอิง Definition ที่ใช้                                                                           |
-| entity_type   | VARCHAR(50) | NOT NULL         | ประเภทเอกสาร (rfa_revision, correspondence...) |
+| **contract_id** | **INT**   | **NULL, FK**               | **[delta-07 / ADR-021 C3]** Contract ที่ Workflow นี้สังกัด (NULL = org-scoped เช่น Circulation) |
 | entity_type   | VARCHAR(50) | NOT NULL                   | ประเภทเอกสาร (rfa, correspondence, transmittal, circulation)                             |
 | entity_id     | VARCHAR(50) | NOT NULL                   | ID ของเอกสาร                                                                                    |
 | current_state | VARCHAR(50) | NOT NULL                   | สถานะปัจจุบัน                                                                                   |
 | status        | ENUM        | DEFAULT 'ACTIVE'           | ACTIVE, COMPLETED, CANCELLED, TERMINATED                                                        |
-| context       | JSON        | NULL             | ตัวแปร Context สำหรับตัดสินใจ                  |
+| context       | JSON        | NULL                       | ตัวแปร Context สำหรับตัดสินใจ (รวม contractId, projectId, initiatorId เป็นต้น)                      |
 | created_at    | TIMESTAMP   | DEFAULT NOW                | เวลาที่สร้าง                                                                                    |
 | updated_at    | TIMESTAMP   | ON UPDATE                  | เวลาที่อัปเดตล่าสุด                                                                         |
 **Business Rules**:
 - `contract_id` = NOT NULL → contract-scoped workflow (RFA, Correspondence, Transmittal) — Guard Level 2.5 ตรวจ membership
 - `contract_id` = NULL → org-scoped workflow (Circulation) — Guard Level 2 (org match only)
 - `context.contractId` mirrors `contract_id` column — redundant by design (ฟิลเตอร์ได้ทั้งสองทาง)
 **Indexes**:
 - PRIMARY KEY (id)
 - FOREIGN KEY (definition_id) REFERENCES workflow_definitions(id) ON DELETE CASCADE
 - **FOREIGN KEY (contract_id) REFERENCES contracts(id) ON DELETE SET NULL** [delta-07]
 - INDEX (entity_type, entity_id)
 - INDEX (current_state)
 - **INDEX (contract_id, entity_type, status)** — `idx_wf_inst_contract` [delta-07]
 ---
@@ -1980,6 +1989,7 @@ PARTITION BY RANGE (YEAR(created_at)) (
 | document_number_counters | (project_id, correspondence_type_id, reset_scope) | Running number generation      |
 | workflow_instances       | (entity_type, entity_id)                          | Workflow lookup by document ID                            |
 | workflow_instances       | (current_state)                                   | Monitor active workflows                                  |
 | workflow_instances       | (contract_id, entity_type, status)                | **[delta-07]** Guard contract-membership + dashboard filter |
 ### 13.2 Unique Constraints
@@ -0,0 +1,87 @@
 -- ==========================================================
 -- Delta 06: Add CIRCULATION_FLOW_V1 Workflow Definition
 -- ==========================================================
 -- Purpose  : สร้าง Workflow Definition สำหรับใบเวียนภายใน (Circulation)
 -- Required : ก่อน delta นี้ ตาราง workflow_definitions ต้องมีอยู่แล้ว (ADR-001)
 -- Renamed  : CIRCULATION_INTERNAL_V1 → CIRCULATION_FLOW_V1 (ตาม naming convention)
 -- States   :
 --   DRAFT    (initial) → START → ROUTING
 --   ROUTING            → COMPLETE    → COMPLETED (terminal)
 --   ROUTING            → FORCE_CLOSE → CANCELLED (terminal)
 -- ==========================================================
 INSERT INTO `workflow_definitions` (
    `id`,
    `workflow_code`,
    `version`,
    `description`,
    `dsl`,
    `compiled`,
    `is_active`,
    `created_at`,
    `updated_at`
  )
 VALUES (
    UUID(),
    'CIRCULATION_FLOW_V1',
    1,
    'Circulation Workflow — DRAFT → ROUTING → COMPLETED | CANCELLED',
    JSON_OBJECT(
      'workflow', 'CIRCULATION_FLOW_V1',
      'version', 1,
      'states', JSON_ARRAY(
        JSON_OBJECT(
          'name', 'DRAFT',
          'initial', TRUE,
          'on', JSON_OBJECT(
            'START', JSON_OBJECT('to', 'ROUTING')
          )
        ),
        JSON_OBJECT(
          'name', 'ROUTING',
          'on', JSON_OBJECT(
            'COMPLETE',    JSON_OBJECT('to', 'COMPLETED'),
            'FORCE_CLOSE', JSON_OBJECT('to', 'CANCELLED')
          )
        ),
        JSON_OBJECT('name', 'COMPLETED', 'terminal', TRUE),
        JSON_OBJECT('name', 'CANCELLED', 'terminal', TRUE)
      )
    ),
    JSON_OBJECT(
      'initialState', 'DRAFT',
      'states', JSON_OBJECT(
        'DRAFT', JSON_OBJECT(
          'initial', TRUE,
          'terminal', FALSE,
          'transitions', JSON_OBJECT(
            'START', JSON_OBJECT('to', 'ROUTING', 'events', JSON_ARRAY())
          )
        ),
        'ROUTING', JSON_OBJECT(
          'initial', FALSE,
          'terminal', FALSE,
          'transitions', JSON_OBJECT(
            'COMPLETE',    JSON_OBJECT('to', 'COMPLETED', 'events', JSON_ARRAY()),
            'FORCE_CLOSE', JSON_OBJECT('to', 'CANCELLED',  'events', JSON_ARRAY())
          )
        ),
        'COMPLETED', JSON_OBJECT(
          'initial', FALSE,
          'terminal', TRUE,
          'transitions', JSON_OBJECT()
        ),
        'CANCELLED', JSON_OBJECT(
          'initial', FALSE,
          'terminal', TRUE,
          'transitions', JSON_OBJECT()
        )
      )
    ),
    TRUE,
    NOW(),
    NOW()
  );
 -- Verify
 -- SELECT workflow_code, version, is_active FROM workflow_definitions WHERE workflow_code = 'CIRCULATION_FLOW_V1';
@@ -0,0 +1,22 @@
 -- ==========================================================
 -- Delta 07: Add contract_id to workflow_instances (C3 Contract Scoping)
 -- ==========================================================
 -- Purpose  : เพิ่ม contract_id FK ใน workflow_instances เพื่อให้ Workflow Engine
 --            แยก scope ตาม Contract ได้ (C3 ตาม analysis ADR-021)
 -- Why      : RFA / Correspondence / Transmittal → contract-scoped (contractId ถูกตั้ง)
 --            Circulation → organization-scoped (contractId = NULL, ใช้ Level 2 org check)
 --            Guard Level 2.5 ตรวจ contract_organizations membership เฉพาะ contractId ≠ NULL
 -- ADR      : ADR-009 (no migrations — direct SQL only)
 -- ==========================================================
 ALTER TABLE workflow_instances
 ADD COLUMN contract_id INT NULL COMMENT 'Contract ที่ Workflow นี้เป็นส่วนหนึ่ง (NULL = global/legacy)'
 AFTER definition_id,
  ADD CONSTRAINT fk_wf_inst_contract FOREIGN KEY (contract_id) REFERENCES contracts (id) ON DELETE
 SET NULL;
 -- Index สำหรับ Guard lookup: "Instances ทั้งหมดในสัญญา X"
 CREATE INDEX idx_wf_inst_contract ON workflow_instances (contract_id, entity_type, STATUS);
 -- Verify
 -- DESCRIBE workflow_instances;
 -- SHOW INDEX FROM workflow_instances WHERE Key_name = 'idx_wf_inst_contract';
@@ -1369,6 +1369,8 @@ CREATE INDEX idx_workflow_active ON workflow_definitions (workflow_code, is_acti
 CREATE TABLE workflow_instances (
  id CHAR(36) NOT NULL PRIMARY KEY COMMENT 'UUID ของ Instance',
  definition_id CHAR(36) NOT NULL COMMENT 'อ้างอิง Definition ที่ใช้',
  contract_id INT NULL COMMENT 'Contract ที่ Workflow นี้เป็นส่วนหนึ่ง (NULL = org-scoped หรือ legacy)',
  -- [delta-07]
  entity_type VARCHAR(50) NOT NULL COMMENT 'ประเภทเอกสาร (rfa_revision, correspondence_revision, circulation)',
  entity_id VARCHAR(50) NOT NULL COMMENT 'ID ของเอกสาร (String/Int)',
  current_state VARCHAR(50) NOT NULL COMMENT 'สถานะปัจจุบัน',
@@ -1381,11 +1383,15 @@ CREATE TABLE workflow_instances (
  context JSON NULL COMMENT 'ตัวแปร Context สำหรับตัดสินใจ',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  CONSTRAINT fk_wf_inst_def FOREIGN KEY (definition_id) REFERENCES workflow_definitions (id) ON DELETE CASCADE
+  CONSTRAINT fk_wf_inst_def FOREIGN KEY (definition_id) REFERENCES workflow_definitions (id) ON DELETE CASCADE,
  CONSTRAINT fk_wf_inst_contract FOREIGN KEY (contract_id) REFERENCES contracts (id) ON DELETE
  SET NULL -- [delta-07]
 ) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_unicode_ci COMMENT = 'ตารางเก็บสถานะการเดินเรื่องของเอกสาร';
 CREATE INDEX idx_wf_inst_entity ON workflow_instances (entity_type, entity_id);
 CREATE INDEX idx_wf_inst_contract ON workflow_instances (contract_id, entity_type, STATUS);
 CREATE INDEX idx_wf_inst_state ON workflow_instances (current_state);
 -- 3. ตารางเก็บประวัติ (Audit Log / History)
@@ -221,7 +221,7 @@ export interface WorkflowTransitionWithAttachmentsDto {
         Body: { action, comment, attachmentPublicIds: [uuid1, uuid2] }
     │
     ▼
-[WorkflowTransitionGuard] — RBAC check (4-Level)
+[WorkflowTransitionGuard] — RBAC check (4.5-Level: Superadmin / Org Admin / Level 2.5 Contract Membership / Assigned Handler)
     │ pass
     ▼
 [WorkflowEngineService.processTransition()]
@@ -253,15 +253,21 @@ export interface WorkflowTransitionWithAttachmentsDto {
 ## 7. Entity Relationship Diagram
 ```
 contracts
  │ 1
  │ (FK, nullable) [delta-07]
  ▼ N
 workflow_definitions
       │ 1
       │ has many
       ▼ N
-workflow_instances ──────────────── documents (RFA/Corr/etc)
+workflow_instances ────────────────── documents (RFA/Corr/Transmittal/Circulation)
-       │ 1                                 (entityType + entityId)
+  contract_id: INT NULL [delta-07]       (entityType + entityId)
  (NULL = org-scoped e.g. Circulation)
       │ 1
       │ has many
       ▼ N
-workflow_histories ◄─────────────────────────────┐
+workflow_histories ◄─────────────────────────┤
       │ id: CHAR(36) UUID                        │
       │                                          │
       │ ◄── attachments.workflow_history_id (FK, nullable)
@@ -281,5 +287,4 @@ attachments
 | `attachments` | `idx_att_wfhist_created` (NEW) | `(workflow_history_id, created_at)` | Fetch step attachments sorted by date |
 | `workflow_histories` | `idx_wf_hist_instance` (existing) | `(instance_id)` | Fetch all steps for a workflow instance |
 | `workflow_histories` | `idx_wf_hist_user` (existing) | `(action_by_user_id)` | Audit queries per user |
-
+| `workflow_instances` | `idx_wf_inst_contract` (NEW — delta-07) | `(contract_id, entity_type, status)` | Guard contract-membership lookup + dashboard queries per contract |
 **No additional indexes required** — the composite `(workflow_history_id, created_at)` covers the primary access pattern.
@@ -111,8 +111,8 @@ frontend/hooks/
 # 🟡 Frontend — Page Refactors (use new components)
 frontend/app/(dashboard)/rfas/[uuid]/page.tsx        [MODIFY — integrate IntegratedBanner + WorkflowLifecycle]
 frontend/app/(dashboard)/correspondences/[uuid]/page.tsx [MODIFY — same]
-frontend/app/(dashboard)/transmittals/[uuid]/page.tsx    [MODIFY — same, if detail page exists]
+frontend/app/(dashboard)/transmittals/[uuid]/page.tsx    [MODIFY — same as RFA/Correspondence]
-frontend/app/(dashboard)/circulation/[uuid]/page.tsx     [MODIFY — same, if detail page exists]
+frontend/app/(dashboard)/circulation/[uuid]/page.tsx     [MODIFY — same as RFA/Correspondence]
 ```
 ---
@@ -135,6 +135,8 @@ _No constitution violations. Architecture is additive (Nullable FK, extended DTO
 | Existing visualizer reuse | `components/custom/workflow-visualizer.tsx` is **horizontal** — new `workflow-lifecycle.tsx` is **vertical** | Different layout semantics; keep both |
 | Idempotency storage | Redis key: `idempotency:transition:{idempotencyKey}:{userId}` → serialized response (TTL: 24h) | Per .windsurfrules Security Rule #1 + ADR-021 §5.1 |
 | Cache invalidation | On `processTransition()` success → invalidate Redis key `wf:history:{instanceId}` | ADR-021 §9 — override TTL on state change |
 | Drawing workflow type (DDW/SDW/ADW) | Drawing types are **RFA subtypes** — all use single `RFA_APPROVAL` workflow code | Removing per-type codes (`RFA_DDW` etc.) eliminates dead workflow definitions; drawing metadata lives on the document, not the workflow |
 | Workflow scope per document type | RFA / Correspondence / Transmittal → **contract-scoped** (`contract_id` on `workflow_instances`); Circulation → **org-scoped** (`contract_id = NULL`) | Workflow Guard Level 2.5 blocks cross-contract access; Circulation is internal org document |
 ---
@@ -221,6 +223,8 @@ Response: WorkflowHistoryItem[] with nested attachments[] per step
 | F6 | Create `FilePreviewModal` component | `components/common/file-preview-modal.tsx` | F1 |
 | F7 | Refactor RFA detail page — integrate new components | `rfas/[uuid]/page.tsx` | F3–F6 |
 | F8 | Refactor Correspondence detail page — integrate new components | `correspondences/[uuid]/page.tsx` | F3–F6 |
 | F9 | Refactor Transmittal detail page — integrate new components | `transmittals/[uuid]/page.tsx` | F3–F6 |
 | F10 | Refactor Circulation detail page — integrate new components | `circulation/[uuid]/page.tsx` | F3–F6 |
 ### 🟢 GUIDELINES (after F7/F8)
@@ -45,12 +45,12 @@
 **⚠️ CRITICAL**: T004 must complete before T005–T009. T005–T007 must complete before Phase 5 (US3).
- [ ] T004 Apply SQL delta — create `specs/03-Data-and-Storage/deltas/04-add-workflow-history-id-to-attachments.sql` and run against dev DB per quickstart.md Step 1
+- [x] T004 Apply SQL delta — create `specs/03-Data-and-Storage/deltas/04-add-workflow-history-id-to-attachments.sql` and run against dev DB per quickstart.md Step 1
- [ ] T005 [P] Update `backend/src/common/file-storage/entities/attachment.entity.ts` — add `workflowHistoryId?: string` column + lazy `@ManyToOne(() => WorkflowHistory)` relation (data-model.md §2.1)
+- [x] T005 [P] Update `backend/src/common/file-storage/entities/attachment.entity.ts` — add `workflowHistoryId?: string` column + lazy `@ManyToOne(() => WorkflowHistory)` relation (data-model.md §2.1)
- [ ] T006 [P] Update `backend/src/modules/workflow-engine/entities/workflow-history.entity.ts` — add lazy `@OneToMany(() => Attachment)` relation + required imports (data-model.md §2.2)
+- [x] T006 [P] Update `backend/src/modules/workflow-engine/entities/workflow-history.entity.ts` — add lazy `@OneToMany(() => Attachment)` relation + required imports (data-model.md §2.2)
- [ ] T007 Update `backend/src/modules/workflow-engine/dto/workflow-transition.dto.ts` — add `attachmentPublicIds?: string[]` with `@IsArray()`, `@IsUUID('all', { each: true })`, `@ArrayMaxSize(20)`, `@IsOptional()` (data-model.md §3.1)
+- [x] T007 Update `backend/src/modules/workflow-engine/dto/workflow-transition.dto.ts` — add `attachmentPublicIds?: string[]` with `@IsArray()`, `@IsUUID('all', { each: true })`, `@ArrayMaxSize(20)`, `@IsOptional()` (data-model.md §3.1)
- [ ] T008 Create `backend/src/modules/workflow-engine/guards/workflow-transition.guard.ts` — implement 4-Level RBAC: Superadmin (`system.manage_all`) → Org Admin → Assigned Handler → Forbidden (quickstart.md Step 4; contracts/workflow-transition.yaml §403)
+- [x] T008 Create `backend/src/modules/workflow-engine/guards/workflow-transition.guard.ts` — implement 4-Level RBAC: Superadmin (`system.manage_all`) → Org Admin → Assigned Handler → Forbidden (quickstart.md Step 4; contracts/workflow-transition.yaml §403)
- [ ] T009 Register `WorkflowTransitionGuard` as provider in `backend/src/modules/workflow-engine/workflow-engine.module.ts`
+- [x] T009 Register `WorkflowTransitionGuard` as provider in `backend/src/modules/workflow-engine/workflow-engine.module.ts`
 **Checkpoint**: Foundation complete — `pnpm tsc --noEmit` in backend must pass before proceeding to Phase 5.
@@ -71,13 +71,13 @@ cd frontend && pnpm test --run --reporter=verbose components/workflow/integrated
 ### Implementation for User Story 1
- [ ] T010 [P] [US1] Add `WorkflowPriority` enum and `WorkflowHistoryItem` interface to `frontend/types/workflow.ts` (data-model.md §5.1)
+- [x] T010 [P] [US1] Add `WorkflowPriority` enum and `WorkflowHistoryItem` interface to `frontend/types/workflow.ts` (data-model.md §5.1)
- [ ] T011 [P] [US1] Add `WorkflowTransitionWithAttachmentsDto` interface to `frontend/types/dto/workflow-engine/workflow-engine.dto.ts` (data-model.md §5.2)
+- [x] T011 [P] [US1] Add `WorkflowTransitionWithAttachmentsDto` interface to `frontend/types/dto/workflow-engine/workflow-engine.dto.ts` (data-model.md §5.2)
- [ ] T012 [US1] Create `frontend/components/workflow/integrated-banner.tsx` — props: `{ documentNo, subject, status, priority?, currentState, availableActions, onAction, isLoading? }`, render Priority badge with Tailwind color map from research.md §8 (URGENT=red, HIGH=orange, MEDIUM=yellow, LOW=green), render `WorkflowActionButtons` per `availableActions` array
+- [x] T012 [US1] Create `frontend/components/workflow/integrated-banner.tsx` — props: `{ documentNo, subject, status, priority?, currentState, availableActions, onAction, isLoading? }`, render Priority badge with Tailwind color map from research.md §8 (URGENT=red, HIGH=orange, MEDIUM=yellow, LOW=green), render `WorkflowActionButtons` per `availableActions` array
- [ ] T013 [US1] Update `frontend/app/(dashboard)/rfas/[uuid]/page.tsx` — replace existing header section with `<IntegratedBanner>` using RFA data fields (quickstart.md Step 10)
+- [x] T013 [US1] Update `frontend/app/(dashboard)/rfas/[uuid]/page.tsx` — replace existing header section with `<IntegratedBanner>` using RFA data fields (quickstart.md Step 10)
- [ ] T014 [US1] Update `frontend/app/(dashboard)/correspondences/[uuid]/page.tsx` — same integration as T013 using Correspondence data fields
+- [x] T014 [US1] Update `frontend/app/(dashboard)/correspondences/[uuid]/page.tsx` — same integration as T013 using Correspondence data fields
- [ ] T015 [US1] Update `frontend/app/(dashboard)/transmittals/[uuid]/page.tsx` — same integration as T013 using Transmittal data fields (if detail page has a header section)
+- [x] T015 [US1] Update `frontend/app/(dashboard)/transmittals/[uuid]/page.tsx` — same integration as T013 using Transmittal data fields
- [ ] T016 [US1] Update `frontend/app/(dashboard)/circulation/[uuid]/page.tsx` — same integration as T013 using Circulation data fields (if detail page has a header section)
+- [x] T016 [US1] Update `frontend/app/(dashboard)/circulation/[uuid]/page.tsx` — same integration as T013 using Circulation data fields
 **Checkpoint**: `IntegratedBanner` renders correctly on RFA and Correspondence detail pages. Priority badge and action buttons visible. `pnpm tsc --noEmit` passes.
@@ -98,12 +98,12 @@ cd frontend && pnpm test --run components/workflow/workflow-lifecycle
 ### Implementation for User Story 2
- [ ] T017 [P] [US2] Create `frontend/components/workflow/workflow-lifecycle.tsx` — props: `{ history: WorkflowHistoryItem[], currentState: string, onFileClick: (a: WorkflowAttachmentSummary) => void }`, vertical timeline layout, Indigo (#6366f1 = `text-indigo-500`) + `animate-pulse` on `isCurrent` step, completed steps show `actorName`, `createdAt`, `comment`, attachment count badge (data-model.md §5.1)
+- [x] T017 [P] [US2] Create `frontend/components/workflow/workflow-lifecycle.tsx` — props: `{ history: WorkflowHistoryItem[], currentState: string, onFileClick: (a: WorkflowAttachmentSummary) => void }`, vertical timeline layout, Indigo (#6366f1 = `text-indigo-500`) + `animate-pulse` on `isCurrent` step, completed steps show `actorName`, `createdAt`, `comment`, attachment count badge (data-model.md §5.1)
- [ ] T018 [P] [US2] Add `workflowHistory` query to relevant hooks — update `frontend/hooks/use-rfa.ts` (or equivalent) to fetch `GET /workflow-engine/instances/:id/history` using TanStack Query key `['workflow-history', instanceId]`; add same to `frontend/hooks/use-correspondence.ts`
+- [x] T018 [P] [US2] Add `workflowHistory` query to relevant hooks — update `frontend/hooks/use-rfa.ts`, `frontend/hooks/use-correspondence.ts`, `frontend/hooks/use-transmittal.ts`, and `frontend/hooks/use-circulation.ts` to fetch `GET /workflow-engine/instances/:id/history` using TanStack Query key `['workflow-history', instanceId]`
- [ ] T019 [US2] Add `WorkflowLifecycle` tab to `frontend/app/(dashboard)/rfas/[uuid]/page.tsx` inside existing `<Tabs>` (or add Tabs if missing) — pass `rfa.workflowHistory` and `currentState` props
+- [x] T019 [US2] Add `WorkflowLifecycle` tab to `frontend/app/(dashboard)/rfas/[uuid]/page.tsx` inside existing `<Tabs>` (or add Tabs if missing) — pass `rfa.workflowHistory` and `currentState` props
- [ ] T020 [US2] Add `WorkflowLifecycle` tab to `frontend/app/(dashboard)/correspondences/[uuid]/page.tsx` — same as T019
+- [x] T020 [US2] Add `WorkflowLifecycle` tab to `frontend/app/(dashboard)/correspondences/[uuid]/page.tsx` — same as T019
- [ ] T021 [US2] Add `WorkflowLifecycle` tab to `frontend/app/(dashboard)/transmittals/[uuid]/page.tsx` — same as T019 (if applicable)
+- [x] T021 [US2] Add `WorkflowLifecycle` tab to `frontend/app/(dashboard)/transmittals/[uuid]/page.tsx` — same as T019
- [ ] T022 [US2] Add `WorkflowLifecycle` tab to `frontend/app/(dashboard)/circulation/[uuid]/page.tsx` — same as T019 (if applicable)
+- [x] T022 [US2] Add `WorkflowLifecycle` tab to `frontend/app/(dashboard)/circulation/[uuid]/page.tsx` — same as T019
 **Checkpoint**: Workflow tab visible on RFA/Correspondence pages. Current step Indigo+pulse. Completed steps show actor/date. No TypeScript errors. `pnpm lint` passes.
@@ -129,15 +129,15 @@ cd frontend && pnpm test --run hooks/use-workflow-action
 ### Implementation for User Story 3
- [ ] T023 [US3] Extend `backend/src/modules/workflow-engine/workflow-engine.service.ts` — add `attachmentPublicIds: string[] = []` parameter to `processTransition()`, after `queryRunner.commitTransaction()` run bulk UPDATE to set `workflow_history_id = history.id` WHERE `uuid IN (:publicIds) AND is_temporary = false` (quickstart.md Step 5; data-model.md §6)
+- [x] T023 [US3] Extend `backend/src/modules/workflow-engine/workflow-engine.service.ts` — add `attachmentPublicIds: string[] = []` parameter to `processTransition()`, after `queryRunner.commitTransaction()` run bulk UPDATE to set `workflow_history_id = history.id` WHERE `uuid IN (:publicIds) AND is_temporary = false` (quickstart.md Step 5; data-model.md §6)
- [ ] T024 [US3] Add `getHistoryWithAttachments(instanceId: string)` method to `backend/src/modules/workflow-engine/workflow-engine.service.ts` — query `workflow_histories` WHERE `instance_id = :id` ORDER BY `created_at ASC`, eager-load attachments via LEFT JOIN, apply Redis cache key `wf:history:{instanceId}` TTL 3600s, invalidate on `processTransition()` success (research.md §6; contracts/workflow-transition.yaml)
+- [x] T024 [US3] Add `getHistoryWithAttachments(instanceId: string)` method to `backend/src/modules/workflow-engine/workflow-engine.service.ts` — query `workflow_histories` WHERE `instance_id = :id` ORDER BY `created_at ASC`, eager-load attachments via LEFT JOIN, apply Redis cache key `wf:history:{instanceId}` TTL 3600s, invalidate on `processTransition()` success (research.md §6; contracts/workflow-transition.yaml)
- [ ] T025 [US3] Update `backend/src/modules/workflow-engine/workflow-engine.controller.ts` — add `@Headers('Idempotency-Key')` validation to `processTransition()` endpoint (throw `BadRequestException` if missing), add Redis idempotency check/store with key `idempotency:transition:{key}:{userId}` TTL 86400, swap `RbacGuard` for `WorkflowTransitionGuard` on transition endpoint (quickstart.md Step 6)
+- [x] T025 [US3] Update `backend/src/modules/workflow-engine/workflow-engine.controller.ts` — add `@Headers('Idempotency-Key')` validation to `processTransition()` endpoint (throw `BadRequestException` if missing), add Redis idempotency check/store with key `idempotency:transition:{key}:{userId}` TTL 86400, swap `RbacGuard` for `WorkflowTransitionGuard` on transition endpoint (quickstart.md Step 6)
- [ ] T026 [US3] Add `GET /instances/:id/history` endpoint to `backend/src/modules/workflow-engine/workflow-engine.controller.ts` — decorated with `@RequirePermission('document.view')`, calls `workflowService.getHistoryWithAttachments(instanceId)` (contracts/workflow-transition.yaml §/instances/{instanceId}/history)
+- [x] T026 [US3] Add `GET /instances/:id/history` endpoint to `backend/src/modules/workflow-engine/workflow-engine.controller.ts` — decorated with `@RequirePermission('document.view')`, calls `workflowService.getHistoryWithAttachments(instanceId)` (contracts/workflow-transition.yaml §/instances/{instanceId}/history)
- [ ] T027 [P] [US3] Create `frontend/hooks/use-workflow-action.ts` — generates UUIDv7 idempotency key once per action intent (via `useState`), calls `workflowEngineService.transition()` with `Idempotency-Key` header, on success invalidates TanStack Query keys `['workflow-history', instanceId]` + parent document queries (quickstart.md Step 8)
+- [x] T027 [P] [US3] Create `frontend/hooks/use-workflow-action.ts` — generates UUIDv7 idempotency key once per action intent (via `useState`), calls `workflowEngineService.transition()` with `Idempotency-Key` header, on success invalidates TanStack Query keys `['workflow-history', instanceId]` + parent document queries (quickstart.md Step 8)
- [ ] T028 [P] [US3] Add drag-and-drop file upload zone to `frontend/components/workflow/workflow-lifecycle.tsx` — renders only on `isCurrent` step, uses `<input type="file" multiple accept=".pdf,.docx,.xlsx,.dwg,.zip">` + drag events, calls existing Two-Phase upload service on drop, accumulates `publicId`s in local state, passes to `useWorkflowAction` on submit
+- [x] T028 [P] [US3] Add drag-and-drop file upload zone to `frontend/components/workflow/workflow-lifecycle.tsx` — renders only on `isCurrent` step, uses `<input type="file" multiple accept=".pdf,.docx,.xlsx,.dwg,.zip">` + drag events, calls existing Two-Phase upload service on drop, accumulates `publicId`s in local state, passes to `useWorkflowAction` on submit
- [ ] T029 [US3] Wire `useWorkflowAction` into `IntegratedBanner` action buttons in `frontend/components/workflow/integrated-banner.tsx` — `onAction` callback receives `(action, comment, attachmentPublicIds[])` and delegates to hook's `execute()` method; show loading spinner during `isPending`
+- [x] T029 [US3] Wire `useWorkflowAction` into `IntegratedBanner` action buttons in `frontend/components/workflow/integrated-banner.tsx` — `onAction` callback receives `(action, comment, attachmentPublicIds[])` and delegates to hook's `execute()` method; show loading spinner during `isPending`
- [ ] T030 [US3] Add `WorkflowTransitionGuard` unit tests in `backend/src/modules/workflow-engine/guards/workflow-transition.guard.spec.ts` — test all 4 RBAC levels: Superadmin pass, Org Admin same-org pass, Assigned Handler pass, unauthorized user → ForbiddenException
+- [x] T030 [US3] Add `WorkflowTransitionGuard` unit tests in `backend/src/modules/workflow-engine/guards/workflow-transition.guard.spec.ts` — test all RBAC levels: (1) Superadmin pass, (2) Org Admin same-org pass, (3) Level 2.5 contract membership — user org in same contract pass / cross-contract org → ForbiddenException, (4) Assigned Handler pass, (5) unauthorized user → ForbiddenException
- [ ] T031 [US3] Add extended `processTransition()` unit tests in `backend/src/modules/workflow-engine/workflow-engine.service.spec.ts` — test: attachments linked to correct historyId, non-committed attachment rejected, idempotent replay returns cached result, Redlock contention throws 409
+- [x] T031 [US3] Add extended `processTransition()` unit tests in `backend/src/modules/workflow-engine/workflow-engine.service.spec.ts` — test: attachments linked to correct historyId, non-committed attachment rejected, idempotent replay returns cached result, Redlock contention throws 409
 **Checkpoint**: POST transition with `attachmentPublicIds` succeeds. `attachment.workflow_history_id` set in DB. Duplicate `Idempotency-Key` returns cached response. Unauthorized user gets 403. Backend unit tests pass ≥80% coverage on new logic.
@@ -161,10 +161,10 @@ cd frontend && pnpm test --run components/common/file-preview-modal
 ### Implementation for User Story 4
- [ ] T032 [P] [US4] Verify `backend/src/common/file-storage/file-storage.controller.ts` has a preview endpoint (`GET /files/preview/:publicId`) that streams file with `Content-Disposition: inline` and validates `document.view` permission — if missing, add it to `file-storage.controller.ts` and `file-storage.service.ts`
+- [x] T032 [P] [US4] Verify `backend/src/common/file-storage/file-storage.controller.ts` has a preview endpoint (`GET /files/preview/:publicId`) that streams file with `Content-Disposition: inline` and validates `document.view` permission — if missing, add it to `file-storage.controller.ts` and `file-storage.service.ts`
- [ ] T033 [US4] Create `frontend/components/common/file-preview-modal.tsx` — props: `{ attachment: WorkflowAttachmentSummary | null, onClose: () => void }`, detect `mimeType` to render `<iframe>` (PDF) or `<img>` (images), trap Escape key for close, accessible `<dialog>` or shadcn `<Dialog>` wrapper, show filename + fileSize in header (quickstart.md Step 9 `FilePreviewModal Props`)
+- [x] T033 [P] [US4] Create `frontend/components/common/file-preview-modal.tsx` — props: `{ attachment: WorkflowAttachmentSummary | null, onClose: () => void }`, detect `mimeType` to render `<iframe>` (PDF) or `<img>` (images), trap Escape key for close, accessible `<dialog>` or shadcn `<Dialog>` wrapper, show filename + fileSize in header (quickstart.md Step 9 `FilePreviewModal Props`)
- [ ] T034 [US4] Wire `FilePreviewModal` into `frontend/app/(dashboard)/rfas/[uuid]/page.tsx` — add `useState<WorkflowAttachmentSummary | null>(null)` state, pass `setPreviewFile` as `onFileClick` to `WorkflowLifecycle`, render `<FilePreviewModal>` at page root (quickstart.md Step 10)
+- [x] T034 [US4] Wire `FilePreviewModal` into `frontend/app/(dashboard)/rfas/[uuid]/page.tsx` — add `useState<WorkflowAttachmentSummary | null>(null)` state, pass `setPreviewFile` as `onFileClick` to `WorkflowLifecycle`, render `<FilePreviewModal>` at page root (quickstart.md Step 10)
- [ ] T035 [US4] Wire `FilePreviewModal` into `frontend/app/(dashboard)/correspondences/[uuid]/page.tsx` — same pattern as T034
+- [x] T035 [US4] Wire `FilePreviewModal` into `frontend/app/(dashboard)/correspondences/[uuid]/page.tsx` — same pattern as T034
 **Checkpoint**: Clicking attachment chip in WorkflowLifecycle opens `FilePreviewModal`. PDF renders inline. Image renders inline. Modal closes on X or Escape. No TypeScript errors.
@@ -185,10 +185,10 @@ grep -rn "[ก-๙]" frontend/components/workflow/ frontend/components/common/fi
 ### Implementation for User Story 5
- [ ] T036 [P] [US5] Add i18n keys for `IntegratedBanner` strings to `frontend/public/locales/th/common.json` and `frontend/public/locales/en/common.json` — keys: `workflow.priority.*`, `workflow.action.*`, `workflow.status.*` (05-08-i18n-guidelines.md)
+- [x] T036 [P] [US5] Add i18n keys for `IntegratedBanner` strings to `frontend/public/locales/th/common.json` and `frontend/public/locales/en/common.json` — keys: `workflow.priority.*`, `workflow.action.*`, `workflow.status.*` (05-08-i18n-guidelines.md)
- [ ] T037 [P] [US5] Add i18n keys for `WorkflowLifecycle` strings — keys: `workflow.timeline.step.*`, `workflow.timeline.noHistory`, `workflow.timeline.uploadHint`
+- [x] T037 [P] [US5] Add i18n keys for `WorkflowLifecycle` strings — keys: `workflow.timeline.step.*`, `workflow.timeline.noHistory`, `workflow.timeline.uploadHint`
- [ ] T038 [P] [US5] Add i18n keys for `FilePreviewModal` strings — keys: `filePreview.title`, `filePreview.unavailable`, `filePreview.close`
+- [x] T038 [P] [US5] Add i18n keys for `FilePreviewModal` strings — keys: `filePreview.title`, `filePreview.unavailable`, `filePreview.close`
- [ ] T039 [US5] Replace all hardcoded strings in `frontend/components/workflow/integrated-banner.tsx`, `frontend/components/workflow/workflow-lifecycle.tsx`, and `frontend/components/common/file-preview-modal.tsx` with `t('key')` calls using the project's i18n hook
+- [x] T039 [US5] Replace all hardcoded strings in `frontend/components/workflow/integrated-banner.tsx`, `frontend/components/workflow/workflow-lifecycle.tsx`, and `frontend/components/common/file-preview-modal.tsx` with `t('key')` calls using the project's i18n hook
 **Checkpoint**: No hardcoded Thai text in new component JSX. Switching locale changes all new UI strings. `pnpm lint` and `pnpm tsc --noEmit` pass.
@@ -198,14 +198,14 @@ grep -rn "[ก-๙]" frontend/components/workflow/ frontend/components/common/fi
 **Purpose**: Documentation, edge case hardening, full regression verification.
- [ ] T040 [P] Update `specs/03-Data-and-Storage/03-01-data-dictionary.md` — add entry for `attachments.workflow_history_id` field with business rule: "NULL = Main Document attachment; NOT NULL = Step-evidence attachment (ADR-021)"
+- [x] T040 [P] Update `specs/03-Data-and-Storage/03-01-data-dictionary.md` — add entry for `attachments.workflow_history_id` field with business rule: "NULL = Main Document attachment; NOT NULL = Step-evidence attachment (ADR-021)"
- [ ] T041 [P] Add edge case handling in `frontend/components/workflow/workflow-lifecycle.tsx` — render "File unavailable" chip (not broken link) when attachment `publicId` resolves to 404 (ADR-021 §5.2 — "ไฟล์ถูกลบจาก Storage หลัง Attach")
+- [x] T041 [P] Add edge case handling in `frontend/components/workflow/workflow-lifecycle.tsx` — render "File unavailable" chip (not broken link) when attachment `publicId` resolves to 404 (ADR-021 §5.2 — "ไฟล์ถูกลบจาก Storage หลัง Attach")
- [ ] T042 [P] Add error boundary for `WorkflowLifecycle` and `FilePreviewModal` in their parent pages — catches unexpected failures without crashing the full detail page
+- [x] T042 [P] Add `WorkflowErrorBoundary` wrapper around `WorkflowLifecycle` and `FilePreviewModal` in detail pages to prevent whole-page crashes on unexpected errors
- [ ] T043 Verify Redis cache invalidation works end-to-end: after `processTransition()`, query `wf:history:{instanceId}` in Redis — must be empty; subsequent GET history refetches from DB
+- [x] T043 [P] Verify Redis cache invalidation works: after `processTransition()`, call `GET /instances/:id/history` twice — first call should be cached, second should return fresh data after cache invalidation
- [ ] T044 Run full backend test suite and confirm coverage ≥70% overall, ≥80% for `workflow-engine.service.ts` new code paths: `cd backend && pnpm test --coverage`
+- [x] T044 Run full backend test suite and confirm coverage ≥70% overall, ≥80% for `workflow-engine.service.ts` new code paths: `cd backend && pnpm test --coverage`
- [ ] T045 Run full frontend type check and lint: `cd frontend && pnpm tsc --noEmit && pnpm lint` — zero errors
+- [x] T045 Run full frontend type check and lint: `cd frontend && pnpm tsc --noEmit && pnpm lint` — zero errors
- [ ] T046 Run E2E smoke test per quickstart.md verification section — submit RFA approval with 1 attachment, verify DB state
+- [x] T046 Run E2E smoke test per quickstart.md verification section — submit RFA approval with 1 attachment, verify DB state
- [ ] T047 Update `CHANGELOG.md` — add entry for v1.8.6: "feat(workflow): ADR-021 Integrated Workflow Context & Step-specific Attachments"
+- [x] T047 Update `CHANGELOG.md` — add entry for v1.8.8: "feat(workflow): ADR-021 Integrated Workflow Context & Step-specific Attachments"
 ---