跳轉到

D-20260812-01｜首頁專案時間線與自適應歷史壓縮

背景與驅動力

每日歷史與月份索引能完整追溯變動，卻不適合作為新讀者理解專案沿革的入口。若另建一份手寫 沿革頁或 JSON 清單，事件標題、日期、連結與現有流水帳會形成第二權威；若只在首頁人工整理， 長期又會因漏更新而失去頭尾。

考慮過的選項

  • 手寫首頁時間線：初期最簡單，但更新時機與歷史流水帳分離，容易漂移，棄。
  • 建立獨立 專案沿革.md 或 JSON 登錄檔：結構清楚，但重複保存既有歷史資料，棄。
  • 由每日歷史條目的可選 marker 生成首頁 managed block，並隨總跨度自適應壓縮（採納）。

決定

  • 歷史記錄/YYYY-MM-DD.md 維持唯一事件權威；ADR 只提供篩選判斷所需的理由與範圍。
  • 入選條目在標題下一行使用 <!-- homepage-milestone importance=N -->，N 只接受 1–5。 未入選就是缺少 marker；ADR frontmatter 不新增 importance，也不補 null、0 或空字串。
  • 標記數不超過 12 時全部顯示。超過後，以最早至最晚標記日期計算跨度：一年內每月一筆、 兩年內每季一筆、三年內每半年一筆、四年以上每年一筆。
  • bucket 內依 importance 高者、日期較晚者、標題穩定排序依序決定；importance 5、全域最早與 最新事件永遠保留，因此 12 是壓縮觸發值，不是硬上限。
  • pnpm history:generate 同時生成月份索引與 總覽 的首頁區塊。時間線連到每日歷史， 不建立獨立沿革頁；視覺使用語意 HTML 與 CSS，無 JavaScript 仍完整可讀。
  • 決策本身構成重大事件時，可與 ADR 同批標記；若 ADR 只規劃未來實作或發布，必須等事件真的 發生後才標記。非 ADR 事件只要獨立符合首頁標準，也可標記。

後果與影響

首頁取得可持續維護的專案敘事，完整歷史與決策理由仍各自留在原權威位置。新增里程碑只需在 每日歷史選擇性加 marker；未入選 ADR 零變更。代價是 history generator 多管理一個首頁 artifact， 且 marker 格式、壓縮決定性與 managed fence 必須納入測試與檢查鏈。本決策據此部分修訂 D-20260728-06，不改變每日正文與月份索引的權威劃分。