个人博客

Via错题本：把英语错题整理做成一个离线 App

Fri, 04 Sep 2026 10:40:00 GMT

Via错题本：把英语错题整理做成一个离线 App#

跟 Via 老师学英语，也把每一次错题变成下一次进步的素材。

网址：mistake.viaenglish.xyz

一、项目简介#

Via错题本是一个面向英语学习场景的错题整理工具。它可以读取学生上传的英语试卷 DOCX 文件，根据试卷结构识别 Part、Passage 和题号，再按学生选择的错题范围生成一份新的错题本 DOCX 文档。

这个项目最初是一个浏览器网页工具，后来在保留网站版本的基础上，增加了 Android App。App 使用 WebView 承载网页界面，同时通过 Android 原生能力完成文件选择和文档保存。

项目的核心目标很简单：减少手工抄录错题的时间，让学生把精力放回到理解、订正和复习上。

二、主要功能#

1. 选择学生和排版方式#

用户输入学生姓名，并选择错题本的生成方式：

按题型分类
按考试分类

2. 上传英语试卷#

工具支持选择 .docx 格式的英语试卷。文件在本地解析，不需要上传到服务器。

3. 识别试卷结构#

程序会从 DOCX 内部的 XML 结构中读取段落、表格和图片，并尝试识别：

Part
Passage
考试分区
题号
题目文本
选项
文章内容
题目中的图片

4. 按题号添加错题#

题号支持多种输入形式，例如：

1
21, 22, 24
2
36-45
3
21, 24, 36-45

程序会根据所选排版方式和题号范围，提取对应的题目内容，并自动过滤重复错题。

5. 错题预览#

App 将操作区和预览区拆成两个界面：

主界面：填写姓名、选择排版方式、上传试卷、添加题目
预览界面：集中查看已添加的错题

这样可以避免在一个页面里堆叠过多内容，手机上操作也更清晰。

6. 生成并导出 DOCX#

程序会基于内置的 DOCX 模板生成错题本，保留文字、表格和图片。Android App 点击“生成错题本”后，会调用系统保存界面，由用户选择文件保存位置。

三、界面设计#

App 的界面遵循“少说明、快操作”的原则：

主标题使用“Via错题本”
标题下方显示“跟Via老师学英语”
右上角放置 Via 老师 Logo
主界面只保留必要字段和按钮
错题预览单独作为第二个界面
使用绿色作为主强调色，保持学习工具的清爽感
表单和按钮采用适合手机触控的尺寸

相比桌面网页，App 版本隐藏了较长的帮助说明和规则文字，把信息分成操作流程和预览结果两个阶段。

四、技术实现#

网页端#

HTML
CSS
原生 JavaScript
JSZip 3.10.1
Web APIs：File、FileReader、Blob、URL、DOMParser

网页端负责主要业务逻辑，包括：

读取 DOCX 文件
解压 DOCX ZIP 包
解析 word/document.xml
读取关系文件和媒体资源
识别题号、Part、Passage 和文章结构
生成新的 document.xml
把内容重新写回 DOCX ZIP 包

Android 端#

Android App 使用 Java 编写原生外壳，WebView 加载 App 内置的网页资源。

原生层主要负责：

初始化 WebView
加载内置 index.html
调用 Android 系统文件选择器读取试卷
从 App 内置资源读取 DOCX 输出模板
接收网页生成的 Base64 文档数据
调用系统“另存为”界面保存 DOCX
处理 Android 返回键
在 WebView 初始化失败时显示兜底错误页面

网页和原生层之间通过一个范围受限的 JavaScript Bridge 通信：

1
网页 index.html
2
    │
3
    ├── AndroidApp.loadAsset("output-template.docx")
4
    └── AndroidApp.saveDocx(base64Data, fileName)
5
             │
6
             └── Android 系统文件保存界面

五、DOCX 处理思路#

DOCX 文件本质上是一个 ZIP 压缩包，里面包含 XML 文档和媒体资源。项目没有依赖服务器端转换，而是在浏览器或 WebView 中直接处理文件。

基本流程如下：

1
选择试卷 DOCX
2
    ↓
3
读取 ZIP 文件
4
    ↓
5
解析 document.xml
6
    ↓
7
提取段落、表格和图片
8
    ↓
9
识别 Part / Passage / 题号
10
    ↓
11
生成错题条目
12
    ↓
13
读取输出模板
14
    ↓
15
替换模板正文
16
    ↓
17
重新打包 DOCX
18
    ↓
19
保存错题本文件

展开收起

这种方式的优点是数据不需要离开设备，适合处理学生试卷这类包含个人学习信息的文件。

六、项目中比较有挑战的部分#

1. DOCX 不是简单的纯文本#

题目可能出现在普通段落、表格、图片或多个 XML 节点中。解析时不能只读取页面上看到的文字，还要处理 Word 文档中的关系文件、媒体文件和格式结构。

2. 不同试卷的结构并不完全一致#

同样是 Part one，有的试卷会明确写出 Passage，有的试卷只通过题号和段落顺序表达结构。因此项目使用了多种识别规则，并为没有显式 Passage 的情况提供回退逻辑。

3. 网页下载和 Android 保存方式不同#

浏览器可以通过 Blob 和 <a download> 下载文件，但 Android App 更适合调用系统文件保存器。最终方案保留了浏览器下载逻辑，同时在 App 中切换到原生保存流程。

4. 离线运行#

最初网页通过 CDN 加载 JSZip。为了让 App 在没有网络的环境中也可以使用，Android 版本把 JSZip 复制到 assets 目录，并把输出模板一并内置。

七、工程结构#

1
错题本/
2
├── 错题本生成器2.4.html          # 原始网站版本
3
├── 输出模版.docx                  # 原始输出模板
4
├── logo.jpg                       # Via 老师 Logo
5
├── android-app/                   # Android Studio 工程
6
│   ├── app/
7
│   │   └── src/main/
8
│   │       ├── assets/
9
│   │       │   ├── index.html     # App 内置页面
10
│   │       │   ├── jszip.min.js   # 本地 JSZip
11
│   │       │   ├── logo.jpg       # App 顶部 Logo
12
│   │       │   └── output-template.docx
13
│   │       ├── java/
14
│   │       │   └── .../MainActivity.java
15
│   │       └── res/
16
│   ├── build.gradle.kts
17
│   ├── settings.gradle.kts
18
│   └── README.md
19
└── Via错题本项目介绍.md

展开收起

八、当前版本#

应用名称：Via错题本
Android Application ID：com.mistakebook.app
当前版本：1.0.5
最低支持版本：Android 7.0（API 24）
编译版本：Android 15（API 35）
Android Gradle Plugin：8.11.0
Gradle：8.13
Java：17+

1
## 结语
2

3
## 下载
4

5
[下载 Android APK](/downloads/via-mistake-book.apk)
6

7
Via错题本不是一个复杂的在线平台，而是一个围绕真实学习流程打磨的小工具：把试卷交给程序，把时间留给学习。
8

9
从网页到 Android App 的过程，也让我重新认识到一个实用工具的价值不只在于“能不能实现”，还在于它是否足够简单、稳定，并且真正贴近用户每天的使用习惯。

Via 作文批改：一个面向学生与教师的英语作文智能批改系统

Fri, 04 Sep 2026 10:30:00 GMT

Via 作文批改：一个面向学生与教师的英语作文智能批改系统#

项目简介#

Via 作文批改是一个面向中学英语写作场景的作文批改系统，提供学生端和教师端两套使用入口。

学生可以直接输入作文，也可以上传作文图片、Word 或 PDF 文件；系统会对图片作文进行 OCR 识别，经过人工校正后，再生成结构化的 AI 批改报告。教师可以查看学生作文、筛选批改状态、阅读详细报告，并补充教师意见。

项目同时提供 Web 网站和 Android APP：

Web 网站：适合电脑浏览器使用，保留完整的后台与报告能力。
Android APP：使用原生 Android WebView 承载网站，针对手机屏幕重新设计了页面布局和交互。

项目地址（部署版本）：https://grade.viaenglish.xyz

为什么做这个项目#

传统英语作文批改通常需要教师逐句阅读、标注错误、给出评分，再整理成评语。这个过程耗时较长，而且学生往往只能看到一个总分，无法快速定位自己在语法、词汇、结构和内容方面的问题。

这个项目希望把作文批改拆成一条可追踪的数字化流程：

1
提交作文
2
   ↓
3
图片 OCR 识别 / 文本读取
4
   ↓
5
人工校正（图片作文）
6
   ↓
7
AI 生成结构化批改报告
8
   ↓
9
按维度查看评分与建议
10
   ↓
11
网页阅读或导出 Word 报告

重点不是只给出一个“作文分数”，而是把评分依据、错误位置、修改建议和参考范文组织成可以继续学习的反馈。

核心功能#

1. 学生端作文提交#

学生登录后可以创建作文记录，并填写以下内容：

作文标题
作文正文
作文要求或题干
作文图片、Word、PDF 等文件
作文要求图片

图片作文会进入 OCR 流程；纯文本作文可以直接进入批改流程。系统会保存作文原文、确认后的文本、文件信息和处理状态，便于后续查看历史记录。

2. OCR 识别与人工校正#

对于手写或拍照作文，系统会优先调用腾讯云 OCR 进行识别，并保存 OCR 原文和识别质量信息。

OCR 结果不直接作为最终批改文本，而是先进入人工校正页面。教师或学生可以检查段落、单词和标点，确认后再生成 AI 报告。这样可以减少因为图片模糊、手写连笔或版面复杂导致的误判。

当 OCR 服务不可用时，系统会保留可继续编辑的兜底状态，而不是让整个提交流程直接中断。

3. AI 结构化批改#

报告生成模块优先调用腾讯混元大模型，并对返回结果做 JSON 解析、字段校验和分数归一化。

当前报告主要包含：

语法评分与语法错误分析
词汇评分与词汇替换建议
结构评分与段落改进建议
内容评分与扣题反馈
综合得分和等级
改进建议
教师确认意见
标准版参考范文
高级版参考范文
原文标注与错误详解

提示词中明确要求模型引用学生原句、针对真实作文进行评价，并限制各评分项和输出格式。服务异常时，系统会生成明确的兜底报告，提示用户核对 OCR 文本或稍后重新生成。

4. 报告分类阅读#

报告页面不是把所有内容一次性堆在长页面中，而是按学习目标拆分成多个入口：

错误详解
语法错误分析
词汇使用
结构改进
内容反馈
改进建议（含老师）
参考范文标准版
高级版
导出报告

在 APP 中，报告首页只展示这些分类菜单；点击菜单后进入对应详情页，再通过返回按钮回到分类首页。这样可以让学生先选择自己想看的维度，降低阅读复杂报告时的信息压力。

评分标准、学生习作图片版和学生习作文字版等原始页面内容没有继续作为独立菜单展示，避免和“错误详解”及评分维度重复。

5. 教师端管理#

教师端可以：

查看学生作文列表
按状态筛选作文
搜索学生
查看作文详情和批改报告
补充或修改教师确认意见
创建、修改和停用学生账号
重置学生密码

学生和教师使用不同的角色权限，登录后会进入各自对应的工作区。

6. Word 报告导出#

网站提供 /api/word/[id] 接口，根据作文和报告数据生成真实的 .docx 文件，并设置下载文件名和正确的 MIME 类型。

导出文档使用 docx 库生成，内容可以继续在 Microsoft Word 或其他兼容软件中编辑、打印和归档。

APP 对导出链接做了专门兼容处理：报告导出请求可以交由系统浏览器接管，使用方式与网站原本的下载行为保持一致。由于网站登录 Cookie 与手机浏览器的登录 Cookie 相互独立，首次在浏览器下载时可能需要先在浏览器中登录网站。

技术架构#

Web 项目#

网站使用 Next.js App Router 构建，主要技术包括：

Next.js 15
React 19
TypeScript
Prisma ORM
SQLite（开发环境）
bcryptjs（密码哈希校验）
Zod（表单数据校验）
docx（Word 文档生成）
腾讯云 OCR
腾讯混元大模型

项目的主要目录如下：

1
grade-web/
2
├─ src/app/                  # 页面、路由和 API Route Handler
3
├─ src/components/           # 报告、布局和交互组件
4
├─ src/lib/actions.ts        # Server Actions：登录、提交、生成报告等
5
├─ src/lib/auth.ts           # Cookie 会话和角色权限
6
├─ src/lib/ocr.ts            # OCR 调用与兜底逻辑
7
├─ src/lib/review.ts         # AI 批改、提示词、JSON 校验和兜底报告
8
├─ src/lib/word-export.ts    # Word 报告生成
9
├─ prisma/schema.prisma      # 数据模型
10
└─ public/                   # 模板、示例图片和字体资源

数据模型#

系统围绕以下几类数据组织：

User：登录账号和角色
Student / Teacher：角色扩展信息
Essay：作文主记录、正文、题目要求和处理状态
EssayFile：作文图片、Word、PDF 等附件
OcrResult：OCR 原文、校正文本、识别质量和供应商信息
CorrectionReport：总分、分项评分、分析文本和参考范文
ReportAnnotation：原文中的错误、修改结果和批注

登录状态使用签名 Cookie 保存，密码在数据库中以哈希形式存储。APP 的“记住密码”功能不直接把密码写入网页存储，而是通过 Android 原生桥接，使用 Android Keystore 中的 AES-GCM 密钥加密后保存。

Android APP 适配#

Android APP 位于 android-app/，本质上是一个轻量的原生 Android WebView 客户端。

APP 的设计目标#

网站继续作为主要业务系统，不重复实现后端逻辑
手机端界面更简洁，减少说明性文字
报告内容按分类分屏查看
保留图片选择、登录、网页后退和断网重试能力
通过 Logo、APP 名称和移动端菜单形成独立的 APP 体验

APP 专属界面#

APP 通过 assets/app.js 和 assets/app.css 注入移动端样式与交互，不改变网站在普通浏览器中的视觉布局。

主要适配包括：

首页隐藏冗余描述，只保留学生、教师入口和图标
开屏显示 logo.jpg，并限制 Logo 在合理尺寸内，保持原图比例
登录页增加“记住密码”功能，并避免 WebView 重复注入造成多个复选框
提交页优化输入框、文件上传区和按钮布局
进度页展示作文图片预览
报告页改为分类菜单 + 详情页的交互模式
普通页面使用底部导航，报告分类页使用铺满屏幕的菜单布局
APP 名称设置为“Via作文批改”

原生层职责#

MainActivity.java 主要负责：

创建和配置 WebView
注入 APP CSS 和 JavaScript
控制页面加载时机，避免原网页开屏界面闪现
调用 Android 文件选择器
保存和读取加密登录凭据
处理外部链接和报告导出链接
显示加载失败页面和重试按钮

网站业务仍由 Next.js 服务端完成，因此 APP 不需要复制数据库、OCR 或 AI 逻辑。

一个完整的使用示例#

以学生上传作文图片为例：

学生打开 Via 作文批改，选择“学生入口”。
登录后填写作文标题，可上传作文图片和题干图片。
系统保存作文记录，并把图片送入 OCR。
学生或教师在 OCR 页面检查识别结果并确认文本。
点击生成报告，服务端调用 AI 模型生成四项评分和详细建议。
生成页展示作文图片预览与处理进度。
报告首页显示九个分类入口。
学生依次查看语法、词汇、结构、内容和改进建议。
需要归档时，从“导出报告”进入 Word 导出流程。

项目中的几个关键问题#

OCR 不能直接等同于最终文本#

图片识别存在漏字、错字、断行和标点问题。因此项目把“识别”和“确认”拆开，先让人检查，再让 AI 批改。

AI 输出需要结构化约束#

大模型输出可能出现字段缺失、格式不统一或分数不合法。项目通过提示词约束、JSON 解析、字段校验、分数归一化和兜底报告，保证页面始终能渲染。

移动端不适合直接照搬桌面页面#

原始报告内容较多，如果在手机上连续展示，会形成很长的滚动页面。因此 APP 把报告拆成多个分类入口，让用户按需查看。

WebView 下载与浏览器下载存在会话差异#

网站报告接口依赖登录 Cookie。WebView、Android 系统下载服务和外部浏览器之间的 Cookie 并不天然共享，因此导出功能需要根据实际设备环境选择接管方式，并在真机上验证登录态和文件保存行为。

本地运行与构建#

启动网站#

Terminal window

1
cd grade-web
2
npm.cmd install
3
npm.cmd run prisma:generate
4
npm.cmd run db:reset
5
npm.cmd run dev

默认访问地址：http://localhost:3000

生产环境需要配置数据库、会话密钥、上传目录、腾讯云 OCR 凭据和混元模型凭据。真实密钥不应写入仓库或博客文章。

构建 Android APP#

Terminal window

1
cd android-app
2
$env:JAVA_HOME='E:\Program Files\Android\Android Studio\jbr'
3
$env:ANDROID_HOME='E:\Android\Sdk'
4
$env:ANDROID_SDK_ROOT='E:\Android\Sdk'
5
$env:GRADLE_USER_HOME='E:\Android\Gradle'
6
.\gradlew.bat clean :app:assembleDebug --offline --console=plain

