編輯 | 究查 | 歷程 | 原始

0.1.1. 專案背景與目標

本文件定義了將大型實體檔案 CB_IMGPSScanImp.pas.bk 進行解耦與重構的標準流程。
核心策略在於「步驟間解耦(Step Decoupling)」,透過引入中介產出物,確保流程中斷時可從失敗步驟直接重試,無需重複耗時的掃描作業。

0.1.2. 環境變數定義

  • {{base_path}} = "doc/curtis/prompt/scanimpl_analysis"
  • {{script_path}} = "script"
  • {{source_file}} = "CB_IMGPSScanImp.pas.bk"

0.1.3. 四階段執行程序規格

0.1.3.1 階段一:原始碼結構提取 (Physical Extraction)

  • 目標:識別所有 TCB_IMGPSScanX 類別的方法實體邊界,建立物理行號索引。
  • 輸入:{{source_file}}。
  • 處理邏輯
    1. 執行逐行掃描。
    2. 匹配正則表達式:^(procedure|function)\s+TCB_IMGPSScanX\.
    3. 紀錄 lIndex:該方法宣告所在的起始行號(從 1 開始計算)。
    4. 紀錄 matcher:該行的完整原始碼字串。
    5. 計算 rIndex:將「下一個方法」的 lIndex - 1 作為當前方法的結束行;若為最後一個方法,則 rIndex 為檔案總行數。
  • 中介輸出{{base_path}}/step1_raw_methods.json
  • 中介輸出腳本{{script_path}}/scanimpl_annalysis_extract_methods.js
  • 結構範例[{"matcher": "...", "lIndex": 120, "rIndex": 150}]

0.1.3.2 階段二:特徵比對與標籤分類 (Semantic Tagging)

  • 目標:讀取邊界索引,根據關鍵字字典規則賦予業務分類標籤 (Tags)。
  • 輸入{{base_path}}/step1_raw_methods.json
  • 處理邏輯
    1. 遍歷中介 JSON 中的所有項目。
    2. 依據 matcher 內容進行關鍵字匹配(分類規則詳見第 4 節)。
    3. 賦予對應的主標籤(如 UIView)與次標籤(如 UIView.treeView)。
    4. 統一初始化 deps: []description: "" 欄位。
  • 中介輸出{{base_path}}/step2_classified_methods.json
  • 中介輸出腳本{{base_path}}/scanimpl_annalysis_classify.js

0.1.3.3 階段三:模組分流實體化 (Module Disaggregation)

  • 目標:將分類完成的總集合,物理性地拆分為五個符合專案規範的正式模組 JSON。
  • 輸入{{base_path}}/step2_classified_methods.json
  • 處理邏輯
    1. 依據項目中的主標籤(ScannerController, BusinessLogic, ImageProcessor, TransportManager, UIView)進行分流。
    2. 格式化 JSON:使用 UTF-8 編碼,縮排為 2 個空格。
  • 目標產出
    • {{base_path}}/scanimpl_annalysis.ScannerController.json
    • {{base_path}}/scanimpl_annalysis.BusinessLogic.json
    • {{base_path}}/scanimpl_annalysis.ImageProcessor.json
    • {{base_path}}/scanimpl_annalysis.TransportManager.json
    • {{base_path}}/scanimpl_annalysis.UIView.json
  • 目標產出腳本{{script_path}}/scanimpl_annalysis_disaggregate.js

0.1.3.4 階段四:邊界驗證與死角萃取 (Validation & Dead Zone Analysis)

  • 目標:產出並執行驗證腳本,確保 JSON 數據與原始碼 100% 對齊。
  • 輸入:上述 5 個模組 JSON 與 {{source_file}}。
  • 驗證腳本規格 ({{script_path}}/scanimpl_annalysis_json.test.js):
    1. 字串對齊斷言:斷言 JSON 裡的 matcher 必須精確等於原檔在 lIndex 行的內容。
    2. 範圍合法性斷言:斷言所有 lIndexrIndex 均 > 0,嚴禁出現 -1。
    3. 覆蓋率分析:標記所有被捕捉的行區段,將未被標記的代碼區塊(如全域變數、Type 定義區)匯出至 remainings.txt
  • 驗證產出
    • {{script_path}}/dist/scanimpl_annalysis.remainings.txt (死角清單)

0.1.4. 方法分類 Tags 映射規則

