# FR-047 規劃頁拆分成 hub＋功能子頁 — 執行交接（2026-07-06）

| 項目 | 內容 |
|------|------|
| 緣由 | user 審 spec 站後拍板：規劃頁太肥（624 行 / 17 功能混一檔），重整為 hub 導航＋功能子頁 |
| branch | `main`（**不切 branch**；working tree 可能有前一 arc 未 commit 的 spec WIP，見 §6 pre-flight） |
| 接手前必讀 | 本檔全文 → `writing-feature-specs` skill → `project-ssp-edit.md`（hub 合格樣本）→ `project-ssp-inventory.md`（子頁 field-level 合格樣本） |
| 預估 | 1 個 session（拆遷為主、新寫為輔；facts 大多已在現有頁內） |

## 🧭 原始需求（WHY，先懂再動）

user 以全端工程師視角審 `docs/specs/v1.8.0/html/project-management/project-planning.html` 後的回饋（原話濃縮）：

> 這頁功能相當複雜，光功能總覽就切到 17 項；匯入匯出、系統安全計畫、控制項實作各自有各自的邏輯與設計，目前全部混在一個主頁面。版面骨幹跟畫面設計都沒拆開，工程師只看到很龐大的資訊，卻不知道有多少區塊、頁面、component 需要維護。希望工程師能快速理解這份 spec 要做多少東西、主題是什麼、畫面長怎樣、各區塊功能、流程、會用到哪些 API 與 DB。每個 Tab 其實都是獨立的功能與畫面；批次維護若有獨立流程也拆開；由一個主功能做導航。

**目標模型**：`project-planning.md` 改造成「hub 導航頁」（版面骨架＋區塊 inventory＋共用底盤），重功能各自拆成獨立子頁——**完全比照另一個 arc 已建立的 SSP 編輯器模式**（`project-ssp-edit.md` hub 216 行＋5 子頁），不發明新規則。閱讀動線：hub 30 秒定位「有幾塊、動哪塊碰哪支檔」→ 開子頁 10 分鐘搞懂一個功能（子頁維持 field-level 詳細度標準）。

**本棒在大圖的位置**：FR-047 手冊「可讀性/詳細化」arc 的結構收斂步——前一棒已完成 SSP 編輯器 hub＋5 子頁、§6 API 格式一致化、UC 全展開；本棒把同一模式套回規劃頁本體，並把跨頁共用的 FlowPhaseBanner 抽成共用元件 spec。

## §0 接手讀序（按序讀，讀完答自檢再動手）

1. 🔒 本檔「🧭 原始需求」＋「§1 拍板結構」＋「§4 決策與理由」——先懂 WHY 與邊界
2. `.claude/skills/writing-feature-specs/SKILL.md`（13 節模板、事實來源紀律、8 步流程）
3. `docs/specs/v1.8.0/project-management/project-ssp-edit.md` —— **hub 頁合格樣本**（13 節保留、每節只放頁級/跨子區＋指向子頁）
4. `docs/specs/v1.8.0/project-management/project-ssp-inventory.md` —— **子頁 field-level 合格樣本**
5. `docs/specs/v1.8.0/project-management/project-planning.md`（624 行，拆遷來源）＋ `project-task-edit.md`（258 行，將擴充）
6. `docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-06-ssp-subpages-and-planning-deepening-handoff.md`（前一棒現況：哪些已完成、working tree 狀態）

**冷接自檢（答不出來回去讀，別動手）**：
1. 為什麼要拆？拆完讀者動線長怎樣？→ 17 功能混一檔、垂直切片被 13 節水平分節切碎；hub 定位 → 子頁自包含
2. hub 的 13 節跟子頁的 13 節差在哪？→ 同構模板；hub 每節只放頁級/跨區塊內容＋子頁連結，子頁範圍縮到該功能、深到 field-level
3. SSP 編輯器要不要動？→ **不動**（已拆好，是本次的模式來源）；選單上跟規劃頁平級（NAV 巢狀只有兩層）
4. 事實來源是哪三個？→ FE/BE code 實掃 + `scripts/deliverables/out/db_schema.json` + `out/routes.json`；搬運既有內容時逐段帶走出處行號並複核
5. 可以 commit / push 嗎？→ 完成一個子頁可 commit（顯式 git add 檔名）；**push 永遠等 user**；不切 branch

