docs(M00): 记录MQTT高级冒烟入口

docs/current-baseline.md

@@ -15,7 +15,7 @@
 | 数据库迁移 | 仅有 `database/migrations/.gitkeep` 和 `database/seeds/.gitkeep` | 当前文件扫描 | 业务 schema 未生成 |
 | M00 部署脚本 | 已有菜单、状态、HTTPS、Certbot、EMQX、备份检查模板 | `setup.sh`、`scripts/setup/`、`deploy/` | PARTIAL，生产未执行 |
 | 参考资料 | 已有清单、脱敏日志、页面/接口/表结构摘要 | `docs/reference-*`、`docs/db-schema-inventory.md` | PARTIAL，仍需按模块迁移正式实现 |
-| WSL 本地 MQTT | EMQX 5.8.9 active/enabled，MQTTX CLI 1.13.0，五端口监听；认证/ACL 冒烟脚本入口和配置自检已生成 | `scripts/dev/wsl/check-local-mqtt.sh`、`scripts/dev/wsl/mqtt-smoke.sh` | 服务级可用；未配置本地账号时冒烟脚本 SKIP，认证/ACL 需配置账号后执行 |
+| WSL 本地 MQTT | EMQX 5.8.9 active/enabled，MQTTX CLI 1.13.0，五端口监听；认证/ACL 冒烟脚本入口、配置自检、可选 TLS/遗嘱/重复消息探测入口已生成 | `scripts/dev/wsl/check-local-mqtt.sh`、`scripts/dev/wsl/mqtt-smoke.sh` | 服务级可用；未配置本地账号时冒烟脚本 SKIP，认证/ACL/TLS/遗嘱/幂等需配置账号和下游证据后执行 |
 
 ## 状态校准
 
@@ -32,5 +32,6 @@
 ## 下一步
 
 1. 在本地被 Git 忽略的 `scripts/dev/wsl/mqtt-smoke.env` 中配置最小权限 MQTT 账号。
-2. 执行 `scripts/dev/wsl/mqtt-smoke.sh`，补齐认证、错误密码拒绝和 ACL 越权结果。
+2. 执行 `scripts/dev/wsl/mqtt-smoke.sh`，补齐认证、错误密码拒绝、ACL 越权、TLS 发布和遗嘱消息结果。
-3. 在 M01 开始前继续保持 M00 生产部署与本地调试基线可复验。
+3. 接入后端/设备消费者后，用重复 `idempotencyKey` 消息补齐幂等处理证据。
+4. 在 M01 开始前继续保持 M00 生产部署与本地调试基线可复验。

docs/devlogs/2026-06-16-M00-V5-基线核验.md

@@ -6,7 +6,7 @@
 - 恢复 `V4.8.md` 为上一版历史备份。
 - 新增 `docs/current-baseline.md`，按当前仓库事实校准模块完成度。
 - 新增 `docs/local-dev-mqtt.md` 和 `scripts/dev/wsl/check-local-mqtt.sh`，固化 WSL 本地 MQTT 服务级核验。
-- 升级 `scripts/dev/wsl/mqtt-smoke.sh`，新增 MQTTX CLI 认证/ACL 冒烟入口和 Git 忽略的本地账号配置样例。
+- 升级 `scripts/dev/wsl/mqtt-smoke.sh`，新增 MQTTX CLI 认证/ACL 冒烟入口、可选 TLS/遗嘱/重复消息探测入口和 Git 忽略的本地账号配置样例。
 
 ## 复用/改写/弃用判断
 
@@ -23,11 +23,12 @@
 - WSL 本地 MQTT 服务级核验：EMQX 包版本 `5.8.9`，服务 `active/enabled`，MQTTX CLI `/usr/local/bin/mqttx` 版本 `1.13.0`，端口 `1883/8883/8083/8084/18083` 均监听。
 - MQTT 冒烟脚本：已执行；未配置本地账号时输出 `SKIP`，不误报认证/ACL 通过。
 - MQTT 配置自检：新增 `--check-config`，本地账号存在时只确认配置，不打印口令；修正示例中的 `'$SYS/#'` 引号，已验证示例可在 `set -u` 下安全加载。