請根據以下關鍵字進行簡單的字串比對分類 (如果不在此列表內,則預設分類到 "UIView" / "UIView.misc"), tags 應允許多組:
* ScannerControl (硬體掃描控制模組)
* StatrTwainScan, OnAcquire, initkscan, CheckScannerConfig, PageEnd, PageDone, R_W_Scanini, GetDefScanIni -> ScannerControl.twainWrapper

  • ImageProcessor (影像處理與轉換模組)
  • DeskewImg, Rotate, CropImg, ImageReSize_FormID, ImageReSize_tmp, CheckNeedCrop -> ImageProcessor.transformer
  • ConvertToBW, ConvertToGray, Image_Smooth, NegativeImg, CleanupBorder -> ImageProcessor.converter
  • MpsGetBarcode, Get_OMR -> ImageProcessor.barcodeRecognizer
  • FindPoint, CheckSize, GetSiteOMR -> ImageProcessor.anchorAnalyzer
  • TransportManager (安全傳輸與 API 通訊模組)

  • ProcessServlet, ProcessServlet_Get, ProcessServlet_FormData -> TransportManager.requestWrapper
  • upFile, dnFile, dnFile_Get, GetftpInfo, SetFtpInfo, FtpCaseComplete -> TransportManager.fileTransfer
  • En_DecryptionStr_Base64, LoadFileGetMD5, HTTPSClientCertificateValidate -> TransportManager.utilities
  • ZipMainFile, ZipMaskFile, ExecuteUnZip -> TransportManager.payloadArchiver
  • BusinessLogic (業務邏輯與資料解析模組)

  • SetSQLData, GetSQLData, FindSQLData, GetSetInf1, GetSetInf2, GetSetInf3, GetSetInf4, GetSetInf5, GetSetInf6, GetSetInf7 -> BusinessLogic.paramState
  • BarCode2FormID, BarCode2CaseID, FormCode2DocNo, DocNo2DocName, DocNoNeedDiv, CreateDocNo_Info, CreateCustDocNo_Info -> BusinessLogic.entityMapping
  • OMRCheckCase, OMRErr2ini, OMRErrini2List -> BusinessLogic.ormRuleEngine
  • SetUseCase, GetUseCase, OldCasetoNewCase, ErrFormtoCurrentForm, DeleteDocNoFileForESCAN -> BusinessLogic.caseManager
  • UIView (UI 視圖與介面呈現模組)

  • 包含 TreeView 的方法 (如 TreeView1Click, DrawDocItem2 等) -> UIView.treeView
  • 包含 ISB, ImageScrollBox, ScrollBox 的方法 (如 ISB1Click, CreatePreViewISB 等) -> UIView.scrollView
  • InitialLanguage, DownLanguage -> UIView.i18n
  • DisplayMode, GoViewMode -> UIView.layouts
  • DataLoading, Timer2Timer, StatusBar1DblClick -> UIView.statusMessenger

example:
pascal // CB_IMGPSScanImp.pas, 假定該分類為 ImageProcessor.anchorAnalyzer function TCB_IMGPSScanX.GetSiteOMR(FileName,Site:String;bt: Integer): Integer;

{
  "matcher": "function TCB_IMGPSScanX.GetSiteOMR(FileName,Site:String;bt: Integer): Integer;",
  "tags": [
    "ImageProcessor",
    "ImageProcessor.anchorAnalyzer"
  ],
  "deps": [],
  "lIndex": "5173",
  "rIndex": "5226",
  "description": ""
}

0.1.4.1 ScannerController (掃描硬體控制模組)

  • ScannerController.twainWrapper (TWAIN 介面與硬體初始化)
  • ScannerController.acquisitionHandler (硬體取像非同步回呼與後處理)

0.1.4.2 ImageProcessor

  • ImageProcessor.transformer (影像幾何與物理變換):如各種縮放 (ReSize)、裁切 (CheckNeedCrop)、旋轉 (Rotate)、去斜 (Deskew) 及所有 UI 比例變換等。
  • ImageProcessor.converter (影像色彩與品質轉換):包含黑白轉換 (ConvertToBW)、平滑化 (Smooth)、遮罩處理 (Mask)、浮水印列印 (PrintImg)。
  • ImageProcessor.anchorAnalyzer (特徵定位與 OMR 分析):包含了分析黑點密度的 GetSiteOMR。

0.1.4.3 TransportManager (傳輸與網路管理模組),新增了:

  • TransportManager.apiClient (RESTful / Servlet 參數與組態拉取)
  • TransportManager.fileTransfer (大檔、影像、FTP 實體傳輸)
  • TransportManager.certificateManager (HTTPS 與 SSL 憑證驗證)
  • TransportManager.payloadArchiver (ZIP 壓縮、解壓縮與進匯出封裝)

0.1.4.4 BusinessLogic

  • BusinessLogic.systemInternal': 系統參數與組態儲存庫 (Config & Parameter Repository),
  • BusinessLogic.configRepository: 系統參數與組態儲存庫 (Config & Parameter Repository),
  • BusinessLogic.ormRuleEngine': OMR 與業務規則檢核引擎 (OMR & Business Rule Engine),
  • BusinessLogic.entityMapping: 領域實體對映與結構管理器 (Entity Mapping & Structure Manager),
  • BusinessLogic.entityModel: 領域實體對映與結構管理器 (Entity Mapping & Structure Manager),
  • BusinessLogic.fileManager': 案件異動與舊案引用處理器 (Case Modification & Legacy Handler),
  • BusinessLogic.caseManager': 案件異動與舊案引用處理器 (Case Modification & Legacy Handler),
  • BusinessLogic.activeXWrapper': 處理 ActiveX 相關,

0.1.4.5 UIView

  • UIView.treeView:樹狀結構呈現與操作 (如 TreeView 的節點刷新、拖曳、點擊)
  • UIView.listView:清單結構呈現 (如 PageLV, AttListBox)
  • UIView.imageScrollBox:影像預覽與捲動 (對應 EnImgScr / TImageScrollBox 相關的視覺控制與預覽)
  • UIView.toolBar:互動工具與面板按鈕 (如各類 BtnClick、FC 分類按鈕)
  • UIView.popupMenu:快顯選單控制 (各類 PMxxxClick 或是 PopupMenuPopup)
  • UIView.i18n:多國語言與翻譯載入
  • UIView.feedback:系統狀態與進度回饋 (包含 Timer、DataLoading、StatusBar)