Day3 教学示例：增强版计算器接入 + QMainWindow/QSS 两版参考实现

- calculator_designer_ext（Day2 增强版：表达式求值 + 括号，递归下降解析器）接入 cmake
- calculator_mainwindow（Day3 上午）：增强版计算器装进 QMainWindow，
  菜单/状态栏/历史停靠窗，纯代码 + 显式 connect，与 mainwindow_showcase 形成坑卡对照
- calculator_mainwindow_qss（Day3 下午）：上午版 + QSS 双主题美化（按键分色/伪状态/深浅切换）
- 验证 mainwindow_showcase（QMainWindow 六大组件综合演示，.ui + .qrc）
- OUTLINE_4DAY.md / ASSIGNMENTS.md Day3 衔接增强版起点 + 参考实现指引
- 补提交 Day2 calculator/ 与 calculator_designer/ 参考实现（CMakeLists 已引用）
- 全量构建 28/28，4 目标离屏自测退出码 0

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/teaching/examples/calculator_mainwindow/README.md

@@ -0,0 +1,76 @@
+# Day3 上午参考实现：计算器 → QMainWindow
+
+> 对应教案 [`OUTLINE_4DAY.md`](../../OUTLINE_4DAY.md) Day3 上午「QMainWindow / 对话框
+> QDialog」+ [`ASSIGNMENTS.md`](../../ASSIGNMENTS.md) Day3 上午课堂练习。手工维护，
+> 非生成产物。
+
+## 定位：把 Day2 增强版计算器装进 QMainWindow
+
+以 Day2 增强版计算器 [`../calculator_designer_ext/`](../calculator_designer_ext/README.md)
+的 `CalculatorDesigner`（`QWidget`，含表达式求值 + 括号）为**中心部件**，给它套上
+`QMainWindow` 外壳：菜单栏 / 状态栏 / 历史停靠窗。**计算器面板本身的输入与求值逻辑
+一字未改**——这正是「界面外壳升级、核心部件不动」的关注点分离。
+
+## 与 Day2 增强版的差异（仅两处，集中在 `calculatordesigner.{h,cpp}`）
+
+| 改动 | 位置 | 目的 |
+|---|---|---|
+| 新增 `evaluated(expr, result)` 信号 | `calculatordesigner.h/.cpp` | 按 `=` 求值成功后发出，供历史停靠窗订阅（演示「给已有部件加信号，与外壳通信」） |
+| 新增 `loadExpression(expr)` 方法 | `calculatordesigner.h/.cpp` | 把一条历史表达式回填到编辑区，配合历史双击 |
+
+`expressionevaluator.{h,cpp}` / `widget.ui` 与 Day2 增强版完全一致（自包含复制，便于
+学员单读 Day3 代码不跳目录）。
+
+## 与 [`../mainwindow_showcase/`](../mainwindow_showcase/README.md) 的分工对照
+
+两者同为 Day3 上午教学载体，风格刻意对立，覆盖不同教学诉求：
+
+| | `mainwindow_showcase` | 本例 `calculator_mainwindow` |
+|---|---|---|
+| 形态 | 极简文本编辑器（`QTextEdit` 中心） | 计算器（`CalculatorDesigner` 中心） |
+| 主窗体结构来源 | `.ui` 表单（Designer） | 纯代码 |
+| 信号槽 | `on_<obj>_<sig>` 自动连接 | 显式 `connect()` |
+| 教学侧重 | QMainWindow 六大组件齐全（含资源 `.qrc`） | 作业线应用 + 显式 connect 坑卡 |
+| 用法 | 教师讲「组件协议」时演示 | 学员课堂练习对照、作业验收参考 |
+
+**坑卡对照**：`mainwindow_showcase` 用自动连接，控件改名静默失效；本例用显式 `connect`，
+`QAction` 忘 connect 时菜单点了没反应——两种「静默失败」在同一节课形成对照。
+
+## 教学要点（对应 OUTLINE_4DAY.md Day3 上午）
+
+1. **中心部件必须 `setCentralWidget`**：`mainwindow.cpp` 构造函数里 `setCentralWidget(m_calc)`。
+   直接往 `QMainWindow` 上 `addWidget` 是 Day3 上午坑卡——布局行为不可预期。
+2. **菜单 + QAction + 显式 connect**：`buildMenu()` 逐菜单逐 `QAction` 建，每个都 `connect`。
+   `m_actAbout` 若忘 `connect`，菜单显示正常、点了没反应。
+3. **模态对话框**：`onAbout()` 用 `QMessageBox::about`，内部 `exec()` 阻塞等关闭。
+4. **非模态停靠窗**：`QDockWidget` + `addDockWidget(Qt::RightDockWidgetArea, ...)`，
+   可拖动 / 浮动 / 关闭（`QDockWidget` 默认行为）。与 `p03/ch06` 三个 modeless 对照文件
+   呼应「非模态对象必须活过函数作用域」——停靠窗是 `new` 在堆上 + parent=`this`。
+5. **信号槽跨对象通信**：`CalculatorDesigner::evaluated` → `MainWindow::onEvaluated`，
+   外壳订阅核心部件的信号，二者解耦。
+
+## 构建与运行
+
+```bash
+# 构建（仓库根；Qt 5.14.2）
+cmake --build build --target qt_calculator_mainwindow
+
+# 离屏自测（9 组计算用例 + 历史追加/双击回填/清空，退出码 0 即全过）
+PATH=E:/Qt/Qt5.14.2/5.14.2/mingw73_64/bin:$PATH \
+QT_QPA_PLATFORM=offscreen \
+  ./build/docs/teaching/examples/qt_calculator_mainwindow.exe; echo "exit=$?"
+
+# 有 GUI 环境直接看窗口
+./build/docs/teaching/examples/qt_calculator_mainwindow.exe
+```
+
+## 自测用例
+
+`MainWindow::runSelfTest()`（offscreen 自动执行）覆盖：
+
+- Day2 全部 9 组计算用例（验证升级外壳后计算行为不变）
+- 按等号后历史停靠窗追加 `"expr = result"` 条目
+- 除零 `Error` **不**进历史（`evaluated` 只在求值成功时 emit）
+- 历史双击 → 表达式回填到编辑区
+- 「清空历史」后列表为空
+- 「关于」action 已创建并显式连接（GUI 弹窗验证靠现场演示）

