# 本地调试说明

## 1. 启动开发环境

```bash
./run-dev.sh
```

- 前端：<http://localhost:3000>（管理页、登录等）
- 后端：<http://localhost:8000>（API）
- `.env` 会被自动加载，可配置 `WECHAT_UPSTREAM_BASE_URL`、`KEY` 等

## 2. 账号 key 与消息接收

- 登录页使用的 **key** 需要与后端「消息接收」使用同一 key，否则收不到该账号消息。
- 在 `.env` 中设置 **`KEY=你的key`**（或 `WECHAT_WS_KEY=你的key`、`WS_KEY=你的key`），与登录时填的 key 一致即可。

## 3. 消息接收：WS 与回调两种方式

### 不设 CALLBACK_BASE_URL（默认，适合本地）

- 不配置 `CALLBACK_BASE_URL` 时，后端用 **WebSocket** 连接 7006 的 GetSyncMsg 拉取消息。
- 7006 若拒绝 WS，日志会出现 `WS disconnected ... server rejected WebSocket`，消息可能收不到，但不影响登录、发消息、联系人等接口调试。

### 使用回调（7006 主动 POST 到本机）

- 7006 在公网，无法直接访问你本机的 `localhost`，需要先用 **ngrok** 把本机 8000 暴露到公网，再设回调。

**一键用 ngrok 调通（推荐）：**

1. **先配置 ngrok**（仅首次）：ngrok 需登录并配置 authtoken，否则会报 `ERR_NGROK_4018`。
   - 打开 https://dashboard.ngrok.com/get-started/your-authtoken 复制 token
   - 执行：`ngrok config add-authtoken <你的token>`
2. **终端 1**：执行
   ```bash
   ./run-ngrok.sh
   ```
   脚本会启动 `ngrok http 8000`，并把得到的公网隧道地址自动写入 `.env` 的 `CALLBACK_BASE_URL`（不会把 signup/dashboard 等链接误写成回调地址）。

2. **终端 2**：启动服务
   ```bash
   ./run-dev.sh
   ```
   后端启动时会读取 `CALLBACK_BASE_URL` 并向 7006 注册 SetCallback，新消息会由 7006 POST 到你的 ngrok 地址。

3. 打开 <http://localhost:3000> 登录，用同一 key 收发消息即可验证回调是否生效。

**手动步骤（不用脚本时）：**

1. 终端运行 `ngrok http 8000`，记下输出的 **https** 地址（如 `https://xxxx.ngrok-free.app`）。
2. 在 `.env` 中增加或修改：`CALLBACK_BASE_URL=https://xxxx.ngrok-free.app`。
3. 执行 `./run-dev.sh`（若已在运行则重启）。之后新消息由 7006 POST 到 `https://xxxx.ngrok-free.app/api/callback/wechat-message`，不再走 WS。

## 4. 手动模拟回调（不暴露公网也可测接口）

不跑隧道时，可直接用 curl 测回调接口是否正常：

```bash
# 替换成你的 key
curl -X POST 'http://localhost:8000/api/callback/wechat-message?key=HBpEnbtj9BJZ' \
  -H 'Content-Type: application/json' \
  -d '{"MsgList":[{"FromUserName":"wxid_test","Content":"你好","MsgType":1}]}'
```

返回 `{"ok":true}` 且后端无报错即表示回调入口和 `_on_ws_message` 逻辑正常。

## 5. 查看日志

- 后端：`backend/data/logs/app.log`（或控制台）
- 搜索 `SetCallback`、`callback/wechat-message`、`WS disconnected` 等便于排查消息接收问题。

## 6. 只调试后端 API

```bash
source .venv/bin/activate
cd "$(dirname "$0")"
uvicorn backend.main:app --host 0.0.0.0 --port 8000
```

再用浏览器或 Postman 访问 <http://localhost:8000/docs> 调试接口。