福大兄弟队——项目系统设计与数据库设计

这个作业属于哪个课程	2601_FZU_SE 软件工程实践
这个作业要求在哪里	团队作业：概要设计和数据库设计
团队名称	BroFuTo 福大兄弟队
这个作业的目标	将校园生存游戏的需求转化为可实现的体系结构、模块、类、接口和数据库设计，明确离线运行与云存档的协作方式，落实成员分工及每周开发里程碑。
其他参考文献	GB/T 8567—2006《计算机软件文档编制规范》；OMG UML 2.5.1；SQLite、Godot、FastAPI 官方文档；文末参考资料。

目录

仓库与交付材料

华为云团队仓库：BroFuTo 团队仓库

材料	仓库或共享文档链接
系统设计说明书	文件 - BroFuTo - Repo
数据库设计说明书	文件 - BroFuTo - Repo
系统设计和数据库设计答辩 PPT	文件 - BroFuTo - Repo
系统设计和数据库设计评审表	BroFuTo_项目系统和数据库设计评审表

项目概况与术语

BroFuTo 是一款以福州大学旗山校区为题材的单人二维俯视角生存游戏。玩家控制角色走位，武器自动攻击；在波次中击败敌人、获取经验与学分，再通过升级选择、超市购买和武器调整形成构筑。

游戏包含七张按顺序解锁的普通地图，每张地图十波，第十波挑战对应首领。晋江楼首通后解锁无尽模式，每十波轮换地图并挑战对应首领。内容设计包括七个角色、十八项玩家属性、十六款武器、二十款道具，以及校园地图、敌人与首领图鉴。

本次设计围绕三个问题展开：玩法模块怎样协作，游戏进度怎样可靠保存，不同设备之间怎样由玩家主动同步。 客户端采用 Godot 与 GDScript，面向 Windows；云服务提供用户名密码认证和存档上传、下载，离线玩法在本机运行。

术语	本文含义
UML	Unified Modeling Language，统一建模语言，用于表达类和对象之间的关系。
ER 图	Entity Relationship Diagram，实体关系图，用于表达数据实体及其关系。
SQL / SQLite	SQL 为结构化查询语言；SQLite 是本项目采用的嵌入式关系数据库引擎。
JSON	JavaScript Object Notation，结构化文本数据交换格式，用于配置和云存档快照。
API / HTTPS	API 为应用程序接口；HTTPS 为加密的 HTTP 通信，本项目用于云功能。
PK / FK	主键 / 外键，分别用于唯一标识记录和约束数据引用。
RNG	Random Number Generator，随机数生成器；保存其状态以恢复候选和波次生成过程。
LLM	Large Language Model，大语言模型，本次用于辅助状态建模、协议分析和数据库约束验证。
检查点	可恢复的游戏状态；战斗中恢复本波起点，波次准备中恢复已提交进度。
快照	同一逻辑时刻的完整进度集合，用于云端保存及本地整份恢复。
revision	云端单调递增的存档版本号，用于识别并发覆盖。

一 系统和数据库设计

1.1 体系结构设计

我们采用表现、应用、领域和基础设施分层。玩家的点击或按键先由界面转换为命令，应用层组织当前对局和操作流程，领域层计算伤害、价格、升级和结算，基础设施层负责配置、本地数据库与云接口访问。

图1 BroFuTo 总体架构

层次或部署单元	主要组成	设计职责
表现层	主界面、战斗信息界面、升级、超市、背包、科技、图鉴和云存档页面	接收输入，展示结果、余额、状态与反馈。
应用层	GameFlow、RunService、ShopService、ProgressService、SaveService、CloudSyncService	组织状态转换、领域命令、保存与同步流程。
领域层	属性与伤害、波次、装备、科技、解锁和结算规则	根据当前状态计算操作是否合法及其结果。
基础设施层	ContentRepository、LocalRepository、SQLiteAdapter、SnapshotCodec、AuthClient	加载内容，执行数据库事务，编码快照及访问云服务。
Ubuntu 云服务器	Nginx、Python FastAPI、SQLite cloud.db	通过 HTTPS 提供账号认证、存档版本查询和快照上传下载。

分层的直接收益是让计算与展示使用同一套规则。例如，武器详情的加成伤害预览和战斗命中共用 DamageService；该服务读取攻击上下文和目标战斗数据，返回伤害结果，角色实体再更新生命和表现。购买按钮提交商品标识，商品价格和扣款由交易服务处理。调整属性公式或超市折扣时，可以沿着同一计算入口修改。

帧级战斗数据保存在内存，包括敌人、子弹、位置、冷却和临时伤害事件。本地数据库在开局、波次起点、准备操作、科技升级和最终结算时写入。这样既能保存玩家决策，也能让战斗更新保持集中。

1.2 功能模块层次设计

系统划分为四个功能组、十个模块。图中的 MOD01—MOD10 与模块职责表对应，便于从需求定位设计和后续开发任务。

图2 BroFuTo 功能模块层次图

