Instruction asset

編輯一般指令

共用內容只保存一份；工具差異放在專用補充，下載時才組合。

基本資料

名稱

唯一代稱

小寫英文、數字與連字號；建立後仍可修改但不可重複。

簡短說明

主要分類

預設排序

標籤

尚無標籤，可先到「分類與標籤」建立。

共用 Markdown 與即時預覽

共用指令內容

# 🚀 新功能開發標準作業流程 (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/` 確認測試過程中無潛在例外拋出。

格式化預覽

工具與套用範圍

適用工具

GitHub Copilot Codex Claude Code Cursor Antigravity

套用範圍

指定路徑模式

每行一筆。當次下載仍可覆寫，不會修改此正式設定。

工具專用補充

只填差異，不要複製整份共用內容。

GitHub Copilot

Codex

Claude Code

Cursor

Antigravity

修改說明

選填；會保存在這次建立的新版本中。

取消