# Local setup This fork adds a local Ant Design Pro admin panel, Telegram private management, Mongo-backed giveaways, per-chat points, and a cross-Bot teacher directory to WilliamButcherBot. ## Requirements - Python 3.12 and `uv` - Node.js 20 or newer - MongoDB 7, or Docker with Docker Compose - One or more Telegram bot tokens, an API ID/API hash, and a test group Bot credentials are managed in the web panel. Sensitive values are stored in `runtime/bot_profiles.json` with mode `0600` and are never returned by the API. Each enabled Bot runs in its own process and uses an isolated MongoDB database; the Web administrator account and sessions remain in the shared control database. ## Configure ```console cp config.env.template config.env ``` The environment file now contains only process-level settings. Set at least: - `MONGO_URL` - Optional admin bind, session, and upload settings After login, open **System settings** and configure the shared Telegram API ID and API Hash. Add any number of Bot profiles; every profile has its own Token, SUDOERS, log groups, media relay group, Pyrogram session, and worker process. Enabled profiles start automatically as soon as the shared API credentials are complete. Token testing uses Telegram's official `getMe` endpoint. ### Telegram Business intelligent reception For each Bot that should handle account chats: 1. Open BotFather, choose the Bot, enter **Bot Settings**, and enable **Business Mode**. Test the Token again in **System settings**; the result must report Business Connection support. 2. Assign the built-in **Intelligent reception specialist** role, or grant `business_assistant.manage` through a custom role. 3. Open **Intelligent reception**, configure an OpenAI-compatible Base URL ending at the API root (for example `https://models.example.com/v1`), API Key, model, timeout, and output limit. Saving this configuration restarts only the selected Bot worker. 4. On the Telegram account that will be represented, open **Settings → Telegram Business / Chat Automation → Chatbots**, connect the Bot, and select the chats it may access. This account-side authorization cannot be automated by the server. 5. Return to **Intelligent reception**, select the connection, create its FAQ entries, choose notification destinations, and enable automatic reception. The account must be eligible for Telegram Business/Chatbots in the official client. Each connection has independent settings, FAQ entries, conversations, daily limits, timezone, and digest schedule. Default limits are 200 AI calls per connection per day and 20 per customer per day. Original messages expire after 30 days; summaries and follow-up state remain until an administrator clears the conversation. The runtime refuses to poll when a webhook is configured, ignores Telegram's native greeting/away messages and messages sent by the Business Bot itself, and never sends outside the official 24-hour reply window. A manual reply by the connected account pauses automation for 24 hours by default. Explicit handoffs remain paused until an authorized owner, operations-group admin, or Web administrator resumes them. The admin panel defaults are: - Address: `http://127.0.0.1:8088/admin` - Username: `admin` - Initial password: `qwe0.123456` The initial password is only used to create the first admin record. The first login must change it. Later changes to the environment value do not overwrite an existing password hash. ## Run with Docker Compose ```console docker compose up --build ``` The container listens on `0.0.0.0:8088`, while Compose publishes it only at `127.0.0.1:8088`. MongoDB is not exposed to the host. Bot profiles persist in the bind-mounted `runtime/` directory. ## Run from the workspace ```console uv sync --python 3.12 cd admin-web npm ci npm run build cd .. uv run python launcher.py ``` For frontend development, keep the bot/API on port 8088 and run: ```console cd admin-web npm run dev ``` Umi runs on port 8090 and proxies `/api/admin/*` to the Python service. The launcher keeps the control panel on port 8088 and starts one internal worker per enabled Bot. The Bot selector in the header routes group operations to the selected worker. ## Telegram commands User points commands: ```text /points /checkin /points_rank /points_history ``` Administrator points commands: ```text /points_add /points_deduct /points_set /points_toggle ``` Giveaway commands: ```text /giveaway 1h | First:1:50, Second:3:10 | Launch | Description | 20 | 5 | 2 /gjoin /glist /gparticipants /gend /gcancel /greroll [tier] /gremove [no-refund] /gban [reason] /gunban ``` Private administration: ```text /manage [chat_id] /cancel ``` Private menu flows expire after ten minutes. Every action rechecks the operator's current Telegram permissions; `SUDOERS` can manage all known groups. Teacher directory: ```text /directory /nearby /teacher_rank /teacher_apply /teacher_list /teacher_unlist /teacher_online /teacher_offline ``` Assign the **Teacher directory manager** role to every Bot that should expose these commands. Teacher identity, location, listing, and presence are global across all configured Bots. A user must first run `/directory` in a managed group so the supervisor can perform a live membership check. Open **Teacher directory** in the Web panel to review applications and configure OpenStreetMap Nominatim. Public Nominatim reverse geocoding remains disabled until a contact email or URL is configured. It is globally limited to one request per second, cached, and only receives coordinates after the user accepts the Telegram privacy prompt. Distance search continues to work when Nominatim is disabled or unavailable. ## Verification ```console uv run ruff check wbb tests sample_config.py uv run python -m compileall -q wbb uv run pytest cd admin-web npm ci npm run typecheck npm test npm run build cd .. docker compose config ``` Ruff is scoped in `pyproject.toml` to this fork's new and modified feature modules; the untouched upstream bot still has its pre-existing lint backlog. Real Telegram group acceptance still requires API ID/API Hash and a disposable test group. Do not use a production group for the first run.