yiekheng/cm_bot_v2
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
cm_bot_v2/AGENTS.md
yiekheng ebccad2094 B4 cutover: retire Flask cm-web, rename cm-web-next → cm-web 
End-state: a single web service (Next.js dashboard) per deployment, no
side-by-side Flask UI. The image name 'cm-web' now points at the Next.js
build; the legacy 'cm-web-next' tag is no longer published.

Changes:
- Delete app/cm_web_view.py and the Flask docker/web/Dockerfile.
- Rename docker/web-next/ → docker/web/ (Next.js Dockerfile takes the
  cm-web slot).
- docker-compose.yml: drop the web-view service. Rename web-next → web,
  container ${CM_DEPLOY_NAME}-web-next → ${CM_DEPLOY_NAME}-web, image
  cm-web-next → cm-web, named volume web-next-auth-data → web-auth-data.
  transfer-bot's depends_on no longer references web-view (vestigial
  startup ordering, never a runtime dependency).
- docker-compose.override.yml: same rename, dockerfile path updated.
- envs: drop CM_WEB_NEXT_HOST_PORT. Repurpose CM_WEB_HOST_PORT for the
  Next.js port (8010 dev, 8011 rex, 8012 siong) — same numeric values
  formerly held by CM_WEB_NEXT_HOST_PORT, so aaPanel routes don't move.
- scripts/dev.sh: drops web-view + web-next from up/reset-db/logs;
  --remove-orphans still cleans up legacy containers from before cutover.
- scripts/publish.sh: drop the cm-web-next build target.
- tests/test_debug_enabled.py: drop app.cm_web_view from the helper
  matrix (cm_api is now the only Flask entrypoint with _debug_enabled).
- AGENTS.md / README.md / docs/aapanel-hardening.md: rewrite Flask-era
  references; add migration steps for existing stacks; update aaPanel
  port references (8000/8001/8005 → 8010/8011/8012).
- .gitignore: add .env, .venv/, .playwright-mcp/, node_modules/, .next/
  so 'git add -A' can't accidentally stage secrets or build artifacts.

Operator action required to upgrade an existing deployment:
  1. .env: drop CM_WEB_NEXT_HOST_PORT line. Set CM_WEB_HOST_PORT to
     what CM_WEB_NEXT_HOST_PORT was. Make sure CM_AUTH_SECRET is set.
  2. aaPanel: if proxy_pass pointed at the legacy Flask port
     (8000/8001/8005), switch it to the new one (8010/8011/8012).
  3. Pull the new cm-web image (Next.js) and redeploy the stack. The
     old ${CM_DEPLOY_NAME}-web-view and ${CM_DEPLOY_NAME}-web-next
     containers will be replaced by a single ${CM_DEPLOY_NAME}-web.

Verified locally: docker-compose YAML parses; transfer-bot runtime is
unchanged (only depends_on tidied); 38-test python suite passes.
2026-05-03 10:12:20 +08:00

107 lines
6.2 KiB
Markdown
Raw Blame History

# Repository Guidelines
## Project Structure & Module Organization
- `app/` contains service modules:
- `cm_api.py` (Flask API, serves on `3000`)
- `cm_telegram.py` (Telegram bot + account monitor thread)
- `cm_transfer_credit.py` (scheduled transfer worker)
- `db.py` (MySQL connection/retry logic)
- `web/` is the Next.js 15 dashboard (`cm-web` service, container port `3000`, host `CM_WEB_HOST_PORT`). Tailwind v4, App Router, TypeScript. Replaced the legacy Flask `app/cm_web_view.py` in the B4 cutover.
- `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 the local dev DB and stack:
```bash
cp envs/dev/.env.example .env
# Edit .env if you want the bot CLI to actually call cm99.net
# (CM_AGENT_ID / CM_AGENT_PASSWORD / CM_SECURITY_PIN).
bash scripts/dev.sh up
```
This brings up `mysql` (port `127.0.0.1:3306`), `api-server`, and
`web` (Next.js dashboard). The schema and a 4-row seed are applied
automatically from `docker/mysql/init.d/`. Bots (`telegram-bot`,
`transfer-bot`) are gated behind a compose `bots` profile and do not
start in dev.
## Auth
- The Next.js dashboard (`cm-web`) gates every route except `/cm-auth` behind a session cookie.
- **Password sign-in** uses `CM_AGENT_ID` and `CM_AGENT_PASSWORD` from the deployment's `.env` (constant-time compare). No separate user table.
- **WebAuthn passkey** sign-in is the preferred path on devices with platform authenticators (Face ID, Touch ID, Android fingerprint). Enroll one at `/cm-passkeys` after the first password login.
- Session: signed `httpOnly` cookie (`cm_auth`), 30-day rolling. Requires `CM_AUTH_SECRET` env var (≥32 chars). Generate with `bash scripts/gen_auth_secret.sh --write`.
- Passkey storage: `/data/auth/passkeys.json` inside the container, mounted from the `${CM_DEPLOY_NAME}-web-auth-data` named volume. Atomic writes; persists across container restarts and image rebuilds.
- "Forgot password" recovery: contact whoever holds the deployment's `.env`. There's no email reset flow.
- Rotating `CM_AUTH_SECRET` invalidates all sessions (forces everyone to re-login).
- The `Secure` cookie attribute is gated on `CM_DEBUG`: `CM_DEBUG=true` drops `Secure` so phone-on-LAN testing over plain HTTP works in dev. Production must keep `CM_DEBUG=false` so the cookie only flies over HTTPS.
## Dev Tier (Local Development)
- Lifecycle: `bash scripts/dev.sh {up,down,reset-db,logs,status}`.
- URL: `http://localhost:8010/` (Next.js dashboard).
- Bot CLI: `bash scripts/bot_cli.sh` (drops into the TUI menu) or
`bash scripts/bot_cli.sh <subcommand>` (e.g., `register`, `set-pin <link>`,
`monitor-once --target 5`). The CLI runs in your local `.venv` and
connects to the dev mysql at `127.0.0.1:3306`.
- The auto-create monitor does NOT run in dev (it lives in `telegram-bot`,
which is gated by the `bots` profile). Use `bot_cli.sh monitor-once` to
exercise the same code path manually.
- Tests: `.venv/bin/python -m unittest tests.test_debug_enabled tests.test_bot_cli -v`.
## 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 (only reachable inside the docker network — exec into a service): `docker compose exec web wget -qO- http://api-server:3000/acc/`
- Web UI loads: open `http://localhost:8010` (dev) or `http://localhost:8011` (rex prod) / `http://localhost:8012` (siong prod). Unauthenticated requests bounce to `/cm-auth`.
- Service logs are clean:
```bash
docker compose logs -f api-server web 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 `web/` changed).
## Security & Configuration Tips
- Never commit real secrets in `.env`.
- `CM_DEBUG` defaults to `false` for `api-server`. Set it to `true` only in local development; rex/siong production env files must leave it unset (the Werkzeug debugger is RCE if reachable). The Next.js `web` service also reads `CM_DEBUG` to decide whether the session cookie carries the `Secure` flag — keep it `false` in production so the cookie is HTTPS-only.
- Keep container clocks mounted (`/etc/timezone`, `/etc/localtime`) as compose currently defines to avoid schedule drift.
Reference in New Issue View Git Blame Copy Permalink