Fishing2Server/AGENTS.md

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 与生成类型一致。

构建与验证

仓库根目录常用命令：

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。