265 lines
8.4 KiB
Markdown
265 lines
8.4 KiB
Markdown
# 情景诗词 - 项目分析报告
|
||
|
||
> 生成时间: 2026-04-18
|
||
> 版本: 1.6.0+26041801
|
||
> 分析工具: flutter analyze
|
||
|
||
---
|
||
|
||
## 一、当前代码质量概览
|
||
|
||
| 指标 | 数量 | 说明 |
|
||
|------|------|------|
|
||
| ❌ 错误 (error) | 0 | 无编译错误 |
|
||
| ⚠️ 警告 (warning) | 0 | 已全部清理 |
|
||
| ℹ️ 提示 (info) | 164 | 需逐步优化 |
|
||
| 📁 文件名不规范 | 20 | 使用连字符命名 |
|
||
| 🔄 废弃API | 25 | withOpacity/activeColor等 |
|
||
| 🔀 异步上下文 | 10 | use_build_context_synchronously |
|
||
|
||
---
|
||
|
||
## 二、需要加强的功能（按优先级排序）
|
||
|
||
### 🔴 优先级 5 - 核心功能缺失
|
||
|
||
1. **☁️ 云端同步**
|
||
- 位置: `lib/views/profile/guide/app-data.dart:1059`
|
||
- 现状: 仅显示"云端同步功能开发中..."
|
||
- 建议: 实现用户数据云端备份与恢复，支持跨设备同步
|
||
- 依赖: 需要后端API支持
|
||
|
||
2. **🔐 用户账号系统**
|
||
- 现状: 仅有投票凭证填写（`login_register_dialog.dart`），无完整账号体系
|
||
- 建议: 实现注册/登录/个人信息管理，为云端同步和社交功能提供基础
|
||
- 依赖: 后端用户系统API
|
||
|
||
3. **📱 二维码能力**
|
||
- 现状: CHANGELOG中标记为开发中
|
||
- 建议: 支持扫码分享诗词、扫码添加好友、生成诗词卡片二维码
|
||
|
||
### 🟠 优先级 4 - 体验优化
|
||
|
||
4. **📖 诗词详情页**
|
||
- 位置: `lib/views/active/popular_page.dart:616` (TODO)
|
||
- 现状: 热门诗词点击后跳转详情页未实现
|
||
- 建议: 实现完整诗词详情页，包含原文/译文/赏析/作者信息
|
||
|
||
5. **🔍 搜索设置功能**
|
||
- 位置: `lib/views/active/active_search_page.dart:206`
|
||
- 现状: 搜索页面"搜索设置"标记为开发中
|
||
- 建议: 支持搜索范围、搜索历史管理、搜索偏好设置
|
||
|
||
6. **📊 历史记录详情与分享**
|
||
- 位置: `lib/views/profile/history_page.dart:515-522`
|
||
- 现状: 分享功能和查看详情功能均标记为开发中
|
||
- 建议: 实现历史记录的详情查看和分享功能
|
||
|
||
7. **🎨 个性化主题设置**
|
||
- 位置: `lib/views/profile/theme/app-diy.dart:84-96`
|
||
- 现状: 弹出"个性化设置开发中"提示
|
||
- 建议: 实现自定义主题色、字体、背景等个性化设置
|
||
|
||
### 🟡 优先级 3 - 功能完善
|
||
|
||
8. **🏠 HarmonyOS桌面小组件**
|
||
- 现状: CHANGELOG中标记为开发中
|
||
- 建议: 完善2x2/4x4布局，天气显示、每日诗句推送
|
||
|
||
9. **📝 笔记功能增强**
|
||
- 现状: 基础笔记功能已有，但缺少富文本、图片附件
|
||
- 建议: 支持Markdown、插入图片、语音笔记
|
||
|
||
10. **🏆 诗词挑战增强**
|
||
- 现状: 基础答题功能已有
|
||
- 建议: 增加排行榜、每日挑战、成就系统、错题本
|
||
|
||
---
|
||
|
||
## 三、现有问题分析
|
||
|
||
### 🐛 Bug类问题
|
||
|
||
| # | 问题 | 位置 | 严重度 | 状态 |
|
||
|---|------|------|--------|------|
|
||
| 1 | `withOpacity` 废弃API | 14处（per_card.dart等） | 低 | 待修复 |
|
||
| 2 | `activeColor` 废弃API | 10处（多个文件） | 低 | 待修复 |
|
||
| 3 | 异步上下文使用不当 | 10处 | 中 | 待修复 |
|
||
| 4 | 文件命名不规范 | 20个文件使用连字符 | 低 | 待修复 |
|
||
| 5 | `library;` 悬空文档注释 | 5个文件 | 低 | 待修复 |
|
||
|
||
### 🏗️ 架构类问题
|
||
|
||
| # | 问题 | 说明 | 建议 |
|
||
|---|------|------|------|
|
||
| 1 | 状态管理不统一 | 部分页面用GetX，部分用setState | 统一使用GetX响应式管理 |
|
||
| 2 | 控制器职责过重 | ThemeController同时管理主题和系统监听 | 拆分为ThemeController和SystemController |
|
||
| 3 | 硬编码字符串 | 多处中文字符串直接写在代码中 | 提取为常量或国际化资源 |
|
||
| 4 | API调用分散 | HTTP请求散落在各个页面 | 统一封装为Repository层 |
|
||
| 5 | 缺少错误边界 | 页面级错误无统一处理 | 添加全局错误捕获和友好提示 |
|
||
|
||
### 📦 依赖类问题
|
||
|
||
| # | 问题 | 说明 | 建议 |
|
||
|---|------|------|------|
|
||
| 1 | 多个本地路径依赖 | audioplayers/flutter_udid/share_plus/file_picker_ohos | 确保本地包版本与上游同步 |
|
||
| 2 | 多个git源依赖 | shared_preferences/get/wakelock_plus等 | 关注上游更新，适时切换为pub.dev |
|
||
| 3 | path_provider冲突 | 已通过git源解决 | 持续关注官方鸿蒙适配进度 |
|
||
|
||
---
|
||
|
||
## 四、可新增功能建议
|
||
|
||
### 🌟 高价值功能
|
||
|
||
1. **🤖 AI诗词助手**
|
||
- 基于诗词内容的智能问答
|
||
- 诗词创作辅助（对联、续写）
|
||
- 诗词意境解读
|
||
|
||
2. **👥 社交互动**
|
||
- 诗词评论与讨论
|
||
- 好友系统与诗词分享
|
||
- 诗词创作社区
|
||
|
||
3. **📅 每日推荐**
|
||
- 基于节气/节日推荐诗词
|
||
- 个性化推荐算法
|
||
- 每日一句推送通知
|
||
|
||
4. **🎮 趣味玩法**
|
||
- 诗词接龙
|
||
- 飞花令
|
||
- 诗词拼图
|
||
- 填字游戏
|
||
|
||
### 🔧 实用功能
|
||
|
||
5. **🔊 朗读功能**
|
||
- TTS语音朗读诗词
|
||
- 多种朗读风格选择
|
||
- 背景音乐配合
|
||
|
||
6. **📖 学习模式**
|
||
- 诗词背诵模式（逐句隐藏）
|
||
- 诗词默写模式
|
||
- 学习进度追踪
|
||
|
||
7. **📊 数据可视化**
|
||
- 个人阅读统计图表
|
||
- 诗词偏好分析
|
||
- 学习趋势报告
|
||
|
||
8. **🎯 智能收藏**
|
||
- 自动分类收藏
|
||
- 标签管理系统
|
||
- 智能去重
|
||
|
||
9. **🌙 番茄钟模式**
|
||
- 专注阅读计时
|
||
- 阅读时长统计
|
||
- 阅读目标设定
|
||
|
||
10. **📱 多端适配**
|
||
- iPad适配优化
|
||
- 折叠屏适配
|
||
- 手表端诗词推送
|
||
|
||
---
|
||
|
||
## 五、代码规范待改进项
|
||
|
||
### 文件命名（20个文件）
|
||
|
||
当前使用连字符命名（`app-diy.dart`），Dart规范要求使用下划线命名（`app_diy.dart`）：
|
||
|
||
| 当前文件名 | 建议文件名 |
|
||
|------------|------------|
|
||
| `app-diy.dart` | `app_diy.dart` |
|
||
| `app-data.dart` | `app_data.dart` |
|
||
| `app_fun.dart` | `app_fun.dart` (已合规) |
|
||
| `learn-us.dart` | `learn_us.dart` |
|
||
| `offline-data.dart` | `offline_data.dart` |
|
||
| `user-plan.dart` | `user_plan.dart` |
|
||
| `care-page.dart` | `care_page.dart` |
|
||
| `care_poetry_page.dart` | (已合规) |
|
||
| `home-load.dart` | `home_load.dart` |
|
||
| `home-set.dart` | `home_set.dart` |
|
||
| `level-jilu.dart` | `level_jilu.dart` |
|
||
| `poetry-page.dart` | `poetry_page.dart` |
|
||
| `flow-anim.dart` | `flow_anim.dart` |
|
||
| `manu-script.dart` | `manu_script.dart` |
|
||
| `help-page.dart` | `help_page.dart` |
|
||
| `notice-page.dart` | `notice_page.dart` |
|
||
| `sp-guide.dart` | `sp_guide.dart` |
|
||
| `bug_list_page.dart` | (已合规) |
|
||
| `tap-liquid-glass.dart` | `tap_liquid_glass.dart` |
|
||
| `search_history_page.dart` | (已合规) |
|
||
|
||
> ⚠️ 重命名文件需同步更新所有import引用，建议分批次进行
|
||
|
||
### 废弃API替换
|
||
|
||
| 废弃API | 替换API | 影响文件数 |
|
||
|---------|---------|-----------|
|
||
| `Color.withOpacity()` | `Color.withValues(alpha:)` | 2个文件14处 |
|
||
| `Switch.activeColor` | `Switch.activeThumbColor` | 5个文件10处 |
|
||
|
||
### 异步上下文安全
|
||
|
||
10处 `use_build_context_synchronously` 警告需添加 `mounted` 检查：
|
||
|
||
```dart
|
||
// 修复前
|
||
Future<void> _loadData() async {
|
||
final data = await api.fetch();
|
||
Navigator.push(context, ...); // 可能不安全
|
||
}
|
||
|
||
// 修复后
|
||
Future<void> _loadData() async {
|
||
final data = await api.fetch();
|
||
if (!mounted) return; // 安全检查
|
||
Navigator.push(context, ...);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、项目文件结构统计
|
||
|
||
| 目录 | 文件数 | 说明 |
|
||
|------|--------|------|
|
||
| `lib/views/` | ~45 | 页面文件 |
|
||
| `lib/services/get/` | 11 | GetX控制器 |
|
||
| `lib/models/` | 7 | 数据模型 |
|
||
| `lib/utils/` | 8 | 工具类 |
|
||
| `lib/controllers/` | 5 | 业务控制器 |
|
||
| `lib/widgets/` | 6 | 公共组件 |
|
||
| `lib/config/` | 1 | 应用配置 |
|
||
| `lib/constants/` | 1 | 常量定义 |
|
||
| `lib/routes/` | 1 | 路由配置 |
|
||
|
||
---
|
||
|
||
## 七、开发进度追踪
|
||
|
||
| 功能 | 优先级 | 状态 | 备注 |
|
||
|------|--------|------|------|
|
||
| 云端同步 | 5 | 🔴 未开始 | 需后端支持 |
|
||
| 用户账号系统 | 5 | 🔴 未开始 | 需后端支持 |
|
||
| 二维码能力 | 4 | 🔴 未开始 | |
|
||
| 诗词详情页 | 4 | 🟡 部分完成 | 热门页跳转未实现 |
|
||
| 搜索设置 | 3 | 🟡 部分完成 | 设置搜索页已实现 |
|
||
| 个性化主题 | 4 | 🔴 未开始 | 弹窗提示开发中 |
|
||
| 历史详情/分享 | 3 | 🔴 未开始 | |
|
||
| HarmonyOS小组件 | 3 | 🟡 开发中 | 基础框架已有 |
|
||
| 朗读功能 | 3 | 🔴 未开始 | |
|
||
| 学习模式 | 2 | 🔴 未开始 | |
|
||
| 社交互动 | 2 | 🔴 未开始 | 需后端支持 |
|
||
| AI诗词助手 | 1 | 🔴 未开始 | 需AI接口 |
|
||
|
||
---
|
||
|
||
*此文档由项目分析自动生成，供开发团队参考。每次重大更新后应同步更新此文档。*
|