xianyan/docs/dev_archive_and_enhancement.md

闲言APP — 开发归档与需求扩展文档

创建时间: 2026-05-04 更新时间: 2026-05-04 版本: v1.2.0 说明: 已完成功能归档 + 待完成需求分析 + 功能扩展增强方案 + 三方库推荐 维护规则: 完成的任务勾选归档，新增需求追加到对应分类，优先级1-5

---

一、已完成功能归档 ✅

1.1 核心Bug修复

#	任务	涉及文件	完成日期	状态
B1	首页句子广场点收藏卡死闪退	home_daily_card.dart home_sentence_card.dart home_provider.dart interaction_animations.dart	2026-05-04	✅
B2	浏览过的句子没有计入缓存	home_provider.dart home_page.dart feed_service.dart	2026-05-04	✅
B3	我的页面积分/签到/笔记数量不正确	user_center_page.dart	2026-05-04	✅
B4	登录状态闪烁	auth_provider.dart	2026-05-03	✅
B5	输入框被键盘遮挡	user_center_page.dart	2026-05-03	✅
B6	编辑框太小	user_center_page.dart	2026-05-03	✅
B7	CupertinoIcons不存在报错	多文件	2026-05-03	✅
B8	统计页面显示0(加载失败)	statistics_provider.dart	2026-05-03	✅
B9	空指针风险修复(12处)	多文件	2026-05-03	✅
B10	蓝色警告清理(13处)	多文件	2026-05-03	✅
B11	蓝色警告深度清理(info级+deprecated)	data_management_page.dart history_page.dart favorite_page.dart likes_page.dart	2026-05-04	✅
B12	空指针防护增强(profile user! + 导入容错)	profile_page.dart data_management_page.dart home_provider.dart	2026-05-04	✅
B13	HomeProvider.toggleLike缺少本地DB写入	home_provider.dart	2026-05-04	✅
B14	数据导入单条格式错误导致整体失败	data_management_page.dart	2026-05-04	✅

1.2 新增功能

#	任务	涉及文件	完成日期	状态
F1	灵感页面搜索框(搜索会话名称+内容)	session_search_bar.dart chat_session_provider.dart inspiration_page.dart	2026-05-04	✅
F2	统计栏点击跳转对应页面	user_center_page.dart	2026-05-04	✅
F3	头像上传功能	user_center_page.dart	2026-05-03	✅
F4	邮箱/手机号安全验证	user_center_page.dart user_center_service.dart	2026-05-03	✅
F5	离线模式基础设施	connectivity_provider.dart offline_banner.dart	2026-05-03	✅
F6	AppIcon动态主题支持	app_icon.dart	2026-05-03	✅
F7	响应式布局组件	responsive_layout.dart	2026-05-03	✅
F8	滚动浏览自动标记已读(2秒延迟)	home_page.dart	2026-05-04	✅
F9	FeedService.action支持view操作	feed_service.dart	2026-05-04	✅
F10	本地数据与登录解耦(收藏/点赞/浏览)	home_provider.dart home_daily_card.dart home_sentence_card.dart favorite_page.dart likes_page.dart history_page.dart app_database.dart	2026-05-04	✅
F11	收藏/点赞页面本地优先+同步横幅	favorite_page.dart likes_page.dart	2026-05-04	✅
F12	登录后同步合并按钮(收藏+点赞+历史)	favorite_page.dart likes_page.dart history_page.dart	2026-05-04	✅
F13	阅读历史Feed来源筛选(pull_down_button)	history_page.dart app_database.dart	2026-05-04	✅
F14	自动备份功能(定时备份+管理+恢复)	backup_service.dart data_management_page.dart	2026-05-04	✅
F15	数据库toggleLike方法+getLikedSentences	app_database.dart	2026-05-04	✅
F16	HomeProvider本地优先策略(收藏/点赞/已读)	home_provider.dart	2026-05-04	✅
F17	导入导出数据验证脚本	Script/verify_export_import.py	2026-05-04	✅
F18	横屏/宽屏适配(4个核心页面)	profile_page.dart history_page.dart favorite_page.dart data_management_page.dart	2026-05-04	✅
F19	数据导入逐条容错(单条失败不影响其他)	data_management_page.dart	2026-05-04	✅
F20	CupertinoSwitch deprecated activeColor→activeTrackColor	data_management_page.dart	2026-05-04	✅

