kb2022 系统采用了前后端分离的设计，目前后端已经实现完成，这个网页是介绍前端开发的相关说明。

前端可以是任意的纯前端项目，例如 angular/react/vue，或者其它的纯前端技术栈，不能使用 php/jsp/asp 等包含了后端逻辑的技术。目前后端已经完成并开发了 http/websocket 接口，前端只能使用浏览器标准接口请求这些后端接口来实现前后端的交互。你可以 在此 查看服务器提供的所有公共接口(同时提供了 swagger 等在线工具，你可以尝试调用以理解这些接口)。

接口请求不会出现跨域，预计会使用 nginx/envoy 把前后端部署在同一域名下，网关或依据 url 中的 path 将请求自动路由给前端或后端服务。服务器的所有接口都在 url 子路径 /api/ 下面，前端项目推荐使用 /view/ 作为自己的根路径(如果使用其它路径前缀需要先协商)，目前 url 路径前缀被如下使用:

1. /api/ 包含了所有供前端调用的公共接口
2. /internal/api/ 这是内部接口，供系统内部微服务之间调用
3. /view/ 预留给前端项目的路径
4. /document/ 项目自动生成的在线接口文档，以及一些调试工具

kb2022 是一个互联网广播项目，它被分为三个不同的端点。

1. 设备，设备是真实的广播硬件，它们接收系统的控制，在正确的时间播放音频，或做其它被要求的事情(例如升级或重新启动)
2. 服务器，服务器是整个系统的核心，它完成了对设备的操控，并将这些以http接口开放出来供前端ui使用
3. 前端，前端是任何调用 服务器接口的ui程序，此页面主要指的是网页程序

此外项目按照实现的功能不同可以分为如下几个大的模块：

1. session 会话
2. meta 元数据
3. assets 资产，目前主要是用户上传的音频
4. task 任务
5. room 直播房间
6. history 历史
7. notice 通知
8. controller 设备控制

前端需要为每个模块开发各自的功能 ui 页面，以供用户使用这些功能

session

session 模块相对简单，用户在使用任何功能前需要先调用 session 模块提供的 Sigin 接口进行登入，一旦登入成功，会返回一个 access token 和 refresh token。 access token 需要在服务功能是被设置到 http header Authorization 中，服务器依据此值识别用户。access token 通常有效期是一小时，如果 token 过期了 http 请求会返回 401 的错误，此外前端应该使用 refresh token 向服务器刷新 access token 并在刷新成功后自动为用户尝试刚刚的请求。

你可以在此查看到 session 接口的详细定义

meta

meta 包含了四种数据，前端需要提供ui对这四种数据进行编辑。

1. 元数据 对前端来说通常应该首先获取系统数据，这些数据将影响后续页面显示的内容，这些数据通常不会改变，可以把它们放入缓存中。
   • 调用 Groups 来获取系统提供了哪些用户组，在编辑用户的页面需要这些数据
   • 调用 Level 来获取任务等级有哪些，在编辑任务的页面需要这些数据
   • 调用 TaskPriority 来获取任务优先级有哪些，在编辑任务的页面需要这些数据
2. 区域数据 区域数据是一个树型结构，它通常就是中国的行政区域名称，例如 中国下面有四川，四川下面有成都，你需要为用户提供区域编写的 ui 页面。(设备部署到不同区域例如四川或上海需要不同的区域数据)
3. 设备数据 任何被管控的设备都有一个与之对应的数据，主要记录了它的硬件信息，受控的逻辑编码和部署在哪个区域。你需要提供 ui 来编写这些数据
4. 用户数据 是大部分系统都存在的，记录了有哪些用户，用户的各种信息，你需要为管理员提供一个编写这些用户数据的 ui 页面

区域/设备/用户 的页面都很类似主要就是增删改查，只是具体数据内容有所不同而已

元数据主要是为系统提供了一些动态设定，前后端都依据这些动态设定进行工作，可以把它看作是记录在数据库中的系统配置文件

assets

kb2022 是一个广播系统，主要功能就是让硬件设备播放音频，音频的一个组要来源就用户上传的 mp3，assets 下的 audio 提供了 mp3 资产相关的接口，你可以在 assets 中查看资产的通用定义(目前只存在 mp3 资产)。

1. 简单来说用户首先需要按块上传音频(之所以按块上传是为了在上传失败，用户重上传时只需要传输未完成的块)。
2. 当上传完成后，用户需要把资产提交给管理员审核
3. 当管理员审核成功后，就可以在后续的任务中使用这个音频
4. 此外审核也可以拒绝，审核过的音频也可以停用启用删除等

除此之外，用户可以查询自己的所有音频(审核中 审核失败 审核成功的)，用户也可以查询所有人已经被审核通过的音频(任务中使用的音频是共用的所以需要可以查询所有人审核过的音频)

task

kb2022 是一个广播系统，任务是它的核心功能，它用于为设备安排要播放的内容。你可以在此查看任务的相关功能

任务依据类型可以分为两种类型:

1. 流程任務。这种任务被指定了一些音频资产和播放时间，每当到达了指定的时间就会自动播放这些音频资产。并且这些任务需要被审核，只有审核过的才会播放(审核过的任务可以被停用启用)
2. 直播任务。这些任务不需要被审核，它会立刻被播放

前端主要的页面就是对流程任务就行增删改查以及审核停用启用等。直播任务则是调用相应接口开启直播。

目前开启直播有如下方式：

1. 选择一些审核过的音频资产进行直播
2. 将音频档案上传给服务器进行直播
3. 实时录音转码为mp3，并实时上传mp3帧给服务器进行直播 浏览器端可以不用实现这个功能

所有任务都包含了一些通用的属性：

1. targets 指定了哪些设备要播放，所有设备都有一个逻辑代，targets 是一个逻辑码数组，所有以数组中任意元素作为逻辑码前缀的设备都会播放
2. level 任务等级，显示了是哪个行政区域创建的任务，比如是四川创建的任务还是成都创建的任务。它的取值应该调用元数据接口获取后供用户选择
3. priority 任务优先级，显示了任务的紧急情况，例如是一般闲聊还是火灾警报。它的取值应该调用元数据接口获取后供用户选择。这里有个技巧所有取值为偶数的值都应该供流程任务使用所有取值为奇数的值都应该供直播类任务使用

你可以在此查看任务相关的所有接口

room

所有任务在进行播放时，都会创建一个房间号，room 模块主要的功能是让管理员可以查看目前有哪些房间，管理员可以对其进行监听(浏览器在 https 时使用 AudioWorkletProcessor 播放实时音频流，使用 AudioContext实时解码mp3音频，如果觉得太复杂可以不实现监听)，以及关闭一些非法的房间

history

history 模块主要用于查询历史数据，以及统计信息，供用户查看：

• task 查看任务执行情况
• emulator 查看设备运行情况
• statistics 統計时间段内有多少任务

notice

系统会在一些情况下发送一些消息供用户相关接口在 notice 中，应该使用 websocket 来订阅新消息通知，并为用户显示消息

controller

除了播放音频，用户也可以为每个设备发送控制指令,它们使用 controller 中的通用接口

Add 接口用于发送一个指令，它包含三个属性:

1. target 这是要控制的设备逻辑码
2. command 要执行何种指令，你可以在此查看定义
3. value 传递的指令参数，以 json 编码，它依据 command 不同而各异。具体定义在此

command 的内容后期可能会增加。所以建议前端为已经定义的 command 提供不同的 ui 界面，同时提供一个手输 command value 的高级界面