+- MQTT 高级探测入口：新增默认关闭的 `QIPAI_MQTT_ENABLE_TLS_SMOKE`、`QIPAI_MQTT_ENABLE_WILL_SMOKE`、`QIPAI_MQTT_ENABLE_IDEMPOTENCY_SMOKE`。无本地账号时仍输出 `SKIP`；有账号后可生成 TLS 发布、遗嘱观测尝试和重复 `idempotencyKey` 发布证据。
 - 敏感信息检查：已调整规则，空示例变量和 shell 参数展开不再误报，真实非占位长值仍会报警；`check-secrets.ps1` 通过。
 - Git 历史敏感模式扫描已执行，只记录命中提交，不输出秘密值。
 
 ## 风险
 
-- MQTT 认证账号、错误密码拒绝、ACL 越权拒绝、TLS、遗嘱消息和重复消息幂等尚未测试。
+- MQTT 认证账号、错误密码拒绝、ACL 越权拒绝、TLS、遗嘱消息和重复消息幂等尚未真实测试；当前只补齐了可选脚本入口。
 - 本地 `admin` 调试账号的具体用途尚未区分 Dashboard 与 MQTT 客户端认证；口令不得写入 Git。
 - WSL 服务级健康不代表生产 Broker 或真实硬件联调完成。

docs/feature-status.md

@@ -7,7 +7,7 @@
 | ENV-001 | 固定 Windows 工作区 | M00-A/M00-B | DONE | 远端 HEAD | 已确认 `D:\qipai`，Git 根、main 分支、固定 origin 和 push 校验通过。 | - | 后续每模块继续复检。 |
 | REF-001 | 参考资料完整纳管 | M00-A | PARTIAL | 本地 HEAD | 已生成哈希清单、脱敏日志、页面地图、接口线索和旧数据库结构清单；含秘密/依赖/真实数据风险的原始包和 SQL 已移出 Git 跟踪。 | 后续仍需按模块生成正式源码/迁移，旧 xjar 需大文件策略。 | 进入 M00-B/M00-C 前继续保持原包忽略和摘要可追溯。 |
 | SCM-001 | 模块完成即完整推送 | M00-B/M00-C | PARTIAL | 远端 HEAD | 首次 main push 成功，`HEAD == origin/main` 校验通过；推送脚本已生成。 | 后续模块仍需逐次执行并记录。 | 继续完善 M00-C 的 WSL 实际验证和脚本闭环。 |
-| WSL-001 | WSL 隔离辅助验证 | M00-C | PARTIAL | `4637e53` | WSL 基础脚本已执行通过；本地 MQTT 服务级核验通过；认证/ACL 冒烟脚本入口和配置自检已生成，未配置账号时 SKIP。 | 正式后端/后台尚未生成，无法执行完整 Linux 构建；MQTT 本地账号未配置，认证/ACL/TLS/协议未验收。 | M01/M09 生成项目后在 WSL 原生临时副本执行完整构建；配置本地 MQTT 最小权限账号后执行冒烟。 |
+| WSL-001 | WSL 隔离辅助验证 | M00-C | PARTIAL | `874e811` | WSL 基础脚本已执行通过；本地 MQTT 服务级核验通过；认证/ACL 冒烟脚本入口、配置自检、可选 TLS/遗嘱/重复消息探测入口已生成，未配置账号时 SKIP。 | 正式后端/后台尚未生成，无法执行完整 Linux 构建；MQTT 本地账号未配置，认证/ACL/TLS/遗嘱/幂等未验收。 | M01/M09 生成项目后在 WSL 原生临时副本执行完整构建；配置本地 MQTT 最小权限账号后执行冒烟和可选探测。 |
 | API-001 | 固定 HTTPS API 域名 | M00-E/M01/M08/M10 | PARTIAL | `4cb3ab6` | 已新增 Windows 检查脚本、Ubuntu 菜单检查和固定域名 Nginx 模板。 | DNS/HTTPS 生产验证未执行，后端健康接口未生成。 | 后续接入真实后端健康接口并执行 Windows/WSL/Ubuntu/微信真机验证。 |
 | TLS-001 | Nginx 与证书自动化 | M00-E/M10 | PARTIAL | `4cb3ab6` | 已生成 Nginx 模板、Certbot 命令说明和菜单第 4 项检查，可检查模板、站点启用、TLS、健康端点、证书文件、续期配置和 `certbot.timer`。 | 证书申请/续期 dry-run、80/443 生产验证未执行。 | 在生产 Ubuntu 执行证书签发、续期 dry-run 和 Nginx 安装记录。 |
 | WXNET-001 | 微信合法域名与真机验证 | M00-E/M08/M10 | TODO | - | 已补 API 域名报告入口，但未做微信后台或真机验证。 | 微信后台/真机未验证。 | 后续导入小程序后执行合法域名和真机验证。 |
