# 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 承載更多共用內容。