1465 行
53 KiB
Markdown
1465 行
53 KiB
Markdown
# TDD-06 离线挂机结算系统设计
|
||
|
||
> 文档类型：技术设计文档（Technical Design Document）
|
||
> 版本：1.1
|
||
> 日期：2026-07-02
|
||
> 关联文档：TDD-04《数据库表结构设计》、TDD-05《API接口设计》、GDD-03《战斗系统设计》、GDD-06《经济系统设计》、GDD-07《帮派门派社交系统设计》、GDD-22《开放世界随机事件》、GDD-23《能量体系与功法相性设计》
|
||
|
||
---
|
||
|
||
## 1. 文档信息
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 目标 | 为《洪荒大陆》挂机手游定义离线挂机结算系统的服务端技术方案，覆盖离线时间快进、资源批量结算、ATB战斗离线结算、弟子代挂、游历事件触发、上线结算面板等核心模块。 |
|
||
| 读者 | 服务端开发（Nakama/Go）、数值策划、测试 |
|
||
| 技术栈 | Nakama 3.x + Go插件 + PostgreSQL 16 + Valkey + Nacos 2.x |
|
||
| 核心约束 | 无任务系统、无赛季重置、概率/机遇驱动、文字战报、ATB行动条、功法加持、能量体系（非体力） |
|
||
| 游戏时间 | 现实:游戏 = 1:3 |
|
||
|
||
---
|
||
|
||
## 2. 系统总览
|
||
|
||
### 2.1 离线结算的核心循环
|
||
|
||
```
|
||
玩家下线
|
||
↓
|
||
记录 last_online_at + 当前状态快照
|
||
↓
|
||
服务端定时任务扫描离线玩家（每 5 分钟）
|
||
↓
|
||
时间快进算法：计算离线期间的事件队列
|
||
↓
|
||
批量结算：资源产出 / 弟子代挂 / 游历事件 / 战斗
|
||
↓
|
||
生成结算结果 JSON（压缩存储到 Valkey）
|
||
↓
|
||
玩家上线
|
||
↓
|
||
拉取结算结果 → 展示结算面板 → 应用状态变更到 DB
|
||
```
|
||
|
||
### 2.2 设计原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| **服务端权威** | 所有离线结算逻辑在服务端完成，客户端只负责展示结算面板 |
|
||
| **延迟结算** | 离线期间只记录事件队列，玩家上线时才批量执行结算（减少 DB 写入压力） |
|
||
| **时间快进** | 离线时间按游戏时间 1:3 换算后，以固定步长快进模拟事件触发 |
|
||
| **幂等性** | 结算结果带版本号，重复登录不会重复结算 |
|
||
| **上限兜底** | 背包满/货币上限/弟子异常等边界情况在结算时统一处理 |
|
||
|
||
---
|
||
|
||
## 3. 离线期间事件触发的服务端模拟逻辑
|
||
|
||
### 3.1 时间快进算法
|
||
|
||
离线期间不实时模拟，而是玩家上线时通过"时间快进"算法一次性计算离线期间的所有事件。
|
||
|
||
```
|
||
算法：OfflineTimeWarp(character_id, last_online_at, now)
|
||
|
||
输入：
|
||
last_online_at — 玩家最后在线时间（timestamptz）
|
||
now — 当前时间（timestamptz）
|
||
|
||
输出：
|
||
event_queue — 离线期间触发的事件列表
|
||
|
||
步骤：
|
||
1. 计算离线时长（现实时间）
|
||
offline_duration_real = now - last_online_at
|
||
offline_duration_game = offline_duration_real × 3 // 现实:游戏 = 1:3
|
||
|
||
2. 限制最大离线结算时长（按境界递增，防止超长离线导致结算爆炸）
|
||
max_offline_hours = 按角色境界动态确定（见下方境界递增表）
|
||
if offline_duration_real > max_offline_hours:
|
||
offline_duration_real = max_offline_hours
|
||
offline_duration_game = max_offline_hours × 3
|
||
|
||
境界递增离线上限表：
|
||
炼气期 → 72 现实小时（默认基准，约3天）
|
||
筑基期 → 96 现实小时（约4天）
|
||
金丹期 → 120 现实小时（约5天，新默认上限）
|
||
元婴期及以上 → 无上限（完全离线结算，不限制时长）
|
||
|
||
// 通过 Nacos 配置可覆盖：
|
||
// offline.max_settle_hours.default = 120（默认上限，金丹期）
|
||
// offline.max_settle_hours.qi_refining = 72
|
||
// offline.max_settle_hours.foundation = 96
|
||
// offline.max_settle_hours.golden_core = 120
|
||
// offline.max_settle_hours.nascent_soul = 0（0表示无上限）
|
||
|
||
3. 确定时间步长（tick_interval）
|
||
// 每个 tick 代表一段游戏时间，期间可能触发 0~N 个事件
|
||
tick_interval_game = 1 游戏小时 // 可通过 Nacos 配置
|
||
|
||
4. 加载玩家离线前状态快照
|
||
snapshot = load_character_snapshot(character_id)
|
||
// 包含：境界、属性、装备、功法、弟子列表、当前挂机状态
|
||
|
||
5. 加载区域事件池
|
||
zone_events = load_zone_event_pool(snapshot.zone_id, snapshot.world_tier)
|
||
// 来自 GDD-22 的区域事件配置
|
||
|
||
6. 时间快进循环
|
||
current_game_time = last_online_at × 3 // 转为游戏时间
|
||
end_game_time = now × 3
|
||
event_queue = []
|
||
|
||
while current_game_time < end_game_time:
|
||
// 6a. 检查定时触发事件
|
||
for event in zone_events:
|
||
if event.trigger_type == "periodic":
|
||
if current_game_time % event.period == 0:
|
||
event_queue.append(Event(event, current_game_time))
|
||
|
||
// 6b. 概率触发事件（游历/挂机遭遇）
|
||
for event in zone_events:
|
||
if event.trigger_type == "probability":
|
||
roll = random(0, 1)
|
||
// 概率衰减：连续触发同类事件时概率递减
|
||
decay = get_fatigue_decay(character_id, event.category)
|
||
effective_rate = event.base_rate × decay
|
||
if roll < effective_rate:
|
||
event_queue.append(Event(event, current_game_time))
|
||
|
||
// 6c. 弟子代挂事件检查
|
||
for disciple in snapshot.disciples:
|
||
if disciple.status == "dispatched":
|
||
disciple_tick_result = simulate_disciple_tick(disciple, current_game_time)
|
||
event_queue.append(disciple_tick_result)
|
||
|
||
// 6d. 推进时间
|
||
current_game_time += tick_interval_game
|
||
|
||
7. 返回 event_queue
|
||
```
|
||
|
||
### 3.2 事件队列结构
|
||
|
||
```go
|
||
type OfflineEvent struct {
|
||
EventID string `json:"event_id"`
|
||
EventType string `json:"event_type"` // combat / gather / disciple / encounter / resource
|
||
TriggerTime int64 `json:"trigger_time"` // 游戏时间戳
|
||
ZoneID string `json:"zone_id"`
|
||
WorldTier int `json:"world_tier"`
|
||
RealmTier int `json:"realm_tier"`
|
||
Payload map[string]interface{} `json:"payload"` // 事件特定数据
|
||
Resolved bool `json:"resolved"` // 是否已结算
|
||
Result map[string]interface{} `json:"result"` // 结算结果
|
||
}
|
||
```
|
||
|
||
### 3.3 事件队列回放
|
||
|
||
```go
|
||
// 玩家上线时调用
|
||
func SettleOfflineEvents(characterID string) (*SettlementReport, error) {
|
||
// 1. 加载事件队列
|
||
events := loadEventQueue(characterID)
|
||
|
||
// 2. 按时间顺序回放
|
||
report := &SettlementReport{CharacterID: characterID}
|
||
for _, event := range events {
|
||
if event.Resolved {
|
||
continue // 已结算跳过（幂等）
|
||
}
|
||
|
||
switch event.EventType {
|
||
case "combat":
|
||
result := resolveOfflineCombat(event)
|
||
report.Battles = append(report.Battles, result)
|
||
case "gather":
|
||
result := resolveOfflineGather(event)
|
||
report.Resources = append(report.Resources, result)
|
||
case "disciple":
|
||
result := resolveDiscipleEvent(event)
|
||
report.DiscipleEvents = append(report.DiscipleEvents, result)
|
||
case "encounter":
|
||
result := resolveEncounter(event)
|
||
report.Encounters = append(report.Encounters, result)
|
||
}
|
||
|
||
event.Resolved = true
|
||
saveEventResult(event)
|
||
}
|
||
|
||
// 3. 批量应用状态变更
|
||
applySettlementToDatabase(report)
|
||
|
||
// 4. 压缩存储结算报告
|
||
saveCompressedReport(characterID, report)
|
||
|
||
return report, nil
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 离线产出计算公式
|
||
|
||
### 4.1 挂机资源产出（接入 GDD-06 经济参数）
|
||
|
||
离线挂机产出遵循 GDD-06 §5.3 的"单位时间/风险期望产出参考"。
|
||
|
||
```
|
||
离线挂机资源产出公式：
|
||
|
||
base_output = zone_base_rate × realm_multiplier × game_hours
|
||
actual_output = base_output × quality_modifier × fatigue_decay × facility_bonus
|
||
|
||
参数说明：
|
||
zone_base_rate — 当前区域基础产出率（来自 GDD-08-附录A）
|
||
realm_multiplier — 境界倍率（炼气 1.0 / 筑基 1.5 / 金丹 2.5 / 元婴 4.0 / 化神 6.5 / 合体 10.0）
|
||
game_hours — 离线游戏时长（现实小时 × 3）
|
||
quality_modifier — 弟子/装备品质修正（1.0~2.5）
|
||
fatigue_decay — 疲劳衰减系数（连续挂机同一区域，每游戏小时 -5%，最低 0.3）
|
||
facility_bonus — 门派/领地设施加成（1.0~2.2）
|
||
```
|
||
|
||
**接入 GDD-06 各境界产出基线**：
|
||
|
||
| 境界 | 1 游戏小时基础产出 | 离线挂机上限（现实 24h） |
|
||
|------|-------------------|------------------------|
|
||
| 炼气期 | 3~6 铜钱 或 低品灵石碎片×0.2 | 216~432 铜钱 |
|
||
| 筑基期 | 15~30 铜钱 或 灵石×0.3~0.5 | 1080~2160 铜钱 |
|
||
| 金丹期 | 灵石（中品）×0.4~0.8 | 28.8~57.6 中品灵石 |
|
||
| 元婴期 | 魂晶/仙晶碎片×0.3~0.6 | 21.6~43.2 碎片 |
|
||
| 化神期 | 仙晶×0.2~0.4 | 14.4~28.8 仙晶 |
|
||
| 合体期 | 仙晶（上品）×0.15~0.3 | 10.8~21.6 上品仙晶 |
|
||
|
||
### 4.2 弟子代挂产出（接入 GDD-07 弟子系统）
|
||
|
||
```
|
||
弟子代挂产出公式：
|
||
|
||
disciple_output = base_output × disciple_quality × race_match × skill_match × guild_facility
|
||
|
||
参数说明：
|
||
base_output — 同 §4.1 的区域基础产出
|
||
disciple_quality — 弟子品质系数（凡品 0.8 / 良品 1.0 / 优品 1.3 / 极品 1.8 / 仙品 2.5）
|
||
race_match — 种族匹配系数（地精挖矿 1.3 / 矮人锻造 1.2 / 其他 1.0）
|
||
skill_match — 生活技能匹配系数（匹配 1.5 / 不匹配 1.0）
|
||
guild_facility — 门派设施等级加成（Lv1 1.0 / Lv2 1.2 / Lv3 1.45 / Lv4 1.8 / Lv5 2.2）
|
||
```
|
||
|
||
**弟子品质与产出对照表（GDD-07 §2.3.2）**：
|
||
|
||
| 品质 | 出现概率 | 效率加成 | 特殊能力 |
|
||
|------|---------|---------|---------|
|
||
| 凡品 | 55% | 80% | 无 |
|
||
| 良品 | 30% | 100% | 小幅降低意外率 |
|
||
| 优品 | 12% | 130% | 可学习一种生活技能加成 |
|
||
| 极品 | 2.8% | 180% | 有概率触发双倍产出 |
|
||
| 仙品 | 0.2% | 250% | 可独立触发小型奇遇 |
|
||
|
||
### 4.3 游历事件产出
|
||
|
||
```
|
||
游历事件产出公式：
|
||
|
||
explore_output = event_reward × risk_multiplier × time_efficiency × sect_bonus
|
||
|
||
参数说明：
|
||
event_reward — 事件基础奖励（来自 GDD-22 事件池配置）
|
||
risk_multiplier — 风险倍率（闲逛 1.0 / 历练 1.3 / 秘境 1.8 / 古迹 2.5 / 禁地 4.0）
|
||
time_efficiency — 时间效率（离线游历按实际游戏时长折算，非满效率）
|
||
sect_bonus — 系统门派游历加成（门派等级 × 2.5%，最高 25%）
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 离线 ATB 战斗结算（接入 GDD-03 战斗公式）
|
||
|
||
### 5.1 离线战斗触发条件
|
||
|
||
离线期间战斗由以下场景触发：
|
||
- 游历途中遭遇野怪/精英/Boss（GDD-03 §6）
|
||
- 弟子代挂遭遇战斗
|
||
- 被其他玩家 PVP 挑战（离线战书默认接受，GDD-03 ✅14）
|
||
|
||
### 5.2 服务端完整 ATB 战斗计算
|
||
|
||
离线战斗采用与在线战斗完全相同的 ATB 引擎，服务端一次性完整计算。
|
||
|
||
```go
|
||
// 离线ATB战斗结算（接入 GDD-03 §三 ATB 机制）
|
||
func SimulateOfflineBattle(attacker, defender *CombatUnit, context BattleContext) *BattleResult {
|
||
// 1. 初始化战斗状态
|
||
battle := &BattleState{
|
||
Units: []*CombatUnit{attacker, defender},
|
||
Tick: 0,
|
||
MaxTicks: 3000, // ✅10 战斗行动时间上限
|
||
MaxActions: 50, // ✅10 单方最多50次行动
|
||
}
|
||
|
||
// 2. 初始化行动条（先手/伏击判定）
|
||
// GDD-03 §3.1：普通遭遇双方初始 0；先手方初始 50
|
||
attacker.ATBGauge = context.AttackerInitGauge // 0 或 50
|
||
defender.ATBGauge = context.DefenderInitGauge // 0 或 50
|
||
|
||
// 3. 加载技能候选池
|
||
attacker.Skills = loadActiveSkills(attacker.CharacterID)
|
||
defender.Skills = loadActiveSkills(defender.CharacterID)
|
||
|
||
// 4. ATB 主循环
|
||
report := &BattleReport{Rounds: []RoundLog{}}
|
||
|
||
for battle.Tick < battle.MaxTicks {
|
||
battle.Tick++
|
||
|
||
// 4a. 行动条填充（GDD-03 §3.1）
|
||
for _, unit := range battle.Units {
|
||
if unit.HP > 0 {
|
||
increment := unit.Speed * 0.1 // ATB_BASE_COEFFICIENT = 0.1
|
||
unit.ATBGauge += increment
|
||
}
|
||
}
|
||
|
||
// 4b. 检查可行动单位
|
||
readyUnits := []*CombatUnit{}
|
||
for _, unit := range battle.Units {
|
||
if unit.ATBGauge >= 100 && unit.HP > 0 {
|
||
readyUnits = append(readyUnits, unit)
|
||
}
|
||
}
|
||
|
||
// 4c. 同 tick 满条冲突判定（GDD-03 §3.1）
|
||
if len(readyUnits) > 1 {
|
||
sort.Slice(readyUnits, func(i, j int) bool {
|
||
vi := readyUnits[i].Speed * (1 + randomFloat(-0.1, 0.1))
|
||
vj := readyUnits[j].Speed * (1 + randomFloat(-0.1, 0.1))
|
||
return vi > vj
|
||
})
|
||
}
|
||
|
||
// 4d. 逐个执行行动
|
||
for _, unit := range readyUnits {
|
||
target := getOpponent(battle, unit)
|
||
|
||
// 控制状态检查
|
||
if unit.HasStatus("stun") {
|
||
report.Rounds = append(report.Rounds, RoundLog{
|
||
Tick: battle.Tick, Actor: unit.ID,
|
||
Action: "stunned", Message: "眩晕中无法行动",
|
||
})
|
||
unit.ATBGauge = 0
|
||
continue
|
||
}
|
||
|
||
// 逃跑判定（GDD-03 §3.8 ✅32-✅34）
|
||
// 玩家预设血量/能量/SAN阈值，达到阈值后每次ATB满自动尝试逃跑
|
||
if unit.IsPlayer && shouldAttemptEscape(unit, context.EscapeConfig) {
|
||
escapeRate := calculateEscapeRate(unit, target, context)
|
||
if random(100) < escapeRate {
|
||
// 逃跑成功：本场战利品清零，无死亡惩罚
|
||
report.Rounds = append(report.Rounds, RoundLog{
|
||
Tick: battle.Tick, Actor: unit.ID,
|
||
Action: "escape_success", Message: "成功逃离战斗",
|
||
})
|
||
result := &BattleResult{
|
||
Winner: "escape",
|
||
EndCondition: "escape_success",
|
||
LootCleared: true, // ✅33 逃跑成功战利品清零
|
||
DeathPenalty: false, // ✅33 无死亡惩罚
|
||
}
|
||
report.Result = result
|
||
return result
|
||
} else {
|
||
// 逃跑失败：无惩罚，继续战斗
|
||
report.Rounds = append(report.Rounds, RoundLog{
|
||
Tick: battle.Tick, Actor: unit.ID,
|
||
Action: "escape_fail", Message: "逃跑失败",
|
||
})
|
||
unit.ATBGauge = 0
|
||
continue
|
||
}
|
||
}
|
||
|
||
// 技能选择（GDD-03 §3.3 ✅24 触发率机制）
|
||
skill := selectSkill(unit, target, battle)
|
||
|
||
// 命中判定
|
||
hitChance := 100 - target.DodgeRate + unit.HitBonus
|
||
if random(100) > hitChance {
|
||
report.Rounds = append(report.Rounds, RoundLog{
|
||
Tick: battle.Tick, Actor: unit.ID, Skill: skill.ID,
|
||
Action: "miss", Message: "身形一晃，闪过了攻击",
|
||
})
|
||
unit.ATBGauge = 0
|
||
continue
|
||
}
|
||
|
||
// 伤害计算（GDD-03 §2.2）
|
||
damage := calculateDamage(unit, target, skill, context)
|
||
|
||
// 暴击判定（GDD-03 §2.2 ✅18）
|
||
critRate := unit.Luck * 0.15 + skill.CritBonus
|
||
if critRate > 60 { critRate = 60 } // 上限60%
|
||
isCrit := random(100) < critRate
|
||
if isCrit {
|
||
critMultiplier := 1.5 // 基础×1.5
|
||
if critMultiplier > 2.0 { critMultiplier = 2.0 } // 上限×2.0
|
||
damage = damage * critMultiplier
|
||
}
|
||
|
||
// 应用伤害
|
||
target.HP -= damage
|
||
if target.HP < 0 { target.HP = 0 }
|
||
|
||
// 记录战报
|
||
report.Rounds = append(report.Rounds, RoundLog{
|
||
Tick: battle.Tick,
|
||
Actor: unit.ID,
|
||
Skill: skill.ID,
|
||
Damage: damage,
|
||
IsCrit: isCrit,
|
||
HPAfter: map[string]int{attacker.ID: attacker.HP, defender.ID: defender.HP},
|
||
})
|
||
|
||
// 行动条归零
|
||
unit.ATBGauge = 0
|
||
|
||
// 行动次数计数
|
||
unit.ActionCount++
|
||
if unit.ActionCount >= battle.MaxActions {
|
||
goto endBattle
|
||
}
|
||
|
||
// 死亡判定
|
||
if target.HP <= 0 {
|
||
goto endBattle
|
||
}
|
||
|
||
// 天赋触发判定（GDD-03 §4.2）
|
||
checkAndTriggerTalents(unit, target, battle, report)
|
||
}
|
||
|
||
// 4e. DOT/状态效果结算
|
||
processStatusEffects(battle, report)
|
||
|
||
// 4f. 战斗结束条件检查（GDD-03 §3.7）
|
||
if attacker.HP <= 0 || defender.HP <= 0 {
|
||
break
|
||
}
|
||
}
|
||
|
||
endBattle:
|
||
// 5. 判定胜负（GDD-03 §3.7 超时处理）
|
||
result := determineWinner(battle, context)
|
||
report.Result = result
|
||
|
||
return result
|
||
}
|
||
|
||
// 逃跑判定辅助函数（GDD-03 §3.8 ✅32-✅34）
|
||
|
||
// shouldAttemptEscape 判断是否应该尝试逃跑
|
||
func shouldAttemptEscape(unit *CombatUnit, config EscapeConfig) bool {
|
||
// 检查血量阈值
|
||
if config.HPThreshold > 0 {
|
||
hpPercent := float64(unit.HP) / float64(unit.MaxHP) * 100
|
||
if hpPercent <= config.HPThreshold {
|
||
return true
|
||
}
|
||
}
|
||
// 检查能量阈值
|
||
if config.EPThreshold > 0 {
|
||
epPercent := float64(unit.EP) / float64(unit.MaxEP) * 100
|
||
if epPercent <= config.EPThreshold {
|
||
return true
|
||
}
|
||
}
|
||
// 检查SAN阈值
|
||
if config.SANThreshold > 0 && unit.SAN > 0 {
|
||
if unit.SAN <= config.SANThreshold {
|
||
return true
|
||
}
|
||
}
|
||
return false
|
||
}
|
||
|
||
// calculateEscapeRate 计算逃跑成功率（GDD-03 §3.8.3 ✅34）
|
||
func calculateEscapeRate(escaper, chaser *CombatUnit, context BattleContext) float64 {
|
||
// 基础率：35%
|
||
baseRate := 35.0
|
||
|
||
// 速度差系数：己方速度/对方速度（上限2.0，下限0.5）
|
||
speedRatio := float64(escaper.Speed) / float64(chaser.Speed)
|
||
if speedRatio > 2.0 { speedRatio = 2.0 }
|
||
if speedRatio < 0.5 { speedRatio = 0.5 }
|
||
|
||
// 状态修正
|
||
statusMod := 1.0
|
||
if escaper.HasStatus("stun") || escaper.HasStatus("root") {
|
||
return 0 // 眩晕/定身无法逃跑
|
||
}
|
||
if escaper.HasStatus("slow") {
|
||
statusMod = 0.7
|
||
}
|
||
if escaper.HasStatus("haste") {
|
||
statusMod = 1.3
|
||
}
|
||
|
||
// 道具修正
|
||
itemMod := 1.0
|
||
if context.HasItem("escape_talisman") {
|
||
itemMod = 1.5
|
||
}
|
||
if context.HasItem("teleport_talisman") {
|
||
return 100 // 瞬移符直接成功
|
||
}
|
||
|
||
finalRate := baseRate * speedRatio * statusMod * itemMod
|
||
if finalRate > 100 { finalRate = 100 }
|
||
return finalRate
|
||
}
|
||
```
|
||
|
||
### 5.3 战斗伤害计算公式（接入 GDD-03 §2.2）
|
||
|
||
```go
|
||
// 物理伤害（GDD-03 §2.2）
|
||
func calculatePhysicalDamage(attacker, defender *CombatUnit, skill *Skill) float64 {
|
||
baseDamage := float64(attacker.Str)*1.0 + attacker.WeaponAtk // 攻击系数=1.0
|
||
skillDamage := baseDamage * skill.DamageCoeff
|
||
|
||
// 亲和度+共鸣修正（GDD-03 §4.4 ✅20）
|
||
affinityMod := 1.0 + skill.AffinityMod
|
||
resonanceMod := 1.0 + skill.ResonanceMod
|
||
skillDamage = skillDamage * affinityMod * resonanceMod
|
||
|
||
// 物理减伤率（GDD-03 §2.2）
|
||
defCoeff := 0.5
|
||
defConst := getDefenseConstant(defender.WorldTier) // Tier1:100 / Tier2:150 / ... / Tier6:640
|
||
phyReduce := float64(defender.Vit)*defCoeff / (float64(defender.Vit)*defCoeff + float64(defConst))
|
||
|
||
finalDamage := skillDamage * (1 - phyReduce)
|
||
|
||
// 阵营伤害修正（GDD-03 §2.3 ✅12）
|
||
alignmentMod := getAlignmentModifier(skill.Alignment, defender.Alignment)
|
||
finalDamage = finalDamage * alignmentMod
|
||
|
||
// 状态修正
|
||
finalDamage = finalDamage * attacker.StatusAtkMod
|
||
|
||
return math.Max(finalDamage, 1) // 最低1点伤害
|
||
}
|
||
|
||
// 法术伤害（GDD-03 §2.2）
|
||
func calculateMagicalDamage(attacker, defender *CombatUnit, skill *Skill) float64 {
|
||
baseDamage := float64(attacker.Spi)*1.0 + attacker.ArtifactAtk // 法攻系数=1.0
|
||
skillDamage := baseDamage * skill.DamageCoeff
|
||
|
||
// 亲和度+共鸣修正
|
||
affinityMod := 1.0 + skill.AffinityMod
|
||
resonanceMod := 1.0 + skill.ResonanceMod
|
||
skillDamage = skillDamage * affinityMod * resonanceMod
|
||
|
||
// 法术减伤率
|
||
magCoeff := 0.5
|
||
magConst := getDefenseConstant(defender.WorldTier) // 与防御常数一致
|
||
magReduce := float64(defender.Spi)*magCoeff / (float64(defender.Spi)*magCoeff + float64(magConst))
|
||
|
||
finalDamage := skillDamage * (1 - magReduce)
|
||
|
||
// 元素克制修正（GDD-03 §2.4 ✅19）
|
||
elementMod := getElementModifier(skill.Element, defender.Element)
|
||
finalDamage = finalDamage * elementMod
|
||
|
||
// 阵营伤害修正
|
||
alignmentMod := getAlignmentModifier(skill.Alignment, defender.Alignment)
|
||
finalDamage = finalDamage * alignmentMod
|
||
|
||
return math.Max(finalDamage, 1)
|
||
}
|
||
```
|
||
|
||
### 5.4 离线战斗性能优化
|
||
|
||
离线战斗与在线战斗共用同一套 ATB 引擎，但有以下优化：
|
||
|
||
| 优化项 | 说明 |
|
||
|--------|------|
|
||
| **跳过战报文案渲染** | 离线计算只生成结构化数据，不生成文字战报文案；文案在客户端展示时即时生成 |
|
||
| **批量预加载** | 一次性加载角色战斗快照 + 技能列表 + 天赋列表，减少 DB 查询 |
|
||
| **计算结果缓存** | 战斗结果缓存到 Valkey，上线时直接读取 |
|
||
| **异步结算** | 玩家上线时先返回"结算中"状态，后台 Goroutine 异步完成计算 |
|
||
|
||
### 5.5 离线战斗场景与惩罚对照（接入 GDD-03 §6.2）
|
||
|
||
| 战斗场景 | 失败惩罚 | 离线处理 |
|
||
|----------|---------|---------|
|
||
| 普通野怪战败 | 不触发死亡惩罚；产出 -60% | 事件标记为 `combat_loss_normal` |
|
||
| 精英怪战败 | 轻度死亡惩罚（进度 -10%） | 事件标记为 `combat_loss_elite`，应用轻度惩罚 |
|
||
| Boss 战败 | 完整死亡惩罚（进度 -20%~30% + 纯度 + 道伤） | 事件标记为 `combat_loss_boss`，应用完整惩罚 |
|
||
| PVP 失败 | 完整死亡惩罚 | 事件标记为 `pvp_loss`，应用完整惩罚 |
|
||
|
||
---
|
||
|
||
## 6. 离线上限与溢出处理
|
||
|
||
### 6.1 背包满处理
|
||
|
||
```go
|
||
// 离线产出溢出处理
|
||
func handleInventoryOverflow(characterID string, items []ItemDrop) {
|
||
inventory := loadInventory(characterID)
|
||
maxSlots := inventory.MaxSlots // 由境界/装备决定
|
||
|
||
for _, item := range items {
|
||
if inventory.UsedSlots >= maxSlots {
|
||
// 背包满：转入邮件系统
|
||
sendToMail(characterID, item, MailType_OfflineOverflow, "离线产出溢出")
|
||
continue
|
||
}
|
||
|
||
// 可堆叠物品尝试合并
|
||
if existing := inventory.FindStackable(item.ItemID); existing != nil {
|
||
remaining := existing.MaxStack - existing.Quantity
|
||
if remaining >= item.Quantity {
|
||
existing.Quantity += item.Quantity
|
||
} else {
|
||
existing.Quantity = existing.MaxStack
|
||
overflow := item.Quantity - remaining
|
||
sendToMail(characterID, Item{ItemID: item.ItemID, Quantity: overflow},
|
||
MailType_OfflineOverflow, "离线产出溢出")
|
||
}
|
||
} else {
|
||
inventory.AddItem(item)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 货币上限处理
|
||
|
||
```go
|
||
// 离线货币产出上限处理（接入 GDD-06 经济参数）
|
||
func handleCurrencyOverflow(characterID string, currencyCode string, amount decimal.Decimal) {
|
||
balance := loadCurrencyBalance(characterID, currencyCode)
|
||
maxBalance := getCurrencyMaxBalance(currencyCode) // 由 Nacos 配置
|
||
|
||
if balance.Amount + amount > maxBalance {
|
||
overflow := (balance.Amount + amount) - maxBalance
|
||
balance.Amount = maxBalance
|
||
|
||
// 溢出部分按比例折算为低一档货币或转入邮件
|
||
converted := convertOverflowCurrency(currencyCode, overflow)
|
||
if converted != nil {
|
||
addCurrency(characterID, converted.Code, converted.Amount)
|
||
}
|
||
} else {
|
||
balance.Amount += amount
|
||
}
|
||
|
||
// 写入经济审计日志（TDD-04 §5.4）
|
||
writeEconomyAudit(characterID, currencyCode, "faucet", "offline_settle", amount)
|
||
}
|
||
```
|
||
|
||
### 6.3 弟子状态异常处理
|
||
|
||
| 异常状态 | 处理方式 |
|
||
|----------|---------|
|
||
| 弟子死亡 | 标记 `status = "dead"`，记录 `died_at`，生成墓碑数据（GDD-07），不产出后续收益 |
|
||
| 弟子叛逃 | 标记 `status = "deserted"`，已产出保留，后续产出取消 |
|
||
| 弟子受伤 | 标记临时 debuff，产出效率 -30%~50%，持续 N 游戏小时 |
|
||
| 弟子顿悟 | 标记 `status = "insight"`，产出效率 +50%，持续 N 游戏小时，可能解锁新技能 |
|
||
|
||
---
|
||
|
||
## 7. 上线结算面板数据结构
|
||
|
||
### 7.1 结算报告 JSON Schema
|
||
|
||
```json
|
||
{
|
||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||
"title": "OfflineSettlementReport",
|
||
"type": "object",
|
||
"required": ["report_id", "character_id", "offline_duration", "settlement_time", "summary"],
|
||
"properties": {
|
||
"report_id": {
|
||
"type": "string",
|
||
"description": "结算报告唯一ID（UUID）"
|
||
},
|
||
"character_id": {
|
||
"type": "string",
|
||
"description": "角色ID"
|
||
},
|
||
"settlement_version": {
|
||
"type": "integer",
|
||
"description": "结算版本号，用于幂等校验"
|
||
},
|
||
"offline_duration": {
|
||
"type": "object",
|
||
"properties": {
|
||
"real_seconds": { "type": "integer", "description": "离线现实秒数" },
|
||
"game_hours": { "type": "number", "description": "离线游戏时长（小时）" },
|
||
"capped": { "type": "boolean", "description": "是否触及上限截断" }
|
||
}
|
||
},
|
||
"settlement_time": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"description": "结算执行时间"
|
||
},
|
||
"summary": {
|
||
"type": "object",
|
||
"description": "收益汇总",
|
||
"properties": {
|
||
"total_currency": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"currency_code": { "type": "string" },
|
||
"amount": { "type": "string", "description": "Decimal字符串" },
|
||
"source": { "type": "string", "enum": ["gather", "disciple", "combat_drop", "encounter"] }
|
||
}
|
||
}
|
||
},
|
||
"total_items": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"item_id": { "type": "string" },
|
||
"item_name": { "type": "string" },
|
||
"quantity": { "type": "integer" },
|
||
"rarity": { "type": "string" }
|
||
}
|
||
}
|
||
},
|
||
"overflow_items_count": { "type": "integer", "description": "溢出到邮件的物品数" },
|
||
"exp_gained": { "type": "string", "description": "修为增长" },
|
||
"energy_change": { "type": "string", "description": "能量变化" }
|
||
}
|
||
},
|
||
"battles": {
|
||
"type": "array",
|
||
"description": "战斗摘要列表",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"battle_id": { "type": "string" },
|
||
"battle_type": { "type": "string", "enum": ["expedition_pve", "pvp", "disciple_combat"] },
|
||
"trigger_time": { "type": "string", "format": "date-time" },
|
||
"opponent_name": { "type": "string" },
|
||
"opponent_race": { "type": "string" },
|
||
"opponent_realm": { "type": "string" },
|
||
"result": { "type": "string", "enum": ["win", "lose", "draw"] },
|
||
"end_condition": { "type": "string", "enum": ["hp_zero", "timeout", "surrender"] },
|
||
"rounds_count": { "type": "integer", "description": "行动次数" },
|
||
"damage_dealt": { "type": "string" },
|
||
"damage_taken": { "type": "string" },
|
||
"death_penalty_applied": { "type": "boolean" },
|
||
"drops_summary": {
|
||
"type": "object",
|
||
"properties": {
|
||
"currency": { "type": "array" },
|
||
"items": { "type": "array" }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"disciple_events": {
|
||
"type": "array",
|
||
"description": "弟子代挂事件列表",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"disciple_id": { "type": "string" },
|
||
"disciple_name": { "type": "string" },
|
||
"disciple_quality": { "type": "string" },
|
||
"event_type": { "type": "string", "enum": ["gather", "combat", "insight", "death", "desertion", "treasure"] },
|
||
"trigger_time": { "type": "string", "format": "date-time" },
|
||
"result": { "type": "string", "enum": ["success", "fail", "death", "insight"] },
|
||
"rewards": { "type": "object" },
|
||
"message": { "type": "string", "description": "叙事化描述" }
|
||
}
|
||
}
|
||
},
|
||
"encounters": {
|
||
"type": "array",
|
||
"description": "游历事件列表",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"encounter_id": { "type": "string" },
|
||
"encounter_type": { "type": "string" },
|
||
"trigger_time": { "type": "string", "format": "date-time" },
|
||
"zone_name": { "type": "string" },
|
||
"title": { "type": "string" },
|
||
"description": { "type": "string" },
|
||
"auto_choice": { "type": "string", "description": "离线自动选择的分支" },
|
||
"choice_reason": { "type": "string", "description": "选择策略说明" },
|
||
"result": { "type": "object" }
|
||
}
|
||
}
|
||
},
|
||
"state_changes": {
|
||
"type": "object",
|
||
"description": "角色状态变更",
|
||
"properties": {
|
||
"hp_change": { "type": "string" },
|
||
"energy_change": { "type": "string" },
|
||
"san_change": { "type": "string" },
|
||
"crime_score_change": { "type": "string" },
|
||
"realm_exp_change": { "type": "string" },
|
||
"death_occurred": { "type": "boolean" },
|
||
"tribulation_triggered": { "type": "boolean" }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.2 结算面板 API
|
||
|
||
```protobuf
|
||
// gRPC 接口定义
|
||
service OfflineSettlementService {
|
||
// 拉取离线结算报告（玩家上线时调用）
|
||
rpc GetSettlementReport (GetSettlementReq) returns (SettlementReportResp);
|
||
|
||
// 确认结算（客户端展示完面板后调用，应用状态变更）
|
||
rpc ConfirmSettlement (ConfirmSettlementReq) returns (ConfirmSettlementResp);
|
||
|
||
// 查询历史结算报告
|
||
rpc ListSettlementHistory (ListSettlementReq) returns (ListSettlementResp);
|
||
}
|
||
|
||
message GetSettlementReq {
|
||
string character_id = 1;
|
||
}
|
||
|
||
message SettlementReportResp {
|
||
int32 code = 1;
|
||
string message = 2;
|
||
SettlementReport data = 3;
|
||
}
|
||
|
||
message SettlementReport {
|
||
string report_id = 1;
|
||
int64 settlement_version = 2;
|
||
OfflineDuration offline_duration = 3;
|
||
SettlementSummary summary = 4;
|
||
repeated BattleSummary battles = 5;
|
||
repeated DiscipleEventSummary disciple_events = 6;
|
||
repeated EncounterSummary encounters = 7;
|
||
StateChanges state_changes = 8;
|
||
string compressed_full_report = 9; // gzip 压缩的完整战报 JSON
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 弟子代挂结算（接入 GDD-07 弟子系统）
|
||
|
||
### 8.1 弟子代挂结算流程
|
||
|
||
```
|
||
弟子代挂结算流程：
|
||
|
||
1. 加载弟子列表（status = "dispatched"）
|
||
2. 计算离线游戏时长
|
||
3. 逐弟子结算：
|
||
a. 检查派遣目标（自建门派资源点 / 帮派领地 / 历练点）
|
||
b. 计算基础产出（§4.2 公式）
|
||
c. 随机事件判定（弟子遭遇/顿悟/死亡）
|
||
d. 累计产出到结算报告
|
||
4. 批量更新弟子状态
|
||
```
|
||
|
||
### 8.2 弟子品质对产出的影响
|
||
|
||
```go
|
||
// 弟子代挂产出计算
|
||
func calculateDiscipleOutput(disciple *Disciple, zone *Zone, gameHours float64) *OutputResult {
|
||
// 基础产出
|
||
baseRate := zone.BaseOutputRate
|
||
|
||
// 品质系数（GDD-07 §2.3.2）
|
||
qualityCoeff := map[string]float64{
|
||
"common": 0.8,
|
||
"fine": 1.0,
|
||
"excellent": 1.3,
|
||
"perfect": 1.8,
|
||
"immortal": 2.5,
|
||
}[disciple.Quality]
|
||
|
||
// 种族匹配系数
|
||
raceCoeff := calculateRaceMatch(disciple.RaceID, zone.ZoneType)
|
||
|
||
// 生活技能匹配
|
||
skillCoeff := 1.0
|
||
if hasMatchingSkill(disciple, zone) {
|
||
skillCoeff = 1.5
|
||
}
|
||
|
||
// 门派设施加成
|
||
facilityCoeff := getGuildFacilityBonus(disciple.GuildID, zone)
|
||
|
||
// 极品/仙品双倍产出概率（GDD-07 §2.3.2）
|
||
doubleChance := 0.0
|
||
if disciple.Quality == "perfect" {
|
||
doubleChance = 0.15 // 15% 概率双倍
|
||
} else if disciple.Quality == "immortal" {
|
||
doubleChance = 0.25 // 25% 概率双倍
|
||
}
|
||
|
||
// 计算总产出
|
||
totalOutput := baseRate * qualityCoeff * raceCoeff * skillCoeff * facilityCoeff * gameHours
|
||
|
||
// 随机波动 ±20%
|
||
totalOutput = totalOutput * randomFloat(0.8, 1.2)
|
||
|
||
// 双倍产出判定
|
||
if randomFloat(0, 1) < doubleChance {
|
||
totalOutput *= 2
|
||
}
|
||
|
||
return &OutputResult{Amount: totalOutput}
|
||
}
|
||
```
|
||
|
||
### 8.3 弟子死亡判定（接入 GDD-07 ✅T4 / GDD-13）
|
||
|
||
```go
|
||
// 弟子离线死亡判定
|
||
func checkDiscipleDeath(disciple *Disciple, missionType string, difficulty int) bool {
|
||
// 基础死亡率（随难度递增）
|
||
baseDeathRate := map[string]float64{
|
||
"gathering": 0.001, // 采集：0.1%
|
||
"training": 0.005, // 历练：0.5%
|
||
"mercenary": 0.02, // 佣兵委托：2%
|
||
"sect_proxy": 0.01, // 门派代挂：1%
|
||
}[missionType]
|
||
|
||
// 难度修正
|
||
difficultyMod := 1.0 + float64(difficulty-1)*0.5 // 每星 +50%
|
||
|
||
// 品质修正（高品质弟子生存率更高）
|
||
qualityMod := map[string]float64{
|
||
"common": 1.2, // 凡品 +20% 死亡率
|
||
"fine": 1.0,
|
||
"excellent": 0.8, // 优品 -20%
|
||
"perfect": 0.6, // 极品 -40%
|
||
"immortal": 0.4, // 仙品 -60%
|
||
}[disciple.Quality]
|
||
|
||
// 保险道具修正
|
||
insuranceMod := 1.0
|
||
if disciple.InsuranceItemID != "" {
|
||
insuranceMod = 0.3 // 有保险道具，死亡率 -70%
|
||
}
|
||
|
||
// 弟子死亡率修正字段（培养/装备可降低）
|
||
deathRateMod := 1.0 - disciple.DeathRateModifier
|
||
|
||
finalDeathRate := baseDeathRate * difficultyMod * qualityMod * insuranceMod * deathRateMod
|
||
|
||
// 每游戏小时判定一次
|
||
return randomFloat(0, 1) < finalDeathRate
|
||
}
|
||
```
|
||
|
||
### 8.4 弟子事件池
|
||
|
||
| 事件类型 | 触发概率 | 效果 | 叙事示例 |
|
||
|----------|---------|------|---------|
|
||
| 正常产出 | 85% | 获得资源 | "弟子在矿脉中采集到灵石×N" |
|
||
| 发现宝藏 | 3% | 额外稀有材料 | "弟子在洞窟深处发现一株千年灵草" |
|
||
| 顿悟 | 5% | 弟子属性/技能提升 | "弟子在采集时顿悟，棍法熟练度+8%" |
|
||
| 遭遇战斗 | 4% | 胜利获额外奖励，失败受伤 | "弟子遭遇妖兽袭击，奋力击退" |
|
||
| 受伤 | 2% | 产出效率临时下降 | "弟子不慎中毒，需要休养" |
|
||
| 死亡 | 0.1%~2% | 弟子永久损失 | "弟子在禁地中殒落..." |
|
||
| 叛逃 | 0.05% | 弟子永久损失（仅低忠诚度） | "弟子心生异志，携物资潜逃" |
|
||
|
||
---
|
||
|
||
## 9. 游历事件离线触发（接入 GDD-22）
|
||
|
||
### 9.1 随机事件池抽取
|
||
|
||
```go
|
||
// 离线游历事件抽取
|
||
func pickOfflineEncounter(character *Character, zone *Zone, gameTime int64) *Encounter {
|
||
// 加载区域事件池（GDD-22 §三）
|
||
eventPool := loadZoneEventPool(zone.ID)
|
||
|
||
// 过滤不适用离线的事件
|
||
validEvents := filterEvents(eventPool, func(e Event) bool {
|
||
return e.OfflineEligible && character.RealmTier >= e.MinRealmTier
|
||
})
|
||
|
||
// 计算每个事件的权重
|
||
weightedEvents := []WeightedEvent{}
|
||
for _, event := range validEvents {
|
||
weight := event.BaseWeight
|
||
|
||
// 时段权重（GDD-03 ✅5：昼夜增益按游戏时间判定）
|
||
timeMod := getTimeModifier(gameTime, event.TimePreference)
|
||
weight *= timeMod
|
||
|
||
// 天气/环境权重
|
||
envMod := getEnvironmentModifier(zone.Weather, event.ElementPreference)
|
||
weight *= envMod
|
||
|
||
// 疲劳衰减（同一区域连续探索）
|
||
fatigueMod := getFatigueDecay(character.ID, event.Category)
|
||
weight *= fatigueMod
|
||
|
||
// 卜算/感知类天赋加成
|
||
if character.HasTalent("divination") {
|
||
weight *= 1.3
|
||
}
|
||
|
||
weightedEvents = append(weightedEvents, WeightedEvent{Event: event, Weight: weight})
|
||
}
|
||
|
||
// 加权随机抽取
|
||
selected := weightedRandomSelect(weightedEvents)
|
||
return selected
|
||
}
|
||
```
|
||
|
||
### 9.2 分支选择策略
|
||
|
||
离线状态下玩家无法实时决策，系统按预设策略自动选择：
|
||
|
||
```go
|
||
// 离线自动分支选择策略
|
||
func autoSelectBranch(encounter *Encounter, character *Character) string {
|
||
// 策略优先级：
|
||
// 1. 安全优先（默认策略）：选择风险最低的选项
|
||
// 2. 收益优先：选择预期收益最高的选项
|
||
// 3. 玩家预设：玩家上线时可设置离线偏好
|
||
|
||
strategy := character.OfflineStrategy // "safe" / "greedy" / "balanced"
|
||
|
||
switch strategy {
|
||
case "safe":
|
||
return selectSafestOption(encounter.Options, character)
|
||
case "greedy":
|
||
return selectHighestRewardOption(encounter.Options, character)
|
||
case "balanced":
|
||
return selectBalancedOption(encounter.Options, character)
|
||
default:
|
||
return selectSafestOption(encounter.Options, character)
|
||
}
|
||
}
|
||
|
||
// 安全优先选择
|
||
func selectSafestOption(options []EncounterOption, character *Character) string {
|
||
safest := options[0]
|
||
for _, opt := range options[1:] {
|
||
if opt.RiskLevel < safest.RiskLevel {
|
||
safest = opt
|
||
}
|
||
}
|
||
return safest.ID
|
||
}
|
||
|
||
// 收益优先选择
|
||
func selectHighestRewardOption(options []EncounterOption, character *Character) string {
|
||
best := options[0]
|
||
bestEV := calculateExpectedValue(best, character)
|
||
for _, opt := range options[1:] {
|
||
ev := calculateExpectedValue(opt, character)
|
||
if ev > bestEV {
|
||
best = opt
|
||
bestEV = ev
|
||
}
|
||
}
|
||
return best.ID
|
||
}
|
||
|
||
// 期望值计算
|
||
func calculateExpectedValue(option EncounterOption, character *Character) float64 {
|
||
rewardEV := option.RewardValue * option.SuccessRate
|
||
riskEV := option.RiskValue * (1 - option.SuccessRate) * option.DeathPenaltyWeight
|
||
return rewardEV - riskEV
|
||
}
|
||
```
|
||
|
||
### 9.3 离线事件类型与处理
|
||
|
||
| 事件类型 | 离线处理方式 | 接入文档 |
|
||
|----------|-------------|---------|
|
||
| 灵气异动 | 自动吸纳（安全策略）或标记（收益策略） | GDD-22 §三 |
|
||
| 古修残魂 | 默认超度（最安全），不选择夺舍 | GDD-22 §三 |
|
||
| 行脚商人 | 默认无视（避免被抢） | GDD-22 §三 |
|
||
| 心魔低语 | 默认压制（最安全） | GDD-22 §三 |
|
||
| 同族求救 | 默认无视（避免风险） | GDD-22 §三 |
|
||
| 天降宝箱 | 默认开启 | GDD-22 §三 |
|
||
| 遭遇战斗 | 自动按 ATB 引擎结算 | GDD-03 §六 |
|
||
| 采集点 | 自动采集（消耗能量） | GDD-06 §三 |
|
||
|
||
---
|
||
|
||
## 10. 性能优化
|
||
|
||
### 10.1 批量结算的并发模型
|
||
|
||
```
|
||
玩家上线触发结算
|
||
↓
|
||
Goroutine Pool（N=CPU核心数）
|
||
├── Goroutine 1: 挂机资源结算
|
||
├── Goroutine 2: 弟子代挂结算
|
||
├── Goroutine 3: 游历事件结算
|
||
├── Goroutine 4: 战斗结算（可能多个）
|
||
└── Goroutine 5: 状态变更合并
|
||
↓
|
||
Channel 汇总结果
|
||
↓
|
||
批量写入 DB（单事务）
|
||
```
|
||
|
||
```go
|
||
// 并发结算模型
|
||
func SettleOfflineConcurrent(characterID string) (*SettlementReport, error) {
|
||
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
|
||
defer cancel()
|
||
|
||
// 并发执行各模块结算
|
||
var (
|
||
gatherResult *GatherResult
|
||
discipleResult *DiscipleResult
|
||
encounterResult *EncounterResult
|
||
battleResults []*BattleResult
|
||
wg sync.WaitGroup
|
||
mu sync.Mutex
|
||
errs []error
|
||
)
|
||
|
||
wg.Add(4)
|
||
|
||
// 挂机资源结算
|
||
go func() {
|
||
defer wg.Done()
|
||
r, err := settleOfflineGather(ctx, characterID)
|
||
mu.Lock()
|
||
if err != nil { errs = append(errs, err) } else { gatherResult = r }
|
||
mu.Unlock()
|
||
}()
|
||
|
||
// 弟子代挂结算
|
||
go func() {
|
||
defer wg.Done()
|
||
r, err := settleOfflineDisciples(ctx, characterID)
|
||
mu.Lock()
|
||
if err != nil { errs = append(errs, err) } else { discipleResult = r }
|
||
mu.Unlock()
|
||
}()
|
||
|
||
// 游历事件结算
|
||
go func() {
|
||
defer wg.Done()
|
||
r, err := settleOfflineEncounters(ctx, characterID)
|
||
mu.Lock()
|
||
if err != nil { errs = append(errs, err) } else { encounterResult = r }
|
||
mu.Unlock()
|
||
}()
|
||
|
||
// 战斗结算（可能包含多场战斗）
|
||
go func() {
|
||
defer wg.Done()
|
||
results, err := settleOfflineBattles(ctx, characterID)
|
||
mu.Lock()
|
||
if err != nil { errs = append(errs, err) } else { battleResults = results }
|
||
mu.Unlock()
|
||
}()
|
||
|
||
wg.Wait()
|
||
|
||
if len(errs) > 0 {
|
||
return nil, fmt.Errorf("settlement errors: %v", errs)
|
||
}
|
||
|
||
// 合并结果
|
||
report := mergeResults(gatherResult, discipleResult, encounterResult, battleResults)
|
||
|
||
// 批量写入 DB（单事务）
|
||
err := applySettlementInTransaction(ctx, characterID, report)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
|
||
return report, nil
|
||
}
|
||
```
|
||
|
||
### 10.2 数据库写入优化
|
||
|
||
| 优化策略 | 说明 |
|
||
|----------|------|
|
||
| **单事务批量写入** | 所有结算结果在一个事务中写入，减少事务开销 |
|
||
| **UPSERT 代替 INSERT+UPDATE** | 货币余额、背包物品使用 `INSERT ... ON CONFLICT UPDATE` |
|
||
| **延迟写入经济审计** | 经济审计日志先缓存到 Valkey，定时批量刷入 DB（每 5 分钟） |
|
||
| **分区表利用** | `battle_logs` 按周分区，`economy_audit_logs` 按月分区，写入只命中当前分区 |
|
||
| **连接池调优** | 结算高峰期使用独立连接池，避免影响在线请求 |
|
||
|
||
```go
|
||
// 单事务批量写入
|
||
func applySettlementInTransaction(ctx context.Context, characterID string, report *SettlementReport) error {
|
||
tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelReadCommitted})
|
||
if err != nil {
|
||
return err
|
||
}
|
||
defer tx.Rollback()
|
||
|
||
// 1. 更新角色状态
|
||
_, err = tx.ExecContext(ctx, `
|
||
UPDATE characters SET
|
||
exp = exp + $1,
|
||
san_current = GREATEST(0, LEAST(san_max, san_current + $2)),
|
||
crime_score = GREATEST(0, crime_score + $3),
|
||
last_online_at = NOW(),
|
||
updated_at = NOW()
|
||
WHERE id = $4
|
||
`, report.ExpGained, report.SanChange, report.CrimeChange, characterID)
|
||
|
||
// 2. 批量更新货币余额（UPSERT）
|
||
for _, curr := range report.TotalCurrency {
|
||
_, err = tx.ExecContext(ctx, `
|
||
INSERT INTO currency_balances (character_id, currency_code, amount, total_earned, updated_at)
|
||
VALUES ($1, $2, $3, $3, NOW())
|
||
ON CONFLICT (character_id, currency_code) DO UPDATE SET
|
||
amount = currency_balances.amount + EXCLUDED.amount,
|
||
total_earned = currency_balances.total_earned + EXCLUDED.total_earned,
|
||
updated_at = NOW()
|
||
`, characterID, curr.CurrencyCode, curr.Amount)
|
||
}
|
||
|
||
// 3. 批量插入背包物品
|
||
for _, item := range report.TotalItems {
|
||
_, err = tx.ExecContext(ctx, `
|
||
INSERT INTO inventories (id, character_id, item_id, slot_type, quantity, instance_data, acquired_at, created_at)
|
||
VALUES (gen_random_uuid(), $1, $2, 'bag', $3, $4, NOW(), NOW())
|
||
`, characterID, item.ItemID, item.Quantity, item.InstanceData)
|
||
}
|
||
|
||
// 4. 更新弟子状态
|
||
for _, de := range report.DiscipleEvents {
|
||
if de.EventType == "death" {
|
||
_, err = tx.ExecContext(ctx, `
|
||
UPDATE disciples SET status = 'dead', died_at = NOW(), tombstone_data = $1
|
||
WHERE id = $2
|
||
`, de.TombstoneData, de.DiscipleID)
|
||
}
|
||
}
|
||
|
||
// 5. 写入战斗记录
|
||
for _, battle := range report.Battles {
|
||
_, err = tx.ExecContext(ctx, `
|
||
INSERT INTO battles (id, battle_type, world_tier, realm_tier, attacker_id, defender_id, status, result_summary, created_at)
|
||
VALUES ($1, $2, $3, $4, $5, $6, 'completed', $7, $8)
|
||
`, battle.ID, battle.Type, battle.WorldTier, battle.RealmTier,
|
||
battle.AttackerID, battle.DefenderID, battle.ResultSummary, battle.CreatedAt)
|
||
}
|
||
|
||
// 6. 写入经济审计日志
|
||
for _, audit := range report.EconomyAudits {
|
||
_, err = tx.ExecContext(ctx, `
|
||
INSERT INTO economy_audit_logs (character_id, entity_type, entity_id, currency_code, flow_type, reason_code, amount, balance_after, world_tier, created_at)
|
||
VALUES ($1, 'character', $1, $2, 'faucet', 'offline_settle', $3, $4, $5, NOW())
|
||
`, characterID, audit.CurrencyCode, audit.Amount, audit.BalanceAfter, audit.WorldTier)
|
||
}
|
||
|
||
// 7. 标记结算完成
|
||
_, err = tx.ExecContext(ctx, `
|
||
UPDATE characters SET offline_settle_version = offline_settle_version + 1 WHERE id = $1
|
||
`, characterID)
|
||
|
||
return tx.Commit()
|
||
}
|
||
```
|
||
|
||
### 10.3 结算结果压缩存储
|
||
|
||
```go
|
||
// 结算结果压缩存储到 Valkey
|
||
func saveCompressedReport(characterID string, report *SettlementReport) error {
|
||
// JSON 序列化
|
||
jsonBytes, err := json.Marshal(report)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
|
||
// gzip 压缩
|
||
var buf bytes.Buffer
|
||
gz := gzip.NewWriter(&buf)
|
||
if _, err := gz.Write(jsonBytes); err != nil {
|
||
return err
|
||
}
|
||
gz.Close()
|
||
|
||
// 存储到 Valkey，TTL = 7 天
|
||
key := fmt.Sprintf("offline_settle:%s:%d", characterID, report.SettlementVersion)
|
||
return valkey.Set(ctx, key, buf.Bytes(), 7*24*time.Hour)
|
||
}
|
||
|
||
// 从 Valkey 读取并解压
|
||
func loadCompressedReport(characterID string, version int64) (*SettlementReport, error) {
|
||
key := fmt.Sprintf("offline_settle:%s:%d", characterID, version)
|
||
data, err := valkey.Get(ctx, key).Bytes()
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
|
||
// gzip 解压
|
||
gz, err := gzip.NewReader(bytes.NewReader(data))
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
defer gz.Close()
|
||
|
||
var report SettlementReport
|
||
if err := json.NewDecoder(gz).Decode(&report); err != nil {
|
||
return nil, err
|
||
}
|
||
|
||
return &report, nil
|
||
}
|
||
```
|
||
|
||
### 10.4 性能指标与监控
|
||
|
||
| 指标 | 目标值 | 监控方式 |
|
||
|------|--------|---------|
|
||
| 单次结算耗时（24h 离线） | < 500ms | Prometheus histogram |
|
||
| 单次结算耗时（120h 离线） | < 3s | Prometheus histogram |
|
||
| 结算并发数 | 100/s（峰值） | Grafana dashboard |
|
||
| DB 写入延迟 | < 100ms | PostgreSQL slow query log |
|
||
| Valkey 缓存命中率 | > 95% | Valkey INFO |
|
||
| 结算失败率 | < 0.1% | AlertManager |
|
||
|
||
---
|
||
|
||
## 11. 已确认决策记录
|
||
|
||
| # | 决策 | 来源 |
|
||
|---|------|------|
|
||
| ✅O01 | 离线结算采用"延迟结算"模式：离线期间只记录事件队列，上线时批量结算 | 本文确认 |
|
||
| ✅O02 | 最大离线结算时长按境界递增：炼气72h→筑基96h→金丹120h→元婴+无上限；默认上限120h，通过 Nacos 可配 | 本文确认 |
|
||
| ✅O03 | 离线战斗使用与在线完全相同的 ATB 引擎，服务端权威计算 | GDD-03 ✅1 |
|
||
| ✅O04 | 离线游历事件自动选择分支，默认"安全优先"策略，玩家可设置偏好 | GDD-22 三 |
|
||
| ✅O05 | 弟子离线死亡判定每游戏小时执行一次，死亡率与难度/品质/保险相关 | GDD-07 ✅T4 |
|
||
| ✅O06 | 结算结果压缩存储到 Valkey，TTL 7 天，支持幂等重复拉取 | 本文确认 |
|
||
| ✅O07 | 背包满时溢出物品转入邮件系统，货币溢出按比例折算低档货币 | TDD-04 |
|
||
| ✅O08 | 结算面板展示战报摘要（不含完整行动序列），完整战报按需加载 | TDD-05 |
|
||
| ✅O09 | 离线产出遵循 GDD-06 经济参数，受疲劳衰减/区域警觉值约束 | GDD-06 §5.3 |
|
||
| ✅O10 | 弟子代挂产出按品质/种族/技能/设施四维系数计算 | GDD-07 §2.3.2 |
|
||
| ✅O11 | 离线 PVP 战书默认接受（GDD-03 ✅14），被挑战方上线后查看战报 | GDD-03 §8.2 |
|
||
| ✅O12 | 结算版本号机制保证幂等性，重复登录不会重复结算 | 本文确认 |
|
||
|
||
---
|
||
|
||
## 12. 验收标准
|
||
|
||
| # | 验收条目 | 测试方法 |
|
||
|---|----------|----------|
|
||
| 1 | 玩家离线 24 现实小时后上线，结算面板正确显示挂机资源/弟子产出/事件列表 | 离线 24h mock + 上线验证 |
|
||
| 2 | 离线战斗结果与在线相同条件下手动触发的战斗结果一致（相同随机种子） | 相同参数对比测试 |
|
||
| 3 | 背包满时溢出物品正确转入邮件，货币溢出正确折算 | 背包填满后离线验证 |
|
||
| 4 | 弟子离线死亡概率符合 GDD-07 设定（品质/难度/保险修正） | 10000 次蒙特卡洛模拟 |
|
||
| 5 | 离线游历事件按"安全优先"策略自动选择，不选择高风险选项 | 事件池 mock 验证 |
|
||
| 6 | 结算结果幂等：同一结算版本重复调用不产生额外收益 | 重复调用验证 |
|
||
| 7 | 72h 离线结算耗时 < 2s（单角色） | 性能基准测试 |
|
||
| 8 | 100 并发结算请求下系统稳定，无 DB 死锁 | 压力测试 |
|
||
| 9 | 结算报告 JSON Schema 验证通过 | JSON Schema 校验工具 |
|
||
| 10 | 离线期间的经济审计日志完整记录（每笔产出/消耗） | 查询 economy_audit_logs |
|
||
| 11 | 弟子品质/数量上限符合 GDD-07 ✅T4（炼气2→合体10，弟子居+2） | 边界值测试 |
|
||
| 12 | 离线 PVP 被挑战默认接受，上线后战报正确展示 | PVP mock 测试 |
|
||
| 13 | Valkey 缓存 TTL 过期后结算报告正确降级到 DB 查询 | TTL 过期测试 |
|
||
| 14 | 结算版本号递增正确，旧版本报告不再重复应用 | 版本号递增测试 |
|
||
|
||
---
|
||
|
||
## 13. 数据库新增/变更（补充 TDD-04）
|
||
|
||
### 13.1 离线结算相关新增字段
|
||
|
||
#### characters 表新增字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| offline_settle_version | bigint | 离线结算版本号，每次结算 +1 |
|
||
| offline_strategy | varchar(16) | 离线事件选择策略：safe / greedy / balanced，默认 safe |
|
||
| last_settle_at | timestamptz | 上次结算时间 |
|
||
|
||
#### 新增表：offline_event_queue
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | uuid | PK | |
|
||
| character_id | uuid | FK, IX | |
|
||
| event_type | varchar(32) | IX | combat / gather / disciple / encounter |
|
||
| trigger_time_game | bigint | IX | 触发时间（游戏时间戳） |
|
||
| payload | jsonb | | 事件数据 |
|
||
| resolved | boolean | IX | 是否已结算 |
|
||
| result | jsonb | | 结算结果 |
|
||
| settle_version | bigint | | 关联的结算版本 |
|
||
| created_at | timestamptz | IX | |
|
||
|
||
**分区**：按 `created_at` 日分区，保留 7 天。
|
||
|
||
#### 新增表：offline_settlement_reports
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | uuid | PK | |
|
||
| character_id | uuid | FK, IX | |
|
||
| settle_version | bigint | UQ(character_id, settle_version) | 结算版本 |
|
||
| offline_duration_real_sec | int | | 离线现实秒数 |
|
||
| offline_duration_game_hours | numeric(10,2) | | 离线游戏时长 |
|
||
| summary | jsonb | | 收益汇总（压缩） |
|
||
| compressed_report | bytea | | gzip 压缩的完整报告 |
|
||
| created_at | timestamptz | IX | |
|
||
|
||
---
|
||
|
||
## 14. Nacos 动态配置项
|
||
|
||
| 配置键 | 类型 | 默认值 | 说明 |
|
||
|--------|------|--------|------|
|
||
| `offline.max_settle_hours.default` | int | 120 | 默认最大离线结算时长（现实小时，金丹期） |
|
||
| `offline.max_settle_hours.qi_refining` | int | 72 | 炼气期离线上限（现实小时） |
|
||
| `offline.max_settle_hours.foundation` | int | 96 | 筑基期离线上限（现实小时） |
|
||
| `offline.max_settle_hours.golden_core` | int | 120 | 金丹期离线上限（现实小时） |
|
||
| `offline.max_settle_hours.nascent_soul` | int | 0 | 元婴期+离线上限（0=无上限） |
|
||
| `offline.tick_interval_game_hours` | float | 1.0 | 时间快进步长（游戏小时） |
|
||
| `offline.event_check_interval` | int | 300 | 定时扫描离线玩家间隔（秒） |
|
||
| `offline.gather.fatigue_decay_per_hour` | float | 0.05 | 挂机疲劳衰减率（每游戏小时） |
|
||
| `offline.gather.fatigue_min` | float | 0.3 | 疲劳衰减最低系数 |
|
||
| `offline.disciple.death_rate_base.gathering` | float | 0.001 | 弟子采集基础死亡率 |
|
||
| `offline.disciple.death_rate_base.mercenary` | float | 0.02 | 弟子佣兵基础死亡率 |
|
||
| `offline.encounter.safe_strategy_weight` | float | 0.8 | 安全策略权重 |
|
||
| `offline.encounter.greedy_strategy_weight` | float | 0.3 | 收益策略权重 |
|
||
| `offline.battle.max_ticks` | int | 3000 | 战斗最大行动时间 |
|
||
| `offline.battle.max_actions` | int | 50 | 单方最大行动次数 |
|
||
| `offline.report.cache_ttl_hours` | int | 168 | 结算报告缓存 TTL（小时） |
|
||
|
||
---
|
||
|
||
## 15. 版本记录
|
||
|
||
| 版本 | 日期 | 修订内容 | 作者 |
|
||
|------|------|----------|------|
|
||
| 1.1 | 2026-07-02 | 离线结算上限按境界递增：炼气72h→筑基96h→金丹120h→元婴+无上限；默认上限从72h调整为120h；Nacos配置拆分为按境界独立配置 | Claude Code |
|
||
| 1.0 | 2026-07-02 | 初始版本：时间快进算法、离线产出公式、ATB战斗结算、弟子代挂、游历事件、上线结算面板、性能优化、数据库变更、Nacos配置 | Claude Code |
|
||
|
||
---
|
||
|
||
*TDD-06 v1.1 | 2026-07-02 | 离线结算上限按境界递增调整：炼气72h→筑基96h→金丹120h→元婴+无上限 | 前序：v1.0*
|
