scuc-qt-course/docs/teaching/PROJECT_GUIDE.md

实训项目集深度解析（按学生关注度：04 / 11 / 02 / 05 / 06 / 08）

题目来源：wiki「02. Qt方向 → 04. 项目集」（pageId 183664900，16 个项目）。 本文对其中学生关注度较高的 6 个项目做深入拆解：题目重点是什么、技术难点在哪、 哪些地方容易卡住、卡住了往哪个方向查。目标是让学生顺利启动、按里程碑推进， 不在环境和 API 细节上消耗整周时间。

每个项目按固定结构展开：定位 → 题目重点 → 技术难点拆解 → 高频坑与排查 → 建议启动路径（里程碑）。里程碑设计原则与 ASSIGNMENTS.md 相同：先保最小可运行闭环，再逐层加功能。

六个项目总览

项目	难度	核心考点	最容易卡住的点
04 简易本地音乐播放器	⭐⭐⭐⭐⭐	QtMultimedia、Model/View、异步元数据	元数据是异步到达的，setMedia 后立即读为空
11 OpenCV 面部识别系统	⭐⭐⭐⭐⭐⭐	OpenCV+Qt 集成、图像格式转换、多线程	环境搭建：MinGW 的 Qt 链不上 MSVC 编译的 OpenCV
02 基于QT的自动售卖机	⭐⭐⭐⭐⭐	QStateMachine、Model/View、互斥锁	带条件的状态跳转（守卫）Qt 没有现成 API
05 个人相册管理与智能标签	⭐⭐⭐⭐⭐	缩略图性能、多线程加载、SQLite 索引	主线程同步加载大图，几十张照片就把界面卡死
06 多功能抽奖与随机点名	⭐⭐⭐⭐	随机算法正确性、定时器动画	CSV 导入中文乱码（Excel 导出的是 GBK）
08 双人飞机大战	⭐⭐⭐⭐⭐	QGraphicsView、游戏循环、碰撞检测	键盘多键同时按：直接在 keyPressEvent 里移动会卡顿、双人抢键

开工前的三条通用提醒（六个项目都适用）

1. 先确认 Qt 版本再写第一行代码。 课程环境是 Qt 5.14.2。自己电脑装了 Qt 6 的 同学注意：这批题目里 04（QMediaPlaylist 在 Qt6 被删除）和 02（QStateMachine 在 Qt6 挪进了独立的 StateMachine 模块）受 Qt5/Qt6 差异影响最大，各项目小节末尾 有版本说明。网上的 Qt5 和 Qt6 示例代码混着抄，是编译报错查半天的常见原因。
2. 资源路径不要用裸相对路径。 双击 exe 和从 IDE 里运行，"当前目录"不一样。 图片、音效等只读资源进 .qrc（:/imgs/xxx.png）；存档、配置等可写数据用 QCoreApplication::applicationDirPath() 或 QStandardPaths 拼绝对路径。 "IDE 里正常、双击就白屏/没声音"多数是这个原因。
3. 每完成一个里程碑就 git commit。 这批题目都要在一份代码上连续叠功能， 没有提交点，一次重构失败就退不回去。验收时 git log 也能说明你是按里程碑推进的。

---

04. 简易本地音乐播放器 ⭐⭐⭐⭐⭐

定位

用 QtMultimedia 做一个能实际使用的播放器：播放控制链路（QMediaPlayer）、 播放列表（Model/View）、元数据展示三块拼起来。没有算法难度，考的是 把 Qt 各模块正确地连在一起，六个项目里属于投入产出比较高的一个。

题目重点

• 这道题的骨架是两条方向相反的状态同步链：
  1. UI → 播放器：按钮/滑块操作调用 play()/pause()/setPosition()/setVolume()；
  2. 播放器 → UI：positionChanged/durationChanged/stateChanged/ metaDataChanged 等信号回写界面。 两条链各自单向、靠信号槽解耦，这正是题面"各UI组件间通过信号与槽高效解耦通信" 要考的。写成"按钮槽里既改播放器又顺手改十个控件"，这部分分就没有了。
• 播放列表用 Model/View（QAbstractTableModel 或至少 QStandardItemModel + QTableView），不要用 QTableWidget 逐格塞字符串，题面明确点了 Model/View。
• 播放模式（列表循环/单曲循环/随机）在 Qt 5.14 里有现成 API： QMediaPlaylist::setPlaybackMode(Loop / CurrentItemInLoop / Random)，一行完成。

技术难点拆解

难点 1：元数据（ID3 标签）是异步到达的。 setMedia() 之后媒体要经历加载 过程，立即调 metaData() 拿到的是空值。正确做法：连接 QMediaPlayer::metaDataAvailableChanged 或 mediaStatusChanged （等 LoadedMedia）信号，在槽里再读 metaData(QMediaMetaData::Title / ContributingArtist / AlbumTitle)。 标题一直显示空白的，基本都是在 setMedia 后下一行就去读了。

难点 2：进度条的拖动回环。 直观的写法是把 positionChanged 连到 slider->setValue()、把 slider->valueChanged 连到 player->setPosition()， 结果两个信号互相触发，拖动时来回跳动甚至卡顿。标准解法：

• 播放器 → 滑块用 setValue（程序触发的 valueChanged 不做 seek）；
• 用户 → 播放器只用 sliderMoved（仅用户拖动才发出），或 sliderPressed 时暂停回写、sliderReleased 时一次性 setPosition()。

