身份验证

AGENTS.md

@@ -0,0 +1,160 @@
+# 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`。