# Fishing2Server 协作说明

## 项目概览

这是一个基于 Fantasy.Net 的游戏服务器项目，主要包含四个工程：

- `Main`：程序入口、启动流程、日志初始化、运行时配置加载。
- `Entity`：实体定义、组件定义、共享模型、生成代码、稳定契约。
- `Hotfix`：业务逻辑、消息处理、HTTP API、辅助类、工厂类、System 扩展，以及可发布/可热更新的逻辑层。
- `ThirdParty`：本地第三方依赖代码。

以当前源码为准，不以旧文档为准。当前 `.csproj` 实际目标框架是 `net10.0`。

## 最重要的架构规则

这个仓库最核心的规则是：

- `Entity` 负责定义。
- `Hotfix` 负责实际业务逻辑。
- 业务逻辑优先写成 `Hotfix` 中的静态扩展、`System`、`Helper`、`Factory`、`Handler`、工具类。
- `Entity` 尽量保持稳定，因为 `Hotfix` 才是后续发布、替换、热更新的主要承载层。

具体落地时：

- 新增或修改字段、组件、枚举、共享数据结构、协议承载类型，优先放在 `Entity`。
- 新增或修改玩法流程、消息处理、校验、奖励结算、状态流转、跨模块编排，优先放在 `Hotfix`。
- 不要把复杂业务直接塞进实体类实例方法里，除非有非常明确的理由，并且符合现有 Fantasy 项目模式。

## 目录职责

- `Main/Program.cs`：服务启动入口。
- `Main/NLog.config`：日志配置。
- `Main/configs.json`：配置相关源定义。
- `Main/cfg/`：运行时配置表 JSON。
- `Entity/Authentication`、`Entity/Game`、`Entity/Gate`、`Entity/Model`、`Entity/Modules`：实体和共享模型定义。
- `Entity/Generate/NetworkProtocol`：协议生成代码。
- `Entity/Generate/ConfigTable`：配置表生成代码。
- `Hotfix/Authentication`、`Hotfix/Game`、`Hotfix/Gate`、`Hotfix/Common`、`Hotfix/Api`：业务逻辑实现，其中 HTTP API 相关逻辑统一放在 `Hotfix/Api`。
- `Tools/NetworkProtocol`：协议定义源文件。
- `Tools/ProtocolExportTool`：协议导出工具。

## 修改代码时的基本判断

处理需求时，先判断它属于哪一类：

- 如果是“数据长什么样、有哪些字段、有哪些共享结构”，改 `Entity`。
- 如果是“数据怎么流转、怎么校验、怎么处理、怎么响应”，改 `Hotfix`。

默认原则：

- 业务变更默认落在 `Hotfix`。
- 目录结构尽量与现有模块保持对称。
- 如果实体在 `Entity/Game/Player`，对应逻辑通常应放在 `Hotfix/Game/Player`。
- 优先复用现有模块，不要随意新起一套平行抽象。

## 命名和组织约定

遵循现有源码习惯：

- `*System`：静态扩展逻辑、Fantasy 系统逻辑。
- `*Helper`：流程编排、模块辅助逻辑。
- `*Factory`：对象创建、初始化组装逻辑。
- `*Handler`：消息处理、RPC 处理、HTTP 处理。

命名空间尽量沿用项目现有风格，主要是 `NB.*`。

## Entity 与 Hotfix 的边界

适合放在 `Entity` 的内容：

- Entity / Component 类型定义。
- 持久化字段和共享字段。
- 枚举、共享模型、基础契约。
- `Main` 和 `Hotfix` 都要依赖的公共类型。
- 生成代码产物。

适合放在 `Hotfix` 的内容：

- `MessageRPC<,>` 等消息处理器。
- HTTP API 的 `Controller`、API `Handler`、API `Helper`、中间件及相关业务流程。
- 对实体/组件的静态扩展方法。
- 玩法规则、条件校验、奖励发放、状态变化。
- 场景生命周期逻辑。
- 登录/JWT/网关业务流程。
- 工厂、帮助类、缓存协作、跨模块调度。

尽量避免：

- 在 `Entity` 中直接编写大量玩法逻辑。
- 直接手改 `Entity/Generate` 下的生成文件。
- 一边改协议源文件，一边又手工改生成后的协议代码。

## 生成代码与源文件规则

以下内容默认视为“产物”而不是“手工主编辑区”：

- 协议源文件：`Tools/NetworkProtocol/**`
- 协议生成输出：`Entity/Generate/NetworkProtocol/**`
- 配置表生成输出：`Entity/Generate/ConfigTable/**`
- 运行时配置 JSON：`Main/cfg/**`

推荐流程：

1. 先改源定义。
2. 再执行生成。
3. 只有在用户明确要求，或生成链路不可用时，才直接改生成产物。

## 常见任务处理方式

### 新增玩法或业务功能

1. 只有在数据结构必须变化时，才修改 `Entity`。
2. 实际功能实现放到 `Hotfix`。
3. 请求入口放在对应模块的 `Handler` 目录。
4. 跨场景或跨模块编排优先写在 `Helper` 或 `System`，不要堆到 `Main`。

### 新增或修改 HTTP API

1. HTTP API 相关实现统一放在 `Hotfix/Api`。
2. 控制器放在 `Hotfix/Api/Controllers`。
3. API 相关服务注册、处理入口、辅助逻辑分别沿用现有 `Handler`、`Helper`、`Middlewares` 目录结构。
4. API 只是入口层，真正的业务规则仍应复用 `Hotfix` 内已有模块逻辑，不要在 Controller 中堆积大量业务代码。

### 新增或修改网络消息

1. 修改 `Tools/NetworkProtocol` 下的协议定义。
2. 生成到 `Entity/Generate/NetworkProtocol`。
3. 在 `Hotfix` 中补齐对应处理逻辑。
4. 非必要不要直接维护 Opcode 或生成消息文件。

### 新增或修改配置表

1. 先修改配置源。
2. 如有需要，重新生成 `Entity/Generate/ConfigTable`。
3. 确保 `Main/cfg` 中的运行时 JSON 与生成类型一致。

## 构建与验证

仓库根目录常用命令：

```powershell
dotnet build Server.sln
dotnet build Main/Main.csproj
dotnet build Entity/Entity.csproj
dotnet build Hotfix/Hotfix.csproj
dotnet run --project Main/Main.csproj
```

完成较大改动前，建议至少做这些检查：

- 优先构建受影响最小的项目。
- 如果公共契约变了，构建整个解决方案。
- 如果动了协议或配置生成链路，确认生成代码和 `Hotfix` 使用方都能正常编译。

## 额外注意事项

- 工作区可能已经有用户自己的未提交改动，不要回滚无关内容。
- 仓库中已有 `bin/`、`obj/` 等构建产物目录，除非任务明确要求，否则忽略它们。
- `CODELY.md` 可以作为背景参考，但其中部分信息已经滞后；若与源码冲突，以源码和项目文件为准。
- 当需求描述不够明确时，优先按本项目既有架构理解：稳定定义放 `Entity`，可变业务放 `Hotfix`。