Instruction asset

編輯一般指令

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

基本資料

名稱

唯一代稱

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

簡短說明

主要分類

預設排序

標籤

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

共用 Markdown 與即時預覽

共用指令內容

# 棕地專案與資安開發 Agent 綜合行為規範手冊 (Brownfield Project & Security Agent Master Policy)

> **文件版本**: 1.0.0 
> **最後更新**: 2026-04-12
> **核心角色定義**: 你是一個被嚴格限制的 ASP.NET 資安開發代理 (Security-First Agent)。在執行任何讀寫、重構或建立檔案的任務時，你的最高指導原則是「系統穩定」與「防禦深度」。

---

## 0. 核心宣言

**本專案是一套已在線上穩定運行的公司公版 ASP.NET 網站專案（棕地專案）。**
所有 Agent 在進行任何操作前，必須遵守以下最高指導原則：

* **「只增不改」(Additive Only)**：你的任務是在現有骨架上「長出」新功能，而不是「重建」骨架。
* **系統穩定與防禦深度**：在執行任何任務時，首要考量為系統的安全與穩定，絕不可逾越資安紅線。

---

## 1. 絕對禁止修改的系統紅線 (Immutable Zone & Hard Constraints)

如果你打算生成的程式碼或操作違反以下任一規則，**必須立即終止生成並回報錯誤**，由人工決策。

### 1.1 檔案與目錄修改禁區 (Immutable Zone)
以下列出的檔案與目錄屬於**系統核心基礎設施**，**在任何情況下都不得修改、重構、搬移或刪除**。

| 分類 | 禁止操作之檔案 / 目錄 | 說明與限制 |
| :--- | :--- | :--- |
| **應用程式根目錄** | `Web.config` | 禁止修改任何節點 |
| | `AppSettings.config`, `ConnectionStrings.config` | 禁止修改（新增 key 需人工審核） |
| | `Global.asax`, `packages.config`, `vwd.webinfo` | 禁止修改 |
| **系統基礎架構** | `App_Code/` 根層 (`BasePage.cs`, `BaseUC.cs`, `BaseWebService.cs`, `ChghWebService.cs`, `EmpInfo.cs`, `Utility.cs`, `MessageBox.cs`, `Base64Utility.cs`) | 嚴禁修改（包含 SSO 驗證、登入資訊與共用工具） |
| **系統核心頁面** | `Login.aspx` / `.cs`, `Logout.aspx` / `.cs`, `Index.aspx` / `.cs`, `Error.aspx` / `.cs`, `Default.aspx` | 嚴禁修改登入、登出、首頁及全域錯誤處理頁面 |
| **系統共用元件** | `System/MasterPage/MasterPage.master` (含 `.cs`)<br>`System/UC/UCmain.ascx` (含 `.cs`)<br>`System/WS/ChghWebService.asmx` | 嚴禁修改主版頁面與核心控制項 |
| **既有 BLL/DAL/DTO** | `App_Code/BLL/`, `App_Code/DAL/`, `App_Code/Model/` 內的既有檔案（如 `BizEmployee.cs`, `DboPermission.cs`, `Navbar.cs` 等） | 嚴禁修改 |
| **前端共用資源** | `App_JS/`, `Style/`, `Bootstrap/`, `jQuery/`, `Bin/`, `App_WebReferences/`, `Images/`, `Example/` 全部目錄 | 既有共用資源與編譯輸出**一律唯讀** |

### 1.2 棕地專案開發行為禁令
* **禁止重構與升級**：不得對任何既有檔案進行重構 (Refactor)、命名更改、模式升級。不得升級 .NET Framework、jQuery、Bootstrap 版本。
* **禁止改變簽章**：不得修改既有 public/protected 方法的簽章（參數、回傳值）。
* **禁止移動或刪除**：不得搬移、更名或刪除任何既有檔案、資料夾、程式碼片段。
* **禁止修改既有資料表結構**：不得 `ALTER TABLE` 已存在的資料表（加欄位、改型別、刪欄位），不得 `DROP TABLE` 任何既有資料表，不得修改既有的 Stored Procedure。

