feat(whatsapp): make linked-device QR mode first-class and compatible

[liuxiaopai-ai]

Summary

This PR makes WhatsApp linked-devices QR mode a first-class, reliable path while preserving existing Cloud API behavior and compatibility with older configs.

Closes #23

What changed

1) First-class WhatsApp mode model (with compatibility)

• Added WhatsAppMode enum (auto, web_qr, cloud_api) in openfang-types.
• Added mode to WhatsAppConfig (default auto).
• Added gateway_url support and explicit gateway URL resolution helper.
• Added legacy compatibility for phone_number_id_env (older generated configs keep working).
• Added resolved_gateway_url() / resolved_phone_number_id() helpers used by runtime logic.

2) Bridge selection logic made explicit and testable

• openfang-api/channel_bridge now chooses WhatsApp runtime path via explicit mode-aware selection:
  • web_qr => gateway route
  • cloud_api => Cloud API route (requires token + phone ID)
  • auto => prefer gateway, fallback to Cloud API when properly configured
• Added focused unit tests for delivery mode selection matrix.

3) QR API endpoints now use live config resolution

• /api/channels/whatsapp/qr/start and /status now resolve gateway URL from live channel config (channels.whatsapp) + env fallback.
• Better setup/error guidance in API responses.

4) Channel configure defaults for WhatsApp

• configure_channel now defaults WhatsApp to:
  • mode = "web_qr" for QR-first setups
  • mode = "cloud_api" when cloud fields are provided
• Ensures saved config matches the user’s actual setup path.

5) CLI/setup mismatch fixes that blocked adoption

• openfang channel setup whatsapp now supports both:
  • Linked Devices QR (recommended)
  • Cloud API
• Fixed wrong legacy env names (WA_*) in setup outputs; now uses WHATSAPP_* defaults consistently.
• Updated channel list env mapping (MATRIX_ACCESS_TOKEN; WhatsApp no longer incorrectly hard-fails on a single env var in QR mode).

6) Docs updated to match implementation

• docs/channel-adapters.md: clear split between web_qr and cloud_api modes; updated examples.
• docs/configuration.md: updated WhatsApp config schema, mode semantics, env var table, and validation expectations.

Tests / verification

Ran locally in this branch:

• ~/.cargo/bin/cargo test -p openfang-types --lib
• ~/.cargo/bin/cargo test -p openfang-api channel_bridge::tests -- --nocapture
• ~/.cargo/bin/cargo check -p openfang-cli
• ~/.cargo/bin/cargo clippy -p openfang-types --lib --tests -- -D warnings
• ~/.cargo/bin/cargo clippy -p openfang-api --lib --tests -- -D warnings
• ~/.cargo/bin/cargo clippy -p openfang-cli --bin openfang (existing warning-only clippy findings outside this PR’s scope)

All targeted tests/checks pass; clippy hard-fail warnings are clean for touched API/types crates.

Risk notes

• Runtime behavior is now mode-driven for WhatsApp, which is intentional and more explicit.
• auto mode preserves backwards behavior by preferring gateway when available and falling back to Cloud API if fully configured.
• Legacy phone_number_id_env is still accepted to avoid breaking older generated configs.