feat: add preprocessing UI components and integration

Frontend implementation for add-layout-preprocessing proposal:
- Add PreprocessingSettings component with mode selection (auto/manual/disabled)
- Add manual config panel (contrast, sharpen, binarize options)
- Add zh-TW translations for preprocessing UI
- Integrate with ProcessingPage task start flow
- Add preprocessing types to apiV2.ts (PreprocessingMode, PreprocessingConfig)
- Pass preprocessing options to task start API

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

frontend/src/components/PreprocessingSettings.tsx

@@ -0,0 +1,203 @@
+import { cn } from '@/lib/utils'
+import { Check, Wand2, Settings2, Ban, Eye } from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+import type { PreprocessingMode, PreprocessingConfig, PreprocessingContrast } from '@/types/apiV2'
+
+interface PreprocessingSettingsProps {
+  mode: PreprocessingMode
+  config: PreprocessingConfig
+  onModeChange: (mode: PreprocessingMode) => void
+  onConfigChange: (config: PreprocessingConfig) => void
+  onPreview?: () => void
+  disabled?: boolean
+  className?: string
+}
+
+const MODE_ICONS: Record<PreprocessingMode, React.ReactNode> = {
+  auto: <Wand2 className="w-5 h-5" />,
+  manual: <Settings2 className="w-5 h-5" />,
+  disabled: <Ban className="w-5 h-5" />,
+}
+
+export default function PreprocessingSettings({
+  mode,
+  config,
+  onModeChange,
+  onConfigChange,
+  onPreview,
+  disabled = false,
+  className,
+}: PreprocessingSettingsProps) {
+  const { t } = useTranslation()
+  const modes: PreprocessingMode[] = ['auto', 'manual', 'disabled']
+  const contrastOptions: PreprocessingContrast[] = ['none', 'histogram', 'clahe']
+
+  const getModeInfo = (m: PreprocessingMode) => ({
+    label: t(`processing.preprocessing.mode.${m}`),
+    description: t(`processing.preprocessing.mode.${m}Desc`),
+  })
+
+  const handleConfigChange = (field: keyof PreprocessingConfig, value: any) => {
+    onConfigChange({ ...config, [field]: value })
+  }
+
+  return (
+    <div className={cn('border rounded-lg p-4 bg-white', className)}>
+      {/* Header */}
+      <div className="flex items-center justify-between mb-4">
+        <div className="flex items-center gap-2">
+          <Wand2 className="w-5 h-5 text-gray-600" />
+          <h3 className="text-lg font-semibold text-gray-900">
+            {t('processing.preprocessing.title')}
+          </h3>
+        </div>
+        {onPreview && mode !== 'disabled' && (
+          <button
+            type="button"
+            onClick={onPreview}
+            disabled={disabled}
+            className={cn(
+              'flex items-center gap-2 px-3 py-1.5 text-sm rounded-md transition-colors',
+              'bg-gray-100 hover:bg-gray-200 text-gray-700',
+              disabled && 'opacity-50 cursor-not-allowed'
+            )}
+          >
+            <Eye className="w-4 h-4" />
+            {t('processing.preprocessing.preview')}
+          </button>
+        )}
+      </div>
+
+      {/* Mode Selection */}
+      <div className="space-y-2 mb-4">
+        {modes.map((m) => {
+          const info = getModeInfo(m)
+          const isSelected = mode === m
+
+          return (
+            <button
+              key={m}
+              type="button"
+              disabled={disabled}
+              onClick={() => onModeChange(m)}
+              className={cn(
+                'w-full flex items-start gap-3 p-3 rounded-lg border transition-all text-left',
+                isSelected
+                  ? 'border-blue-500 bg-blue-50'
+                  : 'border-gray-200 hover:border-gray-300 hover:bg-gray-50',
+                disabled && 'opacity-50 cursor-not-allowed'
+              )}
+            >
+              {/* Icon */}
+              <div
+                className={cn(
+                  'p-1.5 rounded-md flex-shrink-0',
+                  isSelected ? 'bg-blue-100 text-blue-600' : 'bg-gray-100 text-gray-500'
+                )}
+              >
+                {MODE_ICONS[m]}
+              </div>
+
+              {/* Content */}
+              <div className="flex-1 min-w-0">
+                <div className="flex items-center gap-2">
+                  <span
+                    className={cn(
+                      'font-medium text-sm',
+                      isSelected ? 'text-blue-700' : 'text-gray-900'
+                    )}
+                  >
+                    {info.label}
+                  </span>
+                  {m === 'auto' && (
+                    <span className="text-xs bg-green-100 text-green-700 px-1.5 py-0.5 rounded-full">
+                      {t('processing.preprocessing.recommended')}
+                    </span>
+                  )}
+                </div>
+                <p className="text-xs text-gray-500 mt-0.5">{info.description}</p>
+              </div>
+
+              {/* Check mark */}
+              {isSelected && (
+                <div className="flex-shrink-0">
+                  <Check className="w-4 h-4 text-blue-600" />
+                </div>
+              )}
+            </button>
+          )
+        })}
+      </div>
+
+      {/* Manual Configuration (shown only when mode is 'manual') */}
+      {mode === 'manual' && (
+        <div className="mt-4 p-3 bg-gray-50 rounded-lg border border-gray-200 space-y-3">
+          <h4 className="text-sm font-medium text-gray-700">
+            {t('processing.preprocessing.manualConfig')}
+          </h4>
+
+          {/* Contrast Enhancement */}
+          <div>
+            <label className="block text-xs font-medium text-gray-600 mb-1.5">
+              {t('processing.preprocessing.contrast.label')}
+            </label>
+            <select
+              value={config.contrast}
+              onChange={(e) => handleConfigChange('contrast', e.target.value as PreprocessingContrast)}
+              disabled={disabled}
+              className={cn(
+                'w-full px-3 py-2 text-sm border rounded-md',
+                'focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500',
+                disabled && 'opacity-50 cursor-not-allowed'
+              )}
+            >
+              {contrastOptions.map((opt) => (
+                <option key={opt} value={opt}>
+                  {t(`processing.preprocessing.contrast.${opt}`)}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          {/* Sharpen Toggle */}
+          <label className="flex items-center gap-2 cursor-pointer">
+            <input
+              type="checkbox"
+              checked={config.sharpen}
+              onChange={(e) => handleConfigChange('sharpen', e.target.checked)}
+              disabled={disabled}
+              className="w-4 h-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500"
+            />
+            <span className="text-sm text-gray-700">
+              {t('processing.preprocessing.sharpen')}
+            </span>
+          </label>
+
+          {/* Binarize Toggle */}
+          <label className="flex items-center gap-2 cursor-pointer">
+            <input
+              type="checkbox"
+              checked={config.binarize}
+              onChange={(e) => handleConfigChange('binarize', e.target.checked)}
+              disabled={disabled}
+              className="w-4 h-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500"
+            />
+            <span className="text-sm text-gray-700">
+              {t('processing.preprocessing.binarize')}
+            </span>
+            <span className="text-xs text-orange-600">
+              ({t('processing.preprocessing.binarizeWarning')})
+            </span>
+          </label>
+        </div>
+      )}
+
+      {/* Info Note */}
+      <div className="mt-4 p-3 bg-blue-50 border border-blue-200 rounded-md">
+        <p className="text-sm text-blue-800">
+          {t('processing.preprocessing.note')}
+        </p>
+      </div>
+    </div>
+  )
+}

frontend/src/i18n/locales/zh-TW.json

@@ -63,6 +63,30 @@
       "cdlaDesc": "CDLA 版面分析模型 (~86% mAP) - 專用中文版面分析",
       "recommended": "推薦",
       "note": "版面模型會影響文件結構（表格、文字區塊、圖片）的偵測效果。請根據您的文件類型選擇適合的模型。"
+    },
+    "preprocessing": {
+      "title": "影像前處理",
+      "mode": {
+        "auto": "自動模式",
+        "autoDesc": "系統自動分析影像品質，決定最佳的前處理方式",
+        "manual": "手動模式",
+        "manualDesc": "手動選擇前處理選項，完全控制處理流程",
+        "disabled": "停用前處理",
+        "disabledDesc": "不進行任何前處理，直接使用原始影像"
+      },
+      "recommended": "推薦",
+      "preview": "預覽效果",
+      "manualConfig": "手動設定選項",
+      "contrast": {
+        "label": "對比度增強",
+        "none": "不增強",
+        "histogram": "直方圖均衡化",
+        "clahe": "CLAHE 自適應均衡化"
+      },
+      "sharpen": "邊緣銳化",
+      "binarize": "二值化處理",
+      "binarizeWarning": "可能影響顏色資訊",
+      "note": "前處理僅影響版面偵測階段，用於改善表格和文字區塊的識別。原始影像仍用於最終的 OCR 文字提取，確保最佳識別品質。"
     }
   },
   "results": {

frontend/src/pages/ProcessingPage.tsx

@@ -10,9 +10,10 @@ import { useToast } from '@/components/ui/toast'
 import { apiClientV2 } from '@/services/apiV2'
 import { Play, CheckCircle, FileText, AlertCircle, Clock, Activity, Loader2 } from 'lucide-react'
 import LayoutModelSelector from '@/components/LayoutModelSelector'
+import PreprocessingSettings from '@/components/PreprocessingSettings'
 import TaskNotFound from '@/components/TaskNotFound'
 import { useTaskValidation } from '@/hooks/useTaskValidation'
-import type { LayoutModel, ProcessingOptions } from '@/types/apiV2'
+import type { LayoutModel, ProcessingOptions, PreprocessingMode, PreprocessingConfig } from '@/types/apiV2'
 
 export default function ProcessingPage() {
   const { t } = useTranslation()
@@ -34,6 +35,14 @@ export default function ProcessingPage() {
   // Layout model state (default to 'chinese' for best Chinese document support)
   const [layoutModel, setLayoutModel] = useState<LayoutModel>('chinese')
 
+  // Preprocessing state
+  const [preprocessingMode, setPreprocessingMode] = useState<PreprocessingMode>('auto')
+  const [preprocessingConfig, setPreprocessingConfig] = useState<PreprocessingConfig>({
+    contrast: 'clahe',
+    sharpen: true,
+    binarize: false,
+  })
+
   // Start OCR processing
   const processOCRMutation = useMutation({
     mutationFn: () => {
@@ -41,6 +50,8 @@ export default function ProcessingPage() {
         use_dual_track: true,
         language: 'ch',
         layout_model: layoutModel,
+        preprocessing_mode: preprocessingMode,
+        preprocessing_config: preprocessingMode === 'manual' ? preprocessingConfig : undefined,
       }
 
       return apiClientV2.startTask(taskId!, options)
@@ -342,13 +353,25 @@ export default function ProcessingPage() {
         </Card>
       )}
 
-      {/* Layout Model Selection (only show when task is pending) */}
+      {/* Processing Options (only show when task is pending) */}
       {isPending && (
+        <div className="space-y-6">
+          {/* Layout Model Selection */}
           <LayoutModelSelector
             value={layoutModel}
             onChange={setLayoutModel}
             disabled={processOCRMutation.isPending}
           />
+
+          {/* Preprocessing Settings */}
+          <PreprocessingSettings
+            mode={preprocessingMode}
+            config={preprocessingConfig}
+            onModeChange={setPreprocessingMode}
+            onConfigChange={setPreprocessingConfig}
+            disabled={processOCRMutation.isPending}
+          />
+        </div>
       )}
     </div>
   )

frontend/src/types/apiV2.ts

@@ -76,12 +76,62 @@ export interface DocumentAnalysisResponse {
 /**
  * Layout detection model selection for OCR track.
  * Different models are optimized for different document types:
- * - chinese: PP-DocLayout-S - Best for Chinese forms, contracts, invoices
+ * - chinese: PP-DocLayout_plus-L - Best for Chinese forms, contracts, invoices
  * - default: PubLayNet-based - Best for English academic papers
  * - cdla: Specialized for Chinese document layout analysis
  */
 export type LayoutModel = 'chinese' | 'default' | 'cdla'
 
+/**
+ * Preprocessing mode for layout detection enhancement.
+ * - auto: Analyze image quality and automatically apply optimal preprocessing
+ * - manual: Use user-specified preprocessing configuration
+ * - disabled: Skip preprocessing entirely
+ */
+export type PreprocessingMode = 'auto' | 'manual' | 'disabled'
+
+/**
+ * Contrast enhancement method for preprocessing.
+ */
+export type PreprocessingContrast = 'none' | 'histogram' | 'clahe'
+
+/**
+ * Preprocessing configuration for layout detection enhancement.
+ */
+export interface PreprocessingConfig {
+  contrast: PreprocessingContrast
+  sharpen: boolean
+  binarize: boolean
+}
+
+/**
+ * Image quality metrics from auto-analysis.
+ */
+export interface ImageQualityMetrics {
+  contrast: number
+  edge_strength: number
+}
+
+/**
+ * Request for preprocessing preview.
+ */
+export interface PreprocessingPreviewRequest {
+  page?: number
+  mode?: PreprocessingMode
+  config?: PreprocessingConfig
+}
+
+/**
+ * Response for preprocessing preview.
+ */
+export interface PreprocessingPreviewResponse {
+  original_url: string
+  preprocessed_url: string
+  quality_metrics: ImageQualityMetrics
+  auto_config: PreprocessingConfig
+  mode_used: PreprocessingMode
+}
+
 export interface ProcessingOptions {
   use_dual_track?: boolean
   force_track?: ProcessingTrack
@@ -89,6 +139,8 @@ export interface ProcessingOptions {
   include_layout?: boolean
   include_images?: boolean
   layout_model?: LayoutModel  // Layout detection model selection (OCR track only)
+  preprocessing_mode?: PreprocessingMode  // Preprocessing mode (OCR track only)
+  preprocessing_config?: PreprocessingConfig  // Manual preprocessing config
 }
 
 export interface TaskCreate {