docs/teaching/examples/calculator_mainwindow/calculatordesigner.cpp

@@ -0,0 +1,248 @@
+#include "calculatordesigner.h"
+
+#include <QPushButton>
+
+#include "expressionevaluator.h"
+#include "ui_widget.h"
+
+namespace {
+bool isOperatorChar(QChar ch) {
+    return ch == QLatin1Char('+') || ch == QLatin1Char('-') ||
+           ch == QLatin1Char('*') || ch == QLatin1Char('/');
+}
+
+bool isDigitOrDotChar(QChar ch) {
+    return ch.isDigit() || ch == QLatin1Char('.');
+}
+}  // namespace
+
+CalculatorDesigner::CalculatorDesigner(QWidget* parent)
+    : QWidget(parent), ui(new Ui::CalculatorForm) {
+    ui->setupUi(this);   // 表单里的控件树 + QGridLayout 全部由 Designer XML 建好
+
+    connect(ui->btn0, &QPushButton::clicked, this, [this] { onDigit(0); });
+    connect(ui->btn1, &QPushButton::clicked, this, [this] { onDigit(1); });
+    connect(ui->btn2, &QPushButton::clicked, this, [this] { onDigit(2); });
+    connect(ui->btn3, &QPushButton::clicked, this, [this] { onDigit(3); });
+    connect(ui->btn4, &QPushButton::clicked, this, [this] { onDigit(4); });
+    connect(ui->btn5, &QPushButton::clicked, this, [this] { onDigit(5); });
+    connect(ui->btn6, &QPushButton::clicked, this, [this] { onDigit(6); });
+    connect(ui->btn7, &QPushButton::clicked, this, [this] { onDigit(7); });
+    connect(ui->btn8, &QPushButton::clicked, this, [this] { onDigit(8); });
+    connect(ui->btn9, &QPushButton::clicked, this, [this] { onDigit(9); });
+    connect(ui->btnDot, &QPushButton::clicked, this, [this] { onDot(); });
+
+    connect(ui->btnPlus, &QPushButton::clicked, this, [this] { onOperator(QLatin1Char('+')); });
+    connect(ui->btnMinus, &QPushButton::clicked, this, [this] { onOperator(QLatin1Char('-')); });
+    connect(ui->btnMul, &QPushButton::clicked, this, [this] { onOperator(QLatin1Char('*')); });
+    connect(ui->btnDiv, &QPushButton::clicked, this, [this] { onOperator(QLatin1Char('/')); });
+
+    connect(ui->btnLeftParen, &QPushButton::clicked, this, &CalculatorDesigner::onLeftParen);
+    connect(ui->btnRightParen, &QPushButton::clicked, this, &CalculatorDesigner::onRightParen);
+
+    connect(ui->btnEquals, &QPushButton::clicked, this, &CalculatorDesigner::onEquals);
+    connect(ui->btnClear, &QPushButton::clicked, this, &CalculatorDesigner::onClear);
+    connect(ui->btnBackspace, &QPushButton::clicked, this, &CalculatorDesigner::onBackspace);
+
+    onClear();
+}
+
+CalculatorDesigner::~CalculatorDesigner() { delete ui; }
+
+void CalculatorDesigner::onDigit(int digit) {
+    if (m_error) onClear();
+    if (m_resultShown) {
+        m_expression.clear();
+        m_openParenCount = 0;
+        m_resultShown = false;
+    }
+
+    const QString token = currentOperandToken();
+    if (token == QStringLiteral("0")) {
+        m_expression.chop(1);  // 用新数字替换孤立的前导 0，避免出现 "007"
+    } else if (currentOperandDigitCount() >= kMaxOperandLength) {
+        return;  // 达到单个运算数的长度上限，忽略后续数字
+    }
+    if (m_expression.size() >= kMaxExpressionLength) return;
+
+    m_expression.append(QString::number(digit));
+    refreshDisplays();
+}
+
+void CalculatorDesigner::onDot() {
+    if (m_error) onClear();
+    if (m_resultShown) {
+        m_expression.clear();
+        m_openParenCount = 0;
+        m_resultShown = false;
+    }
+
+    const QString token = currentOperandToken();
+    if (token.contains(QLatin1Char('.'))) return;  // 当前运算数已有小数点
+
+    const int appended = token.isEmpty() ? 2 : 1;  // 空token时需要补一个前导 0
+    if (m_expression.size() + appended > kMaxExpressionLength) return;
+
+    if (token.isEmpty()) m_expression.append(QLatin1Char('0'));
+    m_expression.append(QLatin1Char('.'));
+    refreshDisplays();
+}
+
+void CalculatorDesigner::onOperator(QChar op) {
+    if (m_error) return;
+    if (m_resultShown) {
+        m_expression = m_lastResultText;
+        m_resultShown = false;
+    }
+
+    if (m_expression.isEmpty()) {
+        if (op != QLatin1Char('-')) return;  // 表达式开头只允许负号（单目负号）
+    } else {
+        const QChar last = m_expression.at(m_expression.size() - 1);
+        if (last == QLatin1Char('(')) {
+            if (op != QLatin1Char('-')) return;  // 左括号后只允许负号
+        } else if (isOperatorChar(last)) {
+            m_expression.chop(1);  // 连续按运算符时，用新的运算符替换上一个
+        }
+    }
+
+    if (m_expression.size() >= kMaxExpressionLength) return;
+    m_expression.append(op);
+    refreshDisplays();
+}
+
+void CalculatorDesigner::onLeftParen() {
+    if (m_error) onClear();
+    if (m_resultShown) {
+        m_expression.clear();
+        m_openParenCount = 0;
+        m_resultShown = false;
+    }
+
+    if (!m_expression.isEmpty()) {
+        const QChar last = m_expression.at(m_expression.size() - 1);
+        if (!isOperatorChar(last) && last != QLatin1Char('(')) {
+            return;  // 数字或右括号后不支持隐式乘法，忽略
+        }
+    }
+    if (m_expression.size() >= kMaxExpressionLength) return;
+
+    m_expression.append(QLatin1Char('('));
+    ++m_openParenCount;
+    refreshDisplays();
+}
+
+void CalculatorDesigner::onRightParen() {
+    if (m_error) return;
+    if (m_resultShown) return;
+    if (m_openParenCount <= 0 || m_expression.isEmpty()) return;
+
+    const QChar last = m_expression.at(m_expression.size() - 1);
+    if (isOperatorChar(last) || last == QLatin1Char('(')) return;  // 括号内需要完整子表达式
+    if (m_expression.size() >= kMaxExpressionLength) return;
+
+    m_expression.append(QLatin1Char(')'));
+    --m_openParenCount;
+    refreshDisplays();
+}
+
+void CalculatorDesigner::onEquals() {
+    if (m_error) return;
+    if (m_expression.isEmpty()) return;
+
+    QString toEvaluate = m_expression;
+    for (int i = 0; i < m_openParenCount; ++i) toEvaluate.append(QLatin1Char(')'));  // 自动补全未闭合括号
+
+    const ExpressionEvaluator::Result result = ExpressionEvaluator::evaluate(toEvaluate);
+    if (!result.ok) {
+        showError();
+        return;
+    }
+
+    const QString resultText = QString::number(result.value, 'g', ExpressionEvaluator::kResultPrecision);
+    m_expression = toEvaluate;
+    m_lastResultText = resultText;
+    m_openParenCount = 0;
+    m_resultShown = true;
+    ui->expressionEdit->setPlainText(m_expression + QStringLiteral(" = ") + resultText);
+    ui->display->setText(resultText);
+
+    // 【新增】通知外壳（历史停靠窗）：本次求值的表达式与结果。
+    emit evaluated(m_expression, resultText);
+}
+
+void CalculatorDesigner::onClear() {
+    m_expression.clear();
+    m_lastResultText.clear();
+    m_openParenCount = 0;
+    m_resultShown = false;
+    m_error = false;
+    ui->expressionEdit->clear();
+    ui->display->setText(QStringLiteral("0"));
+}
+
+void CalculatorDesigner::onBackspace() {
+    if (m_error) { onClear(); return; }
+    if (m_resultShown) return;  // 结果已展示，需先清空或继续输入新表达式
+    if (m_expression.isEmpty()) return;
+
+    const QChar removed = m_expression.at(m_expression.size() - 1);
+    m_expression.chop(1);
+    if (removed == QLatin1Char('(')) --m_openParenCount;
+    else if (removed == QLatin1Char(')')) ++m_openParenCount;
+    refreshDisplays();
+}
+
+QString CalculatorDesigner::displayText() const { return ui->display->text(); }
+
+QString CalculatorDesigner::expressionText() const { return ui->expressionEdit->toPlainText(); }
+
+// 【新增】把一条历史表达式回填到编辑区：重置状态机并把表达式原样载入，
+// 未闭合括号数按字符重新统计。调用后用户可直接按 = 重新求值，或继续编辑。
+void CalculatorDesigner::loadExpression(const QString& expr) {
+    if (m_error) onClear();
+    m_expression = expr;
+    m_openParenCount = 0;
+    for (const QChar ch : m_expression) {
+        if (ch == QLatin1Char('(')) ++m_openParenCount;
+        else if (ch == QLatin1Char(')')) --m_openParenCount;
+    }
+    if (m_openParenCount < 0) m_openParenCount = 0;
+    m_resultShown = false;
+    m_lastResultText.clear();
+    refreshDisplays();
+}
+
+QString CalculatorDesigner::currentOperandToken() const {
+    int start = m_expression.size();
+    while (start > 0 && isDigitOrDotChar(m_expression.at(start - 1))) --start;
+    return m_expression.mid(start);
+}
+
+int CalculatorDesigner::currentOperandDigitCount() const {
+    const QString token = currentOperandToken();
+    int count = 0;
+    for (const QChar ch : token) {
+        if (ch.isDigit()) ++count;
+    }
+    return count;
+}
+
+QString CalculatorDesigner::lastNumberToken() const {
+    int end = m_expression.size();
+    while (end > 0 && !isDigitOrDotChar(m_expression.at(end - 1))) --end;  // 跳过末尾的运算符/括号
+    int start = end;
+    while (start > 0 && isDigitOrDotChar(m_expression.at(start - 1))) --start;
+    return m_expression.mid(start, end - start);
+}
+
+void CalculatorDesigner::refreshDisplays() {
+    ui->expressionEdit->setPlainText(m_expression);
+    const QString token = lastNumberToken();
+    ui->display->setText(token.isEmpty() ? QStringLiteral("0") : token);
+}
+
+void CalculatorDesigner::showError() {
+    ui->display->setText(QStringLiteral("Error"));
+    m_error = true;
+}

