Class CharacterLogManager

java.lang.Object

client.CharacterLogManager

public final class CharacterLogManager
extends Object

角色各種「*log」資料表的查詢／寫入協作者，由 P5 God class 拆分自 MapleCharacter。

本類別封裝對 bosslog（王挑戰每日次數）、onetimelog（一次性事件旗標）、 prizelog／aclog（領獎／成就領取閘門）、chronolog（時空石 30 天閘門）等 資料表的計數查詢與插入，這些紀錄被遊戲內容用來實作「每日／一次性」挑戰與領獎限制。

MapleCharacter 以**逐字搬移**的方式把這些方法移入此處，並對每個對外公開方法保留 **簽名完全相同**的委派（delegate），因此所有 Java 呼叫端與 ~2,700 支腳本完全不受影響。協作者僅 持有對所屬角色的回參考，沿用其角色 id／帳號 id（同 package 存取）與共用的 SLF4J logger （MapleCharacter.log）。

Method Summary

Modifier and Type	Method	Description
int	getAcLog(String bossid)	查詢帳號在過去 24 小時內領取指定成就的次數，用於每日成就領取閘門。
int	getBossLog(String bossid)	查詢角色在過去 24 小時內挑戰指定王的次數，用於每日王挑戰次數閘門。
int	getChronosphereLog(String chronoLog)	查詢角色在過去 30 天內使用指定時空石的次數，用於 30 天時空石閘門。
int	getGiftLog(String bossid)	查詢帳號在過去 24 小時內的禮物（gift）領取次數，用於以帳號為單位的每日禮物閘門。
int	getLog(client.LogScope scope, client.ResetType resetType, String eventName)	取得指定維度在當前週期內的計數。
int	getLog(String scope, String resetType, String eventName)	getLog(LogScope, ResetType, String) 的字串便利重載；無法解析列舉時回傳 0。
int	getOneTimeLog(String log)	查詢角色是否已有指定一次性事件旗標，用於「一次性」事件閘門。
int	getPrizeLog(String bossid)	查詢帳號是否已領取指定獎勵，用於以帳號為單位的領獎閘門。
void	setAcLog(String bossid)	為帳號寫入一筆成就領取紀錄。
void	setBossLog(String bossid)	為角色寫入一筆指定王的挑戰紀錄。
void	setChronosphereLog(String chronoLog)	為角色寫入一筆時空石使用紀錄。
void	setLog(client.LogScope scope, client.ResetType resetType, String eventName)	對指定維度的計數 +1（UPSERT）。
void	setLog(client.LogScope scope, client.ResetType resetType, String eventName, int delta)	對指定維度的計數累加 delta（UPSERT，會依 resetType 的日曆邊界自動重置）。
void	setLog(String scope, String resetType, String eventName)	setLog(LogScope, ResetType, String) 的字串便利重載。
void	setLog(String scope, String resetType, String eventName, int delta)	setLog(LogScope, ResetType, String, int) 的字串便利重載；無法解析列舉時靜默不作為。
void	setOneTimeLog(String log)	為角色寫入一筆一次性事件旗標。
void	setPrizeLog(String bossid)	為帳號寫入一筆領獎紀錄。

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

getBossLog

public int getBossLog(String bossid)

查詢角色在過去 24 小時內挑戰指定王的次數，用於每日王挑戰次數閘門。

對 bosslog 資料表以 characterid（角色 id）與 bossid 條件計數， 並以 SQL lastattempt >= subtime(current_timestamp, '1 0:0:0.0') 限定為近一日內的紀錄。 透過 DatabaseConnection 取得當前執行緒共用的 Connection 執行唯讀查詢， 不會修改任何狀態；查詢過程中發生任何例外時靜默回傳 -1。

Parameters:

bossid - 王的識別字串

Returns:

近 24 小時內的挑戰次數；查無紀錄或發生例外時回傳 -1

setBossLog

public void setBossLog(String bossid)

為角色寫入一筆指定王的挑戰紀錄。

對 bosslog 資料表插入一列（characterid＝角色 id、bossid）， 其 lastattempt 由資料表預設值帶入當前時間，藉此推進 getBossLog(String) 的每日計數。 經 Db.update(String, Object...) 執行寫入（僅關閉 Statement，不關閉共用 Connection）； 發生例外時以 MapleCharacter.log 記錄 debug 並吞掉。

Parameters:

bossid - 王的識別字串

getOneTimeLog

public int getOneTimeLog(String log)

查詢角色是否已有指定一次性事件旗標，用於「一次性」事件閘門。

對 onetimelog 資料表以 characterid（角色 id）與 log 條件計數 （不含時間限制，故為永久旗標）。透過 DatabaseConnection 取得共用 Connection 執行唯讀查詢，不修改任何狀態；發生例外時靜默回傳 -1。

