Skill asset

編輯 Skill

Skill 是完整資料夾資產；建立後可逐一加入腳本、參考文件、範本、圖片與子資料夾。

Skill 名稱

唯一代稱

簡短說明

主要分類

標籤

SKILL.md

五種工具預設適用

---
name: webservice-doc-generator
description: "Use when: 依 WebService範本.doc 產生 ASMX WebService 串接 Word 文件、WS table 文件、WebMethod 參數回傳文件，輸出到 說明文件。同一個 ASMX 必須產生同一份 doc，文件內依 WebMethod 分章節整理，不可拆成每個 Method 一份。"
argument-hint: "可指定 ASMX；若指定 WebMethod，仍輸出該 ASMX 的單一整合文件並標示指定方法"
---

# WebService Word 文件產生器

## 技能用途

當使用者要求「依 WebService 範本產生 Word」、「產生 WS 串接文件」、「整理 ASMX method 參數與回傳欄位」、「將同一個 ASMX 的 WebMethod 彙整成 Word」時，使用本 Skill。

本 Skill 的目標是：讀取 ASP.NET Web Site Project 內的 ASMX / WebMethod 程式碼，套用本 Skill 內建的 `assets/WebService範本.doc`，產生可提供開發人員串接 WS 的 Word 文件，並放在 `說明文件/` 資料夾。

**重要規則：同一個 ASMX 只產生一份 Word 文件。** 若同一個 ASMX 內有多個 WebMethod，必須全部放在同一份文件中，依 WebMethod 分章節整理參數、回傳欄位與實作參考說明。禁止為同一個 ASMX 拆成多個 `{method}.docx`。

## 固定輸入來源

優先接受以下來源：

1. 使用者指定的 `.asmx` 或 `App_Code/WS/*.cs`。
2. 使用者指定的 WebMethod 名稱。
3. 若未指定方法，從 `WWWRoot/App_Code/WS/**/*.cs` 或 `WWWRoot/System/WebService/**/*.asmx` 的 WebService 清單中挑選一個代表性 ASMX。
4. 讀取該 ASMX 對應 code-behind 內所有 `[WebMethod]` 的 XML 註解、`[WebMethod(Description = "...")]`、參數簽章、回傳 JSON 結構、DTO 類別欄位與實際前端 AJAX 呼叫方式。
5. 若使用者指定單一 WebMethod，仍以該 WebMethod 所屬 ASMX 為單位產生整合文件；可在文件內優先排列或標示指定方法，但不可只輸出單一 Method 文件。

挑選 ASMX 或 Method 排序時，優先選擇：

1. 查詢型方法。
2. 有明確 `WebMethod Description`。
3. 參數與回傳 DTO 清楚。
4. 有既有前端 AJAX 呼叫可參考。

## 固定輸出

輸出 Word 檔案到：

```text
說明文件/{asmx}_{中文服務說明}_API規格書.docx
```

命名規則：

1. `{asmx}` 使用 `.asmx` 檔名去除副檔名，例如 `ServiceNameWS`。
2. `{中文服務說明}` 優先使用 WebService 類別 XML summary，例如 `社團WebService`；若沒有則使用 ASMX 名稱。
3. 檔名固定以 `_API規格書.docx` 結尾，表示這是一份 ASMX 整合文件。
4. 檔名只保留 Windows 可用字元；移除 `\ / : * ? " < > |` 與多餘空白。
5. 不要加入額外固定字尾，例如 `_重新產生`、`_實作說明版`，除非原檔被使用中無法覆寫。若需避開鎖定，才在檔名後加時間戳或明確說明原因。
6. 若同目錄已存在舊版 `{asmx}_{method}_{中文說明}.docx` 拆分文件，產生整合文件成功後應嘗試刪除；若被 Word 或預覽程序鎖定，保留並在回覆中說明。

## Skill 資產

本 Skill 攜帶可編輯 Word 範本：

```text
./assets/WebService範本.doc
```

產生文件時必須複製範本內容後另存新檔，不可覆寫 Skill 資產。

## Word 範本結構

`WebService範本.doc` 主要提供服務基本資料與初始表格樣式。整合文件產生後應包含：

| 表格 | 用途 |
|---|---|
| Table 1 | 服務基本資料：負責人員、測試環境 URL、正式環境 URL、ASMX 路徑、Method、Protocols、說明、是否多筆資料 |
| Table 2 | Method 清單：Method、Protocols、說明、是否多筆資料 |
| 後續表格 | 每個 WebMethod 各一張查詢參數與回傳欄位表 |

## Table 1 填寫規則

文件第一個段落通常為：

```text
{{API功能}}規格書
```

產生文件時必須將 `{{API功能}}` 替換為 ASMX 服務中文說明，例如 `社團 WebService API`。不可保留 `{{API功能}}` 預留字。