编号	模块	主要职责	关键协作对象
MOD01	流程与会话	开始、继续、状态转换、暂停、最终结算入口。	GameFlow、RunService
MOD02	角色与战斗	移动、自动攻击、属性、伤害、拾取与化学效果。	BattleController、PlayerActor、DamageService
MOD03	关卡与敌人	七地图、波次、首领、无尽、障碍物与阶梯高度。	MapController、WaveDirector、EnemyActor
MOD04	升级与超市	待选升级、购买、学分刷新、限购与候选状态。	LevelUpService、ShopService
MOD05	装备管理	六个上阵槽、武器背包、替换、出售、合成和参数预览。	WeaponInventory、MergeService
MOD06	永久成长	科研点、科技、顺序解锁、个人纪录与结算奖励。	ProgressService、SettlementService
MOD07	内容与资源	定义解析、内容标识校验、资源准备与图鉴内容索引。	ContentRepository、资源加载器
MOD08	本地持久化	检查点、准备进度、事务、备份、迁移和快照导入导出。	SaveService、LocalRepository、SQLiteAdapter
MOD09	云功能	注册登录、旧密码改密、云摘要、主动上传下载及版本冲突处理。	CloudSyncService、AuthClient
MOD10	表现与设置	页面交互、音效、受伤和暴击反馈、设备设置及输入焦点。	各界面、反馈组件、设置服务

模块划分以职责和数据修改入口为依据。图鉴内容索引归 MOD07，搜索框、翻页和详情展示归 MOD10；MOD01 组织结束对局的流程，MOD06 处理成长奖励，MOD08 提交最终数据。这样能够明确一次操作经过哪些模块，以及每个模块负责哪一步。

1.3 数据库选型与数据分布

客户端需要支持离线运行；云端面对少量玩家主动发起的低频同步。结合这两类访问方式，我们选择两端均使用 SQLite。

方案	客户端存档	云端存档	本次选择
SQLite	嵌入客户端，玩家无需安装数据库服务。	由单实例应用服务组织查询和短写事务。	本地与云端均采用。
MySQL	需要额外数据库服务。	适合集中式访问，需要单独部署和维护。	保留为方案比较。
PostgreSQL	需要额外数据库服务。	适合集中式访问，需要单独部署和维护。	保留为方案比较。

本地数据库 brofuto.db 和云端数据库 cloud.db 独立存储。客户端通过 HTTPS 交换 JSON 逻辑快照，服务器根据登录身份定位该账号的云档案。

数据类别	保存位置	云同步范围
角色、地图、武器、道具、敌人、科技定义	随包 JSON 与 Godot 资源	随版本发布。
永久科研点、科技等级、地图角色解锁	本地数据库	纳入快照。
个人纪录、结算历史	本地数据库	纳入快照。
进行中对局、恢复检查点、武器与道具	本地数据库	纳入快照。
分辨率、音量、按键等设备设置	本机设置文件	保留在当前设备。
用户名、密码摘要、登录会话	云端数据库	由账号服务管理。
帧级敌人、弹体、位置与冷却	战斗内存	由当前波次运行维护。

静态内容与玩家进度分别管理：校园地图、武器名称和图片路径由内容资源提供；数据库保存玩家选了什么、获得了什么，以及继续时需要恢复什么。catalog_ref 是由内容清单生成的引用索引，用于检查存档中的内容标识。

1.4 ER 分析

我们从永久成长、进行中对局和云账号三组实体建立数据关系。

1.4.1 永久成长与结算

图3 永久成长与结算 ER 图

一个 local_profile 对应多个解锁项、科技等级、历史结算和个人纪录。run_history.run_id 唯一标识一次最终结算；解锁记录可以追溯到产生它的结算，初始解锁的来源为空。个人纪录也关联产生该纪录的结算。

这个结构把科研点余额、解锁事实和奖励来源联系起来。结算服务在同一事务中写入历史、增加科研点、更新解锁和纪录；再次处理同一 run_id 时读取已有结果。

1.4.2 当前对局与装备

图4 当前对局检查点与装备 ER 图

本机保留一个玩家档案和最多一局进行中的对局。对局关联一个恢复检查点，以及持有武器、道具和上阵槽位。检查点与对局在同一事务建立，读取时共同校验。

每把持有武器使用独立的 instance_id。上阵槽位只引用实例，未被槽位引用的实例留在背包。这样既能表示“购买后暂不上阵”，也能按具体实例执行出售、替换和合成。复合外键同时检查对局标识和武器实例，保证槽位只能引用本局武器。

1.4.3 云账号与快照

图5 云账号会话与快照 ER 图

一个 cloud_account 可以关联多个登录会话，最多拥有一份当前云存档和一份覆盖前版本。云端 account_id 表示账号归属，快照中的 profile_uuid 表示游戏进度身份。登录账号变化时，本地进度继续保留；上传和下载时显示双方摘要，由玩家选择覆盖方向。

1.5 表结构设计

数据库共设计 16 张表，其中本地 12 张、云端 4 张。下表列出主要字段与约束，完整字段类型、索引和建表 SQL 见数据库设计说明书第 4 章及附录。

