# 產品評估指標框架 (Metrics Framework)
## 1. 指標框架概述
本指標框架旨在為「MCP Civil Tools」專案提供一套衡量產品表現、追蹤用戶行為、並驅動持續改進的機制。透過合理的指標設定與監測，團隊可以更好地理解產品的健康狀況、用戶對各項功能的接受程度，並為產品決策提供數據支持。
## 2. 北極星指標定義
* **建議思考方向**: **「透過 MCP Civil Tools 成功完成的有效工程查詢/計算次數」**
* **選擇依據**:
* 此指標直接反映產品的核心價值——提供準確、便捷的土木工程計算與查詢服務——是否被用戶有效利用。
* 「成功完成」強調了結果的有效性和準確性，排除了錯誤調用或無效查詢。
* 「有效」可以進一步定義為用戶最終採納或基於該結果進行了下一步操作的查詢/計算。
* **輔助衡量**:
* 若能追蹤到 LLM 客戶端，可以考慮「由 MCP Civil Tools 提供的答案被用戶採納的比例」。
## 3. 核心指標體系建議
考慮到本產品作為一個後端工具服務的特性，可以結合 **HEART 框架** (Happiness, Engagement, Adoption, Retention, Task success) 和 **AARRR 模型** (Acquisition, Activation, Retention, Referral, Revenue - 此處 Revenue 可能不直接適用，但前幾項仍有參考價值) 的部分理念，重點關注以下幾類指標：
* **任務成功率 (Task Success - HEART)**:
* **API 調用成功率**: (成功響應數 / 總請求數) * 100%。目標 > 99.9%。
* **核心功能計算準確率**: (需要人工抽樣或與已知結果比對) 針對關鍵計算（如邊坡穩定、逕流量）的結果準確度。
* **查詢命中率**: (查詢到有效結果的次數 / 總查詢次數) * 100%。針對查表類 API。
* **使用與活躍度 (Engagement & Adoption - HEART / Activation - AARRR)**:
* **API 總調用量**: 每日/每週/每月 API 請求總數。
* **活躍用戶數 (若可識別)**: 每日/每週/每月調用 API 的獨立客戶端/用戶數 (可能需要 MCP 客戶端傳遞識別信息)。
* **各功能模塊使用頻次**: 不同 API (例如 `calc_slope_stability` vs `get_manning_n`) 的調用次數分佈，了解哪些功能最受歡迎。
* **新用戶首次成功調用時長**: (若可追蹤新用戶) 從首次嘗試到成功調用核心功能的平均時間。
* **性能與可靠性**:
* **平均 API 響應時間**: 各 API 的平均處理時間。目標 < 500ms (P95)。
* **API 錯誤率**: (錯誤響應數 / 總請求數) * 100%。按錯誤類型分類。
* **伺服器正常運行時間 (Uptime)**: 伺服器可用時長百分比。
* **用戶滿意度 (Happiness - HEART)**: (較難直接量化，可間接或通過用戶反饋收集)
* **用戶反饋數量與類型**: 收集到的 Bug 報告、功能建議、正面評價等。
* **(若有 LLM 整合) LLM 返回結果中，本工具提供內容的點讚/點踩率。**
* **留存 (Retention - HEART & AARRR)**: (若可識別用戶)
* **用戶周/月留存率**: 本周/月活躍用戶中，下周/月仍然活躍的比例。
## 4. 功能級評估指標
| 功能模塊 | 建議追蹤指標 | 備註 |
| -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------- |
| **座標轉換** | `latlon_to_utm` 調用次數, `utm_to_latlon` 調用次數, 平均響應時間, 錯誤率 | 監測使用頻率和轉換成功率 |
| **曼寧係數查詢** | `get_manning_n` 調用次數, 查詢命中率, 未命中時返回建議列表的次數 | 評估數據覆蓋度和用戶體驗 |
| **邊坡穩定計算** | `calc_slope_stability` 調用次數, 平均計算時間, 不同計算方法使用分佈 | 了解核心計算功能的使用情況 |
| **土壤侵蝕計算** | `calc_soil_erosion` 調用次數, 平均計算時間 | |
| **集水區逕流量計算** | `calc_catchment_runoff` 調用次數, 不同參數組合使用情況 (例如是否使用P值推估I) | 分析用戶對不同計算路徑的偏好 |
| **擋土牆檢核** | `check_retaining_wall` 調用次數, 各項檢核通過率 (滑動/傾覆/承載力) | 了解設計方案的初步合格率 |
| **支援清單查詢 API** | 各 `list_supported_...` API 調用次數 | 反映用戶對輔助查詢功能的依賴程度 |
| **USLE 因子查詢** | 各 `query_..._factor_tool` 調用次數 | |
## 5. 指標監測計劃
* **數據收集方式**:
* **伺服器日誌**: FastAPI 可以配置日誌中間件，記錄每個請求的詳細信息 (路徑、方法、狀態碼、響應時間、用戶代理、IP位址等)。
* **應用內指標打點**: 在關鍵函數執行前後記錄時間戳，或在特定邏輯分支處增加計數器。
* **(可選) 專用監控服務**: 集成如 Prometheus (配合 `starlette-exporter`) 或 Sentry (錯誤追蹤)。
* **數據收集工具建議**:
* **日誌管理**: ELK Stack (Elasticsearch, Logstash, Kibana) 或 Grafana Loki。
* **指標監控與告警**: Prometheus + Grafana, Alertmanager。
* **錯誤追蹤**: Sentry。
* **數據存儲與處理**:
* 日誌文件定期歸檔。
* 監控數據存儲於時序資料庫 (如 Prometheus)。
* **報告與分析頻率**:
* **每日**: 關注核心 API 錯誤率、伺服器健康狀況 (CPU、內存)。
* **每週**: 分析 API 調用趨勢、用戶活躍度變化、功能使用熱度。
* **每月**: 檢視留存指標、任務成功率長期趨勢，評估產品迭代效果。
* **儀表板 (Dashboard) 建議** (使用 Grafana 或 Kibana 創建):
* **總覽儀表板**: 北極星指標、API 總調用量、活躍用戶數、平均響應時間、總體錯誤率。
* **功能模塊儀表板**: 各核心功能的使用量、成功率、平均響應時間。
* **錯誤分析儀表板**: 錯誤類型分佈、高頻錯誤 API、錯誤趨勢。
* **性能儀表板**: CPU/內存使用率、請求隊列長度 (若適用)、GC 活動 (若適用)。
* **負責人**: (待用戶指定)
* 指標定義與調整：產品經理/開發負責人
* 監控系統搭建與維護：開發/運維工程師
* 數據分析與報告：產品經理/數據分析師 (若有)
* **迭代與優化**:
* 定期 (例如每季度) 回顧指標體系的有效性，根據產品發展和業務目標調整或新增指標。
* 對於未達預期的指標，深入分析原因並制定改進措施。
