docs: justify phone_collector as aiogram-dialog migration exception (#2055)#2075
Open
yastman wants to merge 1 commit into
Open
docs: justify phone_collector as aiogram-dialog migration exception (#2055)#2075yastman wants to merge 1 commit into
yastman wants to merge 1 commit into
Conversation
…2055) Parent: #1232 (Replace custom aiogram FSM with aiogram-dialog). Per the issue body, CRM quick actions (#2053) and the demo handler (#2054) are migrating to aiogram-dialog, but the phone collector should stay on raw aiogram Router + FSMContext. Reason: - Telegram lead capture uses KeyboardButton(request_contact=True) inside ReplyKeyboardMarkup. One tap sends a verified Contact payload. - aiogram-dialog renders inline-keyboard Select/Button widgets and does NOT provide a request_contact widget. - A forced migration would replace one-tap contact share with manual phone typing, measurably reducing opt-in rate for lead capture. The exception is now documented in two places: 1. telegram_bot/handlers/phone_collector.py — module docstring expands from a single-line '#628' note into a full design-exception block that names #1232 and #2055, lists the trade-off, and tells future readers when the exception can be dropped (product accepts weaker UX or aiogram-dialog ships a contact-share widget). 2. docs/engineering/sdk-registry.md — adds a new bullet at the end of the aiogram-dialog gotchas section calling out phone_collector as the SINGLE intentional exception to the 'no custom FSM' rule, with cross-references to #2053 and #2054. This closes the documentation deliverable from #2055; the actual code of phone_collector.py is intentionally unchanged. Verification: uv run python -c 'from telegram_bot.handlers import phone_collector' OK uv run pytest tests/unit/handlers/test_phone_collector.py tests/unit/handlers/test_phone_crm_integration.py -q 47 passed uv run python scripts/check_markdown_links.py All relative Markdown links OK. uvx ruff check telegram_bot/handlers/phone_collector.py All checks passed! Closes #2055
This was referenced May 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request was created by @kiro-agent on behalf of @yastman 👻
Comment with /kiro fix to address specific feedback or /kiro all to address everything.
Learn about Kiro autonomous agent
Summary
Per the issue body, CRM quick actions (#2053) and the demo handler (#2054) are migrating to aiogram-dialog, but
phone_collectorshould stay on raw aiogramRouter+FSMContext. Reason:KeyboardButton(request_contact=True)insideReplyKeyboardMarkup. One tap sends a verifiedContactpayload.Select/Buttonwidgets and does not provide arequest_contactwidget.This PR makes the exception explicit in two places, so a future reader doing a "consistency refactor" doesn't accidentally weaken the UX.
Changes
telegram_bot/handlers/phone_collector.py— module docstring expanded from a single-line#628note into a full design-exception block referencing Replace custom aiogram FSM with aiogram-dialog (crm_callbacks, phone_collector, demo_handler) #1232 and dialog: document phone collector as justified FSM/router exception (#1232) #2055, with the explicit trade-off and a "drop this exception when..." condition.docs/engineering/sdk-registry.md— new bullet at the end of the aiogram-dialog gotchas section calling outphone_collectoras the single intentional exception, with cross-references to dialog: migrate CRM quick actions to aiogram-dialog MessageInput + Select (#1232) #2053 and dialog: fold demo handler query input into catalog dialog (#1232) #2054.This is a docs-only PR — no behaviour change in
phone_collector.py.Verification
Closes #2055
Parent: #1232