| 列 | 內容 |
|---|---|
| R1C2 | 負責人員；來源未提供時保持空白 |
| R2C2 | 測試環境 URL；來源未提供時填 `依測試環境網域 + {asmx_path}` |
| R3C2 | 正式環境 URL；來源未提供時填 `依正式環境網域 + {asmx_path}` |
| R4C2 | ASMX 路徑，例如 `/System/WebService/{asmx}.asmx` |
| R5C2 | 此 ASMX 內所有 WebMethod 名稱，以 `、` 分隔 |
| R6C2 | `POST`；若部分方法使用 multipart/form-data，需一併註明 |
| R7C2 | ASMX 整體中文說明與關鍵行為；可包含 `res.d` 包裝提醒 |
| R8C2 | 依 WebMethod 而定；若部分方法回傳陣列或清單，需一併註明 |

## Table 2 Method 清單規則

整合文件的 Table 2 是 Method 清單，不放查詢參數與回傳欄位。

固定欄位：

| 欄 | 內容 |
|---|---|
| C1 | Method |
| C2 | Protocols |
| C3 | 說明 |
| C4 | 是否多筆資料 |

Method 清單第一列為標題列，底色可沿用查詢參數標題列色碼 `16764057`。每個 WebMethod 一列。

## WebMethod 章節與參數表規則

Table 2 後方必須依序為每個 WebMethod 建立章節：

```text
Method：{method} - {中文說明}
ASMX 路徑：{asmx_path}/{method}
Protocols：{POST 或 POST (multipart/form-data)}
是否回傳多筆資料：{是/否}
```

每個 WebMethod 章節下方各建立一張 4 欄表格，僅放「查詢參數」與「回傳欄位」。不要把呼叫範例、解析方式、權限說明、注意事項放進參數表。

固定欄位：

| 欄 | 內容 |
|---|---|
| C1 | 參數名稱或回傳欄位名稱 |
| C2 | 資料型別 |
| C3 | 欄位中文名稱 |
| C4 | 備註 |

表格壓縮規則：

1. 不要保留範本多餘空白列。
2. 每一列四欄都要填入有意義內容；若是區塊標題列，C2-C4 填原標題欄位名稱，不留空白。
3. 回傳欄位若為 array，該列 C2 填 `array`，C4 需加註 `詳見下方資料({arrayName})` 或同等說明。
4. array 底下欄位需先建立一列合併 4 欄的陣列資料標示列，例如 `資料(data)`，再列出陣列物件欄位。
5. array 物件欄位只寫回傳欄位名稱，例如 `AlbumId`、`AlbumName`；不要寫成 `data[].AlbumId` 或 `{arrayName}[].FieldName`。
6. 原範本中可能有合併儲存格列；不要用逐列刪除的方式壓縮原表格，容易因合併列觸發 Word COM `HRESULT`。應先在原 Table 2 後插入新的 Method 清單表，再刪除原 Table 2；每個 WebMethod 的參數表則在後續章節另外建立。
7. 每個 WebMethod 參數表的列數應等於：參數標題列 + 參數列 + 回傳標題列 + 回傳外層欄位列 + array 標示列 + array 物件欄位列。

表格底色規則必須比照範本：

| 列類型 | 範例 | 底色 |
|---|---|---|
| 查詢參數標題列 | `查詢參數` | `16764057` |
| 回傳欄位標題列 | `回傳欄位` | `14857101` |
| array 資料標示列 | `資料(data)` | `12379094` |

array 資料標示列必須合併整列 4 欄。

每個 WebMethod 參數表建議順序：

1. `查詢參數 | 資料型別 | 欄位中文名稱 | 備註`
2. 每個 method 參數一列。
3. `回傳欄位 | 資料型別 | 欄位中文名稱 | 備註`
4. JSON 外層欄位，例如 `success`、`message`、`data`。
5. 若外層欄位含 array，例如 `data | array | ...`，下一列建立 `資料(data)` 合併標示列。
6. DTO 或 array 物件欄位，例如 `Id`、`Name`、`AlbumId`、`AlbumName`。

## 實作參考說明規則

以下內容必須放在 WebMethod 參數表外面的文件段落，不可放入 Method 清單或參數表：

1. 呼叫範例。
2. ASMX `res.d` 解析方式。
3. 權限說明。
4. 錯誤處理或注意事項。

段落格式：

```text
實作參考說明
呼叫範例：POST {asmx_path}/{method}；contentType=application/json; charset=utf-8；data={...}
解析方式：var d = typeof res.d !== "undefined" ? res.d : res; var obj = typeof d === "string" ? JSON.parse(d) : d;
權限說明：{依來源整理，若無權限檢查則寫無特殊權限檢查}
```

## PowerShell Word COM 流程

在 Windows 且 Word COM 可用時，使用 PowerShell 操作 Word 範本。不要用純文字方式寫入 `.docx`。

標準流程：