## §1 拍板結構（user 已核可，照做）

### 左側選單（render_html.py `NAV_STRUCTURE`，約 :267）

```python
("專案管理", [
    "project-management/_overview.md",
    "project-management/project-dashboard.md",
    "project-management/project-list.md",
    "project-management/project-create.md",
    "project-management/project-ap-list.md",
    "project-management/project-overview.md",
    ("project-management/project-planning.md", [          # hub（改造）
        "project-management/planning-status.md",           # 新增
        "project-management/project-task-edit.md",         # 既有，擴充
        "project-management/planning-batch-ops.md",        # 新增
        "project-management/planning-basic-info.md",       # 新增
    ]),
    ("project-management/project-ssp-edit.md", [           # 不動
        ...5 子頁不動...
    ]),
]),
...
("共用元件", [                                             # 新群組（放最後一群）
    "shared-components/flow-phase-banner.md",              # 新增（資料夾也新建）
]),
```

- Tab4 程序書管理 / Tab5 雲端整合 → 證據管理群既有頁（`evidence/document-pool.md`、`evidence/project-cloud-integration.md`），**不搬家**，hub 的六 Tab 對照表交叉連結。
- 「共用元件」群收跨頁元件 spec，本次先進 FlowPhaseBanner 一頁；資料夾 `docs/specs/v1.8.0/shared-components/`。

### 新頁 H1 標題（NAV 顯示名來源）

| 檔案 | H1 |
|------|-----|
| planning-status.md | `# 控制項／AO 現況編輯與程序書（Implementation Status）` |
| project-task-edit.md | 改題為 `# AO 任務配置與啟動（Task Config）`（檔名不動，scope 擴大） |
| planning-batch-ops.md | `# 批次維護：匯入匯出與文件匯出（Batch Operations）` |
| planning-basic-info.md | `# 專案基本資訊與參與人員（Basic Info & Participants）` |
| shared-components/flow-phase-banner.md | `# 階段推進橫幅（FlowPhaseBanner）` |

## §2 拆遷對照表（現 project-planning.md → 新家；逐段搬、帶出處、複核）

| 現內容 | 新家 |
|--------|------|
| §1.1 #1 現況編輯、#2 程序書、#13 節點參與人員；UC-PP-01/05/08（含 3 張 .dot）；§6.3 全部＋§6.1 程序書/file-upload 列；§9.3 `ssp_implemented_requirements`/`ssp_statements`/`ssp_reference_documents`＋`planning-er-ssp.dot`；§3 寫 SSP 與節點人員兩列；坑 1/3/5 | **planning-status.md** |
| §1.1 #4 任務、#5 快速配置、#6 開始執行；UC-PP-02（含 .dot）；§6.4 全部（job PUT＋start-task-execution）；§9.3 `job_executions`＋四張關聯表＋`planning-er-jobs.dot`；§3 任務更新/開始執行兩列；坑 2/6/7/8/10 | **project-task-edit.md**（既有內容為底，補 #5/#6 與 UC-PP-02 全域） |
| §1.1 #7~#10；UC-PP-03/06/07（含 3 張 .dot）；§6.1 SSP 批次/任務批次/文件匯出各列（**匯入三步×2 的 request/response 欄位表現況指向 GAI-SD-02，要按 field-level 標準補寫**，含 Excel 樣板欄位定義） | **planning-batch-ops.md** |
| §1.1 #15/#16；UC-PP-09（含 .dot）；PUT `/grc/project` 規格；`projects`/`project_participants`；§11 Drive 改名列；坑 11（⚠️ 無角色守門安全 finding，完整搬） | **planning-basic-info.md** |
| §1.1 #12；UC-PP-04（含 .dot）；§6.5 全部；`stage_objects`；§4 階段推進前置列 | **shared-components/flow-phase-banner.md**（另加「哪些頁面使用」一節：grep 全站 spec 提及 FlowPhaseBanner / stage advance 的頁，各頁改成引用連結、刪重複描述） |
| §1.1 #3 樹導覽、#11 進度卡；§6.2 載入類；讀取鏈 DB 清單；載入時序圖；六 Tab 對照表；坑 4/9（跨區塊） | **hub 保留** |

