[T.6] 团队项目：技术规格说明书

项目	内容
这个作业属于哪个课程	课程社区
这个作业的要求在哪里	作业要求
我在这个课程的目标是	凝聚整个团队通过一定的软件开发流程，在预计时间内发布"足够好"的符合用户需求的软件，并证明其是可维护和持续发展的，并在其中做出应有的贡献，提升进行软件工程开发的能力。
这个作业在哪个具体方面帮助我实现目标	通过实验作业，明确了平台实现所有功能所需的技术规范，以及相应测试流程和部署维护方式，为后续敏捷开发打下了坚实的基础。

说明

该文档旨在说明WildCard系统的技术设计方案，明确各部分的技术边界、模块划分、功能实现、测试标准、性能指标和风险控制等，为后续实现、联调、测试和维护提供统一依据。

系统概述

WildCard是一款支持用户通过低代码形式构建卡牌游戏规则的产品，用户可以构建游戏规则、游玩自定义游戏、上传自定义规则以及游玩他人构建游戏等。

概念与术语

• Web app：指基于浏览器运行、具备接近原生应用交互体验的网页应用。本项目采用 Web App 形式，以支持跨平台访问，包括桌面端浏览器和移动端浏览器。
• 规则：规则是对某种卡牌游戏玩法的结构化描述，包含基础信息、牌属性定义、玩家属性定义、牌型规则等内容，支持导出为json。
• 规则编辑器：规则编辑器是面向创作者的低代码图形化构建界面，用于配置牌、玩家、牌桌属性，绘制流程图，构建牌型规则、对局流程、结算流程和自定义方法流程。
• 流程图节点（前端中可视化节点）：规则编辑器中的基本构建单元，对应执行组件、值组件、运算组件、逻辑组件、控制流组件等可视化模块。
• 房间：一次联机对局的会话载体。
• 响应式适配：根据屏幕尺寸、方向和交互设备差异，动态调整布局和组件表现，基于媒体查询等方法实现。

技术栈说明

程序设计语言

前端：html + typescript + css（本项目包含规则编辑器、流程图节点等内容，静态类型有助于降低维护成本，因此采用typescript而不使用javascript）

开发框架

前端

• vue3：前端核心框架，负责组件化开发和响应式视图更新
• Vue Router：负责单页应用路由管理
• Pinia：负责全局状态管理
• WebSocket：负责实时通信
• 辅助工具：针对规则编辑器可使用Vue Flow；针对游戏对局等华丽效果考虑vue3-pixi；对于普通页面设计可采用Element UI、Naive UI；使用vite进行项目构建；使用vitest进行单元测试

运行环境

前端

开发环境

• Node.js 20.x 或更高 LTS 版本
• 现代浏览器
• Npm

用户运行环境

• 支持现代 JavaScript 特性的主流浏览器。前端基于vue3开发，最低要求需支持原生ES2016的现代浏览器
• 项目实际开发与部署以Chrome、Edge、Firefox及Safari为主要兼容目标（可改）

后端

• Rust: Edition 2024, 1.95.0

软件架构

WildCard可以分为前端Web App子系统、后端业务服务子系统、数据存储与日志子系统。

前端Web App子系统

主要功能

• 页面渲染与用户交互
• 规则编辑可视化
• 规则市场浏览与搜索
• 房间创建、加入
• 游戏对局界面展示
• 对局历史和回放播放
• 评论、收藏与举报
• 用户资料展示

模块划分

• 用户模块：支持用户通过页面登录、注册与找回密码等操作，支持用户修改昵称与头像等操作，展示基础的用户信息，同时维护和记住用户登录状态
• 规则市场模块：支持游戏规则的展示，支持搜索、筛选、排序等操作，支持游戏规则详情展示，支持收藏、评论与举报
• 规则编辑器模块：支持通过图形化界面进行包括规则基础信息编辑、牌属性定义、玩家属性定义、对局流程编辑、结算流程编辑等在内的各种操作，构建自定义规则
• 房间与联机模块：支持创建房间，支持通过房间号、链接以及二维码等方式加入房间进行游戏，支持房间内玩家展示，支持游戏开始、结束与掉线提示，支持实时对局操作与局内互动
• 回放模块：支持对局历史展示与回放播放

