Skip to main content

副本、扫荡与宝箱

0. 本篇结论​

本功能定义副本、扫荡与宝箱的功能定位、玩家流程、核心规则、UI 状态、配置与系统边界；本次整理状态为 draft；原声明为 producer_review_needed / canonical_candidate，不提升为批准规则。

整理来源与事实层级（WEN-12 draft）​

  • 固定来源：project2-docs@ec43be0e13c8624cfafd36c0fd803f3b89733fff 的 features/instance.md、feature-map.md、manifest.yaml；原审核状态均为 producer_review_needed / canonical_candidate。
  • §5.1～5.2 是原文报告的接口/注释线索，不是批准规则；§4 及§6 是目标流程和 UI 候选，不能因存在协议/模型而宣布可挑战或已废弃。
  • 已确认基线仅指固定文档路径、原声明及既有规则编号；原件与逐条产品批准记录缺证，不能将其转成“已确认产品规则”。本轮未读取游戏实现、配置或运行版本，当前版本是否上线全部待定。
  • 边界：副本只整理挑战、扫荡、星级、宝箱、次数与状态接口。主线全服首通候选在 排行榜集中记录，副本不承担首通规则或发奖责任。通用战斗、胜负与结算权威归 战斗关卡（B1-D），具体关卡内容归关卡库。
  • 来源登记、两侧证据、影响与用户决定点见 玩法整理台账，对应 B1E-Q05、Q06。后文验收为候选检查项，本轮未执行游戏验收。

1. 功能定位​

副本系统是主线关卡之外的挑战、扫荡、星级、宝箱和 Boss/材料产出玩法候选。原文报告注册后端保留协议、角色快照字段、处理逻辑路由和 role model，同时核心业务逻辑大面积注释或返回错误，历史归类为“后端预留/暂未开放功能”；该报告未绑定后端 SHA，不证明当前版本状态，不能按已上线完整玩法使用。

2. 范围​

In Scope：副本主页数据、副本类型、开始副本、挑战结算、扫荡、宝箱领取、每日次数、星级、Boss 伤害字段、role instance 持久化结构。

Out of Scope：全服首通、领地掠夺、主线战斗结算、具体副本 UI 接入、完整 Boss 机制。全服首通只在迁移资料 中观察到，不纳入本迁移资料 权威范围。

3. 玩家入口、解锁与提示​

候选入口应位于主界面、玩法入口或活动入口。副本类型可按玩家等级、主线进度、活动时间或配置开放。迁移资料未确认独立副本功能目录；迁移资料 也未开放完整逻辑，因此入口和开放条件需制作人确认。

4. 核心玩家流程​

  1. 玩家打开副本主页，查看副本类型、关卡、次数、宝箱和进度。
  2. 玩家选择副本并发起开始请求。
  3. 玩家完成战斗后提交胜负、星级或伤害。
  4. 后端校验是否可挑战、是否可扫荡、是否可领取宝箱。
  5. 后端发放奖励并更新副本数据。
  6. 客户端刷新副本主页、红点和奖励展示。

以上流程是目标流程；迁移资料显示并未完整实现该闭环。

5. 核心规则​

5.1 历史文档所述接口状态（未绑定后端 SHA）​

  • INSTANCE-R-001：InstanceMain 原文报告可返回 roleTmp.GetRoleInstance().Instance。
  • INSTANCE-R-002：InstanceStart 原文报告直接返回 InstanceStart Error。
  • INSTANCE-R-003：InstanceChallenge 原文报告直接返回 InstanceChallenge Error。
  • INSTANCE-R-004：InstanceSweep 原文报告直接返回 InstanceSweep Error。
  • INSTANCE-R-005：InstanceRewardBox 原文报告直接返回 InstanceRewardBox Error。

5.2 历史文档所述保留逻辑与配置状态​

  • INSTANCE-R-006：service/role/model/instance/entity.go 中挑战、扫荡、宝箱、红点等逻辑大多被注释保留。
  • INSTANCE-R-007：gameconfig/config.go 中 InstanceCfg 构建被注释，gameconfig/instancecfg/instance.go 也以注释逻辑为主。