@@ -15,5 +15,5 @@
 | OPS-002 | 单仓库 Gitea 推送与拉取部署 | M00-B/M10 | PARTIAL | 远端 HEAD | Windows 到 Gitea `origin/main` 首次 push 与远端校验通过。 | 生产服务器只读拉取部署尚未验证。 | M00-D/M00-E 继续完善生产拉取、菜单部署和状态检查。 |
 | OPS-003 | 整仓发布清单 | M00-E/M10 | PARTIAL | 本地 HEAD | `deploy-business.sh` 可生成 dry-run release manifest；正式构建待项目生成。 | 后端/后台尚未生成。 | M01/M09 后接入真实构建结果。 |
 | OPS-004 | 菜单式更新与环境监测 | M00-E/M10 | PARTIAL | `292ab7f` | `setup.sh` 已接入初始化、更新、MQTT、HTTPS、状态、备份、恢复、回滚和诊断菜单；`--backup-status` 已在 WSL 验证，可检查备份工具、目录和模板。 | 未在生产 Ubuntu 执行；真实备份配置未启用。 | 生产执行后补部署记录、真实备份和恢复演练记录。 |
-| IOT-001 | MQTT Broker 生产部署 | M00/M06 | PARTIAL | `a0b02ec` | 已生成 EMQX Ubuntu 安装说明、ACL 模板、授权模板、菜单第 3 项检查和 WSL MQTTX CLI 冒烟脚本。 | 缺生产 EMQX 安装、端口限制、真实账号、ACL/TLS 验收和实机验证；本地账号未配置。 | 生产执行后补 EMQX 版本、端口、ACL、备份和 MQTT 冒烟记录；本地继续补 TLS/遗嘱/幂等测试。 |
+| IOT-001 | MQTT Broker 生产部署 | M00/M06 | PARTIAL | `874e811` | 已生成 EMQX Ubuntu 安装说明、ACL 模板、授权模板、菜单第 3 项检查和 WSL MQTTX CLI 冒烟脚本；本地脚本已覆盖认证/ACL 入口和可选 TLS/遗嘱/重复消息探测入口。 | 缺生产 EMQX 安装、端口限制、真实账号、ACL/TLS 验收和实机验证；本地账号未配置，后端/设备幂等消费者未接入。 | 生产执行后补 EMQX 版本、端口、ACL、备份和 MQTT 冒烟记录；本地配置最小权限账号后跑完整冒烟。 |
 | SYS-001 | 微信原生小程序 | M00-C/M08 | TODO | - | - | 参考小程序压缩包尚未深度整理。 | 后续导入正式 `miniapp/`。 |

docs/local-dev-mqtt.md

@@ -41,6 +41,9 @@ bash scripts/dev/wsl/mqtt-smoke.sh
 - 允许订阅 Topic 连接检查。
 - 错误密码拒绝。
 - 越权订阅 Topic 探测。
+- 可选 TLS 发布探测。
+- 可选遗嘱消息观测探测。
+- 可选重复消息发布，用于下游幂等验证取证。
 
 如果未配置 `QIPAI_MQTT_USERNAME` 和 `QIPAI_MQTT_PASSWORD`，脚本会输出 `SKIP`，不得视为认证/ACL 已通过。
 
@@ -51,18 +54,21 @@ bash scripts/dev/wsl/mqtt-smoke.sh
 
 - `QIPAI_MQTT_DENIED_SUBSCRIBE_TOPIC` 默认值为 `'$SYS/#'`，必须保留引号，避免 shell 把 `$SYS` 当作本地变量展开。
 - `--check-config` 只确认本地账号配置存在，不打印口令，不执行 MQTT 连接。
