cm_bot_v2/AGENTS.md

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:

   git clone <repo-url> cm_bot_v2
   cd cm_bot_v2
   

3. Create .env at repo root for compose interpolation:

   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):

   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:

   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:

   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:

  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.
• CM_DEBUG defaults to false for both Flask services. Set it to true only in local development; rex/siong production env files must leave it unset (the Werkzeug debugger is RCE if reachable).
• 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.