生成的 Debug APK 位于：

1
android-app/app/build/outputs/apk/debug/app-debug.apk

后续计划#

后续可以继续完善以下方向：

增加 PDF 报告导出
支持更多 OCR 供应商和本地 OCR
增加作文版本对比和修改前后 diff
增加班级统计、分数趋势和错误类型统计
增加报告分享和教师批量导出
对 APP 下载流程做更多 Android 版本和浏览器兼容性测试
将开发环境 SQLite 平滑迁移到生产级数据库
增加自动化测试、接口监控和报告生成耗时统计

总结#

下载#

下载 Android APK

Via 作文批改并不是简单地把一个大模型接口包装成“打分工具”，而是围绕作文批改建立了一条完整流程：从文件上传、OCR 识别、人工确认，到 AI 分项评分、教师复核和 Word 归档。

这个项目的核心价值在于把复杂的批改结果拆解成学生能理解、教师能复核、系统能持续扩展的结构化数据，同时通过 Web + Android WebView 的方式，用较低成本兼顾电脑端和移动端使用体验。

秋招督学：把求职准备拆成每天可执行的动作

Fri, 04 Sep 2026 10:20:00 GMT

秋招督学：把求职准备拆成每天可执行的动作#

一个面向嵌入式 C/C++ 秋招的个人学习与求职管理 App。它把目标倒计时、每日任务、专注计时、能力地图、复习记录和求职进度放在同一条执行链路里，帮助我回答一个很具体的问题：今天最应该做什么，以及做完之后留下了什么证据？

项目背景#

准备嵌入式岗位时，学习内容往往同时横跨 C/C++、数据结构、Linux、MCU、驱动、RTOS、网络、项目和面试表达。传统待办应用只能记录“要做什么”，却很难持续回答下面几件事：

今天应该优先补哪一个能力短板？
任务延期后，如何保留原计划并重新安排？
学过的知识是否真正掌握，什么时候需要再次复习？
投递、笔试、面试之后，是否完成了复盘并形成下一步行动？

“秋招督学”就是在这个背景下做的一个个人工具。它不试图替代课程、题库或招聘平台，而是专注于把“目标—计划—执行—复盘”串成闭环。

核心功能#

1. 首次设置与目标倒计时#

首次打开 App 时，可以设置称呼、目标岗位、目标准备完成日、每天可投入时间和当前阶段。保存后，系统会生成当天的起步计划，并在首页展示距离目标日期的剩余天数。

目标岗位支持多选，内置嵌入式软件、嵌入式 Linux、单片机 / RTOS 和 C++ 开发等方向。计划中的任务数量由用户自己决定，不强制固定为“三件事”，更强调可兑现的承诺。

2. 今日作战台#

首页只保留最重要的信息：

距离目标日期还有多少天；
当前备战阶段；
今日任务完成进度；
今日有效专注分钟数；
待复习知识点数量；
开始专注、今日复盘和历史复盘入口。

任务的创建、编辑和删除统一放在“计划”页，首页负责快速确认状态，减少打开 App 后的决策成本。

3. 计划与逾期补救#

任务包含标题、日期、预计时长、类型、关联能力域、完成标准、优先级和“当日必做”标记。支持学习、算法、项目、复习、简历、投递、面试准备和复盘等类型。

历史未完成任务不会被自动挪到今天，而是按原计划日期保留在“历史未完成”视图中。这样既能看到真实的延期记录，也可以继续编辑、完成或删除，避免因为漏做一天而丢失上下文。

4. 专注计时#

专注模块支持正计时和倒计时两种模式：

正计时：从 00:00 开始累计，适合自由投入；
倒计时：支持 25、45、60、90 分钟预设；
两种模式都支持暂停、继续、最小化和结束；
App 进入后台或锁屏后，重新回到页面仍能根据时间戳恢复准确状态；
结束后记录有效专注时长，关联任务时可以继续填写成果和掌握程度。

进行中的计时状态保存在 localStorage，历史专注记录写入本地数据库。少于 1 分钟的片段默认不计入有效专注，避免统计被误触或短暂试用污染。

5. 能力地图与间隔复习#

能力页内置 10 个能力域，包括：

能力域	示例知识点
C 语言与底层语义	指针、内存、位运算、未定义行为、编译链接
现代 C++	RAII、移动语义、智能指针、STL、并发
数据结构与算法	链表、树、排序、二分、动态规划
操作系统与 Linux	进程线程、同步、虚拟内存、GDB、strace
MCU 与计算机体系	Cortex-M、中断、DMA、启动文件、链接脚本
驱动、接口与硬件调试	GPIO、UART、I2C、SPI、CAN、设备树
RTOS 与实时系统	调度、队列、信号量、优先级反转、FreeRTOS
网络与通信	TCP/IP、Socket、MQTT、抓包与故障定位
工程、构建与质量	Git、CMake、交叉编译、测试、Sanitizer
项目表达与求职	项目职责、技术难点、量化指标、面试复盘

每个能力域包含具体知识点。用户可以逐项点亮自己确认掌握的内容，等级按“已点亮知识点 / 总知识点”自动计算为 0～5 级，不依赖一个看似精确但缺少依据的主观分数。

完成学习任务后，可以填写 1～5 级掌握程度，并将任务加入复习队列。复习结果分为“忘记、模糊、基本掌握、熟练”，系统按照 1、3、7、14、30 天间隔计算下一次复习日期。

6. AI 每日计划建议#

AI 计划不是自动写入待办的黑盒功能，而是一个“候选生成器”：

前端收集目标岗位、当前阶段、剩余天数、能力掌握度、已点亮 / 未点亮知识点、今日已排任务和剩余时间；
Kotlin 原生层通过 WebView Bridge 将请求转发到 CloudBase 云函数；
云函数调用腾讯混元 MaaS，要求模型返回 4～8 个具体、可验收的任务候选；
客户端再次校验任务类型、能力 ID、时长、重复标题和总时长；
用户勾选后，候选任务才会真正加入今日计划。

云函数不会使用本地规则伪装成模型结果。当网络、云函数或模型异常时，界面会显示真实失败原因，而不是返回一组看起来像 AI 生成的假数据。

7. 求职看板与复盘#

求职页用阶段看板管理岗位记录，阶段包括“意向、已投递、笔试、一面、二面 / 终面、Offer、结束”。每条记录可以保存公司、岗位、下一步日期和备注，并一键创建准备任务。

每日复盘记录当天收获、未完成原因、明天最重要的一件事以及明天计划做几件事。历史复盘按日期倒序保存，避免复盘变成一次性弹窗。

“我的”页面提供最近 7 天的执行周报，包括有效专注时长、任务完成率、学习天数、新增求职记录和每日柱状图，并支持调用 Android 分享能力输出纯文本周报。

技术架构#

本地 HTML/CSS/JavaScript

IndexedDB

localStorage

进行中计时与内容缓存

Kotlin WebView Bridge

通知、闹钟、分享、文件导入导出、RSS

CloudBase HTTP 云函数

Tencent MaaS / 混元

本地 HTML/CSS/JavaScript

IndexedDB

localStorage

进行中计时与内容缓存

Kotlin WebView Bridge

通知、闹钟、分享、文件导入导出、RSS

CloudBase HTTP 云函数

Tencent MaaS / 混元

Android 原生壳#

Kotlin + Android SDK；
minSdk 26，targetSdk 35，Java / Kotlin JVM 17；
单 Activity 承载本地 WebView 页面；
通过 AndroidBridge 暴露通知、闹钟、分享、文件选择、行业资讯和 AI 请求等能力；
使用 AlarmManager 实现专注结束提醒和每日计划 / 复盘提醒；
外部 HTTP(S) 链接交给系统浏览器打开，应用内只加载受信任的本地资源。

本地 Web 应用#

HTML + CSS + 原生 JavaScript，无运行时 CDN 依赖；
页面资源随 APK 打包在 app/src/main/assets/www；
使用 IndexedDB 保存 profile、tasks、skills、sessions、applications、reviews、settings 七类数据；
IndexedDB 不可用时回退到 localStorage，保证浏览器预览和部分受限环境仍可工作；
使用响应式布局、深色主题、语义化按钮和 aria-* 属性，适配移动端屏幕。

云端 AI 服务#

CloudBase 函数 cloudbase/daily-advice/index.js 同时提供两类能力：

daily-plan：根据能力短板和剩余时间生成今日任务候选；
行业资讯学习建议：基于真实 RSS 文章生成摘要、关联能力、练习和面试自测问题。

模型密钥只配置在云函数环境变量 TENCENT_MAAS_API_KEY 中，不写入 Android 工程、前端资源或 Git。

关键实现取舍#

本地优先，而不是先做账号系统#

这是一个个人使用工具，核心数据不依赖登录和云同步。离线时仍然可以创建任务、计时、复盘和复习；只有行业资讯和 AI 建议需要网络。这样既降低了首版复杂度，也减少了学习记录被上传的隐私风险。

时间戳驱动计时，而不是依赖定时器累计#

JavaScript 的 setInterval 只能负责刷新界面，真正的计时依据是 startedAt、runStartedAt、elapsedBeforePauseMs 和 endAt。因此页面进入后台、被系统挂起或重新打开后，都可以重新计算实际经过的时间。

AI 负责建议，人负责承诺#

AI 只生成候选任务，用户必须明确勾选后才会写入计划。这一设计保留了 AI 的拆解能力，同时避免模型在不了解真实精力和临时安排时替用户做决定。

真实数据优先于“看起来完整”#

行业资讯只接受真实 RSS 内容；AI 失败时不返回本地假候选；能力等级由知识点点亮比例计算。项目更关注数据口径可解释，而不是让页面始终显示一个漂亮但不可信的数字。

测试与验证#

项目提供 tools/webview-smoke-test.mjs，通过 WebView 调试协议覆盖主要交互链路，包括：

底部导航和页面切换；
目标设置、任务新增 / 编辑 / 删除；
AI 候选生成与仅添加已勾选任务；
逾期任务按原日期展示；
正计时暂停、恢复、最小化和结束；
能力知识点点亮与等级更新；
求职记录新增、阶段更新和删除；
每日复盘与历史复盘；
Android 原生 Bridge 是否可用。

本地构建 Debug APK：

Terminal window

1
./gradlew assembleDebug

Windows PowerShell：

Terminal window

1
.\gradlew.bat assembleDebug

生成的 APK 默认位于：

1
app/build/outputs/apk/debug/app-debug.apk

项目结构#

1
.
2
├─ app/
3
│  └─ src/main/
4
│     ├─ java/com/qiuzhao/supervisor/
5
│     │  ├─ MainActivity.kt              # WebView 容器与原生桥接
6
│     │  ├─ FocusAlarmReceiver.kt        # 专注结束通知
7
│     │  └─ DailyReminderReceiver.kt     # 每日提醒通知
8
│     ├─ assets/www/
9
│     │  ├─ index.html                   # 页面结构与弹窗
10
│     │  ├─ css/app.css                  # 主题与响应式样式
11
│     │  └─ js/app.js                    # 状态、数据和交互逻辑
12
│     └─ AndroidManifest.xml
13
├─ cloudbase/daily-advice/
14
│  ├─ index.js                           # AI 计划 / 行业建议云函数
15
│  └─ DEPLOY.md                          # 部署说明
16
├─ tools/webview-smoke-test.mjs          # WebView 端到端冒烟测试
17
└─ REQUIREMENTS.md                       # 产品需求与验收标准

展开收起

当前状态与后续方向#

当前版本已经完成个人使用场景下的 MVP 主链路：本地数据、任务计划、专注计时、能力地图、间隔复习、求职记录、每日 / 历史复盘、原生通知、RSS 行业资讯和 AI 任务建议。

后续可以继续完善：

更丰富的日 / 周 / 月统计和图表；
周报图片分享、桌面小组件和通知快捷操作；
简历版本管理与求职数据导出；
可选的端到端加密云同步；
更细粒度的岗位能力模板和计划模板。

写在最后#

下载#

下载 Android APK

这个项目对我来说，重点不只是“做了一个待办 App”，而是尝试把自己的求职方法固化成一套可执行、可追踪、可复盘的工具：

把目标拆成任务，把任务变成专注记录，把记录沉淀成能力变化，再把复盘结果带回下一次计划。

它仍然是一个个人项目，但也正因为使用者就是我自己，很多交互取舍都来自真实使用中的摩擦，而不是先假设一个理想用户。

基于 ZigBee 与 4G 的无线温湿度监测及远程控制系统

Fri, 04 Sep 2026 10:10:00 GMT

基于 ZigBee 与 4G 的无线温湿度监测及远程控制系统#

项目简介#

这是一个面向物联网环境监测场景设计的嵌入式项目。系统使用 CC2530 和 DHT11 组成无线采集终端，通过 ZigBee 将温湿度数据发送给协调器；协调器中的 CC2530 负责接收无线数据，STM32F103 负责数据解析、状态显示与告警控制，最后通过 ML307R 4G 模块将数据上传到 OneNET 云平台。

除了基本的数据采集和云端展示，系统还实现了温湿度超限告警、LED 与蜂鸣器控制、云端属性下发以及网络异常后的自动重连，形成了一条完整的“端—网关—云”物联网链路。

项目最终实现的主要功能包括：

DHT11 温湿度周期采集；
终端 OLED 本地数据显示；
CC2530 ZigBee 自动组网与无线传输；
STM32 串口接收、帧校验和异常重同步；
网关 OLED 显示节点地址、温湿度、网络状态和上传次数；
温湿度超限时通过 RGB LED 和蜂鸣器报警；
ML307R 通过 4G 网络接入 OneNET；
云端查看温湿度及执行 LED、蜂鸣器远程控制；
4G 掉线或连续发布失败后的自动重连。

项目效果#

系统正常运行后，数据链路如下：

1
DHT11
2
  ↓
3
终端 CC2530
4
  ↓ ZigBee
5
协调器 CC2530
6
  ↓ UART
7
STM32F103
8
  ↓ USART3 / AT 指令
9
ML307R 4G 模块
10
  ↓ 蜂窝网络
11
OneNET 云平台

终端 OLED 用于显示当前 ZigBee 入网状态、节点短地址、温度和湿度；网关 OLED 用于显示接收到的节点数据、4G 网络状态、云端发布状态以及串口诊断计数。

将本文迁移到博客时，需要同时上传上图，或者将图片地址替换为博客图床地址。

系统架构#

系统可以分为采集终端、ZigBee 协调器、4G 网关和云平台四个部分。

层级	核心器件	主要职责
采集终端	CC2530、DHT11、OLED	采集温湿度、显示数据、加入 ZigBee 网络并周期发送数据
ZigBee 协调器	CC2530	建立 ZigBee 网络、接收终端数据、提取节点短地址并通过串口转发
4G 网关	STM32F103RCT6、ML307R、OLED、RGB LED、蜂鸣器	解析数据、显示状态、执行告警、连接 4G 并与 OneNET 通信
云平台	OneNET	保存和展示设备属性，并向网关下发控制命令

这样的分层方式将局域无线采集与广域网络通信分离：CC2530 专注于 ZigBee 组网，STM32 专注于网关业务，ML307R 专注于蜂窝联网。各模块之间通过明确的数据协议连接，便于单独调试和后续扩展。

硬件组成#

采集终端#

终端以 CC2530 为主控，主要外设连接如下：

功能	引脚
DHT11 DATA	P2.0，外接 10 kΩ 上拉电阻
OLED SCL	P1.2
OLED SDA	P1.3
蜂鸣器	P1.7
LED1	P1.4
LED2	P0.1
LED3	P1.0
LED4	P1.1

终端完成 ZigBee 入网后，大约每 2.000～2.255 秒采集并发送一次数据。增加少量随机抖动，可以降低多个终端同时发送造成碰撞的概率。

协调器与 4G 网关#

协调器板上同时包含 CC2530 和 STM32F103RCT6。两颗 MCU 分工明确：CC2530 处理 ZigBee 协议栈，STM32 负责网关业务。

功能	STM32 引脚	连接对象
ZigBee 数据输入	PC11 / UART4_RX	CC2530 P0.4 / USART1_TX
调试串口	PA9、PA10 / USART1	CH340N / USB1
ML307R 通信	PB10、PB11 / USART3	ML307R
OLED SCL	PA12	板载 OLED
OLED SDA	PA11	板载 OLED
RGB LED	PC13、PC14、PC15	板载 LED
蜂鸣器	PA15	板载有源蜂鸣器驱动电路

三路串口均采用 115200、8N1：USART1 输出调试日志，UART4 接收 CC2530 数据，USART3 与 ML307R 通信，从硬件和软件层面避免了串口资源冲突。

软件与工具链#

模块	开发环境或框架
CC2530 ZigBee 程序	TI Z-Stack、IAR Embedded Workbench for 8051
STM32 网关程序	Keil MDK、STM32F10x 标准外设库
蜂窝通信	ML307R RTU 固件及 AT 指令
云平台	OneNET 物联网平台