+- `QIPAI_MQTT_ENABLE_TLS_SMOKE=true` 时会对 `QIPAI_MQTT_TLS_PROTOCOL://QIPAI_MQTT_TLS_HOST:QIPAI_MQTT_TLS_PORT` 执行一次发布探测；本地自签证书可临时使用 `QIPAI_MQTT_TLS_INSECURE=true`，生产验收必须提供 CA/证书链证据。
+- `QIPAI_MQTT_ENABLE_WILL_SMOKE=true` 时会尝试观测遗嘱消息；如果 MQTTX 退出路径被 Broker 视为正常断开，脚本会输出 `WARN`，仍需结合 Broker 和客户端故障日志验收。
+- `QIPAI_MQTT_ENABLE_IDEMPOTENCY_SMOKE=true` 时会向同一 Topic 连续发布相同 `idempotencyKey` 的消息；脚本只证明重复消息已发出，最终幂等必须由后端/设备日志证明。
 
 ## 验收边界
 
 端口监听正常只证明服务级可用，不能证明以下项目已完成：
 
-- TLS 证书链和客户端校验。
+- TLS 证书链和客户端校验；当前仅有可选发布探测入口。
 - MQTT 客户端认证账号实际可用性。
 - 错误密码拒绝实际结果。
 - ACL 越权拒绝实际结果。
 - MQTT 3.1 / QoS 1 业务协议联调。
-- 遗嘱消息。
+- 遗嘱消息；当前仅有可选观测探测入口。
-- 重复消息幂等。
+- 重复消息幂等；当前仅能发布重复消息，尚未接入下游消费断言。
 - 真实控制箱、门锁、插座执行结果。
 
 ## 账号记录规则

docs/module-status.md

@@ -2,7 +2,7 @@
 
 | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 |
 |---|---|---|---|---|
-| M00 单仓库与服务器基础骨架 | PARTIAL | `4637e53` | docs/devlogs/2026-06-16-M00-V5-基线核验.md | V5.0 已接入；已有成果基线、WSL 本地 MQTT 服务级核验、认证/ACL 冒烟入口和配置自检已补；生产部署、账号配置、TLS 和业务项目仍未完成。 |
+| M00 单仓库与服务器基础骨架 | PARTIAL | `874e811` | docs/devlogs/2026-06-16-M00-V5-基线核验.md | V5.0 已接入；已有成果基线、WSL 本地 MQTT 服务级核验、认证/ACL 冒烟入口、配置自检、可选 TLS/遗嘱/重复消息探测入口已补；生产部署、账号配置、真实验收和业务项目仍未完成。 |
 | M01 后端 API 基础工程 | TODO | - | - | 等 M00 基线完成后开始。 |
 | M02 登录、租户、权限 | TODO | - | - | - |
 | M03 门店、房间、价格、营业时间 | TODO | - | - | - |

scripts/dev/wsl/mqtt-smoke.env.example

@@ -15,3 +15,25 @@ QIPAI_MQTT_PASSWORD=
 QIPAI_MQTT_ALLOWED_PUBLISH_TOPIC=
 QIPAI_MQTT_ALLOWED_SUBSCRIBE_TOPIC=
 QIPAI_MQTT_DENIED_SUBSCRIBE_TOPIC='$SYS/#'
+
+# Optional TLS smoke. For local self-signed EMQX certificates only, keep
+# QIPAI_MQTT_TLS_INSECURE=true; production checks should provide CA/cert/key.
+QIPAI_MQTT_ENABLE_TLS_SMOKE=false
+QIPAI_MQTT_TLS_HOST=127.0.0.1
+QIPAI_MQTT_TLS_PORT=8883
+QIPAI_MQTT_TLS_PROTOCOL=mqtts
+QIPAI_MQTT_TLS_INSECURE=true
+QIPAI_MQTT_TLS_CA=
+QIPAI_MQTT_TLS_CERT=
+QIPAI_MQTT_TLS_KEY=
+
+# Optional will-message observation. It may warn if the CLI exits gracefully;
+# broker/client failure-path evidence must be confirmed from logs.
+QIPAI_MQTT_ENABLE_WILL_SMOKE=false
+QIPAI_MQTT_WILL_TOPIC=
+QIPAI_MQTT_WILL_MESSAGE=
+
+# Optional duplicate publish for downstream idempotency verification.
+QIPAI_MQTT_ENABLE_IDEMPOTENCY_SMOKE=false
+QIPAI_MQTT_IDEMPOTENCY_TOPIC=
+QIPAI_MQTT_IDEMPOTENCY_KEY=

