# 用戶故事地圖 (User Story Map)
## 1. 用戶故事地圖概述
本用戶故事地圖旨在梳理「MCP Civil Tools」專案的現有產品功能，將其組織為用戶活動流和具體的用戶任務/故事。這有助於理解產品的全貌，並為後續的功能迭代和版本規劃提供依據。本地圖反映了當前已實現的功能，並預留了擴展空間以納入未來版本的新故事。
## 2. 用戶活動流 (橫向)
(識別現有產品支持的主要用戶活動)
| 用戶活動 (Epic) | 描述 |
| ---------------------- | -------------------------------------------- |
| **A. 座標處理與轉換** | 處理和轉換地理空間座標，主要針對台灣地區常用系統。 |
| **B. 工程參數查詢** | 快速查詢土木工程設計和分析中常用的規範參數。 |
| **C. 基礎工程計算** | 執行常見的土木工程基礎計算。 |
| **D. 水利工程計算** | 進行與水流、排水相關的計算。 |
| **E. 土壤與邊坡工程計算** | 分析土壤特性、邊坡穩定性及土壤流失。 |
| **F. 結構物初步設計輔助** | 提供擋土牆、U型溝等小型結構物的初步計算輔助。 |
| **G. 輔助工具與清單** | 提供其他輔助查詢和支援列表功能。 |
## 3. 用戶任務分解 (縱向) 與版本映射
(在每個活動下列出支持的具體用戶任務/故事，並映射到版本)
---
### 用戶活動 A: 座標處理與轉換
| 用戶任務/故事 (User Story) | 價值/目的 | 現有實現 (v0.1.0) | 未來版本規劃 |
| :---------------------------------------------------------- | :-------------------------------------- | :---------------- | :----------- |
| 作為工程師，我可以將經緯度座標轉換為 TWD97 座標，以便在專案中使用。 | 統一專案座標系統 | ✅ `latlon_to_utm` | |
| 作為GIS分析師，我可以將 TWD97 座標轉換為經緯度，以便在通用地圖上展示。 | 數據可視化與共享 | ✅ `utm_to_latlon` | |
| 作為開發者，我可以指定不同的座標基準面 (Datum) 進行轉換。 | 提高轉換的靈活性和適用性 | ✅ (部分支援) | (考慮更多Datum) |
---
### 用戶活動 B: 工程參數查詢
| 用戶任務/故事 (User Story) | 價值/目的 | 現有實現 (v0.1.0) | 未來版本規劃 |
| :-------------------------------------------------------------- | :-------------------------------------- | :---------------- | :----------- |
| 作為設計師，我可以查詢不同溝渠材料的曼寧係數，以便進行水力計算。 | 獲取準確的設計參數 | ✅ `get_manning_n` | |
| 作為工程師，我可以查詢常用工程材料的物理力學參數，以便進行結構分析。 | 快速獲取材料特性 | ✅ `query_material_params` | (擴充材料庫) |
| 作為規劃師，我可以查詢特定地區的 IDF 降雨強度資料，以便進行排水設計。 | 獲取設計暴雨參數 | ✅ `query_idf_curve` | (擴充地區/更新資料) |
| 作為水保技師，我可以查詢不同土地利用類型的逕流係數，以便估算逕流量。 | 獲取地表逕流參數 | ✅ `get_runoff_coefficient` | |
| 作為研究員，我可以查詢 USLE/RUSLE 中的 R, K, C, P 因子值。 | 進行土壤流失評估 | ✅ `query_r_factor_tool`, `query_k_factor_tool`, `query_c_factor_tool`, `query_p_factor_tool` | (支援更多查詢條件) |
---
### 用戶活動 C: 基礎工程計算
| 用戶任務/故事 (User Story) | 價值/目的 | 現有實現 (v0.1.0) | 未來版本規劃 |
| :------------------------------------------------------------------ | :-------------------------------------- | :---------------- | :----------- |
| 作為結構工程師，我可以計算擋土牆的主動土壓力係數，以便進行牆體設計。 | 獲取設計荷載 | ✅ `calc_active_earth_pressure` | |
| 作為結構工程師，我可以計算擋土牆的被動土壓力係數，以便校核牆體穩定性。 | 獲取抗力參數 | ✅ `calc_passive_earth_pressure` | |
| (未來) 作為岩土工程師，我可以初步估算淺基礎的容許承載力。 | 快速評估地基條件 | | v0.2.0+ |
---
### 用戶活動 D: 水利工程計算
| 用戶任務/故事 (User Story) | 價值/目的 | 現有實現 (v0.1.0) | 未來版本規劃 |
| :------------------------------------------------------------------ | :-------------------------------------- | :---------------- | :----------- |
| 作為水利工程師，我可以計算給定條件下渠道的平均流速。 | 評估水流狀態 | ✅ `channel_flow_velocity` (隱含於 `get_manning_n` 及 `calc_catchment_runoff` 相關邏輯) | (獨立API) |
| 作為水利工程師，我可以計算給定條件下渠道的流量。 | 評估通水能力 | ✅ `channel_flow_discharge` (隱含於 `calc_catchment_runoff` 相關邏輯) | (獨立API) |
| 作為排水工程師，我可以估算集水區在特定降雨條件下的洪峰逕流量。 | 設計排水設施容量 | ✅ `calc_catchment_runoff` | (支援更多方法) |
| (未來) 作為水力設計師，我可以計算不同斷面形狀明渠的水力要素。 | 詳細水力設計 | | v0.2.0+ |
---
### 用戶活動 E: 土壤與邊坡工程計算
| 用戶任務/故事 (User Story) | 價值/目的 | 現有實現 (v0.1.0) | 未來版本規劃 |
| :------------------------------------------------------------------ | :-------------------------------------- | :---------------- | :----------- |
| 作為岩土工程師，我可以計算邊坡在特定條件下的穩定安全係數。 | 評估邊坡安全性 | ✅ `calc_slope_stability` | (支援更多方法) |
| 作為水保技師，我可以估算特定區域的土壤侵蝕模數或年平均土壤流失量。 | 評估水土流失風險 | ✅ `calc_soil_erosion` | (支援RUSLE) |
| 作為生態工程師，我可以根據邊坡條件查詢合適的植生護坡建議。 | 選擇適宜的生態工法 | ✅ `suggest_vegetation_slope` | (擴充建議庫) |
---
### 用戶活動 F: 結構物初步設計輔助
| 用戶任務/故事 (User Story) | 價值/目的 | 現有實現 (v0.1.0) | 未來版本規劃 |
| :------------------------------------------------------------------ | :-------------------------------------- | :---------------- | :----------- |
| 作為設計助理，我可以初步檢核重力式擋土牆的穩定性 (滑動、傾覆、承載力)。 | 快速篩選設計方案 | ✅ `check_retaining_wall` | (更詳細檢核) |
| 作為結構繪圖員，我可以計算U型溝所需的主筋和分佈筋數量。 | 輔助鋼筋配置 | ✅ `calculate_u_channel_rebar` | |
| 作為估算員，我可以根據鋼筋號數和長度計算其總重量。 | 材料用量估算 | ✅ `calculate_rebar_weight` | |
---
### 用戶活動 G: 輔助工具與清單
| 用戶任務/故事 (User Story) | 價值/目的 | 現有實現 (v0.1.0) | 未來版本規劃 |
| :------------------------------------------------------------------ | :-------------------------------------- | :---------------- | :----------- |
| 作為開發者，我可以查詢伺服器支援的曼寧係數材料列表。 | 了解可用參數範圍 | ✅ `list_supported_manning_materials` (透過 `get_manning_n` 間接實現) | (獨立API) |
| 作為用戶，我可以查詢伺服器支援的坡面保護工法列表。 | 了解可選工法 | ✅ `list_slope_protection_methods` | |
| (類似地，其他 `list_supported_...` API) | 提升API易用性和用戶體驗 | ✅ (多個) | |
---
## 4. 故事優先級與版本映射 (總覽)
(此部分與 Roadmap 中的功能優先級和版本規劃保持一致，此處提供一個簡化視角)
* **v0.1.0 (Current)**: 包含上述所有標註為 ✅ 的現有功能。
* **v0.1.x (Maintenance/Optimization)**:
* 修復已知 Bug。
* API 輸入/輸出優化 (更清晰的提示、單位)。
* 完善文檔。
* **v0.2.0 (Feature Enhancement)**: (參考 Roadmap 中規劃的新功能和增強功能)
* 例如：更詳細的擋土牆設計、擴展明渠水力計算、邊坡穩定支援更多方法等。
* **vNext (Future)**: (參考 Roadmap 中的長期目標)
* 例如：結果視覺化、資料庫集成、GIS/CAD 集成等。
**(用戶可根據 Roadmap 的更新，同步調整此處的版本映射和未來規劃的故事。)**
