AGENTS.md
從 Google Drive .github/AGENTS.md 匯入
共用指令內容
使用中棕地專案與資安開發 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 補加：
$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 發現衝突時，必須輸出以下格式等待決策：
## 棕地衝突報告
**需求描述**: [簡述新功能需求]
**衝突檔案**: [列出需要修改的既有檔案]
**衝突原因**: [說明為何新功能無法僅透過新增檔案完成]
**影響範圍**: [列出可能受影響的其他功能或頁面]
**建議方案**:
- 方案 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 | 測試案例撰寫指引 |