Parameters:

log - 一次性事件的識別字串

Returns:

符合的紀錄筆數（0 表示尚未觸發、大於 0 表示已觸發）；查無或例外時回傳 -1

setOneTimeLog

public void setOneTimeLog(String log)

為角色寫入一筆一次性事件旗標。

對 onetimelog 資料表插入一列（characterid＝角色 id、log）， 使 getOneTimeLog(String) 之後對同一旗標永久回傳大於 0。 經 Db.update(String, Object...) 執行寫入（僅關閉 Statement，不關閉共用 Connection）； 發生例外時以 MapleCharacter.log 記錄 debug 並吞掉。

注意：參數名 log 與類別共用 logger 同名，方法內部記錄一律以 MapleCharacter.log 限定。

Parameters:

log - 一次性事件的識別字串

setPrizeLog

public void setPrizeLog(String bossid)

為帳號寫入一筆領獎紀錄。

對 prizelog 資料表插入一列（accid＝帳號 id、bossid）， 推進 getPrizeLog(String) 的領取計數。注意此閘門以**帳號**為單位 （取自 chr.getClient().getAccID()），而非角色。 經 Db.update(String, Object...) 執行寫入（僅關閉 Statement，不關閉共用 Connection）； 發生例外時以 MapleCharacter.log 記錄 debug 並吞掉。

Parameters:

bossid - 領獎來源（王／事件）的識別字串

getPrizeLog

public int getPrizeLog(String bossid)

查詢帳號是否已領取指定獎勵，用於以帳號為單位的領獎閘門。

對 prizelog 資料表以 accid（帳號 id，取自 chr.getClient().getAccID()） 與 bossid 條件計數（不含時間限制，故為永久領取旗標）。透過 DatabaseConnection 取得共用 Connection 執行唯讀查詢，不修改任何狀態；發生例外時靜默回傳 -1。

Parameters:

bossid - 領獎來源（王／事件）的識別字串

Returns:

符合的紀錄筆數（大於 0 表示已領取）；查無或例外時回傳 -1

setAcLog

public void setAcLog(String bossid)

為帳號寫入一筆成就領取紀錄。

對 aclog 資料表插入一列（accid＝帳號 id、bossid）， 其 lastattempt 由資料表預設值帶入當前時間，推進 getAcLog(String) 的每日成就閘門。 此閘門以**帳號**為單位（取自 chr.getClient().getAccID()）。 經 Db.update(String, Object...) 執行寫入（僅關閉 Statement，不關閉共用 Connection）； 發生例外時以 MapleCharacter.log 記錄 debug 並吞掉。

Parameters:

bossid - 成就來源的識別字串

getAcLog

public int getAcLog(String bossid)

查詢帳號在過去 24 小時內領取指定成就的次數，用於每日成就領取閘門。

對 aclog 資料表以 accid（帳號 id，取自 chr.getClient().getAccID()） 與 bossid 條件計數，並以 SQL lastattempt >= subtime(current_timestamp, '1 0:0:0.0') 限定為近一日內的紀錄。透過 DatabaseConnection 取得共用 Connection 執行唯讀查詢， 不修改任何狀態；發生例外時靜默回傳 -1。

Parameters:

bossid - 成就來源的識別字串

Returns:

近 24 小時內的領取次數；查無或例外時回傳 -1

getGiftLog

public int getGiftLog(String bossid)

查詢帳號在過去 24 小時內的禮物（gift）領取次數，用於以帳號為單位的每日禮物閘門。

對 bosslog 資料表以 accountid（帳號 id，取自 chr.accountid） 與 bossid 條件計數，並以 SQL lastattempt >= subtime(current_timestamp, '1 0:0:0.0') 限定為近一日內的紀錄。透過 DatabaseConnection 取得共用 Connection 執行唯讀查詢， 不修改任何狀態；發生例外時靜默回傳 -1。

注意：本方法與 getBossLog(String) 查詢**同一張** bosslog 資料表，但比對的是 accountid 欄位（帳號層級），而 getBossLog(String) 比對的是 characterid 欄位（角色層級）。

Parameters:

bossid - 禮物來源（王／事件）的識別字串

Returns:

近 24 小時內的領取次數；查無或例外時回傳 -1

getChronosphereLog

public int getChronosphereLog(String chronoLog)

查詢角色在過去 30 天內使用指定時空石的次數，用於 30 天時空石閘門。

對 chronolog 資料表以 characterid（角色 id）與 chronid 條件計數， 並以 SQL lastattempt >= subtime(current_timestamp, '30 0:0:0.0') 限定為近 30 日內的紀錄。 透過 DatabaseConnection 取得共用 Connection 執行唯讀查詢，不修改任何狀態； 發生例外時靜默回傳 -1。

