↑ 需求首頁 ⌂ 需求中心

FR-047 功能 SPEC 手冊（新人工程師導向）— Design

  • 日期：2026-07-05
  • 狀態：設計核可（user approved，本檔為討論結論歸檔）
  • 目的：建立「按大功能分冊、頁面為單位」的工程 SPEC 手冊，讓新到職全端工程師能快速上手、查功能邏輯、進行開發與維護
  • 與 FR-046 的關係：FR-046（GAI-SD-01~07，Word）給顧問 / 合約；本案給內部工程師與客戶接手工程師，是不同受眾的另一套載體。GAI-SD-02/03/07 內容可被引用，不重寫

1. 問題

FR-046 的文件按「技術面向」切（架構 / API 全量 / DB 全量），適合顧問評估，但工程師查「某個功能怎麼運作」要跨三本翻，無法輔助上手（user 2026-07-05 反饋：「會查到天荒地老」）。

2. 決策（user 拍板）

決策點 結論
受眾 新到職新手全端工程師
組織方式 按大功能分冊（功能群），頁面為 spec 單位
載體 雙軌：markdown 進 repo 為主（可 grep / 連結跳 code），release 時用 FR-046 renderer batch 轉 docx 快照
圖 沿用 Graphviz .dot（維持 renderer 相容）
產製模式 pilot（本 session 手做）→ user 驗收模板 → 量產發包（執行者 prompt 給其他 session / agent）
Pilot 專案管理功能群的「專案規劃」頁

3. 兩層結構

docs/specs/
├── README.md                          # 總索引：功能群 → 頁面 對照（新人入口）
├── <feature-group>/                   # 大功能群（kebab-case）
│   ├── _overview.md                   # 功能群總覽（輕量）
│   ├── <page>.md                      # 頁面 spec（13 節模板）
│   └── ...
  • granularity 準則：一個頁面 spec = 一條 FE route（使用者導航得到的頁面）；頁內 dialog / tab / stepper 歸該頁 spec，不另立檔。
  • _overview.md 只放三種共用物：頁面地圖、共用狀態機與角色權限基調、核心資料模型（小 ERD）。頁面 spec 引用 overview、只寫本頁差異——避免同一狀態機抄多份。
  • 讀者 vs 生產 內容界線（硬規則）：docs/specs/（含 README）純讀者交付物，生產 meta（量產進度 / wave / 狀態 / SOP / 撰寫規則）一律禁入，各住 tracker / writing-feature-specs skill / 本 design.md；完整頁面清單靠側邊欄自動生成、README 不手維護。完整規則見 writing-feature-specs skill「讀者 vs 生產 內容界線」段。

4. 頁面 spec 13 節模板

  1. 功能描述（目的、使用者、在產品中的位置）
  2. Use Case（UC-編號 / 角色 / 前置 / 主流程 / 例外 / 產出，沿用 GAI-SD-07 格式）
  3. 權限矩陣（角色 × 操作；引用 overview + 本頁差異）
  4. 狀態機與前置條件（狀態圖 + 轉換規則；引用 overview + 本頁差異）
  5. UI 設計（版面結構 + 互動 + 空 / 載入 / 錯誤狀態）
  6. 前端檔案地圖（route → view / component / store / service 相對路徑）
  7. 後端檔案地圖（route → app service → domain → repo / model 相對路徑）
  8. API 規格（本頁用到的 endpoint；細節連 GAI-SD-02 / Swagger）
  9. DB(本頁讀寫的表、關鍵欄位；細節連 GAI-SD-03)
  10. 頁面邏輯與資料對應（載入時序圖 + API 欄位 ↔︎ 畫面欄位 + 錯誤對應）
  11. 背景行為與外部依賴（job / socket / jedi-* / 系統參數）
  12. 邊界情況與已知坑（i18n、時區、大資料量、技術債）
  13. 開發與驗證（本機怎麼看到、測試帳號、E2E 位置、相關 FR / changelog 連結）

內容真實性鐵則（承 FR-046）：檔案地圖 / API / 狀態條件 / error code 一律從 code 掃出與核實，不憑記憶或舊文件；敏感資訊規範沿用 docs/交付文件/v1.8.0/conventions.md §B。

5. 被排除的選項

  • 只出 Word：工程師日常查閱不能搜尋 / 跳轉，且必與 code 脫節。
  • 按技術模組（32 個）逐一寫：新人心智模型是「頁面 / 功能」，不是 code 目錄。
  • 13 節全部塞功能群層（不分兩層）：狀態機 / 權限會在頁面間重複，改一漏多。

6. 未來反悔條件

  • 若頁面 spec 平均篇幅失控（>15 頁），檢討把第 8 / 9 節降為純連結。
  • 若 md→docx 需求消失（客戶接受 repo 交付），可停維護雙軌的 docx build。
  • 量產後若發現某功能群頁面互相糾纏（如稽核執行三頁共用一個狀態機），允許升級 overview 承載更多共用內容。