diff --git a/resources/js/chat-room/friend-panel.js b/resources/js/chat-room/friend-panel.js
index 12c985f..5011b70 100644
--- a/resources/js/chat-room/friend-panel.js
+++ b/resources/js/chat-room/friend-panel.js
@@ -153,6 +153,7 @@ function appendEmpty(container, text) {
 function resolveFriendAvatar(headface) {
     const avatar = String(headface || "1.gif");
 
+    // 后端可能返回 storage 相对路径或头像文件名，这里统一转成可直接使用的图片地址。
     return avatar.startsWith("storage/") ? `/${avatar}` : `/images/headface/${avatar}`;
 }
 
@@ -191,6 +192,7 @@ function makeFriendRow(friend) {
     const button = document.createElement("button");
     button.className = "fp-action-btn fp-btn-remove";
     button.textContent = "删除";
+    // 好友行是接口返回后动态创建的，按钮监听直接挂在当前行元素上即可。
     button.addEventListener("click", () => {
         void friendAction("remove", username, button);
     });
@@ -260,6 +262,7 @@ async function friendAction(action, username, button) {
                 Accept: "application/json",
             },
             body: JSON.stringify({
+                // 房间 ID 用于后端生成房间内通知或校验上下文，不参与前端判权。
                 room_id: roomId(),
             }),
         });
@@ -316,6 +319,7 @@ export async function friendSearch() {
                 Accept: "application/json",
             },
             body: JSON.stringify({
+                // 搜索添加也带上当前房间，保持和用户卡片添加好友入口一致。
                 room_id: roomId(),
             }),
         });
diff --git a/resources/js/chat-room/lightbox.js b/resources/js/chat-room/lightbox.js
index ec457d8..871aa28 100644
--- a/resources/js/chat-room/lightbox.js
+++ b/resources/js/chat-room/lightbox.js
@@ -36,6 +36,7 @@ export function openChatImageLightbox(imageUrl, imageName = "聊天图片") {
  * @returns {void}
  */
 export function closeChatImageLightbox(event = null) {
+    // 遮罩点击才能关闭；点击预览图本身时保持打开，避免误关。
     if (event && event.target !== event.currentTarget) {
         return;
     }
@@ -73,12 +74,14 @@ export function initChatImageLightboxEvents() {
 
         const imagePreview = event.target.closest("[data-chat-image-lightbox-image]");
         if (imagePreview) {
+            // 图片节点自己不触发关闭，关闭按钮和遮罩由其他分支处理。
             return;
         }
 
         const opener = event.target.closest("[data-chat-image-lightbox-open]");
         if (opener) {
             event.preventDefault();
+            // data-full 优先使用原图地址，href 作为旧链接结构的兼容兜底。
             openChatImageLightbox(opener.dataset.full || opener.href, opener.dataset.alt || "聊天图片");
             return;
         }