Prompt file imported from HyperLee/SlidingWindow (.github/prompts/spec.prompt.md). Copyright stays with the author.

SlidingWindow 滑動視窗 — 開發規格書

本文件為「SlidingWindow（滑動視窗演算法）教學專案」的完整開發規格，內容包含專案目標、功能需求、檔案結構、實作細節、測試規劃與交付驗收條件。撰寫者請依本規格進行實作。

1. 專案目標

打造一個專門介紹 滑動視窗（Sliding Window）演算法 的教學型 .NET 主控台專案，內容兼具：

1. 理論說明：在 README.md 提供完整、詳細、全面的演算法概念介紹。
2. 程式範例：以 C# 實作 8–10 題 LeetCode 經典滑動視窗題目，每題獨立類別、含詳細註解、時空間複雜度分析與 ASCII 視窗移動圖解。
3. 可執行示範：透過 Program.cs 提供互動式選單，逐題展示輸入、輸出與執行過程。
4. 單元測試：以 xUnit 對每題實作進行正確性驗證，包含正常案例與邊界案例。
5. 延伸練習：在 README.md 末尾整理 LeetCode 題號、難度、連結與練習建議清單。

2. 技術規格

3. 專案結構

SlidingWindow/
├── SlidingWindow.sln
├── README.md                           # 演算法完整教學文件（繁體中文）
├── .editorconfig
├── .gitignore
├── .github/
│   ├── instructions/csharp.instructions.md
│   └── prompts/spec.prompt.md          # 本規格書
├── SlidingWindow/                      # 主專案
│   ├── SlidingWindow.csproj
│   ├── Program.cs                      # 互動式選單入口
│   └── Algorithms/                     # 每題獨立一個類別檔案
│       ├── ISlidingWindowDemo.cs       # 共用展示介面
│       ├── MaxSumSubarrayOfSizeK.cs            # 題 1
│       ├── LongestSubstringWithoutRepeating.cs  # 題 2
│       ├── FindAllAnagramsInString.cs           # 題 3
│       ├── MinimumWindowSubstring.cs            # 題 4
│       ├── MinimumSizeSubarraySum.cs            # 題 5
│       ├── LongestSubstringWithKDistinct.cs     # 題 6
│       ├── PermutationInString.cs               # 題 7
│       ├── SlidingWindowMaximum.cs              # 題 8
│       ├── FruitIntoBaskets.cs                  # 題 9
│       └── LongestRepeatingCharacterReplacement.cs  # 題 10
└── SlidingWindow.Tests/                # 測試專案
    ├── SlidingWindow.Tests.csproj
    └── Algorithms/
        ├── MaxSumSubarrayOfSizeKTests.cs
        ├── LongestSubstringWithoutRepeatingTests.cs
        ├── ... （與題目一一對應）

4. README.md 內容規範

README.md 使用 繁體中文，章節結構如下：

1. 專案簡介：一句話說明專案目的與適用對象。
2. 什麼是滑動視窗：定義、與雙指針的關係、為何能將 O(n²) 降至 O(n)。
3. 核心機制：左右指標、視窗擴張/收縮、增量更新（add new、remove old）。
4. 演算法類型：
   • 4.1 固定窗口大小（Fixed-size Window）：含通用模板（虛擬碼）。
   • 4.2 可變窗口大小（Variable-size Window）：含通用模板（虛擬碼）。
5. 解題步驟 SOP：建立窗口 → 擴張 → 判斷 → 收縮 → 更新答案。
6. 適用題型特徵：何時應該想到滑動視窗。
7. ASCII 視覺化範例：以「最大和子陣列」為例，逐步畫出視窗移動。
8. 範例題目索引：列出本專案 10 題實作，含題號、題名、難度、複雜度。
9. 如何執行：

   dotnet build
   dotnet run --project SlidingWindow
   dotnet test

10. LeetCode 練習清單：表格形式，欄位包含 #、題名（中/英）、難度、連結、是否已實作、相似題型。建議至少 20 題，涵蓋 Easy / Medium / Hard。
11. 參考資料：權威來源連結（LeetCode、Wikipedia、教學文章）。
12. 授權：MIT 或專案既有授權。

5. 演算法範例題目清單（10 題）

每題需在 Algorithms/ 目錄下建立獨立 .cs 檔案，並透過 ISlidingWindowDemo 介面註冊到 Program.cs 選單。

6. 程式碼撰寫規範

6.1 共用介面 ISlidingWindowDemo

namespace SlidingWindow.Algorithms;

/// <summary>
/// 統一的演算法展示介面，讓 Program.cs 能以選單方式逐題執行。
/// </summary>
public interface ISlidingWindowDemo
{
    /// <summary>選單顯示用題目名稱（含 LeetCode 題號）。</summary>
    string Title { get; }

    /// <summary>難度（Easy / Medium / Hard）。</summary>
    string Difficulty { get; }

    /// <summary>執行示範：列印題目說明、輸入、輸出與視窗移動過程。</summary>
    void Run();
}

6.2 每個演算法類別必備項目

1. 檔案首行：namespace SlidingWindow.Algorithms;（file-scoped namespace）。
2. 類別 XML 註解：說明題目、輸入輸出、思路、複雜度。
3. 公開核心方法（純函式，便於測試），例如：

   public static int MaxSum(int[] nums, int k);
   public static int LengthOfLongestSubstring(string s);