难点 3：专辑封面在很多平台后端拿不到。 QMediaMetaData::CoverArtImage 依赖系统解码后端，Windows/Linux 上对 MP3 内嵌封面经常返回空。题面已经给了 降级路径，按题面做即可：拿不到就在歌曲同目录找 cover.jpg/folder.jpg， 再拿不到显示默认占位图。想真正解析 ID3 内嵌封面（APIC 帧）可引入 TagLib， 算加分项，不是及格线。

难点 4：解码后端决定能不能出声。 QMediaPlayer 自己不解码，依赖系统后端： Windows（DirectShow/WMF）放 MP3/WAV 没问题，FLAC 未必；Linux 走 GStreamer， 缺 gstreamer1.0-plugins-good/bad/ugly、gst-libav 就没有声音。 建议先用 WAV 文件打通全链路，再测 MP3/FLAC，把"代码错"和"后端缺解码器" 两类问题分开。

难点 5（可选算法项）：LRC 歌词同步。 题面点了二分查找：把 LRC 解析成 按时间戳排序的 QVector<QPair<qint64, QString>>，positionChanged 里用 std::upper_bound 定位当前行。这是题目"算法与数据结构优化"一节里 最容易落地的一项（Fisher-Yates 随机也是，见项目 06 的展开）。

高频坑与排查

症状	真实原因	排查/解法
编译报 QMediaPlayer: No such file	没链 multimedia 模块	qmake: QT += multimedia；CMake: find_package(... Multimedia) + target_link_libraries(... Qt5::Multimedia)
不报错但没声音	① 后端缺解码器 ② 文件路径错（相对路径） ③ 音量为 0	先播 WAV；QMediaPlayer::error 信号连上打印；路径用 QUrl::fromLocalFile(绝对路径)，不要手拼 file://
歌曲标题/歌手一直空白	元数据异步，读早了	挪进 metaDataAvailableChanged 槽里读
拖进度条时来回跳动	双向信号回环	用 sliderMoved/sliderReleased，见难点 2
显示时间是一串大数字	position() 返回毫秒（qint64）	QTime(0,0).addMSecs(pos).toString("mm:ss")
关闭再打开，列表没了	只存了内存	关闭时（closeEvent）把路径列表写 QSettings 或 JSON，启动时读回；注意存绝对路径
随机模式来回就那两首	用 rand()%n 且每次独立随机	用 QMediaPlaylist::Random，或自己实现 Fisher-Yates 洗牌序列

建议启动路径（里程碑）

1. M1（半天）：一个按钮 + 一个 QMediaPlayer，点击播放一个写死路径的 WAV。 打通"模块链接 + 能出声"，这一步没过不要写任何 UI。
2. M2（1 天）：QFileDialog 多选添加 → QMediaPlaylist + Model/View 列表 → 双击列表任意行播放。
3. M3（1 天）：播放/暂停/上下曲按钮、进度条（含拖动 seek）、音量条、 时间标签。到这里已经可以日常使用。
4. M4（1 天）：三种播放模式切换 + 元数据/封面展示（含降级链）+ 列表持久化。
5. M5（加分，量力）：LRC 歌词二分同步、系统托盘、QSS 明暗双主题、LRU 最近播放。

Qt5 / Qt6 版本说明（本项目受影响最大）

• QMediaPlaylist 在 Qt6 被删除，没有替代类。用 Qt6 就得自己维护 QList<QUrl> + 当前索引 + 播放模式逻辑（mediaStatusChanged 收到 EndOfMedia 时按模式算下一首），工作量不小，选 Qt6 前想清楚。
• Qt6 里 setMedia() 改为 setSource()，且必须 setAudioOutput(new QAudioOutput) 才有声音——Qt6 下没有声音，先查这一条。
• Qt6 的 metaData() 返回 QMediaMetaData 对象，取值用 .value(QMediaMetaData::Title)，与 Qt5 的 API 不同。
• 结论：此题用课程环境 Qt 5.14.2 做，问题最少。

---

11. （OpenCV）基于 OpenCV 的面部识别系统 ⭐⭐⭐⭐⭐⭐

定位

六个里唯一的六星题。难度不在识别算法（模型是现成的），而在工程集成： OpenCV 环境搭建、cv::Mat 与 QImage 互转、视频流不阻塞 UI、 "检测→特征→比对"流水线的正确串联。选这题前要有准备：第一周必须把环境跑通， 跑不通后面无从谈起。

题目重点

• 先分清两个概念，题目是两级流水线，不要混为一谈：
  1. 人脸检测（detection）：找出画面里哪里有脸（矩形框）。传统方案 cv::CascadeClassifier（Haar），现代方案 DNN（如 YuNet / ResNet-SSD）。
  2. 人脸识别（recognition）：判断这张脸是谁。用预训练模型 （SFace/FaceNet/ArcFace 的 ONNX）把人脸编码成 128/512 维特征向量， 与注册库中向量算余弦相似度，超过阈值即判定为该人。
• 识别不是训练神经网络。模型是下载来的 .onnx/.xml 文件， 用 cv::dnn::readNet 或 cv::FaceRecognizerSF 加载。在想"要不要自己训练模型" 的同学可以打住：那不是本题要求，实训周期内也做不完。
• 题面明说"可选只通过图片识别"，这是官方给的降级出口。摄像头/实时流 做不下来时，"导入图片→检测→识别→标注展示"的静态版本仍是一个完整、 可以及格的系统。

技术难点拆解

难点 0（第一关）：环境。 OpenCV 官网给 Windows 的预编译包是 MSVC 编译的， MinGW 版 Qt 链不上（C++ ABI 不兼容，症状是链接期大量 undefined reference）。 三条出路，按推荐排序：

