feat: add group duty pin notification feature

- Introduced a new configuration option `DUTY_PIN_NOTIFY` to control whether the bot re-pins the duty message when updated, providing notifications to group members.
- Updated the architecture documentation to reflect the new functionality of re-pinning duty messages.
- Enhanced the `.env.example` file to include the new configuration option with a description.
- Added tests to verify the behavior of the new refresh pin command and its integration with the existing group duty pin functionality.
- Updated internationalization messages to include help text for the new `/refresh_pin` command.

duty_teller/handlers/__init__.py

@@ -21,4 +21,5 @@ def register_handlers(app: Application) -> None:
     app.add_handler(import_duty_schedule.duty_schedule_document_handler)
     app.add_handler(group_duty_pin.group_duty_pin_handler)
     app.add_handler(group_duty_pin.pin_duty_handler)
+    app.add_handler(group_duty_pin.refresh_pin_handler)
     app.add_error_handler(errors.error_handler)

duty_teller/handlers/commands.py

@@ -163,6 +163,7 @@ async def help_cmd(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
         t(lang, "help.set_phone"),
         t(lang, "help.calendar_link"),
         t(lang, "help.pin_duty"),
+        t(lang, "help.refresh_pin"),
     ]
     if await is_admin_async(update.effective_user.id):
         lines.append(t(lang, "help.import_schedule"))

duty_teller/handlers/group_duty_pin.py

@@ -3,6 +3,7 @@
 import asyncio
 import logging
 from datetime import datetime, timezone
+from typing import Literal
 
 import duty_teller.config as config
 from telegram import Update
@@ -90,16 +91,21 @@ async def _schedule_next_update(
         )
 
 
-async def update_group_pin(context: ContextTypes.DEFAULT_TYPE) -> None:
-    """Job callback: refresh pinned duty message and schedule next update at shift end."""
-    chat_id = context.job.data.get("chat_id")
-    if chat_id is None:
-        return
+async def _refresh_pin_for_chat(
+    context: ContextTypes.DEFAULT_TYPE, chat_id: int
+) -> Literal["updated", "no_message", "failed"]:
+    """Refresh pinned duty message for a chat: edit text, optionally re-pin, schedule next.
+
+    Returns:
+        "updated" if the message was updated successfully;
+        "no_message" if there is no pin record for this chat;
+        "failed" if edit or permissions failed.
+    """
     loop = asyncio.get_running_loop()
     message_id = await loop.run_in_executor(None, _sync_get_message_id, chat_id)
     if message_id is None:
         logger.info("No pin record for chat_id=%s, skipping update", chat_id)
-        return
+        return "no_message"
     text = await loop.run_in_executor(
         None, lambda: _get_duty_message_text_sync(config.DEFAULT_LANGUAGE)
     )
@@ -111,8 +117,32 @@ async def update_group_pin(context: ContextTypes.DEFAULT_TYPE) -> None:
         )
     except (BadRequest, Forbidden) as e:
         logger.warning("Failed to edit pinned message chat_id=%s: %s", chat_id, e)
+        next_end = await loop.run_in_executor(None, _get_next_shift_end_sync)
+        await _schedule_next_update(context.application, chat_id, next_end)
+        return "failed"
+    if config.DUTY_PIN_NOTIFY:
+        try:
+            await context.bot.unpin_chat_message(chat_id=chat_id)
+            await context.bot.pin_chat_message(
+                chat_id=chat_id,
+                message_id=message_id,
+                disable_notification=False,
+            )
+        except (BadRequest, Forbidden) as e:
+            logger.warning(
+                "Re-pin after update failed chat_id=%s: %s", chat_id, e
+            )
     next_end = await loop.run_in_executor(None, _get_next_shift_end_sync)
     await _schedule_next_update(context.application, chat_id, next_end)
+    return "updated"
+
+
+async def update_group_pin(context: ContextTypes.DEFAULT_TYPE) -> None:
+    """Job callback: refresh pinned duty message and schedule next update at shift end."""
+    chat_id = context.job.data.get("chat_id")
+    if chat_id is None:
+        return
+    await _refresh_pin_for_chat(context, chat_id)
 
 
 async def my_chat_member_handler(
@@ -223,8 +253,25 @@ async def pin_duty_cmd(update: Update, context: ContextTypes.DEFAULT_TYPE) -> No
         await update.message.reply_text(t(lang, "pin_duty.failed"))
 
 
+async def refresh_pin_cmd(
+    update: Update, context: ContextTypes.DEFAULT_TYPE
+) -> None:
+    """Handle /refresh_pin: immediately refresh pinned duty message in the group."""
+    if not update.message or not update.effective_chat or not update.effective_user:
+        return
+    chat = update.effective_chat
+    lang = get_lang(update.effective_user)
+    if chat.type not in ("group", "supergroup"):
+        await update.message.reply_text(t(lang, "refresh_pin.group_only"))
+        return
+    chat_id = chat.id
+    result = await _refresh_pin_for_chat(context, chat_id)
+    await update.message.reply_text(t(lang, f"refresh_pin.{result}"))
+
+
 group_duty_pin_handler = ChatMemberHandler(
     my_chat_member_handler,
     ChatMemberHandler.MY_CHAT_MEMBER,
 )
 pin_duty_handler = CommandHandler("pin_duty", pin_duty_cmd)
+refresh_pin_handler = CommandHandler("refresh_pin", refresh_pin_cmd)