Files

Developer 283950ea07 chore: 批量代码优化与功能迭代更新

本次提交包含大量代码优化、功能新增与服务端配置更新：
1. 修复分析报告统计数据，调整CMake策略设置
2. 优化APP权限配置、编辑器与聊天界面组件
3. 更新依赖库版本与pubspec配置
4. 新增文件传输服务端、信令服务器相关配置与脚本
5. 完善用户注销功能与数据库迁移脚本
6. 优化多处动画效果、代码风格与日志输出
7. 新增多种调试与部署脚本，修复已知BUG

2026-05-12 06:28:04 +08:00

14 KiB

Raw Blame History

闲言APP — 传输助手功能扩展设计文档

创建时间: 2026-05-11
更新时间: 2026-05-12
作用: 12项传输助手功能扩展的完整架构设计
上次更新: v11.5.0 F6语音消息核心功能完成
架构方案: 方案A — 扩展式架构

一、功能总览

编号	功能	模块	优先级	传输协议	实现状态
F1	🖼️ 双人/多人协作画布	collaboration/canvas	P2	WebRTC DataChannel	⬜
F2	📋 剪贴板同步管理	collaboration/clipboard	P2	信令通道 + WsRelay	⬜
F3	📱 屏幕共享+受限操作	collaboration/screen_share	P3	WebRTC 视频流	⬜
F4	大文件断点续传	file_transfer/transport	P1	WsRelay + WebRTC	✅ 92%
F5	消息送达回执	file_transfer/delivery	P1	信令通道	✅ 90%
F6	🎙️ 语音消息	file_transfer/voice	P2	WsRelay	🔵 82%
F7	🔌 USB有线传输	file_transfer/transport	P3	USB OTG	⬜
F8	☁️ 云端暂存(24h)	file_transfer/cloud_cache	P1	HTTPS REST	🔵 75%
F9	📊 传输统计面板	file_transfer/stats	P2	本地数据库	✅ 100%
F10	局域网网页访问	web_transfer	P1	HTTP Server	⬜
F11	跨网络网页传输	web_transfer	P1	WsRelay + WebRTC	⬜
F12	网页双向互传	web_transfer	P1	全协议	⬜

二、模块架构

2.1 目录结构

lib/features/
├── file_transfer/                    ← 现有模块，扩展
│   ├── database/
│   │   ├── transfer_database.dart    ← 扩展: 云端暂存CRUD
│   │   └── transfer_tables.dart      ← 扩展: 新增表
│   ├── models/
│   │   ├── transfer_enums.dart       ← 扩展: 新枚举
│   │   ├── transfer_device.dart
│   │   ├── transfer_message.dart     ← 扩展: 回执/语音字段
│   │   ├── transfer_task.dart        ← 扩展: 断点续传字段
│   │   ├── cloud_cache_record.dart   ← ✅ 已实现
│   │   ├── voice_message_data.dart   ← 新增
│   │   └── delivery_receipt.dart     ← 新增
│   ├── presentation/
│   │   ├── pages/
│   │   │   ├── file_transfer_page.dart
│   │   │   ├── transfer_chat_page.dart    ← 扩展: 语音+回执
│   │   │   ├── transfer_settings_page.dart
│   │   │   ├── transfer_stats_page.dart   ← 新增
│   │   │   └── device_pairing_page.dart
│   │   └── widgets/
│   │       ├── voice_bubble.dart          ← 新增
│   │       ├── receipt_indicator.dart     ← ✅ 已实现
│   │       ├── transfer_bubble.dart       ← ✅ 扩展完成
│   │       └── ...
│   ├── providers/
│   │   ├── transfer_provider.dart         ← ✅ 扩展完成
│   │   ├── transfer_state.dart            ← ✅ 拆分完成
│   │   ├── transfer_notifier.dart         ← ✅ 拆分完成
│   │   ├── transfer_pairing_handler.dart  ← ✅ 拆分完成
│   │   ├── transfer_signaling_handler.dart← ✅ 拆分完成
│   │   ├── cloud_cache_provider.dart      ← ✅ 已实现
│   │   └── transfer_stats_provider.dart   ← 新增
│   └── services/
│       ├── transport/
│       │   ├── ws_relay_service.dart      ← ✅ 扩展完成
│       │   ├── ws_relay_chunk_assembler.dart ← ✅ 拆分完成
│       │   ├── ws_relay_resume_handler.dart  ← ✅ 拆分完成
│       │   ├── webrtc_service.dart        ← 扩展: DataChannel复用
│       │   ├── transport_router.dart      ← 扩展: 新传输类型
│       │   └── usb_transport_service.dart ← 扩展: USB OTG
│       ├── cloud_cache_service.dart       ← ✅ 已实现
│       ├── delivery_receipt_service.dart  ← ✅ 已实现
│       ├── voice_message_service.dart     ← 新增
│       ├── transfer_stats_service.dart    ← 新增
│       └── signaling_service.dart         ← ✅ 扩展完成
│
├── collaboration/                    ← 新增模块
│   ├── canvas/  (F1)
│   ├── clipboard/  (F2)
│   └── screen_share/  (F3)
│
└── web_transfer/                     ← 新增模块(F10/F11/F12)

