文件網站導覽重整方案
本文件用來承接「首頁卡片太多、資料庫需要可視化、需求與完成狀態不夠一眼可讀」的整理工作。
本次規劃只調整文件網站的導覽與資訊呈現方式，不改變專案需求邊界、程式架構、資料模型、API 規劃、資料庫欄位或既有參考文件內容。
整理目標
| 目標 | 說明 |
|---|
| 讓首頁回答核心問題 | 使用者一進首頁就能知道專案要做什麼、目前做到哪裡、下一步是什麼。 |
| 讓需求符合度可視化 | 將需求整理成「已符合 / 部分符合 / 尚未符合」，避免用語模糊造成誤判。 |
| 讓階段邊界明確 | 第一階段與第二階段都要清楚呈現已完成、未完成、不納入範圍。 |
| 讓資料庫進度獨立呈現 | MySQL / Schema Automation 不塞在首頁細節中，改由資料庫儀表板承接。 |
| 保留完整文件索引 | 既有詳細文件不刪除，統一由 docs 索引與主題頁承接。 |
不做的事
| 不做項目 | 原因 |
|---|
| 不刪除既有文件 | 既有文件仍是開發與決策追溯依據。 |
| 不改需求邊界 | 本次只整理呈現方式，不把尚未確認的需求升級成已承諾交付。 |
不改 progress.json 規則 | 進度資料來源仍維持現有同步流程。 |
| 不導入前端框架 | 文件網站仍維持靜態 HTML，降低維護成本。 |
| 不放敏感資訊 | 資料庫 IP、帳號、密碼與正式連線資訊不得放入公開文件網站。 |
目前痛點
| 痛點 | 影響 |
|---|
| 首頁卡片與入口太多 | 使用者不知道應先看哪一份。 |
| 需求、進度、資料庫、索引混在同一層 | 每張卡片的視覺重量接近，難以判斷主次。 |
| 第二階段與平台化需求分散 | 不容易看出哪些已完成、哪些只是規劃。 |
| 資料庫主線文件很多 | MySQL / Schema Automation 的進度需要更像儀表板，而不是文件清單。 |
| 詳細紀錄與決策入口混用 | 首頁像資料夾，不像專案總覽。 |
建議頁面角色
| 頁面 | 角色 | 應回答的問題 |
|---|
index.html | 專案總覽首頁 | 專案是什麼、目前完成什麼、下一步看哪裡。 |
開發進度總覽.html | 進度與完成時間 | 各階段百分比、完成時間、對應 commit 與下一步。 |
docs/phase-two-dashboard.html | 第二階段儀表板 | 第二階段已完成、未完成、待確認項與目前主線。 |
docs/database-dashboard.html | 資料庫可視化儀表板 | MySQL / Schema Automation 完成度、流程與風險。 |
docs/README.html | 完整文件索引 | 所有詳細文件、驗證紀錄與實作前確認清單。 |
docs/platform-capability-roadmap.html | 需求符合度總覽 | 使用者需求是否已納入、在哪個階段完成、剩餘缺口。 |
首頁建議資訊架構
首頁建議只保留五個主要區塊，讓第一次閱讀與主管溝通都能快速掌握。
| 區塊 | 內容 | 呈現方式 |
|---|
| 專案定位 | 一句話說明「智慧設備順序控制系統共用骨架」定位與邊界。 | 頁首摘要 |
| 需求符合度 | 核心需求以「已符合 / 部分符合 / 尚未符合」呈現。 | 小型狀態表 |
| 階段邊界 | 第一階段、第二階段、長期平台分開列出完成與未完成。 | 分段儀表板 |
| 目前主線 | 最新程式狀態、最新文件狀態、下一個建議節點。 | 單一重點卡片 |
| 快速入口 | 需求地圖、開發進度、第二階段、資料庫、完整索引。 | 最多五張入口卡 |
需求符合度呈現草案
此表是首頁或未來需求地圖頁的呈現規格，用來回答「我的需求是否有被包含」。
| 使用者需求 | 目前狀態 | 階段說明 | 首頁顯示重點 |
|---|
| 程式邏輯、設備動作可由 JSON 或其他設定工具編程，不影響核心 | 部分符合 | 第一階段已建立設定檔鏈路、Workflow / Adapter 抽象；圖形化或外部工具尚未建立。 | 已有設定檔基礎，尚未有編輯工具。 |
| 使用 API 呼叫，由 Server 控制設備狀態並查詢設備狀態 | 尚未符合 | WebApi 屬於後續正式平台，不在第一階段交付。 | 已列入後續平台需求。 |
| 控制端透過 Service 掌握設備順序控制或控制裝置 | 尚未符合 | ServiceHost 屬於後續正式執行入口。 | 第一階段先由 ConsoleHost 驗證核心。 |
| 裝置可動態載入外部 DLL，例如馬達通訊、顯示面板刷新控制 | 尚未符合 | 已有 Adapter 契約基礎，但動態載入與外掛生命週期尚未設計。 | 需列入平台化能力。 |
| 一台主機可管理多個設備單元，降低部署成本 | 部分符合 | 已有 DeviceId / Adapter / Workflow 基礎；仍需補設備單元邊界、資源鎖、排程與狀態隔離。 | 已納入平台化需求地圖。 |
已完成 / 未完成呈現規則
| 狀態 | 定義 | 顯示方式 |
|---|
| 已符合 | 程式、測試或驗證紀錄已能支持需求的主要行為。 | 綠色或完成標籤，附對應文件或 commit。 |
| 部分符合 | 已有基礎能力，但尚缺正式入口、整合、驗證或營運能力。 | 黃色或進行中標籤，列出已完成與待補。 |
| 尚未符合 | 需求已討論或納入規劃，但尚未進入實作或驗證。 | 灰色或規劃中標籤，標明所屬階段。 |
| 不納入本階段 | 已明確排除於目前階段外。 | 邊界標籤，避免誤認為缺漏。 |
首頁應移出的內容
| 目前首頁內容 | 建議承接位置 |
|---|
| 大量 MySQL 實作前確認與實作紀錄 | docs/database-dashboard.html 與 docs/README.html |
| 每一份細節文件卡片 | docs/README.html |
| 第二階段細節清單 | docs/phase-two-dashboard.html |
| 舊架構與第一階段規格的詳細說明 | 保留原 HTML，首頁只留入口 |
| 開發日誌逐筆紀錄 | docs/development-log.html |
建議執行順序
| 順序 | 工作 | 目的 |
|---|
| 1 | 建立本導覽重整方案 | 先固定資訊架構，不直接大改首頁。 |
| 2 | 建立或同步 docs/platform-capability-roadmap.html | 將需求符合度用「已符合 / 部分符合 / 尚未符合」整理出來。 |
| 3 | 調整首頁為五區塊總覽 | 讓首頁從文件清單改成專案決策儀表板。 |
| 4 | 檢查手機版與 PDF 版 | 確認主管、工程師與手機閱讀都能看清楚。 |
| 5 | 同步 public 與線上部署 | 確認 Cloudflare Pages 呈現一致。 |
驗收標準
| 驗收項目 | 標準 |
|---|
| 首頁可讀性 | 首頁第一屏能看出專案定位、目前階段與下一步。 |
| 需求可追蹤 | 核心需求能對應到已符合、部分符合、尚未符合。 |
| 階段邊界清楚 | 第一階段與第二階段都有已完成 / 未完成說明。 |
| 詳細文件可找回 | 被移出首頁的細節仍能從 docs 索引找到。 |
| 不改專案承諾 | 只調整呈現，不新增未確認交付範圍。 |
| 手機可閱讀 | 主要表格與卡片在手機上不遮字、不需要猜內容。 |
建議下一步
建議下一步先建立「需求符合度 / 平台化需求地圖」文件頁，將使用者已提出的核心需求整理成已符合、部分符合、尚未符合，再依該頁內容調整首頁。
返回文件首頁