1. Qt 用 MSVC kit（装 Visual Studio Community / Build Tools，Qt 安装时勾选 MSVC 组件），直接用官方 OpenCV 包，最省事；
2. 坚持 MinGW，就要用 CMake + 同版本 MinGW 自己编译 OpenCV（预留一个晚上）；
3. Linux/WSL：apt install libopencv-dev，基本没有这个问题。

第一周内跑不通"读一张图并显示"，就应该向老师求助或换项目。环境是本题 最大的淘汰因素，及时求助不丢人。

难点 1：cv::Mat → QImage 的三个常见错误。

• 通道序：OpenCV 是 BGR，Qt 是 RGB。直接 QImage(mat.data, w, h, QImage::Format_RGB888) 得到的画面偏蓝。 用 QImage::Format_BGR888（Qt 5.14 起可用），或先 cv::cvtColor(BGR2RGB)。
• 行对齐：QImage 构造必须显式传 mat.step 作 bytesPerLine， 否则某些分辨率下图像出现斜纹/错位（Mat 行末可能有 padding）。
• 生命周期：这种构造是浅拷贝，QImage 借用 Mat 的内存。Mat 先析构 （比如函数局部变量）就会花屏或崩溃。跨函数传递前 .copy() 一次。

三个问题合起来，建议直接采用这个写法：

QImage matToQImage(const cv::Mat &bgr) {
    return QImage(bgr.data, bgr.cols, bgr.rows,
                  static_cast<int>(bgr.step),
                  QImage::Format_BGR888).copy();   // copy() 断开内存借用
}

难点 2：视频流驱动方式。 入门版：QTimer 每 33ms 触发 "cap.read() → 检测 → 转 QImage → label->setPixmap()"。能跑，但检测一慢 （DNN 单帧可能超过 100ms）整个 UI 就冻住。正式版：把 VideoCapture + 检测识别 放进 QThread 工作线程，处理完一帧发 frameReady(QImage) 信号回主线程 （QImage 隐式共享，跨线程信号传值安全）。注意子线程里不能直接操作任何 QWidget。 建议先用 QTimer 版打通流程，再整体搬进线程，一步到位容易两头出错。

难点 3：识别流水线的数据设计。 注册（录入）与识别共用前半段：

帧/图片 → 检测得人脸框 → 裁剪+对齐 → 特征提取模型 → 128/512维向量
   注册：向量 + 姓名 存库（多张照片可求平均向量，题面提示了）
   识别：向量与库中所有向量算余弦相似度 → 最高分且超阈值 → 判定身份

数据库不必上 SQL：人数少时 QVector<Person{name, QVector<float> feat}> + JSON 持久化完全够用（题面也允许）。余弦相似度手写只有几行（点积/模长）， 阈值从 0.36（SFace 官方推荐值附近）起调。建议做一个滑块让阈值可调， 演示时展示"调阈值看误识率变化"，本身就是加分点。

难点 4：级联检测器文件路径。 CascadeClassifier::load("haarcascade_frontalface_default.xml") 返回 false 不抛异常，不检查返回值的话，程序照常运行但永远检测不到脸。 xml 在 OpenCV 安装目录 etc/haarcascades/ 下，复制到程序目录并用绝对路径加载， load 后一定要检查返回值。

高频坑与排查

症状	真实原因	排查/解法
链接期大量 undefined reference to cv::...	MinGW Qt 配 MSVC OpenCV	见难点 0，换 MSVC kit 或自编译
程序一启动就闪退	运行时找不到 opencv_worldXXX.dll	把 dll 拷到 exe 旁，或把 OpenCV bin 目录加进 PATH
画面人脸偏蓝	BGR/RGB 通道序	Format_BGR888 或 cvtColor
图像斜纹/花屏/随机崩溃	没传 mat.step / QImage 借用已析构的 Mat	用上面 matToQImage 的写法
摄像头打不开	索引不对 / 被其它程序占用 / 权限	VideoCapture cap(0) 换 1、2 试；检查 cap.isOpened()
检测一直没结果	级联 xml 没加载成功	检查 load() 返回值
检测有框但识别乱认	没做人脸对齐/裁剪就送识别模型；阈值太松	用检测框裁剪（DNN 方案用 FaceRecognizerSF::alignCrop）；调高阈值
一开检测 UI 就明显卡顿	检测在主线程	降低检测频率（每 3 帧检测 1 次，框沿用上一次）或移到工作线程

建议启动路径（里程碑）

1. M1（第一周内必须完成）：环境验证——Qt 程序里用 cv::imread 读一张图、 转 QImage 显示在 QLabel。这是本题第一个必须通过的节点。
2. M2：QTimer + VideoCapture 实时显示摄像头画面（不检测）。
3. M3：加 Haar 级联检测，画面上实时画人脸框（cv::rectangle 或转 QPixmap 后 QPainter 画）。
4. M4：接入特征提取模型（推荐 OpenCV 4.5.4+ 自带的 YuNet 检测 + SFace 识别， API 最顺）；做注册界面：拍照/导入 → 提特征 → 存 JSON。
5. M5：实时比对 + 画面标注姓名/相似度 + 识别日志列表。到此即完整达标。
6. M6（加分，量力）：多张照片平均特征、阈值滑块、识别事件抓拍存盘。 跟踪/活体检测等题面"提升"项投入大、产出小，谨慎选择。

版本说明

• OpenCV 用 4.x（推荐 ≥4.5.4，才有 FaceDetectorYN/FaceRecognizerSF）。 网上大量教程是 3.x 的 cv::face::LBPHFaceRecognizer（在 contrib 模块里， 官方预编译包不含），照抄编译不过，而且 LBPH 效果也远不如 DNN 方案。
• QImage::Format_BGR888 需要 Qt ≥ 5.14，课程环境刚好够用；更老的 Qt 只能 cvtColor。