位置	表名	关键字段与类型	主键或主要约束
本地	schema_meta	key TEXT、value TEXT	key 主键，保存附加元信息。
本地	catalog_ref	content_id TEXT、kind TEXT、content_version TEXT	内容标识主键；类别限定为角色、地图、武器等。
本地	local_profile	profile_id INTEGER、profile_uuid TEXT、research_points INTEGER、local_revision INTEGER	档案槽固定为 1；逻辑身份唯一，科研点非负。
本地	run_history	run_id TEXT、outcome TEXT、research_awarded INTEGER、ended_at TEXT	run_id 主键；关联玩家、角色和地图。
本地	progress_unlock	profile_id INTEGER、content_id TEXT、origin_run_id TEXT	档案与内容标识组成联合主键；结算来源可为空。
本地	tech_progress	profile_id INTEGER、tech_id TEXT、level INTEGER	档案与科技标识组成联合主键，等级至少为 1。
本地	personal_record	profile_id INTEGER、record_key TEXT、value INTEGER、run_id TEXT	档案与纪录类型组成联合主键；关联历史结算。
本地	active_run	run_id TEXT、profile_id INTEGER、character_id TEXT、mode TEXT	对局标识主键；档案标识唯一。
本地	run_checkpoint	run_id TEXT、kind TEXT、current_hp REAL、credits INTEGER、多个 JSON 文本字段	对局标识同时为主键和外键；状态限定为战斗起点、升级或超市。
本地	weapon_instance	instance_id TEXT、run_id TEXT、weapon_id TEXT、rarity INTEGER	实例标识主键；对局与实例标识另建联合唯一约束。
本地	equipped_slot	run_id TEXT、slot_index INTEGER、weapon_instance_id TEXT	对局与槽位组成联合主键；槽位 1—6，武器实例唯一。
本地	held_item	run_id TEXT、item_id TEXT、quantity INTEGER	对局与道具标识组成联合主键；持有数量为正整数。
云端	cloud_account	account_id TEXT、username_key TEXT、password_hash TEXT	账号标识主键；用户名小写键唯一。
云端	auth_session	token_digest TEXT、account_id TEXT、expires_at TEXT	令牌摘要主键；关联账号。
云端	cloud_save	account_id TEXT、revision INTEGER、upload_request_id TEXT、snapshot_json TEXT	账号标识同时为主键和外键；每账号一份当前快照。
云端	cloud_save_previous	account_id TEXT、previous_revision INTEGER、snapshot_json TEXT	账号标识同时为主键和外键；每账号一份覆盖前版本。

设计时我们将高频关系查询拆成独立表，例如武器实例、上阵槽位、解锁和科技；候选列表、属性修正、随机状态等随检查点整体读取的数据，使用 JSON 文本字段保存。数据库检查主键、外键、唯一性和数值范围；整数列增加 CHECK(typeof(列名)='integer')，在类型亲和性转换后检查存储类型，确保学分、科研点、等级、数量、槽位和版本号按整数保存。领域层继续检查科技前置、内容类别、合成条件及属性单位。

六槽与同局武器的约束通过以下表定义表达：

CREATE TABLE equipped_slot (
  run_id TEXT NOT NULL
    REFERENCES active_run(run_id) ON DELETE CASCADE,
  slot_index INTEGER NOT NULL CHECK(slot_index BETWEEN 1 AND 6),
  weapon_instance_id TEXT NOT NULL UNIQUE,
  PRIMARY KEY(run_id, slot_index),
  FOREIGN KEY(run_id, weapon_instance_id)
    REFERENCES weapon_instance(run_id, instance_id)
);

购买、合成、科技升级和结算都以事务提交。以合成为例，先校验具体材料实例与配方，再删除受影响的上阵引用、消耗材料、创建产物并更新槽位；提交成功后刷新内存与界面，失败则回滚整笔操作。

1.6 接口与手动云同步

内部模块通过明确的输入、输出和前置条件协作。命令结果包含 ok、code、message_key 和 data，界面根据结果刷新展示。

内部接口	输入	输出与关键行为
start_run	角色、模式、地图	创建 RunState 与第一波检查点，检查解锁条件。
resolve_hit	HitContext、目标状态	返回伤害结果，依次处理闪避、防御、独立减免与生命变化。
choose_upgrade	升级候选标识	更新属性与待选次数，提交准备状态。
buy_or_reroll	商品标识或刷新命令	更新余额、候选及背包，校验费用与限购。
equip_sell_merge	武器实例与目标槽位	返回装备结果，检查六槽和实例唯一性。
finish_run	对局标识、结局与冻结统计	提交科研点、解锁、纪录和历史，同局返回同一结算结果。
save_exit	当前运行状态	战斗中引用波起点，准备中保存已完成操作。
import_snapshot	完整快照、期望本地版本	校验并备份当前档案，事务替换同步范围内的数据。

云端接口统一位于 /api/v1，包括以下操作：

方法与路径	用途	关键条件
POST /auth/register	注册账号	校验用户名与密码，检查用户名唯一性。
POST /auth/login	登录	返回本次登录令牌和到期时间。
POST /auth/logout	退出登录	撤销当前会话。
PUT /auth/password	使用旧密码改密	成功后撤销该账号全部登录会话。
GET /save/meta	查询云存档摘要	返回是否有档案、版本号、更新时间与上传请求标识。
GET /save	下载指定版本快照	按预期版本读取，与已展示摘要一致。
PUT /save	上传完整快照	检查预期版本与请求标识，备份旧档后提交新版本。

上传流程为：查看双方摘要 → 确认以本地覆盖云端 → 校验预期版本 → 备份旧云档 → 写入快照并增加版本号。两台设备读取同一云版本后先后上传，后一次请求会收到版本冲突，再由玩家查看最新摘要并决定操作。

下载流程为：查看云摘要 → 下载对应版本 → 校验快照 → 确认替换本地进度 → 创建备份 → 事务导入。同步按整份快照恢复科研点、装备、解锁、纪录和进行中对局，设备设置继续保留在本机。

二 设计类图与系统安全权限

2.1 设计类图与对象职责

类图使用三段式类框展示类名与 Godot 基类、属性和方法；+ 表示公有，- 表示私有。方法标出参数类型和返回类型。关联使用实线开放箭头，依赖使用虚线开放箭头，组合在整体端标实心菱形，并为关联和组合补充多重性。

2.1.1 战斗流程与命中服务

图6 战斗流程与命中服务设计类图