.dot 檔都在 `project-management/assets/`，搬引用不搬檔案；圖的 alt 文字照舊。

## §2.5 UI wireframe 附圖（每頁必有；user 2026-07-06 追加需求）

**每個 hub 與子頁的 §5 UI 設計，第一張圖必須是「版面 wireframe」**——用區塊格局呈現「這頁有哪幾塊、相對位置、每塊歸誰管」，比截圖＋文字對照更快建立空間感（user 原話：版面骨架用附圖模式比現在容易懂，每個區塊都要）。

**管線已就緒（本棒前置已完成，不用再改工具）**：`render_html.py` 已支援手繪 `.svg` 直接內嵌（同 `.dot` 的 figure/diagram 樣式＋圖說），md 寫法：`![圖說](assets/wireframes/<page>-wireframe.svg)`。

**Canonical 範本（樣式唯一依據，照抄格局再改內容）**：`docs/specs/v1.8.0/project-management/assets/wireframes/project-planning-hub-wireframe.svg`——hub 整頁骨架已畫好，hub 的 §5 直接引用這張。

**樣式慣例（也要寫進 skill 的 template reference，見 §7）**：
- viewBox 寬 900、白底亮色系；字體 `-apple-system, 'Noto Sans TC', sans-serif`；標題 15px bold＋說明 13px
- **灰**（`#F1EFE8`/`#B4B2A9`/文字 `#444441`）＝本頁自己描述的結構；**彩色**＝有獨立子頁的區塊，框內第二行標 `→ 目標檔名.md（UC 編號）`；**虛線框**＝dialog / 條件顯示層
- 色票用固定 ramp（teal `#E1F5EE`/`#5DCAA5`/`#085041`；coral `#FAECE7`/`#F0997B`/`#712B13`；pink `#FBEAF0`/`#ED93B1`/`#72243E`；purple `#EEEDFE`/`#AFA9EC`/`#3C3489`），fill/stroke/文字三值一組，別自創顏色
- **每區塊標 2~3 條代表性 API**（12px mono `ui-monospace, Menlo, monospace`，method＋path，同 ramp 深色）——只標代表性，完整清單在 §6；圖例註明這點
- **彩色區塊整塊包 `<a href="目標.md">` 可點跳轉**（SVG 是內嵌進 HTML 的，`rewrite_links` 會自動 `.md`→`.html`；`<a>` 內第一個子元素放 `<title>開啟：xxx</title>` 當 hover 提示）。href 相對於「引用該圖的 md 所在資料夾」寫（如 hub 在 project-management/ 引用 → 跨群連結寫 `../evidence/xxx.md`、`../shared-components/xxx.md`）。hub 的區塊連子頁；**子頁的 wireframe 區塊連本頁內小節錨點**（如 `#api`、`#uc`，用 pandoc 自動 id，build 後開瀏覽器驗一次可跳）
- 圖底兩行圖例（彩＝子頁可點／灰＝本頁／虛線＝dialog＋補充去向＋「API 僅代表性」註記）
- 示意相對位置與層級即可，不追像素精準；單圖區塊 ≤ 8 個，多了拆張

**每頁要畫什麼**：