软件设计与实现

前端

代码编写

• 页面与路由：实现系统全部页面与路由守卫，包括公共页面路由、登录态保护路由、房间与回放动态路由、异常跳转页等
• 通用组件：实现跨页面复用的通用组件，例如弹窗、标签、按钮等
• 业务组件：实现规则卡片、玩家面板、手牌区、出牌区、评论面板、编辑器节点面板、属性配置等业务级组件
• 状态管理：实现各业务模块的状态管理，包括全局状态、错误状态等
• 图形化编辑器：实现节点模型定义、边连接规则、节点属性表单、类型校验、草稿保存恢复等
• 对局交互：实现出牌选择、不出牌操作、房间聊天、对局状态更新、回放播放等

后端

需求

首先整理后端架构中需要实现的需求。

• 网络联机：支持多名玩家通过网络连接至同一个游戏房间进行实时对战。
• 规则解耦与高扩展性：框架必须将“底层网络通信/房间管理”与“上层具体游戏规则”严格分离。游戏规则应作为可插拔的模块（接口实现）接入系统。
• 状态驱动：将游戏对局抽象为有限状态机（FSM），通过状态转移及其副作用（Side Effects）来推进游戏进程。

根据以上的需求，设计总体架构如下：

总体架构设计

系统采用中心式架构（Client-Server），服务器作为绝对的权威节点，负责维护全局状态、校验操作合法性并驱动状态机流转。客户端作为“纯展示与输入采集终端”（Dumb Client），基于服务器下发的数据渲染界面。

架构分层：

1. 网络与会话层

系统在网络层采用非阻塞的异步 I/O，负责维持长连接。前期 Demo 采用 TCP, 成品中使用 WebSocket。这一层管理玩家的接入、离开以及房间的生命周期。

网络层 IO 需要具备的接口如下：

• 广播：服务器单向将当前状态或事件通知给房间内的所有玩家。
• 单点问答：服务器向指定客户端发送需要玩家做出回应的消息，并挂起当前协程，等待该客户端的异步响应。

2. 通用状态机引擎层

游戏的整个生命周期被抽象为有限状态机。状态的转移由服务器主动发起询问并由玩家的输入事件驱动。

• 状态：表示游戏当前所处的阶段。
• 转移条件：对玩家的相应的判断（如：玩家的输入是否合法，判断玩家相应的出牌是否大于上家）。
• 转移副作用：
  • 状态变更
  • 牌桌数据更新
  • 网络分发（调用网络层的广播、单点问答）
  • 每次转移的过程，对应着一次协程的挂起

以斗地主为例的状态流转：

• `State A (抢地主阶段)`：轮询玩家叫分 → 确定地主并分配底牌 → 转移至 C。

• `State B (出牌阶段)`：轮询出牌 → 校验牌型 → 某玩家手牌清空 → 转移至 D。

• `State C (结算状态)`：计算得分，广播赢家。

3. 游戏逻辑实现层

• 实现具体的游戏规则模块
• 定义该游戏特有的状态集合（如准备、抢地主、出牌、结算）。
• 封装牌型解析与合法性校验算法。

在中心式服务器架构下，状态数据实行严格的信息隔离：

• 全局数据：驻留在服务器内存中，包含完整牌堆和所有人的手牌。
• 局部视图：服务器在广播或单播时，仅下发该玩家有权知晓的数据（如自身手牌、公共桌面牌、其他玩家的剩余牌数）。

4. 客户端/UI 展现层

采用了此架构后，前端只需要完成下面的渲染任务和本地校验：

• 牌桌区：渲染服务器下发的公共信息（上一家出的牌等）
• 手牌区：渲染服务器下发的己方卡牌，支持多选交互。
• 操作区：渲染服务器询问所能回应的操作。

客户端本地校验：

如果每次出牌都必须等服务器返回 true/false，在弱网环境下，玩家点击“出牌”按钮后会卡顿几百毫秒，体验极其糟糕。这就要求客户端和服务器必须运行同一套规则校验代码。

玩家点击出牌。客户端立刻在本地运行算法，如果选的牌连“顺子”都构不成，或者打不过上家，本地直接警告“出牌不合法”，无需网络请求。