GameFlow 负责页面和运行状态；BattleController 组织当前波次，管理玩家及敌人实体。MapController 提供地图高度和障碍查询。空间检查通过后，玩家与敌人将 HitContext 和 TargetCombatState 提交给 DamageService，再依据返回结果更新自身生命并发送反馈事件。

这样可以统一武器面板预览与实际伤害，也能集中检查化学效果、暴击、防御及独立减免的处理顺序。地图判定与伤害计算分别承担空间规则和数值规则。

2.1.2 武器攻击与化学效果

图7 武器攻击与化学效果设计类图

WeaponController 遍历上阵武器，生成投射物或施加效果。Projectile 保存发射时的高度和命中快照，通过地图控制器检查阻挡与目标高度。每个投射物关联一个地图控制器，同一地图控制器可被零至多个投射物共享，对应两端多重性为 0..* 和 1。ChemicalEffectController 管理燃烧、腐蚀和触电等效果的层数与触发进度，经过目标实体调用统一伤害服务。

化学持续伤害在命中上下文中标为不可暴击；暂停时停止推进有效游戏时间。东三教学楼的阶梯高度也由同一地图查询入口处理，投射物按发射高度命中同层目标。

2.1.3 成长与装备

图8 成长与装备设计类图

RunService 管理当前 RunState，其中组合一个武器清单。ShopService 受理购买与合成命令，调用 MergeService.prepare 校验材料、产物和槽位，再随准备状态提交。终局时，RunService 冻结统计并调用 SettlementService；后者取得 ProgressService.plan_settlement 生成的科研点、解锁和纪录变化，通过 LocalRepository 完成一次结算事务。ProgressService 同时负责永久 PlayerProfile 的科技校验与成长计算。

局内对局与永久档案分别保存。开局复制科技效果到本局属性来源中，本局升级和道具继续在这一基础上累加。最终结束时结算科研点并清除进行中对局，使局内构筑与局外成长各有清楚的数据生命周期。

2.1.4 本地存档与云同步

图9 本地存档与云同步设计类图

SaveService 确定恢复点，LocalRepository 执行本地事务，SQLiteAdapter 封装数据库访问。CloudSyncService 通过 SnapshotCodec 编码和校验快照，通过 AuthClient 使用本次登录身份发起请求，再调用同一个本地仓库完成导入。

这一设计复用本地读档和云下载的校验规则。两条恢复路径都会检查六槽、余额、内容引用、随机状态和检查点类型，减少不同入口出现不同规则的情况。

2.2 系统安全设计

安全设计围绕账号、存档归属、数据输入及恢复操作展开。

设计方面	具体方案	作用
传输保护	云请求统一使用 HTTPS，Nginx 将 API 请求转发给监听本机地址的应用服务。	保护用户名、密码和存档传输，集中管理公网入口。
密码保存	注册与改密时由 Argon2id 库生成独立的密码学安全随机盐；password_hash 保存算法、版本、参数、盐和摘要的完整编码，登录通过库验证。	每次设置密码使用新盐，编码字符串提供验证所需信息。
会话管理	生成至少 256 位随机令牌，客户端内存持有；服务器保存 SHA-256 令牌摘要及到期时间。	区分登录身份，支持退出撤销与过期检查。
账号隔离	服务器从认证令牌确定 account_id，据此查询和更新存档。	限定每次请求可访问的数据归属。
查询安全	SQL 使用参数绑定。	将查询结构与输入值分开。
输入校验	检查快照字段、长度、嵌套深度、版本、非负余额、六槽和内容引用。	在写入前识别格式与业务约束错误。
认证控制	按来源 IP 和账号限制认证频率，失败登录使用统一提示。	控制重复尝试并统一交互反馈。
日志	记录请求标识、账号标识、结果码与耗时。	关联问题与操作结果，便于定位。
备份恢复	覆盖前保留一份备份；通过 SQLite 一致性备份方式生成数据库副本。	为覆盖及数据恢复保留明确路径。

改密使用旧密码校验，成功后撤销该账号的全部登录会话，客户端重新登录。登录会话有效期设计为 24 小时；云请求失败时保留本地进度，并在云页面显示处理结果。

2.3 权限设计

主体	离线玩法和本地进度	云存档	账号相关操作
未登录玩家	进入游戏、读取和保存本机进度。	登录后使用上传、下载。	注册、登录。
已登录玩家	继续操作本机进度。	查看并上传、下载当前账号的云存档。	退出、使用旧密码改密。
服务器运行进程	通过 API 接收快照。	在服务目录访问 cloud.db 及受控备份。	校验密码摘要、会话与账号归属。
部署维护人员	按设备或服务器文件权限维护。	通过维护工具执行备份和恢复。	按服务器权限维护服务配置。

认证和游戏进度分别管理。切换账号保留本地游戏进度；上传时明确目标账号，下载时明确将替换的本地档案及对局。玩家能够在操作发生前看到其影响。

2.4 健壮性与异常处理

我们将交易、结算和存档覆盖作为重点检查路径。每条路径都明确失败后保留什么状态，以及如何继续。

场景	处理规则	验证重点
学分不足或合成材料不符	保留交易前余额、材料和候选，显示原因。	操作前后相关数据一致。
数据库写入失败或锁等待超时	回滚整笔命令，内存和界面保持旧值。	界面展示与已提交数据一致。
同一对局重复进入结算	按 run_id 返回已有结果。	科研点、解锁和历史只提交一次。
两台设备上传同一旧版本	后提交请求返回版本冲突。	当前云档与覆盖前版本保持完整。
上传成功响应丢失	查询元数据，用上传请求标识确认结果。	识别已完成请求，正确展示版本。
快照格式或内容版本不兼容	保留本地档案，提示兼容问题。	本地继续入口可用。
下载导入中断	按事务提交状态读取完整旧档或完整新档。	历史、余额、武器和检查点同步恢复。

