260312:0932 20260312:0930 n8n workflow, backend and frontend MOD.

backend/src/modules/migration/dto/import-correspondence.dto.ts

@@ -13,7 +13,7 @@ export class ImportCorrespondenceDto {
 
   @IsString()
   @IsNotEmpty()
-  title!: string;
+  subject!: string;
 
   @IsString()
   @IsNotEmpty()

backend/src/modules/migration/dto/migration-queue-query.dto.ts

@@ -0,0 +1,27 @@
+import { IsOptional, IsEnum, IsInt, Min } from 'class-validator';
+import { Type } from 'class-transformer';
+import { MigrationReviewStatus } from '../entities/migration-review-queue.entity';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class PaginationDto {
+  @ApiPropertyOptional({ default: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @ApiPropertyOptional({ default: 10 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  limit?: number = 10;
+}
+
+export class MigrationQueueQueryDto extends PaginationDto {
+  @ApiPropertyOptional({ enum: MigrationReviewStatus })
+  @IsOptional()
+  @IsEnum(MigrationReviewStatus)
+  status?: MigrationReviewStatus;
+}

backend/src/modules/migration/entities/migration-error.entity.ts

@@ -0,0 +1,44 @@
+import {
+  Entity,
+  Column,
+  PrimaryGeneratedColumn,
+  CreateDateColumn,
+} from 'typeorm';
+
+export enum MigrationErrorType {
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
+  AI_PARSE_ERROR = 'AI_PARSE_ERROR',
+  API_ERROR = 'API_ERROR',
+  DB_ERROR = 'DB_ERROR',
+  SECURITY = 'SECURITY',
+  UNKNOWN = 'UNKNOWN',
+}
+
+@Entity('migration_errors')
+export class MigrationError {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ name: 'batch_id', length: 50, nullable: true })
+  batchId?: string;
+
+  @Column({ name: 'document_number', length: 100, nullable: true })
+  documentNumber?: string;
+
+  @Column({
+    name: 'error_type',
+    type: 'enum',
+    enum: MigrationErrorType,
+    nullable: true,
+  })
+  errorType?: MigrationErrorType;
+
+  @Column({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage?: string;
+
+  @Column({ name: 'raw_ai_response', type: 'text', nullable: true })
+  rawAiResponse?: string;
+
+  @CreateDateColumn({ name: 'created_at' })
+  createdAt!: Date;
+}

backend/src/modules/migration/entities/migration-review-queue.entity.ts

@@ -0,0 +1,61 @@
+import {
+  Entity,
+  Column,
+  PrimaryGeneratedColumn,
+  CreateDateColumn,
+} from 'typeorm';
+
+export enum MigrationReviewStatus {
+  PENDING = 'PENDING',
+  APPROVED = 'APPROVED',
+  REJECTED = 'REJECTED',
+}
+
+@Entity('migration_review_queue')
+export class MigrationReviewQueue {
+  @PrimaryGeneratedColumn()
+  id!: number;
+
+  @Column({ name: 'document_number', length: 100, unique: true })
+  documentNumber!: string;
+
+  @Column({ type: 'text', nullable: true })
+  title?: string;
+
+  @Column({ name: 'original_title', type: 'text', nullable: true })
+  originalTitle?: string;
+
+  @Column({ name: 'ai_suggested_category', length: 50, nullable: true })
+  aiSuggestedCategory?: string;
+
+  @Column({
+    name: 'ai_confidence',
+    type: 'decimal',
+    precision: 4,
+    scale: 3,
+    nullable: true,
+  })
+  aiConfidence?: number;
+
+  @Column({ name: 'ai_issues', type: 'json', nullable: true })
+  aiIssues?: any;
+
+  @Column({ name: 'review_reason', length: 255, nullable: true })
+  reviewReason?: string;
+
+  @Column({
+    type: 'enum',
+    enum: MigrationReviewStatus,
+    default: MigrationReviewStatus.PENDING,
+  })
+  status!: MigrationReviewStatus;
+
+  @Column({ name: 'reviewed_by', length: 100, nullable: true })
+  reviewedBy?: string;
+
+  @Column({ name: 'reviewed_at', type: 'timestamp', nullable: true })
+  reviewedAt?: Date;
+
+  @CreateDateColumn({ name: 'created_at' })
+  createdAt!: Date;
+}

backend/src/modules/migration/migration.controller.ts

@@ -3,7 +3,10 @@ import { MigrationService } from './migration.service';
 import { ImportCorrespondenceDto } from './dto/import-correspondence.dto';
 import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
 import { CurrentUser } from '../../common/decorators/current-user.decorator';
-import { ApiTags, ApiOperation, ApiBearerAuth, ApiHeader } from '@nestjs/swagger';
+import { ApiTags, ApiOperation, ApiBearerAuth, ApiHeader, ApiQuery, ApiParam } from '@nestjs/swagger';
+import { MigrationQueueQueryDto } from './dto/migration-queue-query.dto';
+import { Get, Param, Query, Res, ParseIntPipe, Body, Headers, Post, UseGuards } from '@nestjs/common';
+import type { Response } from 'express';
 
 @ApiTags('Migration')
 @ApiBearerAuth()
@@ -27,4 +30,79 @@ export class MigrationController {
     const userId = user?.id || user?.userId || 5;
     return this.migrationService.importCorrespondence(dto, idempotencyKey, userId);
   }
+
+  @Get('queue')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Get migration review queue' })
+  async getReviewQueue(@Query() query: MigrationQueueQueryDto) {
+    return this.migrationService.getReviewQueue(query);
+  }
+
+  @Get('queue/:id')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Get a specific queue item by ID' })
+  @ApiParam({ name: 'id', type: Number })
+  async getQueueItemById(@Param('id', ParseIntPipe) id: number) {
+    return this.migrationService.getQueueItemById(id);
+  }
+
+  @Get('errors')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Get migration errors' })
+  @ApiQuery({ name: 'page', required: false, type: Number })
+  @ApiQuery({ name: 'limit', required: false, type: Number })
+  async getErrors(
+    @Query('page') page?: number,
+    @Query('limit') limit?: number
+  ) {
+    return this.migrationService.getErrors(page, limit);
+  }
+
+  @Post('queue/:id/approve')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Approve and import a queued migration item' })
+  @ApiParam({ name: 'id', type: Number })
+  @ApiHeader({
+    name: 'Idempotency-Key',
+    description: 'Unique key per document and batch to prevent duplicate inserts',
+    required: true,
+  })
+  async approveQueueItem(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() dto: ImportCorrespondenceDto,
+    @Headers('idempotency-key') idempotencyKey: string,
+    @CurrentUser() user: any
+  ) {
+    const userId = user?.id || user?.userId || 5;
+    return this.migrationService.approveQueueItem(id, dto, idempotencyKey, userId);
+  }
+
+  @Post('queue/:id/reject')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Reject a queued migration item' })
+  @ApiParam({ name: 'id', type: Number })
+  async rejectQueueItem(
+    @Param('id', ParseIntPipe) id: number,
+    @CurrentUser() user: any
+  ) {
+    const userId = user?.id || user?.userId || 5;
+    return this.migrationService.rejectQueueItem(id, userId);
+  }
+
+  @Get('staging-file')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Stream a file from staging' })
+  @ApiQuery({ name: 'path', required: true, type: String })
+  async getStagingFile(
+    @Query('path') filePath: string,
+    @Res() res: Response
+  ) {
+    const stream = this.migrationService.getStagingFileStream(filePath);
+    res.set({
+      'Content-Type': 'application/pdf',
+      'Content-Disposition': 'inline; filename="document.pdf"',
+    });
+    stream.pipe(res);
+  }
 }
+

backend/src/modules/migration/migration.module.ts

@@ -10,10 +10,15 @@ import { CorrespondenceStatus } from '../correspondence/entities/correspondence-
 import { Project } from '../project/entities/project.entity';
 import { FileStorageModule } from '../../common/file-storage/file-storage.module';
 
+import { MigrationReviewQueue } from './entities/migration-review-queue.entity';
+import { MigrationError } from './entities/migration-error.entity';
+
 @Module({
   imports: [
     TypeOrmModule.forFeature([
       ImportTransaction,
+      MigrationReviewQueue,
+      MigrationError,
       Correspondence,
       CorrespondenceRevision,
       CorrespondenceType,

backend/src/modules/migration/migration.service.ts

@@ -15,7 +15,14 @@ import { CorrespondenceType } from '../correspondence/entities/correspondence-ty
 import { CorrespondenceStatus } from '../correspondence/entities/correspondence-status.entity';
 import { Project } from '../project/entities/project.entity';
 import { FileStorageService } from '../../common/file-storage/file-storage.service';
-
+import {
+  MigrationReviewQueue,
+  MigrationReviewStatus,
+} from './entities/migration-review-queue.entity';
+import { MigrationError } from './entities/migration-error.entity';
+import { MigrationQueueQueryDto } from './dto/migration-queue-query.dto';
+import { createReadStream, existsSync } from 'fs';
+import * as path from 'path';
 @Injectable()
 export class MigrationService {
   private readonly logger = new Logger(MigrationService.name);
@@ -30,6 +37,10 @@ export class MigrationService {
     private readonly correspondenceStatusRepo: Repository<CorrespondenceStatus>,
     @InjectRepository(Project)
     private readonly projectRepo: Repository<Project>,
+    @InjectRepository(MigrationReviewQueue)
+    private readonly reviewQueueRepo: Repository<MigrationReviewQueue>,
+    @InjectRepository(MigrationError)
+    private readonly errorRepo: Repository<MigrationError>,
     private readonly fileStorageService: FileStorageService
   ) {}
 
@@ -202,7 +213,7 @@ export class MigrationService {
         revisionLabel: revNum === 0 ? '0' : revNum.toString(),
         isCurrent: true,
         statusId: status.id,
-        subject: dto.title,
+        subject: dto.subject,
         description: 'Migrated from legacy system via Auto Ingest',
         body: dto.body || undefined,
         documentDate: parseDateStr(dto.document_date || dto.issued_date),
@@ -248,6 +259,50 @@ export class MigrationService {
         await queryRunner.manager.save('RfaRevision', rfaRev);
       }
 
+      // 5.5 Handle Tags
+      if (
+        dto.details &&
+        Array.isArray(dto.details.tags) &&
+        dto.details.tags.length > 0
+      ) {
+        for (const tagItem of dto.details.tags) {
+          let tagName: string | undefined;
+
+          if (typeof tagItem === 'string') {
+            tagName = tagItem;
+          } else if (tagItem && typeof tagItem === 'object') {
+            const tObj = tagItem as { tag_name?: unknown };
+            if (typeof tObj.tag_name === 'string') {
+              tagName = tObj.tag_name;
+            }
+          }
+
+          if (!tagName) continue;
+
+          // Find or create Tag
+          const tagRes = (await queryRunner.manager.query(
+            'SELECT id FROM tags WHERE project_id = ? AND tag_name = ? LIMIT 1',
+            [project.id, tagName]
+          )) as Array<{ id: number }>;
+
+          let tagId: number;
+          if (tagRes && tagRes.length > 0) {
+            tagId = tagRes[0].id;
+          } else {
+            const insertRes = (await queryRunner.manager.query(
+              "INSERT INTO tags (project_id, tag_name, color_code, created_by) VALUES (?, ?, 'default', ?)",
+              [project.id, tagName, userId]
+            )) as { insertId: number };
+            tagId = insertRes.insertId;
+          }
+
+          // Link to correspondence
+          await queryRunner.manager.query(
+            'INSERT IGNORE INTO correspondence_tags (correspondence_id, tag_id) VALUES (?, ?)',
+            [correspondence.id, tagId]
+          );
+        }
+      }
       // 6. Track Transaction
       const transaction = queryRunner.manager.create(ImportTransaction, {
         idempotencyKey,
@@ -295,4 +350,105 @@ export class MigrationService {
       await queryRunner.release();
     }
   }
+  async getReviewQueue(query: MigrationQueueQueryDto) {
+    const { page = 1, limit = 10, status } = query;
+    const skip = (page - 1) * limit;
+
+    const queryBuilder = this.reviewQueueRepo.createQueryBuilder('queue');
+    if (status) {
+      queryBuilder.where('queue.status = :status', { status });
+    }
+    
+    queryBuilder.orderBy('queue.createdAt', 'DESC');
+    queryBuilder.skip(skip).take(limit);
+
+    const [items, total] = await queryBuilder.getManyAndCount();
+
+    return {
+      items,
+      total,
+      page,
+      limit,
+      totalPages: Math.ceil(total / limit),
+    };
+  }
+
+  async getQueueItemById(id: number) {
+    const item = await this.reviewQueueRepo.findOne({ where: { id } });
+    if (!item) {
+      throw new BadRequestException(`Queue item with ID ${id} not found`);
+    }
+    return item;
+  }
+
+  async getErrors(page: number = 1, limit: number = 10) {
+    const skip = (page - 1) * limit;
+
+    const [items, total] = await this.errorRepo.findAndCount({
+      order: { createdAt: 'DESC' },
+      skip,
+      take: limit,
+    });
+
+    return {
+      items,
+      total,
+      page,
+      limit,
+      totalPages: Math.ceil(total / limit),
+    };
+  }
+
+  async approveQueueItem(id: number, dto: ImportCorrespondenceDto, idempotencyKey: string, userId: number) {
+    const queueItem = await this.reviewQueueRepo.findOne({ where: { id } });
+    if (!queueItem) {
+      throw new BadRequestException('Queue item not found');
+    }
+
+    if (queueItem.status !== MigrationReviewStatus.PENDING) {
+      throw new BadRequestException(`Queue item is already ${queueItem.status}`);
+    }
+
+    // Attempt the import
+    const result = await this.importCorrespondence(dto, idempotencyKey, userId);
+
+    // If successful, update the queue item status
+    queueItem.status = MigrationReviewStatus.APPROVED;
+    queueItem.reviewedBy = userId.toString();
+    queueItem.reviewedAt = new Date();
+    await this.reviewQueueRepo.save(queueItem);
+
+    return result;
+  }
+
+  async rejectQueueItem(id: number, userId: number) {
+    const queueItem = await this.reviewQueueRepo.findOne({ where: { id } });
+    if (!queueItem) {
+      throw new BadRequestException('Queue item not found');
+    }
+
+    queueItem.status = MigrationReviewStatus.REJECTED;
+    queueItem.reviewedBy = userId.toString();
+    queueItem.reviewedAt = new Date();
+    await this.reviewQueueRepo.save(queueItem);
+
+    return {
+      message: 'Document rejected successfully',
+      id: queueItem.id,
+    };
+  }
+
+  getStagingFileStream(filePath: string) {
+    if (!filePath) {
+        throw new BadRequestException('File path is required');
+    }
+
+    const resolvedPath = path.resolve(filePath);
+    if (!existsSync(resolvedPath)) {
+        throw new BadRequestException('File not found at specified path');
+    }
+
+    return createReadStream(resolvedPath);
+  }
 }
+

frontend/app/(dashboard)/admin/migration/errors/page.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { migrationService } from "@/lib/services/migration.service";
+import { MigrationErrorItem } from "@/types/migration";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { format } from "date-fns";
+import { ArrowLeftIcon } from "lucide-react";
+import Link from "next/link";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+
+export default function MigrationErrorsPage() {
+  const [items, setItems] = useState<MigrationErrorItem[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetchData();
+  }, []);
+
+  const fetchData = async () => {
+    try {
+      setLoading(true);
+      const res = await migrationService.getErrors({ limit: 100 });
+      setItems(res.items);
+    } catch (error) {
+      console.error("Failed to fetch errors", error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      <div className="flex justify-between items-center">
+        <div>
+          <h1 className="text-3xl font-bold tracking-tight text-red-600">Migration Errors</h1>
+          <p className="text-muted-foreground mt-1">
+            Systemic errors encountered during the background migration process.
+          </p>
+        </div>
+        <Link href="/admin/migration">
+          <Button variant="outline">
+            <ArrowLeftIcon className="mr-2 h-4 w-4" /> Back to Queue
+          </Button>
+        </Link>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Error Audit Log</CardTitle>
+        </CardHeader>
+        <CardContent>
+          {loading ? (
+            <div className="py-10 text-center">Loading errors...</div>
+          ) : items.length === 0 ? (
+            <div className="py-10 text-center text-muted-foreground">No errors found.</div>
+          ) : (
+            <div className="rounded-md border">
+              <Table>
+                <TableHeader>
+                  <TableRow>
+                    <TableHead>Batch ID</TableHead>
+                    <TableHead>Document No.</TableHead>
+                    <TableHead>Error Type</TableHead>
+                    <TableHead>Error Message</TableHead>
+                    <TableHead>Occurred At</TableHead>
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  {items.map((item) => (
+                    <TableRow key={item.id}>
+                      <TableCell className="font-mono text-sm">{item.batchId || "-"}</TableCell>
+                      <TableCell className="font-medium">{item.documentNumber || "-"}</TableCell>
+                      <TableCell>
+                        <Badge variant="destructive">{item.errorType || "UNKNOWN"}</Badge>
+                      </TableCell>
+                      <TableCell className="max-w-md break-words">
+                        <span className="text-sm text-muted-foreground line-clamp-2" title={item.errorMessage}>
+                          {item.errorMessage || "-"}
+                        </span>
+                      </TableCell>
+                      <TableCell>{format(new Date(item.createdAt), "dd MMM yyyy, HH:mm")}</TableCell>
+                    </TableRow>
+                  ))}
+                </TableBody>
+              </Table>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

frontend/app/(dashboard)/admin/migration/page.tsx

@@ -0,0 +1,140 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { migrationService } from "@/lib/services/migration.service";
+import { MigrationReviewQueueItem, MigrationReviewStatus } from "@/types/migration";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { format } from "date-fns";
+import { EyeIcon, FileXIcon } from "lucide-react";
+import Link from "next/link";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+
+export default function MigrationReviewQueuePage() {
+  const [items, setItems] = useState<MigrationReviewQueueItem[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [statusFilter, setStatusFilter] = useState<string>("PENDING");
+
+  useEffect(() => {
+    fetchData();
+  }, [statusFilter]);
+
+  const fetchData = async () => {
+    try {
+      setLoading(true);
+      const res = await migrationService.getReviewQueue({
+        status: statusFilter === "ALL" ? undefined : (statusFilter as MigrationReviewStatus),
+        limit: 50,
+      });
+      setItems(res.items);
+    } catch (error) {
+      console.error("Failed to fetch queue", error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      <div className="flex justify-between flex-wrap gap-4 items-center">
+        <div>
+          <h1 className="text-3xl font-bold tracking-tight">Migration Review Queue</h1>
+          <p className="text-muted-foreground mt-1">
+            Review and correct documents that AI flagged as low confidence.
+          </p>
+        </div>
+        <div className="flex items-center gap-4">
+          <Link href="/admin/migration/errors">
+            <Button variant="outline">
+              <FileXIcon className="mr-2 h-4 w-4" /> View Error Logs
+            </Button>
+          </Link>
+          <Select value={statusFilter} onValueChange={setStatusFilter}>
+            <SelectTrigger className="w-[180px]">
+              <SelectValue placeholder="Status" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="ALL">All Status</SelectItem>
+              <SelectItem value="PENDING">Pending</SelectItem>
+              <SelectItem value="APPROVED">Approved</SelectItem>
+              <SelectItem value="REJECTED">Rejected</SelectItem>
+            </SelectContent>
+          </Select>
+        </div>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Queue Items - {statusFilter}</CardTitle>
+        </CardHeader>
+        <CardContent>
+          {loading ? (
+            <div className="py-10 text-center">Loading queue...</div>
+          ) : items.length === 0 ? (
+            <div className="py-10 text-center text-muted-foreground">No items in the queue.</div>
+          ) : (
+            <div className="rounded-md border">
+              <Table>
+                <TableHeader>
+                  <TableRow>
+                    <TableHead>Document No.</TableHead>
+                    <TableHead>Suggested Category</TableHead>
+                    <TableHead>Confidence</TableHead>
+                    <TableHead>Status</TableHead>
+                    <TableHead>Created At</TableHead>
+                    <TableHead className="text-right">Action</TableHead>
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  {items.map((item) => (
+                    <TableRow key={item.id}>
+                      <TableCell className="font-medium">{item.documentNumber}</TableCell>
+                      <TableCell>{item.aiSuggestedCategory || "Unknown"}</TableCell>
+                      <TableCell>
+                        <Badge 
+                          variant={
+                            !item.aiConfidence 
+                              ? "destructive" 
+                              : item.aiConfidence > 0.8 
+                                ? "default" 
+                                : item.aiConfidence > 0.5 
+                                  ? "secondary" 
+                                  : "destructive"
+                          }
+                        >
+                          {item.aiConfidence ? (item.aiConfidence * 100).toFixed(1) + "%" : "N/A"}
+                        </Badge>
+                      </TableCell>
+                      <TableCell>
+                        <Badge variant={item.status === 'PENDING' ? 'outline' : item.status === 'APPROVED' ? 'default' : 'destructive'}>
+                          {item.status}
+                        </Badge>
+                      </TableCell>
+                      <TableCell>{format(new Date(item.createdAt), "dd MMM yyyy, HH:mm")}</TableCell>
+                      <TableCell className="text-right">
+                        <Link href={`/admin/migration/review/${item.id}`}>
+                          <Button size="sm" variant="ghost">
+                            <EyeIcon className="h-4 w-4 mr-2" /> Review
+                          </Button>
+                        </Link>
+                      </TableCell>
+                    </TableRow>
+                  ))}
+                </TableBody>
+              </Table>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

frontend/app/(dashboard)/admin/migration/review/[id]/page.tsx

@@ -0,0 +1,362 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useParams, useRouter } from "next/navigation";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import * as z from "zod";
+import { migrationService } from "@/lib/services/migration.service";
+import { MigrationReviewQueueItem } from "@/types/migration";
+import { Button } from "@/components/ui/button";
+import {
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@/components/ui/form";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { ArrowLeftIcon, CheckCircleIcon, XCircleIcon } from "lucide-react";
+import Link from "next/link";
+import { toast } from "sonner";
+import { Card, CardContent } from "@/components/ui/card";
+
+const reviewFormSchema = z.object({
+  document_number: z.string().min(1, "Document number is required"),
+  subject: z.string().min(1, "Subject is required"),
+  category: z.string().min(1, "Category is required"),
+  document_date: z.string().optional(),
+  issued_date: z.string().optional(),
+  received_date: z.string().optional(),
+  sender_id: z.string().optional(),
+  discipline_id: z.string().optional(),
+});
+
+type ReviewFormValues = z.infer<typeof reviewFormSchema>;
+
+export default function MigrationReviewPage() {
+  const params = useParams();
+  const router = useRouter();
+  const id = Number(params.id);
+
+  const [item, setItem] = useState<MigrationReviewQueueItem | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [submitting, setSubmitting] = useState(false);
+
+  const form = useForm<ReviewFormValues>({
+    resolver: zodResolver(reviewFormSchema),
+    defaultValues: {
+      document_number: "",
+      subject: "",
+      category: "",
+      document_date: "",
+      issued_date: "",
+      received_date: "",
+      sender_id: "",
+      discipline_id: "",
+    },
+  });
+
+  useEffect(() => {
+    if (!id) return;
+    fetchItem(id);
+  }, [id]);
+
+  const fetchItem = async (itemId: number) => {
+    try {
+      setLoading(true);
+      const res = await migrationService.getQueueItem(itemId);
+      setItem(res);
+
+      if (res) {
+        // Pre-fill form from database item and aiIssues payload
+        const issues = res.aiIssues || {};
+        form.reset({
+          document_number: res.documentNumber || "",
+          subject: res.title || res.originalTitle || "",
+          category: res.aiSuggestedCategory || "",
+          document_date: issues.document_date || "",
+          issued_date: issues.issued_date || "",
+          received_date: issues.received_date || "",
+          sender_id: issues.sender_id ? String(issues.sender_id) : "",
+          discipline_id: issues.discipline_id ? String(issues.discipline_id) : "",
+        });
+      }
+    } catch (error) {
+      console.error("Failed to load queue item", error);
+      toast.error("Failed to load queue item");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const onSubmit = async (values: ReviewFormValues) => {
+    if (!item) return;
+
+    try {
+      setSubmitting(true);
+      const issues = item.aiIssues || {};
+      
+      const payload = {
+        document_number: values.document_number,
+        subject: values.subject,
+        category: values.category,
+        source_file_path: issues.source_file_path || "",
+        migrated_by: "SYSTEM_IMPORT",
+        batch_id: "MANUAL_REVIEW_BATCH",
+        project_id: 1, // Assumption or pulled from store
+        document_date: values.document_date,
+        issued_date: values.issued_date,
+        received_date: values.received_date,
+        sender_id: values.sender_id ? Number(values.sender_id) : undefined,
+        discipline_id: values.discipline_id ? Number(values.discipline_id) : undefined,
+        details: {
+          tags: issues.tags || [],
+          ai_confidence: item.aiConfidence,
+        }
+      };
+
+      // Mock idempotency key based on timestamp to ensure uniqueness per approval retry
+      const idempotencyKey = `review-${item.id}-${Date.now()}`;
+      await migrationService.approveQueueItem(item.id, payload, idempotencyKey);
+      
+      toast.success("Document approved and imported successfully");
+      router.push("/admin/migration");
+    } catch (error: any) {
+      console.error("Failed to approve item", error);
+      toast.error(error?.response?.data?.message || "Failed to approve and import");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const onReject = async () => {
+    if (!item || !confirm("Are you sure you want to REJECT this document? It will not be imported.")) return;
+
+    try {
+      setSubmitting(true);
+      await migrationService.rejectQueueItem(item.id);
+      toast.success("Document rejected");
+      router.push("/admin/migration");
+    } catch (error: any) {
+      console.error("Failed to reject item", error);
+      toast.error("Failed to reject document");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  if (loading) {
+    return <div className="py-10 text-center">Loading document data...</div>;
+  }
+
+  if (!item) {
+    return <div className="py-10 text-center text-red-500">Document not found</div>;
+  }
+
+  const pdfUrl = item.aiIssues?.source_file_path 
+    ? migrationService.getStagingFileUrl(item.aiIssues.source_file_path)
+    : null;
+
+  return (
+    <div className="flex flex-col h-[calc(100vh-6rem)] space-y-4">
+      <div className="flex justify-between items-center shrink-0">
+        <div className="flex items-center gap-4">
+          <Link href="/admin/migration">
+            <Button variant="outline" size="icon">
+              <ArrowLeftIcon className="h-4 w-4" />
+            </Button>
+          </Link>
+          <div>
+            <h1 className="text-2xl font-bold tracking-tight">Review Document: {item.documentNumber}</h1>
+            <p className="text-sm text-muted-foreground flex items-center gap-2">
+              Status: <span className="font-semibold text-primary">{item.status}</span>
+              {' | '} Confidence: <span className={item.aiConfidence && item.aiConfidence < 0.8 ? "text-red-500" : "text-green-500"}>{item.aiConfidence ? (item.aiConfidence * 100).toFixed(1) + "%" : "N/A"}</span>
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="flex flex-1 gap-6 overflow-hidden">
+        {/* Left Side: PDF Viewer */}
+        <Card className="flex-1 hidden md:flex flex-col overflow-hidden border-2 border-primary/10 shadow-md">
+          <CardContent className="p-0 flex-1 relative bg-slate-100">
+            {pdfUrl ? (
+              <iframe
+                src={`${pdfUrl}#toolbar=0&navpanes=0`}
+                className="absolute inset-0 w-full h-full"
+                title="Document Viewer"
+              />
+            ) : (
+              <div className="absolute inset-0 flex items-center justify-center text-muted-foreground">
+                <p>No Source File Path found for this document</p>
+              </div>
+            )}
+          </CardContent>
+        </Card>
+
+        {/* Right Side: Form */}
+        <Card className="w-full md:w-[450px] lg:w-[500px] flex-shrink-0 flex flex-col overflow-hidden border-2 border-primary/10 shadow-md">
+          <div className="p-4 border-b bg-muted/30">
+            <h2 className="font-semibold text-lg flex items-center gap-2">
+              Extracted Information
+            </h2>
+            {item.reviewReason && (
+              <p className="text-sm text-red-500 mt-1 font-medium bg-red-50 p-2 rounded border border-red-100">
+                Reason: {item.reviewReason}
+              </p>
+            )}
+          </div>
+          <CardContent className="flex-1 overflow-y-auto p-4 custom-scrollbar">
+            <Form {...form}>
+              <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+                <FormField
+                  control={form.control}
+                  name="document_number"
+                  render={({ field }) => (
+                    <FormItem>
+                      <FormLabel>Document Number</FormLabel>
+                      <FormControl>
+                        <Input {...field} />
+                      </FormControl>
+                      <FormMessage />
+                    </FormItem>
+                  )}
+                />
+                <FormField
+                  control={form.control}
+                  name="subject"
+                  render={({ field }) => (
+                    <FormItem>
+                      <FormLabel>Subject</FormLabel>
+                      <FormControl>
+                        <Textarea {...field} rows={3} />
+                      </FormControl>
+                      <FormMessage />
+                    </FormItem>
+                  )}
+                />
+                
+                <div className="grid grid-cols-2 gap-4">
+                  <FormField
+                    control={form.control}
+                    name="category"
+                    render={({ field }) => (
+                      <FormItem>
+                        <FormLabel>Category</FormLabel>
+                        <Select onValueChange={field.onChange} defaultValue={field.value}>
+                          <FormControl>
+                            <SelectTrigger>
+                              <SelectValue placeholder="Select type" />
+                            </SelectTrigger>
+                          </FormControl>
+                          <SelectContent>
+                            <SelectItem value="CORR">CORR</SelectItem>
+                            <SelectItem value="RFA">RFA</SelectItem>
+                            <SelectItem value="LETTER">LETTER</SelectItem>
+                            <SelectItem value="MEMO">MEMO</SelectItem>
+                          </SelectContent>
+                        </Select>
+                        <FormMessage />
+                      </FormItem>
+                    )}
+                  />
+                  <FormField
+                    control={form.control}
+                    name="discipline_id"
+                    render={({ field }) => (
+                      <FormItem>
+                        <FormLabel>Discipline ID</FormLabel>
+                        <FormControl>
+                          <Input {...field} type="number" placeholder="Optional" />
+                        </FormControl>
+                        <FormMessage />
+                      </FormItem>
+                    )}
+                  />
+                </div>
+
+                <div className="grid grid-cols-2 gap-4">
+                  <FormField
+                    control={form.control}
+                    name="document_date"
+                    render={({ field }) => (
+                      <FormItem>
+                        <FormLabel>Doc Date</FormLabel>
+                        <FormControl>
+                          <Input {...field} type="date" />
+                        </FormControl>
+                      </FormItem>
+                    )}
+                  />
+                  <FormField
+                    control={form.control}
+                    name="issued_date"
+                    render={({ field }) => (
+                      <FormItem>
+                        <FormLabel>Issued Date</FormLabel>
+                        <FormControl>
+                          <Input {...field} type="date" />
+                        </FormControl>
+                      </FormItem>
+                    )}
+                  />
+                </div>
+
+                <FormField
+                  control={form.control}
+                  name="sender_id"
+                  render={({ field }) => (
+                    <FormItem>
+                      <FormLabel>Sender Org ID</FormLabel>
+                      <FormControl>
+                        <Input {...field} type="number" placeholder="Optional" />
+                      </FormControl>
+                      <FormMessage />
+                    </FormItem>
+                  )}
+                />
+
+                {item.aiIssues?.key_points && item.aiIssues.key_points.length > 0 && (
+                  <div className="mt-6 border-t pt-4">
+                    <h3 className="font-semibold text-sm mb-2 text-muted-foreground">AI Extracted Key Points</h3>
+                    <ul className="text-sm space-y-1 list-disc pl-4 text-muted-foreground">
+                      {item.aiIssues.key_points.map((point: string, i: number) => (
+                        <li key={i}>{point}</li>
+                      ))}
+                    </ul>
+                  </div>
+                )}
+
+                <div className="flex gap-4 pt-6 mt-4 border-t sticky bottom-0 bg-background/95 backdrop-blur z-10">
+                  <Button
+                    type="button"
+                    variant="destructive"
+                    className="flex-1"
+                    disabled={submitting || item.status !== 'PENDING'}
+                    onClick={onReject}
+                  >
+                    <XCircleIcon className="w-4 h-4 mr-2" />
+                    Reject
+                  </Button>
+                  <Button 
+                    type="submit" 
+                    className="flex-1 bg-green-600 hover:bg-green-700 text-white" 
+                    disabled={submitting || item.status !== 'PENDING'}
+                  >
+                    <CheckCircleIcon className="w-4 h-4 mr-2" />
+                    {submitting ? "Processing..." : "Approve & Import"}
+                  </Button>
+                </div>
+              </form>
+            </Form>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  );
+}

frontend/components/admin/sidebar.tsx

@@ -4,7 +4,7 @@ import Link from 'next/link';
 import { usePathname } from 'next/navigation';
 import { useState } from 'react';
 import { cn } from '@/lib/utils';
-import { Settings, Activity, Shield, FileStack, ChevronDown, ChevronRight } from 'lucide-react';
+import { Settings, Activity, Shield, FileStack, ChevronDown, ChevronRight, Database } from 'lucide-react';
 
 interface MenuItem {
   href?: string;
@@ -54,6 +54,14 @@ export const menuItems: MenuItem[] = [
       { href: '/admin/monitoring/sessions', label: 'Active Sessions' },
     ],
   },
+  {
+    label: 'Migration',
+    icon: Database,
+    children: [
+      { href: '/admin/migration', label: 'Review Queue' },
+      { href: '/admin/migration/errors', label: 'Error Logs' },
+    ],
+  },
   { href: '/admin/settings', label: 'Settings', icon: Settings },
 ];
 

frontend/lib/services/migration.service.ts

@@ -0,0 +1,54 @@
+import api from '../api';
+import {
+  MigrationReviewQueueItem,
+  MigrationErrorItem,
+  PaginatedResponse,
+  MigrationReviewStatus,
+} from '@/types/migration';
+
+export const migrationService = {
+  getReviewQueue: async (params: {
+    page?: number;
+    limit?: number;
+    status?: MigrationReviewStatus;
+  }): Promise<PaginatedResponse<MigrationReviewQueueItem>> => {
+    const { data } = await api.get('/migration/queue', { params });
+    return data;
+  },
+
+  getQueueItem: async (id: number): Promise<MigrationReviewQueueItem> => {
+    const { data } = await api.get(`/migration/queue/${id}`);
+    return data;
+  },
+
+  getErrors: async (params: {
+    page?: number;
+    limit?: number;
+  }): Promise<PaginatedResponse<MigrationErrorItem>> => {
+    const { data } = await api.get('/migration/errors', { params });
+    return data;
+  },
+
+  approveQueueItem: async (id: number, payload: any, idempotencyKey: string) => {
+    const { data } = await api.post(`/migration/queue/${id}/approve`, payload, {
+      headers: {
+        'idempotency-key': idempotencyKey,
+      },
+    });
+    return data;
+  },
+
+  rejectQueueItem: async (id: number) => {
+    const { data } = await api.post(`/migration/queue/${id}/reject`);
+    return data;
+  },
+
+  getStagingFileUrl: (filePath: string) => {
+    // Generate the URL directly since it returns a file stream.
+    // Ensure we encode the file path correctly.
+    // It assumes your axios baseURL is set to your nestjs API.
+    // If working with raw <img> or <iframe>, you might need to append the token,
+    // or handle it via a fetch wrapper that downloads creating an object URL.
+    return `/api/migration/staging-file?path=${encodeURIComponent(filePath)}`;
+  },
+};

frontend/types/migration.ts

@@ -0,0 +1,47 @@
+export enum MigrationReviewStatus {
+  PENDING = 'PENDING',
+  APPROVED = 'APPROVED',
+  REJECTED = 'REJECTED',
+}
+
+export interface MigrationReviewQueueItem {
+  id: number;
+  documentNumber: string;
+  title?: string;
+  originalTitle?: string;
+  aiSuggestedCategory?: string;
+  aiConfidence?: number;
+  aiIssues?: any;
+  reviewReason?: string;
+  status: MigrationReviewStatus;
+  reviewedBy?: string;
+  reviewedAt?: string;
+  createdAt: string;
+}
+
+export enum MigrationErrorType {
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
+  AI_PARSE_ERROR = 'AI_PARSE_ERROR',
+  API_ERROR = 'API_ERROR',
+  DB_ERROR = 'DB_ERROR',
+  SECURITY = 'SECURITY',
+  UNKNOWN = 'UNKNOWN',
+}
+
+export interface MigrationErrorItem {
+  id: number;
+  batchId?: string;
+  documentNumber?: string;
+  errorType?: MigrationErrorType;
+  errorMessage?: string;
+  rawAiResponse?: string;
+  createdAt: string;
+}
+
+export interface PaginatedResponse<T> {
+  items: T[];
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+}

specs/03-Data-and-Storage/n8n.workflow.json

@@ -415,7 +415,7 @@
     {
       "parameters": {
         "operation": "executeQuery",
-        "query": "INSERT INTO migration_review_queue (document_number, title, original_title, ai_suggested_category, ai_confidence, ai_issues, review_reason, status, created_at) VALUES ('{{$json.document_number}}', '{{$json.ai_result.subject || $json.title}}', '{{$json.title}}', '{{$json.ai_result.suggested_category}}', {{$json.ai_result.confidence}}, '{{JSON.stringify($json.ai_result.key_points || [])}}', '{{$json.review_reason}}', 'PENDING', NOW()) ON DUPLICATE KEY UPDATE status = 'PENDING', review_reason = '{{$json.review_reason}}', created_at = NOW()",
+        "query": "INSERT INTO migration_review_queue (document_number, title, original_title, ai_suggested_category, ai_confidence, ai_issues, review_reason, status, created_at) VALUES ('{{$json.document_number}}', '{{$json.ai_result.subject || $json.title}}', '{{$json.title}}', '{{$json.ai_result.suggested_category}}', {{$json.ai_result.confidence}}, '{{JSON.stringify({ key_points: $json.ai_result.key_points || [], source_file_path: $json.pdf_path, raw: $json.ai_result, sender_id: $json.ai_result.sender_org_id, discipline_id: $json.ai_result.discipline_id, document_date: $json.ai_result.document_date, issued_date: $json.ai_result.issued_date, received_date: $json.ai_result.received_date, tags: $json.ai_result.suggested_tags })}}', '{{$json.review_reason}}', 'PENDING', NOW()) ON DUPLICATE KEY UPDATE status = 'PENDING', review_reason = '{{$json.review_reason}}', ai_issues = '{{JSON.stringify({ key_points: $json.ai_result.key_points || [], source_file_path: $json.pdf_path, raw: $json.ai_result, sender_id: $json.ai_result.sender_org_id, discipline_id: $json.ai_result.discipline_id, document_date: $json.ai_result.document_date, issued_date: $json.ai_result.issued_date, received_date: $json.ai_result.received_date, tags: $json.ai_result.suggested_tags })}}', created_at = NOW()",
         "options": {}
       },
       "id": "d76e9be2-9cc9-4b18-96de-637cbef9e90a",
@@ -701,7 +701,7 @@
       "name": "Build Import Payload",
       "typeVersion": 2,
       "parameters": {
-        "jsCode": "const item = $input.first();\nconst config = $('Set Configuration').first().json.config;\nconst ai = item.json.ai_result || {};\n\nreturn [{\n  json: {\n    ...item.json,\n    import_payload: {\n      document_number: String(item.json.document_number || ''),\n      title: String(ai.subject || item.json.title || 'ไม่มีชื่อเรื่อง'),\n      category: ai.type_code || 'LETTER',\n      source_file_path: item.json.file_path || '/dev/null',\n      ai_confidence: ai.confidence || 0.8,\n      migrated_by: 'SYSTEM_IMPORT',\n      batch_id: config.BATCH_ID,\n      project_id: Number(ai.project_id || config.PROJECT_ID),\n      discipline_id: ai.discipline_id || null,\n      sender_id: ai.sender_id || null,\n      receiver_id: ai.receiver_id || null,\n      document_date: ai.issued_date || '',\n      issued_date: ai.issued_date || '',\n      received_date: ai.received_date || '',\n      body: ai.body || '',\n      details: {\n        legacy_number: item.json.legacy_number || '',\n        remark: ai.remark || '',\n        key_points: ai.key_points || [],\n        tags: ai.tags || []\n      }\n    }\n  }\n}];"
+        "jsCode": "const item = $input.first();\nconst config = $('Set Configuration').first().json.config;\nconst ai = item.json.ai_result || {};\n\nlet subjectStr = String(ai.subject || item.json.title || 'ไม่มีชื่อเรื่อง');\nlet categoryCode = ai.type_code || 'LETTER';\n\nif (subjectStr.includes('ขออนุมัติ')) {\n  categoryCode = 'RFA';\n}\n\nlet remarkStr = ai.remark || '';\nif (item.json.legacy_number) {\n  remarkStr = (`Legacy Number: ${item.json.legacy_number}\\n` + remarkStr).trim();\n}\n\nreturn [{\n  json: {\n    ...item.json,\n    import_payload: {\n      document_number: String(item.json.document_number || ''),\n      subject: subjectStr,\n      category: categoryCode,\n      source_file_path: item.json.file_path || '/dev/null',\n      ai_confidence: ai.confidence || 0.8,\n      migrated_by: 'SYSTEM_IMPORT',\n      batch_id: config.BATCH_ID,\n      project_id: Number(ai.project_id || config.PROJECT_ID),\n      discipline_id: ai.discipline_id || null,\n      sender_id: ai.sender_id || null,\n      receiver_id: ai.receiver_id || null,\n      document_date: ai.issued_date || '',\n      issued_date: ai.issued_date || '',\n      received_date: ai.received_date || '',\n      body: ai.body || '',\n      details: {\n        legacy_number: item.json.legacy_number || '',\n        remark: remarkStr,\n        key_points: ai.key_points || [],\n        tags: ai.tags || []\n      }\n    }\n  }\n}];"
       },
       "type": "n8n-nodes-base.code",
       "position": [