iotsaas/docs/产品管理模块设计.md

产品管理模块（Product & TSL & OTA）分析设计

状态：分析设计（待评审，先不开发） 日期：2026-09-19 目标：论证并设计中控屏/IoT 平台所需的"产品管理"能力（产品参数、物模型 TSL、固件 OTA）

---

1. 结论先行（建议）

非常需要，且应尽快立项。 当前系统是"设备直管"模式，缺少产品（Product）这一层抽象，导致物模型零散、固件无管理、新增设备类型成本高。引入 产品 → 设备 两级模型（对标涂鸦/阿里云 IoT 的 Product 概念）是平台标准化的必经之路，并能直接支撑中控屏标准控制 UI、场景、AI 控制、固件升级。

---

2. 现状与痛点

2.1 现状（代码事实）

• Device 实体（device 表）字段：deviceId, deviceName, platform, deviceType, manufacturer, model, firmwareVersion, status, capabilities(JSON), ..., homeId, roomId —— 无 productId。
• Device.capabilities：设备级 JSON，存"设备能力描述"，每个设备重复存静态能力，无产品级统一定义。
• AiDeviceProfile（ai_device_profile 表，iot-device 与 iot-rule 两侧都有）：设备级"指令码档案"（powerCode/brightnessCode/colorTempCode/temperatureCode/modeCode…），本质是物模型 DP 雏形，但按 deviceId 维度重复存储。
• Device.firmwareVersion：仅版本字符串，无固件库、无升级包、无 OTA 任务、无灰度/回滚。
• 涂鸦侧 TuyaDeviceDTO 有 productId/productName/category，但平台未把它沉淀为自有 Product 实体，仅在对接时透传。

2.2 痛点

1. 重复定义、难维护：同类设备（同型号）每个都重复存 capabilities / AiDeviceProfile 指令码，产品能力变更需逐设备改。
2. 无标准物模型：控制逻辑（DP 点、属性/事件/服务）散落在设备 JSON 与 AiDeviceProfile，AI 控制、场景、中控屏各自解析，易错且无法复用。
3. 固件无管理：只有版本号，无法上传/发布/下发/灰度/回滚固件，中控屏等设备的固件升级无法支撑。
4. 产品参数无沉淀：厂商/型号/品类/联网方式/配网/图标等散落，无法以"产品"维度统一管理和展示标准控制 UI。
5. 接入新设备类型成本高：每接一类设备都要改代码/前端，无法配置化。

---

3. 产品管理模块范围

能力	说明
产品基础信息	名称、品类(category)、厂商(manufacturer)、型号(model)、联网方式(wifi/ble/zigbee/matter)、配网方式、图标、说明、发布状态
物模型（TSL）	属性(Property)、事件(Event)、服务(Action) 三类功能点，含 DP 点定义与涂鸦/平台映射
固件管理（OTA）	固件版本库、升级包存储(md5)、发布、升级任务、灰度、回滚、设备当前版本追踪
平台映射	本平台 Product ↔ 涂鸦 productId 等（platform + platformProductId）
设备归属	Device 增加 productId，继承产品物模型与固件基线
接入/配网模板（二期）	标准化配网流程、设备自动归属产品

---

4. 与现有概念的关系（迁移策略）

现有	去向
Device.manufacturer / model	提升到 Product；Device 改为引用 productId（建议移除冗余，或保留只读快照防不一致）
Device.capabilities(JSON)	由 Product 物模型(TSL)生成，设备运行时状态另存（device_data/status），不再每设备存静态能力
AiDeviceProfile（设备级指令码）	下沉为 Product 物模型的 DP 定义（powerCode 等即产品的"开关属性"）；AI 控制/场景直接读产品物模型，设备不再单独存
涂鸦 productId	Product.platform + platformProductId 字段建立映射（一个平台产品 → 本平台一个 Product）
Device.firmwareVersion	保留为设备"当前版本"（运行时上报）；新增 firmware 表管理"可用版本库"，ota_task 记录目标版本

---

5. 数据模型设计

5.1 product（产品表）

字段	说明
id	PK
product_key	业务编码（如 P_LIGHT_001）
name	产品名称
category	品类（light/switch/ac/security…）
manufacturer	厂商
model	型号
platform	接入平台（tuya/local/matter…）
platform_product_id	涂鸦 productId 等映射
connect_type	wifi/ble/zigbee/matter
net_config_type	配网方式
icon	图标
description	说明
status	草稿/已发布
spec_version	当前物模型版本号
create_time / update_time	—

5.2 物模型（TSL）

推荐拆表（便于校验、UI 渲染、DP 映射），顶层用 spec_version 关联快照：

