docs(M00): 记录WSL EMQX辅助入口

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 冒烟脚本入口、配置自检、可选 TLS/遗嘱/重复消息探测入口已生成 | `scripts/dev/wsl/check-local-mqtt.sh`、`scripts/dev/wsl/mqtt-smoke.sh` | 服务级可用；未配置本地账号时冒烟脚本 SKIP，认证/ACL/TLS/遗嘱/幂等需配置账号和下游证据后执行 |
+| WSL 本地 MQTT | EMQX 5.8.9 active/enabled，MQTTX CLI 1.13.0，五端口监听；认证/ACL 冒烟脚本入口、配置自检、可选 TLS/遗嘱/重复消息探测入口和 WSL EMQX 检查/启动/停止入口已生成 | `scripts/dev/wsl/check-local-mqtt.sh`、`scripts/dev/wsl/check-emqx.sh`、`scripts/dev/wsl/start-emqx.sh`、`scripts/dev/wsl/stop-emqx.sh`、`scripts/dev/wsl/mqtt-smoke.sh` | 服务级可用；未配置本地账号时冒烟脚本 SKIP，认证/ACL/TLS/遗嘱/幂等需配置账号和下游证据后执行 |
 
 ## 状态校准
 

docs/deployment-changelog.md

@@ -1,5 +1,17 @@
 # 部署变更记录
 
+## 2026-06-16 / V5.0-wsl-emqx-helpers
+
+- 关联模块：M00-C/WSL-001/IOT-001
+- 关联 commit：`a690e85`
+- 变化内容：补齐 `scripts/dev/wsl/check-emqx.sh`、`start-emqx.sh`、`stop-emqx.sh` 三个 WSL 本地 EMQX 辅助入口；`check-emqx.sh` 复用服务级 MQTT 基线检查。
+- 配置变化：无；脚本只操作 WSL 本地 systemd 服务，不安装、不降级、不重置 EMQX。
+- 数据库变化：无。
+- 兼容性：不影响生产 Ubuntu 菜单，不修改 `setup.sh`，不触发生产部署。
+- 已执行验证：待提交前执行 `bash -n scripts/dev/wsl/*.sh`、`check-emqx.sh`、Windows 总检查和敏感信息检查。
+- 回滚方式：移除新增三个 WSL 辅助脚本即可回到上一状态；不涉及生产配置。
+- 生产环境人工步骤：无；生产 EMQX 仍通过 Ubuntu `/opt/apps/setup.sh` 菜单和部署文档管理。
+
 ## 2026-06-16 / V5.0-baseline-local-mqtt
 
 - 关联模块：M00-C/M00-E/IOT-001

docs/deployment-status.md

@@ -14,20 +14,20 @@
 | Gitea 仓库 SSH | ssh://git@git.txyundm.cn:2222/panda/qipai.git |
 | 生产拉取仓库 | ssh://git@127.0.0.1:2222/panda/qipai.git |
 | 默认分支 | main |
-| 最近模块 push commit | `292ab7f`（M00-E 备份恢复检查模板） |
-| 最近 push 远端校验 | 通过：`HEAD == origin/main`（`292ab7f062d351f7791f2a12249fc27a25935679`） |
+| 最近模块 push commit | `847a28d`（M00-C MQTT 高级冒烟入口） |
+| 最近 push 远端校验 | 通过：`HEAD == origin/main`（`847a28da48cc4ffdaf9e102267c700815144c7f9`） |
 | 目标系统 | Ubuntu 24.04 |
 | 内核架构 | x86_64 |
 | DPKG 架构 | amd64 |
 | 用户空间位数 | 64 |
 | EMQX 版本/架构 | 菜单可检查；未安装/未验证 |
 | 服务器 MQTTX | 不安装 |
-| 命令行 MQTT 工具 | mosquitto-clients：未安装/未验证 |
+| 命令行 MQTT 工具 | WSL MQTTX CLI 1.13.0 已安装；mosquitto-clients 可选 |
 | Windows MQTTX 验证 | 未验证 |
