Nikolay Tatarinov
7ffa727832
Some checks failed
CI / lint-and-test (push) Failing after 27s
- 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.
52 lines
3.2 KiB
Markdown
52 lines
3.2 KiB
Markdown
# 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](CONTRIBUTING.md) and [README.md](README.md) for full setup.
|
|
- **Lint:** `ruff check duty_teller tests`
|
|
- **Security:** `bandit -r duty_teller -ll`
|
|
|
|
## Documentation
|
|
|
|
- User and architecture docs: [docs/](docs/), [docs/architecture.md](docs/architecture.md).
|
|
- Configuration reference: [docs/configuration.md](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](https://www.conventionalcommits.org/) (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](AGENTS.md) is the single versioned reference for AI and maintainers.
|