• product_property（属性）：id, product_id, code(如 switch_1), name, access(读/写/上报), type(bool/int/enum/float/string/json), min, max, step, unit, enum_list, dp_id(涂鸦DP映射), default_value, sort
• product_event（事件）：id, product_id, code, name, type(info/alert/fault), params(JSON)
• product_action（服务）：id, product_id, code, name, input(JSON), output(JSON)

可选：同时存一份 product.spec_json（完整 TSL 快照）便于缓存下发。

5.3 firmware（固件表）

字段	说明
id	PK
product_id	所属产品
version	固件版本
file_url	升级包地址
file_md5	校验
size	大小
release_note	更新说明
is_latest	是否最新
status	草稿/已发布
create_time	—

5.4 ota_task（升级任务）

字段	说明
id	PK
product_id	产品
firmware_id	目标固件
target_version	目标版本
scope	全部 / 指定设备 / 灰度%
device_ids	指定设备
status	进行中/完成/暂停/失败
success_count / fail_count	统计
create_time	—

5.5 Device 改造

• 新增 product_id（FK，关联 product.id）。
• 视情况移除 model/manufacturer 冗余（或保留只读快照）。
• firmwareVersion 保留为设备当前运行版本（上报）。

---

6. 接口设计（建议）

6.1 管理端（后台/管理员）

• POST/GET/PUT/DELETE /api/v1/products —— 产品 CRUD
• GET /api/v1/products/{id}/spec —— 物模型查询
• POST /api/v1/products/{id}/spec/properties 等 —— DP/事件/服务增删改
• POST /api/v1/products/{id}/firmware —— 上传固件
• GET /api/v1/products/{id}/firmwares —— 固件列表
• POST /api/v1/products/{id}/ota —— 创建升级任务
• GET /api/v1/ota-tasks/{id} —— 任务进度

6.2 设备/中控屏侧（复用）

• 设备详情返回 productId + 物模型（用于渲染标准控制 UI，不再依赖零散 capabilities）。
• 控制接口基于物模型 DP（统一语义）。
• 固件查询：设备上报/拉取最新固件版本，触发 OTA。

---

7. 固件 OTA 流程

1. 管理员上传固件到 Product → 生成 firmware 记录（version, url, md5）。
2. 创建 ota_task（目标版本 + 设备范围 / 灰度比例）。
3. 设备定期上报/查询最新固件（或平台主动推送升级指令）→ 下载升级 → 上报新 firmwareVersion → 任务统计。
4. 支持回滚（将上一版本 is_latest=false，重新下发任务）。

• 中控屏本身也是一类 Product，可纳入同一套 OTA 管理。

---

8. 分阶段实施

• P0 产品基础：product 表 + Device.productId 改造 + 产品 CRUD；按 model+manufacturer 自动归并或手动建产品，给存量设备回填 productId。
• P1 物模型：TSL（property/event/action）建模 + 管理接口；将 AiDeviceProfile / capabilities 迁移沉淀为产品物模型，AI 控制/场景改读产品物模型。
• P2 固件 OTA：✅ 已实现（2026-09-19）。后端 FirmwareService/Controller：固件注册(草稿)/发布(置最新)/最新版查询、升级任务创建(all/designated/gray 物化目标设备)/任务分页/详情/设备上报回调(回写 device.firmware_version、统计完成)/暂停。管理后台「设备管理→产品管理」含固件OTA面板（注册/发布/建任务/进度/暂停）。V13/V14 迁移已在开发库(iot-mysql 3386)执行，8 台涂鸦设备已 reconcile 归类为 8 个产品。
• P3 标准化控制：✅ 已实现（2026-09-20）。核心是「标准控制模型」ControlSchemaService：GET /api/v1/products/{id}/control-schema（产品级）与 GET /api/v1/devices/{deviceId}/control-schema（设备级，含 DP 当前值填充）。物模型→控件映射：bool→switch、int/float 有范围→slider、enum→segmented、其余→number/text；主开关自动识别（开关/电源/switch/power 优先，否则唯一可写 bool）。设备无产品时 available=false，客户端回退原有渲染。消费端：管理后台「物模型→控制预览」按模型渲染只读控件；Android DeviceControlActivity 优先拉后端模型渲染（ApiService.getDeviceControlSchema），失败/无模型回退涂鸦 schema（需 Android Studio 编译确认）。
• P4 高级：✅ 大部分已实现（2026-09-20）。版本回滚 POST /products/{id}/ota/rollback（不指定版本则回退上一个已发布版本）；灰度改为设备ID稳定哈希分组（同一设备恒在同一组，可配合不同版本做 A/B 对比）；统计看板 GET /ota-tasks/stats?productId=（任务数/进行中/完成/暂停、成功失败数、成功率、设备固件版本分布），管理后台 OTA 面板顶部为统计卡片 + 版本分布。未做：配网模板。

---

9. 风险与注意

