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/api/personal_calendar_ics.py

@@ -56,10 +56,12 @@ def build_team_ics(duties_with_name: list[tuple[Duty, str]]) -> bytes:
     """Build a VCALENDAR (ICS) with one VEVENT per duty for team calendar.
 
     Same structure as personal calendar; PRODID is Team Calendar; each VEVENT
-    has SUMMARY='Duty' and DESCRIPTION set to the duty holder's full_name.
+    has SUMMARY set to the duty holder's full_name (or "Duty" if full_name is
+    empty or missing), and DESCRIPTION set to full_name.
 
     Args:
-        duties_with_name: List of (Duty, full_name). full_name is used for DESCRIPTION.
+        duties_with_name: List of (Duty, full_name). full_name is used for
+            SUMMARY and DESCRIPTION.
 
     Returns:
         ICS file content as bytes (UTF-8).
@@ -79,7 +81,8 @@ def build_team_ics(duties_with_name: list[tuple[Duty, str]]) -> bytes:
             end_dt = end_dt.replace(tzinfo=timezone.utc)
         event.add("dtstart", start_dt)
         event.add("dtend", end_dt)
-        event.add("summary", "Duty")
+        summary = (full_name or "").strip() or "Duty"
+        event.add("summary", summary)
         event.add("description", full_name)
         event.add("uid", f"duty-{duty.id}@duty-teller")
         event.add("dtstamp", datetime.now(timezone.utc))

duty_teller/config.py

@@ -64,6 +64,7 @@ class Settings:
     external_calendar_ics_url: str
     duty_display_tz: str
     default_language: str
+    duty_pin_notify: bool
 
     @classmethod
     def from_env(cls) -> "Settings":
@@ -108,6 +109,8 @@ class Settings:
             duty_display_tz=os.getenv("DUTY_DISPLAY_TZ", "Europe/Moscow").strip()
             or "Europe/Moscow",
             default_language=normalize_lang(os.getenv("DEFAULT_LANGUAGE", "en")),
+            duty_pin_notify=os.getenv("DUTY_PIN_NOTIFY", "1").strip().lower()
+            not in ("0", "false", "no"),
         )
 
 
@@ -128,6 +131,7 @@ CORS_ORIGINS = _settings.cors_origins
 EXTERNAL_CALENDAR_ICS_URL = _settings.external_calendar_ics_url
 DUTY_DISPLAY_TZ = _settings.duty_display_tz
 DEFAULT_LANGUAGE = _settings.default_language
+DUTY_PIN_NOTIFY = _settings.duty_pin_notify
 
 
 def is_admin(username: str) -> bool:

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)

duty_teller/i18n/messages.py

@@ -13,6 +13,11 @@ MESSAGES: dict[str, dict[str, str]] = {
         "help.set_phone": "/set_phone — Set or clear phone for duty display",
         "help.calendar_link": "/calendar_link — Get personal calendar subscription link (private chat)",
         "help.pin_duty": "/pin_duty — In a group: pin the duty message (bot needs admin with Pin messages)",
+        "help.refresh_pin": "/refresh_pin — In a group: refresh pinned duty message text immediately",
+        "refresh_pin.group_only": "The /refresh_pin command works only in groups.",
+        "refresh_pin.no_message": "There is no pinned duty message to refresh in this chat.",
+        "refresh_pin.updated": "Pinned duty message updated.",
+        "refresh_pin.failed": "Could not update the pinned message (permissions or edit error).",
         "calendar_link.private_only": "The /calendar_link command is only available in private chat.",
         "calendar_link.access_denied": "Access denied.",
         "calendar_link.success": (
@@ -82,6 +87,11 @@ MESSAGES: dict[str, dict[str, str]] = {
         "help.set_phone": "/set_phone — Указать или очистить телефон для отображения в дежурстве",
         "help.calendar_link": "/calendar_link — Получить ссылку на персональную подписку календаря (только в личке)",
         "help.pin_duty": "/pin_duty — В группе: закрепить сообщение о дежурстве (нужны права админа у бота)",
+        "help.refresh_pin": "/refresh_pin — В группе: немедленно обновить текст закреплённого сообщения о дежурстве",
+        "refresh_pin.group_only": "Команда /refresh_pin работает только в группах.",
+        "refresh_pin.no_message": "В этом чате нет закреплённого сообщения о дежурстве для обновления.",
+        "refresh_pin.updated": "Закреплённое сообщение о дежурстве обновлено.",
+        "refresh_pin.failed": "Не удалось обновить закреплённое сообщение (права или ошибка редактирования).",
         "calendar_link.private_only": "Команда /calendar_link доступна только в личке.",
         "calendar_link.access_denied": "Доступ запрещён.",
         "calendar_link.success": (