# Repository Guidelines

## Project Structure & Module Organization
- `app/` contains service modules:
  - `cm_api.py` (Flask API, serves on `3000`)
  - `cm_web_view.py` (Flask UI, container `8000`, host `8001`)
  - `cm_telegram.py` (Telegram bot + account monitor thread)
  - `cm_transfer_credit.py` (scheduled transfer worker)
  - `db.py` (MySQL connection/retry logic)
- `docker/<service>/Dockerfile` builds one image per service (`cm-api`, `cm-web`, `cm-telegram`, `cm-transfer`).
- `docker-compose.yml` uses registry images; `docker-compose.override.yml` swaps to local builds.
- `scripts/local_build.sh` starts local compose; `scripts/publish.sh` builds and pushes all images via buildx.

## Reproduce From Scratch (Clean Machine)
1. Install prerequisites:
   - Docker Engine + Docker Compose v2
   - MySQL 8+ reachable by containers
   - Telegram bot token(s) for bot and optional alerting
2. Clone and enter repo:
   ```bash
   git clone <repo-url> cm_bot_v2
   cd cm_bot_v2
   ```
3. Create `.env` at repo root for compose interpolation:
   ```bash
   CM_IMAGE_PREFIX=local
   DOCKER_IMAGE_TAG=dev
   TELEGRAM_BOT_TOKEN=<required>
   TELEGRAM_ALERT_CHAT_ID=<optional>
   TELEGRAM_ALERT_BOT_TOKEN=<optional>
   CM_TRANSFER_MAX_THREADS=1
   ```
4. Prepare MySQL schema (minimum required):
   ```sql
   CREATE DATABASE rex_cm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   USE rex_cm;

   CREATE TABLE acc (
     username VARCHAR(64) PRIMARY KEY,
     password VARCHAR(128) NOT NULL,
     status   VARCHAR(32) DEFAULT '',
     link     VARCHAR(512) DEFAULT ''
   );

   CREATE TABLE user (
     f_username       VARCHAR(64) PRIMARY KEY,
     f_password       VARCHAR(128) NOT NULL,
     t_username       VARCHAR(64) NOT NULL,
     t_password       VARCHAR(128) NOT NULL,
     last_update_time TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
   );
   ```
5. Seed at least one `acc.username` matching prefix `13c...` (required by `CM_BOT_HAL.get_next_username()`), for example:
   ```sql
   INSERT INTO acc (username, password, status, link) VALUES ('13c1000', 'seed', '', '');
   ```
6. Configure DB connection values:
   - Default fallback is hardcoded in `app/db.py` (`DB_HOST=192.168.0.210`, etc.).
   - For reliable reproduction, add `DB_HOST`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `DB_PORT` to service `environment:` in compose files (at minimum `api-server`, `telegram-bot`, `transfer-bot`).
7. Start services locally:
   ```bash
   docker compose -f docker-compose.yml -f docker-compose.override.yml up --build
   ```
   Or run `bash scripts/local_build.sh` (uses `sudo` by default).

## Build, Test, and Development Commands
- `python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt`: optional non-Docker local env.
- `docker compose -f docker-compose.yml -f docker-compose.override.yml up --build`: local dev stack.
- `docker compose up -d`: run prebuilt/published images.
- `bash scripts/publish.sh <tag>`: build + push all service images (`gitea.04080616.xyz/yiekheng`).

## Verification Checklist
- API responds: `curl http://localhost:3000/acc/`
- Web UI loads: open `http://localhost:8001`
- Service logs are clean:
  ```bash
  docker compose logs -f api-server web-view telegram-bot transfer-bot
  ```
- Telegram bot validates with `/menu` and `/9` in chat after startup.

## Coding Style & Naming Conventions
- Python 3.9, 4-space indentation, snake_case for variables/functions, module names as `cm_<role>.py`.
- Preserve existing class names (`CM_API`, `CM_BOT`, `CM_BOT_HAL`).
- Keep environment variable names uppercase and document new ones in this file.
- No enforced formatter/linter in-repo; match the surrounding style in touched files.

## Testing Guidelines
- No automated test suite is currently committed.
- Required minimum before PR: run verification checklist above on local compose.
- For logic-heavy changes, add `pytest` tests under `tests/` and include execution command/results in PR.

## Commit & Pull Request Guidelines
- Use short, focused commit subjects in imperative tone (existing history: `Fix ...`, `Update ...`, `Refactor ...`).
- Keep each commit scoped to one behavior change.
- PR must include:
  - problem statement and solution summary,
  - services/files affected,
  - required env/config changes,
  - API/log evidence (and UI screenshot if `cm_web_view.py` changed).

## Security & Configuration Tips
- Never commit real secrets in `.env`.
- `app/cm_bot_hal.py` currently contains hardcoded agent credentials/pin; move these to env vars before production use.
- Keep container clocks mounted (`/etc/timezone`, `/etc/localtime`) as compose currently defines to avoid schedule drift.