5.3 正式上线前确认​

  • INSTANCE-R-008：若要正式上线，需要重新确认配置源、处理逻辑 逻辑、客户端入口和测试覆盖。

5.4 操作矩阵​

N/A。当前不在策划案正文中复述核心玩家流程；进入 PLAN 时，仅对状态变化、消耗/产出、奖励发放、跨系统反馈或失败反馈补齐操作矩阵。

6. UI 状态与交互​

6.1 界面图与交互说明​

N/A。当前未从迁移草稿中映射到界面图片；如后续涉及 UI 改动，应补充界面图、线框图或参考图。

6.2 页面结构与交互​

UI 需要副本类型页签、关卡列表、剩余次数、开始按钮、扫荡按钮、星级条件、宝箱节点、奖励预览、失败原因和红点。由于当前后端未开放，UI 设计必须明确展示哪些状态来自服务端，避免客户端假设可挑战。

6.3 UI 页面状态表​

N/A。当前仅保留已绑定页面/状态的参考图和页面结构说明；具体可执行状态在 UI 评审或 UI brief 中确认。

7. 配置、数据与 Contract​

本节只记录策划案需要的逻辑数据与跨部门 contract，不预设物理配置表、协议文件、service 文件或 仓库落点。正式命名、字段名、接口名、协议对象名、文件名和仓库落点进入执行前由 Work Package 的 contract-registry.yaml、execution brief 和对应执行任务确认。

7.1 策划数据需求​

策划数据需求只描述逻辑数据域、逻辑字段或规则语义，不等同于配置表字段名、协议字段名或数据库字段名。正式字段命名进入 contract-registry.yaml、execution brief 和对应执行任务确认。

数据域逻辑字段 / 规则设计含义必填 / 边界产出责任
副本基础规则副本 ID、阶段、开放条件、挑战消耗、扫荡条件、红点规则定义副本入口、章节、阶段、挑战和扫荡条件进入执行前补齐默认值、边界和可选性Planning
副本奖励规则奖励组、宝箱条件、防重复领取、每日/周期限制定义挑战奖励、扫荡奖励和宝箱奖励进入执行前补齐默认值、边界和可选性Planning
正式上线确认项配置源、入口、挑战逻辑、扫荡逻辑、宝箱逻辑、测试覆盖定义当前预留功能转正式功能前必须补齐的内容进入执行前补齐默认值、边界和可选性Planning / 服务端 / 客户端

7.2 运行时数据与接口需求​

Contract设计含义使用方说明
副本状态数据保存副本进度、挑战记录、扫荡状态和宝箱状态服务端 / 客户端当前候选显示多处业务逻辑仍需正式确认
副本操作接口处理主页、开始、挑战、扫荡和宝箱领取服务端 / 客户端错误返回不能作为正式上线行为
红点与入口刷新根据可挑战、可扫荡和可领奖状态刷新入口服务端 / 客户端需要定义正式计算方式

7.3 跨部门 Contract 命名清单​

Contract 类型逻辑对象命名状态阻塞阶段说明
配置数据副本、阶段、挑战、扫荡、宝箱和红点待 PLAN 确认PLAN 前不预设物理配置表名
协议 / API副本主页、开始、挑战、扫荡、宝箱领取待 PLAN 确认执行前由服务端 / UI brief 确认
错误码副本未开放、挑战失败、扫荡不可用、宝箱不可领取待 PLAN 确认执行前需要玩家提示
资源引用副本入口、章节图、宝箱图标和扫荡表现待 PLAN 确认执行前由美术 / UI brief 确认

8. 系统边界​

方向负责内容备注
Planning逻辑数据、数值、文本需求、资源需求进入执行前由 PL 任务细化
服务端协议、校验、持久化、奖励发放、幂等与安全仅相关功能需要
客户端UI、交互、表现、本地状态、红点和跳转仅相关功能需要
美术图标、模型、特效、音频和导出资源仅相关功能需要
Ops / GM后台配置、运营投放、公告、补偿和数据看板仅相关功能需要