docs/teaching/examples/calculator_mainwindow/calculatordesigner.h

@@ -0,0 +1,66 @@
+#pragma once
+
+#include <QChar>
+#include <QString>
+#include <QWidget>
+
+QT_BEGIN_NAMESPACE
+namespace Ui {
+class CalculatorForm;
+}
+QT_END_NAMESPACE
+
+// CalculatorDesigner —— 计算器面板（QWidget）。
+// 【Day3 calculator_mainwindow】相对 ../calculator_designer_ext/ 版仅两处改动：
+//   ① 新增 evaluated(expression,result) 信号：按 = 求值成功后发出，供 MainWindow
+//      的历史停靠窗订阅（演示「给已有部件加信号，与外壳通信」）。
+//   ② 新增 loadExpression(expr)：把一条历史表达式回填到编辑区（演示「部件对外
+//      提供 API」，配合历史双击回填）。
+//   其余输入校验/状态机/求值逻辑一字未改。
+class CalculatorDesigner : public QWidget {
+    Q_OBJECT
+public:
+    explicit CalculatorDesigner(QWidget* parent = nullptr);
+    ~CalculatorDesigner() override;
+
+    // 供自测直接调用，效果等价于点击对应按钮；逻辑与 ../calculator_designer_ext/ 版一字不差。
+    void onDigit(int digit);
+    void onDot();
+    void onOperator(QChar op);
+    void onLeftParen();
+    void onRightParen();
+    void onEquals();
+    void onClear();
+    void onBackspace();
+
+    QString displayText() const;
+    QString expressionText() const;
+
+    // 【新增】把一条历史表达式回填到编辑区（历史双击时调用）。
+    void loadExpression(const QString& expr);
+
+signals:
+    // 【新增】按 = 求值成功后发出，参数为（自动补全括号后的表达式, 结果文本）。
+    void evaluated(const QString& expression, const QString& result);
+
+private:
+    // 单个运算数（数字串）允许的最大长度，要求不得小于 10 位。
+    static constexpr int kMaxOperandLength = 15;
+    static_assert(kMaxOperandLength >= 10, "单个运算数的最大长度不得小于 10 位");
+    // 表达式总长度上限，要求不得低于 100 个字符。
+    static constexpr int kMaxExpressionLength = 200;
+    static_assert(kMaxExpressionLength >= 100, "表达式总长度上限不得低于 100 个字符");
+
+    QString currentOperandToken() const;
+    int currentOperandDigitCount() const;
+    QString lastNumberToken() const;
+    void refreshDisplays();
+    void showError();
+
+    Ui::CalculatorForm* ui;
+    QString m_expression;      // 当前正在编辑的表达式，例如 "12+3*(4-2"
+    QString m_lastResultText;  // 上一次成功计算得到的结果文本
+    int m_openParenCount = 0;  // 尚未闭合的左括号数量
+    bool m_resultShown = false;  // 显示区当前展示的是计算结果而非正在输入的数字
+    bool m_error = false;
+};

