xianyan/docs/10_三方库接入开发清单.md

闲言APP — 统一开发清单

创建时间: 2026-04-29 更新时间: 2026-05-18 版本: v2.2.0 整合来源: 10_三方库接入开发清单.md + 2026-04-28-feed-enhancement-plan.md + 2026-04-28-feed-integration-plan.md + 2026-04-28-offline-cache-dev-plan.md 说明: 四文档合一，含代码验证结果 + 偷工减料识别 + 未完成功能汇总 v2.2更新: 新增Phase 11-14(鸿蒙适配+文件传输+Riverpod修复+导航修复) + 状态同步

---

一、代码验证 & 偷工减料分析

对4个文档中标记✅的功能进行代码级验证，识别以下问题类型： 🔴 偷工减料 — 声称完成但代码实现不完整/空壳 🟡 半成品 — 基础框架在但核心逻辑缺失 🟢 已完成 — 代码验证通过

1.1 🔴 偷工减料项

#	文档声明	文件	问题	修复建议	状态
Q1	Phase 6.1 ✅ connectivity_plus 工具状态实时监测	tool_center_provider.dart	仅有 import 和基础网络监听，无工具状态实时监测逻辑	补充：网络断开时标记在线工具为offline，恢复时刷新	✅ 已修复
Q2	Phase 14 ✅ CacheService.preloadChannels	cache_service.dart:186-195	预加载方法只检查缓存数量，未实际拉取数据	委托给 OfflineManager.preloadNow()	✅ 已修复
Q3	Phase 2 ✅ Drift schema v3 迁移	app_database.dart	FeedCache/OfflineActionQueue 表已定义，但onUpgrade 迁移逻辑需确认	已验证 v1→v2→v3→v4 全路径覆盖	✅ 已验证
Q4	Phase 8 ✅ 深度链接	deep_link_service.dart + main.dart	仅有 import，未验证深度链接路由是否完整注册	已修复路由映射 + 新增更多工具路由	✅ 已修复

1.2 🟡 半成品项

#	文档声明	文件	问题	修复建议	状态
H1	Phase 6.12 ✅ flutter_svg 工具分类图标+空状态插画	仅编辑器3处使用	灵感工具中心未使用 flutter_svg	为工具分类创建 SVG 图标	✅ 已完成
H2	Phase 9.3 ⬜ drift 汉字查询结果持久化	无 hanzi_cache_dao	未创建	新建 HanziCaches表 + 迁移	✅ 已完成
H3	Phase 12.5 ⬜ 图片压缩选图	无独立页面	imgCompress 方法存在但无UI页面	新建 img_compress_tool_page.dart	✅ 已完成
H4	Phase 12.6 ⬜ 压缩后图片保存到相册	无	imgCompress API 存在但未接入 gal 保存	图片压缩页接入 gal	✅ 已完成
H5	Phase 13.3 ⬜ 一言刷新庆祝效果	无	confetti 仅在签到/编辑器使用	一言工具页接入 confetti	⏳
H6	Phase 13.4 ⬜ 一言卡片入场动画	无	flutter_animate 已广泛使用	一言工具页接入 flutter_animate	⏳
H7	Phase 13.6 ⬜ 一言卡片自动取色背景	无	adaptive_palette 仅编辑器使用	一言工具页接入 adaptive_palette	⏳
H8	Phase 8.4 ⬜ 应用评分引导	无	完全未实现	接入 in_app_review 或自定义评分弹窗	⏳
H9	Phase 3.3 ⬜ 标签管理滑动操作	无	标签管理页不存在	需先创建标签管理页	⏳

1.3 🟢 已验证通过项（核心功能）