---

02. 基于 QT 的自动售卖机 ⭐⭐⭐⭐⭐

定位

题面是售卖机，考的其实是软件设计。没有硬技术门槛（不需要多媒体、不需要 第三方库），看的是状态机建模、Model/View 数据流、并发保护、JSON 持久化 四个工程概念用得对不对。它是六个项目里最不容易被环境卡住的选择； 全用 if-else 也能跑起来，但设计分就没有了。

题目重点

• 核心是用状态机管交易流程：待机 → 已投币 → 已选商品 → 出货中 → 找零中 → 完成。 题面点名 QStateMachine。关键在于："当前允许做什么"由状态决定，而不是由 散落各处的 if 判断决定——待机态投币按钮可用、选货按钮禁用；已投币态反之。 评分时首先看的就是这一点。
• 第二个重心是数据与界面分离：商品/库存/零钱集中在一个数据管理类 （单例或注入均可），前台购买界面和后台管理界面共享同一个模型—— 前台买走一瓶，后台表格里的库存立刻变。这是 Model/View 真正的考点： 一份 QAbstractTableModel，两处视图。
• QMutex 那条要求，本质是要求把"扣库存+扣零钱"做成一个原子操作： deductStock() 里 QMutexLocker locker(&mutex); 检查+扣减一起完成。 加分做法：开一个 QThread 模拟并发购买，演示"不加锁会超卖、加锁不会"。

技术难点拆解

难点 1：QStateMachine 是事件驱动异步的，和直觉不同。

• machine.start() 之后状态并不立即进入，要等事件循环跑起来。 start 后下一行断言当前状态，必然失败。
• 状态迁移用 state->addTransition(sender, &Sender::signal, targetState) 声明， UI 更新挂在 QState::entered/exited 信号上，或用 state->assignProperty(widget, "enabled", true) 让状态机自动改属性。 这套接对了，代码里基本不需要手写"if 当前状态是 X"。

难点 2：带条件的迁移（守卫条件）没有现成 API。 "投币额 ≥ 商品价才允许出货" 这种条件迁移，Qt 的标准做法是自定义 Transition：继承 QSignalTransition 重写 eventTest()，不满足条件返回 false（迁移不发生）。嫌重的话有个务实变通： 在槽里判断条件、满足才 emit sufficientPayment()，让状态机只监听这个信号。 两种都算对，后者更容易讲清楚。这是本题最隐蔽的设计问题，动手前先想好， 不要写到一半才发现 addTransition 不支持带条件，回头改架构。

难点 3：找零算法的正确性边界。 贪心（从大面额往小配）对常规币制 {50,20,10,5,1} 是最优的，但零钱库存有限时贪心会失败：库存没有 5 元、有 3 张 2 元时找 6 元，贪心先拿 5 就走进死路。及格线：贪心 + 失败时整单退币（题面明确 允许"无法找零则退币"）；加分线：库存受限的找零本质是完全背包可行性问题， 用 DP 或回溯保证"能找开就一定找得开"。答辩时能说清贪心什么时候会错， 比闷头写 DP 更有价值。

难点 4：持久化的时机与原子性。 "数据变更时自动保存"不要真的每次变更都 全量写盘（快速连点可能写出半截 JSON）。简单可靠的做法：变更只置脏标记 + QTimer 500ms 防抖落盘；写盘用 QSaveFile 替代 QFile（写完才原子替换， 崩溃不损坏存档）。QSaveFile 知道的学生不多，用上可以作为一个细节亮点。

高频坑与排查

症状	真实原因	排查/解法
machine.start() 后状态没进入	状态机异步启动	初始化逻辑挂到 initialState 的 entered 信号，不要 start 后同步读状态
迁移不触发	信号签名不匹配 / 当前不在源状态	迁移只在源状态激活时监听；连 QState::entered 打日志看状态流
忘了 setInitialState	状态机启动即静默停止	machine.setErrorState/日志；new 完状态第一件事设初始态
后台改库存前台不动	两界面各持一份数据副本	共享同一个 model 实例；改数据走 setData 或发 dataChanged
表格改了数字界面不刷	自定义 model 改数据没 emit dataChanged	所有修改路径统一收口到一个函数，里面负责 emit
偶发库存变负数	检查与扣减分离，中间被插队	"检查+扣减"放进同一个 QMutexLocker 作用域
JSON 读回来全是 0	QJsonObject 取值类型不对（如 toInt() 用在 double 上）/ 键名拼写	先 qDebug() << doc.toJson() 核对；封装 load/save 对称函数
程序异常退出后存档损坏	直接 QFile 覆盖写	换 QSaveFile

建议启动路径（里程碑）

1. M1（1 天）：不带界面，先写 VendingData 数据类（商品表、零钱表、 加锁的 deduct/refund 接口）+ JSON load/save，用 qDebug 自测。数据层立住， 后面基本是接线工作。
2. M2（1 天）：前台购买界面（商品按钮阵列 + 投币按钮 + 信息提示区）， 先用普通槽函数把"投币→选货→出货→找零"跑通（暂时用 if-else 没关系）。
3. M3（1–2 天）：引入 QStateMachine 重构 M2 的流程控制——按钮使能交给 assignProperty，流程迁移交给 transition。先能跑再重构，比一步到位稳。
4. M4（1 天）：管理员后台（密码 QDialog + QTableView 库存表，共享模型）+ 售罄置灰、无法找零拦截两条异常流。
5. M5（加分）：交易流水 + 报表（QSortFilterProxyModel 排序即可，QtCharts 可选）、 多线程购买压测演示、折扣规则引擎。

版本说明

