# device_model_docs

**Repository Path**: fangye945a/device_model_docs

## Basic Information

- **Project Name**: device_model_docs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 设备模型管理设计文档集

> 文档版本：V1.0
> 编制日期：2026-07-22
> 适用范围：RK3506 ARMv7、Buildroot/OpenHarmony Linux、musl、约 512 MB RAM 的 Linux 控制器
> 文档状态：研发基线建议稿

## 1. 文档目的

本目录给出设备模型资产化、动态导入和安全激活的产品与技术基线，用于指导产品、前端、Go 后端、DSDK 服务、设备模型 SDK、测试和运维人员协同开发。

文档基于以下现有工程的公开接口、构建入口和代码调用关系整理，不修改这些工程：

- DSDK 服务框架：`dsdk_service`
- CT16 设备模型开发 SDK：`sdk_release`
- Linux 控制器 Web 工程：`zaiohDeviceWorkSpace`
- MCU 设备模型参考工程：`zaiohController`

## 2. 文档导航

| 文档 | 主要读者 | 解决的问题 |
|---|---|---|
| [设备模型管理 PRD](device-model-management-prd.md) | 产品、研发、测试、项目交付 | 做什么、为什么做、业务规则和验收标准 |
| [设备模型管理概要设计](device-model-management-high-level-design.md) | 前端、Go 后端、DSDK、测试 | 模块如何拆分、接口如何定义、关键流程如何落地 |
| [设备模型管理架构设计](device-model-management-architecture.md) | 架构师、技术负责人、核心开发 | 系统边界、运行时关系、ABI、可靠性和演进策略 |

## 3. 架构图

README 直接加载 PNG，确保 Gitee 网页可以预览。交互式 HTML 支持深浅主题、节点检索、关系查看、缩放和导出；SVG 和 Archify JSON 用于离线查看与后续维护。

### 3.1 系统总体架构

![设备模型管理系统总体架构](diagrams/device-model-system.png)

[交互式 HTML](diagrams/device-model-system.html) · [SVG](diagrams/device-model-system.svg) · [Archify JSON](diagrams/device-model-system.architecture.json)

### 3.2 导入、激活与回滚时序

![设备模型导入、激活与回滚时序](diagrams/model-import-activation.png)

[交互式 HTML](diagrams/model-import-activation.html) · [SVG](diagrams/model-import-activation.svg) · [Archify JSON](diagrams/model-import-activation.sequence.json)

### 3.3 修订生命周期

![设备模型修订生命周期](diagrams/model-revision-lifecycle.png)

[交互式 HTML](diagrams/model-revision-lifecycle.html) · [SVG](diagrams/model-revision-lifecycle.svg) · [Archify JSON](diagrams/model-revision-lifecycle.lifecycle.json)

## 4. 核心结论

1. 不引入 `modelId` 或其他不可读的资产 ID。设备模型由三元组 `(type, vendor, model)` 唯一标识。
2. `version` 是展示和兼容说明，不参与唯一性判断；同版本内容变化通过规范化 ZIP 的 SHA-256 `revisionDigest` 区分。
3. `sn` 继续作为设备实例唯一键。Web 模块只管理模型资产，不承担设备实例编排和控制调度。
4. 一份 ZIP 只描述一个三元组，包含一个 SO、接口物模型、控制物模型、状态物模型和清单文件。
5. 首期不做进程内热卸载。激活时原子替换部署 SO，重启 `dsdk_service`，完成健康检查；失败时恢复上一修订并再次重启。
6. 每个三元组最多保留当前修订和上一稳定修订。新导入、在线编辑都生成新修订，不原地篡改历史内容。
7. 无法确认厂商和型号时使用 `identityMode=project`：固定 `vendor=project`，`model` 由项目编码和项目别名生成；相似模型只推荐，不自动合并。
8. 云平台首期仅保留 `CloudRepository` 接口和禁用态 UI，不定义真实云协议，不制造“已同步”假状态。
9. SHA-256 只证明文件完整性，不能证明来源可信。首期只允许受信网络中的已认证管理员导入；包签名作为后续安全增强。

## 5. “当前”与“目标”标记

三份文档统一使用以下表述，评审时不得混用：

- **当前已实现**：能够在现有代码中找到对应入口和行为。
- **本期目标**：本轮设备模型管理研发必须完成的能力。
- **后续规划**：已预留边界，但不纳入本期验收。

## 6. 建议评审顺序

1. 产品、项目交付、测试先评审 PRD 中的身份规则、项目模型、覆盖/删除和验收标准。
2. DSDK 与 SDK 团队评审插件 ABI、单模型包约束、健康检查和重启回滚契约。
3. Web 前后端评审 REST API、错误码、上传限制、修订并发和页面状态。
4. 架构与安全负责人评审可信边界、SO 风险、审计和未来签名升级路径。
5. 完成接口冻结后再拆分研发任务，避免前后端继续沿用现有 mock 数据结构。

## 7. 本期非交付项

- 不修改或生成 MCU 固件。
- 不实现云平台模型库的上传、下载、鉴权和冲突协议。
- 不实现第三方不可信 SO 的强隔离执行。
- 不实现运行中 SO 的 `dlclose`、无进程重启热替换或跨架构二进制转换。
- 不替代现有设备实例配置、现场接线和业务应用编排模块。

## 8. 术语速查

| 术语 | 含义 |
|---|---|
| 设备模型 | 三元组、版本、描述、SO、接口/控制/状态物模型组成的可交付资产 |
| 模型键 `ModelKey` | `(type, vendor, model)`，模型的业务唯一键 |
| 修订摘要 `revisionDigest` | 规范化 ZIP 内容的 SHA-256，用于区分同一模型的不同内容 |
| 设备实例 | 现场某一具体设备，继续由 `sn` 标识 |
| 标准模型 | 能确认厂商、型号，`identityMode=standard` 的可通用模型 |
| 项目模型 | 厂商/型号未知，按项目临时命名，`identityMode=project` 的模型 |
| 当前修订 | 最近一次导入或编辑产生的候选修订，可能未激活或激活失败 |
| 上一修订 | 当前修订之前保留的稳定修订，主要用于回滚 |
| 激活 | 将指定修订部署给 DSDK 服务并经重启、健康检查后投入使用 |