模块	验证结果
Feed 数据模型 + API 服务层 (15端点)	✅ feed_model.dart + feed_service.dart 完整
HomeProvider 替换 Hitokoto	✅ home_provider.dart 完整
频道分类 Header + 排序下拉	✅ home_square_header.dart
骨架屏 shimmer	✅ FeedSentenceSkeleton + DailyCardSkeleton
动画增强 (FavoriteBounce/Like/入场)	✅ interaction_animations.dart
FeedTypeColor 18种主题色	✅ feed_model.dart
AppSlidable + AppToast + AppStickyHeader	✅ 通用组件完整
AppMarkdown + AppPopupMenu	✅ 通用组件完整
离线模式 (OfflineManager + OfflinePage)	✅ 完整
缓存管理 (CacheService + CacheManagementPage)	✅ 完整
稍后读列表 (ReadLaterPage)	✅ Feed API + 离线降级
服务端收藏同步 (FavoriteProvider)	✅ FeedService.fetchFavorites
Feed搜索整合 (SearchProvider)	✅ FeedService.search
Drift FeedCache + OfflineActionQueue 表	✅ 代码生成完整
深度链接 (DeepLinkService)	✅ 完整
文件传输 7通道 (WiFi/蓝牙/NFC/USB/WebRTC/LocalSend/WebSocket)	✅ 完整
鸿蒙30包适配	✅ 全量完成
液态玻璃效果鸿蒙恢复	✅ 仅阉割路由，保留视觉
鸿蒙端全量导航修复	✅ 89条路由映射+96处迁移
Riverpod Notifier 反模式修复	✅ 9+1个Notifier修复

---

二、已完成功能归档

Phase 1: flutter_slidable 接入 ✅

#	任务	文件	状态
1.1	AppSlidable 通用封装 + SlideActionConfig/DeleteConfirm	shared/widgets/app_slidable.dart	✅
1.2	笔记列表替换 Dismissible	note_list_page.dart	✅
1.3	收藏列表滑动取消收藏/分享	favorite_page.dart	✅
1.4	阅读历史滑动删除/收藏	history_page.dart	✅
1.5	搜索页历史滑动删除	search_page.dart	✅
1.6	工具搜索历史滑动删除	tool_search_page.dart	✅
1.7	工具管理滑动操作	tool_list_page.dart	✅
1.8	句子列表滑动收藏/纠错/分享	首页句子卡片	✅
1.9	OCR历史记录滑动删除	OCR工具页	✅
1.10	一言历史滑动操作	一言工具页	✅

Phase 2: flutter_sticky_header 接入 ✅

#	任务	文件	状态
2.1	AppStickyHeaderSliver 通用封装	shared/widgets/app_sticky_header.dart	✅
2.2	工具中心分类吸顶	tool_panel.dart	✅
2.3	笔记列表日期分组吸顶	note_list_page.dart	✅
2.4	阅读历史日期分组吸顶	history_page.dart	✅
2.5	热搜榜平台分组吸顶	热搜工具页	✅
2.6	传统色色系分组吸顶	china_colors_page.dart	✅
2.7	汉语工具拼音A-Z分组吸顶	汉字查询结果页	✅
2.8	酒方大全分类吸顶	jiufang_tool_page.dart	✅
2.9	首页 SliverPersistentHeader 替换	home_square_header.dart	✅

Phase 3: flutter_markdown_plus 接入 ✅

#	任务	文件	状态
3.1	AppMarkdownBody / AppMarkdown 通用封装	shared/widgets/app_markdown.dart	✅
3.2	工具结果展示	工具详情页	✅
3.3	笔记内容渲染	note_edit_page.dart	✅
3.4	工具说明展示	tool_detail_page.dart	✅

Phase 4: pull_down_button 接入 ✅

#	任务	文件	状态
4.1	AppPopupMenu 通用封装	shared/widgets/app_popup_menu.dart	✅
4.2	工具卡片操作菜单	tool_grid_item.dart	✅
4.3	笔记列表操作菜单	note_list_page.dart	✅
4.4	收藏列表操作菜单	favorite_page.dart	✅

Phase 5: sliver_tools + bot_toast ✅

#	任务	文件	状态
5.1	AppToast 通用封装	shared/widgets/app_toast.dart	✅
5.2	替换 SnackBar 为 AppToast	全局	✅
5.3	SliverPinnedHeader 替代部分 SliverPersistentHeader	首页	✅