1.3 三方库接入(已完成)

库	用途	状态
flutter_slidable	滑动操作(收藏/删除/分享)	✅
flutter_sticky_header	日期分组吸顶	✅
flutter_markdown_plus	Markdown渲染	✅
pull_down_button	iOS风格弹出菜单	✅
sliver_tools + bot_toast	Sliver布局+Toast	✅
flutter_animate	入场/交互动画	✅
confetti	签到庆祝效果	✅
adaptive_palette	句子卡片取色	✅
cached_network_image	头像缓存	✅
shimmer	骨架屏	✅
flutter_svg	SVG图标	✅
fl_chart	数据图表	✅
lottie	加载动画	✅

---

二、待完成需求清单

2.1 🔴 P1 — 高优先级(用户体验关键)

#	任务	当前状态	扩展方案	涉及文件	优先级
T1	阅读历史页面功能单一	✅ 已完成(搜索+日期筛选+批量+统计+Feed筛选)	见下方扩展方案A	history_page.dart	5
T2	我的收藏页面功能单一	✅ 已完成(搜索+排序+批量+统计+视图切换+分组)	见下方扩展方案B	favorite_page.dart	5
T3	数据管理页面空壳UI	✅ 已完成(真实统计+导出+导入+备份+可视化)	见下方扩展方案C	data_management_page.dart	4

2.2 🟡 P2 — 中优先级(功能完善)

#	任务	当前状态	扩展方案	涉及文件	优先级
T4	我的页面列表底部版本号+介绍	✅ 已完成	添加AppInfoFooter组件	user_center_page.dart	3
T5	阅读历史+收藏重新设计	✅ 已完成	先写HTML预览确认方案	新页面	3
T6	Feed API 评分系统	未接入	详情页1-5星评分	详情页	2
T7	Feed API 屏蔽/举报	未接入	pull_down_button新增选项	菜单	2
T8	服务端浏览历史同步	✅ 已完成(统一数据源+离线降级)	统一数据源+离线降级	history_page.dart	2
T9	点赞历史页面	✅ 已完成(本地优先+服务端同步)	新建likes_page	likes_page.dart	2

2.3 🟢 P3 — 低优先级(锦上添花)

#	任务	当前状态	扩展方案	涉及文件	优先级
T10	应用评分引导	未实现	in_app_review	设置页	1
T11	标签管理页	不存在	滑动删除/重命名	新页面	1
T12	热门排行榜独立页	未独立展示	/api/feed/trending	新页面	1
T13	"换一批"随机内容	未接入	/api/feed/random	首页	1
T14	频道管理(排序/隐藏)	未实现	用户自定义频道	新页面	1

---

三、需求扩展增强方案

方案A: 阅读历史页面增强

当前问题:

• 仅列表展示，无搜索/筛选
• 只能单条删除，无批量操作
• 无统计概览(今日阅读/本周阅读/总计)
• 服务端数据与本地数据未统一

扩展方案:

#	功能	说明	推荐三方库
A1	🔍 搜索历史	✅ 已完成	原生TextField
A2	📅 日期筛选	✅ 已完成	原生CupertinoDatePicker
A3	✅ 批量选择+删除	✅ 已完成	原生 + flutter_slidable
A4	📊 阅读统计概览	✅ 已完成	fl_chart(迷你趋势图)
A5	🔄 统一数据源	✅ 已完成	connectivity_plus
A6	📤 分享/导出	✅ 已完成	share_plus + archive
A7	🏷️ 标签筛选	✅ 已完成	pull_down_button
A8	📖 阅读模式	待开发	heroine(卡片展开)

推荐新增三方库:

库	用途	理由
visibility_detector	精确检测卡片可见性	替代Timer延迟标记，滚动时精确记录阅读时长
in_app_review	应用评分引导	引导用户在App Store评分