docs/teaching/examples/calculator_mainwindow/expressionevaluator.cpp

@@ -0,0 +1,145 @@
+#include "expressionevaluator.h"
+
+namespace {
+
+// 递归下降解析器：expression := term (('+'|'-') term)*
+//                term       := factor (('*'|'/') factor)*
+//                factor     := ('+'|'-') factor | '(' expression ')' | number
+// 括号会先被完整求值，天然实现"优先级提升"；乘除法在 term 层处理，
+// 天然高于 expression 层的加减法。
+// 【Day3 calculator_mainwindow】与 ../calculator_designer_ext/ 版一字不差。
+class Parser {
+public:
+    explicit Parser(const QString& text) : m_text(text) {}
+
+    ExpressionEvaluator::Result parse() {
+        ExpressionEvaluator::Result result;
+        skipSpaces();
+        if (atEnd()) {
+            result.errorMessage = QStringLiteral("表达式为空");
+            return result;
+        }
+
+        bool ok = true;
+        const double value = parseExpression(ok);
+        skipSpaces();
+        if (!ok) {
+            result.errorMessage = m_error;
+            return result;
+        }
+        if (!atEnd()) {
+            result.errorMessage = QStringLiteral("表达式包含无法识别的字符");
+            return result;
+        }
+
+        result.ok = true;
+        result.value = value;
+        return result;
+    }
+
+private:
+    double parseExpression(bool& ok) {
+        double value = parseTerm(ok);
+        while (ok) {
+            skipSpaces();
+            if (peek() == QLatin1Char('+')) {
+                advance();
+                value += parseTerm(ok);
+            } else if (peek() == QLatin1Char('-')) {
+                advance();
+                value -= parseTerm(ok);
+            } else {
+                break;
+            }
+        }
+        return value;
+    }
+
+    double parseTerm(bool& ok) {
+        double value = parseFactor(ok);
+        while (ok) {
+            skipSpaces();
+            if (peek() == QLatin1Char('*')) {
+                advance();
+                value *= parseFactor(ok);
+            } else if (peek() == QLatin1Char('/')) {
+                advance();
+                const double rhs = parseFactor(ok);
+                if (!ok) return 0.0;
+                if (rhs == 0.0) {
+                    fail(QStringLiteral("除数不能为零"), ok);
+                    return 0.0;
+                }
+                value /= rhs;
+            } else {
+                break;
+            }
+        }
+        return value;
+    }
+
+    double parseFactor(bool& ok) {
+        skipSpaces();
+        if (peek() == QLatin1Char('+')) {
+            advance();
+            return parseFactor(ok);
+        }
+        if (peek() == QLatin1Char('-')) {
+            advance();
+            return -parseFactor(ok);
+        }
+        if (peek() == QLatin1Char('(')) {
+            advance();
+            const double value = parseExpression(ok);
+            if (!ok) return 0.0;
+            skipSpaces();
+            if (peek() != QLatin1Char(')')) {
+                fail(QStringLiteral("括号不匹配"), ok);
+                return 0.0;
+            }
+            advance();
+            return value;
+        }
+        return parseNumber(ok);
+    }
+
+    double parseNumber(bool& ok) {
+        skipSpaces();
+        const int start = m_pos;
+        bool hasDigits = false;
+        while (!atEnd() && peek().isDigit()) { advance(); hasDigits = true; }
+        if (!atEnd() && peek() == QLatin1Char('.')) {
+            advance();
+            while (!atEnd() && peek().isDigit()) { advance(); hasDigits = true; }
+        }
+        if (!hasDigits) {
+            fail(QStringLiteral("表达式格式错误，缺少数字"), ok);
+            return 0.0;
+        }
+        const QString token = m_text.mid(start, m_pos - start);
+        bool numOk = false;
+        const double value = token.toDouble(&numOk);
+        if (!numOk) {
+            fail(QStringLiteral("数字格式错误"), ok);
+            return 0.0;
+        }
+        return value;
+    }
+
+    void skipSpaces() { while (!atEnd() && peek().isSpace()) advance(); }
+    bool atEnd() const { return m_pos >= m_text.size(); }
+    QChar peek() const { return atEnd() ? QChar() : m_text.at(m_pos); }
+    void advance() { ++m_pos; }
+    void fail(const QString& message, bool& ok) { ok = false; m_error = message; }
+
+    const QString& m_text;
+    int m_pos = 0;
+    QString m_error;
+};
+
+}  // namespace
+
+ExpressionEvaluator::Result ExpressionEvaluator::evaluate(const QString& expression) {
+    Parser parser(expression);
+    return parser.parse();
+}