只有本地校验通过，才发给服务器。服务器再算一遍，确认无误后，执行状态转移。

一次完整的“出牌”流程如下：

1. [服务器] 广播轮到 Player 1 出牌，上家牌型是“对 3”。
2. [客户端] P1 选中“对 5”，点击出牌。
3. [客户端逻辑库] 本地执行 compare([5, 5], [3, 3])，返回 True。
4. [客户端 UI] UI 立即响应，从手牌移出两个 5，并向服务器发送相应。
5. [服务器逻辑库] 收到请求，同样执行 compare([5, 5], [3, 3])，确认合法。
6. [服务器] 执行状态转移，向全房间广播 Player 1 打出的牌。
7. [其他客户端] 收到广播，更新桌面显示。

系统文档编写

• 功能规格说明书：在需求/功能产生变动时进行维护
• 技术规格说明书：在实现阶段补充功能的详细逻辑设计、数据库设计和API接口设计
  • 功能的详细逻辑设计：输入、具体流程、输出、边界条件、错误处理、依赖关系
  • 数据库设计：表名、字段名、类型、约束、说明
  • API接口设计：接口名称、接口类型、接口路径、接口行为、请求字段、响应字段、错误处理（错误码和含义）
• 每日例会报告：每个人的工作（昨天已完成的工作、今日计划完成的工作、遇到的困难）、燃尽图、每日例会的照片

测试计划

测试架构总体设计

测试设计

本项目采用经典测试金字塔模型，从下至上分为三层：

• 底层：单元测试，覆盖后端核心逻辑，运行速度快，不依赖外部服务，每次代码提交都要执行
• 中间层：集成测试，覆盖 API 接口、数据库交互、缓存、WebSocket 信令、多客户端场景，需要启动真实服务或模拟客户端，在合并到开发分支前执行
• 顶层：端到端测试，模拟真实用户在浏览器中的完整操作流程，在部署前执行

统一测试技术栈

类别	选用技术
后端单元测试	Rust 内置测试框架（cargo test + mockall）
后端集成测试	Axum TestClient、模拟 WebSocket 客户端
前端测试	Vitest + Vue Test Utils + jsdom
端到端测试	Cypress
压力测试	Locust
网络故障测试	Linux tc 命令 / Mahimahi
CI/CD	GitHub Actions

---

后端单元测试

测试目标：验证核心业务逻辑的正确性，不依赖数据库、网络或外部服务。使用 mockall 模拟外部依赖。

测试范围：

• 房间状态机：等待中、游戏中、已结束等状态的合法转换
• 短码生成器：房间 ID 和规则 ID 的唯一性生成
• 牌型匹配器：各种牌型的识别准确性
• 等等

测试方法：使用 Rust 内置测试框架（cargo test），mockall 模拟外部依赖。

执行频率：每次代码提交时执行。

---

后端集成测试

测试目标：验证各模块之间的协作，需要启动真实服务或模拟客户端。

API 接口测试

测试范围：

• 用户系统接口：注册、登录、密码修改、用户名修改
• 房间管理接口：创建房间、加入房间、退出房间
• 规则管理接口：保存规则、加载规则、提交审核
• 等等

测试方法：使用 Axum TestClient 发送请求并验证响应。数据库相关测试使用测试数据库，每个测试用例使用事务回滚保证隔离。缓存相关测试使用测试环境缓存实例，每个测试用例执行后清理测试数据。

WebSocket 信令与多客户端场景测试

测试范围：

• 连接建立与断开
• 房间加入与离开
• 重连机制
• 主动断线重连后的状态恢复
• 状态同步
• 多人对局正常流程
• 等等

测试方法：模拟多个 WebSocket 客户端，模拟多人加入、消息广播、离开房间、断线重连等操作，断言消息接收正确性及各客户端状态一致性。

执行频率：每次代码提交和 Pull Request 时执行。

---

前端测试设计

测试目标：验证 Vue 组件渲染、用户交互和前端逻辑的正确性。

测试范围：

