透明装修直播方案：用乐橙云 API 做工地实时监控与业主互动（实战）

---

去年夏天，某家装品牌在热搜上挂了一天：业主称「照片里的吊顶和现场不一样」。公关忙到凌晨，工程部却拿不出带时间戳的连续画面——只有监理手机里的零散照片和微信群聊天记录。那次复盘后，我们定了一条产品原则：透明装修不是多拍几张图，而是让业主随时能看、能问、能留痕。

---

装修是典型的 长周期、低频次、高信任成本 服务。业主怕偷工减料、怕工人偷懒、怕材料偷换；装企怕扯皮、怕投诉、怕口碑反噬。行业里的「透明」往往停留在：

• 监理每周发九宫格；
• 微信群丢几张现场图；
• 偶尔开一次视频通话。

这些方式不可检索、不可授权、不可规模化。当工地从几十个涨到几百个，装企需要一套 设备云 + 业务系统 的能力：设备在线可查、直播按户签发、历史可回放、互动可审计。

乐橙开放平台面向 要把乐橙 IPC 能力接进自己产品 的开发者：绑定与资产同步、实时拉流、云录像查询、对讲（端能力/SDK/小程序 RTMP 路径）等，都走现行 OpenAPI 体系（勿使用文档里「旧版本协议、不再维护」栏目下的接口；设备列表用 listDeviceDetailsByPage，不用停维护的 deviceList）。

我们划定的 MVP

能力	业主侧感知	技术实现
工地直播	小程序/H5「看我家」	bindDeviceLive / FLV 回放
在线状态	「施工中 / 离线」	分页同步 deviceStatus
历史片段	「昨天有没有施工」	getCloudRecords + 录播 HLS
互动	语音提醒工人（受控）	RTMP 对讲链路 / SDK
权限	只看自家工地	业务层映射 + 子账号

不做第一期：AI 识别是否贴砖、自动判违规——留给算法团队第二期。

总体架构

工地 IPC → 乐橙云 → 装企后端（OpenAPI）→ 业主小程序 / H5
                         ↑
              项目/合同/工地/设备 映射表
                         ↑
                   监理 App / 工单

密钥与签名只在装企服务端；业主端只拿 短时播放凭证 或自家 session token。

---

1. 数据模型：合同—工地—机位

contract（业主合同）
   └── site（工地）
          └── camera（deviceId + channelId + 机位名：客厅/水电/泥木）

新工地进场 SOP：配网 → 绑定开发者账号 → 分页列表验收 online → 写入映射表。我们曾因为监理用私人号在 App 里加设备，导致 listDeviceDetailsByPage 同步不到，业主端一直「暂无画面」——现在绑定必须走公司开发者主账号或 bindDevice。

2. 资产同步与「能不能看」

async function syncSiteCamera(token, deviceId) {
  const data = await platformCall('listDeviceDetailsByPage', {
    token, pageSize: 10, page: 1, source: 'bind',
  });
  const dev = data.deviceList?.find((d) => d.deviceId === deviceId);
  if (!dev || dev.deviceStatus !== 'online') {
    return { ok: false, reason: 'offline' };
  }
  const ch = dev.channelList?.[0];
  return {
    ok: ch?.channelStatus === 'online',
    csStatus: ch?.csStatus, // using 时可开云录像留痕
    ability: dev.deviceAbility,
  };
}

业主首页展示：在线绿点 / 离线灰点；csStatus 为 using 时展示「云端留存已开通」标签，降低「怕扯皮没证据」的焦虑。

3. 业主看直播：签发 HLS（5 分钟跑通）

async function openOwnerLive(token, deviceId, channelId, ownerId) {
  assertOwnerCanViewSite(ownerId, deviceId); // 业务权限，必做
  const live = await platformCall('bindDeviceLive', {
    token,
    deviceId,
    channelId: String(channelId),
    streamId: 1,       // 辅码流，工地多路时省带宽
    liveMode: 'proxy',
  });
  const hls = live.streams?.[0]?.hls;
  auditLog({ ownerId, deviceId, action: 'live_start' });
  return { hls, expiresIn: 300 }; // 业务层短效，勿长期存明文 url
}

踩坑 A：把 m3u8 当 flv 给播放器 —— 黑屏。HLS 用 hls.js 或 Safari 原生。

踩坑 B：直播地址泄露等于工地裸播。我们禁止把 url 写进分享链接；每次「进入工地」重新签发，并限并发（见进阶）。

Web 端若要更流畅，可改用 createDeviceFlvLive（realTime） 出 FLV，与上一篇直播选型文思路一致。

4. 业主看「昨天施工了吗」：云录像链路

透明装修不仅要 实时看，还要 事后查（纠纷、进度确认）：