CC2530 工程基于 Z-Stack 的 SampleApp 示例进行二次开发，在 OSAL 事件机制中加入 DHT11 采集、OLED 显示和传感器数据发送任务。STM32 工程采用前后台结构：中断负责快速接收数据，主循环负责协议解析、设备控制和云端通信。

数据通信设计#

终端到协调器：ZigBee 数据帧#

终端成功读取 DHT11 后发送 5 字节数据：

1
['T', 'H', temperature, humidity, checksum]

校验值为前 4 个字节相加后取低 8 位：

1
checksum = 'T' + 'H' + temperature + humidity;

协调器收到数据后会检查帧头、长度、校验值和温湿度范围。数据有效时，它从 Z-Stack 的接收包结构中读取真实的 ZigBee 网络短地址：

1
pkt->srcAddr.addr.shortAddr

因此，网关不仅能知道温湿度，还能区分数据来自哪个终端节点。协调器接收成功后会向终端广播 D1 确认帧，终端通过 LED 显示本次数据已被接收。

协调器到 STM32：ASCII 串口帧#

为了方便串口调试和跨平台解析，CC2530 将无线数据转换为固定格式的 ASCII 帧：

1
$TH,IIII,TTT,HHH*CC\r\n

各字段含义如下：

字段	含义
`IIII`	4 位十六进制 ZigBee 网络短地址
`TTT`	3 位十进制温度
`HHH`	3 位十进制湿度
`CC`	从字符 `T` 到湿度末位之间所有 ASCII 字节的异或校验

示例：

1
$TH,E839,025,060*CC\r\n

STM32 的 UART4 中断只负责把字节写入 128 字节环形缓冲区，避免在中断中执行耗时操作。主循环再以 $ 为同步字符，以换行符为帧结束标志，完成格式检查、异或校验、数值转换和量程判断。

这种设计即使遇到丢字节、粘包或无效数据，也能在下一次出现 $ 时重新同步。网关还记录累计接收字节数和无效帧数，并显示为：

1
UART B:<接收字节数> E:<无效帧数>

这组计数在排查引脚、波特率和数据格式问题时非常实用。

STM32 到 OneNET：4G 属性上报#

STM32 通过 USART3 向 ML307R 发送 AT 指令，主要初始化过程包括：

连续发送 AT，确认模块已经完成启动且串口通信稳定；
选择 OneNET RTU 任务；
写入产品、设备和鉴权参数；
配置会话清理、保活时间和多消息模式；
订阅属性上报回复与属性设置通道；
重启模块并等待蜂窝网络注册完成；
发布一次设备属性，并以平台返回的 code:200 作为真正成功的依据。

每次上报的数据不仅包含温度和湿度，还包含本地输出设备的当前状态：

1
{
2
  "id": "1",
3
  "version": "1.0",
4
  "params": {
5
    "temp": { "value": 25 },
6
    "humi": { "value": 60 },
7
    "LED1": { "value": false },
8
    "LED2": { "value": false },
9
    "buzzer": { "value": false }
10
  }
11
}

程序只有在收到 OneNET 的成功回复后才增加 OLED 上的上传计数，避免将“AT 指令已经发出”误判为“数据已经被云平台接受”。

告警与远程控制#

网关默认采用以下告警规则：

温度大于 28 ℃时点亮红灯；
湿度大于 80% 时点亮蓝灯；
红灯或蓝灯任意一个处于告警状态时，蜂鸣器鸣响。

阈值集中定义在 协调器4G上云/app_config.h 中，便于根据应用场景调整。

OneNET 还可以向设备下发 LED1、LED2 和 buzzer 布尔属性。STM32 使用一个按长度接收的状态机解析 ML307R 主动上报的属性设置消息，执行本地控制后，再向平台返回对应的 set_reply。

本地告警请求和云端蜂鸣器请求采用“逻辑或”合并：只要告警条件或云端控制有任意一方要求蜂鸣器开启，蜂鸣器就保持鸣响。这样可以避免远程操作意外屏蔽现场告警。

程序运行流程#

终端流程#

初始化 CC2530、OLED 和 DHT11；
启动 Z-Stack 并搜索 ZigBee 网络；
入网成功后启动周期任务；
读取 DHT11 的 40 位数据并校验；
在 OLED 显示节点地址、温度和湿度；
通过 ZigBee 发送传感器帧；
等待协调器确认，并进入下一次采集周期。

DHT11 读取失败时，OLED 会显示 DHT11 ERROR，程序不会发送无效数据。

网关流程#

初始化调试串口、UART4、OLED、LED、蜂鸣器和 ML307R；
配置 ML307R 并连接 OneNET；
持续从 UART4 环形缓冲区取出 CC2530 数据；
对串口帧执行重新同步、格式检查和校验；
更新 OLED、LED 和蜂鸣器状态；
将最新属性上传到 OneNET；
处理云端属性下发；
连续发布失败达到上限后，将网络标记为离线并定期重连。

即使 4G 网络暂时不可用，ZigBee 数据接收、OLED 显示和现场告警仍然可以继续运行，避免云端故障影响本地监测功能。

项目目录说明#

1
zuwang/
2
├─ Projects/                              # Z-Stack 与 CC2530 主工程
3
│  └─ zstack/Samples/SampleApp/
4
├─ Components/                            # Z-Stack HAL 与公共组件
5
├─ 终端采集温湿度/                         # 早期终端独立工程及参考代码
6
├─ 协调器4G上云/                           # STM32 + ML307R 网关工程
7
│  ├─ main.c                              # 网关主流程
8
│  ├─ zigbee.c/.h                         # UART4 接收及协议解析
9
│  ├─ ml307.c/.h                          # ML307R AT 指令通信
10
│  ├─ onenet.c/.h                         # OneNET 接入、上报与属性下发
11
│  ├─ led.c/.h                            # RGB LED 控制
12
│  ├─ buzzer.c/.h                         # 蜂鸣器控制
13
│  └─ app_config.h                        # 应用参数与云平台配置
14
├─ 参考文件/                               # 流程图、硬件资料和调试记录
15
└─ 烧录文件/                               # 最终可烧录 HEX 文件

展开收起

CC2530 的核心业务代码位于：

1
Projects/zstack/Samples/SampleApp/Source/
2
├─ SampleApp.c
3
├─ SampleAppDht11.c/.h
4
├─ SampleAppTerminal.c/.h
5
└─ SampleAppUart.c/.h

编译与烧录#

CC2530#

使用 IAR Embedded Workbench for 8051 打开：

1
Projects/zstack/Samples/SampleApp/CC2530DB/SampleApp.ewp

工程包含终端与协调器 Target，需要分别选择对应目标进行编译和下载。

STM32#

使用 Keil MDK 打开：

1
协调器4G上云/Project.uvprojx

根据自己的 OneNET 产品配置修改 app_config.h，编译后下载到 STM32F103RCT6。

仓库的 烧录文件 目录已经提供三个最终固件：

1
EndDevice_CC2530.hex
2
Coordinator_CC2530.hex
3
Gateway_STM32.hex

推荐烧录顺序：

将 Gateway_STM32.hex 烧录到协调器板上的 STM32；
将 Coordinator_CC2530.hex 烧录到协调器 CC2530；
将 EndDevice_CC2530.hex 烧录到终端 CC2530；
先启动协调器，再启动终端。

调试与验证#

建议按照链路从近到远逐级验证：

观察终端 OLED 是否经历 SEARCHING、JOINING 并最终显示 ZB:ONLINE；
检查终端是否显示合理的温湿度；
查看网关 OLED 的 UART B/E 计数；
确认网关能够显示真实节点地址和传感器数据；
通过 USB1 打开 115200、8N1 串口日志；
检查 [CC2530 RX] 和 [ZIGBEE] 日志；
检查 [ML307 TX]、[ML307 RX] 和 OneNET 的 code:200 回复；
最后在 OneNET 查看设备在线状态、属性更新时间及远程控制结果。

串口诊断信息可以快速定位故障：

现象	可能原因
`B=0`	UART4 未收到数据，应检查固件、PC11/RXD4 信号和 CC2530 运行状态
`B>0`、`E=0`、节点仍为 `----`	串口有数据，但尚未收到完整有效的 `$TH` 帧
`B>0`、`E>0`	帧格式、波特率、接线或校验值不匹配
ZigBee 日志正常但云端不更新	检查 SIM 卡、天线、ML307R 注册状态及 OneNET 鉴权参数

开发过程中遇到的问题#

1. STM32 串口引脚判断错误#

最初将 CC2530 数据接收配置为 PA3/USART2_RX，但开发板原理图中的板内网络 RXD4 实际连接到 PC11/UART4_RX，导致网关一直显示 UART B:0。

修正 UART4 引脚与中断入口后，STM32 才能正确接收协调器数据。这次问题说明，在使用集成开发板时，不能只根据 MCU 的常用串口引脚猜测连接关系，必须以原理图上的网络名和实际走线为准。

2. 中断中执行过多业务导致时序风险#

早期实现如果在串口中断内直接解析协议或处理业务，很容易延长中断占用时间。最终方案让中断仅负责写环形缓冲区，将协议解析放到主循环中，既减少丢字节风险，也便于实现错误恢复。

3. DHT11 时序与 ZigBee 任务冲突#

DHT11 对微秒级时序较敏感，但长时间关闭中断会影响 Z-Stack 的系统节拍和无线任务。最终只在约 4 ms 的关键 40 位读取窗口中进行必要的临界区保护，而 18～20 ms 的启动阶段保持中断开启，在传感器时序与协议栈实时性之间取得平衡。

4. 发送成功不等于云端接收成功#

串口发送完 AT 指令只能说明命令已经交给 4G 模块，不能证明 OneNET 已经接受数据。因此程序将平台返回的 code:200 作为成功依据，并且只在收到成功回复后增加上传计数。

5. 本地告警与云端控制的状态冲突#

如果云端控制直接覆盖本地状态，可能出现云端关闭蜂鸣器后现场高温告警失效的问题。本项目将本地告警与云端请求分别保存，最后合并输出，使远程控制不会破坏基本的安全告警逻辑。

6. 旧版工程与新工具链的兼容问题#

项目还处理了 IAR 10 启动文件虚拟寄存器、Z-Stack Target 内存空间不足、HAL LCD 与终端 P1.7 蜂鸣器引脚冲突，以及自定义 UART 与 Z-Stack HAL UART 对象冲突等问题。这些问题大多不是业务代码错误，而是旧协议栈、编译器版本和硬件复用共同产生的工程兼容问题。

项目亮点#

我认为这个项目最有价值的部分，并不是单独驱动了某一个传感器或模块，而是完成了不同芯片、协议和网络之间的系统集成：

将 DHT11 的单总线时序与 Z-Stack 的事件调度结合；
使用 ZigBee 网络短地址区分终端，为多节点扩展保留基础；
设计带校验、可读且能重新同步的 MCU 间串口协议；
使用环形缓冲区实现中断接收和主循环解析解耦；
将本地采集、现场告警、4G 上云和远程控制组合为闭环；
网络异常时保留本地功能，并实现发布失败后的重连机制；
通过 OLED、串口日志和计数器建立了较完整的可观测性。

可继续改进的方向#

当前系统已经完成核心功能，后续还可以从以下方向继续完善：

将 DHT11 更换为 SHT30、AHT20 等精度更高的传感器；
支持多个终端节点，并在云端按节点地址分别展示数据；
增加终端离线判断、心跳包和数据序号，识别丢包与重复包；
将阈值、采样周期等参数改为云端可配置；
增加 Flash 参数持久化，设备重启后保留云端设置；
对 ZigBee 应用数据增加更强的 CRC 或消息认证；
将同步等待式 AT 通信改为完全非阻塞状态机；
增加看门狗、断网缓存和网络恢复后的历史数据补传；
对云平台密钥进行安全存储，避免将真实凭据写入公开源码。

总结#

本项目搭建了一套完整的 ZigBee—4G 无线温湿度监测系统。终端负责采集，ZigBee 负责局域无线传输，STM32 负责网关控制，ML307R 负责广域联网，OneNET 负责云端展示和远程控制。

在实现过程中，我不仅完成了 DHT11、OLED、串口和 4G 模块等外设驱动，更重要的是实践了事件驱动、通信协议设计、中断与缓冲区、网络状态管理、故障诊断以及多模块联调。相比单一的传感器实验，这个项目更接近一个小型但完整的物联网产品原型。

发布前注意事项#

如果要将源码同步到公开仓库，请务必先处理以下内容：

删除或替换 app_config.h 中真实的 OneNET 产品 ID、设备 ID、Access Key 和 Token；
不要在博客截图、串口日志或示例命令中暴露设备鉴权信息；
建议提供一个 app_config.example.h 示例文件，并通过 .gitignore 忽略真实配置；
检查历史提交中是否曾经保存密钥；若已经公开，应立即在平台侧轮换密钥；
博客中的项目效果图可以使用设备实拍、终端 OLED、网关 OLED、串口日志和 OneNET 属性页面组成。

基于 Qt+OpenCV 人脸识别考勤系统

Fri, 04 Sep 2026 10:00:00 GMT

OpenCV-Qt-FaceAttendance 工程阅读与代码详解#

1. 项目定位#

这是一个“摄像头客户端 + 人脸识别服务端”的 Qt Widgets 桌面考勤系统。客户端负责采集视频、检测人脸、压缩图片和展示结果；服务端负责接收图片、调用 SeetaFace 识别、查询 SQLite 员工资料、写入考勤记录并返回 JSON。

本文不讨论简历包装，而是沿着真实代码说明工程如何启动、一帧图像如何流转、各模块为何这样划分，以及当前实现有哪些边界。项目不是前后端 HTTP 系统，而是基于 TCP 的本地客户端/服务端程序。

核心概念：OpenCV 负责摄像头、图像处理和 JPEG 编解码，不负责网络通信；Qt Network 负责 TCP 收发；QDataStream 负责把长度字段和字节数组序列化到 TCP 字节流。JPEG 是标准格式，“长度 + JPEG 数据”是本工程约定的应用层封装。

2. 技术栈#

C++11
Qt Widgets：.ui 界面、QMainWindow、信号槽、QTimer/QDataStream
OpenCV 4.x：VideoCapture、灰度转换、Haar Cascade、JPEG 编解码
SeetaFace 6：人脸检测、关键点定位、人脸注册和特征库查询
Qt Network：QTcpSocket、QTcpServer
Qt SQL + SQLite：员工表、考勤表和人脸 ID 映射
qmake：两个工程分别由 .pro 文件构建

3. 目录与职责#

1
OpenCV-Qt-FaceAttendance/
2
├─ FaceAttendanceClient/       # 客户端：摄像头和结果展示
3
│  ├─ faceattendance.cpp/.h
4
│  ├─ faceattendance.ui
5
│  └─ FaceAttendence.pro
6
├─ FaceAttendanceServer/       # 服务端：识别、数据库和管理窗口
7
│  ├─ attendancewin.cpp/.h     # TCP 服务和考勤主流程
8
│  ├─ qfaceobject.cpp/.h       # SeetaFace 封装
9
│  ├─ registerwin.cpp/.h       # 人员注册
10
│  ├─ selectwin.cpp/.h         # 员工/考勤查询
11
│  └─ FaceAttendaceServer.pro
12
├─ SeetaFace/                  # 仓库内附带的头文件、库和模型目录
13
└─ opencv452/                  # 仓库内附带的 OpenCV 开发文件

建议阅读顺序：FaceAttendanceClient/faceattendance.cpp -> FaceAttendanceServer/attendancewin.cpp -> qfaceobject.cpp -> registerwin.cpp -> main.cpp。

4. 总体架构#

1
摄像头
2
  ↓
3
客户端 FaceAttendance::timerEvent()
4
  ├─ OpenCV 采集帧
5
  ├─ Haar Cascade 检测第一张人脸
6
  ├─ Mat 人脸区域编码为 JPEG
7
  └─ QDataStream 写入 [长度][JPEG]，TCP 发给 9999 端口
8
          ↓
9
服务端 AttendanceWin::read_data()
10
  ├─ 按长度处理 TCP 半包
11
  ├─ JPEG 解码为 cv::Mat
12
  └─ queued signal 投递到 QFaceObject 工作线程
13
          ↓
14
QFaceObject::face_query()
15
  └─ SeetaFace Query -> faceId/相似度
16
          ↓
17
AttendanceWin::recv_faceid()
18
  ├─ faceId 查询 employee 表
19
  ├─ 插入 attendance 表
20
  └─ JSON 返回客户端
21
          ↓
22
客户端 recv_data() 更新姓名、工号、部门、时间

展开收起

5. 一次完整打卡的数据流#

把工程串起来理解，比逐个函数孤立阅读更有效。一次打卡会经历以下过程：

1
摄像头
2
  │ BGR 视频帧
3
  ▼
4
FaceAttendance::timerEvent()
5
  │ 灰度化、Haar 检测、截取第一张人脸 ROI
