From a82f06b7020eebd17da17ad6eab9e48b9e35f459 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 26 Aug 2026 15:33:04 +0800 Subject: [PATCH] =?UTF-8?q?fix(analyze):=20=E4=BF=AE=E6=AD=A3=20CPM=20?= =?UTF-8?q?=E7=94=98=E7=89=B9=E5=9C=96=E7=94=A8=E5=B0=8F=E6=95=B8=E5=A4=A9?= =?UTF-8?q?=E6=95=B8=E7=9A=84=20dateFormat=20X=20=E5=B0=8E=E8=87=B4=20Gite?= =?UTF-8?q?a=20=E6=B8=B2=E6=9F=93=20Invalid=20date=EF=BC=8C=E6=94=B9?= =?UTF-8?q?=E7=94=A8=20dateFormat=20YYYY-MM-DD=20=E9=8C=A8=E9=BB=9E?= =?UTF-8?q?=E6=97=A5=E6=9C=9F=E3=80=81=E6=95=B4=E6=95=B8=E5=B0=8F=E6=99=82?= =?UTF-8?q?=E8=88=87=20after=20=E4=B8=B2=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- references/cpm-chart.md | 33 +++++++++++++++++++++++++++++++++ skills/analyze/SKILL.md | 2 +- templates/analyze-page.md | 14 ++++++++++++++ 3 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 references/cpm-chart.md diff --git a/references/cpm-chart.md b/references/cpm-chart.md new file mode 100644 index 0000000..8bf4d58 --- /dev/null +++ b/references/cpm-chart.md @@ -0,0 +1,33 @@ +# CPM 甘特圖畫法 + +`analyze` 步驟 8 畫關鍵路徑圖時，一律照本檔語法；不得自行發明日期算法。 + +## 事故 + +`dateFormat X`（Unix 時間戳）配上天數換算出的小數（例：`1.3`、`5.0`）會讓 Gitea 的 mermaid 渲染器丟出 `Invalid date:5.0`，整張圖不顯示。原因是 `X` 格式的日期權杖只吃整數，小數的整數部分之外還剩零頭，解析失敗；即使剩的零頭是 `.0`，字串比對也對不上，一樣判定無效。**小數與 `dateFormat X` 不能同框，沒有例外。** + +## 規則 + +1. **`dateFormat` 固定用 `YYYY-MM-DD`，不用 `X`。** 第一個工作包給一個任意錨點日期（例如 `2000-01-01`），註明「錨點日期非真實排程，只用於相對呈現」。 +2. **每個工作包一個 `id`**，格式 `wp01`、`wp02`……跟編號對應，全小寫、不帶連字號（mermaid id 不吃 `-`）。 +3. **時長一律用整數小時 `{h}h`，直接取 WBS 表的工時(h) 欄位**，不得把工時換算成天數小數再填進圖裡。天數換算只留在標題與 WBS 表文字，圖本身不出現小數。 +4. **除了第一個工作包，其餘一律用 `after {上一個id}`** 串接，不手算累積日期。少算或算錯只會出现在這一步，串接法直接消掉這類錯誤。 +5. 關鍵路徑上的工作包標 `crit`；候補（非關鍵路徑）不進這張圖，只留在 WBS 表與候補清單文字。 + +## 範本 + +關鍵路徑 `WP-02 → WP-05 → WP-09`，工時依序 10h、13h、8h： + +```mermaid +gantt + title 關鍵路徑（單位：小時；錨點日期非真實排程，僅供相對呈現） + dateFormat YYYY-MM-DD + axisFormat %m-%d %H:%M + section 關鍵路徑 + WP-02 {名稱} :crit, wp02, 2000-01-01, 10h + WP-05 {名稱} :crit, wp05, after wp02, 13h + WP-09 {名稱} :crit, wp09, after wp05, 8h +``` + +- 總天數（`= 總工時 / 8`，四捨五入到小數點後 1 位）寫進標題旁的文字或圖下方一行，不進圖本身。 +- 完成條件：圖裡每個時長都是整數加 `h`，沒有任何小數；每個工作包都有 `id`；除第一個外全部用 `after`。 diff --git a/skills/analyze/SKILL.md b/skills/analyze/SKILL.md index 1be65bb..b224c4b 100644 --- a/skills/analyze/SKILL.md +++ b/skills/analyze/SKILL.md @@ -31,7 +31,7 @@ All wiki reads and writes go through `jsc-gitea:wiki`. Completion condition: every user story has reached consensus under both conditions of `references/consensus.md`, and every reuse decision — reused, or rejected with its reason — is recorded in 複用決策. 6. Run a **Work Breakdown Structure (WBS)**: split the user stories into work packages, number them sequentially (`WP-01`, `WP-02`, ...) and mark dependencies. Completion condition: every user story on the plan page maps to at least one numbered work package, and every dependency edge is recorded in the WBS table's 相依 column. 7. **`WP-01` is always the delivery/handover work package** — see "Delivery package is WP-01" below. It stands alone, never merged into an implementation package, and every implementation package that consumes its spec depends on it. Completion condition: `WP-01` is marked 交付 `是` and holds only spec-shaped items, and every implementation package that consumes its spec names `WP-01` in its 相依 column — or the no-handover case below is confirmed with the user and its reason is written on the page. -8. Estimate every work package's effort in hours and days with the **Critical Path Method (CPM)**, and mark the critical path. Completion condition: every work package carries an hours figure and a days figure, and the critical path plus its total days are written on the page. +8. Estimate every work package's effort in hours and days with the **Critical Path Method (CPM)**, and mark the critical path. Draw the critical path as a mermaid gantt chart per `references/cpm-chart.md` — its date/duration rules are mandatory, not a suggestion; skipping them is how the `Invalid date` rendering failure happens. Completion condition: every work package carries an hours figure and a days figure, the critical path plus its total days are written on the page, and the gantt chart follows `references/cpm-chart.md` exactly (integer-hour durations, `after` chaining, no `dateFormat X`). 9. Split every work package into todos with **Test-Driven Development (TDD)**, formatted `[ ]` (open) / `[x]` (done). Each todo is one vertical slice: one seam, one test, one minimal implementation. Seams and anti-patterns: `references/tdd.md`. Completion condition: every work package carries at least one `[ ]` todo, and every todo names its seam and the behaviour its test asserts. 10. Apply `templates/analyze-page.md` to create or update the analysis page and write it back via `jsc-gitea:wiki`. The page content is Traditional Chinese, exactly as the template dictates. Completion condition: the page is saved on the wiki and carries every section the template dictates, including the source branch, the head sha and the 未決項 section (「無」 when there is none). 11. If the analysis page is new: add it to `ANALYZE_CONTENTS` per `templates/analyze-contents.md`, and flip the plan's status in `PLAN_CONTENTS` to the literal 「已分析」. Completion condition: `ANALYZE_CONTENTS` shows the new row and `PLAN_CONTENTS` shows the literal 「已分析」, both saved on the wiki. diff --git a/templates/analyze-page.md b/templates/analyze-page.md index d1763f8..32f00d7 100644 --- a/templates/analyze-page.md +++ b/templates/analyze-page.md @@ -41,6 +41,20 @@ PR 欄記錄該工作包的 PR 連結與編號；PR 未合併前不得開始下 - 關鍵路徑：{WP-01 → WP-02 → ⋯⋯}，總天數 {d} - 實作候補：{WP-02、WP-03、⋯⋯} +## 關鍵路徑（CPM） + +甘特圖語法固定照 `references/cpm-chart.md`：`dateFormat YYYY-MM-DD` 配任意錨點日期、每個工作包一個 `id`、時長用整數小時、除第一個外全部 `after {上一個id}` 串接。**不得用 `dateFormat X` 或把工時換算成小數天數填進圖裡**，會炸出 `Invalid date`。 + +```mermaid +gantt + title 關鍵路徑（單位：小時；錨點日期非真實排程，僅供相對呈現） + dateFormat YYYY-MM-DD + axisFormat %m-%d %H:%M + section 關鍵路徑 + WP-01 {名稱} :crit, wp01, 2000-01-01, {h}h + WP-02 {名稱} :crit, wp02, after wp01, {h}h +``` + ## 待辦事項（TDD） ### WP-01 {交付、交接工作包名稱} -- 2.53.0