# Proto 完整工作流

## 1. 命名与放置

`.proto` 文件必须放在某个 `cn.etetet.<pkg>/Proto/` 目录下，且文件名遵守：

```
<Module>_<Direction>_<StartOpcode>.proto
```

| 字段 | 取值 | 说明 |
|---|---|---|
| `Module` | 任意（如 `HeroOuter`、`BagOuter`、`LoginInner`）| 模块标识 |
| `Direction` | `C` / `S` / `CS` | C=外网消息（客户端可见），S=内网消息（仅服务端），CS=同时 |
| `StartOpcode` | 整数 | Opcode 从这里递增分配给每条 message |

opcode 分配规范（避免冲突）：

| 模块 | Outer 起始 | Inner 起始 |
|---|---|---|
| Login | 1000 | 20001 |
| Router | 1100 | - |
| StateSync | 11001 | 21001 |
| ActorLocation | - | 20100 |
| Hero | 3000 | - |
| Bag | 3100 | - |
| Gacha | 3200 | - |
| 业务新模块 | 4000+ | 30000+ |

---

## 2. 消息注解（决定生成的 C# 类继承谁）

### RPC 请求 / 响应

```proto
// ResponseType R2C_SummonHero          ← 必须在 message 上一行
message C2G_SummonHero // ISessionRequest
{
    int32 RpcId = 1;
    string reqId = 2;       ← 推荐字段，前 2 个固定 RpcId + reqId
    int32 configId = 3;
}

message R2C_SummonHero // ISessionResponse
{
    int32 RpcId = 1;
    int32 Error = 2;        ← 前 3 个固定 RpcId / Error / Message
    string Message = 3;
    HeroInfo hero = 4;
}
```

生成结果继承 `MessageObject, ISessionRequest` 和 `MessageObject, ISessionResponse`，并通过 `[ResponseType(nameof(R2C_SummonHero))]` 自动配对。

### 单向通知（服务端推客户端）

```proto
message Hero_HeroInfo // IMessage
{
    HeroInfo hero = 1;
}
```

### 嵌套 DTO

```proto
message HeroInfo
{
    int64 heroId = 1;
    int32 level = 2;
    repeated SkillInfo skills = 3;     // List<SkillInfo>
}

message SkillInfo
{
    int32 skillId = 1;
    int32 skillLevel = 2;
}
```

不加任何 `//` 注解的 message 默认继承 `MessageObject`，可作为 DTO 嵌入其他消息。

### 完整可识别的父类标记

Proto2CS 解析时，把 `message X // Y` 里的 `Y` 直接拼到生成类的继承列表。常见值：

- `IRequest` / `IResponse` — 内网请求/响应
- `ISessionRequest` / `ISessionResponse` — 客户端 ↔ Gate 的 RPC
- `IMessage` — 单向通知
- `IActorMessage` / `IActorRequest` / `IActorResponse` — Actor 模型消息

---

## 3. 生成

**Unity 菜单触发**：

```
ET → Proto → Proto2CS
```

**MCP 触发**：

```
CallMcpTool execute_menu_item {"menuPath": "ET/Proto/Proto2CS"}
```

工具会：
1. 扫描所有 `cn.etetet.*/Proto/*.proto`
2. 按文件名解析 Opcode
3. 输出三份 C# 到：
   - `cn.etetet.proto/CodeMode/Model/Client/<Name>.cs`
   - `cn.etetet.proto/CodeMode/Model/Server/<Name>.cs`
   - `cn.etetet.proto/CodeMode/Model/ClientServer/<Name>.cs`

> CodeMode 下只有 `ClientServer/` 子目录有 `AssemblyReference.asmref`（指向 ET.Model），所以在 `CodeMode: 3 = ClientServer` 模式下，**只有 ClientServer 那份会被编译**进 ET.Model。`Client/` 和 `Server/` 是预留给纯客户端/纯服务端模式的。

---

## 4. 调用

### 客户端发 RPC

```csharp
C2G_SummonHero request = C2G_SummonHero.Create();
request.configId = 1;
R2C_SummonHero response = await clientScene
    .GetComponent<ClientSenderComponent>()
    .Call(request, false) as R2C_SummonHero;
if (response.Error != 0)
{
    Log.Error(response.Message);
}
```

### 服务端 RPC Handler

```csharp
// Scripts/Hotfix/Server/C2G_SummonHeroHandler.cs
[MessageSessionHandler(SceneType.Gate)]
public class C2G_SummonHeroHandler : RpcMessageHandler<C2G_SummonHero, R2C_SummonHero>
{
    protected override async ETTask OnRun(
        Session session, C2G_SummonHero request, R2C_SummonHero response)
    {
        Player player = session.GetComponent<SessionPlayerComponent>()?.Player;
        if (player == null) {
            response.Error = ErrorCode.ERR_RpcFail;
            return;
        }
        // 业务...
        await ETTask.CompletedTask;
    }
}
```

注意：
- **不要**写 `protected override string Module => "X"` 这种属性，ET0004 会报。
- 文件放 `Scripts/Hotfix/Server/`。

### 服务端推单向通知

```csharp
Hero_HeroInfo notice = Hero_HeroInfo.Create();
notice.hero = HeroMapper.ToProto(hero);
session.Send(notice);
```

### 客户端通知 Handler

```csharp
// Scripts/Hotfix/Client/Hero_HeroInfoHandler.cs
[MessageHandler(SceneType.Main)]
[FriendOf(typeof(HeroComponent))]
public class Hero_HeroInfoHandler : MessageHandler<Scene, Hero_HeroInfo>
{
    protected override async ETTask Run(Scene scene, Hero_HeroInfo message)
    {
        var comp = scene.GetComponent<HeroComponent>() ?? scene.AddComponent<HeroComponent>();
        comp.HeroMap[message.hero.heroId] = message.hero;
        EventSystem.Instance.Publish(scene, new HeroUpdatedEvent { HeroId = message.hero.heroId });
        await ETTask.CompletedTask;
    }
}
```

---

## 5. 常见 Proto 坑

1. **写完 .proto 不跑 Proto2CS → 引用方报"找不到类型"**：必须先生成。
2. **缺 `// ISessionRequest`**：消息生成出来不继承 `ISessionRequest`，handler 的 `MessageSessionHandler<TReq, TResp>` 类型约束失败 → 编译报错。
3. **缺 `// ResponseType R2C_X`**：客户端 `await session.Call(req)` 无法推断响应类型。
4. **文件名 opcode 重复**：和别的 proto 撞 opcode → 运行时崩。规范分配规则见上面表格。
5. **手写 `new HeroInfo {...}`** → ET0031。改 `HeroInfo.Create()`。
6. **修改 .proto 字段顺序 / 类型** → MemoryPack 序列化兼容性问题。线上版本要么不改，要么走版本兼容方案。

---

## 6. 一键自检 checklist

写完一个新 .proto 后：

```
- [ ] 文件名格式 <Module>_<Direction>_<Opcode>.proto
- [ ] Opcode 不与其他 .proto 冲突（grep "_C_<同段号>_"）
- [ ] RPC 消息有 // ResponseType
- [ ] 请求带 // ISessionRequest 或 // IRequest
- [ ] 响应带 // ISessionResponse 或 // IResponse
- [ ] 通知带 // IMessage
- [ ] 跑了 ET/Proto/Proto2CS
- [ ] 检查 cn.etetet.proto/CodeMode/Model/ClientServer/<Name>.cs 已生成
- [ ] Assets/Refresh 让 Unity 索引到新文件
- [ ] recompile_scripts 验证 0 错误
```