6
  │ OpenCV imencode() 生成 JPEG 字节
7
  ▼
8
QDataStream + QTcpSocket
9
  │ [quint64 长度][QByteArray/JPEG]
10
  ▼
11
AttendanceWin::read_data()
12
  │ 等待完整数据、QPixmap 显示、OpenCV imdecode()
13
  ▼
14
query(cv::Mat&) 信号
15
  │ 跨线程排队调用
16
  ▼
17
QFaceObject::face_query()
18
  │ SeetaFace Query -> faceId + similarity
19
  ▼
20
send_faceid(int64_t) 信号
21
  │ 回到 AttendanceWin 所在线程
22
  ▼
23
AttendanceWin::recv_faceid()
24
  │ employee 查询 -> attendance 插入 -> JSON 回包
25
  ▼
26
FaceAttendance::recv_data()
27
  └─ 更新姓名、工号、部门、时间和认证状态

展开收起

这个流程中存在三种不同的数据身份：

数据	含义	存储位置
JPEG 字节	某一时刻采集的人脸图片	只在网络传输过程中短暂存在
`faceId`	SeetaFace 特征库中某个人脸的编号	`face.db` 与 `employee.faceId`
`employeeId`	业务系统中的员工编号	SQLite `server.db`

faceId 不是员工号。识别算法只返回 faceId，服务端必须再查询 employee 表，才能得到业务身份。

6. 客户端代码深读#

6.1 对象和事件来源#

客户端的核心成员如下：

1
cv::VideoCapture cap;       // 摄像头
2
cv::CascadeClassifier cascade; // Haar 人脸检测器
3
QTcpSocket msocket;         // 与识别服务端通信
4
QTimer mtimer;              // 连接和断线重连
5
int send_flag = -1;         // 控制同一张脸的发送频率

main.cpp 创建 QApplication 和 FaceAttendance 后进入 a.exec()。此后程序不再靠手写循环运行，而由 Qt 事件循环分发定时器、Socket 和界面事件。

构造函数中的 startTimer(100) 使用的是 QObject 的基础定时器，所以超时后进入重写的 timerEvent()；mtimer 则是一个独立的 QTimer，通过 timeout 信号发起连接。两者用途不同。

6.2 摄像头采集与 Haar 检测#

每次 timerEvent() 先执行：

1
cv::Mat srcImage;
2
if (cap.grab()) {
3
    cap.read(srcImage);
4
}
5
if (srcImage.data == nullptr) return;

grab() 推进视频流，read() 取出并解码当前帧。随后将 BGR 图像转为灰度图，再使用 detectMultiScale() 得到人脸矩形列表。灰度化可以减少输入通道数，符合 Haar 分类器的工作方式。

当前实现只处理 faceRects.at(0)，所以画面中有多张脸时只识别检测列表中的第一张。列表顺序不保证等同于“离摄像头最近”或“面积最大”；若需要明确策略，应按矩形面积或中心距离排序。

6.3 ROI 的内存关系#

1
cv::Mat faceImage = srcImage(rect);

这行通常创建的是 ROI 视图，faceImage 与 srcImage 共享底层像素内存，而不是立即复制整块数据。当前函数紧接着调用 imencode()，在 srcImage 仍有效时完成编码，所以可以工作。如果要把 ROI 保存到异步队列，应使用 faceImage.clone() 获得独立数据。

6.4 JPEG 编码与 TCP 封装#

1
std::vector<uchar> buf;
2
cv::imencode(".jpg", faceImage, buf);
3
QByteArray byte(reinterpret_cast<const char *>(buf.data()), buf.size());
4

5
QByteArray sendData;
6
QDataStream stream(&sendData, QIODevice::WriteOnly);
7
stream.setVersion(QDataStream::Qt_5_14);
8
quint64 bytesize = byte.size();
9
stream << bytesize << byte;
10
msocket.write(sendData);

这里分三层理解：

imencode() 把像素矩阵编码为标准 JPEG。
QDataStream 把 quint64 和 QByteArray 按 Qt 的序列化规则写入 sendData。
QTcpSocket::write() 把 sendData 交给 Socket 发送缓冲区。

write() 成功只代表数据被接受进 Qt/操作系统缓冲区，不代表服务端已经完成接收或识别。若要确认发送进度，可以监听 bytesWritten；若要确认业务完成，则必须等待服务端回包。

6.5 `send_flag` 状态变化#

send_flag 是一个简易的抗抖机制：

1
没有检测到人脸 -> send_flag = 0
2
连续检测到人脸 -> 0, 1, 2, 3...
3
send_flag > 2  -> 发送一次，然后设置为 -2
4
人脸继续存在   -> 保持 -2，不再发送
5
人脸离开       -> 重置为 0

发送后设置为 -2，后续帧不会再进入 send_flag >= 0 分支，因此同一张脸会保持“不再发送”状态，直到检测不到人脸时重置为 0。它是一种简单的抗抖和防重复打卡策略，不是带时间窗口的通用限流器。

6.6 BGR/RGB 与图像生命周期#

OpenCV 彩色图默认是 BGR，Qt 的 QImage::Format_RGB888 需要 RGB，因此显示前必须交换通道。QImage 构造函数此处引用 cv::Mat 的现有内存，没有深拷贝；当前代码马上用 QPixmap::fromImage() 生成用于控件显示的对象，没有把临时 QImage 保存到函数外。

如果以后将 QImage 缓存为成员变量，应调用 copy() 或确保对应 cv::Mat 一直有效，否则可能访问已经释放或被下一帧覆盖的内存。

6.7 连接和断线重连#

客户端启动后每 5 秒调用一次：

1
msocket.connectToHost(QHostAddress::LocalHost, 9999);

连接成功后停止重连定时器；断开时以 3 秒间隔重新启动。QHostAddress::LocalHost 对应本机回环地址，因此当前配置只能连接本机服务端。若服务端在另一台设备上，需要把地址改为配置项。

6.8 JSON 结果接收#

recv_data() 使用 readAll() 读取当前已经到达的字节，并调用 QJsonDocument::fromJson()。识别成功时更新控件，姓名为空时隐藏成功提示。

这里没有为 JSON 设置消息边界。TCP 可能把一条 JSON 分成多次到达，也可能把多条 JSON 合并到一次 readyRead 中。因此正式实现应该保留接收缓冲区，并给 JSON 增加长度字段或换行分隔符。

7. 服务端网络代码深读#

7.1 监听和连接对象#

AttendanceWin 构造时调用：

1
mserver.listen(QHostAddress::Any, 9999);

Any 表示监听本机所有网卡地址。收到 newConnection 后，nextPendingConnection() 返回代表该客户端的 QTcpSocket，其 readyRead 信号连接到 read_data()。

当前窗口只有一个 QTcpSocket *msocket 和一个 quint64 bsize。后连接的客户端会覆盖 msocket，不同连接也会共享 bsize，因此代码实际适用于一个考勤客户端，并不具备完整的多客户端并发管理能力。

7.2 为什么要有长度字段#

TCP 是有序字节流，不保留应用层的消息边界。客户端一次 write() 的内容，服务端可能分多次收到；客户端连续多次 write()，服务端也可能一次收到多条消息。

长度字段的作用是告诉接收端：“下一段有效载荷应有多少字节”。服务端先读取 bsize，如果剩余字节不足就返回，等待下一次 readyRead。这处理了单个图片分段到达的情况。

7.3 `QByteArray` 序列化细节#

代码使用 stream << bytesize << byte，接收端使用 stream >> bsize 和 stream >> data。QDataStream 在序列化 QByteArray 时本身也会写入数组长度，因此流中并非简单的“8 字节长度后紧跟裸 JPEG”，而是 Qt 序列化格式：外层手写的 quint64 后还有 QByteArray 自己的长度信息。

由于两端都设置 QDataStream::Qt_5_14 并使用对称的 <</>>，它们能够正确解析。但若以后使用非 Qt 客户端，就必须明确字节序和 QByteArray 序列化规则，或者改成手工写入固定头部与裸 payload。

7.4 当前半包处理的边界#

现有逻辑表达了正确方向，但还不是通用解析器：

sizeof(bsize) 只检查外层长度字段，不代表后面的 QByteArray 序列化头已经完整；
bytesAvailable() >= bsize 没有把 QByteArray 自身的长度前缀计算在内；
一次到达多个完整包时没有 while 循环继续解析；
没有限制 bsize 最大值，错误长度可能造成异常资源消耗；
Socket 断开后没有清理残留接收状态。

更稳妥的实现是把所有新字节追加到 receiveBuffer，用显式固定长度包头解析，只有当包头和 payload 都完整时才取出一包，并循环处理缓冲区中的后续完整包。

7.5 JPEG 解码#

收到完整 QByteArray 后，代码一方面使用 QPixmap::loadFromData() 在服务端界面显示图片，另一方面转换为 std::vector<uchar>，再调用：

1
cv::imdecode(buf, cv::IMREAD_COLOR);

输出是 BGR cv::Mat。若 JPEG 损坏，faceImage.empty() 为真；当前代码只打印错误，仍然发出识别信号，合理的异常路径应该在此直接返回并向客户端发送错误结果。

8. SeetaFace 模块深读#

8.1 三个模型的作用#

模型文件	作用
`fd_2_00.dat`	找出图像中的人脸区域
`pd_2_00_pts5.dat`	定位眼睛、鼻子、嘴角等 5 个关键点
`fr_2_10.dat`	提取人脸特征并进行相似度检索

QFaceObject 用静态 FaceEngine *fengineptr 保证进程中共享同一引擎实例。首次构造时加载模型，并调用 initializeDatabase() 加载或创建 face.db。

8.2 `face.db` 和 `server.db` 的区别#

1
face.db
2
  SeetaFace 自己保存的人脸特征库
3
  保存特征和算法生成的 faceId
4

5
server.db
6
  SQLite 业务数据库
7
  保存员工资料、faceId 映射和考勤记录

删除 face.db 会丢失人脸特征；只保留 server.db 时，员工资料还在，但识别引擎无法找到对应特征。反过来，只保留 face.db 时算法可能返回 faceId，但服务端查不到员工姓名。两个数据库必须保持一致。

8.3 注册流程#

face_register() 依次完成：

检查输入图像非空。
将 cv::Mat 的数据指针、宽、高、通道数填入 SeetaImageData。
调用 DetectFaces()，没有人脸就返回 -1。
先调用 Query()，相似度大于 0.7 时认为已经注册。
调用 Register() 获取新 faceId。
调用 Save("./face.db") 持久化特征库。

之后 RegisterWin 才将个人资料和这个 faceId 写入 SQLite。由于这两步不在同一个事务中，存在特征注册成功但业务数据插入失败的可能，此时 face.db 中会出现没有对应员工记录的孤立特征。

8.4 查询流程和阈值#

face_query() 调用 Query() 得到候选 faceId 与 similarity。信号中使用 similarity > 0.4 ? faceid : -1，低于阈值按陌生人处理。

注册去重阈值 0.7 和识别阈值 0.4 用途不同：前者避免重复录入，后者决定一次识别是否可信。它们是工程中的经验值，不应理解为通用标准。部署时需要根据摄像头、光照、人员规模以及误识率/拒识率要求重新测试。

9. Qt 多线程模型#

9.1 当前线程关系#

1
服务端 GUI 线程
2
  QTcpServer/QTcpSocket
3
  JPEG 解码与界面更新
4
  SQLite 查询和写入
5
       │ query(cv::Mat&) 信号
6
       ▼
7
识别工作线程
8
  QFaceObject::face_query()
9
  SeetaFace::Query()
10
       │ send_faceid(int64_t) 信号
11
       ▼
12
服务端 GUI 线程
13
  AttendanceWin::recv_faceid()

fobject.moveToThread(thread) 改变 QFaceObject 的线程归属。发送者和接收者位于不同线程时，Qt 的自动连接会使用队列方式：信号参数进入目标线程事件队列，槽函数稍后在目标线程执行。

9.2 元类型注册#

main.cpp 调用：

1
qRegisterMetaType<cv::Mat>("cv::Mat&");
2
qRegisterMetaType<int64_t>("int64_t");

Qt 的队列连接需要知道如何复制信号参数，所以自定义或非 Qt 内建类型需要注册。cv::Mat 本身采用引用计数，普通复制通常是浅拷贝；如果发送后源数据可能被改写，跨线程前应 clone()。

9.3 为什么识别放到工作线程#

SeetaFace 推理可能耗时。如果直接在 readyRead 槽中识别，GUI 线程会停止处理绘制、输入和后续网络事件。移入工作线程后，界面仍可响应，Socket 事件也能继续分发。

9.4 生命周期问题#

当前 QThread *thread 是构造函数中的局部指针，没有保存为成员，也没有在窗口退出时执行 quit() 和 wait()；QFaceObject 又是 AttendanceWin 的成员对象。关闭程序时可能出现“线程仍在运行，对象已经析构”的问题。

更标准的写法是让窗口保存线程指针，连接 thread->finished 与清理逻辑，并在析构前按顺序停止接收新任务、quit()、wait()。共享的静态 FaceEngine 也需要明确释放者并确认注册和查询不会跨线程并发访问。

10. 数据库和管理功能#

10.1 数据表#

服务端启动时创建：

1
CREATE TABLE IF NOT EXISTS employee(
2
    employeeId INTEGER PRIMARY KEY AUTOINCREMENT,
3
    name VARCHAR(256),
4
    sex VARCHAR(32),
5
    birthday TEXT,
6
    address TEXT,
7
    phone TEXT,
8
    faceId INTEGER UNIQUE,
9
    headfile TEXT
10
);
11

12
CREATE TABLE IF NOT EXISTS attendance(
13
    attendanceId INTEGER PRIMARY KEY AUTOINCREMENT,
14
    employeeId INTEGER,
15
    attendanceTime TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
16
);

展开收起

employee.faceId 唯一，防止一个算法 ID 关联多名员工。attendance.employeeId 当前没有外键，数据库不会自动校验员工是否存在，也不会级联处理员工删除。

10.2 注册窗口#

注册窗口支持选择图片和摄像头拍照。提交时先完成人脸特征注册，再用 QSqlTableModel 构造员工记录，调用 insertRecord() 和 submitAll() 写入数据库。

头像保存到 ./data/，文件名使用姓名的 Base64 字符串。它能降低中文文件名带来的路径兼容问题，但同名员工可能覆盖同一文件；更可靠的方式是使用员工编号或 UUID。

10.3 识别、回包和考勤落库#

recv_faceid() 用绑定参数查询：

1
SELECT employeeId, name FROM employee WHERE faceId = :faceId;

找到员工后，服务端构造包含员工号、姓名、部门和时间的 JSON，写回客户端，再向 attendance 插入员工号。当前部门值是硬编码，不来自数据表；时间由服务端本机生成。

当前实现没有上下班规则、时间窗口或去重约束。因此只要客户端再次发送并识别成功，就会新增考勤记录。

10.4 查询窗口#

SelectWin 根据单选按钮选择 employee 或 attendance 表，再用 QSqlTableModel::select() 加载到 QTableView。这展示了 Qt SQL 的 Model/View 用法，但没有条件筛选、分页、排序规则或关联员工姓名。

11. 构建和运行#

11.1 两个独立工程#

客户端和服务端分别由 FaceAttendence.pro 与 FaceAttendaceServer.pro 构建。客户端需要 Qt core/gui/widgets/network；服务端还需要 sql，两者都链接 OpenCV 和 SeetaFace。

建议运行顺序：

检查 Qt SQLite 驱动、OpenCV DLL、SeetaFace DLL 和模型文件。
启动服务端，确认 server.db 打开且 9999 端口监听成功。
在服务端注册窗口录入至少一个人脸与员工资料。
启动客户端，确认摄像头画面和 TCP 连接日志。
面向摄像头，依次观察检测、发送、服务端识别、数据库写入和客户端回显。

11.2 当前路径依赖#

源码和 .pro 文件包含 D:\FaceRecognitionAttendanceSystem\... 形式的绝对路径。若工程位于其他目录，需要同步修改 OpenCV、SeetaFace 和模型路径。更好的做法是使用 qmake 变量、相对目录或配置文件，并用 QCoreApplication::applicationDirPath() 定位运行资源。

11.3 Linux 移植不是直接重新编译#

当前依赖目录含 MinGW 库和 Windows DLL，不能直接用于 Linux。移植时需要 Linux 版 OpenCV/SeetaFace 动态库，修改 .pro 的头文件与链接目录，处理 .so 搜索路径、摄像头设备权限、Qt 平台插件以及模型资源路径。

12. 代码中的关键限制与改造思路#

12.1 `server.db` 的创建判断#

服务端 main.cpp 用 QDir::exists("./server.db") 和 mkdir("./server.db") 处理数据库路径，但 server.db 应是文件而不是目录。SQLite 在文件不存在时可以自动创建；这里应直接 setDatabaseName() 后 open()，或用 QFile::exists() 判断。

12.2 多客户端会话#

要支持多个终端，建议为每个连接创建独立会话对象，至少保存：