-| WSL 环境验证 | 已完成轻量检查、shell 语法检查、临时副本准备和清理；本地 MQTT 服务级核验通过；完整构建待正式项目生成 |
+| WSL 环境验证 | 已完成轻量检查、shell 语法检查、临时副本准备和清理；本地 MQTT 服务级核验通过；V5.0 点名的 WSL EMQX 检查/启动/停止入口已补齐；完整构建待正式项目生成 |
 | 最近环境快检 | 2026-06-16 WSL 本地 MQTT 服务级核验通过；EMQX 5.8.9 active/enabled，MQTTX CLI 1.13.0，五端口监听；认证/ACL/TLS/协议仍未验收 |
 | 最近部署后复检 | 未执行 |
-| 最近验证 commit | `292ab7f`；备份恢复检查模板已推送并完成远端校验 |
+| 最近验证 commit | `a690e85`；WSL EMQX 辅助入口已本地验证，待推送后远端校验 |
 | 最近验证日期 | 2026-06-16 |
 | 已验证系统 | Ubuntu 24.04 / 未验证 |
 | 菜单 1 首次安装 | 脚本已实现目录布局；未在生产 Ubuntu 执行 |

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

@@ -7,6 +7,7 @@
 - 新增 `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 冒烟入口、可选 TLS/遗嘱/重复消息探测入口和 Git 忽略的本地账号配置样例。
+- 补齐 `check-emqx.sh`、`start-emqx.sh`、`stop-emqx.sh` 三个 V5.0 点名的 WSL 本地 EMQX 辅助脚本入口。
 
 ## 复用/改写/弃用判断
 
@@ -16,7 +17,7 @@
 
 ## 部署影响
 
-有。新增本地 MQTT 核验脚本和文档，不改动生产部署脚本，不安装或重置 EMQX。
+有。新增本地 MQTT 核验脚本和 WSL 辅助脚本入口，不改动生产部署脚本，不安装或重置 EMQX。
 
 ## 测试记录
 
@@ -24,6 +25,7 @@
 - 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` 发布证据。
+- WSL EMQX 辅助脚本：新增 `check-emqx.sh` 复用服务级基线检查，`start-emqx.sh`/`stop-emqx.sh` 仅管理本地 EMQX systemd 服务；脚本不安装、不降级、不重置 EMQX。
 - 敏感信息检查：已调整规则，空示例变量和 shell 参数展开不再误报，真实非占位长值仍会报警；`check-secrets.ps1` 通过。
 - Git 历史敏感模式扫描已执行，只记录命中提交，不输出秘密值。
 

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 | `874e811` | WSL 基础脚本已执行通过；本地 MQTT 服务级核验通过；认证/ACL 冒烟脚本入口、配置自检、可选 TLS/遗嘱/重复消息探测入口已生成，未配置账号时 SKIP。 | 正式后端/后台尚未生成，无法执行完整 Linux 构建；MQTT 本地账号未配置，认证/ACL/TLS/遗嘱/幂等未验收。 | M01/M09 生成项目后在 WSL 原生临时副本执行完整构建；配置本地 MQTT 最小权限账号后执行冒烟和可选探测。 |
+| WSL-001 | WSL 隔离辅助验证 | M00-C | PARTIAL | `a690e85` | WSL 基础脚本已执行通过；本地 MQTT 服务级核验通过；认证/ACL 冒烟脚本入口、配置自检、可选 TLS/遗嘱/重复消息探测入口已生成；V5.0 点名的 WSL EMQX 检查/启动/停止入口已补齐。 | 正式后端/后台尚未生成，无法执行完整 Linux 构建；MQTT 本地账号未配置，认证/ACL/TLS/遗嘱/幂等未验收；生产 EMQX 不由 WSL 脚本管理。 | 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 域名报告入口，但未做微信后台或真机验证。 | 微信后台/真机未验证。 | 后续导入小程序后执行合法域名和真机验证。 |

docs/module-status.md

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

docs/repository-completeness.md

@@ -11,5 +11,5 @@
 | 大文件 | WARN | `参考/mazongjian-server.xjar` 约 194MB，已记录哈希并作为大文件阻断项忽略。 |
 | 行尾/空白 | PASS | `scripts/dev/windows/test-all.ps1` 已运行，`git diff --check` 通过。 |
 | 忽略规则 | PASS | 真实 `backup/`、`backups/` 仍忽略；`deploy/backup/` 模板已放行并提交。 |
