文件網站資訊架構整理規劃

本文件用來整理文件網站下一輪版面調整方向，目標是讓首頁減量、第二階段邊界更清楚，並讓資料庫進度可以用可視化方式呈現。

目前先做規劃，不直接移除既有文件，也不改變 progress.json 格式、GitHub Actions 同步流程或 Cloudflare Pages 發布方式。

整理目標

目標	說明
首頁減量	首頁只保留專案總覽、目前狀態、階段邊界、下一步與少量快速入口。
分頁承接細節	將大量實作紀錄、確認清單與資料庫細節移到次頁或主題頁。
第二階段邊界清楚	明確呈現第二階段已完成、未完成、暫不做與需確認項目。
資料庫可視化	讓 MySQL / Schema Automation 進度、資料流、資料表與風險一眼可讀。
手機閱讀友善	分頁內容以短區塊、表格與可掃描標題整理，避免首頁過長。

目前問題

問題	影響
首頁卡片太多	使用者需要花時間判斷哪一張卡片最重要。
MySQL 文件分散	Schema Attribute、SQL Generator、Dry Run、Inspector、Initializer 等內容散在多份文件。
進度與邊界混在一起	目前可以看到百分比，但不容易直接看出「哪些已完成、哪些還沒開始」。
工程紀錄與主管總覽混合	首頁同時承載技術細節與狀態總覽，閱讀負擔變高。
資料庫缺少圖像化入口	使用者需要從多份文字文件推回資料表、Schema 產生流程與風險。

建議資訊架構

頁面	定位	主要內容
`index.html`	文件首頁 / 專案總覽	目前開發狀態、第一階段 / 第二階段邊界、目前主線、下一步、四到六個快速入口。
`docs/phase-two-dashboard.html`	第二階段儀表板	第二階段完成 / 未完成清單、主要模組進度、目前決策、下一個驗收節點。
`docs/database-dashboard.html`	資料庫可視化儀表板	MySQL 自動建表進度、Schema 流程圖、資料表草圖、目前風險與待確認項。
`docs/verification-dashboard.html`	驗證節點總覽	自動測試數、人工驗證節點、最近驗證結果、下一個需要人工檢查的節點。
`docs/README.html`	完整文件索引	保留所有文件連結，作為工程師查找細節的總索引。
`docs/development-log.html`	開發歷程	依日期記錄 commit、測試結果、完成時間與後續建議。

首頁建議保留內容

區塊	建議內容
目前開發狀態	總進度、第二階段進度、最新程式 commit、測試數、部署狀態。
專案邊界	第一階段已完成 / 未完成，第二階段已完成 / 未完成。
目前主線	目前正在做的主軸，例如 MySQL Schema Automation。
下一步	單一主要建議與一到兩個備選項。
快速入口	架構方向、開發進度總覽、第二階段儀表板、資料庫儀表板、驗證節點、完整文件索引。

首頁建議移出內容

內容	移往
大量 MySQL 實作前確認文件	`docs/database-dashboard.html` 與 `docs/README.html`。
每一份實作紀錄卡片	`docs/development-log.html` 與完整文件索引。
詳細 Schema Dry Run / Inspector 流程	`docs/database-dashboard.html`。
長篇歷程說明	`docs/development-log.html`。
舊階段細節	`docs/phase-two-dashboard.html` 或完整文件索引。

第二階段儀表板建議內容

已完成

項目	狀態
第二階段規劃架構	已完成
MySQL 套件選型分析	已完成
Schema Attribute 設計與第一版實作	已完成
SQL Generator 第一版	已完成
SchemaDryRunPlanner	已完成
ConsoleHost DryRun 顯示與人工驗證	已完成
Schema Initializer DryRun	已完成
MySqlSchemaInspector 抽象介面與 Mock Inspector	已完成
MySQL Schema Inspector 純程式 helper	已完成

未完成

項目	狀態
MySqlConnector 導入確認	待確認
真實 MySQL provider	未開始
真實 `information_schema` 讀取	未開始
真實 DB 行前連線驗證	未開始
Schema Apply / DDL Executor	未開始
TaskStore 實際資料寫入	未開始
Web API / 背景服務	第二階段後續，尚未導入

資料庫儀表板建議內容

資料庫主線進度

模組	建議顯示
Schema Attribute	100%，已可由 C# Class 維護欄位型別、索引與描述。
SQL Generator	100%，已可產生 MySQL 5.6.2 相容 SQL。
Dry Run Planner	100%，已可比對期望 Schema 與目前 Schema。
Mock Inspector	100%，已可支援不連 DB 的差異驗證。
Query Builder / Row Mapper / Snapshot Assembler	100%，已完成純程式 helper。
MySqlConnector Provider	0%，需確認後才能導入套件與真實 DB。
真實 MySQL Inspect	0%，需連線資訊與權限確認。
Schema Apply	0%，需另行確認是否允許執行 DDL。
TaskStore 寫入	0%，需在 Schema Automation 具備安全邊界後再進入。

建議流程圖

flowchart LR
    A["C# Schema Class"] --> B["SchemaDefinitionParser"]
    B --> C["Expected Schema"]
    D["MySQL information_schema"] --> E["MySqlSchemaInspector"]
    E --> F["Current Schema"]
    C --> G["SchemaDryRunPlanner"]
    F --> G
    G --> H["Dry Run Plan"]
    H --> I["SQL Preview / ConsoleHost 顯示"]

建議資料表視覺區

資料表	定位	目前狀態
`TaskExecution`	任務主檔，記錄任務狀態、開始 / 結束時間與結果。	草案已整理，尚未真實建表。
`NodeExecution`	節點歷程，記錄每個 Workflow Node 的執行結果。	草案已整理，尚未真實建表。
`CommandExecution`	Adapter 指令紀錄，記錄 Device / Command / Request / Response。	草案已整理，尚未真實建表。
`LogTrace`	補充 Log / Trace，用於追蹤錯誤與操作脈絡。	草案已整理，尚未真實建表。

實作順序建議

順序	工作	原因
1	建立本規劃文件	先固定整理方向，避免直接改首頁造成資訊遺失。
2	建立 `phase-two-dashboard`	先讓第二階段已完成 / 未完成邊界清楚。
3	建立 `database-dashboard`	把 MySQL 文件集中成可視化入口。
4	建立 `verification-dashboard`	讓測試與人工驗證節點有獨立入口。
5	精簡首頁卡片	確認次頁可承接後，再把首頁改成總覽。
6	同步 README / docs index	確保文件入口一致。
7	檢查手機版與線上部署	確認閱讀體驗與 Cloudflare Pages 部署正常。

不建議現在做的事

項目	原因
直接刪除既有文件	目前仍需要完整歷程，應先建立次頁承接。
把首頁改成互動式 SPA	會擴大前端維護成本，與目前靜態文件網站定位不符。
改變 `progress.json` 結構	會影響既有 Actions 同步與首頁讀取邏輯。
在未確認前導入資料庫套件	會觸及 AGENTS.md 的停止確認規則。
在文件網站放入密碼或連線字串	真實密碼不得寫入 repo 或公開網站。

下一步建議

建議下一步先建立 docs/phase-two-dashboard.md 與 docs/database-dashboard.md，把第二階段與 MySQL 進度拆出首頁。

完成兩個次頁後，再調整 index.html，讓首頁只保留專案總覽與少量快速入口。

返回文件首頁