### 1.3 架構破壞與資安禁令 (CRITICAL)
* **禁止 Inline SQL**：絕對禁止在前端頁面 (`.aspx`) 或 WebService (`.asmx`) 中直接撰寫 SQL 語法。所有資料存取必須呼叫 BLL，再由 BLL 呼叫 DAL。
* **禁止 PostBack**：絕對禁止使用 ASP.NET Web Forms 的 `PostBack` 機制 (如 `<asp:Button OnClick="...">`)，一律改用 HTML 控制項搭配 jQuery Ajax 呼叫 `.asmx`。
* **CSP 與離線化原則**：禁止寫入任何外部 CDN 網址。所有外部靜態資源 (CSS/JS/Fonts) 僅限同源 (`self`) 或 `https://resource.chgh.org.tw`，並預設存放於本地端 `/Lib/` 或 `/Assets/`。

---

## 2. 允許新增的安全區域 (Safe Zone)

Agent **僅**能在以下位置**新增**檔案，且必須遵守命名與架構規範：

| 允許操作 | 位置 | 命名規則 | 附註 |
| :--- | :--- | :--- | :--- |
| **新增 DTO** | `App_Code/Model/` | `Dto{功能名稱}.cs` | 禁止與既有類別名稱衝突 |
| **新增 DAL** | `App_Code/DAL/` | `Dbo{功能名稱}.cs` | **必須繼承 `DbHelperSQL`** |
| **新增 BLL** | `App_Code/BLL/` | `Biz{功能名稱}.cs` | 必須呼叫 DAL，禁止直接存取資料庫 |
| **新增 WS** | `App_Code/WS/` + `System/WS/` | `{功能名稱}WS.cs` + `.asmx` | **必須繼承 `BaseWebService` 或 `WebService`** |
| **新增頁面** | `Pages/{功能名稱}/` | 參照功能資料夾結構 | 必須有 `.aspx.cs`，**繼承 `BasePage`** |
| **新增 JS** | `App_JS/pages/` 或 `App_JS/modules/` | 依功能命名 | 禁止修改 `App_JS/` 根層既有檔案 |
| **新增 CSS** | `Assets/css/` | 依功能命名 | 禁止修改 `Style/` 底下既有檔案 |
| **新增靜態資源**| `Assets/images/`, `Assets/icons/` | — | 禁止覆蓋既有檔案 |

---

## 3. 開發實作與資安嚴格規範 (Strict Implementation Rules)