Phase 6: Feed API 核心功能 ✅

#	任务	文件	状态
6.1	Feed 数据模型 (FeedItem/FeedChannel/FeedAction)	feed_model.dart	✅
6.2	Feed API 服务层 (15端点)	feed_service.dart	✅
6.3	HomeProvider 替换 Hitokoto	home_provider.dart	✅
6.4	频道分类 Header + 排序下拉	home_square_header.dart	✅
6.5	句子卡片 Feed 适配	home_sentence_card.dart	✅
6.6	主页互动操作 (滑动收藏/稍后读/刷新)	home_page.dart	✅
6.7	每日推荐卡片 (收藏+Feed来源)	home_daily_card.dart	✅
6.8	FeedTypeColor 18种主题色	feed_model.dart	✅
6.9	骨架屏 shimmer	skeleton.dart	✅
6.10	动画增强 (FavoriteBounce/Like/入场)	interaction_animations.dart	✅
6.11	智能下拉刷新	home_provider.dart	✅
6.12	智能推荐Tab	home_square_header.dart	✅
6.13	内容详情页增强	home_sentence_card.dart	✅

Phase 7: 离线模式 + 缓存管理 ✅

#	任务	文件	状态
7.1	FeedCache + OfflineActionQueue Drift 表	app_database.dart	✅
7.2	Drift schema v3→v4 迁移	app_database.dart	✅
7.3	Hive 新增3个Box (feed_cache/offline_queue/cache_config)	app_kv_store.dart	✅
7.4	CacheConfig 模型	cache_config.dart	✅
7.5	CacheService (读写/统计/清理/策略)	cache_service.dart	✅
7.6	OfflineManager (网络监听/队列/同步/预加载)	offline_manager.dart	✅
7.7	OfflineProvider + CacheProvider	offline_provider.dart + cache_provider.dart	✅
7.8	OfflinePage (网络状态/预加载/队列/策略)	offline_page.dart	✅
7.9	CacheManagementPage (存储/分类/清理)	cache_management_page.dart	✅
7.10	离线Banner	home_page.dart	✅
7.11	路由注册 (/offline + /cache + /readlater)	app_router.dart	✅

Phase 8: Feed 扩展功能 ✅

#	任务	文件	状态
8.1	服务端收藏同步	favorite_provider.dart	✅
8.2	稍后读列表页	readlater_page.dart	✅
8.3	Feed搜索整合	search_provider.dart	✅
8.4	Feed图片展示 (imageUrl/likes/source)	feed_model.dart	✅

Phase 9: 已有库深度利用 ✅

#	任务	文件	状态
9.1	shimmer 工具列表/搜索结果骨架屏	工具中心+搜索页	✅
9.2	cached_network_image 头像缓存	profile/account	✅
9.3	adaptive_palette 句子卡片取色	home_sentence_card.dart	✅
9.4	lottie 工具加载动画+空状态	工具中心	✅
9.5	confetti 签到庆祝效果	signin_page.dart	✅
9.6	gal 传统色保存到相册	china_colors_page.dart	✅
9.7	archive+crypto 数据导出加密	data_management_page.dart	✅
9.8	drift 工具使用统计持久化	app_database.dart	✅
9.9	google_fonts 笔记编辑器字体	note_edit_page.dart	✅
9.10	connectivity_plus 工具状态监测	tool_center_provider.dart	✅
9.11	flutter_svg 工具分类图标	工具中心	✅

Phase 10: 深度链接 ✅