2.2 信令服务器扩展 ✅

server/index.js 已实现通用消息转发，支持所有新消息类型:

delivery-ack, chunk-ack, resume-request
voice-meta, cloud-cache-notify
canvas-stroke, canvas-cursor, canvas-join, canvas-leave, canvas-snapshot
screen-share-offer, screen-share-answer, screen-share-stop
remote-input

2.3 服务端API扩展

POST /api/file_transfer/cloud_cache/upload       上传暂存文件
GET  /api/file_transfer/cloud_cache/download     下载暂存文件
GET  /api/file_transfer/cloud_cache/list         查询暂存列表
DELETE /api/file_transfer/cloud_cache/clean      自动清理过期(服务端cron)
POST /api/file_transfer/cloud_cache/notify       通知离线设备有暂存
GET  /api/file_transfer/transfer_stats           传输统计数据
POST /api/file_transfer/voice_upload             语音文件上传
GET  /api/file_transfer/voice_download           语音文件下载

三、功能详细设计

F4: 大文件断点续传 ✅ 92%

实现状态: ✅ 核心完成 — v11.0.0+v11.1.0 协议+分片确认+重传+续传+UI控制+自动保存，待集成测试

已实现文件:

ws_relay_service.dart — fileMeta/fileChunk扩展字段
ws_relay_chunk_assembler.dart — 分片组装+chunkAck
ws_relay_resume_handler.dart — 断点续传+失败重传
transfer_task.dart — fileId/totalChunks/receivedChunks/retryCount字段
transfer_notifier.dart — _saveTaskProgress自动保存
TransferTaskCard — 暂停/继续/续传/取消按钮+分片进度条
TransferBubble — 文件气泡传输控制按钮

F5: 消息送达回执 ✅ 90%

实现状态: ✅ 核心完成 — v11.0.0 回执服务+UI指示器+气泡集成，待真机集成测试

UI指示器: 📤已发送(灰色单勾) → ✅已送达(灰色双勾) → ✅✅已读(蓝色双勾)

已实现文件:

delivery_receipt_service.dart — sendDeliveryAck + onReceiptUpdated
receipt_indicator.dart — 单勾/双勾/蓝色双勾
transfer_bubble.dart — 集成回执指示器
transfer_signaling_handler.dart — 自动注册回执监听

F6: 🎙️ 语音消息 🔵 82%

实现状态: 🔵 进行中 — v11.5.0 录音+播放+波形+VoiceBubble+聊天页集成，待真机测试

已实现:

组件	文件	状态
VoiceMessageData模型	`voice_message_data.dart`	✅
VoiceMessageService(录音+播放+波形)	`voice_message_service.dart`	✅
VoiceBubble(播放+进度+波形动画)	`voice_bubble.dart`	✅
VoiceRecordingOverlay(录音覆盖层)	`voice_recording_overlay.dart`	✅
TransferChatPage(🎤长按录音)	`transfer_chat_page.dart`	✅
TransferNotifier.sendVoiceMessage	`transfer_notifier.dart`	✅
语音消息发送(复用sendFiles)	WsRelay小文件模式	✅

