Files

CI / lint-and-test (push) Failing after 27s

Details

feat: enhance error handling and configuration validation

- Added a global exception handler to log unhandled exceptions and return a generic 500 JSON response without exposing details to the client.
- Updated the configuration to validate the `DATABASE_URL` format, ensuring it starts with `sqlite://` or `postgresql://`, and log warnings for invalid formats.
- Introduced safe parsing for numeric environment variables (`HTTP_PORT`, `INIT_DATA_MAX_AGE_SECONDS`) with defaults on invalid values, including logging warnings for out-of-range values.
- Enhanced the duty schedule parser to enforce limits on the number of schedule rows and the length of full names and duty strings, raising appropriate errors when exceeded.
- Updated internationalization messages to include generic error responses for import failures and parsing issues, improving user experience.
- Added unit tests to verify the new error handling and configuration validation behaviors.

2026-03-02 23:36:03 +03:00

3.2 KiB

Raw Blame History

Duty Teller — AI agent documentation

This file is for AI assistants (e.g. Cursor) and maintainers. All project documentation and docstrings must be in English. User-facing UI strings remain localized (ru/en) in duty_teller/i18n/.

Project summary

Duty Teller is a Telegram bot plus Mini App for team duty shift calendar and group reminders. Stack: python-telegram-bot v22, FastAPI, SQLite (SQLAlchemy), Vanilla JS webapp. The bot and web UI support Russian and English; configuration and docs are in English.

Key entry points

CLI / process: main.py or, after pip install -e ., the duty-teller console command. Both delegate to duty_teller.run.main().
Application setup: duty_teller/run.py — builds the Telegram Application, registers handlers via register_handlers(app), runs polling and FastAPI in a thread, calls config.require_bot_token() so the app exits clearly if BOT_TOKEN is missing.
HTTP API: duty_teller/api/app.py — FastAPI app, route registration, static webapp mounted at /app.

Where to change what

Area	Location
Telegram handlers	`duty_teller/handlers/`
REST API	`duty_teller/api/`
Business logic	`duty_teller/services/`
Database (models, repository, schemas)	`duty_teller/db/`
Translations (ru/en)	`duty_teller/i18n/`
Duty-schedule parser	`duty_teller/importers/`
Config (env vars)	`duty_teller/config.py`
Miniapp frontend	`webapp/`
Migrations	`alembic/` (config in `pyproject.toml` under `[tool.alembic]`)

Running and testing

Tests: From repository root: pytest. Use PYTHONPATH=. if imports fail. See CONTRIBUTING.md and README.md for full setup.
Lint: ruff check duty_teller tests
Security: bandit -r duty_teller -ll

Documentation

User and architecture docs: docs/, docs/architecture.md.
Configuration reference: docs/configuration.md.
Build docs: pip install -e ".[docs]", then mkdocs build / mkdocs serve.

Docstrings and code comments must be in English (Google-style docstrings). UI strings are the only exception; they live in duty_teller/i18n/.

Conventions

Commits: Conventional Commits (e.g. feat:, fix:, docs:).
Branches: Gitea Flow; changes via Pull Request.
Testing: pytest, 80% coverage target; unit and integration tests.
Config: Environment variables (e.g. .env); no hardcoded secrets.
Database: One logical transaction per session_scope — a single commit at the end of the business operation (e.g. in run_import). Repository helpers used inside such a flow (e.g. get_or_create_user_by_full_name) accept commit=False and let the caller commit once.
Error handling: Do not send str(exception) from parsers or DB to the user. Use generic i18n keys (e.g. import.parse_error_generic, import.import_error_generic) and log the full exception server-side.
Cursor: The project does not version .cursor/. You can mirror this file in .cursor/rules/ locally; AGENTS.md is the single versioned reference for AI and maintainers.

3.2 KiB Raw Blame History