feat: implement role-based access control for miniapp

- Introduced a new roles table in the database to manage user roles ('user' and 'admin') for access control.
- Updated the user model to include a foreign key reference to the roles table, allowing for role assignment.
- Enhanced command handlers to support the `/set_role` command for admins to assign roles to users.
- Refactored access control logic to utilize role checks instead of username/phone allowlists, improving security and maintainability.
- Updated documentation to reflect changes in access control mechanisms and role management.
- Added unit tests to ensure correct functionality of role assignment and access checks.

docs/configuration.md

@@ -8,10 +8,10 @@ All configuration is read from the environment (e.g. `.env` via python-dotenv).
 | **DATABASE_URL** | string (SQLAlchemy URL) | `sqlite:///data/duty_teller.db` | Database connection URL. Example: `sqlite:///data/duty_teller.db`. |
 | **MINI_APP_BASE_URL** | string (URL, no trailing slash) | *(empty)* | Base URL of the miniapp (for documentation and CORS). Trailing slash is stripped. Example: `https://your-domain.com/app`. |
 | **HTTP_PORT** | integer | `8080` | Port for the HTTP server (FastAPI + static webapp). |
-| **ALLOWED_USERNAMES** | comma-separated list | *(empty)* | Telegram usernames allowed to open the calendar miniapp (without `@`; case-insensitive). If both this and `ADMIN_USERNAMES` are empty, no one can open the calendar. Example: `alice,bob`. |
-| **ADMIN_USERNAMES** | comma-separated list | *(empty)* | Telegram usernames with admin role (access to miniapp + `/import_duty_schedule` and future admin features). Example: `admin1,admin2`. |
-| **ALLOWED_PHONES** | comma-separated list | *(empty)* | Phone numbers allowed to access the miniapp (user sets via `/set_phone`). Comparison uses digits only (spaces, `+`, parentheses, dashes ignored). Example: `+7 999 123-45-67,89001234567`. |
-| **ADMIN_PHONES** | comma-separated list | *(empty)* | Phone numbers with admin role; same format as `ALLOWED_PHONES`. |
+| **ALLOWED_USERNAMES** | comma-separated list | *(empty)* | **Not used for access.** Kept for reference only. Access to the miniapp is controlled by **roles in the DB** (assigned by an admin via `/set_role`). |
+| **ADMIN_USERNAMES** | comma-separated list | *(empty)* | Telegram usernames treated as **admin fallback** when the user has **no role in the DB**. If a user has a role in the DB, only that role applies. Example: `admin1,admin2`. |
+| **ALLOWED_PHONES** | comma-separated list | *(empty)* | **Not used for access.** Kept for reference only. |
+| **ADMIN_PHONES** | comma-separated list | *(empty)* | Phones treated as **admin fallback** when the user has **no role in the DB** (user sets phone via `/set_phone`). Comparison uses digits only. Example: `+7 999 123-45-67`. |
 | **MINI_APP_SKIP_AUTH** | `1`, `true`, or `yes` | *(unset)* | If set, `/api/duties` is allowed without Telegram initData (dev only; insecure). |
 | **INIT_DATA_MAX_AGE_SECONDS** | integer | `0` | Reject Telegram initData older than this many seconds. `0` = disabled. Example: `86400` for 24 hours. |
 | **CORS_ORIGINS** | comma-separated list | `*` | Allowed origins for CORS. Leave unset or set to `*` for allow-all. Example: `https://your-domain.com`. |
@@ -19,11 +19,15 @@ All configuration is read from the environment (e.g. `.env` via python-dotenv).
 | **DUTY_DISPLAY_TZ** | string (timezone name) | `Europe/Moscow` | Timezone for the pinned duty message in groups. Example: `Europe/Moscow`, `UTC`. |
 | **DEFAULT_LANGUAGE** | `en` or `ru` (normalized) | `en` | Default UI language when the user's Telegram language is unknown. Values starting with `ru` are normalized to `ru`, otherwise `en`. |
 
+## Roles and access
+
+Access to the calendar miniapp and admin actions is determined by **roles stored in the database** (table `roles`, link `users.role_id`). Roles: `user` (miniapp access) and `admin` (miniapp + `/import_duty_schedule`, `/set_role`). An admin assigns roles with **`/set_role @username user|admin`** (or by replying to a message with `/set_role user|admin`). If a user has **no role in the DB**, they are treated as admin only if they are listed in **ADMIN_USERNAMES** or **ADMIN_PHONES** (env fallback). `ALLOWED_USERNAMES` and `ALLOWED_PHONES` are not used for access.
+
 ## Quick setup
 
 1. Copy `.env.example` to `.env`.
 2. Set `BOT_TOKEN` to the token from BotFather.
-3. For miniapp access, set `ALLOWED_USERNAMES` and/or `ADMIN_USERNAMES` (and optionally `ALLOWED_PHONES` / `ADMIN_PHONES`).
+3. Set `ADMIN_USERNAMES` (and optionally `ADMIN_PHONES`) so that at least one admin can use the bot and assign roles via `/set_role`.
 
 For Mini App URL and production deployment notes (reverse proxy, initData), see the [README](../README.md) Setup and Docker sections.