前端与客户端架构
联犀的客户端包括平台管理 Web、移动应用、小程序、设备与语音终端，以及通过公开接口开发的独立应用。它们消费共同业务能力，同时保留各自的交互、协议和发布边界。
平台 Web 使用多应用工程组织界面与共享能力，后端合同生成对应客户端模型；实时连接则独立维护频道、订阅和页面生命周期。本文解释这些部分如何协作。
放大查看 SVG ↗ · 下载 SVG · 下载高清 PNG
1. 不同客户端各自承担什么
| 客户端 | 主要职责 | 需要分别确认的内容 |
|---|---|---|
| 平台管理应用 | 平台运营、企业、应用和公共能力配置 | 当前身份、应用条件与管理入口 |
| 企业与 IoT 应用 | 项目、设备、数据、控制和相应业务流程 | 项目范围、动作权限与设备反馈 |
| 行业应用 | 能源、停车等具体业务页面和规则 | 行业模型、统计口径与产品流程 |
| 移动端与小程序 | 面向移动场景组织交互 | 系统权限、终端能力、网络与接口合同 |
| 设备、语音与媒体终端 | 对应协议下的采集、交互与执行 | 硬件、接入协议及真实设备行为 |
| 独立业务应用 | 在自己的仓库中开发产品和集成 | 公开 SDK、应用注册、成员与数据授权 |
| 官网与文档站 | 产品、架构、指南及开发资料展示 | 各自静态构建、资源和链接交付 |
多个终端可以访问同一设备业务接口，但并不天然具有相同功能。例如，某个移动端已经能够查设备，仍需要单独实现相应控制交互、订阅和结果呈现。
2. 平台 Web 的工程分层
平台 Web 通过 pnpm workspace 和 Turbo 组织多应用，主要使用 Vue 3、TypeScript、Vite 和 Pinia 等。各应用维护自己的路由、页面和产品流程，跨应用复用的业务能力放在自有共享包中。
| 部分 | 负责什么 | 复用原则 |
|---|---|---|
| 应用与路由 | 页面入口、产品导航和独立业务流程 | 保持所属产品的职责与发布边界 |
| 共享业务组件 | 跨应用使用的业务交互和组合 | 具有实际复用需求后再沉淀 |
| 请求与生成 SDK | 调用合同、参数模型和认证上下文 | 避免各页面手写不同数据模型 |
| 状态与查询协调 | 当前身份、页面数据和相关刷新 | 让变更后的关联数据保持一致 |
| 实时连接 | 连接、频道订阅、重连与取消 | 与当前身份和业务范围协同维护 |
| 重型功能 | 大屏、图表、地图、编辑器和文件预览 | 按路由或组件实际使用时加载 |
多应用工程表达代码组织与构建关系，运行时是否采用其他前端装配方式属于独立选择，不能只根据目录数量推断。
3. 后端合同如何进入界面
后端维护接口源定义和相应输入输出语义，生成链产出服务定义、OpenAPI 及对应客户端。平台 Web 使用生成 SDK 和统一请求器调用业务接口；独立应用则按公开版本消费相应 SDK。
合同包括字段结构，也包括大整数、空值、时间单位、错误和权限语义。更新接口后，应同步对应生成物和受影响页面，而不是在一个页面临时修补成另一种数据模型。
平台内部 direct 客户端用于服务能力复用，独立应用通过公开 SDK 和受保护接口接入。二者具有不同的部署和身份边界。
4. 从进入页面到显示数据
人员进入应用时，客户端识别当前登录、企业和应用上下文，加载相应菜单与页面入口。页面再按当前项目和查询条件发起请求，服务端完成实际业务授权后返回结果，界面据此展示数据、空状态或错误。
菜单和按钮负责呈现可操作入口，服务端负责最终授权。即使按钮被隐藏，直接发出的请求仍需要经过业务检查；权限拒绝也应由界面明确呈现，而不能伪装成“没有数据”。
修改后为什么要刷新关联数据
一次设备、成员或配置修改，可能同时影响列表、详情、统计和关联选项。客户端应在业务变更完成后协调刷新对应结果，让用户看到本次操作的实际状态。
设备控制还需要区分请求受理和最终反馈。页面可以显示等待状态，并依据后续回执或属性变化更新结果；不能仅因按钮请求成功就将设备画成已经完成动作。
5. 实时连接与项目切换
WebSocket 建立连接后，还要按相应频道完成业务订阅。连接管理、订阅确认、断线重连、取消订阅和页面销毁各有生命周期。
这个过程需要防止旧请求晚到后覆盖新项目，也要防止旧订阅继续更新当前页面。具体应用是否已经正确实现这些行为，需要在其实际请求与连接管理中确认。
6. 大屏、图表和编辑器为什么按需加载
登录与普通业务页面主要依赖认证、布局、路由和轻量交互。地图、编辑器、图表及文件处理引擎具有更大的加载与运行成本，应在实际页面使用时再加载。
按需加载使产品进入路径与重型功能保持清楚边界。共享包也需要提供适合使用的窄入口，避免页面只使用一个小功能，却连带加载整套编辑器或大屏引擎。
数据可视化同样消费真实业务接口与实时通道。图表展示效果、数据来源和授权范围需要一起确认，不能仅凭图形正常渲染判断业务数据已经正确。
7. 平台源码开发与独立应用开发
| 路线 | 适合的工作 | 接入方式 |
|---|---|---|
| 平台源码开发 | 维护平台页面、共享业务组件、生成合同和内部能力装配 | 授权源码工程及平台生成 SDK |
| 独立应用开发 | 构建自己的前端、业务后端、协议服务或行业产品 | 公开 ur-kit / SDK 和授权接口 |
| 终端开发 | 实现设备采集、语音交互、控制与回执 | 对应设备协议和终端 SDK / 接口 |
独立应用还需维护自己的业务数据和初始化流程。复用平台登录，不会自动实现自有业务表的企业与项目隔离；部署成功，也需要继续核验实际登录、菜单、成员授权与业务读写。
8. 如何验证一个客户端链路
先检查入口与当前身份，再观察请求是否携带正确上下文、服务端结果是否符合权限和查询条件，最后检查关联刷新与实时状态。对设备控制、文件上传和媒体交互，还要覆盖相应终端实际行为。
实施入口分别见平台前端开发、独立应用开发和WebSocket 开发。
架构专题导航
平台总体架构 · 后端运行架构 · SaaS 与权限架构 · IoT 接入与数据架构 · AI 与工具执行架构 · 云边协同架构 · 部署架构与组件选型
更新日志
2026/10/27 13:22
查看所有更新日志
c4a4b-于93dfc-于