feat: 移除計時並停用報表預覽
This commit is contained in:
+17
-287
@@ -3,307 +3,37 @@ description: 僅由 /sdlc-analyze 指令叫用。對一顆需求議題執行可
|
||||
|
||||
# sdlc-analyze
|
||||
|
||||
對一顆需求議題執行可行性檢查，把疑點一題一題問到雙方有共識，再把共識變成一批工作包議題。
|
||||
|
||||
分成三段：**可行性分析**到共識摘要為止，除了起錶之外完全不寫入 Gitea；使用者看過摘要
|
||||
點頭之後，才進入**產生工作包**建立議題；最後**排上時程與看板**，把相依、截止日、
|
||||
Milestone、看板與人天估算補上。
|
||||
|
||||
這份檔案是流程正本。各平台的轉接檔只是指回這裡，不要把規則抄過去。
|
||||
|
||||
## 輸入
|
||||
|
||||
一個需求議題編號。
|
||||
|
||||
## 計時範圍
|
||||
|
||||
錶起在**它分析的那顆需求議題**上：在「起錶」那一步起，在「停錶並回報」那一步停，
|
||||
涵蓋整道 /sdlc-analyze。
|
||||
|
||||
起點放在第一段開頭，因為分析最耗時的正是共識之前那一段——四類疑點逐題問到收斂。
|
||||
從第二段才起錶的話，那段時間永遠是零，而報表上「分析不花時間」會直接餵給下一次估算。
|
||||
|
||||
錶已經跑在同一顆議題上時起錶什麼都不做，所以 plan 接著跑 analyze 不會把累積的時間
|
||||
切成兩段。**錶不跨階段跑**，也**不碰別顆議題上的錶**。
|
||||
|
||||
## 〔可委派〕的意思
|
||||
|
||||
標題後綴 `〔可委派〕` 的步驟只在意結果：**你的環境若能把工作交給子代理，就交出去，
|
||||
只把結果帶回來；不能就自己做。** 沒有這個後綴的步驟一律自己做。
|
||||
|
||||
怎麼挑、為什麼這樣挑，見 `references/delegation.md`——判準只有那一份，這裡不複述。
|
||||
一個需求議題編號。先用 `scripts/issue-extract.js` 讀取結構化內容；先看 `未處理留言數`。若有留言，直接走 `/sdlc-sync` 的流程，完成後自動接回這裡；不要要求使用者重打指令。接回前重新抽取一次拿到更新後的描述；若使用者不整併，繼續並在摘要註明。
|
||||
|
||||
## 第一段：可行性分析
|
||||
|
||||
### 1. 讀議題
|
||||
依序讀取並逐條對照：
|
||||
|
||||
```
|
||||
node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
```
|
||||
1. `references/feasibility-architecture.md`
|
||||
2. `references/feasibility-logic.md`
|
||||
3. `references/feasibility-data.md`
|
||||
4. `references/feasibility-schedule.md`
|
||||
|
||||
拿到的是結構化欄位，不必再讀整份議題全文。
|
||||
能從程式碼查證的事項自行查證；只有需要使用者決策的事項才提問。架構、邏輯、資料、時程四類依序完成，每次只問一題，每題提供建議與手動輸入。最後輸出共識摘要、變更假設、未決事項與人天估算；摘要只印終端，不寫入 Gitea。
|
||||
|
||||
**先看 `未處理留言數`。** 只要不是 0，就代表議題描述可能是過期的——留言裡有決策還沒被
|
||||
整併回描述。這時**先停下來**告訴使用者有幾則未整併的留言，問他要不要現在整併。
|
||||
|
||||
要整併的話**直接走 `/sdlc-sync` 的流程**（`prompts/sdlc-sync.md`），做完**自動接回這裡**：
|
||||
重新抽取一次拿到更新後的描述，再往下走。**不要要求使用者重打指令**——他已經說要整併了。
|
||||
|
||||
使用者選擇不整併就繼續，但要記下這件事，並在共識摘要裡註明「分析基於未整併留言前的描述」。
|
||||
|
||||
### 2. 起錶
|
||||
|
||||
議題確認存在之後，在**這顆需求議題**上起錶：
|
||||
|
||||
```
|
||||
node scripts/timer.js --repo <owner/name> --index <需求議題編號> --dry-run
|
||||
```
|
||||
|
||||
確認無誤後拿掉 `--dry-run` 再跑一次。錶已經跑在同一顆上時它什麼都不做，重跑不會把
|
||||
已經累積的時間切成兩段。
|
||||
|
||||
錶跑在別顆議題上時會被擋下（`STOPWATCH_ON_OTHER_ISSUE`）。**照實告訴使用者是哪一顆，
|
||||
請他自己去停**，不要代勞：那一段時間該記在哪顆議題上只有他知道。順帶說明停錶不會動到
|
||||
任何既有的工作樹——碼錶只管時間、工作樹只管檔案。
|
||||
|
||||
### 3. 對四份清單列出疑點 〔可委派〕
|
||||
|
||||
依序讀這四份規則正本，逐條對照議題內容：
|
||||
|
||||
1. `references/feasibility-architecture.md` — 架構：放錯 repo、循環相依、穿越邊界。
|
||||
2. `references/feasibility-logic.md` — 邏輯：既有功能是不是已經做過同一件事。
|
||||
3. `references/feasibility-data.md` — 資料：schema 變更、遷移、交易邊界。
|
||||
4. `references/feasibility-schedule.md` — 時程：相依鏈最長路徑、未知數最大的一項。
|
||||
|
||||
每一條檢查若在議題裡找不到答案，就轉成一個問題。**能在程式碼裡查證的就自己去查，
|
||||
不要拿去問使用者**——把問題留給只有人能回答的事。
|
||||
|
||||
### 4. 逐題問到共識
|
||||
|
||||
**一次問一題。** 問完等使用者回答，再問下一題，讓他能看著前一題的答案回答下一題。
|
||||
不要一次丟出五個問題，也不要把多個問題包成一題的多個選項。
|
||||
|
||||
順序固定為**架構 → 邏輯 → 資料 → 時程**，前一類的問題全部清空才進入下一類。
|
||||
前面的答案常常會讓後面的問題消失或改寫；每問完一題，重新檢視剩下的問題還成不成立。
|
||||
|
||||
每一題固定給兩個選項：
|
||||
|
||||
- **建議** — 你的答案，附上理由。理由要寫「為什麼是這個」，不是複述問題。
|
||||
- **手動輸入** — 讓使用者自己寫。任何一題都必須能手動作答，不被選項限制。
|
||||
|
||||
問題本身要具體到能用一句話回答。問不出收斂答案的問題，多半是問題本身太大，拆開再問。
|
||||
|
||||
### 5. 輸出共識摘要
|
||||
|
||||
全部問完後，輸出一份摘要讓使用者做最後確認，內容包含：
|
||||
|
||||
- **每一類的結論** — 架構／邏輯／資料／時程各自問出了什麼，逐條列出「問題 → 答案」。
|
||||
- **改變了什麼** — 分析過程中翻掉或修正了需求議題裡的哪些假設。
|
||||
- **仍然未決的事** — 問了但沒有答案、或使用者明確說「之後再說」的事。
|
||||
- **人天估算** — 每一項的估算與最沒把握的那一項。
|
||||
|
||||
摘要只印在終端，**不寫回議題、不建立任何東西**。使用者看過點頭之後，才進入下一段。
|
||||
使用者確認共識摘要後，**先列出要交付或驗收的項目，逐項向使用者確認**。使用者未確認或拒絕時，立即停止，不建立工作包、不排程、不寫入後續資料。
|
||||
|
||||
## 第二段：產生工作包
|
||||
|
||||
**使用者對共識摘要點頭之後才開始。** 摘要沒有經過確認就不要往下走。
|
||||
確認交付／驗收項目後，依共識切出可獨立完成的工作包，套用 `templates/work-package-issue.md`。每顆工作包的待辦與驗收都要可逐項勾選；對應已確認交付項目的待辦置於第一項。工作包整體也依交付優先排序，但不得違反先決關係。
|
||||
|
||||
### 6. 切出工作包
|
||||
每顆工作包先以 `scripts/issue-create.js --dry-run` 檢查，再移除旗標實跑。只使用既有標籤。建立後回報編號、標題與網址。
|
||||
|
||||
把需求切成幾顆工作包。一顆工作包是**開發者拿了就能動手、做完有明確結果**的單位：
|
||||
它有自己的驗收標準，做完能單獨被檢視，不必等別的工作包一起才看得出成果。
|
||||
## 第三段：排程
|
||||
|
||||
切的依據是第一段問出來的共識，特別是時程清單那份暫定拆法——那本來就是這一段的草稿。
|
||||
以 `startDate`、`days` 與 `depends` 組成計畫檔，執行 `scripts/schedule.js` 計算截止日；依序用 `issue-link.js`、`issue-update.js` 與 `project-add.js` 補上既有相依、Milestone、看板、截止日與人天估算。各腳本先 dry-run，再實跑。日期與人天是排程資料，不是耗時統計。
|
||||
|
||||
**標題格式為「{動詞}{名詞}」**，例如「建立工作包的抽取契約」、「產生圖解版總覽網頁」。
|
||||
**禁止流水編號與任何無意義代號**（`WP-01`、`任務三`、`第一階段`）：命名本身就要說明用途，
|
||||
看標題就知道這顆在做什麼，不必點進去。
|
||||
|
||||
### 7. 組出每顆工作包的內容
|
||||
|
||||
套用 `templates/work-package-issue.md`，依序填滿九個段落：
|
||||
|
||||
1. **這個工作包在做什麼** — 一句話。讓人掃過標題與這一行就決定要不要點進來。
|
||||
2. **描述** — 從使用者的角度說這顆做完之後什麼事變得可能，不要寫成逐層的實作清單。
|
||||
3. **架構圖** — 見下方「架構圖的限制」。
|
||||
4. **範圍邊界** — 明列**不做什麼**。這一段的用途是抵抗範圍蔓延，寫得越具體越有用。
|
||||
5. **介面契約** — 表格，四欄：介面／產出者／消費者／形狀。讓人知道自己產出的東西誰會消費。
|
||||
這顆不產出對外介面就寫一列「無」，不要留空表。
|
||||
6. **待辦** — 巢狀結構：每一項待辦底下掛**它自己的**驗收標準，讓人知道這一項做到什麼程度算完成。
|
||||
|
||||
```
|
||||
- [ ] 建立共用函式庫
|
||||
- [ ] 具名 flag 解析可拒絕未知參數
|
||||
- [ ] 單行 JSON 輸出格式固定
|
||||
- [ ] 加上前置檢查
|
||||
- [ ] 四層各自回傳可區分的錯誤碼
|
||||
```
|
||||
|
||||
上層是待辦、縮排一層是該項的驗收，不要再往下巢狀。兩者都用 checkbox，實作時會被逐項勾選。
|
||||
7. **整體驗收** — 整顆工作包做完才驗得出來的事，與個別待辦的驗收不重複。
|
||||
8. **repo 列表** — 這顆會動到哪些 repo。
|
||||
9. **關聯** — 至少要有一行 `需求議題：#<編號>` 指回來源。阻擋、先決與人天估算由後續流程補上。
|
||||
|
||||
### 8. 先試跑，再寫入
|
||||
|
||||
每顆工作包各寫一個暫存檔，然後逐顆：
|
||||
|
||||
```
|
||||
node scripts/issue-create.js --repo <owner/name> --title "<標題>" --body-file <暫存檔> \
|
||||
--labels "<標籤>" --dry-run
|
||||
```
|
||||
|
||||
`--dry-run` 會印出將送出的請求、把標籤名稱換成 id，並在標題已存在時如實顯示「實跑會是
|
||||
no-op」。確認無誤後拿掉該旗標再跑一次。
|
||||
|
||||
標籤一樣只能從 `scripts/labels-list.js` 回傳的既有標籤裡挑，**不得自行建立新標籤**。
|
||||
|
||||
中斷後重跑不會產生重複工作包：`issue-create` 以標題查重，發現同名議題就回傳既有那一顆
|
||||
並把 `created` 設為 `false`。
|
||||
|
||||
### 9. 回報
|
||||
|
||||
列出每顆工作包的編號、標題與網址。不要把議題內容再貼一次。
|
||||
|
||||
**這裡不停錶**——指令還沒跑完，第三段還要排時程。停錶在最後的「停錶並回報」那一步。
|
||||
|
||||
## 第三段：排上時程與看板
|
||||
|
||||
工作包建好之後，把它們之間的關係與時程補上。做完這一段，看板上呈現的才是真實的
|
||||
開發順序，而不是一堆平鋪的議題。
|
||||
|
||||
### 10. 算出截止日 〔可委派〕
|
||||
|
||||
把每顆工作包的編號、人天估算與先決關係寫成一份計畫檔：
|
||||
|
||||
```json
|
||||
{
|
||||
"startDate": "2026-09-21",
|
||||
"workPackages": [
|
||||
{ "index": 12, "title": "建立共用函式庫", "days": 3 },
|
||||
{ "index": 13, "title": "建立抽取契約", "days": 2, "depends": [12] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
node scripts/schedule.js --plan-file <計畫檔>
|
||||
```
|
||||
|
||||
它依相依關係做拓撲排序，保證**任一工作包的截止日都不早於它的先決**——人工排時程
|
||||
最常見的矛盾就是前置工作比後續還晚到期。相依成環時它會直接報錯並指出環上的成員，
|
||||
那代表拆法有問題，回頭改拆法，不要硬排。
|
||||
|
||||
日期以日曆日累加，不跳週末也不扣假日。要跳的話自己把 `startDate` 或人天調整過再算。
|
||||
|
||||
### 11. 逐顆補上關係與時程
|
||||
|
||||
對每一顆工作包，依序：
|
||||
|
||||
```
|
||||
node scripts/issue-link.js --repo <owner/name> --index <編號> --depends <先決編號清單>
|
||||
node scripts/issue-update.js --repo <owner/name> --index <編號> \
|
||||
--milestone "<既有 Milestone 名稱>" --due-date <schedule 算出的日期> --estimate-days <人天>
|
||||
node scripts/project-add.js --repo <owner/name> --index <編號> --project "<看板名稱或網址>"
|
||||
```
|
||||
|
||||
三支都先用 `--dry-run` 看過再實跑。三支都是冪等的：相依已存在就跳過、已在看板上就不重發、
|
||||
估算沒變就不改 body。
|
||||
|
||||
**Milestone 與看板都只掛既有的。** 指到不存在的 Milestone 會中止並列出可選項目；
|
||||
看板名稱靠掃最近 50 筆議題反查 id，反查不到就會請你直接貼專案網址（結尾即 id）。
|
||||
本流程不建立 Milestone，也不建立專案。
|
||||
|
||||
### 12. 產生分析版的圖解總覽 〔可委派〕
|
||||
|
||||
排程完成後重新抽取需求與全部工作包，組成 `schemaVersion: 1` 的需求級 JSON。
|
||||
工作包依賴與截止日必須來自重新抽取的實際資料，不使用模型記憶中的暫定值。
|
||||
執行：
|
||||
|
||||
```
|
||||
node scripts/overview-render.js --input <json> --output <html> --manifest <manifest>
|
||||
```
|
||||
|
||||
HTML 內重新產生 SVG 與 HTML／CSS 視圖；不能直接搬用議題 Mermaid。預覽優先使用平台
|
||||
能力，否則啟動短命 Node server 供瀏覽器截圖。產生 full-page 與局部圖 PNG 後執行：
|
||||
|
||||
```
|
||||
node scripts/issue-assets.js --repo <owner/name> --index <需求議題編號> --manifest <manifest>
|
||||
```
|
||||
|
||||
截圖全部上傳成附件，需求議題正文只保留附件索引。只有真正可用的 preview URL 才使用
|
||||
既有 `--overview-url`；不可把 `.tmp/` 或 `0.0.0.0` 寫回 Gitea。
|
||||
產出 HTML 可委派；預覽截圖、附件上傳與任何 `issue-assets`／`issue-update` 寫回都不委派，
|
||||
由主流程執行並處理錯誤。
|
||||
若平台 preview 不可用，執行 `node scripts/overview-capture.js --backend auto`；
|
||||
它依序嘗試 Firefox，再嘗試 `rsvg-convert`／`resvg`。所有 backend 都不可用時必須
|
||||
停止並保留 `.tmp/` 的 HTML／SVG，不得宣稱截圖完成。
|
||||
### 13. 停錶並回報
|
||||
|
||||
回報之前先停錶，這一段計時到此為止：
|
||||
|
||||
```
|
||||
node scripts/timer.js --repo <owner/name> --index <需求議題編號> --stop
|
||||
```
|
||||
|
||||
它**只停這一顆**上的錶，與「起錶」那一步起的是同一顆。錶本來就沒在跑不算失敗
|
||||
（`碼錶已停` 會是 `false` 並附一句說明），回報照樣做完。
|
||||
|
||||
列出每顆工作包的編號、標題、截止日與所屬 Milestone，並指出**相依鏈最長路徑**上的那幾顆
|
||||
——那條路徑決定整體交期。
|
||||
|
||||
## 已知限制：人天估算只寫得進 body
|
||||
|
||||
Gitea 1.27 的 API 沒有任何請求定義接受 `time_estimate`，該欄位只出現在議題的回應裡。
|
||||
也就是說**議題的估算欄位無法由 API 寫入**，只能靠人在網頁上填。
|
||||
|
||||
因此 `issue-update --estimate-days` 只把估算寫成議題 body 裡人類可讀的一行
|
||||
（`估算人天：N`，放在「關聯」段落）。之後 `sdlc-report` 要比對估算與實際工時時，
|
||||
讀的也是這一行。
|
||||
|
||||
## 架構圖的限制
|
||||
|
||||
圖表以抽象 `kind`、`direction`、`nodes`、`edges` 保存。renderer 產生議題 Mermaid
|
||||
與 HTML SVG；不能讓模型直接維護兩套圖表語法。節點超過 12、文字超過 8 字或無法
|
||||
安全轉換時，拆圖或記錄 `omitted` 原因。
|
||||
## 邊界
|
||||
|
||||
- **共識摘要之前不對 Gitea 寫入任何內容**：不建議題、不改描述、不貼標籤、不留留言。
|
||||
**碼錶除外**——它記的是工時，不是內容；而分析最耗時的正是共識之前那一段，不從那裡
|
||||
起錶，那段時間就永遠是零。
|
||||
- 第二段只建立工作包議題。不建相依、不掛 Milestone、不加看板、不寫人天估算——那是第三段的事。
|
||||
- 第三段只掛既有的 Milestone 與看板。不自行建立標籤、Milestone 或專案看板。
|
||||
- 不修改使用者的專案檔案。查證既有功能時只讀不寫。
|
||||
- 不替使用者決定他沒回答的事。問不到答案就進「仍然未決的事」。
|
||||
- 計時只動這顆需求議題：在它上面起錶、在它上面停錶。**不停別顆議題上的錶**，
|
||||
被別顆的錶擋下時交還給使用者決定，不繞過去。
|
||||
- 不關閉或刪除任何既有議題。
|
||||
# Artifact 交接與視圖
|
||||
|
||||
完成第三段排程後，依 `references/artifact-contract.md` 重新抽取需求與全部工作包，
|
||||
組成一份 `schemaVersion: 1` 的 JSON 暫存檔。這份 JSON 是 HTML renderer 的輸入，
|
||||
不是 Gitea 的第二份正本。
|
||||
|
||||
先執行：
|
||||
|
||||
```
|
||||
node scripts/overview-render.js --input <json> --output <html> --manifest <manifest>
|
||||
```
|
||||
|
||||
renderer 驗證失敗時，不截圖、不上傳、不更新議題，保留 `.tmp/` 的輸入與錯誤供修正。
|
||||
HTML 必須自包含，不依賴 CDN；圖表由抽象節點／邊資料重新產生 SVG，不能直接搬用議題
|
||||
Mermaid。公式是可選欄位，單一公式無法渲染時保留原文並標示未渲染。
|
||||
|
||||
預覽優先使用執行環境提供的預覽能力。沒有預覽能力時，使用 `0.0.0.0` 綁定的
|
||||
ephemeral Node 靜態伺服器，只為瀏覽器截圖，完成後一定停止。產生 full-page 與所有
|
||||
局部圖 PNG，為每張圖填入 manifest 的角色、固定檔名與 SHA-256。
|
||||
|
||||
截圖全部是需求議題附件，不嵌入圖片；執行：
|
||||
|
||||
```
|
||||
node scripts/issue-assets.js --repo <owner/name> --index <需求議題編號> --manifest <manifest>
|
||||
```
|
||||
|
||||
這支腳本負責 hash 重用、附件上傳與「圖解版總覽附件」索引的冪等更新。上傳或索引
|
||||
更新失敗就是流程失敗。只有預覽平台提供真正可用的 URL 時，才另外使用既有的
|
||||
`--overview-url`；不可把 `.tmp/` 或 `0.0.0.0` 寫回 Gitea。
|
||||
- 不產生 HTML、SVG、manifest、截圖、附件或任何平台 preview。
|
||||
- 不建立 Milestone 或專案看板。
|
||||
- 不修改使用者專案檔案。
|
||||
- 不關閉或刪除既有議題。
|
||||
- 共識摘要與交付確認前不建立任何工作包。
|
||||
|
||||
Reference in New Issue
Block a user