| 頁 | wireframe 內容（每區塊都要標對應 API＋可點連結） |
|----|---------------|
| hub | 整頁骨架（✅ 已畫好＝canonical，含區塊 API 標註＋10 個可點連結） |
| planning-status.md | 右面板該區塊放大：實作狀態下拉＋現況描述＋AO 備註＋程序書清單/上傳鈕＋節點參與人員的欄位區塊格局；各小區標對應 PUT/POST 與頁內 §6 錨點 |
| project-task-edit.md | 任務卡展開格局：名稱/描述/指南、類型、指派（含審核人標記）、部門/設備/問卷區、儲存鈕；上方註 Header 的快速配置/開始執行入口；標 job PUT / start-task-execution |
| planning-batch-ops.md | 批次維護選單＋匯入 dialog 三步（上傳→驗證預覽表格（錯誤列標紅）→confirm）的流程格局，兩組 Excel 共用一張、文件匯出下拉另一小塊；三步各標對應 endpoint |
| planning-basic-info.md | Tab2 表單（名稱/描述/起訖）＋ Tab3 參與人員表格（角色下拉、owner 鎖定標記）並排兩塊；標 `PUT /grc/project`（共用一支） |
| flow-phase-banner.md | banner 解剖：階段進度點軸＋當前階段標籤＋前置條件提示區＋推進/退回按鈕（含 disabled 原因 tooltip）；標 stage/info 與 stage/advance |

## §3 hub 改造後的 13 節（比照 project-ssp-edit.md）

1 功能描述——§1.1 總覽表**每列「詳述」欄直連子頁**；2 UC——改 UC 索引表（UC 編號→子頁）；3 權限——進頁權限＋三層遞進總表（細節在子頁）；4 狀態機——planning gate 頁級一份；5 UI——整頁截圖＋版面骨架圖＋六 Tab 對照表（照舊）；6 API——載入類 4 條完整（§6.2 原文）＋總清單其餘列指向子頁；7/8 檔案地圖——View 主檔＋「區塊→component→子頁」對照；9 DB——讀取鏈清單＋er 圖引用移子頁；10——載入時序＋進度卡計算；11——無 socket 等頁級；12——只留跨區塊坑；13——照舊。目標 150~220 行。

## §4 拍板決策與理由（勿再開會）

1. **Tab2＋Tab3 合一頁**：共用同一支 `PUT /grc/project`、同一條 UC-09、同一組寫入表，拆兩頁必有一頁 90% 是指標；頁內 §5 分兩大節呈現兩個畫面。
2. **任務域不開新檔**：`project-task-edit.md` 已存在且已 field-level，擴充納入快速配置＋開始執行（同批任務資料的批次操作）。
3. **SSP 編輯器留選單第二層**（不塞規劃頁下）：NAV 巢狀僅支援兩層，且它自帶 5 子頁；Tab1 關係由 hub 對照表交代。
4. **FlowPhaseBanner 進新「共用元件」群**：它出現在各生命週期頁，現況多頁重複描述——收斂成一份、各頁引用。
5. **批次維護獨立成頁**：三條「匯出→離線填→上傳→線上修正→confirm」流程＋文件匯出是獨立作業面，是現頁最亂的來源。

## §5 工作順序

1. Pre-flight（§6）→ 2. 建 `shared-components/` 資料夾＋flow-phase-banner.md → 3. planning-status.md → 4. 擴充 project-task-edit.md → 5. planning-batch-ops.md（含 field-level 補寫）→ 6. planning-basic-info.md → 7. hub 瘦身改造（§5 引用 canonical wireframe）→ 8. NAV_STRUCTURE 更新＋全站 grep 修 `project-planning.md#` 錨點與 banner 重複段 → 9. build `python3 scripts/deliverables/render_html.py "docs/specs/v1.8.0"` 必 ✅、開瀏覽器抽查 hub 與兩個子頁 → 10. 自查（敏感 grep=0、「GRC 系統」=0、斷鏈 0）→ 11. 更新 FR-047 tracker → 12. skill 更新（§7）。**每個子頁（步驟 2~6）都含自己的 §2.5 wireframe**（照 canonical 樣式，存 `assets/wireframes/`）。每完成一頁可獨立 commit（顯式 add 該頁＋assets＋NAV diff）。

