PRD-03 热更新与活动系统需求文档¶

文档类型：产品需求文档（Product Requirements Document）
版本：v1.1
日期：2026-07-06
关联文档：TDD-00《挂机手游技术栈方案.md》、GDD-06《经济系统设计》、GDD-08《大陆地图与区域开放系统》、GDD-18《世界地图副本遗迹生成引擎》、GDD-22《开放世界随机事件与玩家可交互内容层》、GDD-21《数值平衡与联调参数总表》、PRD-01《核心玩法与系统需求文档》、PRD-02《境界隔离系统需求文档》

1. 需求背景¶

《洪荒大陆》不做赛季重置，也不通过官方任务链驱动内容。世界节奏由四类来源共同构成：

固定副本（常驻/轮换的资源与挑战副本，GDD-18 §三）；
随机世界事件（外神入侵、天材地宝、妖兽潮等，GDD-22 §四）；
玩家发起事件（消耗道具/资源开启秘境、召唤帮派 Boss、举行仪式等，GDD-22 §4.4）；
天启分红（高境界玩家天启后，原门派/帮派不可携带资源转为阵营/帮派每日分红，GDD-06 §13.5 / GDD-08 §3.8）。

为了在不发版的前提下持续轮换上述内容、快速修正经济/战斗参数、响应线上异常，必须同时具备：

客户端热更新能力：基于 Cocos Creator 3.x Asset Bundle + CDN，覆盖活动 UI、战报文案、事件配置、资源等；
服务器动态参数能力：基于 Nacos 配置中心，对战斗、经济、事件、地图等关键参数进行热更，无需停服。

核心设计约束来源：PRD-01（无赛季/无任务系统/概率机遇驱动）、GDD-06 §13.5（活动轮换原则）、GDD-22（开放世界随机事件层）、TDD-00 §2.3/§3.5（Asset Bundle 热更 / Nacos 配置中心）。

2. 客户端热更新¶

2.1 热更范围¶

类型	可热更内容	不可热更内容（必须整包/商店发版）
Asset Bundle	活动玩法 UI 与逻辑脚本、战报文案/i18n、事件配置表、场景/地图资源、图集、音效、角色立绘	引擎版本升级、原生插件/SDK 变更、操作系统权限配置、核心网络协议版本变更
配置 JSON	数值配置（掉落、技能生成参数、事件权重）、活动开关、版本号	客户端底层协议结构不兼容变更
H5 小程序活动	通过 WebView 加载的 H5 活动页、运营页面	WebView 容器本身版本

来源：TDD-00 §2.3；GDD-18 §7.1（权重/掉落配置可热更）。

2.2 版本号与 Manifest¶

版本号规则：主版本.次版本.热更版本.资源版本，例如 1.2.3.4。

位	含义	触发场景
主版本	大版本/商业资料片	整包发版
次版本	中型玩法/系统上线	整包或大型 Bundle 发版
热更版本	脚本/逻辑/配置热更	Asset Bundle 热更即可
资源版本	纯美术/音效/文案替换	Asset Bundle 热更即可

Manifest 字段：

{
  "packageUrl": "https://cdn.example.com/bundles/",
  "remoteManifestUrl": "https://cdn.example.com/project.manifest",
  "remoteVersionUrl": "https://cdn.example.com/version.manifest",
  "version": "1.2.3.4",
  "minEngineVersion": "3.8.0",
  "assets": {
    "bundles/event_summer": { "md5": "a1b2c3", "size": 2048, "compressed": true },
    "config/event_pool.json": { "md5": "d4e5f6", "size": 12 }
  },
  "searchPaths": ["hotupdate"],
  "signature": "base64(RSA-SHA256)"
}

客户端本地保存 project.manifest；启动时拉取远程 version.manifest 做快速比对；有差异时再拉完整 project.manifest。
Manifest 必须带服务端私钥签名，客户端用内置公钥校验，防止篡改/中间人攻击。

2.3 差分包机制¶

服务端按版本维护完整 project.manifest；CDN 同时存放按 Bundle 切分的压缩包（.zip/.zip.*）。
客户端比对本地与远程 assets 字典，生成 Added / Modified / Deleted 列表。
优先下载 Bundle 级差异：若某 Bundle 内任一文件变更，则下载该 Bundle 的整包差分（避免万级小文件逐个请求）。
支持断点续传、失败重试、CDN 自动切换。
下载完成后按文件 MD5/SHA-256 校验；校验不通过则重试，最多 3 次后标记失败。

