补充前端交互边界注释

resources/js/chat-room/bank-modal.js

@@ -94,6 +94,7 @@ export async function bankAction(type) {
         return;
     }
 
+    // 提交期间禁用按钮，避免连续点击重复发起同一笔存取款请求。
     btnEl.disabled = true;
     try {
         const response = await fetch(`/bank/${type}`, {
@@ -112,6 +113,7 @@ export async function bankAction(type) {
             inputEl.value = "";
             await bankLoadInfo();
 
+            // 如果用户正停留在排行榜页，存取款成功后同步刷新当前页余额排名。
             if (document.getElementById("bank-view-ranking")?.style.display !== "none") {
                 await fetchBankRanking(bankRankPage);
             }
@@ -311,6 +313,7 @@ function syncRankingButtons(lastPage) {
  * @returns {string}
  */
 function renderRankingRow(user, index) {
+    // 排行榜接口每页 20 条，这里用当前页和页内索引还原全局名次。
     const absoluteRank = (bankRankPage - 1) * 20 + index + 1;
     let rankClass = "";
     if (bankRankSort === "desc" && bankRankPage === 1) {

resources/js/chat-room/mobile-drawer.js

@@ -347,6 +347,7 @@ export function bindMobileDrawerControls() {
         scheduleRenderMobileUserList();
     });
 
+    // 只有名单抽屉打开时才立即重渲染，关闭状态下等下次打开再读取最新 onlineUsers。
     window.addEventListener("chatroom:users-updated", () => {
         if (mobileDrawerOpen === "users") {
             renderMobileUserList();

resources/js/chat-room/preferences-status.js

@@ -15,6 +15,7 @@ let blockMenuEventsBound = false;
  * @returns {{blocked_system_senders:string[],sound_muted:boolean}}
  */
 export function normalizeChatPreferences(raw, blockableSystemSenders = BLOCKABLE_SYSTEM_SENDERS) {
+    // 服务端或旧本地缓存可能包含已下架发送者，规整时只保留当前白名单。
     const blocked = Array.isArray(raw?.blocked_system_senders)
         ? raw.blocked_system_senders.filter((sender) => blockableSystemSenders.includes(sender))
         : [];
@@ -317,6 +318,7 @@ export function bindBlockMenuControls() {
  * @returns {boolean}
  */
 export function shouldMigrateLocalChatPreferences(serverPreferences, localBlockedSenders, localMuted) {
+    // 只有服务端尚无偏好时才迁移旧本地设置，避免覆盖已同步的账号配置。
     const hasServerPreferences = (serverPreferences?.blocked_system_senders || []).length > 0
         || Boolean(serverPreferences?.sound_muted);
 

resources/js/chat-room/rooms.js

@@ -72,6 +72,7 @@ export function renderRoomStatusRow(room, options = {}) {
             ? '<span style="font-size:9px;color:#7090b0;margin-left:3px;">当前</span>'
             : '<span style="font-size:9px;color:#336699;opacity:.7;margin-left:3px;">当前</span>')
         : "";
+    // 当前房间不生成跳转事件，避免重复进入同一房间触发无意义刷新。
     const clickHandler = isCurrent ? "" : buildRoomClickHandler(room.id, options.roomUrlResolver);
     const badge = room.online > 0
         ? `<span style="background:#e8f5e9;color:#2e7d32;border-radius:8px;padding:0 ${variant === "mobile" ? "6px" : "5px"};font-size:10px;font-weight:bold;white-space:nowrap;flex-shrink:0;">${room.online}${variant === "mobile" ? "" : " "}人</span>`