文档
This commit is contained in:
309
docs/walletman后端对接.md
Normal file
309
docs/walletman后端对接.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# WalletMan 后端对接文档
|
||||
|
||||
> 前端对接见 [walletman前端对接.md](./walletman前端对接.md)
|
||||
|
||||
Android 宿主通过 **HTTP + WebSocket + FCM** 与 walletman 服务端通信。服务端默认 `:16000`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 架构
|
||||
|
||||
```
|
||||
Android 宿主 ◄── HTTP/WS ──► walletman :16000 ◄── 代理 TCP ──► 钱包 API
|
||||
◄── FCM data-only ──► Firebase
|
||||
```
|
||||
|
||||
| 链路 | 用途 |
|
||||
|------|------|
|
||||
| HTTP REST | 登录、绑钱包、业务 |
|
||||
| WebSocket `/ws` | 设备注册、TCP 代理、心跳 |
|
||||
| FCM | WS 断线拉活、token 过期重绑 |
|
||||
|
||||
**clientId：** 设备唯一 ID，WS 注册 key + FCM 目标 key，需与 App 侧 `DeviceInfo.getUniqueIdSync()` 一致。
|
||||
|
||||
---
|
||||
|
||||
## 2. 启动与配置
|
||||
|
||||
```bash
|
||||
cd servers/walletman/cmd/server
|
||||
go run . -tls android
|
||||
```
|
||||
|
||||
测试页：`http://localhost:16000/test/index.html`
|
||||
|
||||
**FCM 服务账号：**
|
||||
|
||||
```
|
||||
servers/walletman/cmd/server/config/fcm-service-account.json
|
||||
```
|
||||
|
||||
或 `FCM_SERVICE_ACCOUNT=/path/to/json`。须与宿主 App `google-services.json` **同一 Firebase 项目**。
|
||||
|
||||
---
|
||||
|
||||
## 3. 通用约定
|
||||
|
||||
**响应：**
|
||||
|
||||
```json
|
||||
{ "success": true, "message": "说明", "data": {} }
|
||||
```
|
||||
|
||||
**需登录接口请求头：**
|
||||
|
||||
```
|
||||
Content-Type: application/json
|
||||
X-User-ID: 10000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. HTTP 接口
|
||||
|
||||
### POST `/login`
|
||||
|
||||
```json
|
||||
// req
|
||||
{ "username": "test123", "password": "123456" }
|
||||
// data
|
||||
{ "userId": 10000, "userToken": "10000" }
|
||||
```
|
||||
|
||||
### POST `/register`
|
||||
|
||||
Token 绑钱包。
|
||||
|
||||
```json
|
||||
{
|
||||
"walletType": "paytm",
|
||||
"params": {
|
||||
"type": "paytm",
|
||||
"token": "...",
|
||||
"refreshToken": "...",
|
||||
"mobile": "9xxxxxxxxx",
|
||||
"deviceId": "...",
|
||||
"chType": "ipay",
|
||||
"chVersion": "3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
// data
|
||||
{ "walletId": "paytm_9xxxxxxxxx", "walletType": "paytm" }
|
||||
```
|
||||
|
||||
`walletId` = `{walletType}_{phone}`。
|
||||
|
||||
常用 `walletType`：`paytm` | `phonepe` | `mobikwik` | `freecharge` | `paytm business` | `phonepe business`。
|
||||
|
||||
### POST `/request-otp` / POST `/verify-otp`
|
||||
|
||||
OTP 绑钱包，见 `http_handler.go`。
|
||||
|
||||
### GET `/wallets`
|
||||
|
||||
```json
|
||||
{
|
||||
"wallets": [{
|
||||
"id": "paytm_9876543210",
|
||||
"walletType": "paytm",
|
||||
"phone": "9876543210",
|
||||
"upi": "xxx@paytm",
|
||||
"status": "active",
|
||||
"otpMode": false
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
`inactive` + 非 OTP → 可能触发 FCM 重绑（`maybeNotifyWalletRebind`）。
|
||||
|
||||
### POST `/fcm/register`
|
||||
|
||||
```json
|
||||
{ "clientId": "设备ID", "fcmToken": "..." }
|
||||
```
|
||||
|
||||
与 WS `register.data.fcmToken` 等价，均 `storeFcmToken`。
|
||||
|
||||
### POST `/fcm/send-wake`
|
||||
|
||||
```json
|
||||
{ "clientId": "xxx" }
|
||||
// 或 { "userId": 10000 }
|
||||
```
|
||||
|
||||
### POST `/fcm/send-rebind`
|
||||
|
||||
```json
|
||||
{
|
||||
"walletId": "paytm_9876543210",
|
||||
"walletType": "paytm",
|
||||
"phone": "9876543210",
|
||||
"retry": false,
|
||||
"notify": true
|
||||
}
|
||||
```
|
||||
|
||||
`clientId` 可省略，按 wallet owner 查 `GetFcmClientID`。
|
||||
|
||||
### GET `/fcm/clients`
|
||||
|
||||
已注册 FCM 的 clientId 列表。
|
||||
|
||||
---
|
||||
|
||||
## 5. WebSocket `/ws`
|
||||
|
||||
URL：`ws://host:16000/ws` 或 `wss://...`
|
||||
|
||||
### 客户端 → 服务端
|
||||
|
||||
**register（连上即发）**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "register",
|
||||
"messageId": "register_1700000000000",
|
||||
"clientId": "设备ID",
|
||||
"data": { "userId": 10000, "fcmToken": "可选" }
|
||||
}
|
||||
```
|
||||
|
||||
- 存 `clientId → Client`
|
||||
- `userManager.SetProxy(userId, clientId, ...)`
|
||||
- 同 clientId 新连接踢旧连接
|
||||
|
||||
**ping（建议 10s）**
|
||||
|
||||
```json
|
||||
{ "type": "ping", "messageId": "ping_xxx" }
|
||||
```
|
||||
|
||||
**proxyReady / proxyData / proxyClose**
|
||||
|
||||
| type | 说明 |
|
||||
|------|------|
|
||||
| proxyReady | TCP 已连 host:port |
|
||||
| proxyData | data.data = base64 |
|
||||
| proxyClose | 结束 |
|
||||
|
||||
### 服务端 → 客户端
|
||||
|
||||
**proxyRequest**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "proxyRequest",
|
||||
"messageId": "req_1700000000000",
|
||||
"data": { "host": "api.phonepe.com", "port": 443 }
|
||||
}
|
||||
```
|
||||
|
||||
443 端口服务端侧做 TLS，再 HTTP/2 转发。
|
||||
|
||||
### 服务端行为
|
||||
|
||||
| 事件 | 行为 |
|
||||
|------|------|
|
||||
| WS 断开 | `cleanupClient` → `sendFcmWake(clientId)` |
|
||||
| 45s 无活动 | 心跳超时清理 + wake |
|
||||
| 代理时 client 离线 | `requestProxy` 失败 → wake |
|
||||
| 钱包 API 请求 | `proxyRoundTripper` → `requestProxy` |
|
||||
|
||||
代码：`websocket_handler.go`、`proxy.go`、`fcm.go`。
|
||||
|
||||
---
|
||||
|
||||
## 6. FCM 下发（data-only）
|
||||
|
||||
重绑 **不发 notification 块**，避免绕过 App 静默逻辑。
|
||||
|
||||
| data key | 说明 |
|
||||
|----------|------|
|
||||
| msg | 文案（客户端 AIDL 失败才本地弹） |
|
||||
| cmd | `wake_proxy` \| `rebind_wallet` |
|
||||
| params | JSON 字符串 |
|
||||
|
||||
### wake_proxy
|
||||
|
||||
```json
|
||||
{ "cmd": "wake_proxy", "params": "{}" }
|
||||
```
|
||||
|
||||
### rebind_wallet
|
||||
|
||||
```json
|
||||
{
|
||||
"cmd": "rebind_wallet",
|
||||
"msg": "Paytm 已过期，点我自动重绑",
|
||||
"params": "{\"walletId\":\"paytm_xxx\",\"walletType\":\"paytm\",\"phone\":\"9xxx\",\"retry\":false,\"tryGtkAnyway\":false}"
|
||||
}
|
||||
```
|
||||
|
||||
PhonePe 默认 `retry=true`。
|
||||
|
||||
### 自动触发
|
||||
|
||||
`wallet.GetStatus() == inactive` 且 `!GetOTPMode()` → `sendFcmRebind(..., notify=true)`。
|
||||
|
||||
### 发送实现
|
||||
|
||||
`sendFcmToClient` → FCM HTTP v1 `projects/{id}/messages:send`。
|
||||
|
||||
---
|
||||
|
||||
## 7. 时序（服务端视角）
|
||||
|
||||
**代理请求**
|
||||
|
||||
```
|
||||
walletman HTTP 出网
|
||||
→ GetProxyClientID(userId)
|
||||
→ requestProxy(clientId, host, 443)
|
||||
→ WS proxyRequest → 等 proxyReady
|
||||
→ 双向 proxyData
|
||||
```
|
||||
|
||||
**断线拉活**
|
||||
|
||||
```
|
||||
WS cleanupClient
|
||||
→ sendFcmWake(clientId)
|
||||
→ 客户端 wakeFromPrefs → 重连 WS register
|
||||
```
|
||||
|
||||
**重绑**
|
||||
|
||||
```
|
||||
inactive 检测 / 手动 /fcm/send-rebind
|
||||
→ FCM rebind_wallet
|
||||
→ 客户端静默 AIDL → POST /register（宿主实现）
|
||||
→ 失败则客户端弹通知，用户点击后走前端 handler
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 调试
|
||||
|
||||
```bash
|
||||
# 服务端日志
|
||||
go run . -tls android
|
||||
|
||||
# 测试页
|
||||
http://localhost:16000/test/index.html
|
||||
```
|
||||
|
||||
| 接口 | 用途 |
|
||||
|------|------|
|
||||
| GET /fcm/clients | 看已注册设备 |
|
||||
| POST /fcm/send-wake | 手动拉活 |
|
||||
| POST /fcm/send-rebind | 手动重绑 |
|
||||
|
||||
| 现象 | 排查 |
|
||||
|------|------|
|
||||
| FCM send failed | 服务账号路径、project_id |
|
||||
| no FCM token for clientId | App 未 POST /fcm/register 或 WS 未带 fcmToken |
|
||||
| Client not connected | WS 未连；发 wake 后重试 |
|
||||
| 重绑发了客户端无反应 | 查 FCM send ok 日志；Firebase 项目是否一致 |
|
||||
Reference in New Issue
Block a user