文档版本：v1.0.0
最后更新：2026年9月7日
项目名称：ReadRecite
目标平台：Android（手机 + TV）

一、项目概述

1.1 项目背景

ReadRecite 是一款基于语音识别技术的智能朗读背书软件。用户提供文本内容后进行朗读背诵，应用通过语音识别实时比对用户朗读与原文，逐字标记正确（蓝色）与错误（红色），并基于朗读情感和内容准确度进行综合评分。

1.2 核心功能

功能模块	描述
文本导入	支持用户输入或粘贴待背诵文本
实时语音识别	基于 ASR 技术将用户语音实时转文本
逐字比对与标记	读对文字变蓝色，读错文字变红色，遗漏保持黑色
情感识别	识别用户朗读语气与情感状态
智能评分	综合准确度、流利度、情感表达等多维度打分
结果回顾	全文展示标记结果，蓝色正确/红色错误/黑色遗漏

1.3 技术选型

开发语言：Kotlin
最低 SDK：API 21（Android 5.0），以兼容 TV 设备
目标 SDK：API 34（Android 14）
架构模式：MVVM + Clean Architecture
语音识别：讯飞语音识别 SDK / Google Speech Recognition API
情感分析：audEERING sensAI / 讯飞情感分析
UI 框架：Jetpack Compose（自适应手机与 TV 布局）
依赖注入：Hilt
异步处理：Kotlin Coroutines + Flow

二、开发规范

2.1 代码风格

2.1.1 语言规范

所有代码、注释、文档必须使用英文撰写
类名使用 PascalCase（如 ReciteViewModel）
函数名与变量名使用 lowerCamelCase（如 startRecognition）
常量使用 UPPER_SNAKE_CASE（如 MAX_RETRY_COUNT）
包名使用全小写，以 com.readrecite 为根包名

2.1.2 格式化工具

使用 Ktlint 强制 Kotlin 代码风格
配置文件：项目根目录的 .editorconfig
提交前执行格式化检查：

bash

./gradlew ktlintFormat
CI 流水线集成 Ktlint 检查，不通过则构建失败

2.1.3 代码质量工具

Detekt：检测代码异味和圈复杂度
Android Lint：检测 API 兼容性问题

2.2 架构规范

2.2.1 分层架构

text

┌─────────────────────────────────────────────┐ │ Presentation Layer │ │ (Compose UI / ViewModel) │ ├─────────────────────────────────────────────┤ │ Domain Layer │ │ (Use Cases / Business Logic) │ ├─────────────────────────────────────────────┤ │ Data Layer │ │ (Repository / Local/Remote Data Source) │ └─────────────────────────────────────────────┘

2.2.2 模块划分

text

app/ # 应用主模块 ├── presentation/ # UI 层 │ ├── phone/ # 手机端专属 UI │ ├── tv/ # TV 端专属 UI │ └── common/ # 双端共用 UI 组件 ├── domain/ # 领域层 │ ├── model/ # 数据模型 │ ├── usecase/ # 用例 │ └── repository/ # 仓储接口 ├── data/ # 数据层 │ ├── repository/ # 仓储实现 │ ├── local/ # 本地数据源（Room） │ └── remote/ # 远程数据源（API） └── di/ # 依赖注入配置

2.3 命名规范

类型	命名规则	示例
Activity/Fragment	`{功能}Activity` / `{功能}Fragment`	`ReciteActivity`
ViewModel	`{功能}ViewModel`	`ReciteViewModel`
Repository	`{功能}Repository`	`ReciteRepository`
UseCase	`{动作}{功能}UseCase`	`CompareTextUseCase`
Composable	`{功能}Screen` / `{组件}Component`	`ReciteScreen`, `TextHighlightComponent`
测试类	`{被测试类}Test`	`ReciteViewModelTest`

三、功能模块详细设计

3.1 文本管理模块

功能：用户文本的导入、存储与管理

核心类：

TextRepository：文本数据仓储
TextEntity：Room 实体类
ImportTextUseCase：文本导入用例

数据库设计（Room）：

kotlin