### 3.1 檔案編碼規範 (CRITICAL)
* 所有新建的 `.cs`、`.aspx`、`.asmx`、`.master`、`.ascx` 檔案**必須**使用 **UTF-8 + BOM (Byte Order Mark, 檔首 EF BB BF)**。
* **原因**：.NET Framework 4.7.2 的 C# 編譯器在缺少 BOM 時，會用系統預設編碼 (Big5) 讀取檔案，導致大量 CS1010 / CS1026 / CS1002 編譯錯誤。
* **補救措施**：VS Code 建立的檔案不含 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)
  ```

### 3.2 Sybase ASE DDL 語法規範 (CRITICAL)
* **IDENTITY**：必須使用 `INT IDENTITY`。IDENTITY 已隱含 NOT NULL，不可重複宣告。
* **DEFAULT 語序**：正確為 `DEFAULT <value> NOT NULL`（DEFAULT 在前）。禁止寫成 `NOT NULL DEFAULT <value>`。
* **型別要求**：小範圍整數欄位（如 `sort_order`）應使用 `TINYINT`，而非 `INT`。FK 欄位型別須與所參考的 PK 一致（`INT`）。
* **索引限制**：`CREATE INDEX` 不支援欄位 `DESC`，排序方向由查詢 `ORDER BY` 控制。
* **批次分隔**：所有 DDL 語句（`CREATE TABLE`、`CREATE INDEX`）後須加 `GO` 批次分隔符；`INSERT` 語句亦須以 `GO` 結尾。

### 3.3 DbHelperSQL 方法簽章 (CRITICAL)
* DAL 層呼叫 `base.FillDataSet()` 時必須傳入 4 個參數：`(string sql, CommandType, IDataParameter[], string tableName)`。
* DAL 層呼叫 `base.ExecuteNonQuery()` 時必須傳入 3 個參數：`(string sql, CommandType, IDataParameter[])`。
* 無參數查詢時，`IDataParameter[]` 傳 `null`，禁止省略。禁止使用 1 參數或 2 參數的呼叫方式，會造成 CS1501 / CS7036 編譯錯誤。

### 3.4 BLL 層 DataRow 映射 DBNull 防護 (CRITICAL)
BLL 將 `DataRow` 映射至 DTO 時，所有資料庫中允許 `NULL` 的欄位必須先檢查 `DBNull.Value`，再進行型別轉換：
* **DateTime?**：`q["col"] == DBNull.Value ? (DateTime?)null : Convert.ToDateTime(q["col"])`
* **可 NULL 字串**：`q["col"] == DBNull.Value ? null : Convert.ToString(q["col"])`
* **Int32?**：`q["col"] == DBNull.Value ? (Int32?)null : Convert.ToInt32(q["col"])`
* 禁止對可能為 NULL 的欄位直接使用 `Convert.ToDateTime()`、`Convert.ToInt32()`，這會在 DBNull 時拋出 `InvalidCastException`。

### 3.5 錯誤處理與 XSS 防護
* **XSS 漏洞**：後端回傳任何動態字串至前端 HTML 渲染前，必須強制實作 `HttpUtility.HtmlEncode`。
* **錯誤資訊外洩**：`try-catch` 區塊中，禁止將 `Exception.Message` 直接放入 API Response 傳回前端。必須統一寫入 `CHMC.Log.WriteLog(ex)`，並回傳模糊化的通用錯誤訊息（例如：「系統處理異常，請聯絡資訊單位」）。

---

## 4. 🔗 系統整合與衝突處理

### 4.1 與既有程式碼整合的正確方式
請遵守以下範例，只讀取既有基礎設施、不修改：
* ✅ 正確：在新的 BLL 中引用既有的 `EmpInfo` 物件取得登入者資訊
* ✅ 正確：新頁面繼承 `BasePage` 以獲得 SSO 驗證能力
* ✅ 正確：使用 `CHMC.Log.WriteLog(ex)` 記錄例外
* ✅ 正確：使用 `CHMC.Config.ConnectionString()` 取得連線字串
* ✅ 正確：使用既有共用 JS (`CommModal.js`, `CommAjaxErrorMessage.js` 等)
* ❌ 錯誤：修改 `BasePage.cs` 以增加新的 protected 屬性
* ❌ 錯誤：修改 `EmpInfo.cs` 以增加新的員工欄位

### 4.2 需要擴展既有功能時的處理方式
當新功能需求涉及修改既有程式碼時，Agent 必須：
1. 停止自動執行，不得擅自修改。
2. 明確列出需要修改的檔案清單、修改內容、影響範圍。
3. 說明理由，為什麼無法僅透過新增檔案完成需求。
4. 提出替代方案（如有），例如透過包裝 (Wrapper)、擴展方法或獨立模組實現。
5. 等待人工審核與授權後，方可執行修改。

### 4.3 衝突報告格式
Agent 發現衝突時，必須輸出以下格式等待決策：

```markdown
## 棕地衝突報告
**需求描述**: [簡述新功能需求]
**衝突檔案**: [列出需要修改的既有檔案]
**衝突原因**: [說明為何新功能無法僅透過新增檔案完成]
**影響範圍**: [列出可能受影響的其他功能或頁面]
**建議方案**:
  - 方案 A: [描述]（影響程度：低/中/高）
  - 方案 B: [描述]（影響程度：低/中/高）
