# UPDSTK 專案目錄結構說明

> 更新日期：2026-04-22
> 專案：UPDSTK — 庫存資料庫更新工具（Clipper → Harbour GTWVT 轉換版）

---

## 專案根目錄：`E:\ConvertFW\UpdStk\`

```
UpdStk\
  origin\      原始 Clipper 程式碼（唯讀，僅供參考）
  source\      Harbour 原始碼（主程式 + 相容層）
  include\     CH 標頭檔
  build\       編譯輸出目錄（EXE、INI、ICO、HBP）
  doc\         技術文件（本檔所在目錄）
```

---

## origin\ — 原始 Clipper 程式碼

> 轉換前的最原始版本，**不可修改**，僅供對照參考。

| 檔案 | 說明 |
|------|------|
| `UPDSTK_ORIGINAL.PRG` | 轉換前的原始 Clipper 主程式（完整保留） |
| `UPDSTK.BAT` | 原始 DOS 批次啟動腳本 |
| `UPDSTK.BNK` | 原始銀行/備份設定檔 |
| `UPDSTK.DOC` | 原始程式說明文件 |
| `UPDSTK.EXE` | 原始 Clipper 編譯執行檔 |
| `UPDSTK.RMK` | 原始 MAKE 編譯腳本 |

---

## source\ — Harbour 原始碼

### 主程式層

| 檔案 | 說明 |
|------|------|
| `main_updstk.prg` | **程式進入點**。初始化 BIG5/GTWVT/UNITRANS/UsrFont/滑鼠，最後呼叫 UpdStk() |
| `UPDSTK.PRG` | **主程式**。原 Clipper 邏輯保留，UI 部分轉換為 Harbour GTWVT |
| `DIALOG.PRG` | 對話框相關函式（AskBox 等） |

### source\compat\ — 相容層

> 補齊 UPDSTK.PRG 所需、但 Harbour 標準函式庫未提供的函式。
> 全部從 HBSTK 專案移植而來。

| 檔案 | 說明 |
|------|------|
| `updstk_errorsys.prg` | **輕量錯誤攔截系統**。安裝 ErrorBlock，顯示 Alert 並寫入 Error.TXT |
| `usrfont.prg` | **自訂 CJK 字型**。載入 USRFONT.24M，提供 UsrFontInit/SetIcon/SetCursorHeight |
| `mouse_handler.prg` | **滑鼠處理器**。MsHandler CLASS + 所有 wrapper 函式（MsAddBtn/MsHitTest 等） |
| `unicode_ime.prg` | **Unicode IME**。處理 BIG5 輸入法與 GTWVT Unicode 模式整合 |
| `color_theme.prg` | **色彩主題**。LoadColorTheme() 從 stk.ini 讀取 16 色配置 |
| `ini_loader.prg` | **INI 載入器**。LoadIni()/GETE() 解析 stk.ini 設定值 |
| `clipper_compat.prg` | **Clipper 相容函式**。補齊 Clipper 原生函式（Color/AWICursor 等） |
| `funcky_compat.prg` | **FUNCKY 函式庫相容**。補齊 FUNCKY.CH 所定義的函式 |
| `comix_compat.prg` | **COMIX CDX 相容**。CmxAutoOpen 等 COMIX 函式的 stub |
| `dos_stubs.prg` | **DOS 環境 stub**。補齊僅在 DOS/Clipper 有的低階函式 |
| `updstk_compat.prg` | **UPDSTK 專用 stub**。ELAPTIME/FEOF/FREADLINE/CHDIR/MKDIR/SETDRIVE 等 |

---

## include\ — CH 標頭檔

| 檔案 | 說明 |
|------|------|
| `SYSTEM.CH` | 系統常數定義（FORM_COLOR/BLANK_COLOR/LEFT_ALIGN 等） |
| `CustomChar.ch` | 自訂字元常數（DG_CIR_* / UC_CIR_* / DG_PAR_* 等圈號定義） |
| `AP.CH` | 應用程式常數 |
| `FUNCKY.CH` | FUNCKY 函式庫常數定義 |
| `INKEY.CH` | 按鍵碼常數（K_ENTER / K_ESC 等） |
| `WinForm.ch` | 視窗表單常數 |
| `CM52.CH` | COMIX 52 格式常數 |
| `CMX52.CH` | COMIX 52 擴充常數 |
| `COLOR.CH` | 顏色常數定義 |
| `MENUMS.CH` | 選單編號常數 |
| `QUICKBOX.CH` | 快速對話框常數 |