方案B: 我的收藏页面增强

当前问题:

• 无搜索功能
• 无批量管理
• 分组功能基础，缺少排序
• 无收藏统计

扩展方案:

#	功能	说明	推荐三方库
B1	🔍 搜索收藏	✅ 已完成	原生TextField
B2	✅ 批量管理	✅ 已完成	原生 + flutter_slidable
B3	📊 收藏统计	✅ 已完成	fl_chart(饼图/柱状图)
B4	🔀 排序	✅ 已完成	pull_down_button
B5	📁 分组增强	✅ 已完成(拖拽排序+重命名+删除)	reorderables
B6	🏷️ 标签系统	待开发	原生Chip
B7	📤 分享收藏集	待开发	share_plus + qr_flutter
B8	🎨 收藏卡片视图切换	✅ 已完成(列表/网格)	原生 + flutter_staggered_grid_view

推荐新增三方库:

库	用途	理由
reorderables	拖拽排序分组	iOS风格长按拖拽重排
flutter_staggered_grid_view	瀑布流布局	收藏卡片不等高，瀑布流更美观

方案C: 数据管理页面增强

当前问题:

• 存储概览硬编码(收藏0条/笔记0条)
• 导出数据为空壳(仅导出版本号)
• 导入数据为空壳(仅弹窗无逻辑)
• 无数据分类详情
• 无自动备份

扩展方案:

#	功能	说明	推荐三方库
C1	📊 真实存储统计	✅ 已完成	drift + hive
C2	📦 完整数据导出	✅ 已完成	archive + crypto
C3	📥 完整数据导入	✅ 已完成	archive + crypto
C4	☁️ 自动备份	✅ 已完成	path_provider + workmanager
C5	📋 数据分类详情	✅ 已完成	原生
C6	🗑️ 分类清理	✅ 已完成	原生
C7	📊 存储空间可视化	✅ 已完成	fl_chart
C8	🔐 数据加密	待开发	flutter_secure_storage

推荐新增三方库:

库	用途	理由
workmanager	后台定时备份	iOS/Android后台任务调度
flutter_secure_storage	敏感数据加密	已在项目中，深度利用

---

四、三方库推荐与利用

4.1 已有库深度利用(未充分使用)

库	当前使用	可扩展用途	优先级
fl_chart	统计页图表	阅读历史趋势图、收藏统计饼图、存储空间环形图	4
flutter_animate	入场动画	收藏卡片交错动画、搜索结果高亮动画、删除动画	3
adaptive_palette	句子卡片取色	收藏卡片取色、历史卡片取色	2
confetti	签到庆祝	收藏满100庆祝、阅读里程碑庆祝	1
heroine	卡片展开	句子详情展开动画、收藏卡片展开	3
lottie	加载动画	空状态动画、删除确认动画	2
cached_network_image	头像缓存	Feed图片缓存展示	3
shimmer	骨架屏	搜索结果骨架屏、收藏列表骨架屏	3
archive + crypto	数据导出	完整数据导入导出+校验	4
drift	本地数据库	阅读统计聚合查询、收藏分组查询	5
hive	KV存储	缓存管理统计、离线队列	4
connectivity_plus	网络检测	数据管理页面网络状态、同步状态	3

4.2 推荐新增三方库

库	版本	用途	接入页面	优先级	兼容性
visibility_detector	^0.4.0+2	精确检测Widget可见性，替代Timer延迟标记	首页句子列表	5	iOS✅ Android✅
reorderables	^0.6.0	拖拽排序(分组/列表)	收藏分组管理	3	iOS✅ Android✅
flutter_staggered_grid_view	^0.7.0	瀑布流布局	收藏页面视图切换	3	iOS✅ Android✅
in_app_review	^2.0.0	App Store评分引导	设置页	1	iOS✅ Android✅
workmanager	^0.5.0	后台定时任务(自动备份)	数据管理	2	iOS⚠️ Android✅
scrollable_positioned_list	^0.3.8	精确滚动定位(跳转到指定日期)	阅读历史	2	iOS✅ Android✅
flutter_highlight	^0.7.0	搜索关键词高亮(更强大)	搜索结果	2	iOS✅ Android✅