2.4 灰度策略¶

维度	说明
分组灰度	按账号 hash、设备 ID、渠道包、地区、测试白名单分组
百分比灰度	通过 Nacos 配置 `hotupdate.gray.{version}.percent` 控制，例如 5% → 20% → 100%
频道隔离	保留 `test` / `staging` / `production` 三套 manifest/CDN 路径，互不干扰
强制/屏蔽	可对特定用户段强制推送或强制屏蔽某版本

灰度期间实时监控崩溃率、启动失败率、校验失败率；任一指标超过阈值自动暂停灰度并触发回滚。

2.5 回滚策略¶

自动回滚：客户端应用新 Bundle 后，若连续 2 次启动异常（崩溃/校验失败/关键接口报错），自动回退到上一版本备份。
手动回滚：运营后台通过 Nacos 设置 hotupdate.rollback_target=1.2.3.3，客户端拉取到该标记后跳过新版本并恢复旧 manifest。
双版本备份：客户端本地保留当前版本与上一稳定版本两份资源，回滚无需重新下载。
服务端回滚：服务器侧关闭新活动入口/新配置，确保旧版本客户端仍可正常游戏。

2.6 异常处理¶

异常	处理策略
下载失败	自动重试 3 次、切换 CDN、延迟到 Wi-Fi 环境继续；最终失败提示玩家稍后重试
校验失败	重下对应文件 → 仍失败则回滚
存储不足	计算所需空间并提示清理；允许玩家跳过非紧急资源（低优先级音频/图集）
网络中断	断点续传；恢复后从断点继续下载
版本不兼容	若 `minEngineVersion` 高于当前引擎，跳转商店强制整包更新
Manifest 签名失败	禁止应用，上报安全告警

3. 服务器动态参数（Nacos）¶

3.1 配置项分类¶

分类	示例参数	影响范围	来源
经济 economy	`economy.faucet.travel.rare_event_rate`、 `economy.faucet.afk.output_rate`、 `economy.tax.trade_rate`、 `economy.exchange.rate_fluctuation_max`、 `economy.sink.repair.cost_rate`	产出/消耗/税率/汇率	GDD-06 §14.3
战斗 combat	`combat.atb.tick_ms`、 `combat.damage.formula.`、 `combat.element.reaction.`、 `combat.cap.crit`、 `combat.cap.dodge`	ATB 节奏、伤害公式、元素反应、硬顶	GDD-03 / GDD-21
事件 event	`event.world.trigger_interval`、 `event.world.weights.`、 `event.player_initiated.costs.`、 `event.破界遗迹.generation_rate`、 `event.encounter.cooldown`	随机事件触发频率/权重、玩家发起事件成本、遗迹生成概率	GDD-18 / GDD-22
地图 map	`map.cross_layer.cost_rate`、 `map.降维护佑.damage_cap`、 `map.layer_unlock.realm_tier`、 `map.realm_tier.pvp_rule`	跨层代价、降维护佑、地图准入	GDD-08 / PRD-02

所有数值最终以 GDD-21《数值平衡与联调参数总表》为准，PRD-03 不另起炉灶。

3.2 热更触发流程¶

运营后台编辑配置 → 审批流（双人确认）→ 发布到 Nacos
    → Nakama / Gin 服务监听配置变更
    → 本地配置快照原子替换
    → 写变更审计日志
    → 向在线客户端推送配置版本号（WS 广播或响应头）
    → 客户端按需拉取新配置

变更生效不重启服务；战斗公式等关键参数使用不可变快照，避免运行时读到中间态。
配置变更后全服公告（视影响范围而定，如税率/产出倍率变更需公告）。

3.3 版本一致性¶

机制	说明
服务端配置版本	Nacos 中维护 `server.config.version`（如 `20260630-001`），每次发布递增
客户端携带版本	客户端每次请求附带 `X-Config-Version`；服务端发现低于当前版本时，在响应中返回最新完整配置或强制刷新指令
实例一致性	所有 Nakama/Gin 实例通过 Nacos 长轮询监听同一 `dataId`；告警监控各实例当前配置版本，发现 skew 立即告警
审计与追溯	配置变更记录保存操作人、变更原因、旧值、新值、生效时间、关联 Git commit hash

3.4 安全与兜底¶

