# 游戏服协议

## 生产

Base: `https://game.xworld.ren`（Caddy → 后端）

## 本地 AIServer（推荐开发）

路径：`AIServer/`（C++ + SQLite）

| Base | `http://127.0.0.1:8080` |
| WS | `ws://127.0.0.1:8080/ws?pid={pid}&token={token}` |

构建与运行见 [`AIServer/README.md`](../AIServer/README.md)。

## HTTP

| 方法 | 路径 | Body | 成功 | 失败 |
| --- | --- | --- | --- | --- |
| POST | `/register` | `{"username","password"}` | `{token,pid}` | `invalid_input` / `user_exists` |
| POST | `/login` | `{"username","password"}` | `{token,pid}` | `invalid_credentials` |
| GET | `/health` | — | `{ok,service,maintenance}` | — |
| GET | `/maintenance` | — | `{enabled,message}` | — |

## WebSocket

```
/ws?pid={pid}&token={token}
```

- 无 token / token 无效 → HTTP 401
- 应用层：`{"op":"hello"}` → `{"op":"hello_ack","ok":true}`；`{"op":"ping"}` → `{"op":"pong"}`
- 维护：若 `data/maintenance.json` 中 `enabled=true`，升级后立刻下发 `{"op":"maintenance","message":"..."}` 并断开
- 协议层 Ping/Pong 由服务端应答

## 维护开关

文件：`AIServer/data/maintenance.json`（与 `--db` 同目录，可用 `--maintenance` 覆盖）

```json
{ "enabled": true, "message": "今晚 2:00-4:00 维护" }
```

| GET | `/maintenance` | — | `{enabled,message}` |
| GET | `/health` | — | 增加 `maintenance` 字段 |

CDN `version.json.notice` 也会在客户端启动时弹公告（不依赖游戏服）。

## 客户端

- `HotUpdate.Net.AuthApi` / `GameNet` / `WsClient`
- Boot：`HttpBase` + `WsUrlTemplate`
- 菜单：**AIGame/Boot/Server/Local AIServer :8080** 或 Production
- 编辑器自动 `guest_{deviceId}` 账号