docs(M06-B): 记录设备拓扑验收并推进协议适配

2026-06-22 17:42:08 +08:00
parent 74a67ac92d
commit c96045f6ef
7 changed files with 76 additions and 11 deletions
@@ -0,0 +1,11 @@
+# M06-B 设备资产与拓扑 API
+
+- `GET /admin-api/devices`
+- `POST /admin-api/devices`
+- `GET /admin-api/device-topology`
+- `POST /admin-api/device-channels`
+- `POST /admin-api/device-links`
+- `POST /admin-api/devices/:id/status`
+- `POST /admin-api/devices/:id/maintenance`
+
+接口要求有效管理会话和 `device.read`/`device.write`、`tenant.manage` 或平台管理员权限；门店管理员只能访问授权门店。
@@ -1,8 +1,8 @@
 # 当前开发成果基线

 > V5.0 首次核验日期：2026-06-16  
-> audited_commit: `c140613`
-> next_engineering_target: M06-B 设备资产、能力和拓扑
+> audited_commit: `74a67ac`
+> next_engineering_target: M06-C 协议适配器和消息幂等
 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。

 ## 总体结论
@@ -0,0 +1,16 @@
+# M06-B 设备资产与拓扑数据库变更
+
+- 迁移版本：`2026062219`
+- 名称：`m06b_device_topology`
+
+## 变更
+
+- 增量扩展 `qipai_devices` 的 ICCID、型号、固件、信号、能力、快照、心跳和维护状态。
+- 新增 `qipai_device_channels`、`qipai_device_links`、`qipai_device_status_snapshots`、`qipai_device_alerts`、`qipai_device_maintenance_records`。
+- 新增 `device.read`、`device.write` 权限并授予既有门店/租户/平台管理员角色。
+- 唯一键阻止设备重复绑定、Sub-1G 拓扑冲突及房间负载重复控制。
+
+## 验证与回滚
+
+- WSL MySQL 8.4.9 临时库完成 `up → verify → down → up → verify`。
+- down 迁移先移除权限和子表，再移除 `qipai_devices` 新增列，不删除旧设备表。
@@ -0,0 +1,36 @@
+# M06-B 设备资产、能力和拓扑
+
+- 日期：2026-06-22
+- 起始 commit：`07790a7`
+- 工程 commit：`74a67ac`
+- ENGINEERING_DELTA=YES
+- 子阶段状态：DONE，工程 commit 已 push 且 `HEAD == origin/main`
+
+## 工程增量
+
+- 扩展设备资产：DeviceID、IMEI、ICCID、类型、型号、固件、信号、能力、状态快照、心跳和维护状态。
+- 新增控制通道模型，支持控制箱 SLOT1/2/3 和智慧插座 MAIN 等通道映射房间负载。
+- 同一租户/房间/控制目标只允许一个通道，控制箱插槽与智慧插座不能重复控制同一负载。
+- 新增控制箱父设备与 Sub-1G 门锁子设备关系，约束门锁唯一父设备、父设备下 subID 唯一、房间同类门锁唯一。
+- 新增状态快照、开放告警和维护记录结构，拓扑接口统一返回资产、通道、父子关系、告警和维护记录。
+- 新增 `device.read`、`device.write`，租户管理员、平台管理员和门店管理员按门店范围使用。
+- 新增设备入库、列表、拓扑、通道绑定、Sub-1G 绑定、状态写入和维护记录 API。
+
+## 验证
+
+- Windows `npm test`：退出码 0，M01-A 至 M06-B 全量契约回归通过。
+- Windows `scripts/dev/windows/test-all.ps1`：退出码 0，仓库、敏感信息、构建、测试、迁移计划和文档一致性门禁通过。
+- WSL MySQL 8.4.9 原生临时副本：`up → verify → down → up → verify` 通过。
+- 迁移语句：up 98、verify 70、down 92。
+- 实测控制箱 `ROOM_POWER` 绑定后，智慧插座重复绑定同一目标返回冲突；Sub-1G 父子关系、能力排序、ONLINE 状态、快照和维护状态均通过。
+- 工程 commit 已 push，`HEAD == origin/main == 74a67ac92d7687abeb9cd4f697efe312eac0c2f9`。
+
+## 数据库与兼容性
+
+- 新迁移：`2026062219_m06b_device_topology`。
+- 旧 `qipai_devices` 保留并增量扩展；旧设备数据不删除。
+- 回滚先删除 M06-B 子表和设备权限，再移除新增设备列与索引。
+
+## 后续
+
+执行游标进入 M06-C：协议适配器和消息幂等。
@@ -38,3 +38,5 @@
 | GRP-003 | 管理员验券 | M05-C/M08 | PARTIAL | `cda640b` | 已提供后台人工验券、配置、映射和记录查询 API，门店数据范围校验生效，券码列表只返回脱敏值。 | 管理员小程序扫码界面待 M08，真实平台核销待授权。 | M08 接入扫码界面；授权后切换 API 模式。 |
 | FRN-001 | 加盟商与自动分账 | M05-D/M10/M08 | PARTIAL | `1680d73` | 已实现租户/门店收款账户、商户号、环境凭据引用、分账授权状态、接收方哈希脱敏、比例总和校验、支付后幂等分账和明细查询；未授权不能开启，生产环境 Mock 强制关闭。 | 缺微信支付服务商和分账权限，尚未执行真实分账。 | M10/M08 补加盟流程与界面；取得权限后执行真实分账与对账。 |
 | BKG-007 | 后台微信支付配置 | M05-D/M08 | PARTIAL | `1680d73` | 已提供收款账户、分账接收方、门店/全局比例策略和授权状态 API；私钥、APIv3 Key 和接收方真实标识只使用环境引用，查询仅返回脱敏信息。 | Vue 后台页面待 M08；真实商户与服务商授权未提供。 | M08 接入响应式配置页面；授权后完成生产验收。 |
