feat(bot): announce successful private rule submissions

Author: Aethersailor

README.md

@@ -4,7 +4,7 @@
 
 - ✅ 自动检查 GitHub 规则与 GEOSITE:CN
 - ✅ DNS / NS 归属地判断，给出添加建议
-- ✅ 群组验证与群组 @ 提及模式
+- ✅ 群组验证、群组 @ 提及与私聊成功播报
 - ✅ Docker 部署，支持 `linux/amd64` 与 `linux/arm64`
 
 > 不提供 Windows 支持，仅建议 Docker 部署。
@@ -52,7 +52,7 @@ skip - 跳过说明
 
 > Token 只显示一次，请妥善保存。
 
-### 获取群组 ID（群组模式 / 群组验证需要）
+### 获取群组 ID（群组模式 / 群组验证 / 群组播报需要）
 
 把 @userinfobot 加入群组，它会返回完整群组 ID（通常以 `-100` 开头）。  
 
@@ -121,6 +121,7 @@ docker compose logs -f rule-bot
 | `REQUIRED_GROUP_NAME` | 群组验证名称 | 空 |
 | `REQUIRED_GROUP_LINK` | 群组验证链接 | 空 |
 | `ALLOWED_GROUP_IDS` | 群组模式允许的群组 ID，逗号分隔 | 空 |
+| `ANNOUNCEMENT_GROUP_ID` | 私聊成功提交后的群组播报目标 ID | 空 |
 | `ADMIN_USER_IDS` | 管理员 Telegram 用户 ID，逗号分隔 | 空 |
 | `TZ` | 时区 | `Asia/Shanghai` |
 | `DNS_CACHE_TTL` | DNS A 记录缓存秒数 | `60` |
@@ -173,6 +174,10 @@ docker compose logs -f rule-bot
 
 同时配置 `REQUIRED_GROUP_ID/NAME/LINK` 后生效，未通过或校验失败会拒绝访问（失败即拒绝）。
 
+### 群组播报（ANNOUNCEMENT_GROUP_ID）
+
+配置后，仅在用户通过私聊成功写入新直连规则时发送一条静默群消息。播报只包含提交结果、规则类型、域名与提交链接，不包含用户名、用户 ID、说明或私聊内容。Bot 未入群、无发言权限、请求超时或发送失败都不会改变私聊添加结果；群内直接添加不会触发重复播报。
+
 ### 管理员模式（ADMIN_USER_IDS）
 
 配置 `ADMIN_USER_IDS` 后，指定的管理员用户可以：

docker-compose.yml

@@ -56,6 +56,10 @@ services:
       # 留空则关闭此功能（仅支持私聊模式）
       # - ALLOWED_GROUP_IDS=-1001234567890,-1009876543210
 
+      # 群组播报 (可选: 私聊成功添加域名后发送隐私安全的规则更新通知)
+      # Bot 必须已加入目标群组并拥有发言权限；发送失败不影响私聊添加结果
+      # - ANNOUNCEMENT_GROUP_ID=-1001234567890
+
       # 管理员配置 (可选: 指定管理员用户 ID，拥有强制添加域名的权限)
       # 支持逗号分隔多个 Telegram 用户 ID，例如：123456789,987654321
       # 管理员可以强制添加被系统检测拒绝的域名

src/config.py

@@ -78,6 +78,14 @@ def __init__(self):
         # 支持逗号分隔的多个群组 ID，例如：-1001234567890,-1009876543210
         self.ALLOWED_GROUP_IDS = self._parse_group_ids(os.getenv("ALLOWED_GROUP_IDS", ""))
 
+        # 私聊成功提交后的群组播报（独立配置，避免改变现有群组行为）
+        announcement_group_id_raw = os.getenv("ANNOUNCEMENT_GROUP_ID", "").strip()
+        self.ANNOUNCEMENT_GROUP_ID = self._parse_required_group_id(
+            announcement_group_id_raw
+        )
+        if announcement_group_id_raw and not self.ANNOUNCEMENT_GROUP_ID:
+            logger.warning(f"无效的 ANNOUNCEMENT_GROUP_ID: {announcement_group_id_raw}")
+
         # 管理员配置（Telegram 用户 ID 列表）
         # 支持逗号分隔的多个用户 ID，例如：123456789,987654321
         self.ADMIN_USER_IDS = self._parse_user_ids(os.getenv("ADMIN_USER_IDS", ""))

src/handlers/handler_manager.py

@@ -93,6 +93,24 @@ async def _handle_data_update(self, changes: Dict[str, bool]) -> None:
         if changes.get("geoip") or changes.get("cn_ipv4"):
             self.geoip_service.reload()
 