待实现:

组件	说明
集成测试	录音→发送→接收→播放全流程真机验证

F8: ☁️ 云端暂存(24h) 🔵 75%

实现状态: 🔵 进行中 — v11.2.0 客户端+服务端已完成，剩余ECDH密钥协商+备份机制

场景: 对方离线时，文件暂存服务器(加密)，对方上线后自动拉取

已实现:

组件	文件	状态
CloudCacheRecord模型	`cloud_cache_record.dart`	✅
CloudCacheUploadStatus/DownloadStatus枚举	`cloud_cache_record.dart`	✅
AES-256-GCM加密/解密	`cloud_cache_service.dart`	✅
uploadFile/downloadFile(含进度回调)	`cloud_cache_service.dart`	✅
checkPendingCache + deleteCache	`cloud_cache_service.dart`	✅
备份管理(saveBackup/cleanExpiredBackups)	`cloud_cache_service.dart`	✅
CloudCacheState + CloudCacheNotifier	`cloud_cache_provider.dart`	✅
Riverpod provider注册	`transfer_provider.dart`	✅
数据库CRUD	`transfer_database.dart`	✅
服务端CloudCache.php控制器	`docs/toolsapi/application/api/controller/CloudCache.php`	✅
upload/download/list/info/delete/notify/clean/install接口	服务端API	✅
安全限制(未登录10MB/登录50MB)	服务端API	✅
危险文件类型检测	服务端API	✅
24小时自动清理(cron)	服务端API	✅
TransferProvider离线→提示暂存→上传	`transfer_notifier.dart` + `transfer_chat_page.dart`	✅
上线自动拉取暂存	`transfer_notifier.dart`	✅
API文档	`API_FILE_TRANSFER_DOC.md`	✅
接口测试(20项全通过)	`docs/toolsapi/scripts/`	✅

待实现:

组件	说明
ECDH密钥协商	当前使用对称加密，ECDH待实现
发送端备份机制完善	本地加密副本+7天自动清理

安全: 端到端加密(AES-256-GCM)，密钥仅收发双方持有，服务器无法解密，到期物理删除

F9: 📊 传输统计面板 ✅ 100%

实现状态: ✅ 已完成 — v11.4.0 统计服务+Provider+页面+路由入口

已实现:

组件	文件	状态
TransferStatsRecords表	`app_database.dart`	✅ v11.0.0
TransferStatsService(5种聚合查询)	`transfer_stats_service.dart`	✅
TransferStatsService(每日快照写入)	`transfer_stats_service.dart`	✅
TransferStatsState+TransferStatsNotifier	`transfer_stats_provider.dart`	✅
TransferStatsPage总览卡片	`transfer_stats_page.dart`	✅
TransferStatsPage趋势折线图(fl_chart)	`transfer_stats_page.dart`	✅
TransferStatsPage设备排行	`transfer_stats_page.dart`	✅
TransferStatsPage文件类型饼图	`transfer_stats_page.dart`	✅
TransferStatsPage传输质量指标	`transfer_stats_page.dart`	✅
设置页"📊统计"入口	`transfer_settings_page.dart`	✅
数据库CRUD方法	`transfer_database.dart`	✅

F1: 🖼️ 双人/多人协作画布

入口: 工具中心"云画布" + 聊天页"🎨画布"按钮

同步协议:

1. 创建画布 → 信令服务器创建canvas房间
2. 邀请他人 → 发送canvas-join消息
3. 绘制笔画 → WebRTC DataChannel广播Stroke
4. 冲突解决 → CRDT Lamport时钟排序
5. 离线缓存 → 本地SQLite暂存未同步笔画
6. 断线重连 → 请求全量stroke快照

画布引擎:

基于 CustomPainter + Canvas API 渲染
支持画笔/橡皮/形状/文字/颜色/粗细
图层面板(可选)
导出为PNG/SVG

