@loviusc/sa-spec 0.2.4 → 0.2.5

package/README.zh-TW.md

@@ -724,6 +724,12 @@ git push origin master
 
 ## 更新紀錄
 
+### v0.2.5
+- **支援前端 UI 線框圖（PlantUML Salt Code-as-Wireframe）**：
+  - **純文字代碼化線框圖**：在 `uml/` 目錄新增標準 `uml/wireframe.puml`，使用 PlantUML Salt 語法（`@startsalt ... @endsalt`）以純文字定義頁面排版、輸入欄位、選項與按鈕，可直接在 VS Code 渲染預覽，並可納入 Git 版本追蹤。
+  - **AI 開發交接前後閉環**：`srs.md` 與 `handoff.md` 新增「UI / 畫面規格」區塊，前端需求直接引用 `uml/wireframe.puml`，供 OpenSpec / Claude Code 精準產出前端元件；純後端需求則標示「無 UI 介面需求」。
+  - **版本升級（`sa-spec upgrade`）既有需求防護**：升級時主動掃描既有需求，若偵測到前端介面描述且缺少 wireframe 則發出補齊提示；已標記無 UI 之純後端需求則略過，不盲目覆蓋既有規格。
+
 ### v0.2.4
 - **序號重複主動告警與重新定號自癒支援**：
   - **唯一性主動檢驗**：`sa-spec check` 與 `sa-spec reindex` 加入重複序號檢測，遇到衝突時即時發出 WARNING 告警並列出衝突目錄與修復建議。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loviusc/sa-spec",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Personal system analysis documentation workspace CLI",
   "publishConfig": {
     "access": "public",

package/readme.md

@@ -724,6 +724,12 @@ git push origin master
 
 ## 更新紀錄
 
+### v0.2.5
+- **支援前端 UI 線框圖（PlantUML Salt Code-as-Wireframe）**：
+  - **純文字代碼化線框圖**：在 `uml/` 目錄新增標準 `uml/wireframe.puml`，使用 PlantUML Salt 語法（`@startsalt ... @endsalt`）以純文字定義頁面排版、輸入欄位、選項與按鈕，可直接在 VS Code 渲染預覽，並可納入 Git 版本追蹤。
+  - **AI 開發交接前後閉環**：`srs.md` 與 `handoff.md` 新增「UI / 畫面規格」區塊，前端需求直接引用 `uml/wireframe.puml`，供 OpenSpec / Claude Code 精準產出前端元件；純後端需求則標示「無 UI 介面需求」。
+  - **版本升級（`sa-spec upgrade`）既有需求防護**：升級時主動掃描既有需求，若偵測到前端介面描述且缺少 wireframe 則發出補齊提示；已標記無 UI 之純後端需求則略過，不盲目覆蓋既有規格。
+
 ### v0.2.4
 - **序號重複主動告警與重新定號自癒支援**：
   - **唯一性主動檢驗**：`sa-spec check` 與 `sa-spec reindex` 加入重複序號檢測，遇到衝突時即時發出 WARNING 告警並列出衝突目錄與修復建議。

package/src/cli.js

@@ -316,6 +316,7 @@ function createReqTemplate(args, label = "new") {
       ensureDir(umlDir),
       ensureFileFromTemplate(path.join("project", "req", "srs.md"), path.join(reqDir, "srs.md"), replacements),
       ensureFileFromTemplate(path.join("project", "req", "uml", "main.puml"), path.join(umlDir, "main.puml"), replacements),
+      ensureFileFromTemplate(path.join("project", "req", "uml", "wireframe.puml"), path.join(umlDir, "wireframe.puml"), replacements),
       ensureFileFromTemplate(path.join("project", "req", "openapi.yaml"), path.join(reqDir, "openapi.yaml"), replacements),
       ensureFileFromTemplate(path.join("project", "req", "db-schema.md"), path.join(reqDir, "db-schema.md"), replacements),
       ensureFileFromTemplate(path.join("project", "req", "handoff.md"), path.join(reqDir, "handoff.md"), replacements),
@@ -337,6 +338,7 @@ function createReqTemplate(args, label = "new") {
     ensureDir(umlDir),
     ensureFileFromTemplate(path.join("project", "req", "srs.md"), path.join(reqDir, "srs.md"), replacements),
     ensureFileFromTemplate(path.join("project", "req", "uml", "main.puml"), path.join(umlDir, "main.puml"), replacements),
+    ensureFileFromTemplate(path.join("project", "req", "uml", "wireframe.puml"), path.join(umlDir, "wireframe.puml"), replacements),
     ensureFileFromTemplate(path.join("project", "req", "openapi.yaml"), path.join(reqDir, "openapi.yaml"), replacements),
     ensureFileFromTemplate(path.join("project", "req", "db-schema.md"), path.join(reqDir, "db-schema.md"), replacements),
     ensureFileFromTemplate(path.join("project", "req", "handoff.md"), path.join(reqDir, "handoff.md"), replacements),
@@ -846,15 +848,70 @@ function upgradeProject(args = []) {
         const handoffRelPath = path.join(reqRelDir, "handoff.md");
         const handoffAbsPath = path.join(cwd, handoffRelPath);
         if (fs.existsSync(handoffAbsPath)) {
-          const content = fs.readFileSync(handoffAbsPath, "utf8");
+          let content = fs.readFileSync(handoffAbsPath, "utf8");
+          let updatedHandoff = false;
           if (content.includes("uml.puml")) {
+            content = content.replace(/uml\.puml/g, "uml/");
+            updatedHandoff = true;
+          }
+          if (!content.includes("## UI") && !content.includes("畫面規格")) {
+            const uiSection = `\n## UI / 畫面規格\n待補充；若有前端介面需求，參照 \`uml/wireframe.puml\`；若無 UI 需求，明確標示「無 UI 介面需求」。\n`;
+            if (content.includes("## 驗收條件")) {
+              content = content.replace("## 驗收條件", `${uiSection}\n## 驗收條件`);
+            } else {
+              content = `${content.trimEnd()}\n${uiSection}`;
+            }
+            updatedHandoff = true;
+          }
+          if (updatedHandoff) {
             if (!dryRun) {
-              fs.writeFileSync(handoffAbsPath, content.replace(/uml\.puml/g, "uml/"), "utf8");
+              fs.writeFileSync(handoffAbsPath, content, "utf8");
             }
             results.push({
               action: "update",
               target: handoffRelPath,
-              message: "更新來源參照 uml.puml -> uml/"
+              message: "更新來源參照與補全 UI/畫面規格章節"
+            });
+          }
+        }
+
+        // 檢查既有需求是否需要 wireframe
+        const wireframeRelPath = path.join(newUmlRelDir, "wireframe.puml");
+        const wireframeAbsPath = path.join(cwd, wireframeRelPath);
+        const srsRelPath = path.join(reqRelDir, "srs.md");
+        const srsAbsPath = path.join(cwd, srsRelPath);
+
+        let explicitNoUi = false;
+        let likelyHasUi = false;
+
+        const inspectUiText = (text) => {
+          if (/無\s*UI/i.test(text) || /純後端/i.test(text) || /無介面/i.test(text)) {
+            explicitNoUi = true;
+          }
+          if (/畫面|介面|UI|前端|按鈕|表單|點擊|頁面|Page|Screen|View|Modal/i.test(text)) {
+            likelyHasUi = true;
+          }
+        };
+
+        if (fs.existsSync(handoffAbsPath)) {
+          inspectUiText(fs.readFileSync(handoffAbsPath, "utf8"));
+        }
+        if (fs.existsSync(srsAbsPath)) {
+          inspectUiText(fs.readFileSync(srsAbsPath, "utf8"));
+        }
+
+        if (!fs.existsSync(wireframeAbsPath)) {
+          if (explicitNoUi) {
+            results.push({
+              action: "skip",
+              target: wireframeRelPath,
+              message: "已標記為無 UI 需求，略過 wireframe"
+            });
+          } else if (likelyHasUi) {
+            results.push({
+              action: "warn",
+              target: wireframeRelPath,
+              message: "偵測到包含前端介面描述，建議透過 AI (sca) 補齊 PlantUML Salt 線框圖"
             });
           }
         }

package/templates/AGENTS.md

@@ -47,7 +47,7 @@
 - `spec:commit` 只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才可執行 `git push`；push 失敗時只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
 - 多人協作與 Git-Flow 模式（延遲綁定序號與自動合併）：支援多人平行開發。執行 `spec:propose`（或 `scp`）時，若目前處於 master/main 分支，AI 必須自動依需求名稱建立並切換至專屬 feature branch（如 `feat/<name>`），並在 `project/<name>/` 建立草稿目錄，內部使用 `{{REQ_ID}}` 佔位，無需使用者手動敲 CLI；執行 `spec:analyze` 前應先確保取得 master 最新規格以防漏檢衝突；執行 `spec:commit` 歸檔時自動向 master 確認最新可用序號定號，自動將目錄定名為正式 `REQ-xxx`、替換內部佔位符、完成提交並自動合併回 master，避免多人合併時的序號競爭與索引衝突。
 - 文件未經使用者確認，不得標示為 `已審核`。
-- `uml/` 內的 UML 圖不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態或資料關係的 UML 圖，例如活動圖、循序圖、使用案例圖、狀態圖或類別圖，不可為了固定格式硬產生活動圖。**嚴禁將多張圖混在同一個檔案中**，必須在需求資料夾下的 `uml/` 目錄拆分成獨立的 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/state.puml`），且每個檔案只能包含一組 `@startuml` 與 `@enduml`，以避免 PlantUML 渲染或預覽失敗。
+- `uml/` 內的 UML 圖不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態、資料關係或介面佈局的圖表，例如活動圖、循序圖、使用案例圖、狀態圖、類別圖；**若需求涉及前端 UI 或使用者操作畫面，必須在 `uml/wireframe.puml` 產出線框圖（使用 PlantUML Salt 語法：`@startsalt ... @endsalt`）**；純後端需求則在 `handoff.md` 明確標記「無 UI 介面需求」。**嚴禁將多張圖混在同一個檔案中**，必須在需求資料夾下的 `uml/` 目錄拆分成獨立的 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/wireframe.puml`），且每個檔案只能包含一組 `@start...` 與 `@end...`，以避免 PlantUML 渲染或預覽失敗。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
 
 # 衝突檢查重點

package/templates/project/req/handoff.md

@@ -22,6 +22,9 @@
 ## DB 變更
 待補充；若無 DB 需求，明確標示「無 DB 需求」。
 
+## UI / 畫面規格
+待補充；若有前端介面需求，參照 `uml/wireframe.puml`（PlantUML Salt 線框圖）；若無 UI 需求，明確標示「無 UI 介面需求」。
+
 ## 驗收條件
 - 待補充。
 

package/templates/project/req/srs.md

@@ -16,6 +16,9 @@
 ## 功能需求
 - 待補充。
 
+## 介面與操作需求
+- 待補充（若涉及前端介面操作，可參照 `uml/wireframe.puml` 線框圖；純後端需求標示「無 UI 介面需求」）。
+
 ## 驗收條件
 - 待補充。
 

package/templates/project/req/uml/wireframe.puml

@@ -0,0 +1,13 @@
+@startsalt
+{+
+  {* {{REQ_ID}} {{REQ_NAME}} 介面草稿 }
+  --
+  {
+    輸入欄位： | "預設內容"
+    選項：     | (X) 單選項目 A | ( ) 單選項目 B
+    核取方塊： | [] 核取項目 1  | [] 核取項目 2
+  }
+  --
+  [ 確認送出 ] | [ 取消 ]
+}
+@endsalt

package/templates/readme.md

@@ -724,6 +724,12 @@ git push origin master
 
 ## 更新紀錄
 
+### v0.2.5
+- **支援前端 UI 線框圖（PlantUML Salt Code-as-Wireframe）**：
+  - **純文字代碼化線框圖**：在 `uml/` 目錄新增標準 `uml/wireframe.puml`，使用 PlantUML Salt 語法（`@startsalt ... @endsalt`）以純文字定義頁面排版、輸入欄位、選項與按鈕，可直接在 VS Code 渲染預覽，並可納入 Git 版本追蹤。
+  - **AI 開發交接前後閉環**：`srs.md` 與 `handoff.md` 新增「UI / 畫面規格」區塊，前端需求直接引用 `uml/wireframe.puml`，供 OpenSpec / Claude Code 精準產出前端元件；純後端需求則標示「無 UI 介面需求」。
+  - **版本升級（`sa-spec upgrade`）既有需求防護**：升級時主動掃描既有需求，若偵測到前端介面描述且缺少 wireframe 則發出補齊提示；已標記無 UI 之純後端需求則略過，不盲目覆蓋既有規格。
+
 ### v0.2.4
 - **序號重複主動告警與重新定號自癒支援**：
   - **唯一性主動檢驗**：`sa-spec check` 與 `sa-spec reindex` 加入重複序號檢測，遇到衝突時即時發出 WARNING 告警並列出衝突目錄與修復建議。

package/templates/rules/uml-style.md

@@ -20,6 +20,7 @@
 - Sequence Diagram：用於描述角色、系統、服務或 API 之間的互動順序。
 - Class Diagram：用於描述主要資料物件、屬性與關聯。
 - State Diagram：用於描述有明確生命週期的物件狀態。
+- Wireframe / Mockup (PlantUML Salt)：用於描述前端介面佈局、表單欄位、按鈕與操作畫面，獨立存放於 `uml/wireframe.puml`（使用 `@startsalt` 與 `@endsalt`）。若需求涉及前端 UI 或使用者操作畫面時按需產出；純後端需求則在 `handoff.md` 標示「無 UI 介面需求」。
 
 ## 圖表說明
 每張 UML 圖旁邊或同一文件內需補充：

package/templates/skills/system-analysis/SKILL.md

@@ -51,7 +51,7 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 - `spec:commit` 只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才可執行 `git push`；push 失敗時只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
 - 多人協作與 Git-Flow 模式（延遲綁定序號與自動合併）：支援多人平行開發。執行 `spec:propose`（或 `scp`）時，若目前處於 master/main 分支，AI 必須自動依需求名稱建立並切換至專屬 feature branch（如 `feat/<name>`），並在 `project/<name>/` 建立草稿目錄，內部使用 `{{REQ_ID}}` 佔位，無需使用者手動敲 CLI；執行 `spec:analyze` 前應先確保取得 master 最新規格以防漏檢衝突；執行 `spec:commit` 歸檔時自動向 master 確認最新可用序號定號，自動將目錄定名為正式 `REQ-xxx`、替換內部佔位符、完成提交並自動合併回 master，避免多人合併時的序號競爭與索引衝突。
 - 文件未經使用者確認，不得標示為 `已審核`。
-- `uml/` 內的 UML 圖不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態或資料關係的 UML 圖，例如活動圖、循序圖、使用案例圖、狀態圖或類別圖，不可為了固定格式硬產生活動圖。**嚴禁將多張圖混在同一個檔案中**，必須在需求資料夾下的 `uml/` 目錄拆分成獨立的 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/state.puml`），且每個檔案只能包含一組 `@startuml` 與 `@enduml`，以避免 PlantUML 渲染或預覽失敗。
+- `uml/` 內的 UML 圖不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態、資料關係或介面佈局的圖表，例如活動圖、循序圖、使用案例圖、狀態圖、類別圖；**若需求涉及前端 UI 或使用者操作畫面，必須在 `uml/wireframe.puml` 產出線框圖（使用 PlantUML Salt 語法：`@startsalt ... @endsalt`）**；純後端需求則在 `handoff.md` 明確標記「無 UI 介面需求」。**嚴禁將多張圖混在同一個檔案中**，必須在需求資料夾下的 `uml/` 目錄拆分成獨立的 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/wireframe.puml`），且每個檔案只能包含一組 `@start...` 與 `@end...`，以避免 PlantUML 渲染或預覽失敗。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
 
 ## analyze 衝突檢查