-| V5 基线文件 | PASS | 已新增 `docs/current-baseline.md`、`docs/local-dev-mqtt.md` 和 `scripts/dev/wsl/check-local-mqtt.sh`。 |
-| 远端一致性 | PASS | 最近一次 `git push origin main` 成功，`git fetch origin main` 后 `HEAD == origin/main`（`289b64d`）。 |
+| V5 基线文件 | PASS | 已新增 `docs/current-baseline.md`、`docs/local-dev-mqtt.md`、`scripts/dev/wsl/check-local-mqtt.sh` 和 V5 点名的 WSL 辅助脚本入口。 |
+| 远端一致性 | PASS | 最近一次 `git push origin main` 成功，`git fetch origin main` 后 `HEAD == origin/main`（`847a28d`）。 |

docs/workspace-status.md

@@ -18,6 +18,9 @@
 | `check-env.sh` | PASS | WSL2 x86_64 环境可用。 |
 | `check-workspace.sh` | PASS | `/mnt/d/qipai` 为 main 分支 Git 工作区。 |
 | `verify-linux.sh` | PASS | `setup.sh` 和 WSL 脚本 bash 语法通过。 |
+| `check-emqx.sh` | PASS | 复用本地 MQTT 服务级基线检查。 |
+| `start-emqx.sh` | 待需时执行 | 仅启动 WSL 本地 EMQX，不安装、不重置。 |
+| `stop-emqx.sh` | 待需时执行 | 仅停止 WSL 本地 EMQX，不影响生产。 |
 | `prepare-test-copy.sh` | PASS | 已复制到 WSL 原生 `~/qipai-wsl-test`。 |
 | `cleanup-test-copy.sh` | PASS | 临时副本已清理。 |
 | 完整 Linux 构建 | 未执行 | 当前尚无正式后端/后台项目依赖可构建。 |
@@ -29,4 +32,4 @@
 | EMQX | PASS | WSL 本地 `emqx` 包版本 `5.8.9`，服务 `active` 且 `enabled`。 |
 | MQTTX CLI | PASS | `/usr/local/bin/mqttx`，版本 `1.13.0`。 |
 | 端口监听 | PASS | `1883`、`8883`、`8083`、`8084`、`18083` 均监听。 |
-| 认证/ACL/TLS/协议 | 未完成 | 服务级健康不代表协议联调完成。 |
+| 认证/ACL/TLS/协议 | 未完成 | 已有可选冒烟入口；服务级健康不代表协议联调完成。 |

scripts/dev/wsl/check-emqx.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "INFO: checking WSL local EMQX through the MQTT baseline"
+"${SCRIPT_DIR}/check-local-mqtt.sh"

scripts/dev/wsl/start-emqx.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "INFO: starting WSL local EMQX service"
+
+if ! command -v systemctl >/dev/null 2>&1; then
+  echo "FAIL: systemctl not found; start EMQX manually in this WSL environment"
+  exit 1
+fi
+
+if ! dpkg-query -W emqx >/dev/null 2>&1; then
+  echo "FAIL: emqx package not found; this script does not install or reset EMQX"
+  exit 1
+fi
+
+if systemctl is-active --quiet emqx; then
+  echo "PASS: emqx service already active"
+  exit 0
+fi
+
+sudo systemctl start emqx
+systemctl is-active --quiet emqx && echo "PASS: emqx service active" || {
+  echo "FAIL: emqx service did not become active"
+  exit 1
+}

scripts/dev/wsl/stop-emqx.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "INFO: stopping WSL local EMQX service"
+
+if ! command -v systemctl >/dev/null 2>&1; then
+  echo "FAIL: systemctl not found; stop EMQX manually in this WSL environment"
+  exit 1
+fi
+
+if ! dpkg-query -W emqx >/dev/null 2>&1; then
+  echo "FAIL: emqx package not found; nothing to stop"
+  exit 1
+fi
+
+if ! systemctl is-active --quiet emqx; then
+  echo "PASS: emqx service already inactive"
+  exit 0
+fi
+
+sudo systemctl stop emqx
+if systemctl is-active --quiet emqx; then
+  echo "FAIL: emqx service is still active"
+  exit 1
+fi
+
+echo "PASS: emqx service stopped"