---

## build\ — 編譯目錄

> 執行 `rebuild.bat` 或 `hbmk2 updstk.hbp -comp=bcc` 即可重新編譯。

### 編譯設定

| 檔案 | 說明 |
|------|------|
| `updstk.hbp` | **Harbour 編譯設定檔**。列出所有來源檔、函式庫、旗標 |
| `updstk.rc` | Windows 資源腳本（內嵌圖示用） |
| `rebuild.bat` | 一鍵編譯批次檔（kill → build → run） |

### 執行時期檔案

| 檔案 | 說明 |
|------|------|
| `UpdStk.exe` | **主執行檔**（編譯輸出） |
| `stk.ini` | 系統設定檔（字型/路徑/顯示參數） |
| `updstk_icon.ico` | 程式圖示（資料庫＋更新箭頭，含 16~256px 多尺寸） |

### 字型資源

| 檔案 | 說明 |
|------|------|
| `USRFONT.24M` | 自訂 CJK 字型點陣資料（24×24 bitmap） |
| `USRFONT.UMAP` | Unicode 對應表（Big5 <-> 字型 slot） |
| `USRFONT.BCACHE` | 字型 bitmap 快取 |
| `ASCFONT.15` | ASCII 字型點陣資料 |
| `ASCFONT.UMAP` | ASCFONT Unicode 對應表 |
| `ASCFONT.BCACHE` | ASCFONT bitmap 快取 |

### 編譯暫存 / Log

| 目錄/檔案 | 說明 |
|-----------|------|
| `hbmk\` | hbmk2 暫存目錄（.c / .obj 中間檔，不需提交） |
| `log\out.log` | 最近一次編譯標準輸出 |
| `log\err.log` | 最近一次編譯錯誤輸出 |

---

## 編譯環境

| 項目 | 路徑 |
|------|------|
| Harbour 32 | `E:\Harbour32\` |
| BCC 32 (Borland C++ 7.73) | `E:\BCC7732\` |
| 編譯指令 | `hbmk2 updstk.hbp -comp=bcc` |
| 編譯工作目錄 | `E:\ConvertFW\UpdStk\build\` |

### 必要環境變數

```bat
set PATH=E:\BCC7732\bin;E:\Harbour32\bin\win\bcc;%PATH%
set HB_CPTERM=BIG5
set HB_CODEPAGE=BIG5
set HB_USER_CFLAGS=-IE:\BCC7732\INCLUDE\windows\crtl -IE:\BCC7732\INCLUDE\windows\sdk
set HB_USER_LDFLAGS=-LE:\BCC7732\LIB -LE:\BCC7732\LIB\psdk
```

---

## stk.ini 主要設定項目

```ini
; 顯示設定
FontName=DFKai-SB       ; GTWVT 字型名稱
FontSize=0              ; 0=自動依螢幕計算
Rows=30                 ; Console 列數
Cols=80                 ; Console 欄數

; 游標設定
CARET_NORMAL_H=0        ; 一般游標高度（px），0=預設
CARET_INSERT_H=0        ; 插入模式游標高度（px），0=全高

; 路徑設定（由 stk.ini 或環境變數提供）
LOC_DBF=                ; DBF 資料庫目錄
LOC_TMP=                ; 暫存目錄
LOC_UPDATE=             ; 更新來源目錄
```

---

## 技術重點

| 功能 | 實作方式 |
|------|----------|
| 中文顯示 | BIG5 codepage + GTWVT CHINESEBIG5_CHARSET(136) |
| 框線字元 | UNITRANS chr(1-18) → Unicode box-drawing（避免 BIG5 衝突） |
| 自訂字型 | UsrFontInit("USRFONT.24M") 載入 CJK bitmap |
| 滑鼠支援 | MsHandler CLASS + SET EVENTMASK 255 + MessageBox 滑鼠點擊 |
| 錯誤處理 | ErrorSys() 安裝 ErrorBlock，寫入 Error.TXT + Alert 顯示 |
| INI 設定 | LoadIni() 解析 stk.ini，GETE() 讀取個別設定值 |