4.3 三方库风险提示

库	风险	建议
workmanager	iOS后台任务限制严格，最小间隔15分钟	仅Android端启用定时备份，iOS端用NSUrlSession
visibility_detector	列表快速滚动时频繁回调	添加防抖(500ms)，避免重复标记
flutter_staggered_grid_view	与Sliver布局可能冲突	使用MasonryGridView替代StaggeredSliver
reorderables	长按拖拽与Slidable手势冲突	分组管理页独立使用，不与Slidable共存

---

五、开发优先级路线图

Phase 1: 核心功能补全 (本周)

T1 阅读历史增强 ──→ T2 收藏增强 ──→ T3 数据管理完善
     │                    │                  │
     ├─ 搜索              ├─ 搜索            ├─ 真实统计
     ├─ 批量删除           ├─ 批量管理         ├─ 完整导出
     ├─ 日期筛选           ├─ 排序            ├─ 完整导入
     └─ 统计概览           └─ 视图切换         └─ 空间可视化

Phase 2: 体验优化 (下周)

T5 重新设计确认 ──→ T4 底部版本号 ──→ T8 服务端历史同步
     │                                     │
     ├─ HTML预览                            ├─ 统一数据源
     └─ 方案确认                            └─ 离线降级

Phase 3: Feed API扩展 (后续)

T6 评分 ──→ T7 屏蔽/举报 ──→ T9 点赞历史

---

六、技术债务记录

#	问题	位置	影响	修复建议
D1	markRead使用Timer(2秒)而非VisibilityDetector	home_page.dart	快速滑动可能误标记	接入visibility_detector
D2	阅读历史服务端+本地双数据源未合并	history_page.dart	✅ 已修复: 统一数据源+离线降级	-
D3	数据管理导出数据为空壳	data_management_page.dart	✅ 已修复: 完整导出+校验	-
D4	数据管理导入为空壳	data_management_page.dart	✅ 已修复: 文件选择+解密+恢复	-
D5	收藏统计数量依赖dashboard API	user_center_page.dart	✅ 已修复: 本地Drift fallback	-
D6	_markedReadIds为static全局Set	home_page.dart	内存不释放	改为Provider管理或定期清理
D7	首页收藏/点赞需登录才能操作	home_daily_card.dart home_sentence_card.dart	✅ 已修复: 本地优先策略	-
D8	收藏/点赞页面未登录显示登录提示	favorite_page.dart likes_page.dart	✅ 已修复: 本地模式+同步横幅	-
D9	profile_page user!强制解包	profile_page.dart	✅ 已修复: user!=null安全检查	-
D10	数据导入单条错误导致整体失败	data_management_page.dart	✅ 已修复: 逐条try-catch容错	-
D11	HomeProvider.toggleLike缺少本地DB写入	home_provider.dart	✅ 已修复: 添加_db.toggleLike	-
D12	核心页面无横屏/宽屏适配	4个页面	✅ 已修复: ResponsiveMaxWidth包裹	-

---

七、变更日志

日期	版本	变更内容
2026-05-04	v1.2.0	蓝色警告深度清理(B11)、空指针防护增强(B12: profile user!→安全检查、数据导入逐条容错)、HomeProvider.toggleLike补全本地DB写入(B13)、数据导入容错(B14: 单条失败不影响其他)、横屏/宽屏适配(F18: 4个核心页面ResponsiveMaxWidth)、CupertinoSwitch deprecated修复(F20)
2026-05-04	v1.1.0	本地数据与登录解耦(D1+D2)、点赞页面本地优先改造、阅读历史Feed来源筛选(A7)、自动备份(C4)、HomeProvider本地优先策略、数据库新增toggleLike/getLikedSentences/getHistoryCountByFeedType、导入导出验证脚本
2026-05-04	v1.0.0	初始创建：归档已完成功能10项、待完成需求14项、扩展方案3套、三方库推荐7个