徐勤民 f4c6b0ea1d Initial commit: 洪荒大陆设计文档+代码骨架

2026-07-02 16:55:34 +08:00

48 KiB

原始文件 Blame 文件历史

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 后台、支付回调、数据埋点	游戏逻辑服 ↔ 结算服、战斗模拟服、配置中心推送

基地址示例

RESTful 网关：  https://api.honghuang.example.com
游戏 gRPC：     grpcs://game.honghuang.example.com
Nakama 实时：   wss://nakama.honghuang.example.com

2.2 认证方式

所有接口（除显式标注「公开」外）均需在请求头携带 Nakama 颁发的 Session Token。

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 统一响应格式

{
  "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	防止刷号

响应头示例：

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	否	邀请码，用于统计

响应示例

{
  "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`，当前版本固定为出生地

响应示例

{
  "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	否	是否携带战斗属性快照

响应示例

{
  "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)`

响应示例

{
  "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	是	客户端唯一键，防止重复扣材料

响应示例

{
  "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	否	护法者

响应示例

{
  "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)`

响应示例

{
  "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	是	二次确认，防止误操作

响应示例

{
  "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 排序

响应示例

{
  "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)`

响应示例（节选）

{
  "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	否	是否消耗灵石购买额外次数

响应示例

{
  "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

响应示例

{
  "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	是	幂等键

响应示例

{
  "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	否	是否替换同槽位旧加持

响应示例

{
  "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	否	天品+/唯一技能可自定义名

响应示例

{
  "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` 限制

响应示例

{
  "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)`

响应示例

{
  "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 游戏小时

响应示例

{
  "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	是	购买数量

响应示例

{
  "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	否	自动出价上限

响应示例

{
  "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	否	创始成员（帮派/家族）

响应示例

{
  "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)`

响应示例

{
  "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	否	是否用体力替代钥匙

响应示例

{
  "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	否	保险道具

响应示例

{
  "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)`

响应示例

{
  "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	否	是否为优先续标

响应示例

{
  "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>。

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 推送消息格式

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 出现、势力领地易主。

{
  "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）。

{
  "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 战斗完成、战报生成。

{
  "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 社交动态

事件：关系请求、道侣护法请求、帮派召集、师徒传功结果。

{
  "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 条，上线后按时间顺序推送：

战斗结算、悬赏/追杀结果、死亡惩罚
关系请求、帮派召集、道侣护法
市场交易/拍卖成交、弟子归来
区域广播（仅保留最近 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 动态配置，服务端实现时以运行时配置为准，不硬编码。

48 KiB 原始文件 Blame 文件历史 Unescape Escape

TDD-05 API接口设计

1. 文档信息

2. 协议总览

2.1 RESTful 与 gRPC 的分工

2.2 认证方式

2.3 统一响应格式

2.4 错误码规范

2.5 限流策略

3. 接口分类与清单

3.1 账号/角色

3.1.1 注册（公开）

3.1.2 登录（公开）

3.1.3 创建角色

3.1.4 获取角色状态

3.2 修炼/境界

3.2.1 获取境界进度

3.2.2 尝试突破

3.2.3 发起渡劫

3.2.4 查询渡劫结果

3.2.5 破界（晋级新世界）

3.3 战斗

3.3.1 发起战斗

3.3.2 查询战报

3.3.3 PVP 挑战

3.4 功法/技能

3.4.1 获取功法列表

3.4.2 功法升层

3.4.3 设置加持功法

3.4.4 学习技能

3.4.5 生成功法玉简

3.5 经济/背包

3.5.1 获取货币余额

3.5.2 交易行挂单

3.5.3 交易行撤单

3.5.4 交易行购买

3.5.5 查询拍卖列表

3.5.6 拍卖出价

3.5.7 查询天机阁情报

3.5.8 购买情报

3.6 社交

3.6.1 创建组织

3.6.2 获取组织信息

3.6.3 加入/退出组织

3.6.4 管理成员权限

3.6.5 发起关系请求（道侣/结义/师徒）

3.6.6 响应关系请求

3.6.7 发布佣兵委托

3.6.8 接取佣兵委托

3.6.9 发布悬赏

3.6.10 接取悬赏

3.7 地图/副本

3.7.1 获取区域信息

3.7.2 查询附近玩家与事件

3.7.3 进入副本/遗迹

3.7.4 查询世界事件

3.7.5 发起玩家事件

3.8 弟子/领地

3.8.1 派遣弟子

3.8.2 领取弟子/领地产出

3.8.3 帮派领地竞标

4. WebSocket / 实时推送

4.1 连接方式

4.2 推送消息格式

4.3 典型推送场景

4.3.1 区域广播

4.3.2 事件触发

4.3.3 战斗结算

4.3.4 社交动态

4.4 离线消息补偿

5. 安全与幂等

6. 与关联文档的接口映射

7. 验收标准（接口层）

8. 版本记录

48 KiB

原始文件 Blame 文件历史