Skill asset

編輯 Skill

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

Skill 名稱

唯一代稱

簡短說明

主要分類

標籤

SKILL.md

五種工具預設適用

---
name: table-doc-generator
description: "Use when: 從 DD、data-model.md、資料表設計、DDL 產生 table Word 文件或 table範本 文件。適用於共用資料表文件產生流程，會使用 Skill 目錄 assets 內的 table範本.doc 或 table範本.pdf，輸出到 說明文件 資料夾，不預設任何系統名稱或 System ID。"
---

# Table Word 文件產生器

## 技能用途

當使用者要求「用 DD 產生 table 文件」、「依 data-model.md 產生 table範本 Word」、「參考 table範本.pdf 產生資料表文件」、「產生 table Word 檔」時，必須使用本 Skill。

本 Skill 的目標是：讀取資料表 DD 來源，套用 Skill 目錄內 `assets/table範本.doc` / `assets/table範本.pdf` 樣式，產生可交付的 Word table 文件，並放在 `說明文件/` 資料夾。

## 固定輸入

優先接受以下來源：

1. `specs/**/data-model.md` 中的資料表詳細設計。
2. 使用者貼上的 DD 表格，欄位至少包含：欄位名稱、型別、限制、說明。
3. 現有 DDL，例如 `CREATE TABLE ...`、`CREATE INDEX ...`、`ALTER TABLE ... ADD CONSTRAINT ...`。

若使用者沒有指定資料表：

1. 若目前 editorContext 指向 `data-model.md`，挑選使用者游標附近或第一張資料表。
2. 若無法判斷，詢問使用者要產生哪一張資料表。

## 固定輸出

輸出 Word 檔案到：

```text
說明文件/{table_name}_table範本.docx
```

若 `說明文件/` 不存在，先建立該資料夾。

## Skill 資產

本 Skill 必須攜帶下列範本資產，讓整個 Skill 目錄可被複製到其他專案後直接使用：

```text
.github/skills/table-doc-generator/assets/table範本.doc
.github/skills/table-doc-generator/assets/table範本.pdf
```

## 範本選用規則

1. 優先且預設使用 Skill 目錄內的 `assets/table範本.doc`，因為 Word COM 可保留既有表格版面。
2. `assets/table範本.pdf` 僅作為視覺與內容參考；若無可編輯 Word 範本，不要硬從 PDF 重建，應先告知使用者需要 `.doc` 或 `.docx` 範本。
3. 不要覆寫 Skill 目錄內的 `assets/table範本.doc` / `assets/table範本.pdf`。
4. 產生輸出時複製範本內容後另存新檔。
5. 只有在使用者明確指定其他範本時，才可改用使用者指定的範本路徑。

## System ID 規則

這是共用文件產生器，不可預設任何系統名稱。

1. `System ID` 只能來自 DD、DDL、使用者明確指定、或既有文件中已存在的系統代碼。
2. 若來源沒有提供 `System ID`，R1 的 `System ID` 值保持空白。
3. 不可自行填入固定系統代碼，例如專案代號、網站名稱或資料表前綴。

## Word 範本結構

既有 `table範本.doc` 的主要表格為 25 列、6 欄：

| 列 | 用途 |
|---|---|
| R1 | `Table Name`、資料表名稱、`System ID`、系統代碼或空白 |
| R2 | `Table Description`、資料表中文說明 |
| R3 | `Table Shape`、`Table`、`Relation Table of View` |
| R4 | 欄位標題列：`N`、`English Field ID`、`Chinese Field ID`、`Type Len`、`Null`、`Description/Constraint/Default` |
| R5-R22 | 欄位明細，最多 18 筆；不足列保持空白 |
| R23 | `Index & Key`、`PrimaryKey`、PK 名稱與欄位 |
| R24 | `IndexKey`、一般索引或唯一索引 |
| R25 | `Trigger`、Trigger 說明；若無則填 `無` |

## 欄位轉換規則

從 DD 轉換到 Word 表格時，依下列規則填值：

| Word 欄位 | 來源 | 規則 |
|---|---|---|
| `N` | 欄位順序 | 從 1 開始 |
| `English Field ID` | 欄位名稱 | 移除 Markdown 反引號，保留原欄位命名 |
| `Chinese Field ID` | 說明 | 取說明第一段作為中文欄名；若說明含代碼，中文欄名取代碼前的主名稱；若說明含「關聯 ...」則只取欄位本身中文名稱，不把關聯文字放入此欄 |
| `Type Len` | 型別 | 一般型別轉小寫，例如 `int`、`varchar(50)`、`datetime`；Identity 欄位固定顯示 `int` |
| `Null` | 限制 | `NULL` 為 `Y`；其他包含 `NOT NULL`、`PK`、`FK NOT NULL`、`DEFAULT ... NOT NULL` 均為 `N` |
| `Description/Constraint/Default` | 限制 + 說明補充 | 填入 PK/FK/DEFAULT/代碼說明/備註，不重複中文欄名 |

### Chinese Field ID 取值範例

| DD 說明 | Chinese Field ID | Description/Constraint/Default |
|---|---|---|
| `人員類型：1=委員，2=幹事` | `人員類型` | `DEFAULT 1；1=委員，2=幹事` |
| `啟用：1=啟用，0=停用` | `啟用` 或 `啟用狀態` | `DEFAULT 1；1=啟用，0=停用` |
| `最後異動日期時間` | `最後異動日期時間` | 空白 |
| `主鍵`（Identity 欄位） | `主鍵` | `Identity / gap = 10` |
| `相簿主鍵；關聯 ewcs_albums_m.album_id` | `相簿主鍵` | `FK；關聯 ewcs_albums_m.album_id` |
| `關聯 ewcs_albums_m.album_id` | 依欄位名稱推導，例如 `相簿主鍵` 或 `相簿 ID` | `FK；關聯 ewcs_albums_m.album_id` |

