lawless/docs/技术文档/TDD-05-API接口设计.md

# TDD-05 API接口设计

> 文档类型：技术设计文档（Technical Design Document）
> 版本：1.2
> 日期：2026-07-06
> 关联文档：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,
    "energy_current": 5000,
    "energy_cap": 5000,
    "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",
    "energy_current": 38500000,
    "energy_cap": 42000000,
    "energy_cap_ceiling": 50000000,
    "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": "筑基期·中期",
    "energy_cap": 42000000,
    "energy_cap_ceiling": 50000000,
    "max_unlocked_world_tier": 2,
    "realm_status": "normal",
    "breakthrough_ready": false,
    "tribulation_pending": false,
    "enlightenment_triggered": 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_energy` | 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 |
| 1.1 | 2026-07-06 | 术语对齐：use_stamina→use_energy、"体力"相关字段改为"能量"（MiMoCode，补记此前未同步的版本号） | MiMoCode |
| 1.2 | 2026-07-06 | 同步✅158能量模型：角色创建/详情/境界进度响应示例移除level/exp字段，改为energy_current/energy_cap/energy_cap_ceiling；境界进度响应新增enlightenment_triggered（顿悟触发状态）字段 | Claude |

---

*本文档数值/阈值均引用 GDD-21《数值平衡与联调参数总表》与 Nacos 动态配置，服务端实现时以运行时配置为准，不硬编码。*