• Qt6 中 QStateMachine 被移出 QtCore，进了独立的 statemachine 模块 （QT += statemachine / find_package(Qt6 COMPONENTS StateMachine)）。 Qt 5.14 下在 QtCore 里直接用，无需额外配置。
• QtCharts 在 Qt 5.14 是独立模块（QT += charts，且要在安装器里勾选过）。 没装的话报表用 QTableView 呈现即可，不必为一张柱状图重装 Qt。

---

05. 个人相册管理与智能标签应用 ⭐⭐⭐⭐⭐

定位

一道性能敏感的 Model/View 大题：核心挑战不是显示图片（一行 setPixmap 的事）， 而是几百上千张照片下界面依然流畅——缩略图异步加载、元数据索引、组合筛选。 "智能标签"名字唬人，实际是可裁剪的加分层：题目允许从"手动标签 + 搜索" 起步，ONNX 智能识别放在最后做。

题目重点

• 本题真正的关键是索引：把图片路径、拍摄日期、评分、标签、收藏这些 元数据放进一个独立于文件系统的库（SQLite 或 JSON 起步），所有浏览、搜索、 筛选都查库，不实时扫磁盘。想通这一点，"虚拟相册"（同一张图归入多个相册 而不复制文件）、组合筛选、倒排索引都是顺理成章的查询而已。
• 第二个关键是缩略图网格的性能。评分演示时老师多半会导入一大批照片， 滚动一卡，前面做得再多也减分。这是本题技术含量最高的部分（见难点 1）。
• 智能标签的合理做法：先把手动标签的完整链路做穿（加标签→存库→按标签搜索）， 智能标签只是标签的另一个生产者——接 ONNX 后生成的标签走完全相同的 存储/搜索链路。架构对了，"智能"是插件；架构不对，"智能"意味着重写。

技术难点拆解

难点 1：缩略图异步加载。 直观的写法：遍历文件夹，每张 QPixmap(path).scaled(...) 塞进 QListWidget。一张 12MP 的 JPEG 解码要 几十上百毫秒，100 张照片主线程就冻结十几秒。正确做法分三层：

1. 解码离开主线程：用 QThreadPool + QRunnable（或 QtConcurrent::run） 在后台解码并缩放，完成后发信号把缩略图（QImage，跨线程传值安全）交回主线程。 注意 QPixmap 不能在非 GUI 线程创建，后台一律用 QImage，回主线程再转。
2. 读小不读大：QImageReader reader(path); reader.setScaledSize(QSize(200,200)); ——JPEG 可以按比例降采样解码，比"解全图再 scaled"快一个数量级、省数倍内存。 这是本题最值得记住的一个 API。
3. 缩略图磁盘缓存：首次生成后存到缓存目录（文件名用路径哈希）， 第二次打开应用直接读缓存。加分项。

视图层用 QListView::IconMode + 自定义 model（配合按需供数）， 不要用 QListWidget 一次性塞几千个 item。

难点 2：SQLite 表设计（标签是多对多）。 三张表就够： photos(id, path, date, rating, favorite)、tags(id, name)、 photo_tags(photo_id, tag_id)。"按标签找图"就是一个 JOIN，这本身就是 题面"倒排索引"的数据库实现，答辩时可以直接这样讲。组合筛选（日期范围 + 评分 + 标签）就是动态拼 WHERE 子句。不想上 QtSql 的同学用 JSON + 内存 QHash<QString标签, QSet<int>图片id> 也能达标，但数据量大后启动变慢。

难点 3：ONNX Runtime 集成（可选层，放最后做）。 流程：下载 squeezenet / mobilenet 分类 ONNX 模型 → C++ 里 Ort::Session 加载 → 图片缩放到 224×224、 归一化成 float tensor → 推理 → top-5 类别按 ImageNet 标签表映射成中文标签存库。 坑主要在预处理：通道序（NCHW vs NHWC）、归一化均值方差要和模型训练时一致， 不一致不报错但输出全错。人脸分组（聚类）工作量再上一个台阶， 建议只有已完成全部基础功能、确有余力的同学做。

难点 4：非破坏性编辑 + 撤销。 题面点了命令模式：每个编辑操作 （旋转/裁剪/调色）封装成命令对象压栈，undo 出栈反做。Qt 有现成的 QUndoStack/QUndoCommand，不必自己实现栈管理。"非破坏性"最省事的实现： 不覆盖原图，编辑结果另存副本，或只存操作参数列表、显示时重放。

高频坑与排查

症状	真实原因	排查/解法
导入文件夹时界面冻死	主线程同步解码大图	QImageReader::setScaledSize + 线程池，见难点 1
后台线程崩溃：QPixmap: It is not safe...	子线程创建了 QPixmap	子线程只用 QImage
内存涨到几个 GB	缓存了全尺寸 QImage	只留缩略图；看大图时才解码全图，且用 QPixmapCache 限额
部分照片没有拍摄日期	截图/微信图片本无 EXIF	降级链：EXIF DateTimeOriginal → 文件修改时间；Qt 自带 EXIF 读取很弱，完整 EXIF 建议引入 TinyEXIF/easyexif（单头文件）
手机竖拍照片横过来了	没处理 EXIF Orientation	QImageReader::setAutoTransform(true)，一行解决
搜索一次卡一秒	每次搜索全量扫描	元数据进 SQLite 建索引，或内存哈希
删除照片后列表错乱	直接操作文件没同步库	所有增删走数据层统一入口，UI 只发请求
中文路径图片读不出	用了 std::string/fopen 链路	全程用 QString/QFile；给 OpenCV/stb 传路径时注意 UTF-8 转换

建议启动路径（里程碑）