docs/teaching/examples/calculator_mainwindow/expressionevaluator.h

@@ -0,0 +1,22 @@
+#pragma once
+
+#include <QString>
+
+// 对形如 "1+2*(3-4)" 的中缀表达式求值：
+// 乘除优先级高于加减，括号可提升优先级。
+// 【Day3 calculator_mainwindow】与 ../calculator_designer_ext/ 版一字不差，
+// 求值逻辑独立于界面外壳——Day3 把 QWidget 换成 QMainWindow，本类不动。
+class ExpressionEvaluator {
+public:
+    struct Result {
+        bool ok = false;
+        double value = 0.0;
+        QString errorMessage;
+    };
+
+    // 结果显示精度（有效数字位数），要求不得小于 10。
+    static constexpr int kResultPrecision = 12;
+    static_assert(kResultPrecision >= 10, "结果显示精度不得小于 10 位有效数字");
+
+    static Result evaluate(const QString& expression);
+};

docs/teaching/examples/calculator_mainwindow/main.cpp

@@ -0,0 +1,28 @@
+// ============================================================================
+//  calculator_mainwindow —— Day3 上午版程序入口
+//  对应教案 OUTLINE_4DAY.md Day3 上午「QMainWindow / 对话框 QDialog」。
+//
+//  把 Day2 增强版计算器（CalculatorDesigner，QWidget）装进 QMainWindow：
+//    - 菜单栏（文件/编辑/视图/帮助，纯代码 + 显式 connect）
+//    - 历史停靠窗（QDockWidget + QListWidget，订阅 evaluated 信号）
+//    - 状态栏（就绪 / 结果临时提示）
+//  离屏自测覆盖 Day2 全部 9 组计算用例 + Day3 新增（历史追加/双击回填/清空）。
+// ============================================================================
+#include <QApplication>
+#include <QTimer>
+
+#include "mainwindow.h"
+
+int main(int argc, char* argv[]) {
+    QApplication app(argc, argv);
+    MainWindow w;
+    w.show();
+
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(0, &w, [&w] {
+            const bool ok = w.runSelfTest();
+            QCoreApplication::exit(ok ? 0 : 1);
+        });
+    }
+    return app.exec();
+}

docs/teaching/examples/calculator_mainwindow/mainwindow.cpp