三 改进分析与 LLM 协助设计

3.1 上次需求分析评审反馈

上次需求分析答辩记录中，老师、助教和其他队伍未提出问题。本次围绕需求到实现的衔接，对存档恢复、云功能、装备数据结构和设计图表进行了主动改进。

3.2 改进内容与过程

改进主题	需要解决的问题	改进过程	当前设计落点
数据持久化	需求已说明要保存进度，需要进一步确定保存位置和写入方式。	列出永久、局内、配置、设备与账号数据；比较数据库；确定本地与云端 SQLite；逐项设计主外键及事务。	系统说明书 §3.2；数据库说明书第 3—5 章。
云存档	跨设备续玩需要明确联网时机、账号方式和覆盖方向。	确认用户名密码认证；限定在云功能中联网；将操作分为查看摘要、确认、上传或下载；增加版本检查与覆盖前备份。	系统说明书 §5.9—5.10；数据库说明书 §4.4、§5.5—5.7。
波次准备恢复	升级和超市中退出后，已作出的选择与购买需要保留。	区分战斗与准备状态；战斗恢复本波起点；升级、购买、刷新和背包操作成功后提交准备检查点；恢复时按检查点类型进入对应页面。	run_checkpoint.kind 与 preparation_json；系统说明书 §5.4。
随机结果恢复	续玩需要保持已经看到的候选、无尽地图顺序与刷新结果。	保存玩法随机流的种子、状态和生成器版本；保存完整候选列表、刷新次数及无尽地图袋序；继续时直接读取。	数据库说明书 §3.3、§4.5。
武器实例与上阵	六槽满后仍可购买，合成和出售需要定位具体武器。	为每把武器建立实例标识；背包与上阵使用持有实例加槽位引用表示；增加槽位范围、实例唯一和同局复合外键。	weapon_instance、equipped_slot；系统说明书 §5.5。
结算一致性	科研点、解锁、纪录及本局清理需要作为一次操作提交。	将 run_id 作为结算唯一标识；冻结统计后，在事务中同时写历史、发科研点、解锁并清理本局。	run_history 与最终结算事务；系统说明书 §5.7。
设计类图	第一版类图使用统一调用箭头，对对象关系和接口类型表达较粗。	按战斗流程、攻击效果、成长装备、存档同步拆图；区分关联、组合和依赖；补充多重性、参数及返回类型；统一受击依赖方向。	系统说明书 §4.4—4.5，四张设计类图。
图文和命名一致性	模块分组、数据库外键及字段名称需要能相互核对。	功能图标出 MOD01—MOD10；ER 图补齐档案、内容索引和结算来源关系；角色统一使用 character_id；补充引用资料版本与位置。	两份说明书的架构、ER、对象表及引用章节。
整数约束	SQLite 的整数类型声明与非负检查仍可接收小数。	用内存数据库复现科研点写入 1.5；为所有整数列补充存储类型检查，验证小数被拒绝、整数正常写入。	数据库说明书 §4.3、§6.1 及建表附录。
服务职责与接口	合成、结算的模块对象与类图需一致，伤害服务需要独立于场景节点。	补齐 MergeService、SettlementService 与调用关系；统一 Result；用 TargetCombatState 传入目标数值；修正投射物与地图的多重性。	系统说明书 §4.4—4.6、§5.3、§5.5、§5.7。
密码加盐	密码摘要需要明确随机盐的来源和存储格式。	注册和改密使用 Argon2id 库生成新随机盐，完整编码随 password_hash 保存，登录调用库验证。	系统说明书 §6.1；数据库说明书 §4.4、§5.7。

例如，确定保留超市准备进度之后，需要同时调整检查点状态、交易提交、继续入口和恢复检查，才能完整表达这一规则。

3.3 LLM 示例一 基于状态机的检查点与恢复设计

工程问题：战斗中退出需要恢复本波起点，升级和超市中退出需要保留已完成操作。一次准备操作又可能同时修改余额、属性、装备、候选和随机状态。恢复设计需要说明这些数据何时共同生效，以及恢复后从哪个状态继续。

设计提示词：

请将 BroFuTo 的保存与恢复规则建模为状态机：
战斗退出恢复本波起点；升级、超市退出保留已提交操作；
保存退出不发科研点，终局统一结算。
对比逐帧存档、统一波起点与按阶段检查点三种方案。
列出状态、迁移条件、持久化字段和事务边界，
检查最后一次升级选择、付费刷新、开始下一波及终局中断。
给出必须保持的数据不变量和可验证的恢复场景。

分析与取舍：逐帧存档需要序列化敌人、弹体和冷却等现场；统一波起点会丢失准备阶段已完成操作。最终采用按阶段检查点，将恢复点分为 wave_start、upgrade 和 shop，由 GameFlow 按检查点类型恢复页面。

状态或操作	持久化设计	恢复语义与不变量
战斗与战斗暂停	使用已提交的 wave_start 检查点。	从本波起点继续，恢复对应生命、装备、统计及随机状态。
升级选择与刷新	候选、学分、属性、待选次数和 RNG 状态共同提交。	已选属性保留，已显示候选保持一致；upgrade 的待选次数大于零。
完成最后一次升级选择	待选次数归零，同时建立 shop 准备状态。	继续时进入超市；shop 的待选次数为零。
超市购买与装备调整	余额、候选、持有物及槽位引用在同一事务中提交。	已购买、出售、合成和替换的结果一致恢复。
开始下一波	先提交新波起点，再启动战斗。	检查点提交成功后才推进本波时间。
最终结算	以 run_id 标识结算，奖励、历史和本局清理共同提交。	重复请求读取既有结果，科研点按该结算记录发放一次。

