Files
FunGameServer-Test/docs/03-Server-v3-开发规划.md
T
2026-08-28 19:44:46 +08:00

188 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Server-v3 开发规划(决策与建议)
> 目标:以 FunGame.Core **v3**(master)为基础,在 `C:\milimoe\FunGame.Server-v3` 重新构建服务器。
> 本文基于 `01-v2-功能总结.md` 与 `02-v3-Core-变更分析.md`,列出**必须做的决策**、**建议架构**与**开发路线**,供确定 v3 开发内容。
---
## 1. 先决决策(需要你拍板的 5 个问题)
### 决策 A:服务器形态
| 选项 | 说明 | 建议 |
|---|---|---|
| **A1. 单一 WebAPI 程序**(推荐) | 一个 ASP.NET Core 进程同时提供:WebSocket 游戏协议 + RESTful API + 回合记录回放端点。与 v3 的 `DefaultRoundRecordSink`(POST) 设计意图吻合,与 Testing-v3 一脉相承 | ✅ 推荐:维护面小、天然支持记录外发与回放、Linux 部署友好 |
| A2. 控制台 + WebAPI 双程序 | 沿用 v2:FunGameServer(控制台) + FunGameWebAPI 双进程 | 保留 v2 习惯,但两套入口重复维护 |
| A3. 控制台单程序 | 只有 Socket/WS 游戏服务 | 无法直接对接 v3 的 POST 外发/回放生态 |
### 决策 B:客户端传输协议
| 选项 | 说明 |
|---|---|
| B1. **WebSocket + JSON**(推荐) | 与 v3 回放/记录 JSON 体系一致;浏览器/Web/桌面端都能连;`/ws` 单端点 |
| B2. WebSocket + 二进制协议 | 性能更高,但需要重新设计序列化(v3 已无 SocketObject) |
| B3. TCP Socket 二进制 | v2 传统;客户端(FunGame.Desktop 等)需同步改造 |
| B4. 纯 REST + 轮询/SSE | 放弃实时长连接,最简但体验差 |
> 注意:v3 已无 `SocketObject`/`SocketMessageType`,**协议要自己定**。建议最小集:
> 连接握手(协议版本/模组清单/版本校验)→ 登录/注册 → 大厅/房间/匹配 → 局内指令(决策点/技能/移动)→ 心跳/断线重连。数据格式直接复用 v3 实体 JSON(JsonService 转换器已就绪)。
### 决策 C:数据层
| 选项 | 说明 |
|---|---|
| C1. **EF Core + SQLite/MySQL**(推荐) | 现代、迁移方便;v2 的 users/rooms/inventory 等表结构可迁移为 EF 模型 |
| C2. 保留 v2 的 SQLHelper 思路自研 | 可从 v2 Server 移植 `MySQLHelper`/`SQLiteHelper` + SQLQueryExtension(注意该包依赖 v2 Core 命名空间,需改) |
| C3. Dapper/ADO 手写 | 轻量但开发量大 |
> v3 需要的持久化比 v2 简单:**对局记录(RoundRecord)可以用 JSON 归档**(Testing-v3 已有 rounds_archive.zip 模式),数据库只存账号/房间/经济等"服务器业务数据"。
### 决策 D:模组加载方式
| 选项 | 说明 |
|---|---|
| D1. **编译期进程内引用**(推荐,跟随 v3 设计) | 模组 = 代码类 + `EntityModuleConfig` 配置;`CharacterModule.Load()` 后 `Factory.GetGameModuleInstances<T>` 实例化。参考 Testing-v3 的 OshimaGameModules |
| D2. DLL 插件加载器自研 | 保留 v2 的 plugins/modules 热插拔体验,但 Core v3 不再提供任何加载器,需要完整自研(隔离上下文、依赖解析、热卸载) |
| D3. 混合 | 核心模组编译期引用,扩展模组走 DLL |
### 决策 E:回合记录外发(v3 特色能力,强烈建议纳入)
| 选项 | 说明 |
|---|---|
| E1. **自收自发**(推荐) | 服务器自身实现 `IRoundRecordSink`,把 `RoundRecord` 写入自己的存储(JSON 归档/数据库),并提供回放 REST 端点(参考 Testing-v3 的 ArchiveStore + /api/rounds 系列) |
| E2. 使用 `DefaultRoundRecordSink` | 直接 POST 到外部数据服务(如独立的回放服务器),Server 只当生产者 |
| E3. 两者结合 | 本地归档 + 转发远端(最完整,实现也最简单:自定义 sink 内包一个 DefaultRoundRecordSink) |
---
## 2. 建议架构(以 A1 + B1 + C1 + D1 + E1 为例)
```
FunGame.Server-v3/ (解决方案:FunGame.Server-v3.slnx)
├── docs/ # 本文档目录
├── Server/ # ASP.NET Core Web API(宿主)
│ ├── Program.cs # 入口:模块加载 + 服务注册 + 管道
│ ├── Networking/ # 协议层(自研,替代 v2 的 Core 网络)
│ │ ├── WebSocketHandler.cs # /ws 长连接接入
│ │ ├── Protocol/ # 消息帧/信封、消息类型枚举(替代 SocketObject)
│ │ └── ClientSession.cs # 会话模型(替代 ServerModel<T>)
│ ├── Controllers/ # RESTful:账号/房间/商店/回放……
│ ├── Services/ # 业务层
│ │ ├── UserService.cs # 注册/登录/签到/找回密码(迁移 v2 逻辑)
│ │ ├── RoomService.cs # 房间/匹配/Elo(迁移 v2 逻辑)
│ │ ├── EconomyService.cs # 商店/市场/报价(迁移 v2 逻辑)
│ │ ├── GameHostService.cs # 对局宿主:GamingQueue 生命周期管理
│ │ └── MatchService.cs # 匹配队列
│ ├── Data/ # EF Core:DbContext + 迁移(users/rooms/inventory…)
│ ├── Records/ # 回合记录
│ │ ├── RoundRecordSink.cs # 实现 IRoundRecordSink → 归档 + 可选转发
│ │ ├── ArchiveStore.cs # 存档读写(参考 Testing-v3,可改数据库存储)
│ │ └── ReplayController.cs # /api/replay 系列回放端点
│ ├── Modules/ # 模组(编译期引用,如 OshimaGameModules)
│ │ ├── CharacterModule.cs / SkillModule.cs / ItemModule.cs
│ │ └── GameMapModule.cs # 地图(Framework.GameMap)
│ ├── Console/ # 管理控制台(ILogger + 指令解析,迁移 v2 ConsoleModel)
│ └── appsettings.json # JWT/CORS/数据库/SMTP/回放存储配置
├── FunGame.Core (项目引用) # C:\milimoe\FunGame.Core 或 NuGet
└── WebUI/ (可选) # 管理后台/回放台(React,参考 Testing-v3 webui)
```
### 核心运行时流程(一局对局)
```
玩家进房/匹配成功
→ GameHostService 创建 GamingQueue(角色列表, map)
→ queue.RoundRecordSink = RoundRecordSink(本服务实现)
→ 局内:玩家决策点指令 → queue.ProcessTurn / GamingMessageHandler 等价物
└── GamingQueue 内部自动:写 RoundRecord → 调 Sink(即时存档/转发)
→ 游戏结束 → 结算(RankingEntry/CharacterStatistics)→ 归档 → 通知客户端
→ 回放:ReplayController 读取归档;BattleStatePredictor 支撑"任意回合状态还原"
```
---
## 3. v3 Server 必须重建的基础设施(对照 v2 清单)
| # | 模块 | v2 位置 | v3 方案 |
|---|---|---|---|
| 1 | 网络监听与 WebSocket 会话 | Core 提供 | ASP.NET Core `UseWebSockets` + 自研会话模型 |
| 2 | 消息协议(信封/序列化) | SocketObject | 自研(推荐 JSON + 类型标记,复用 v3 JsonService) |
| 3 | 数据库访问 | SQLHelper + SQLQueryExtension | EF Core(或移植 v2 SQLHelper) |
| 4 | 配置系统 | INIHelper(Core) | `Microsoft.Extensions.Configuration`(JSON/appsettings) |
| 5 | 日志 | ServerHelper/TXTHelper(Server + Core) | `ILogger` + Serilog 等 |
| 6 | 邮件 | MailSender(Core) | 自研 SMTP 封装或 MailKit |
| 7 | 认证 | JWT + APIBearer(v2 WebAPI 已有) | 迁移 v2 WebAPI 认证架构 |
| 8 | 任务调度 | TaskScheduler(Core) | `BackgroundService` / `System.Threading.Timer` |
| 9 | 插件体系 | ServerPluginLoader/WebAPIPluginLoader(Core) | 按决策 D:模块化替代或自研加载器 |
| 10 | 控制台指令 | 迁移 v2 ConsoleModel | 指令字典 + ILogger(保留 ban/kick/logout/show/reload) |
---
## 4. 可从 v2 直接迁移的业务代码(高复用)
以下逻辑与 Core 运行时解耦程度高,**迁移成本低**(主要是改命名空间 + 换数据访问 + 换传输参数):
- ✅ `ConnectController` 握手逻辑(人数/黑名单/参数校验)→ 适配新协议
- ✅ `DataRequestController` 的业务方法:房间创建/进入/退出/房主移交/设置、准备、开始游戏流程、聊天
- ✅ 匹配算法 `MatchingRoom`(Elo 扩圈)
- ✅ `DataRequestService`:注册流程、登录流程(含 autokey、check-login key 思路)、找回密码
- ✅ 每日签到、游戏时长统计、重复登录踢下线
- ✅ 商店/市场/报价/物品使用全套经济逻辑(事务化)
- ✅ `ConsoleModel` 指令解析与常用指令
- ✅ WebAPI 的 JWT/CORS/认证处理器架构、`PayloadModel` 包装
**需要重写/放弃的 v2 部分**:
- 所有 `Milimoe.FunGame.Core.*` 网络/传输引用(协议层)
- SQLHelper 调用点(改为 EF/新数据层)
- 插件事件链(v3 无 ServerPlugin)——如果保留插件需求,事件点要么自建事件总线,要么砍掉
- GameModuleServer 机制(v3 无此基类)——对局宿主改为直接驱动 GamingQueue
---
## 5. 建议开发路线(里程碑)
### M0:地基(0.5~1 周)
- [ ] Server-v3 解决方案骨架(slnx + WebAPI 项目 + 项目引用 v3 Core)
- [ ] appsettings 配置体系、ILogger、统一响应模型 `PayloadModel`(迁移)
- [ ] 模块加载骨架:CharacterModule/SkillModule/ItemModule/地图模块 + `Factory.GetGameModuleInstances`
- [ ] 用 Testing-v3 的 OshimaGameModules(或精简示例模组)跑通:**进程内 GamingQueue 一局模拟 → RoundRecord → 归档 → 回放端点**(这是 v3 的核心价值验证)
### M1:网络与账号(1~2 周)
- [ ] WebSocket `/ws` 会话层 + 自研消息协议(握手/心跳/分发)
- [ ] EF Core + SQLite:users/profiles/rooms 迁移脚本
- [ ] 注册(邮箱验证码可选)、登录(密码加密 + 登录 key/autokey)、JWT
- [ ] 管理控制台指令框架(kick/logout/show/ban/reload)
### M2:房间与匹配(1~2 周)
- [ ] 房间 CRUD/进入退出/房主移交/设置/准备/开始流程(迁移 v2)
- [ ] 匹配队列 + Elo 扩圈匹配(迁移)
- [ ] 对局启动:GameHostService 创建 GamingQueue、绑定 IRoundRecordSink、局内指令转发
### M3:局内体验与回放(1~2 周)
- [ ] 局内指令协议:决策点(攻击/技能/物品/移动)、广播(Actions 实时推送,可基于 sink 事件)
- [ ] 断线重连(对局内重连,参考 v2 ReconnectToGame 思路)
- [ ] 回放台:`/api/replay/*` + 可选 React webui(可直接复用 Testing-v3 webui 改造)
### M4:经济与扩展(1~2 周)
- [ ] 商店/市场/报价/签到迁移(EF 数据层)
- [ ] SMTP 找回密码、每日签到、游戏时长统计
- [ ] 排位统计(Rating 计算可参考 Testing-v3 的 `CalculateRating`)
### M5:加固与发布(持续)
- [ ] 并发与事务正确性、压力测试
- [ ] Linux 自包含发布脚本(参考 Testing-v3 publish-linux.sh)
- [ ] 单元测试:迁移 Testing-v3 的 Tests(EffectAutoRecordTest / RoundRecordSinkTest)
---
## 6. 开放问题(建议尽早确认)
1. **客户端是谁?** FunGame.Desktop(v2 客户端)是否同步升级协议?若保留 v2 客户端,Server-v3 需要兼容 v2 的 SocketObject 协议——那网络层改动会大很多。
2. **回放数据存哪?** JSON 归档(简单、Testing-v3 模式)vs 数据库(可查询/统计)vs 远端 POST(DefaultRoundRecordSink)。
3. **要不要账号系统?** 如果 v3 服务器定位为"对战/回放服务",可以砍掉注册/邮箱,仅保留昵称 + JWT 匿名身份(大幅缩短开发)。
4. **插件生态是否保留?** 如果 Oshima 社区依赖 v2 的 ServerPlugin/WebAPIPlugin 插件,需要自研加载器;否则用"模块 + 服务内扩展点"替代。
5. **核心业务与 Testing-v3 的关系**:Testing-v3 的对战模拟/回放功能是直接并入 Server-v3(作为测试与演示能力),还是独立保留?
6. **Core v3 还在迭代**(3.0.0-dev):建议以 ProjectReference 或本地 NuGet 引用 master,跟随提交更新,并关注 nuget 自动发布工作流(正式版发布后可切 NuGet)。
---
## 7. 一句话总结
> **v2 是"Core 给的服务器",v3 是"自己搭的服务器 + Core 给的战斗/回放引擎"。**
> Server-v3 的核心价值 = v3 战斗引擎(GamingQueue)+ 回合记录/即时外发(IRoundRecordSink)+ 回放(BattleStatePredictor/ArchiveStore),叠加自研的网络/账号/房间/经济层;v2 的成熟业务代码可迁移复用,但底层基础设施(网络、数据库、配置、日志)需要在新项目里重建。