🚀 新功能開發標準作業流程 (SOP)

本文件定義了專案中開發新功能的標準生命週期，所有開發人員與 AI 輔助工具在建構功能時，皆必須嚴格遵循此流程。

階段 1：既有資源評估 (Assessment)

在撰寫任何新程式碼之前，必須先確認是否能重複使用現有資源，以避免疊床架屋。

* 盤點共用核心：檢查 CHMC.dll。

* 決策路徑：

* 已有可用方法（如：加解密、日誌記錄、設定檔讀取）：優先引用該方法，並於程式碼註解中明確標示來源。

* 無可用方法：進入「階段 2」開始全新開發。

階段 2：需求分析與系統設計 (Design)

確保開發目標與資料結構在動工前已完全底定。

1. 功能對焦：釐清並確認功能目標、使用者故事（User Story）以及預期的輸入/輸出。

2. 資料庫設計 (DB)：設計關聯式資料表結構，確立主鍵 (PK)、外鍵 (FK) 與必要的索引 (Index)，並於 Sybase ASE 資料庫中建置完成。

* ⛔ Sybase ASE DDL 語法規範：

* IDENTITY 欄位必須使用 INT IDENTITY，IDENTITY 已隱含 NOT NULL。

* DEFAULT 語序：DEFAULT <value> NOT NULL（DEFAULT 在前，NOT NULL 在後）。

* 小範圍整數欄位（如 sort_order）使用 TINYINT。

* CREATE INDEX 不支援 DESC，排序方向由查詢 ORDER BY 控制。

* FK 欄位型別須與所參考的 PK 一致（INT）。

* 每個 DDL 語句後須加 GO 批次分隔符。

3. 通訊介面設計 (API)：定義 WebService 預計提供的 WebMethod，以及前後端交換資料的 JSON 格式 (Request / Response)。

階段 3：後端核心建構 (Backend Construction)

嚴格遵守「由下而上」的順序進行開發，確保資料流的安全與穩定。

> ⛔ 全階段通用約束 — 檔案編碼：

> 本階段（及階段 4）所有新建的 .cs、.aspx、.asmx、.master、.ascx 檔案必須使用 UTF-8 + BOM 編碼。

> VS Code 的 create_file 工具不會自動加 BOM，建檔後須立即用 PowerShell 補加：

> ```powershell

> $utf8BOM = New-Object System.Text.UTF8Encoding $true

> $utf8NoBOM = New-Object System.Text.UTF8Encoding $false

> $content = [System.IO.File]::ReadAllText("檔案路徑", $utf8NoBOM)

> [System.IO.File]::WriteAllText("檔案路徑", $content, $utf8BOM)

> ```

1. 建立 Models (DTO) 類別

* 位置：App_Code/Models/

* 命名：Dto{功能名稱}.cs

2. 建立 DAL 類別

* 位置：App_Code/DAL/

* 命名：Dbo{功能名稱}.cs

* 規範：遵循 #file:.github/instructions/DAL.instructions.md（必須使用參數化查詢防範 SQL 注入）。

* ⛔ DbHelperSQL 方法簽章：FillDataSet 必須傳 4 參數 (sql, CommandType.Text, parameters/null, TableName)；ExecuteNonQuery 必須傳 3 參數 (sql, CommandType.Text, parameters)。禁止省略任何參數。

3. 建立 BLL 類別

* 位置：App_Code/BLL/

* 命名：Biz{功能名稱}.cs

* 規範：遵循 #file:.github/instructions/BLL.instructions.md（負責商業邏輯與 DTO 驗證）。

* ⛔ DataRow 映射 DBNull 防護：將 DataRow 映射至 DTO 時，所有資料庫中允許 NULL 的欄位（如 data_dt、data_op，或區分建立/更新時的 create_dt、data_dt、create_op、data_op）必須先以 q["col"] == DBNull.Value 判斷，再進行 Convert.ToDateTime() / Convert.ToInt32() 等型別轉換。直接轉換 DBNull 會拋出 InvalidCastException。

4. 建立 WebService 類別

* 位置：App_Code/WS/

* 命名：{功能名稱}WS.cs

* 規範：遵循 #file:.github/instructions/WebService.instructions.md（必須實作全域例外攔截與 CHMC.Log 日誌記錄）。

階段 4：前端介面與串接 (Frontend Development)

建構使用者介面，並透過 AJAX 與後端 API 進行安全通訊。

1. ⛔ 建立 ASPX 頁面與 Code-Behind (CRITICAL)：

* 每個 .aspx 頁面必須同時建立對應的 .aspx.cs code-behind 檔案。禁止建立沒有 code-behind 的 .aspx 頁面。

* .aspx 的 <%@ Page %> 指令必須包含 CodeFile="PageName.aspx.cs" 與 Inherits="Pages_Feature_PageName"。

* Code-behind 類別必須繼承 BasePage，以取得 SSO 驗證、Session 管理與權限檢查能力。

* 後台 Admin 頁面：CheckAuthorization 維持預設 false，但仍須繼承 BasePage。

* 前台公開頁面：CheckAuthorization 維持預設 false，但仍須繼承 BasePage。

* 類別命名規則：依路徑以底線串接，例如 Pages/Welfare/Admin/Dashboard.aspx → Pages_Welfare_Admin_Dashboard。

* 同時建立對應的 .js 檔案。

* 規範：遵循 #file:.github/instructions/Frontend.instructions.md 中的「⛔ 0. ASPX Code-Behind 強制規範」。

2. 設計 HTML 結構：使用 Bootstrap 5 組件庫設計響應式 (RWD) 結構，絕對禁止使用會觸發 PostBack 的伺服器控制項。

3. 撰寫 JavaScript：

* 使用 jQuery 3.7.2 的 AJAX (POST) 呼叫「階段 3」建立的 WebService。

* 將回傳資料安全地渲染至頁面（強制使用 Encode 或 .text() 防範 XSS）。

* 規範：遵循 #file:.github/instructions/Frontend.instructions.md。

階段 5：整合與測試 (Testing & Delivery)

確保品質達到標準後方可進入版控。

1. 本機驗證：在本機開發環境進行完整的端到端 (End-to-End) 功能測試，確保前後端 JSON 通訊無誤且無 500/403 錯誤。

2. 相容性測試：進行跨瀏覽器測試（如 Edge, Chrome），確保 UI 渲染與 JS 執行正常。

3. 日誌審查：檢查 App_Data/Logs/ 確認測試過程中無潛在例外拋出。