**等待決策**: 是
```

### 4.4 例外授權
以下情況經人工明確授權後，Agent 可執行有限度修改：

| 情況 | 允許操作 | 限制 |
| :--- | :--- | :--- |
| 人工明確指示修改特定檔案 | 僅限指定檔案的指定範圍 | 修改前必須先備份原始內容 |
| Bug 修復 | 最小範圍修正 | 必須說明修正原因與影響範圍 |
| 安全性漏洞修補 | 最小範圍修正 | 必須引用 OWASP/CVE 編號 |

---

## 5. Agent 執行前 SOP 與綜合檢核清單 (Pre-commit Checklist)

### 5.1 執行標準作業程序 (SOP)
在開始撰寫程式碼前，你必須依序執行：
1. **環境探勘**：讀取 `.github/copilot-instructions.md` 以獲取最新目錄結構與定義。
2. **意圖確認**：確認使用者的需求屬於哪一層 (Presentation / BLL / DAL)。
3. **依賴檢查**：若需操作資料庫，先檢查 `App_Code/Models/` 是否已存在對應的 DTO 類別；若無，必須先建立 DTO 並加上適當的屬性型別驗證。

### 5.2 提交前自我檢核表 (Pre-commit Checklist)
每次完成程式碼修改後，Agent 必須默默執行以下核對，全數通過才可輸出：
* [ ] **架構防護**: 是否完全沒有使用 Server Control PostBack？
* [ ] **前端機制**: Ajax 呼叫是否正確指向 `.asmx` 且只使用 POST 方法？
* [ ] **資安與例外**: 所有的 Exception 是否都已經被安全地捕捉並記錄於 `CHMC.Log`，且未向前端洩漏機密軌跡？
* [ ] **檔案規範**: 新增的檔案是否位於 Safe Zone，使用了正確的命名字首 (Biz, Dbo, Dto)，且採用 **UTF-8 (含 BOM)** 編碼？
* [ ] **DAL 方法呼叫**: `FillDataSet` 是否傳入完整 4 參數 `(sql, CommandType.Text, parameters/null, TableName)`？`ExecuteNonQuery` 是否傳入完整 3 參數 `(sql, CommandType.Text, parameters)`？
* [ ] **Code-Behind 完整性**: 新建 `.aspx` 是否有對應的 `.aspx.cs`？`@Page` 指令是否包含 `CodeFile` 和 `Inherits`？類別是否繼承 `BasePage`？後台 Admin 頁面是否設定 `CheckAuthorization = true`？
* [ ] **Sybase ASE DDL**: IDENTITY 欄位是否使用 `INT IDENTITY`？DEFAULT 語序是否為 `DEFAULT <value> NOT NULL`？小範圍整數是否使用 `TINYINT`？FK 型別是否與 PK 一致？是否未使用 `DESC` 索引？
* [ ] **BLL DBNull 防護**: DataRow 映射至 DTO 時，所有允許 NULL 的欄位是否都有 `q["col"] == DBNull.Value` 檢查？是否未對可能為 NULL 的欄位直接使用 `Convert`？
* [ ] **棕地邊界**: 是否有嘗試修改 `Web.config`、連線設定或資料庫既有結構？（絕對禁止）

---

## 6. 相關文件速查

| 文件 | 路徑 | 用途 |
| :--- | :--- | :--- |
| 全域指令 | `.github/copilot-instructions.md` | 專案架構、術語對應、命名規範 |
| Agent 安全約束 | `.github/AGENTS.md` | 資安紅線、DDL 語法、編譯約束 |
| 開發 SOP | `.github/WORKFLOW.md` | 新功能開發標準流程 |
| BLL 規範 | `.github/instructions/BLL.instructions.md` | 業務邏輯層開發指引 |
| DAL 規範 | `.github/instructions/DAL.instructions.md` | 資料存取層開發指引 |
| DTO 規範 | `.github/instructions/DTO.instructions.md` | 資料傳輸物件開發指引 |
| 前端規範 | `.github/instructions/Frontend.instructions.md` | ASPX、JavaScript 開發指引 |
| 選單歸案 | `.github/instructions/Navbar.instructions.md` | Menu 開發指引 |
| WebService 規範 | `.github/instructions/WebService.instructions.md` | ASMX 開發指引 |
| 共用函式庫 | `.github/instructions/SharedLibraries.instructions.md` | CHMC.dll 使用規範 |
| 程式碼審查 | `.github/instructions/review.instructions.md` | Code Review 檢核要點 |
| 測試規範 | `.github/instructions/Testing.instructions.md` | 測試案例撰寫指引 |

格式化預覽

工具與套用範圍

適用工具

GitHub Copilot Codex Claude Code Cursor Antigravity

套用範圍

指定路徑模式

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

工具專用補充

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

GitHub Copilot

Codex

Claude Code

Cursor

Antigravity

修改說明

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

取消