add docs folder.

Signed-off-by: chaoq <chaoq@gxtech.ltd>
2025-09-17 15:55:45 +08:00
parent 0ca9d5011f
commit 202ebef35d
8 changed files with 4991 additions and 0 deletions
--- a/docs/dev-plan.md
+++ b/docs/dev-plan.md
@@ -0,0 +1,285 @@
+## 实现步骤
+
+  阶段1：基础架构和登录
+  **目标**：搭建项目基础架构，实现用户登录功能
+  **验收标准**：
+  - [ ] 项目能正常编译运行，无构建错误
+  - [ ] MVVM架构清晰，ViewModel与UI分离
+  - [ ] 网络请求能正常访问测试API
+  - [ ] Room数据库能正常读写用户数据
+  - [ ] 登录界面UI完整，手机号输入和验证码功能正常
+  - [ ] 登录成功后可跳转至主界面，失败有明确提示
+  - [ ] 用户会话能在应用重启后保持
+  **测试**：单元测试通过，登录流程测试通过
+
+  阶段2：实时通信基础
+  **目标**：集成LiveKit，实现基础音视频通话
+  **验收标准**：
+  - [ ] LiveKit库集成成功，无版本冲突
+  - [ ] 音视频权限申请流程完整，用户授权处理正确
+  - [ ] 本地摄像头预览正常显示，画面清晰无卡顿
+  - [ ] 能成功连接到LiveKit测试房间
+  - [ ] 基础通话功能正常，可正常开启/关闭音视频
+  - [ ] 网络状态变化时有一定容错处理
+  **测试**：LiveKit连接测试通过，音视频权限测试通过
+
+  阶段3：协作会话
+  **目标**：实现完整的会议管理和控制功能
+  **验收标准**：
+  - [ ] 会议发起界面完整，能输入会议主题和设置
+  - [ ] 加入会议功能正常，支持邀请码和链接加入
+  - [ ] 参会者列表实时显示，能显示在线状态
+  - [ ] 音视频控制按钮响应及时，状态显示正确
+  - [ ] 会议邀请码生成正确，可被其他用户成功使用
+  - [ ] 简单录制功能正常，能保存录制文件
+  - [ ] 会议结束处理完整，资源释放正确
+  **测试**：端到端会议测试通过，参会者管理测试通过
+
+  阶段4：AR环境集成
+  **目标**：集成ARCore，实现基础AR功能
+  **验收标准**：
+  - [ ] ARCore v1.50.0依赖配置正确，无版本冲突
+  - [ ] AR权限申请处理完整，用户拒绝时有降级方案
+  - [ ] AR场景能正常初始化，相机画面显示正常
+  - [ ] 平面检测功能正常，能识别水平和垂直平面
+  - [ ] 点击交互响应及时，能在检测到的平面上创建锚点
+  - [ ] 在低端设备上有适当的降级处理
+  - [ ] AR场景切换和退出时资源释放正确
+  **测试**：ARCore兼容性测试通过，平面检测测试通过
+
+  阶段5：AR标注工具
+  **目标**：实现完整的AR标注功能
+  **验收标准**：
+  - [ ] 箭头标注能准确放置在AR空间中，位置稳定
+  - [ ] 画笔涂鸦流畅，支持不同颜色和粗细
+  - [ ] 矩形框选工具能准确框选目标区域
+  - [ ] 激光笔指示实时响应，移动平滑
+  - [ ] 清除标注功能完整，能清除单个或全部标注
+  - [ ] 标注在不同设备间同步位置准确
+  - [ ] 标注能稳定跟随AR场景移动，无明显漂移
+  **测试**：AR标注同步测试通过，标注稳定性测试通过
+
+  阶段6：协作增强
+  **目标**：增强协作功能，支持白板、屏幕共享等
+  **验收标准**：
+  - [ ] 白板模式切换流畅，界面响应及时
+  - [ ] 屏幕共享功能正常，能捕获和传输屏幕内容
+  - [ ] 文件发送/接收功能完整，支持常见格式
+  - [ ] 颜色选择器交互友好，支持多种颜色选择
+  - [ ] 撤销/重做功能正常，操作历史记录完整
+  - [ ] 白板内容能实时同步给所有参会者
+  - [ ] 文件传输过程有进度显示，支持断点续传
+  **测试**：白板协作功能测试通过，文件传输完整性测试通过
+
+  阶段7：AI能力集成
+  **目标**：集成AI服务，提供智能化功能
+  **验收标准**：
+  - [ ] 语音转文字API调用正常，转换准确率>90%
+  - [ ] 实时字幕显示及时，延迟<3秒
+  - [ ] 会议纪要生成功能完整，包含关键信息
+  - [ ] AI知识库查询响应及时，结果相关度高
+  - [ ] AI服务异常时有适当的错误处理
+  - [ ] 用户可控制AI功能的开启/关闭
+  - [ ] AI处理过程有明确的进度和状态提示
+  **测试**：AI服务集成测试通过，语音识别准确率测试通过
+
+  阶段8：优化和兼容性
+  **目标**：优化性能，提升用户体验
+  **验收标准**：
+  - [ ] 应用启动时间<3秒，界面切换流畅
+  - [ ] 音视频通话延迟<200ms，画质清晰
+  - [ ] AR渲染帧率>30fps，标注稳定无漂移
+  - [ ] 内存占用合理，无内存泄漏
+  - [ ] 电池消耗优化，正常使用下耗电合理
+  - [ ] 网络自适应良好，弱网环境下功能降级graceful
+  - [ ] 支持多种设备，从低端到高端都有良好体验
+  - [ ] 崩溃率<0.1%，异常处理完善
+  **测试**：性能压力测试通过，设备兼容性测试通过
+
+## 技术挑战与解决方案
+
+  挑战1：LiveKit连接和房间管理
+  - 问题：房间连接失败，网络适配，断线重连
+  - 解决方案：使用LiveKit 2.x的自动重连机制，ConnectionQuality API监控网络状态
+
+  挑战2：ARCore v1.50.0新特性适配
+  - 问题：新版本ARCore API变化，性能优化要求
+  - 解决方案：使用ARCore 1.50.0的增强命中测试和光照估计功能
+
+  挑战3：多端标注同步
+  - 问题：不同设备看到的标注位置不一致
+  - 解决方案：使用AR锚点和时间戳同步
+
+  挑战4：性能优化
+  - 问题：AR+视频通话耗电严重
+  - 解决方案：动态调整帧率和码率
+
+  挑战5：设备兼容性
+  - 问题：低端设备不支持ARCore
+  - 解决方案：功能降级，仅使用2D标注
+
+## 具体实现细节
+
+  Gradle依赖配置：
+  dependencies {
+      // UI
+      implementation 'androidx.compose.ui:ui:1.5.4'
+      implementation 'androidx.compose.material3:material3:1.1.2'
+
+      // LiveKit
+      implementation 'io.livekit:livekit-android:2.20.2'
+
+      // AR
+      implementation 'com.google.ar:core:1.50.0'
+
+      // 网络
+      implementation 'com.squareup.retrofit2:retrofit:2.9.0'
+      implementation 'com.squareup.okhttp3:okhttp:4.12.0'
+
+      // 本地存储
+      implementation 'androidx.room:room-runtime:2.6.1'
+
+      // 权限
+      implementation 'pub.devrel:easypermissions:3.0.0'
+  }
+
+  核心组件示例：
+  class MainActivity : ComponentActivity() {
+      override fun onCreate(savedInstanceState: Bundle?) {
+          super.onCreate(savedInstanceState)
+          setContent {
+              SynergyLensTheme {
+                  MainNavigation()
+              }
+          }
+      }
+  }
+
+  @Composable
+  fun CallScreen(
+      room: Room,
+      onAnnotationClick: () -> Unit
+  ) {
+      val room by rememberLiveKitRoom()
+      val remoteParticipants by room.remoteParticipants.collectAsState()
+      val currentParticipant = remoteParticipants.values.firstOrNull()
+
+      Box(modifier = Modifier.fillMaxSize()) {
+          // 视频渲染 - 使用最新的VideoRenderer组件
+          currentParticipant?.let { participant ->
+              VideoRenderer(
+                  participant = participant,
+                  modifier = Modifier.fillMaxSize()
+              )
+          }
+
+          // 控制按钮
+          CallControls(
+              room = room,
+              onAnnotationClick = onAnnotationClick
+          )
+      }
+  }
+
+  class LiveKitManager(applicationContext: Context) {
+      private val room = LiveKit.create(
+          appContext = applicationContext,
+          options = RoomOptions(
+              adaptiveStream = true,
+              dynacast = true,
+              // 新版本特性：端到端加密
+              e2eeOptions = E2EEOptions(
+                  keyProvider = BaseKeyProvider("your-encryption-key")
+              )
+          )
+      )
+
+      suspend fun connectToRoom(url: String, token: String) {
+          try {
+              room.connect(url, token)
+              // 新版本API：使用TrackPublication来管理音视频
+              room.localParticipant.setMicrophoneEnabled(true)
+              room.localParticipant.setCameraEnabled(true)
+          } catch (e: Exception) {
+              // 新版本错误处理
+              when (e) {
+                  is ConnectException -> println("连接失败: ${e.message}")
+                  is AuthenticationException -> println("认证失败")
+                  else -> println("其他错误: ${e.message}")
+              }
+          }
+      }
+
+      fun disconnect() {
+          room.disconnect()
+      }
+
+      fun release() {
+          room.release()
+      }
+  }
+
+  class ARAnnotationManager(
+      private val arFragment: ArFragment
+  ) {
+      fun placeArrow(x: Float, y: Float) {
+          // 使用ARCore v1.50.0增强的命中测试
+          val frame = arFragment.arSceneView.arFrame ?: return
+          val hitResults = frame.hitTest(x, y)
+
+          val hitResult = hitResults.firstOrNull {
+              it.trackable is Plane && (it.trackable as Plane).isPoseInPolygon(it.hitPose)
+          } ?: return
+
+          val anchor = hitResult.createAnchor()
+          val anchorNode = AnchorNode(anchor)
+          val arrowNode = createArrowNode()
+          anchorNode.addChild(arrowNode)
+          arFragment.arSceneView.scene.addChild(anchorNode)
+      }
+
+      fun createArrowNode(): Node {
+          // 使用ARCore 1.50.0的光照估计创建更真实的渲染
+          return Node().apply {
+              renderable = ShapeFactory.makeCylinder(
+                  0.01f, 0.1f,
+                  Vector3(0f, 0.05f, 0f),
+                  MaterialFactory.makeOpaqueWithColor(
+                      context,
+                      Color(1.0f, 0.0f, 0.0f)
+                  )
+              )
+          }
+      }
+  }
+
+## 测试策略
+
+  单元测试：
+  - 登录流程测试
+  - LiveKit房间连接测试
+  - LiveKit TrackPublication管理测试
+  - AR标注创建测试
+
+  集成测试：
+  - 端到端通话测试
+  - AR标注同步测试
+  - 设备兼容性测试
+
+  UI测试：
+  - 界面交互测试
+  - 控制按钮功能测试
+
+## 部署要求
+
+  客户端要求：
+  - 最小SDK： Android 8.0 (API 26)
+  - 目标SDK： Android 16 (API 36)
+  - 权限： CAMERA, RECORD_AUDIO, INTERNET
+  - 可选： ARCore支持设备 (v1.50.0+)
+
+  服务端接口：
+  - 用户认证API
+  - LiveKit 2.x房间管理
+  - AI服务API (语音转文字等)
+  - 需要支持E2EE端到端加密