木鸡SteadyGame——项目系统设计与数据库设计

仓库与交付材料

一 本次设计解决什么问题

SteadyGame把普通摄像头作为体感输入，在浏览器本机完成姿态识别，让玩家通过身体倾斜控制小球、通过腕部轨迹切西瓜，并体验八段锦两式跟练。三种玩法复用同一姿态输入模块，区别在于世界对象、交互规则和结果形式。

上一轮主要回答用户需要什么、页面如何操作。本轮进一步回答：物品保存什么位置，关节如何转换到舞台，什么情况算命中，谁更新分数，暂停和重试如何处理，哪些数据能够保存。

老师提出了两个直接问题：是否需要Game类表示不同游戏；应补充不同游戏的时序图，讲清物品位置、人体关节与移动物品相交，再判断得分。我们据此形成统一Game抽象、三种独立玩法时序、运动目标相交算法及结算事务设计。

本次接口设计覆盖账号、玩法目录、训练轮次、摄像头处理同意、三种玩法结算、个人历史与统计、报告、导出和排行榜，共22个HTTP操作。字段级请求响应契约见配套接口文档。视频帧和逐帧关节点仅在浏览器本机处理，不上传至业务服务。

术语约定：UML为统一建模语言，API为应用程序接口，LLM为大语言模型，CSRF为跨站请求伪造，UUID为通用唯一标识符，P95为观测值的第95百分位。后文时长均为毫秒，业务日期使用UTC。

二 系统架构与功能模块

2.1 总体架构

浏览器负责Vue页面、摄像头生命周期、MediaPipe姿态推理、动作映射、Game运行和Canvas绘制。Spring Boot业务服务负责身份、轮次配置、结果校验、明确保存、个人历史与导出。MySQL保存业务摘要；导出文件放私有目录，通过鉴权接口下载。

采用同源HTTPS入口和模块化单体，适应当前八人团队与课程项目规模。推理和绘制分频运行，模型忙时只处理最新帧，禁止积压旧视频。模型适配层把MediaPipe内部输出转成17个命名关节，游戏不依赖模型内部下标。

姿态识别和碰撞判定在浏览器本机完成，减少视频传输与服务端推理开销；服务端校验客户端结果摘要中的字段、计分公式和轮次归属。

2.2 功能模块层次

Camera只管理视频流，Pose只识别关键点，Motion只生成控制信号。Game根据规则更新世界，Renderer只绘制，ResultGateway只负责提交与重试。职责边界清楚后，各成员可用固定样例先开发，再接入真实识别。

三 类设计与 Game 问题回应

3.1 三个不同的概念

Game统一三种玩法的运行生命周期。 Game提供initialize、update、pause、resume、snapshot、finish、dispose；各玩法实现维护自身物体与规则。GameCoordinator负责流程与唯一结算，GameFactory负责创建对象。

小球游戏拥有Ball、五个Target和若干Obstacle；切西瓜维护Fruit和左右腕轨迹；八段锦持有StageMachine。CollisionDetector只判断几何相交，ScorePolicy按已确认的计数算分，HTTP提交交给ResultGateway。新增第四玩法实现Game并注册工厂即可，摄像头和姿态模块保持公共契约。

GameSession与GameResult最多一对一，数据库用结果表的session_id主键实现唯一结算。八段锦score固定为null，动作完成情况由阶段摘要表示。

四 物品位置 相交算法与三种游戏时序

4.1 先统一坐标和时间

原始关节坐标对应未镜像视频，x与y取值0至1，left和right按人体解剖学命名。舞台使用等比缩放和留白，视频、腕点叠加、游戏对象共用同一坐标变换，镜像只做一次。碰撞使用CSS逻辑像素，不在宽高分别归一化后直接套圆形距离公式。

移动物品保存id、previous、position、velocity、radius、spawnAtMs和state。每次碰撞都对齐同一时间区间；生成或销毁的物品只参与其存活区间。暂停冻结活动时钟和物品，清空腕轨迹，恢复首帧只建立起点。

设计初值为所需关节置信度至少0.6、快照不旧于250ms、连续腕点间隔不超过200ms；设备验收时按实际识别表现校准。

4.2 平衡小球时序

肩髋相对偏移减去自然站姿基线，再经死区、滤波与限幅形成leanX。Game据此移动小球，保存小球与目标的前后位置，对两圆相对运动做相交检测。人体关节在这里用于控制小球，实际接触对象是Ball和Target。