1
QTcpSocket *socket
2
QByteArray receiveBuffer
3
quint64 expectedPayloadSize
4
ParseState state

Socket 断开时销毁对应会话，不让不同客户端共享 bsize。

12.3 统一消息格式#

图片请求和 JSON 响应应使用同一种包头，例如：

1
| magic | version | messageType | payloadLength | payload |

messageType 区分图像、识别结果和错误；payloadLength 必须设置合理上限；解析器将新字节追加到缓冲区，并循环取出所有完整消息。

12.4 业务一致性#

人脸特征库与 SQLite 是两个存储系统，无法直接使用同一个数据库事务。注册时需要补偿逻辑：如果 SQLite 插入失败，应删除刚注册的特征或记录待清理状态。删除员工时也应同步删除特征和头像。

12.5 错误处理#

当前多个操作只打印日志，生产代码应向上返回明确错误，包括摄像头打不开、Haar/SeetaFace 模型加载失败、JPEG 编解码失败、Socket 写入失败、数据库提交失败和特征库保存失败。

13. 建议的调试路径#

遇到“没有识别结果”时，不要直接怀疑模型，应顺着数据链逐段确认：

采集层： cap.isOpened() 是否为真，帧尺寸和 empty() 是否正常。
检测层： Haar 文件是否加载成功，faceRects.size() 是否大于 0。
编码层： imencode() 是否成功，JPEG 字节数是否合理。
连接层： Socket 是否进入 ConnectedState，服务端是否收到 newConnection。
拆包层： bsize 与 bytesAvailable() 是否符合预期。
解码层： imdecode() 后的 cv::Mat 是否为空。
识别层： 模型和 face.db 是否加载成功，相似度是多少。
映射层： 返回的 faceId 是否存在于 employee 表。
数据层： SQL 是否执行成功，lastError() 输出什么。
回包层： JSON 是否完整到达客户端并成功解析。

14. 工程理解总结#

这个工程的核心不是单独某个人脸识别 API，而是把多个子系统串成一条完整链路：

1
Qt 事件循环
2
  + OpenCV 摄像头与图像处理
3
  + Qt TCP 字节流通信
4
  + SeetaFace 特征库检索
5
  + Qt 跨线程信号槽
6
  + SQLite 业务数据持久化

阅读时应始终区分四个边界：OpenCV 与 Qt 图像对象的内存边界、JPEG 编码与 TCP 封包的协议边界、GUI 线程与识别线程的执行边界，以及 SeetaFace faceId 与业务 employeeId 的数据边界。把这四处理解清楚，工程的主要结构就清楚了。

平衡球 Linux Qt 上位机：实现与架构

Thu, 13 Aug 2026 10:00:00 GMT

本文档的目标不是只告诉你“如何运行”，而是带你从入口、协议、 Linux I/O、线程通信一直读到 Qt 界面。读完后，你应该能自己说清数据从 GD32 到曲线的完整路径，也能够继续修改代码。

上位机连接 PTY 模拟器后的运行界面

1. 这个升级项目解决了什么问题#

原工程的 GD32F407 负责采集小球位置、运行 FreeRTOS 任务、执行 PID 计算并控制舵机。Linux 端不代替 MCU 的实时控制环，而是承担上位机职责：

从串口持续接收 B0 位置帧和 B1 PID 帧。
以曲线和数值展示当前位置、目标位置和 PID 参数。
下发 F0 目标位置命令和 E0 PID 参数命令。
将运行数据同时记录为 CSV 并上传到虚拟机 192.168.28.128 上的 MySQL。
使用 QSqlTableModel 在界面中查询和刷新历史数据。
在没有开发板时，通过 PTY 伪串口模拟真实设备。

这个边界很重要：PID 仍然在 MCU 上执行。Linux 调度延迟不确定，串口也有传输延迟，如果把 10 ms 或 50 ms 控制环移到普通 Linux 用户态，控制周期抖动会明显变大。上位机适合做人机交互、数据管理和参数配置，MCU 适合做硬实时控制。

2. 开发和运行环境#

当前工程已在以下环境实际编译和运行：

项目	当前环境
Linux 虚拟机	Ubuntu 24.04.3 x86_64
虚拟机地址	`bob@192.168.28.128`
远端工程	`/home/bob/balance-ball-linux-host/linux-host`
Qt	Qt 6.4.2 Widgets
Qt 用户安装目录	`/home/bob/.local/balance-qt6`
构建工具	CMake + GNU g++ 13
Linux I/O	termios + epoll + eventfd + timerfd
界面线程模型	Qt 主线程 + 一个串口 QThread

Qt 被解包到用户目录，不需要 sudo。tools/install_user_qt6.sh 会下载 Qt Base 的开发文件、运行库和 QPA 图形插件，然后生成 env.sh。

1
linux-host/
2
├── CMakeLists.txt                       # 构建目标和测试入口
3
├── balance-console-screenshot.png      # 真实 PTY 联调截图
4
├── 项目实现与架构阅读指南.md       # 本文档
5
├── src/
6
│   ├── main.cpp                         # Qt 程序入口和命令行参数
7
│   ├── protocol/
8
│   │   ├── protocol_codec.h             # 协议数据结构和公共接口
9
│   │   └── protocol_codec.cpp           # 组帧、拆帧、大小端转换
10
│   ├── io/
11
│   │   ├── serial_worker.h              # 串口工作线程声明
12
│   │   └── serial_worker.cpp            # termios/epoll/eventfd/timerfd
13
│   └── app/
14
│       ├── database_config.h            # MySQL 连接参数与建表 SQL
15
│       ├── main_window.h                # 主窗口状态和接口
16
│       ├── main_window.cpp              # 界面、信号槽、CSV/MySQL 记录
17
│       ├── position_plot.h              # 实时曲线控件声明
18
│       └── position_plot.cpp            # QPainter 自绘曲线
19
├── tests/
20
│   ├── protocol_codec_test.cpp          # 协议单元测试
21
│   ├── database_integration_test.cpp    # 真实 MySQL 端到端测试
22
│   ├── main_window_test.cpp             # 目标/PID 界面语义测试
23
│   └── serial_worker_test.cpp           # 真实 PTY 串口集成测试
24
└── tools/
25
    ├── device_simulator.cpp              # 无板卡设备模拟器
26
    ├── install_user_qt6.sh               # 无 sudo 安装 Qt
27
    ├── run_console.sh                    # 构建并启动上位机
28
    └── run_simulator.sh                  # 构建并启动模拟器

展开收起

这里有一个值得保留的工程边界：protocol 不知道串口，io 不知道界面布局，app 通过已解析数据更新界面。这使协议可以独立测试，也使串口实现之后能够替换成 TCP 而不重写整个界面。

4. 整体架构和线程边界#

B0/B1/F0/E0

bytesReceived 排队信号

enqueueFrame

GD32 / PTY 模拟器

Linux 串口从设备

SerialWorker

termios + epoll

StreamParser

粘包/拆包/校验

MainWindow

Qt 主线程

PositionPlot

CSV 文件

MySQL

balance_ball

QSqlTableModel

历史查询

B0/B1/F0/E0

bytesReceived 排队信号

enqueueFrame

GD32 / PTY 模拟器

Linux 串口从设备

SerialWorker

termios + epoll

StreamParser

粘包/拆包/校验

MainWindow

Qt 主线程

PositionPlot

CSV 文件

MySQL

balance_ball

QSqlTableModel

历史查询

4.1 Qt 主线程负责什么#

创建和绘制所有 QWidget。
响应连接、下发、记录等用户操作。
调用 StreamParser::feed() 解析已收到的字节块。
更新数值和曲线，并将数据写入 CSV/MySQL。
通过 QSqlTableModel 在对话框中展示 MySQL 历史记录。

Qt 规定 QWidget 只能在 GUI 主线程操作，所以 SerialWorker 不会直接调用任何界面函数。

4.2 串口工作线程负责什么#

打开和配置串口。
在 epoll_wait() 中等待串口可读、可写、唤醒和定时事件。
将收到的字节以 Qt 信号发给主线程。
将多个下发帧按入队顺序写入串口。
断线后每秒尝试重连，并每秒上报通信统计。

4.3 跨线程通信为什么是安全的#

bytesReceived 等信号以 Qt::QueuedConnection 连接到主窗口。工作线程发出信号时，Qt 只把参数复制到主线程事件队列；真正的界面槽函数会在主线程执行。

主线程调用 enqueueFrame() 时，发送队列受 QMutex 保护。入队后通过 eventfd 唤醒 epoll_wait()。这不依赖 Qt 工作线程的事件循环，因为 SerialWorker::run() 本身就是一个持续运行的 Linux 事件循环。

5. 协议格式：先把“12 字节和 16 字节”说清楚#

5.1 通用帧结构#

1
AA AA CMD LEN PAYLOAD... CHECKSUM BB

字段	长度	含义
帧头	2 字节	固定为 `AA AA`
CMD	1 字节	B0/B1/F0/E0
LEN	1 字节	只表示 PAYLOAD 的字节数
PAYLOAD	LEN 字节	命令数据
CHECKSUM	1 字节	CMD + LEN + PAYLOAD 的 8 位累加和
帧尾	1 字节	固定为 `BB`

MCU 的上报帧之后可能还有 0A 换行字节。它是传输时附加的分隔字节，不在 LEN 中，也不参与校验。解析器会把它当作帧间噪声跳过。

5.2 B0 位置帧逐字节解释#

假设位置是 120 mm，即 0x0078：

1
索引       0   1   2   3   4   5   6        7
2
字节      AA  AA  B0  02  00  78  CHECKSUM BB
3
含义      帧头    命令 长度 高  低  校验     帧尾

所以原 MCU 代码中：

1
frame[4] = cur_pos >> 8;       /* 位置高字节 */
2
frame[5] = cur_pos & 0xFF;     /* 位置低字节 */

是完全对得上的。4 和 5 是数组索引，不是“第 4 个 PID 字节”。 B0 的 payload 只有 2 字节，完整协议帧是 8 字节；如果再附加 0A，串口总共发送 9 字节。

5.3 B1 PID 帧的 12 字节在哪里#

kp、ki、kd 都是 32 位 float：

1
3 个 float × 4 字节 = 12 字节 payload

B1 完整帧的索引如下：

1
索引       0   1   2   3   4..7   8..11  12..15  16       17
2
含义      AA  AA  B1  0C   kp      ki      kd    CHECKSUM  BB
3
长度       2       1   1     4       4       4       1       1

因此：

1
完整 B1 协议帧 = 2 + 1 + 1 + 12 + 1 + 1 = 18 字节
2
如果帧后还发 0A = 19 个串口字节

PID 数据本身仍然只有 12 字节。 你看到索引最大到 15，是因为前面已经有 4 个字节的帧头、命令和长度，不是 PID 变成了 16 字节。

5.4 为什么 B0 是高字节在前，B1 float 却是低字节在前#

这是原嵌入式协议的字段约定，不是 C/C++ 强制规定：

B0/F0 的 16 位位置通过移位显式拆分，协议约定为大端。
B1 是 MCU 内存中的 float 按字节上传，GD32 是小端，所以为小端。
E0 下发 PID 又按原接收协议使用大端 float。

理想的新协议应该统一端序，但上位机首先要兼容已有 MCU 实现。所以代码对每个字段显式使用 qFromLittleEndian 或 qToBigEndian，不直接用结构体 reinterpret_cast。

5.5 本项目的命令表#

CMD	方向	LEN	payload
`B0`	MCU → Linux	2	当前位置，16 位大端
`B1`	MCU → Linux	12	kp/ki/kd，3 个 32 位小端 float
`F0`	Linux → MCU	2	目标位置，16 位大端
`E0`	Linux → MCU	5	1 字节选择器 + 4 字节大端 float

6. 建议的代码阅读顺序#

不要一开始就从 main_window.cpp 第一行读到最后一行。界面代码很长，会掩盖真正的主线。建议分七轮：

读 protocol_codec.h，只记住帧结构、命令字和公共接口。
读 protocol_codec_test.cpp，用具体字节理解协议预期行为。
读 protocol_codec.cpp，重点看 StreamParser::feed()。
读 serial_worker.h 中的信号、队列和原子变量，再读 run()。
读 serial_worker_test.cpp，看测试怎样在 PTY 两端扮演 Linux 和 MCU。
读 MainWindow::onWorkerBytes() 和两个 send...()，先跳过 setupUi()。
最后读 setupUi()、PositionPlot::paintEvent() 和模拟器。

每读完一轮，都尝试回答：“这个模块接收什么，输出什么，它在哪个线程运行？”如果这三点能答清楚，就不会在细节中迷路。

7. `protocol_codec` 逐函数讲解#

7.1 `byteAt()`#

QByteArray::at() 返回 char，而 char 在某些编译器上是有符号的。0xAA 可能被解释为负数。byteAt() 统一转换为 quint8，避免协议比较时出现符号扩展。

7.2 `floatFromLittleEndian()`#

先把 4 字节按小端解码为 quint32 位模式。
再用 std::memcpy() 把相同位模式复制到 float。

不用 reinterpret_cast<float *> 的原因是它可能同时触发未对齐访问和 C++ 严格别名问题。memcpy 是这种位级转换的稳妥写法。

7.3 `floatToBigEndian()`#

过程与上面相反：先拿到 float 的 32 位模式，再用 qToBigEndian() 存入 4 字节数组。它用于 E0 PID 参数下发。

7.4 `StreamParser::feed()`#

这是协议层最重要的函数。串口和 TCP 都是字节流，一次 read() 不会保证恰好返回一帧。可能发生：

半包：一帧被分成多次接收。
粘包：一次接收多帧。
粘包 + 半包：前面有完整帧，最后只有下一帧的一部分。
噪声：帧头之前有 0A、无效字节或损坏帧。

feed() 的处理顺序是：

1
追加新字节
2
  ↓
3
查找 AA AA
4
  ↓
5
不足 4 字节？ 保留，等下次
6
  ↓
7
读 LEN，如果 > 64 则拒绝并重新寻找帧头
8
  ↓
9
整帧还没到？ 保留，等下次
10
  ↓
11
检查 CHECKSUM 和 BB
12
  ↓
13
生成 Frame，从缓冲区删除该帧，继续解析后续数据

如果找不到完整 AA AA，但缓冲区最后一字节是 AA，它会保留这一字节。因为它可能是下一次数据中帧头的第一个 AA。

LEN 上限 64 是内存和异常流量保护。如果上位机收到 LEN=100，解析器不会等待 100 字节，而是计一次拒绝、移除一个字节，然后继续搜索下一个 AA AA。这避免故意或损坏的长度字节让缓冲区无限增长。

7.5 `checksum8()`#

将 command、payload.size() 和所有 payload 字节累加，只保留低 8 位。它能发现常见传输错误，但不是密码学完整性保护。

7.6 `encodeFrame()`#

按帧头、命令、长度、payload、校验、帧尾的顺序构造通用帧。Linux 下发不额外加 0A，因为帧长已经由 LEN 唯一确定。

7.7 `encodeTargetPosition()`#

把 16 位目标位置拆为高字节和低字节，再构造 F0 帧。测试中 0x1234 的完整帧必须是 AA AA F0 02 12 34 38 BB。

7.8 `encodePidValue()`#

一个 E0 帧只下发一个 PID 参数。payload 是“选择器 + 4 字节大端 float”，选择器 0/1/2 分别表示 Kp/Ki/Kd。所以界面点击“下发 PID”后会连续入队 3 帧，而不是一个包发三个 float。

7.9 `decodePosition()` 和 `decodePidValues()`#

它们首先检查 CMD 和 payload 长度。只有匹配时才返回 std::optional 中的数值，否则返回 std::nullopt。这让调用者必须显式处理“这不是我要的帧”。

7.10 `toHexText()`#

把字节显示为 AA AA F0 ... 格式，只用于通信日志和测试诊断，不参与协议传输。

8. `SerialWorker` 逐函数讲解#

8.1 三个被 epoll 监听的 fd#

fd	事件	用途
`serialFd`	EPOLLIN/EPOLLOUT/ERR/HUP	收发串口数据和检测断线
`localWakeFd`	EPOLLIN	主线程通知“有新发送帧”或“请求退出”
`timerFd`	EPOLLIN	每秒重连和更新统计

epoll 并不只是为了“高并发服务器”。对这个单设备项目，它的价值是把串口、跨线程唤醒和定时器统一到一个不忙等待的事件循环。不需要为了简历故意宣称 “高并发”，应该准确表述为“基于 epoll 的事件驱动非阻塞 I/O”。

8.2 `baudFlag()`#

把界面中的整数波特率映射为 termios 需要的 B115200 等常量。不支持的值返回 0，后续配置会以 EINVAL 失败。

8.3 `addEpollFd()`#

封装 epoll_ctl(EPOLL_CTL_ADD)，将 fd 和关心的事件注册到 epoll 实例。

8.4 `enqueueFrame()`#

空帧直接忽略。
加锁 txMutex_。
把整个 QByteArray 放入 txQueue_。
解锁后调用 wakeLoop()。

