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.
2026-02-23 10:51:47 +03:00
parent 77a94fa91b
commit 8091c608e8
14 changed files with 270 additions and 24 deletions
--- a/tests/test_handlers_group_duty_pin.py
+++ b/tests/test_handlers_group_duty_pin.py
@@ -4,9 +4,10 @@ from datetime import datetime, timedelta, timezone
 from unittest.mock import AsyncMock, MagicMock, patch

 import pytest
-from telegram.error import BadRequest
+from telegram.error import BadRequest, Forbidden
 from telegram.constants import ChatMemberStatus

+import duty_teller.config as config
 from duty_teller.handlers import group_duty_pin as mod


@@ -126,27 +127,34 @@ async def test_schedule_next_update_when_utc_none_runs_once_with_retry_delay():

@pytest.mark.asyncio
 async def test_update_group_pin_edits_message_and_schedules_next():
-    """update_group_pin: with message_id and text, edits message and schedules next update."""
+    """update_group_pin: with message_id and text, edits message, re-pins with notification, schedules next."""
    context = MagicMock()
    context.job = MagicMock()
    context.job.data = {"chat_id": 123}
    context.bot = MagicMock()
    context.bot.edit_message_text = AsyncMock()
+    context.bot.unpin_chat_message = AsyncMock()
+    context.bot.pin_chat_message = AsyncMock()
    context.application = MagicMock()
    context.application.job_queue = MagicMock()
    context.application.job_queue.get_jobs_by_name = MagicMock(return_value=[])
    context.application.job_queue.run_once = MagicMock()

-    with patch.object(mod, "_sync_get_message_id", return_value=1):
-        with patch.object(
-            mod, "_get_duty_message_text_sync", return_value="Current duty"
-        ):
-            with patch.object(mod, "_get_next_shift_end_sync", return_value=None):
-                with patch.object(mod, "_schedule_next_update", AsyncMock()):
-                    await mod.update_group_pin(context)
+    with patch.object(config, "DUTY_PIN_NOTIFY", True):
+        with patch.object(mod, "_sync_get_message_id", return_value=1):
+            with patch.object(
+                mod, "_get_duty_message_text_sync", return_value="Current duty"
+            ):
+                with patch.object(mod, "_get_next_shift_end_sync", return_value=None):
+                    with patch.object(mod, "_schedule_next_update", AsyncMock()):
+                        await mod.update_group_pin(context)
    context.bot.edit_message_text.assert_called_once_with(
        chat_id=123, message_id=1, text="Current duty"
    )
+    context.bot.unpin_chat_message.assert_called_once_with(chat_id=123)
+    context.bot.pin_chat_message.assert_called_once_with(
+        chat_id=123, message_id=1, disable_notification=False
+    )


@pytest.mark.asyncio
@@ -165,7 +173,7 @@ async def test_update_group_pin_no_message_id_skips():

@pytest.mark.asyncio
 async def test_update_group_pin_edit_raises_bad_request_still_schedules_next():
-    """update_group_pin: edit_message_text BadRequest -> log, _schedule_next_update still called."""
+    """update_group_pin: edit_message_text BadRequest -> no unpin/pin, _schedule_next_update still called."""
    context = MagicMock()
    context.job = MagicMock()
    context.job.data = {"chat_id": 111}
@@ -173,6 +181,8 @@ async def test_update_group_pin_edit_raises_bad_request_still_schedules_next():
    context.bot.edit_message_text = AsyncMock(
        side_effect=BadRequest("Message not modified")
    )
+    context.bot.unpin_chat_message = AsyncMock()
+    context.bot.pin_chat_message = AsyncMock()
    context.application = MagicMock()

    with patch.object(mod, "_sync_get_message_id", return_value=2):
@@ -182,9 +192,62 @@ async def test_update_group_pin_edit_raises_bad_request_still_schedules_next():
                    mod, "_schedule_next_update", AsyncMock()
                ) as mock_schedule:
                    await mod.update_group_pin(context)
+    context.bot.unpin_chat_message.assert_not_called()
+    context.bot.pin_chat_message.assert_not_called()
    mock_schedule.assert_called_once_with(context.application, 111, None)