// 列表：某工地某天有哪些云片段
const list = await platformCall('getCloudRecords', {
  token, deviceId, channelId: '0',
  beginTime: '2026-05-21 08:00:00',
  endTime: '2026-05-21 20:00:00',
  count: 30,
});

// 播放：选中 10:15–10:45（注意 createDeviceRecordHls 不支持跨自然日，需按天切）
const play = await platformCall('createDeviceRecordHls', {
  token, deviceId, channelId: '0',
  beginTime: '2026-05-21 10:15:00',
  endTime: '2026-05-21 10:45:00',
  recordType: 'cloudRecord',
});
return play.url;

产品文案从「我们发了照片」升级为 「您可自行查看 10:15–10:45 云端录像」——信任感差很多。

5. 业主互动：边界要说清

业主最想「喊一嗓子」：「师傅，这块砖怎么贴的？」
平台侧：

• OpenAPI bindDeviceLive：解决「看」，不直接等于「喊话」。
• 对讲：设备能力含 AudioTalk 时，可走 OpenSDK 或小程序文档路径——FLV 拉流 + RTMP 推流（createDeviceRtmpLive，对讲场景 isTalk: true）。

我们的产品设计是 「预约互动」：业主提交问题 → 监理审核 → 限时开启对讲 3 分钟，避免深夜骚扰工人，也避免未授权远程喊话引发劳资问题。技术可行，流程必须克制。

6. 装企侧：多工地看板

总部运营需要 多路缩略预览（不是 200 路同时高清）：

listDeviceDetailsByPage 拉全量 online 工地
    → 看板每格辅码流轮巡（12 路/屏）
    → 点击某工地再 bindDeviceLive 高清
    → 异常 offline 进工单派监理上门

这与连锁巡店、远程监考是同一套 「分页资产 + 按需签发 + 控并发」 模式，只是业务皮肤不同。

7. 端到端时序（业主「看我家」）

业主打开小程序
  → 后端校验 contractId
  → syncSiteCamera 在线？
  → bindDeviceLive 返回 hls
  → 播放器出画 + 水印（合同号后四位）
  → 结束销毁 url 引用，写 auditLog

验收清单：

□ 工地 IPC 绑定到公司开发者账号
□ listDeviceDetailsByPage 在线
□ 业主 A 无法看业主 B 的 deviceId（权限单测）
□ 直播可播；云存开通时可查 getCloudRecords
□ 无 appSecret 出现在小程序包内

---

隐私与合规

• 工地可能有邻居入镜，协议与公示要说明监控范围与用途。
• 工人休息区是否关机/遮挡，装企政策要写在合同里，技术只做 定时计划（直播计划模块可在控制台或相关 OpenAPI 配置）。
• 审计：谁何时看了哪路、是否发起对讲。

性能与成本

• 并发与带宽按账号限额；促销期「全业主同时看」要错峰或辅码流。
• 云存套餐按通道计费，200 工地要算 路数 + 留存天数，不是只算摄像机硬件。
• 列表接口定时同步即可，别每次打开小程序都全量分页扫账号下所有设备。

与轻应用 / 低代码的关系

PoC 阶段可用平台 轻应用、JS 播放组件 快速演示「透明工地」；正式 SaaS 仍建议 自建后端 + OpenAPI，才能把 合同、权限、审计、 branding 握在自己手里。

常见踩坑

现象	原因	处理
业主看不到	设备未绑开发者账号	统一 bindDevice SOP
经常 offline	工地断网/断电	离线工单 + 4G 机位
回放空	未开云存 / csStatus 非 using	上线前开通套餐
被判引流/盗链	把 hls 链接当永久分享	短效签发 + 鉴权

---

小结

透明装修的产品本质，是把 信任 从「人发图」变成 「系统可验证的可视化」：设备进开发者资产池、业主按权限看直播、云端留痕可回放、互动可审计。技术链路上，**listDeviceDetailsByPage** 管状态，**bindDeviceLive** 管实时，**getCloudRecords + createDeviceRecordHls** 管事后，对讲走 SDK/RTMP 能力并与业务流程绑定。

若你是家装 SaaS、区域装企或工程监理平台，建议先选 一个试点工地 走通绑定与业主 HLS 播放，再扩到多工地看板与云录像。乐橙开放平台以视频技术与安全为核心，开放低代码组件与 OpenAPI，帮助开发者较低成本落地监控、直播、云存储等视频场景——透明家装、明厨亮灶、农场直播在底座上是同一类能力延展。

注册与文档：在 乐橙开放平台 完成开发者注册并创建应用，于控制台获取密钥；在 在线开发文档 中查阅接入指南、设备直播说明、云录像查询、录播 HLS 等章节。以上为实践笔记，生产以最新文档为准。