“整帧入队”和“只由一个工作线程写 fd”两个条件，保证多个界面操作同时发送时不会把两帧的字节交叉。volatile 不能实现这个保证，因为它不提供互斥、原子性或线程间 happens-before 关系。

8.5 `requestStop()`#

以 release 语义将 stopRequested_ 设为 true，然后写 eventfd。如果只改标志而不唤醒，工作线程可能永远阻塞在 epoll_wait(-1)。

8.6 `run()`#

run() 是整个 I/O 线程的生命周期：

创建 epoll、eventfd 和 timerfd。
设置 timerfd 首次 1 秒后触发，之后每秒触发。
尝试打开串口。
进入 epoll_wait()。
按 fd 类型分发事件。
检查到退出标志后注销串口，关闭所有 fd，发出 finished()。

串口 EPOLLIN 到来后会循环 read()，直到返回 EAGAIN。这是边缘式思路中常见的“一次把已到达数据读干净”，也可减少 epoll 唤醒次数。当前注册使用默认水平触发，即使未一次读完也不会丢数据。

8.7 `openSerial()`#

使用以下标志打开设备：

O_RDWR：同时读写。
O_NOCTTY：不让该串口成为进程的控制终端。
O_NONBLOCK：读写不阻塞工作线程。
O_CLOEXEC：以后如果启动子进程，子进程不继承该 fd。

打开失败不会让线程退出。它会报告“等待设备”，再由 timerfd 每秒重试。这对 USB 转串口拔插很实用。

8.8 `configureSerial()`#

cfmakeraw() 关闭终端的行缓冲、回显和特殊字符处理，让串口成为原始二进制通道。之后配置 8 数据位、1 停止位、无校验、无硬件流控，即 8N1。

VMIN=0 和 VTIME=0 配合 O_NONBLOCK，使没有数据时 read() 立即返回；等待由 epoll 负责，不由 termios 超时负责。

8.9 `collectOutgoingFrames()`#

在互斥锁保护下把队列中的整帧顺序追加到 pending。之后所有实际 write() 都由工作线程完成。

8.10 `flushPending()`#

Linux write() 可能只写出部分字节，所以使用 offset 记住已写位置。如果遇到 EAGAIN，它会给串口加上 EPOLLOUT 关注；内核通知可写时再继续。全部写完后清空 pending、重置偏移，并取消 EPOLLOUT，避免可写事件造成空转。

8.11 `consumeWakeEvent()` 和 `wakeLoop()`#

eventfd 内部是一个 64 位计数器。wakeLoop() 写入 1，consumeWakeEvent() 把已累积的唤醒值读空。多次快速入队可以合并成一次 epoll 处理，不会需要一帧对应一个线程事件。

9. `MainWindow` 逐函数讲解#

9.1 `setupStyle()`#

设置全局 Qt Style Sheet。界面使用浅灰工作区、白色图表、青绿色实时信号、黄色目标线和红色故障状态。风格的目标是高频使用的仪器控制台，不是宣传页。

9.2 `setupUi()`#

界面主体是一个水平 QSplitter：

1
┌─标题与连接工具栏───────────────────────┐
2
│ 左侧：全尺寸位置曲线       │ 右侧：数值/目标/PID/统计 │
3
└─状态栏───────────────────────────────────┘

setupUi() 最后才连接按钮信号和槽。数值控件的变化不会自动下发，必须点击明确的“下发”按钮，避免用户输入过程中反复改变 MCU 参数。通信日志区已删除，左侧空间全部用于位置轨迹。标题只保留“平衡球控制台”。

9.3 `refreshPorts()`#

扫描 /dev/ttyUSB* 和 /dev/ttyACM*。串口下拉框可编辑，因此 PTY 的 /dev/pts/N 可直接输入，不需要把短暂存在的 PTY 枚举到普通硬件串口列表。

9.4 `connectDevice()` 和 `startDemoMode()`#

这两个是命令行自动化入口。--device 会填写串口和波特率后连接； --demo 会立即启动内置数学模型。如果已经有连接，会先停止旧连接。

9.5 `startSerial()`#

从界面取设备路径和波特率。
创建 QThread 和 SerialWorker。
把 worker 移到工作线程。
连接 started/run、数据、状态、错误、统计和 finished 信号。
清空协议解析器的历史半包。
启动线程。

9.6 `stopSerial()`#

先调用 requestStop() 写 eventfd，再请求 QThread 退出并等待最多 3 秒。线程停止后才销毁 worker 和 thread，避免 fd 仍在使用时对象已经被删除。

9.7 `onWorkerBytes()`#

这是“串口字节到界面数值”的桥梁：

累加接收字节数。
如果开启原始帧日志，显示十六进制字节。
把数据交给 parser_.feed()。
对 B0 调用 updateTelemetry()。
对 B1 更新 PID 实时显示；用户正在编辑时不覆盖编辑框。
更新接受帧、拒绝帧和半包缓冲字节数。

解析在主线程是可接受的，因为单帧最长受限且运算量很小。如果以后变成多设备、高帧率或复杂解码，可再把解析移到 worker，对界面只发已解码的结构体。

9.8 `sendTargetPosition()`#

从 spin box 取目标，构造 F0 帧并整帧入队。只有这个函数成功执行后，输入框数值才成为 targetPosition_，并进入曲线和记录。因此只修改输入框而没有点击“下发目标”时，CSV 和 MySQL 仍记录上一个有效目标。

9.9 `sendPidParameters()`#

读取三个 spin box，对 Kp/Ki/Kd 分别构造一个 E0 帧。三帧顺序进入同一发送队列，并由同一 I/O 线程写出。原先 PID 难以修改的原因是 B1 每 100 ms 将 MCU 旧值重新写回 spin box。现在使用 pidEditorDirty_ 区分“用户待下发值”和 “设备实时回报值”，只在用户没有编辑，或 B1 已与下发值一致时同步编辑器。

9.10 `toggleRecording()` 和 `appendRecordLine()`#

开始记录时打开 CSV 文件并写表头：

1
timestamp,current_mm,target_mm,kp,ki,kd

开始记录时同时调用 ensureDatabaseConnection()。MySQL 可用时，每次 B0 更新会向 CSV 和 position_records 各写一行；MySQL 不可用时降级为“仅 CSV”，不中断监控。演示模式中每 25 个 20 ms 周期刷新一次文件缓冲，在性能和异常退出时的数据丢失量之间折中。

9.11 `ensureDatabaseConnection()`#

使用 QMYSQL 连接虚拟机 192.168.28.128:3306，用户名 bob、密码按当前学习环境配置为 已隐藏。连接成功后自动创建 balance_ball 数据库和 position_records 表。函数具有懒连接语义：启动上位机时不强制连 MySQL，只在开始记录或点击查询时连接。

9.12 `insertDatabaseRecord()`#

使用预处理 SQL 和命名绑定参数插入时间、当前位置、有效目标和 PID。不使用字符串拼接数值，避免格式和 SQL 转义问题。写入失败后将数据库标记为不可用，后续仍继续 CSV 记录。

9.13 `showDatabaseRecords()`#

创建历史记录对话框，用 QSqlTableModel 直接绑定 position_records。表格按 ID 倒序显示、禁止界面编辑，并提供刷新按钮重新执行 select()。

9.14 `startDemo()` 和 `updateDemoData()`#

内置演示模式每 20 ms 用 QTimer 更新一次简化二阶模型，可以快速检查界面和 CSV/MySQL，但它不经过串口。需要验证 Linux I/O 时，应该使用 PTY 模拟器。

9.15 `updateTelemetry()`#

统一更新当前位置、有效目标、曲线和 CSV/MySQL。将所有入口汇总到一个函数，可以避免演示数据和串口数据对界面的更新行为不一致。

10. `PositionPlot` 怎样画实时曲线#

10.1 为什么没有使用 Qt Charts#

这个项目只需要一条位置曲线和一条目标线。用 QPainter 自绘可以减少依赖，也能精确控制网格、游标、颜色和时间窗。

10.2 `appendSample()`#

使用 QElapsedTimer 记录单调时间，不受系统时钟调整影响。每个样本保存为 QPointF(秒, 毫米)。只保留可见 12 秒再多 1 秒的数据，防止长时间运行后内存无限增长。

10.3 `paintEvent()`#

每次重绘执行：

清空背景。
预留坐标轴文字边距。
绘制 0~300 mm 水平网格。
绘制最近 12 秒时间网格。
绘制黄色目标虚线。
把样本映射到图表坐标，用 QPainterPath 连成青绿曲线。
在最新位置绘制游标和圆点。

mapPoint() 完成“时间/毫米坐标”到“像素坐标”的线性映射。因为屏幕 y 轴向下增大，而数学图表 y 轴向上增大，所以 y 计算从 plotArea.bottom() 往上减。

11. PTY 设备模拟器的实现#

11.1 PTY 是什么#

PTY（pseudo terminal）是 Linux 内核提供的主从设备对。模拟器持有主端 fd， Qt 上位机像普通串口一样打开 /dev/pts/N 从端。

1
模拟器 write(master)  →  上位机 read(/dev/pts/N)
2
模拟器 read(master)   ←  上位机 write(/dev/pts/N)

因为上位机打开的真是一个 Linux 字符设备，所以 termios、非阻塞 read/write 和 epoll 全部会真实执行。这比把随机数直接塞给界面更接近真实硬件联调。

11.2 `DeviceState`#

保存位置、速度、目标、Kp/Ki/Kd 和模拟时间。它是模拟设备的全部可变状态。

11.3 `encodeFrame()`、`sendPosition()` 和 `sendPid()`#

模拟器故意不链接 Qt 协议库，而是用标准 C++ 独立实现编码。这避免测试两端共享同一个错误实现后仍然看起来“互相匹配”。

B0 每 20 ms 发送一次。
B1 每 100 ms 发送一次。
上报帧后附加换行，模拟 MCU 当前行为。

11.4 `updatePhysics()`#

使用一个带阻尼和正弦扰动的简化二阶模型。它不是精确的球板动力学模型，但可以产生连续、有惯性、能够趋近目标的位置数据，适合验证曲线和命令下发。

11.5 `parseIncoming()` 和 `executeFrame()`#

模拟器也会处理半包、粘包和错误帧。收到 F0 后改变目标；收到 E0 后按选择器改变对应 PID 值，并在终端打印更新结果。

12. 构建、测试和运行#

12.1 登录虚拟机#

Terminal window

1
ssh 192.168.28.128

12.2 首次安装用户目录 Qt#

Terminal window

1
cd /home/bob/balance-ball-linux-host/linux-host
2
bash tools/install_user_qt6.sh
3
source /home/bob/.local/balance-qt6/env.sh

脚本不调用 sudo dpkg -i，而是使用 apt-get download 下载 deb，再用 dpkg-deb -x 解包到 ~/.local/balance-qt6。它会强制下载 Core/Gui/Sql/Widgets 和 libqt6sql6-mysql 驱动，即使这些包在系统 dpkg 中已显示安装。原因是用户目录中的 Qt CMake 配置会按自己的前缀寻找运行库。

12.3 手动构建和测试#

Terminal window

1
source /home/bob/.local/balance-qt6/env.sh
2
cd /home/bob/balance-ball-linux-host/linux-host
3
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
4
cmake --build build -j2
5
ctest --test-dir build --output-on-failure

当前验证结果：

1
protocol_codec_test  Passed
2
sql_driver_test      Passed
3
database_integration_test Passed
4
main_window_test     Passed
5
serial_worker_test   Passed
6
100% tests passed, 0 tests failed

12.4 配置虚拟机本机 MySQL#

上位机使用的连接参数是：

1
host:     192.168.28.128
2
port:     3306
3
user:     bob
4
password: 已隐藏
5
database: balance_ball
6
table:    position_records

这里的主机地址是 Ubuntu 虚拟机的网卡地址。已实际验证 TCP 登录：

Terminal window

1
mysql -h192.168.28.128 -ubob -p -e "SELECT 1;"

服务器返回 MySQL 8.0.46 和 bob@%，该账号具有 CREATE、INSERT、SELECT 等所需权限。程序会自动建库建表，无需手工创建 balance_ball。生产环境不应在源码中保存密码，本项目按当前本地学习环境的明确要求配置。

position_records 表结构：

字段	类型	含义
`id`	BIGINT AUTO_INCREMENT	主键
`recorded_at`	DATETIME(3)	毫秒级记录时间
`current_mm`	DOUBLE	当前位置
`target_mm`	DOUBLE	已下发的有效目标
`kp` / `ki` / `kd`	DOUBLE	设备当前回报 PID

12.5 无串口的内置演示模式#

Terminal window

1
./tools/run_console.sh --demo

这适合检查界面、曲线和 CSV/MySQL，但不检查 termios/epoll。也可以使用命令行直接开始记录：

Terminal window

1
./tools/run_console.sh --demo --record /tmp/balance-demo.csv

--record 调用的是和界面“开始记录”按钮相同的函数，因此可以用于无人值守验收，不是另外伪造的数据库通道。

12.6 使用 PTY 模拟真实串口#

终端 1：

Terminal window

1
cd /home/bob/balance-ball-linux-host/linux-host
2
./tools/run_simulator.sh

输出示例：

1
平衡球设备模拟器已启动
2
Qt 上位机串口请选择：/dev/pts/0

终端 2：

Terminal window

1
cd /home/bob/balance-ball-linux-host/linux-host
2
./tools/run_console.sh --device /dev/pts/0 --baud 115200

/dev/pts/0 每次运行都可能变化，必须使用模拟器当次打印的路径。

在界面中改变目标和 PID 并点击下发后，终端 1 会打印：

1
目标位置更新为 180 mm
2
Kp 更新为 0.2
3
Ki 更新为 0.01
4
Kd 更新为 0.6

12.7 以后连接真实板卡#

把 USB 转串口插入虚拟机，确保不是只映射给 Windows 主机。
用 dmesg 或 ls /dev/ttyUSB* /dev/ttyACM* 确认设备名。
确保用户有权限。常见做法是将用户加入 dialout 组后重新登录。
运行：

Terminal window

1
./tools/run_console.sh --device /dev/ttyUSB0 --baud 115200

13. CMake 构建目标#

目标	类型	用途
`balance_protocol`	静态库	协议编解码，供程序和测试共用
`balance_console`	Qt 可执行程序	主上位机
`protocol_codec_test`	Qt Test	协议单元测试
`sql_driver_test`	Qt Test	验证 QMYSQL 运行时驱动可加载
`database_integration_test`	Qt Test + MySQL	真实建表、写入、查询与清理
`main_window_test`	Qt Test	有效目标和 PID 编辑/下发语义
`serial_worker_test`	Qt Test + PTY	Linux I/O 集成测试，只在 Linux 构建
`balance_device_simulator`	标准 C++ 程序	独立 PTY 设备模拟器

CMAKE_AUTOMOC 会对带 Q_OBJECT 的类自动运行 Qt moc，生成信号槽需要的元对象代码。

14. 测试在验证什么#

14.1 `protocol_codec_test`#

用例	验证内容
`encodesTargetPosition`	F0 大端位置和校验和
`parsesFragmentedPositionFrame`	一帧分三次到达仍只输出一帧
`parsesStickyFramesAndPidValues`	B0+B1 粘包、换行和小端 float
`rejectsCorruptFrameAndResynchronizes`	损坏帧后能找回下一帧
`boundsInvalidPayloadLength`	LEN=255 不会让缓冲无限等待

14.2 `serial_worker_test`#

测试创建真实 PTY 主从对：

SerialWorker 在 QThread 中打开 PTY 从端。
测试从主端写 B0，检查 bytesReceived 收到数据并解出 120 mm。
调用 enqueueFrame() 发 F0，从 PTY 主端读回并逐字节比较。
连续入队 Kp/Ki/Kd 三个 E0 帧，验证字节顺序不交叉。
请求线程退出，验证 eventfd 能唤醒 epoll 且线程在 2 秒内停止。

这个测试覆盖了“能编译”无法覆盖的真实 Linux fd 行为。

14.3 `main_window_test`#

将目标输入从 160 改为 210，不点击下发时有效目标仍是 160。
点击“下发目标”后，有效目标才变为 210。
编辑 Kp/Ki/Kd 后数值保持可写，点击下发后演示控制器采用新参数。

14.4 `database_integration_test`#

使用工程配置的地址和账号真实连接 MySQL。
自动创建 balance_ball 和 position_records。
插入一条 120/160 mm 的测试数据并用 SQL 读回逐字段比较。
使用 QSqlTableModel 过滤并读取该行，覆盖查询对话框的核心路径。
验证完成后删除自己的测试行，不影响正式记录。

15. 常见问题和面试表达#

15.1 既然只有一个平衡球，为什么还用 epoll#

不要回答“因为高并发”。这个项目当前不是高并发。准确回答是：

epoll 用于将串口可读/可写、跨线程 eventfd 唤醒和 timerfd 定时重连统一到一个事件循环，避免忙轮询。如果以后接入 TCP 或多设备，该模型也可扩展，但当前简历不应夸大为高并发系统。