```powershell
$skillDir = Join-Path $PWD '.github\skills\webservice-doc-generator'
$template = Join-Path $skillDir 'assets\WebService範本.doc'
$outputDir = Join-Path $PWD '說明文件'
$output = Join-Path $outputDir '{asmx}_{中文服務說明}_API規格書.docx'

if (-not (Test-Path $template)) {
    throw "找不到 WebService 範本：$template"
}

if (-not (Test-Path $outputDir)) {
    New-Item -ItemType Directory -Path $outputDir | Out-Null
}

$word = New-Object -ComObject Word.Application
$word.Visible = $false
try {
    $doc = $word.Documents.Open($template, $false, $false)
    $table1 = $doc.Tables.Item(1)
    $table2 = $doc.Tables.Item(2)

    function Set-CellText([object]$tbl, [int]$row, [int]$col, [string]$text) {
        try {
            $range = $tbl.Cell($row, $col).Range
            $range.Text = $text
        } catch { }
    }

    # 依來源填 Table 1。
    # 原範本 Table 2 不建議用 Rows.Delete() 壓縮，範本含合併列時可能觸發 HRESULT。
    # 穩定做法：在原 Table 2 後建立 Method 清單表，填完後刪除原 Table 2。
    # 每個 WebMethod 章節再各自新增一張參數/回傳欄位表。
    # 在各 Method 參數表外新增「實作參考說明」段落。

    if (Test-Path $output) {
        Remove-Item $output -Force
    }

    $doc.SaveAs2($output, 16)
    $doc.Close($false)
}
finally {
    if ($word) { $word.Quit() }
}
```

若輸出檔被 Word 或預覽程序佔用，不要強制關閉使用者程序；改用時間戳檔名輸出，並在回覆中說明原因。

### Table 2 Method 清單穩定重建範例

以下流程可避免原範本合併儲存格造成刪列失敗：

```powershell
$oldTable2 = $doc.Tables.Item(2)
$insertRange = $oldTable2.Range
$insertRange.Collapse(0) # wdCollapseEnd
$insertRange.InsertParagraphAfter()
$insertRange = $doc.Range($insertRange.End, $insertRange.End)

$rowCount = $methodRows.Count
$newTable2 = $doc.Tables.Add($insertRange, $rowCount, 4)
for ($r = 1; $r -le $rowCount; $r++) {
    for ($c = 1; $c -le 4; $c++) {
        $newTable2.Cell($r, $c).Range.Text = [string]$methodRows[$r - 1][$c - 1]
    }
}

$oldTable2.Delete()
```

`$methodRows` 必須只包含 Method 清單列。每個 WebMethod 的 `$rows` 參數表必須只包含實際要輸出的參數與回傳欄位列，不要包含呼叫範例、解析方式或權限說明。

## 驗證流程

產生 Word 檔後必須驗證：

1. 確認檔案存在於 `說明文件/`。
2. 確認檔案大小大於 0。
3. 用 Word COM 唯讀開啟輸出檔。
4. 確認文件至少有 `2 + WebMethod 數量` 個表格：Table 1 服務基本資料、Table 2 Method 清單、每個 WebMethod 各一張參數/回傳欄位表。
5. 確認 Table 1 的 ASMX 路徑、Method、Protocols、說明已填入。
6. 確認 Table 2 沒有呼叫範例、解析方式、權限說明。
7. 確認 Table 2 是 Method 清單，且包含該 ASMX 的所有 WebMethod。
8. 確認每個 WebMethod 都有自己的參數/回傳欄位表，且表格沒有多餘空白列。
9. 確認文件全文包含每個 Method 對應的 `實作參考說明`。
10. 確認檔名符合 `{asmx}_{中文服務說明}_API規格書.docx`。
11. 若存在舊版 `{asmx}_{method}_{中文說明}.docx` 拆分文件，確認已刪除或在回覆中說明檔案鎖定原因。

## 回覆格式

完成後用簡短中文回覆：

1. 檔案位置，使用可點擊連結。
2. 使用哪個 ASMX，以及整合了哪些 WebMethod。
3. 摘要 Method 數量、每個 Method 是否都有參數/回傳欄位表、舊拆分文件是否已清理。
4. 說明實作參考已放在 table 外。
5. 若因 Word COM 或檔案鎖定改用替代檔名，說明原因。

## 禁止事項

1. 不要修改 `assets/WebService範本.doc`。
2. 不要把呼叫範例、解析方式、權限說明塞進 Table 2 Method 清單或任何 WebMethod 參數表。
3. 不要保留範本內大量空白列。
4. 不要為同一個 ASMX 拆成多份 Method 文件。
5. 不要硬編任何特定 ASMX、method、DTO、系統名稱或負責人。
6. 不要以 Markdown 文件替代使用者要求的 Word 文件。
7. 不要略過輸出後驗證。

必須包含 YAML frontmatter 的 name 與 description。

修改說明

取消