微应用按需读取与资源加载

本章面向建筑群、建筑单元和业务空间微应用的开发与维护人员，按 2.00.083 源码契约说明。启用前确认目标前后端与数据库能力，不把文档发布当作平台已升级。

确定范围和最少字段

总览优先读取告警、在线／离线和少量关键业务状态（如运行、占用、故障）。先确定当前组织、正式位置范围或实际绑定设备，再使用 POST /thinklink/device/find-page-by-fields。

{
  "current": 1,
  "pageSize": 50,
  "location_code_subtree": "<当前建筑的位置编码>",
  "fields": ["online"],
  "alarm_detail": false
}

占位符需替换为当前组织真实位置。每行固定返回 eui、alarm_status、alarm_desc；其他内容按需选择。需要编辑设备时显式请求 id，需要名称或归组时再加 name、location_code。

• fields 选择基础字段、计算字段 online 或完整 transform_3d。属性及遥测使用独立选择器，不能将 telemetry_data 当作物理列塞入 fields。
• server_attrs、shared_attrs、process_data 使用字段名数组或 true（整组）；telemetry_data 按物模型 ID 选择字段或整模型，例如 {"<物模型ID>":["temperature"]}。省略表示不请求，不能用 false 或 null 代替省略。
• 总览不默认请求完整配置、整组属性、全量遥测或 alarm_detail:true。选中建筑、空间、设备后再读取详情。
• 本级范围使用原列表的 location_code，包含后代使用 location_code_subtree。位置树按完整 path 边界判断，不能对 code 做前缀匹配。业务空间按实际绑定确定设备范围，不默认等于位置子树。
• 普通查询沿用当前组织与 PUBLIC 可见性；子树分支额外限定当前组织。调用方仍须明确所需范围，不能把所有无子树查询宣称为仅当前组织。空绑定或不存在的位置不能回退到整个组织。

完整分页与失败状态

返回 {data,total,current,pageSize}。需要完整建筑或空间汇总时，按 total 完整分页，按 EUI 去重并检查范围覆盖。第一页不能代表所有设备；任何一页失败、结果过期或中途范围改变时，都不能将部分结果标为完整汇总。

alarm_status 是每台设备当前告警按等级的计数，alarm_desc 是描述集合；它们不是位置子树统计接口。online 根据 active_time 和两倍 heart_period 计算，任一缺失时为 false，不能无条件等同于自定义 _online。

未请求、未加载、加载失败、数据过期及字段缺失必须分别保留状态，不能补为正常、无告警、0 或 false。按键投影会省略 JSON null；需要区分 null 与缺失时读取完整数据组或专用接口。本分页接口读取持久化数据，find-device-data 读取当前缓存，脚本刚更新时两者可能不同。

数据复用和资源缓存

同一组织、范围及字段集合的请求在卡片和视图之间复用。缓存键包含组织、范围和字段；切换组织或范围后不能复用旧范围的汇总。名称、模型、空间绑定和 transform_3d 与高频状态分开加载。可靠订阅覆盖的字段可合并增量更新，但不能假定新增字段已有 MQTT 推送。

模型、贴图、图片、视频和文档通过文件管理 API上传及替换。先查 quota，配置保存文件 ID；使用时获取 access-ticket，按有效期续取，再通过 /v/:ticket 读取。单文件及组织合计均为 50 MiB。资源按场景加载并复用，不随每次状态轮询重复下载。替换后依据 update_time 或资源版本使缓存失效并重新加载；匿名访问必须明确开启共享。

应用验收

核对实际请求范围和字段、全部分页、空绑定、缺失字段和失败状态；检查跨卡片重复请求、票据过期、关闭共享、替换资源后展示。保留既有应用 ID、配置、路由、菜单与业务权限，并在实际托管页面验证；本地构建或上传成功不能代替托管验收。