合法性校验：Nacos 配置发布前经 JSON Schema + 数值范围校验，非法配置拒绝发布并保留旧值。
紧急回滚：运营后台一键回滚到上一个稳定配置版本；客户端在 10 秒内收到旧版本号。
默认值：服务启动时加载本地默认配置兜底；Nacos 不可用时继续服务并告警。

4. 随机事件系统¶

4.1 事件池维护¶

事件池按作用域与类型维护，支持服务端配置热更与客户端 Asset Bundle 文案热更：

事件类型	作用域	示例	维护方式
个人遭遇	单玩家	灵气异动、心魔来袭、古修残魂、顿悟征兆	配置表 + 客户端文案 Bundle
区域事件	同区域/同层	天材地宝出世、妖兽异动、副本入口刷新	服务端事件池配置
世界事件	全服	外神入侵、神兽现世、灵气潮汐	服务端事件池配置
玩家发起事件	全服/区域	召唤秘境、帮派 Boss、仪式召集、悬赏追杀	玩家消耗 + 服务端校验

事件池条目包含：ID、触发条件、权重、冷却、 layer 限制、参与人数上限、奖励池、分支/链式后续事件。

4.2 触发与刷新¶

时间刷新：以现实时间 08:00 为每日基准（GDD-02 ✅87），重置个人/区域事件冷却。
行为触发：游历、挂机、突破、交易、PVP 等行为按概率触发对应事件。
世界事件调度：服务端调度器按权重随机抽取，通过 Kafka 广播给所有在线玩家，并在「世界脉动」面板展示（GDD-22 §4）。
防重复：同类型事件对同一玩家/区域有现实时间冷却；同区域同时存在世界事件数量上限防止信息过载。

4.3 玩家发起事件¶

入口	触发条件	消耗	广播与参与
地图面板「召唤秘境」	持有对应道具、达到 layer/境界	道具 + 货币（sink）	区域广播，其他玩家可进入；超过时限或人数上限后入口关闭
帮派「召唤帮派 Boss」	帮派资金/权限	帮派资金 + 材料	帮派/势力频道广播，成员可参与
仪式召集	道侣/结义/师徒关系	关系值 + 道具	关系链广播
发布悬赏	持有货币	赏金 + 平台抽成	佣兵大厅/世界脉动展示（GDD-13）

所有消耗必须服务端校验，防止客户端篡改。
玩家发起事件产生的奖励/风险由事件设计决定，不得凭空创造官方增发资源。

4.4 事件链与分支¶

部分事件具备多阶段状态机：例如「外神入侵」分为「征兆 → 降临 → 抵御 → 封印/失控」四阶段，玩家/社区选择影响下一阶段事件池与奖励。
分支状态存储于 PostgreSQL + Valkey，支持跨玩家协作/竞争。
事件链中的选择结果对参与玩家分别结算，稀有分支受概率与玩家机缘属性影响。

4.5 事件奖励¶

奖励类型：货币/材料、技能玉简/拓本、稀有线索、情报凭证、声望、称号/外观。
奖励严格按事件触发层级与参与玩家境界投放，高境界玩家进入低层级事件时适用跨境界产出衰减（GDD-06 §13.2）。
具体数值引用 GDD-21；奖励概率与倍数可通过 Nacos 热更。

5. 活动轮换¶

5.1 无赛季原则¶

不存在官方赛季重置、段位清空、排行榜清零。
活动内容随时间自然轮换，玩家进度、领地、称号、资源永久保留。

5.2 四类活动来源¶

来源	说明	周期/触发	运营干预方式
固定副本	常驻副本 + 主题副本轮换（如「百炼塔」「古战场」）	每日/每周进入次数限制（GDD-18 §7.3.3）	Nacos 调整掉落倍率、次数、主题
随机世界事件	外神入侵、天材地宝、妖兽潮等	服务端按权重随机触发	Nacos 调整权重、间隔、奖励倍率
玩家发起事件	玩家消耗资源开启秘境/Boss/仪式	由玩家行为驱动	Nacos 调整消耗、冷却、参与上限
天启分红	高境界玩家天启后，原门派/帮派资源转为阵营/帮派每日分红	长期持续	Nacos 调整分红比例与上限

5.3 活动日历¶

服务端维护一个「活动日历」服务，将上述四类来源合并为玩家可见的近期动态：

固定副本按日/周排程；
随机世界事件按概率预告（如「近日洪荒边境灵气躁动」暗示事件发生概率上升）；
玩家发起事件实时加入日历；
天启分红按日发放并展示。

