From 07790a7924fde3717b838ea1748434c1bc46f9dd Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 22 Jun 2026 17:27:24 +0800 Subject: [PATCH] =?UTF-8?q?docs(M06-A):=20=E8=AE=B0=E5=BD=95MQTT=E5=9F=BA?= =?UTF-8?q?=E7=A1=80=E9=AA=8C=E6=94=B6=E5=B9=B6=E6=8E=A8=E8=BF=9B=E8=AE=BE?= =?UTF-8?q?=E5=A4=87=E8=B5=84=E4=BA=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 6 ++-- .../2026-06-22-M06-A-mqtt-health.md | 12 +++++++ docs/configuration.md | 9 +++++ docs/current-baseline.md | 6 ++-- docs/deployment-changelog.md | 12 +++++++ .../2026-06-22-M06-A-Broker与MQTT基础.md | 35 +++++++++++++++++++ docs/feature-status.md | 2 +- docs/module-status.md | 12 +++---- docs/mqtt-deployment.md | 30 +++++++++++----- docs/mqtt-protocol-mapping.md | 16 +++++---- docs/unresolved-issues.md | 1 + 11 files changed, 113 insertions(+), 28 deletions(-) create mode 100644 docs/api-changelog/2026-06-22-M06-A-mqtt-health.md create mode 100644 docs/devlogs/2026-06-22-M06-A-Broker与MQTT基础.md diff --git a/README.md b/README.md index 86d2a37..d059020 100644 --- a/README.md +++ b/README.md @@ -120,9 +120,9 @@ WSL 已验证：EMQX `5.8.9`、MQTTX CLI `1.13.0`、EMQX 服务 `active (running 项目已开发部分模块。具体完成度不得从 README 猜测，必须以现有代码、测试、数据库迁移、Git 历史以及 `docs/current-baseline.md`、`docs/module-status.md`、`docs/feature-status.md` 为准。 -- 当前执行游标：`M06-A` -- 最近工程提交：`1680d73`，完成 M05-D 收款账户、接收方、比例策略和幂等分账。 -- 下一工程目标：M06-A Broker 与 MQTT 基础。 +- 当前执行游标：`M06-B` +- 最近工程提交：`c140613`，完成 M06-A MQTT 3.1/QoS 1、重连订阅恢复、健康检查、正式 Topic ACL 和菜单 3 安装/更新入口。 +- 下一工程目标：M06-B 设备资产、能力和拓扑。 ## 版本递进 diff --git a/docs/api-changelog/2026-06-22-M06-A-mqtt-health.md b/docs/api-changelog/2026-06-22-M06-A-mqtt-health.md new file mode 100644 index 0000000..749642f --- /dev/null +++ b/docs/api-changelog/2026-06-22-M06-A-mqtt-health.md @@ -0,0 +1,12 @@ +# M06-A MQTT 健康状态 API + +- `GET /app-api/ready` +- `GET /admin-api/ready` + +`checks` 新增： + +- `mqttConfigured`：MQTT 用户名和密码均已配置。 +- `mqttConnected`：后端当前与 Broker 真实连接。 +- `mqttSubscriptionsReady`：两个设备上行 Topic 已成功订阅。 + +健康接口不返回 Broker 凭据、Client ID 或错误堆栈。 diff --git a/docs/configuration.md b/docs/configuration.md index 9f9cfa4..ec22ade 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -61,6 +61,15 @@ MYSQL_DATABASE=<以项目实际数据库名为准> 检测结果只能使用 `PASS/WARN/FAIL`，不得回显密码。只有五项全部通过，数据库环境才可标记 `DONE`。 +## MQTT 后端连接 + +- 生产变量：`QIPAI_MQTT_URL`、`QIPAI_MQTT_CLIENT_ID`、`QIPAI_MQTT_USERNAME`、`QIPAI_MQTT_PASSWORD`。 +- 调优变量：`QIPAI_MQTT_RECONNECT_MS=3000`、`QIPAI_MQTT_CONNECT_TIMEOUT_MS=10000`、`QIPAI_MQTT_MAX_MESSAGE_BYTES=65536`。 +- 生产账号固定建议为 `qipai_backend_prod`；真实密码只写 `/etc/qipai/qipai.secrets`，不得进入 Git、日志或错误响应。 +- 用户名和密码必须同时配置；生产环境缺任一项时后端拒绝启动。 +- 后端使用 MQTT 3.1（`protocolVersion: 3`）和 QoS 1，订阅 `/devicesend/+`、`/devicewill/+`，发布 `/deviceaccept/{DeviceID}`。 +- `/app-api/ready`、`/admin-api/ready` 返回 `mqttConfigured`、`mqttConnected`、`mqttSubscriptionsReady`，只有真实连接并恢复订阅后后两项才为真。 + ## 微信支付 v3 - 运行变量：`QIPAI_WECHAT_PAY_CREDENTIALS`。 diff --git a/docs/current-baseline.md b/docs/current-baseline.md index a58d0d2..0406a75 100644 --- a/docs/current-baseline.md +++ b/docs/current-baseline.md @@ -1,15 +1,15 @@ # 当前开发成果基线 > V5.0 首次核验日期：2026-06-16 -> audited_commit: `6c506ff` -> next_engineering_target: M05-B 接入微信支付、退款和对账 +> audited_commit: `c140613` +> next_engineering_target: M06-B 设备资产、能力和拓扑 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。 ## 总体结论 | 范围 | 当前状态 | 证据 | 结论 | |---|---|---|---| -| 总纲版本 | V5.3 已成为当前权威总纲，V5.2/V5.1/V5.0/V4.8 已保留为历史备份 | 根目录存在 `V5.3.md`、`V5.2.md`、`V5.1.md`、`V5.0.md` 和 `V4.8.md` | 可继续按 V5.3 的执行游标开发 | +| 总纲版本 | V5.4 已成为当前权威总纲，旧版已保留为历史备份 | 根目录存在 `V5.4.md` 及旧版总纲 | 可继续按 V5.4 的执行游标开发 | | Git 远端 | `origin=ssh://git@git.txyundm.cn:2222/panda/qipai.git`，分支 `main` | `git rev-list main...origin/main` 为 `0 0` | 本地与远端同步 | | 正式后端 | 已完成 Fastify、迁移兼容、outbox/worker、多应用租户、微信身份/会话，以及六角色 RBAC 和门店范围 | `backend/src/auth/**`、`database/migrations/2026061805_m02c_rbac.*.sql`、`backend/tests/**` | M01、M02-A/B/C DONE；MySQL 已验证 capability 和跨租户门店授权拒绝；下一阶段 M02-D | | 后台管理端 | 仅有 `admin/.gitkeep` | 当前文件扫描 | M09 未开始，不能标记 DONE | diff --git a/docs/deployment-changelog.md b/docs/deployment-changelog.md index bf11c92..5f79366 100644 --- a/docs/deployment-changelog.md +++ b/docs/deployment-changelog.md @@ -1,5 +1,17 @@ # 部署变更记录 +## 2026-06-22 / M06-A-mqtt-foundation + +- 关联模块：M06-A/IOT-001 +- 关联 commit：`c140613` +- 变化内容：菜单 3 从只读检查扩展为管理员确认后安装/更新 EMQX；新增正式厂商 Topic ACL；后端接入 MQTT.js 3.1/QoS 1、重连、订阅恢复与健康检查。 +- 配置变化：新增 MQTT Client ID、重连间隔、连接超时和消息大小环境变量；生产必须配置成对的 MQTT 用户名与密码。 +- 数据库变化：无。 +- 兼容性：健康接口只新增检查字段；未配置 MQTT 凭据的开发/测试环境不启动连接，生产环境缺凭据会拒绝启动。 +- 已执行验证：Windows 全量回归、WSL Bash 语法、WSL EMQX 5.8.9 服务级检查通过；认证冒烟因本地账号缺失按预期 SKIP。 +- 回滚方式：回退工程 commit，并恢复旧 ACL 模板；生产若已应用配置，先备份 EMQX 数据和配置后再回滚。 +- 生产环境人工步骤：在 `101.42.38.246` 执行菜单 3，创建 `qipai_backend_prod` 和设备账号，应用 ACL，限制 18083，执行备份和三个 Topic 冒烟。 + ## 2026-06-16 / V5.0-status-doc-guard - 关联模块：M00-B/SCM-001 diff --git a/docs/devlogs/2026-06-22-M06-A-Broker与MQTT基础.md b/docs/devlogs/2026-06-22-M06-A-Broker与MQTT基础.md new file mode 100644 index 0000000..4bf6dc5 --- /dev/null +++ b/docs/devlogs/2026-06-22-M06-A-Broker与MQTT基础.md @@ -0,0 +1,35 @@ +# M06-A Broker 与 MQTT 基础 + +- 日期：2026-06-22 +- 起始 commit：`a8c3e7d` +- 工程 commit：`c140613` +- ENGINEERING_DELTA=YES +- 子阶段状态：PARTIAL/BLOCKED_EXTERNAL；可独立工程内容已完成并 push，游标推进 M06-B + +## 工程增量 + +- 引入 MQTT.js 5.15.1，固定 MQTT 3.1（`protocolVersion: 3`）和 QoS 1。 +- 后端启动时连接 Broker，使用持久会话、3 秒自动重连，并在每次连接后显式恢复 `/devicesend/+`、`/devicewill/+`。 +- 下行只允许 `/deviceaccept/{DeviceID}`；DeviceID 校验限制为安全字符和 64 字符以内。 +- 上下行消息默认限制 64 KiB；超限上行拒绝进入后续处理，超限下行不发布。 +- ready 接口新增 MQTT 已配置、真实连接和订阅恢复三层状态。 +- 生产环境要求 MQTT 用户名和密码成对存在，缺失时拒绝启动，凭据不写日志。 +- 菜单 3 支持管理员选择安装/更新 EMQX，并检查架构、systemd、端口、包架构和服务器未安装 MQTTX。 +- ACL 切换为正式三个厂商 Topic，后端账号和单设备账号使用最小权限。 + +## 验证 + +- `npm test`：退出码 0，M01-A 至 M05-D 全量回归及 M06-A MQTT 测试通过。 +- `scripts/dev/windows/test-all.ps1`：代码测试、构建、迁移计划、工作区和文档一致性通过；新文件暂存前完整性门禁按预期提示，显式暂存后复检通过。 +- WSL `bash -n`：`setup.sh`、`scripts/setup/emqx.sh`、`mqtt-smoke.sh` 退出码 0。 +- WSL EMQX：5.8.9、active/enabled、1883/8883/8083/8084/18083 均通过。 +- WSL MQTT 认证冒烟：因本地 Git 忽略凭据未配置而 `SKIP`，未伪造通过。 +- 工程 commit 已 push，`HEAD == origin/main == c1406137186d857c81180eb3643d385d05e3bb03`。 + +## 外部阻塞 + +生产 Ubuntu 的 EMQX 安装、正式账号、ACL、端口限制、备份和真实发布订阅尚未由管理员执行；M06-A 因此保持 `PARTIAL/BLOCKED_EXTERNAL`，但不阻塞 M06-B 设备资产模型。 + +## 后续 + +执行游标进入 M06-B：设备资产、能力和拓扑。 diff --git a/docs/feature-status.md b/docs/feature-status.md index 9d67610..dcd6f6e 100644 --- a/docs/feature-status.md +++ b/docs/feature-status.md @@ -16,7 +16,7 @@ | OPS-002 | 单仓库 Gitea 推送与拉取部署 | M00-B/M10 | PARTIAL | 远端 HEAD | Windows 到 Gitea `origin/main` 首次 push 与远端校验通过。 | 生产服务器只读拉取部署尚未验证。 | M00-D/M00-E 继续完善生产拉取、菜单部署和状态检查。 | | OPS-003 | 整仓发布清单 | M00-E/M10 | PARTIAL | `59d92c0` | `deploy-business.sh --dry-run` 可在 Windows/WSL 验证当前 HEAD 的 release manifest 结构；`check-release-manifest.ps1` 已接入 `test-all.ps1`；正式构建待项目生成。 | 后端/后台尚未生成，生产菜单未执行。 | M01/M09 后接入真实构建结果，并在生产菜单 2 生成真实 release manifest。 | | OPS-004 | 菜单式更新与环境监测 | M00-E/M10 | PARTIAL | `292ab7f` | `setup.sh` 已接入初始化、更新、MQTT、HTTPS、状态、备份、恢复、回滚和诊断菜单；`--backup-status` 已在 WSL 验证，可检查备份工具、目录和模板。 | 未在生产 Ubuntu 执行；真实备份配置未启用。 | 生产执行后补部署记录、真实备份和恢复演练记录。 | -| IOT-001 | MQTT Broker 生产部署 | M00/M06 | PARTIAL | `874e811` | 已生成 EMQX Ubuntu 安装说明、ACL 模板、授权模板、菜单第 3 项检查和 WSL MQTTX CLI 冒烟脚本；本地脚本已覆盖认证/ACL 入口和可选 TLS/遗嘱/重复消息探测入口。 | 缺生产 EMQX 安装、端口限制、真实账号、ACL/TLS 验收和实机验证；本地账号未配置，后端/设备幂等消费者未接入。 | 生产执行后补 EMQX 版本、端口、ACL、备份和 MQTT 冒烟记录；本地配置最小权限账号后跑完整冒烟。 | +| IOT-001 | MQTT Broker 生产部署 | M00/M06 | PARTIAL | `c140613` | 菜单 3 已支持 Ubuntu 24.04 amd64 原生安装/更新与复检；正式 Topic ACL 已固定；后端实现 MQTT.js 3.1、QoS 1、持久会话、自动重连、订阅恢复、消息上限和真实连接健康状态；Windows 全量测试通过，WSL EMQX 5.8.9 服务级检查通过。 | 缺生产 EMQX 安装、正式账号、ACL/端口/备份验收；WSL 本地账号未配置，认证冒烟按预期 SKIP。 | 由管理员在生产菜单 3 执行并登记结果；提供本地最小权限账号后完成错误密码、ACL、TLS、遗嘱和三个 Topic 冒烟。 | | SYS-001 | 微信原生小程序 | M00-C/M08 | PARTIAL | `c658b09` | 微信原生基础模板、固定生产 API 配置和开发者工具项目配置已纳管；JSON 与 JavaScript 静态语法检查通过。 | 当前仅为基础模板，登录、门店、订单和多角色业务页面尚未接入。 | 保持 M03-C 当前游标；到 M08 基于现有模板实现完整业务，不重复初始化。 | | CFG-001 | 小程序品牌自定义 | M02-A/M03/M08 | PARTIAL | `8b8fb28` | 已建立 AppID/tenant 品牌配置表和 `/app-api/bootstrap`；同一 AppID 两租户隔离读取在 MySQL 8.4.9 实测通过。 | Logo/分享图片上传与小程序实际展示属于后续阶段。 | M03/M08 接入配置管理和小程序展示。 | | BKG-010 | 后台多小程序管理 | M02-A/M08/M10 | PARTIAL | `8b8fb28` | 已建立逻辑应用、租户绑定和租户配置模型；多租户 AppID 未指定租户会被拒绝。 | 尚无后台管理页面，多 AppID 真机配置未验证。 | M02-B/C 完成身份权限，M08 增加管理页面。 | diff --git a/docs/module-status.md b/docs/module-status.md index 8cffb02..b2e9f6a 100644 --- a/docs/module-status.md +++ b/docs/module-status.md @@ -3,15 +3,15 @@ ```yaml execution_cursor: current_module: M06 - current_stage: M06-A + current_stage: M06-B stage_status: TODO - last_completed_stage: M05-D - next_stage: M06-A - last_engineering_commit: 1680d73 + last_completed_stage: M06-A + next_stage: M06-B + last_engineering_commit: c140613 last_push_verified: true base_branch: main blocked_reason: "" - updated_at: 2026-06-22T19:30:00+08:00 + updated_at: 2026-06-22T20:25:00+08:00 ``` | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 | @@ -22,7 +22,7 @@ execution_cursor: | M03 门店、房间、价格、营业时间 | DONE | `d563078` | docs/devlogs/2026-06-18-M03-D-场景码NFC与WiFi.md | M03-A/B/C/D 已完成门店房间、装修广告、媒体、地图选店、场景码/NFC 页面导航和受控 Wi-Fi；真实微信小程序码图片生成留待 M08 真机联调。 | | M04 订单、时段锁定、支付闭环 | DONE | `91801fe` | docs/devlogs/2026-06-20-M04-D-订单分享.md | M04-A/B/C/D 已完成可信定价、并发预占、订单状态机、续费取消换房、管理员调整、代下单和最小权限分享；Windows 全量回归与 WSL MySQL 8.4.9 模块回归通过。 | | M05 会员、余额、套餐、优惠券 | PARTIAL | `1680d73` | docs/devlogs/2026-06-22-M05-D-分账与收款配置.md | M05-A/B/C/D 工程闭环已完成：统一支付、微信支付退款、团购直订、门店收款账户、分账接收方、比例策略、授权门禁、幂等分账和对账查询均通过 Windows 与 WSL MySQL 回归；真实微信/团购/分账权限未提供，模块保持 PARTIAL/BLOCKED_EXTERNAL。 | -| M06 设备、MQTT 与真实硬件联动 | TODO | - | - | - | +| M06 设备、MQTT 与真实硬件联动 | PARTIAL | `c140613` | docs/devlogs/2026-06-22-M06-A-Broker与MQTT基础.md | M06-A 已完成 MQTT.js 3.1/QoS 1、重连与订阅恢复、健康检查、消息大小限制、正式 Topic ACL 和菜单 3 安装/更新入口；生产 EMQX、正式账号与 ACL 尚未现场执行，继续 M06-B。 | | M07 保洁、通知、任务和语音播报 | TODO | - | - | - | | M08 微信原生小程序完整业务 | TODO | - | - | - | | M09 后台管理端完整业务 | TODO | - | - | - | diff --git a/docs/mqtt-deployment.md b/docs/mqtt-deployment.md index f9ee044..09b2e48 100644 --- a/docs/mqtt-deployment.md +++ b/docs/mqtt-deployment.md @@ -3,18 +3,33 @@ | 项目 | 当前值 | |---|---| | Broker 主机 | 101.42.38.246 | -| Broker 软件 | EMQX 5.x，待安装/验证 | +| Broker 软件 | EMQX 5.x（最低 5.3），待生产安装/验证 | | 安装方式 | Ubuntu Apt 原生安装，禁止 Docker | | 安装说明 | `deploy/emqx/install-ubuntu24-amd64.md` | | MQTTX | 服务器不安装，Windows 可使用 | | 命令行工具 | mosquitto-clients 可选 | | 匿名连接 | 待验证关闭 | -| ACL | 已生成 `deploy/emqx/acl.conf.template`，生产未应用 | +| ACL | 已按三个厂商 Topic 固定 `deploy/emqx/acl.conf.template`，生产未应用 | | 授权配置 | 已生成 `deploy/emqx/authorization.hocon.template`，生产未应用 | | 1883 | 菜单第 3 项/`setup.sh --mqtt` 可检查，生产未验证 | | 18083 | 菜单第 3 项/`setup.sh --mqtt` 可检查；必须限制访问，生产未验证 | -| 备份 | 待生成 | -| 恢复 | 待生成 | +| 备份 | 菜单 6 已检查 EMQX 导出能力与备份目录；生产导出演练待执行 | +| 恢复 | `deploy/backup/backup-restore-runbook.md` 已有入口；生产恢复演练待执行 | + +## 菜单 3 行为 + +- 先检查 Ubuntu 架构、EMQX 包、systemd、自启、1883/18083、ACL 模板和服务器是否误装 MQTTX。 +- 未安装时可由管理员输入 `I`，已安装时可输入 `U`；脚本使用 EMQX 官方 Apt 安装脚本并执行 `apt-get install -y emqx`。 +- Codex 不远程执行生产安装。账号、密码及认证数据只从 `/etc/qipai/qipai.secrets` 建立，脚本和日志不打印凭据。 + +## 后端 MQTT 基础 + +- MQTT.js `5.15.1`，协议固定 MQTT 3.1（`protocolVersion: 3`）。 +- QoS 1；订阅 `/devicesend/+`、`/devicewill/+`，发布 `/deviceaccept/{DeviceID}`。 +- 持久会话、3 秒自动重连、每次连接后显式恢复订阅。 +- 默认消息上限 65536 字节，超限上行拒绝进入业务处理，超限下行不发布。 +- `/app-api/ready` 与 `/admin-api/ready` 分别返回 MQTT 是否配置、是否连接、订阅是否恢复。 +- 生产环境缺少 MQTT 账号或密码时拒绝启动；真实值只写 `/etc/qipai/qipai.secrets`。 ## WSL 本地开发 Broker @@ -29,8 +44,7 @@ | 认证/ACL 冒烟入口 | `scripts/dev/wsl/mqtt-smoke.sh`，本地账号文件 `scripts/dev/wsl/mqtt-smoke.env` 不入库 | | 验收边界 | 未配置本地 MQTT 账号前，认证、ACL、TLS、遗嘱消息、重复消息幂等和真实硬件联调未完成 | -## 当前 M00 结论 +## 当前 M06-A 结论 -- 已提供 EMQX Ubuntu 24.04 amd64 原生安装说明、ACL 模板和授权模板。 -- 菜单第 3 项已扩展为检查 EMQX 命令、systemd 服务、1883/18083 端口和模板文件。 -- 未在生产 Ubuntu 安装 EMQX，未创建真实设备账号，未执行真实 MQTT 发布/订阅。 +- 已提供可选择安装/更新的 Ubuntu 24.04 amd64 菜单、正式 Topic ACL、后端连接生命周期和可复现单元测试。 +- 未在生产 Ubuntu 安装 EMQX，未创建真实设备账号，未执行生产发布/订阅，因此 IOT-001 保持 `PARTIAL/BLOCKED_EXTERNAL`。 diff --git a/docs/mqtt-protocol-mapping.md b/docs/mqtt-protocol-mapping.md index 1cc7fe9..882d282 100644 --- a/docs/mqtt-protocol-mapping.md +++ b/docs/mqtt-protocol-mapping.md @@ -1,17 +1,19 @@ # MQTT 协议映射 -当前尚未完成厂商协议深度录入。M00 仅提供 EMQX ACL 安全基线，后续 M06 必须以正式协议文档为准，记录 Topic、命令、字段、回包、超时、重试和审计要求。 +M06-A 已按正式协议固定 MQTT Topic、QoS 和客户端权限；具体命令字段、回包、超时和重试在 M06-C/D/E 继续录入。 | 设备 | Topic/命令 | 方向 | 字段 | 状态 | |---|---|---|---|---| -| 4G 智能门禁控电箱 | 待补充 | 双向 | 待补充 | TODO | -| Sub-1G 智能门锁 | 待补充 | 双向 | 待补充 | TODO | -| 4G 智慧插座 | 待补充 | 双向 | 待补充 | TODO | +| 4G 智能门禁控电箱 | `/devicesend/{DeviceID}`、`/devicewill/{DeviceID}`、`/deviceaccept/{DeviceID}` | 双向 | M06-C/D 补命令字段 | PARTIAL | +| Sub-1G 智能门锁 | 经父控制箱使用相同三个 Topic | 双向 | M06-C/D 补 `subID/subtype` 与命令字段 | PARTIAL | +| 4G 智慧插座 | `/devicesend/{DeviceID}`、`/devicewill/{DeviceID}`、`/deviceaccept/{DeviceID}` | 双向 | M06-C/E 补命令字段 | PARTIAL | -## M00 ACL 基线 +## M06-A ACL 基线 | 客户端 | 允许发布 | 允许订阅 | 状态 | |---|---|---|---| -| 设备客户端 `qipai-device-*` | `qipai/${clientid}/telemetry`、`qipai/${clientid}/status`、`qipai/${clientid}/event/#` | `qipai/${clientid}/command/#` | 模板已生成，M06 精化 | -| 后端服务 `qipai_backend` | `qipai/+/command/#` 等业务命令与事件主题 | 设备遥测、状态和事件主题 | 模板已生成，M06 精化 | +| 设备客户端 `qipai-device-{DeviceID}`，用户名等于 DeviceID | `/devicesend/{DeviceID}`、`/devicewill/{DeviceID}` | `/deviceaccept/{DeviceID}` | 模板已固定，生产未应用 | +| 后端服务 `qipai_backend_prod` | `/deviceaccept/+` | `/devicesend/+`、`/devicewill/+` | 模板已固定，生产未应用 | | 普通客户端 | 禁止 `$SYS/#`、`#`、`+/#` | 禁止未显式允许主题 | 模板已生成 | + +后端 MQTT.js 固定使用 MQTT 3.1（`protocolVersion: 3`）、QoS 1、持久会话、自动重连，并在每次连接成功后显式恢复两个上行订阅。单条应用消息默认限制为 64 KiB。 diff --git a/docs/unresolved-issues.md b/docs/unresolved-issues.md index e9fdd7f..a03bcf2 100644 --- a/docs/unresolved-issues.md +++ b/docs/unresolved-issues.md @@ -13,3 +13,4 @@ | ISSUE-009 | 2026-06-22 | M05-B/ORD-001 | 微信支付 v3 真实预支付、通知、退款和账单下载尚未联调。 | 高 | 已完成请求签名、JSAPI 参数、原始通知体验签、AES-GCM 解密、幂等记账、全额/部分退款、退款状态推进、人工处理失败状态和对账记录；使用生成密钥与可控传输完成协议测试。 | 缺真实商户号、APIv3 Key、商户私钥、平台证书及可用商户环境。 | 用户提供凭据后写入 `/etc/qipai/qipai.secrets`，在生产回调域名完成小额支付、重复通知、部分退款、全额退款和账单下载验收。 | BLOCKED_EXTERNAL | | ISSUE-010 | 2026-06-22 | M05-C/GRP-001/GRP-002 | 美团/点评、抖音等团购核销与直订未完成真实平台联调。 | 高 | 已完成统一适配器、人工/Mock/API 核销、券码哈希、重复核销幂等、HMAC 回调、映射、人工队列和认领成单；后台配置与记录 API 已具备。 | 缺平台商家授权、Token、正式签名协议和回调测试环境。 | 获取授权后新增厂商专用适配器并执行验券、重复推送、取消和异常重试验收。 | BLOCKED_EXTERNAL | | ISSUE-011 | 2026-06-22 | M05-D/FRN-001 | 微信支付真实分账尚未联调。 | 高 | 已完成收款账户、接收方、比例策略、授权门禁、成功支付校验、API 请求签名、幂等批次、失败人工处理和查询；Mock 仅限非生产。 | 缺微信支付服务商/分账权限、已授权接收方和生产商户凭据。 | 取得权限后登记环境接收方映射，执行小额支付后多接收方分账、重复请求和失败对账验收。 | BLOCKED_EXTERNAL | +| ISSUE-012 | 2026-06-22 | M06-A/IOT-001 | 生产 EMQX、正式 MQTT 客户端账号和 ACL 尚未现场验收。 | 高 | 已完成菜单 3 安装/更新、正式 Topic ACL、后端 MQTT 3.1/QoS 1、重连、订阅恢复、健康检查、消息限制和 Mock 客户端测试；WSL EMQX 服务级检查通过。 | Codex 不自动操作生产 Ubuntu，且尚无生产 MQTT 账号；WSL 本地最小权限账号也未配置。 | 管理员在 `101.42.38.246` 执行菜单 3 并建立账号/ACL；提供 Git 忽略的本地账号后执行错误密码、越权、TLS、遗嘱和三个 Topic 冒烟。 | BLOCKED_EXTERNAL |