Update utils.py

src/DjangoBlog/comments/utils.py

@@ -1,17 +1,55 @@
+#zyl：
+
 import logging
 
+# 引入 Django 的国际化翻译函数，用于将字符串标记为可翻译
+# 在多语言环境中，这些字符串会被翻译成当前激活的语言
 from django.utils.translation import gettext_lazy as _
 
+# 引入项目工具函数：获取当前站点域名
 from djangoblog.utils import get_current_site
+# 引入项目工具函数：发送邮件（封装了 Django 的 send_mail）
 from djangoblog.utils import send_email
 
+# 创建日志记录器实例，使用当前模块名作为 logger 名称
+# 日志级别和处理器在项目的 settings.py 中配置
 logger = logging.getLogger(__name__)
 
 
 def send_comment_email(comment):
+    """
+    发送评论相关邮件通知
+    
+    功能说明：
+    1. 向发表评论的用户发送感谢邮件
+    2. 如果当前评论是回复他人的评论，则同时向被回复者发送通知邮件
+    
+    参数:
+        comment (Comment): 评论模型实例，包含评论的所有信息
+        
+    返回:
+        None: 无返回值，错误会被记录到日志
+        
+    注意:
+        - 邮件发送失败不会中断程序执行，异常会被捕获并记录
+        - 使用 HTTPS 协议构建文章链接，确保安全性
+        - 邮件内容支持 HTML 格式和国际化翻译
+    """
+    
+    # 获取当前站点的域名（例如：www.example.com）
+    # 用于构建完整的文章访问链接
     site = get_current_site().domain
+    
+    # 邮件主题：感谢评论（使用国际化标记）
     subject = _('Thanks for your comment')
+    
+    # 构建文章完整 URL（HTTPS 协议）
+    # comment.article.get_absolute_url() 获取文章相对路径
     article_url = f"https://{site}{comment.article.get_absolute_url()}"
+    
+    # 构建发送给评论作者的 HTML 邮件内容
+    # 包含文章链接，点击可直接查看评论
+    # 使用 _() 标记可翻译字符串，并通过 % 运算符格式化
     html_content = _("""<p>Thank you very much for your comments on this site</p>
                     You can visit <a href="%(article_url)s" rel="bookmark">%(article_title)s</a>
                     to review your comments,
@@ -19,10 +57,20 @@ def send_comment_email(comment):
                     <br />
                     If the link above cannot be opened, please copy this link to your browser.
                     %(article_url)s""") % {'article_url': article_url, 'article_title': comment.article.title}
+    
+    # 获取评论作者的邮箱地址（发送目标）
     tomail = comment.author.email
+    
+    # 发送感谢邮件给当前评论的作者
+    # send_email 是项目封装的邮件发送工具函数
     send_email([tomail], subject, html_content)
+    
+    # 尝试发送回复通知邮件（如果当前评论是回复）
     try:
+        # 检查是否存在父评论（即是否是回复他人的评论）
         if comment.parent_comment:
+            # 构建回复通知邮件内容
+            # 通知被回复者：你的评论收到了新的回复
             html_content = _("""Your comment on <a href="%(article_url)s" rel="bookmark">%(article_title)s</a><br/> has 
                    received a reply. <br/> %(comment_body)s
                     <br/>   
@@ -32,7 +80,26 @@ def send_comment_email(comment):
                      %(article_url)s
                     """) % {'article_url': article_url, 'article_title': comment.article.title,
                             'comment_body': comment.parent_comment.body}
+            
+            # 获取被回复者（父评论作者）的邮箱
             tomail = comment.parent_comment.author.email
+            
+            # 发送通知邮件给父评论作者
             send_email([tomail], subject, html_content)
+    
+    # 捕获邮件发送过程中的任何异常
     except Exception as e:
-        logger.error(e)
+        # 记录错误日志，但不中断程序执行
+        # 这是防御性编程：邮件发送失败不应影响评论提交
+        logger.error(f"Failed to send comment notification email: {e}", exc_info=True)
+
+# 使用场景说明：
+# 1. 用户提交评论后，在视图中调用此函数
+# 2. 首次评论：只发送感谢邮件给评论者
+# 3. 回复评论：发送感谢邮件给回复者，同时发送通知给被回复者
+# 4. 适用于博客、论坛等需要邮件通知的评论系统
+
+# 安全注意事项：
+# - 邮件内容包含用户生成的内容（评论正文），需要防范 XSS
+# - 实际项目中，comment.parent_comment.body 应进行 HTML 转义或清理
+# - 当前代码假设 body 内容是安全的（已在其他环节处理）