+@pytest.mark.asyncio
+async def test_update_group_pin_repin_raises_still_schedules_next():
+    """update_group_pin: edit succeeds, unpin or pin raises -> log, _schedule_next_update still called."""
+    context = MagicMock()
+    context.job = MagicMock()
+    context.job.data = {"chat_id": 222}
+    context.bot = MagicMock()
+    context.bot.edit_message_text = AsyncMock()
+    context.bot.unpin_chat_message = AsyncMock(side_effect=Forbidden("Not enough rights"))
+    context.bot.pin_chat_message = AsyncMock()
+    context.application = MagicMock()
+
+    with patch.object(config, "DUTY_PIN_NOTIFY", True):
+        with patch.object(mod, "_sync_get_message_id", return_value=3):
+            with patch.object(mod, "_get_duty_message_text_sync", return_value="Text"):
+                with patch.object(mod, "_get_next_shift_end_sync", return_value=None):
+                    with patch.object(
+                        mod, "_schedule_next_update", AsyncMock()
+                    ) as mock_schedule:
+                        with patch.object(mod, "logger") as mock_logger:
+                            await mod.update_group_pin(context)
+    context.bot.edit_message_text.assert_called_once()
+    mock_logger.warning.assert_called_once()
+    assert "Re-pin" in mock_logger.warning.call_args[0][0]
+    mock_schedule.assert_called_once_with(context.application, 222, None)
+
+
+@pytest.mark.asyncio
+async def test_update_group_pin_duty_pin_notify_false_skips_repin():
+    """update_group_pin: DUTY_PIN_NOTIFY False -> edit only, no unpin/pin, schedule next."""
+    context = MagicMock()
+    context.job = MagicMock()
+    context.job.data = {"chat_id": 333}
+    context.bot = MagicMock()
+    context.bot.edit_message_text = AsyncMock()
+    context.bot.unpin_chat_message = AsyncMock()
+    context.bot.pin_chat_message = AsyncMock()
+    context.application = MagicMock()
+
+    with patch.object(config, "DUTY_PIN_NOTIFY", False):
+        with patch.object(mod, "_sync_get_message_id", return_value=4):
+            with patch.object(mod, "_get_duty_message_text_sync", return_value="Text"):
+                with patch.object(mod, "_get_next_shift_end_sync", return_value=None):
+                    with patch.object(mod, "_schedule_next_update", AsyncMock()) as mock_schedule:
+                        await mod.update_group_pin(context)
+    context.bot.edit_message_text.assert_called_once()
+    context.bot.unpin_chat_message.assert_not_called()
+    context.bot.pin_chat_message.assert_not_called()
+    mock_schedule.assert_called_once_with(context.application, 333, None)
+
+
@pytest.mark.asyncio
 async def test_pin_duty_cmd_group_only_reply():
    """pin_duty_cmd in private chat -> reply group_only."""
@@ -276,6 +339,98 @@ async def test_pin_duty_cmd_pin_raises_replies_failed():
    mock_t.assert_called_with("en", "pin_duty.failed")