+| DEV-003 | 设备管理 | M06-B/M08 | PARTIAL | `74a67ac` | 已实现 DeviceID/IMEI/ICCID/型号/固件/信号/能力资产，控制箱通道、智慧插座负载、Sub-1G 父子拓扑、状态快照、开放告警和维护记录查询；门店数据范围生效。 | 尚无后台/手机页面，在线状态仍需 M06-C/G 由真实消息更新。 | M06-C 接入协议消息与幂等；M08 实现响应式界面。 |
+| BKG-004 | 后台设备管理 | M06-B/M08 | PARTIAL | `74a67ac` | 已提供设备入库、列表、拓扑、通道绑定、Sub-1G 绑定、状态和维护 API；同一房间控制目标唯一，控制箱与智慧插座重复负载被数据库拒绝。 | Vue 后台页面和真实设备扫码入库待 M08/M06-G。 | M06-C/D/E 接入协议后补真实状态；M08 实现管理页面。 |
@@ -3,15 +3,15 @@
 ```yaml
 execution_cursor:
  current_module: M06
-  current_stage: M06-B
+  current_stage: M06-C
  stage_status: TODO
-  last_completed_stage: M06-A
-  next_stage: M06-B
-  last_engineering_commit: c140613
+  last_completed_stage: M06-B
+  next_stage: M06-C
+  last_engineering_commit: 74a67ac
  last_push_verified: true
  base_branch: main
  blocked_reason: ""
-  updated_at: 2026-06-22T20:25:00+08:00
+  updated_at: 2026-06-22T21:05: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 与真实硬件联动 | 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。 |
+| M06 设备、MQTT 与真实硬件联动 | PARTIAL | `74a67ac` | docs/devlogs/2026-06-22-M06-B-设备资产与拓扑.md | M06-A/B 已完成 MQTT 基础、设备资产、能力、控制通道、Sub-1G 父子拓扑、状态快照、告警/维护结构和门店权限；生产 Broker 与真实硬件仍待联调，继续 M06-C。 |
 | M07 保洁、通知、任务和语音播报 | TODO | - | - | - |
 | M08 微信原生小程序完整业务 | TODO | - | - | - |
 | M09 后台管理端完整业务 | TODO | - | - | - |