• 通用组件：弹窗、标签、按钮等组件的渲染和点击事件
• 业务组件：规则卡片、玩家面板、手牌区、出牌区、评论面板、编辑器节点面板、属性配置等组件的独立渲染和交互
• 图形化编辑器：节点模型数据结构验证、边连接规则校验、节点属性表单的类型校验、草稿保存恢复逻辑、撤销/重做功能、规则导出JSON正确性
• 状态管理：用户状态（登录退出）、游戏状态（回合切换、出牌、状态更新）、编辑器状态（节点增删改查、选中状态）

测试方法：使用 Vitest 作为测试运行器，Vue Test Utils 进行组件挂载和交互模拟，jsdom 模拟浏览器 DOM 环境。

执行频率：每次代码提交时执行。

---

端到端测试设计

测试目标：模拟真实用户在浏览器中的完整操作流程，验证前后端集成正确性。

测试范围：

• 用户注册登录全流程
• 开发者创建规则并提交审核全流程
• 多人联机完整对局

测试方法：使用 Cypress 在真实浏览器中运行。

---

网络故障测试

测试目标：验证在网络层异常环境下系统的健壮性。

测试范围：

• 网络连接突然中断后的恢复能力
• 基础延迟环境下的操作响应

测试方法：使用 Linux tc 命令或 Mahimahi 工具模拟网络延迟、丢包、连接中断。

---

压力测试设计

测试工具

使用 Locust 进行压力测试。Locust 是一个基于 Python 的开源压力测试工具，支持 Web 界面实时监控、分布式运行、自定义测试场景。

测试目标

验证系统在高并发场景下的性能表现，核心关注两个指标：

指标	含义	单位
吞吐率（RPS）	服务器每秒能处理的请求数	请求数/秒
用户平均请求等待时间（RTT）	从发出请求到收到完整响应的时间	毫秒

测试范围

• 房间创建接口并发能力
• WebSocket 信令服务器并发连接能力

---

CI/CD 集成设计

测试目标：实现代码提交后的自动化测试与部署。

技术选型：GitHub Actions。

执行策略

测试类型	触发条件	执行内容
冒烟测试	每次 Pull Request	核心 E2E 流程
完整回归测试	每天凌晨定时	全部 E2E 场景
压力测试	主分支合并 / 每天凌晨	Locust 压测
网络故障测试	每周 / 版本发布前	手动或定时触发（不在 CI 流水线中自动执行）

测试流程

1. 后端单元测试
2. 后端集成测试（含 API 接口、WebSocket 信令与多客户端场景）
3. 前端单元测试
4. 端到端测试（冒烟）
5. 压力测试（仅主分支或定时任务）
6. 部署上线（仅主分支，部署后冒烟验证）

软件性能

WildCard 是一个基于 Web 的自定义规则卡牌联机游戏平台。系统性能量度覆盖浏览器交互、实时通信、并发承载、资源加载、异常恢复和部署运行等方面，性能量度框架如下。

量度维度	主要对象	关注重点	量度方式
接口交互性能	注册、登录、密码修改、创建房间、加入房间、保存规则、加载规则、提交审核等接口	请求成功率、响应时间、错误率	通过后端集成测试和压力测试统计接口耗时与错误情况
实时通信性能	WebSocket 连接建立、断开、重连、广播、状态同步	连接稳定性、重连恢复能力、消息广播时延、状态一致性	模拟多个 WebSocket 客户端进行联机场景测试，并结合网络故障注入测试验证
前端交互性能	流程组件编辑器中的拖拽、移动、删除、连线等操作	编辑流畅度、交互反馈速度、页面稳定性	通过前端组件测试和真实浏览器场景验证编辑体验
资源加载性能	背景、卡背、卡面等自定义素材	加载时间、资源体积、弱网环境表现	对不同规格素材进行加载测试，并结合素材压缩前后结果对比分析
回放访问性能	历史对局列表、回放进入、时间轴跳转、视角切换	回放打开速度、跳转反馈速度、状态还原正确性	通过端到端测试和人工校验结合的方式验证
并发承载性能	房间创建接口、WebSocket 信令服务	并发请求承载能力、稳定连接能力、运行期资源占用	使用 Locust 进行压力测试，并在目标服务器环境下记录 CPU、内存和带宽占用
异常恢复能力	延迟、丢包、断链等网络异常场景	恢复时间、恢复成功率、恢复后状态一致性	使用 tc 或 Mahimahi 模拟网络异常环境进行故障测试
部署运行适配性	Ubuntu 24.04 云端部署、浏览器访问	部署成功率、部署后可用性、跨端可访问性	通过 GitHub Actions、Docker 部署和部署后冒烟测试验证

