这是一个"谁是卧底"游戏的主持方平台，用于管理游戏流程、展示游戏状态和处理游戏逻辑。
- 游戏方注册和组名管理
- 随机分配卧底和平民身份
- 接收和展示游戏方的描述
- 处理投票并判定结果
- 自动计算得分
- 异常上报与记录
- 实时可视化界面
所有后端 API 均返回统一结构：
{
"code": 200,
"message": "ok",
"data": {
"...": "..."
}
}当 code != 200 时，请根据 message 判断失败原因，data 会附带可选的调试信息。
pip install -r requirements.txt（主持方才需要）设置主持方令牌 ADMIN_TOKEN（后端和前端需要一致）：
- Windows PowerShell：
$env:ADMIN_TOKEN="host-secret"
- 未设置时默认值为
host-secret，建议线上环境务必自定义。
推荐方式（使用新的入口文件）：
python run_backend.py或者使用旧方式：
python backend.py后端服务器会在 http://0.0.0.0:5000 启动，显示本机IP地址供游戏方连接。
推荐方式（使用新的入口文件）：
python run_frontend.py或者使用旧方式：
python frontend.py前端界面会在 http://0.0.0.0:5001 启动，提供可视化的游戏管理界面。
- 前端界面（主持方）：
http://localhost:5001 - 后端API（游戏方）：
http://localhost:5000 - 确保游戏方能够访问服务器的IP地址（局域网内）
interactive_client.py 需要把 BASE_URL 改成主持方的IP地址。自己测试的时候就是填入后端日志里的局域网访问后面的地址。
python interactive_client.py- 同时运行前后端
- 在打开多个终端分别运行
interactive_client.py，输入组名 - 主持方在前端开始游戏并开始新回合
- 游戏方按顺序发送描述（每人60秒，超时自动跳过）
- 游戏方进行投票（投票阶段60秒，超过60秒未投票自动跳过）
- 系统自动处理投票结果，如果卧底被票出去了则游戏结束（如果卧底存活，系统会自动开始下一回合）
注意：测试客户端通过按enter手动控制流程进度，实际上线时应该是游戏方通过获取阶段状态来判断进行到哪一步了
Undercover/
├── backend/ # 后端模块（已重构为模块化结构）
│ ├── app.py # Flask应用主入口
│ ├── config.py # 配置（词库、令牌等）
│ ├── utils.py # 工具函数
│ ├── routes/ # REST API路由
│ │ ├── game.py # 游戏控制路由（主持方专用）
│ │ ├── player.py # 玩家相关路由
│ │ └── public.py # 公开API路由
│ ├── websocket/ # WebSocket处理
│ │ └── handlers.py # WebSocket事件处理
│ └── services/ # 服务模块
│ ├── broadcast.py # 广播服务
│ └── timer.py # 倒计时服务
├── frontend/ # 前端模块（已重构为模块化结构）
│ ├── app.py # Flask应用主文件
│ ├── utils.py # 工具函数
│ ├── templates/ # HTML模板
│ │ └── index.html
│ └── static/ # 静态资源
│ ├── css/
│ │ └── style.css
│ └── js/
│ └── main.js
├── game_logic.py # 游戏逻辑核心模块
├── run_backend.py # 后端启动入口（推荐）
├── run_frontend.py # 前端启动入口（推荐）
├── backend.py # 旧后端入口（已废弃，建议使用run_backend.py）
├── frontend.py # 旧前端入口（已废弃，建议使用run_frontend.py）
├── interactive_client.py # 游戏方测试客户端
├── requirements.txt # 依赖包
├── words.txt # 词库文件
└── README.md # 项目说明
本项目适合3人小组分工：
- 网络通信负责人: 负责API接口设计和文档编写
- 前端开发负责人: 负责可视化界面开发
- 后端开发负责人: 负责服务器和游戏逻辑开发
-
描述阶段：
- 描述阶段总时长：180秒（3分钟）
- 每个发言者有 60秒 时间提交描述，超时后自动跳过
- 所有发言者必须在180秒内完成描述
-
投票阶段：
- 投票阶段总时长：60秒（1分钟）
- 在投票阶段开始后，如果某个组超过 60秒 还未投票，会自动跳过（投给自己，表示弃权）
- 重要：如果所有人都投票了（包括被跳过的），系统会立即处理投票结果，不会等到60秒结束
- 如果60秒到了还有组没投票，也会自动跳过所有未投票的组并处理投票结果
- 这样既给每个组足够时间投票，又避免某个组一直不投票导致游戏卡住
- 游戏方通过API注册，输入组名
- 主持方随机选择卧底，分配词语
- 游戏方按顺序发送描述（每人60秒，描述阶段总时长180秒，超时自动跳过）
- 游戏方进行投票（投票阶段总时长60秒，超过60秒未投票自动跳过）
- 系统自动处理投票结果并计算得分
- 如果游戏未结束，自动开始下一回合
终端1 - 启动后端：
python run_backend.py终端2 - 启动前端：
python run_frontend.py终端1 - 启动后端：
python backend.py终端2 - 启动前端：
python frontend.py游戏方需要知道后端服务器的IP地址（后端启动时会显示），然后通过API接口进行注册和游戏。可以使用 interactive_client.py 作为测试客户端。