@@ -0,0 +1,212 @@
+// ============================================================================
+//  mainwindow.cpp —— Day3 上午版实现
+//  详见 mainwindow.h 顶部注释。本文件只做外壳组装，不含任何计算逻辑。
+// ============================================================================
+#include "mainwindow.h"
+#include "calculatordesigner.h"
+
+#include <QAction>
+#include <QDebug>
+#include <QDockWidget>
+#include <QKeySequence>
+#include <QListWidget>
+#include <QListWidgetItem>
+#include <QMenu>
+#include <QMenuBar>
+#include <QMessageBox>
+#include <QStatusBar>
+
+MainWindow::MainWindow(QWidget* parent) : QMainWindow(parent) {
+    setWindowTitle(QStringLiteral("计算器（QMainWindow 版）"));
+
+    // ★ 中心部件必须显式安放（Day3 上午坑卡：直接往 QMainWindow 上 addWidget
+    //   布局行为不可预期）。CalculatorDesigner 是 QWidget，原样塞进去即可。
+    m_calc = new CalculatorDesigner(this);
+    setCentralWidget(m_calc);
+
+    buildMenu();
+    buildDock();
+    buildStatusBar();
+
+    // 计算器求值成功 → 历史停靠窗追加一条（Day2 信号槽的复用：给已有部件
+    // 加 evaluated 信号，外壳订阅它）。
+    connect(m_calc, &CalculatorDesigner::evaluated, this, &MainWindow::onEvaluated);
+}
+
+MainWindow::~MainWindow() = default;
+
+// ---- 菜单栏（纯代码 + 显式 connect，对照 mainwindow_showcase 的 .ui 自动连接）----
+void MainWindow::buildMenu() {
+    QMenu* fileMenu = menuBar()->addMenu(QStringLiteral("文件(&F)"));
+    m_actQuit = fileMenu->addAction(QStringLiteral("退出(&Q)"));
+    m_actQuit->setShortcut(QKeySequence(QStringLiteral("Ctrl+Q")));
+    connect(m_actQuit, &QAction::triggered, this, &QWidget::close);
+
+    QMenu* editMenu = menuBar()->addMenu(QStringLiteral("编辑(&E)"));
+    m_actClearHistory = editMenu->addAction(QStringLiteral("清空历史(&C)"));
+    connect(m_actClearHistory, &QAction::triggered, this, &MainWindow::onClearHistory);
+
+    QMenu* viewMenu = menuBar()->addMenu(QStringLiteral("视图(&V)"));
+    m_actToggleHistory = viewMenu->addAction(QStringLiteral("显示历史(&H)"));
+    m_actToggleHistory->setCheckable(true);
+    m_actToggleHistory->setChecked(true);
+    connect(m_actToggleHistory, &QAction::toggled, this, &MainWindow::onToggleHistoryVisible);
+
+    QMenu* helpMenu = menuBar()->addMenu(QStringLiteral("帮助(&H)"));
+    m_actAbout = helpMenu->addAction(QStringLiteral("关于(&A)"));
+    // ★ 显式 connect：忘了这一行，菜单显示正常、点了没反应（Day3 上午坑卡）。
+    connect(m_actAbout, &QAction::triggered, this, &MainWindow::onAbout);
+}
+
+// ---- 历史停靠窗 ----
+void MainWindow::buildDock() {
+    m_history = new QListWidget(this);
+    m_history->setAlternatingRowColors(true);
+    m_dock = new QDockWidget(QStringLiteral("历史"), this);
+    m_dock->setObjectName(QStringLiteral("historyDock"));   // 供 saveState/restoreState
+    m_dock->setAllowedAreas(Qt::LeftDockWidgetArea | Qt::RightDockWidgetArea | Qt::BottomDockWidgetArea);
+    m_dock->setWidget(m_history);
+    addDockWidget(Qt::RightDockWidgetArea, m_dock);
+    // 双击历史条目 → 回填表达式（QListWidget 信号槽）
+    connect(m_history, &QListWidget::itemDoubleClicked, this, &MainWindow::onHistoryDoubleClicked);
+}
+
+void MainWindow::buildStatusBar() {
+    statusBar()->showMessage(QStringLiteral("就绪"));
+}
+
+void MainWindow::refreshStatus(const QString& msg) {
+    statusBar()->showMessage(msg, 3000);   // 临时提示，3 秒后恢复
+}
+
+// ---- 槽 ----
+void MainWindow::onAbout() {
+    // 标准对话框：QMessageBox::about 是模态的，exec() 内部阻塞等用户关闭。
+    QMessageBox::about(this, QStringLiteral("关于"),
+        QStringLiteral(
+            "<b>计算器（QMainWindow 版）</b><br><br>"
+            "Day3 上午教学参考实现：把 Day2 增强版计算器（表达式求值 + 括号）"
+            "装进 QMainWindow，演示菜单栏 / 状态栏 / 历史停靠窗。<br><br>"
+            "对应教案 OUTLINE_4DAY.md Day3 上午。"));
+}
+
+void MainWindow::onClearHistory() {
+    m_history->clear();
+    refreshStatus(QStringLiteral("已清空历史"));
+}
+
+void MainWindow::onToggleHistoryVisible(bool checked) {
+    m_dock->setVisible(checked);
+}
+
+void MainWindow::onEvaluated(const QString& expr, const QString& result) {
+    m_history->addItem(expr + QStringLiteral(" = ") + result);
+    refreshStatus(QStringLiteral("结果: ") + result);
+}
+
+void MainWindow::onHistoryDoubleClicked(QListWidgetItem* item) {
+    // 条目文本形如 "expr = result"，取最后一个 " = " 左侧作为表达式回填。
+    // 用 lastIndexOf 而非 indexOf：result 文本里一般不含 " = "，但用 lastIndexOf
+    // 更稳妥（避免表达式里万一出现 " = "，实际上表达式不会含 =）。
+    const QString text = item->text();
+    const int idx = text.lastIndexOf(QStringLiteral(" = "));
+    if (idx < 0) return;
+    m_calc->loadExpression(text.left(idx));
+    refreshStatus(QStringLiteral("已回填表达式"));
+}
+
+// ------------------------------------------------------------ 自测 ----
+bool MainWindow::runSelfTest() {
+    auto expect = [](const char* label, bool cond) -> bool {
+        if (!cond) { qCritical() << "自测失败：" << label; return false; }
+        qInfo() << "自测通过：" << label; return true;
+    };
+    auto expectEq = [](const char* label, const QString& actual, const QString& expected) -> bool {
+        if (actual != expected) {
+            qCritical() << "自测失败：" << label << "实际=" << actual << "预期=" << expected;
+            return false;
+        }
+        qInfo() << "自测通过：" << label << "=>" << actual;
+        return true;
+    };
+
+    // —— Day2 计算 9 组用例（验证升级外壳后计算行为不变）——
+    m_calc->onClear();
+    m_calc->onDigit(7); m_calc->onOperator(QLatin1Char('+')); m_calc->onDigit(3); m_calc->onEquals();
+    if (!expectEq("7 + 3 =", m_calc->displayText(), QStringLiteral("10"))) return false;
+    if (!expect("历史追加第 1 条", m_history->count() == 1)) return false;
+    if (!expectEq("历史条目文本", m_history->item(0)->text(), QStringLiteral("7+3 = 10"))) return false;
+
+    m_calc->onClear();
+    m_calc->onDigit(6); m_calc->onOperator(QLatin1Char('/')); m_calc->onDigit(0); m_calc->onEquals();
+    if (!expectEq("6 ÷ 0 =", m_calc->displayText(), QStringLiteral("Error"))) return false;
+    if (!expect("除零 Error 不进历史", m_history->count() == 1)) return false;
+
+    m_calc->onClear();
+    m_calc->onDigit(4); m_calc->onDot(); m_calc->onDigit(5);
+    m_calc->onOperator(QLatin1Char('+'));
+    m_calc->onDigit(0); m_calc->onDot(); m_calc->onDigit(5);
+    m_calc->onEquals();
+    if (!expectEq("4.5 + 0.5 =", m_calc->displayText(), QStringLiteral("5"))) return false;
+
+    m_calc->onClear();
+    m_calc->onDigit(1); m_calc->onDigit(2); m_calc->onBackspace();
+    if (!expectEq("12 退格", m_calc->displayText(), QStringLiteral("1"))) return false;
+
+    m_calc->onClear();
+    m_calc->onDigit(2); m_calc->onOperator(QLatin1Char('+'));
+    m_calc->onDigit(3); m_calc->onOperator(QLatin1Char('+'));
+    m_calc->onDigit(4); m_calc->onEquals();
+    if (!expectEq("2 + 3 + 4 =", m_calc->displayText(), QStringLiteral("9"))) return false;
+
+    m_calc->onClear();
+    m_calc->onDigit(2); m_calc->onOperator(QLatin1Char('+'));
+    m_calc->onDigit(3); m_calc->onOperator(QLatin1Char('*'));
+    m_calc->onDigit(4); m_calc->onEquals();
+    if (!expectEq("2 + 3 × 4 =", m_calc->displayText(), QStringLiteral("14"))) return false;
+
+    m_calc->onClear();
+    m_calc->onLeftParen();
+    m_calc->onDigit(2); m_calc->onOperator(QLatin1Char('+')); m_calc->onDigit(3);
+    m_calc->onRightParen();
+    m_calc->onOperator(QLatin1Char('*'));
+    m_calc->onDigit(4); m_calc->onEquals();
+    if (!expectEq("(2 + 3) × 4 =", m_calc->displayText(), QStringLiteral("20"))) return false;
+
+    m_calc->onClear();
+    m_calc->onDigit(1); m_calc->onOperator(QLatin1Char('+'));
+    m_calc->onLeftParen();
+    m_calc->onDigit(2); m_calc->onOperator(QLatin1Char('*'));
+    m_calc->onLeftParen();
+    m_calc->onDigit(3); m_calc->onOperator(QLatin1Char('+')); m_calc->onDigit(4);
+    m_calc->onRightParen();
+    m_calc->onRightParen();
+    m_calc->onEquals();
+    if (!expectEq("1 + (2 × (3 + 4)) =", m_calc->displayText(), QStringLiteral("15"))) return false;
+
+    m_calc->onClear();
+    m_calc->onLeftParen();
+    m_calc->onDigit(1); m_calc->onOperator(QLatin1Char('+')); m_calc->onDigit(2);
+    m_calc->onEquals();
+    if (!expectEq("(1 + 2 = 自动补全", m_calc->displayText(), QStringLiteral("3"))) return false;
+
+    // 9 组用例里：第 4 组（12 退格）无 onEquals、第 2 组（6÷0）Error 不 emit，
+    // 其余 7 次 onEquals 各进历史一条。
+    if (!expect("历史累计 7 条", m_history->count() == 7)) return false;
+
+    // —— Day3 新增：历史双击回填 ——
+    QListWidgetItem* last = m_history->item(m_history->count() - 1);
+    if (!expectEq("最后一条历史", last->text(), QStringLiteral("(1+2) = 3"))) return false;
+    onHistoryDoubleClicked(last);
+    if (!expectEq("双击回填表达式区", m_calc->expressionText(), QStringLiteral("(1+2)"))) return false;
+
+    // —— Day3 新增：清空历史 ——
+    onClearHistory();
+    if (!expect("清空历史后 count==0", m_history->count() == 0)) return false;
+
+    // —— Day3 新增：关于 action 已创建并显式连接 ——
+    // （QMessageBox::about 是模态弹窗，离屏下不真正触发，GUI 弹窗验证靠现场演示）
+    if (!expect("关于 action 已创建", m_actAbout != nullptr)) return false;
+
+    return true;
+}

