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

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

---

## 1. 需求背景

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

1. **固定副本**（常驻/轮换的资源与挑战副本，GDD-18 §三）；
2. **随机世界事件**（外神入侵、天材地宝、妖兽潮等，GDD-22 §四）；
3. **玩家发起事件**（消耗道具/资源开启秘境、召唤帮派 Boss、举行仪式等，GDD-22 §4.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 字段**：

```json
{
  "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 差分包机制

1. 服务端按版本维护完整 `project.manifest`；CDN 同时存放按 Bundle 切分的压缩包（`.zip`/`.zip.*`）。
2. 客户端比对本地与远程 `assets` 字典，生成 **Added / Modified / Deleted** 列表。
3. 优先下载 Bundle 级差异：若某 Bundle 内任一文件变更，则下载该 Bundle 的整包差分（避免万级小文件逐个请求）。
4. 支持断点续传、失败重试、CDN 自动切换。
5. 下载完成后按文件 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 核心约束——无任务系统、无赛季重置、概率/机遇驱动、降低官方存在感。所有活动内容均通过固定副本、随机世界事件、玩家发起事件与破界分红自然轮换；官方仅提供规则、基础设施、反作弊与动态调参能力。