玩家余额回收 (主动下分)

包网系统可以在玩家退出游戏大厅或需要立即退还资金时，主动调用此接口收回玩家在 VCT 平台该玩家该币种在所有 Provider 的本地剩余余额。

调用此接口后，VCT 平台会将该玩家该币种的所有本地钱包余额汇总并转为待结算状态，等待结算窗口后发起 离线/额度回收回调 (/api/v1/callback/offline)，将汇总金额通知包网系统。

环境地址

环境	Base URL
生产环境	https://hub-panel-api.v7stech.com
测试环境	https://hub-panel-api-dev.v7stech.com

接口信息

属性	值
路径	POST /papi/v1/player/reclaim
认证	Agent Token（Bearer）
Content-Type	application/x-www-form-urlencoded

请求参数

参数名	类型	必填	说明
member_id	string	是	玩家唯一标识（包网侧玩家 ID）
currency	string	是	指定结算的币种代码（例如 MYR）
session_id	string	是	游戏启动接口返回的 VCT 会话 ID；必须原样传回，用于精确绑定本次结算

请求示例

curl -X POST https://api.example.com/papi/v1/player/reclaim \
  -H "Authorization: Bearer {agent_token}" \
  -d "member_id=player_001&currency=MYR&session_id=vct-session-uuid-001"

响应字段

Data 字段结构

字段	类型	说明
member_id	string	玩家包网侧 ID
session_id	string	本次 VCT 游戏会话唯一 ID
reclaimed_amount	decimal	最终结算金额；首次 settling 响应不返回，稍后通过 /api/v1/callback/offline 发送
currency	string	结算的货币代码（若没有余额或无需结算，返回空字符串）
action	string	本次回收动作，主动下分通常为 exit_game
settlement_status	string	首次为 settling；completed 表示包网已确认 Offline；callback_failed 表示包网未确认

同一币种的多个 Provider 钱包会作为一笔 reclaim 汇总清零。后台 Force Kick 使用相同的汇总规则。

code=0 只表示 Hub 已接收并执行 reclaim 请求，不等于 Redis lock 已释放。包网必须检查 data.settlement_status。

请求已接受（结算中）

Hub 会立即接受请求，不等待结算窗口，也不会提前返回最终金额：

{
  "status": true,
  "code": 0,
  "data": {
    "member_id": "player_001",
    "currency": "MYR",
    "action": "exit_game",
    "session_id": "vct-session-uuid-001",
    "settlement_status": "settling"
  },
  "msg": "获取成功"
}

最终 reclaimed_amount 只会出现在稍后发送的 /api/v1/callback/offline 请求中。包网不能根据这里的 code=0 或 settlement_status=settling 判断结算已经完成。

结算完成（completed）

Hub 等待结算窗口结束、计算最终金额，并且包网成功确认 /api/v1/callback/offline 后，才会把本次 session 标记为 completed。如果包网之后使用相同的 session_id 再次请求 reclaim，Hub 会返回已确认的最终金额：

{
  "status": true,
  "code": 0,
  "data": {
    "member_id": "player_001",
    "currency": "MYR",
    "action": "exit_game",
    "session_id": "vct-session-uuid-001",
    "reclaimed_amount": 100.00,
    "settlement_status": "completed"
  },
  "msg": "获取成功"
}

这个响应不是首次 reclaim 的响应。首次请求必须先返回 settling；最终金额会先通过 /api/v1/callback/offline 异步通知包网，之后相同 session_id 的重复请求才会返回 completed 和 reclaimed_amount。

失败响应

{
  "status": false,
  "code": 7,
  "data": {},
  "msg": "player_not_found"
}

Offline 未确认时

如果 data.settlement_status 为 callback_failed，包网没有成功确认 Hub 发出的 /api/v1/callback/offline。Hub 会保留同币种结算锁直到自动 TTL 到期；管理员也可以在 Player Sessions 页面使用相同 session_id 手动 Retry。包网不应把 code=0 当作已经完成结算，必须按 session_id 保持幂等。

AI 开发提示词（可直接复制）

请在当前包网项目中实现 VCT 玩家余额回收（主动下分）流程。

接口：POST {VCT_BASE_URL}/papi/v1/player/reclaim
Content-Type：application/x-www-form-urlencoded
Authorization：Bearer {agent_token}
必填参数：member_id、currency、session_id；session_id 必须来自游戏启动响应并原样传回。

实现要求：
1. 以 Agent + member_id + currency + session_id 建立幂等键和“结算中”状态，阻止同币种重复启动或重复下分。
2. code=0 只表示 VCT 接受请求；必须继续读取 data.settlement_status。
3. settling 表示异步结算中，不得当作完成，不得从当前响应推断 reclaimed_amount。
4. completed 表示 VCT 已收到包网 offline 成功确认；只有此状态可显示最终 reclaimed_amount。
5. callback_failed 表示 offline 未确认，保持幂等状态并提示等待自动重试或人工处理。
6. 最终金额以随后 `/api/v1/callback/offline` 携带的同一 session_id 为准；不要因重复 reclaim 或 offline 重复入账。
7. 对同一 session_id 的重复调用返回现有状态，不创建第二个回收流程。
8. 网络超时后先查询本地请求记录或以相同幂等键重试，不能生成新的 session_id。
9. 不暴露 Agent Secret/Token；日志记录 member_id、currency、session_id、业务 code 和 settlement_status 即可。
10. 增加测试：settling、completed、callback_failed、重复请求、错误 session_id、网络超时、玩家不存在和 offline 重试。

请复用现有会话、锁、HTTP Client 和错误封装，完成后端流程、状态展示与测试。