# tibdroid

**Repository Path**: teachitback/tibdroid

## Basic Information

- **Project Name**: tibdroid
- **Description**: tibdroid app work with tibclaw
- **Primary Language**: Java
- **License**: BSL-1.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TibDroid - TeachItBack Android Client

[![Android](https://img.shields.io/badge/Android-13%2B-green)](https://developer.android.com/)
[![Kotlin](https://img.shields.io/badge/Kotlin-1.9-blue)](https://kotlinlang.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 📱 项目简介

TibDroid 是 TeachItBack 学习助手系统的 Android 客户端应用，为学生提供便捷的移动端学习体验。应用通过 Zenoh 协议与本地 TibClaw 服务器通信，实现文档 OCR、AI 分析和知识问答等功能。

## ✨ 核心功能

### 当前实现 (v1.0)

- 📝 **聊天界面** - 简洁直观的对话式交互
- 📤 **文件上传** - 支持图片和文档上传
- 📷 **相机集成** - 拍照快速获取学习资料
- 💾 **消息持久化** - Room 数据库本地存储
- 🎨 **现代 UI** - Material Design 3 设计风格

### 即将推出的功能

- 🔍 **OCR 识别** - DeepSeek 智能文字识别
- 🤖 **AI 分析** - 智能摘要和知识提取
- 📊 **学习统计** - 学习进度追踪
- 📚 **错题本** - 知识薄弱点管理
- 🧮 **智能测验** - 自动生成练习题

## 🏗️ 技术栈

### 核心技术

- **Kotlin** - 现代化 Android 开发语言
- **Jetpack Compose** - 声明式 UI 框架
- **Room** - Android 官方持久化方案
- **Coroutines & Flow** - 响应式编程
- **ViewModel & LiveData** - MVVM 架构组件
- **ViewBinding** - 类型安全的视图绑定

### 通信协议

- **Zenoh** - 高性能物联网数据平面
  - 低延迟 P2P 通信
  - 支持路由和 NAT 穿透
  - 类型安全的消息传递

### 测试框架

- **JUnit** - 单元测试
- **Coroutines Test** - 协程测试支持
- **TDD** - 测试驱动开发流程

## 📁 项目结构

```
tibdroid/
├── app/
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/com/teachitback/tibdroid/
│   │   │   │   ├── data/
│   │   │   │   │   ├── local/          # Room 数据库
│   │   │   │   │   ├── model/          # 数据模型
│   │   │   │   │   └── repository/    # 仓库层
│   │   │   │   ├── ui/
│   │   │   │   │   └── chat/          # 聊天界面
│   │   │   │   └── MainActivity.kt
│   │   │   └── res/                 # 资源文件
│   │   └── test/                     # 单元测试
│   └── build.gradle
├── docs/
│   └── plans/                        # 开发计划
├── gradle/
│   └── wrapper/
├── .gitignore
├── build.gradle
├── settings.gradle
├── gradlew
├── gradlew.bat
└── LICENSE
```

## 🚀 快速开始

### 环境要求

- **Android Studio** - Koala (2023.1.1) 或更高版本
- **JDK** - OpenJDK 11 或更高版本
- **Android SDK** - API 34 (Android 14)
- **Gradle** - 8.5

### 克隆项目

```bash
git clone https://gitee.com/teachitback/tibdroid.git
cd tibdroid
```

### 构建应用

**开发版 (Debug):**
```bash
./gradlew assembleDebug
```

**发布版 (Release):**
```bash
./gradlew assembleRelease
```

### 安装到设备

```bash
./gradlew installDebug
```

### 运行测试

```bash
# 单元测试
./gradlew test

# Instrumented 测试
./gradlew connectedAndroidTest
```

## 💻 开发指南

### 编码规范

- **Kotlin Coding Conventions** - 遵循官方代码规范
- **TDD 原则** - 先写测试，再写实现
- **MVVM 架构** - 保持视图和逻辑分离

### 提交规范

使用语义化提交信息：

```
feat: 添加新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构代码
test: 添加或修改测试
chore: 构建/工具配置更新
```

### 分支策略

- `master` - 稳定发布版本
- `feature/*` - 新功能开发
- `fix/*` - 问题修复
- `hotfix/*` - 紧急修复

## 🔧 配置说明

### Zenoh 连接配置

应用通过 Zenoh 路由器与 TibClaw 服务器通信。配置说明请参考 [TibClaw 仓库](https://gitee.com/teachitback/tibclaw)。

### 数据库版本管理

当前数据库版本：`v1`

升级时请：
1. 更新 `version` 号码
2. 实现 `Migration` 类
3. 添加到 `addMigrations()`

## 📊 架构设计

### MVVM 模式

```mermaid
graph TB
    View[View<br/>Activity/Fragment] -->|observes| ViewModel[ViewModel<br/>Business Logic]
    ViewModel -->|uses| Repository[Repository<br/>Data Access]
    Repository -->|uses| Room[Room<br/>Local Database]

    Room -->|Flow推送| ViewModel
    ViewModel -->|StateFlow| View

    style View fill:#2d3748
    style ViewModel fill:#4a5568
    style Repository fill:#718096
    style Room fill:#a0aec0
```

### 数据流

```mermaid
sequenceDiagram
    participant User as 用户
    participant View as View
    participant VM as ViewModel
    participant Repo as Repository
    participant Room as Room DB

    User->>View: 1. 用户输入
    View->>VM: 2. 调用业务逻辑
    VM->>Repo: 3. 持久化数据
    Repo->>Room: 4. 写入数据库
    Room-->>Repo: 4.1 Flow推送更新
    Repo-->>VM: 4.2 Flow数据更新
    VM->>VM: 5. 转换为StateFlow
    VM-->>View: 6. StateFlow更新
    View->>User: 7. 更新UI显示

    Note over User,Room: 数据流向
```

## 🧪 测试策略

### 单元测试

- **Repository 层** - 使用内存数据库测试 DAO
- **ViewModel 层** - Mock Repository 测试业务逻辑
- **Model 层** - 验证数据类行为

### 测试覆盖率目标

- **目标**: 80%+ 核心逻辑覆盖率
- **工具**: JaCoCo 代码覆盖率报告

## 📱 截图

### 主界面
- 现代化聊天界面
- 消息气泡展示
- 快捷操作按钮

### 消息类型
- 用户消息（蓝色）
- AI 回复（灰色）
- 图片预览
- 文件上传

## 🤝 贡献指南

我们欢迎所有形式的贡献！

### 报告问题

请在 [Issues](https://gitee.com/teachitback/tibdroid/issues) 页面提交 bug 报告或功能请求。

### 提交代码

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 推送分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 代码审查

所有 PR 必须通过：
- ✅ CI/CD 检查
- ✅ 代码审查
- ✅ 测试覆盖检查

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🔗 相关链接

- **主仓库**: [TeachItBack](https://gitee.com/teachitback/teachitback)
- **TibClaw 服务器**: [TibClaw](https://gitee.com/teachitback/tibclaw)
- **Zenoh 文档**: [Eclipse Zenoh](https://zenoh.io/)

## 👥 团队

- **开发**: TeachItBack 团队
- **维护**: TeachItBack 社区

## 📮 联系方式

- **邮箱**: support@teachitback.com
- **问题反馈**: [GitHub/Gitee Issues](https://gitee.com/teachitback/tibdroid/issues)

---

Made with ❤️ by TeachItBack Team