Class GuiApiServer

java.lang.Object
server.gui.GuiApiServer
public final class GuiApiServer extends Object
GUI 管理控制台的輕量 HTTP API，提供 gui/ 前端讀取「即時」伺服器狀態。

使用 JDK 內建 HttpServer（零新相依），僅綁定 127.0.0.1 ——永遠不對外可達，符合本專案 localhost 信任的安全姿態 （與 DatabaseConnection 對 loopback DB 的特例一致）。回應為 UTF-8 JSON。

於 server.Start.run() 在三個 Netty 伺服器與遊戲資料皆就緒後啟動 （start()），於關服流程停止（stop()）。可由 settings.ini 的 gui.api.enabled / gui.api.port 開關與設定埠號。

端點：

  • GET /api/health —— 存活檢查。
  • GET /api/overview —— 總覽頁所需的即時資訊（在線、歷史最高、運行時間、 今日註冊、倍率、各頻道狀態、最近嚴重事件、管理員模式、倒數關機狀態）。
  • GET /api/players —— 玩家管理頁的角色清單（characters 表內容聯結 accounts 取遊戲帳號名，並依目前在線玩家集合標記 online 狀態）。
  • GET /api/players/{id} —— 單一角色 + 其帳號的完整詳情（供詳情/編輯視窗）。
  • POST /api/players/{id} —— 儲存詳情視窗的修改（帳號欄位、角色欄位， 以及帳號/MAC/IP 的封鎖狀態）；角色在線時變更會即時套用到遊戲中（見 LiveCharacterEditor）。
  • POST /api/players/{id}/password —— 以 {"password":"…"} 變更該角色所屬帳號的密碼。
  • GET /api/players/{id}/equips —— 角色目前穿戴的裝備清單（部位中文名、道具名、可編輯數值、 潛能含可讀名稱與可指定的潛能選項）；線上以記憶體穿戴格位為準、離線自 inventoryequipment 載入。
  • POST /api/players/{id}/equips/{position} —— 儲存單件裝備的數值；角色在線時即時套用到記憶體並刷新 （見 MapleCharacter.reloadEquip），離線時定點寫回 inventoryequipment。
  • GET /api/bans/related —— 封鎖/解封頁的「關聯帳號」：以創建與最後連線的 IP/MAC 連動歸群（union-find 連通分量），回傳每組共用 IP/MAC 的帳號（含其所有角色名與封鎖狀態）。
  • POST /api/bans/account/{id} —— 以 {"banned":bool} 切換單一帳號的封鎖狀態 （accounts.banned）。
  • POST /api/control/shutdown —— 以 {"minutes":N} 排程倒數關機 （等同遊戲內 !shutdowntime N）；{"cancel":true} 取消倒數。
  • POST /api/control/admin-mode —— 以 {"enabled":bool} 切換 「管理員模式」（只有 GM 帳號可登入），並寫回 settings.ini 以便重啟後記住。
  • GET /api/chatlog?type=N&names=a,b —— 對話紀錄頁的訊息清單（依頻道型別、可選角色名稱 篩選；chatlog 表聯結 characters 取角色名，依時間遞增回傳最近 N 筆）。
  • GET /api/chatlog/context?id=N —— 某句話前後的對話上下文（同頻道、不套用名稱篩選），供「跳到」檢視。
  • GET /api/chatlog/check-name?name=X —— 驗證遊戲暱稱是否存在（供加入篩選前檢查）。
  • GET /api/logs/lookup?q=X —— 統一紀錄頁的查詢：以遊戲帳號或角色暱稱解析出帳號 + 其所有角色 （角色暱稱搜尋會一併回傳預選的角色 id）。
  • GET /api/logs/entries?accId=N&charId=M —— 某角色（CHAR 範圍）與其帳號（ACC 範圍） 在當前週期的 _acc_char_log 計數（依日／週／月／永久分類，與遊戲端 getLog 讀同一列）。
  • POST /api/logs/entry —— 以 {accId,charId,scope,resetType,eventName,count} 覆蓋當前週期某筆計數。
  • POST /api/logs/entry/delete —— 以 {accId,charId,scope,resetType,eventName} 刪除當前週期某筆計數。
  • GET /api/drops/monsters —— 「掉落物設定 / 怪物掉落」頁的怪物清單（WZ Mob.img 的 怪物 id → 名稱，附各怪在 drop_data 的掉落列數 dropCount）。
  • GET /api/drops/monster/{id} —— 單一怪物的掉落列（drop_data 聯結 wz_itemdata 取道具名）。
  • POST /api/drops/monster/{id} —— 以 {itemId,min,max,chance,questId} 新增一筆掉落， 寫入 drop_data 並重載掉落表使其即時生效（等同 !reloaddrops）。
  • PUT /api/drops/drop/{id} —— 以 {min,max,chance,questId} 修改既有掉落列 （以 drop_data.id 定位，不更換物品），並重載掉落表使其即時生效。
  • DELETE /api/drops/drop/{id} —— 刪除既有怪物掉落列（以 drop_data.id 定位），並重載掉落表使其即時生效。
  • GET /api/drops/item-lookup?code=X|name=Y —— 道具代碼↔名稱互查（讀 wz_itemdata），供新增視窗自動帶入另一欄。
  • GET /api/drops/global —— 全部全域掉落（drop_data_global 聯結 wz_itemdata 取道具名； 含怪物等級門檻 mobLevel、活動旗標 eventOnly 與起訖時間 startDate／endDate）。
  • POST /api/drops/global —— 以 {itemId,min,max,chance,mobLevel,eventOnly,startDate,endDate} 新增一筆全域掉落（continent=-1 套用所有地圖），寫入 drop_data_global 並重載掉落表使其即時生效。
  • PUT /api/drops/global/{id} —— 以 {min,max,chance,mobLevel,eventOnly,startDate,endDate} 修改既有全域掉落 （以 drop_data_global.id 定位，不更換物品），並重載掉落表使其即時生效。
  • DELETE /api/drops/global/{id} —— 刪除既有全域掉落列（以 drop_data_global.id 定位），並重載掉落表使其即時生效。
  • GET /api/shops —— 「NPC 商店」頁左側的商店清單（shops 表的 shopid／npcid， NPC 名稱取自 WZ String.wz/Npc.img，附各商店在 shopitems 的販售列數 itemCount）。
  • GET /api/shops/{shopId} —— 單一商店的販售道具列（shopitems 聯結 wz_itemdata 取道具名）。
  • POST /api/shops/{shopId} —— 以 {itemId,buyable,price,reqItem,reqItemQ,minLevel,expiration} 新增一筆販售道具，寫入 shopitems 並清空商店快取使其即時生效（等同 !reloadshops）。
  • PUT /api/shops/item/{id} —— 以 {buyable,price,reqItem,reqItemQ,minLevel,expiration} 修改既有販售列 （以 shopitems.shopitemid 定位，不更換物品），並清空商店快取使其即時生效。
  • DELETE /api/shops/item/{id} —— 刪除既有販售列（以 shopitems.shopitemid 定位），並清空商店快取使其即時生效。
  • GET /api/gachapon —— 「轉蛋機設置」頁左側的機台清單（gashapons 左聯 gashapon_items， 每台機台附其 id／npcId／name 與獎勵列數 itemCount）。
  • POST /api/gachapon —— 以 {npcId,name} 新增一台機台，寫入 gashapons（刻意不重載快取， 須另按「刷新轉蛋機」才生效）；回傳新機台 id。
  • PUT /api/gachapon/{id} —— 以 {npcId,name} 修改既有機台（以 gashapons.id 定位；刻意不重載快取）。
  • DELETE /api/gachapon/{id} —— 刪除既有機台（以 gashapons.id 定位）並連帶刪除其所有 gashapon_items（gashaponsid={id}；刻意不重載快取）。
  • GET /api/gachapon/{id}/items —— 單一機台的獎勵列（gashapon_items 以 gashaponsid={id}， 聯結 wz_itemdata 取道具名）。
  • POST /api/gachapon/{id}/items —— 以 {itemid,chance,min,max,showmsg} 新增一筆獎勵，寫入 gashapon_items（gashaponsid={id}；刻意不重載快取）；回傳新獎勵 id。
  • PUT /api/gachapon/item/{itemId} —— 以 {chance,min,max,showmsg} 修改既有獎勵 （以 gashapon_items.id 定位，不更換物品；刻意不重載快取）。
  • DELETE /api/gachapon/item/{itemId} —— 刪除既有獎勵列（以 gashapon_items.id 定位；刻意不重載快取）。
  • POST /api/gachapon/reload —— 手動重載遊戲內轉蛋機快取（GashaponFactory.reloadGashapons()， 等同 !reloadgashpon），讓先前對 gashapons／gashapon_items 的變更即時生效。
  • GET /api/cashshop —— 「商城設置」頁的完整狀態：items（CashItemFactory 現行商品目錄， 每筆含序號／道具／價格／旗標與所屬分類名）、categories（後端唯一定義的分類碼→名稱對照）、 settings（點裝清除能力／強制楓葉點數／回收價百分比三項）。
  • POST /api/cashshop/item —— 以 {serial?,category?,itemId,count,price,period,gender,mark,showup,priority} 新增或修改一筆商品（serial 缺/0 時依 category 取下一個空序號），寫入 cashshop_modified_items 並即時更新執行中目錄（CashItemFactory.saveModifiedItem(int, int, int, int, int, int, int, boolean, int)）；回 {ok,serial}。
  • DELETE /api/cashshop/item/{serial} —— 以序號刪除一筆商品（CashItemFactory.removeModifiedItem(int)）。
  • POST /api/cashshop/reload —— 全量重載商城目錄（CashItemFactory.initialize(boolean)，等同 !reloadCS）。
  • GET /api/cashshop/export —— 以 CommodityXmlConverter.exportXml() 把資料庫匯出為 Commodity.img.xml（直接下載原始 XML，非 JSON）。
  • POST /api/cashshop/import —— 請求內文為 Commodity.img.xml 原始文字，以 CommodityXmlConverter.importXml(String) 匯入資料庫；回 {imported:N}。
  • POST /api/cashshop/settings —— 以 {stripEquipStats?,forceMaplePoint?,recyclePercent?} 設定三項商城設定欄位（現金商城點裝清除能力／現金商城強制楓葉點數／現金商城回收價百分比）， 即時寫入 ServerConstants 並各以 ServerProperties.saveProperty(String, String) 寫回 settings.ini。
  • GET /api/special-items —— 「特殊道具」頁的全部設定（special_items 聯結 wz_itemdata 取道具名）。
  • POST /api/special-items —— 以 camelCase 全欄位新增一筆（itemId 須存在且未重複；寫入後立刻重載快取即時生效）。
  • PUT /api/special-items/{itemId} —— 修改既有特殊道具設定（以 item_id 定位；寫入後立刻重載快取即時生效）。
  • DELETE /api/special-items/{itemId} —— 刪除既有特殊道具設定（以 item_id 定位；刪除後立刻重載快取即時生效）。
  • POST /api/special-items/reload —— 手動全量重載遊戲內特殊道具快取（SpecialItemFactory.reload()，等同 !reloadspecialitems）；增刪改已自動重載，此端點供外部直接改 special_items 後手動全量同步。
  • GET /api/fishing —— 「釣魚系統」頁的全部設定：config（總開關／觸發間隔秒數／全地圖旗標／指定地圖；取自 ServerConstants.fishingEnabled／fishingIntervalSeconds／fishingAllMaps／fishingMaps） 與 rewards（fishing_rewards 聯結 wz_itemdata 取道具名）。
  • POST /api/fishing/config —— 以 {enabled,intervalSeconds,allMaps,maps}（maps 為逗號分隔字串） 即時設定釣魚開關／間隔／地圖範圍，套用到 ServerConstants 並寫回 settings.ini（設定為遊戲端直接讀取的即時欄位，免重載）。
  • POST /api/fishing/rewards —— 以 FishingRewardInput（camelCase 全欄位）新增一筆釣魚獎勵，寫入 fishing_rewards 並重載獎勵快取（FishingRewardFactory.reloadItems()）即時生效；回傳含新 id 與道具名的完整列。
  • PUT /api/fishing/rewards/{id} —— 修改既有釣魚獎勵（以 fishing_rewards.id 定位），寫入後重載快取即時生效。
  • DELETE /api/fishing/rewards/{id} —— 刪除既有釣魚獎勵（以 fishing_rewards.id 定位），刪除後重載快取即時生效。
  • GET /api/backup —— 「備份設置」頁的狀態：自動備份開關／間隔／保留份數（ServerConstants.DbBackup*）、 備份資料夾名稱，以及 Backup/ 下既有備份 zip 清單（檔名／大小／修改時間，新→舊）。
  • POST /api/backup/settings —— 以 {enabled,intervalMinutes,keep} 設定並持久化自動備份三參數 （寫回 settings.ini），並即時重排程使其免重啟生效。
  • POST /api/backup/run —— 立即執行一次資料庫備份；成功回傳新備份檔名／大小／修改時間。
  • POST /api/backup/restore —— 以 {name} 從某個既有備份 zip 還原（覆寫）資料庫 （破壞性操作，嚴格驗證檔名防路徑穿越、以執行中旗標防與備份重疊）。
  • GET /api/settings —— 「設置」頁的狀態：目前全服倍率（經驗／楓幣／掉落，小數）、 管理員上線預設效果（隱身／無敵）、線上玩家自動存檔（開關／間隔分鐘）、打怪獲得楓葉點數 （開關／機率／點數區間／每日上限）、道具堆疊區間、經驗區間倍率。
  • POST /api/settings/rates —— 以 {exp,meso,drop,mesoDropChance}（前三者小數倍率、 後者 0~100 整數 %）即時設定全服倍率與楓幣掉落機率，套用到所有頻道並寫回 settings.ini。
  • POST /api/settings/admin-login —— 以 {hide?,godmode?} 切換管理員(GM)上線預設的隱身／無敵 （等同 !hide / !godmode），寫回 settings.ini，下次該 GM 角色登入時生效。
  • POST /api/settings/auto-save —— 以 {enabled,intervalMinutes} 設定線上玩家定時自動存檔， 寫回 settings.ini 並即時重排程（見 PlayerAutoSaver）。
  • POST /api/settings/kill-point —— 以 {enabled,chance,min,max,dailyLimit} 即時設定「打怪獲得 楓葉點數」（開關／機率 0~100%／每次隨機點數區間／每日上限，dailyLimit=0 表不限），套用到 ServerConstants.mobdropMP 等欄位並寫回 settings.ini；點數以帳號為單位、每日重置累計。
  • POST /api/settings/item-stacks —— 以 {value}（格式 "起始ID-結束ID:堆疊上限, …"） 整批設定道具堆疊區間，即時套用（ServerConstants.getStackOverride(int)）並寫回 settings.ini。
  • POST /api/settings/exp-brackets —— 以 {value}（格式 "起始等級-結束等級:倍率, …"） 整批設定經驗區間倍率，即時套用（ServerConstants.getExpBracketRate(int)）並寫回 settings.ini。
  • POST /api/settings/level-up —— 以 {enabled} 切換「連續升級」（一次經驗連升數級時不再 捨棄超額經驗），套用到 ServerConstants.連續升級 並寫回 settings.ini。

寫入端點同樣只綁 127.0.0.1，沿用本專案 localhost 信任的安全姿態。

  • Method Details

    • start

      public static void start()
      啟動 HTTP API（依 settings.ini 開關；重複呼叫無作用）。

    • stop

      public static void stop()
      停止 HTTP API（關服流程呼叫；未啟動則無作用）。