## 索引與鍵值規則

從 DD 的「索引」與「外鍵」區塊填入底部列：

1. Primary Key 填在 R23：

```text
PK_{table_name} ({pk_column})
```

2. 一般 Index、Unique Index 填在 R24，多筆以換行分隔：

```text
idx_{table_name}_{purpose}({column_1}, {column_2})
UQ_{table_name}_{purpose}({column_name})
```

3. 外鍵若存在，附加在 R24 或 Description 中，格式：

```text
FK_{table_name}_{purpose}({fk_column}) REFERENCES {ref_table}({ref_column})
```

4. 若無 Trigger，R25 填：

```text
無
```

## 資料庫 / DD 規範

產生 table 文件時要遵守來源 DD 規則：

1. 資料表名稱與欄位名稱以來源為準，不自行改名。
2. Identity 欄位文件中 `Type Len` 顯示為 `int`，Null 欄填 `N`，`Description/Constraint/Default` 填 `Identity / gap = 10`。
3. `DEFAULT` 語序以來源 DD 為準；文件描述中保留 `DEFAULT <value>`。
4. Index 不標示 `DESC`，除非來源文件明確要求。
5. FK 欄位型別以來源 DD 為準；不可自行改成其他型別。
6. FK 欄位的關聯資訊（例如 `關聯 ewcs_albums_m.album_id`）必須放在 `Description/Constraint/Default`，不可放在 `Chinese Field ID`。

## PowerShell Word COM 產生流程

在 Windows 且 Word COM 可用時，使用 PowerShell 操作 Word 範本。不要用純文字方式寫入 `.docx`。

標準流程：

```powershell
$skillDir = Join-Path $PWD '.github\skills\table-doc-generator'
$template = Join-Path $skillDir 'assets\table範本.doc'
$outputDir = Join-Path $PWD '說明文件'
$output = Join-Path $outputDir '{table_name}.docx'

if (-not (Test-Path $template)) {
    throw "找不到 Skill 內建範本：$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)
    $table = $doc.Tables.Item(1)

    function Set-CellText([object]$tbl, [int]$row, [int]$col, [string]$text) {
        try {
            $range = $tbl.Cell($row, $col).Range
            $range.Text = $text
        } catch { }
    }

    # R1 System ID 只能填來源或使用者指定值；沒有來源就保持空白。
    # 依 DD 填入各儲存格。

    if (Test-Path $output) {
        Remove-Item $output -Force
    }

    $doc.SaveAs2($output, 12)
    $doc.Close($false)
}
finally {
    if ($word) { $word.Quit() }
}
```

注意：`SaveAs2(..., 12)` 代表 `wdFormatXMLDocument`，用來輸出真正的 `.docx`（OOXML/ZIP）。不要用舊式 OLE Word 格式搭配 `.docx` 副檔名。

## 驗證流程

產生 Word 檔後必須做唯讀驗證：

1. 確認檔案存在於 `說明文件/`。
2. 確認檔案大小大於 0。
3. 用 Word COM 唯讀開啟輸出檔。
4. 抽查至少以下列：R1、R2、R4、第一筆欄位列、最後一筆欄位列、R23、R24、R25。
5. 驗證 R1 的 `System ID` 沒有被填入未指定的固定系統名稱。
6. 最終回覆使用者時提供檔案連結與抽查結果摘要。

驗證指令概念：

```powershell
$output = Join-Path (Join-Path $PWD '說明文件') '{table_name}.docx'
Get-Item $output | Select-Object FullName, Length, LastWriteTime

$word = New-Object -ComObject Word.Application
$word.Visible = $false
try {
    $doc = $word.Documents.Open($output, $false, $true)
    $table = $doc.Tables.Item(1)
    foreach ($r in @(1,2,4,5,23,24,25)) {
        $cells = @()
        for ($c=1; $c -le $table.Columns.Count; $c++) {
            try {
                $text = $table.Cell($r,$c).Range.Text -replace '[\r\a]', '' -replace '\s+$',''
                $cells += $text
            } catch {
                $cells += '<merged>'
            }
        }
        "R$r`t" + ($cells -join ' | ')
    }
    $doc.Close($false)
}
finally {
    if ($word) { $word.Quit() }
}
```

## 回覆格式

完成後用簡短中文回覆：

1. 檔案位置，使用可點擊連結。
2. 使用哪個資料表與來源 DD。
3. 摘要已驗證的表頭、System ID 是否來自來源或保持空白、欄位數、PK、Index、Trigger。
4. 若因缺少 Word COM 或範本無法產生，清楚說明阻礙與需要的補件。

範例：

```text
已完成，檔案放在：[說明文件/{table_name}.docx](說明文件/{table_name}.docx)。

這次使用 `data-model.md` 的 `{table_name}`，已套用 `table範本.doc` 版面並驗證表頭、System ID、欄位、PK、Index 與 Trigger 欄位。
```

## 禁止事項

1. 不要修改 Skill 內建的 `assets/table範本.doc` 或 `assets/table範本.pdf`。
2. 不要以 Markdown 文件替代使用者要求的 Word 文件。
3. 不要使用本機絕對路徑寫進文件內容。
4. 不要在無法確認欄位語意時自行編造欄位。
5. 不要略過輸出後驗證。
6. 不要預設或硬編任何系統名稱、System ID、網站名稱、專案代號。

必須包含 YAML frontmatter 的 name 與 description。

修改說明

取消