462 lines
14 KiB
Markdown
462 lines
14 KiB
Markdown
# 别摇小鸡 - 技术决策与问题记录
|
||
|
||
> 基于产品需求文档分析的技术架构决策点和待解决问题汇总
|
||
|
||
## 📋 项目概览
|
||
|
||
**项目名称：** 别摇小鸡心情记录App
|
||
**开发平台：** Android原生（Kotlin）
|
||
**当前版本：** V1.0 MVP
|
||
**更新日期：** 2025-10-22
|
||
|
||
---
|
||
|
||
## 🏗️ 已确认的技术架构
|
||
|
||
### 核心技术栈
|
||
- **开发语言：** Kotlin
|
||
- **UI框架：** Android Jetpack (ViewModel, LiveData, Navigation)
|
||
- **动画引擎：** Lottie + Property Animation
|
||
- **传感器：** Android Sensor Framework (Accelerometer)
|
||
- **数据存储：** SQLite Room + SharedPreferences
|
||
- **图片处理：** Glide
|
||
|
||
### 功能开发优先级
|
||
**优先级1 (V1.0核心功能)：**
|
||
- ✅ 六种基础情绪选择（开心、生气、悲伤、烦恼、孤单、害怕）
|
||
- ✅ 传感器摇晃检测与心情值计算
|
||
- ✅ 小鸡2D动画响应系统
|
||
- ✅ 心情记录保存（文字+心情值）
|
||
|
||
**优先级2 (V1.0后续功能)：**
|
||
- ✅ 心情日历月视图展示
|
||
- ✅ 基础用户设置（昵称、头像）
|
||
|
||
**优先级3 (V1.1+功能)：**
|
||
- 📷 图片添加与编辑功能
|
||
- 📊 基础心情统计（饼图、趋势图）
|
||
- 🔄 云端数据同步选项
|
||
|
||
---
|
||
|
||
## 🎯 UI/UX 交互细节 (待UI设计图后确认)
|
||
|
||
### 页面交互确认点
|
||
1. **情绪选择页**
|
||
- [ ] 情绪按钮切换交互方式
|
||
- [ ] 选中状态的视觉反馈效果
|
||
|
||
2. **准备摇晃页**
|
||
- [ ] 是否需要倒计时动画(3-2-1-开始)
|
||
- [ ] 不同情绪的引导文案差异化
|
||
|
||
3. **摇晃页面**
|
||
- [ ] 心情值进度条的位置设计(顶部/底部)
|
||
- [ ] 小鸡晕眩状态的渐进变化
|
||
|
||
4. **结果展示页**
|
||
- [ ] 心情强度文字的动画效果
|
||
- [ ] 心情值数字的计数动画
|
||
|
||
### 边界情况处理
|
||
5. **异常场景**
|
||
- [ ] 摇晃过程中电话接入处理
|
||
- [ ] 传感器故障时的备用方案
|
||
|
||
6. **用户输入**
|
||
- [ ] 文字输入字数限制建议(建议200字)
|
||
- [ ] 自动保存草稿功能
|
||
|
||
---
|
||
|
||
## 🔧 技术实现问题记录
|
||
|
||
### 传感器与算法相关 (V1.0基础实现)
|
||
|
||
**高优先级：**
|
||
- [ ] **心情值算法调优**
|
||
- 当前公式：`心情值 = Σ(加速度幅值) / 摇晃时间`
|
||
- 需要根据实际测试数据调整权重系数
|
||
- 考虑不同设备传感器的差异性
|
||
|
||
- [ ] **摇晃检测阈值设定**
|
||
- 最小摇晃时间：文档建议3秒(可能需要调整到2秒)
|
||
- 加速度阈值：区分正常使用和主动摇晃
|
||
- 采样频率：50Hz是否合适
|
||
|
||
**中优先级：**
|
||
- [ ] **数据滤波算法**
|
||
- 低通滤波器参数设置
|
||
- 高频噪声去除策略
|
||
- 设备兼容性处理
|
||
|
||
### 动画与性能相关 (V1.0基础实现)
|
||
|
||
**高优先级：**
|
||
- [ ] **小鸡动画系统**
|
||
- 占位图资源路径规划
|
||
- 动画状态机设计
|
||
- 与传感器数据的实时响应
|
||
|
||
- [ ] **动画性能优化**
|
||
- 使用Hardware Layer加速
|
||
- ViewPropertyAnimator vs Lottie选择
|
||
- 内存占用控制
|
||
|
||
**中优先级：**
|
||
- [ ] **音效反馈系统** (可选功能)
|
||
- 摇晃过程中的音效设计
|
||
- 音效文件压缩和缓存
|
||
|
||
### 数据存储与架构
|
||
|
||
**V1.0基础实现：**
|
||
- [ ] **数据库结构确认**
|
||
```sql
|
||
-- 确认表结构设计是否符合实际使用场景
|
||
-- 考虑预留扩展字段
|
||
```
|
||
|
||
- [ ] **数据迁移准备**
|
||
- user_config表添加version字段
|
||
- 为未来云端同步预留接口
|
||
|
||
**V1.1+扩展准备：**
|
||
- [ ] **云端同步架构预埋**
|
||
- sync_queue表的实现
|
||
- 冲突解决策略
|
||
- 离线优先的设计模式
|
||
|
||
### 系统适配与兼容性
|
||
|
||
**高优先级：**
|
||
- [ ] **Android版本适配**
|
||
- 最低支持版本：Android 5.0 (API 21+)
|
||
- 目标版本：Android 13+ (API 33+)
|
||
- 权限管理：动态申请传感器权限
|
||
|
||
- [ ] **深色模式支持** (待确认)
|
||
- 两套色彩方案准备
|
||
- 小鸡黄在深色背景下的适配
|
||
|
||
**中优先级：**
|
||
- [ ] **字体适配策略**
|
||
- 支持系统字体大小设置
|
||
- 使用sp单位，限制最大最小字号
|
||
- 不同屏幕密度的适配
|
||
|
||
- [ ] **设备性能差异处理**
|
||
- 低端设备的动画降级
|
||
- 内存使用优化策略
|
||
|
||
---
|
||
|
||
## 📊 数据分析预埋
|
||
|
||
### 友盟集成准备 (V1.1+)
|
||
- [ ] 基础页面访问统计
|
||
- [ ] 用户行为路径追踪
|
||
- [ ] 性能监控指标
|
||
- [ ] 崩溃报告收集
|
||
|
||
### 本地数据分析
|
||
- [ ] 心情记录频率统计
|
||
- [ ] 情绪分布分析
|
||
- [ ] 摇晃强度分布
|
||
- [ ] 用户留存分析
|
||
|
||
---
|
||
|
||
## 🚀 性能优化目标
|
||
|
||
### V1.0性能指标
|
||
- [ ] App启动时间 < 2秒
|
||
- [ ] 摇晃动画延迟 < 50ms
|
||
- [ ] 内存占用 < 100MB
|
||
- [ ] 电池消耗控制
|
||
|
||
### 持续优化项
|
||
- [ ] 传感器功耗优化
|
||
- [ ] 动画渲染性能提升
|
||
- [ ] 数据库查询优化
|
||
- [ ] 图片加载和缓存策略
|
||
|
||
---
|
||
|
||
## 🏠 首页需求详细分析
|
||
|
||
### 首页核心定位
|
||
**主要功能：** 历史记录浏览展示
|
||
**次要功能：** 创建新心情记录入口
|
||
**页面性质：** 内容消费型页面（非操作型页面）
|
||
|
||
### 完整用户流程
|
||
|
||
**创建新记录流程：**
|
||
```
|
||
首页 → 点击添加心情按钮 → 底部情绪选择弹框 → 选择情绪 →
|
||
添加心情页面(摇晃页) → 心情详情编辑页 → 保存 → 返回首页显示新记录
|
||
```
|
||
|
||
**浏览历史记录流程：**
|
||
```
|
||
首页 → 左右滑动查看历史记录 → 时间指示器实时更新 →
|
||
单条记录操作(收藏/分享/查看详情)
|
||
```
|
||
|
||
### 首页页面结构
|
||
|
||
**1. 顶部导航栏 (ActionBar/Toolbar)**
|
||
- **更多按钮：** 点击弹出侧边抽屉菜单
|
||
- **统计按钮：** 跳转到统计页面
|
||
|
||
**2. 时间指示器**
|
||
- **功能：** 显示当前浏览记录的时间
|
||
- **交互：** 左右滑动历史记录时，时间动态变化到对应记录时间
|
||
- **格式：** "YYYY.MM.DD 星期几 HH:mm"
|
||
|
||
**3. 历史记录展示区 (核心区域)**
|
||
- **容器：** ViewPager2横向滑动卡片
|
||
- **卡片元素：**
|
||
- 小鸡形象（根据心情显示对应颜色和表情）
|
||
- 心情详情（情绪类型、强度、文字内容、图片）
|
||
- 操作按钮：收藏/取消收藏、分享、查看详情
|
||
- **滑动效果：** 横向推送切换动画
|
||
- **数据加载：** 初始10条 + 滑动预加载无限滚动
|
||
|
||
**4. 添加心情按钮**
|
||
- **位置：** 页面右下角FloatingActionButton
|
||
- **功能：** 触发创建新心情记录流程
|
||
|
||
### 关键技术实现方案
|
||
|
||
**1. 数据加载策略**
|
||
- **初始加载：** 最近10条历史记录
|
||
- **预加载机制：** 滑动时无感加载更多数据
|
||
- **分页实现：** Android Paging 3.x库
|
||
- **缓存策略：** Room本地数据库 + 内存缓存
|
||
|
||
**2. 页面状态管理**
|
||
- **空白状态：** 首次使用显示空页面引导
|
||
- **位置保持：** 详情页返回时保持原浏览位置
|
||
- **自动跳转：** 创建新记录后自动跳转到最新记录
|
||
|
||
**3. 交互细节**
|
||
- **情绪选择弹框：** BottomSheetDialog从底部滑出
|
||
- **弹框关闭：** 支持点击外部区域关闭
|
||
- **滑动动画：** ViewPager2 + 自定义PageTransformer
|
||
- **状态切换：** 属性动画实现平滑过渡
|
||
|
||
### 首页开发模块拆分
|
||
|
||
**阶段1：基础框架搭建**
|
||
- **模块1.1：** MainActivity基础布局结构
|
||
- **模块1.2：** 数据模型定义(MoodRecord, Emotion枚举)
|
||
- **模块1.3：** Room数据库设计和实现
|
||
- **模块1.4：** ViewModel和Repository架构
|
||
|
||
**阶段2：历史记录展示**
|
||
- **模块2.1：** 空白状态页面实现
|
||
- **模块2.2：** 历史记录卡片Fragment设计
|
||
- **模块2.3：** ViewPager2集成和分页加载
|
||
- **模块2.4：** 滑动动画和效果优化
|
||
|
||
**阶段3：添加心情功能**
|
||
- **模块3.1：** FloatingActionButton实现
|
||
- **模块3.2：** 情绪选择BottomSheet弹框
|
||
- **模块3.3：** 页面跳转和参数传递
|
||
|
||
**阶段4：交互细节完善**
|
||
- **模块4.1：** 动画效果完善
|
||
- **模块4.2：** 异常处理和边界情况
|
||
- **模块4.3：** 性能优化和内存管理
|
||
|
||
**阶段5：测试和优化**
|
||
- **模块5.1：** 端到端流程测试
|
||
- **模块5.2：** UI细节调整和完善
|
||
- **模块5.3：** 代码质量优化
|
||
|
||
### 技术风险评估和解决方案
|
||
|
||
**风险1：大量历史记录的内存占用**
|
||
- **解决方案：** ViewPager2 + FragmentStateAdapter + 分页加载
|
||
- **优化策略：** 及时回收不可见的Fragment，限制内存中同时保持的卡片数量
|
||
|
||
**风险2：滑动流畅性和动画性能**
|
||
- **解决方案：** 使用硬件加速，优化布局层级
|
||
- **测试策略：** 在低端设备上进行性能测试
|
||
|
||
**风险3：数据状态同步复杂性**
|
||
- **解决方案：** 使用LiveData + ViewModel架构，确保UI与数据状态同步
|
||
- **边界处理：** 网络异常、数据库操作失败等异常情况处理
|
||
|
||
---
|
||
|
||
## ❓ 待确认的决策点
|
||
|
||
### 已确认问题：
|
||
1. **✅ 首页定位：** 历史记录浏览为主，创建记录为辅
|
||
2. **✅ 交互流程：** 完整的创建和浏览流程已确认
|
||
3. **✅ 技术方案：** 数据加载、动画、状态管理策略已确认
|
||
4. **✅ 开发规划：** 模块化开发路径已确定
|
||
|
||
### 待确认问题：
|
||
1. **UI交互相关：** 具体的动画时长、缓动曲线参数
|
||
2. **音效反馈：** V1.0是否需要音效功能
|
||
3. **深色模式：** 是否需要支持深色主题
|
||
4. **字数限制：** 心情记录文字的长度限制
|
||
5. **侧边抽屉：** 更多按钮弹出的具体功能项
|
||
6. **统计页面：** 统计页面的具体功能和数据展示
|
||
|
||
### 其他技术风险评估：
|
||
- **传感器兼容性：** 不同设备传感器差异较大（摇晃页面）
|
||
- **动画性能：** 实时响应可能影响流畅度
|
||
- **数据准确性：** 心情值算法需要大量测试验证
|
||
|
||
## 🔄 当前开发状态
|
||
|
||
### ✅ 已完成工作
|
||
- **模块1.1**: MainActivity基础布局结构（已完成）
|
||
- **Bug修复**: 语法错误、依赖冲突、主题配置问题（已修复）
|
||
- **项目架构**: 从Compose成功转换为View系统
|
||
- **测试覆盖**: 完整的单元测试和测试数据生成器
|
||
|
||
### 🔄 当前状态
|
||
- **编译状态**: ✅ 编译成功
|
||
- **安装状态**: ✅ 可安装到设备
|
||
- **运行状态**: 🔄 主题修复待验证（需重启IDE）
|
||
|
||
### 📋 下一步计划
|
||
1. **立即任务**: 验证主题修复效果，确保应用正常启动
|
||
2. **模块1.2**: 数据模型定义（MoodRecord, Emotion枚举）
|
||
3. **模块1.3**: Room数据库设计和实现
|
||
4. **模块1.4**: ViewModel和Repository架构
|
||
|
||
### ⚠️ 待解决问题
|
||
- **文件锁定**: Gradle build目录锁定问题（需手动重启IDE解决）
|
||
- **模块名称**: 已修复settings.gradle.kts中的项目名称不一致问题
|
||
- **主题验证**: 修复后的主题需要在设备上验证
|
||
- **图标资源**: 当前使用占位图标，需要设计师提供正式资源
|
||
|
||
**2025-10-22 (Gradle构建错误修复):**
|
||
- 🐛 **问题**: Module entity with name: Chick_Mood should be available
|
||
- ✅ **分析**: settings.gradle.kts中项目名称与错误信息不一致
|
||
- ✅ **修复**: 将rootProject.name从"chick_mood"改为"Chick_Mood"
|
||
- 🔄 **待验证**: 需重启IDE解决文件锁定问题后重新构建
|
||
|
||
**2025-10-22 (R.jar文件锁定问题):**
|
||
- 🐛 **问题**: Windows系统文件锁定，无法删除R.jar文件
|
||
- ✅ **分析**: Java进程未完全释放文件句柄
|
||
- ✅ **处理**: 已强制结束Java进程，提供完整解决方案
|
||
- 🔄 **待完成**: 需用户手动关闭所有程序后删除build目录
|
||
|
||
---
|
||
|
||
## 📝 开发规范
|
||
|
||
### 核心开发原则
|
||
|
||
**1. 模块化开发**
|
||
- ✅ 每次只开发一个小模块，避免一次性编写大量代码
|
||
- ✅ 每个模块独立测试，确保功能正确性
|
||
- ✅ 模块间接口清晰，便于集成和维护
|
||
|
||
**2. 测试驱动**
|
||
- ✅ 每个模块提供必要的测试数据和测试代码
|
||
- ✅ 单元测试覆盖核心业务逻辑
|
||
- ✅ 集成测试验证模块间交互
|
||
|
||
**3. 代码质量**
|
||
- ✅ 提供必要且合适的中文注释
|
||
- ✅ 代码结构规范、科学，遵循设计模式
|
||
- ✅ 便于后续维护和功能迭代
|
||
|
||
### 编码标准
|
||
|
||
**代码结构规范**
|
||
```kotlin
|
||
/**
|
||
* 类/方法功能描述
|
||
* @param 参数说明
|
||
* @return 返回值说明
|
||
* @author 开发者
|
||
* @date 开发日期
|
||
*/
|
||
class ClassName {
|
||
// 类属性
|
||
private val property: Type = initial_value
|
||
|
||
/**
|
||
* 方法功能描述
|
||
*/
|
||
fun methodName(): ReturnType {
|
||
// 方法实现
|
||
}
|
||
}
|
||
```
|
||
|
||
**注释规范**
|
||
- 类和公共方法必须包含KDoc注释
|
||
- 复杂业务逻辑添加行内注释说明
|
||
- 常量和重要变量添加用途说明
|
||
|
||
**命名规范**
|
||
- 类名：PascalCase (例：`MoodActivity`)
|
||
- 方法名：camelCase (例：`calculateMoodValue()`)
|
||
- 常量：UPPER_SNAKE_CASE (例：`MAX_SHAKE_DURATION`)
|
||
- 变量：camelCase (例：`currentMoodValue`)
|
||
|
||
## 📝 更新记录
|
||
|
||
**2025-10-22:**
|
||
- 创建技术决策文档
|
||
- 梳理V1.0核心技术架构
|
||
- 记录待解决的交互和技术问题
|
||
- 确定功能开发优先级
|
||
|
||
**2025-10-22 (开发规范):**
|
||
- 添加模块化开发原则
|
||
- 确立测试驱动开发流程
|
||
- 制定代码质量和注释标准
|
||
- 明确编码规范和命名约定
|
||
|
||
**2025-10-22 (首页需求分析):**
|
||
- 完成首页UI分析和交互流程理解
|
||
- 明确首页定位：历史记录浏览为主，创建记录为辅
|
||
- 制定详细的模块化开发规划（5个阶段，18个模块）
|
||
- 确定技术实现方案和风险控制策略
|
||
- 记录完整用户流程和页面结构需求
|
||
|
||
**2025-10-22 (模块1.1开发完成):**
|
||
- ✅ 完成MainActivity基础布局结构搭建
|
||
- ✅ 转换项目架构从Compose到View系统
|
||
- ✅ 添加必要的依赖库（Room、ViewPager2、LiveData等）
|
||
- ✅ 创建完整的布局文件和资源文件
|
||
- ✅ 实现ViewBinding和基础组件初始化
|
||
- ✅ 添加完整的单元测试覆盖
|
||
|
||
**2025-10-22 (Bug修复记录):**
|
||
- 🐛 **问题1**: MainActivity语法错误（时间格式化缺少右括号）
|
||
- ✅ 修复：修正`timeFormatter.format(Date(timestamp))`语法
|
||
- 🐛 **问题2**: Compose依赖冲突导致编译失败
|
||
- ✅ 修复：删除所有Compose相关文件和依赖
|
||
- 🐛 **问题3**: 应用启动闪退（主题配置不兼容）
|
||
- ✅ 定位：崩溃日志显示布局解析失败
|
||
- ✅ 分析：Material主题缺少AppCompat支持
|
||
- ✅ 修复：更新主题为`Theme.AppCompat.Light.NoActionBar`
|
||
- 🔄 待验证：需重启IDE解决文件锁定问题
|
||
|
||
**技术选型决策（View系统 vs Compose）：**
|
||
- ✅ **选择View系统原因**：
|
||
- 复杂交互支持更好（ViewPager2横向滑动、传感器集成）
|
||
- 性能优化更直接（内存管理、硬件加速）
|
||
- 开发复杂度更低（团队熟悉度高、调试工具完善）
|
||
- 长期维护成本更低（稳定性、可预测性）
|
||
- ❌ **Compose潜在问题**：
|
||
- 复杂手势处理和自定义动画实现复杂度高
|
||
- 大量数据内存占用控制困难
|
||
- API稳定性有待观察
|
||
|
||
---
|
||
|
||
*此文档将随着开发进展持续更新，记录重要的技术决策和解决方案。* |