+    async def _announce_private_addition(self, chat, domain: str, add_result: dict) -> bool:
+        """Broadcast only successful additions that originated in private chat."""
+        if (
+            not self.group_service
+            or not add_result.get("success")
+            or getattr(chat, "type", None) != "private"
+        ):
+            return False
+        try:
+            return await self.group_service.announce_rule_submission(
+                domain,
+                add_result.get("commit_sha", ""),
+                add_result.get("commit_url", ""),
+            )
+        except Exception as e:
+            logger.warning("群组播报调用异常，不影响私聊添加结果: {}", e)
+            return False
+
     async def check_and_add_domain_auto(
         self, 
         domain: str, 
@@ -1359,6 +1377,12 @@ async def _handle_admin_force_add_callback(self, query, user_id: int, data: str)
             reply_markup = InlineKeyboardMarkup(keyboard)
 
             await query.edit_message_text(result_text, reply_markup=reply_markup, parse_mode='Markdown')
+            if add_result.get("success"):
+                await self._announce_private_addition(
+                    getattr(query.message, "chat", None),
+                    target_domain,
+                    add_result,
+                )
             self.set_user_state(user_id, "waiting_add_domain")
 
         except Exception as e:
@@ -1522,6 +1546,12 @@ async def _add_domain_to_github(self, query, user_id: int, description: str):
             reply_markup = InlineKeyboardMarkup(keyboard)
 
             await query.edit_message_text(result_text, reply_markup=reply_markup, parse_mode='Markdown')
+            if add_result.get("success"):
+                await self._announce_private_addition(
+                    getattr(query.message, "chat", None),
+                    target_domain,
+                    add_result,
+                )
 
             # 保持添加模式，便于继续输入域名
             self.set_user_state(user_id, "waiting_add_domain")
@@ -1587,6 +1617,12 @@ async def _add_domain_to_github_message(self, message, user_id: int, description
             reply_markup = InlineKeyboardMarkup(keyboard)
 
             await processing_msg.edit_text(result_text, reply_markup=reply_markup, parse_mode='Markdown')
+            if add_result.get("success"):
+                await self._announce_private_addition(
+                    getattr(message, "chat", None),
+                    target_domain,
+                    add_result,
+                )
 
             # 保持添加模式，便于继续输入域名
             self.set_user_state(user_id, "waiting_add_domain")

src/services/group_service.py

@@ -1,8 +1,9 @@
 """
-群组验证服务
-检查用户是否加入指定群组
+群组服务
+检查用户是否加入指定群组，并提供隐私安全的规则提交播报
 """
 
+import asyncio
 from typing import Optional
 from loguru import logger
 from telegram import Bot
@@ -19,6 +20,7 @@ def __init__(self, config: Config, bot: Bot):
         self.config = config
         self.bot = bot
         self._group_check_enabled = bool(getattr(config, "GROUP_CHECK_ENABLED", False))
+        self._announcement_group_id = getattr(config, "ANNOUNCEMENT_GROUP_ID", None)
         self._membership_cache = TTLCache[int, bool](2048, 300)
 
     def is_group_check_enabled(self) -> bool:
@@ -77,3 +79,63 @@ def get_join_group_message(self) -> str:
         message += "加入后请重新尝试使用机器人功能。"
 
         return message 
+
+    async def announce_rule_submission(
+        self,
+        domain: str,
+        commit_sha: str = "",
+        commit_url: str = "",
+    ) -> bool:
+        """Best-effort broadcast that never changes the core add result."""
+        if not self._announcement_group_id:
+            return False
+
+        short_sha = (commit_sha or "")[:8]
+        message = (
+            "📣 *直连规则更新*\n\n"
+            "✅ *结果：* 已成功提交\n"
+            "🧭 *类型：* `DOMAIN-SUFFIX`\n"
+            f"🌐 *域名：* `{domain}`"
+        )
+        if commit_url and short_sha:
+            message += f"\n🔗 *提交：* [查看 {short_sha}]({commit_url})"
+
+        try:
+            await asyncio.wait_for(
+                self.bot.send_message(
+                    chat_id=self._announcement_group_id,
+                    text=message,
+                    parse_mode="Markdown",
+                    disable_notification=True,
+                    disable_web_page_preview=True,
+                ),
+                timeout=8,
+            )
+            logger.info(
+                "群组播报已发送: group={}, domain={}, commit={}",
+                self._announcement_group_id,
+                domain,
+                short_sha or "unknown",
+            )
+            return True
+        except asyncio.TimeoutError:
+            logger.warning(
+                "群组播报超时，不影响规则提交: group={}, domain={}",
+                self._announcement_group_id,
+                domain,
+            )
+        except TelegramError as e:
+            logger.warning(
+                "群组播报失败，不影响规则提交: group={}, domain={}, error={}",
+                self._announcement_group_id,
+                domain,
+                e,
+            )
+        except Exception as e:
+            logger.warning(
+                "群组播报异常，不影响规则提交: group={}, domain={}, error={}",
+                self._announcement_group_id,
+                domain,
+                e,
+            )
+        return False

tests/test_config.py

@@ -0,0 +1,24 @@
+import os
+import unittest
+from unittest.mock import patch
+
+from src.config import Config
+
+
+class TestConfig(unittest.TestCase):
+    def test_announcement_group_id_is_optional_and_parsed(self):
+        env = {
+            "TELEGRAM_BOT_TOKEN": "telegram-token",
+            "GITHUB_TOKEN": "github-token",
+            "GITHUB_REPO": "example/repo",
+            "DIRECT_RULE_FILE": "rules.list",
+            "ANNOUNCEMENT_GROUP_ID": "-1001234567890",
+        }
+        with patch.dict(os.environ, env, clear=True):
+            config = Config()
+
+        self.assertEqual(config.ANNOUNCEMENT_GROUP_ID, -1001234567890)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_group_service.py

@@ -2,6 +2,9 @@
 import sys
 import unittest
 from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+from telegram.error import TelegramError
 
 sys.path.append(os.path.join(os.path.dirname(__file__), ".."))
 
@@ -23,5 +26,58 @@ def test_join_group_message_escapes_markdown_sensitive_content(self):
         self.assertIn("https://t.me/group\\_name\\(test\\)", message)
 
 
+class TestGroupAnnouncements(unittest.IsolatedAsyncioTestCase):
+    async def test_disabled_announcement_does_not_call_telegram(self):
+        bot = AsyncMock()
+        config = SimpleNamespace(
+            GROUP_CHECK_ENABLED=False,
+            ANNOUNCEMENT_GROUP_ID=None,
+        )
+        service = GroupService(config, bot)
+
+        result = await service.announce_rule_submission("example.com", "abc123")
+
+        self.assertFalse(result)
+        bot.send_message.assert_not_awaited()
+
+    async def test_announcement_is_concise_and_privacy_safe(self):
+        bot = AsyncMock()
+        config = SimpleNamespace(
+            GROUP_CHECK_ENABLED=False,
+            ANNOUNCEMENT_GROUP_ID=-1001234567890,
+        )
+        service = GroupService(config, bot)
+
+        result = await service.announce_rule_submission(
+            "example.com",
+            "abcdef1234567890",
+            "https://github.com/example/repo/commit/abcdef1234567890",
+        )
+
+        self.assertTrue(result)
+        kwargs = bot.send_message.await_args.kwargs
+        self.assertEqual(kwargs["chat_id"], -1001234567890)
+        self.assertIn("已成功提交", kwargs["text"])
+        self.assertIn("DOMAIN-SUFFIX", kwargs["text"])
+        self.assertIn("example.com", kwargs["text"])
+        self.assertIn("abcdef12", kwargs["text"])
+        self.assertNotIn("用户", kwargs["text"])
+        self.assertNotIn("说明", kwargs["text"])
+        self.assertTrue(kwargs["disable_notification"])
+
+    async def test_telegram_failure_is_isolated(self):
+        bot = AsyncMock()
+        bot.send_message.side_effect = TelegramError("forbidden")
+        config = SimpleNamespace(
+            GROUP_CHECK_ENABLED=False,
+            ANNOUNCEMENT_GROUP_ID=-1001234567890,
+        )
+        service = GroupService(config, bot)
+
+        result = await service.announce_rule_submission("example.com")
+
+        self.assertFalse(result)
+
+
 if __name__ == "__main__":
     unittest.main()

tests/test_runtime_safety.py

@@ -4,7 +4,7 @@
 import unittest
 from pathlib import Path
 from types import SimpleNamespace
-from unittest.mock import MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
 
 from src import healthcheck
 from src.handlers.group_handler import GroupHandler
@@ -69,6 +69,26 @@ async def test_handler_manager_bounds_user_states(self):
         self.assertEqual(len(manager.user_states), 4)
         self.assertIn(9, manager.user_states)
 
+    async def test_announcement_only_runs_for_private_success(self):
+        manager = HandlerManager.__new__(HandlerManager)
+        manager.group_service = SimpleNamespace(
+            announce_rule_submission=AsyncMock(return_value=True)
+        )
+        result = {"success": True, "commit_sha": "abc", "commit_url": "https://example.test"}
+
+        private_result = await manager._announce_private_addition(
+            SimpleNamespace(type="private"), "example.com", result
+        )
+        group_result = await manager._announce_private_addition(
+            SimpleNamespace(type="supergroup"), "other.com", result
+        )
+
+        self.assertTrue(private_result)
+        self.assertFalse(group_result)
+        manager.group_service.announce_rule_submission.assert_awaited_once_with(
+            "example.com", "abc", "https://example.test"
+        )
+
     async def test_group_mention_uses_utf16_aware_parser(self):
         handler = GroupHandler.__new__(GroupHandler)
         entity = SimpleNamespace(type="mention")