4. Run() 方法：列印 1–2 組示範輸入、呼叫核心方法、輸出結果，並以 ASCII 圖示視窗移動（至少對首組輸入展示 3–5 步）。
5. 註解規範：
   • 使用 /// XML 文件註解描述公開方法、參數、回傳值。
   • 關鍵步驟（指標移動、視窗收縮、答案更新）以 // 行內註解說明「為什麼」這樣寫。
6. 錯誤處理：對非法輸入（null、空陣列、k <= 0 或 k > n）拋出 ArgumentException 或 ArgumentNullException，並在 XML 註解中以 <exception> 標註。
7. Null 安全：遵循 is null / is not null 寫法，不使用 == null。
8. C# 14 風格：偏好模式比對、switch expression、集合表達式 [..]、nameof 取代字串字面值。

6.3 ASCII 視窗圖解範例（範本）

輸入: nums = [2, 1, 5, 1, 3, 2], k = 3
步驟 1: [2  1  5] 1  3  2   sum = 8
步驟 2:  2 [1  5  1] 3  2   sum = 7
步驟 3:  2  1 [5  1  3] 2   sum = 9  ← 目前最大
步驟 4:  2  1  5 [1  3  2]  sum = 6
最大和 = 9

每題的 Run() 至少需以類似格式展示一組輸入。

6.4 Program.cs 互動式選單

• 啟動時以表格列出 10 題（含難度標記）。
• 接受使用者輸入：
  • 數字 1–10：執行對應題目的 Run()。
  • a：依序執行全部題目。
  • q：離開程式。
• 使用 List<ISlidingWindowDemo> 集中註冊，避免硬編碼 switch。
• 對於非預期輸入給予友善提示，不應拋出例外。

7. 測試規範（SlidingWindow.Tests）

7.1 專案設定

• 模板：dotnet new xunit -n SlidingWindow.Tests，目標框架 net10.0。
• 透過 <ProjectReference> 引用主專案。
• 加入 sln：dotnet sln add SlidingWindow.Tests。

7.2 測試覆蓋要求

每題至少包含以下測試案例：

1. 典型案例：題目原文範例。
2. 邊界案例：
   • 空輸入（陣列 []、字串 ""） → 預期回傳 0 或空集合。
   • 單一元素 / 單一字元。
   • 全部相同元素。
   • k 等於陣列長度。
3. 無解案例：例如最小覆蓋子字串中 t 無法在 s 中組成。
4. 非法輸入案例：null、k <= 0、k > n → 預期 Throws<ArgumentException> 或 Throws<ArgumentNullException>。

7.3 命名與風格

• 測試類別：{演算法類別}Tests。
• 測試方法：MethodName_Scenario_ExpectedResult，例如 MaxSum_TypicalInput_ReturnsLargestWindowSum。
• 使用 [Theory] + [InlineData] 處理多組輸入。
• 不撰寫 // Arrange / Act / Assert 註解（依據 csharp.instructions.md）。

8. 建置與執行指令

# 建置整個方案
dotnet build SlidingWindow.sln

# 執行主程式（互動式選單）
dotnet run --project SlidingWindow

# 執行所有測試
dotnet test SlidingWindow.sln

# 僅執行單題（範例）
dotnet test --filter "FullyQualifiedName~MinimumWindowSubstringTests"

9. 交付驗收條件（Definition of Done）

實作完成後，須同時滿足下列所有條件方視為完成：

• 1. dotnet build 通過，無警告（或僅有可接受之資訊性警告）。
• 2. dotnet test 全部通過，且每題至少 4 個測試案例（含 1 個邊界、1 個非法輸入）。
• 3. dotnet run --project SlidingWindow 可顯示選單並正確執行 10 題範例。
• 4. README.md 章節 1–12 全部完成，內含至少 1 張 ASCII 視窗圖解、至少 20 題 LeetCode 練習清單。
• 5. 所有 .cs 公開 API 含 XML 文件註解。
• 6. 所有檔案使用 UTF-8（無 BOM 或一致採 BOM，與既有檔案保持一致）。
• 7. 程式碼遵循 .editorconfig 與 csharp.instructions.md（PascalCase / camelCase / I 介面前綴 / file-scoped namespace / is null 寫法）。
• 8. SlidingWindow.sln 同時包含主專案與測試專案。

10. 開發順序建議

1. 建立 Algorithms/ISlidingWindowDemo.cs 共用介面。
2. 依「題 1 → 題 10」順序逐題實作，每題完成後立即補上對應的單元測試（TDD 風格）。
3. 完成核心邏輯後，改寫 Program.cs 為互動式選單。
4. 建立 SlidingWindow.Tests 專案並加入 sln。
5. 撰寫 README.md（理論章節先寫，題目表格在實作後補齊）。
6. 跑 dotnet build + dotnet test 全綠後完成。

11. 不在本次範圍內（Out of Scope）

• Web API、ASP.NET Core、資料庫整合、JWT 驗證等項目（僅為 csharp.instructions.md 通用建議，本專案為主控台教學專案，不需採用）。
• 容器化、CI/CD、部署。
• 效能基準測試（BenchmarkDotNet）。
• 國際化（i18n）、英文版 README。

如未來需要，可在後續迭代再加入。