fix: bug

DEBUG.md

@@ -0,0 +1,80 @@
+# 本地调试说明
+
+## 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> 调试接口。