15.2 为什么不在 Qt 主线程里直接 read#

即使 fd 是非阻塞的，持续读写、断线处理和重连仍会占用 GUI 事件循环。独立 I/O 线程可以让绘制和用户操作保持响应，再用排队信号穿过线程边界。

15.3 为什么协议解析不依赖“一次 read 一帧”#

因为串口驱动只保证字节顺序，不保证应用层帧边界。正确解析器必须保留半包、循环处理粘包，并在错误后重新同步帧头。

15.4 多个任务同时发送时怎样防止帧交叉#

上层以完整 QByteArray 入队，队列受互斥锁保护，只有 SerialWorker 一个线程执行底层 write()。部分写使用 offset 继续，完成当前 pending 数据后才清空。

15.5 `volatile` 能不能替代互斥锁#

不能。volatile 主要告诉编译器每次进行实际内存访问，常用于寄存器或中断可见变量。它不保证复合操作原子性，不保护容器内部结构，也不建立 C++ 线程间内存顺序。本项目的停止标志用 std::atomic_bool，队列用 QMutex。

15.6 为什么 PID 周期改变后要重新整定#

离散 PID 中积分项累加频率和微分项的时间尺度都取决于采样周期 dt。如果代码的积分和微分公式没有显式带 dt，把 50 ms 改成 10 ms 后，每秒积分累加次数变成 5 倍，而相邻误差变化量也对应变小。即使公式正确引入 dt，采样、滤波、舍机和被控对象的离散特性也已变化，仍需复核稳定性和响应。

15.7 本项目和 FreeRTOS 上的队列怎样对应#

FreeRTOS Queue 适合在 MCU 任务或 ISR 之间传递固定大小消息，具有阻塞和唤醒语义。 Linux Qt 上位机中使用 QQueue<QByteArray> + QMutex + eventfd，是因为帧长可变，而工作线程已经以 epoll 为唤醒中心。两者解决的都是“消息传递 + 同步”，但应根据平台和事件模型选择，不需强行使用同一实现。

16. 如何把它写进嵌入式 Linux 简历#

项目名称可以写成：

基于 FreeRTOS 与 Linux Qt 的平衡球控制与监控系统

推荐描述：

在 GD32F407 + FreeRTOS 平衡球控制项目上开发 Linux Qt6 上位机，完成位置/PID 实时监控、目标和参数下发、曲线展示与 CSV/MySQL 数据记录，使用 QSqlTableModel 实现历史数据查询。基于 termios 配置 115200 8N1 二进制串口，使用 epoll + eventfd + timerfd 实现非阻塞收发、跨线程唤醒、统计和断线重连；设计支持半包、粘包、错帧重同步和长度上限保护的流式协议解析器。搭建 PTY 伪串口设备模拟器和 Qt Test 自动化测试，在无开发板环境下完成协议与 Linux I/O 双向联调。

面试时应主动说明：当前是单设备，epoll 是事件驱动 I/O 设计，不是为了虚构高并发指标。这种边界意识比简单堆叠“高并发”关键词更有说服力。

17. 后续升级路线#

阶段 1：真实板卡回归#

确认 B0/B1 的实际帧长、换行和 float 端序。
对比 Qt 与原上位机显示值。
测试 USB 串口拔插和自动重连。
确认 MCU 对 F0/E0 的校验和范围保护。

阶段 2：协议健壮性#

增加协议版本、序号和应答帧。
下发命令在超时时重试，但必须设计幂等语义。
将 8 位累加和升级为 CRC16。
统一所有多字节整数和 float 端序。

阶段 3：数据与可观测性#

记录帧序号、延迟、丢帧和重连次数。
增加记录文件分卷和元数据。
对 CSV 增加离线回放功能，用同一曲线控件复现运行过程。

阶段 4：网络化（真有需求时再做）#

在嵌入式 Linux 板上将串口转换为 TCP/WebSocket 服务。
Qt 客户端通过网络连接远端设备。
将运输层接口抽象为 Serial/TCP 两种实现，复用同一协议层。
只在多设备、多用户或远程监控确实存在时，再设计认证、并发和流控。

18. 阅读完成后的自检问题#

B1 中 PID 是 12 字节，为什么完整帧是 18 字节？
如果一次 read() 只返回 AA AA B0，解析器怎样处理？
如果 LEN 是 100，为什么解析器不会继续等待 100 字节？
主线程入队一帧后，正阻塞在 epoll_wait() 的工作线程怎样被唤醒？
为什么串口只在一个线程中执行 write()？
为什么 EPOLLOUT 不能一直注册？
bytesReceived 是在哪个线程发出，onWorkerBytes() 又在哪个线程执行？
内置演示模式和 PTY 模拟器分别能验证什么？
为什么 PID 运算仍然留在 GD32/FreeRTOS 端？
如果以后加 TCP，哪些模块应该复用，哪个模块需要替换？

如果这 10 个问题可以不看代码说清楚，你对这个 Linux 上位机的主体架构就已经真正理解了。

tiny-httpd：从零实现 Linux 静态 HTTP 服务器

Wed, 12 Aug 2026 10:00:00 GMT

1. 项目定位#

tiny-httpd 是一个使用 C 语言独立实现的 Linux 静态 HTTP 服务器。项目面向嵌入式 Linux 用户态开发岗位，重点展示 Linux 系统编程、网络编程、并发控制、守护进程和模块化 C 工程能力。

项目只把 Zaver 等开源服务器作为设计参考，没有复用其源文件。功能范围被有意控制在静态 GET 服务：

支持 HTTP/1.0、HTTP/1.1 和 GET；
解析 Host、Connection、If-Modified-Since；
支持 keep-alive 和空闲超时；
返回 200、304、400、403、404、405、414 等状态；
目录 URI 自动追加 index.html；
根据扩展名设置 MIME 类型；
使用 epoll + EPOLLONESHOT + 固定线程池 处理并发；
使用最小堆组织超时任务；
使用 sendfile 发送静态文件；
阻止 URI 路径逃逸；
默认以双 fork 守护进程运行，并使用 PID 文件锁防止重复启动。

项目不实现 POST、CGI、FastCGI、反向代理、HTTPS、Range、HTTP/2 和动态业务。

2. 工程目录#

1
http_server/
2
├── CMakeLists.txt
3
├── README.md
4
├── 需求.md
5
├── 工程代码详解.md
6
├── config/
7
│   └── server.conf
8
├── include/
9
│   ├── build_features.h
10
│   ├── common.h
11
│   ├── config.h
12
│   ├── daemon.h
13
│   ├── http_protocol.h
14
│   ├── io.h
15
│   ├── list.h
16
│   ├── priority_queue.h
17
│   ├── server.h
18
│   ├── static_file.h
19
│   ├── thread_pool.h
20
│   └── timer.h
21
├── src/
22
│   ├── config.c
23
│   ├── daemon.c
24
│   ├── http_protocol.c
25
│   ├── io.c
26
│   ├── list.c
27
│   ├── main.c
28
│   ├── priority_queue.c
29
│   ├── server.c
30
│   ├── static_file.c
31
│   ├── thread_pool.c
32
│   └── timer.c
33
├── tests/
34
│   ├── CMakeLists.txt
35
│   ├── test_http_protocol.c
36
│   ├── test_list.c
37
│   ├── test_priority_queue.c
38
│   └── test_thread_pool.c
39
└── www/
40
    └── index.html

展开收起

主要模块职责如下：

模块	主要职责
`main`	参数解析和启动流程编排
`config`	配置解析、范围校验、路径绝对化
`daemon`	双 fork、setsid、PID 文件锁和描述符重定向
`server`	Socket、epoll、任务分发和连接生命周期
`http_protocol`	请求行、请求头、HTTP 日期和 MIME 解析
`static_file`	URI 映射、安全校验、响应构造和文件发送
`io`	非阻塞完整写和 sendfile
`thread_pool`	固定工作线程和 FIFO 任务队列
`timer`	线程安全的超时任务管理
`priority_queue`	按到期时间排序的二叉最小堆
`list`	线程池使用的单向链表

3. 总体架构#

服务器由一个事件线程和若干工作线程组成。

默认

-f

监听 fd

客户端 fd

是

否

读取配置

运行模式

双 fork 守护化

前台运行

初始化服务器

监听 Socket

epoll

线程池

定时器最小堆

epoll_wait

accept 新连接

提交线程池任务

read 请求

解析 GET

URI 映射

响应头和 sendfile

keep-alive

重设超时并 rearm

关闭连接

默认

-f

监听 fd

客户端 fd

是

否

读取配置

运行模式

双 fork 守护化

前台运行

初始化服务器

监听 Socket

epoll

线程池

定时器最小堆

epoll_wait

accept 新连接

提交线程池任务

read 请求

解析 GET

URI 映射

响应头和 sendfile

keep-alive

重设超时并 rearm

关闭连接

完整调用链：

1
main
2
├── http_config_load
3
├── http_daemonize                  # -f 前台模式跳过
4
└── http_server_run
5
    ├── install_signal_handlers
6
    ├── http_timer_manager_init
7
    ├── http_thread_pool_init
8
    ├── create_listening_socket
9
    ├── epoll_create1
10
    └── epoll_wait
11
        ├── accept_connections
12
        │   └── register_connection
13
        │       └── connection_schedule_timeout
14
        └── dispatch_connection
15
            └── http_thread_pool_submit
16
                └── handle_connection_task
17
                    ├── read
18
                    ├── http_request_parse
19
                    ├── process_request
20
                    │   ├── http_resolve_static_path
21
                    │   └── http_send_static_response
22
                    │       ├── http_write_all
23
                    │       └── http_send_file
24
                    └── connection_rearm 或 connection_close_locked

展开收起

主线程不解析 HTTP，也不发送文件，只管理事件和超时。工作线程承担可能耗时的请求处理，避免慢客户端阻塞整个事件循环。

4. 启动流程与配置#

4.1 main 函数#

入口位于 src/main.c。程序使用 getopt_long 支持：

参数	含义
`-c FILE`	指定配置文件
`-f`	前台运行，方便调试
`-h`	输出帮助

启动顺序是：解析参数、读取配置、按需守护化、运行服务器、退出时清理 PID 文件。

main 只负责流程编排，不放网络业务逻辑，使入口函数保持短小。

4.2 配置结构#

1
typedef struct http_server_config {
2
    char document_root[PATH_MAX];
3
    char pid_file[PATH_MAX];
4
    int port;
5
    int thread_count;
6
    int idle_timeout_ms;
7
    int listen_backlog;
8
} http_server_config_t;

配置示例：

1
root=../www
2
port=8080
3
threads=4
4
idle_timeout_ms=5000
5
backlog=128
6
pid_file=../tiny_httpd.pid

http_config_load 会：

跳过空行和注释；
分割 key=value；
删除首尾空白；
严格检查整数和范围；
拒绝未知配置项；
验证 root 是有效目录；
将 root 和 PID 文件路径转换成绝对路径。

路径绝对化很重要，因为守护进程会执行 chdir("/")。如果保留相对路径，守护化后就无法找到站点目录。

5. 守护进程实现#

src/daemon.c 使用经典双 fork：

1
原进程
2
└── fork
3
    ├── 父进程退出
4
    └── 子进程
5
        ├── setsid
6
        └── fork
7
            ├── 第一代子进程退出
8
            └── 最终守护进程

第一次 fork 和 setsid 使进程脱离原会话、进程组和控制终端。第二次 fork 使最终进程不再是会话首进程，从而不能重新获得控制终端。

其他守护化操作：

umask(027) 限制新文件权限；
chdir("/") 避免占用启动目录；
标准输入、输出和错误重定向到 /dev/null；
创建 PID 文件并使用 flock(LOCK_EX | LOCK_NB) 加排他锁。

PID 文件描述符在服务运行期间保持打开，否则文件锁会被释放。第二个实例尝试启动时无法获得锁，从而避免重复启动。

6. Socket 和 epoll#

6.1 创建监听 Socket#

create_listening_socket 依次执行：

socket(AF_INET, SOCK_STREAM, 0)；
设置 SO_REUSEADDR；
使用 fcntl 添加 O_NONBLOCK；
使用 fcntl 添加 FD_CLOEXEC；
bind 到配置端口和 INADDR_ANY；
listen 开始监听。

O_NONBLOCK 使系统调用在暂时无法完成时返回 EAGAIN，不会无限阻塞线程。FD_CLOEXEC 防止描述符被以后执行的其他程序意外继承。

6.2 epoll 注册#

监听 fd 使用：

1
listen_event.events = EPOLLIN;
2
listen_event.data.ptr = NULL;

客户端 fd 使用：

1
event.events = EPOLLIN | EPOLLONESHOT | EPOLLRDHUP;
2
event.data.ptr = connection;

项目约定 data.ptr == NULL 表示监听 fd，其他值直接保存连接对象指针，省去额外的 fd 映射表。

6.3 LT 与 ET#

当前客户端事件没有设置 EPOLLET，因此使用水平触发 LT，而不是边缘触发 ET。

选择 LT 的原因：

行为直观，代码容易验证；
数据没有读完时，重新激活后仍可收到通知；
避免 ET 下未读到 EAGAIN 导致通知丢失。

工作线程仍循环读到 EAGAIN，目的是尽量一次取完当前数据、减少事件循环往返，并不代表使用了 ET。

6.4 EPOLLONESHOT#

一次事件触发后，EPOLLONESHOT 会暂时禁用这个 fd，直到调用 EPOLL_CTL_MOD 重新激活。

它防止同一客户端连接被主线程重复提交给多个工作线程：

1
连接可读
2
-> epoll 只报告一次
3
-> 一个工作线程处理
4
-> 处理完成
5
-> keep-alive 时重新激活

因此本项目的线程池并发单位是不同连接，而不是同一连接内的多个线程。

6.5 epoll 与定时器结合#

事件循环先调用 http_timer_next_timeout 获取最近定时任务剩余时间，再把它作为 epoll_wait 的 timeout。

这样没有网络事件时，epoll 会在最近连接超时时自动醒来；没有定时任务时 timeout 为 -1，可以无限等待。不需要额外的定时器线程，也不需要固定间隔轮询。

7. 线程池#

线程池核心结构：

1
typedef struct http_thread_pool {
2
    pthread_t *threads;
3
    int thread_count;
4
    int stopping;
5
    pthread_mutex_t mutex;
6
    pthread_cond_t condition;
7
    http_list_t tasks;
8
} http_thread_pool_t;

任务只保存函数指针和上下文：

1
typedef struct http_task {
2
    void (*function)(void *argument);
3
    void *argument;
4
} http_task_t;

http_thread_pool_submit 在锁内把任务追加到 FIFO 链表，然后通过 pthread_cond_signal 唤醒一个线程。

工作线程等待条件必须写成 while：

1
while (http_list_size(&pool->tasks) == 0 && !pool->stopping) {
2
    pthread_cond_wait(&pool->condition, &pool->mutex);
3
}

原因是条件变量可能虚假唤醒，或者任务已经被另一个线程取走。醒来后必须重新检查条件。

任务出队后先解锁，再执行回调。否则一个线程处理网络请求期间会一直占用队列锁，其他线程无法取任务，线程池将失去并发意义。

销毁时设置 stopping、广播唤醒线程，再 pthread_join 等待已入队任务完成。

8. 连接生命周期#

这是整个项目最关键的部分。

1
typedef struct http_connection {
2
    int fd;
3
    int closed;
4
    uint64_t timer_generation;
5
    atomic_int reference_count;
6
    pthread_mutex_t mutex;
7
    http_server_t *server;
8
    char receive_buffer[HTTP_REQUEST_BUFFER_SIZE];
9
    size_t receive_length;
10
} http_connection_t;

字段	作用
`fd`	客户端 Socket
`closed`	防止重复关闭
`timer_generation`	使旧超时任务失效
`reference_count`	保证对象仍被使用时不释放
`mutex`	保护连接状态和接收缓冲区
`server`	访问共享服务器对象
`receive_buffer`	保存未完全解析的数据
`receive_length`	有效数据长度

8.1 锁与引用计数的区别#

互斥锁解决并发读写状态的问题；
引用计数解决对象何时可以释放的问题。

连接可能同时被基础连接、线程池任务和定时任务引用。仅使用互斥锁不能阻止对象在另一个线程使用时被释放。

connection_retain 原子增加引用，connection_release 原子减少引用。引用数归零时才销毁 mutex 和连接对象。

8.2 关闭连接#

connection_close_locked 在持锁状态下：

检查是否已经关闭；
设置 closed；
增加 generation，使定时任务失效；
从 epoll 删除 fd；
关闭 Socket。

它不会直接释放连接对象。调用者先解锁，再释放基础引用，否则可能释放 mutex 后又执行 unlock，造成 use-after-free。

8.3 工作线程处理连接#

handle_connection_task 的流程：