LLM 的作用：协助展开状态迁移与中断路径，检查最后一次升级选择后的页面状态，再把玩法规则转成检查点字段和数据库约束。准备阶段保留进度、战斗回到波起点的规则由团队确认。

设计产出与验证：形成状态转换图、CheckpointState、检查点 JSON 字典和准备操作事务。验证场景包括连续升级后退出、付费刷新后恢复、准备事务失败、终局提交前后中断。对应系统说明书 §5.1、§5.4、§5.7，以及数据库说明书 §4.5、§5.3—5.4。

3.4 LLM 示例二 云存档的并发控制与重试协议

工程问题：两台设备可能同时看到同一份云档，并先后上传不同进度；服务器提交成功后，响应也可能在网络中丢失。协议需要区分版本冲突、重复请求和上传失败，确保玩家确认的覆盖对象与实际写入版本一致。

设计提示词：

BroFuTo 主动上传完整存档，覆盖前保留一个旧版本。
请分析两设备同时上传、提交成功但响应丢失、
查看摘要后云档被其他设备更新三种时序。
比较按客户端时间覆盖与按服务器 revision 条件写入。
设计 If-Match、首次创建条件、request_id 和错误响应，
给出事务顺序、重试判定及备份一致性规则。
明确哪些检查在事务外完成，哪些必须在事务内复核。

分析与取舍：客户端时间无法直接表示云档的先后版本，最终采用服务器 revision 和条件写入。客户端先展示双方摘要，确认后提交预期版本；服务器在事务中核对版本，将备份与新档作为一次写入提交。

竞争或故障场景	协议处理	设计效果
两设备均读取版本 17 后上传	首次提交生成版本 18；另一次携带版本 17 的请求返回 409。	第二台设备重新查看摘要并确认覆盖。
首次上传时云端尚无存档	使用 If-None-Match: *，仅在云档不存在时创建。	同时创建由服务器判定，当前云档保持唯一。
上传已提交，成功响应丢失	客户端查询元数据；当前 upload_request_id 与本次相同且正文一致时，识别为已提交。	返回既有结果；若已有更晚上传，则重新确认当前云档。
下载前云档版本变化	按摘要对应的 revision 请求正文，版本不符时返回冲突。	下载确认与实际取得的快照保持一致。
覆盖事务中断	旧档备份和当前档更新共同提交或回滚。	当前档与覆盖前版本保持对应关系。

LLM 的作用：协助把操作描述展开为多设备时序，检查版本校验与实际写入之间的竞争窗口，并明确重试的判定条件。最终设计采用完整快照覆盖、服务器版本校验和最近上传请求识别。

设计产出与验证：形成上传时序图、GET /save/meta、GET /save、PUT /save 协议，以及 cloud_save 和 cloud_save_previous 的事务设计。验证重点是同版本竞争、响应丢失、正文版本变化和事务中断，分别检查响应码、版本号及备份内容。

3.5 LLM 示例三 装备关系建模与数据库约束验证

工程问题：玩家可持有多把同款武器，但最多上阵六把。购买、替换、出售和合成必须定位具体实例，同时保持槽位唯一、武器归属和余额一致。数据库设计需要将这些规则转成可执行的约束。

设计提示词：

请根据以下规则设计装备关系模型和 SQLite 约束：
最多六把上阵，满槽购买进入背包；同款武器可有多个实例；
出售与合成消耗指定实例，合成结果按材料所在槽位放置。
对比分离背包表与“持有实例＋槽位引用”两种模型，
给出主键、唯一约束、同局复合外键和交易顺序。
构造重复上阵、跨局引用、小数余额等反例，
用可执行 SQL 检查约束是否真正成立。

分析与取舍：采用“持有实例＋槽位引用”模型。weapon_instance 保存持有武器，equipped_slot 引用上阵实例；未被槽位引用的实例就是背包武器。购买满槽时直接增加持有实例，替换只调整引用，出售与合成按 instance_id 处理。

业务不变量	关系或约束设计	验证反例
一局最多六个上阵位置	槽位范围限定为 1—6，(run_id, slot_index) 为复合主键。	插入槽位 7，或重复占用同一槽位。
同一实例最多上阵一次	weapon_instance_id 设置唯一约束。	将同一武器实例放入两个槽位。
上阵武器属于当前对局	(run_id, weapon_instance_id) 复合外键引用持有实例。	引用其他对局的武器或不存在的实例。
余额、品级与数量按整数保存	整数列同时检查存储类型与合法范围。	写入 1.5、负余额或零持有数量。
合成结果与准备状态一致	移除材料槽位引用、消耗材料、建立产物和新引用，在同一事务提交。	在处理材料或产物期间中断事务。

LLM 的作用：协助比较关系模型、推导外键与唯一性约束，并用反例检验设计。核对中发现，SQLite 的 INTEGER 类型声明配合非负检查仍可接收 1.5，因此补充 CHECK(typeof(列名)='integer')，使整数要求落实到建表定义。

设计产出与验证：形成装备 ER 图、字段字典、建表 SQL 和交易顺序。建表约束脚本在 SQLite 内存数据库中完成 33 项检查，覆盖整数存储、六槽限制、实例唯一、引用完整性、事务回滚和云版本条件更新，检查全部通过。