docs/teaching/examples/calculator_mainwindow/mainwindow.h

@@ -0,0 +1,59 @@
+// ============================================================================
+//  mainwindow.h —— Day3 上午版：把增强版计算器装进 QMainWindow
+//
+//  对应教案 OUTLINE_4DAY.md Day3 上午「QMainWindow / 对话框 QDialog」。
+//  本类只做「外壳」：菜单栏 / 状态栏 / 历史停靠窗 + 把 CalculatorDesigner
+//  作为中心部件 setCentralWidget。计算器面板本身的输入/求值逻辑一字未改
+//  （见 calculatordesigner.cpp）——这正是「界面外壳升级、核心部件不动」
+//  的关注点分离演示。
+//
+//  与 mainwindow_showcase 的风格对照（同为 Day3 上午教学载体）：
+//    - mainwindow_showcase：.ui 表单定义主窗体结构 + on_<obj>_<sig> 自动连接
+//    - 本例：纯代码建菜单/停靠窗 + 显式 connect()
+//  两种风格并列，前者突出「Designer 快速搭骨架」，后者突出「QAction 必须
+//  connect 才生效」（Day3 上午坑卡：菜单显示正常点了没反应）。
+// ============================================================================
+#ifndef CALCULATOR_MAINWINDOW_H
+#define CALCULATOR_MAINWINDOW_H
+
+#include <QMainWindow>
+
+class CalculatorDesigner;
+class QListWidget;
+class QListWidgetItem;
+class QDockWidget;
+class QAction;
+
+class MainWindow : public QMainWindow {
+    Q_OBJECT
+public:
+    explicit MainWindow(QWidget* parent = nullptr);
+    ~MainWindow() override;
+
+    // 离屏自测：复用 Day2 的 9 组计算用例 + Day3 新增（历史追加 / 双击回填 /
+    // 关于对话框触发）。返回全过为 true，供 main.cpp 决定退出码。
+    bool runSelfTest();
+
+private slots:
+    void onAbout();                                  // 帮助→关于：QMessageBox::about
+    void onClearHistory();                           // 编辑→清空历史
+    void onToggleHistoryVisible(bool checked);       // 视图→显示历史
+    void onEvaluated(const QString& expr, const QString& result);  // 计算器求值→追加历史
+    void onHistoryDoubleClicked(QListWidgetItem* item);            // 双击历史→回填表达式
+
+private:
+    void buildMenu();
+    void buildDock();
+    void buildStatusBar();
+    void refreshStatus(const QString& msg);
+
+    CalculatorDesigner* m_calc = nullptr;
+    QListWidget*        m_history = nullptr;
+    QDockWidget*        m_dock = nullptr;
+    QAction*            m_actQuit = nullptr;
+    QAction*            m_actClearHistory = nullptr;
+    QAction*            m_actToggleHistory = nullptr;
+    QAction*            m_actAbout = nullptr;
+};
+
+#endif  // CALCULATOR_MAINWINDOW_H