锁定连接；
循环 read 到 EAGAIN；
调用 http_request_parse；
数据不完整则保留缓冲区；
完整请求调用 process_request；
使用 memmove 删除已经消费的请求；
缓冲区还有完整请求则继续处理；
短连接或错误时关闭；
长连接创建新超时任务，并 rearm EPOLLONESHOT；
释放任务持有的连接引用。

同一次 read 中存在多个顺序请求时，该循环也能逐个处理。

9. HTTP 解析#

解析结果分为：

1
HTTP_PARSE_COMPLETE
2
HTTP_PARSE_INCOMPLETE
3
HTTP_PARSE_BAD_REQUEST
4
HTTP_PARSE_METHOD_NOT_ALLOWED
5
HTTP_PARSE_URI_TOO_LONG

HTTP_PARSE_INCOMPLETE 不是协议错误，表示请求被 TCP 分段，只到达了一部分。服务器保留数据并等待下一次可读事件。

9.1 请求行#

支持的格式：

1
GET /index.html HTTP/1.1

解析器查找两个空格，把请求行分成方法、URI 和版本：

方法必须是 GET，否则返回 405；
URI 不能为空且不能超过固定容量；
版本只接受 HTTP/1.0 或 HTTP/1.1；
HTTP/1.1 默认 keep-alive；
HTTP/1.0 默认关闭。

9.2 请求头#

解析器查找 CRLF，逐行处理请求头，直到遇到空行。

请求头	行为
`Host`	保存值；HTTP/1.1 缺少 Host 返回 400
`Connection`	close 或 keep-alive 覆盖默认值
`If-Modified-Since`	解析 GMT 日期，用于 304

请求头名称不区分大小写。未知请求头被忽略，以兼容浏览器自动携带的其他字段。

9.3 304 缓存#

如果请求携带 If-Modified-Since，且文件修改时间 st_mtime 不晚于请求时间，服务器返回 304，Content-Length 为 0，不发送文件实体。

解析 HTTP 日期使用 strptime，转换 UTC 时间使用 timegm，响应日期通过 gmtime_r + strftime 生成。

10. URI 映射和安全#

http_resolve_static_path 按以下顺序执行：

移除查询串；
解码 %xx；
拒绝控制字符、NUL、反斜杠和编码斜杠；
与站点根目录拼接；
目录目标追加 index.html；
使用 realpath 解析点目录和符号链接；
验证最终路径仍在站点根目录；
使用 stat 确认目标是普通文件。

不能只检查 URI 是否包含 ..，因为还存在百分号编码、符号链接和复杂路径组合。项目以 realpath 的最终结果为准。

根目录若是 /srv/www，只允许：

1
/srv/www
2
/srv/www/index.html
3
/srv/www/assets/app.css

/srv/www-secret/file 虽有相同字符串前缀，但前缀后不是 / 或字符串结尾，因此不会被误判为根目录内部。

11. 响应、MIME 和 sendfile#

正常响应包含状态行、Date、Server、Connection、Content-Type、Content-Length 和 Last-Modified。

字符串使用有容量限制的 snprintf 构造，并检查是否发生截断。

MIME 表支持 HTML、CSS、JavaScript、TXT、JSON、PNG、JPEG、GIF、SVG、ICO 和 PDF。未知扩展名使用 application/octet-stream。

响应头通过 http_write_all 发送，文件实体通过 http_send_file 调用 Linux sendfile。

传统文件发送路径通常是：

1
文件 -> 内核页缓存 -> 用户态缓冲区 -> Socket 内核缓冲区

sendfile 避免应用层自行执行 read + write 和管理文件缓冲区，适合静态文件服务，也有利于资源受限设备减少内存复制。

一次 write 或 sendfile 不保证发完全部数据。两个 I/O 函数都会维护剩余长度，并处理：

EINTR：重试；
EAGAIN：使用 poll(POLLOUT) 等待可写；
部分写：移动游标后继续；
超过 30 秒仍不可写：以 ETIMEDOUT 失败。

12. 定时器和最小堆#

定时器使用 CLOCK_MONOTONIC 计算毫秒时间。它不受手工修改系统时间或 NTP 调整影响，适合计算相对超时。

底层优先队列是动态数组实现的二叉最小堆：

堆顶始终是最早到期任务；
插入通过向上调整恢复堆性质；
删除堆顶通过向下调整恢复堆性质；
查看堆顶为 O(1)；
插入、删除为 O(log n)。

12.1 generation 机制#

每次连接进入新阶段时递增 timer_generation。定时任务保存创建时的 generation，回调执行时只有两者仍相等才关闭连接。

旧任务无需从堆中间查找删除，到期后发现 generation 不匹配便自然失效。代价是旧任务在原到期时间前仍占用少量内存。

12.2 定时任务所有权#

http_timer_schedule_owned 接收执行回调和参数清理回调。任务正常执行、取消或管理器销毁时，参数清理回调都会释放上下文。

连接定时任务借此释放自己持有的连接引用，防止引用计数泄漏。

13. 信号和异常处理#

SIGINT 和 SIGTERM 的处理器只设置 sig_atomic_t 标志。清理资源仍在普通事件循环中执行，因为日志、malloc 和 pthread 锁等操作不是异步信号安全的。

服务器忽略 SIGPIPE。客户端提前断开后，写 Socket 会返回 EPIPE，而不会终止整个服务进程。

关键 errno：

errno	含义与处理
`EINTR`	被信号中断，重试系统调用
`EAGAIN/EWOULDBLOCK`	非阻塞 fd 暂时无法继续，稍后重试
`EPIPE`	对端已断开，关闭当前连接
`ETIMEDOUT`	等待可写超时，终止当前响应

14. 构建与测试#

构建命令：

Terminal window

1
cmake -S . -B build
2
cmake --build build -j4

项目启用：

1
-Wall -Wextra -Wpedantic -Werror

所有警告都按错误处理，可以尽早发现隐式声明、类型错误和未使用变量。

运行测试：

Terminal window

1
ctest --test-dir build --output-on-failure

测试	验证内容
`test_list`	FIFO 顺序、元素数量和空链表
`test_priority_queue`	最小堆按到期时间弹出
`test_thread_pool`	4 个线程完整执行 1000 个任务
`test_http_protocol`	GET、Host、Connection、不完整请求、POST 拒绝

已经完成的集成验证包括 200、304、403、404、405、keep-alive 连接复用、路径逃逸拒绝、守护进程 PID 文件和信号停止清理。

15. 当前限制#

该项目适合学习和小型静态服务，还不是完整的生产服务器：

HTTP 解析器只覆盖当前需要的语法，不是完整 RFC 实现；
工作线程在发送遇到 EAGAIN 时使用 poll 等待，不是完全事件驱动写；
没有活动连接表，退出时部分空闲连接依赖进程结束由内核回收；
定时任务使用 generation 失效，旧任务到期前仍占内存；
没有请求速率限制、最大连接数和单 IP 限制；
没有日志文件及轮转；
没有 TLS、Range 和动态请求；
尚未提供 ARM 交叉编译工具链和开发板实测数据；
尚未使用 wrk/ab 得到可复现的吞吐和延迟结果。

后续可增加连接注册表、完全事件驱动写、sanitizer 检查、ARM 部署、压力测试和 systemd service。

停车场车位与车辆调度系统

Tue, 11 Aug 2026 10:00:00 GMT

1. 课题名称#

停车场车位与车辆调度系统的设计与实现

2. 课题背景#

随着城市机动车数量不断增加，停车场管理问题越来越常见。传统人工管理方式效率较低，容易出现车位分配不合理、车辆等待时间过长、信息记录不完整等问题。为了提高停车场管理效率，有必要设计一个能够完成车辆进出管理、车位分配、等待调度和记录查询的简易系统。

本课题以停车场管理为实际应用场景，使用 C 语言和数据结构基础知识实现一个命令行停车场车位与车辆调度系统。该系统不依赖数据库和 Web 技术，重点体现数组、结构体、队列等知识在实际问题中的应用，适合作为数据结构课程设计题目。

3. 设计目标#

本系统的主要目标如下：

实现车辆进场登记与车位分配
实现停车场满载情况下的车辆排队等待
实现车辆离场处理及费用计算
实现空闲车位释放后的自动调度
实现停车区、等待区和历史记录的查询
通过项目实践加深对数据结构与 C 语言程序设计的理解

4. 需求分析#

4.1 功能需求#

系统应具备以下功能：

车辆进场
车辆离场
查看停车区车辆信息
查看等待队列信息
查看历史记录
查看车位统计信息
退出系统

4.2 业务规则#

停车场车位数量固定
当停车场有空位时，车辆可直接进入并分配车位
当停车场已满时，后续车辆进入等待队列
当有车辆离场时，若等待队列非空，则队头车辆自动进入停车场
停车费用按停车时长计算
车辆信息和历史记录在程序运行期间保存在内存中

4.3 输入输出需求#

输入内容主要包括：

菜单编号
车牌号
进场时间
离场时间

输出内容主要包括：

车位分配结果
等待队列状态
离场车辆费用信息
当前停车场统计信息
历史停车记录

5. 可行性分析#

5.1 技术可行性#

本系统只使用 C 语言完成，所用知识均为课程阶段已学习内容，包括：

结构体
数组
循环队列
函数设计
模块化编程

实现难度适中，技术上完全可行。

5.2 经济可行性#

本系统作为课程设计项目，不需要额外硬件设备或商业软件支持，仅需普通编译环境即可运行，因此成本低。

5.3 操作可行性#

系统采用菜单方式交互，输入输出直观，操作简单，适合演示与测试。

6. 总体设计#

6.1 系统结构#

系统采用模块化设计，主要由以下模块组成：

main.c
parking.c / parking.h
queue.c / queue.h
vehicle.c / vehicle.h
record.c / record.h
utils.c / utils.h

各模块功能如下：

main 模块负责菜单显示和主流程控制
parking 模块负责车位管理和停车区操作
queue 模块负责等待车辆的排队调度
vehicle 模块负责车辆信息初始化与显示
record 模块负责历史记录保存与查看
utils 模块负责时间和费用等通用处理

6.2 系统流程#

系统总体流程如下：

初始化停车区、等待队列和历史记录表
显示主菜单
根据用户输入执行相应功能
若选择退出，则结束程序
否则返回主菜单继续执行

7. 数据结构设计#

7.1 车辆信息结构体#

车辆信息使用 Vehicle 结构体表示，主要字段如下：

plate_number：车牌号
enter_time：进场时间
exit_time：离场时间
duration：停车时长
space_id：车位编号
fee：停车费用

该结构体是系统中最核心的数据对象，用于停车区、等待队列和历史记录之间的数据传递。

7.2 停车区结构#

停车区使用结构体数组实现，每个车位使用 ParkingSpace 结构体表示，包含：

id：车位编号
occupied：是否被占用
vehicle：当前停放车辆信息

整个停车场使用 ParkingLot 结构体表示，包含：

spaces[MAX_SPACES]：车位数组
capacity：停车场容量
occupied_count：已占用车位数

这种设计本质上属于顺序存储结构，便于通过下标直接访问车位信息。

7.3 等待队列结构#

等待车辆使用循环队列实现，其结构为：

data[MAX_WAITING]：等待车辆数组
front：队头下标
rear：队尾下标
size：当前队列长度

队列满足先进先出原则，符合“先到先等、先等先入场”的业务需求。

7.4 历史记录结构#

历史记录使用顺序表形式实现，即使用数组保存所有离场车辆信息，结构中包含：

records[MAX_RECORDS]：历史记录数组
count：当前记录数

这种实现方式简单直观，适合课程设计规模的数据管理。

8. 详细设计#

8.1 主菜单设计#

系统主菜单包括以下选项：

车辆进场
车辆离场
查看停车区车辆
查看等待队列
查看历史记录
查看车位统计
退出系统

程序在 main 函数中通过 do...while 循环持续显示菜单，直到用户输入 0 退出。

8.2 车辆进场设计#

车辆进场处理流程如下：

输入车牌号
输入进场时间
初始化车辆结构体
调用 park_vehicle 判断停车区是否有空位
若有空位则分配车位
若无空位则调用 enqueue_vehicle 加入等待队列

该功能体现了顺序表查找空闲位置和队列入队操作。

8.3 车辆离场设计#

车辆离场处理流程如下：

输入离场车辆车牌号
在停车区查找该车辆
若未找到，则提示错误
若找到，则输入离场时间
计算停车时长
计算停车费用
将离场车辆写入历史记录
释放车位
若等待队列非空，则调度队头车辆进入停车场

该部分是整个系统的核心逻辑，体现了多个数据结构之间的协作。

8.4 停车区查询设计#

停车区查询功能遍历车位数组：

已占用车位显示车牌号
未占用车位显示空闲状态

该功能能够直观反映当前停车场状态。

8.5 等待队列查询设计#

等待队列查询功能从队头开始遍历循环队列，依次输出等待车辆信息，用于显示排队情况。

8.6 历史记录查询设计#

历史记录查询功能遍历历史记录数组，输出每一辆已离场车辆的车牌号、车位号、进场时间、停车时长和费用信息。

8.7 统计功能设计#

系统统计功能输出以下信息：

车位总数
已占用车位数
剩余车位数
等待车辆数

用于反映停车场当前运行情况。

9. 核心算法说明#

9.1 车位分配算法#

系统采用顺序扫描方式分配车位：

从第一个车位开始遍历
查找第一个未被占用的车位
将该车辆分配到该车位
更新车位状态和已占用计数

该算法实现简单，适合小规模停车场系统。

9.2 等待调度算法#

系统采用先进先出调度策略：

当停车场满时，车辆进入等待队列尾部
当车位释放后，从队头取出一辆等待车辆
将其安排进入空闲车位

该算法保证等待顺序公平合理。

9.3 费用计算算法#

系统当前使用简单计费规则：

停车时长为 exit_time - enter_time
每小时收费 5 元
若计算结果小于等于 0，则默认收费 5 元

该算法实现简单，便于验证和演示。后续可以继续扩展为更复杂的收费策略。

10. 主要函数说明#

10.1 `init_parking_lot`#

功能：初始化停车场，包括车位编号、占用状态和容量信息。

10.2 `park_vehicle`#

功能：将车辆停入停车场，若有空位则返回车位号，否则返回失败标志。

10.3 `remove_vehicle`#

功能：根据车牌号将车辆从停车区移除，并返回车辆信息。

10.4 `enqueue_vehicle`#

功能：将车辆加入等待队列。

10.5 `dequeue_vehicle`#

功能：从等待队列取出队头车辆。

10.6 `add_record`#

功能：将离场车辆写入历史记录表。

10.7 `calculate_duration`#

功能：计算停车时长。

10.8 `calculate_fee`#

功能：根据停车时长计算费用。

11. 测试设计#

11.1 测试目标#

验证系统各项基础功能是否能够正确运行，重点检查：

车辆进场功能是否正确
车位分配是否合理
等待队列是否符合先进先出
离场后费用计算是否正确
历史记录是否成功保存

11.2 测试用例#

测试用例 1：车辆正常进场#

输入一辆新车牌号和进场时间
预期结果：车辆进入停车场并获得车位编号

测试用例 2：停车场满后进入等待队列#

连续输入超过车位容量的车辆
预期结果：超出容量的车辆进入等待队列

测试用例 3：车辆正常离场#

输入已在停车场中的车辆车牌号和离场时间
预期结果：车辆成功离场，显示停车时长和费用

测试用例 4：等待车辆自动调度#

在停车场满且等待队列非空时，有车辆离场
预期结果：等待队列中的第一辆车自动进入停车场

测试用例 5：查询功能测试#

分别查看停车区、等待队列、历史记录和统计信息
预期结果：输出内容与当前系统状态一致

12. 运行环境与运行方法#

12.1 运行环境#

操作系统：Linux、macOS 或 Windows
编译器：GCC

12.2 编译命令#

Terminal window

1
gcc main.c parking.c queue.c vehicle.c record.c utils.c -o parking

12.3 运行命令#

Terminal window

1
./parking

13. 系统特点与不足#

13.1 系统特点#

采用 C 语言实现，结构清晰
数据结构应用明确，符合课程设计要求
功能完整，能够完成基本停车场管理流程
模块划分清楚，便于后续维护和扩展

13.2 系统不足#

当前数据只保存在内存中，程序退出后不会自动持久化
时间输入仅按整数小时处理，精度较低
未实现按车牌模糊查询、修改记录等扩展功能
未加入异常输入处理和更复杂的收费模型

14. 改进方向#

后续可以从以下方向继续完善：

增加文件存储功能，实现数据持久化
增加车牌查询和车辆修改功能
优化收费策略
增加不同类型车位管理
增加图形界面或可视化界面

15. 课程设计总结#

通过本次课程设计，完成了一个基于 C 语言和基础数据结构的停车场车位与车辆调度系统。系统实现了车辆进场、离场、等待调度、历史记录查询和车位统计等主要功能，将抽象的数据结构知识与具体业务问题结合起来。

在实现过程中，加深了对结构体、数组、循环队列、模块化编程等知识的理解，也提高了分析问题、拆分模块和组织程序的能力。该项目具有较强的实践性和教学意义，达到了课程设计的基本目标。