日期：2026 年 3 月 31 日 —— 4 月 12 日

项目：绘画 AI 博弈小游戏 —— 人机对抗绘画猜词与心理解读系统

一、本阶段整体进度

本阶段项目正式进入开发阶段，团队围绕后端架构搭建、数据库设计、前端画板实现、AI 多模态接口联调四大方向同步推进，完成了从 “方案设计” 到 “代码落地” 的关键一步。

本阶段核心成果：

• 完成 Flask 后端完整骨架，实现 RESTful API + WebSocket 双通信体系
• 配置安全管理（API Key 隔离）
• 完成 SQLite 数据库 7 张表设计与索引优化
• 前端实现 Canvas 在线画板 + 实时同步 + 行为数据采集
• AI 模块完成 智谱 GLM-4V 对接，实现图片识别与猜词
• WebSocket通信架构与Socket.IO实战解析
• 团队四人博客同步更新

完成后端从 0 → 可运行、可联调、可扩展 的基础体系构建，为游戏联机、AI 识别、心理分析模块提供底层支撑。

模块一：需求分析和方案设计

一、功能分析

后端作为项目核心中枢，需承担四大能力：

1. 页面路由：首页、房间页、心理报告页渲染
2. 用户体系：游客模式快速登录、信息存储、历史记录查询
3. 房间管理：创建房间、6 位房间码加入、人数限制、状态同步
4. 实时联机：绘画同步、猜词广播、游戏阶段控制
5. 数据持久化：用户、房间、对局、绘画、猜词、行为、心理报告存储
6. AI 识别接入：多模态模型调用、结果解析、置信度判定
7. 心理分析：绘画特征入库、报告生成与存储

二、库表设计

库名：zhipu.db共 7 张核心表，完全支撑游戏全业务链路：

1. users（用户表）
2. rooms（房间表）
3. room_players（房间 - 玩家关联表）
4. rounds（回合 / 对局表）
5. guesses（玩家猜词表）
6. drawing_behaviors（绘画行为表）
7. psychology_reports（心理报告表）

1. 核心表设计（示例）

-- 用户表
CREATE TABLE IF NOT EXISTS users (
    id          TEXT PRIMARY KEY,
    nickname    TEXT NOT NULL,
    avatar      TEXT DEFAULT '',
    created_at  REAL NOT NULL,
    total_score INTEGER DEFAULT 0,
    games_played INTEGER DEFAULT 0,
    games_won   INTEGER DEFAULT 0
);

-- 房间表
CREATE TABLE IF NOT EXISTS rooms (
    id          TEXT PRIMARY KEY,
    code        TEXT UNIQUE NOT NULL,
    host_id     TEXT NOT NULL,
    status      TEXT DEFAULT 'waiting',
    difficulty  TEXT DEFAULT 'medium',
    max_players INTEGER DEFAULT 4,
    current_round INTEGER DEFAULT 0,
    max_rounds  INTEGER DEFAULT 5,
    created_at  REAL NOT NULL,
    updated_at  REAL NOT NULL,
    FOREIGN KEY (host_id) REFERENCES users(id)
);

三、技术选型与应用

1. Flask 框架优势

• 轻量、灵活、适合快速开发
• 插件生态完善（Flask-SocketIO、Flask-CORS）
• 适合小型实训项目，部署简单
• 与 SQLite 无缝配合

2. Flask-SocketIO 作用

• 提供 WebSocket 长连接
• 支持房间广播、分组发送
• 满足绘画实时同步需求

3. SQLite 优势

• 单文件、零配置、无需启动服务
• 足够支撑 2–4 人联机小游戏数据量
• 便于提交、演示、打包

---

模块二：Flask 项目骨架搭建

一、工程结构设计

zhipu/
├── app.py              # 应用入口、路由、Socket 事件
├── config.py           # 全局配置、密钥、AI配置、游戏参数
├── models.py           # 数据库连接、CRUD、表结构初始化
├── utils/
│   ├── ai_recognizer.py    # AI多模态识别
│   ├── psychology.py       # 心理分析规则
│   └── word_bank.py        # 词库管理
├── templates/          # HTML页面
└── static/             # 前端资源

二、路由划分策略

1. 页面路由（GET）

• / 首页大厅
• /room/<code> 游戏房间
• /report/<id> 心理报告

2. RESTful API（HTTP）

• /api/user/create 创建用户
• /api/room/create 创建房间
• /api/room/join 加入房间
• /api/leaderboard 排行榜
• /api/user/<id>/history 历史记录

3. WebSocket 实时事件

• join_room 加入房间频道
• drawing_update 笔触同步
• submit_guess 提交猜词
• start_game 开始游戏
• round_result 回合结果广播

---

模块三：安全管理