scripts/dev/wsl/mqtt-smoke.sh

@@ -17,6 +17,17 @@ client_id="qipai-device-smoke-$(date +%s)"
 allowed_publish_topic="${QIPAI_MQTT_ALLOWED_PUBLISH_TOPIC:-qipai/${client_id}/status}"
 allowed_subscribe_topic="${QIPAI_MQTT_ALLOWED_SUBSCRIBE_TOPIC:-qipai/${client_id}/command/#}"
 denied_subscribe_topic="${QIPAI_MQTT_DENIED_SUBSCRIBE_TOPIC:-\$SYS/#}"
+enable_tls_smoke="${QIPAI_MQTT_ENABLE_TLS_SMOKE:-false}"
+enable_will_smoke="${QIPAI_MQTT_ENABLE_WILL_SMOKE:-false}"
+enable_idempotency_smoke="${QIPAI_MQTT_ENABLE_IDEMPOTENCY_SMOKE:-false}"
+tls_host="${QIPAI_MQTT_TLS_HOST:-$host}"
+tls_port="${QIPAI_MQTT_TLS_PORT:-8883}"
+tls_protocol="${QIPAI_MQTT_TLS_PROTOCOL:-mqtts}"
+tls_insecure="${QIPAI_MQTT_TLS_INSECURE:-false}"
+will_topic="${QIPAI_MQTT_WILL_TOPIC:-qipai/${client_id}/will}"
+will_message="${QIPAI_MQTT_WILL_MESSAGE:-{\"type\":\"will\",\"clientId\":\"${client_id}\"}}"
+idempotency_topic="${QIPAI_MQTT_IDEMPOTENCY_TOPIC:-qipai/${client_id}/status}"
+idempotency_key="${QIPAI_MQTT_IDEMPOTENCY_KEY:-smoke-${client_id}}"
 
 echo "INFO: MQTT smoke target ${protocol}://${host}:${port}, version ${mqtt_version}, qos ${qos}"
 
@@ -30,6 +41,30 @@ if ! command -v mqttx >/dev/null 2>&1; then
   exit 1
 fi
 
+is_true() {
+  case "${1:-}" in
+    true|TRUE|1|yes|YES|on|ON) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+append_tls_args() {
+  local -n target_args=$1
+
+  if [ -n "${QIPAI_MQTT_TLS_CA:-}" ]; then
+    target_args+=(--ca "$QIPAI_MQTT_TLS_CA")
+  fi
+  if [ -n "${QIPAI_MQTT_TLS_CERT:-}" ]; then
+    target_args+=(--cert "$QIPAI_MQTT_TLS_CERT")
+  fi
+  if [ -n "${QIPAI_MQTT_TLS_KEY:-}" ]; then
+    target_args+=(--key "$QIPAI_MQTT_TLS_KEY")
+  fi
+  if is_true "$tls_insecure"; then
+    target_args+=(--insecure)
+  fi
+}
+
 if [ ! -f "${SCRIPT_DIR}/mqtt-smoke.env" ]; then
   echo "WARN: local env not found: scripts/dev/wsl/mqtt-smoke.env"
   echo "INFO: copy scripts/dev/wsl/mqtt-smoke.env.example and fill local credentials outside Git"
@@ -49,6 +84,9 @@ fi
 if [ "$check_config_only" = true ]; then
   echo "PASS: local MQTT smoke configuration is present"
   echo "INFO: username configured; password is intentionally not printed"
+  echo "INFO: optional TLS smoke enabled: ${enable_tls_smoke}"
+  echo "INFO: optional will-message smoke enabled: ${enable_will_smoke}"
+  echo "INFO: optional idempotency smoke enabled: ${enable_idempotency_smoke}"
   exit 0
 fi
 
