NLMA國土功能分區圖連線 1.0.1
作者：Xing Li

安裝與更新
1. QGIS「外掛程式 > 管理與安裝外掛程式 > 從 ZIP 安裝」，選取 NLMA-functional-zone-map-connections-1.0.1.zip。
2. 更新既有版本後請重新啟動 QGIS，再開啟專案。
3. 既有專案請在新版成功展圖後重新儲存一次，使它改用新版快照。
4. 點擊上方工具列的地圖按鈕，或外掛選單「載入／變更縣市…」。

選單與圖層
- 外掛與工具列使用黃綠色雲端搭配深綠色分區地圖的新 SVG 圖示。
- 圖層清單只顯示 NLMA_國土功能分區，隱藏 Band 1／2／3 圖例，並隨專案保存。
- PNG 仍使用 RGB 彩色呈現；隱藏圖例不改變顏色、影像品質或不透明度。
- 先選版本，再選縣市。首次預設「報部審議階段」及「臺北市」。
- 版本選項依序為報部審議階段、公開展覽階段；內部使用官方報部版、公展版參數。
- 縣市順序採內附的國土測繪中心清單；下方顯示該縣市及版本的公告。
- 沒有更改選項直接按 OK，不會重連、不會改變自訂不透明度。
- 真正切換縣市或版本時，更新既有 NLMA_國土功能分區 圖層，保留 ID、順序及群組，
  並套用 70% 不透明度；後續平移、縮放保留使用者調整的不透明度。
- 不會自動把畫面移到縣市，請自行平移或定位至該區域。
- 舊專案如果已有多個外掛圖層，優先變更目前選取者，否則變更第一個。

背景展圖與品質
- 平移、縮放、旋轉或相關顯示變化停止約 0.8 秒後，依主畫布範圍取圖。
- 依出圖範圍採矩形影像，維持至少 2 倍取樣的目標及等比例 DPI；長邊最高 4096，
  仍遵守官方服務上限。範圍與像素寬高比一致，定位檔按像素中心計算。
- 通過格式、尺寸與解碼檢查後，直接保存官方 PNG，不重新壓縮。
- 臺灣本島使用 EPSG:3826；澎湖、金門、連江使用 EPSG:3825。
- 不變更專案座標系統；若與影像 CRS 不同，仍由 QGIS 重投影顯示。
- 圖層未勾選、未列入主畫布、超出設定的顯示比例尺或關閉渲染時，不要求新圖。
- 無關圖層的顯示變動不會取消相同範圍的既有影像請求。

Token 與錯誤處理
- Token 使用超過 30 分鐘，只有下次需要新影像時才取得新工作階段；閒置不定時請求。
- 30 分鐘是本機更新門檻，不是已確認的伺服器 Token 自然效期。
- HTTP 授權錯誤、回應中的 498／499、E1／E2、HTML、逾時或無效影像會提示並暫停。
- 「重新連線」可重試；隱藏圖層等恢復顯示並需要展圖時才連線。
- 「暫停連線」停止自動取圖；「連線狀態」顯示目前選擇與實際影像所屬縣市、版本。
- 切換失敗會保留舊影像的身分，避免把舊影像誤認成新縣市／版本。
- 舊版快取沒有可靠的影像身分記錄時，顯示「舊版保留影像（縣市與版本尚未驗證）」，
  新圖成功後自動改為已驗證的實際來源。
- 更新中途失敗會嘗試還原來源、CRS、樣式、不透明度與影像資訊；若還原亦失敗，
  明確提示「未能完整還原」，不宣稱已保留完整原狀。
- DNS、TLS、代理與連線中斷有不同提示；不輸出含憑證回應、Cookie 或 Token 網址。
- 各控制器使用獨立記憶體 Cookie jar，未整合 QGIS 自訂代理／認證設定。

專案保存與重開
- 改在 QGIS 寫入單一圖層時保存快照。PNG 與 PGW 完整寫入後，才更新專案引用。
- 快照採內容識別，內容相同可重用；新影像不覆寫已存在的舊快照。
- 儲存後繼續平移，不會刪除已存專案引用的快照；較舊備份仍保有原快照。
- 若快照寫入失敗，保留此次專案引用的工作影像並提示，請檢查磁碟空間後再次儲存。
- 快照位於 QGIS 使用者設定目錄的 nluz_background/snapshots；沒有嵌入 QGZ。
- 重開專案或在已開專案啟用外掛，會辨識原圖層並重新連線，不重複新增圖層。
- 同機同設定目錄的保存恢復是本版設計範圍；搬移到另一台電腦仍須另行處理快照檔案。
- 0.1.9 以前已遺失的影像無法靠新版還原，須重新連線取得影像後再儲存。

快取與停用
- 只清理本次執行所建立、且沒有圖層或保存失敗紀錄引用的暫存 PNG／PGW。
- 不掃描或刪除先前工作階段資料夾，也不自動刪除 snapshots，以保護舊專案與備份。
- 停用／卸載外掛取消請求、監聽及工具列按鈕；保留目前影像與已存快照。
- 停用後影像不會繼續更新。

資料與使用範圍
- 各直轄市、縣(市)國土功能分區圖皆為公開展覽草案，非依法核定及公告結果。
- 公展與報部版依官方入口選擇的工作階段、圖層與圖面設定展圖，標示樣式可能不同。
- 公告與排序隨安裝包提供，尚無手動更新公告功能；介面不顯示公告網址或擷取日期。
- 本圖層為主畫布最後成功影像；版面配置、地圖集及其他地圖視窗不會另行取圖。
- 第三方工具，非官方產品；成功取圖不代表正式對外 API 或長期代理使用授權。

本版驗證
- 1.0.1 依 QGIS 掃描修正 E741：將 engine.py 的區域變數 l 改為 service_layer，驗證邏輯不變。
- 外掛簡介與 About 加入中文說明，英文在前、中文在後。
- 已完成語法與 12 組離線回歸：保存事件、儲存後平移、快照寫入失敗、完整還原、
  縣市／影像身分、同選項不重連、透明度、矩形幾何、Token 邊界、舊回應、顯示及快取保護等。
- 2026-10-15 以 PowerShell 正常 WebSession 取得桃園市報部版 1280×800 PNG；
  Python HTTP 用戶端的對照測試被官方代理以 E1 拒絕，未將成功取圖視為穩定 API 權限。
- 維護者已回報 1.0.0 沿用程式在 Windows／QGIS 4.2.3 測試功能正常；1.0.1 尚未另行實機測試。

建議實機驗收順序
1. 載入臺北市報部審議階段，調整不透明度後打開選單、原選項按 OK，確認不變。
2. 儲存專案，再平移成功取圖，不再儲存，關閉專案後離線重開，確認保存當時影像仍在。
3. 恢復網路後重新連線，確認同一圖層可再次平移／縮放取圖。
4. 切換金門或澎湖，確認圖層為 EPSG:3825、70% 不透明度，並在已知位置比對定位。
5. 無效 Token 測試可在 QGIS Python 主控台執行：
   p = qgis.utils.plugins['nluz_background']; e = next(iter(p.engines.values()))
   e.token = 'invalid_token_for_error_test'; e.acquired = __import__('time').monotonic(); e.last_key = None; p.schedule()
   預期提示並暫停，保留影像與身分；再由選單重新連線恢復。這不是自然到期測試。
6. 閒置 30 分鐘，確認沒有背景請求；再平移時才更新工作階段。
