Files

Nikolay Tatarinov fa22976e75 feat: enhance Mini App design guidelines and refactor layout components

- Updated Mini App design guidelines to include detailed instructions on UI changes, accessibility rules, and verification processes.
- Refactored multiple components to utilize `MiniAppScreen` and `MiniAppScreenContent` for consistent layout structure across the application.
- Improved error handling in `GlobalError` and `NotFound` components by integrating new layout components for better user experience.
- Introduced new hooks for admin functionality, streamlining access checks and data loading processes.
- Enhanced documentation to reflect changes in design policies and component usage, ensuring clarity for future development.

2026-03-06 17:51:33 +03:00

4.1 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), Next.js (static export) Mini App. 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-next/` (Next.js, Tailwind, shadcn/ui; static export in `webapp-next/out/`)
Admin panel (Mini App)	`webapp-next/src/app/admin/page.tsx`; API: `GET /api/admin/me`, `GET /api/admin/users`, `PATCH /api/admin/duties/:id`
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. Frontend: cd webapp-next && npm test && npm run build.
Lint: ruff check duty_teller tests
Security: bandit -r duty_teller -ll

Documentation

User and architecture docs: docs/, docs/architecture.md.
Mini App design guideline — Theme, layout, safe areas, component patterns, accessibility for webapp-next.
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.
Mini App (webapp-next): When adding or changing UI in webapp-next/, follow the Mini App design guideline: use only design tokens and Tailwind aliases, use shared Mini App screen shells, keep Telegram SDK access behind src/hooks/telegram/*, apply safe-area/content-safe-area and accessibility rules, and run the Mini App verification matrix (light/dark, iOS/Android safe area, low-perf Android, deep links, admin flow, fallback states).
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.

4.1 KiB Raw Blame History