核心性能指标包括以下五项：

• 房间创建接口在并发场景下的稳定性
• WebSocket 信令服务器的稳定连接能力
• 断线重连后的状态恢复能力
• 高规格图形素材加载时的性能表现
• 对局回放的打开与跳转响应速度

上述指标直接对应系统的核心使用路径，是性能验证的重点内容。

实现阶段统一记录以下数据：接口响应时间分布，WebSocket 稳定连接数与消息广播延迟，素材加载耗时与压缩效果，回放打开与跳转耗时，以及目标部署环境下的 CPU、内存和带宽占用曲线。上述数据构成系统性能基线，也是发布判断的直接依据。

 

软件的能力边界

WildCard 的能力边界建立在“浏览器端交互、自定义规则构建、房间制联机、规则审核后发布、对局回放”这一组已定义能力之上。文档中的能力表述以现有规格说明书中已经定义的功能与流程为边界。

边界主题	当前能力范围	边界说明
客户端形态	Web 端，适配 PC 和移动端浏览器	当前文档只定义了网页端形态，不包含原生移动端应用或离线客户端
联机模型	以房间为单位的多人联机	当前联机流程围绕房间 ID、二维码、密码和房主机制展开，不适用于超大规模开放式实时会话
规则表达方式	通过平台提供的流程组件、类、属性和方法构建规则逻辑	当前文档不支持任意脚本上传、任意代码执行或无限复杂规则编排的依据
联机规则来源	经过审核并上架规则市场的规则可进入联机流程	未审核规则不应进入公开联机路径，这是平台治理边界的一部分
图形资产能力	支持背景、卡背、卡面等自定义素材	现有文档已明确高规格素材可能导致加载缓慢，文档不对任意大尺寸素材作无条件性能承诺
回放能力	支持历史对局查看、回放进入、时间轴控制和视角切换	当前仅定义了回放查看能力，并未扩展到回放编辑、分支回放或复杂检索分析
管理治理能力	支持审核与举报管理	当前机制以人工审核、人工处理为主，不应表述为完全自动化内容治理系统
性能承诺边界	明确建立完整测试与性能验证机制	在缺乏实测数据前，文档不承诺具体吞吐量、具体延迟上限或大规模公网承载能力

系统当前按单机云主机部署能力进行规划和验证。目前的部署环境为 Ubuntu 24.04、腾讯云 2 核 CPU、4GB 内存、60GB SSD 云硬盘和 5Mbps 带宽，并采用 Docker 部署与 GitHub Actions 自动化流程。在未引入集群化、水平扩容、消息队列、CDN 等设计之前，系统能力表述限定为“在既定部署环境下满足阶段功能与性能要求”。

 

出口条件

WildCard 的发布标准同时覆盖功能验收、测试验证、异常恢复、部署验证、内容治理和性能验证。软件发布前必须同时满足以下条件。

类别	出口条件
阶段功能完成度	若以 Alpha 阶段为目标，则应至少完成用户系统基础功能、自定义规则构建功能和联机功能；若进入 Beta 阶段，则还应补齐规则市场、对局回放、审核与举报等后续功能
自动化测试通过	后端单元测试、后端集成测试、前端测试、端到端测试应纳入 CI/CD 流程并稳定通过
网络异常验证完成	应完成延迟、丢包、连接中断等故障场景测试，验证断线重连和状态恢复机制有效
压力测试完成	应对房间创建接口和 WebSocket 信令服务进行压力测试，并形成可复核的测试记录
部署环境验证通过	应在既定服务器环境中完成 Docker 部署，并在部署后通过冒烟测试
内容审核链路可用	规则提交审核、审核通过后上架、违规内容举报与处理链路应完整可用
素材治理机制可用	自定义图形素材上传后，应具备预压缩或等效治理机制，避免高规格素材直接破坏系统体验
性能基线形成	核心接口、实时通信、资源加载和回放访问应形成与目标部署环境相匹配的性能基线记录

