Compare commits
1 Commits
663768ce17
...
master
| Author | SHA1 | Date | |
|---|---|---|---|
| 74f4c01603 |
499
交接文档.md
Normal file
499
交接文档.md
Normal file
@@ -0,0 +1,499 @@
|
|||||||
|
# Temi 终端控制应用交接文档
|
||||||
|
|
||||||
|
本文档面向后续接手本项目的技术人员，重点说明项目定位、当前架构、配置约定、关键业务流程、排障思路，以及与旧版实现相比已经发生的变化。建议先通读本文，再结合 `technique.md` 和代码深入。
|
||||||
|
|
||||||
|
## 1. 项目定位与当前状态
|
||||||
|
|
||||||
|
- 项目类型：基于 Temi SDK 的 Android 应用（Kotlin）。
|
||||||
|
- Android 模块：`app`
|
||||||
|
- 包名：`com.example.lzwcai_terminal_temi`
|
||||||
|
- 核心能力：
|
||||||
|
- 通过 MQTT 指令控制 Temi 机器人导航、巡逻、接待、通知播报和基础动作。
|
||||||
|
- 通过 LiveKit 进行音视频接入，并把房间内收到的 ASR/文本数据转发到 MQTT。
|
||||||
|
- 通过 HTTP 接口做设备激活、运行时配置拉取、门禁工作流调用。
|
||||||
|
- 通过 Telemetry 上报机器人状态心跳、事件、电量和位姿。
|
||||||
|
- 当前版本和早期代码相比，最大的变化是：
|
||||||
|
- MQTT 用户名/密码不再写死在代码中，而是在激活后从服务端拉取并存入本地。
|
||||||
|
- 设置页主配置已经从单纯的 `network_ip` 扩展成 `base_url + 登录账号 + 激活码 + 设备名`。
|
||||||
|
- 主流程增加了激活态控制、自动回充、门禁工作流、接待返航工作流、ASR 转发等能力。
|
||||||
|
|
||||||
|
推荐阅读顺序：
|
||||||
|
|
||||||
|
1. 本文档：快速建立维护视角。
|
||||||
|
2. `technique.md`：查看协议和流程图。
|
||||||
|
3. `MainActivity.kt`、`SettingsActivity.kt`、`MqttManager.kt`、`TaskController.kt`：理解当前真实行为。
|
||||||
|
|
||||||
|
## 2. 核心模块一览
|
||||||
|
|
||||||
|
代码主要集中在 `app/src/main/java/com/example/lzwcai_terminal_temi`：
|
||||||
|
|
||||||
|
- `MainActivity`
|
||||||
|
- 主界面与机器人事件中心。
|
||||||
|
- 管理 MQTT / LiveKit 生命周期、TTS 状态、人体检测、到站处理、UI 状态、激活提示。
|
||||||
|
- `SettingsActivity`
|
||||||
|
- 配置页。
|
||||||
|
- 负责 `base_url`、登录账号密码、激活码、设备名、LiveKit 参数、当前位置、特殊状态、`agent_demp_id` 等配置。
|
||||||
|
- `ConnectionService`
|
||||||
|
- 连接层编排。
|
||||||
|
- 根据当前配置和激活状态创建/更新 `MqttManager` 与 `LiveKitManager`。
|
||||||
|
- `MqttManager`
|
||||||
|
- MQTT 连接、重连、订阅、发布。
|
||||||
|
- 解析 `robot/cmd` 与 `soul2user`，管理流式播报、TTS 队列和任务启动。
|
||||||
|
- `TaskController`
|
||||||
|
- 任务状态机。
|
||||||
|
- 管理 `patrol`、`reception`、`notification`、`speech` 等任务，以及任务超时、巡逻推进、接待确认按钮。
|
||||||
|
- `MainTaskPolicy`
|
||||||
|
- 统一定义空闲态 / 特殊状态下的行为决策。
|
||||||
|
- 控制是否允许自动回充、门禁工作流、到站播报、闲时问候。
|
||||||
|
- `NavController`
|
||||||
|
- Temi 导航与动作封装。
|
||||||
|
- 包含 `goTo`、`recharge`、`repose`、`turnBy`、`tiltAngle`、`randomPatrol` 等。
|
||||||
|
- `AutoRechargeScheduler`
|
||||||
|
- 机器人空闲到站后的延时自动回充。
|
||||||
|
- 当前策略是空闲到站后 10 秒且不在 `home base` 时触发 `recharge()`。
|
||||||
|
- `WorkflowService`
|
||||||
|
- 工作流调用编排。
|
||||||
|
- 负责开门、关门、接待返航工作流，并在缺配置时尝试刷新服务端配置。
|
||||||
|
- `HttpManager`
|
||||||
|
- HTTP 接口封装。
|
||||||
|
- 负责登录、激活、拉取运行时配置、执行工作流。
|
||||||
|
- `LiveKitManager`
|
||||||
|
- LiveKit 房间连接、事件监听、自动重连、麦克风开关控制。
|
||||||
|
- 麦克风开启条件依赖人体检测稳定状态和 TTS 静音状态。
|
||||||
|
- `TelemetryManager`
|
||||||
|
- 周期性心跳与事件上报。
|
||||||
|
- 包含电量、位置、运动状态、任务状态、MQTT/LiveKit 连接状态。
|
||||||
|
- `RobotEventHandler`
|
||||||
|
- 机器人事件辅助逻辑。
|
||||||
|
- 用于状态归类、地点归一化、角度归一化。
|
||||||
|
- `UiState`
|
||||||
|
- 主界面上网络异常横幅、激活提示横幅、连接指示灯颜色更新。
|
||||||
|
- `PermissionManager`
|
||||||
|
- Temi 权限检查与申请。
|
||||||
|
- `AnimatedEmojiView`
|
||||||
|
- 自绘表情组件，受任务状态和 TTS 状态驱动。
|
||||||
|
- `LogManager`
|
||||||
|
- Logcat 监听与订阅。
|
||||||
|
|
||||||
|
## 3. 运行环境与依赖
|
||||||
|
|
||||||
|
### 3.1 开发环境
|
||||||
|
|
||||||
|
- Android Studio：近期版本即可，需支持：
|
||||||
|
- AGP `8.10.1`
|
||||||
|
- Kotlin `2.0.21`
|
||||||
|
- JDK：17
|
||||||
|
- Android SDK：
|
||||||
|
- `compileSdk = 36`
|
||||||
|
- `minSdk = 23`
|
||||||
|
- `targetSdk = 36`
|
||||||
|
- 运行设备：Temi 真机优先；模拟器仅适合 UI 预览。
|
||||||
|
|
||||||
|
### 3.2 主要依赖
|
||||||
|
|
||||||
|
见 [`app/build.gradle.kts`](file:///Users/tan/Documents/project/lzwcai-terminal-temi/app/build.gradle.kts#L41-L52) 与 [`libs.versions.toml`](file:///Users/tan/Documents/project/lzwcai-terminal-temi/gradle/libs.versions.toml#L1-L26)：
|
||||||
|
|
||||||
|
- Temi SDK：`com.robotemi:sdk:1.137.1`
|
||||||
|
- MQTT：
|
||||||
|
- `org.eclipse.paho.android.service:1.1.1`
|
||||||
|
- `org.eclipse.paho.client.mqttv3:1.2.5`
|
||||||
|
- LiveKit Android：`2.23.5`
|
||||||
|
- AndroidX / Material / Emoji2 等基础 UI 依赖。
|
||||||
|
|
||||||
|
### 3.3 权限
|
||||||
|
|
||||||
|
- Temi 权限：
|
||||||
|
- `MAP`
|
||||||
|
- `SEQUENCE`
|
||||||
|
- `FACE_RECOGNITION`
|
||||||
|
- `SETTINGS`
|
||||||
|
- Android 权限：
|
||||||
|
- `RECORD_AUDIO`
|
||||||
|
- `CAMERA`
|
||||||
|
|
||||||
|
说明：
|
||||||
|
|
||||||
|
- `MainActivity.onStart()` 会注册机器人监听器并按激活状态决定是否启动 MQTT / LiveKit / Telemetry。
|
||||||
|
- `onRobotReady()` 中会触发 `PermissionManager.checkAndRequestPermissions()`。
|
||||||
|
- LiveKit 权限未授予时不会建立连接。
|
||||||
|
|
||||||
|
## 4. 配置与持久化约定
|
||||||
|
|
||||||
|
应用配置统一存放在 `SharedPreferences("app_prefs")`。
|
||||||
|
|
||||||
|
### 4.1 关键配置项
|
||||||
|
|
||||||
|
- 服务与激活相关：
|
||||||
|
- `base_url`：后端服务基础地址，例如 `http://192.168.11.24:8088`
|
||||||
|
- `login_username` / `login_password`：调用登录接口用的账号密码
|
||||||
|
- `activation_code`：激活码
|
||||||
|
- `device_name`：设备名称
|
||||||
|
- `device_id`：本机生成并持久化的设备标识
|
||||||
|
- `is_activated`：是否已激活
|
||||||
|
- 运行时下发配置：
|
||||||
|
- `mqtt_username` / `mqtt_password`
|
||||||
|
- `od_wfid` / `od_wf_key`：开门工作流配置
|
||||||
|
- `cd_wfid` / `cd_wf_key`：关门工作流配置
|
||||||
|
- `vr_wfid` / `vr_wf_key`：接待返航工作流配置
|
||||||
|
- 任务与状态：
|
||||||
|
- `current_location`：当前位置
|
||||||
|
- `special_state`：特殊状态开关
|
||||||
|
- `agent_demp_id`：`soul2user` 过滤字段
|
||||||
|
- LiveKit：
|
||||||
|
- `livekit_url`
|
||||||
|
- `livekit_room`
|
||||||
|
- `livekit_token`
|
||||||
|
- `livekit_enabled`
|
||||||
|
- 兼容字段：
|
||||||
|
- `network_ip`：仍会被保存，但现在是由 `base_url` 自动解析 host 后回填，主要给旧逻辑或排查时参考。
|
||||||
|
|
||||||
|
### 4.2 设置页实际能力
|
||||||
|
|
||||||
|
当前 `SettingsActivity` 不只是“填 IP”，而是包含以下能力：
|
||||||
|
|
||||||
|
- 保存 `base_url`、`agent_demp_id`、登录用户名、登录密码。
|
||||||
|
- 触发设备激活：
|
||||||
|
- 调 `HttpManager.activateDevice()`
|
||||||
|
- 成功后拉取 MQTT 与工作流配置
|
||||||
|
- 将 `is_activated` 设为 `true`
|
||||||
|
- 保存 LiveKit URL / 房间 / Token / 自动连接开关。
|
||||||
|
- 选择当前位置。
|
||||||
|
- 开关特殊状态。
|
||||||
|
- 清除当前任务。
|
||||||
|
- 查看 About 信息。
|
||||||
|
- 长按 3 秒重启应用。
|
||||||
|
|
||||||
|
### 4.3 一个重要行为
|
||||||
|
|
||||||
|
当 `base_url` 发生变化时，设置页会主动清空以下信息并重置激活状态：
|
||||||
|
|
||||||
|
- `activation_code`
|
||||||
|
- `device_name`
|
||||||
|
- `is_activated`
|
||||||
|
- MQTT 用户名/密码
|
||||||
|
- 所有工作流 ID / API Key
|
||||||
|
|
||||||
|
这意味着切环境后必须重新激活，文档和运维流程都要按这个行为来理解。
|
||||||
|
|
||||||
|
## 5. 通信协议与主题约定
|
||||||
|
|
||||||
|
### 5.1 MQTT Broker 与主题
|
||||||
|
|
||||||
|
- Broker 地址：`tcp://<base_url_host>:1883`
|
||||||
|
- 实际 host 由 `ConnectionService.resolveBrokerHostFromBaseUrl()` 从 `base_url` 提取。
|
||||||
|
- MQTT 账号：
|
||||||
|
- 从本地 `mqtt_username` / `mqtt_password` 读取。
|
||||||
|
- 这些值通常由激活成功后从服务端拉取。
|
||||||
|
- 订阅主题：
|
||||||
|
- `robot/cmd`：控制指令
|
||||||
|
- `soul2user`：流式播报文本
|
||||||
|
- 发布主题：
|
||||||
|
- `robot/status`：状态心跳
|
||||||
|
- `robot/event`：事件上报，例如 `battery_low`
|
||||||
|
- `robot/asr`：LiveKit 收到的文本/ASR 转发结果
|
||||||
|
|
||||||
|
### 5.2 指令映射
|
||||||
|
|
||||||
|
指令解析统一在 `MqttManager.handleJsonCommand()`：
|
||||||
|
|
||||||
|
- 基础控制：
|
||||||
|
- `recharge`
|
||||||
|
- `goto`
|
||||||
|
- `repose`
|
||||||
|
- `turn`
|
||||||
|
- `tilt`
|
||||||
|
- `stop`
|
||||||
|
- `terminate`
|
||||||
|
- `continue`
|
||||||
|
- `status`
|
||||||
|
- 语音：
|
||||||
|
- `speak`
|
||||||
|
- `stream`
|
||||||
|
- 任务：
|
||||||
|
- `patrol`
|
||||||
|
- `notification`
|
||||||
|
- `reception`
|
||||||
|
|
||||||
|
### 5.3 当前实现里的几个“非直觉行为”
|
||||||
|
|
||||||
|
这些点很容易和旧文档或接口约定不一致，接手时必须知道：
|
||||||
|
|
||||||
|
- `reception` 指令里的 `location` 目前没有真正使用。
|
||||||
|
- `MqttManager` 里接待地点被硬编码为 `前台`。
|
||||||
|
- `destination` 默认值是 `会议室`。
|
||||||
|
- `text` 默认值是“你是我要接待的贵宾吗？”
|
||||||
|
- `goto` 若收到未知地点，不会报错退出，而是会回退到 `会议室`。
|
||||||
|
- 这是 `NavController.goTo()` 的当前保护逻辑。
|
||||||
|
- `stream` 不只是简单播报全文。
|
||||||
|
- 文本会进入 `speechBuffer`
|
||||||
|
- 根据中英文标点和换行拆句
|
||||||
|
- `is_final=true` 时会刷新剩余缓存
|
||||||
|
- `soul2user` 消息支持通过 `agent_demp_id` 过滤 `demp_id`。
|
||||||
|
- 当 `session_id` 或 `message_id` 变化时，当前流式 TTS 会被打断并切换到新的会话上下文。
|
||||||
|
|
||||||
|
### 5.4 常见指令示例
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"action":"goto","location":"前台"}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"action":"speak","text":"欢迎光临","lang":"zh"}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"action":"patrol","flag":false,"locations":["前台","会议室"],"times":2,"waiting":5}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"action":"notification","location":"大厅","text":"会议即将开始，请尽快入场"}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. 关键业务流程说明
|
||||||
|
|
||||||
|
### 6.1 激活态控制
|
||||||
|
|
||||||
|
`MainActivity` 已经把“是否激活”纳入主流程：
|
||||||
|
|
||||||
|
- 未激活时：
|
||||||
|
- 主界面显示“请先激活应用”横幅
|
||||||
|
- MQTT 断开
|
||||||
|
- LiveKit 断开
|
||||||
|
- Telemetry 停止
|
||||||
|
- 不再进入正常联网工作态
|
||||||
|
- 已激活时：
|
||||||
|
- 恢复 MQTT / LiveKit 连接流程
|
||||||
|
- 开始心跳上报
|
||||||
|
|
||||||
|
这部分逻辑是当前版本的重要门槛，所有“为什么没连上 MQTT / LiveKit”的排查都先确认 `is_activated`。
|
||||||
|
|
||||||
|
### 6.2 任务状态机
|
||||||
|
|
||||||
|
任务逻辑集中在 [`TaskController.kt`](file:///Users/tan/Documents/project/lzwcai-terminal-temi/app/src/main/java/com/example/lzwcai_terminal_temi/TaskController.kt)：
|
||||||
|
|
||||||
|
- `currentTask` 主要值：
|
||||||
|
- 空字符串：空闲
|
||||||
|
- `speech`
|
||||||
|
- `patrol`
|
||||||
|
- `reception`
|
||||||
|
- `notification`
|
||||||
|
- 巡逻：
|
||||||
|
- 支持指定路线和随机路线
|
||||||
|
- 支持 `times`、`waiting`、`nonStop`
|
||||||
|
- 通过 `handlePatrolArrival()` 推进路线索引和剩余圈数
|
||||||
|
- 接待：
|
||||||
|
- 到达接待点后开启等待
|
||||||
|
- 稳定检测到人时显示确认按钮并播报接待文案
|
||||||
|
- 点击按钮后前往目的地
|
||||||
|
- 通知：
|
||||||
|
- 到达目标地点即播报一次并结束任务
|
||||||
|
- 纯播报：
|
||||||
|
- 由 MQTT 流式/非流式语音触发
|
||||||
|
- TTS 队列清空后自动清回空任务
|
||||||
|
- 任务超时：
|
||||||
|
- 接待任务在等待阶段会启动 15 分钟超时
|
||||||
|
- 超时后播报“任务超时了，任务被取消，我先回充电桩了”并执行回充
|
||||||
|
|
||||||
|
### 6.3 到站、播报与自动回充
|
||||||
|
|
||||||
|
`onGoToLocationStatusChanged()` 是到站处理的关键入口：
|
||||||
|
|
||||||
|
- 到站后会：
|
||||||
|
- 更新 `lastArrivalLocation`
|
||||||
|
- 回写 `current_location`
|
||||||
|
- 处理巡逻到站推进
|
||||||
|
- 处理接待任务到站
|
||||||
|
- 处理通知任务到站
|
||||||
|
- 根据 `MainTaskPolicy` 决定是否播报“已到达xxx”
|
||||||
|
- 自动回充当前规则：
|
||||||
|
- 仅在空闲任务或 `speech` 任务下允许
|
||||||
|
- 特殊状态下禁用
|
||||||
|
- 仅在不在 `home base` 时生效
|
||||||
|
- 到站 10 秒后自动执行 `recharge()`
|
||||||
|
|
||||||
|
### 6.4 人体检测、门禁与问候
|
||||||
|
|
||||||
|
人体检测在 `MainActivity` 中做去抖：
|
||||||
|
|
||||||
|
- `DETECTED`：约 0.8 秒稳定确认
|
||||||
|
- `IDLE`：约 5 秒稳定确认
|
||||||
|
|
||||||
|
稳定状态变化后：
|
||||||
|
|
||||||
|
- 会调用 `LiveKitManager.setDetectionActive()` 更新麦克风逻辑。
|
||||||
|
- 会优先交给 `TaskController.handleDetectionStateChanged()` 处理任务内行为。
|
||||||
|
- 如果当前是空闲态且允许门禁逻辑：
|
||||||
|
- 在 `home base` 检测到人时执行开门工作流
|
||||||
|
- 回到 `IDLE` 时执行关门工作流
|
||||||
|
- 如果当前是空闲态且不在 `home base`：
|
||||||
|
- 检测到人时会按当前时段播报“早上好 / 中午好 / 下午好 / 晚上好”
|
||||||
|
|
||||||
|
### 6.5 LiveKit 与语音互斥
|
||||||
|
|
||||||
|
LiveKit 麦克风并不是“连上就开”，而是由三项共同决定：
|
||||||
|
|
||||||
|
- LiveKit 连接时传入的 `enableMic`
|
||||||
|
- `detectionActive == true`
|
||||||
|
- `ttsMuted == false`
|
||||||
|
|
||||||
|
也就是说：
|
||||||
|
|
||||||
|
- 机器人开始 TTS 时会自动关闭麦克风。
|
||||||
|
- TTS 结束后才允许再次开麦。
|
||||||
|
- 没有人时不会持续开麦。
|
||||||
|
|
||||||
|
### 6.6 工作流调用
|
||||||
|
|
||||||
|
当前工作流主要有三类：
|
||||||
|
|
||||||
|
- 开门：`od_wfid` / `od_wf_key`
|
||||||
|
- 关门：`cd_wfid` / `cd_wf_key`
|
||||||
|
- 接待返航：`vr_wfid` / `vr_wf_key`
|
||||||
|
|
||||||
|
调用路径：
|
||||||
|
|
||||||
|
- `WorkflowService.executeDoorWorkflow()`：处理开门/关门。
|
||||||
|
- `WorkflowService.markReceptionReturnPending()`：
|
||||||
|
- 在接待确认按钮点击后设置“返航待触发”。
|
||||||
|
- `WorkflowService.triggerReceptionReturnWorkflowIfNeeded()`：
|
||||||
|
- 当机器人后续回到 `home base` 时触发返航工作流。
|
||||||
|
|
||||||
|
补充说明：
|
||||||
|
|
||||||
|
- 如果本地没有 workflow 配置，`WorkflowService` 会尝试重新调用 `fetchRuntimeConfigs()` 刷新一次。
|
||||||
|
- 工作流执行失败时，主界面会展示短暂的“网络异常”横幅。
|
||||||
|
|
||||||
|
### 6.7 Telemetry 上报
|
||||||
|
|
||||||
|
[`TelemetryManager`](file:///Users/tan/Documents/project/lzwcai-terminal-temi/app/src/main/java/com/example/lzwcai_terminal_temi/TelemetryManager.kt) 负责状态上报：
|
||||||
|
|
||||||
|
- 心跳频率：每 15 秒一次
|
||||||
|
- 状态快照字段包括：
|
||||||
|
- `task`
|
||||||
|
- `location`
|
||||||
|
- `mqttConnected`
|
||||||
|
- `liveKitConnected`
|
||||||
|
- `battery`
|
||||||
|
- `movement`
|
||||||
|
- `position`
|
||||||
|
- 低电量策略：
|
||||||
|
- 电量 `<= 20%` 且未充电
|
||||||
|
- 10 分钟内只重复提醒一次
|
||||||
|
- 本地播报“电量低，请及时充电。”
|
||||||
|
- 向 `robot/event` 发布 `battery_low`
|
||||||
|
|
||||||
|
## 7. 日志与排障
|
||||||
|
|
||||||
|
### 7.1 主要日志来源
|
||||||
|
|
||||||
|
- Logcat Tag：
|
||||||
|
- `MainActivity`
|
||||||
|
- `MqttManager`
|
||||||
|
- `LiveKitManager`
|
||||||
|
- `SettingsActivity`
|
||||||
|
- `ConnectionService`
|
||||||
|
- `TaskController`
|
||||||
|
- `TelemetryManager`
|
||||||
|
- `HttpManager`
|
||||||
|
- `LogManager.startLogcatListener()` 会在应用启动时开始监听。
|
||||||
|
|
||||||
|
### 7.2 排障建议
|
||||||
|
|
||||||
|
- MQTT 连不上：
|
||||||
|
- 先确认是否已激活
|
||||||
|
- 再看 `base_url` 是否能正确解析出 host
|
||||||
|
- 再看本地是否已有 `mqtt_username` / `mqtt_password`
|
||||||
|
- 查看 `MqttManager` 日志中的 `MQTT connect skipped`、`Initial connection failed`
|
||||||
|
- 激活失败：
|
||||||
|
- 检查 `base_url` 是否正确
|
||||||
|
- 检查登录账号密码是否正确
|
||||||
|
- 检查激活码和设备名是否填写完整
|
||||||
|
- 查看 `HttpManager` 的 `Login failed`、`Activation failed`
|
||||||
|
- 工作流不触发：
|
||||||
|
- 检查本地是否已保存 `od_*` / `cd_*` / `vr_*`
|
||||||
|
- 确认 `home base` 地点名称归一化后能匹配
|
||||||
|
- 查看是否处于特殊状态或非空闲任务，导致门禁逻辑被策略层禁用
|
||||||
|
- 接待任务不工作：
|
||||||
|
- 先注意当前实现里接待地点默认就是 `前台`
|
||||||
|
- 检查是否稳定检测到人，而不是瞬时检测
|
||||||
|
- 检查按钮是否显示、任务是否超时被取消
|
||||||
|
- 导航到错误地点：
|
||||||
|
- 当前未知地点会自动回退到 `会议室`
|
||||||
|
- 先检查 Temi 侧地点名称是否与消息一致
|
||||||
|
- LiveKit 不连或没声音：
|
||||||
|
- 检查 URL / Room / Token / 自动连接开关
|
||||||
|
- 检查麦克风和摄像头权限
|
||||||
|
- 注意“已连接但没人时不开麦”是当前设计，不是异常
|
||||||
|
- `monitor.py` 调试失败：
|
||||||
|
- 它仍然写死了 `API_KEY` / `API_SECRET` / URL / 房间名
|
||||||
|
- 需要和当前 LiveKit 环境保持一致
|
||||||
|
|
||||||
|
## 8. 常见改动场景指引
|
||||||
|
|
||||||
|
### 8.1 新增 MQTT 指令
|
||||||
|
|
||||||
|
推荐修改顺序：
|
||||||
|
|
||||||
|
1. 在 `MqttManager.handleJsonCommand()` 增加 `action` 分支。
|
||||||
|
2. 如果涉及持续态流程，在 `TaskController` 增加任务类型，而不是把状态散落在 `MainActivity`。
|
||||||
|
3. 如果需要策略控制，同时补 `MainTaskPolicy`。
|
||||||
|
4. 如果需要状态上报，扩展 `TelemetryManager`。
|
||||||
|
|
||||||
|
### 8.2 修正接待逻辑
|
||||||
|
|
||||||
|
如果你希望接待任务真正使用 MQTT 中的 `location`：
|
||||||
|
|
||||||
|
1. 修改 `MqttManager` 中 `reception` 分支，不要再写死 `前台`。
|
||||||
|
2. 联调 `TaskController.startReceptionMode()` 与现场 Temi 地点名称。
|
||||||
|
3. 回归测试接待确认按钮、接待返航工作流、朝向恢复逻辑。
|
||||||
|
|
||||||
|
### 8.3 调整自动回充或门禁策略
|
||||||
|
|
||||||
|
优先改这里：
|
||||||
|
|
||||||
|
- `MainTaskPolicy`：决定什么情况下允许自动回充、门禁、问候
|
||||||
|
- `AutoRechargeScheduler`：决定延时多久回充
|
||||||
|
- `MainActivity.handleStableDetectionStateChanged()`：决定何时触发开门/关门
|
||||||
|
|
||||||
|
### 8.4 更换服务环境
|
||||||
|
|
||||||
|
新环境切换步骤建议如下：
|
||||||
|
|
||||||
|
1. 在设置页改 `base_url`
|
||||||
|
2. 确认激活状态已被重置
|
||||||
|
3. 重新填写登录信息和激活码
|
||||||
|
4. 重新激活，拉取 MQTT 与工作流配置
|
||||||
|
5. 再检查 LiveKit 参数是否也需要同步更新
|
||||||
|
|
||||||
|
### 8.5 扩展 HTTP / 工作流集成
|
||||||
|
|
||||||
|
建议在 `HttpManager` 中新增原子接口，在 `WorkflowService` 中编排业务流程，避免把 HTTP 细节直接散落到 `MainActivity`。
|
||||||
|
|
||||||
|
## 9. 安全与后续优化建议
|
||||||
|
|
||||||
|
- 敏感信息：
|
||||||
|
- 登录账号密码目前明文保存在 `SharedPreferences`
|
||||||
|
- LiveKit 默认 `API_KEY` / `API_SECRET` 仍写在代码中
|
||||||
|
- `monitor.py` 里也写死了 LiveKit 凭据和 URL
|
||||||
|
- 配置管理：
|
||||||
|
- 现在已经有“激活后拉运行配置”的雏形，可以继续把更多环境配置收敛到服务端
|
||||||
|
- 协议一致性：
|
||||||
|
- `reception.location` 未实际生效
|
||||||
|
- `goto` 未知地点会静默降级到 `会议室`
|
||||||
|
- 这些行为最好和上游协议重新对齐
|
||||||
|
- 文案资源化：
|
||||||
|
- 业务提示语很多还写在 Kotlin 代码里，后续可以逐步迁移到 `strings.xml`
|
||||||
|
- 稳定性：
|
||||||
|
- 工作流失败现在只是展示网络异常横幅，可考虑补充错误事件上报和重试机制
|
||||||
|
|
||||||
|
## 10. 建议接手路径
|
||||||
|
|
||||||
|
如果你是第一次接手，建议按下面顺序熟悉：
|
||||||
|
|
||||||
|
1. 先在真机上跑通激活流程。
|
||||||
|
2. 在设置页填好 `base_url`、登录账号、激活码、设备名，确认 MQTT 能连上。
|
||||||
|
3. 用 `goto`、`speak`、`patrol`、`notification` 四类指令验证基础链路。
|
||||||
|
4. 再测试空闲态门禁、接待任务、自动回充、低电量事件。
|
||||||
|
5. 最后再看 `technique.md` 里的流程图，对照 `MainActivity` 和 `TaskController` 理解策略差异。
|
||||||
|
|
||||||
|
如需继续维护，建议同步更新 `README.md` 与 `technique.md`，因为它们目前还有一部分内容停留在旧版实现描述。
|
||||||
Reference in New Issue
Block a user