# Local setup

This fork adds a local Ant Design Pro admin panel, Telegram private management,
Mongo-backed giveaways, and per-chat points 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.

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 <user> <amount> <reason>
/points_deduct <user> <amount> <reason>
/points_set <user> <balance> <reason>
/points_toggle <enable|disable>
```

Giveaway commands:

```text
/giveaway 1h | First:1:50, Second:3:10 | Launch | Description | 20 | 5 | 2
/gjoin <id>
/glist
/gparticipants <id>
/gend <id>
/gcancel <id>
/greroll <id> [tier]
/gremove <id> <user_id> [no-refund]
/gban <user> [reason]
/gunban <user>
```

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.

## 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.