正式发布判断重点包括以下三项：

• 房间创建接口的并发稳定性
• WebSocket 稳定连接能力
• 断线重连后的状态恢复能力

这三项直接决定联机玩法是否成立，属于核心技术出口条件。若这三项尚未通过压力测试和异常测试验证，即使功能已经实现，软件也仅可作为内部试运行版本或阶段性验收版本，不作为稳定正式版发布。

 

技术风险识别和评估

WildCard 的主要技术风险集中在实时同步、单机资源承载、素材加载、测试覆盖、回放实现和跨端适配等方面。主要风险如下：

风险项	风险说明	可能性	影响程度	应对策略
WebSocket 多客户端状态不同步	联机系统依赖多客户端实时同步，若广播、重连或状态恢复出现问题，将直接破坏对局正确性	高	高	优先补齐 WebSocket 集成测试、断线重连测试和网络故障测试；对关键状态变更建立一致性校验
单机部署资源不足	当前部署环境为单台 2C4G5M 云主机，随着房间数、连接数和资源加载压力上升，可能出现 CPU、内存和带宽瓶颈	高	高	尽快完成房间创建与 WebSocket 压测，记录资源曲线；在需要时升级资源规格，并保持后端具备迁移和扩容条件
高规格素材拖慢加载	用户上传高分辨率背景和卡面素材后，可能导致加载过慢、前端内存压力过大或弱网体验恶化	高	高	落实素材预压缩、尺寸限制、格式限制和上传校验，并对代表性素材做专项加载测试
审核与举报链路不完整	自定义规则和素材带来内容合规风险，若审核链路未闭环，违规内容可能进入公开市场	中	高	将审核链路视为发布前置条件，未通过审核的规则不得上架或公开联机；完善举报处理流程
测试设计已定义但落地不足	现有技术规格说明书中的多项测试仍处于待完善状态，若未补齐测试直接发布，回归风险较高	高	高	先完成最小可发布测试集，包括单元、集成、端到端冒烟、网络故障和压力测试
回放功能实现复杂度高	回放功能要求正确记录和重建对局过程，若数据结构、索引和恢复逻辑设计不足，容易出现状态错乱或性能下降	中	中	在实现前明确回放事件记录方式、恢复机制和数据保留策略，并进行专门测试
浏览器与终端适配不稳定	图形化规则构建界面包含拖拽、连线、属性编辑等复杂交互，不同终端上的兼容性风险较高	中	中	明确支持的浏览器范围，对桌面端和移动端分别进行关键路径验证
邮件链路依赖风险	注册、找回密码和邮箱修改都依赖邮件发送流程，外部邮件服务异常会影响账户系统关键路径	中	中	在实现阶段补齐邮件发送、重试、超时和失败提示策略，避免关键流程完全依赖单一链路
规则复杂度增长导致性能波动	规则由流程组件、类和方法组合构成，若缺乏复杂度控制，可能影响前端编辑和后端执行表现	中	中	在实现阶段补充规则规模约束，并对复杂规则做代表性性能验证

 

系统的核心技术风险集中在“实时联机能力是否稳定成立”与“单机部署条件下是否能承受目标负载”两个方面。发布前的技术验证重点包括 WebSocket 同步链路、房间创建接口、网络异常恢复、素材治理和压力测试结果固化。上述关键链路形成稳定验证证据后，系统方可进入正式发布流程。

 

软件部署和维护

部署环境

项目整体基于网页web端实现，目标适配PC、移动端等用户端，项目整体将统一部署到服务器云端，相应云端开发部署环境为ubuntu 24.04，目前已在腾讯云上购买了相应云服务器，其基本配置如下:

• 2核 CPU，4GB 内存，60GB SSD云硬盘 5Mbps 带宽

部署方式

使用GitHub Action运行自动化测试、打包Docker镜像和自动部署。

Docker部署

为了保证部署环境和开发测试环境的一致性，以及CI 部署的方便性，我们采取了Docker 部署方式。

运行

服务端就在上述的服务器环境下进行运行。

用户端则没有特殊的要求，只要有浏览器即可。

维护

同样是在上述服务器环境下进行，通过新建分支并在其上对可能出现的bug进行修正。