三个案例分别落到状态模型、通信协议和关系模型。LLM 协助展开方案与反例，团队确认玩法及同步规则，再通过图表、接口、约束和验证场景固定设计结果。

四 团队绩效与协作流程

4.1 本次作业工作流程

步骤	工作内容	交付成果	检查重点
1 需求与资料整理	阅读国标、课程要求、需求说明书及内容目录，整理需要确认的规则。	设计基线、问题清单。	范围、术语和来源是否一致。
2 关键方案确认	比较数据库，确认离线运行、云认证、同步范围及恢复规则。	数据分布与设计决策。	各方案是否符合团队规模与玩家场景。
3 系统设计	划分模块，设计对象、状态、接口和安全权限。	架构图、功能层次图、类图、接口与权限表。	调用方向、职责边界和异常处理是否清楚。
4 数据库设计	根据永久成长和局内状态建立实体、字段、外键、索引和事务。	ER 图、数据字典、建表 SQL、快照协议。	六槽、同局引用、余额与结算约束是否一致。
5 交叉核对	对照需求、评分项和实际操作路径审查设计。	修改清单、需求与设计追踪表。	发现的问题能否定位到具体图、字段或流程。
6 修订与排版	修正类图、ER 关系和命名，统一引用和图文样式。	两份 Word 与 Markdown 说明书。	目录、编号、图中文字、表格和分页。
7 展示与归档	整理博客、答辩材料、评审表及仓库链接。	博客和课堂展示材料。	评分点覆盖、链接与提交记录。

4.2 组员分工与贡献比例

本次分工以两份说明书中的责任安排为基础。贡献度由团队结合交付内容、审阅修改和个人提交记录共同确认后填写，七人比例合计为 100%。

学号	工作内容	贡献度
102400226	石华波：负责总体架构与核心战斗设计，梳理 GameFlow、伤害流程和首图集成关系，统筹系统设计。	16%
102400310	陈炳珲：负责需求协调、模块接口与设计整合，整理需求追踪、设计决策和团队进度。	14%
052402138	朱宇濠：负责成长数据与本地存储设计，梳理属性配置、装备交易、数据表和 SQLite 访问。	14%
102400308	游诗可：负责场景与界面设计，细化地图场景、碰撞高度、页面流程和界面集成。	14%
102400302	郭锦蓉：负责角色、敌人与表现设计，整理资源接入、角色敌人表现及图鉴内容关系。	14%
102400329	吴江彬：负责云存档与交互设计，梳理认证、主动同步、覆盖确认和备份联动。	14%
102400333	詹铖煜：负责测试与一致性验证设计，整理高度、交易、结算、恢复和回归检查。	14%

贡献统计按可核对的交付记录进行：任务表登记负责人、产出和审阅人；代码、文档和资源修改关联个人 commit；共同完成的图表或章节分别记录承担部分。团队汇总后核对总比例，再用于本次作业的个人贡献分配。

4.3 沟通与版本协作

团队通过 QQ、微信同步进度，共享任务表记录负责人、截止日期、交付路径、依赖和审阅结果。日常同步包含已完成内容、下一步工作和需要协作处理的问题；每周按照里程碑检查集成版本和产出。

Git 仓库采用功能、文档和资源分支协作。主分支名称以华为云团队仓库当前配置为准；各成员在自己的分支完成任务，提交说明关联模块或需求编号，交叉审阅后合并。每名成员提交本人负责的设计、代码或资源 commit。

影响多个模块的修改，先明确输入输出和负责人。例如，调整武器字段时同步属性预览、商品购买、合成、存档和图鉴；调整恢复规则时同步状态转换、检查点、交易事务和继续入口。

文本冲突按共同基线逐段核对；Godot 场景、图片等文件由对应负责人统一整合。合并后检查资源引用、字段名称和受影响的运行路径，审阅结论登记到任务记录。

4.4 验证与追踪安排

设计使用需求编号、模块编号、接口编号和验证编号建立关联。例如，武器背包需求对应 MOD05、装备操作接口以及“满六槽购买和合成”的验证；存档需求对应 MOD08、保存恢复接口以及准备恢复、战斗回退和结算中断检查。

验证主题	主要检查场景	关联负责人
输入与时间	WASD、点地移动、焦点切换；暂停后子弹、效果、再生与冷却同步停止。	石华波、游诗可、詹铖煜
装备交易	六槽满后购买入包；按指定实例替换、出售、合成；费用和材料失败回滚。	朱宇濠、詹铖煜
地图规则	低矮和高大障碍、水面；台阶换层与同高度命中。	游诗可、郭锦蓉、詹铖煜
存档结算	战斗回到波起点；准备进度保留；同局科研点结算一次。	石华波、朱宇濠、詹铖煜
云同步	账号隔离、版本冲突、响应丢失确认、下载导入和覆盖备份。	吴江彬、詹铖煜
文档一致性	需求、图表、字段、接口、资源和验证记录相互对应。	陈炳珲及各模块负责人

五 开发计划与人员安排

5.1 每周开发计划与里程碑

项目以 11 月 3 日交付可玩版本为近期节点，随后推进云功能及系统联动，11 月中下旬开展迭代冲刺。每周以运行版本、内容清单和验证记录检查进度。