docs/teaching/examples/calculator_mainwindow/widget.ui

@@ -0,0 +1,200 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ui version="4.0">
+ <class>CalculatorForm</class>
+ <widget class="QWidget" name="CalculatorForm">
+  <property name="geometry">
+   <rect>
+    <x>0</x>
+    <y>0</y>
+    <width>358</width>
+    <height>320</height>
+   </rect>
+  </property>
+  <property name="windowTitle">
+   <string>计算器面板</string>
+  </property>
+  <layout class="QVBoxLayout" name="rootLayout">
+   <item>
+    <widget class="QTextEdit" name="expressionEdit">
+     <property name="minimumSize">
+      <size>
+       <width>0</width>
+       <height>50</height>
+      </size>
+     </property>
+     <property name="maximumSize">
+      <size>
+       <width>16777215</width>
+       <height>80</height>
+      </size>
+     </property>
+     <property name="readOnly">
+      <bool>true</bool>
+     </property>
+     <property name="alignment">
+      <set>Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter</set>
+     </property>
+    </widget>
+   </item>
+   <item>
+    <widget class="QLineEdit" name="display">
+     <property name="text">
+      <string>0</string>
+     </property>
+     <property name="alignment">
+      <set>Qt::AlignRight|Qt::AlignTrailing|Qt::AlignVCenter</set>
+     </property>
+     <property name="readOnly">
+      <bool>true</bool>
+     </property>
+    </widget>
+   </item>
+   <item>
+    <layout class="QGridLayout" name="keypadLayout">
+     <item row="0" column="0">
+      <widget class="QPushButton" name="btn7">
+       <property name="text">
+        <string>7</string>
+       </property>
+      </widget>
+     </item>
+     <item row="0" column="1">
+      <widget class="QPushButton" name="btn8">
+       <property name="text">
+        <string>8</string>
+       </property>
+      </widget>
+     </item>
+     <item row="0" column="2">
+      <widget class="QPushButton" name="btn9">
+       <property name="text">
+        <string>9</string>
+       </property>
+      </widget>
+     </item>
+     <item row="0" column="3">
+      <widget class="QPushButton" name="btnDiv">
+       <property name="text">
+        <string>÷</string>
+       </property>
+      </widget>
+     </item>
+     <item row="1" column="0">
+      <widget class="QPushButton" name="btn4">
+       <property name="text">
+        <string>4</string>
+       </property>
+      </widget>
+     </item>
+     <item row="1" column="1">
+      <widget class="QPushButton" name="btn5">
+       <property name="text">
+        <string>5</string>
+       </property>
+      </widget>
+     </item>
+     <item row="1" column="2">
+      <widget class="QPushButton" name="btn6">
+       <property name="text">
+        <string>6</string>
+       </property>
+      </widget>
+     </item>
+     <item row="1" column="3">
+      <widget class="QPushButton" name="btnMul">
+       <property name="text">
+        <string>×</string>
+       </property>
+      </widget>
+     </item>
+     <item row="2" column="0">
+      <widget class="QPushButton" name="btn1">
+       <property name="text">
+        <string>1</string>
+       </property>
+      </widget>
+     </item>
+     <item row="2" column="1">
+      <widget class="QPushButton" name="btn2">
+       <property name="text">
+        <string>2</string>
+       </property>
+      </widget>
+     </item>
+     <item row="2" column="2">
+      <widget class="QPushButton" name="btn3">
+       <property name="text">
+        <string>3</string>
+       </property>
+      </widget>
+     </item>
+     <item row="2" column="3">
+      <widget class="QPushButton" name="btnMinus">
+       <property name="text">
+        <string>-</string>
+       </property>
+      </widget>
+     </item>
+     <item row="3" column="0">
+      <widget class="QPushButton" name="btn0">
+       <property name="text">
+        <string>0</string>
+       </property>
+      </widget>
+     </item>
+     <item row="3" column="1">
+      <widget class="QPushButton" name="btnDot">
+       <property name="text">
+        <string>.</string>
+       </property>
+      </widget>
+     </item>
+     <item row="3" column="2">
+      <widget class="QPushButton" name="btnEquals">
+       <property name="text">
+        <string>=</string>
+       </property>
+      </widget>
+     </item>
+     <item row="3" column="3">
+      <widget class="QPushButton" name="btnPlus">
+       <property name="text">
+        <string>+</string>
+       </property>
+      </widget>
+     </item>
+     <item row="4" column="0">
+      <widget class="QPushButton" name="btnClear">
+       <property name="text">
+        <string>C</string>
+       </property>
+      </widget>
+     </item>
+     <item row="4" column="1">
+      <widget class="QPushButton" name="btnBackspace">
+       <property name="text">
+        <string>⌫</string>
+       </property>
+      </widget>
+     </item>
+     <item row="4" column="2">
+      <widget class="QPushButton" name="btnLeftParen">
+       <property name="text">
+        <string>(</string>
+       </property>
+      </widget>
+     </item>
+     <item row="4" column="3">
+      <widget class="QPushButton" name="btnRightParen">
+       <property name="text">
+        <string>)</string>
+       </property>
+      </widget>
+     </item>
+    </layout>
+   </item>
+  </layout>
+ </widget>
+ <resources/>
+ <connections/>
+</ui>