1. M1（1 天）：选文件夹 → 列出所有图片文件 → 同步加载 20 张的缩略图网格 + 双击全屏看图（先不管性能，打通视觉闭环）。
2. M2（1–2 天）：把 M1 的加载改成 QImageReader 降采样 + 线程池异步。 验收标准：导入 500 张照片，滚动不卡。这是本题技术难度最高的一步，值得花足时间。
3. M3（1 天）：元数据层——SQLite/JSON 三表结构，手动标签、星级、收藏的 增删改查 + 持久化。
4. M4（1 天）：搜索框（文件名/标签实时过滤）+ 组合筛选面板（日期范围/评分/ 收藏）。到此为完整达标的相册管理器。
5. M5（加分）：虚拟相册、旋转/裁剪/亮度对比度编辑 + QUndoStack 撤销、 缩略图磁盘缓存。
6. M6（大加分，量力）：ONNX 自动标签；人脸检测分组（可参考项目 11 的 OpenCV 部分，环境成本也相同）。

版本说明

• QImageReader::setAutoTransform 在 Qt5 默认 false（Qt6 默认 true）。 课程环境下不手动打开，竖拍照片就会横着显示。
• QtSql 的 SQLite 驱动随 Qt 发行版自带，无需另装 SQLite；MySQL 等驱动不自带， 不要把时间花在配数据库服务上，本题 SQLite 文件库就够了。

---

06. 多功能抽奖与随机点名程序 ⭐⭐⭐⭐

定位

六个里唯一的四星题，功能面窄，但考正确性：随机算法是否真的公平、 不重复抽取是否真的不重复、权重抽奖概率是否真的和权重成正比。 适合想稳妥完成、把精力花在细节上的同学。注意题面的算法项 （Fisher-Yates、轮盘赌）是答辩必问点，只写一个 rand()%n 过不了关。

题目重点

• UI 上的"滚动"只是演出，抽取结果在点"开始"那一刻就该定了。合理的架构： 按下开始 → 先用算法抽出结果 → QTimer 驱动名字快速轮播制造悬念 → 按下停止 → 动画减速定格到预定结果。让"停止那一刻的随机数"决定中奖者， 公平性就依赖用户手速，答辩说不清。这一条想通了，逻辑层（抽取）和 表现层（动画）自然就分开了。
• 三个算法是题目的核心，各 20 行以内，务必自己写、写到能白板复现：
  1. Fisher-Yates 洗牌（从 N 人不重复抽 M 人：洗牌取前 M）；
  2. 轮盘赌选择（权重抽奖：随机数落在累计权重区间上）；
  3. 随机数源：QRandomGenerator::global()->bounded(n)，自动用系统熵播种。 rand() 不 srand 的话每次运行结果相同，演示时会当场暴露。
• 名单管理（增删改、txt/CSV 导入、持久化）是体力活，但中文编码有一个 几乎必踩的坑，见下。

技术难点拆解

难点 1：CSV/文本导入的编码。 Windows Excel 导出的 CSV 默认 GBK/ANSI 编码，QTextStream 按默认设置读（Qt5 是 Locale，而记事本另存的 UTF-8 又带 BOM），中文名很容易乱码。稳妥做法：读入字节后探测——有 UTF-8 BOM 按 UTF-8， 否则先按 UTF-8 严格解码、失败再退 GBK（QTextCodec::codecForName("GBK")）。 另外 CSV 字段可能带引号包裹和内嵌逗号，课程场景用 line.split(',') 可以接受， 但至少要 trimmed() 并跳过空行。（xlsx 是压缩包格式，Qt 原生读不了， 题面说"CSV 或 xlsx"，选 CSV 即可，不必为 xlsx 引第三方库。）

难点 2：滚动动画的两种实现，选简单的那种。 题面提示了 QPropertyAnimation， 但对"名字快速切换"这个效果，QTimer + 每 tick 换 QLabel 文本才是对口工具 （30–50ms 一换足够快）。QPropertyAnimation 适合做结果揭晓的放大/滑入动画 （配合 QGraphicsOpacityEffect 或对 geometry 做动画）。"减速定格"用变周期 QTimer：每次 tick 后 interval *= 1.15，超过 300ms 时停在预定结果， 二十行代码就有不错的现场效果。

难点 3：不重复抽取的状态一致性。 "抽过的人从池子里移除"说起来简单， 坑在多处状态要同步：候选池、已中奖列表、UI 上两个列表控件。要先定好 数据以谁为准：数据层一个 QList<Person> + 一个 QSet<int> drawnIds， 两个视图都从它渲染。再叠加"中途重置""切换可重复模式""删除已中奖的人" 这些操作时才不会乱。先想清数据结构，UI 只是它的投影。

难点 4：权重抽奖 + 不重复的组合。 各自单独都好写，组合时注意：抽走一人后 总权重要重算（或轮盘赌遍历时跳过已中者）。验证方法值得写进报告： 循环抽 10 万次统计频率，和权重比例对照，这个小实验就是公平性的答辩证据。

高频坑与排查

症状	真实原因	排查/解法
导入名单中文乱码	Excel CSV 是 GBK	编码探测降级链，见难点 1
每次运行抽中的人一样	rand() 没播种	换 QRandomGenerator::global()
"不重复"偶尔重复	从 UI 控件读名单，删除项后索引错位	状态收口到数据层，UI 只渲染
滚动动画卡顿	tick 里做了重活（如重排全列表）	tick 只改一个 QLabel 文本
多人抽取结果有重复	循环 M 次独立随机	Fisher-Yates 洗牌取前 M
全屏后布局错乱	固定坐标写死	全程用布局管理器；全屏用 showFullScreen()，记得处理 Esc 退出
音效不响	路径/模块问题	QSoundEffect 只支持 WAV，不解码 MP3；QT += multimedia；资源走 qrc