• 存量迁移：设备需回填 productId（按 model+manufacturer 归并或人工关联）。
• 兼容性：保留 capabilities 读兼容，逐步切到产品物模型，避免一次性大改。
• 物模型版本：用 spec_version 管理，产品变更不影响已部署设备（设备绑定创建时的 spec 快照）。
• 涂鸦映射一致性：platformProductId 与涂鸦 productId 对齐，DP 映射字段 dp_id 准确。

---

10. 价值总结

引入产品层可一次性解决当前三大痛点：① 物模型统一（消除 capabilities/AiDeviceProfile 设备级重复）② 固件可管理（OTA）③ 设备类型配置化接入。同时为已规划的中控屏标准控制 UI、场景、AI 语音控制提供统一数据底座，是平台从"能连设备"走向"可运营 IoT 平台"的关键一步。

---

11. 已确认决策（2026-09-19 评审）

项	决策
存量设备回填	两者结合：系统按 model+platform 自动预归类生成建议产品与归属，管理员在后台确认/调整
Device 冗余字段	移除 Device.model / manufacturer，统一从 product 取（需同步改所有读写该字段的逻辑：DeviceController.createDevice、DeviceInfo DTO、AiDeviceProfile、前端设备卡片等）
物模型存储	拆表：product_property / product_event / product_action，每行一个 DP 点，含 dp_id 涂鸦映射与 spec_version
首期范围	P0 + P1 全做：产品基础 + Device.product_id + 存量回填 + 物模型（属性/事件/服务）建模与接口，并将 AiDeviceProfile / capabilities 下沉为产品物模型

11.1 开发前影响面排查（移除冗余字段必做）

• Device.model / manufacturer 读写点：DeviceController（create/update/query）、DeviceInfo/DeviceData 等 DTO、SQL 映射、前端设备详情/卡片展示。
• AiDeviceProfile 下沉：iot-device 写入、iot-rule 读取（AI 控制翻译）需改为读产品物模型；迁移脚本把存量 deviceId 级指令码归并到所属产品的 property。
• capabilities 兼容：保留读兼容，新设备改由产品物模型生成；提供回填/转换脚本。

12. 实现进度（2026-09-19，P0+P1 基础）

12.1 已完成（可编译，已通过 LSP）

• SQL backend/sql/V13__add_product_module.sql：新建 product / product_property / product_event / product_action / firmware / ota_task 六表；device 表新增 product_id 列（保留原 model/manufacturer 兼容快照，未物理删除）。
• 实体 + Mapper：6 个实体与 6 个 BaseMapper（纯新增）。
• ProductService / Impl：产品 CRUD、物模型查询与增删改、resolveProductId（按平台信息解析/自动建产品）、reconcileDevices（存量设备按 model+platform 自动归类回填 product_id）。
• ProductController POST/GET/PUT/DELETE /api/v1/products、/products/{id}/spec、/properties|events|actions、/reconcile、/resolve。
• Device / DeviceInfo 增加 productId；TuyaDeviceAdapter.getDeviceInfo 回填 productId（设备详情可返回所属产品）。

12.2 未做（高风险，单列计划，未破坏现有功能）

1. ✅ 移除 Device.model/manufacturer 冗余（D）：V14 给 device 加 platform_product_id（承接塞进 model 列的涂鸦 productId）、迁移存量、再 DROP COLUMN model/manufacturer。Device 实体删两字段加 platformProductId；TuyaController 改设 platformProductId；reconcileDevices 改按 platform+platformProductId 归类；DeviceInfo 的 model/manufacturer 改为从 product 取（TuyaDeviceAdapter 注入 ProductMapper）→ 前端零改动。
2. ✅ AiDeviceProfile 下沉产品级（C，向后兼容）：ai_device_profile 加 product_id。iot-device 探测与 iot-rule 解析/保存全部改为优先读产品级、推断落产品级；旧设备级作 fallback。AiDeviceView 加 productId。
3. ✅ 设备同步自动关联（B）：TuyaController 创建/更新涂鸦设备时自动 resolveProductId 设 device.product_id。
4. ✅ capabilities 由物模型生成：DeviceServiceImpl.getDeviceInfo 改为依据设备所属 product + product_property 动态推导能力描述（product 元数据 + 每个功能点 code/name/type/access/writable/min/max/step/unit/enum/default），取代各 adapter 硬编码能力（如 LocalDeviceAdapter 的 switch/brightness/color）；device.capabilities 列仅保留 dps 运行时态；无产品时回退 adapter 自带能力。前端无引用，零改动。

验证：后端 mvn -pl iot-device,iot-rule -am compile 通过（exitCode 0）。存量设备 productId 回填与产品创建由部署后执行 POST /api/v1/products/reconcile 完成（已基于 platformProductId）。