## §6 Pre-flight（必跑）

```bash
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git branch --show-current            # 應為 main；不是就停下問 user
git status --short | head -30        # 預期有前一 arc 的 spec WIP——不可 reset/checkout/stash，只新增與編輯目標檔
ls docs/specs/v1.8.0/project-management/   # 確認 project-ssp-* 5 子頁與 project-task-edit.md 已存在
grep -n "NAV_STRUCTURE" scripts/deliverables/render_html.py | head -1
python3 scripts/deliverables/render_html.py "docs/specs/v1.8.0" | tail -3   # 改動前先確認 build 綠
```

## §7 收尾配套（本棒範圍內）

- **FR-047 tracker**（`docs/features/FR-047-2607-feature-spec-handbook/tracker.md`）：登記 5 個新/改頁與 hub 改造，附 commit。
- **writing-feature-specs skill**：SKILL.md 加拆分門檻鐵則——用 [sitewide plan](2026-07-06-sitewide-wireframe-and-split-plan.md) 的「修正後拆分判準」版（數值紅旗觸發人工判定，拆分條件＝獨立畫面數 ≥2；單畫面 CRUD 不拆；hub 樣本 `project-ssp-edit.md`、子頁樣本 `project-ssp-inventory.md`）；並把原本指向 `project-planning.md` 的「pilot 合格樣貌」改指 hub＋子頁雙樣本。**若 W3 session 已做過 skill 更新則跳過此項**（同款收尾在兩份交接都有列，先做的做、後做的驗）。
- **writing-feature-specs template reference 加 wireframe 慣例**：§5 UI 第一張圖必為版面 wireframe（§2.5 的樣式慣例全文搬進去，canonical 指 `project-planning-hub-wireframe.svg`），新頁一律適用。
- spec 檔頭「變更紀錄」各加一行（日期 2026-07-06 / FR-047 / 一句話）。

## §8 行為規範提醒

不切 branch；顯式 `git add <檔名>` 禁 `-am`/`add -A`（working tree 有他人 WIP）；push 等 user 明示；禁晶晶體與「GRC 系統」；敏感資訊 grep pattern 見 `docs/交付文件/v1.8.0/conventions.md` §B；表結構一律對 `out/db_schema.json`、endpoint 對 `out/routes.json`，**不信舊文件與記憶**；搬運內容也要複核出處行號仍有效（code 可能已改）。

## §9 不在本棒 scope（別順手做）

- SSP 編輯器 hub＋5 子頁內容（已完成，不重寫）
- `evidence/document-pool.md`、`evidence/project-cloud-integration.md` 內容
- FR-046 交付文件管線（另一條線，Task 12/13 進行中）
- 其他功能群的 workspace 頁套用拆分門檻（等 skill 規則落地後另排）
- 補 §5 實機截圖（若缺，登記 tracker 待補，不擋本棒）

## §10 給 fresh session 的超短 prompt（user 複製貼）

```
請接手 FR-047 規劃頁拆分重整。先讀
docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-06-planning-hub-split-handoff.md
全文，答完 §0 冷接自檢四問再動手；照 §5 工作順序執行（hub＋4 子頁＋共用元件群＋NAV＋skill 門檻規則）。
每頁 §5 UI 第一張圖必為版面 wireframe（§2.5 慣例，canonical =
docs/specs/v1.8.0/project-management/assets/wireframes/project-planning-hub-wireframe.svg，
render_html 已支援 .svg 內嵌）。
working tree 有前一 arc 未 commit 的 WIP，只動目標檔、顯式 git add、不切 branch、push 等我指示。
```