本局60秒、5个目标，每目标10分；小球到达终点线额外加50分，最高100分。目标先从active改consumed，再targetsHit加一并更新分数。障碍接触只记collisions，不扣分；持续重叠不逐帧累加。正常计时结束为completed，提前退出为aborted。

4.3 切西瓜时序

腕轨迹为A到B，同一区间水果圆心为C0到C1。令R0=A-C0、R1=B-C1、d=R1-R0；投影参数u=clamp(-(R0点积d)/(d点积d),0,1)。若d长度近零，取u=0。当length(R0+u*d)不大于水果半径加刀刃半径时，才判为相交。

该算法同时处理腕点快速穿过和水果自身移动。水果曲线轨迹按物理步分段处理，不能把最终圆心套到过去整段腕轨迹。一次挥手可切多个真实相交的不同水果，每个水果都要独立检测。

数值例：腕点从(200,300)到(400,300)，水果从(300,280)到(300,320)，水果半径35、刀刃半径8，相对最短距离为0，因此命中。命中立即把该水果设为consumed，再cutCount加一。若之前切中1个，现在切中2个，分数从10变20；远处未相交的水果保持active。

本局60秒，score=10*cutCount。双手同帧命中同一id只计一次，旧轨迹重放不重复加分；漏切无得分，maxCombo只展示。没有隐藏连击倍率。

4.4 八段锦两式时序

两手托天理三焦（tuotian）和调理脾胃须单举（danju）各有ready、raise、hold、recover四阶段。使用腕肩高度、肘角和左右关系判断，必须按顺序且连续满足本阶段条件；低置信、多人、过期时暂停并清空当前候选保持时间，已完成阶段不重复累计。

两式共8阶段完成时outcome=completed，提前退出或达到15分钟安全上限但未完成时为aborted。上传两式汇总和受限action_attempt摘要，score固定null。阶段摘要记录软件规则观察到的条件，用于流程反馈，不用于专业动作质量或健康评价。

五 接口设计与数据库设计

5.1 接口设计与模块契约

所有写请求带X-CSRF-Token，登录态使用SGSESSION，匿名态使用SGGUEST。JSON响应统一code、message、data，请求追踪号放X-Request-Id响应头。登录轮换账号会话和CSRF，保留同浏览器的SGGUEST以支持用户稍后选择保存。

创建轮次由客户端生成sessionId并和mode提交，该ID同时作为训练会话主键和幂等依据；配置由后端返回并冻结。三种玩法共用创建、同意、开始和查询，只在结果提交时区分路径。暂停恢复和姿态识别属于本机模块。

下面把“模块接口”和“HTTP接口”分开列出：前者说明模块间调用的方法、数据和职责；后者说明浏览器访问服务端的路径。浏览器内部方法是模块间调用契约；HTTP字段、状态码和响应头以配套OpenAPI为准。

浏览器端模块接口

服务端模块接口

对外HTTP接口目录（统一前缀 /api）

配套接口文档中的逐项说明包含每个操作的请求体、响应体、状态码和示例；机器可读版本为OpenAPI JSON。模块职责和调用关系与系统设计说明书“体系结构模块接口”一节及答辩PPT第3页的模块接口页对应；博客中的目录用于展示模块边界和调用入口，具体字段级契约应与OpenAPI及逐项说明一起核对。

结果以session为幂等边界：相同结果重试返回原结果，不同内容返回409。后端校验路径、请求和轮次mode一致，trackingDurationMs不超过activeDurationMs，活动时长不超过本轮配置，小球score=targetsHit10+(reachedEnd?50:0)，最高100分；切西瓜score=10cutCount，并按60秒配置中的spawnIntervalMs与activeDurationMs校验动态水果数上界；八段锦score=null，阶段尝试与汇总一致。

5.2 ER分析与表结构

查看ER图和表结构（数据库设计说明书PDF）。

用户与轮次一对多，轮次与结果一对零或一；当前轮次归属为账号或访客二选一。保存不是复制一份成绩，而是在事务中绑定账号并设置saved_to_history。game玩法目录变化不修改已创建轮次冻结的config_snapshot和rules_version。

公共查询字段使用关系列，玩法差异汇总放经过严格验证的JSON。历史索引为user_id、saved_to_history、finished_at、id，保证本人筛选与稳定倒序。时间范围左闭右开且不超过366天，pageSize不超过100。

结算事务先锁轮次，再校验、插入唯一结果、更新轮次终态；保存事务再次验证原归属和明确同意。跨表的score公式和JSON阶段规则由服务层验证，MySQL CHECK只承担本行可表达的约束。