客户端与表现​

当前资料未确认独立副本入口。若该功能继续推进，需要确认副本入口、UI、红点、战斗入口和奖励展示。

美术与音频需求​

需要副本入口图标、副本类型图标、关卡节点、星级图标、宝箱图标、Boss 或材料副本表现、扫荡反馈和奖励领取反馈。当前 art 资料不足。

9. 数值、经济与奖励​

候选数值包括副本开放条件、每日挑战次数、扫荡次数、材料产出、星级奖励、Boss 伤害奖励和宝箱奖励。注册后端当前没有启用完整 InstanceCfg，因此不能从注册后端确认实际奖励和消耗规则。

10. 异常、安全与运营边界​

10.1 异常与安全​

正式实现必须处理客户端伪造胜利、伪造伤害、重复扫荡、重复宝箱、次数并发扣减、战斗开始超时、配置缺失、跨日重置和奖励重复发放。当前注册后端通过直接返回错误阻止了大部分业务路径。

10.2 埋点与运营​

建议记录副本打开、开始、挑战结果、失败原因、扫荡、宝箱领取、次数不足、配置缺失和后端拒绝原因。后端未开放期间，埋点也应标注功能未启用状态。

11. Feature Relations 与回归范围​

Feature Relations​

依赖 battle-mission、item-resource、player-level-energy-power-privilege、main-entry-red-dot。可能影响 task、ranking 和 activity-timeopen。

回归范围​

以 Feature Relations 影响功能、核心玩家流程、配置与系统边界为基础；进入执行前由 PLAN / QA brief 细化最小回归范围。

12. 验收标准​

12.1 关键验收结论​

在当前状态下，验收标准是：副本文档不得宣称功能已完整上线；若进入开发，必须先补配置源确认、后端 处理逻辑 解注释/重写、客户端入口、测试和奖励验收。正式上线后再验收主页、开始、结算、扫荡、次数、宝箱和红点闭环。

12.2 规则验收清单​

规则文本统一在§5维护；以下仅保留编号作为候选验收引用，不另存一份规则，也不代表验收已通过。

  • INSTANCE-R-001：核对§5同编号规则的候选行为与边界。
  • INSTANCE-R-002：核对§5同编号规则的候选行为与边界。
  • INSTANCE-R-003：核对§5同编号规则的候选行为与边界。
  • INSTANCE-R-004：核对§5同编号规则的候选行为与边界。
  • INSTANCE-R-005：核对§5同编号规则的候选行为与边界。
  • INSTANCE-R-006：核对§5同编号规则的候选行为与边界。
  • INSTANCE-R-007：核对§5同编号规则的候选行为与边界。
  • INSTANCE-R-008：核对§5同编号规则的候选行为与边界。

12.3 执行层验收​

  • 如填写操作矩阵，成功路径、失败场景、玩家反馈和状态权威均已覆盖。
  • 如填写 UI 页面状态表，页面 / 弹窗状态均已覆盖，或明确标记为 N/A。
  • Section 7 中标记为 PLAN 前或执行前阻塞的 contract 已在 contract-registry.yaml、execution brief 或执行任务中确认。
  • 相关 Feature Relations 回归通过。

13. 待澄清问题 / Open Questions​

  • 副本是否为当前版本正式功能、后端预留功能，还是已废弃功能。
  • 配置源表和 planning 相关负责人ship 需要确认。
  • 客户端副本入口是否存在于未扫描或未注册路径。
  • 是否仍需要全服首通；迁移资料显示未发现 全服首通协议/API 或对应 处理逻辑。

14. 变更记录​

日期版本修改人变更摘要
2026-10-13WEN-12 draftAutoDev Symphony保留原审核声明；补充来源/层级/玩法边界及待定台账；规则验收改为编号引用，移除尾部重复空图段
2026-06-16v0.2Codex补充规则编号、操作矩阵、UI 状态表、逻辑字段和执行层验收锚点
2026-06-16v0.1Codex按新版功能策划案模板重排章节；保留既有规则内容并映射参考图