@Entity(tableName = "recite_texts") data class TextEntity( @PrimaryKey(autoGenerate = true) val id: Long = 0, val title: String, val content: String, val createdAt: Long, val lastRecitedAt: Long? )

3.2 语音识别模块

功能：实时语音识别与转写

技术方案：

手机端：讯飞语音识别 SDK（支持离线）或 Google Speech Recognition API
TV 端：优先使用遥控器麦克风输入

核心接口：

kotlin

interface SpeechRecognizer { fun startRecognition(onPartialResult: (String) -> Unit) fun stopRecognition(): String fun isSpeaking(): Boolean }

注意事项：

TV 设备不支持 android.hardware.microphone 硬件特性，需通过遥控器麦克风获取音频
在 AndroidManifest.xml 中声明 android.hardware.microphone 为 required="false"

3.3 文本比对与标记模块

功能：逐字比对用户朗读内容与原文，生成标记结果

核心算法：

kotlin

data class CharResult( val char: Char, val status: CharStatus, // CORRECT, WRONG, MISSING val index: Int ) enum class CharStatus { CORRECT, WRONG, MISSING }

比对逻辑：

将原文按字符拆分
将识别结果按字符拆分
使用最长公共子序列（LCS）算法进行对齐
匹配的字符标记为 CORRECT（蓝色）
不匹配的字符标记为 WRONG（红色）
原文中未被匹配的字符标记为 MISSING（黑色）

3.4 情感识别模块

功能：分析用户朗读时的语气与情感状态

技术方案：

使用 audEERING sensAI 或讯飞情感分析 SDK
输出情感维度：愉悦度（Valence）、唤醒度（Arousal）、优势度（Dominance）

评分维度：

情感匹配度：朗读情感与文本情感的一致性
情感丰富度：情感表达的饱满程度
节奏感：语速与停顿的自然度

3.5 评分模块

功能：综合多维度输出评分

评分维度：

维度	权重	说明
准确度	40%	正确字符数 / 总字符数
流利度	20%	语速、停顿、连贯性
完整度	20%	遗漏字符数 / 总字符数
情感表达	20%	情感识别结果评分

评分输出：

总分（0-100）
各维度分项得分
错误详情列表（位置、错误类型）

四、UI/UX 设计规范

4.1 手机端设计

背诵界面：

全屏显示当前背诵句子
每个文字独立显示
正确文字：蓝色（#2196F3）
错误文字：红色（#F44336）
遗漏文字：黑色（#000000）
类似卡拉 OK 歌词的横向滚动效果

结果回顾界面：

全文展示
段落级别颜色标记
可滚动查看所有标记结果

4.2 TV 端适配规范

TV 设备与手机设备的硬件差异显著，需特别注意以下规范：

4.2.1 声明 TV 支持

在 AndroidManifest.xml 中声明：

xml

<uses-feature android:name="android.hardware.touchscreen" android:required="false" /> <uses-feature android:name="android.software.leanback" android:required="true" />

4.2.2 运行时检测 TV 设备

kotlin

val isTelevision = packageManager.hasSystemFeature(PackageManager.FEATURE_LEANBACK) if (isTelevision) { // 加载 TV 专属布局 } else { // 加载手机布局 }

4.2.3 TV 交互规范

焦点导航：使用 D-pad 遥控器操作，确保所有可交互元素可通过方向键聚焦
文字大小：TV 端文字尺寸至少为手机端的 1.5 倍，确保远距离可读
间距规范：焦点元素间距至少 48dp，避免误触
无触摸依赖：所有交互必须支持遥控器操作

4.2.4 TV 布局适配

使用 Jetpack Compose 的 LocalConfiguration 检测屏幕类型，动态切换布局：

kotlin

@Composable fun ReciteScreen() { val isTv = LocalConfiguration.current.isTv if (isTv) { ReciteTvScreen() } else { RecitePhoneScreen() } }

4.3 双端共用规范

使用 Material Design 组件构建 UI
支持屏幕方向变化和折叠状态切换
应用进入后台时暂停录音，回到前台时恢复

五、基准测试规范

5.1 性能基准测试（Macrobenchmark）

使用 Jetpack Macrobenchmark 库进行应用级性能测试。

5.1.1 测试模块配置

在 benchmark 模块的 build.gradle.kts 中：

kotlin

android { defaultConfig { // 确保基准测试在已编译优化状态下运行 includeInProfile = true } } dependencies { implementation("androidx.benchmark:benchmark-macro-junit4:1.4.0") }

5.1.2 启动性能测试

kotlin

@RunWith(AndroidJUnit4::class) class StartupBenchmark { @Test fun startup() = benchmarkRule.measureRepeated( packageName = "com.readrecite", metrics = listOf(StartupTimingMetric()), iterations = 5, startupMode = StartupMode.COLD ) { pressHome() startActivityAndWait() } }

验收标准：冷启动时间 ≤ 2 秒

5.1.3 UI 帧率测试

kotlin

@Test fun reciteScroll() = benchmarkRule.measureRepeated( packageName = "com.readrecite", metrics = listOf(FrameTimingMetric()), iterations = 10 ) { // 模拟滚动背诵结果页面 scrollToEnd() }

验收标准：丢帧率 ≤ 5%

5.2 微基准测试（Microbenchmark）

使用 androidx.benchmark:benchmark-junit4 进行核心算法性能测试。

kotlin

@Benchmark fun textComparison() { val result = textComparator.compare(originalText, recognizedText) }

验收标准：

1000 字文本比对 ≤ 50ms
内存分配 ≤ 5MB

5.3 语音识别基准测试

测试项	指标	验收标准
识别延迟	从说话到显示结果的时间	≤ 300ms
识别准确率	标准测试集	≥ 90%
实时因子	处理时间/语音时长	≤ 0.5
CPU 占用	识别过程中	≤ 30%
内存占用	识别过程中	≤ 150MB

5.4 性能监控

使用 Android Profiler 监控 CPU、内存、网络
使用 LeakCanary 检测内存泄漏
使用 Firebase Performance Monitoring 进行线上性能监控

六、CI/CD 配置（cnb.cool）

6.1 cnb.cool 简介

cnb.cool 是腾讯云推出的云原生构建平台，支持通过项目根目录的 .cnb.yml 文件配置构建任务。

6.2 构建配置（.cnb.yml）

在项目根目录创建 .cnb.yml 文件：

yaml

master: push: - docker: # 使用 Android SDK 镜像进行构建[reference:33] image: mobiledevops/android-sdk-image:34.0.1 # 挂载 Gradle 缓存目录，加快构建速度[reference:34] volumes: - /root/.gradle:cow stages: # 阶段1：执行 Gradle 构建 - name: android-build script: ./gradlew clean assembleRelease # 阶段2：列出生成的 APK 文件[reference:35] - name: list-apk script: ls -la ./app/build/outputs/apk/release/ # 阶段3：上传 APK 作为构建产物 - name: upload-apk script: | # 将 APK 复制到制品目录 mkdir -p ./artifacts cp ./app/build/outputs/apk/release/*.apk ./artifacts/

6.3 多分支构建策略

yaml

不同分支使用不同构建配置

master: push: - docker: image: mobiledevops/android-sdk-image:34.0.1 volumes: - /root/.gradle:cow stages: - name: build-release script: ./gradlew assembleRelease develop: push: - docker: image: mobiledevops/android-sdk-image:34.0.1 volumes: - /root/.gradle:cow stages: - name: build-debug script: ./gradlew assembleDebug - name: run-tests script: ./gradlew test

6.4 部署配置（.cnb/tag_deploy.yml）

如需自动化部署，可在 .cnb/tag_deploy.yml 中配置部署环境：

yaml

environments:

name: production description: 生产环境 permissions: roles: - master - developer deploy:
- name: 发布 APK env: BUILD_TYPE: release

6.5 构建优化建议

缓存 Gradle 依赖：通过挂载 /root/.gradle 目录避免重复下载
使用国内镜像：在 build.gradle 中配置国内 Maven 镜像加速依赖下载
启用 Gradle 守护进程：在 gradle.properties 中配置 org.gradle.daemon=true
并行构建：配置 org.gradle.parallel=true

七、测试策略

7.1 单元测试

框架：JUnit 4 + MockK
覆盖范围：Domain 层所有 UseCase、Repository 接口
覆盖率目标：≥ 80%

7.2 集成测试

框架：AndroidX Test + Espresso
覆盖范围：Repository 实现、数据库操作、API 调用

7.3 UI 测试

框架：Compose UI Test
覆盖范围：核心用户流程（导入文本 → 朗读 → 查看结果）

7.4 TV 专项测试

在 Android TV 模拟器和实体 TV 设备上测试
测试遥控器导航的所有交互路径
测试不同分辨率下的 UI 显示（1080p、4K）

7.5 语音识别精度测试

使用多样化语音数据（不同口音、语速、音量、背景噪音）进行大规模测试。

八、部署与运维

8.1 版本号规范

遵循语义化版本规范：MAJOR.MINOR.PATCH

versionCode：递增整数
versionName：语义化版本号

8.2 签名配置

在 gradle.properties 或环境变量中配置签名信息：

properties

RELEASE_STORE_FILE=/path/to/keystore RELEASE_STORE_PASSWORD=*** RELEASE_KEY_ALIAS=alias RELEASE_KEY_PASSWORD=***

8.3 多渠道打包（可选）

如需区分手机版和 TV 版，可使用 productFlavors：

kotlin

android { flavorDimensions "device" productFlavors { create("phone") { dimension = "device" // 手机专属配置 } create("tv") { dimension = "device" // TV 专属配置 } } }

九、附录

9.1 依赖清单（核心）

kotlin

dependencies { // Jetpack implementation("androidx.core:core-ktx:1.12.0") implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.7.0") implementation("androidx.room:room-runtime:2.6.1")

// Compose
implementation("androidx.compose.ui:ui:1.6.0")
implementation("androidx.compose.material3:material3:1.2.0")

// TV 支持
implementation("androidx.leanback:leanback:1.0.0")

// 依赖注入
implementation("com.google.dagger:hilt-android:2.48")

// 测试
testImplementation("junit:junit:4.13.2")
androidTestImplementation("androidx.test.ext:junit:1.1.5")
androidTestImplementation("androidx.benchmark:benchmark-junit4:1.4.0")

}

朗读背书软件（ReadRecite）Android 开发文档1.0

一、项目概述

1.1 项目背景

1.2 核心功能

1.3 技术选型

二、开发规范

2.1 代码风格

2.1.1 语言规范

2.1.2 格式化工具

2.1.3 代码质量工具

2.2 架构规范

2.2.1 分层架构

2.2.2 模块划分

2.3 命名规范

三、功能模块详细设计

3.1 文本管理模块

3.2 语音识别模块

3.3 文本比对与标记模块

3.4 情感识别模块

3.5 评分模块

四、UI/UX 设计规范

4.1 手机端设计

4.2 TV 端适配规范

4.2.1 声明 TV 支持

4.2.2 运行时检测 TV 设备

4.2.3 TV 交互规范

4.2.4 TV 布局适配

4.3 双端共用规范

五、基准测试规范

5.1 性能基准测试（Macrobenchmark）

5.1.1 测试模块配置

5.1.2 启动性能测试

5.1.3 UI 帧率测试

5.2 微基准测试（Microbenchmark）

5.3 语音识别基准测试

5.4 性能监控

六、CI/CD 配置（cnb.cool）

6.1 cnb.cool 简介

6.2 构建配置（.cnb.yml）

6.3 多分支构建策略

不同分支使用不同构建配置

6.4 部署配置（.cnb/tag_deploy.yml）

6.5 构建优化建议

七、测试策略

7.1 单元测试

7.2 集成测试

7.3 UI 测试

7.4 TV 专项测试

7.5 语音识别精度测试

八、部署与运维

8.1 版本号规范

8.2 签名配置

8.3 多渠道打包（可选）

九、附录

9.1 依赖清单（核心）

9.2 参考资料