Parameters:

chronoLog - 時空石的識別字串（對應資料表 chronid 欄位）

Returns:

近 30 天內的使用次數；查無或例外時回傳 -1

setChronosphereLog

public void setChronosphereLog(String chronoLog)

為角色寫入一筆時空石使用紀錄。

對 chronolog 資料表插入一列（characterid＝角色 id、chronid）， 其 lastattempt 由資料表預設值帶入當前時間，推進 getChronosphereLog(String) 的 30 天閘門。 經 Db.update(String, Object...) 執行寫入（僅關閉 Statement，不關閉共用 Connection）； 發生例外時以 MapleCharacter.log 記錄 debug 並吞掉。

Parameters:

chronoLog - 時空石的識別字串（對應資料表 chronid 欄位）

setLog

public void setLog(client.LogScope scope,
 client.ResetType resetType,
 String eventName)

對指定維度的計數 +1（UPSERT）。便利重載，等同 setLog(LogScope, ResetType, String, int) 的 delta = 1。

Parameters:

scope - 範圍維度（角色／帳號）

resetType - 重置週期維度（日／週／月／永久）

eventName - 事件名稱（識別字）

setLog

public void setLog(client.LogScope scope,
 client.ResetType resetType,
 String eventName,
 int delta)

對指定維度的計數累加 delta（UPSERT，會依 resetType 的日曆邊界自動重置）。

以 (acc_id, char_id, scope, reset_type, event_name) 唯一鍵 UPSERT 到 _acc_char_log： 不存在則插入（初值 delta）；已存在則依該列 last_update 是否仍落在當前週期內，決定 累加（count + delta）或就地重置（跨週期後第一次寫入 → 直接設為 delta）。 last_update 一律設為 NOW()。

SQL 賦值順序攸關正確性：count = IF(...) 必須排在 last_update = NOW() 之前，使 IF 內讀到的是更新前的 last_update；若顛倒，比較對象會變成 剛寫入的 NOW()（恆 ≥ 週期起點）導致永遠累加、重置失效。

採 MySQL 8.0.19+ 的列別名 UPSERT 語法（VALUES ... AS v），避免已棄用的 VALUES()。 經 Db.update(String, Object...) 執行（僅關閉 Statement，不關閉共用 Connection）；發生例外時記錄 debug 並吞掉。

Parameters:

scope - 範圍維度；LogScope.ACC 時 char_id 填哨兵 0，LogScope.CHAR 時填角色 id

resetType - 重置週期維度（日／週／月／永久）

eventName - 事件名稱（識別字）

delta - 累加量（可為負值；通常為正）

getLog

public int getLog(client.LogScope scope,
 client.ResetType resetType,
 String eventName)

取得指定維度在當前週期內的計數。

查詢 _acc_char_log 對應唯一鍵的計數，並加上 last_update >= 當前週期起點 的條件： 若該列不存在、或其 last_update 已落在上一個週期（即已過期、尚未被下一次寫入就地重置）， 一律回傳 0。透過 DatabaseConnection 取得共用 Connection 執行唯讀查詢， 不修改任何狀態；發生例外時記錄 debug 並回傳 0。

Parameters:

scope - 範圍維度（角色／帳號）

resetType - 重置週期維度（日／週／月／永久）

eventName - 事件名稱（識別字）

Returns:

當前週期內的計數；查無、已過期或發生例外時回傳 0

setLog

public void setLog(String scope,
 String resetType,
 String eventName)

setLog(LogScope, ResetType, String) 的字串便利重載。scope／resetType 以列舉名稱字串帶入（大小寫不拘，如 "CHAR"、"day"）；無法解析時靜默不作為。

Parameters:

scope - 範圍維度字串（"CHAR" / "ACC"）

resetType - 重置週期字串（"DAY" / "WEEK" / "MON" / "NEVER"）

eventName - 事件名稱（識別字）

setLog

public void setLog(String scope,
 String resetType,
 String eventName,
 int delta)

setLog(LogScope, ResetType, String, int) 的字串便利重載；無法解析列舉時靜默不作為。

Parameters:

scope - 範圍維度字串（"CHAR" / "ACC"）

resetType - 重置週期字串（"DAY" / "WEEK" / "MON" / "NEVER"）

eventName - 事件名稱（識別字）

delta - 累加量

getLog

public int getLog(String scope,
 String resetType,
 String eventName)

getLog(LogScope, ResetType, String) 的字串便利重載；無法解析列舉時回傳 0。

Parameters:

scope - 範圍維度字串（"CHAR" / "ACC"）

resetType - 重置週期字串（"DAY" / "WEEK" / "MON" / "NEVER"）

eventName - 事件名稱（識別字）

Returns:

當前週期內的計數；無法解析、查無、已過期或例外時回傳 0