created/active轮次从创建时起24小时清理，未保存结果从结算时起24小时清理；SGGUEST滑动闲置24小时且不早于其未保存轮次的expiresAt。已保存历史不自动过期。导出文件从成功生成后起算10分钟，排队不提前过期。数据库表名、字段和关系以配套数据库设计说明书、ER图和DDL为准；三份材料均列出上表11张表，主要实体关系与DDL外键能对上，字段类型、默认值、索引和CHECK约束以DDL为准。数据库设计说明书第4.2.8节和附录A将action_attempt是否落库列为待决事项，而ER图和DDL已包含该表；本博客的数据表描述遵循ER图与DDL。接口提交的attempts数组保持阶段顺序，服务端先按规则快照校验顺序，再在结算事务中按数组顺序写入action_attempt；created_at用于记录时间，不承担同一毫秒内的排序。公开榜按训练结果和轮次派生，不另建表。

六 安全 权限与健壮性

6.1 权限设计

后端从Cookie身份上下文确定userId；替换sessionId或exportId仍需通过拥有者校验，非本人统一返回404。UUID用于资源标识，资源访问仍按拥有者校验。

6.2 具体安全措施

密码使用自适应哈希库，账号Cookie配置HttpOnly、Secure、SameSite，登录成功轮换会话。全部写操作验证CSRF，数据库使用参数化查询。昵称按文本转义，禁止把用户输入直接放入v-html；导出CSV文本单元格防公式注入。

导出文件放在非公开目录，下载时再次鉴权并检查有效期，客户端不能提供服务器文件路径。日志只保留必要追踪信息，不写Cookie、密码、视频和逐帧姿态。摄像头用途告知、浏览器权限和成绩保存同意分别处理。

6.3 异常与恢复

授权拒绝、模型失败、低置信、多人和数据过期都必须有具体提示。无效输入冻结时间与世界，恢复重新建立基线，不补算暂停时间。退出、撤回或结束时停止所有MediaStreamTrack，取消游戏与推理循环。

网络异常保留不可变的结算摘要，原session原结果重试；不能把提交失败显示为已保存。数据库失败整体回滚，导出任务使用租约恢复，私有文件生成成功后才发布下载入口。

七 需求改进及过程

改进过程为：核对老师意见和本次作业要求，以配套数据库设计材料、系统设计说明书和本次接口契约为共同依据，确定模块职责与字段映射，补充对象、状态和时序设计，建立边界样例，再对系统设计、接口文档与博客交叉核对。

八 三个LLM设计协作示例

本节用三张对话截图展示三个LLM设计协作示例，每张图对应一个示例。截图记录了提问与回答；相关设计结论均结合本项目材料核对。

示例一 模块调用链与依赖方向

示例二 结果字段边界与重复提交处理

示例三 动作规则版本与尝试记录约束

九 本次工作流程与团队绩效

本次工作按需求核对、系统设计、数据库映射和材料整合推进。

下表是团队确认的本次作业实际分工与贡献度比例，合计100%，用于小组成绩向个人成绩映射。

协作以华为云团队仓库为统一基线，按模块分支开发，合并前由对应交叉评审人检查。接口字段变更同步更新契约与消费者清单，图文从统一图源重新生成。

十 逐周开发计划与每人开发责任

10.1 逐周计划

以下为2026年预期开发计划，按周列出里程碑与交付物；11月中下旬安排两周项目冲刺，覆盖作业要求指定的冲刺阶段。

10.2 每人开发责任

十一 验证结果与验收计划

本次完成资料核对、目标设计、图源和PNG生成，并运行22项参考程序用例。OpenAPI、逐项说明和Postman集合的22个接口操作已交叉核对；请求体可解析为JSON，Postman脚本通过语法检查。用例覆盖相对运动、擦边、零长度、镜像、双手去重、暂停断轨及计分等边界。

验收计划覆盖真实浏览器中的摄像头权限与隐私流程、独立MySQL中的迁移和并发结算与归属测试，以及桌面和手机设备的性能记录；识别置信度、时序窗口和性能目标在设备验收时校准。

十二 参考资料

1. 课程本次作业
2. 上一轮团队博客
3. GB/T 8567-2006 官方信息
4. OMG UML 2.5.1
5. MediaPipe Pose Landmarker Web
6. MDN getUserMedia
7. OWASP 会话管理
8. MySQL CHECK约束