8.4 KiB
8.4 KiB
情景诗词 - 项目分析报告
生成时间: 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 - 核心功能缺失
-
☁️ 云端同步
- 位置:
lib/views/profile/guide/app-data.dart:1059 - 现状: 仅显示"云端同步功能开发中..."
- 建议: 实现用户数据云端备份与恢复，支持跨设备同步
- 依赖: 需要后端API支持
- 位置:
-
🔐 用户账号系统
- 现状: 仅有投票凭证填写（
login_register_dialog.dart），无完整账号体系 - 建议: 实现注册/登录/个人信息管理，为云端同步和社交功能提供基础
- 依赖: 后端用户系统API
- 现状: 仅有投票凭证填写（
-
📱 二维码能力
- 现状: CHANGELOG中标记为开发中
- 建议: 支持扫码分享诗词、扫码添加好友、生成诗词卡片二维码
🟠 优先级 4 - 体验优化
-
📖 诗词详情页
- 位置:
lib/views/active/popular_page.dart:616(TODO) - 现状: 热门诗词点击后跳转详情页未实现
- 建议: 实现完整诗词详情页，包含原文/译文/赏析/作者信息
- 位置:
-
🔍 搜索设置功能
- 位置:
lib/views/active/active_search_page.dart:206 - 现状: 搜索页面"搜索设置"标记为开发中
- 建议: 支持搜索范围、搜索历史管理、搜索偏好设置
- 位置:
-
📊 历史记录详情与分享
- 位置:
lib/views/profile/history_page.dart:515-522 - 现状: 分享功能和查看详情功能均标记为开发中
- 建议: 实现历史记录的详情查看和分享功能
- 位置:
-
🎨 个性化主题设置
- 位置:
lib/views/profile/theme/app-diy.dart:84-96 - 现状: 弹出"个性化设置开发中"提示
- 建议: 实现自定义主题色、字体、背景等个性化设置
- 位置:
🟡 优先级 3 - 功能完善
-
🏠 HarmonyOS桌面小组件
- 现状: CHANGELOG中标记为开发中
- 建议: 完善2x2/4x4布局，天气显示、每日诗句推送
-
📝 笔记功能增强
- 现状: 基础笔记功能已有，但缺少富文本、图片附件
- 建议: 支持Markdown、插入图片、语音笔记
-
🏆 诗词挑战增强
- 现状: 基础答题功能已有
- 建议: 增加排行榜、每日挑战、成就系统、错题本
三、现有问题分析
🐛 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源解决 | 持续关注官方鸿蒙适配进度 |
四、可新增功能建议
🌟 高价值功能
-
🤖 AI诗词助手
- 基于诗词内容的智能问答
- 诗词创作辅助（对联、续写）
- 诗词意境解读
-
👥 社交互动
- 诗词评论与讨论
- 好友系统与诗词分享
- 诗词创作社区
-
📅 每日推荐
- 基于节气/节日推荐诗词
- 个性化推荐算法
- 每日一句推送通知
-
🎮 趣味玩法
- 诗词接龙
- 飞花令
- 诗词拼图
- 填字游戏
🔧 实用功能
-
🔊 朗读功能
- TTS语音朗读诗词
- 多种朗读风格选择
- 背景音乐配合
-
📖 学习模式
- 诗词背诵模式（逐句隐藏）
- 诗词默写模式
- 学习进度追踪
-
📊 数据可视化
- 个人阅读统计图表
- 诗词偏好分析
- 学习趋势报告
-
🎯 智能收藏
- 自动分类收藏
- 标签管理系统
- 智能去重
-
🌙 番茄钟模式
- 专注阅读计时
- 阅读时长统计
- 阅读目标设定
-
📱 多端适配
- 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 检查：
// 修复前
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接口 |
此文档由项目分析自动生成，供开发团队参考。每次重大更新后应同步更新此文档。