# 规范-热更与兼容性

> **位置**: `docs/开发规范/规范-热更与兼容性.md`
> **版本**: v1.0
> **日期**: 2026-07-08
> **关联**: AGENTS.md、TDD-02（客户端热更新技术方案）、PRD-03（热更新与活动系统）

---

## 1. 热更铁律

### 1.1 Asset Bundle 热更

| 规则 | 优先级 | 说明 |
|------|--------|------|
| 客户端启动时检查热更包版本 | P0 | 版本不匹配时强制下载更新 |
| 热更包大小 < 50MB（单次） | P0 | 大资源分多个 Bundle 按需加载 |
| 热更下载失败可重试 3 次 | P0 | 失败后提示手动更新或跳过（非强制内容） |
| 热更发布 1 小时内可一键回滚 | P0 | 回滚到上一版本，不影响玩家数据 |
| 热更内容限定：UI/文案/配置/脚本 | P0 | **禁止热更修改协议格式/数据库结构** |

### 1.2 热更禁止行为

- ❌ 热更修改 Protobuf 字段编号/类型
- ❌ 热更修改数据库表结构
- ❌ 热更删除已存在的 API 接口
- ❌ 热更修改核心战斗公式（影响平衡性的走 Nacos 配置热更）
- ❌ 热更包未经测试直接上生产

---

## 2. 协议兼容性

### 2.1 Protobuf 向后兼容

```protobuf
// ✅ 正确：新增字段用新编号
message CharacterData {
  string id = 1;
  int32 energy_current = 2;
  int32 energy_cap = 3;
  // v1.1 新增
  int32 seclusion_end_time = 4;
}

// ✅ 正确：废弃字段保留编号（reserved）
message OldMessage {
  reserved 3, 5;
  reserved "old_field_name";
  string new_field = 1;
}

// ❌ 错误：修改已有字段编号
message Bad {
  string id = 2;  // 原来是 1，修改后旧客户端解析错误
}
```

### 2.2 API 向后兼容

| 规则 | 优先级 | 说明 |
|------|--------|------|
| 新增 API 必须走版本号 | P0 | `/v2/character/create` |
| 旧 API 保留至少 2 个版本 | P0 | 旧版本标记 deprecated，客户端迁移后下线 |
| 禁止删除已有 API 路径 | P0 | 只能标记 deprecated，返回 410 Gone |
| 禁止修改已有 API 参数含义 | P0 | 如需修改，新建 API 路径 |
| 服务端必须忽略未知字段 | P0 | 旧客户端连接新服务端时不崩溃 |

### 2.3 数据模型向后兼容

| 规则 | 优先级 | 说明 |
|------|--------|------|
| 新增字段必须有默认值 | P0 | 旧存档读取时自动填充默认值 |
| 禁止删除已有字段 | P0 | 废弃字段保留，数据迁移到新结构 |
| 禁止修改字段数据类型 | P0 | 如需修改，新增字段 + 迁移脚本 |
| 数据模型变更必须提供迁移函数 | P0 | `migrateV1toV2()`，递增 `DATA_MODEL_VERSION` |
| 迁移脚本必须经过测试 | P0 | 用生产数据脱敏副本测试迁移 |

---

## 3. 兼容性检查清单

发版前必须检查：

```
□ Protobuf reserved 字段是否完整
□ 新增 API 是否走了版本号
□ 旧 API 是否仍可用
□ 数据模型迁移脚本是否测试通过
□ 旧客户端能否连接新服务端
□ 热更包大小是否 < 50MB
□ 热更回滚方案是否就绪
```

---

## 4. 版本记录

- **v1.0**（2026-07-08）: 初始版本，覆盖热更规则、协议兼容、数据兼容