#	任务	文件	状态
10.1	DeepLinkService (xianyan:// + https://)	deep_link_service.dart	✅
10.2	main.dart 注册	main.dart	✅

Phase 11: 鸿蒙30包全量适配 ✅ (🆕 v2.2)

#	任务	说明	状态
11.1	第一批 11 个 TPC 官方合并	shared_preferences/path_provider/url_launcher等	✅
11.2	第二批 9 个 TPC 包合并+自行适配	file_picker/receive_sharing_intent/wakelock_plus等	✅
11.3	第三批 10 个自行编写ohos原生代码	audioplayers/record/sqflite/flutter_blue_plus等	✅
11.4	联合插件模式适配	ohos原生代码在独立*_ohos子包	✅
11.5	直接插件模式适配	ohos原生代码在主包ohos/目录	✅

Phase 12: 文件传输核心架构 ✅ (🆕 v2.2)

#	任务	文件	状态
12.1	文件传输核心架构	file_transfer/	✅
12.2	LocalSend HTTP 传输	localsend_service.dart	✅
12.3	WebRTC P2P 传输	webrtc_service.dart	✅
12.4	WebSocket 中继传输	ws_relay_service.dart	✅
12.5	蓝牙 BLE 配对	bluetooth_pairing_service.dart	✅
12.6	NFC 配对	nfc_pairing_service.dart	✅
12.7	QR 码配对	qr_pairing_service.dart	✅
12.8	WiFi 热点	hotspot_service.dart	✅
12.9	USB OTG 有线传输	usb_transport_service.dart	✅
12.10	送达回执	delivery_receipt_service.dart	✅
12.11	断点续传	ws_relay_resume_handler.dart	✅
12.12	文件分流传输	transport_router.dart	✅
12.13	语音消息	voice_message_service.dart	✅
12.14	加密传输	ecdh_key_exchange.dart + message_encryption_service.dart	✅

Phase 13: 鸿蒙端液态玻璃+导航修复 ✅ (🆕 v2.2)

#	任务	文件	说明	状态
13.1	恢复鸿蒙端液态玻璃效果	app.dart	仅阉割路由，保留全部视觉特效	✅
13.2	补全鸿蒙端33条缺失路由	ohos_nav_bridge.dart	新增33条路由+带参数路由处理	✅
13.3	全项目96处导航调用迁移	28个文件	context.push → context.appPush	✅
13.4	appPush 扩展 extra 参数	app_nav_extension.dart	支持路由参数传递	✅

Phase 14: Riverpod Notifier 反模式修复 ✅ (🆕 v2.2)

#	任务	文件	说明	状态
14.1	构造函数使用 state/ref 修复	9个Notifier	初始化逻辑移至 build()	✅
14.2	CanvasProvider 构建期间修改状态	canvas_provider.dart	Future.microtask + _disposed 防护	✅
14.3	isLoading 默认值修复	PoetryState/ProgressState/CountdownState	build() 返回 isLoading: false	✅

---

三、未完成功能清单（按优先级排序）

🔴 P1 — 核心功能缺失

所有 P1 核心功能已修复完成 ✅

🟡 P2 — 体验增强缺失

#	功能	来源	说明	涉及文件	状态
U5	flutter_svg 工具分类图标	Phase 6.12	工具中心未使用SVG图标	工具中心相关页面	✅ 已完成
U6	一言工具页 confetti 庆祝效果	Phase 13.3	一言刷新时无庆祝动画	一言工具页	⏳
U7	一言工具页 flutter_animate 入场动画	Phase 13.4	一言卡片无入场动画	一言工具页	⏳
U8	一言工具页 adaptive_palette 自动取色	Phase 13.6	一言卡片无自动取色背景	一言工具页	⏳
U9	Feed API 评分系统	8.2-E7	action=rating 未接入	详情页+FeedService	⏳
U10	Feed API 屏蔽/举报	8.2-E8	action=block/report 未接入	菜单扩展	⏳
U11	Feed API 不感兴趣	8.2-E10	action=dislike 未接入	滑动操作扩展	⏳
U12	Feed API 阅读时长上报	8.2-E9	action=readtime 未接入	详情页逻辑	⏳
U13	服务端浏览历史同步	8.2-E13	/api/feed/history 未接入	history_page.dart	⏳
U14	点赞历史页面	8.2-E14	/api/feed/likes 未接入	新建 likes_page.dart	⏳
U15	评论展示	8.2-E11	/api/feed/comments 未接入	详情页+评论组件	📦 归档暂缓
U16	分页预加载优化	enhancement F4	滚动到80%时预加载下一页	home_page.dart	✅ 已完成

🟢 P3 — 后续规划

#	功能	来源	说明	涉及文件
U17	应用评分引导	Phase 8.4	完全未实现	设置页
U18	标签管理页+滑动操作	Phase 3.3	页面不存在	新建标签管理页
U19	信息流统计展示	8.2-E15	/api/feed/stats 未接入	设置页/关于页
U20	热门排行榜独立页面	8.2-E16	/api/feed/trending 未独立展示	新建 trending_page.dart
U21	"换一批"随机内容	8.2-E17	/api/feed/random 未接入	首页
U22	频道管理(排序/隐藏)	8.2-E18	用户自定义频道	新建频道管理页
U23	评论回复功能	enhancement F3	暂缓，先做评论展示	详情页
U24	热搜配图	Phase 10.3	API无图片字段，待后端支持	热搜工具页

---

四、后续开发计划

Phase A: 偷工减料修复 (P1 🔴) ✅ 全部完成

#	任务	文件	说明	状态
A1	修复 CacheService.preloadChannels 空壳	cache_service.dart	委托给 OfflineManager.preloadNow()	✅
A2	补充 connectivity_plus 工具状态实时监测	tool_center_provider.dart	初始化网络检测 + 动态更新	✅
A3	验证 Drift schema 迁移路径	app_database.dart	v1→v2→v3→v4 全路径覆盖	✅
A4	深度链接端到端测试	deep_link_service.dart	修复路由映射 + 新增12个工具路由	✅

Phase B: 缺失功能补全 (P1 🔴) ✅ 全部完成

#	任务	文件	说明	状态
B1	新建图片压缩工具页	img_compress_tool_page.dart	image_picker选图 + imgCompress API + gal保存	✅
B2	新建汉字查询Drift缓存	app_database.dart + hanzi_tool_page.dart	HanziCaches表(v4) + 迁移	✅

Phase C: 一言工具页增强 (P2 🟡)

#	任务	文件	说明	优先级
C1	一言刷新 confetti 庆祝效果	一言工具页	刷新成功时播放庆祝动画	P2
C2	一言卡片 flutter_animate 入场	一言工具页	交错入场动画	P2
C3	一言卡片 adaptive_palette 取色	一言工具页	自动取色渐变背景	P2

Phase D: Feed API 互动扩展 (P2 🟡)

#	任务	文件	说明	优先级
D1	评分系统 (action=rating)	详情页	1-5星评分+动画反馈	P2
D2	屏蔽/举报 (action=block/report)	菜单	pull_down_button 新增选项	P2
D3	不感兴趣 (action=dislike)	滑动操作	左滑新增👎	P2
D4	阅读时长上报 (action=readtime)	详情页	停留时长自动上报	P2
D5	评论展示 (/api/feed/comments)	详情页	评论列表+shimmer	P2
D6	服务端浏览历史同步	history_page.dart	/api/feed/history	P2
D7	点赞历史页面	新建 likes_page.dart	/api/feed/likes	P2

Phase E: UI/体验优化 (P2 🟡)

#	任务	文件	说明	优先级	状态
E1	flutter_svg 工具分类图标	工具中心	替换emoji为SVG图标	P2	✅ 已完成
E2	分页预加载优化	home_page.dart	滚动到80%时预加载	P2	✅ 已完成

Phase F: 后续规划 (P3 🟢)

#	任务	文件	说明	优先级
F1	应用评分引导	设置页	in_app_review 或自定义弹窗	P3
F2	标签管理页	新建	滑动删除/重命名	P3
F3	信息流统计展示	设置页	/api/feed/stats	P3
F4	热门排行榜独立页	新建 trending_page.dart	/api/feed/trending	P3
F5	"换一批"随机内容	首页	/api/feed/random	P3
F6	频道管理(排序/隐藏)	新建频道管理页	/api/feed/channels	P3
F7	评论回复功能	详情页	暂缓，先完成评论展示	P3

---

五、Feed API 端点接入状态

#	端点	路径	状态
1	频道列表	/api/feed/channels	✅
2	信息流列表	/api/feed/list	✅
3	信息流详情	/api/feed/detail	✅
4	互动操作 (like/favorite/readlater)	/api/feed/action	✅ 部分
5	热门内容	/api/feed/trending	✅
6	个性化推荐	/api/feed/recommend	✅
7	随机内容	/api/feed/random	✅
8	搜索	/api/feed/search	✅
9	收藏列表	/api/feed/favorites	✅
10	点赞列表	/api/feed/likes	⬜
11	浏览历史	/api/feed/history	⬜
12	稍后读列表	/api/feed/readlater	✅
13	评论列表	/api/feed/comments	⬜
14	刷新检查	/api/feed/refresh	✅
15	信息流统计	/api/feed/stats	⬜

Feed 互动操作接入状态

action	状态	优先级
like / unlike	✅	-
favorite / unfavorite	✅	-
share	✅	-
readlater / unreadlater	✅	-
dislike	⬜	P2
rating	⬜	P2
block / unblock	⬜	P2
report	⬜	P2
comment	⬜	P3
comment_like / comment_unlike	⬜	P2
readtime	⬜	P2

---

六、跨平台兼容性速查

库	iOS	Android	鸿蒙	类型	兼容性
flutter_slidable	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐
flutter_sticky_header	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐
flutter_markdown_plus	✅	✅	✅	纯Dart	⭐⭐⭐⭐
pull_down_button	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐
sliver_tools	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐
bot_toast	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐
cached_network_image	✅	✅	✅	混合	⭐⭐⭐⭐
connectivity_plus	✅	✅	✅	插件(本地化)	⭐⭐⭐⭐
image_picker	✅	✅	✅	插件(本地化)	⭐⭐⭐⭐
gal	✅	✅	✅	插件(本地化)	⭐⭐⭐
flutter_secure_storage	✅	✅	✅	插件(本地化)	⭐⭐⭐⭐
app_links	✅	✅	✅	插件(本地化)	⭐⭐⭐⭐
adaptive_palette	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐
confetti	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐
flutter_animate	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐
lottie	✅	✅	✅	混合	⭐⭐⭐⭐
flutter_svg	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐
drift	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐
hive	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐
flutter_webrtc	✅	✅	✅	插件(本地化)	⭐⭐⭐⭐
flutter_blue_plus	✅	✅	✅	插件(本地化)	⭐⭐⭐⭐
mobile_scanner	✅	✅	✅	插件(本地化)	⭐⭐⭐⭐
shelf	✅	✅	✅	纯Dart	⭐⭐⭐⭐⭐

---

七、本地包管理

包	路径	用途
liquid_glass_widgets	packages/liquid_glass_widgets	iOS 26 毛玻璃
liquid_glass_easy	packages/liquid_glass_easy	毛玻璃便捷组件
pro_image_editor	packages/pro_image_editor	图片编辑器
flex_color_picker	packages/flex_color_picker	颜色选择器
share_plus	packages/share_plus	分享
image_size_getter	packages/image_size_getter	图片尺寸检测
flutter_quill	packages/flutter_quill	富文本编辑器
flutter_shaders_ui	packages/flutter_shaders_ui	Shader效果
flutter_card_swiper	packages/flutter_card_swiper	卡片滑动切换
flutter_spritesheet_animation	packages/flutter_spritesheet_animation	精灵图帧动画
extended_image	packages/extended_image	图片缓存+裁剪
photo_view	packages/photo_view	图片缩放查看
flutter_image_compress	packages/flutter_image_compress	图片压缩
catcher_2	packages/catcher_2	异常捕获
badges	packages/badges	角标徽章
nearby_service	packages/nearby_service	近场设备发现
flutter_markdown_plus	packages/flutter_markdown_plus	Markdown渲染