1645 行
48 KiB
Markdown
1645 行
48 KiB
Markdown
# TDD-05 API接口设计
|
||
|
||
> 文档类型：技术设计文档（Technical Design Document）
|
||
> 版本：1.0
|
||
> 日期：2026-06-30
|
||
> 关联文档：TDD-00《挂机手游技术栈方案.md》、TDD-04《数据库表结构设计》、GDD-03/06/07/13/14/16/18/22、PRD-01/02/03
|
||
|
||
---
|
||
|
||
## 1. 文档信息
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 目标 | 为《洪荒大陆》挂机手游定义客户端 ↔ 服务端、服务端 ↔ 服务间的接口规范，覆盖账号、角色、修炼、战斗、功法、经济、社交、地图、弟子/领地八大模块。 |
|
||
| 读者 | 客户端开发、服务端开发（Nakama/Go）、测试、运维、数值策划 |
|
||
| 技术栈 | 客户端 Cocos Creator 3.x + protobufjs；服务端 Nakama（Go/Lua）+ Gin HTTP API；配置中心 Nacos；缓存 Valkey；数据库 PostgreSQL 16 |
|
||
| 核心约束 | 无任务系统、无赛季重置；技能随机生成+固定命名；官方存在感低；概率/机遇驱动；ATB 行动速度制；功法加持取代本命技；破界为唯一晋级术语。 |
|
||
|
||
---
|
||
|
||
## 2. 协议总览
|
||
|
||
### 2.1 RESTful 与 gRPC 的分工
|
||
|
||
| 维度 | RESTful（HTTPS/JSON） | gRPC（HTTP/2 + Protobuf） |
|
||
|------|----------------------|---------------------------|
|
||
| 适用场景 | 查询、CRUD、列表分页、交易行、拍卖、背包、社交关系、GM/运营接口 | 需要服务端权威结算、低延迟、强状态一致性的玩法动作：突破、渡劫、破界、战斗、PVP、副本进入、弟子派遣 |
|
||
| 调用方式 | `METHOD /api/v1/{resource}/{id}` | `service.Method(Request) returns (Response)` |
|
||
| 幂等性 | 读操作幂等；写操作配合 `Idempotency-Key` | 关键写操作在服务端做幂等键去重 |
|
||
| 客户端支持 | Cocos Creator 内置 HTTP / axios 风格封装 | protobufjs + 可选 grpc-web（若浏览器端需要） |
|
||
| 内部服务间 | Gin 后台、支付回调、数据埋点 | 游戏逻辑服 ↔ 结算服、战斗模拟服、配置中心推送 |
|
||
|
||
**基地址示例**
|
||
|
||
```text
|
||
RESTful 网关： https://api.honghuang.example.com
|
||
游戏 gRPC： grpcs://game.honghuang.example.com
|
||
Nakama 实时： wss://nakama.honghuang.example.com
|
||
```
|
||
|
||
### 2.2 认证方式
|
||
|
||
所有接口（除显式标注「公开」外）均需在请求头携带 Nakama 颁发的 Session Token。
|
||
|
||
```http
|
||
Authorization: Bearer <nakama_session_token>
|
||
X-Client-Version: 1.2.0.1056
|
||
X-Trace-Id: <uuid> // 可选，网关未提供时自动生成
|
||
```
|
||
|
||
- Token 由 Nakama 在注册/登录时签发，默认有效期 60 天，可在后台强制吊销。
|
||
- 网关（OpenResty/Traefik）负责校验 token 签名、解析 `player_id` 与 `character_id`，并追加到内部请求头 `X-Player-Id`、`X-Character-Id`。
|
||
- 跨境界/跨服调用时，额外校验 `X-Character-Id` 的 `world_tier` 与目标接口是否匹配。
|
||
|
||
### 2.3 统一响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": { },
|
||
"trace_id": "0190a1b2-c3d4-7e8f-9a0b-1c2d3e4f5a6b"
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `code` | 业务状态码，`0` 为成功；非零见 §2.4 |
|
||
| `message` | 可读说明，客户端可用于 Toast/日志 |
|
||
| `data` | 业务数据，失败时可为 `null` |
|
||
| `trace_id` | 全链路追踪 ID，排查时必带 |
|
||
|
||
HTTP 状态码仅用于表达传输/网关层结果：
|
||
|
||
| HTTP 状态 | 含义 |
|
||
|-----------|------|
|
||
| 200 | 请求到达，业务结果看 `code` |
|
||
| 400 | 参数缺失/非法 |
|
||
| 401 | Token 无效/过期/未携带 |
|
||
| 403 | 权限不足（如跨境界、阵营不符、组织权限不足） |
|
||
| 404 | 资源不存在 |
|
||
| 409 | 状态冲突（如重复请求、条件不满足） |
|
||
| 429 | 触发限流 |
|
||
| 500 | 服务端内部错误 |
|
||
|
||
### 2.4 错误码规范
|
||
|
||
错误码为 4 位数字：`[模块 1 位][级别 2 位][序号 1 位]`。
|
||
|
||
| 模块位 | 含义 |
|
||
|--------|------|
|
||
| 1xxx | 账号/认证 |
|
||
| 2xxx | 角色/角色状态 |
|
||
| 3xxx | 修炼/境界/渡劫/破界 |
|
||
| 4xxx | 战斗/PVP |
|
||
| 5xxx | 功法/技能/玉简 |
|
||
| 6xxx | 经济/背包/交易行/拍卖/情报 |
|
||
| 7xxx | 社交/门派/帮派/家族/关系/佣兵/悬赏 |
|
||
| 8xxx | 地图/副本/遗迹/事件 |
|
||
| 9xxx | 系统/配置/限流 |
|
||
|
||
**公共错误码**
|
||
|
||
| 错误码 | 说明 | HTTP |
|
||
|--------|------|------|
|
||
| 0 | 成功 | 200 |
|
||
| 1001 | Token 缺失 | 401 |
|
||
| 1002 | Token 无效或过期 | 401 |
|
||
| 1003 | 客户端版本过低 | 400 |
|
||
| 9001 | 请求过于频繁 | 429 |
|
||
| 9002 | 服务内部错误 | 500 |
|
||
| 9003 | 配置加载中，请稍后 | 503 |
|
||
| 9004 | 重复请求（幂等键冲突） | 409 |
|
||
|
||
模块专属错误码在各自接口章节给出。
|
||
|
||
### 2.5 限流策略
|
||
|
||
限流在网关层基于 Token Bucket 实现，按 `character_id` + `path/method` 维度计数，热点接口额外按 IP/设备维度做兜底。
|
||
|
||
| 类型 | 默认速率 | Burst | 说明 |
|
||
|------|----------|-------|------|
|
||
| 读接口（GET） | 60 次/分钟 | 10 | 列表查询建议客户端本地缓存 5~10s |
|
||
| 通用写接口 | 30 次/分钟 | 5 | 含创建订单、派遣弟子等 |
|
||
| 核心玩法动作 | 10 次/分钟 | 3 | 突破、渡劫、破界、PVP、副本进入 |
|
||
| 经济敏感接口 | 20 次/分钟 | 3 | 挂单、撤单、购买、出价 |
|
||
| 全服广播/聊天 | 120 条/分钟 | 20 | 文字+表情，超长文本额外拆分计数 |
|
||
| 登录/注册 | 10 次/分钟/IP | 3 | 防止刷号 |
|
||
|
||
响应头示例：
|
||
|
||
```http
|
||
X-RateLimit-Limit: 30
|
||
X-RateLimit-Remaining: 27
|
||
X-RateLimit-Reset: 1719820800
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 接口分类与清单
|
||
|
||
### 3.1 账号/角色
|
||
|
||
#### 3.1.1 注册（公开）
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 游客/设备注册，创建 Nakama 账号并返回 session token |
|
||
| REST | `POST /api/v1/auth/register` |
|
||
| gRPC | `rpc Register (RegisterReq) returns (AuthResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_id` | string | 是 | 设备唯一标识（首次注册） |
|
||
| `platform` | string | 是 | `ios` / `android` / `harmony` / `guest` |
|
||
| `invite_code` | string | 否 | 邀请码，用于统计 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"player_id": "p-uuid-001",
|
||
"nakama_token": "eyJhbGciOi...",
|
||
"expires_at": "2026-08-30T12:00:00Z",
|
||
"is_new": true
|
||
},
|
||
"trace_id": "..."
|
||
}
|
||
```
|
||
|
||
**错误码**：1004（设备ID非法）、1005（平台不支持）、1006（邀请码无效）
|
||
|
||
**限流**：10 次/分钟/IP，burst 3。
|
||
|
||
---
|
||
|
||
#### 3.1.2 登录（公开）
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 设备/Token 登录，刷新 Nakama session |
|
||
| REST | `POST /api/v1/auth/login` |
|
||
| gRPC | `rpc Login (LoginReq) returns (AuthResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `device_id` | string | 是 | 设备标识 |
|
||
| `platform` | string | 是 | 平台 |
|
||
| `refresh_token` | string | 否 | 长期刷新令牌 |
|
||
|
||
**响应示例**：同 3.1.1。
|
||
|
||
**错误码**：1002（Token 过期）、1007（账号被封禁）
|
||
|
||
**限流**：10 次/分钟/IP，burst 3。
|
||
|
||
---
|
||
|
||
#### 3.1.3 创建角色
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 在当前账号下创建新角色；人族不可直接创建（GDD-01/02） |
|
||
| REST | `POST /api/v1/characters` |
|
||
| gRPC | `rpc CreateCharacter (CreateCharacterReq) returns (CharacterResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `name` | string | 是 | 角色名，2~14 字符，屏蔽词过滤 |
|
||
| `race_id` | string | 是 | 创角可选种族，如 `tiger_yao`、`elf_light` |
|
||
| `birth_world_tier` | int | 否 | 默认 `1`，当前版本固定为出生地 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"character_id": "c-uuid-101",
|
||
"player_id": "p-uuid-001",
|
||
"name": "铁爪传",
|
||
"race_id": "tiger_yao",
|
||
"world_tier": 1,
|
||
"realm_tier": 1,
|
||
"minor_realm": 1,
|
||
"level": 1,
|
||
"status": "active",
|
||
"created_at": "2026-06-30T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：2001（角色名重复/不合法）、2002（该账号角色数已达上限）、2003（种族不可创建）、2004（出生层级非法）
|
||
|
||
**限流**：5 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.1.4 获取角色状态
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 拉取角色完整状态，用于登录后主界面初始化 |
|
||
| REST | `GET /api/v1/characters/{character_id}` |
|
||
| gRPC | `rpc GetCharacter (GetCharacterReq) returns (CharacterResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `character_id` | uuid | 是 | 路径参数 |
|
||
| `with_snapshot` | bool | 否 | 是否携带战斗属性快照 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"character_id": "c-uuid-101",
|
||
"name": "铁爪传",
|
||
"race_id": "tiger_yao",
|
||
"world_tier": 2,
|
||
"realm_tier": 2,
|
||
"minor_realm": 1,
|
||
"realm_status": "normal",
|
||
"level": 32,
|
||
"exp": 185000,
|
||
"base_stats": { "str": 45, "vit": 38, "wis": 22, "agi": 51, "spi": 18, "luk": 27 },
|
||
"battle_stats": { "hp_max": 3200, "atk": 480, "def": 220, "speed": 310 },
|
||
"san_current": 88,
|
||
"san_max": 100,
|
||
"crime_score": 12,
|
||
"heavenly_value": 5,
|
||
"karma_value": 3,
|
||
"reputation_score": 120,
|
||
"last_online_at": "2026-06-30T11:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：2005（角色不存在）、2006（无权查看该角色）、2007（角色已删除/封禁）
|
||
|
||
**限流**：60 次/分钟。
|
||
|
||
---
|
||
|
||
### 3.2 修炼/境界
|
||
|
||
#### 3.2.1 获取境界进度
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 查询当前境界、修为、小境界、解锁的最高世界层级 |
|
||
| REST | `GET /api/v1/characters/{character_id}/realm` |
|
||
| gRPC | `rpc GetRealmProgress (RealmReq) returns (RealmProgressResp)` |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"realm_tier": 2,
|
||
"minor_realm": 2,
|
||
"realm_name": "筑基期·中期",
|
||
"exp": 185000,
|
||
"exp_to_next": 220000,
|
||
"max_unlocked_world_tier": 2,
|
||
"realm_status": "normal",
|
||
"breakthrough_ready": false,
|
||
"tribulation_pending": false
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：3001（境界数据缺失）
|
||
|
||
**限流**：60 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.2.2 尝试突破
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 小境界突破（如初期→中期），服务端按概率判定成功与否；失败不跨层掉落（GDD-12） |
|
||
| REST | `POST /api/v1/characters/{character_id}/realm/breakthrough` |
|
||
| gRPC | `rpc AttemptBreakthrough (BreakthroughReq) returns (BreakthroughResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `target_minor_realm` | int | 是 | 目标小境界 |
|
||
| `consumables` | []object | 否 | 使用的丹药/材料实例 ID 列表 |
|
||
| `helper_ids` | []uuid | 否 | 道侣/结义护法者角色 ID |
|
||
| `idempotency_key` | string | 是 | 客户端唯一键，防止重复扣材料 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"success": true,
|
||
"from": { "realm_tier": 2, "minor_realm": 2 },
|
||
"to": { "realm_tier": 2, "minor_realm": 3 },
|
||
"exp_consumed": 220000,
|
||
"record_id": "r-uuid-202",
|
||
"special_event": "小顿悟·功法进度+30%"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：3002（修为不足）、3003（已达当前境界上限）、3004（有未完成的渡劫/转化）、3005（护法者条件不符）、3006（突破失败，详情见 data）
|
||
|
||
**限流**：1 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.2.3 发起渡劫
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 大境界圆满后发起渡劫（天劫/心魔/天罚），异步进入渡劫流程 |
|
||
| REST | `POST /api/v1/characters/{character_id}/realm/tribulation` |
|
||
| gRPC | `rpc StartTribulation (TribulationReq) returns (TribulationResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `target_realm_tier` | int | 是 | 目标大境界 |
|
||
| `tribulation_type` | string | 否 | `normal`/`heart_devil`/`qi_deviation`/`chaos`，不填由服务端按阵营/状态决定 |
|
||
| `consumables` | []object | 否 | 渡劫道具 |
|
||
| `helper_ids` | []uuid | 否 | 护法者 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"tribulation_id": "t-uuid-303",
|
||
"status": "in_progress",
|
||
"base_success_rate": 0.65,
|
||
"modified_success_rate": 0.78,
|
||
"estimated_ticks": 120,
|
||
"start_at": "2026-06-30T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：3007（未满足渡劫条件）、3008（目标境界非法）、3009（已在渡劫中）、3010（SAN 过低无法渡劫）
|
||
|
||
**限流**：1 次/5 分钟。
|
||
|
||
---
|
||
|
||
#### 3.2.4 查询渡劫结果
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 查询最近一次渡劫结果/进度 |
|
||
| REST | `GET /api/v1/characters/{character_id}/realm/tribulation` |
|
||
| gRPC | `rpc GetTribulationResult (TribulationReq) returns (TribulationResp)` |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"tribulation_id": "t-uuid-303",
|
||
"status": "completed",
|
||
"result": "success",
|
||
"from_realm_tier": 2,
|
||
"to_realm_tier": 3,
|
||
"penalties": null,
|
||
"drops": [{ "item_id": "heavenly_dew", "quantity": 1 }]
|
||
}
|
||
}
|
||
```
|
||
|
||
**限流**：30 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.2.5 破界（晋级新世界）
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 大境界圆满并持有破界钥/关键道具后，触发破界事件并永久解锁下一世界层级（GDD-08） |
|
||
| REST | `POST /api/v1/characters/{character_id}/realm/world-break` |
|
||
| gRPC | `rpc WorldBreak (WorldBreakReq) returns (WorldBreakResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `target_world_tier` | int | 是 | 目标世界层级 |
|
||
| `key_item_instance_id` | uuid | 否 | 破界钥/关键道具实例 ID；首次破界（1→2）可不填 |
|
||
| `confirm` | bool | 是 | 二次确认，防止误操作 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"success": true,
|
||
"from_world_tier": 2,
|
||
"to_world_tier": 3,
|
||
"from_realm_tier": 2,
|
||
"to_realm_tier": 3,
|
||
"breakthrough_record_id": "br-uuid-404",
|
||
"world_event": "破界·洪荒腹地已解锁",
|
||
"ruin_generated": false
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：3011（未解锁前置世界）、3012（缺少破界钥）、3013（境界未圆满）、3014（处于转化/渡劫中不可破界）、3015（目标世界名额已满，仅层4太古秘境）
|
||
|
||
**限流**：1 次/5 分钟。
|
||
|
||
---
|
||
|
||
### 3.3 战斗
|
||
|
||
#### 3.3.1 发起战斗
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 触发一场 PVE 战斗（游历遭遇/副本/遗迹），服务端完整计算并返回战报 ID；战斗结算权威在服务端（GDD-03） |
|
||
| REST | `POST /api/v1/combats` |
|
||
| gRPC | `rpc StartCombat (StartCombatReq) returns (CombatResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `battle_type` | string | 是 | `expedition_pve` / `dungeon_pve` / `ruin_pve` |
|
||
| `context_id` | uuid | 是 | 关联上下文：游历记录/副本运行/遗迹 ID |
|
||
| `party_members` | []uuid | 否 | 队友角色 ID（副本/遗迹） |
|
||
| `preferred_skills` | []uuid | 否 | 玩家偏好的技能实例 ID 排序 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"battle_id": "b-uuid-505",
|
||
"status": "completed",
|
||
"result_summary": {
|
||
"winner": "attacker",
|
||
"end_condition": "hp_zero"
|
||
},
|
||
"drops": {
|
||
"currency": [{ "currency_code": "yao_crystal_low", "amount": 32 }],
|
||
"items": [{ "item_id": "ghost_marrow_fragment", "quantity": 1 }]
|
||
},
|
||
"death_penalty_applied": false
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：4001（战斗类型非法）、4002（上下文不存在）、4003（队伍成员不满足条件）、4004（处于保护期不可战斗）
|
||
|
||
**限流**：20 次/分钟（PVE）。
|
||
|
||
---
|
||
|
||
#### 3.3.2 查询战报
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 获取完整文字战报（ATB 行动序列） |
|
||
| REST | `GET /api/v1/combats/{battle_id}` |
|
||
| gRPC | `rpc GetBattleReport (BattleReportReq) returns (BattleReportResp)` |
|
||
|
||
**响应示例**（节选）
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"battle_id": "b-uuid-505",
|
||
"type": "expedition_pve",
|
||
"realm_tier": 2,
|
||
"game_timestamp": "2026-06-30T12:00:00Z",
|
||
"attacker": { "id": "c-uuid-101", "name": "铁爪传", "race": "tiger_yao" },
|
||
"defender": { "id": "npc-ghost-01", "name": "幽魂", "race": "ghost" },
|
||
"rounds": [
|
||
{ "round": 1, "tick": 40, "actor": "attacker", "skill_id": "hunt_claw_3", "damage": 612, "is_crit": true, "hp_after": { "attacker": 3200, "defender": 2188 } }
|
||
],
|
||
"result": { "winner": "attacker", "end_condition": "hp_zero" },
|
||
"special_events": []
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：4005（战报不存在）、4006（无权查看该战报）
|
||
|
||
**限流**：60 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.3.3 PVP 挑战
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 向同 `realm_tier` 玩家发起战书，异步结算；受每日次数与戾气规则约束（GDD-03 ✅17 / ✅14） |
|
||
| REST | `POST /api/v1/combats/pvp` |
|
||
| gRPC | `rpc PvpChallenge (PvpChallengeReq) returns (CombatResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `target_character_id` | uuid | 是 | 被挑战者角色 ID |
|
||
| `bounty_id` | uuid | 否 | 若由悬赏触发，传入悬赏 ID |
|
||
| `use_paid_chance` | bool | 否 | 是否消耗灵石购买额外次数 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"battle_id": "b-uuid-506",
|
||
"status": "completed",
|
||
"result_summary": { "winner": "attacker", "end_condition": "hp_zero" },
|
||
"honor_points": 30,
|
||
"death_penalty_applied": false,
|
||
"daily_pvp_count": 3,
|
||
"daily_pvp_limit": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：4007（目标不在同境界层级）、4008（目标处于新手/死亡保护期）、4009（每日 PVP 次数已达上限）、4010（不可挑战同帮派/同家族成员）、4011（被悬赏目标不可拒绝时无需战书）
|
||
|
||
**限流**：基础 5 次/天免费 + 付费最多 15 次/天；接口调用限 10 次/分钟。
|
||
|
||
---
|
||
|
||
### 3.4 功法/技能
|
||
|
||
#### 3.4.1 获取功法列表
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 查询角色已学功法实例（主修+副修） |
|
||
| REST | `GET /api/v1/characters/{character_id}/manuals` |
|
||
| gRPC | `rpc ListManuals (ManualListReq) returns (ManualListResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `is_buffing` | bool | 否 | 仅查询加持中的功法 |
|
||
| `page` | int | 否 | 分页，默认 1 |
|
||
| `page_size` | int | 否 | 默认 20，最大 100 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"total": 5,
|
||
"list": [
|
||
{
|
||
"manual_instance_id": "mi-uuid-601",
|
||
"manual_id": "baihu_sha_dian",
|
||
"name": "《白虎煞典》",
|
||
"current_layer": 4,
|
||
"max_layer": 9,
|
||
"proficiency": 4500,
|
||
"is_main": true,
|
||
"is_buffing": true,
|
||
"domain": "body",
|
||
"element": "none",
|
||
"source_tag": "ORIGINAL"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**限流**：60 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.4.2 功法升层
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 消耗材料与熟练度尝试提升功法层数；成功率非 100%（GDD-04） |
|
||
| REST | `POST /api/v1/characters/{character_id}/manuals/{manual_instance_id}/upgrade` |
|
||
| gRPC | `rpc UpgradeManual (UpgradeManualReq) returns (ManualResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `materials` | []object | 是 | `{inventory_id, quantity}` 列表 |
|
||
| `use_insight_item` | bool | 否 | 是否使用顿悟道具 |
|
||
| `idempotency_key` | string | 是 | 幂等键 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"manual_instance_id": "mi-uuid-601",
|
||
"old_layer": 4,
|
||
"new_layer": 5,
|
||
"success": true,
|
||
"proficiency_left": 120,
|
||
"unlocked_skill": { "skill_id": "hunt_claw_3", "skill_name": "猎爪·三式" }
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：5001（功法不存在）、5002（材料不足）、5003（熟练度不足）、5004（已达境界层数上限）、5005（功法处于隐患态不可操作）
|
||
|
||
**限流**：5 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.4.3 设置加持功法
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 将一门已学功法设为加持位；切换后 24 现实小时磨合期（GDD-04 8.2.5） |
|
||
| REST | `POST /api/v1/characters/{character_id}/manuals/{manual_instance_id}/buff` |
|
||
| gRPC | `rpc SetBuffingManual (BuffManualReq) returns (BuffSlotResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `slot_index` | int | 是 | 0~2，取决于已解锁位数 |
|
||
| `unset_others` | bool | 否 | 是否替换同槽位旧加持 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"slot_index": 0,
|
||
"manual_instance_id": "mi-uuid-601",
|
||
"buff_speed_bonus": 0.08,
|
||
"breakin_until": "2026-07-01T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：5006（功法不可加持）、5007（加持位未解锁）、5008（功法为隐患态）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.4.4 学习技能
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 通过玉简/功法解锁/NPC传授等途径学习技能；服务端校验种族/职业/境界/属性/SAN 要求（GDD-17） |
|
||
| REST | `POST /api/v1/characters/{character_id}/skills/learn` |
|
||
| gRPC | `rpc LearnSkill (LearnSkillReq) returns (SkillResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `source_type` | string | 是 | `jade_slip` / `manual_unlock` / `npc` / `event` / `teaching` |
|
||
| `source_id` | uuid | 是 | 来源实例 ID（玉简物品/功法实例/NPC ID 等） |
|
||
| `custom_name` | string | 否 | 天品+/唯一技能可自定义名 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"skill_instance_id": "si-uuid-701",
|
||
"skill_id": "hunt_claw_3",
|
||
"name": "猎爪·三式",
|
||
"source_tag": "JADE_SLIP",
|
||
"can_copy_to_jade_slip": false,
|
||
"proficiency": 0,
|
||
"instance_data": { "base_coef": 1.35, "cd": 300, "cost": 20, "element": "none" }
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：5009（来源不存在）、5010（学习条件不满足）、5011（玉简来源不可二次复制）、5012（独属技能跨族学习被禁止）、5013（唯一技能持有者未变更）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.4.5 生成功法玉简
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 将「原始习得」技能消耗 40% 熟练度拓印为玉简；玉简学会后不可再拓印（GDD-07 ✅T5） |
|
||
| REST | `POST /api/v1/characters/{character_id}/skills/{skill_instance_id}/jade-slip` |
|
||
| gRPC | `rpc CreateJadeSlip (JadeSlipReq) returns (ItemResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `consume_proficiency` | bool | 是 | 是否消耗熟练度（默认 true） |
|
||
| `copy_count` | int | 否 | 一次拓印份数，受 `copy_count_left` 限制 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"inventory_id": "inv-uuid-801",
|
||
"item_id": "jade_slip_hunt_claw_3",
|
||
"name": "《猎爪·三式》玉简",
|
||
"quantity": 1,
|
||
"instance_data": { "skill_level": 3, "durability": 5 },
|
||
"proficiency_consumed": 240
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：5014（技能不可拓印）、5015（熟练度不足）、5016（拓印次数已达上限）
|
||
|
||
**限流**：5 次/分钟。
|
||
|
||
---
|
||
|
||
### 3.5 经济/背包
|
||
|
||
#### 3.5.1 获取货币余额
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 查询角色钱包余额 |
|
||
| REST | `GET /api/v1/characters/{character_id}/currencies` |
|
||
| gRPC | `rpc GetCurrencyBalances (CurrencyReq) returns (CurrencyBalancesResp)` |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"balances": [
|
||
{ "currency_code": "spirit_stone_low", "amount": 1280, "total_earned": 5600, "total_spent": 4320 },
|
||
{ "currency_code": "yao_crystal_low", "amount": 32, "total_earned": 120, "total_spent": 88 }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**限流**：60 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.5.2 交易行挂单
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 将背包物品托管到交易行，指定结算货币；铜钱/银两不可作为市场结算货币（GDD-06） |
|
||
| REST | `POST /api/v1/market/orders` |
|
||
| gRPC | `rpc CreateMarketOrder (MarketOrderReq) returns (MarketOrderResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `inventory_id` | uuid | 是 | 托管物品实例 ID |
|
||
| `currency_code` | string | 是 | 结算货币，如 `spirit_stone_low` |
|
||
| `unit_price` | decimal | 是 | 单价，≥1 |
|
||
| `quantity` | int | 是 | 数量，堆叠物可部分上架 |
|
||
| `duration_hours` | int | 否 | 挂单时长，默认 48 游戏小时 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"order_id": "mo-uuid-901",
|
||
"status": "active",
|
||
"listed_at": "2026-06-30T12:00:00Z",
|
||
"expired_at": "2026-07-02T12:00:00Z",
|
||
"tax_rate": 0.05
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：6001（物品不存在/不可交易）、6002（结算货币非法）、6003（价格非法）、6004（物品已绑定）、6005（超过同类型挂单上限）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.5.3 交易行撤单
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 撤销未成交订单，物品退回背包 |
|
||
| REST | `DELETE /api/v1/market/orders/{order_id}` |
|
||
| gRPC | `rpc CancelMarketOrder (OrderIdReq) returns (MarketOrderResp)` |
|
||
|
||
**错误码**：6006（订单不存在）、6007（订单状态不可撤销）、6008（无权操作该订单）
|
||
|
||
**限流**：20 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.5.4 交易行购买
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 按单价购买指定数量，系统扣税后结算 |
|
||
| REST | `POST /api/v1/market/orders/{order_id}/buy` |
|
||
| gRPC | `rpc BuyMarketOrder (BuyOrderReq) returns (TradeResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `quantity` | int | 是 | 购买数量 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"trade_id": "tr-uuid-902",
|
||
"order_id": "mo-uuid-901",
|
||
"quantity": 10,
|
||
"total_price": 500,
|
||
"tax": 25,
|
||
"currency_code": "spirit_stone_low",
|
||
"items": [{ "inventory_id": "inv-uuid-803", "item_id": "iron_ore", "quantity": 10 }]
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：6009（余额不足）、6010（数量超过挂单剩余）、6011（订单已失效）、6012（同境界交易限制，临时下界只买不卖）
|
||
|
||
**限流**：20 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.5.5 查询拍卖列表
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 按层级/类型/状态筛选官方拍卖或势力拍卖（GDD-14） |
|
||
| REST | `GET /api/v1/auctions` |
|
||
| gRPC | `rpc ListAuctions (AuctionListReq) returns (AuctionListResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `world_tier` | int | 否 | 境界层级过滤 |
|
||
| `auction_type` | string | 否 | `official` / `organization` |
|
||
| `category` | string | 否 | `rare_bloodline` / `jade_slip` / `artifact` / ... |
|
||
| `status` | string | 否 | `active` / `preparing` / `sold` |
|
||
|
||
**限流**：60 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.5.6 拍卖出价
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 对拍卖出价，需先缴纳保证金；支持自动出价上限 |
|
||
| REST | `POST /api/v1/auctions/{auction_id}/bids` |
|
||
| gRPC | `rpc BidAuction (BidReq) returns (BidResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `amount` | decimal | 是 | 出价金额 |
|
||
| `is_auto_bid` | bool | 否 | 是否自动出价 |
|
||
| `auto_max_amount` | decimal | 否 | 自动出价上限 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"bid_id": "bid-uuid-903",
|
||
"auction_id": "auc-uuid-904",
|
||
"amount": 15000,
|
||
"deposit_paid": 1500,
|
||
"is_auto_bid": false,
|
||
"bid_at": "2026-06-30T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：6013（拍卖不存在）、6014（出价低于最低加价）、6015（保证金不足）、6016（拍卖已结束）、6017（已被势力黑吃黑标记冻结）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.5.7 查询天机阁情报
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 浏览可购买的情报订单（资源/事件/位置/悬赏线索/副本入口/唯一技能线索） |
|
||
| REST | `GET /api/v1/intelligence` |
|
||
| gRPC | `rpc ListIntelligence (IntelListReq) returns (IntelListResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `intel_type` | string | 否 | `resource` / `event` / `location` / `bounty_clue` / `instance_entry` / `unique_skill_clue` |
|
||
| `target_world_tier` | int | 否 | 目标世界层级 |
|
||
|
||
**限流**：60 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.5.8 购买情报
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 购买情报获得限时 BUFF；受同时生效上限 3 条约束（GDD-06 ✅C07） |
|
||
| REST | `POST /api/v1/intelligence/{order_id}/buy` |
|
||
| gRPC | `rpc BuyIntelligence (BuyIntelReq) returns (IntelBuffResp)` |
|
||
|
||
**错误码**：6018（情报不存在/已售罄）、6019（同时生效情报超限）、6020（卖家冷却中不可购买同一目标）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
### 3.6 社交
|
||
|
||
#### 3.6.1 创建组织
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 创建门派/帮派/家族；`org_type` 区分 `system_sect`（玩家自建门派）/ `guild` / `family` |
|
||
| REST | `POST /api/v1/guilds` |
|
||
| gRPC | `rpc CreateOrganization (CreateOrgReq) returns (OrgResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `org_type` | string | 是 | `player_sect` / `guild` / `family` |
|
||
| `name` | string | 是 | 组织名 |
|
||
| `region_id` | uuid | 否 | 驻地地域（帮派/门派） |
|
||
| `founding_members` | []uuid | 否 | 创始成员（帮派/家族） |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"guild_id": "g-uuid-1001",
|
||
"name": "白虎堂",
|
||
"org_type": "guild",
|
||
"leader_id": "c-uuid-101",
|
||
"level": 1,
|
||
"member_limit": 50,
|
||
"created_at": "2026-06-30T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：7001（名称重复/不合法）、7002（创建者境界不足）、7003（已加入同类型组织）、7004（创始成员条件不足）
|
||
|
||
**限流**：5 次/小时。
|
||
|
||
---
|
||
|
||
#### 3.6.2 获取组织信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 查询组织基础信息、成员、建筑、仓库概览 |
|
||
| REST | `GET /api/v1/guilds/{guild_id}` |
|
||
| gRPC | `rpc GetOrganization (OrgIdReq) returns (OrgResp)` |
|
||
|
||
**限流**：60 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.6.3 加入/退出组织
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 申请加入或主动退出；系统门派退出有 3 现实天冷却与纯度惩罚（GDD-07 ✅T1） |
|
||
| REST | `POST /api/v1/guilds/{guild_id}/members`（加入） / `DELETE /api/v1/guilds/{guild_id}/members/me`（退出） |
|
||
| gRPC | `rpc JoinOrganization (OrgMemberReq) returns (OrgMemberResp)` / `rpc LeaveOrganization (OrgIdReq) returns (OrgMemberResp)` |
|
||
|
||
**错误码**：7005（组织不存在）、7006（不满足加入条件）、7007（退出冷却中）、7008（组织领主不可直接退出）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.6.4 管理成员权限
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 帮主/掌门/长老调整成员职位、踢出成员 |
|
||
| REST | `PUT /api/v1/guilds/{guild_id}/members/{character_id}` |
|
||
| gRPC | `rpc UpdateMemberRole (UpdateRoleReq) returns (OrgMemberResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `role` | string | 是 | `leader` / `vice` / `elder` / `member` / `disciple_manager` |
|
||
| `action` | string | 是 | `promote` / `demote` / `kick` |
|
||
|
||
**错误码**：7009（权限不足）、7010（目标职位不可操作）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.6.5 发起关系请求（道侣/结义/师徒）
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 向目标玩家发起道侣/结义/师徒请求；目标在线时实时推送，离线保留 48 游戏小时 |
|
||
| REST | `POST /api/v1/relations/{relation_type}/requests` |
|
||
| gRPC | `rpc SendRelationRequest (RelationReq) returns (RelationResp)` |
|
||
|
||
**relation_type**：`lover` / `sworn_brother` / `master` / `apprentice` / `enemy`
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `target_character_id` | uuid | 是 | 目标角色 |
|
||
| `vow_path` | string | 否 | 道侣誓约路径 |
|
||
|
||
**错误码**：7011（目标不存在）、7012（关系类型互斥）、7013（冷却中）、7014（目标已拒绝 5 次/天）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.6.6 响应关系请求
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 接受/拒绝/解除关系 |
|
||
| REST | `POST /api/v1/relations/{relation_type}/requests/{request_id}/respond` |
|
||
| gRPC | `rpc RespondRelationRequest (RelationResponseReq) returns (RelationResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `action` | string | 是 | `accept` / `reject` / `dissolve` |
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.6.7 发布佣兵委托
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 在佣兵大厅发布普通/限时委托；悬赏委托单独接口 |
|
||
| REST | `POST /api/v1/contracts` |
|
||
| gRPC | `rpc PublishContract (PublishContractReq) returns (ContractResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `contract_type` | string | 是 | `mercenary` / `limited_time` |
|
||
| `difficulty` | int | 是 | 1~6 星 |
|
||
| `currency_code` | string | 是 | 报酬货币 |
|
||
| `base_reward` | decimal | 是 | 基础报酬 |
|
||
| `target_params` | object | 否 | 讨伐/护送/采集目标 |
|
||
| `valid_until` | string | 否 | 有效期 |
|
||
|
||
**错误码**：7015（委托类型非法）、7016（报酬货币与层级不匹配）、7017（发布者信用等级过低）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.6.8 接取佣兵委托
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 个人/组队/派遣弟子接取委托；悬赏委托单独接取 |
|
||
| REST | `POST /api/v1/contracts/{contract_id}/accept` |
|
||
| gRPC | `rpc AcceptContract (AcceptContractReq) returns (ContractResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `accept_type` | string | 是 | `personal` / `party` / `disciple` |
|
||
| `disciple_id` | uuid | 否 | 弟子代派时必填 |
|
||
| `party_members` | []uuid | 否 | 组队接取时必填 |
|
||
|
||
**错误码**：7018（委托不存在）、7019（接取条件不足）、7020（已达每日接单上限）、7021（弟子不可用）
|
||
|
||
**限流**：20 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.6.9 发布悬赏
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 发布私人悬赏或报官悬赏（GDD-13） |
|
||
| REST | `POST /api/v1/bounties` |
|
||
| gRPC | `rpc PublishBounty (PublishBountyReq) returns (BountyResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `bounty_type` | string | 是 | `official_bounty` / `private_bounty` |
|
||
| `target_character_id` | uuid | 是 | 目标 |
|
||
| `reward_amount` | decimal | 是 | 悬赏金 |
|
||
| `currency_code` | string | 是 | 按目标层级货币 |
|
||
| `valid_days` | int | 否 | 1/3/7 游戏天 |
|
||
| `is_anonymous` | bool | 否 | 私人悬赏匿名 |
|
||
|
||
**错误码**：7022（目标不可悬赏）、7023（报官次数已达每日上限）、7024（同一目标私人悬赏上限 5 条）、7025（悬赏金低于最低标准）
|
||
|
||
**限流**：5 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.6.10 接取悬赏
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 接取悬赏令，进入追杀流程 |
|
||
| REST | `POST /api/v1/bounties/{bounty_id}/accept` |
|
||
| gRPC | `rpc AcceptBounty (BountyIdReq) returns (BountyResp)` |
|
||
|
||
**错误码**：7026（悬赏不存在/已过期）、7027（接取人数已满）、7028（24h 内不可重复接取同一目标）、7029（猎人威望封禁中）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
### 3.7 地图/副本
|
||
|
||
#### 3.7.1 获取区域信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 查询当前所在地域/小区域信息、PVP 规则、资源密度、当前天候 |
|
||
| REST | `GET /api/v1/world/regions/{region_id}` |
|
||
| gRPC | `rpc GetRegion (RegionReq) returns (RegionResp)` |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"region_id": "reg-uuid-2001",
|
||
"world_tier": 2,
|
||
"name": "焚骨荒原",
|
||
"is_safe_zone": false,
|
||
"pvp_rules": { "enabled": true, "karma_coefficient": 1.0 },
|
||
"weather": "blood_moon",
|
||
"resource_density": 3,
|
||
"danger_level": 3,
|
||
"nearby_player_count": 28
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：8001（区域不存在）、8002（未解锁该区域）
|
||
|
||
**限流**：60 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.7.2 查询附近玩家与事件
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 获取附近约 30 位玩家与当前区域正在进行的事件标记（GDD-08 ✅D17 / GDD-22） |
|
||
| REST | `GET /api/v1/world/regions/{region_id}/nearby` |
|
||
| gRPC | `rpc GetNearby (NearbyReq) returns (NearbyResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `limit` | int | 否 | 默认 30 |
|
||
| `event_types` | []string | 否 | 过滤事件类型 |
|
||
|
||
**限流**：30 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.7.3 进入副本/遗迹
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 进入随机副本/常驻副本/破界遗迹；校验境界、钥匙、次数、组队条件 |
|
||
| REST | `POST /api/v1/instances/{instance_id}/enter` |
|
||
| gRPC | `rpc EnterInstance (EnterInstanceReq) returns (InstanceRunResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `party_members` | []uuid | 否 | 队员 |
|
||
| `consumable_key_id` | uuid | 否 | 副本钥匙实例 ID |
|
||
| `use_stamina` | bool | 否 | 是否用体力替代钥匙 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"run_id": "run-uuid-3001",
|
||
"instance_id": "ins-uuid-3002",
|
||
"status": "in_progress",
|
||
"difficulty_coefficient": 1.15,
|
||
"consumed_keys": 1,
|
||
"started_at": "2026-06-30T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：8003（副本不存在/未开放）、8004（境界不足）、8005（次数已达上限）、8006（缺少钥匙/体力）、8007（队伍平均境界差距过大）、8008（SAN 低于进入阈值，混沌副本）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.7.4 查询世界事件
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 拉取当前层级/区域可参与的随机事件、玩家发起事件、世界异象（GDD-22） |
|
||
| REST | `GET /api/v1/world/events` |
|
||
| gRPC | `rpc ListWorldEvents (WorldEventReq) returns (WorldEventListResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `world_tier` | int | 否 | 默认当前层级 |
|
||
| `region_id` | uuid | 否 | 默认当前区域 |
|
||
| `event_scope` | string | 否 | `personal` / `regional` / `global` |
|
||
|
||
**限流**：30 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.7.5 发起玩家事件
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 消耗道具发起秘境/悬赏/护法/仪式等玩家事件，广播给同区域/势力玩家（GDD-22 4.4） |
|
||
| REST | `POST /api/v1/world/events` |
|
||
| gRPC | `rpc PublishPlayerEvent (PlayerEventReq) returns (WorldEventResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `event_type` | string | 是 | `summon_instance` / `seek_protection` / `ritual` / `bounty` / `sell_intel` |
|
||
| `region_id` | uuid | 是 | 事件所在区域 |
|
||
| `cost_items` | []object | 否 | 消耗道具 |
|
||
| `description` | string | 否 | 玩家自定义描述 |
|
||
|
||
**错误码**：8009（事件类型非法）、8010（道具不足）、8011（该区域禁止此类事件）
|
||
|
||
**限流**：10 次/分钟。
|
||
|
||
---
|
||
|
||
### 3.8 弟子/领地
|
||
|
||
#### 3.8.1 派遣弟子
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 将弟子派遣到自建门派资源点、帮派领地、历练点或佣兵委托；同一弟子同一时间只能在一个地点（GDD-07） |
|
||
| REST | `POST /api/v1/disciples/{disciple_id}/dispatch` |
|
||
| gRPC | `rpc DispatchDisciple (DispatchReq) returns (DiscipleMissionResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `target_type` | string | 是 | `private_sect` / `guild_territory` / `training` / `contract` |
|
||
| `target_id` | uuid | 是 | 目标 ID |
|
||
| `duration_minutes` | int | 是 | 派遣时长 |
|
||
| `insurance_item_id` | uuid | 否 | 保险道具 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"mission_id": "dm-uuid-4001",
|
||
"disciple_id": "d-uuid-4002",
|
||
"target_type": "guild_territory",
|
||
"started_at": "2026-06-30T12:00:00Z",
|
||
"ended_at": "2026-06-30T18:00:00Z",
|
||
"status": "dispatched"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：9001（弟子不存在）、9002（弟子状态不可用）、9003（目标不存在）、9004（派遣时长超过剩余配额）、9005（帮派领地派遣超过弟子总数 1/2）
|
||
|
||
**限流**：20 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.8.2 领取弟子/领地产出
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 结算并领取已完成的弟子委托或帮派领地产出 |
|
||
| REST | `POST /api/v1/missions/{mission_id}/claim` |
|
||
| gRPC | `rpc ClaimMissionOutput (MissionIdReq) returns (MissionRewardResp)` |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"mission_id": "dm-uuid-4001",
|
||
"result": "success",
|
||
"rewards": {
|
||
"currency": [{ "currency_code": "spirit_stone_low", "amount": 120 }],
|
||
"items": [{ "item_id": "iron_ore", "quantity": 8 }],
|
||
"events": [{ "type": "disciple_insight", "detail": "棍法熟练度+8%" }]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：9006（委托未结束）、9007（已领取）、9008（弟子死亡/叛逃）
|
||
|
||
**限流**：30 次/分钟。
|
||
|
||
---
|
||
|
||
#### 3.8.3 帮派领地竞标
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 功能 | 帮派对领地进行暗标出价；每周五 20:00 开放 48 小时窗口（GDD-07 ✅T2） |
|
||
| REST | `POST /api/v1/guilds/{guild_id}/territories/bids` |
|
||
| gRPC | `rpc BidTerritory (TerritoryBidReq) returns (TerritoryBidResp)` |
|
||
|
||
**请求参数**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `territory_id` | uuid | 是 | 目标领地 |
|
||
| `bid_amount` | decimal | 是 | 出价（帮派资金） |
|
||
| `is_renewal` | bool | 否 | 是否为优先续标 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"bid_id": "tb-uuid-5001",
|
||
"territory_id": "ter-uuid-5002",
|
||
"bid_amount": 25000,
|
||
"deposit_locked": 2500,
|
||
"window_end_at": "2026-07-02T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**：9009（非竞标窗口期）、9010（帮派资金不足）、9011（出价低于底价）、9012（已达持有领地数量上限）、9013（无权代表帮派出价）
|
||
|
||
**限流**：5 次/分钟。
|
||
|
||
---
|
||
|
||
## 4. WebSocket / 实时推送
|
||
|
||
### 4.1 连接方式
|
||
|
||
客户端通过 Nakama Realtime Socket（WebSocket + Protobuf）建立长连接，连接时携带与 HTTP/gRPC 相同的 `Authorization: Bearer <token>`。
|
||
|
||
```text
|
||
wss://nakama.honghuang.example.com/ws
|
||
```
|
||
|
||
连接成功后，服务端将角色加入以下频道/订阅：
|
||
|
||
| 频道/Topic | 格式 | 说明 |
|
||
|------------|------|------|
|
||
| 区域频道 | `region:{world_tier}:{region_id}` | 同区域玩家聊天与系统广播 |
|
||
| 种族方言频道 | `race:{race_id}:layer0` | 仅炼气期出生地可见 |
|
||
| 洪荒共通语频道 | `common:{world_tier}` | 层1+ 跨种族频道 |
|
||
| 势力频道 | `org:{guild_id}` | 门派/帮派/家族频道，跨区常驻 |
|
||
| 个人事件流 | `events:{character_id}` | 个人离线/在线遭遇、弟子归来、市场异动 |
|
||
| 战斗频道 | `battle:{battle_id}` | PVP/PVE 结算通知、战报就绪 |
|
||
| 社交频道 | `social:{character_id}` | 关系请求、道侣护法、帮派召集 |
|
||
|
||
### 4.2 推送消息格式
|
||
|
||
```protobuf
|
||
message RealtimePush {
|
||
string trace_id = 1;
|
||
string channel = 2;
|
||
string event_type = 3; // 例如 region_broadcast / battle_settled / social_request
|
||
bytes payload = 4; // 按 event_type 对应的 protobuf 序列化
|
||
int64 server_ts = 5; // 服务端时间戳（毫秒）
|
||
}
|
||
```
|
||
|
||
### 4.3 典型推送场景
|
||
|
||
#### 4.3.1 区域广播
|
||
|
||
事件：玩家破界、稀有资源刷新、世界 BOSS 出现、势力领地易主。
|
||
|
||
```json
|
||
{
|
||
"event_type": "region_broadcast",
|
||
"channel": "region:2:reg-uuid-2001",
|
||
"payload": {
|
||
"broadcast_level": "regional",
|
||
"title": "天降异火",
|
||
"content": "焚骨荒原出现天降异火，火系材料产出提升 50%，剩余 2 游戏小时。",
|
||
"expires_at": "2026-06-30T14:00:00Z",
|
||
"marker": { "type": "resource", "region_id": "reg-uuid-2001" }
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4.3.2 事件触发
|
||
|
||
事件：灵气异动、弟子顿悟、心魔来袭、奇遇 NPC 出现（GDD-22）。
|
||
|
||
```json
|
||
{
|
||
"event_type": "encounter_triggered",
|
||
"channel": "events:c-uuid-101",
|
||
"payload": {
|
||
"encounter_id": "enc-uuid-6001",
|
||
"encounter_type": "ancient_ghost",
|
||
"title": "古修残魂",
|
||
"options": [
|
||
{ "id": "ask", "text": "询问" },
|
||
{ "id": "seize", "text": "夺舍" },
|
||
{ "id": "ignore", "text": "超度" }
|
||
],
|
||
"timeout_seconds": 120
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4.3.3 战斗结算
|
||
|
||
事件：PVP 战书被接受/拒绝、PVE/PVP 战斗完成、战报生成。
|
||
|
||
```json
|
||
{
|
||
"event_type": "battle_settled",
|
||
"channel": "battle:b-uuid-506",
|
||
"payload": {
|
||
"battle_id": "b-uuid-506",
|
||
"result": "attacker_win",
|
||
"winner_id": "c-uuid-101",
|
||
"honor_points": 30,
|
||
"report_ready": true,
|
||
"death_penalty_applied": false
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4.3.4 社交动态
|
||
|
||
事件：关系请求、道侣护法请求、帮派召集、师徒传功结果。
|
||
|
||
```json
|
||
{
|
||
"event_type": "social_request",
|
||
"channel": "social:c-uuid-101",
|
||
"payload": {
|
||
"request_id": "req-uuid-7001",
|
||
"relation_type": "lover",
|
||
"from_character": { "id": "c-uuid-102", "name": "青鸾" },
|
||
"action_required": "accept_or_reject",
|
||
"expires_at": "2026-07-02T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.4 离线消息补偿
|
||
|
||
玩家断线期间，以下消息按优先级进入 Valkey 离线队列（`offline:{character_id}`），上限 200 条，上线后按时间顺序推送：
|
||
|
||
1. 战斗结算、悬赏/追杀结果、死亡惩罚
|
||
2. 关系请求、帮派召集、道侣护法
|
||
3. 市场交易/拍卖成交、弟子归来
|
||
4. 区域广播（仅保留最近 20 条）
|
||
|
||
---
|
||
|
||
## 5. 安全与幂等
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| 传输加密 | 全链路 HTTPS/WSS/TLS 1.3 |
|
||
| 请求签名 | 高敏感写操作（交易、出价、悬赏）要求客户端对请求体做 HMAC-SHA256 签名，密钥由 Nakama session 派生 |
|
||
| 幂等控制 | 所有扣费/扣材料/创建资源的写接口要求 `idempotency_key`；服务端以 `character_id + idempotency_key` 去重 24h |
|
||
| 越界校验 | 网关按 `player:{id}:realm` 缓存路由，拦截跨境界非法请求 |
|
||
| 防重放 | Token 绑定会话，异常时间戳/Sequence 差值过大拒绝 |
|
||
|
||
---
|
||
|
||
## 6. 与关联文档的接口映射
|
||
|
||
| 关联文档 | 本接口设计承接点 |
|
||
|----------|------------------|
|
||
| TDD-00 | 协议选型、Nakama 认证、Nacos 配置热更、网关路由 |
|
||
| TDD-04 | 字段命名与表结构对齐：`characters`、`character_manuals`、`market_orders`、`auctions`、`disciples`、`instances` 等 |
|
||
| GDD-03 | 战斗接口完全服务端权威；ATB 战报字段与 `battle_logs.report` 结构一致 |
|
||
| GDD-04 | 功法升层、加持切换、磨合期、顿悟待触发状态 |
|
||
| GDD-06 | 货币分层、交易行结算货币限制、天机阁情报购买上限、税率 |
|
||
| GDD-07 | 四组织（门派/帮派/家族/自建门派）统一用 `guilds` 资源；功法玉简消耗 40% 熟练度；领地竞标周期 |
|
||
| GDD-13 | 佣兵委托三种接取方式、悬赏双轨制、信用等级、保险道具 |
|
||
| GDD-14 | 拍卖双轨制、保证金、防狙击延时、追杀令、天罚标记 |
|
||
| GDD-16 | 道侣/结义/师徒/仇敌关系请求与解除；家族技能触发条件由客户端本地校验，服务端在组队副本结算时验证 |
|
||
| GDD-18 | 副本/遗迹进入校验钥匙、次数、动态难度；破界遗迹广播 |
|
||
| GDD-22 | 区域事件查询、玩家发起事件、离线信息流、遭遇气泡推送 |
|
||
| PRD-01/02/03 | 需求边界与验收标准来源；PRD-02 境界隔离在网关层实现；PRD-03 热更参数通过 Nacos 下发，不在本接口清单重复定义 |
|
||
|
||
---
|
||
|
||
## 7. 验收标准（接口层）
|
||
|
||
| # | 验收条目 | 测试方法 |
|
||
|---|----------|----------|
|
||
| 1 | 所有接口携带无效/过期 Nakama token 时返回 401，业务码 1002 | 使用过期 token 调用 GET/POST 样例接口 |
|
||
| 2 | 同一 `idempotency_key` 重复调用突破/渡劫/购买接口，第二次返回 9004 且不重复扣资源 | 连续两次相同 key 请求 |
|
||
| 3 | 炼气期角色请求进入层2 区域时返回 403/8002，并提示「尚未破界」 | 构造越界请求 |
|
||
| 4 | PVP 挑战跨 `realm_tier` 时返回 4007；每日免费 5 次用尽后返回 4009 | 跨境界请求与次数mock |
|
||
| 5 | 交易行使用铜钱/银两作为结算货币时返回 6002 | 非法货币请求 |
|
||
| 6 | 玉简来源技能调用生成玉简接口返回 5011；独属技能跨族学习返回 5012 | 不同来源标签技能测试 |
|
||
| 7 | 帮派领地竞标在非窗口期调用返回 9009 | 时间mock |
|
||
| 8 | WebSocket 断线重连后，离线期间的关键消息（战斗/悬赏/关系请求）按优先级补推 | 断线mock + 消息回放 |
|
||
|
||
---
|
||
|
||
## 8. 版本记录
|
||
|
||
| 版本 | 日期 | 修订内容 | 作者 |
|
||
|------|------|----------|------|
|
||
| 1.0 | 2026-06-30 | 初始版本：协议总览、8 大类 35+ 接口定义、错误码/限流、WebSocket 推送、安全与验收标准 | Kimi Code CLI |
|
||
|
||
---
|
||
|
||
*本文档数值/阈值均引用 GDD-21《数值平衡与联调参数总表》与 Nacos 动态配置，服务端实现时以运行时配置为准，不硬编码。*
|