运营可通过 GM 后台在不发版的情况下调整活动日历权重与参数。

6. 数据埋点¶

6.1 经济监控¶

指标	用途	来源
各货币日净产出/消耗比	识别通胀/通缩	GDD-06 §14.1
交易行均价趋势	识别操纵/洗钱	GDD-06 §14.1
死亡修复 sink / 总 faucet	验证高惩罚经济回收	GDD-06 §14.1
鸿蒙紫气净增发/充值额	监控偷渡补贴	GDD-06 §7.2

6.2 事件参与度¶

指标	用途
各类型事件触发次数、参与人次、完成率	评估事件吸引力
玩家发起事件数 / 成功率 / 参与转化率	评估玩家驱动内容健康度
事件分支选择分布	验证分支设计
世界事件对在线时长/留存影响	验证世界事件价值

6.3 热更成功率¶

指标	用途
manifest 拉取成功率、下载成功率、校验成功率	验证热更链路
版本覆盖率 / 版本 adoption 曲线	验证灰度效果
热更后崩溃率 / 回滚率	验证版本质量
灰度组与全量组关键指标对比	验证灰度安全

7. 非功能性需求¶

类别	需求	备注
兼容性	客户端保持对至少前两个 manifest 版本的向后兼容；服务端配置 schema 升级时旧字段保留默认值	避免强制更新造成用户流失
可回滚	客户端与服务端均可在 5 分钟内回滚到上一稳定版本/配置	自动 + 手动双保险
灰度策略	支持百分比、分组、地区、渠道多维度灰度；可随时暂停/全量/回退	来源 TDD-00 §2.3
监控告警	Prometheus/Grafana 监控热更成功率、Nacos 配置版本一致性、事件参与度、经济指标；P0 告警：热更失败率 > 5%、配置版本 skew > 1%、异常经济波动 > 50%
安全	Manifest 与资源签名、传输 HTTPS/WSS、Nacos 鉴权、客户端公钥内置、防篡改校验
性能	启动热更检查 P99 < 3s；普通 Bundle 差分包下载 P99 < 30s；服务端配置全局生效 P99 < 10s
审计	所有配置变更、活动开关、灰度调整记录操作人/原因/旧值/新值	满足运营合规

8. 验收标准¶

#	验收条目	测试方法
1	客户端启动时能在 3 秒内完成 manifest 比对，并仅下载变更的 Asset Bundle 差分包	抓包/日志统计下载文件数与耗时；验证未变更文件不再下载
2	Manifest 被篡改或签名不匹配时，客户端拒绝应用新资源并触发告警	替换 CDN 上 manifest 签名，观察客户端是否拦截并上报
3	Nacos 修改 `economy.faucet.afk.output_rate` 后，服务端在 10 秒内生效，且所有 Nakama/Gin 实例配置版本一致	修改参数后调用各实例接口返回的配置版本号，检查是否一致
4	灰度发布新版本后，仅指定百分比/分组用户进入新版本，其余用户保持旧版本；灰度期间崩溃率超过阈值自动暂停	构造灰度计划，抽样用户版本号；模拟新版本崩溃样本观察是否自动回滚
5	玩家发起「召唤秘境」事件时，服务端校验道具/货币消耗后才生成入口，并在区域频道与世界脉动广播	尝试客户端篡改消耗数量，验证服务端拒绝；检查广播与入口生成
6	高境界玩家参与低层级世界事件时，奖励按跨境界衰减规则结算，不会破坏低层经济	记录不同境界角色参与同一事件的产出，核对衰减系数
7	热更失败（下载/校验/应用失败）后，客户端能自动回滚到上一稳定版本并正常进入游戏	模拟 CDN 返回错误文件/断网，观察回滚与启动结果
8	事件系统每日 08:00 重置个人/区域冷却，且同类型事件在冷却期内不会重复触发同一玩家	调整系统时间/等待刷新，验证冷却逻辑

9. 版本记录¶

版本	日期	修订内容	作者
v1.0	2026-06-30	初始版本：客户端热更新、服务器动态参数、随机事件系统、活动轮换、数据埋点、非功能需求与验收标准	Kimi Code CLI

设计原则重申：本文档继承 PRD-01 核心约束——无任务系统、无赛季重置、概率/机遇驱动、降低官方存在感。所有活动内容均通过固定副本、随机世界事件、玩家发起事件与天启分红自然轮换；官方仅提供规则、基础设施、反作弊与动态调参能力。