建议启动路径（里程碑）

1. M1（半天）：控制台级验证——名单硬编码，Fisher-Yates 抽 M 人、轮盘赌 带权抽 1 人，qDebug 打印 + 万次频率统计自检。算法先于界面。
2. M2（1 天）：主界面：名单列表（增删改）+ txt/CSV 导入（含编码处理）+ JSON 持久化。
3. M3（1 天）：单人抽取全流程：开始滚动 → 停止减速定格 → 结果进 "已中奖"列表；可重复/不可重复开关。
4. M4（半天）：多人抽取模式 + 中奖记录导出 txt + 抽奖/点名模式切换文案。
5. M5（加分）：权重列 + 轮盘赌抽奖、分组抽奖、结果揭晓 QPropertyAnimation 动画、背景音乐音效、全屏模式、自定义背景图。

版本说明

• QTextCodec 在 Qt6 移入 core5compat 兼容模块（Qt6 正统是 QStringConverter/QStringDecoder）。课程环境 Qt 5.14 直接用 QTextCodec 即可。
• QRandomGenerator 需要 Qt ≥ 5.10，课程环境没问题；教程里出现 qsrand/qrand（已废弃）的可以跳过不看。

---

08. 双人飞机大战 ⭐⭐⭐⭐⭐

定位

一道实时程序架构题：游戏循环、大量对象的生命周期管理、键盘多键并发、 碰撞检测，和前五个事件驱动的表单程序是完全不同的思维方式。 它是六个里代码量最大、最容易烂尾的：功能清单（双人、三模式、道具、 BOSS、弹幕）是开放的，没有里程碑约束很容易把时间耗在素材和关卡设计上。 另一面是演示效果最好，适合愿意投入的同学。

题目重点

• 先选定框架路线，两条路二选一，不要混：
  • 路线 A：QGraphicsView 框架（题面推荐）——QGraphicsScene 管对象、 QGraphicsItem 派生飞机/子弹、场景自带 collidingItems() 碰撞检测。 省很多底层代码，但要理解 item 坐标系和场景坐标系的区别。
  • 路线 B：QWidget + QPainter 手绘——一个大 widget，paintEvent 里画所有 对象，自己维护对象列表和矩形碰撞。原始一些，但每一步都在自己掌控里， 配套教材 ch10 的绘图知识直接够用。
  • 建议：跟着题面走 A；如果 QGraphicsView 两天内没找到感觉，及时退到 B。 B 路线做完，好过 A 路线做一半。
• 游戏循环是全部逻辑的驱动源：一个 QTimer（16ms ≈ 60FPS）驱动每帧 处理输入 → 移动所有对象 → 生成敌机/子弹 → 碰撞检测 → 清理死亡对象 → 重绘。 所有会动的东西都由这一个 timer 统一驱动。给每个子弹/敌机各开一个 QTimer 是常见错误，几百个 timer 会把事件循环拖垮，而且相位不齐。
• 对象生命周期是本题隐含的 C++ 考点：子弹飞出屏幕、敌机被击落，都要从 场景移除并 delete。忘删，内存与遍历量持续膨胀，越玩越卡； 删早了（还在容器遍历中），程序崩溃。见难点 3。

技术难点拆解

难点 1：键盘多键同时按（双人模式的关键）。 直接在 keyPressEvent 里 player.move() 有两个问题：一是依赖系统键盘重复，第一下和连发之间有停顿， 手感卡；二是玩家1 按住 W 时玩家2 再按方向键，系统键盘重复只服务最后按下的键, 另一个玩家会直接失控。标准解法是按键状态表 + 游戏循环采样：

QSet<int> pressedKeys;
void keyPressEvent(QKeyEvent *e) override {
    if (e->isAutoRepeat()) return;          // 屏蔽系统自动重复
    pressedKeys.insert(e->key());
}
void keyReleaseEvent(QKeyEvent *e) override {
    if (e->isAutoRepeat()) return;
    pressedKeys.remove(e->key());
}
// 游戏循环每帧：
if (pressedKeys.contains(Qt::Key_W)) p1.moveUp();
if (pressedKeys.contains(Qt::Key_Up)) p2.moveUp();   // 互不干扰，天然支持斜向

双人模式能不能玩取决于这一段，建议一开始就按这个写法来。另外游戏主 widget 要 setFocusPolicy(Qt::StrongFocus)，否则按键事件不会分发到它。

难点 2：碰撞检测的量级与精度。

• 起步：矩形相交（QRect::intersects 或 QGraphicsView 的 collidingItems） 完全够用。QGraphicsItem 默认按 boundingRect+shape() 判定；飞机贴图 四角是透明的，会出现"看着没碰到就爆了"——重写 shape() 返回缩小的 QPainterPath，或直接把判定框缩成机身核心（弹幕游戏的通行做法， 玩家只会觉得手感变好）。
• 量级：每帧"所有子弹 × 所有敌机"是 O(N²)，课程规模（500 个对象以内） 暴力检测没有问题——先暴力，卡了再优化。题面的四叉树是加分项，报告里 给出"对象数-帧耗时"对比数据，比只谈复杂度有说服力。
• 帧率稳定性：QTimer 精度默认约 15ms 且会漂移，位移量写死"每帧 5 像素" 在卡顿时会变慢。进阶写法：用 QElapsedTimer 测真实帧间隔 dt， 位移 = 速度 × dt。及格线不强求，答辩能说出这个问题在哪就是加分。