周次	时间	本周主要工作	里程碑	对应产出与检查标准
第 1 周	10 月 19—25 日	完成系统与数据库设计；核对模块、类图、ER、接口和安全；准备 10 月 23 日答辩；搭建正式客户端的模块骨架。	M1 设计基线与答辩，10 月 23 日。	两份说明书、设计图、博客、答辩材料及评审记录；模块入口与数据结构可供成员并行开发。
第 2 周	10 月 26 日—11 月 1 日	完成首图十波闭环；集成七地图内容与碰撞；接入属性升级、超市、装备、本地保存及结算。	M2 核心玩法与内容集成，11 月 1 日。	可运行的核心闭环、地图及资源清单、本地数据库；检查六槽交易、准备恢复、波次继续和科研点结算。
第 3 周	11 月 2—8 日	11 月 2—3 日整理并交付可玩版本；随后集成账号、主动上传下载、覆盖备份和版本冲突处理。	M3 可玩版本交付，11 月 3 日；M4 云功能集成，11 月 8 日。	Windows 运行包、源码与资源归档、关键流程记录；云接口及两设备上传下载回归记录。
第 4 周	11 月 9—15 日	完善无尽、科技、解锁和图鉴联动；检查内容版本兼容；测量战斗与存档性能。	M5 系统联动与首轮优化，11 月 15 日。	无尽阶段切换、科技成长和图鉴验证记录；性能测量、兼容检查及问题清单。
第 5 周	11 月 16—22 日	进入迭代冲刺，集中处理高优先级缺陷；开展跨设备存档、七地图、首领与装备内容回归。	M6 冲刺候选版本，11 月 22 日。	候选发布版、缺陷处理记录、跨设备恢复与内容回归结果；重点问题完成复验。
第 6 周	11 月 23—29 日	继续冲刺与稳定性修复，检查导出包、迁移恢复、操作说明和完整体验流程，统一归档。	M7 稳定版本与项目归档，11 月 29 日。	稳定运行包、最终验证记录、更新后的说明书、演示材料与资源清单。

本地成长和存档安排在云同步之前，先形成可继续的完整游戏进度，再把同一份进度导出为快照。模块协作以首图闭环为集成入口，地图、角色和敌人内容按统一配置接入；进入冲刺阶段后，优先处理影响通关、结算、存档和启动的问题。

5.2 每位成员的开发责任

成员与学号	开发角色	负责的详细开发部分	主要交付	依赖与协作
石华波 102400226	架构与核心战斗	MOD01、MOD02；GameFlow、RunService、输入与暂停、自动攻击、伤害计算、首图波次闭环及整体集成。	核心战斗场景、统一伤害服务、可运行集成版本。	与朱宇濠统一属性及结算接口；与游诗可联调高度和碰撞；与詹铖煜复验战斗路径。
陈炳珲 102400310	需求协调与设计整合	维护需求到模块接口的追踪；组织配置、接口和规则变更；维护周计划、问题清单、博客及展示材料。	接口约定、追踪表、周进度与评审材料。	收集各成员产出与阻塞，协调影响多个模块的变更。
朱宇濠 052402138	成长数据与本地存储	MOD04、MOD05、MOD06、MOD08；属性修正、升级候选、超市交易、六槽背包、合成出售、科技、SQLite 表及事务、检查点和最终结算。	成长与装备模块、本地数据库访问层、恢复与结算逻辑。	与石华波统一运行状态；向吴江彬提供快照导出导入入口；与詹铖煜检查事务和恢复。
游诗可 102400308	场景与界面	MOD03 场景部分、MOD10；七地图布局、障碍碰撞、东三阶梯高度区、台阶过渡、各界面流程、设置与输入焦点。	地图场景、碰撞与高度配置、界面及流程集成。	与石华波联调移动和命中；与郭锦蓉统一资源尺寸、遮挡与场景表现。
郭锦蓉 102400302	角色敌人与表现	MOD03 敌人表现、MOD07 内容资源；角色、普通敌人与首领资源接入，前摇和危险预警，图鉴对象、名称与资源引用。	角色敌人场景、首领表现、图鉴内容及资源索引。	与游诗可统一场景表现；与石华波联调敌人攻击；与陈炳珲核对内容标识。
吴江彬 102400329	云存档与交互	MOD09；FastAPI 认证与云存档接口、云端 SQLite、登录改密、摘要确认、手动同步、版本冲突和覆盖备份，以及客户端云页面联动。	云服务与客户端适配、账号页面、同步流程和部署配置。	依赖本地快照与事务入口；与朱宇濠统一字段和版本；与詹铖煜完成两设备回归。
詹铖煜 102400333	测试与一致性验证	根据需求及设计维护检查用例；覆盖战斗暂停、地图高度、装备交易、科研点结算、保存恢复、云账号隔离及版本冲突；测量性能并组织回归。	验证记录、缺陷清单、复验结果与版本质量报告。	与各模块负责人复现和关闭问题，向集成负责人提供发布检查结果。

每个交付任务包含负责人、预计完成周、输入依赖、输出文件或运行入口、验证方式。负责开发的成员先检查本模块，测试成员对集成后的操作路径进行复验，设计整合成员同步接口和文档。

参考资料

1. GB/T 8567—2006《计算机软件文档编制规范》，系统设计参考第 7.9 节，软件结构与详细处理参考第 7.13 节，数据库设计参考第 7.14 节。

2. BroFuTo《软件需求规格说明书》及《游戏设计说明》，作为功能、校园内容与规则设计依据。

3. OMG UML 2.5.1，用于类图记法。

4. SQLite 适用场景、事务、PRAGMA 配置、在线备份。

5. Godot 官方文档与 godot-sqlite，用于引擎组织与数据库适配。

6. FastAPI 官方教程，用于云接口设计与实现参考。

7. OWASP 密码存储指南，用于密码摘要与参数配置参考。

8. SQLite 数据类型与类型亲和性，用于整数存储约束；