Nikolay Tatarinov
fa22976e75
- 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.
55 lines
4.1 KiB
Markdown
55 lines
4.1 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), 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](CONTRIBUTING.md) and [README.md](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/), [docs/architecture.md](docs/architecture.md).
|
|
- [Mini App design guideline](docs/miniapp-design.md) — Theme, layout, safe areas, component patterns, accessibility for webapp-next.
|
|
- 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.
|
|
- **Mini App (webapp-next):** When adding or changing UI in `webapp-next/`, follow the [Mini App design guideline](docs/miniapp-design.md): 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](AGENTS.md) is the single versioned reference for AI and maintainers.
|