难点 3：容器遍历中删除对象。 每帧要清理出界子弹/死亡敌机， for (auto *b : bullets) { if (出界) { bullets.removeOne(b); delete b; } } 是遍历中修改容器，未定义行为，迟早崩溃。两个安全做法： 一，标记-清扫：遍历只打 dead 标记，遍历结束后统一 removeIf + delete（或 QMutableListIterator）； 二，碰撞回调里不直接 delete 对方，只标记。另外 QGraphicsScene 删 item 要 scene->removeItem(item); delete item;，只 delete 的话场景还留着悬空指针。 这是本题最常见的崩溃原因，写清理代码前先把这段看明白。

难点 4：对象设计与生成节奏。 建一个基类（如 Entity：位置/速度/血量/ advance()/rect()），玩家机、敌机、子弹、道具全部派生。多态在这里不是 为了展示技巧，是实际需要：游戏循环只面对 QList<Entity*>。敌机生成用 "生成计时器 + 关卡脚本"（第几秒出什么阵型），数据驱动（写在表/JSON 里） 比硬编码 if 好调平衡。关于素材：飞机/子弹贴图用开源素材包（如 Kenney.nl 免费素材），自己画像素图非常耗时；实在没素材，纯色几何图形（QPainter 画三角形飞机）完全不影响技术评分。

难点 5：双人对战模式的裁剪。 题面三模式（单人/合作/对战）全做工作量很大。 架构上留好口子即可：碰撞规则表里"玩家子弹是否伤害另一玩家"是一个 bool， 合作为 false、对战为 true——对战模式本质是碰撞规则的一次配置变更。 想通这层，第三模式的边际成本很低；想不通就先做单人+合作。

高频坑与排查

症状	真实原因	排查/解法
按方向键飞机不动	焦点不在游戏 widget 上	setFocusPolicy(Qt::StrongFocus)；场景/视图结构下注意谁拿焦点
移动一顿一顿 / 双人互相抢键	直接在 keyPressEvent 移动	按键状态表 + 循环采样，见难点 1
玩一会儿越来越卡	出界子弹没清理，对象只增不减	每帧清理；调试时在窗口标题实时显示对象数，方便发现泄漏
随机崩溃在碰撞/清理附近	遍历中删除 / 双重 delete	标记-清扫，见难点 3
子弹出生位置不对	item 坐标系与场景坐标系混淆	生成子弹用 mapToScene()/item->scenePos() 换算
看着没碰到就判死	判定框是含透明边的整图矩形	重写 shape() 或缩小判定矩形
背景滚动有裂缝	两张背景图衔接坐标差 1 像素 / 非整数位移	两张图首尾相接循环复位；位移取整
全屏炸弹一放帧率骤降	一帧内 delete 几百对象 + 特效	分帧清理，或炸弹只做标记、由正常清理流程消化
CPU 占一核 100%	timer 间隔设 0 或忙循环	16ms 间隔足够；QGraphicsView 的 setViewportUpdateMode 用默认值即可

建议启动路径（里程碑）

1. M1（1 天）：窗口 + 游戏循环 timer + 一架能被 WASD 流畅操控的飞机 （按键状态表一步到位）。这一步的手感决定整个项目的手感。
2. M2（1 天）：玩家子弹（按住 J 连发、出界清理）+ 敌机从顶部随机生成 直线下落 + 子弹打敌机的碰撞与爆炸消失。到这里游戏已经成立。
3. M3（1 天）：敌机撞玩家/敌弹打玩家 → 生命值与无敌闪烁 → 得分显示 → Game Over 判定。加第二名玩家（方向键 + 小键盘0），合作模式成立。
4. M4（1 天）：滚动背景、开始菜单/暂停/结束三场景切换（简单 FSM： 一个 enum + QStackedWidget 或场景切换）、最高分持久化（QSettings）。
5. M5（加分）：道具掉落、BOSS（多阶段血条 + 正弦/极坐标弹幕）、 对战模式（碰撞规则开关）、音效（QSoundEffect + WAV）。
6. 提醒一条执行纪律：M2 没完成前不做素材、不写 BOSS。本题烂尾的原因 几乎都是顺序反了。

版本说明

• 本题用到的 QGraphicsView/QPainter/事件系统在 Qt5/Qt6 间差异很小， 是六题中版本风险最低的。注意音效走 QSoundEffect（只支持 WAV）， 背景音乐才用 QMediaPlayer——后者在 Qt6 的差异见项目 04 的版本说明。
• 高分屏（Windows 缩放 150%）下坐标可能被缩放干扰，演示机若有此问题， 入口处 QApplication::setAttribute(Qt::AA_EnableHighDpiScaling)（Qt 5.14） 或环境变量 QT_SCALE_FACTOR=1 兜底。

---

怎么选、怎么起步

• 想稳妥拿分、不被环境问题拖住：选 02 售卖机 或 06 抽奖点名。 纯 Qt 标准模块，问题集中在设计和细节，本文的排查表能覆盖大部分。
• 想做完自己还能用：选 04 音乐播放器 或 05 相册管理。 多媒体和性能两个方向各有一个硬难点（异步元数据 / 异步缩略图）， 啃下来收获扎实。
• 接受环境风险、想上技术高度：选 11 面部识别。第一周先过环境验证（M1）， 过不了及时降级到图片识别版或换题。
• 看重答辩演示效果：选 08 飞机大战。用里程碑约束进度，M2 前不碰素材。

无论选哪个：第一周结束时必须有一个能运行的 M1。这批项目的失败方式高度一致： 前两周画界面调样式，最后一周才发现核心链路（能出声/能链上库/状态机能转/ 键盘不卡）有硬问题。先做最难的部分。