@@ -110,4 +148,74 @@ else
   echo "WARN: denied topic did not produce a clear authorization error; verify ACL manually"
 fi
 
-echo "INFO: will-message and idempotency checks are not automated yet"
+if is_true "$enable_tls_smoke"; then
+  tls_args=(
+    --hostname "$tls_host"
+    --port "$tls_port"
+    --protocol "$tls_protocol"
+    --mqtt-version "$mqtt_version"
+    --qos "$qos"
+    --username "$QIPAI_MQTT_USERNAME"
+    --password "$QIPAI_MQTT_PASSWORD"
+  )
+  append_tls_args tls_args
+
+  echo "INFO: verifying TLS publish target ${tls_protocol}://${tls_host}:${tls_port}"
+  mqttx pub "${tls_args[@]}" \
+    --client-id "${client_id}-tls" \
+    --topic "$allowed_publish_topic" \
+    --message "{\"type\":\"tls-smoke\",\"clientId\":\"${client_id}\"}" >/dev/null
+  echo "PASS: TLS publish accepted"
+else
+  echo "SKIP: optional TLS smoke disabled; set QIPAI_MQTT_ENABLE_TLS_SMOKE=true to run it"
+fi
+
+if is_true "$enable_idempotency_smoke"; then
+  echo "INFO: publishing duplicate idempotency key ${idempotency_key} to ${idempotency_topic}"
+  mqttx pub "${common_args[@]}" \
+    --client-id "${client_id}-idem-a" \
+    --topic "$idempotency_topic" \
+    --message "{\"type\":\"idempotency-smoke\",\"clientId\":\"${client_id}\",\"idempotencyKey\":\"${idempotency_key}\",\"sequence\":1}" >/dev/null
+  mqttx pub "${common_args[@]}" \
+    --client-id "${client_id}-idem-b" \
+    --topic "$idempotency_topic" \
+    --message "{\"type\":\"idempotency-smoke\",\"clientId\":\"${client_id}\",\"idempotencyKey\":\"${idempotency_key}\",\"sequence\":1}" >/dev/null
+  echo "PASS: duplicate idempotency messages published"
+  echo "INFO: downstream service/device logs must still prove the duplicate was handled idempotently"
+else
+  echo "SKIP: optional idempotency smoke disabled; set QIPAI_MQTT_ENABLE_IDEMPOTENCY_SMOKE=true to publish duplicates"
+fi
+
+if is_true "$enable_will_smoke"; then
+  will_capture="/tmp/qipai-mqtt-smoke-will-${client_id}.out"
+  rm -f "$will_capture"
+
+  echo "INFO: attempting will-message observation on ${will_topic}"
+  timeout 10 mqttx sub "${common_args[@]}" \
+    --client-id "${client_id}-will-listener" \
+    --topic "$will_topic" \
+    --output-mode clean \
+    --file-write "$will_capture" >/tmp/qipai-mqtt-smoke-will-sub.out 2>/tmp/qipai-mqtt-smoke-will-sub.err &
+  will_sub_pid=$!
+  sleep 2
+
+  timeout 3 mqttx sub "${common_args[@]}" \
+    --client-id "${client_id}-will-source" \
+    --topic "$allowed_subscribe_topic" \
+    --will-topic "$will_topic" \
+    --will-message "$will_message" \
+    --will-qos "$qos" \
+    --output-mode clean >/tmp/qipai-mqtt-smoke-will-source.out 2>/tmp/qipai-mqtt-smoke-will-source.err || true
+
+  sleep 3
+  if grep -Fq "$will_message" "$will_capture" 2>/dev/null; then
+    echo "PASS: will message observed"
+  else
+    echo "WARN: will message was not observed; MQTTX timeout may have closed gracefully, verify broker/client failure path manually"
+  fi
+
+  kill "$will_sub_pid" >/dev/null 2>&1 || true
+  wait "$will_sub_pid" >/dev/null 2>&1 || true
+else
+  echo "SKIP: optional will-message smoke disabled; set QIPAI_MQTT_ENABLE_WILL_SMOKE=true to attempt observation"
+fi