+# --- refresh_pin_cmd ---
+
+
+@pytest.mark.asyncio
+async def test_refresh_pin_cmd_private_replies_group_only():
+    """refresh_pin_cmd in private chat -> reply refresh_pin.group_only."""
+    update = MagicMock()
+    update.message = MagicMock()
+    update.message.reply_text = AsyncMock()
+    update.effective_chat = MagicMock()
+    update.effective_chat.type = "private"
+    update.effective_chat.id = 1
+    update.effective_user = MagicMock()
+    context = MagicMock()
+
+    with patch("duty_teller.handlers.group_duty_pin.get_lang", return_value="en"):
+        with patch("duty_teller.handlers.group_duty_pin.t") as mock_t:
+            mock_t.return_value = "Group only"
+            await mod.refresh_pin_cmd(update, context)
+    update.message.reply_text.assert_called_once_with("Group only")
+    mock_t.assert_called_with("en", "refresh_pin.group_only")
+
+
+@pytest.mark.asyncio
+async def test_refresh_pin_cmd_group_updated_replies_updated():
+    """refresh_pin_cmd in group with pin record -> _refresh_pin_for_chat returns updated -> reply refresh_pin.updated."""
+    update = MagicMock()
+    update.message = MagicMock()
+    update.message.reply_text = AsyncMock()
+    update.effective_chat = MagicMock()
+    update.effective_chat.type = "group"
+    update.effective_chat.id = 100
+    update.effective_user = MagicMock()
+    context = MagicMock()
+
+    with patch("duty_teller.handlers.group_duty_pin.get_lang", return_value="en"):
+        with patch.object(
+            mod, "_refresh_pin_for_chat", AsyncMock(return_value="updated")
+        ):
+            with patch("duty_teller.handlers.group_duty_pin.t") as mock_t:
+                mock_t.return_value = "Updated"
+                await mod.refresh_pin_cmd(update, context)
+    update.message.reply_text.assert_called_once_with("Updated")
+    mock_t.assert_called_with("en", "refresh_pin.updated")
+
+
+@pytest.mark.asyncio
+async def test_refresh_pin_cmd_group_no_message_replies_no_message():
+    """refresh_pin_cmd: no pin record -> _refresh_pin_for_chat returns no_message -> reply refresh_pin.no_message."""
+    update = MagicMock()
+    update.message = MagicMock()
+    update.message.reply_text = AsyncMock()
+    update.effective_chat = MagicMock()
+    update.effective_chat.type = "group"
+    update.effective_chat.id = 100
+    update.effective_user = MagicMock()
+    context = MagicMock()
+
+    with patch("duty_teller.handlers.group_duty_pin.get_lang", return_value="en"):
+        with patch.object(
+            mod, "_refresh_pin_for_chat", AsyncMock(return_value="no_message")
+        ):
+            with patch("duty_teller.handlers.group_duty_pin.t") as mock_t:
+                mock_t.return_value = "No message"
+                await mod.refresh_pin_cmd(update, context)
+    update.message.reply_text.assert_called_once_with("No message")
+    mock_t.assert_called_with("en", "refresh_pin.no_message")
+
+
+@pytest.mark.asyncio
+async def test_refresh_pin_cmd_group_edit_raises_replies_failed():
+    """refresh_pin_cmd: _refresh_pin_for_chat returns failed (e.g. BadRequest) -> reply refresh_pin.failed."""
+    update = MagicMock()
+    update.message = MagicMock()
+    update.message.reply_text = AsyncMock()
+    update.effective_chat = MagicMock()
+    update.effective_chat.type = "group"
+    update.effective_chat.id = 100
+    update.effective_user = MagicMock()
+    context = MagicMock()
+
+    with patch("duty_teller.handlers.group_duty_pin.get_lang", return_value="en"):
+        with patch.object(
+            mod, "_refresh_pin_for_chat", AsyncMock(return_value="failed")
+        ):
+            with patch("duty_teller.handlers.group_duty_pin.t") as mock_t:
+                mock_t.return_value = "Failed"
+                await mod.refresh_pin_cmd(update, context)
+    update.message.reply_text.assert_called_once_with("Failed")
+    mock_t.assert_called_with("en", "refresh_pin.failed")
+
+
 # --- my_chat_member_handler ---


--- a/tests/test_personal_calendar_ics.py
+++ b/tests/test_personal_calendar_ics.py
@@ -46,7 +46,7 @@ def test_build_personal_ics_one_duty():


 def test_build_team_ics_vevent_has_description_with_full_name():
-    """Team ICS VEVENT includes DESCRIPTION with the duty holder's full_name."""
+    """Team ICS VEVENT has SUMMARY=full_name and DESCRIPTION=full_name."""
    duties = [
        _duty(1, "2025-02-20T09:00:00Z", "2025-02-20T18:00:00Z", "duty"),
    ]
@@ -56,11 +56,28 @@ def test_build_team_ics_vevent_has_description_with_full_name():
    events = [c for c in cal.walk() if c.name == "VEVENT"]
    assert len(events) == 1
    ev = events[0]
-    assert ev.get("summary") == "Duty"
+    assert ev.get("summary") == "Test User"
    assert ev.get("description") == "Test User"
    assert b"Team Calendar" in ics or "Team Calendar" in ics.decode("utf-8")


+def test_build_team_ics_empty_full_name_summary_fallback():
+    """When full_name is empty or missing, SUMMARY is 'Duty'."""
+    duty_ns = SimpleNamespace(
+        id=1,
+        start_at="2025-02-20T09:00:00Z",
+        end_at="2025-02-20T18:00:00Z",
+        event_type="duty",
+    )
+    for empty_name in ("", "   ", None):
+        duties = [(duty_ns, empty_name)]
+        ics = build_team_ics(duties)
+        cal = ICalendar.from_ical(ics)
+        events = [c for c in cal.walk() if c.name == "VEVENT"]
+        assert len(events) == 1
+        assert events[0].get("summary") == "Duty"
+
+
 def test_build_personal_ics_event_types():
    """Unavailable and vacation get correct SUMMARY."""
    duties = [