一、config.py 核心设计

采用环境变量优先 + 默认值兜底，实现：

• 密钥不硬编码
• API Key 不上传 Git
• 部署环境自动适配

我们在 config.py 里这样写：

import os
​
# 从环境变量读取，如果没有就用空字符串
ZHIPU_API_KEY = os.environ.get('ZHIPU_API_KEY', '')

然后在启动脚本里设置环境变量：

# Linux/Mac
export ZHIPU_API_KEY="你的密钥"
python app.py
​
# Windows (start.bat)
set ZHIPU_API_KEY=你的密钥
python app.py
 

---

模块四：数据库模块开发（models.py）

一、上下文管理器实现（核心）

@contextmanager
def get_db_connection():
    conn = get_db()
    try:
        yield conn
        conn.commit()
    except Exception:
        conn.rollback()
        raise
    finally:
        conn.close()

作用

• 自动连接 / 关闭
• 自动提交 / 回滚
• 防止连接泄漏
• 保证事务原子性

二、数据模型开发

1. 初始化数据库

def init_db():
    with get_db_connection() as conn:
        conn.executescript('''
        CREATE TABLE IF NOT EXISTS users (...);
        CREATE TABLE IF NOT EXISTS rooms (...);
        ''')

2. 用户 CRUD

def create_user(nickname):
    user_id = str(uuid.uuid4())[:8]
    with get_db_connection() as conn:
        conn.execute(
            'INSERT INTO users (id, nickname, created_at) VALUES (?,?,?)',
            (user_id, nickname, time.time())
        )
    return user_id

3. 房间 CRUD

def create_room(host_id):
    room_id = str(uuid.uuid4())[:8]
    code = _generate_room_code()
    with get_db_connection() as conn:
        conn.execute('INSERT INTO rooms ...')
        conn.execute('INSERT INTO room_players ...')
    return room_id, code

三、索引设计（高频查询优化）

CREATE INDEX IF NOT EXISTS idx_rooms_code ON rooms(code);
CREATE INDEX IF NOT EXISTS idx_room_players_room ON room_players(room_id);
CREATE INDEX IF NOT EXISTS idx_rounds_room ON rounds(room_id);

作用

• 通过房间码快速查找房间
• 快速加载房间内玩家
• 快速加载对局历史
• 避免全表扫描

---

模块五：WebSocket 通信与实时联机设计

一、核心事件设计

@socketio.on('drawing_update')
def handle_drawing_update(data):
    room_id = data.get('room_id')
    stroke_data = data.get('stroke_data')
    emit('drawing_sync', {
        'user_id': data.get('user_id'),
        'stroke_data': stroke_data
    }, to=room_id, include_self=False)

二、通信流程

1. 画家绘制 → 触发 drawing_update
2. 后端广播 → drawing_sync
3. 所有观众实时回放笔触
4. 低延迟、高同步、省流量

---

模块六：Flask-SocketIO async_mode 问题解决

一、问题

• 使用 eventlet 出现兼容性异常
• 第三方 AI SDK 不兼容协程
• Windows 环境不稳定

二、解决方案

socketio = SocketIO(app, async_mode='threading')

threading 优势

• 无额外依赖
• 全平台稳定
• 兼容所有第三方库
• 适合 4 人以内联机

---

模块七：核心业务流程开发（房间→加入→查询）

一、完整流程示例

1. 创建用户
2. 创建房间（返回 6 位 code）
3. 其他用户通过 code 加入
4. 查询房间信息（含玩家列表）
5. 开始游戏 → 进入回合

# 1. 创建用户
host_id = create_user("房主")

# 2. 创建房间
room_id, code = create_room(host_id)

# 3. 加入房间
join_room(room_id, player_id)

# 4. 查询房间信息
room = get_room(room_id)

---

开发总结

本阶段完成后端骨架 + 数据库模块的完整工程化落地：

1. 规范化项目结构，模块化分层清晰
2. 安全的配置体系，密钥与代码隔离
3. 七张表完整库表设计，关系合理、索引齐全
4. 上下文管理器保证数据安全，无连接泄漏
5. REST + WebSocket 双通信模式，支持联机游戏
6. 房间 / 玩家 / 对局 CRUD 可直接支撑前端联调
7. 解决 SocketIO 异步问题，全平台稳定运行

模块已具备可运行、可测试、可扩展能力，为下周前后端联调、AI 识别接入、心理分析模块开发奠定坚实基础。

---

后续计划

1. 前后端全流程联调（登录→房间→绘画→同步→猜词→结果）
2. AI 多模态识别接口完整接入
3. 绘画行为 → 心理特征解析开发
4. 联机延迟优化、异常重连机制
5. 前端界面与游戏状态机完善