教案对齐官方方案书：重写为 5 天 C++/Qt 教学设计，补齐 6 个 Qt 技术缺口示例

- docs/teaching/OUTLINE.md、slides/day1-5.html、index.html：替换此前自定义的 4 天方案，严格对齐 docs/TRAINING_PLAN_2026.md「C++方向」Day1-5 课堂内容（Day6-10 为纯项目实作，不在教案范围） - docs/teaching/examples/：官方方案书要求但仓库 p03/(wiki 抓取内容) 未覆盖的 QSS/Model-View/JSON/QThread/QPropertyAnimation/QStateMachine 六个技术点，各补一个最小可运行示例 + README 教学文档，均已离屏验证跑通；手工维护，不属于 gen_part3.py 生成产物 - 根 CMakeLists.txt：接入 docs/teaching/examples 构建（BUILD_QT_PART 分支内），不改动生成器管理的 p01/p03 CMakeLists - 任务卡改为目标/验收标准/基础知识参考三段式模板，custom.css 配套新增样式 - docs/teaching/PRETEST.md：10 题 10 分钟 C++ 摸底测验，验证教案假定的受众基础是否成立，并与 OUTLINE.md §0 的分层预案挂钩
2026-07-02 11:31:44 +08:00
parent 6bb38563b5
commit 83620c0cf5
23 changed files with 1862 additions and 1041 deletions
@@ -0,0 +1,56 @@
+# JSON 解析与写入 —— 教学补充示例
+
+> 对应方案书「C++方向 Day3」："Qt 文件 IO 操作与 JSON 等主流数据格式解析"。
+> 仓库 `p03/ch11` 的 wiki 抓取内容覆盖了 `QFile`/`QTextStream`/`QDataStream`，
+> 唯独没有 JSON，本示例是手工补写的教学补充，**不属于**
+> `tools/gen_part3.py` 的生成产物。
+
+## 概念
+
+Qt 从 5.0 起自带 JSON 支持（`QtCore` 模块，不需要额外依赖第三方 JSON 库），
+核心是四个类：
+
+- `QJsonValue` —— 一个 JSON 值（字符串/数字/布尔/数组/对象/null）；
+- `QJsonObject` —— 键值对集合，对应 JSON 里的 `{ ... }`；
+- `QJsonArray` —— 值的列表，对应 JSON 里的 `[ ... ]`；
+- `QJsonDocument` —— 顶层容器，负责整个文档和字节流（`QByteArray`）之间的
+  相互转换（序列化/反序列化）。
+
+与 `p03/ch11` 已有的 `QTextStream`/`QDataStream` 对比：那两个解决的是"文本行"
+和"二进制结构体"的读写；JSON 解决的是"带层级结构的数据"（对象嵌数组嵌对象）的
+读写，是目前最常见的配置文件/网络接口数据格式。
+
+## 代码走读
+
+见 [`qt_json_parse_write.cpp`](qt_json_parse_write.cpp)：
+
+1. 用 `QJsonObject`/`QJsonArray` 构造一份"学员信息"数据；
+2. `QJsonDocument(obj).toJson(QJsonDocument::Indented)` 序列化成带缩进的可读
+   字节流（`QJsonDocument::Compact` 则是不带空白的紧凑格式，写文件/网络传输
+   常用这个）；
+3. `QJsonDocument::fromJson(bytes)` 反序列化回来，`.isObject()` 判断顶层类型后
+   逐个字段取值。
+
+这个示例不涉及 GUI，纯粹是数据结构的构造/序列化/反序列化，所以用
+`QCoreApplication` 而不是 `QApplication`，不需要 `QT_QPA_PLATFORM=offscreen`。
+
+## 验证方式
+
+```bash
+tools/run_qt.sh qt_json_parse_write
+```
+
+预期终端输出：先打印一段带缩进的 JSON 文本，再打印从中解析出的姓名/分数/标签。
+
+## 练习方向（供任务卡引用）
+
+- 把结果写入一个真实文件（结合 `p03/ch11/qfile_basic.cpp` 的 `QFile` 写法），
+  再从文件读回来解析，构成一个完整的"落盘 JSON 配置"流程；
+- 故意构造一段格式错误的 JSON 字符串喂给 `fromJson`，观察 `parsed.isNull()`
+  为 `true` 时如何做错误提示（而不是让程序崩溃或读到脏数据）。
+
+## 参考
+
+- 本仓库对照：[`p03/ch11/qfile_basic.cpp`](../../../../p03/ch11/qfile_basic.cpp)、
+  [`qtextstream_io.cpp`](../../../../p03/ch11/qtextstream_io.cpp)
+- Qt 官方文档：*JSON Support in Qt*（doc.qt.io，选读·需联网）
@@ -0,0 +1,49 @@
+// ============================================================================
+//  qt_json_parse_write —— 教学补充示例（非 wiki 生成，手工维护）
+//  用途：方案书「C++方向 Day3」要求的 JSON 等主流数据格式解析，仓库 p03/ch11
+//        原有 wiki 抓取内容只覆盖 QFile/QTextStream/QDataStream，没有 JSON，
+//        故补一个最小示例。
+//  说明：JSON 读写不需要 GUI，用 QCoreApplication 即可，不需要
+//        QT_QPA_PLATFORM=offscreen，直接 tools/run_qt.sh qt_json_parse_write 即可。
+//  配套文档：docs/teaching/examples/json_io/README.md
+// ============================================================================
+
+#include <QCoreApplication>
+#include <QJsonObject>
+#include <QJsonArray>
+#include <QJsonDocument>
+#include <QDebug>
+
+int main(int argc, char* argv[]) {
+    QCoreApplication app(argc, argv);
+
+    // 1) 构造一个 JSON 对象（对应课程里“学员信息”这类结构）
+    QJsonObject student;
+    student["name"] = QStringLiteral("张三");
+    student["score"] = 92;
+    QJsonArray tags;
+    tags.append(QStringLiteral("Qt"));
+    tags.append(QStringLiteral("C++"));
+    student["tags"] = tags;
+
+    // 2) 序列化：QJsonObject -> QJsonDocument -> 字节数组（可直接写文件）
+    QJsonDocument doc(student);
+    QByteArray bytes = doc.toJson(QJsonDocument::Indented);
+    qDebug().noquote() << "序列化结果：\n" << bytes;
+
+    // 3) 反序列化：字节数组 -> QJsonDocument -> 取值
+    QJsonDocument parsed = QJsonDocument::fromJson(bytes);
+    if (!parsed.isNull() && parsed.isObject()) {
+        QJsonObject obj = parsed.object();
+        qDebug() << "姓名：" << obj["name"].toString();
+        qDebug() << "分数：" << obj["score"].toInt();
+        const QJsonArray parsedTags = obj["tags"].toArray();
+        for (const QJsonValue& v : parsedTags)
+            qDebug() << "标签：" << v.toString();
+    } else {
+        qDebug() << "JSON 解析失败";
+        return 1;
+    }
+
+    return 0;
+}