F2: 📋 剪贴板同步管理

入口: 灵感页面"剪贴板管理"会话流

增强现有 ClipboardSyncService:

现有: 仅文本同步，轮询检测
新增: 图片剪贴板同步(压缩后通过WsRelay)
新增: 剪贴板历史记录(SQLite存储)
新增: 置顶/删除/搜索
新增: 手动发送剪贴板内容

F3: 📱 屏幕共享+受限操作

流程:

1. 发起方请求共享 → screen-share-offer信令
2. 接收方同意 → screen-share-answer信令
3. WebRTC视频流建立 → 发起方捕获屏幕编码发送
4. 接收方观看实时画面
5. 受限操作: 接收方点击预设区域 → remote-input信令 → 发起方模拟点击

安全机制:

共享方随时可终止共享
受限操作需共享方授权(首次弹窗确认)
操作日志记录(谁在何时执行了什么动作)
超时自动断开(30分钟)

F7: 🔌 USB有线传输

Android USB OTG:

通过 usb_accessory 模式建立通信
速度: USB 2.0 ~30MB/s, USB 3.0 ~100MB/s
限制: 仅Android↔Android，需USB OTG支持

F10/F11/F12: 网页传输

模式1: 取件码模式(现有) 输入6位码 → 连接房间 → 接收文件

模式2: 账号模式(新增) 登录账号 → 发现同账号App设备 → 双向传输

模式3: 局域网模式(新增) 自动发现局域网App → 直连传输

四、数据库扩展 ✅

实现状态: ✅ 已完成 — schemaVersion=13，6张新表+字段ALTER

4.1 新增表

cloud_cache_records — 云端暂存记录 ✅
chunk_ack_logs — 分片确认日志 ✅
delivery_receipts — 消息送达回执 ✅
clipboard_items — 剪贴板历史 ✅
canvas_documents — 画布文档 ✅
transfer_stats_records — 传输统计快照 ✅

4.2 现有表扩展 ✅

transfer_records 新增: file_id, total_chunks, received_chunks, retry_count
transfer_msg_records 新增: delivery_status, delivered_at, read_at, voice_duration, voice_waveform

五、信令协议扩展 ✅

实现状态: ✅ 已完成 — 14种新消息类型 + 通用转发机制

5.1 新增 SignalingMessageType 枚举 ✅

delivery-ack, chunk-ack, resume-request, voice-meta, cloud-cache-notify, canvas-stroke, canvas-cursor, canvas-join, canvas-leave, canvas-snapshot, screen-share-offer, screen-share-answer, screen-share-stop, remote-input

5.2 消息格式 ✅

所有新消息类型均通过通用转发机制路由，格式: { type, from, to, payload }

六、性能指标

功能	目标	方案
断点续传恢复	<2秒	本地缓存receivedChunks
送达回执延迟	<500ms	信令通道直发
云端暂存上传	取决于网络	分片+进度回调
云端暂存下载	取决于网络	分片+进度回调
统计面板	加载<500ms	预计算+缓存

14 KiB Raw Blame History Unescape Escape

闲言APP — 传输助手功能扩展设计文档

一、功能总览

二、模块架构

2.1 目录结构

2.2 信令服务器扩展 ✅

2.3 服务端API扩展

三、功能详细设计

F4: 大文件断点续传 ✅ 92%

F5: 消息送达回执 ✅ 90%

F6: 🎙️ 语音消息 🔵 82%

F8: ☁️ 云端暂存(24h) 🔵 75%

F9: 📊 传输统计面板 ✅ 100%

F1: 🖼️ 双人/多人协作画布

F2: 📋 剪贴板同步管理

F3: 📱 屏幕共享+受限操作

F7: 🔌 USB有线传输

F10/F11/F12: 网页传输

四、数据库扩展 ✅

4.1 新增表

4.2 现有表扩展 ✅

五、信令协议扩展 ✅

5.1 新增 SignalingMessageType 枚举 ✅

5.2 消息格式 ✅

六、性能指标

14 KiB

Raw Blame History