1. 登录与入口
登录流程
- 打开浏览器，访问系统首页（如
http://localhost:5000 或服务器地址）
- 点击"登录"按钮，进入登录页面
- 输入管理员用户名和密码
- 登录成功后自动跳转至管理后台页面（
/admin）
注意：管理员（admin/tadmin）登录后直接进入管理后台，不会跳转到比赛选择页。管理员可以同时执裁比赛，从管理后台退出后可通过 /matches 进入比赛选择页。
管理后台界面结构
左侧为导航栏，包含 4 个功能模块：
球队管理
→
赛程管理
→
用户管理
→
系统设置
2. 球队管理
功能概述
- 查看所有球队列表（含球员数量统计）
- 新增球队（中英文名称、教练姓名）
- 编辑球队信息
- 删除球队（同时删除关联球员）
- 展开球队查看/添加/编辑/删除球员
添加球队操作步骤
- 在管理后台点击左侧"球队管理"标签
- 点击"添加球队"按钮
- 填写球队中文名称、英文名称、教练姓名（中英文）
- 点击"保存"完成添加
管理球员
- 在球队列表中点击球队行左侧的展开按钮
- 展开后显示该队所有球员（号码、中英文名）
- 点击"添加球员"可新增球员（号码、中英文名）
- 点击球员行的"编辑"可修改信息
- 点击"删除"可移除球员
提示：球员号码为必填项，同一球队内号码不可重复。中英文名称均需填写以支持多语言显示。
3. 赛程管理
功能概述
- 查看所有比赛列表（含队伍、比分、状态、裁判、场地）
- 新增比赛（选择队伍、阶段、场地、裁判、时间）
- 编辑比赛信息（修改队伍、棍色、裁判分配等）
- 删除比赛
- 手动修改比赛状态（scheduled / live / completed）
- 手动更新比分
- 触发淘汰赛队伍自动更新
新增比赛操作步骤
- 点击左侧"赛程管理"标签
- 点击"添加比赛"按钮
- 选择队伍 A 和队伍 B（淘汰赛阶段可为空，使用引用描述）
- 设置棍色（白棍/黑棍）
- 填写比赛场次号、小组名、阶段（小组赛/淘汰赛）
- 设置比赛时间和场地
- 分配裁判（可选）
- 点击"保存"完成添加
淘汰赛队伍自动更新
当小组赛比赛完成后，淘汰赛的队伍对阵需要根据小组赛排名自动填充。
- 确保所有相关小组赛已完成（状态为 completed）
- 在赛程管理页面点击"更新淘汰赛"按钮
- 系统自动根据小组排名填充淘汰赛对阵（如 A组第1名、B组第2名等）
- 检查淘汰赛对阵是否正确
注意：更新淘汰赛后，之前手动设置的淘汰赛队伍会被覆盖。建议在所有小组赛结束后再执行此操作。
4. 用户管理
功能概述
- 查看所有系统用户列表（用户名、角色、显示名、创建时间）
- 创建新用户（设置用户名、密码、角色、显示名）
- 删除用户（不可删除 ID=1 的超级管理员）
- 重置用户密码
可创建的角色类型
| 角色值 | 说明 | 权限范围 |
|---|
| admin | 系统管理员 | 全部功能 + 执裁 |
| referee | 裁判员 | 执裁分配给自己的比赛 |
| refadmin | 裁判长 | 执裁全部比赛 + 检录 + 修改已完成比赛 |
| ref1-4 | 编号裁判 | 执裁分配给自己的比赛 |
| ck1/ck2 | 场地检录员 | 仅检录对应场地的比赛 |
| ckadmin | 检录管理员 | 检录全部比赛 + 退回检录 |
| tadmin | 测试管理员 | 全部功能 + 模拟比赛 |
| tref | 测试裁判 | 执裁 + 模拟功能 |
创建用户步骤
- 点击左侧"用户管理"标签
- 点击"添加用户"按钮
- 输入用户名（登录用，不可重复）
- 设置初始密码
- 选择角色（admin / referee / refadmin / ck1 / ck2 等）
- 填写显示名（中文姓名，用于界面显示）
- 点击"保存"完成创建
安全提示：初始密码建议设为简单密码（如 123456），并提醒用户首次登录后修改。重置密码操作需要用户明确同意后方可执行。
5. 系统设置
默认比赛设置
管理员可以设置系统默认的比赛参数，所有新建比赛会自动继承这些设置。裁判在赛前设置页面可在此基础上修改。
| 参数 | 默认值 | 说明 |
|---|
| 半场时长 | 12 分钟 | 常规时间上下半场各 12 分钟 |
| 中场休息 | 3 分钟 | 上下半场之间的休息 |
| 加时赛启用 | 关闭 | 是否启用加时赛 |
| 加时赛半场时长 | 5 分钟 | 加时赛上下半场各 5 分钟 |
| 加时赛前休息 | 3 分钟 | 常规时间结束后到加时赛前的休息 |
| 加时赛休息 | 3 分钟 | 加时赛上下半场之间的休息 |
| 金球前休息 | 1 分钟 | 加时赛平局后进入金球前的休息 |
| 每队每节暂停 | 1 次 | 每支球队每节可使用的暂停次数 |
| 暂停时长 | 1 分钟 | 每次暂停的持续时间 |
| 最后禁止暂停 | 最后 2 分钟 | 每节最后 N 秒不允许叫暂停 |
| 进球后罚时 | 暂停 | 进球后是否暂停正在执行的罚时 |
| 进球后倒计时 | 30 秒 | 进球后的重新开球倒计时 |
6. Excel 导入导出
球队数据导入
- 在球队管理页面，点击"导入Excel"按钮
- 可选择先下载模板，按模板格式填写数据
- 模板支持两种格式：多 Sheet（每支球队一个 Sheet）或单 Sheet（列含球队名、教练、球员信息）
- 上传 .xlsx 文件
- 勾选"清空旧数据"可覆盖导入（谨慎操作）
- 系统自动解析并导入球队和球员数据
注意：球队名称需含中英文，球员需含号码和中英文名。导入时同名球队会更新而非重复创建。
球队数据导出
- 在球队管理页面，点击"导出Excel"按钮
- 系统生成 Excel 文件并自动下载
- 文件包含：汇总 Sheet（全部球员列表）+ 每支球队独立 Sheet
- 每支球队 Sheet 含球员号码、姓名、进球数、罚时统计
赛程数据导入
- 在赛程管理页面，点击"导入Excel"按钮
- 可先下载赛程模板，按格式填写
- 列包括：场次、小组名、队伍A、队A棍色、队伍B、队B棍色、开始时间、场地、主裁判
- 小组赛：队伍A/B 直接填写球队名称
- 淘汰赛：队伍A/B 填写引用描述（如"A组第1名"、"第3场赢家"）
- 上传文件，系统自动解析并创建比赛
提示：棍色列填写"黑棍"或"白棍"，系统自动识别。裁判列需填写裁判的显示名。
赛程数据导出
- 在赛程管理页面，点击"导出Excel"按钮
- 系统生成赛程 Excel 并自动下载
- 文件包含所有比赛的对阵、时间、场地、裁判信息
7. 比赛接管与手动完赛
比赛接管
当裁判断线超过 20 秒，系统自动暂停比赛并保存快照。管理员或其他有权限的裁判可以接管该比赛。
- 管理后台会收到实时弹窗通知，显示断线比赛信息（原裁判账号、断线时间、当前比分/阶段）
- 在比赛列表中，断线比赛状态显示为"特殊暂停/断线"
- 点击该比赛进入执裁页面
- 系统自动调用接管 API，解除原裁判执裁锁
- 接管后可选择"恢复比赛"（使用快照数据）或"手动完赛"
权限说明：admin、tadmin、refadmin、tref 角色可以接管比赛。普通裁判（referee/ref1-4）不能接管他人执裁的比赛。
手动完赛
当比赛因断线无法继续时，管理员可直接输入最终比分结束比赛。
- 在管理后台比赛列表中，找到 live 状态的断线比赛
- 点击红色的"手动完赛"按钮
- 在弹窗中输入最终比分 A 和 B
- 确认后比赛标记为 completed
- 后续可通过管理页面补录进球/罚时记录
注意：手动完赛会清除原有事件记录（如有），仅保留最终比分。建议仅在无法恢复比赛时使用。
8. 比赛日志管理
功能概述
- 查看所有比赛日志文件列表（文件名、大小、修改时间）
- 查看单场比赛日志内容
- 删除指定日志文件
- 批量清理超过指定天数的日志（默认 30 天）
提示：每场比赛结束（正常完赛或手动完赛）后会自动生成日志文件，记录比赛过程和最终比分。
1. 登录与入口
登录流程
- 打开浏览器，访问系统首页
- 点击"登录"按钮，进入登录页面
- 输入检录员用户名和密码（如 ck1、ck2、ckadmin）
- 登录成功后跳转至比赛选择页（
/matches）
- 在比赛列表中找到需要检录的比赛，点击进入检录页面
场地限制：ck1 只能看到和操作 Court 1 场地的比赛；ck2 只能看到和操作 Court 2 场地的比赛。ckadmin 和 refadmin 可以操作所有比赛。
2. 检录流程概览
比赛已排程 (scheduled)
→
检录队A大名单
→
检录队B大名单
→
检录完成 (checked)
→
裁判可开始比赛
检录员的核心任务是在比赛开始前，确认双方球队的参赛球员名单。只有两队都完成检录后，裁判才能开始比赛。
3. 赛前检录操作
检录步骤
- 在比赛选择页（
/matches）找到需要检录的比赛
- 点击比赛卡片进入检录页面（
/checkin/比赛ID）
- 页面显示比赛信息（队伍名称、棍色、比赛编号）
- 页面两侧分别显示队伍 A 和队伍 B 的完整大名单
- 点击球员卡片将其移出大名单（适用于不在场的球员）
- 被移出的球员会显示为灰色/删除线状态
- 确认后点击"确认检录"按钮提交
- 系统自动保存大名单并通知裁判端
提示：检录的核心是"移出不在场的球员"，最终上场名单需≤10人。点击灰色球员可恢复其到大名单中。
检录状态说明
| 状态 | 含义 | 可操作 |
|---|
| 未检录 | 两队均未完成检录 | 可检录 |
| 部分检录 | 仅一队完成检录 | 可检录另一队 |
| 已检录 | 两队均完成检录 | ck1/ck2 不可修改，ckadmin 可退回 |
4. 大名单管理
大名单操作说明
- 初始大名单为球队全部注册球员
- 点击球员卡片 = 移出大名单（该球员不参加本场比赛）
- 再次点击灰色球员 = 恢复到大名单
- 检录完成后，裁判端会实时收到大名单更新
- 裁判在赛前设置页面可以看到检录后的上场名单
注意：一旦两队都完成检录（状态变为 checked），ck1/ck2 将无法再修改大名单。如需修改，需联系 ckadmin 退回检录状态。
5. 退回检录（仅 ckadmin / refadmin）
退回操作
当检录有误或需要修改大名单时，ckadmin 或 refadmin 可以退回检录状态。
- 进入需要退回的比赛检录页面
- 点击"退回检录"按钮
- 系统清除检录记录，比赛状态恢复为 scheduled
- 可重新进行检录操作
权限：仅 ckadmin 和 refadmin 可执行退回操作。退回后之前的检录数据将被清除。
6. 注意事项
- 检录需在比赛开始前完成，裁判无法在未检录的情况下开始比赛
- ck1/ck2 仅能操作自己场地的比赛，无法查看其他场地的比赛
- 检录完成后大名单会实时同步到裁判端，无需通知裁判
- 如果球员信息有误（如号码、姓名错误），需联系管理员在球队管理中修改
- 检录页面支持实时刷新，多设备同时操作会同步更新
- 淘汰赛阶段的比赛同样需要检录，流程一致
1. 登录与入口
登录流程
- 打开浏览器，访问系统首页
- 点击"登录"按钮，进入登录页面
- 输入裁判员用户名和密码
- 登录成功后跳转至比赛选择页（
/matches）
- 在比赛列表中找到分配给自己的比赛
- 点击比赛卡片进入执裁页面（
/match/比赛ID）
权限说明：ref1-ref4 和 referee 角色只能看到分配给自己的比赛。refadmin 可以看到所有比赛。admin/tadmin 可以执裁任意比赛。
2. 赛前设置
设置页面内容
进入比赛后首先显示赛前设置页面，包含以下配置项：
| 设置项 | 说明 | 默认值 |
|---|
| 球队信息 | 显示两队名称和棍色（只读） | - |
| 半场时长 | 常规时间每半场时长（1-60分钟） | 12 分钟 |
| 中场休息 | 上下半场间休息时长（1-30分钟） | 3 分钟 |
| 启用加时赛 | 开关，开启后可配置加时赛参数 | 关闭 |
| 加时赛半场时长 | 加时赛每半场时长 | 5 分钟 |
| 加时赛前休息 | 常规时间到加时赛间的休息 | 3 分钟 |
| 加时赛休息 | 加时赛上下半场间休息 | 3 分钟 |
| 金球前休息 | 加时赛平局后进入金球前的休息 | 1 分钟 |
| 每队每节暂停 | 每支球队每节可叫暂停次数（0-5） | 1 次 |
| 暂停时长 | 每次暂停持续时间（30秒/1分钟） | 1 分钟 |
| 最后禁止暂停 | 每节最后N秒不允许暂停 | 最后2分钟 |
| 开始方式 | 纯手动/定时开始/倒计时开始 | 倒计时开始 |
| 进球后罚时 | 进球后是否暂停正在执行的罚时 | 暂停 |
| 进球后倒计时 | 进球后重新开球倒计时 | 30秒 |
赛前检录确认
设置页面下方显示两队大名单。点击球员可将其移出本场比赛名单（需≤10人上场）。检录员完成的检录结果会自动同步到此处。
前提条件：比赛必须已完成检录（两队均已确认）才能开始。如果检录未完成，系统会提示"请等待检录完成"。
3. 开始比赛
开始方式
| 模式 | 说明 |
|---|
| 纯手动 | 点击"开始比赛"按钮后直接进入上半场，时钟不自动启动 |
| 定时开始 | 设置当地时间，到时间后自动开始 |
| 倒计时开始 | 设置倒计时分钟数（1-30分钟），倒计时结束后自动进入上半场 |
开始操作
- 确认赛前设置和大名单无误
- 点击页面底部的"▶ 开始比赛"按钮
- 系统将比赛状态设为 live，并锁定执裁权（其他裁判无法同时执裁）
- 根据开始方式，进入倒计时或直接开始上半场
- 使用空格键或"开始比赛"按钮启动/暂停时钟
执裁锁：同一裁判不能同时执裁多场比赛。如果已有进行中的比赛，需先结束当前比赛才能开始下一场。
4. 比赛操作
核心操作按钮
| 操作 | 按钮 | 快捷键 | 说明 |
|---|
| 犯规/死球 | 📢 犯规/死球 | D | 暂停时钟，记录犯规/死球事件 |
| 比赛继续 | 🔄 比赛继续 | R | 恢复时钟，从犯规/死球/暂停中恢复 |
| 确认进球 | 🥅 确认进球 | G | 记录进球，选择进球球员，更新比分 |
| 确认暂停 | ⏸ 确认暂停 | T | 记录球队暂停，启动暂停倒计时 |
| 判罚出场 | 🟥 判罚出场 | P | 选择犯规球员和罚时时长（1分钟/2分钟/5分钟） |
| 点球 | 🎯 点球 | K | 进入点球模式，记录点球进球或未进 |
| 裁判员暂停 | 🩺 裁判员暂停 | S | 特殊暂停（如球员受伤、设备问题），暂停所有计时 |
| 补登记 | 📝 补登记 | - | 补录之前遗漏的进球或罚时事件 |
| 开始/暂停 | ▶ 开始比赛 | 空格 | 启动或暂停比赛时钟 |
进球操作流程
- 比赛进行中，点击"🥅 确认进球"或按 G
- 选择进球队伍（A队或B队）
- 从大名单中选择进球球员（可搜索号码或姓名）
- 确认后比分自动+1，记录进球时间和当前阶段
- 系统自动进入进球后倒计时（如启用）
- 倒计时结束后或按"比赛继续"恢复比赛
判罚出场流程
- 点击"🟥 判罚出场"或按 P
- 选择犯规队伍
- 选择犯规球员
- 选择罚时时长：1分钟（轻微犯规）/ 2分钟（普通犯规）/ 5分钟（严重犯规）
- 确认后开始罚时倒计时，球员显示为"罚时中"
- 罚时到期时系统弹出提醒，需确认球员回场
提示：罚时期间如果比赛暂停（犯规/死球/暂停），罚时计时也会暂停，恢复比赛后继续。进球后罚时是否暂停取决于赛前设置。
点球流程
- 点击"🎯 点球"或按 K
- 选择执行点球的队伍
- 选择执行球员
- 点球执行后选择"进球"或"未进"
- 如进球，比分+1并记录点球进球事件
- 点球结束后恢复比赛
裁判员暂停
裁判员暂停（原"特殊暂停"）用于处理比赛中的特殊情况，如球员受伤、设备故障等。
- 暂停时所有计时停止（比赛时钟、罚时、暂停倒计时等）
- 界面上方显示"裁判员暂停"状态标签
- 再次点击"裁判员暂停"或按 S 恢复比赛
- 裁判员暂停不计入球队暂停次数
5. 快捷键一览
| 快捷键 | 功能 | 使用场景 |
|---|
| 空格 | 开始/暂停比赛 | 启动时钟或暂停时钟 |
| D | 犯规/死球 | 吹哨停止比赛时使用 |
| R | 比赛继续 | 从停止状态恢复比赛 |
| G | 确认进球 | 有进球时使用 |
| T | 确认暂停 | 球队请求暂停时使用 |
| P | 判罚出场 | 需要罚时球员时使用 |
| K | 点球 | 判罚点球时使用 |
| S | 裁判员暂停 | 需要暂停处理特殊情况时使用 |
提示：快捷键提示显示在页面底部，会根据当前语言自动翻译。建议裁判员熟记快捷键以提高执裁效率。
6. 阶段流程
比赛阶段状态机
赛前准备
→
赛前倒计时
→
上半场
→
中场休息
下半场结束后，裁判需要做出决策：
- 如果比分不同 → 直接结束比赛
- 如果比分相同且启用加时赛 → 进入加时赛前休息
- 如果比分相同且未启用加时赛 → 结束比赛（平局）
加时赛阶段流程
加时赛前休息
→
加时赛上半场
→
加时赛休息
→
加时赛下半场
加时赛下半场
→
裁判决策
→
金球前休息
→
金球加时
→
比赛结束
金球加时为不限时正向计时，任何一方进球即比赛结束（金球制胜）。
休息阶段说明
- 中场休息、加时赛休息等休息阶段会自动倒计时
- 休息期间不需要裁判操作，倒计时结束后自动进入下一阶段
- 休息结束前 30 秒会显示提醒倒计时
- 每节（上半场/下半场/加时赛上半场/加时赛下半场）开始时，暂停次数重置
7. 断线恢复
心跳机制
- 裁判端每 5 秒发送一次心跳请求到服务器
- 服务器检测心跳，超过 20 秒未收到心跳判定为断线
- 断线后服务器自动暂停比赛（设为"特殊暂停"状态）并保存最终快照
- 管理员页面收到实时通知弹窗
离线模式
网络异常时，裁判端自动进入离线模式：
- 界面显示"离线中"提示，告知裁判当前数据未同步
- 所有操作事件暂存到 localStorage 队列
- 比赛状态在内存中继续运行
- 网络恢复后自动按顺序重放离线事件队列
- 长时间断网且前端关闭时，最多丢失最后 10 秒的数据
原裁判重连恢复
- 断线后重新连接，进入比赛页面
- 系统检测到快照数据，直接显示恢复界面（跳过检录/设置加载）
- 恢复界面显示：原裁判账号、断线时间、当前比分、比赛阶段
- 点击"恢复比赛"按钮，以快照数据为基础恢复比赛
- 可编辑关键数据（比分、时间、阶段、暂停次数、罚时等）
- 确认后以"特殊暂停"状态进入比赛界面
- 裁判手动决定何时继续比赛
注意：如果比赛已被其他裁判接管或手动完赛，原裁判重连后将看到相应提示，无法恢复。
其他裁判接管
- admin、tadmin、refadmin、tref 角色可以接管断线比赛
- 接管时自动解除原裁判执裁锁
- 接管后可选择恢复比赛或手动完赛
- 恢复时可修改快照数据（比分、时间、阶段等）
- 恢复后比赛进入"特殊暂停"状态，由接管裁判决定继续时机
8. 补登记
功能说明
补登记用于在比赛进行中或休息阶段，补录之前遗漏的进球或罚时事件。
- 点击"📝 补登记"按钮进入补登记模式
- 选择补登记类型：进球 或 罚时
- 选择事件发生的阶段（上半场/下半场/加时赛等）
- 选择队伍和球员
- （如为罚时）选择罚时时长
- 确认后事件被添加到比赛记录中
- 如果是进球，比分相应更新
提示：补登记的进球阶段会自动匹配当前或最近的比赛阶段。在休息阶段也可以补登记之前阶段的进球。
9. 结束比赛
正常完赛
- 下半场或加时赛下半场结束时，系统等待裁判决策
- 如果比分不同：裁判选择"结束比赛"
- 如果比分相同且启用加时赛：裁判选择"进入加时赛"
- 如果比分相同且未启用加时赛：裁判选择"结束比赛"（平局）
- 金球加时中任何一方进球，比赛自动结束
- 比赛结束后状态变为 completed，自动生成比赛日志
- 射手榜和罚时榜自动重新计算
手动完赛（断线场景）
- 仅 admin、tadmin、refadmin、tref、referee 角色可操作
- 在管理后台或接管后的裁判端操作
- 输入最终比分 A 和 B
- 确认后比赛标记为 completed
- 后续可通过管理页面补录详细记录
比赛结束后
- 执裁锁自动释放（active_referee_id 清空）
- 快照数据自动清除
- 比赛日志文件自动生成
- 射手榜、罚时榜全量重新计算
- 淘汰赛对阵自动可更新（需管理员手动触发）
- refadmin/tadmin/tref 可修改已完成比赛的比分
总结：裁判员的核心操作围绕 8 个快捷键展开。建议赛前熟悉快捷键和操作流程，赛中保持网络稳定，遇到断线不要慌张，系统会自动保存数据并支持恢复。