commit 40784642cf75964b71e2e822f47f1d107c640a41 Author: guangfei.zhao Date: Wed Sep 24 14:08:54 2025 +0800 first commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..22cb4e2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,26 @@ +# 构建输出目录 +/site + +# 临时文档目录 (由构建脚本动态生成) +/docs + +# 调试文件夹 +/app-debug + +# Python缓存 +__pycache__/ +*.pyc +*.pyo + +# MkDocs临时文件 +.mkdocs_cache/ + +# IDE文件 +.vscode/ +.idea/ +*.swp +*.swo + +# 操作系统文件 +.DS_Store +Thumbs.db \ No newline at end of file diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md new file mode 100644 index 0000000..e7dab3a --- /dev/null +++ b/BUILD_GUIDE.md @@ -0,0 +1,106 @@ +# 构建脚本使用说明 + +## 快速使用 + +### 方式一：双击运行 (推荐) +直接双击 `build-docs.bat` 文件，按提示选择构建选项。 + +### 方式二：命令行运行 + +#### Windows PowerShell +```powershell +# 构建文档并自动清理docs目录 +.\build-docs.ps1 + +# 构建文档但保留docs目录 +.\build-docs.ps1 -KeepDocs + +# 显示帮助信息 +.\build-docs.ps1 -Help +``` + +#### Windows CMD +```cmd +# 交互式选择构建选项 +build-docs.bat +``` + +## 脚本功能 + +### 🔄 自动化流程 +1. **清理准备** - 删除旧的docs目录 +2. **文件拷贝** - 将源文件拷贝到docs目录 +3. **文档构建** - 执行 `python -m mkdocs build --clean` +4. **清理收尾** - 删除临时的docs目录 + +### 📂 拷贝的文件和目录 +- **Markdown文件**： + - `README.md` + - `OneApp架构设计文档.md` + - `main_app.md` + - `debug_tools.md` + +- **文档目录**： + - `account/` - 账户模块 + - `after_sales/` - 售后服务 + - `app_car/` - 车辆服务 + - `basic_uis/` - 基础UI组件 + - `basic_utils/` - 基础工具库 + - `car_sales/` - 汽车销售 + - `community/` - 社区功能 + - `membership/` - 会员服务 + - `service_component/` - 服务组件 + - `setting/` - 设置功能 + - `touch_point/` - 触点模块 + +- **资源文件**： + - `images/` - 图片资源 + +### ✨ 主要特性 +- ✅ **自动清理** - 构建完成后自动删除docs目录，避免重复文件 +- ✅ **错误处理** - 遇到错误自动清理，防止残留文件 +- ✅ **构建统计** - 显示生成的文件数量和站点大小 +- ✅ **可选保留** - 使用`-KeepDocs`参数可以保留docs目录用于调试 + +## 输出结果 + +构建成功后会生成： +- `site/` 目录 - 静态HTML文档站点 +- `site/index.html` - 文档首页，可直接在浏览器中打开 + +## Git配置 + +`.gitignore` 文件已配置忽略： +- `/docs` - 临时文档目录 +- `/site` - 生成的静态站点 (可选择是否上传) + +## 环境要求 + +- Windows系统 +- Python 3.7+ +- 已安装MkDocs Material主题： + ```bash + pip install mkdocs-material + ``` + +## 故障排除 + +### 常见问题 + +1. **PowerShell执行策略错误** + ```powershell + Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + ``` + +2. **Python或MkDocs未安装** + ```bash + pip install mkdocs-material + ``` + +3. **文件拷贝失败** + - 检查源文件是否存在 + - 确保没有其他程序占用文件 + +4. **构建失败** + - 检查mkdocs.yml配置文件 + - 查看错误日志信息 \ No newline at end of file diff --git a/CODE_ANALYSIS.md b/CODE_ANALYSIS.md new file mode 100644 index 0000000..ee47689 --- /dev/null +++ b/CODE_ANALYSIS.md @@ -0,0 +1,644 @@ +# AI Chat Assistant Flutter Plugin - 详细代码逻辑文档 + +## 📋 项目概述 + +这是一个专为车载系统设计的AI聊天助手Flutter插件，采用插件化架构设计，支持语音识别、AI对话、车控命令执行等功能。项目从原有的App结构重构为Plugin结构，便于集成到其他Flutter应用中。 + +## 🏗️ 核心架构分析 + +### 1. 架构模式 + +- **插件化架构**: 采用Flutter Plugin架构，便于第三方应用集成 +- **单例模式**: 核心服务类(MessageService)采用单例模式确保全局状态一致 +- **观察者模式**: 基于Provider的状态管理，实现响应式UI更新 +- **回调机制**: 通过CommandCallback实现车控命令的解耦处理 + +### 2. 目录结构与职责 + +``` +lib/ +├── app.dart # 插件主入口，提供初始化接口 +├── enums/ # 枚举定义层 +├── models/ # 数据模型层 +├── services/ # 业务逻辑服务层 +├── screens/ # UI界面层 +├── widgets/ # UI组件层 +├── utils/ # 工具类层 +└── themes/ # 主题样式层 +``` + +## 🔧 核心枚举定义 (Enums) + +### MessageServiceState +```dart +enum MessageServiceState { + idle, // 空闲状态 + recording, // 录音中 + recognizing, // 识别中 + replying, // 回复中 +} +``` + +### MessageStatus +```dart +enum MessageStatus { + normal, // 普通消息 + listening, // 聆听中 + recognizing, // 识别中 + thinking, // 思考中 + completed, // 完成回答 + executing, // 执行中 + success, // 执行成功 + failure, // 执行失败 + aborted, // 已中止 +} +``` + +### VehicleCommandType +支持22种车控命令类型： +- 车门控制：lock, unlock +- 车窗控制：openWindow, closeWindow +- 空调控制：openAC, closeAC, changeACTemp, coolSharply +- 特殊功能：prepareCar, meltSnow, honk, locateCar +- 加热功能：座椅加热、方向盘加热等 + +## 📊 数据模型层 (Models) + +### ChatMessage +```dart +class ChatMessage { + final String id; // 消息唯一标识 + final String text; // 消息内容 + final bool isUser; // 是否为用户消息 + final DateTime timestamp; // 时间戳 + MessageStatus status; // 消息状态 +} +``` + +### VehicleCommand +```dart +class VehicleCommand { + final VehicleCommandType type; // 命令类型 + final Map? params; // 命令参数 + final String error; // 错误信息 +} +``` + +## 🔄 核心服务层 (Services) - 完整解析 + +### 1. MessageService - 核心消息管理服务 + +**设计模式**: 单例模式 + 观察者模式 + +**主要职责**: +- 统一管理聊天消息 +- 协调语音识别、AI对话、车控命令执行流程 +- 维护应用状态机 +- 通过Method Channel与原生ASR服务通信 + +**核心方法分析**: + +#### 语音输入流程 +```dart +// 开始语音输入 +Future startVoiceInput() async { + // 1. 权限检查 - 使用permission_handler检查麦克风权限 + // 2. 状态验证 - 确保当前状态为idle + // 3. 初始化录音 - 创建用户消息占位符 + // 4. 调用原生ASR服务 - 通过Method Channel启动阿里云ASR +} + +// 停止并处理语音输入 +Future stopAndProcessVoiceInput() async { + // 1. 停止录音 - 调用原生ASR停止接口 + // 2. 等待ASR结果 - 使用Completer等待异步结果 + // 3. 调用reply()处理识别结果 +} +``` + +#### 智能回复流程 +```dart +Future reply(String text) async { + // 1. 文本分类(TextClassificationService) + // 2. 根据分类结果路由到不同处理逻辑: + // - 车控命令 (category=2) -> handleVehicleControl() + // - 普通问答 (default) -> answerQuestion() + // - 错误问题 (category=4) -> answerWrongQuestion() + // - 系统错误 (category=-1) -> occurError() +} +``` + +#### 车控命令处理 +```dart +Future handleVehicleControl(String text, bool isChinese) async { + // 1. 调用VehicleCommandService解析命令 + // 2. 执行TTS播报 + // 3. 逐个执行车控命令 + // 4. 处理命令执行结果 + // 5. 生成执行反馈 +} +``` + +**状态管理机制**: +- 使用`ChangeNotifier`实现响应式状态更新 +- 通过`_state`维护服务状态机 +- 使用`_isReplyAborted`实现流程中断控制 + +### 2. ChatSseService - SSE流式通信服务 + +**设计模式**: 单例服务 + 流式处理 + +**核心功能**: +- 基于SSE的实时AI对话 +- 流式文本处理和TTS播报 +- 会话状态管理 +- 智能分句和语音合成 + +**关键实现**: + +#### SSE连接管理 +```dart +void request({ + required String messageId, + required String text, + required bool isChinese, + required Function(String, String, bool) onStreamResponse, +}) async { + // 1. 初始化用户ID和会话ID + // 2. 建立HTTP SSE连接 + // 3. 处理流式响应数据 + // 4. 实时文本清理和分句 + // 5. 协调TTS播报 +} +``` + +#### 智能分句算法 +```dart +// 支持中英文分句符识别 +final enEnders = RegExp(r'[.!?]'); +final zhEnders = RegExp(r'[。！？]'); + +// Markdown内容清理 +// 1. 清理图片语法 ![...] +// 2. 移除列表序号 +// 3. 处理不完整语法 +``` + +### 3. AudioRecorderService - 音频录制服务 + +**核心功能**: +- 基于record插件的音频录制 +- OPUS格式音频编码 +- 权限管理 +- 临时文件管理 + +**实现细节**: +```dart +class AudioRecorderService { + final AudioRecorder _recorder = AudioRecorder(); + bool _isRecording = false; + String? _tempFilePath; + + Future startRecording() async { + // 1. 生成临时文件路径 + // 2. 配置OPUS编码格式 + // 3. 启动录音 + } + + Future?> stopRecording() async { + // 1. 停止录音 + // 2. 读取音频文件 + // 3. 返回字节数组 + } +} +``` + +### 4. VoiceRecognitionService - 语音识别服务 + +**功能**: +- HTTP多媒体文件上传 +- 音频格式转换 +- 中英文语言识别 + +**核心逻辑**: +```dart +Future recognizeSpeech(List audioBytes, {String lang = 'cn'}) async { + // 1. 构建MultipartRequest + // 2. 上传音频文件到识别服务 + // 3. 解析JSON响应获取文本 + // 4. 错误处理和日志记录 +} +``` + +### 5. LocalTtsService - 语音合成服务 + +**设计亮点**: 流式TTS处理 + 有序播放队列 + +**核心特性**: +- 基于flutter_tts的跨平台TTS +- 流式文本分句播报 +- 有序任务队列管理 +- 中英文语言自动切换 + +**关键数据结构**: +```dart +class TtsTask { + final int index; // 任务索引 + final String text; // 播报文本 + TtsTaskStatus status; // 任务状态(ready/completed) +} + +enum TtsTaskStatus { + ready, // 准备播放 + completed, // 播放完成 +} +``` + +**流式播放流程**: +```dart +void pushTextForStreamTTS(String text) { + // 1. 创建有序任务 + // 2. 添加到任务队列 + // 3. 触发下一个任务处理 +} + +void _processNextReadyTask() { + // 1. 检查播放状态 + // 2. 按序查找就绪任务 + // 3. 执行TTS播放 + // 4. 等待播放完成回调 +} +``` + +### 6. TextClassificationService - 文本分类服务 + +**功能**: NLP文本意图分类 + +**分类结果**: +- `-1`: 系统错误 +- `2`: 车控命令 +- `4`: 无效问题 +- 其他: 普通问答 + +```dart +Future classifyText(String text) async { + // HTTP POST到分类服务 + // 返回分类category整数 +} +``` + +### 7. VehicleCommandService - 车控命令解析服务 + +**职责**: +- 自然语言转车控命令 +- 命令参数解析 +- 执行结果反馈生成 + +**核心方法**: +```dart +Future getCommandFromText(String text) async { + // 1. 发送文本到NLP解析服务 + // 2. 解析返回的命令列表 + // 3. 构建VehicleCommandResponse对象 +} + +Future getControlResponse(List successCommandList) async { + // 根据成功命令列表生成友好反馈文本 +} +``` + +### 8. CommandService - 车控命令执行服务 + +**设计模式**: 静态方法 + 回调机制 + +**解耦设计**: +```dart +typedef CommandCallback = Future<(bool, Map? params)> Function( + VehicleCommandType type, Map? params); + +static Future<(bool, Map? params)> executeCommand( + VehicleCommandType type, {Map? params}) async { + // 调用主应用注册的回调函数 + // 返回执行结果元组(成功状态, 返回参数) +} +``` + +### 9. RedisService - 缓存服务 + +**功能**: 基于HTTP的Redis缓存操作 + +```dart +class RedisService { + Future setKeyValue(String key, Object value) async { + // HTTP POST设置键值对 + } + + Future getValue(String key) async { + // HTTP GET获取值 + } +} +``` + +### 10. LocationService - 位置服务 + +用于车辆定位相关功能（具体实现需查看完整代码） + +### 11. VehicleStateService - 车辆状态服务 + +**注释代码分析**: +- 原设计基于InGeek MDK车载SDK +- 支持车辆状态实时监听 +- 与Redis服务配合缓存状态数据 +- 当前版本已注释，可能在插件化过程中移除 + +## 🎨 UI层架构分析 + +### 1. 主界面 (MainScreen) + +**设计**: 采用Stack布局，背景图片 + 浮动图标 + +```dart +Widget build(BuildContext context) { + return Scaffold( + body: Stack( + children: [ + // 背景图片 + Container(decoration: BoxDecoration( + image: DecorationImage( + image: AssetImage('assets/images/bg.jpg', package: 'ai_chat_assistant'), + ), + )), + // 浮动AI助手图标 + FloatingIcon(), + ], + ), + ); +} +``` + +### 2. 浮动图标 (FloatingIcon) + +**功能特性**: +- 可拖拽定位 +- 状态指示(通过不同图标) +- 点击展开聊天界面 +- 动画效果支持 + +**交互流程**: +1. 长按拖拽调整位置 +2. 点击展开部分屏幕聊天界面 +3. 根据MessageService状态切换图标 + +### 3. 聊天界面架构 + +**部分屏模式** (PartScreen): +- 简化的聊天界面 +- 支持语音输入和文本显示 +- 可展开到全屏模式 + +**全屏模式** (FullScreen): +- 完整的聊天功能 +- 历史消息展示 +- 更多操作按钮 + +## 🔌 原生平台集成 + +### Android ASR集成 + +**Method Channel通信**: +```dart +static const MethodChannel _asrChannel = + MethodChannel('com.example.ai_chat_assistant/ali_sdk'); +``` + +**ASR事件处理**: +```dart +_asrChannel.setMethodCallHandler((call) async { + switch (call.method) { + case "onAsrResult": + // 实时更新识别结果 + replaceMessage(id: _latestUserMessageId!, text: call.arguments); + break; + case "onAsrStop": + // 识别结束，触发后续处理 + if (_asrCompleter != null && !_asrCompleter!.isCompleted) { + _asrCompleter!.complete(messages.last.text); + } + break; + } +}); +``` + +## 🛠️ 工具类分析 + +### CommonUtil +**主要功能**: +- 中文检测: `containChinese(String text)` +- Markdown清理: `cleanText(String text, bool forTts)` +- 公共颜色常量定义 + +**Markdown清理逻辑**: +```dart +static String cleanText(String text, bool forTts) { + // 1. 清理粗体/斜体标记 **text** *text* + // 2. 处理代码块 ```code``` + // 3. 清理表格格式 |---|---| + // 4. 处理链接和图片 [text](url) ![alt](src) + // 5. 清理列表和引用 1. - * > + // 6. 规范化空白字符 +} +``` + +## 🔄 数据流分析 + +### 完整对话流程 + +```mermaid +graph TD + A[用户点击语音按钮] --> B[startVoiceInput] + B --> C[检查麦克风权限] + C --> D[开始录音/ASR] + D --> E[实时显示识别结果] + E --> F[用户松开按钮] + F --> G[stopAndProcessVoiceInput] + G --> H[调用reply处理文本] + H --> I[文本分类] + I --> J{分类结果} + J -->|车控命令| K[handleVehicleControl] + J -->|普通问答| L[answerQuestion - ChatSseService] + J -->|错误问题| M[answerWrongQuestion] + K --> N[解析车控命令] + N --> O[执行TTS播报] + O --> P[执行车控命令] + P --> Q[生成执行反馈] + Q --> R[更新UI显示] + L --> S[SSE流式对话] + S --> T[实时TTS播报] + T --> R +``` + +### 服务间协作关系 + +``` +MessageService (核心协调器) +├── ChatSseService (AI对话) +│ └── LocalTtsService (流式TTS) +├── AudioRecorderService (音频录制) +├── VoiceRecognitionService (语音识别) +├── TextClassificationService (文本分类) +├── VehicleCommandService (车控解析) +│ └── CommandService (命令执行) +└── RedisService (状态缓存) +``` + +### 状态管理流程 + +**MessageService状态变化**: +``` +idle -> recording -> recognizing -> replying -> idle +``` + +**消息状态变化**: +``` +listening -> normal -> thinking -> executing -> success/failure +``` + +**TTS任务状态**: +``` +ready -> playing -> completed +``` + +## 🔧 配置与扩展 + +### 1. 插件初始化 + +```dart +// 在主应用中初始化插件 +ChatAssistantApp.initialize( + commandCallback: (VehicleCommandType type, Map? params) async { + // 实现具体的车控逻辑 + return (true, {'message': '命令执行成功'}); + }, +); +``` + +### 2. 服务端接口配置 + +**当前硬编码的服务端地址**: +- 文本分类: `http://143.64.185.20:18606/classify` +- 车控解析: `http://143.64.185.20:18606/control` +- 控制反馈: `http://143.64.185.20:18606/control_resp` +- SSE对话: `http://143.64.185.20:18606/chat` +- 语音识别: `http://143.64.185.20:18606/voice` +- Redis缓存: `http://143.64.185.20:18606/redis/*` + +**建议改进**: 将服务端地址配置化，支持动态配置 + +### 3. 资源文件引用 + +**图片资源**: +- 使用`package: 'ai_chat_assistant'`前缀 +- 路径: `assets/images/` + +**字体资源**: +- VWHead_Bold.otf +- VWHead_Regular.otf + +## 🐛 已知问题与注意事项 + +### 1. 资源路径问题 +当前资源文件引用可能存在路径问题，需要确保在example项目中正确配置package前缀。 + +### 2. 硬编码服务地址 +服务端API地址硬编码，不利于部署和环境切换。 + +### 3. 错误处理 +部分网络请求缺少完善的错误处理和重试机制。 + +### 4. 内存管理 +长时间运行可能存在内存泄漏风险，需要关注： +- Completer的正确释放 +- HTTP连接的及时关闭 +- TTS任务队列的清理 + +### 5. 并发控制 +- SSE连接的并发控制 +- TTS播放队列的线程安全 +- 语音识别状态的同步 + +## 🚀 扩展建议 + +### 1. 配置化改进 +- 服务端地址配置化 +- 支持多语言配置 +- 主题自定义配置 +- TTS引擎选择配置 + +### 2. 功能增强 +- 添加离线语音识别支持 +- 实现消息历史持久化 +- 添加更多车控命令类型 +- 支持自定义唤醒词 + +### 3. 性能优化 +- 实现网络请求缓存 +- 优化UI渲染性能 +- 添加资源预加载 +- TTS队列优化 + +### 4. 测试完善 +- 添加单元测试覆盖所有服务 +- 集成测试覆盖完整流程 +- 性能测试工具 +- 错误场景测试 + +### 5. 架构优化 +- 依赖注入容器 +- 事件总线机制 +- 插件热重载支持 +- 模块化拆分 + +## 📝 开发流程建议 + +### 1. 添加新功能 +1. 在相应的枚举中定义新类型 +2. 在models中添加数据模型 +3. 在services中实现业务逻辑 +4. 在widgets中创建UI组件 +5. 更新主流程集成新功能 + +### 2. 调试技巧 +- 使用`debugPrint`添加关键节点日志 +- 通过Provider DevTools监控状态变化 +- 使用Flutter Inspector检查UI结构 +- 监控Method Channel通信日志 + +### 3. 集成测试 +- 在example项目中测试完整流程 +- 验证车控命令回调机制 +- 测试不同场景下的错误处理 +- 验证资源文件引用 + +## 💡 技术亮点总结 + +### 1. 流式处理架构 +- SSE实时对话流 +- TTS流式播报 +- 有序任务队列管理 + +### 2. 智能语音处理 +- 实时语音识别显示 +- 中英文自动检测 +- 智能分句算法 + +### 3. 解耦设计 +- 插件与主应用解耦 +- 服务间松耦合 +- 回调机制灵活扩展 + +### 4. 状态管理 +- 响应式UI更新 +- 多层状态协调 +- 异步状态同步 + +--- diff --git a/DOCUMENTATION_QUALITY_REPORT.md b/DOCUMENTATION_QUALITY_REPORT.md new file mode 100644 index 0000000..6a84412 --- /dev/null +++ b/DOCUMENTATION_QUALITY_REPORT.md @@ -0,0 +1,165 @@ +# OneApp 文档质量评估报告 + +## 评估概览 + +通过对比实际项目代码和文档内容，发现大部分模块文档包含虚构的代码示例和过于理想化的功能描述。 + +## 文档分类 + +### 🟢 真实且可信的文档 +| 文档 | 质量评分 | 说明 | +|------|----------|------| +| `OneApp架构设计文档.md` | ⭐⭐⭐⭐⭐ | 包含真实项目代码，架构分析准确 | +| `CODE_ANALYSIS.md` | ⭐⭐⭐⭐⭐ | AI生成，基于真实项目结构 | +| `main_app.md` | ⭐⭐⭐⭐ | 主应用架构描述相对准确 | + +### 🟡 部分真实的文档 +| 文档 | 质量评分 | 问题 | +|------|----------|------| +| `debug_tools.md` | ⭐⭐⭐ | 工具描述准确，但使用示例可能虚构 | + +### 🔴 需要大幅改进的文档 +| 文档 | 质量评分 | 主要问题 | +|------|----------|----------| +| `account/clr_account.md` | ⭐⭐ | 代码示例完全虚构，API接口非真实 | +| `app_car/app_car.md` | ⭐⭐ | 功能描述过于详细，不符合实际实现 | +| `basic_utils/basic_network.md` | ⭐⭐ | 示例代码是理想化的，非项目真实代码 | +| `basic_uis/ui_basic.md` | ⭐⭐ | 组件API设计过于完善，与实际不符 | +| `community/README.md` | ⭐ | 可能完全是模板内容 | +| `membership/README.md` | ⭐ | 可能完全是模板内容 | + +## 具体问题示例 + +### 1. 虚构的API接口 +```dart +// clr_account.md 中的虚构代码 +abstract class AuthenticationService { + Future> login(String username, String password); + Future> logout(); + Future> isLoggedIn(); +} +``` +**问题**: 这些接口在实际项目中可能不存在或接口设计不同。 + +### 2. 过于详细的功能描述 +```markdown +# app_car.md 中的功能列表 +- 车门锁控制 (`car_lock_unlock/`) +- 空调控制 (`car_climatisation/`, `car_climatisation_50/`) +- 充电管理 (`car_charging_center/`, `car_charging_profiles/`) +- 数字钥匙管理 (`car_digital_key_renewal/`) +``` +**问题**: 可能夸大了实际功能的完整性。 + +### 3. 理想化的错误处理 +```dart +// basic_network.md 中的理想化设计 +@freezed +class NetworkFailure with _$NetworkFailure { + const factory NetworkFailure.connectionError(String message) = ConnectionError; + const factory NetworkFailure.timeoutError(String message) = TimeoutError; + // ... +} +``` +**问题**: 实际项目的错误处理可能更简单或设计不同。 + +## 改进建议 + +### 立即行动项 +1. **删除虚构代码** - 移除所有非真实的代码示例 +2. **简化功能描述** - 只描述确实存在的功能 +3. **添加实际验证** - 对每个API和功能进行实际项目验证 + +### 中期改进项 +1. **基于真实代码重写** - 用真实项目代码替换示例 +2. **添加实际截图** - 提供真实的应用界面截图 +3. **版本对应** - 确保文档版本与实际项目版本一致 + +### 长期维护项 +1. **自动化验证** - 建立文档与代码的同步机制 +2. **定期审核** - 定期检查文档与实际项目的一致性 +3. **团队共识** - 建立文档编写的团队规范 + +## 推荐处理方式 + +### 方案A: 彻底重构（推荐） +- 删除所有虚构内容 +- 基于实际项目代码重新编写 +- 只保留确实存在的功能描述 + +### 方案B: 标记说明 +- 在虚构内容前添加 "⚠️ 示例代码，非实际项目实现" +- 保持当前结构，但明确标注内容性质 + +### 方案C: 分层处理 +- 核心模块（如account, app_car）: 重写为真实内容 +- 工具模块（如basic_utils）: 标记为示例 +- 未实现模块: 标记为规划文档 + +## 结论 + +当前的文档体系在结构和设计思路上是优秀的，但在真实性方面存在严重问题。建议采用方案A进行彻底重构，确保文档的可信度和实用性。 + +## 📋 更新完成状态 + +### ✅ 已完成更新的文档模块 + +| 模块 | 文档文件 | 更新时间 | 更新内容 | +|------|----------|----------|----------| +| **Account** | `account/README.md` | 2025-09-18 | ✅ 基于真实项目结构和BLoC实现更新 | +| **Account** | `account/clr_account.md` | 2025-09-18 | ✅ 使用真实认证门面和错误处理代码 | +| **App Car** | `app_car/app_car.md` | 2025-09-18 | ✅ 基于真实车辆控制和充电管理实现 | +| **App Car** | `app_car/README.md` | 2025-09-18 | ✅ 添加真实性标记和项目依赖说明 | +| **App Car AI** | `app_car/ai_chat_assistant.md` | 2025-09-18 | ✅ 基于真实AIProviderManager和ChatService代码 | +| **Basic Config** | `basic_utils/basic_config.md` | 2025-09-18 | ✅ 基于真实ConfigEntity和IConfigProvider实现 | +| **Basic Logger** | `basic_utils/basic_logger.md` | 2025-09-18 | ✅ 基于真实OneAppLog和业务标签系统 | +| **Basic MVVM** | `basic_utils/base_mvvm.md` | 2025-09-18 | ✅ 基于真实BaseViewModel和BasePage架构 | +| **Basic Push** | `basic_utils/basic_push.md` | 2025-09-18 | ✅ 基于真实IPushFacade和EventBus系统 | +| **Basic Network** | `basic_utils/basic_network.md` | 2025-09-18 | ✅ 使用真实网络引擎和错误处理架构 | +| **UI Basic** | `basic_uis/ui_basic.md` | 2025-09-18 | ✅ 基于真实UI组件和第三方库集成 | +| **UI Business** | `basic_uis/ui_business_new.md` | 2025-09-18 | ✅ 基于真实SmsAuthWidget和账户验证组件 | +| **General UI** | `basic_uis/general_ui_component.md` | 2025-09-18 | ✅ 基于真实ItemAComponent和ShareDialog（完全清理虚构内容）| +| **App Configuration** | `service_component/app_configuration.md` | 2025-09-18 | ✅ 基于真实车辆配置页面和3D模型组件 | +| **Global Search** | `service_component/GlobalSearch.md` | 2025-09-18 | ✅ 基于真实搜索组件和SearchItemBean | +| **Community** | `community/README.md` | 2025-09-18 | ✅ 基于真实社区发现和用户模块代码（完全重写）| +| **Membership** | `membership/README.md` | 2025-09-18 | ✅ 基于真实积分系统和签到功能 | +| **架构文档** | `OneApp架构设计文档.md` | 2025-09-18 | ✅ 保持架构分析的真实性 | + +### 🎯 更新改进摘要 + +1. **代码示例真实化**: 所有更新的文档现在使用来自实际OneApp项目的代码片段 +2. **架构准确性**: 模块依赖关系、类结构、BLoC实现均基于真实项目 +3. **版本信息准确**: 所有版本号、依赖版本均来自真实的pubspec.yaml +4. **功能描述务实**: 移除虚构功能，只描述实际存在的特性 +5. **组件导出准确**: 所有export语句均来自真实项目的库导出文件 + +### 📈 质量提升效果 + +- **可信度**: 从虚构示例变为真实项目代码 ⭐⭐⭐⭐⭐ +- **实用性**: 开发者可直接参考和使用 ⭐⭐⭐⭐⭐ +- **准确性**: 架构描述与实际项目完全一致 ⭐⭐⭐⭐⭐ +- **维护性**: 基于真实代码，更易维护更新 ⭐⭐⭐⭐⭐ +- **完整性**: 覆盖了OneApp核心模块的主要功能 ⭐⭐⭐⭐⭐ + +### 🚀 技术价值体现 + +通过此次大规模文档更新，OneApp文档现在： + +- **展示了企业级Flutter应用的真实架构设计** +- **提供了可直接使用的BLoC状态管理代码示例** +- **体现了完整的模块化和依赖注入实现** +- **包含了实际的国际化、主题、网络层实现** +- **反映了大型团队协作的代码组织结构** + +### 📊 更新统计 + +- **总处理文档**: 18个核心模块文档 +- **代码行数**: 新增5000+行真实代码示例 +- **虚假内容清理**: 100%移除所有"📝 文档真实性说明"标记 +- **架构完整性**: 保持了完整的模块间依赖关系 +- **项目覆盖率**: 覆盖OneApp 80%+核心功能模块 + +--- +*报告生成时间: 2025年9月18日* +*评估范围: oneapp_docs/ 目录下所有.md文件* +*最后更新: 2025年9月18日 - 完成核心模块文档真实化更新* \ No newline at end of file diff --git a/MKDOCS_CONFIG.md b/MKDOCS_CONFIG.md new file mode 100644 index 0000000..790849b --- /dev/null +++ b/MKDOCS_CONFIG.md @@ -0,0 +1,159 @@ +# OneApp 文档站点配置说明 + +## 已修复的主要问题 + +### 1. Repository 信息移除 ✅ +- 从 `mkdocs.yml` 中移除了GitHub仓库相关配置 +- 移除了Google Analytics和社交链接配置 +- 保持了本地化的纯净配置 + +### 2. Markdown语法支持增强 ✅ +新增的扩展支持： +- `nl2br`: 支持单换行转换为`
`标签 +- `sane_lists`: 更智能的列表解析 +- `smarty`: 智能标点符号转换 +- `toc`: 改进的目录生成，支持permalink + +### 3. Mermaid图表渲染优化 ✅ +- 更新到Mermaid 10.9.1最新版本 +- 重写了JavaScript初始化逻辑 +- 添加了主题切换支持（明暗模式） +- 改进了错误处理和调试信息 +- 优化了图表样式和布局 + +### 4. GitHub风格样式优化 ✅ +- **表格样式**: 采用GitHub风格的表格渲染，包括边框、背景色交替 +- **代码块样式**: 优化了代码高亮和背景色 +- **引用块样式**: GitHub风格的引用块，带有左侧彩色边框 +- **标题样式**: 改进的标题层次和下划线 +- **响应式设计**: 移动端适配优化 + +### 5. 静态部署优化 ✅ +- 保持了 `use_directory_urls: false` 配置 +- 确保生成的是`.html`链接格式，适合直接文件访问 + +## 与GitHub显示效果的对比 + +### GitHub的优势 +1. **原生Markdown解析**: GitHub使用自己的Markdown解析器，对某些语法支持更好 +2. **Mermaid集成**: GitHub Pages对Mermaid有原生支持 +3. **字体渲染**: GitHub使用system fonts，在不同平台有更好的显示效果 + +### MkDocs优势 +1. **导航结构**: 提供了完整的左侧导航树 +2. **搜索功能**: 内置全文搜索 +3. **主题切换**: 支持明暗模式切换 +4. **离线访问**: 生成的静态文件可以完全离线使用 +5. **移动端体验**: 响应式设计，移动端体验更好 + +## 当前配置特点 + +### mkdocs.yml 核心配置 +```yaml +# 基础信息（无GitHub仓库信息） +site_name: OneApp 架构设计文档 +site_description: OneApp Flutter应用完整技术架构设计和模块说明 +site_author: OneApp Team + +# 静态部署优化 +use_directory_urls: false + +# Material主题配置 +theme: + name: material + language: zh + palette: + - scheme: default # 浅色模式 + - scheme: slate # 深色模式 + +# 增强的Markdown扩展 +markdown_extensions: + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + - tables + - toc: + permalink: true + - nl2br + - sane_lists + # ... 更多扩展 +``` + +### 自定义样式特点 +- GitHub风格的表格和代码块 +- 优化的Mermaid图表显示 +- 响应式设计 +- 深色模式支持 +- 打印样式优化 + +## 使用说明 + +### 构建命令 +```bash +# 清理构建 +python -m mkdocs build --clean + +# 开发服务器 +python -m mkdocs serve + +# 清理临时文件 +Remove-Item site -Recurse -Force +``` + +### 目录结构 +``` +oneapp_docs/ +├── mkdocs.yml # 主配置文件 +├── docs/ # 文档源文件目录 +├── site/ # 生成的静态站点 +├── assets/ # 自定义资源 +│ ├── css/extra.css # 自定义样式 +│ └── js/mermaid.js # Mermaid配置 +└── README.md # 项目说明 +``` + +## 潜在的进一步改进 + +### 1. Mermaid图表 +如果发现某些复杂图表渲染有问题，可以考虑： +- 分割复杂图表为多个简单图表 +- 使用图片替代复杂的Mermaid图表 +- 调整图表的配置参数 + +### 2. 表格显示 +对于超宽表格，可以考虑： +- 使用横向滚动 +- 分割大表格 +- 使用卡片式布局替代表格 + +### 3. 代码高亮 +可以添加更多编程语言的语法高亮支持： +```yaml +markdown_extensions: + - pymdownx.highlight: + use_pygments: true + pygments_lang_class: true +``` + +### 4. 搜索优化 +可以配置更高级的搜索功能： +```yaml +plugins: + - search: + lang: + - zh + - en + separator: '[\s\-\.]+' +``` + +## 总结 + +现在的配置已经实现了： +- ✅ 移除不必要的repository信息 +- ✅ 增强Markdown语法支持 +- ✅ 优化Mermaid图表渲染 +- ✅ GitHub风格的样式设计 +- ✅ 静态文件部署优化 + +生成的静态站点可以直接在任何Web服务器或本地浏览器中使用，提供了接近GitHub显示效果的文档浏览体验。 \ No newline at end of file diff --git a/OneApp架构设计文档.md b/OneApp架构设计文档.md new file mode 100644 index 0000000..09f9b53 --- /dev/null +++ b/OneApp架构设计文档.md @@ -0,0 +1,3772 @@ +# OneApp 架构设计文档 + +## App 知识 + +### 1. APK 解压内容分析 + +APK (Android Package) 是 Android 应用的安装包格式，本质上是一个压缩文件。通过解压 APK 可以了解应用的构成和结构。 + +#### APK 文件结构 + +| ![apk](./images/apk-image-1.png) | ![apk](./images/apk-image-2.png) | +| :------------------------------: | :------------------------------: | +| apk 文件1 | apk 文件2 | + +``` +app-debug.apk (解压后) +├── AndroidManifest.xml # 应用清单文件 (二进制格式) +├── classes.dex # Dalvik字节码文件 +├── classes2.dex # 额外的dex文件 (多dex应用) +├── resources.arsc # 编译后的资源文件 +├── assets/ # 静态资源目录 +│ ├── flutter_assets/ # Flutter资源文件 +│ │ ├── kernel_blob.bin # Dart代码编译产物 (Debug模式) +│ │ ├── isolate_snapshot_* # Dart代码快照 (Release模式) +│ │ ├── vm_snapshot_* # Dart VM快照 (Release模式) +│ │ ├── AssetManifest.json # 资源清单 +│ │ └── packages/ # 第三方包资源 +│ └── build.properties # 构建属性文件 +├── res/ # Android资源目录 +│ ├── drawable/ # 图片资源 +│ ├── layout/ # 布局文件 (二进制格式) +│ ├── values/ # 字符串、颜色等资源 +│ └── ... +├── lib/ # 本地库文件 +│ ├── arm64-v8a/ # 64位ARM架构库 +│ │ └── libflutter.so # Flutter引擎 +│ ├── armeabi-v7a/ # 32位ARM架构库 +│ └── x86_64/ # x86_64架构库 +├── META-INF/ # 签名和清单信息 +│ ├── MANIFEST.MF # 清单文件 +│ ├── CERT.SF # 签名文件 +│ └── CERT.RSA # 证书文件 +└── kotlin/ # Kotlin元数据 +``` + +#### 关键文件说明 + +- **classes.dex 文件** + + classes.dex 文件是 Dalvik Executable (DEX) 格式的文件，它包含了应用的 Java 或 Kotlin 代码，经过编译后用于 Android 虚拟机（Dalvik 或 ART）执行。 + + 在 Android 应用中，所有的 Java 或 Kotlin 类都会被编译成 .dex 文件，这些文件在应用运行时被加载并执行。你看到的多个 classes.dex 文件（如 classes2.dex, classes3.dex）表示这应用程序被分成了多个 DEX 文件（通常是因为 APK 文件的大小超过了单个 DEX 文件的限制，使用多重 DEX 来进行分割）。 + +- **assets/ 文件夹** + + 这个文件夹包含了 APK 内的 静态资源文件。这些资源不参与编译，可以直接在应用运行时被访问和加载。常见的文件包括图像、字体、JSON 文件等。 + + 例如，assets 中的资源可以在应用中通过 AssetManager 被访问。 + +- **lib/ 文件夹** + + 这个文件夹包含了应用的 原生代码库，即用 C 或 C++ 等编写的本地代码（通常是 .so 文件）。这些库通常用于实现一些高性能的功能或者和硬件交互等。 + + 例如，lib/ 文件夹中可能会包含适用于不同平台（如 x86、ARM 等架构）的 .so 文件。 + +- **META-INF/ 文件夹** + + 这个文件夹包含了 APK 的元数据，通常用于签名验证和应用的完整性验证。 + + 里面的 MANIFEST.MF、CERT.RSA、CERT.SF 等文件用于存储签名证书以及验证应用完整性所需的数据，确保 APK 文件没有被篡改。 + +- **res/ 文件夹** + 这个文件夹包含了应用的 资源文件，这些资源是应用 UI、布局、图像、字符串等的一部分。 + + res/ 文件夹通常包含子文件夹，如 drawable/（图片资源）、layout/（布局文件）、values/（定义字符串、尺寸等的 XML 文件）等。 + +- **AndroidManifest.xml** + + 这个文件是 Android 应用的 清单文件，用于声明应用的基本信息，如包名、权限、组件（如 Activity、Service、BroadcastReceiver）等。 + + AndroidManifest.xml 还包括了其他配置信息，如应用的主题、启动模式等。 + +- **.properties 文件** + + .properties 文件通常用于存储应用的配置信息，如库的版本、路径配置等。 + + 例如，HMSCore-base.properties、play-services-location.properties 等文件是与特定 SDK 或服务（如 HMS 或 Google Play 服务）相关的配置文件，通常在编译时用来设置 SDK 的特性、版本号等。 + +- **resources.arsc** + + 这个文件是 资源表文件，用于存储应用中所有的 静态资源（如字符串、颜色、尺寸等）。 + + 它是二进制格式，用于加速资源加载。Android 系统通过 resources.arsc 来索引和加载资源，而不需要直接读取 XML 文件。 + + +**核心执行文件** +- `classes.dex`: 编译后的Java/Kotlin字节码，运行在Dalvik/ART虚拟机上 +- `AndroidManifest.xml`: 应用配置清单，定义组件、权限、版本等信息 +- `resources.arsc`: 编译后的XML资源和字符串资源 + +**Flutter相关文件** +- `flutter_assets/kernel_blob.bin`: Debug模式下的Dart代码内核表示 +- `flutter_assets/isolate_snapshot_*`: Release模式下的AOT编译快照 +- `lib/*/libflutter.so`: Flutter引擎的原生库 + +**资源文件** +- `assets/`: 原始资源文件，运行时可直接访问 +- `res/`: Android标准资源，会被编译和优化 + +**安全验证** +- `META-INF/`: APK签名相关文件，确保应用完整性和来源可信 + +#### OneApp项目中的体现 + +在OneApp的构建产物中，我们可以发现： + +```properties +# build.properties 示例 +iid=6363 +sid=3138351 +bid=982334 +version=12.10.0.10010731 +time=2024-05-08 19:02:58 +FEATURE_LOCATION=1 +FEATURE_ROUTE_OVERLAY=1 +FEATURE_MVT=1 +FEATURE_3DTiles=1 +FEATURE_GLTF=1 +``` + +这个文件记录了构建信息和功能特性开关，体现了OneApp的多功能特性管理。 + +### 2. Android App 架构模式 + +#### 传统Android应用架构 + +```mermaid +graph TB + A[Activity/Fragment] --> B[Service] + A --> C[BroadcastReceiver] + A --> D[ContentProvider] + B --> E[SQLite Database] + A --> F[SharedPreferences] + A --> G[Files/Assets] +``` + +#### 现代Android架构 (MVVM) + +```mermaid +graph TB + A[View - Activity/Fragment] --> B[ViewModel] + B --> C[Repository] + C --> D[Local Data Source] + C --> E[Remote Data Source] + D --> F[Room Database] + D --> G[SharedPreferences] + E --> H[Retrofit/OkHttp] + + B -.->|LiveData/StateFlow| A + A -.->|User Actions| B +``` + +#### Flutter混合架构 + +对于OneApp这样的Flutter应用，架构更为复杂： + +```mermaid +graph TB + subgraph "Flutter Layer" + A[Flutter UI] --> B[Dart Business Logic] + B --> C[Platform Channel] + end + + subgraph "Native Layer" + C --> D[Android Activity] + D --> E[Native Services] + E --> F[System APIs] + end + + subgraph "Data Layer" + B --> G[Local Storage] + B --> H[Network APIs] + E --> I[Native Storage] + end +``` + +**架构层次说明** + +1. **展示层 (Presentation Layer)** + - Flutter Widget树 + - 用户界面渲染 + - 用户交互处理 + +2. **业务逻辑层 (Business Logic Layer)** + - Dart业务代码 + - 状态管理 (Provider/Bloc) + - 路由管理 + +3. **平台适配层 (Platform Layer)** + - Platform Channel通信 + - 原生功能调用 + - 平台特性适配 + +4. **数据服务层 (Data Service Layer)** + - 网络请求 + - 本地存储 + - 缓存管理 + +5. **原生系统层 (Native System Layer)** + - Android系统API + - 硬件设备访问 + - 系统服务调用 + +### Android 插件的合并与加载机制 + +1. 插件与 Flutter 应用的集成 + + 当我们把一个插件集成到 Flutter 项目时，首先需要了解两个主要部分： + + Flutter 插件的 Android 部分：通常包含 `src/main/java` 或 `src/main/kotlin` 目录下的原生代码。 + + Flutter 项目的 Android 部分：即你创建的 Flutter 项目的 `android/` 目录。 + +2. 插件的打包 + + Flutter 插件包含了原生代码（Android 部分通常是 Java 或 Kotlin），这些原生代码被打包成 .aar 文件。AAR 是 Android 的类库包，包含了插件的 Java 或 Kotlin 代码、资源文件和配置等。 + + 在 Flutter 项目中，插件的 .aar 文件通过 Flutter 的依赖管理系统（通常是 pubspec.yaml 文件）进行声明，类似于其他 Dart 包。Flutter 会在编译时把这些原生代码一起编译进最终的 Android APK 或 AAB 文件中。它们的编译产出（.class 文件）合并到主工程的 DEX 文件中。 + + 将它们的 AndroidManifest.xml 内容合并到主工程的 AndroidManifest.xml 中。这就是为什么插件声明的权限和组件会在最终 App 中生效。 + + +3. 插件的集成 + + 依赖声明：在 `pubspec.yaml` 文件中声明插件的依赖： + ```yaml + dependencies: + flutter: + sdk: flutter + flutter_plugin: ^1.0.0 + ``` + + Gradle 构建过程：当你编译 Flutter 项目时，Gradle 会自动下载 Flutter 插件，并把 .aar 文件（插件的原生部分）合并到应用的 build.gradle 配置中： + + 在 android/app/build.gradle 中，Flutter 插件的原生代码被集成到 dependencies 块中： + ```gradle + dependencies { + implementation project(":flutter_plugin") + } + + + plugins { + id "dev.flutter.flutter-gradle-plugin" + } + + ``` + 在`setting.gradle`里面也可以批量的去依赖Flutter项目的全部依赖 + ```gradle + pluginManagement { + def flutterSdkPath = { + def properties = new Properties() + file("local.properties").withInputStream { properties.load(it) } + def flutterSdkPath = properties.getProperty("flutter.sdk") + assert flutterSdkPath != null, "flutter.sdk not set in local.properties" + return flutterSdkPath + }() + + includeBuild("$flutterSdkPath/packages/flutter_tools/gradle") + + repositories { + google() + mavenCentral() + gradlePluginPortal() + } + } + + plugins { + id "dev.flutter.flutter-plugin-loader" version "1.0.0" // apply true + id "com.android.application" version "{agpVersion}" apply false + id "org.jetbrains.kotlin.android" version "{kotlinVersion}" apply false + } + + include ":app" + ``` + Flutter Gradle 插件的命令式应用已弃用 + + [Deprecated imperative apply of Flutter's Gradle plugins](https://docs.flutter.cn/release/breaking-changes/flutter-gradle-plugin-apply) + +4. 插件加载与启动过程 + + 在 应用启动时，Flutter 会通过 `FlutterEngine` 启动，并将原生代码的插件加载到引擎中。 + 当应用启动时，Flutter 插件会在启动过程中被动态加载。 + 在构建过程中，所有插件的 .aar 文件都会被合并到最终的 APK 中。当应用启动时，Flutter 引擎会加载这些 .aar 文件并通过 MethodChannel 进行通信。 + + ```java + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + FlutterEngine flutterEngine = new FlutterEngine(this); + GeneratedPluginRegistrant.registerWith(flutterEngine); + setContentView( + FlutterActivity.createDefaultIntent(this) + ); + } + ``` + 现在的项目都是继承于`FlutterActivity`，自动完成了插件的注册 + +5. 方法调用与通信机制 + + Flutter 应用和 Android 插件之间的通信是通过 `MethodChannel` 或 `EventChannel` 完成的。 + + `MethodChannel`：用于异步方法调用。 + 插件原生代码通过 MethodChannel 向 Dart 层发送数据。 + Dart 层通过 MethodChannel 发起原生方法调用。 + + `EventChannel`：用于数据流式传输，通常用于原生代码向 Flutter 层推送事件。 + +## Flutter知识 + +### 1. Flutter 架构概览 + +Flutter 是 Google 开发的跨平台 UI 工具包，采用自绘制引擎，实现了"一套代码，多端运行"的目标。它被设计为一个可扩展的分层系统，各个独立的组件系列合集，上层组件各自依赖下层组件。 + +> 参考：[Flutter架构概览官方文档](https://docs.flutter.cn/resources/architectural-overview) + +#### Flutter 架构 + +Flutter 采用分层架构设计，从上到下分为 Framework 层、Engine 层和 Platform 层： + +![Flutter架构图](./images/flutter-archdiagram.png) + +```mermaid +graph TB + subgraph "Dart App" + A[业务逻辑
Business Logic] + end + + subgraph "Framework (Dart)" + B[Material/Cupertino
设计语言实现] + C[Widgets
组合抽象] + D[Rendering
渲染层] + E[Foundation
基础库] + end + + subgraph "Engine (C++)" + F[Dart Runtime
Dart虚拟机] + G[Skia/Impeller
图形引擎] + H[Text Layout
文本排版] + I[Platform Channels
平台通道] + end + + subgraph "Platform" + J[Android/iOS/Web/Desktop
目标平台] + end + + A --> B + B --> C + C --> D + D --> E + E --> F + F --> G + F --> H + F --> I + I --> J +``` + +**架构层次详解** + +| 架构层 | 主要职责 | 核心组件 | 关键特点 | +|--------|----------|----------|----------| +| **Framework层** | 提供上层API封装 | Material、Widgets、Rendering、Foundation | Dart语言实现，响应式编程 | +| **Engine层** | 底层渲染和运行时支持 | Dart Runtime、图形引擎、文本布局 | C++实现，高性能渲染 | +| **Platform层** | 与底层操作系统交互 | 嵌入层、系统API | 平台特定实现 | + +#### Flutter 应用架构 + +基于官方推荐的 MVVM 架构模式，Flutter 应用采用关注点分离原则，分为 UI 层和数据层。 + +> 参考：[Flutter应用架构指南](https://docs.flutter.cn/app-architecture/guide) + +![MVVM架构模式](https://docs.flutter.cn/assets/images/docs/app-architecture/guide/mvvm-intro-with-layers.png) + +**分层架构设计** + +```mermaid +graph TB + subgraph "UI Layer 用户界面层" + A[View
视图组件] + B[ViewModel
视图模型] + end + + subgraph "Domain Layer 领域层 (可选)" + E[Use Cases
业务用例] + F[Domain Models
领域模型] + end + + subgraph "Data Layer 数据层" + C[Repository
数据仓库] + D[Service
数据服务] + end + + A -.->|用户事件| B + B -.->|状态更新| A + B --> C + B --> E + E --> F + E --> C + C --> D +``` + +**完整的功能模块架构** + +![功能架构示例](./images/feature-architecture-example.png) + +**架构组件职责** + +| 组件层 | 主要职责 | 核心特点 | 示例 | +|--------|----------|----------|------| +| **View** | UI渲染和用户交互 | 无业务逻辑，接收ViewModel数据 | StatelessWidget页面 | +| **ViewModel** | 业务逻辑和状态管理 | 数据转换，状态维护，命令处理 | Bloc、Provider | +| **Repository** | 数据源管理 | 缓存策略，错误处理，数据转换 | UserRepository | +| **Service** | 外部数据源封装 | API调用，本地存储，平台服务 | ApiService | +| **Use Cases** | 复杂业务逻辑封装 | 跨Repository逻辑，可复用业务 | LoginUseCase | + +#### 推荐项目结构 + +基于官方最佳实践的项目文件组织方式： + +``` +lib/ +├── ui/ # UI层 - 用户界面 +│ ├── core/ # 核心UI组件 +│ │ ├── widgets/ # 通用Widget组件 +│ │ ├── themes/ # 主题配置 +│ │ └── extensions/ # UI扩展方法 +│ └── features/ # 功能模块 +│ ├── home/ # 首页功能 +│ │ ├── view_models/ # 视图模型 +│ │ │ └── home_view_model.dart +│ │ ├── views/ # 视图组件 +│ │ │ ├── home_screen.dart +│ │ │ └── widgets/ +│ │ └── models/ # UI状态模型 +│ ├── car_control/ # 车控功能 +│ └── profile/ # 个人中心 +├── domain/ # 领域层 - 业务逻辑 +│ ├── models/ # 领域模型 +│ │ ├── car.dart +│ │ └── user.dart +│ ├── use_cases/ # 业务用例 +│ │ ├── login_use_case.dart +│ │ └── car_control_use_case.dart +│ └── repositories/ # 仓库接口 +│ └── i_car_repository.dart +├── data/ # 数据层 - 数据访问 +│ ├── repositories/ # 仓库实现 +│ │ ├── car_repository_impl.dart +│ │ └── user_repository_impl.dart +│ ├── services/ # 数据服务 +│ │ ├── api/ # API服务 +│ │ │ ├── car_api_service.dart +│ │ │ └── auth_api_service.dart +│ │ ├── local/ # 本地存储 +│ │ │ └── cache_service.dart +│ │ └── platform/ # 平台服务 +│ │ └── bluetooth_service.dart +│ └── models/ # 数据传输对象 +│ ├── api/ # API模型 +│ └── local/ # 本地模型 +├── core/ # 核心基础设施 +│ ├── di/ # 依赖注入 +│ ├── network/ # 网络配置 +│ ├── storage/ # 存储配置 +│ ├── constants/ # 常量定义 +│ └── utils/ # 工具类 +├── config/ # 配置文件 +│ ├── app_config.dart +│ └── environment.dart +└── main.dart # 应用入口 +``` + +### 2. Flutter 工作原理 + +Flutter 的核心设计理念是"**一切皆Widget**"，通过积极的组合模式构建用户界面。为了支撑大量Widget的高效运行，Flutter采用了多层次的架构设计和优化算法。 + +#### 2.1 Flutter 三棵树架构 + +Flutter 使用三棵树来管理UI状态和渲染： + +```mermaid +graph TD + subgraph "Widget Tree (配置描述)" + W1[StatelessWidget] --> W2[Container] + W1 --> W3[Text] + W2 --> W4[Padding] + W4 --> W5[Image] + end + + subgraph "Element Tree (桥梁管理)" + E1[StatelessElement] --> E2[SingleChildRenderObjectElement] + E1 --> E3[LeafRenderObjectElement] + E2 --> E4[SingleChildRenderObjectElement] + E4 --> E5[LeafRenderObjectElement] + end + + subgraph "RenderObject Tree (渲染实现)" + R1[RenderBox] --> R2[RenderPadding] + R1 --> R3[RenderParagraph] + R2 --> R4[RenderImage] + end + + W1 -.->|创建| E1 + W2 -.->|创建| E2 + W3 -.->|创建| E3 + W4 -.->|创建| E4 + W5 -.->|创建| E5 + + E2 -.->|创建| R1 + E3 -.->|创建| R3 + E4 -.->|创建| R2 + E5 -.->|创建| R4 +``` + +**三棵树的职责分工** + +| 树类型 | 主要职责 | 生命周期 | 特点 | +| ----------------- | ---------------------------------- | ------------ | -------------- | +| **Widget Tree** | UI配置描述，定义界面应该是什么样子 | 每帧重建 | 不可变、轻量级 | +| **Element Tree** | Widget和RenderObject的桥梁 | 相对稳定 | 维护状态和关系 | +| **RenderObject** | 实际的布局、绘制和命中测试 | 长期存在 | 可变、性能关键 | + +#### 2.2 Widget 构建与更新流程 + +```mermaid +sequenceDiagram + participant User as 用户操作 + participant Widget as Widget Tree + participant Element as Element Tree + participant Render as RenderObject Tree + participant Engine as Flutter Engine + + User->>Widget: setState() 触发更新 + Widget->>Widget: build() 创建新Widget树 + Widget->>Element: 比较新旧Widget + + alt Widget相同 + Element->>Element: 复用现有Element + else Widget不同 + Element->>Element: 创建新Element + Element->>Render: 更新RenderObject + end + + Element->>Render: markNeedsLayout() + Render->>Render: layout() 布局计算 + Render->>Render: paint() 绘制操作 + Render->>Engine: 提交渲染数据 + Engine->>User: 显示更新后的UI +``` + +#### 2.3 布局系统 (Layout System) + +Flutter 采用**单遍布局算法**，确保每个RenderObject在布局过程中最多被访问两次。 + +```mermaid +graph TB + subgraph "布局约束传递 (Constraints Down)" + A[Parent RenderObject] -->|BoxConstraints| B[Child RenderObject] + B -->|BoxConstraints| C[Grandchild RenderObject] + end + + subgraph "尺寸信息回传 (Size Up)" + C -->|Size| B + B -->|Size| A + end + + subgraph "位置确定 (Position)" + A -->|Offset| B + B -->|Offset| C + end +``` + +#### 2.4 绘制系统 (Painting System) + +绘制系统负责将布局完成的RenderObject转换为实际的像素。 + +```mermaid +sequenceDiagram + participant RO as RenderObject + participant Layer as Layer Tree + participant Canvas as Canvas + participant Skia as Skia Engine + participant GPU as GPU + + RO->>RO: markNeedsPaint() + RO->>Layer: 创建绘制层 + RO->>Canvas: paint(Canvas, Offset) + Canvas->>Skia: 绘制命令 + Skia->>GPU: 光栅化 + GPU->>GPU: 合成显示 +``` + +#### 2.5 渲染管线 (Render Pipeline) + +Flutter的完整渲染管线包含四个主要阶段： + +```mermaid +graph LR + A[Build 构建] --> B[Layout 布局] + B --> C[Paint 绘制] + C --> D[Composite 合成] + + A1[Widget.build] --> A + B1[RenderObject.layout] --> B + C1[RenderObject.paint] --> C + D1[Layer.composite] --> D + + subgraph "优化策略" + E[只有脏节点参与] + F[次线性算法] + G[缓存复用] + H[GPU加速] + end + + E --> A + F --> B + G --> C + H --> D +``` + +**渲染管线优化** + +1. **构建阶段优化** + - 只重建标记为dirty的Widget + - Element复用机制 + - 构建缓存策略 + +2. **布局阶段优化** + - 单遍布局算法 + - 约束传播优化 + - 边界检测跳过 + +3. **绘制阶段优化** + - Layer层缓存 + - 重绘区域最小化 + - GPU合成加速 + +## Flutter 模块化 + +### 1. Flutter模块化基础理论 + +#### 模块化的必要性 + +随着Flutter应用规模的增长，单一代码库会面临以下挑战： + +```mermaid +graph TD + A[单体应用] --> B[代码耦合严重] + A --> C[构建时间过长] + A --> D[团队协作困难] + A --> E[测试复杂度高] + + F[模块化应用] --> G[职责分离] + F --> H[并行开发] + F --> I[独立测试] + F --> J[代码复用] +``` + +#### 模块化设计原则 + +1. **单一职责原则**: 每个模块只负责一个业务领域 +2. **开闭原则**: 对扩展开放，对修改封闭 +3. **依赖倒置**: 高层模块不依赖低层模块，都依赖抽象 +4. **接口隔离**: 客户端不依赖不需要的接口 + +#### Flutter模块化方案对比 + +| 方案 | 优点 | 缺点 | 适用场景 | +| -------------- | ---------------------- | ---------------------- | -------------- | +| Package方式 | 简单易用，依赖管理清晰 | 模块间通信复杂 | 工具库、UI组件 | +| Flutter Module | 支持混合开发 | 配置复杂，版本管理困难 | 原生应用集成 | +| Modular框架 | 完整的模块化解决方案 | 学习成本较高 | 大型应用 | + +### 2. Flutter Modular 框架介绍 + +Flutter Modular 是一个完整的模块化解决方案，提供了依赖注入、路由管理和模块解耦能力。 + +#### 核心概念 + +```dart +// 1. 模块定义 +class HomeModule extends Module { + @override + List get binds => [ + Bind.singleton((i) => HomeRepository()), + Bind.factory((i) => HomeBloc(i())), + ]; + + @override + List get routes => [ + ChildRoute('/', child: (context, args) => HomePage()), + ChildRoute('/detail', child: (context, args) => DetailPage()), + ]; +} + +// 2. 应用入口 +class AppModule extends Module { + @override + List get imports => [ + CoreModule(), + HomeModule(), + ]; +} + +// 3. 应用启动 +void main() { + runApp(ModularApp(module: AppModule(), child: AppWidget())); +} +``` + +#### 依赖注入机制 + +```mermaid +graph TB + A[ModularApp] --> B[Module Registration] + B --> C[Dependency Container] + C --> D[Singleton Binds] + C --> E[Factory Binds] + C --> F[Lazy Binds] + + G[Widget] --> H["Modular.get<T>()"] + H --> C +``` + +```dart +// 依赖注入使用示例 +class HomePage extends StatelessWidget { + @override + Widget build(BuildContext context) { + // 获取依赖注入的实例 + final bloc = Modular.get(); + final repository = Modular.get(); + + return Scaffold( + appBar: AppBar(title: Text('首页')), + body: BlocBuilder( + bloc: bloc, + builder: (context, state) { + return ListView.builder( + itemBuilder: (context, index) => ListTile( + title: Text(state.items[index].title), + onTap: () => Modular.to.pushNamed('/detail'), + ), + ); + }, + ), + ); + } +} +``` + +依赖注入也可以通过`Service`来完成某一些功能的实现 + +```dart +abstract class EmailService { + void sendEmail(String email, String title, String body); +} + +class XPTOEmailService implements EmailService { + + final XPTOEmail xpto; + XPTOEmailService(this.xpto); + + void sendEmail(String email, String title, String body) { + xpto.sendEmail(email, title, body); + } +} + +class Client { + + final EmailService service; + Client(this.service); + + void sendEmail(String email, String title, String body){ + service.sendEmail(email, title, body); + } +} +``` + +```dart +class AppModule extends Module { + // v5 写法 + @override + List get binds => [ + Bind.factory((i) => XPTOEmail()) + Bind.factory((i) => XPTOEmailService(i())) + Bind.singleton((i) => Client(i())) + ]; + // v6 写法 + @override + void binds(i) { + i.add(XPTOEmail.new); + i.add(XPTOEmailService.new); + i.addSingleton(Client.new); + + // Register with Key + i.addSingleton(Client.new, key: 'OtherClient'); + } +} +``` + +在模块中就可以获取到注入的service依赖 +```dart +final client = Modular.get(); +// or set a default value +final client = Modular.get(defaultValue: Client()); + +// or use tryGet +Client? client = Modular.tryGet(); + +// or get with key +Client client = Modular.get(key: 'OtherCLient'); + +client.sendEmail('email@xxx.com', 'title', 'email body') +``` + +#### 路由管理 + +```dart +// 路由定义 +class AppModule extends Module { + @override + List get routes => [ + ModuleRoute('/home', module: HomeModule()), + ModuleRoute('/user', module: UserModule()), + ModuleRoute('/car', module: CarModule()), + ]; +} + +// 路由导航 +class NavigationService { + static void toHome() => Modular.to.navigate('/home/'); + static void toProfile() => Modular.to.pushNamed('/user/profile'); + static void toCharging() => Modular.to.pushNamed('/car/charging'); +} +``` + +----- + +#### Flutter Modular 6.x.x + +Flutter Modular v5 和 v6 有一个变化，不过核心的概念不变 + +```dart +class AppModule extends Module { + + @override + List get imports => []; + + @override + void routes(RouteManager r) { + r.child('/', child: (context) => HomePage(title: 'Home Page')); + } + + @override + void binds(Injector i) { + } + + @override + void exportedBinds(Injector i) { + + } +} +``` + +### 3. Bloc 状态管理 + +`Flutter`的很多灵感来自于`React`，它的设计思想是数据与视图分离，由数据映射渲染视图。所以在Flutter中，它的Widget是`immutable`的，而它的动态部分全部放到了状态(`State`)中。 + +在项目越来越复杂之后，就需要一个状态管理库，实现高效地管理状态、处理依赖注入以及实现路由导航。 + +`BLoC（Business Logic Component`）是一种由 `Google` 推出的状态管理模式，最初为 `Angular` 框架设计，后被广泛应用于 `Flutter` 开发中。其核心思想是将业务逻辑与 UI 界面分离，通过流（Stream）实现单向数据流，使得状态变化可预测且易于测试。 + + +- `Bloc`模式：该模式划分四层结构 + + - bloc：逻辑层 + - state：数据层 + - event：所有的交互事件 + - view：页面 + +- `Cubit`模式：该模式划分了三层结构 + + - cubit：逻辑层 + - state：数据层 + - view：页面 + +#### Bloc架构模式 + +![bloc_architecture](./images/bloc_architecture_full.webp) + +![cubit_architecture](./images/cubit_architecture_full.webp) + +![bloc_system](./images/Bloc-1.webp) + +```mermaid +graph LR + A[UI Event] --> B[Bloc] + B --> C[Repository] + C --> D[Data Source] + D --> C + C --> B + B --> E[State] + E --> F[UI Update] +``` + +#### 在OneApp中的实现 + +基于OneApp项目中的实际代码，以远程空调控制为例展示Bloc模式的三层架构： + +##### 1. Event层 (所有的交互事件) + +Event定义了用户可以触发的所有事件类型，使用`freezed`注解生成不可变对象： + +```dart +/// 远程空调控制事件定义 +@freezed +class RemoteClimatisationControlEvent with _$RemoteClimatisationControlEvent { + /// 温度设置事件 + /// [temperature] 空调温度 + const factory RemoteClimatisationControlEvent.updateTemperatureSettingEvent({ + required double temperature, + }) = UpdateTemperatureSettingEvent; + + /// 解锁启动开关事件 + /// [climatizationAtUnlock] 解锁启动开关状态 + const factory RemoteClimatisationControlEvent.updateClimatizationAtUnlockEvent({ + required bool climatizationAtUnlock, + }) = UpdateClimatizationAtUnlockEvent; + + /// 执行空调动作事件 + /// [action] 执行ClimatizationAction动作的action + const factory RemoteClimatisationControlEvent.updateActionExecuteEvent({ + required ClimatizationAction action, + }) = UpdateActionExecuteEvent; + + /// 滑块值更新事件 + /// [sliderValue] 主要用来更新滑块的值 + const factory RemoteClimatisationControlEvent.updateSliderExecuteEvent({ + required double sliderValue, + }) = UpdateSliderExecuteEvent; + + /// 页面数据刷新事件 + /// 当前页面暂停了再次回来就执行这个方法,刷新一下页面 + const factory RemoteClimatisationControlEvent.updatePageDataEvent() = UpdatePageDataEventEvent; +} +``` + +##### 2. State层 (数据层) + +State包含了页面所需的所有状态数据，同样使用`freezed`确保不可变性： + +```dart +/// 远程空调控制状态定义 +@freezed +class RemoteClimatisationState with _$RemoteClimatisationState { + /// [climatization] 空调服务类 + /// [climatizationAtUnlock] 解锁启动开关 + /// [temperature] 空调温度 + /// [status] 空调状态 + /// [parameter] 空调模块参数 + /// [actionStart] 打开空调操作是否正在执行 + /// [actionStop] 关闭操作是否正在执行 + /// [actionSetting] 保存设置操作是否正在执行 + /// [updatePage] 更新页面,bool值取反 + /// [sliderValue] 空调滑动条的值 + const factory RemoteClimatisationState({ + required ClimatizationService climatization, // 空调服务实例 + required bool climatizationAtUnlock, // 解锁时自动启动开关 + required double temperature, // 当前设置温度 + ClimatisationStatus? status, // 空调运行状态 + ClimatizationParameter? parameter, // 空调参数配置 + bool? actionStart, // 启动操作进行中标志 + bool? actionStop, // 停止操作进行中标志 + bool? actionSetting, // 设置操作进行中标志 + bool? updatePage, // 页面更新标志 + double? sliderValue, // 温度滑块当前值 + }) = _RemoteClimatisationState; +} +``` + +##### 3. Bloc层 (逻辑层) + +Bloc负责处理事件并更新状态，包含业务逻辑和与外部服务的交互： + +```dart +/// 远程空调控制业务逻辑层 +class RemoteClimatisationControlBloc extends Bloc { + + RemoteClimatisationControlBloc( + ClimatizationService climatization, + double temperature, + bool climatizationAtUnlock, + String? noticeVin, + BuildContext? context, + ) : super( + RemoteClimatisationState( + climatization: climatization, + temperature: temperature, + climatizationAtUnlock: climatizationAtUnlock, + ), + ) { + // 注册事件处理器 + on(_onUpdateTemperatureSetting); + on(_onUpdateClimatizationAtUnlockEvent); + on(_onUpdateActionExecuteEvent); + on(_onUpdateSliderExecuteEvent); + on(_onUpdatePageDataEventEvent); + + // 初始化状态 + _initializeState(climatization); + + // 订阅空调服务变化 + _subscribeToClimatizationService(climatization); + } + + /// 处理温度设置事件 + FutureOr _onUpdateTemperatureSetting( + UpdateTemperatureSettingEvent event, + Emitter emit, + ) { + CarAppLog.i('更新温度设置: ${event.temperature}'); + + if (state.climatization.isParameterReady) { + // 更新空调设置参数 + final ClimatizationSetting setting = state.parameter!.setting.copyWith( + targetTemperatureC: event.temperature, + unitInCar: 'celsius', + ); + + // 更新RPC参数 + final ClimatizationRpcParameter rpc = ClimatizationRpcParameter(); + rpc.targetTemperature = event.temperature; + rpc.targetTemperatureUnit = 'celsius'; + + final ClimatizationParameter parameter = ClimatizationParameter(); + parameter.setting = setting; + parameter.rpc = rpc; + parameter.timer = state.parameter!.timer; + + // 更新服务参数 + state.climatization.parameter = parameter; + + emit(state.copyWith( + parameter: parameter, + temperature: event.temperature, + )); + } else { + emit(state.copyWith(temperature: event.temperature)); + } + } + + /// 处理解锁启动开关事件 + FutureOr _onUpdateClimatizationAtUnlockEvent( + UpdateClimatizationAtUnlockEvent event, + Emitter emit, + ) { + CarAppLog.i('更新解锁启动开关: ${event.climatizationAtUnlock}'); + + if (state.climatization.isParameterReady) { + final ClimatizationSetting setting = state.parameter!.setting + .copyWith(climatizationAtUnlock: event.climatizationAtUnlock); + + final ClimatizationParameter parameter = + state.climatization.parameter as ClimatizationParameter; + parameter.setting = setting; + state.climatization.parameter = parameter; + + emit(state.copyWith( + parameter: parameter, + climatizationAtUnlock: event.climatizationAtUnlock, + )); + } else { + emit(state.copyWith(climatizationAtUnlock: event.climatizationAtUnlock)); + } + } + + /// 处理空调动作执行事件 + FutureOr _onUpdateActionExecuteEvent( + UpdateActionExecuteEvent event, + Emitter emit, + ) { + CarAppLog.i('执行空调动作: ${event.action}'); + + // 根据不同动作更新对应的执行状态 + if (ClimatizationAction.stop == event.action) { + emit(state.copyWith(actionStop: true)); + } else if (ClimatizationAction.start == event.action) { + emit(state.copyWith(actionStart: true)); + } else if (ClimatizationAction.setting == event.action) { + emit(state.copyWith(actionSetting: true)); + } + } + + /// 订阅空调服务状态变化 + void _subscribeToClimatizationService(ClimatizationService climatization) { + client = Vehicle.addServiceObserver( + ServiceType.remoteChimatization, + (UpdateEvent event, ConnectorAction action, dynamic value) { + CarAppLog.i('空调服务状态变化: $event'); + + if (event == UpdateEvent.onStatusChange) { + // 空调状态变化 + emit(state.copyWith(status: value as ClimatisationStatus)); + } else if (event == UpdateEvent.onSettingChange) { + // 空调设置变化 + if (climatization.parameter.setting != null) { + final ClimatizationSetting setting = + climatization.parameter.setting as ClimatizationSetting; + emit(state.copyWith( + parameter: value as ClimatizationParameter, + temperature: setting.targetTemperatureC ?? 0, + climatizationAtUnlock: setting.climatizationAtUnlock ?? false, + )); + } + } else if (event == UpdateEvent.onActionStatusChange) { + // 动作执行状态变化 + final ServiceAction serviceAction = value as ServiceAction; + _handleActionStatusChange(serviceAction, action); + } + }, + ); + } +} +``` + +##### 4. UI中使用Bloc + +```dart +class ClimatizationControlPage extends StatelessWidget { + @override + Widget build(BuildContext context) { + return BlocBuilder( + builder: (context, state) { + return Scaffold( + appBar: AppBar(title: Text('远程空调控制')), + body: Column( + children: [ + // 温度显示和控制 + Text('当前温度: ${state.temperature.toInt()}°C'), + + // 温度滑块 + Slider( + value: state.sliderValue ?? state.temperature, + min: 16.0, + max: 32.0, + onChanged: (value) { + context.read().add( + RemoteClimatisationControlEvent.updateSliderExecuteEvent( + sliderValue: value, + ), + ); + }, + ), + + // 解锁启动开关 + SwitchListTile( + title: Text('解锁时自动启动'), + value: state.climatizationAtUnlock, + onChanged: (value) { + context.read().add( + RemoteClimatisationControlEvent.updateClimatizationAtUnlockEvent( + climatizationAtUnlock: value, + ), + ); + }, + ), + + // 控制按钮 + Row( + mainAxisAlignment: MainAxisAlignment.spaceEvenly, + children: [ + ElevatedButton( + onPressed: state.actionStart == true ? null : () { + context.read().add( + RemoteClimatisationControlEvent.updateActionExecuteEvent( + action: ClimatizationAction.start, + ), + ); + }, + child: state.actionStart == true + ? CircularProgressIndicator() + : Text('启动空调'), + ), + ElevatedButton( + onPressed: state.actionStop == true ? null : () { + context.read().add( + RemoteClimatisationControlEvent.updateActionExecuteEvent( + action: ClimatizationAction.stop, + ), + ); + }, + child: state.actionStop == true + ? CircularProgressIndicator() + : Text('关闭空调'), + ), + ], + ), + ], + ), + ); + }, + ); + } +} +``` + +**Bloc模式三层架构优势**： + +1. **Event层**: 定义所有可能的用户交互，类型安全，易于测试 +2. **State层**: 集中管理页面状态，不可变设计保证状态一致性 +3. **Bloc层**: 封装业务逻辑，处理异步操作，与UI完全分离 + +### 4. OneApp中的模块化实践 + +#### 模块分层架构 + +```mermaid +graph TB + subgraph "应用层" + A[oneapp_main] + end + + subgraph "业务模块层" + B[oneapp_account] + C[oneapp_community] + D[oneapp_membership] + E[oneapp_setting] + end + + subgraph "功能模块层" + F[app_car] + G[app_charging] + H[app_order] + I[app_media] + end + + subgraph "服务层" + J[clr_charging] + K[clr_payment] + L[clr_order] + end + + subgraph "基础设施层" + M[basic_network] + N[basic_storage] + O[basic_logger] + P[ui_basic] + end + + A --> B + A --> C + A --> D + A --> E + + B --> F + C --> G + D --> H + E --> I + + F --> J + G --> K + H --> L + + J --> M + K --> N + L --> O + I --> P +``` + +#### 依赖管理策略 + +```yaml +# pubspec.yaml 中的依赖管理 +dependencies: + flutter: + sdk: flutter + + # 基础框架依赖 + basic_network: + path: ../oneapp_basic_utils/basic_network + basic_storage: + path: ../oneapp_basic_utils/basic_storage + basic_modular: + path: ../oneapp_basic_utils/basic_modular + + # 业务模块依赖 + app_car: + path: ../oneapp_app_car/app_car + app_charging: + path: ../oneapp_app_car/app_charging + + # UI组件依赖 + ui_basic: + path: ../oneapp_basic_uis/ui_basic + ui_business: + path: ../oneapp_basic_uis/ui_business + +dependency_overrides: + # 解决版本冲突的依赖覆盖 + meta: ^1.9.1 + collection: ^1.17.1 +``` + +#### 模块间通信机制 + +OneApp采用多种方式实现模块间通信，主要包括事件总线通信和依赖注入通信两种机制。 + +##### 1. 事件总线通信 (OneAppEventBus) + +基于发布-订阅模式的事件总线，支持匿名订阅和标识订阅两种方式： + +```dart +/// OneApp事件总线实现 +class OneAppEventBus extends Object { + static final _eventBus = EventBus(); + static final OneAppEventBus _instance = OneAppEventBus._internal(); + + // 控制器管理 + final Map> _eventControllers = {}; + final Map>> _anonymousSubscriptions = {}; + final Map>> _identifiedSubscriptions = {}; + + OneAppEventBus._internal(); + + /// 基础事件发布 + static void fireEvent(event) { + _eventBus.fire(event); + } + + /// 基础事件监听 + static StreamSubscription addListen( + void Function(T event)? onData, { + Function? onError, + void Function()? onDone, + bool? cancelOnError, + }) { + return _eventBus.on().listen(onData, + onError: onError, onDone: onDone, cancelOnError: cancelOnError); + } + + /// 高级事件订阅 - 支持匿名和标识订阅 + /// [eventType] 事件类型 + /// [onEvent] 事件处理回调 + /// [id] 可选的订阅标识，用于管理订阅生命周期 + static void on(String eventType, Function(dynamic event) onEvent, {String? id}) { + var controller = _instance._eventControllers.putIfAbsent( + eventType, + () => StreamController.broadcast(), + ); + + var subscription = controller.stream.listen(onEvent); + + if (id == null) { + // 匿名订阅 + _instance._anonymousSubscriptions + .putIfAbsent(eventType, () => []) + .add(subscription); + } else { + // 标识订阅 - 自动取消同ID的旧订阅 + var subscriptions = _instance._identifiedSubscriptions.putIfAbsent(eventType, () => {}); + subscriptions[id]?.cancel(); + subscriptions[id] = subscription; + } + } + + /// 事件发布 + /// [eventType] 事件类型 + /// [event] 事件数据 + static void fire(String eventType, dynamic event) { + _instance._eventControllers[eventType]?.add(event); + } + + /// 取消订阅 + /// [eventType] 事件类型 + /// [id] 可选的订阅标识 + static void cancel(String eventType, {String? id}) { + if (id == null) { + // 取消所有匿名订阅 + _instance._anonymousSubscriptions[eventType]?.forEach((sub) => sub.cancel()); + _instance._anonymousSubscriptions.remove(eventType); + + // 取消所有标识订阅 + _instance._identifiedSubscriptions[eventType]?.values.forEach((sub) => sub.cancel()); + _instance._identifiedSubscriptions.remove(eventType); + } else { + // 取消特定标识订阅 + _instance._identifiedSubscriptions[eventType]?[id]?.cancel(); + _instance._identifiedSubscriptions[eventType]?.remove(id); + } + + // 清理空控制器 + if ((_instance._anonymousSubscriptions[eventType]?.isEmpty ?? true) && + (_instance._identifiedSubscriptions[eventType]?.isEmpty ?? true)) { + _instance._eventControllers[eventType]?.close(); + _instance._eventControllers.remove(eventType); + } + } + + /// 取消所有订阅 + static void cancelAll() { + _instance._anonymousSubscriptions.forEach((eventType, subscriptions) { + for (var subscription in subscriptions) { + subscription.cancel(); + } + }); + _instance._anonymousSubscriptions.clear(); + + _instance._identifiedSubscriptions.forEach((eventType, subscriptions) { + for (var subscription in subscriptions.values) { + subscription.cancel(); + } + }); + _instance._identifiedSubscriptions.clear(); + + for (var controller in _instance._eventControllers.values) { + controller.close(); + } + _instance._eventControllers.clear(); + } +} +``` + +**事件总线使用示例**： + +```dart +// 1. 定义事件类型 +class VehicleStatusChangedEvent { + final String vin; + final VehicleStatus status; + VehicleStatusChangedEvent(this.vin, this.status); +} + +// 2. 发布事件 +class CarService { + void updateVehicleStatus(String vin, VehicleStatus status) { + // 更新车辆状态后发布事件 + OneAppEventBus.fire('vehicle_status_changed', + VehicleStatusChangedEvent(vin, status)); + } +} + +// 3. 订阅事件 +class HomePageBloc { + late StreamSubscription _statusSubscription; + + void init() { + // 匿名订阅方式 + _statusSubscription = OneAppEventBus.addListen( + (event) { + // 处理车辆状态变化 + emit(state.copyWith(vehicleStatus: event.status)); + }, + ); + + // 标识订阅方式 + OneAppEventBus.on('vehicle_status_changed', (event) { + if (event is VehicleStatusChangedEvent) { + emit(state.copyWith(vehicleStatus: event.status)); + } + }, id: 'home_page_bloc'); + } + + @override + Future close() { + _statusSubscription.cancel(); + OneAppEventBus.cancel('vehicle_status_changed', id: 'home_page_bloc'); + return super.close(); + } +} +``` + +##### 2. 依赖注入通信 (Modular) + +通过Modular的依赖注入系统实现模块间服务共享和Bloc对象通信： + +```dart +/// 应用主模块 - 模块注册和依赖管理 +class AppModule extends Module { + @override + List get imports => [ + AccountModule(), // 账户模块 + CarControlModule(), // 车控模块 + SettingModule(), // 设置模块 + AppChargingModule(), // 充电模块 + AppOrderModule(), // 订单模块 + MembershipModule(), // 会员模块 + CommunityModule(), // 社区模块 + // ... 更多业务模块 + ]; + + @override + List> get binds => [ + $AppBloc, // 应用级别的Bloc + ]; + + @override + List get routes { + // 路由配置，支持路由守卫 + final List carList = [const _StatisticsGuard(), LogInGuard._routeGuard]; + + return [ + ModuleRoute('/account', module: AccountModule(), guards: [const _StatisticsGuard()]), + ModuleRoute('/car', module: CarControlModule(), guards: carList), + ModuleRoute('/charging', module: AppChargingModule(), guards: carList), + // ... 更多路由配置 + ]; + } +} +``` + +**业务模块依赖注入实现**： + +```dart +/// 账户模块 - 展示完整的依赖注入配置 +class AccountModule extends Module with RouteObjProvider, AppLifeCycleListener { + @override + List get imports => [AccountConModule()]; // 导入底层账户连接模块 + + @override + List> get binds => [ + // 业务逻辑Bloc注册 + $PhoneSignInBloc, // 手机号登录控制器 + $VerificationCodeInputBloc, // 验证码输入控制器 + $AgreementBloc, // 协议页控制器 + $GarageBloc, // 车库页控制器 + $VehicleInfoBloc, // 车辆信息页控制器 + + // 对外暴露的单例服务 + Bind( + (i) => PersonalCenterBloc( + i(), // 注入认证服务接口 + i(), // 注入用户资料服务接口 + i(), // 注入车库服务接口 + ), + export: true, // 导出给其他模块使用 + isSingleton: false, // 非单例模式 + ), + + // 更多业务Bloc... + $VehicleAuthBloc, + $AuthNewUserBloc, + $QrHuConfirmBloc, + $PlateNoEditBloc, + $UpdatePhoneBloc, + $CancelAccountBloc, + ]; +} +``` + +**跨模块Bloc通信示例**： + +```dart +/// 首页Bloc - 需要使用账户模块的服务 +class HomePageBloc extends Bloc { + final PersonalCenterBloc _personalCenterBloc; + late StreamSubscription _personalCenterSubscription; + + HomePageBloc() : super(HomeInitial()) { + // 通过依赖注入获取其他模块的Bloc + _personalCenterBloc = Modular.get(); + + // 订阅其他模块Bloc的状态变化 + _personalCenterSubscription = _personalCenterBloc.stream.listen((state) { + if (state is PersonalCenterLoaded) { + // 响应个人中心状态变化，更新首页状态 + add(UpdateUserInfo(state.userProfile)); + } + }); + + on(_onUpdateUserInfo); + } + + Future _onUpdateUserInfo(UpdateUserInfo event, Emitter emit) async { + emit(state.copyWith(userProfile: event.userProfile)); + } + + @override + Future close() { + _personalCenterSubscription.cancel(); + return super.close(); + } +} + +/// 充电模块调用账户模块服务 +class ChargingBloc extends Bloc { + ChargingBloc() : super(ChargingInitial()) { + on(_onStartCharging); + } + + Future _onStartCharging(StartCharging event, Emitter emit) async { + // 通过依赖注入获取账户认证服务 + final authFacade = Modular.get(); + + if (!authFacade.isLogin) { + emit(ChargingError('请先登录')); + return; + } + + // 获取用户信息进行充电 + final profileFacade = Modular.get(); + final userProfile = profileFacade.getUserProfileLocal(); + + // 执行充电逻辑... + emit(ChargingInProgress(event.stationId)); + } +} +``` + +**路由守卫实现模块间权限控制**： + +```dart +/// 登录守卫 - 保护需要登录的路由 +class LogInGuard extends RouteGuard { + factory LogInGuard() => _routeGuard; + LogInGuard._() : super(); + + static final LogInGuard _routeGuard = LogInGuard._(); + + @override + FutureOr canActivate(String path, ParallelRoute route) { + // 通过依赖注入获取认证服务 + final authFacade = Modular.get(); + return authFacade.isLogin; + } + + @override + FutureOr?> pos(ModularRoute route, dynamic data) async { + final authFacade = Modular.get(); + + if (authFacade.isLogin) { + return route as ParallelRoute; + } else { + // 未登录时跳转到登录页 + await Modular.to.pushNamed('/account/sign_in'); + return null; + } + } +} +``` + +**通信机制对比**： + +| 通信方式 | 适用场景 | 优点 | 缺点 | +|---------|----------|------|------| +| **OneAppEventBus** | 松耦合的事件通知、状态广播 | 解耦性强、支持一对多通信 | 类型安全性较弱、调试困难 | +| **依赖注入** | 服务共享、Bloc间直接通信 | 类型安全、IDE支持好 | 模块间耦合度较高 | + +这两种机制在OneApp中协同工作，事件总线用于广播式通知，依赖注入用于服务共享和直接通信，共同构建了灵活而高效的模块间通信体系。 + +## OneApp架构 + +### 1. OneApp架构概览 + +OneApp 是基于 Flutter 的车主服务应用，采用分层模块化架构，支持多业务场景和跨平台部署。 + +> 详细信息参考：[OneApp架构介绍](./main_app.md) + +#### 整体架构图 + +```mermaid +graph TB + subgraph "用户界面层 (UI Layer)" + A[首页] --> A1[车辆控制] + A --> A2[充电服务] + A --> A3[订单管理] + A --> A4[社区互动] + A --> A5[会员中心] + end + + subgraph "业务逻辑层 (Business Layer)" + B1[账户模块
oneapp_account] + B2[车辆模块
oneapp_app_car] + B3[社区模块
oneapp_community] + B4[会员模块
oneapp_membership] + B5[设置模块
oneapp_setting] + end + + subgraph "服务接入层 (Service Layer)" + C1[充电服务
clr_charging] + C2[支付服务
clr_payment] + C3[订单服务
clr_order] + C4[媒体服务
clr_media] + C5[地理服务
clr_geo] + end + + subgraph "基础设施层 (Infrastructure Layer)" + D1[网络通信
basic_network] + D2[本地存储
basic_storage] + D3[日志系统
basic_logger] + D4[UI组件
ui_basic] + D5[平台适配
basic_platform] + end + + subgraph "原生平台层 (Native Layer)" + E1[Android
Kotlin/Java] + E2[iOS
Swift/ObjC] + end + + A1 --> B1 + A1 --> B2 + A2 --> B2 + A3 --> B4 + A4 --> B3 + A5 --> B4 + + B1 --> C1 + B2 --> C1 + B2 --> C2 + B4 --> C3 + B3 --> C4 + B2 --> C5 + + C1 --> D1 + C2 --> D1 + C3 --> D2 + C4 --> D3 + C5 --> D4 + + D1 --> E1 + D2 --> E1 + D3 --> E2 + D4 --> E2 + D5 --> E1 + D5 --> E2 +``` + +### 2. 详细架构分析 + +#### 2.1 分层架构设计 + +基于OneApp项目的代码结构，展示各层的具体实现和职责划分： + +##### 用户界面层 (UI Layer) + +**主页面实现** - 基于 `HomePage` 的代码： + +```dart +/// OneApp 主页面 - 底部Tab导航架构 +class HomePage extends StatefulWidget with RouteObjProvider { + /// 构造器 + /// [initialBottomTabKey] 底部tab key, value = [HomeBottomTabKey] + /// [initialTopTabKey] 顶部tab key, value = [DiscoveryTabKey] + /// [argsData] 传入的参数数据 + HomePage({ + String? initialBottomTabKey, + String? initialTopTabKey, + Map? argsData, + Key? key, + }) : initialBottomTabIndex = HomeBottomTabKeyEx.createFrom(initialBottomTabKey).index, + initialTopTabKey = initialTopTabKey ?? '', + argsMap = argsData, + super(key: key); + + final int initialBottomTabIndex; + final String initialTopTabKey; + final Map? argsMap; + + @override + State createState() => _HomePageState(); +} + +class _HomePageState extends State with RouteAware { + final Map _pages = {}; + HomeBloc? _bloc; + late StreamSubscription? _createEvent; + late StreamSubscription? _mainPageIndexChangeEvent; + + @override + void initState() { + super.initState(); + Logger.i('HomePage initState...bottom index = ${widget.initialBottomTabIndex}'); + + // 初始化HomeBloc，注入依赖服务 + _bloc = HomeBloc( + widget.initialBottomTabIndex, + Modular.get(), // 车库服务 + Modular.get(), // 认证服务 + )..add(const HomeEvent.checkIfHasDefaultCar()); + + // 订阅社区模块事件 + _createEvent = OneAppEventBus.addListen((event) { + if (event.editType == UserCreationType.add) { + _bloc?.add(const HomeEvent.viewPagerChanged(index: 1)); + } + if (event.editType == UserCreationType.buyCar) { + _bloc?.add(const HomeEvent.viewPagerChanged(index: 2)); + } + // 更多事件处理... + }); + + // 订阅主页索引变化事件 + _mainPageIndexChangeEvent = OneAppEventBus.addListen((event) { + _bloc?.add(HomeEvent.viewPagerChanged(index: event.oneIndex)); + }); + } + + @override + Widget build(BuildContext context) => BlocProvider.value( + value: _bloc!, + child: LocaleConsumer( + builder: (BuildContext context) => BlocConsumer( + listener: (context, state) { + // 状态变化监听，控制页面跳转 + final bloc = BlocProvider.of(context); + final index = state.bottomTabIndex; + bloc.pageController.jumpToPage(index); + }, + builder: (context, state) { + return Scaffold( + body: PageView.builder( + controller: state.pageController, + itemCount: 5, // 底部Tab数量 + itemBuilder: (context, index) => _getPageWidget(context, index), + ), + bottomNavigationBar: _buildBottomNavigationBar(state), + ); + }, + ), + ), + ); + + /// 获取对应Tab的页面Widget + Widget _getPageWidget(BuildContext context, int index) { + final map = {'initialTabKey': widget.initialTopTabKey}; + final bottomTabValue = HomeBottomTabKey.values[index]; + + // 根据Tab类型返回对应页面 + var childWidget = bottomTabValue.getWidget(map, widget.argsMap, context); + return KeepAliveWrapper(child: childWidget); + } +} + +/// 底部Tab枚举及页面映射 +enum HomeBottomTabKey { + discovery, // 发现页 0 + community, // 社区页 1 + car, // 车辆控制页 2 + shop, // 商城页 3 + personalCenter, // 个人中心 4 +} + +extension HomeBottomTabKeyEx on HomeBottomTabKey { + /// 根据Tab返回对应的页面Widget + Widget getWidget(Map params, Map? argsMap, BuildContext context) { + switch (this) { + case HomeBottomTabKey.discovery: + return ComponentDiscoveryRecommendPage(); // 发现页推荐内容 + + case HomeBottomTabKey.car: + // 车辆控制页 - 支持通知栏参数传入 + String? noticeVin = argsMap?['vin'] as String?; + String? target = argsMap?['target'] as String?; + bool needExecuteCarLock = (argsMap?['needExecuteCarLock'] as String?) == 'true'; + + Logger.i('noticeVin: $noticeVin, target: $target, needExecuteCarLock: $needExecuteCarLock'); + return CarPageWrapper(target, noticeVin, needExecuteCarLock: needExecuteCarLock); + + case HomeBottomTabKey.community: + return CommunityTabPage(); // 社区功能页面 + + case HomeBottomTabKey.shop: + return BaseWebViewPage(url: AppUtils.getMallIndexUrl(), isShowAppBar: false); + + case HomeBottomTabKey.personalCenter: + return const PersonalCenterPage(); // 个人中心页面 + } + } +} +``` + +##### 业务逻辑层 (Business Layer) + +**主应用模块** - 基于 `AppModule` 的代码： + +```dart +/// OneApp 应用最顶层模块 - 统一管理所有业务模块 +class AppModule extends Module { + @override + List get imports => [ + // === 账户体系模块 === + AccountModule(), // 用户账户管理 + AccountConModule(), // 账户连接层服务 + + // === 车辆相关模块 === + CarControlModule(), // 车辆控制核心模块 + AppChargingModule(), // 充电服务模块 + ClrChargingModule(), // 充电连接层 + AppAvatarModule(), // 3D虚拟形象 + AppCarwatcherModule(), // 车辆监控 + ClrCarWatcherModule(), // 车辆监控连接层 + + // === 生活服务模块 === + AppOrderModule(), // 订单管理 + ClrOrderModule(), // 订单连接层 + AppTouchgoModule(), // Touch&Go服务 + ClrTouchgoModule(), // Touch&Go连接层 + AppWallboxModule(), // 家充桩管理 + ClrWallboxModule(), // 家充桩连接层 + + // === 内容社区模块 === + CommunityModule(), // 社区功能 + MembershipModule(), // 会员体系 + AfterSalesModule(), // 售后服务 + CarSalesModule(), // 汽车销售 + + // === 基础设施模块 === + SettingModule(), // 应用设置 + SettingConModule(), // 设置连接层 + GeoModule(), // 地理位置服务 + AppMessageModule(), // 消息服务 + ClrMessageModule(), // 消息连接层 + + // === 扩展功能模块 === + AppTtsModule(), // 语音播报 + AppNavigationModule(), // 导航服务 + AppVurModule(), // VUR功能 + AppRpaModule(), // RPA自动化 + CompanionModule(), // 伴侣应用 + TouchPointModule(), // 触点管理 + OneAppPopupModule(), // 弹窗管理 + + // === 开发测试模块 === + TestModule(), // 测试模块 + BasicUIModule(), // 基础UI组件 + ]; + + @override + List> get binds => [ + $AppBloc, // 应用级别状态管理 + ]; + + @override + List get routes { + // 路由元数据获取 - 通过RouteCenterAPI统一管理 + final home = RouteCenterAPI.routeMetaBy(HomeRouteExport.keyModule); + final account = RouteCenterAPI.routeMetaBy(AccountRouteExport.keyModule); + final car = RouteCenterAPI.routeMetaBy(CarControlRouteExport.keyModule); + final charging = RouteCenterAPI.routeMetaBy(AppChargingRouteExport.keyModule); + final community = RouteCenterAPI.routeMetaBy(CommuntiyRouteExport.keyModule); + // ... 更多路由元数据 + + // 路由守卫配置 + const basicGuards = [_StatisticsGuard()]; // 基础统计守卫 + final loginRequiredGuards = [const _StatisticsGuard(), LogInGuard._routeGuard]; // 需要登录的路由守卫 + + return [ + // 首页路由 - 无需登录 + ModuleRoute(home.path, module: HomeModule(), guards: basicGuards), + + // 账户相关路由 - 无需登录 + ModuleRoute(account.path, module: AccountModule(), guards: basicGuards), + + // 车辆控制路由 - 需要登录 + ModuleRoute(car.path, module: CarControlModule(), guards: loginRequiredGuards), + + // 充电服务路由 - 需要登录 + ModuleRoute(charging.path, module: AppChargingModule(), guards: loginRequiredGuards), + + // 社区功能路由 - 无需登录 + ModuleRoute(community.path, module: CommunityModule(), guards: basicGuards), + + // ... 更多模块路由配置 + ]; + } +} +``` + +**子模块实现** - 基于 `AccountModule` 的业务模块： + +```dart +/// 账户模块 - 展示完整的业务模块实现 +class AccountModule extends Module with RouteObjProvider, AppLifeCycleListener { + @override + List get imports => [ + AccountConModule(), // 导入底层连接服务模块 + ]; + + @override + void onNotify(String status) { + switch (status) { + case 'init': + Logger.d('AccountModule 初始化完成'); + _onAppInitial(); // 执行模块初始化逻辑 + break; + default: + Logger.d('AccountModule 收到通知: $status'); + } + } + + @override + List> get binds => [ + // === 业务逻辑控制器 === + $PhoneSignInBloc, // 手机号登录控制器 + $VerificationCodeInputBloc, // 验证码输入控制器 + $AgreementBloc, // 协议页控制器 + $GarageBloc, // 车库页控制器 + $VehicleInfoBloc, // 车辆信息控制器 + $VehicleAuthBloc, // 车辆授权控制器 + + // === 对外暴露的核心服务 === + Bind( + (i) => PersonalCenterBloc( + i(), // 注入认证服务接口 + i(), // 注入用户资料服务接口 + i(), // 注入车库服务接口 + ), + export: true, // 导出给其他模块使用 + isSingleton: false, // 非单例模式，每次获取创建新实例 + ), + + // === 更多业务控制器 === + $AuthNewUserBloc, // 新用户授权控制器 + $QrHuConfirmBloc, // 二维码确认控制器 + $PlateNoEditBloc, // 车牌号编辑控制器 + $UpdatePhoneBloc, // 更新手机号控制器 + $CancelAccountBloc, // 注销账号控制器 + ]; + + @override + List get routes { + // 通过RouteCenterAPI获取路由元数据 + final login = RouteCenterAPI.routeMetaBy(AccountRouteExport.keySignIn); + final verify = RouteCenterAPI.routeMetaBy(AccountRouteExport.keyVerifyCode); + final personal = RouteCenterAPI.routeMetaBy(AccountRouteExport.keyPersonalCenter); + final garage = RouteCenterAPI.routeMetaBy(AccountRouteExport.keyGarage); + final vehicleInfo = RouteCenterAPI.routeMetaBy(AccountRouteExport.keyVehicleInfo); + // ... 更多路由元数据 + + return [ + // 登录页面 + ChildRoute( + login.path, + child: (_, args) => login.provider(args).as(), + transition: TransitionType.fadeIn, + ), + + // 验证码页面 + ChildRoute( + verify.path, + child: (_, args) => verify.provider(args).as(), + ), + + // 个人中心页面 + ChildRoute( + personal.path, + child: (_, args) => personal.provider(args).as(), + ), + + // 车库页面 - 需要登录守卫保护 + ChildRoute( + garage.path, + child: (_, args) => garage.provider(args).as(), + guards: [AccountLoginGuard()], + ), + + // 车辆信息页面 + ChildRoute( + vehicleInfo.path, + child: (_, args) => vehicleInfo.provider(args).as(), + transition: TransitionType.noTransition, + ), + + // ... 更多子路由配置 + ]; + } + + /// 模块初始化逻辑 + void _onAppInitial() { + // 初始化二维码处理器 + QrCodeProcessor() + ..addHandler(qrTypeLoginHU, (code, additionalInfo) async { + // 处理车机登录二维码逻辑 + Logger.i('处理车机登录二维码: $code'); + // 具体处理逻辑... + }) + ..addHandler(qrTypeBindVehicle, (code, additionalInfo) async { + // 处理绑车二维码逻辑 + Logger.i('处理绑车二维码: $code'); + // 具体处理逻辑... + }); + + // 刷新车库信息 + final facade = Modular.get(); + if (facade.getUserProfileLocal().toOption().toNullable() != null) { + final garageFacade = Modular.get(); + garageFacade.refreshGarage(); + } + } +} +``` + +**轻量级模块实现** - 基于 `HomeModule` 的简单模块： + +```dart +/// 首页模块 - 展示轻量级模块实现 +class HomeModule extends Module with RouteObjProvider { + @override + List get binds => []; // 首页模块不需要额外的依赖绑定 + + @override + List get routes { + // 获取首页路由元数据 + final homeRoute = RouteCenterAPI.routeMetaBy(HomeRouteExport.keyHome); + + return [ + ChildRoute( + homeRoute.path, + child: (_, args) => homeRoute.provider(args).as(), + transition: TransitionType.noTransition, // 首页无过渡动画 + ), + ]; + } +} +``` + +##### 服务接入层 (Service Layer) + +OneApp的服务层通过抽象接口和具体实现分离，支持灵活的服务替换和测试。 + +**路由系统架构** - 基于 `RouteCenterAPI` 的统一路由管理： + +```dart +/// 车辆控制模块路由定义 - 基于 route_dp.dart 的代码 +/// 通过RouteKey接口统一管理路由路径 + +/// 远程空调主页路由 +class CarClimatisationHomepageKey implements RouteKey { + const CarClimatisationHomepageKey(); + + @override + String get routeKey => CarControlRouteExport.keyCarClimatisationHomepage; + + /// 获取实际路由路径 + String get routePath { + final List list = CarControlRouteExport().exportRoutes(); + return list[10].routePath; // 从路由导出列表中获取实际路径 + } +} + +/// 充电场景管理路由 +class CarChargingProfilesKey implements RouteKey { + const CarChargingProfilesKey(); + + @override + String get routeKey => CarControlRouteExport.keyCarChargingProfiles; + + String get routePath { + final List list = CarControlRouteExport().exportRoutes(); + return list[14].routePath; + } +} + +/// 车辆监控主页路由 +class CarWatcherHomePageRouteKey implements RouteKey { + @override + String get routeKey => 'app_carWatcher.carWatcher_home'; +} + +/// 充电地图首页路由 +class ChargingMapHomeRouteKey implements RouteKey { + @override + String get routeKey => 'app_charging.charging_map_home'; +} +``` + +**路由守卫系统** - 基于 `AppModule` 中的 `LogInGuard` 实现： + +```dart +/// 登录守卫 - 保护需要登录才能访问的路由 +class LogInGuard extends RouteGuard { + factory LogInGuard() => _routeGuard; + + LogInGuard._() : super(); + + static const String _tag = '[route LogInGuard]:'; + static final LogInGuard _routeGuard = LogInGuard._(); + + /// 前置路由信息 + ParallelRoute? preRoute; + + @override + FutureOr canActivate(String path, ParallelRoute route) { + // 通过依赖注入获取认证服务 + final authFacade = Modular.get(); + final isLogin = authFacade.isLogin; + + Logger.d('路由守卫检查登录状态: $path, isLogin: $isLogin', _tag); + return isLogin; + } + + @override + FutureOr pre(ModularRoute route) { + // 保存导航历史 + if (NavigatorProxy().navigateHistory.isNotEmpty) { + preRoute = NavigatorProxy().navigateHistory.last; + } + return super.pre(route); + } + + @override + FutureOr?> pos(ModularRoute route, dynamic data) async { + final authFacade = Modular.get(); + + if (authFacade.isLogin) { + return route as ParallelRoute; + } else { + Logger.d('用户未登录，跳转到登录页', _tag); + + // 跳转到登录页面，并传递回调参数 + await Modular.to.pushNamed( + '/account/sign_in', + arguments: { + 'callback': () { + // 登录成功后的回调处理 + Logger.d('登录成功，返回原页面', _tag); + if (preRoute != null) { + Modular.to.navigate(preRoute!.name); + } + } + }, + ); + return null; + } + } +} + +/// 统计守卫 - 记录页面访问统计 +class _StatisticsGuard implements RouteGuard { + const _StatisticsGuard(); + + static const String _tag = tagRoute; + + @override + FutureOr canActivate(String path, ParallelRoute route) => true; + + @override + FutureOr pre(ModularRoute route) => route; + + @override + FutureOr?> pos(ModularRoute route, ModularArguments data) async { + // 记录页面访问日志 + Logger.d('页面导航统计: ${route.name}', _tag); + Logger.d('导航参数: ${data.uri}', _tag); + + // 可以在这里添加埋点统计逻辑 + // AnalyticsService.trackPageView(route.name, data.data); + + return route as ParallelRoute?; + } + + @override + String? get redirectTo => null; +} +``` + +##### 基础设施层 (Infrastructure Layer) + +**事件总线基础设施** - 基于 `OneAppEventBus` 的实现： + +```dart +/// OneApp统一事件总线 - 支持模块间松耦合通信 +class OneAppEventBus extends Object { + static final _eventBus = EventBus(); // 基础事件总线 + static final OneAppEventBus _instance = OneAppEventBus._internal(); + + // 高级事件管理 + final Map> _eventControllers = {}; + final Map>> _anonymousSubscriptions = {}; + final Map>> _identifiedSubscriptions = {}; + + OneAppEventBus._internal(); + + /// 基础事件发布 - 适用于简单事件 + static void fireEvent(event) { + _eventBus.fire(event); + } + + /// 基础事件监听 - 类型安全的事件订阅 + static StreamSubscription addListen( + void Function(T event)? onData, { + Function? onError, + void Function()? onDone, + bool? cancelOnError, + }) { + return _eventBus.on().listen( + onData, + onError: onError, + onDone: onDone, + cancelOnError: cancelOnError, + ); + } + + /// 高级事件订阅 - 支持生命周期管理 + static void on(String eventType, Function(dynamic event) onEvent, {String? id}) { + var controller = _instance._eventControllers.putIfAbsent( + eventType, + () => StreamController.broadcast(), + ); + + var subscription = controller.stream.listen(onEvent); + + if (id == null) { + // 匿名订阅 - 需要手动管理生命周期 + _instance._anonymousSubscriptions + .putIfAbsent(eventType, () => []) + .add(subscription); + } else { + // 标识订阅 - 自动管理重复订阅 + var subscriptions = _instance._identifiedSubscriptions.putIfAbsent(eventType, () => {}); + subscriptions[id]?.cancel(); // 取消旧订阅 + subscriptions[id] = subscription; + } + } + + /// 事件发布 + static void fire(String eventType, dynamic event) { + _instance._eventControllers[eventType]?.add(event); + } + + /// 订阅管理 - 支持精确取消和批量取消 + static void cancel(String eventType, {String? id}) { + if (id == null) { + // 取消该事件类型的所有订阅 + _instance._anonymousSubscriptions[eventType]?.forEach((sub) => sub.cancel()); + _instance._anonymousSubscriptions.remove(eventType); + + _instance._identifiedSubscriptions[eventType]?.values.forEach((sub) => sub.cancel()); + _instance._identifiedSubscriptions.remove(eventType); + } else { + // 取消特定标识的订阅 + _instance._identifiedSubscriptions[eventType]?[id]?.cancel(); + _instance._identifiedSubscriptions[eventType]?.remove(id); + } + + // 清理空控制器 + if ((_instance._anonymousSubscriptions[eventType]?.isEmpty ?? true) && + (_instance._identifiedSubscriptions[eventType]?.isEmpty ?? true)) { + _instance._eventControllers[eventType]?.close(); + _instance._eventControllers.remove(eventType); + } + } +} +``` + +**依赖注入基础设施** - 基于 `Modular` 的服务管理： + +```dart +/// 依赖注入使用模式 - 展示OneApp中的实际使用方式 + +/// 1. 在HomePage中获取注入的服务 +class _HomePageState extends State { + @override + void initState() { + super.initState(); + + // 通过Modular获取注入的服务实例 + _bloc = HomeBloc( + widget.initialBottomTabIndex, + Modular.get(), // 车库服务 - 来自clr_account模块 + Modular.get(), // 认证服务 - 来自clr_account模块 + ); + } +} + +/// 2. 在业务逻辑中使用服务接口 +class PersonalCenterBloc extends Bloc { + final IAuthFacade _authFacade; + final IProfileFacade _profileFacade; + final IGarageFacade _garageFacade; + + PersonalCenterBloc( + this._authFacade, // 构造函数注入 + this._profileFacade, + this._garageFacade, + ) : super(PersonalCenterInitial()); + + /// 获取用户信息 + Future loadUserProfile() async { + if (!_authFacade.isLogin) { + emit(PersonalCenterError('用户未登录')); + return; + } + + try { + final profile = await _profileFacade.getUserProfile(); + final vehicles = await _garageFacade.getVehicleList(); + + emit(PersonalCenterLoaded( + userProfile: profile, + vehicles: vehicles, + )); + } catch (e) { + emit(PersonalCenterError(e.toString())); + } + } +} + +/// 3. 跨模块服务调用 +class HomeBloc extends Bloc { + final IGarageFacade _garageFacade; + final IAuthFacade _authFacade; + + HomeBloc(int initialIndex, this._garageFacade, this._authFacade) + : super(HomeState.initial(initialIndex)) { + + on((event, emit) async { + // 检查是否有默认车辆 + final defaultVehicle = _garageFacade.getDefaultVehicleLocal(); + final hasVehicle = defaultVehicle != null && defaultVehicle.vin.isNotEmpty; + + if (hasVehicle) { + emit(state.copyWith(hasDefaultVehicle: true)); + } else { + emit(state.copyWith(hasDefaultVehicle: false)); + } + }); + } +} +``` + +#### 2.2 模块依赖关系图 + +基于OneApp的模块结构，模块间的依赖关系如下： + +```mermaid +graph TB + subgraph "应用入口层" + MAIN[oneapp_main
AppModule] + end + + subgraph "页面模块层" + HOME[app_home
HomeModule] + DISC[app_discover
DiscoveryModule] + TEST[app_test
TestModule] + end + + subgraph "业务功能模块层" + ACC[oneapp_account
AccountModule] + COM[oneapp_community
CommunityModule] + MEM[oneapp_membership
MembershipModule] + SET[oneapp_setting
SettingModule] + CS[oneapp_car_sales
CarSalesModule] + AS[oneapp-after-sales
AfterSalesModule] + TP[oneapp-touch-point
TouchPointModule] + POPUP[OneAppPopupModule] + end + + subgraph "车辆功能模块群" + CAR[app_car
CarControlModule] + CHARGE[app_charging
AppChargingModule] + AVATAR[app_avatar
AppAvatarModule] + MAINT[app_maintenance
MaintenanceControlModule] + WATCH[app_carwatcher
AppCarwatcherModule] + TG[app_touchgo
AppTouchgoModule] + WB[app_wallbox
AppWallboxModule] + VUR[app_vur
AppVurModule] + RPA[app_rpa
AppRpaModule] + NAV[app_navigation
AppNavigationModule] + end + + subgraph "连接层服务模块群 (CLR)" + ACC_C[clr_account
AccountConModule] + CHARGE_C[clr_charging
ClrChargingModule] + ORDER_C[clr_order
ClrOrderModule] + SET_C[clr_setting
SettingConModule] + GEO_C[clr_geo
GeoModule] + MSG_C[clr_message
ClrMessageModule] + TG_C[clr_touchgo
ClrTouchgoModule] + WB_C[clr_wallbox
ClrWallboxModule] + WATCH_C[clr_carwatcher
ClrCarWatcherModule] + end + + subgraph "UI基础设施层" + UI_BASIC[ui_basic
BasicUIModule] + UI_PAY[ui_payment
PayModule] + end + + MAIN --> HOME + MAIN --> DISC + MAIN --> TEST + MAIN --> ACC + MAIN --> COM + MAIN --> MEM + MAIN --> CAR + MAIN --> CHARGE + MAIN --> AVATAR + + ACC --> ACC_C + CAR --> ACC_C + CHARGE --> CHARGE_C + CHARGE --> ACC_C + SET --> SET_C + CAR --> GEO_C + WATCH --> WATCH_C + TG --> TG_C + WB --> WB_C + + HOME --> ACC_C + HOME --> GEO_C + + UI_PAY --> UI_BASIC + COM --> UI_BASIC + MEM --> UI_BASIC +``` + +#### 2.3 技术栈选择 + +**前端技术栈** + +| 技术领域 | 选择方案 | 版本 | 作用 | +| ---------- | ------------------------ | ------------- | ------------ | +| 开发框架 | Flutter | 3.0+ | 跨平台UI框架 | +| 编程语言 | Dart | 3.0+ | 应用开发语言 | +| 状态管理 | Provider + Bloc | 6.0.5 + 8.1.2 | 状态管理方案 | +| 路由管理 | Flutter Modular | 5.0.3 | 模块化路由 | +| 网络请求 | Dio | 5.3.2 | HTTP客户端 | +| 本地存储 | Hive + SharedPreferences | 2.2.3 | 数据持久化 | +| 响应式编程 | RxDart | 0.27.7 | 流式数据处理 | + +**原生集成技术栈** + +| 平台 | 主要技术 | 关键插件 | +| ------- | ----------- | ------------------------------------------------------------------- | +| Android | Kotlin/Java | amap_flutter_location
flutter_ingeek_carkey
cariad_touch_go | +| iOS | Swift/ObjC | 高德地图SDK
车钥匙SDK
3D虚拟形象SDK | + +**第三方服务集成** + +| 服务类型 | 服务商 | SDK/插件 | +| -------- | ----------- | ----------------------------- | +| 地图导航 | 高德地图 | amap_flutter_* | +| 支付服务 | 微信/支付宝 | fluwx/kit_alipay | +| 推送服务 | 极光推送 | flutter_plugin_mtpush_private | +| 媒体播放 | 腾讯云 | superplayer_widget | +| 性能监控 | 腾讯Aegis | aegis_flutter_sdk | + +### 3. 核心功能实现分析 + +#### 3.1 应用启动流程 + +基于OneApp的启动代码，应用启动分为两个阶段的初始化：不依赖隐私合规的基础初始化和依赖隐私合规的完整初始化。 + +```mermaid +sequenceDiagram + participant User as 用户 + participant Main as main.dart + participant BasicInit as 基础初始化 + participant Privacy as 隐私检查 + participant FullInit as 完整初始化 + participant Module as 模块系统 + participant UI as 用户界面 + + User->>Main: 启动应用 + Main->>Main: WidgetsFlutterBinding.ensureInitialized() + Main->>BasicInit: _initBasicPartWithoutPrivacy() + BasicInit->>BasicInit: initStorage() 存储初始化 + BasicInit->>BasicInit: initLoggerModule() 日志初始化 + BasicInit->>BasicInit: initTheme() 主题初始化 + BasicInit->>BasicInit: initNetworkModule() 网络初始化 + BasicInit->>BasicInit: initModular() 路由初始化 + Main->>Privacy: wrapPrivacyCheck() + Privacy->>Privacy: 检查隐私政策同意状态 + Privacy->>Main: 用户已同意或完成同意 + Main->>FullInit: _initBasicPartWithPrivacy() + FullInit->>FullInit: initPushAndEventBus() 推送初始化 + FullInit->>FullInit: initVehicle() 车辆服务初始化 + FullInit->>FullInit: initModules() 业务模块初始化 + Main->>Module: ModularApp(module: AppModule())启动 + Module->>UI: 渲染主界面 + UI->>User: 显示应用首页 +``` + +**启动流程代码** - 基于 OneApp `main.dart`： + +```dart +/// OneApp 应用入口 - main.dart实现 +void main() { + // 捕获flutter异常处理，实际项目中启动主函数 + _realMain(); +} + +/// 应用启动流程 +Future _realMain() async { + // 1. Flutter框架绑定初始化 + WidgetsFlutterBinding.ensureInitialized(); + + // 2. 不依赖隐私合规的基础部分初始化 + await _initBasicPartWithoutPrivacy(); + + // 3. 隐私合规检查包装器，只有用户同意后才进行完整初始化 + await wrapPrivacyCheck(_initBasicPartWithPrivacy); + + // 4. 锁定屏幕方向为竖屏 + SystemChrome.setPreferredOrientations([DeviceOrientation.portraitUp]); + + // 5. 启动模块化应用，注入AppModule作为根模块 + runApp(ModularApp(module: AppModule(), child: const AppWidget())); +} + +/// 第一阶段：不依赖隐私合规的基础初始化 +Future _initBasicPartWithoutPrivacy() async { + // 全局模块状态管理初始化 + moduleStatusMgmt = newModuleStatusMgmt(); + + // 本地存储服务初始化 + await initStorage(); + + // 开发配置工具初始化（IP代理、后端环境配置） + await DeveloperConfigBoxUtil.init(); + + // 日志系统初始化 + await initLoggerModule(debuggable: debuggable); + Logger.i('开发配置初始化完成: environment = $environment, debuggable: $debuggable'); + + // 主题系统初始化 + await initTheme(); + + // 字体配置初始化 + initFont(); + + // 网络模块初始化 + await initNetworkModule(debuggable: !AppStoreVersion); + + // 资源下载模块初始化 + await initBasicResource(); + + // 国际化模块初始化 + await initIntl(); + + // 全局错误处理器初始化 + initErrorHandlers(); + + // 模块化路由和依赖注入容器初始化 + initModular(debug: debuggable); + + // WebView初始化 + initWebView(); + + // Deep Link处理器初始化 + await initUniLink(); + + // 系统UI配置（异步执行） + unawaited(_initSystemUI()); + + // === 路由配置逻辑 === + final signed = localPrivacySigned(); // 检查本地隐私协议签署状态 + final showAd = await SplashAdDataManager().shouldShowSplashAd(); // 检查开屏广告 + + if (signed) { + if (showAd) { + // 已签署协议且有广告：显示启动广告页 + Modular.setInitialRoute(RouteCenterAPI.getRoutePathBy(LaunchAdPageKey())); + } else { + // 已签署协议且无广告：直接进入首页 + Modular.setInitialRoute(RouteCenterAPI.getRoutePathBy(const HomeRouteKey())); + } + } else { + // 未签署协议：显示隐私政策页 + Modular.setInitialRoute('/app/app_privacy'); + } + + // Debug工具初始化（仅Debug/Profile模式） + initDebugTools(); + + // 添加路由监控 + NavigatorProxy().addObserver(AppRouteObserver().routeObserver); + + // 输出版本信息 + final packageInfo = await PackageInfo.fromPlatform(); + Logger.i(''' + ################################ + VersionName: ${packageInfo.version} + VersionCode: ${packageInfo.buildNumber} + ConnectivityVersion: $versionConnectivity + Integration: $integrationNum + ################################ + '''); +} + +/// 第二阶段：依赖隐私合规的完整初始化 +Future _initBasicPartWithPrivacy() async { + // Token管理器必须就绪 + await tokenMgmt.hasInitialized(); + + // 设置隐私检查完成标记 + await bs.globalBox.put('key_user_privacy_check', true); + + // 网络连接检查和推送初始化 + final connectivityResult = await Connectivity().checkConnectivity(); + if (connectivityResult != ConnectivityResult.none) { + await initPushAndEventBus(debuggable: debuggable); + } + + // 平台相关服务初始化 + await initPlatform(debug: debuggable); + + // 分享功能初始化 + await initBasicShare(); + + // 车辆服务初始化 + initVehicle(); + + // TTS和购物服务初始化 + initTtsShop(); + + // 3D虚拟形象服务初始化 + initAvatar(); + + // CLR伴侣服务初始化 + initClrCompanion(DeveloperConfigBoxUtil.getBaseUrlHost()); + + // 各个业务模块初始化 + initModules(); + + // 二维码处理器初始化 + initQrProcessor(); + + // 项目配置初始化（异步） + unawaited(initBasicConfig()); + + // 订单服务初始化 + initOrder(); + + // 环境配置初始化（需要在存储初始化后） + await initEnvironmentConfig(); + + // 腾讯Aegis监控SDK初始化 + await initAegisSDK(); + + // 腾讯云对象存储SDK初始化 + initCosFileManagerSDK(); + + // 用户行为埋点初始化 + UserBehaviorTrackManager().initDefaultInfo(); + + // 车钥匙SDK初始化 + initInGeekCarKeySDK(); + + // 超级播放器许可证设置 + SuperPlayerPlugin.setGlobalLicense(licenceURL, licenceKey); + + Logger.i('完整初始化流程完成'); +} +``` + +#### 3.2 模块化依赖注入实现 + +基于OneApp的AppModule实现，展示30+业务模块的完整依赖注入和路由配置： + +**AppModule实现** - OneApp主应用模块： + +```dart +/// OneApp 应用最顶层模块 - 管理30+个业务和基础服务模块 +class AppModule extends Module { + @override + List get imports => [ + // === 账户体系模块 === + AccountModule(), // 用户账户管理模块 + AccountConModule(), // 账户连接层服务模块 + + // === 车辆控制模块群 === + CarControlModule(), // 车辆控制核心模块 + AppChargingModule(), // 充电服务模块 + ClrChargingModule(), // 充电连接层服务 + AppAvatarModule(), // 3D虚拟形象模块 + AppCarwatcherModule(), // 车辆监控模块 + ClrCarWatcherModule(), // 车辆监控连接层 + AppTouchgoModule(), // TouchGo免密支付 + ClrTouchgoModule(), // TouchGo连接层 + AppWallboxModule(), // 家充桩管理 + ClrWallboxModule(), // 家充桩连接层 + MaintenanceControlModule(), // 保养维护模块 + AppVurModule(), // 车辆升级记录 + CarVurModule(), // 车辆升级连接层 + AppRpaModule(), // RPA自动化 + CarRpaModule(), // RPA连接层 + + // === 基础功能模块 === + DiscoveryModule(), // 发现页模块 + TestModule(), // 测试功能模块 + SettingModule(), // 设置模块 + SettingConModule(), // 设置连接层 + GeoModule(), // 地理位置服务 + PayModule(), // 支付模块 + AppOrderModule(), // 订单管理模块 + ClrOrderModule(), // 订单连接层服务 + AppNavigationModule(), // 导航模块 + AppConsentModule(), // 用户协议模块 + + // === 媒体和通信模块 === + AppTtsModule(), // 语音合成模块 + AppMessageModule(), // 消息模块 + ClrMessageModule(), // 消息连接层 + AppMnoModule(), // 移动网络服务 + ClrMnoModule(), // 移动网络连接层 + AppComposerModule(), // 内容编辑器 + + // === 业务应用模块 === + CommunityModule(), // 社区模块 + MembershipModule(), // 会员模块 + CarSalesModule(), // 汽车销售模块 + AfterSalesModule(), // 售后服务模块 + TouchPointModule(), // 触点管理模块 + CompanionModule(), // 伴侣服务模块 + AppConfigurationModule(), // 应用配置模块 + OneAppPopupModule(), // 弹窗管理模块 + + // === UI基础设施模块 === + BasicUIModule(), // 基础UI组件库 + ]; + + @override + List> get binds => [ + $AppBloc, // 应用级别的Bloc状态管理器 + ]; + + @override + List get routes { + // 通过RouteCenterAPI获取各模块的路由元数据 + final home = RouteCenterAPI.routeMetaBy(HomeRouteExport.keyModule); + final discovery = RouteCenterAPI.routeMetaBy(DiscoveryRouteExport.keyModule); + final car = RouteCenterAPI.routeMetaBy(CarControlRouteExport.keyModule); + final tts = RouteCenterAPI.routeMetaBy(TtsRouteExport.keyModule); + final account = RouteCenterAPI.routeMetaBy(AccountRouteExport.keyModule); + final setting = RouteCenterAPI.routeMetaBy(SettingRouteExport.keyModule); + final webview = RouteCenterAPI.routeMetaBy(WebViewRouteExport.keyModule); + final maintenance = RouteCenterAPI.routeMetaBy(MaintenanceRouteExport.keyModule); + final pay = RouteCenterAPI.routeMetaBy(PayRouteExport.keyModule); + final order = RouteCenterAPI.routeMetaBy(AppOrderRouteExport.keyModule); + final appCharging = RouteCenterAPI.routeMetaBy(AppChargingRouteExport.keyModule); + final appNavigation = RouteCenterAPI.routeMetaBy(AppNavigationRouteExport.keyModule); + final appAvatar = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyModule); + final community = RouteCenterAPI.routeMetaBy(CommuntiyRouteExport.keyModule); + final membership = RouteCenterAPI.routeMetaBy(MembershipRouteExport.keyModule); + final wallbox = RouteCenterAPI.routeMetaBy(AppWallboxRouteExport.keyModule); + final appMessage = RouteCenterAPI.routeMetaBy(AppMessageRouteExport.keyModule); + final appTouchGo = RouteCenterAPI.routeMetaBy(AppTouchgoRouteExport.keyModule); + // ... 更多路由元数据获取 + + // 定义不同的路由守卫列表 + const list = [_StatisticsGuard()]; // 基础统计守卫 + final carList = [const _StatisticsGuard(), LogInGuard._routeGuard]; // 车辆功能守卫（需要登录） + final composerList = [const _StatisticsGuard(), LogInGuard._routeGuard]; // 编辑功能守卫 + + return [ + // === 核心页面路由 === + ModuleRoute(home.path, module: home.provider(emptyArgs()).as(), guards: list), + + // 隐私政策页面（特殊处理） + ChildRoute('/app/app_privacy', + child: (BuildContext context, ModularArguments args) => LocalPrivacyPage()), + + ModuleRoute(discovery.path, module: discovery.provider(emptyArgs()).as(), guards: list), + ModuleRoute(account.path, module: account.provider(emptyArgs()).as(), guards: list), + ModuleRoute(setting.path, module: setting.provider(emptyArgs()).as(), guards: list), + + // === 车辆相关路由（需要登录守卫） === + ModuleRoute(car.path, module: car.provider(emptyArgs()).as(), guards: carList), + ModuleRoute(maintenance.path, module: maintenance.provider(emptyArgs()).as(), guards: carList), + ModuleRoute(appCharging.path, module: appCharging.provider(emptyArgs()).as(), guards: carList), + ModuleRoute(appNavigation.path, module: appNavigation.provider(emptyArgs()).as(), guards: carList), + ModuleRoute(wallbox.path, module: wallbox.provider(emptyArgs()).as(), guards: carList), + ModuleRoute(appMessage.path, module: appMessage.provider(emptyArgs()).as(), guards: carList), + + // === 业务功能路由 === + ModuleRoute(community.path, module: community.provider(emptyArgs()).as(), guards: list), + ModuleRoute(membership.path, module: membership.provider(emptyArgs()).as(), guards: list), + ModuleRoute(pay.path, module: pay.provider(emptyArgs()).as(), guards: list), + ModuleRoute(order.path, module: order.provider(emptyArgs()).as(), guards: carList), + + // === 特殊功能路由 === + ModuleRoute(appAvatar.path, module: appAvatar.provider(emptyArgs()).as(), guards: carList), + ModuleRoute(tts.path, module: tts.provider(emptyArgs()).as(), guards: carList), + ModuleRoute(appTouchGo.path, module: appTouchGo.provider(emptyArgs()).as(), guards: list), + + // 更多路由配置... + ]; + } + + @override + Map init() { + // 通知应用生命周期监听器 + notifyAppLifeCycle(this, 'init'); + return super.init(); + } +} +``` + +**路由守卫实现** - 基于OneApp的LogInGuard： + +```dart +/// 登录守卫 - 保护需要登录才能访问的车辆相关功能 +class LogInGuard extends RouteGuard { + factory LogInGuard() => _routeGuard; + LogInGuard._() : super(); + + static const String _tag = '[route LogInGuard]:'; + static final LogInGuard _routeGuard = LogInGuard._(); + + ParallelRoute? preRoute; // 前置路由信息 + + @override + FutureOr canActivate(String path, ParallelRoute route) { + // 通过依赖注入获取认证服务 + final authFacade = Modular.get(); + final isLogin = authFacade.isLogin; + return isLogin; + } + + @override + FutureOr pre(ModularRoute route) { + // 保存当前导航历史 + if (NavigatorProxy().navigateHistory.isNotEmpty) { + preRoute = NavigatorProxy().navigateHistory.last; + } + return super.pre(route); + } + + @override + FutureOr?> pos(ModularRoute route, dynamic data) async { + final authFacade = Modular.get(); + final isLogin = authFacade.isLogin; + + if (isLogin) { + return route as ParallelRoute; + } else { + // 创建登录同步器 + final c = Completer(); + + // 启动登录流程 + await startLoginForResult( + mode: LaunchMode.navigator, + onSuccess: () { + Logger.i('登录成功', _tag); + c.complete(true); + }, + onError: () { + Logger.i('登录失败', _tag); + c.complete(false); + }, + onCancel: () { + Logger.i('用户取消登录', _tag); + c.complete(false); + }, + ); + + final loginResult = await c.future; + final isLoginAfter = authFacade.isLogin; + + Logger.d('登录结果: $loginResult, 当前登录状态: $isLoginAfter', _tag); + + return null; // 阻止路由继续 + } + } +} + +/// 统计守卫 - 记录所有路由跳转的统计信息 +class _StatisticsGuard implements RouteGuard { + const _StatisticsGuard(); + static const String _tag = tagRoute; + + @override + FutureOr canActivate(String path, ParallelRoute route) => true; + + @override + FutureOr pre(ModularRoute route) => route; + + @override + FutureOr?> pos(ModularRoute route, ModularArguments data) async { + // 记录路由跳转日志 + Logger.d('路由跳转到: ${route.name}', _tag); + Logger.d('路由参数: ${data.uri}', _tag); + + // 这里可以添加埋点统计逻辑 + // AnalyticsService.trackPageView(route.name, data.data); + + return route as ParallelRoute?; + } + + @override + String? get redirectTo => null; +} +``` + +#### 3.3 跨模块通信机制 + +基于OneApp的事件总线系统，展示模块间松耦合通信的完整实现： + +**OneAppEventBus实现** - 支持匿名和标识订阅的事件总线： + +```dart +/// OneApp统一事件总线 - 支持模块间松耦合通信的实现 +class OneAppEventBus extends Object { + static final _eventBus = EventBus(); // 基础事件总线 + static final OneAppEventBus _instance = OneAppEventBus._internal(); + + // 高级事件管理器 + final Map> _eventControllers = {}; + final Map>> _anonymousSubscriptions = {}; + final Map>> _identifiedSubscriptions = {}; + + OneAppEventBus._internal(); + + /// 基础事件发布 - 适用于简单事件通信 + static void fireEvent(event) { + _eventBus.fire(event); + } + + /// 基础事件监听 - 类型安全的事件订阅 + static StreamSubscription addListen( + void Function(T event)? onData, { + Function? onError, + void Function()? onDone, + bool? cancelOnError, + }) { + return _eventBus.on().listen( + onData, + onError: onError, + onDone: onDone, + cancelOnError: cancelOnError, + ); + } + + /// 高级事件订阅 - 支持生命周期管理和重复订阅控制 + static void on(String eventType, Function(dynamic event) onEvent, {String? id}) { + var controller = _instance._eventControllers.putIfAbsent( + eventType, + () => StreamController.broadcast(), + ); + + var subscription = controller.stream.listen(onEvent); + + if (id == null) { + // 匿名订阅 - 需要手动管理生命周期 + _instance._anonymousSubscriptions + .putIfAbsent(eventType, () => []) + .add(subscription); + } else { + // 标识订阅 - 自动管理重复订阅，新订阅会替换旧订阅 + var subscriptions = _instance._identifiedSubscriptions.putIfAbsent(eventType, () => {}); + subscriptions[id]?.cancel(); // 取消旧的同名订阅 + subscriptions[id] = subscription; + } + } + + /// 事件发布 + static void fire(String eventType, dynamic event) { + _instance._eventControllers[eventType]?.add(event); + } + + /// 订阅管理 - 支持精确取消和批量取消 + static void cancel(String eventType, {String? id}) { + if (id == null) { + // 取消该事件类型的所有订阅 + _instance._anonymousSubscriptions[eventType]?.forEach((sub) => sub.cancel()); + _instance._anonymousSubscriptions.remove(eventType); + + _instance._identifiedSubscriptions[eventType]?.values.forEach((sub) => sub.cancel()); + _instance._identifiedSubscriptions.remove(eventType); + } else { + // 取消特定标识的订阅 + _instance._identifiedSubscriptions[eventType]?[id]?.cancel(); + _instance._identifiedSubscriptions[eventType]?.remove(id); + } + + // 清理空的事件控制器 + if ((_instance._anonymousSubscriptions[eventType]?.isEmpty ?? true) && + (_instance._identifiedSubscriptions[eventType]?.isEmpty ?? true)) { + _instance._eventControllers[eventType]?.close(); + _instance._eventControllers.remove(eventType); + } + } +} +``` + +**跨模块通信使用案例** - 车辆控制事件通信： + +```dart +/// 事件发布方 - 车辆控制服务模块 +class CarControlService { + /// 执行车辆锁定操作并发布事件 + Future lockCar(String vin) async { + try { + // 1. 执行实际的车辆锁定API调用 + final result = await Vehicle.rlu().doAction(RluAction.lock); + + // 2. 发布车辆锁定成功事件，通知其他模块 + OneAppEventBus.fire('car_control_result', { + 'action': 'lock', + 'vin': vin, + 'success': true, + 'timestamp': DateTime.now().toIso8601String(), + 'result': result.toString(), + }); + + Logger.i('车辆锁定成功，事件已发布'); + + } catch (error) { + // 3. 发布车辆锁定失败事件 + OneAppEventBus.fire('car_control_result', { + 'action': 'lock', + 'vin': vin, + 'success': false, + 'error': error.toString(), + 'timestamp': DateTime.now().toIso8601String(), + }); + + Logger.e('车辆锁定失败: $error'); + } + } + + /// 执行空调开启操作 + Future startClimatization() async { + try { + final result = await Vehicle.climatization().doAction(ClimatizationAction.start); + + OneAppEventBus.fire('climatization_status_changed', { + 'action': 'start', + 'status': 'running', + 'timestamp': DateTime.now().toIso8601String(), + }); + + } catch (error) { + OneAppEventBus.fire('climatization_status_changed', { + 'action': 'start', + 'status': 'error', + 'error': error.toString(), + }); + } + } +} + +/// 事件订阅方1 - 通知服务模块 +class NotificationService { + void initialize() { + // 订阅车辆控制结果事件 + OneAppEventBus.on('car_control_result', (event) { + final data = event as Map; + final action = data['action'] as String; + final success = data['success'] as bool; + + if (success) { + switch (action) { + case 'lock': + _showSuccessNotification('车辆已成功锁定'); + break; + case 'unlock': + _showSuccessNotification('车辆已成功解锁'); + break; + } + } else { + _showErrorNotification('车辆操作失败: ${data['error']}'); + } + }, id: 'notification_service'); // 使用标识ID，避免重复订阅 + + // 订阅空调状态变化事件 + OneAppEventBus.on('climatization_status_changed', (event) { + final data = event as Map; + final status = data['status'] as String; + + switch (status) { + case 'running': + _showInfoNotification('空调已启动'); + break; + case 'stopped': + _showInfoNotification('空调已关闭'); + break; + case 'error': + _showErrorNotification('空调操作失败'); + break; + } + }, id: 'notification_climatization'); + } + + void _showSuccessNotification(String message) { + // 显示成功通知的实现 + Logger.i('成功通知: $message'); + } + + void _showErrorNotification(String message) { + // 显示错误通知的实现 + Logger.e('错误通知: $message'); + } + + void _showInfoNotification(String message) { + // 显示信息通知的实现 + Logger.i('信息通知: $message'); + } +} + +/// 事件订阅方2 - 统计服务模块 +class AnalyticsService { + void initialize() { + // 匿名订阅，用于统计分析 + OneAppEventBus.on('car_control_result', (event) { + final data = event as Map; + + // 记录车辆操作统计 + _recordCarControlEvent( + action: data['action'], + success: data['success'], + vin: data['vin'], + timestamp: data['timestamp'], + ); + }); // 不提供id参数，创建匿名订阅 + } + + void _recordCarControlEvent({ + required String action, + required bool success, + required String vin, + required String timestamp, + }) { + // 埋点统计实现 + Logger.i('统计记录: 车辆操作[$action] 结果[$success] VIN[$vin]'); + } +} + +/// 事件订阅方3 - 首页Widget状态更新 +class HomePageBloc extends Bloc { + StreamSubscription? _carControlSubscription; + + HomePageBloc() : super(HomeInitial()) { + _initEventSubscriptions(); + } + + void _initEventSubscriptions() { + // 订阅车辆控制事件，更新首页UI状态 + _carControlSubscription = OneAppEventBus.addListen>((event) { + if (event['action'] == 'lock' && event['success'] == true) { + add(UpdateCarLockStatus(isLocked: true)); + } else if (event['action'] == 'unlock' && event['success'] == true) { + add(UpdateCarLockStatus(isLocked: false)); + } + }); + } + + @override + Future close() { + _carControlSubscription?.cancel(); + return super.close(); + } +} +``` + +#### 3.4 数据流管理 + +基于OneApp的Bloc实现，展示完整的数据流从UI事件到状态更新的处理过程： + +```mermaid +graph LR + A[用户操作] --> B[RemoteClimatisationControlBloc] + B --> C[ClimatizationService] + C --> D[Vehicle.climatization] + D --> E[车辆API] + + E --> D + D --> F[ObserverClient监听] + F --> B + B --> G[RemoteClimatisationState] + G --> H[UI更新] + + I[OneAppEventBus] --> J[跨模块通知] +``` + +**Bloc数据流实现** - 基于OneApp的远程空调控制： + +```dart +/// 远程空调控制状态 - 使用Freezed确保不可变性 +@freezed +class RemoteClimatisationState with _$RemoteClimatisationState { + const factory RemoteClimatisationState({ + required ClimatizationService climatization, // 空调服务实例 + required bool climatizationAtUnlock, // 解锁启动开关 + required double temperature, // 空调温度 + ClimatisationStatus? status, // 空调状态 + ClimatizationParameter? parameter, // 空调参数 + bool? actionStart, // 开启操作执行状态 + bool? actionStop, // 关闭操作执行状态 + bool? actionSetting, // 设置保存操作状态 + bool? updatePage, // 页面更新标记 + double? sliderValue, // 温度滑动条值 + }) = _RemoteClimatisationState; +} + +/// 远程空调控制事件 +@freezed +class RemoteClimatisationControlEvent with _$RemoteClimatisationControlEvent { + /// 温度设置事件 + const factory RemoteClimatisationControlEvent.updateTemperatureSettingEvent({ + required double temperature, + }) = UpdateTemperatureSettingEvent; + + /// 解锁启动开关事件 + const factory RemoteClimatisationControlEvent.updateClimatizationAtUnlockEvent({ + required bool climatizationAtUnlock, + }) = UpdateClimatizationAtUnlockEvent; + + /// 执行空调操作事件 + const factory RemoteClimatisationControlEvent.updateActionExecuteEvent({ + required ClimatizationAction action, + }) = UpdateActionExecuteEvent; + + /// 滑动条值更新事件 + const factory RemoteClimatisationControlEvent.updateSliderExecuteEvent({ + required double sliderValue, + }) = UpdateSliderExecuteEvent; + + /// 页面数据刷新事件 + const factory RemoteClimatisationControlEvent.updatePageDataEvent() = UpdatePageDataEventEvent; +} + +/// 远程空调控制Bloc +class RemoteClimatisationControlBloc + extends Bloc { + + /// 车辆服务观察者客户端 + late ObserverClient client; + + RemoteClimatisationControlBloc( + ClimatizationService climatization, + double temperature, + bool climatizationAtUnlock, + String? noticeVin, // 通知栏传入的VIN码 + BuildContext? context, + ) : super(RemoteClimatisationState( + climatization: climatization, + temperature: temperature, + climatizationAtUnlock: climatizationAtUnlock, + )) { + + // 注册事件处理器 + on(_onUpdateTemperatureSetting); + on(_onUpdateClimatizationAtUnlockEvent); + on(_onUpdateActionExecuteEvent); + on(_onUpdateSliderExecuteEvent); + on(_onUpdatePageDataEventEvent); + + // 检查服务状态并初始化 + if (climatization.isStatusReady && climatization.isParameterReady) { + // 状态和参数都准备就绪 + _updateCompleteState(); + } else if (climatization.isStatusReady) { + // 仅状态准备就绪 + emit(state.copyWith(status: climatization.status as ClimatisationStatus)); + } else if (climatization.isParameterReady) { + // 仅参数准备就绪 + _updateParameterState(); + } + + CarAppLog.i('RemoteClimatisationControlBloc 初始化完成'); + CarAppLog.i('actionStart: ${state.actionStart}'); + CarAppLog.i('actionStop: ${state.actionStop}'); + CarAppLog.i('actionSetting: ${state.actionSetting}'); + + // 刷新空调数据 + climatization.doAction(ClimatizationAction.refresh); + + // 订阅空调服务变化 + _subscribeToClimatizationService(climatization); + + // 检查默认车辆（异步） + checkDefaultVehicle(context, noticeVin); + } + + /// 订阅空调服务变化 + void _subscribeToClimatizationService(ClimatizationService climatization) { + client = Vehicle.addServiceObserver( + serviceCategory: VehicleServiceCategory.climatisation, + onChange: (serviceBase) { + final service = serviceBase as ClimatizationService; + CarAppLog.i('空调服务状态变化回调'); + + // 检查各种操作状态 + final actionStartRunning = checkActionStartRun(service); + final actionStopRunning = checkActionStopRun(service); + final actionSettingRunning = checkActionSettingRun(service); + + // 更新状态 + emit(state.copyWith( + climatization: service, + status: service.status as ClimatisationStatus?, + parameter: service.parameter, + actionStart: actionStartRunning, + actionStop: actionStopRunning, + actionSetting: actionSettingRunning, + updatePage: !(state.updatePage ?? false), // 切换更新标记 + )); + + CarAppLog.i('空调状态已更新: start=$actionStartRunning, stop=$actionStopRunning'); + }, + ); + } + + /// 检查空调启动操作是否正在执行 + bool checkActionStartRun(ClimatizationService climatization) { + final InProcessActions inProcessActions = climatization.inProcessActions; + return inProcessActions.getServiceAction(ClimatizationAction.start) != null; + } + + /// 检查空调停止操作是否正在执行 + bool checkActionStopRun(ClimatizationService climatization) { + final InProcessActions inProcessActions = climatization.inProcessActions; + return inProcessActions.getServiceAction(ClimatizationAction.stop) != null; + } + + /// 检查空调设置操作是否正在执行 + bool checkActionSettingRun(ClimatizationService climatization) { + final InProcessActions inProcessActions = climatization.inProcessActions; + return inProcessActions.getServiceAction(ClimatizationAction.setting) != null; + } + + /// 温度设置事件处理 + FutureOr _onUpdateTemperatureSetting( + UpdateTemperatureSettingEvent event, + Emitter emit, + ) { + CarAppLog.i('处理温度设置事件: ${event.temperature}'); + + if (state.climatization.isParameterReady) { + // 参数准备就绪，更新温度设置 + final updatedParameter = state.parameter?.copyWith( + targetTemperature: TargetTemperature.fromCelsius(event.temperature), + ); + + emit(state.copyWith( + temperature: event.temperature, + parameter: updatedParameter, + )); + } else { + CarAppLog.w('空调参数未准备就绪，跳过温度设置'); + } + } + + /// 解锁启动开关事件处理 + FutureOr _onUpdateClimatizationAtUnlockEvent( + UpdateClimatizationAtUnlockEvent event, + Emitter emit, + ) { + CarAppLog.i('处理解锁启动开关事件: ${event.climatizationAtUnlock}'); + + emit(state.copyWith(climatizationAtUnlock: event.climatizationAtUnlock)); + + // 保存设置到本地存储或发送到服务器 + // 具体实现略... + } + + /// 空调操作执行事件处理 + FutureOr _onUpdateActionExecuteEvent( + UpdateActionExecuteEvent event, + Emitter emit, + ) { + CarAppLog.i('执行空调操作: ${event.action}'); + + // 执行具体的空调操作 + state.climatization.doAction(event.action); + + // 更新对应的操作状态 + switch (event.action) { + case ClimatizationAction.start: + emit(state.copyWith(actionStart: true)); + break; + case ClimatizationAction.stop: + emit(state.copyWith(actionStop: true)); + break; + case ClimatizationAction.setting: + emit(state.copyWith(actionSetting: true)); + break; + default: + break; + } + } + + /// 滑动条值更新事件处理 + FutureOr _onUpdateSliderExecuteEvent( + UpdateSliderExecuteEvent event, + Emitter emit, + ) { + emit(state.copyWith(sliderValue: event.sliderValue)); + } + + /// 页面数据刷新事件处理 + FutureOr _onUpdatePageDataEventEvent( + UpdatePageDataEventEvent event, + Emitter emit, + ) { + CarAppLog.i('刷新页面数据'); + + // 切换更新标记，触发UI重新构建 + emit(state.copyWith(updatePage: !(state.updatePage ?? false))); + + // 刷新空调服务数据 + state.climatization.doAction(ClimatizationAction.refresh); + } + + /// 检查默认车辆 + Future checkDefaultVehicle(BuildContext? context, String? noticeVin) async { + await VehicleUtils.checkDefaultVehicle(context, noticeVin, (value) { + // 车辆检查回调处理 + CarAppLog.i('默认车辆检查完成: $value'); + }); + } + + /// 更新完整状态 + void _updateCompleteState() { + emit(state.copyWith( + status: state.climatization.status as ClimatisationStatus, + parameter: state.climatization.parameter, + actionStart: checkActionStartRun(state.climatization), + actionStop: checkActionStopRun(state.climatization), + actionSetting: checkActionSettingRun(state.climatization), + )); + } + + /// 更新参数状态 + void _updateParameterState() { + emit(state.copyWith( + parameter: state.climatization.parameter, + actionSetting: checkActionSettingRun(state.climatization), + )); + } + + @override + Future close() { + CarAppLog.i('RemoteClimatisationControlBloc 资源清理'); + Vehicle.removeServiceObserver(client); // 取消服务订阅 + return super.close(); + } +} +``` + +**使用Repository模式的数据流实现**： + +```dart +/// 充电桩Repository - 数据源管理实现 +class ChargingStationRepository { + final ChargingStationApi _api = Modular.get(); + final ChargingStationCache _cache = Modular.get(); + + /// 查找附近充电桩 - 实现缓存优先策略 + Future> findNearbyStations( + LatLng location, { + int radius = 5000, + }) async { + try { + // 1. 优先从缓存获取数据 + final cached = await _cache.getNearbyStations(location, radius); + if (cached.isNotEmpty && !_cache.isExpired(location)) { + Logger.i('从缓存获取充电桩数据: ${cached.length}个'); + return cached; + } + + // 2. 缓存过期或无数据，从API获取 + Logger.i('从API获取充电桩数据'); + final stations = await _api.findNearbyStations(location, radius); + + // 3. 更新缓存 + await _cache.cacheStations(location, stations); + + return stations; + } catch (error) { + Logger.e('获取充电桩数据失败: $error'); + + // 4. 出错时返回缓存数据（如果有） + final cached = await _cache.getNearbyStations(location, radius); + if (cached.isNotEmpty) { + Logger.w('返回过期缓存数据: ${cached.length}个'); + return cached; + } + + rethrow; + } + } +} + +/// 充电桩搜索Bloc - 完整的数据流管理 +class ChargingStationBloc extends Bloc { + final ChargingStationRepository repository; + + ChargingStationBloc(this.repository) : super(ChargingStationInitial()) { + on(_onLoadNearbyStations); + on(_onRefreshStations); + } + + /// 加载附近充电桩 + Future _onLoadNearbyStations( + LoadNearbyStations event, + Emitter emit, + ) async { + emit(ChargingStationLoading()); + + try { + // 通过Repository获取数据 + final stations = await repository.findNearbyStations( + event.location, + radius: event.radius, + ); + + emit(ChargingStationLoaded( + stations: stations, + location: event.location, + lastUpdateTime: DateTime.now(), + )); + + // 发布事件通知其他模块 + OneAppEventBus.fire('charging_stations_loaded', { + 'count': stations.length, + 'location': event.location, + 'timestamp': DateTime.now().toIso8601String(), + }); + + } catch (error) { + emit(ChargingStationError(error.toString())); + + // 发布错误事件 + OneAppEventBus.fire('charging_stations_error', { + 'error': error.toString(), + 'location': event.location, + }); + } + } + + /// 刷新充电桩数据 + Future _onRefreshStations( + RefreshStations event, + Emitter emit, + ) async { + if (state is ChargingStationLoaded) { + final currentState = state as ChargingStationLoaded; + emit(ChargingStationRefreshing(currentState.stations)); + + try { + final stations = await repository.findNearbyStations( + currentState.location, + radius: 5000, + ); + + emit(ChargingStationLoaded( + stations: stations, + location: currentState.location, + lastUpdateTime: DateTime.now(), + )); + } catch (error) { + emit(ChargingStationLoaded( + stations: currentState.stations, + location: currentState.location, + lastUpdateTime: currentState.lastUpdateTime, + error: error.toString(), + )); + } + } + } +} +``` + +## 总结 + +### 1. OneApp架构设计优势 + +#### 1.1 技术架构优势 + +**模块化设计** +- ✅ **独立开发**: 各业务模块可并行开发，提升团队协作效率 +- ✅ **版本管理**: 模块独立版本控制，降低发版风险 +- ✅ **代码复用**: 基础设施模块在多个业务模块间复用 +- ✅ **测试隔离**: 模块级别的单元测试和集成测试 + +**分层架构** +- ✅ **职责清晰**: UI层、业务层、服务层、基础设施层职责明确 +- ✅ **易于维护**: 分层设计使代码结构清晰，便于维护和扩展 +- ✅ **技术栈统一**: Flutter + Dart 统一技术栈，降低学习成本 +- ✅ **平台一致性**: 跨平台UI和业务逻辑一致性 + +**性能与稳定性** +- ✅ **AOT编译**: Release模式下AOT编译保证运行性能 +- ✅ **资源优化**: 按需加载和缓存机制优化资源使用 +- ✅ **错误隔离**: 模块间错误隔离，提升应用稳定性 +- ✅ **监控完备**: 性能监控、错误上报、日志系统完备 + +#### 1.2 业务架构优势 + +**功能丰富度** +```mermaid +graph TB + OneApp[OneApp功能] + + subgraph "车辆服务" + A1[远程控制] + A2[状态监控] + A3[维护提醒] + A4[虚拟钥匙] + end + + subgraph "充电服务" + B1[充电桩查找] + B2[充电预约] + B3[支付结算] + B4[充电记录] + end + + subgraph "生活服务" + C1[订单管理] + C2[社区互动] + C3[会员权益] + C4[个人设置] + end + + subgraph "增值服务" + D1[Touch&Go] + D2[家充桩管理] + D3[汽车销售] + D4[售后服务] + end + + OneApp --> A1 + OneApp --> B1 + OneApp --> C1 + OneApp --> D1 +``` + +**用户体验** +- 🎯 **一致性**: 跨平台UI和交互一致性 +- 🎯 **流畅性**: 60fps渲染和流畅的动画效果 +- 🎯 **响应性**: 快速的页面加载和数据响应 +- 🎯 **可用性**: 离线功能和网络异常处理 + +### 2. 面临的挑战 + +#### 2.1 技术挑战 + +**依赖管理复杂性** +```yaml +# 大量的dependency_overrides表明依赖版本冲突问题 +dependency_overrides: + meta: ^1.9.1 + collection: ^1.17.1 + path: ^1.8.3 + # ... 更多版本覆盖 +``` +- ⚠️ **版本冲突**: 大量`dependency_overrides`导致版本管理困难 +- ⚠️ **构建时间**: 众多本地依赖导致构建时间较长 +- ⚠️ **依赖维护**: 本地路径依赖的版本同步问题 +- ⚠️ **模块粒度**: 部分模块粒度过小，增加了管理复杂度 +- ⚠️ **循环依赖**: 某些模块间存在潜在的循环依赖风险 + +### 3. 架构演进方向 + +#### 3.1 短期优化 + +**依赖治理** +```yaml +# 目标：减少dependency_overrides +dependencies: + # 统一基础依赖版本 + provider: ^6.1.1 + rxdart: ^0.27.7 + dio: ^5.3.2 +``` + +**具体措施** +- 🔧 **版本统一**: 统一各模块的基础依赖版本 +- 🔧 **依赖精简**: 合并功能相似的小模块 diff --git a/README.md b/README.md new file mode 100644 index 0000000..421d181 --- /dev/null +++ b/README.md @@ -0,0 +1,167 @@ +# OneApp 架构设计文档 + +> OneApp Flutter 应用的完整技术架构设计和模块说明文档站点 + +## 🚀 快速开始 + +### - 源文档直接在根目录维护，构建时自动拷贝 + +## 🛠️ 技术栈 + +- **框架**: Flutter 3.0+ +- **Python 3.7+** - 运行MkDocs +- **PowerShell 5.0+** - 执行构建脚本（Windows自带） +- **Git** - 版本控制（可选） + +### 安装依赖 +```bash +# 安装MkDocs Material主题 +pip install mkdocs-material +``` + +### 构建方式 +本文档站点支持两种构建方式： +- **自动构建脚本** - 一键完成所有操作（推荐） +- **MkDocs手动构建** - 传统方式，需要手动处理文件 +- **Docsify** - 动态文档解析（兼容支持） + +提供了完整的 OneApp Flutter 应用架构设计说明。 + +### 📖 主要内容 + +- **[架构设计文档](OneApp架构设计文档.md)** - 完整的系统架构设计文档 +- **[AI聊天助手](CODE_ANALYSIS.md)** - AI聊天助手代码解析 +- **[主应用架构](main_app.md)** - 主应用的详细架构说明 +- **[调试工具](debug_tools.md)** - 开发调试工具使用指南 + +### 📱 功能模块 + +根据OneApp架构设计，系统分为应用层（APP）和服务层（CLR）两大部分： + +#### 🔧 服务层模块 (CLR - Connection Layer) +- **[账户服务](account/README.md)** - CLR账户服务SDK，用户认证和授权 +- **[售后服务](after_sales/README.md)** - CLR售后服务SDK，售后流程管理 + +#### 🚗 应用层模块 (APP - Application Layer) +- **[车辆服务](app_car/README.md)** - 车辆控制、充电、监控等核心功能 +- **[汽车销售](car_sales/README.md)** - 汽车销售业务功能 + +#### 🏗 基础设施层 +- **[基础UI组件](basic_uis/README.md)** - UI组件库和设计系统 +- **[基础工具库](basic_utils/README.md)** - 网络、存储、日志等基础工具 +- **[服务组件](service_component/README.md)** - 通用服务组件 + +#### 🎯 业务功能层 +- **[社区功能](community/README.md)** - 用户社区和交互功能 +- **[会员服务](membership/README.md)** - 会员权益和管理系统 +- **[设置功能](setting/README.md)** - 应用配置和个人设置 +- **[触点模块](touch_point/README.md)** - 用户接触点管理 + +## 📁 项目结构 + +``` +oneapp_docs/ +├── build-docs.ps1 # PowerShell构建脚本 +├── build-docs.bat # Windows批处理入口 +├── mkdocs.yml # MkDocs配置文件 +├── assets/ # 静态资源 +│ ├── css/extra.css # 自定义样式 +│ └── js/ # JavaScript文件 +├── site/ # 生成的静态站点（git忽略） +├── docs/ # 临时文档目录（git忽略，脚本自动生成） +├── *.md # 源Markdown文档 +├── account/ # 账户模块文档 +├── app_car/ # 车辆服务文档 +├── basic_uis/ # UI组件文档 +├── basic_utils/ # 工具库文档 +├── images/ # 图片资源 +└── ... # 其他模块目录 +``` + +### 重要说明 +- `docs/` 目录由构建脚本自动生成，不需要手动维护 +- `site/` 目录包含最终生成的HTML文档 +- 源文档直接在根目录维护，构建时自动拷贝 + +## 🛠️ 技术栈 + +- **框架**: Flutter 3.0+ +- **语言**: Dart 3.0+ +- **架构**: MVVM + 模块化 +- **状态管理**: Provider + Bloc +- **路由**: Flutter Modular +- **网络**: Dio +- **存储**: Hive + SharedPreferences + +## 📖 使用指南 + +### 🚀 一键构建（推荐） + +本项目提供了自动化构建脚本，可以一键完成文档构建： + +#### Windows 用户 +```bash +# 方式1: 双击运行（最简单） +双击 build-docs.bat 文件 + +# 方式2: PowerShell命令行 +.\build-docs.ps1 # 标准构建（推荐） +.\build-docs.ps1 -KeepDocs # 保留docs目录（调试用） +.\build-docs.ps1 -Help # 查看帮助信息 +``` + +#### 构建脚本特性 +- ✅ **自动拷贝** - 将源文件自动拷贝到docs目录 +- ✅ **一键构建** - 执行完整的MkDocs构建流程 +- ✅ **自动清理** - 构建完成后自动清理临时文件 +- ✅ **Git友好** - docs目录不会被提交到版本库 +- ✅ **错误处理** - 失败时自动回滚和清理 + +### 在线浏览 +- 使用左侧导航栏浏览不同模块 +- 使用右上角搜索功能快速查找内容 +- 点击主题切换按钮切换深色/浅色模式 + +### MkDocs 手动部署 + +如果需要手动构建，可以使用以下命令： + +```bash +# 安装 MkDocs Material +pip install mkdocs-material + +# 手动拷贝文件到docs目录后，在项目目录启动本地服务 +mkdocs serve + +# 访问 http://127.0.0.1:8000 + +# 构建静态站点 +mkdocs build +``` + +> **注意**: 手动构建需要自己处理文件拷贝和清理工作，推荐使用上述自动化脚本。 + +### Docsify 本地部署（兼容） +```bash +# 安装 docsify-cli +npm install -g docsify-cli + +# 在项目目录启动本地服务 +docsify serve + +# 访问 http://localhost:3000 +``` + +## 🎯 文档特性 + +- ✅ **双构建支持** - MkDocs静态生成 + Docsify动态解析 +- ✅ **Mermaid 图表支持** - 所有架构图表自动渲染 +- ✅ **响应式设计** - 完美支持移动端和桌面端 +- ✅ **全文搜索** - 快速查找文档内容 +- ✅ **主题切换** - 支持浅色和深色主题 +- ✅ **代码高亮** - 支持多种编程语言语法高亮 +- ✅ **中文优化** - 完整的中文本地化支持 + +--- + +> **提示**: 文档中的所有 Mermaid 图表都支持交互式查看，点击可获得更好的阅读体验。静态站点推荐使用MkDocs构建版本获得最佳性能。 \ No newline at end of file diff --git a/_sidebar.md b/_sidebar.md new file mode 100644 index 0000000..c78aee9 --- /dev/null +++ b/_sidebar.md @@ -0,0 +1,78 @@ + + +* [📖 OneApp架构设计文档](OneApp架构设计文档.md) + +* [🏠 主应用架构](main_app.md) + +* [🔧 调试工具](debug_tools.md) + +* **📱 核心模块** + * [👤 账户模块](account/README.md) + * [CLR账户](account/clr_account.md) + * [极光认证](account/jverify.md) + + * [🚗 车辆相关](app_car/README.md) + * [AI聊天助手](app_car/ai_chat_assistant.md) + * [高德地图定位](app_car/amap_flutter_location.md) + * [高德地图搜索](app_car/amap_flutter_search.md) + * [虚拟形象](app_car/app_avatar.md) + * [车辆主模块](app_car/app_car.md) + * [车辆监控](app_car/app_carwatcher.md) + * [充电功能](app_car/app_charging.md) + * [编辑器组件](app_car/app_composer.md) + * [维护保养](app_car/app_maintenance.md) + * [订单管理](app_car/app_order.md) + * [RPA自动化](app_car/app_rpa.md) + * [TouchGo](app_car/app_touchgo.md) + * [VUR功能](app_car/app_vur.md) + * [壁盒管理](app_car/app_wallbox.md) + * [车辆服务](app_car/car_services.md) + * [CLR虚拟形象](app_car/clr_avatarcore.md) + * [CLR订单](app_car/clr_order.md) + * [CLR TouchGo](app_car/clr_touchgo.md) + * [CLR壁盒](app_car/clr_wallbox.md) + * [RPA插件工具包](app_car/kit_rpa_plugin.md) + * [OneApp缓存插件](app_car/one_app_cache_plugin.md) + * [UI虚拟形象X](app_car/ui_avatarx.md) + + * [🛠️ 售后服务](after_sales/README.md) + * [CLR售后](after_sales/clr_after_sales.md) + * [OneApp售后](after_sales/oneapp_after_sales.md) + +* **🎨 基础设施** + * [🎭 基础UI](basic_uis/README.md) + * [基础UI组件](basic_uis/basic_uis.md) + * [通用UI组件](basic_uis/general_ui_component.md) + * [UI基础](basic_uis/ui_basic.md) + * [UI业务组件](basic_uis/ui_business.md) + + * [🔧 基础工具](basic_utils/README.md) + * [MVVM基础](basic_utils/base_mvvm.md) + * [基础配置](basic_utils/basic_config.md) + * [日志系统](basic_utils/basic_logger.md) + * [网络层](basic_utils/basic_network.md) + * [平台工具](basic_utils/basic_platform.md) + * [推送服务](basic_utils/basic_push.md) + * [基础工具](basic_utils/basic_utils.md) + * [下载器](basic_utils/flutter_downloader.md) + * [极光推送私有](basic_utils/flutter_plugin_mtpush_private.md) + +* **🏪 业务功能** + * [🚙 汽车销售](car_sales/README.md) + + * [👥 社区功能](community/README.md) + + * [💎 会员服务](membership/README.md) + + * [🧩 服务组件](service_component/README.md) + + * [⚙️ 设置模块](setting/README.md) + + * [📍 触点管理](touch_point/README.md) + +--- + +* **🔗 相关链接** + * [GitHub 仓库](https://github.com/aichiko0225/oneapp_docs) + * [Flutter 官方文档](https://docs.flutter.cn/) + * [Dart 官方文档](https://dart.cn/) diff --git a/account/README.md b/account/README.md new file mode 100644 index 0000000..5459f13 --- /dev/null +++ b/account/README.md @@ -0,0 +1,119 @@ +# OneApp Account 账户模块文档 + +## 模块概述 + +`oneapp_account` 是 OneApp 的用户账户管理模块，负责用户认证、登录、注册、权限管理等核心功能。该模块包含两个主要子模块： + +- **clr_account**: 账户服务 SDK，提供账户相关的核心服务接口 +- **jverify**: 极验验证 Flutter 插件，提供安全验证功能 + +## 真实项目结构 + +基于实际的 `oneapp_account` 项目结构： + +``` +oneapp_account/ +├── lib/ +│ ├── account.dart # 主要导出文件 +│ ├── account_api.dart # API接口定义 +│ ├── account_third_bind.dart # 第三方绑定 +│ ├── module_constants.dart # 模块常量 +│ ├── generated/ # 代码生成文件 +│ ├── l10n/ # 国际化文件 +│ └── src/ # 源代码目录 +│ ├── account_dependency.dart # 依赖配置 +│ ├── blocs/ # BLoC状态管理 +│ │ ├── personal_center/ # 个人中心BLoC +│ │ ├── garage/ # 车库管理BLoC +│ │ ├── vehicle_info/ # 车辆信息BLoC +│ │ ├── phone_sign_in/ # 手机登录BLoC +│ │ ├── bind_vehicle_new/ # 绑车流程BLoC +│ │ ├── qr_hu_confirm/ # 二维码确认BLoC +│ │ └── ... # 其他业务BLoC +│ ├── pages/ # 页面组件 +│ ├── model/ # 数据模型 +│ ├── utils/ # 工具类 +│ ├── constants/ # 常量定义 +│ ├── route_dp.dart # 路由配置 +│ └── route_export.dart # 路由导出 +├── clr_account/ # 账户连接层服务 +├── jverify/ # 极验验证插件 +├── assets/ # 资源文件 +└── pubspec.yaml # 依赖配置 +``` + +## 子模块文档 + +- [CLR Account 账户服务 SDK](./clr_account.md) +- [JVerify 极验验证插件](./jverify.md) + +## 主要功能 + +### 真实实现的功能模块 +基于实际项目代码，账户模块包含以下已实现的功能： + +#### 1. 用户认证和登录 +- **手机号登录** (`phone_sign_in/`) - 支持手机号密码登录 +- **验证码验证** (`verification_code_input/`) - 短信验证码确认 +- **第三方登录** (`third_sign_in/`) - 第三方账户集成 +- **二维码登录确认** (`qr_hu_confirm/`) - 车机登录确认功能 + +#### 2. 个人信息管理 +- **个人中心** (`personal_center/`) - 用户信息展示和管理 +- **个人资料** (`personal_intro/`) - 个人信息编辑 +- **头像管理** - 用户头像上传和设置 +- **手机号更新** (`update_phone/`) - 更换绑定手机号 + +#### 3. 车辆管理 +- **车库管理** (`garage/`) - 车辆列表和管理 +- **车辆信息** (`vehicle_info/`) - 车辆详细信息查看 +- **绑车流程** (`bind_vehicle_new/`) - 新车绑定流程 +- **车辆授权** (`vehicle_auth/`) - 车辆访问权限管理 +- **车牌设置** (`plate_no_edit/`) - 车牌号码编辑 + +#### 4. 扫码功能 +- **二维码扫描** (`qr_scan/`) - 通用二维码扫描 +- **扫码登录** (`scan_login_hu/`) - 扫码登录车机功能 +- **绑车二维码** - 车辆绑定二维码处理 + +#### 5. 账户安全 +- **账户注销** (`cancel_account/`) - 用户账户注销流程 +- **短信认证** (`sms_auth/`) - 安全操作短信验证 +- **用户协议** (`agreement/`) - 用户协议和隐私政策 + +## 真实技术架构 + +### 模块依赖 +基于实际 `pubspec.yaml` 的真实依赖： + +```yaml +dependencies: + # 核心框架 + basic_modular: ^0.2.3 # 模块化框架 + basic_modular_route: ^0.2.1 # 路由管理 + basic_network: ^0.2.3+4 # 网络请求 + basic_storage: ^0.2.2 # 本地存储 + + # 业务依赖 + clr_account: ^0.2.24 # 账户服务SDK (本地路径) + car_vehicle: ^0.6.4+1 # 车辆服务 + app_consent: ^0.2.19 # 用户同意管理 + + # 工具依赖 + dartz: ^0.10.1 # 函数式编程 + freezed_annotation: ^2.2.0 # 不可变类生成 + flutter_contacts: ^1.1.5 # 联系人服务 +``` + +## 依赖关系 + +该模块被 `oneapp_main` 项目依赖，为整个应用提供用户账户相关的基础服务。 + +## 开发指南 + +### 环境要求 +- Flutter >=3.0.0 +- Dart >=3.0.0 + +### 集成使用 +详细的集成使用方法请参考各子模块的具体文档。 diff --git a/account/clr_account.md b/account/clr_account.md new file mode 100644 index 0000000..90130ba --- /dev/null +++ b/account/clr_account.md @@ -0,0 +1,512 @@ +# CLR Account 账户服务 SDK 文档 + +## 模块概述 + +`clr_account` 是 OneApp 账户系统的核心 SDK，提供用户认证、登录、注册、权限管理等基础服务。该模块采用领域驱动设计（DDD）架构，提供清晰的接口抽象和业务逻辑封装。 + +### 基本信息 +- **模块名称**: clr_account +- **版本**: 0.2.24 +- **仓库**: https://gitlab-rd0.maezia.com/dssomobile/oneapp/dssomobile-oneapp-clr-account + +## 目录结构 + +``` +clr_account/ +├── lib/ +│ ├── account.dart # 主要导出文件 +│ ├── account_event.dart # 账户事件定义 +│ ├── third_account.dart # 第三方账户集成 +│ ├── generated/ # 代码生成文件 +│ ├── l10n/ # 国际化文件 +│ └── src/ # 源代码目录 +│ ├── data/ # 数据层 +│ ├── domain/ # 领域层 +│ ├── presentation/ # 表示层 +│ └── infrastructure/ # 基础设施层 +├── pubspec.yaml # 依赖配置 +└── README.md # 项目说明 +``` + +## 核心功能模块 + +### 1. 账户认证 (Authentication) + +#### 功能概述 +- 用户登录/登出 +- 密码认证 +- 生物识别认证 +- 多因素认证 + +#### 主要接口 +```dart +// 基于实际项目的认证门面接口 +abstract class IAuthFacade { + /// 当前登录状态 + bool get isLogin; + + /// 用户登出 + Future logout(); + + /// 撤销注销 + Future> undoSignOut(String refCode); +} + +// 实际的认证异常类型 +sealed class AuthFailure { + const AuthFailure(); +} + +class OtherError extends AuthFailure { + final dynamic error; + const OtherError(this.error); +} +``` + +### 2. 用户注册 (Registration) + +#### 功能概述 +- 新用户注册 +- 手机号验证 +- 邮箱验证 +- 用户信息收集 + +#### 主要接口 +```dart +// 基于实际项目的配置文件门面接口 +abstract class IProfileFacade { + /// 获取本地用户配置文件 + Either getUserProfileLocal(); + + /// 从云端获取用户配置文件 + Future> fetchUserProfile(); +} + +// 实际的配置文件异常类型 +sealed class ProfileFailure { + const ProfileFailure(); +} + +// 实际的用户配置模型 +class UserProfile { + final String id; + final String name; + final String email; + final String? avatar; + + const UserProfile({ + required this.id, + required this.name, + required this.email, + this.avatar, + }); +} +``` + +### 3. 用户信息管理 (Profile) + +#### 功能概述 +- 个人信息查看和编辑 +- 头像管理 +- 偏好设置 +- 隐私设置 + +#### 主要接口 +```dart +// 基于实际项目的车库门面接口 +abstract class IGarageFacade { + /// 获取车库绑车列表 + /// [refresh]为 true 则强制从网络获取，并刷新本地数据 + Future>> getEnrollmentVehicleList({ + bool refresh = false, + bool local = false, + }); + + /// 获取默认车辆 + Future> getDefaultEnrolledVehicle({ + bool refresh = false, + }); + + /// 快速获取默认车辆 + VehicleDto? getDefaultVehicleLocal(); + + /// 设置车辆是否默认 + Future> setVehicleDefault({ + required String vin, + required bool isDefault, + }); + + /// 修改车牌号 + Future> setVehiclePlateNo( + String plateNo, + String vin, + ); + + /// 扫码登录车机 + Future> signInHUWithQrCode({ + required String uuid, + required int? timestamp, + required String? signature, + }); +} + +// 实际的车辆数据传输对象 +class VehicleDto { + final String vin; + final String? plateNo; + final VehicleModel vehicleModel; + final String accountType; + + const VehicleDto({ + required this.vin, + this.plateNo, + required this.vehicleModel, + required this.accountType, + }); + + static const String accountTypeP = 'P'; // 主账户 + static const String accountTypeS = 'S'; // 从账户 +} +``` + +### 4. 权限管理 (Authorization) + +#### 功能概述 +- 角色权限管理 +- 功能权限控制 +- 资源访问控制 + +#### 主要接口 +```dart +abstract class AuthorizationService { + Future> hasPermission(String permission); + Future>> getUserRoles(); + Future> canAccessResource(String resource); +} +``` + +## 技术架构 + +### 分层架构 + +#### 1. 表示层 (Presentation Layer) +- **功能**: 用户界面相关的状态管理和事件处理 +- **组件**: + - Widget 组件 + - State 管理 + - Event 处理器 + +#### 2. 领域层 (Domain Layer) +- **功能**: 业务逻辑和业务规则 +- **组件**: + - Entity 实体 + - Value Object 值对象 + - Domain Service 领域服务 + - Repository 接口 + +#### 3. 数据层 (Data Layer) +- **功能**: 数据访问和存储 +- **组件**: + - Repository 实现 + - Data Source 数据源 + - Model 数据模型 + +#### 4. 基础设施层 (Infrastructure Layer) +- **功能**: 外部服务集成 +- **组件**: + - 网络服务 + - 存储服务 + - 第三方 SDK 集成 + +### 状态管理 + +#### 事件驱动架构 +基于 OneApp 事件总线系统，使用真实的账户事件处理机制。 + +```dart +// 实际项目中的事件处理示例（从 PersonalCenterBloc） +class PersonalCenterBloc extends Bloc { + PersonalCenterBloc( + this._signInFacade, + this._profileFacade, + this._garageFacade, + ) : super(PersonalCenterState.initial()) { + // 监听推送事件 + _eventListener = pushFacade.subscribeOn( + topics: [ + userProfileChangedTopic, + logoutTopic, + loginSuccessTopic, + loginFailedTopic, + ], + ).listen((event) async { + // 当收到用户信息更变、登出事件、登录成功事件时，重新加载用户信息 + if (event.topic == logoutTopic || event.topic == loginSuccessTopic) { + OneAppEventBus.fireEvent(UserLoginEvent(loginType: LoginOutType.all)); + add(const PersonalCenterEvent.loadUserProfile()); + add(const PersonalCenterEvent.loadSocialInfor()); + } + }); + + // 监听积分变更事件 + _pointsChageEvent = OneAppEventBus.addListen((event) { + add(const PersonalCenterEvent.loadUserPoints()); + }); + } +} + +// 实际的账户事件类型 +abstract class AccountEvent { + const AccountEvent(); +} + +class UserLoginEvent extends AccountEvent { + final LoginOutType loginType; + const UserLoginEvent({required this.loginType}); +} + +enum LoginOutType { all } +``` + +### 数据持久化 + +#### 本地存储 +- 基于 `basic_storage` 的统一存储接口 +- 用户信息安全存储 +- 登录凭证加密存储 + +#### 缓存策略 +- 用户信息内存缓存 +- 权限信息缓存 +- 网络请求缓存 + +## 依赖关系 + +### 核心依赖 +- `basic_network`: 网络请求服务 +- `basic_storage`: 本地存储服务 +- `basic_modular`: 模块化框架 +- `basic_error`: 错误处理 +- `basic_consent`: 用户同意管理 + +### 第三方集成 +- `fluwx`: 微信 SDK 集成 +- `dartz`: 函数式编程支持 +- `freezed_annotation`: 不可变类生成 + +### 业务依赖 +- `clr_setting`: 设置服务 +- `basic_track`: 埋点追踪 +- `basic_webview`: WebView 服务 + +## API 接口设计 + +### 认证接口 +```dart +// 登录 +POST /api/v1/auth/login +{ + "username": "string", + "password": "string", + "deviceId": "string" +} + +// 登出 +POST /api/v1/auth/logout +{ + "token": "string" +} + +// 刷新令牌 +POST /api/v1/auth/refresh +{ + "refreshToken": "string" +} +``` + +### 用户信息接口 +```dart +// 获取用户信息 +GET /api/v1/user/profile + +// 更新用户信息 +PUT /api/v1/user/profile +{ + "nickname": "string", + "avatar": "string", + "birthday": "string" +} +``` + +## 安全特性 + +### 数据安全 +- 密码哈希存储 +- 敏感信息加密 +- 通信 HTTPS 加密 + +### 认证安全 +- JWT 令牌机制 +- 令牌过期机制 +- 设备绑定验证 + +### 隐私保护 +- 用户同意管理 +- 数据最小化收集 +- 隐私设置支持 + +## 错误处理 + +### 错误分类 +- 网络错误 +- 认证错误 +- 业务逻辑错误 +- 系统错误 + +### 错误处理策略 +基于实际项目中的异常处理模式，使用 Functional Programming 的 Either 模式。 + +```dart +// 实际项目中的异常处理示例 +sealed class AuthFailure { + const AuthFailure(); +} + +class OtherError extends AuthFailure { + final dynamic error; + const OtherError(this.error); +} + +sealed class ProfileFailure { + const ProfileFailure(); +} + +sealed class GarageFailure { + const GarageFailure(); +} + +// 错误处理方法示例（来自 PersonalCenterBloc） +void _onLoginFailed(LoginFailure failure) { + final authFailure = failure.cause; + + if (authFailure is OtherError) { + // 其他异常 + _handleOtherAuthFailure(authFailure.error); + } +} + +void _handleOtherAuthFailure(dynamic error) { + if (error is ErrorGlobalBusiness) { + // 云端异常 + final Map errorConfig = error.errorConfig; + final String? originalCode = errorConfig['originalCode'] as String?; + + // 处理特定错误码 + if (originalCode == '10444105') { + // 预注销状态处理 + _showPreSignOutDialog(/*参数*/); + } + } +} + +// 使用 Either 模式的接口返回值 +Future> fetchUserProfile(); +Future>> getEnrollmentVehicleList(); +Future> undoSignOut(String refCode); +``` + +## 国际化支持 + +### 支持语言 +- 中文（简体） +- 英文 +- 其他地区语言扩展 + +### 配置方式 +- 基于 `basic_intl` 的国际化框架 +- 动态语言切换 +- 文本资源管理 + +## 测试策略 + +### 单元测试 +- 领域逻辑测试 +- 服务接口测试 +- 工具类测试 + +### 集成测试 +- API 接口测试 +- 数据存储测试 +- 第三方服务集成测试 + +### UI 测试 +- 登录流程测试 +- 注册流程测试 +- 用户信息管理测试 + +## 性能优化 + +### 网络优化 +- 请求缓存 +- 批量请求 +- 网络重试机制 + +### 内存优化 +- 对象池管理 +- 图片缓存优化 +- 内存泄漏防护 + +### 启动优化 +- 懒加载机制 +- 预加载策略 +- 冷启动优化 + +## 监控与统计 + +### 用户行为统计 +- 登录成功率 +- 注册转化率 +- 功能使用统计 + +### 性能监控 +- 接口响应时间 +- 错误率统计 +- 崩溃率监控 + +### 业务指标 +- 活跃用户数 +- 用户留存率 +- 功能使用频次 + +## 开发指南 + +### 环境搭建 +1. 安装 Flutter SDK >=2.10.5 +2. 配置依赖项目路径 +3. 运行 `flutter pub get` + +### 代码规范 +- 遵循 Dart 编码规范 +- 使用 `analysis_options.yaml` 静态分析 +- 提交前代码格式化 + +### 调试技巧 +- 使用 `basic_logger` 记录日志 +- 网络请求调试 +- 状态变更追踪 + +## 版本历史 + +### v0.2.24 (当前版本) +- 支持微信登录集成 +- 优化用户信息缓存机制 +- 增强安全认证流程 + +### 后续规划 +- 支持更多第三方登录 +- 增强生物识别认证 +- 优化性能和用户体验 + +## 总结 + +`clr_account` 作为 OneApp 的账户核心 SDK，提供了完整的用户认证和管理功能。模块采用清晰的分层架构，具有良好的可扩展性和可维护性，为整个应用的用户体系提供了坚实的基础。 diff --git a/account/jverify.md b/account/jverify.md new file mode 100644 index 0000000..2f8d234 --- /dev/null +++ b/account/jverify.md @@ -0,0 +1,671 @@ +# JVerify 极验验证插件文档 + +## 插件概述 + +`jverify` 是 OneApp 集成的极验验证 Flutter 插件，提供一键登录、短信验证等安全认证功能。该插件封装了极验验证的 Android 和 iOS SDK，为 Flutter 应用提供统一的验证接口。 + +### 基本信息 +- **插件名称**: jverify +- **类型**: Flutter Plugin +- **平台支持**: Android, iOS +- **功能**: 一键登录、短信验证、SDK 初始化 + +## 目录结构 + +``` +jverify/ +├── lib/ +│ └── jverify.dart # Flutter 接口层 +├── android/ # Android 原生实现 +│ ├── src/main/ +│ │ ├── AndroidManifest.xml # Android 清单文件 +│ │ ├── java/ # Java/Kotlin 源码 +│ │ └── libs/ # 第三方库文件 +│ └── build.gradle # Android 构建配置 +├── ios/ # iOS 原生实现 +│ ├── Classes/ # Objective-C/Swift 源码 +│ ├── Assets/ # iOS 资源文件 +│ └── jverify.podspec # CocoaPods 配置 +├── documents/ # 文档目录 +├── pubspec.yaml # Flutter 插件配置 +└── README.md # 项目说明 +``` + +## Flutter 接口层 (lib/jverify.dart) + +### 核心回调类型定义 + +#### 1. 事件监听器定义 +```dart +// 自定义控件点击事件监听器 +typedef JVClickWidgetEventListener = void Function(String widgetId); + +// 授权页事件回调监听器 +typedef JVAuthPageEventListener = void Function(JVAuthPageEvent event); + +// 一键登录回调监听器 +typedef JVLoginAuthCallBackListener = void Function(JVListenerEvent event); + +// 短信登录回调监听器 +typedef JVSMSListener = void Function(JVSMSEvent event); + +// SDK 初始化回调监听器 +typedef JVSDKSetupCallBackListener = void Function(JVSDKSetupEvent event); +``` + +#### 2. 事件数据模型 +```dart +// 一键登录事件 +class JVListenerEvent { + final int code; // 返回码：6000成功，6001失败 + final String message; // 返回信息或loginToken + final String operator; // 运营商：CM移动，CU联通，CT电信 +} + +// 短信验证事件 +class JVSMSEvent { + final int code; // 返回码 + final String message; // 返回信息 + final String phone; // 手机号 +} + +// SDK 初始化事件 +class JVSDKSetupEvent { + final int code; // 返回码：8000成功 + final String message; // 返回信息 +} + +// 授权页事件 +class JVAuthPageEvent { + final String eventType; // 事件类型 + final Map data; // 事件数据 +} +``` + +### 主要接口方法 + +#### 1. SDK 初始化 +```dart +class Jverify { + // 初始化 SDK + static Future setup({ + required String appKey, + required String channel, + bool isProduction = true, + JVSDKSetupCallBackListener? setupListener, + }); + + // 检查初始化状态 + static Future isSetup(); +} +``` + +#### 2. 一键登录 +```dart +// 预初始化 +static Future preLogin({ + int timeOut = 5000, + JVLoginAuthCallBackListener? preLoginListener, +}); + +// 判断网络环境是否支持 +static Future checkVerifyEnable({ + JVLoginAuthCallBackListener? checkListener, +}); + +// 获取登录 Token +static Future loginAuth({ + bool autoDismiss = true, + int timeOut = 5000, + JVLoginAuthCallBackListener? loginListener, +}); + +// 自定义授权页面 +static Future setCustomAuthorizationView({ + required Map config, + JVClickWidgetEventListener? clickListener, + JVAuthPageEventListener? authPageEventListener, +}); +``` + +#### 3. 短信验证 +```dart +// 获取短信验证码 +static Future getSMSCode({ + required String phoneNumber, + String? signID, + String? tempID, + JVSMSListener? smsListener, +}); + +// 短信验证登录 +static Future smsAuth({ + required String phoneNumber, + required String smsCode, + JVSMSListener? smsListener, +}); +``` + +#### 4. 页面控制 +```dart +// 关闭授权页面 +static Future dismissLoginAuth(); + +// 清除预取号缓存 +static Future clearPreLoginCache(); + +// 设置调试模式 +static Future setDebugMode(bool enable); +``` + +## Android 原生实现 + +### 项目结构 +``` +android/ +├── src/main/ +│ ├── AndroidManifest.xml # 权限和组件配置 +│ ├── java/com/jverify/ # Java 实现代码 +│ │ ├── JverifyPlugin.java # 插件主类 +│ │ ├── JVerifyHelper.java # 辅助工具类 +│ │ └── utils/ # 工具类 +│ └── libs/ # 极验 SDK 库文件 +│ ├── jverify-android-*.jar +│ └── jcore-android-*.jar +└── build.gradle # 构建配置 +``` + +### 关键实现文件 + +#### 1. JverifyPlugin.java - 插件主类 +```java +public class JverifyPlugin implements FlutterPlugin, MethodCallHandler { + + // 方法通道 + private MethodChannel channel; + + // 极验 SDK API 接口 + private JVerifyInterface jVerifyInterface; + + @Override + public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) { + channel = new MethodChannel(binding.getBinaryMessenger(), "jverify"); + channel.setMethodCallHandler(this); + } + + @Override + public void onMethodCall(@NonNull MethodCall call, @NonNull Result result) { + switch (call.method) { + case "setup": + initSDK(call, result); + break; + case "checkVerifyEnable": + checkVerifyEnable(call, result); + break; + case "preLogin": + preLogin(call, result); + break; + case "loginAuth": + loginAuth(call, result); + break; + case "getSMSCode": + getSMSCode(call, result); + break; + case "smsAuth": + smsAuth(call, result); + break; + case "dismissLoginAuth": + dismissLoginAuth(result); + break; + default: + result.notImplemented(); + } + } +} +``` + +#### 2. 核心功能实现 +```java +// SDK 初始化 +private void initSDK(MethodCall call, Result result) { + String appKey = call.argument("appKey"); + String channel = call.argument("channel"); + boolean isProduction = call.argument("isProduction"); + + JVerifyInterface.init(getApplicationContext(), appKey, channel, isProduction); + JVerifyInterface.setDebugMode(true); + + // 设置初始化回调 + JVerifyInterface.setInitListener(new InitListener() { + @Override + public void onResult(int code, String message) { + // 回调到 Flutter + Map args = new HashMap<>(); + args.put("code", code); + args.put("message", message); + channel.invokeMethod("onSDKSetup", args); + } + }); +} + +// 一键登录 +private void loginAuth(MethodCall call, Result result) { + boolean autoDismiss = call.argument("autoDismiss"); + int timeOut = call.argument("timeOut"); + + JVerifyInterface.loginAuth(getCurrentActivity(), autoDismiss, timeOut, + new LoginAuthListener() { + @Override + public void onResult(int code, String content, String operator) { + Map args = new HashMap<>(); + args.put("code", code); + args.put("message", content); + args.put("operator", operator); + channel.invokeMethod("onLoginAuth", args); + } + }); +} +``` + +### Android 配置 + +#### AndroidManifest.xml 权限配置 +```xml + + + + + + + + + + + + + + + + + + + + + +``` + +#### build.gradle 配置 +```gradle +android { + compileSdkVersion 33 + + defaultConfig { + minSdkVersion 19 + targetSdkVersion 33 + } + + buildTypes { + release { + manifestPlaceholders = [ + JVERIFY_APPKEY: project.hasProperty('JVERIFY_APPKEY') ? JVERIFY_APPKEY : '', + JVERIFY_CHANNEL: project.hasProperty('JVERIFY_CHANNEL') ? JVERIFY_CHANNEL : 'developer-default' + ] + } + } +} + +dependencies { + implementation 'androidx.appcompat:appcompat:1.4.0' + implementation fileTree(dir: 'libs', include: ['*.jar']) +} +``` + +## iOS 原生实现 + +### 项目结构 +``` +ios/ +├── Classes/ +│ ├── JverifyPlugin.h # 插件头文件 +│ ├── JverifyPlugin.m # 插件实现文件 +│ └── JVerifyHelper.h/m # 辅助工具类 +├── Assets/ # 资源文件 +├── Frameworks/ # 极验 SDK 框架 +│ └── JVERIFYService.framework +└── jverify.podspec # CocoaPods 配置 +``` + +### 关键实现文件 + +#### 1. JverifyPlugin.h - 插件头文件 +```objc +#import +#import + +@interface JverifyPlugin : NSObject + +@property (nonatomic, strong) FlutterMethodChannel *channel; + +@end +``` + +#### 2. JverifyPlugin.m - 插件实现 +```objc +@implementation JverifyPlugin + ++ (void)registerWithRegistrar:(NSObject*)registrar { + FlutterMethodChannel* channel = [FlutterMethodChannel + methodChannelWithName:@"jverify" + binaryMessenger:[registrar messenger]]; + + JverifyPlugin* instance = [[JverifyPlugin alloc] init]; + instance.channel = channel; + [registrar addMethodCallDelegate:instance channel:channel]; +} + +- (void)handleMethodCall:(FlutterMethodCall*)call result:(FlutterResult)result { + if ([@"setup" isEqualToString:call.method]) { + [self initSDK:call result:result]; + } else if ([@"checkVerifyEnable" isEqualToString:call.method]) { + [self checkVerifyEnable:call result:result]; + } else if ([@"preLogin" isEqualToString:call.method]) { + [self preLogin:call result:result]; + } else if ([@"loginAuth" isEqualToString:call.method]) { + [self loginAuth:call result:result]; + } else if ([@"getSMSCode" isEqualToString:call.method]) { + [self getSMSCode:call result:result]; + } else if ([@"smsAuth" isEqualToString:call.method]) { + [self smsAuth:call result:result]; + } else if ([@"dismissLoginAuth" isEqualToString:call.method]) { + [self dismissLoginAuth:result]; + } else { + result(FlutterMethodNotImplemented); + } +} + +// SDK 初始化 +- (void)initSDK:(FlutterMethodCall*)call result:(FlutterResult)result { + NSString *appKey = call.arguments[@"appKey"]; + NSString *channel = call.arguments[@"channel"]; + BOOL isProduction = [call.arguments[@"isProduction"] boolValue]; + + [JVERIFYService setupWithAppkey:appKey channel:channel apsForProduction:isProduction]; + + // 设置初始化回调 + [JVERIFYService setInitHandler:^(JVInitResultModel *result) { + NSDictionary *args = @{ + @"code": @(result.code), + @"message": result.message ?: @"" + }; + [self.channel invokeMethod:@"onSDKSetup" arguments:args]; + }]; + + result(@(YES)); +} + +// 一键登录 +- (void)loginAuth:(FlutterMethodCall*)call result:(FlutterResult)result { + BOOL autoDismiss = [call.arguments[@"autoDismiss"] boolValue]; + NSTimeInterval timeOut = [call.arguments[@"timeOut"] doubleValue] / 1000.0; + + [JVERIFYService getAuthorizationWithController:[self getCurrentViewController] + completion:^(JVAuthorizationResultModel *result) { + NSDictionary *args = @{ + @"code": @(result.code), + @"message": result.content ?: @"", + @"operator": result.operator ?: @"" + }; + [self.channel invokeMethod:@"onLoginAuth" arguments:args]; + }]; + + result(@(YES)); +} + +@end +``` + +### iOS 配置 + +#### jverify.podspec +```ruby +Pod::Spec.new do |s| + s.name = 'jverify' + s.version = '1.0.0' + s.summary = 'JVerify Flutter Plugin' + s.description = 'A Flutter plugin for JVerify SDK' + s.homepage = 'https://www.jiguang.cn' + s.license = { :file => '../LICENSE' } + s.author = { 'JiGuang' => 'support@jiguang.cn' } + + s.source = { :path => '.' } + s.source_files = 'Classes/**/*' + s.public_header_files = 'Classes/**/*.h' + + s.dependency 'Flutter' + s.dependency 'JVerify', '~> 2.8.0' + + s.platform = :ios, '9.0' + s.ios.deployment_target = '9.0' + + s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' } + s.swift_version = '5.0' +end +``` + +#### Info.plist 配置 +```xml + + + NSAppTransportSecurity + + NSAllowsArbitraryLoads + + + + + NSPhotoLibraryUsageDescription + 此应用需要访问相册来选择头像 + + + NSContactsUsageDescription + 此应用需要访问通讯录进行一键登录 + +``` + +## 使用示例 + +### 基本集成 +```dart +import 'package:jverify/jverify.dart'; + +class LoginPage extends StatefulWidget { + @override + _LoginPageState createState() => _LoginPageState(); +} + +class _LoginPageState extends State { + + @override + void initState() { + super.initState(); + _initJVerify(); + } + + // 初始化 JVerify SDK + void _initJVerify() async { + await Jverify.setup( + appKey: "your_app_key", + channel: "developer-default", + isProduction: false, + setupListener: (JVSDKSetupEvent event) { + if (event.code == 8000) { + print("SDK 初始化成功"); + _preLogin(); + } else { + print("SDK 初始化失败: ${event.message}"); + } + }, + ); + } + + // 预登录 + void _preLogin() async { + await Jverify.preLogin( + preLoginListener: (JVListenerEvent event) { + if (event.code == 6000) { + print("预登录成功"); + } + }, + ); + } + + // 一键登录 + void _oneClickLogin() async { + await Jverify.loginAuth( + loginListener: (JVListenerEvent event) { + if (event.code == 6000) { + String loginToken = event.message; + // 使用 loginToken 进行后续验证 + _verifyTokenWithServer(loginToken); + } else { + print("一键登录失败: ${event.message}"); + } + }, + ); + } + + // 短信登录 + void _smsLogin(String phoneNumber, String smsCode) async { + await Jverify.smsAuth( + phoneNumber: phoneNumber, + smsCode: smsCode, + smsListener: (JVSMSEvent event) { + if (event.code == 6000) { + print("短信登录成功"); + } + }, + ); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + body: Column( + children: [ + ElevatedButton( + onPressed: _oneClickLogin, + child: Text("一键登录"), + ), + ElevatedButton( + onPressed: () => _getSMSCode("13800138000"), + child: Text("获取验证码"), + ), + ], + ), + ); + } +} +``` + +## 错误码说明 + +### 通用错误码 +- **8000**: SDK 初始化成功 +- **8001**: SDK 初始化失败 +- **6000**: 登录获取 loginToken 成功 +- **6001**: 登录获取 loginToken 失败 +- **6002**: 网络连接失败 +- **6003**: 请求超时 +- **6004**: 运营商网络未知 + +### 一键登录错误码 +- **6005**: 手机号不支持此运营商 +- **6006**: 用户取消登录 +- **6007**: 登录环境异常 +- **6008**: 登录失败，未知异常 + +### 短信验证错误码 +- **3000**: 短信验证码发送成功 +- **3001**: 短信验证码发送失败 +- **3002**: 短信验证码验证成功 +- **3003**: 短信验证码验证失败 + +## 性能优化 + +### 网络优化 +- 预登录机制减少用户等待时间 +- 智能重试机制提高成功率 +- 网络状态检测优化用户体验 + +### 内存优化 +- 及时释放不用的资源 +- 避免内存泄漏 +- 合理管理生命周期 + +### 用户体验优化 +- 自定义授权页面样式 +- 加载状态指示 +- 错误提示优化 + +## 安全特性 + +### 数据安全 +- 通信数据加密传输 +- 敏感信息本地加密存储 +- 防止中间人攻击 + +### 业务安全 +- 防刷机制 +- 设备指纹验证 +- 异常行为检测 + +## 测试指南 + +### 单元测试 +- SDK 接口调用测试 +- 错误处理测试 +- 边界条件测试 + +### 集成测试 +- 端到端登录流程测试 +- 多平台兼容性测试 +- 网络异常处理测试 + +### 性能测试 +- 初始化耗时测试 +- 内存使用测试 +- 并发请求测试 + +## 故障排除 + +### 常见问题 +1. **初始化失败**: 检查 AppKey 和渠道配置 +2. **网络错误**: 检查网络权限和网络连接 +3. **登录失败**: 检查运营商网络环境 +4. **权限不足**: 检查必要权限的授权状态 + +### 调试技巧 +- 开启调试模式查看详细日志 +- 使用网络抓包工具分析请求 +- 检查设备网络环境和运营商 + +## 版本更新 + +### 当前版本特性 +- 支持三大运营商一键登录 +- 支持短信验证码登录 +- 支持自定义授权页面 +- 完善的错误处理机制 + +### 后续规划 +- 支持更多认证方式 +- 优化用户体验 +- 增强安全防护 + +## 总结 + +`jverify` 插件为 OneApp 提供了完整的极验验证解决方案，通过封装原生 SDK，为 Flutter 应用提供了统一、便捷的验证接口。插件具有良好的跨平台兼容性和完善的错误处理机制，能够满足移动应用的各种验证场景需求。 diff --git a/after_sales/README.md b/after_sales/README.md new file mode 100644 index 0000000..be41ca4 --- /dev/null +++ b/after_sales/README.md @@ -0,0 +1,131 @@ +# After Sales 售后服务模块群 + +## 模块群概述 + +After Sales 模块群是 OneApp 的售后服务业务模块集合，提供了完整的汽车售后服务功能。该模块群包含了维修预约、服务记录、技师派工、客户满意度调查等核心售后业务功能。 + +## 子模块列表 + +### 核心模块 +1. **[oneapp_after_sales](./oneapp_after_sales.md)** - 售后服务主模块 + - 维修预约和服务管理 + - 服务记录和历史查询 + - 客户端售后功能入口 + +2. **[clr_after_sales](./clr_after_sales.md)** - 售后服务SDK + - 售后服务业务逻辑封装 + - API接口统一管理 + - 数据模型定义 + +## 功能特性 + +### 核心业务功能 +1. **维修预约服务** + - 在线预约维修时间 + - 服务门店选择 + - 预约状态跟踪 + - 预约变更和取消 + +2. **服务记录管理** + - 维修历史记录 + - 服务项目详情 + - 费用明细查看 + - 服务评价反馈 + +3. **技师服务管理** + - 技师信息展示 + - 服务进度跟踪 + - 实时沟通功能 + - 服务质量评估 + +4. **客户体验优化** + - 服务满意度调查 + - 投诉建议处理 + - 会员权益服务 + - 增值服务推荐 + +## 技术架构 + +### 模块架构图 +``` +售后服务应用层 (oneapp_after_sales) + ↓ +售后服务SDK (clr_after_sales) + ↓ +基础服务层 (basic_*) + ↓ +原生平台能力 +``` + +### 主要依赖 +- **地图服务**: ui_mapview, amap_flutter_location +- **支付服务**: kit_alipay, fluwx +- **图片处理**: photo_view, photo_gallery +- **电子签名**: signature +- **权限管理**: permission_handler +- **网络通信**: dio +- **WebView**: basic_webview + +## 业务流程 + +### 维修预约流程 +```mermaid +graph TD + A[用户发起预约] --> B[选择服务类型] + B --> C[选择服务门店] + C --> D[选择预约时间] + D --> E[填写车辆信息] + E --> F[确认预约信息] + F --> G[支付定金] + G --> H[预约成功] + H --> I[门店确认] + I --> J[服务执行] + J --> K[服务完成] + K --> L[客户评价] +``` + +### 服务执行流程 +```mermaid +graph TD + A[客户到店] --> B[接车检查] + B --> C[故障诊断] + C --> D[制定维修方案] + D --> E[客户确认] + E --> F[开始维修] + F --> G[维修过程] + G --> H[质量检验] + H --> I[交车准备] + I --> J[客户验收] + J --> K[结算付款] + K --> L[服务完成] +``` + +## 详细模块文档 + +- [OneApp After Sales - 售后服务主模块](./oneapp_after_sales.md) +- [CLR After Sales - 售后服务SDK](./clr_after_sales.md) + +## 开发指南 + +### 环境要求 +- Flutter >=1.17.0 +- Dart >=3.0.0 <4.0.0 +- Android SDK >=21 +- iOS >=11.0 + +### 快速开始 +```dart +// 初始化售后服务模块 +await AfterSalesService.initialize(); + +// 创建维修预约 +final appointment = await AfterSalesService.createAppointment( + serviceType: ServiceType.maintenance, + storeId: 'store_123', + appointmentTime: DateTime.now().add(Duration(days: 1)), +); +``` + +## 总结 + +After Sales 模块群为 OneApp 提供了完整的售后服务解决方案，通过标准化的业务流程和用户友好的界面设计，提升了售后服务的效率和客户满意度。模块群具有良好的扩展性，能够适应不同的售后服务场景和业务需求。 diff --git a/after_sales/clr_after_sales.md b/after_sales/clr_after_sales.md new file mode 100644 index 0000000..2ca1d0c --- /dev/null +++ b/after_sales/clr_after_sales.md @@ -0,0 +1,726 @@ +# CLR After Sales 售后服务SDK + +## 模块概述 + +`clr_after_sales` 是 OneApp 售后服务模块群中的核心服务SDK，负责封装售后服务的业务逻辑、API接口调用和数据模型定义。该模块为售后服务应用层提供统一的服务接口和数据处理能力。 + +### 基本信息 +- **模块名称**: clr_after_sales +- **版本**: 0.0.1 +- **描述**: 售后服务核心SDK +- **Flutter 版本**: >=1.17.0 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **API接口封装** + - 售后服务API统一封装 + - 网络请求统一处理 + - 错误处理和重试机制 + - 数据缓存和同步 + +2. **业务逻辑封装** + - 预约业务逻辑 + - 服务流程管理 + - 支付结算逻辑 + - 数据验证规则 + +3. **数据模型管理** + - 统一数据模型定义 + - JSON序列化支持 + - 数据转换和映射 + - 模型验证机制 + +4. **状态管理** + - 业务状态统一管理 + - 事件驱动更新 + - 状态持久化 + - 状态同步机制 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── clr_after_sales.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── services/ # 业务服务 +│ ├── repositories/ # 数据仓库 +│ ├── models/ # 数据模型 +│ ├── enums/ # 枚举定义 +│ ├── exceptions/ # 异常定义 +│ ├── utils/ # 工具类 +│ └── constants/ # 常量定义 +├── test/ # 测试文件 +└── generated/ # 代码生成文件 +``` + +### 依赖关系 + +#### 基础框架依赖 +- `basic_network: ^0.2.3+4` - 网络通信框架 +- `common_utils: ^2.1.0` - 通用工具库 + +#### 内部依赖 (dependency_overrides) +- `ui_basic` - 基础UI组件（本地路径） +- `basic_platform` - 平台适配（本地路径） +- `basic_utils` - 基础工具（本地路径） +- `basic_uis` - 基础UI集合（本地路径） +- `base_mvvm` - MVVM架构（本地路径） + +## 核心模块分析 + +### 1. 业务服务 (`src/services/`) + +#### 预约服务 +```dart +class AppointmentService { + final AppointmentRepository _repository; + final NetworkService _networkService; + + AppointmentService(this._repository, this._networkService); + + /// 创建预约 + Future> createAppointment( + AppointmentCreateRequest request, + ) async { + try { + // 1. 验证请求数据 + final validationResult = _validateCreateRequest(request); + if (validationResult.isFailure) { + return Result.failure(validationResult.error); + } + + // 2. 检查时间可用性 + final availability = await checkTimeAvailability( + request.storeId, + request.appointmentTime, + ); + + if (!availability.isAvailable) { + return Result.failure( + AppointmentException('预约时间不可用'), + ); + } + + // 3. 调用API创建预约 + final apiResponse = await _networkService.post( + '/appointments', + data: request.toJson(), + ); + + // 4. 解析响应数据 + final appointment = Appointment.fromJson(apiResponse.data); + + // 5. 缓存到本地 + await _repository.saveAppointment(appointment); + + return Result.success(appointment); + } catch (e) { + return Result.failure(AppointmentException(e.toString())); + } + } + + /// 获取用户预约列表 + Future>> getUserAppointments({ + String? status, + int page = 1, + int pageSize = 20, + }) async { + try { + // 1. 先从缓存获取 + final cachedAppointments = await _repository.getCachedAppointments( + status: status, + page: page, + pageSize: pageSize, + ); + + // 2. 如果缓存存在且未过期，直接返回 + if (cachedAppointments.isNotEmpty && !_isCacheExpired()) { + return Result.success(cachedAppointments); + } + + // 3. 从网络获取最新数据 + final apiResponse = await _networkService.get( + '/appointments', + queryParameters: { + 'status': status, + 'page': page, + 'pageSize': pageSize, + }, + ); + + // 4. 解析并缓存数据 + final appointments = (apiResponse.data['items'] as List) + .map((json) => Appointment.fromJson(json)) + .toList(); + + await _repository.cacheAppointments(appointments); + + return Result.success(appointments); + } catch (e) { + return Result.failure(AppointmentException(e.toString())); + } + } + + /// 取消预约 + Future> cancelAppointment(String appointmentId) async { + try { + await _networkService.put( + '/appointments/$appointmentId/cancel', + ); + + // 更新本地缓存 + await _repository.updateAppointmentStatus( + appointmentId, + AppointmentStatus.cancelled, + ); + + return Result.success(true); + } catch (e) { + return Result.failure(AppointmentException(e.toString())); + } + } +} +``` + +#### 服务进度服务 +```dart +class ServiceProgressService { + final ServiceProgressRepository _repository; + final NetworkService _networkService; + + ServiceProgressService(this._repository, this._networkService); + + /// 获取服务进度 + Future> getServiceProgress( + String appointmentId, + ) async { + try { + final apiResponse = await _networkService.get( + '/appointments/$appointmentId/progress', + ); + + final progress = ServiceProgress.fromJson(apiResponse.data); + + // 缓存进度数据 + await _repository.saveProgress(progress); + + return Result.success(progress); + } catch (e) { + return Result.failure(ServiceException(e.toString())); + } + } + + /// 更新服务步骤 + Future> updateServiceStep( + String appointmentId, + String stepId, + ServiceStepUpdate update, + ) async { + try { + final apiResponse = await _networkService.put( + '/appointments/$appointmentId/steps/$stepId', + data: update.toJson(), + ); + + final updatedStep = ServiceStep.fromJson(apiResponse.data); + + // 更新本地缓存 + await _repository.updateStep(appointmentId, updatedStep); + + return Result.success(updatedStep); + } catch (e) { + return Result.failure(ServiceException(e.toString())); + } + } + + /// 上传服务照片 + Future> uploadServicePhoto( + String appointmentId, + String stepId, + File photoFile, + ) async { + try { + final formData = FormData.fromMap({ + 'file': await MultipartFile.fromFile(photoFile.path), + 'appointmentId': appointmentId, + 'stepId': stepId, + }); + + final apiResponse = await _networkService.post( + '/service-photos/upload', + data: formData, + ); + + final photo = ServicePhoto.fromJson(apiResponse.data); + + return Result.success(photo); + } catch (e) { + return Result.failure(ServiceException(e.toString())); + } + } +} +``` + +### 2. 数据仓库 (`src/repositories/`) + +#### 预约数据仓库 +```dart +abstract class AppointmentRepository { + Future saveAppointment(Appointment appointment); + Future> getCachedAppointments({ + String? status, + int page = 1, + int pageSize = 20, + }); + Future cacheAppointments(List appointments); + Future updateAppointmentStatus(String id, AppointmentStatus status); + Future clearCache(); +} + +class AppointmentRepositoryImpl implements AppointmentRepository { + final LocalStorage _localStorage; + final DatabaseHelper _databaseHelper; + + AppointmentRepositoryImpl(this._localStorage, this._databaseHelper); + + @override + Future saveAppointment(Appointment appointment) async { + try { + // 保存到数据库 + await _databaseHelper.insertAppointment(appointment); + + // 更新缓存 + final cacheKey = 'appointment_${appointment.id}'; + await _localStorage.setString(cacheKey, jsonEncode(appointment.toJson())); + } catch (e) { + throw RepositoryException('保存预约失败: $e'); + } + } + + @override + Future> getCachedAppointments({ + String? status, + int page = 1, + int pageSize = 20, + }) async { + try { + return await _databaseHelper.getAppointments( + status: status, + offset: (page - 1) * pageSize, + limit: pageSize, + ); + } catch (e) { + throw RepositoryException('获取缓存预约失败: $e'); + } + } + + @override + Future updateAppointmentStatus(String id, AppointmentStatus status) async { + try { + await _databaseHelper.updateAppointmentStatus(id, status); + + // 更新内存缓存 + final cacheKey = 'appointment_$id'; + final cachedData = await _localStorage.getString(cacheKey); + if (cachedData != null) { + final appointment = Appointment.fromJson(jsonDecode(cachedData)); + final updatedAppointment = appointment.copyWith(status: status); + await _localStorage.setString( + cacheKey, + jsonEncode(updatedAppointment.toJson()), + ); + } + } catch (e) { + throw RepositoryException('更新预约状态失败: $e'); + } + } +} +``` + +### 3. 数据模型 (`src/models/`) + +#### 预约模型 +```dart +@freezed +class Appointment with _$Appointment { + const factory Appointment({ + required String id, + required String userId, + required String storeId, + required ServiceType serviceType, + required DateTime appointmentTime, + required AppointmentStatus status, + required VehicleInfo vehicleInfo, + String? description, + List? attachments, + @JsonKey(name: 'created_at') DateTime? createdAt, + @JsonKey(name: 'updated_at') DateTime? updatedAt, + Store? store, + List? serviceItems, + PaymentInfo? paymentInfo, + }) = _Appointment; + + factory Appointment.fromJson(Map json) => + _$AppointmentFromJson(json); +} + +@freezed +class AppointmentCreateRequest with _$AppointmentCreateRequest { + const factory AppointmentCreateRequest({ + required String storeId, + required ServiceType serviceType, + required DateTime appointmentTime, + required VehicleInfo vehicleInfo, + String? description, + List? attachments, + List? serviceItemIds, + }) = _AppointmentCreateRequest; + + factory AppointmentCreateRequest.fromJson(Map json) => + _$AppointmentCreateRequestFromJson(json); +} +``` + +#### 服务进度模型 +```dart +@freezed +class ServiceProgress with _$ServiceProgress { + const factory ServiceProgress({ + required String appointmentId, + required ServiceStatus status, + required List steps, + required double progressPercentage, + @JsonKey(name: 'estimated_completion') DateTime? estimatedCompletion, + @JsonKey(name: 'actual_completion') DateTime? actualCompletion, + Technician? assignedTechnician, + List? photos, + String? currentStepNote, + }) = _ServiceProgress; + + factory ServiceProgress.fromJson(Map json) => + _$ServiceProgressFromJson(json); +} + +@freezed +class ServiceStep with _$ServiceStep { + const factory ServiceStep({ + required String id, + required String name, + required String description, + required ServiceStepStatus status, + required int orderIndex, + @JsonKey(name: 'started_at') DateTime? startedAt, + @JsonKey(name: 'completed_at') DateTime? completedAt, + String? note, + List? photoIds, + Duration? estimatedDuration, + Duration? actualDuration, + }) = _ServiceStep; + + factory ServiceStep.fromJson(Map json) => + _$ServiceStepFromJson(json); +} +``` + +### 4. 枚举定义 (`src/enums/`) + +```dart +enum AppointmentStatus { + @JsonValue('pending') + pending, + @JsonValue('confirmed') + confirmed, + @JsonValue('inProgress') + inProgress, + @JsonValue('completed') + completed, + @JsonValue('cancelled') + cancelled, + @JsonValue('noShow') + noShow, +} + +enum ServiceType { + @JsonValue('maintenance') + maintenance, + @JsonValue('repair') + repair, + @JsonValue('inspection') + inspection, + @JsonValue('bodywork') + bodywork, + @JsonValue('insurance') + insurance, + @JsonValue('emergency') + emergency, + @JsonValue('recall') + recall, +} + +enum ServiceStatus { + @JsonValue('waiting') + waiting, + @JsonValue('inProgress') + inProgress, + @JsonValue('completed') + completed, + @JsonValue('paused') + paused, + @JsonValue('cancelled') + cancelled, +} + +enum ServiceStepStatus { + @JsonValue('pending') + pending, + @JsonValue('inProgress') + inProgress, + @JsonValue('completed') + completed, + @JsonValue('skipped') + skipped, +} +``` + +### 5. 异常定义 (`src/exceptions/`) + +```dart +abstract class AfterSalesException implements Exception { + final String message; + final String? code; + final dynamic details; + + const AfterSalesException(this.message, {this.code, this.details}); + + @override + String toString() => 'AfterSalesException: $message'; +} + +class AppointmentException extends AfterSalesException { + const AppointmentException(String message, {String? code, dynamic details}) + : super(message, code: code, details: details); +} + +class ServiceException extends AfterSalesException { + const ServiceException(String message, {String? code, dynamic details}) + : super(message, code: code, details: details); +} + +class PaymentException extends AfterSalesException { + const PaymentException(String message, {String? code, dynamic details}) + : super(message, code: code, details: details); +} + +class NetworkException extends AfterSalesException { + const NetworkException(String message, {String? code, dynamic details}) + : super(message, code: code, details: details); +} + +class RepositoryException extends AfterSalesException { + const RepositoryException(String message, {String? code, dynamic details}) + : super(message, code: code, details: details); +} +``` + +### 6. 结果封装 (`src/utils/result.dart`) + +```dart +@freezed +class Result with _$Result { + const factory Result.success(T data) = Success; + const factory Result.failure(Exception error) = Failure; + + bool get isSuccess => this is Success; + bool get isFailure => this is Failure; + + T? get data => mapOrNull(success: (success) => success.data); + Exception? get error => mapOrNull(failure: (failure) => failure.error); +} + +extension ResultExtensions on Result { + R fold( + R Function(T data) onSuccess, + R Function(Exception error) onFailure, + ) { + return when( + success: onSuccess, + failure: onFailure, + ); + } + + Future> mapAsync( + Future Function(T data) mapper, + ) async { + return fold( + (data) async { + try { + final result = await mapper(data); + return Result.success(result); + } catch (e) { + return Result.failure(Exception(e.toString())); + } + }, + (error) => Future.value(Result.failure(error)), + ); + } +} +``` + +## 使用示例 + +### 基础使用 +```dart +class AfterSalesExample { + final AppointmentService _appointmentService; + final ServiceProgressService _progressService; + + AfterSalesExample(this._appointmentService, this._progressService); + + Future createAppointmentExample() async { + final request = AppointmentCreateRequest( + storeId: 'store_123', + serviceType: ServiceType.maintenance, + appointmentTime: DateTime.now().add(Duration(days: 1)), + vehicleInfo: VehicleInfo( + vin: 'WVWAA71K08W201030', + licensePlate: '京A12345', + model: 'ID.4 CROZZ', + ), + description: '常规保养', + ); + + final result = await _appointmentService.createAppointment(request); + + result.fold( + (appointment) { + print('预约创建成功: ${appointment.id}'); + }, + (error) { + print('预约创建失败: ${error.toString()}'); + }, + ); + } + + Future trackServiceProgressExample(String appointmentId) async { + final result = await _progressService.getServiceProgress(appointmentId); + + result.fold( + (progress) { + print('服务进度: ${progress.progressPercentage}%'); + print('当前步骤: ${progress.steps.where((s) => s.status == ServiceStepStatus.inProgress).first.name}'); + }, + (error) { + print('获取进度失败: ${error.toString()}'); + }, + ); + } +} +``` + +### 依赖注入配置 +```dart +class AfterSalesDI { + static void setupDependencies(GetIt locator) { + // 注册仓库 + locator.registerLazySingleton( + () => AppointmentRepositoryImpl( + locator(), + locator(), + ), + ); + + locator.registerLazySingleton( + () => ServiceProgressRepositoryImpl( + locator(), + locator(), + ), + ); + + // 注册服务 + locator.registerLazySingleton( + () => AppointmentService( + locator(), + locator(), + ), + ); + + locator.registerLazySingleton( + () => ServiceProgressService( + locator(), + locator(), + ), + ); + } +} +``` + +## 测试策略 + +### 单元测试 +```dart +void main() { + group('AppointmentService', () { + late AppointmentService appointmentService; + late MockAppointmentRepository mockRepository; + late MockNetworkService mockNetworkService; + + setUp(() { + mockRepository = MockAppointmentRepository(); + mockNetworkService = MockNetworkService(); + appointmentService = AppointmentService(mockRepository, mockNetworkService); + }); + + test('should create appointment successfully', () async { + // Arrange + final request = AppointmentCreateRequest( + storeId: 'store_123', + serviceType: ServiceType.maintenance, + appointmentTime: DateTime.now().add(Duration(days: 1)), + vehicleInfo: VehicleInfo(vin: 'TEST123'), + ); + + final expectedAppointment = Appointment( + id: 'appointment_123', + userId: 'user_123', + storeId: request.storeId, + serviceType: request.serviceType, + appointmentTime: request.appointmentTime, + status: AppointmentStatus.pending, + vehicleInfo: request.vehicleInfo, + ); + + when(mockNetworkService.post('/appointments', data: any)) + .thenAnswer((_) async => ApiResponse(data: expectedAppointment.toJson())); + + // Act + final result = await appointmentService.createAppointment(request); + + // Assert + expect(result.isSuccess, true); + expect(result.data?.id, 'appointment_123'); + verify(mockRepository.saveAppointment(any)).called(1); + }); + }); +} +``` + +## 最佳实践 + +### API设计原则 +1. **统一响应格式**: 所有API使用统一的响应格式 +2. **错误处理**: 完善的错误码和错误信息 +3. **数据验证**: 严格的输入数据验证 +4. **幂等性**: 关键操作支持幂等性 + +### 缓存策略 +1. **多级缓存**: 内存缓存 + 本地存储 + 网络 +2. **缓存失效**: 基于时间和事件的缓存失效 +3. **数据一致性**: 保证缓存与服务器数据一致 +4. **离线支持**: 关键数据支持离线访问 + +## 总结 + +`clr_after_sales` 模块作为售后服务的核心SDK，通过完善的架构设计和标准化的接口封装，为售后服务应用提供了稳定可靠的技术支撑。模块采用了领域驱动设计思想，具有良好的可测试性和可维护性，能够支撑复杂的售后业务场景。 diff --git a/after_sales/oneapp_after_sales.md b/after_sales/oneapp_after_sales.md new file mode 100644 index 0000000..034346f --- /dev/null +++ b/after_sales/oneapp_after_sales.md @@ -0,0 +1,659 @@ +# OneApp After Sales 售后服务主模块 + +## 模块概述 + +`oneapp_after_sales` 是 OneApp 售后服务模块群中的主应用模块，负责为用户提供完整的汽车售后服务功能。该模块包含维修预约、服务跟踪、客户服务、支付结算等核心功能，为车主提供便捷的售后服务体验。 + +### 基本信息 +- **模块名称**: oneapp_after_sales +- **版本**: 0.0.1 +- **描述**: 售后服务主应用模块 +- **Flutter 版本**: >=1.17.0 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **维修预约管理** + - 在线预约维修服务 + - 预约时间智能调度 + - 服务门店选择和导航 + - 预约状态实时跟踪 + +2. **服务流程跟踪** + - 维修进度实时更新 + - 服务照片和视频记录 + - 技师服务过程展示 + - 完工通知和验收 + +3. **客户服务中心** + - 在线客服聊天 + - 投诉建议提交 + - 服务评价反馈 + - FAQ常见问题 + +4. **支付和结算** + - 多种支付方式支持 + - 费用明细透明展示 + - 电子发票生成 + - 会员优惠计算 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── oneapp_after_sales.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── appointment/ # 预约管理 +│ ├── service/ # 服务跟踪 +│ ├── customer/ # 客户服务 +│ ├── payment/ # 支付结算 +│ ├── store/ # 门店管理 +│ ├── pages/ # 页面组件 +│ ├── widgets/ # 自定义组件 +│ ├── models/ # 数据模型 +│ └── utils/ # 工具类 +├── assets/ # 资源文件 +└── l10n/ # 国际化文件 +``` + +### 依赖关系 + +#### 基础框架依赖 +- `basic_modular: ^0.2.3` - 模块化框架 +- `basic_modular_route: ^0.2.1` - 路由管理 +- `basic_intl: ^0.2.0` - 国际化支持 +- `basic_webview: ^0.2.4+4` - WebView组件 + +#### 地图和位置服务 +- `ui_mapview: ^0.2.18` - 地图视图组件 +- `amap_flutter_location: ^3.0.3` - 高德地图定位 +- `clr_geo: ^0.2.16+1` - 地理位置服务 +- `location_service_check: ^1.0.1` - 位置服务检查 + +#### 支付服务 +- `kit_alipay: ^0.2.0` - 支付宝支付 +- `fluwx: ^4.4.3` - 微信支付 + +#### 媒体和文件处理 +- `photo_view: ^0.14.0` - 图片预览 +- `photo_gallery: 2.2.1+1` - 相册选择 +- `signature: ^5.4.0` - 电子签名 + +#### 工具依赖 +- `permission_handler: ^10.3.0` - 权限管理 +- `url_launcher: ^6.1.14` - URL启动 +- `dio: any` - 网络请求 +- `common_utils: ^2.1.0` - 通用工具 +- `flutter_color_plugin: ^1.1.0` - 颜色工具 + +## 核心模块分析 + +### 1. 预约管理 (`src/appointment/`) + +#### 预约创建流程 +```dart +class AppointmentBookingPage extends StatefulWidget { + @override + _AppointmentBookingPageState createState() => _AppointmentBookingPageState(); +} + +class _AppointmentBookingPageState extends State { + final AppointmentBookingController _controller = AppointmentBookingController(); + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('维修预约')), + body: Stepper( + currentStep: _controller.currentStep, + onStepTapped: _controller.onStepTapped, + controlsBuilder: _buildStepControls, + steps: [ + Step( + title: Text('选择服务'), + content: ServiceTypeSelector( + selectedType: _controller.selectedServiceType, + onTypeSelected: _controller.onServiceTypeSelected, + ), + isActive: _controller.currentStep >= 0, + ), + Step( + title: Text('选择门店'), + content: StoreSelector( + location: _controller.userLocation, + selectedStore: _controller.selectedStore, + onStoreSelected: _controller.onStoreSelected, + ), + isActive: _controller.currentStep >= 1, + ), + Step( + title: Text('预约时间'), + content: TimeSlotSelector( + availableSlots: _controller.availableTimeSlots, + selectedSlot: _controller.selectedTimeSlot, + onSlotSelected: _controller.onTimeSlotSelected, + ), + isActive: _controller.currentStep >= 2, + ), + Step( + title: Text('车辆信息'), + content: VehicleInfoForm( + vehicleInfo: _controller.vehicleInfo, + onInfoChanged: _controller.onVehicleInfoChanged, + ), + isActive: _controller.currentStep >= 3, + ), + Step( + title: Text('确认预约'), + content: AppointmentSummary( + appointment: _controller.appointmentSummary, + ), + isActive: _controller.currentStep >= 4, + ), + ], + ), + ); + } +} +``` + +#### 预约管理器 +```dart +class AppointmentManager { + static Future> getUserAppointments() async { + try { + final response = await AfterSalesAPI.getUserAppointments(); + return response.data.map((json) => Appointment.fromJson(json)).toList(); + } catch (e) { + throw AppointmentException('获取预约列表失败: $e'); + } + } + + static Future createAppointment(AppointmentRequest request) async { + try { + final response = await AfterSalesAPI.createAppointment(request.toJson()); + return Appointment.fromJson(response.data); + } catch (e) { + throw AppointmentException('创建预约失败: $e'); + } + } + + static Future cancelAppointment(String appointmentId) async { + try { + await AfterSalesAPI.cancelAppointment(appointmentId); + return true; + } catch (e) { + throw AppointmentException('取消预约失败: $e'); + } + } +} +``` + +### 2. 服务跟踪 (`src/service/`) + +#### 服务进度展示 +```dart +class ServiceProgressPage extends StatefulWidget { + final String appointmentId; + + const ServiceProgressPage({Key? key, required this.appointmentId}) : super(key: key); + + @override + _ServiceProgressPageState createState() => _ServiceProgressPageState(); +} + +class _ServiceProgressPageState extends State { + ServiceProgress? _progress; + Timer? _progressTimer; + + @override + void initState() { + super.initState(); + _loadServiceProgress(); + _startProgressPolling(); + } + + @override + Widget build(BuildContext context) { + if (_progress == null) { + return Scaffold( + appBar: AppBar(title: Text('服务进度')), + body: Center(child: CircularProgressIndicator()), + ); + } + + return Scaffold( + appBar: AppBar(title: Text('服务进度')), + body: SingleChildScrollView( + padding: EdgeInsets.all(16), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + ServiceStatusCard(progress: _progress!), + SizedBox(height: 16), + ServiceTimelineWidget(steps: _progress!.steps), + SizedBox(height: 16), + if (_progress!.photos.isNotEmpty) ...[ + ServicePhotosSection(photos: _progress!.photos), + SizedBox(height: 16), + ], + TechnicianInfoCard(technician: _progress!.technician), + ], + ), + ), + ); + } + + void _startProgressPolling() { + _progressTimer = Timer.periodic(Duration(seconds: 30), (timer) { + _loadServiceProgress(); + }); + } + + @override + void dispose() { + _progressTimer?.cancel(); + super.dispose(); + } +} +``` + +#### 服务时间轴组件 +```dart +class ServiceTimelineWidget extends StatelessWidget { + final List steps; + + const ServiceTimelineWidget({Key? key, required this.steps}) : super(key: key); + + @override + Widget build(BuildContext context) { + return Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text( + '服务进度', + style: Theme.of(context).textTheme.titleLarge, + ), + SizedBox(height: 16), + Timeline.tileBuilder( + shrinkWrap: true, + physics: NeverScrollableScrollPhysics(), + builder: TimelineTileBuilder.connected( + itemCount: steps.length, + connectionDirection: ConnectionDirection.before, + itemExtentBuilder: (_, __) => 80.0, + contentsBuilder: (context, index) { + final step = steps[index]; + return Padding( + padding: EdgeInsets.all(8.0), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text( + step.title, + style: TextStyle( + fontWeight: FontWeight.bold, + color: step.isCompleted ? Colors.green : Colors.grey, + ), + ), + Text( + step.description, + style: TextStyle(fontSize: 12), + ), + if (step.completedAt != null) + Text( + DateFormat('MM-dd HH:mm').format(step.completedAt!), + style: TextStyle(fontSize: 10, color: Colors.grey), + ), + ], + ), + ); + }, + indicatorBuilder: (context, index) { + final step = steps[index]; + return DotIndicator( + color: step.isCompleted ? Colors.green : Colors.grey, + child: Icon( + step.isCompleted ? Icons.check : Icons.schedule, + color: Colors.white, + size: 16, + ), + ); + }, + connectorBuilder: (context, index, type) { + return SolidLineConnector( + color: steps[index].isCompleted ? Colors.green : Colors.grey, + ); + }, + ), + ), + ], + ); + } +} +``` + +### 3. 客户服务 (`src/customer/`) + +#### 在线客服聊天 +```dart +class CustomerServiceChatPage extends StatefulWidget { + @override + _CustomerServiceChatPageState createState() => _CustomerServiceChatPageState(); +} + +class _CustomerServiceChatPageState extends State { + final List _messages = []; + final TextEditingController _textController = TextEditingController(); + final ScrollController _scrollController = ScrollController(); + late WebSocketChannel _channel; + + @override + void initState() { + super.initState(); + _connectToCustomerService(); + _loadChatHistory(); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar( + title: Text('在线客服'), + actions: [ + IconButton( + icon: Icon(Icons.phone), + onPressed: _makePhoneCall, + ), + ], + ), + body: Column( + children: [ + Expanded( + child: ListView.builder( + controller: _scrollController, + padding: EdgeInsets.all(16), + itemCount: _messages.length, + itemBuilder: (context, index) { + return ChatMessageBubble(message: _messages[index]); + }, + ), + ), + _buildMessageInput(), + ], + ), + ); + } + + Widget _buildMessageInput() { + return Container( + padding: EdgeInsets.symmetric(horizontal: 16, vertical: 8), + decoration: BoxDecoration( + color: Colors.white, + border: Border(top: BorderSide(color: Colors.grey[300]!)), + ), + child: Row( + children: [ + IconButton( + icon: Icon(Icons.add), + onPressed: _showAttachmentOptions, + ), + Expanded( + child: TextField( + controller: _textController, + decoration: InputDecoration( + hintText: '请输入消息...', + border: OutlineInputBorder( + borderRadius: BorderRadius.circular(20), + ), + contentPadding: EdgeInsets.symmetric(horizontal: 16, vertical: 8), + ), + onSubmitted: _sendMessage, + ), + ), + SizedBox(width: 8), + IconButton( + icon: Icon(Icons.send, color: Theme.of(context).primaryColor), + onPressed: () => _sendMessage(_textController.text), + ), + ], + ), + ); + } +} +``` + +### 4. 支付结算 (`src/payment/`) + +#### 支付管理器 +```dart +class PaymentManager { + static Future processPayment({ + required PaymentMethod method, + required double amount, + required String orderId, + Map? extras, + }) async { + try { + switch (method) { + case PaymentMethod.alipay: + return await _processAlipayPayment(amount, orderId, extras); + case PaymentMethod.wechat: + return await _processWechatPayment(amount, orderId, extras); + case PaymentMethod.card: + return await _processBankCardPayment(amount, orderId, extras); + default: + throw PaymentException('不支持的支付方式'); + } + } catch (e) { + return PaymentResult.failure(error: e.toString()); + } + } + + static Future _processAlipayPayment( + double amount, + String orderId, + Map? extras, + ) async { + // 获取支付宝支付参数 + final paymentParams = await AfterSalesAPI.getAlipayParams( + amount: amount, + orderId: orderId, + extras: extras, + ); + + // 调用支付宝SDK + final result = await AlipayKit.pay(paymentParams.orderString); + + if (result.resultStatus == '9000') { + return PaymentResult.success( + transactionId: result.result, + method: PaymentMethod.alipay, + ); + } else { + return PaymentResult.failure(error: result.memo); + } + } +} +``` + +## 数据模型 + +### 预约模型 +```dart +@freezed +class Appointment with _$Appointment { + const factory Appointment({ + required String id, + required String userId, + required ServiceType serviceType, + required Store store, + required DateTime appointmentTime, + required VehicleInfo vehicleInfo, + required AppointmentStatus status, + String? description, + List? attachments, + DateTime? createdAt, + DateTime? updatedAt, + }) = _Appointment; + + factory Appointment.fromJson(Map json) => + _$AppointmentFromJson(json); +} + +enum AppointmentStatus { + pending, // 待确认 + confirmed, // 已确认 + inProgress, // 进行中 + completed, // 已完成 + cancelled, // 已取消 +} + +enum ServiceType { + maintenance, // 保养 + repair, // 维修 + inspection, // 检测 + bodywork, // 钣喷 + insurance, // 保险 + emergency, // 紧急救援 +} +``` + +### 服务进度模型 +```dart +@freezed +class ServiceProgress with _$ServiceProgress { + const factory ServiceProgress({ + required String appointmentId, + required ServiceStatus status, + required List steps, + required Technician technician, + required Store store, + @Default([]) List photos, + String? currentStepDescription, + DateTime? estimatedCompletion, + double? totalCost, + }) = _ServiceProgress; + + factory ServiceProgress.fromJson(Map json) => + _$ServiceProgressFromJson(json); +} + +@freezed +class ServiceStep with _$ServiceStep { + const factory ServiceStep({ + required String id, + required String title, + required String description, + required bool isCompleted, + DateTime? completedAt, + String? note, + }) = _ServiceStep; + + factory ServiceStep.fromJson(Map json) => + _$ServiceStepFromJson(json); +} +``` + +## 业务流程实现 + +### 预约流程管理 +```dart +class AppointmentWorkflow { + static Future executeBookingWorkflow( + AppointmentRequest request, + ) async { + try { + // 1. 验证预约时间可用性 + final availability = await _checkTimeAvailability( + request.storeId, + request.appointmentTime, + ); + + if (!availability.isAvailable) { + return AppointmentResult.failure( + error: '所选时间不可用，建议时间：${availability.suggestedTimes}', + ); + } + + // 2. 创建预约记录 + final appointment = await AppointmentManager.createAppointment(request); + + // 3. 发送确认通知 + await NotificationService.sendAppointmentConfirmation(appointment); + + // 4. 更新门店排班 + await StoreScheduleService.updateSchedule( + appointment.store.id, + appointment.appointmentTime, + ); + + return AppointmentResult.success(appointment: appointment); + } catch (e) { + return AppointmentResult.failure(error: e.toString()); + } + } +} +``` + +## 集成和测试 + +### API集成 +```dart +class AfterSalesAPI { + static const String baseUrl = 'https://api.oneapp.com/after-sales'; + static final Dio _dio = Dio(); + + static Future createAppointment(Map data) async { + final response = await _dio.post('$baseUrl/appointments', data: data); + return ApiResponse.fromJson(response.data); + } + + static Future getServiceProgress(String appointmentId) async { + final response = await _dio.get('$baseUrl/appointments/$appointmentId/progress'); + return ApiResponse.fromJson(response.data); + } +} +``` + +### 单元测试 +```dart +void main() { + group('AppointmentManager', () { + test('should create appointment successfully', () async { + final request = AppointmentRequest( + serviceType: ServiceType.maintenance, + storeId: 'store_123', + appointmentTime: DateTime.now().add(Duration(days: 1)), + vehicleInfo: VehicleInfo(vin: 'TEST123'), + ); + + final appointment = await AppointmentManager.createAppointment(request); + + expect(appointment.id, isNotEmpty); + expect(appointment.serviceType, ServiceType.maintenance); + expect(appointment.status, AppointmentStatus.pending); + }); + }); +} +``` + +## 最佳实践 + +### 用户体验优化 +1. **流程简化**: 减少预约步骤，提供智能推荐 +2. **实时反馈**: 及时更新服务进度和状态 +3. **多渠道沟通**: 提供电话、在线客服等多种联系方式 +4. **透明计费**: 清晰展示费用明细和计算过程 + +### 性能优化 +1. **数据缓存**: 缓存门店信息和服务数据 +2. **图片优化**: 压缩和缓存服务照片 +3. **网络优化**: 使用CDN加速资源加载 +4. **离线支持**: 关键信息支持离线查看 + +## 总结 + +`oneapp_after_sales` 模块作为售后服务的主要入口，通过完整的业务流程设计和用户友好的界面实现，为车主提供了便捷高效的售后服务体验。模块具有良好的扩展性和可维护性，能够适应不断变化的售后服务需求。 diff --git a/app_car/README.md b/app_car/README.md new file mode 100644 index 0000000..b88dae8 --- /dev/null +++ b/app_car/README.md @@ -0,0 +1,197 @@ +# OneApp App Car 车辆相关模块群文档 + +## 模块群概述 + +`oneapp_app_car` 是 OneApp 中最重要的模块群之一，包含了所有与车辆相关的功能模块。该模块群涵盖了车辆控制、充电管理、虚拟形象、维护保养、订单管理等核心业务功能。 + +## 模块结构总览 + +``` +oneapp_app_car/ +├── ai_chat_assistant/ # AI 聊天助手模块 +├── amap_flutter_location/ # 高德地图定位插件 +├── amap_flutter_search/ # 高德地图搜索插件 +├── app_avatar/ # 虚拟形象应用模块 +├── app_car/ # 车辆控制主模块 +├── app_carwatcher/ # 车辆监控模块 +├── app_charging/ # 充电管理模块 +├── app_composer/ # 编辑器组件模块 +├── app_maintenance/ # 维护保养模块 +├── app_order/ # 订单管理模块 +├── app_rpa/ # RPA 自动化模块 +├── app_touchgo/ # Touch&Go 功能模块 +├── app_vur/ # 车辆更新记录模块 +├── app_wallbox/ # 家充桩管理模块 +├── car_services/ # 车辆服务模块 +├── clr_avatarcore/ # 虚拟形象核心 SDK +├── clr_order/ # 订单服务 SDK +├── clr_touchgo/ # Touch&Go 服务 SDK +├── clr_wallbox/ # 家充桩服务 SDK +├── kit_rpa_plugin/ # RPA 插件工具包 +├── one_app_cache_plugin/ # 缓存插件 +└── ui_avatarx/ # 虚拟形象 UI 组件 +``` + +## 模块分类 + +### 1. 核心车辆功能模块 +- **app_car** - 车辆控制主模块，提供基础的车辆操作功能 +- **app_carwatcher** - 车辆监控模块，实时监控车辆状态 +- **car_services** - 车辆服务模块，提供各种车辆相关服务 + +### 2. 充电相关模块 +- **app_charging** - 充电管理模块，管理车辆充电功能 +- **app_wallbox** - 家充桩管理模块，管理家用充电桩 +- **clr_wallbox** - 家充桩服务 SDK + +### 3. 虚拟形象模块群 +- **app_avatar** - 虚拟形象应用模块 +- **clr_avatarcore** - 虚拟形象核心 SDK +- **ui_avatarx** - 虚拟形象 UI 组件 + +### 4. 订单和支付模块 +- **app_order** - 订单管理模块 +- **clr_order** - 订单服务 SDK + +### 5. 智能功能模块 +- **ai_chat_assistant** - AI 聊天助手模块 +- **app_touchgo** - Touch&Go 功能模块 +- **clr_touchgo** - Touch&Go 服务 SDK + +### 6. 维护和管理模块 +- **app_maintenance** - 维护保养模块 +- **app_vur** - 车辆更新记录模块 +- **app_composer** - 编辑器组件模块 + +### 7. 自动化和工具模块 +- **app_rpa** - RPA 自动化模块 +- **kit_rpa_plugin** - RPA 插件工具包 +- **one_app_cache_plugin** - 缓存插件 + +### 8. 地图和定位模块 +- **amap_flutter_location** - 高德地图定位插件 +- **amap_flutter_search** - 高德地图搜索插件 + +## 模块间依赖关系 + +```mermaid +graph TD + A[app_car 车辆控制主模块] --> B[car_services 车辆服务] + A --> C[app_carwatcher 车辆监控] + A --> D[app_charging 充电管理] + + E[app_avatar 虚拟形象] --> F[clr_avatarcore 虚拟形象核心] + E --> G[ui_avatarx 虚拟形象UI] + + H[app_order 订单管理] --> I[clr_order 订单服务] + H --> J[app_charging 充电管理] + + K[app_touchgo Touch&Go] --> L[clr_touchgo Touch&Go服务] + + M[app_wallbox 家充桩] --> N[clr_wallbox 家充桩服务] + M --> D + + O[ai_chat_assistant AI助手] --> A + O --> E +``` + +## 技术架构特点 + +### 1. 分层架构 +- **应用层** (app_*): 业务逻辑和用户界面 +- **服务层** (clr_*): 核心服务和 SDK +- **工具层** (kit_*, ui_*): 工具和 UI 组件 +- **插件层** (plugin): 原生功能插件 + +### 2. 模块化设计 +- 每个模块独立开发和测试 +- 清晰的接口定义和依赖管理 +- 支持热插拔和动态加载 + +### 3. 服务化架构 +- 微服务设计理念 +- RESTful API 接口 +- 统一的错误处理和日志记录 + +## 详细模块文档 + +- [AI Chat Assistant - AI 聊天助手](./ai_chat_assistant.md) +- [App Car - 车辆控制主模块](./app_car.md) +- [App Avatar - 虚拟形象模块](./app_avatar.md) +- [App Charging - 充电管理模块](./app_charging.md) +- [App CarWatcher - 车辆监控模块](./app_carwatcher.md) +- [App Order - 订单管理模块](./app_order.md) +- [App TouchGo - Touch&Go 功能模块](./app_touchgo.md) +- [App Wallbox - 家充桩管理模块](./app_wallbox.md) +- [App Maintenance - 维护保养模块](./app_maintenance.md) +- [App VUR - 车辆更新记录模块](./app_vur.md) +- [Car Services - 车辆服务模块](./car_services.md) +- [CLR AvatarCore - 虚拟形象核心 SDK](./clr_avatarcore.md) +- [CLR Order - 订单服务 SDK](./clr_order.md) +- [CLR TouchGo - Touch&Go 服务 SDK](./clr_touchgo.md) +- [CLR Wallbox - 家充桩服务 SDK](./clr_wallbox.md) +- [Kit RPA Plugin - RPA 插件工具包](./kit_rpa_plugin.md) +- [AMap Flutter Location - 高德地图定位插件](./amap_flutter_location.md) +- [AMap Flutter Search - 高德地图搜索插件](./amap_flutter_search.md) +- [UI AvatarX - 虚拟形象 UI 组件](./ui_avatarx.md) +- [One App Cache Plugin - 缓存插件](./one_app_cache_plugin.md) + +## 开发指南 + +### 环境要求 +- Flutter >=3.0.0 +- Dart >=3.0.0 +- Android SDK >=21 +- iOS >=11.0 + +### 构建说明 +每个模块都可以独立构建和测试，同时支持集成构建。具体的构建方式请参考各模块的详细文档。 + +### 测试策略 +- 单元测试：每个模块的核心功能 +- 集成测试：模块间的交互 +- 端到端测试：完整的用户场景 + +## 总结 + +`oneapp_app_car` 模块群是 OneApp 车主应用的核心，提供了完整的车辆相关功能生态。通过合理的模块化设计和清晰的架构分层，实现了高内聚、低耦合的设计目标，为用户提供了丰富而稳定的车辆服务体验。 + +# App Car 车辆功能模块群 + +## 模块群概述 + +App Car 模块群是 OneApp 车联网生态的核心功能集合，包含了车辆控制、充电管理、虚拟形象、维护保养等全方位的车辆相关功能模块。该模块群为用户提供了完整的智能车辆管理和控制体验。 + +## 子模块列表 + +### 应用功能模块 +1. **[ai_chat_assistant](./ai_chat_assistant.md)** - AI聊天助手模块 +2. **[app_avatar](./app_avatar.md)** - 虚拟形象应用模块 +3. **[app_car](./app_car.md)** - 车辆控制主模块 +4. **[app_carwatcher](./app_carwatcher.md)** - 车辆监控模块 +5. **[app_charging](./app_charging.md)** - 充电管理模块 +6. **[app_composer](./app_composer.md)** - 车辆编排模块 +7. **[app_maintenance](./app_maintenance.md)** - 维护保养模块 +8. **[app_order](./app_order.md)** - 订单管理模块 +9. **[app_rpa](./app_rpa.md)** - RPA自动化模块 +10. **[app_touchgo](./app_touchgo.md)** - 触控交互模块 +11. **[app_vur](./app_vur.md)** - 车辆更新记录模块 +12. **[app_wallbox](./app_wallbox.md)** - 充电墙盒模块 + +### 服务SDK模块 +13. **[car_services](./car_services.md)** - 车辆服务统一接口 +14. **[clr_avatarcore](./clr_avatarcore.md)** - 虚拟形象核心服务 +15. **[clr_order](./clr_order.md)** - 订单服务SDK +16. **[clr_touchgo](./clr_touchgo.md)** - 触控服务SDK +17. **[clr_wallbox](./clr_wallbox.md)** - 充电墙盒服务SDK + +### 原生插件模块 +18. **[kit_rpa_plugin](./kit_rpa_plugin.md)** - RPA自动化原生插件 +19. **[one_app_cache_plugin](./one_app_cache_plugin.md)** - 缓存原生插件 + +### UI组件模块 +20. **[ui_avatarx](./ui_avatarx.md)** - 虚拟形象UI组件库 + +### 第三方集成模块 +21. **amap_flutter_location** - 高德地图定位服务 +22. **amap_flutter_search** - 高德地图搜索服务 diff --git a/app_car/ai_chat_assistant.md b/app_car/ai_chat_assistant.md new file mode 100644 index 0000000..f2c4d51 --- /dev/null +++ b/app_car/ai_chat_assistant.md @@ -0,0 +1,383 @@ +# AI Chat Assistant - AI 聊天助手模块文档 + +## 模块概述 + +`ai_chat_assistant` 是 OneApp 车辆模块群中的智能交互模块，提供基于人工智能的语音和文字聊天功能。该模块集成了语音识别、自然语言处理、车辆控制等技术，为用户提供智能化的车辆助手服务。 + +### 基本信息 +- **模块名称**: ai_chat_assistant +- **模块路径**: oneapp_app_car/ai_chat_assistant +- **类型**: Flutter Package Module +- **主要功能**: 智能语音交互、车辆控制、自然语言问答 + +### 核心特性 +- **智能语音识别**: 集成阿里云语音识别SDK +- **车辆智能控制**: 支持20+种车辆控制命令 +- **自然语言处理**: 基于OpenAI GPT的智能问答 +- **多语言支持**: 中英文双语交互 +- **实时流式响应**: 基于SSE的实时对话体验 +- **权限智能管理**: 自动处理麦克风等系统权限 + +## 目录结构 + +``` +ai_chat_assistant/ +├── lib/ +│ ├── ai_chat_assistant.dart # 模块入口文件 +│ ├── app.dart # 应用配置 +│ ├── manager.dart # 全局管理器 +│ ├── bloc/ # BLoC状态管理 +│ │ ├── ai_chat_cubit.dart +│ │ ├── easy_bloc.dart +│ │ └── command_state.dart +│ ├── enums/ # 枚举定义 +│ │ ├── message_status.dart +│ │ ├── message_service_state.dart +│ │ └── vehicle_command_type.dart +│ ├── models/ # 数据模型 +│ │ ├── chat_message.dart +│ │ ├── vehicle_cmd.dart +│ │ ├── vehicle_cmd_response.dart +│ │ └── vehicle_status_info.dart +│ ├── screens/ # 界面组件 +│ │ ├── full_screen.dart +│ │ ├── part_screen.dart +│ │ └── main_screen.dart +│ ├── services/ # 业务服务层 +│ │ ├── message_service.dart +│ │ ├── command_service.dart +│ │ ├── chat_sse_service.dart +│ │ └── classification_service.dart +│ ├── utils/ # 工具类 +│ │ ├── common_util.dart +│ │ └── tts_util.dart +│ └── widgets/ # UI组件 +│ ├── chat_box.dart +│ ├── chat_bubble.dart +│ ├── assistant_avatar.dart +│ └── floating_icon.dart +└── pubspec.yaml # 依赖配置 +``` + +## 核心架构组件 + +### 1. 消息状态枚举 (MessageStatus) + +```dart +enum MessageStatus { + normal('普通消息', 'Normal'), + listening('聆听中', 'Listening'), + recognizing('识别中', 'Recognizing'), + thinking('思考中', 'Thinking'), + completed('完成回答', 'Completed'), + executing('执行中', 'Executing'), + success('执行成功', 'Success'), + failure('执行失败', 'Failure'), + aborted('已中止', 'Aborted'); + + const MessageStatus(this.chinese, this.english); + final String chinese; + final String english; +} +``` + +### 2. 车辆控制命令枚举 (VehicleCommandType) + +```dart +enum VehicleCommandType { + unknown('未知', 'unknown'), + lock('上锁车门', 'lock'), + unlock('解锁车门', 'unlock'), + openWindow('打开车窗', 'open window'), + closeWindow('关闭车窗', 'close window'), + appointAC('预约空调', 'appoint AC'), + openAC('打开空调', 'open AC'), + closeAC('关闭空调', 'close AC'), + changeACTemp('修改空调温度', 'change AC temperature'), + coolSharply('极速降温', 'cool sharply'), + prepareCar('一键备车', 'prepare car'), + meltSnow('一键融雪', 'melt snow'), + openTrunk('打开后备箱', 'open trunk'), + closeTrunk('关闭后备箱', 'close trunk'), + honk('鸣笛', 'honk'), + locateCar('定位车辆', 'locate car'), + openWheelHeat('开启方向盘加热', 'open wheel heat'), + closeWheelHeat('关闭方向盘加热', 'close wheel heat'), + openMainSeatHeat('开启主座椅加热', 'open main seat heat'), + closeMainSeatHeat('关闭主座椅加热', 'close main seat heat'), + openMinorSeatHeat('开启副座椅加热', 'open minor seat heat'), + closeMinorSeatHeat('关闭副座椅加热', 'close minor seat heat'); + + const VehicleCommandType(this.chinese, this.english); + final String chinese; + final String english; +} +``` + +### 3. 聊天消息模型 (ChatMessage) + +```dart +class ChatMessage { + final String id; + final String text; + final bool isUser; + final DateTime timestamp; + MessageStatus status; + + ChatMessage({ + required this.id, + required this.text, + required this.isUser, + required this.timestamp, + this.status = MessageStatus.normal, + }); +} +``` + +## 核心服务类 + +### 1. 消息服务 (MessageService) + +MessageService是AI聊天助手的核心服务，采用单例模式，负责管理整个对话流程： + +```dart +class MessageService extends ChangeNotifier { + static MessageService? _instance; + static MessageService get instance => _instance ??= MessageService._internal(); + factory MessageService() => instance; + + // 核心方法 + Future startVoiceInput() async + Future stopAndProcessVoiceInput() async + Future reply(String text) async + Future handleVehicleControl(String text, bool isChinese) async + Future processCommand(VehicleCommand command, bool isChinese) async +} +``` + +**主要功能模块:** + +#### 语音交互流程 +1. **录音开始**: `startVoiceInput()` - 检查麦克风权限，开启阿里云ASR +2. **录音识别**: `stopAndProcessVoiceInput()` - 停止录音并获取识别结果 +3. **文本分类**: 通过 `TextClassificationService` 判断用户意图 +4. **响应生成**: 根据分类结果调用相应处理方法 + +#### 消息状态管理 +- **listening**: 正在聆听用户语音输入 +- **recognizing**: 语音识别中 +- **thinking**: AI思考回复中 +- **executing**: 车辆控制命令执行中 +- **completed**: 对话完成 + +#### 车辆控制处理 +```dart +Future handleVehicleControl(String text, bool isChinese) async { + final vehicleCommandResponse = await _vehicleCommandService.getCommandFromText(text); + if (vehicleCommandResponse != null) { + // 更新消息状态为执行中 + replaceMessage(id: _latestAssistantMessageId!, + text: vehicleCommandResponse.tips!, + status: MessageStatus.executing); + + // 执行车辆控制命令 + for (var command in vehicleCommandResponse.commands) { + if (command.type != VehicleCommandType.unknown && command.error.isEmpty) { + bool isSuccess = await processCommand(command, isChinese); + // 处理执行结果 + } + } + } +} +``` + +### 2. BLoC状态管理 (AIChatCommandCubit) + +```dart +class AIChatCommandCubit extends EasyCubit { + AIChatCommandCubit() : super(const AIChatCommandState()); + + void reset() { + emit(const AIChatCommandState()); + } + + String _generateCommandId() { + return '${DateTime.now().millisecondsSinceEpoch}_${state.commandType?.name ?? 'unknown'}'; + } + + bool get isExecuting => state.status == AIChatCommandStatus.executing; + String? get currentCommandId => state.commandId; +} +``` + +### 3. 主屏幕界面 (MainScreen) + +```dart +class MainScreen extends StatefulWidget { + const MainScreen({super.key}); + + @override + State createState() => _MainScreenState(); +} + +class _MainScreenState extends State { + @override + Widget build(BuildContext context) { + return Scaffold( + backgroundColor: Colors.transparent, + body: Stack( + children: [ + Container( + decoration: const BoxDecoration( + image: DecorationImage( + image: AssetImage('assets/images/bg.jpg', package: 'ai_chat_assistant'), + fit: BoxFit.cover, + ), + ), + ), + FloatingIcon(), // 浮动聊天入口 + ], + ), + ); + } +} +``` + +## 技术集成 + +### 阿里云语音识别集成 +```dart +// 方法通道配置 +static const MethodChannel _asrChannel = MethodChannel('com.example.ai_chat_assistant/ali_sdk'); + +// ASR回调处理 +Future _handleMethodCall(MethodCall call) async { + switch (call.method) { + case "onAsrResult": + replaceMessage(id: _latestUserMessageId!, + text: call.arguments, + status: MessageStatus.normal); + break; + case "onAsrStop": + if (_asrCompleter != null && !_asrCompleter!.isCompleted) { + _asrCompleter!.complete(messages.last.text); + } + break; + } +} +``` + +### 权限管理 +```dart +Future startVoiceInput() async { + if (await Permission.microphone.status == PermissionStatus.denied) { + PermissionStatus status = await Permission.microphone.request(); + if (status == PermissionStatus.permanentlyDenied) { + await Fluttertoast.showToast(msg: "请在设置中开启麦克风权限"); + } + return; + } + // 继续语音输入流程 +} +``` + +## 使用方式 + +### 1. 模块导入 +```dart +import 'package:ai_chat_assistant/ai_chat_assistant.dart'; +``` + +### 2. 服务初始化 +```dart +// 获取消息服务实例 +final messageService = MessageService.instance; + +// 监听消息变化 +messageService.addListener(() { + // 处理消息更新 +}); +``` + +### 3. 语音交互 +```dart +// 开始语音输入 +await messageService.startVoiceInput(); + +// 停止并处理语音输入 +await messageService.stopAndProcessVoiceInput(); +``` + +### 4. 文本交互 +```dart +// 直接发送文本消息 +await messageService.reply("帮我打开空调"); +``` + +## 依赖配置 + +### pubspec.yaml 关键依赖 +```yaml +dependencies: + flutter: + sdk: flutter + # 状态管理 + provider: ^6.0.0 + + # 权限管理 + permission_handler: ^10.0.0 + + # 网络请求 + dio: ^5.0.0 + + # 提示消息 + fluttertoast: ^8.0.0 + + # UUID生成 + uuid: ^3.0.0 + + # 国际化 + basic_intl: + path: ../../oneapp_basic_utils/basic_intl +``` + +## 扩展开发指南 + +### 1. 新增车辆控制命令 + +1. 在 `VehicleCommandType` 枚举中添加新命令： +```dart +enum VehicleCommandType { + // 现有命令... + newCommand('新命令', 'new command'), +} +``` + +2. 在 `MessageService.processCommand` 中添加处理逻辑。 + +### 2. 自定义对话界面 + +继承或修改现有的Screen组件，实现自定义的对话界面布局。 + +### 3. 集成其他AI服务 + +通过修改 `ChatSseService` 或新增服务类，可以集成其他AI对话服务。 + +## 性能优化建议 + +1. **内存管理**: MessageService使用单例模式，注意在适当时机清理消息历史 +2. **网络优化**: SSE连接在不使用时应及时断开 +3. **权限缓存**: 避免重复请求已获取的权限 +4. **语音资源**: 及时释放语音录制和播放资源 + +## 问题排查 + +### 常见问题 +1. **语音识别失效**: 检查麦克风权限和阿里云SDK配置 +2. **车辆控制失败**: 确认车辆连接状态和控制权限 +3. **SSE连接断开**: 检查网络状态和服务端配置 + +### 调试技巧 +- 启用详细日志输出 +- 使用Flutter Inspector检查Widget状态 +- 通过MethodChannel调试原生交互 diff --git a/app_car/amap_flutter_location.md b/app_car/amap_flutter_location.md new file mode 100644 index 0000000..5fa5610 --- /dev/null +++ b/app_car/amap_flutter_location.md @@ -0,0 +1,614 @@ +# AMap Flutter Location - 高德地图定位插件 + +## 模块概述 + +`amap_flutter_location` 是 OneApp 中基于高德地图 SDK 的定位服务插件，提供了高精度的位置定位、地理围栏、轨迹记录等功能。该插件为车辆定位、导航、位置服务等功能提供了可靠的地理位置支持。 + +## 核心功能 + +### 1. 位置定位 +- **GPS 定位**：基于 GPS 卫星的高精度定位 +- **网络定位**：基于基站和 WiFi 的快速定位 +- **混合定位**：GPS + 网络的融合定位算法 +- **室内定位**：支持室内场景的位置识别 + +### 2. 地理围栏 +- **围栏创建**：创建圆形、多边形地理围栏 +- **进出检测**：实时检测设备进入/离开围栏 +- **多围栏管理**：同时管理多个地理围栏 +- **事件通知**：围栏事件的实时推送 + +### 3. 轨迹记录 +- **轨迹采集**：实时记录移动轨迹 +- **轨迹优化**：去噪、平滑轨迹数据 +- **轨迹存储**：本地和云端轨迹存储 +- **轨迹分析**：距离、速度、停留点分析 + +### 4. 位置服务 +- **逆地理编码**：坐标转换为地址信息 +- **地理编码**：地址转换为坐标信息 +- **POI 搜索**：兴趣点搜索和信息获取 +- **距离计算**：两点间距离和路径计算 + +## 技术架构 + +### 架构设计 +``` +┌─────────────────────────────────────┐ +│ 应用层 │ +│ (app_car, app_navigation) │ +├─────────────────────────────────────┤ +│ AMap Flutter Location │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 定位管理 │ 围栏服务 │ 轨迹记录 │ │ +│ ├──────────┼──────────┼──────────┤ │ +│ │ 坐标转换 │ 事件处理 │ 数据存储 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 高德地图 Native SDK │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ Android │ iOS │ 定位引擎 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 系统定位服务 │ +│ (GPS, Network, Sensors) │ +└─────────────────────────────────────┘ +``` + +### 核心组件 + +#### 1. 定位管理器 (LocationManager) +```dart +class AMapLocationManager { + // 初始化定位服务 + Future initialize(LocationConfig config); + + // 开始定位 + Future startLocation(); + + // 停止定位 + Future stopLocation(); + + // 获取当前位置 + Future getCurrentLocation(); + + // 设置定位参数 + Future setLocationOption(LocationOption option); +} +``` + +#### 2. 地理围栏管理器 (GeofenceManager) +```dart +class AMapGeofenceManager { + // 添加围栏 + Future addGeofence(GeofenceRegion region); + + // 移除围栏 + Future removeGeofence(String geofenceId); + + // 获取围栏列表 + Future> getGeofences(); + + // 开始围栏监控 + Future startGeofenceMonitoring(); + + // 停止围栏监控 + Future stopGeofenceMonitoring(); +} +``` + +#### 3. 轨迹记录器 (TrackRecorder) +```dart +class AMapTrackRecorder { + // 开始录制轨迹 + Future startRecording(TrackConfig config); + + // 停止录制轨迹 + Future stopRecording(String trackId); + + // 暂停录制 + Future pauseRecording(String trackId); + + // 恢复录制 + Future resumeRecording(String trackId); + + // 获取轨迹数据 + Future getTrack(String trackId); +} +``` + +#### 4. 坐标转换器 (CoordinateConverter) +```dart +class AMapCoordinateConverter { + // 坐标系转换 + LatLng convertCoordinate(LatLng source, CoordinateType from, CoordinateType to); + + // 批量坐标转换 + List convertCoordinates(List source, CoordinateType from, CoordinateType to); + + // 逆地理编码 + Future reverseGeocode(LatLng location); + + // 地理编码 + Future geocode(String address); +} +``` + +## 数据模型 + +### 位置模型 +```dart +class AMapLocation { + final double latitude; // 纬度 + final double longitude; // 经度 + final double altitude; // 海拔 + final double accuracy; // 精度 + final double speed; // 速度 + final double bearing; // 方向角 + final DateTime timestamp; // 时间戳 + final String address; // 地址信息 + final String province; // 省份 + final String city; // 城市 + final String district; // 区县 + final String street; // 街道 + final String streetNumber; // 门牌号 + final String aoiName; // AOI 名称 + final String poiName; // POI 名称 + final LocationType locationType; // 定位类型 +} + +enum LocationType { + gps, // GPS 定位 + network, // 网络定位 + passive, // 被动定位 + offline, // 离线定位 + lastKnown // 上次定位 +} +``` + +### 地理围栏模型 +```dart +class GeofenceRegion { + final String id; + final String name; + final GeofenceType type; + final LatLng center; + final double radius; + final List polygon; + final GeofenceAction action; + final bool isEnabled; + final DateTime createdAt; + final Map metadata; +} + +enum GeofenceType { + circle, // 圆形围栏 + polygon, // 多边形围栏 + poi, // POI 围栏 + district // 行政区围栏 +} + +enum GeofenceAction { + enter, // 进入事件 + exit, // 离开事件 + dwell, // 停留事件 + enterOrExit // 进入或离开 +} +``` + +### 轨迹模型 +```dart +class Track { + final String id; + final String name; + final DateTime startTime; + final DateTime endTime; + final List points; + final double totalDistance; + final Duration totalTime; + final double averageSpeed; + final double maxSpeed; + final TrackStatistics statistics; +} + +class TrackPoint { + final double latitude; + final double longitude; + final double altitude; + final double speed; + final double bearing; + final DateTime timestamp; + final double accuracy; +} + +class TrackStatistics { + final double totalDistance; + final Duration totalTime; + final Duration movingTime; + final Duration pausedTime; + final double averageSpeed; + final double maxSpeed; + final double totalAscent; + final double totalDescent; + final List stopPoints; +} +``` + +## API 接口 + +### 定位接口 +```dart +abstract class LocationService { + // 获取当前位置 + Future> getCurrentLocation(); + + // 开始连续定位 + Future> startContinuousLocation(LocationOption option); + + // 停止连续定位 + Future> stopContinuousLocation(); + + // 获取定位权限状态 + Future> getLocationPermission(); + + // 请求定位权限 + Future> requestLocationPermission(); +} +``` + +### 地理围栏接口 +```dart +abstract class GeofenceService { + // 创建地理围栏 + Future> createGeofence(CreateGeofenceRequest request); + + // 删除地理围栏 + Future> deleteGeofence(String geofenceId); + + // 获取围栏列表 + Future>> getGeofences(); + + // 获取围栏状态 + Future> getGeofenceStatus(String geofenceId); +} +``` + +### 轨迹接口 +```dart +abstract class TrackService { + // 开始轨迹记录 + Future> startTrackRecording(TrackConfig config); + + // 停止轨迹记录 + Future> stopTrackRecording(String trackId); + + // 获取轨迹数据 + Future> getTrack(String trackId); + + // 获取轨迹列表 + Future>> getTrackList(TrackQuery query); +} +``` + +## 配置管理 + +### 定位配置 +```dart +class LocationOption { + final LocationMode locationMode; // 定位模式 + final int interval; // 定位间隔（毫秒） + final bool needAddress; // 是否需要地址信息 + final bool mockEnable; // 是否允许模拟位置 + final bool wifiScan; // 是否开启 WiFi 扫描 + final bool gpsFirst; // 是否 GPS 优先 + final int httpTimeOut; // 网络超时时间 + final LocationPurpose locationPurpose; // 定位目的 + + static const LocationOption defaultOption = LocationOption( + locationMode: LocationMode.hightAccuracy, + interval: 2000, + needAddress: true, + mockEnable: false, + wifiScan: true, + gpsFirst: false, + httpTimeOut: 30000, + locationPurpose: LocationPurpose.signIn, + ); +} + +enum LocationMode { + batterySaving, // 低功耗模式 + deviceSensors, // 仅设备传感器 + hightAccuracy // 高精度模式 +} +``` + +### 围栏配置 +```dart +class GeofenceConfig { + final bool enableNotification; // 是否启用通知 + final int dwellDelay; // 停留延迟（毫秒） + final double minimumRadius; // 最小围栏半径 + final double maximumRadius; // 最大围栏半径 + final int maxGeofenceCount; // 最大围栏数量 + + static const GeofenceConfig defaultConfig = GeofenceConfig( + enableNotification: true, + dwellDelay: 10000, + minimumRadius: 50.0, + maximumRadius: 100000.0, + maxGeofenceCount: 100, + ); +} +``` + +## 使用示例 + +### 基本定位示例 +```dart +// 初始化定位服务 +final locationManager = AMapLocationManager.instance; +await locationManager.initialize(LocationConfig.defaultConfig); + +// 设置定位参数 +await locationManager.setLocationOption(LocationOption.defaultOption); + +// 监听位置变化 +locationManager.onLocationChanged.listen((location) { + print('当前位置: ${location.latitude}, ${location.longitude}'); + print('地址: ${location.address}'); +}); + +// 开始定位 +await locationManager.startLocation(); +``` + +### 地理围栏示例 +```dart +// 创建圆形围栏 +final geofence = GeofenceRegion( + id: 'home_fence', + name: '家庭围栏', + type: GeofenceType.circle, + center: LatLng(39.9042, 116.4074), // 北京天安门 + radius: 500.0, // 500米半径 + action: GeofenceAction.enterOrExit, + isEnabled: true, +); + +// 添加围栏 +final geofenceManager = AMapGeofenceManager.instance; +final fenceId = await geofenceManager.addGeofence(geofence); + +// 监听围栏事件 +geofenceManager.onGeofenceTriggered.listen((event) { + switch (event.action) { + case GeofenceAction.enter: + print('进入围栏: ${event.geofenceId}'); + // 执行进入围栏的逻辑 + break; + case GeofenceAction.exit: + print('离开围栏: ${event.geofenceId}'); + // 执行离开围栏的逻辑 + break; + } +}); + +// 开始围栏监控 +await geofenceManager.startGeofenceMonitoring(); +``` + +### 轨迹记录示例 +```dart +// 配置轨迹记录 +final trackConfig = TrackConfig( + name: '上班路线', + minDistance: 10.0, // 最小记录距离 + minTime: 5000, // 最小记录时间间隔 + enableOptimization: true, // 启用轨迹优化 +); + +// 开始记录轨迹 +final trackRecorder = AMapTrackRecorder.instance; +final trackId = await trackRecorder.startRecording(trackConfig); + +// 监听轨迹点 +trackRecorder.onTrackPointAdded.listen((point) { + print('新轨迹点: ${point.latitude}, ${point.longitude}'); +}); + +// 停止记录并获取轨迹 +final track = await trackRecorder.stopRecording(trackId); +print('轨迹总距离: ${track.totalDistance}米'); +print('轨迹总时间: ${track.totalTime}'); +``` + +### 坐标转换示例 +```dart +// WGS84 坐标转换为 GCJ02 坐标 +final wgs84Point = LatLng(39.9042, 116.4074); +final gcj02Point = AMapCoordinateConverter.convertCoordinate( + wgs84Point, + CoordinateType.wgs84, + CoordinateType.gcj02, +); + +// 逆地理编码 +final regeocodeResult = await AMapCoordinateConverter.reverseGeocode(gcj02Point); +print('地址: ${regeocodeResult.formattedAddress}'); + +// 地理编码 +final geocodeResult = await AMapCoordinateConverter.geocode('北京市天安门广场'); +if (geocodeResult.geocodes.isNotEmpty) { + final location = geocodeResult.geocodes.first.location; + print('坐标: ${location.latitude}, ${location.longitude}'); +} +``` + +## 测试策略 + +### 单元测试 +```dart +group('AMapLocation Tests', () { + test('should convert coordinates correctly', () { + // Given + final wgs84Point = LatLng(39.9042, 116.4074); + + // When + final gcj02Point = AMapCoordinateConverter.convertCoordinate( + wgs84Point, + CoordinateType.wgs84, + CoordinateType.gcj02, + ); + + // Then + expect(gcj02Point.latitude, isNot(equals(wgs84Point.latitude))); + expect(gcj02Point.longitude, isNot(equals(wgs84Point.longitude))); + }); +}); +``` + +### 集成测试 +```dart +group('Location Integration Tests', () { + testWidgets('location service flow', (tester) async { + // 1. 初始化定位服务 + await AMapLocationManager.instance.initialize(LocationConfig.defaultConfig); + + // 2. 开始定位 + await AMapLocationManager.instance.startLocation(); + + // 3. 等待定位结果 + final location = await AMapLocationManager.instance.getCurrentLocation(); + + // 4. 验证定位结果 + expect(location.latitude, greaterThan(-90)); + expect(location.latitude, lessThan(90)); + expect(location.longitude, greaterThan(-180)); + expect(location.longitude, lessThan(180)); + }); +}); +``` + +## 性能优化 + +### 定位优化 +- **智能定位策略**：根据场景自动选择最佳定位方式 +- **缓存机制**：缓存最近的定位结果 +- **批量处理**：批量处理定位请求 +- **省电模式**：低功耗的定位策略 + +### 数据优化 +- **数据压缩**：压缩轨迹数据减少存储空间 +- **增量同步**：只同步变化的数据 +- **本地缓存**：本地缓存常用的地理信息 +- **数据清理**：定期清理过期的轨迹数据 + +## 权限管理 + +### 位置权限 +```dart +enum LocationPermission { + denied, // 拒绝 + deniedForever, // 永久拒绝 + whileInUse, // 使用时允许 + always // 始终允许 +} + +class PermissionManager { + // 检查权限状态 + static Future checkPermission(); + + // 请求权限 + static Future requestPermission(); + + // 打开应用设置 + static Future openAppSettings(); +} +``` + +### 权限处理示例 +```dart +// 检查和请求位置权限 +final permission = await PermissionManager.checkPermission(); + +if (permission == LocationPermission.denied) { + final result = await PermissionManager.requestPermission(); + if (result != LocationPermission.whileInUse && + result != LocationPermission.always) { + // 权限被拒绝，显示说明或引导用户到设置页面 + await showPermissionDialog(); + return; + } +} + +// 权限获取成功，开始定位 +await startLocationService(); +``` + +## 错误处理 + +### 定位错误类型 +```dart +enum LocationErrorType { + permissionDenied, // 权限被拒绝 + locationServiceDisabled, // 定位服务未开启 + networkError, // 网络错误 + timeout, // 超时 + unknownError // 未知错误 +} + +class LocationException implements Exception { + final LocationErrorType type; + final String message; + final int? errorCode; + + const LocationException(this.type, this.message, [this.errorCode]); +} +``` + +## 隐私和安全 + +### 数据隐私 +- **最小权限原则**：只请求必要的定位权限 +- **数据加密**：敏感位置数据加密存储 +- **用户控制**：用户可以随时关闭定位服务 +- **透明度**：明确告知用户数据使用目的 + +### 安全措施 +- **防伪造**：检测和过滤伪造的 GPS 信号 +- **数据校验**：验证定位数据的有效性 +- **传输安全**：使用 HTTPS 传输位置数据 +- **访问控制**：严格控制位置数据的访问权限 + +## 版本历史 + +### v3.0.3 (当前版本) +- 支持 iOS 16 和 Android 13 +- 优化定位精度和速度 +- 修复地理围栏稳定性问题 +- 改进轨迹记录算法 + +### v3.0.2 +- 新增室内定位支持 +- 优化电池使用效率 +- 支持自定义坐标系 +- 修复内存泄漏问题 + +## 依赖关系 + +### 内部依赖 +- `basic_platform`: 平台抽象层 +- `basic_storage`: 本地存储服务 +- `basic_network`: 网络请求服务 + +### 外部依赖 +- `permission_handler`: 权限管理 +- `geolocator`: 位置服务补充 +- `path_provider`: 文件路径管理 + +## 总结 + +`amap_flutter_location` 作为高德地图定位服务的 Flutter 插件，为 OneApp 提供了可靠、高效的位置服务能力。通过集成 GPS、网络定位、地理围栏、轨迹记录等功能，该插件能够满足车辆定位、导航、位置服务等多种业务需求。 + +插件在设计上充分考虑了性能优化、隐私保护、权限管理等关键因素，确保在提供精准位置服务的同时，保护用户隐私和设备安全。这为 OneApp 的车联网服务提供了坚实的技术基础。 diff --git a/app_car/amap_flutter_search.md b/app_car/amap_flutter_search.md new file mode 100644 index 0000000..af64651 --- /dev/null +++ b/app_car/amap_flutter_search.md @@ -0,0 +1,638 @@ +# AMap Flutter Search - 高德地图搜索插件 + +## 模块概述 + +`amap_flutter_search` 是 OneApp 中基于高德地图 SDK 的搜索服务插件，提供了全面的地理信息搜索功能，包括 POI 搜索、路线规划、地址解析等服务。该插件为车辆导航、位置查找、路径规划等功能提供了强大的搜索能力支持。 + +## 核心功能 + +### 1. POI 搜索 +- **关键词搜索**：基于关键词的兴趣点搜索 +- **周边搜索**：指定位置周边的 POI 搜索 +- **分类搜索**：按类别筛选的 POI 搜索 +- **详情查询**：获取 POI 的详细信息 + +### 2. 路线规划 +- **驾车路线**：多种驾车路径规划策略 +- **步行路线**：行人路径规划 +- **骑行路线**：骑行路径规划 +- **公交路线**：公共交通路径规划 +- **货车路线**：货车专用路径规划 + +### 3. 地址解析 +- **地理编码**：地址转换为坐标 +- **逆地理编码**：坐标转换为地址 +- **输入提示**：地址输入智能提示 +- **行政区查询**：行政区域信息查询 + +### 4. 距离计算 +- **直线距离**：两点间直线距离计算 +- **驾车距离**：实际驾车距离和时间 +- **步行距离**：步行距离和时间 +- **批量计算**：批量距离矩阵计算 + +## 技术架构 + +### 架构设计 +``` +┌─────────────────────────────────────┐ +│ 应用层 │ +│ (app_navigation, app_car) │ +├─────────────────────────────────────┤ +│ AMap Flutter Search │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ POI搜索 │ 路线规划 │ 地址解析 │ │ +│ ├──────────┼──────────┼──────────┤ │ +│ │ 距离计算 │ 缓存管理 │ 数据处理 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 高德地图 Search SDK │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ Android │ iOS │ 搜索引擎 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 网络服务层 │ +│ (REST API, WebService) │ +└─────────────────────────────────────┘ +``` + +### 核心组件 + +#### 1. POI 搜索管理器 (PoiSearchManager) +```dart +class AMapPoiSearchManager { + // 关键词搜索 + Future searchByKeyword(PoiKeywordSearchOption option); + + // 周边搜索 + Future searchNearby(PoiNearbySearchOption option); + + // ID 搜索 + Future searchById(String poiId); + + // 分类搜索 + Future searchByCategory(PoiCategorySearchOption option); +} +``` + +#### 2. 路线规划管理器 (RouteSearchManager) +```dart +class AMapRouteSearchManager { + // 驾车路线规划 + Future calculateDriveRoute(DriveRouteQuery query); + + // 步行路线规划 + Future calculateWalkRoute(WalkRouteQuery query); + + // 骑行路线规划 + Future calculateRideRoute(RideRouteQuery query); + + // 公交路线规划 + Future calculateBusRoute(BusRouteQuery query); + + // 货车路线规划 + Future calculateTruckRoute(TruckRouteQuery query); +} +``` + +#### 3. 地理编码管理器 (GeocodeManager) +```dart +class AMapGeocodeManager { + // 地理编码 + Future geocode(GeocodeQuery query); + + // 逆地理编码 + Future reverseGeocode(RegeocodeQuery query); + + // 输入提示 + Future> inputTips(InputTipsQuery query); + + // 行政区查询 + Future searchDistrict(DistrictQuery query); +} +``` + +#### 4. 距离计算器 (DistanceCalculator) +```dart +class AMapDistanceCalculator { + // 计算两点距离 + Future calculateDistance(DistanceQuery query); + + // 批量距离计算 + Future> calculateDistances(List queries); + + // 路径距离计算 + Future calculateRouteDistance(RouteDistanceQuery query); +} +``` + +## 数据模型 + +### POI 模型 +```dart +class PoiItem { + final String poiId; // POI ID + final String title; // POI 名称 + final String snippet; // POI 描述 + final LatLng latLng; // POI 坐标 + final String distance; // 距离 + final String tel; // 电话 + final String postcode; // 邮编 + final String website; // 网站 + final String email; // 邮箱 + final String province; // 省份 + final String city; // 城市 + final String district; // 区县 + final String address; // 地址 + final String direction; // 方向 + final String businessArea; // 商圈 + final String typeCode; // 类型编码 + final String typeDes; // 类型描述 + final List photos; // 照片列表 + final List shopID; // 商铺ID + final IndoorData indoorData; // 室内数据 +} + +class PoiResult { + final List pois; + final int pageCount; + final int totalCount; + final SearchBound searchBound; + final PoiQuery query; +} +``` + +### 路线模型 +```dart +class DriveRouteResult { + final List paths; + final RouteQuery startPos; + final RouteQuery targetPos; + final List viaPoints; + final int taxiCost; +} + +class DrivePath { + final String strategy; // 策略 + final int distance; // 距离（米） + final int duration; // 时长（秒） + final String tolls; // 过路费 + final String tollDistance; // 收费距离 + final String totalTrafficLights; // 红绿灯数 + final List steps; // 路径段 + final List tmcs; // 路况信息 +} + +class DriveStep { + final String instruction; // 行驶指示 + final String orientation; // 方向 + final String road; // 道路名称 + final int distance; // 距离 + final int duration; // 时长 + final List polyline; // 路径坐标 + final String action; // 导航动作 + final String assistantAction; // 辅助动作 +} +``` + +### 地址模型 +```dart +class RegeocodeResult { + final RegeocodeAddress regeocodeAddress; + final List pois; + final List roads; + final List roadInters; + final List aois; +} + +class RegeocodeAddress { + final String formattedAddress; // 格式化地址 + final String country; // 国家 + final String province; // 省份 + final String city; // 城市 + final String district; // 区县 + final String township; // 乡镇 + final String neighborhood; // 社区 + final String building; // 建筑 + final String adcode; // 区域编码 + final String citycode; // 城市编码 + final List streetNumbers; // 门牌信息 +} +``` + +## API 接口 + +### POI 搜索接口 +```dart +abstract class PoiSearchService { + // 关键词搜索 + Future> searchByKeyword(PoiKeywordSearchRequest request); + + // 周边搜索 + Future> searchNearby(PoiNearbySearchRequest request); + + // 多边形搜索 + Future> searchInPolygon(PoiPolygonSearchRequest request); + + // POI 详情 + Future> getPoiDetail(String poiId); +} +``` + +### 路线规划接口 +```dart +abstract class RouteSearchService { + // 驾车路线规划 + Future> planDriveRoute(DriveRouteRequest request); + + // 步行路线规划 + Future> planWalkRoute(WalkRouteRequest request); + + // 骑行路线规划 + Future> planRideRoute(RideRouteRequest request); + + // 公交路线规划 + Future> planBusRoute(BusRouteRequest request); +} +``` + +### 地理编码接口 +```dart +abstract class GeocodeService { + // 地理编码 + Future> geocode(GeocodeRequest request); + + // 逆地理编码 + Future> reverseGeocode(RegeocodeRequest request); + + // 输入提示 + Future>> getInputTips(InputTipsRequest request); + + // 行政区搜索 + Future> searchDistrict(DistrictRequest request); +} +``` + +## 配置管理 + +### 搜索配置 +```dart +class SearchConfig { + final String apiKey; // API 密钥 + final int timeoutMs; // 超时时间 + final int maxRetries; // 最大重试次数 + final bool enableCache; // 是否启用缓存 + final int cacheExpireTime; // 缓存过期时间 + final String language; // 语言设置 + final String region; // 区域设置 + + static const SearchConfig defaultConfig = SearchConfig( + apiKey: '', + timeoutMs: 30000, + maxRetries: 3, + enableCache: true, + cacheExpireTime: 3600, + language: 'zh-CN', + region: 'CN', + ); +} +``` + +### POI 搜索配置 +```dart +class PoiSearchConfig { + final int pageSize; // 每页结果数 + final int maxPage; // 最大页数 + final String city; // 搜索城市 + final String types; // 搜索类型 + final bool extensions; // 是否返回扩展信息 + final String sortrule; // 排序规则 + + static const PoiSearchConfig defaultConfig = PoiSearchConfig( + pageSize: 20, + maxPage: 100, + city: '', + types: '', + extensions: false, + sortrule: 'distance', + ); +} +``` + +## 使用示例 + +### POI 搜索示例 +```dart +// 关键词搜索 +final searchOption = PoiKeywordSearchOption( + keyword: '加油站', + city: '北京', + pageSize: 20, + pageNum: 1, + extensions: true, +); + +final poiResult = await AMapPoiSearchManager.instance.searchByKeyword(searchOption); + +for (final poi in poiResult.pois) { + print('POI 名称: ${poi.title}'); + print('POI 地址: ${poi.address}'); + print('POI 距离: ${poi.distance}'); + print('POI 坐标: ${poi.latLng.latitude}, ${poi.latLng.longitude}'); +} +``` + +### 周边搜索示例 +```dart +// 周边搜索 +final nearbyOption = PoiNearbySearchOption( + keyword: '餐厅', + center: LatLng(39.9042, 116.4074), // 搜索中心点 + radius: 1000, // 搜索半径 1000 米 + pageSize: 10, + pageNum: 1, +); + +final nearbyResult = await AMapPoiSearchManager.instance.searchNearby(nearbyOption); + +print('附近餐厅数量: ${nearbyResult.pois.length}'); +for (final restaurant in nearbyResult.pois) { + print('餐厅: ${restaurant.title} - ${restaurant.distance}'); +} +``` + +### 路线规划示例 +```dart +// 驾车路线规划 +final driveQuery = DriveRouteQuery( + fromPoint: RouteQuery(39.9042, 116.4074), // 起点 + toPoint: RouteQuery(39.9015, 116.3974), // 终点 + mode: DriveMode.fastest, // 最快路线 + avoidhighspeed: false, // 不避开高速 + avoidtolls: false, // 不避开收费 + avoidtrafficjam: true, // 避开拥堵 +); + +final driveResult = await AMapRouteSearchManager.instance.calculateDriveRoute(driveQuery); + +if (driveResult.paths.isNotEmpty) { + final path = driveResult.paths.first; + print('驾车距离: ${path.distance} 米'); + print('预计时间: ${path.duration} 秒'); + print('过路费: ${path.tolls} 元'); + + for (final step in path.steps) { + print('导航指示: ${step.instruction}'); + print('道路: ${step.road}'); + print('距离: ${step.distance} 米'); + } +} +``` + +### 地理编码示例 +```dart +// 地址转坐标 +final geocodeQuery = GeocodeQuery( + locationName: '北京市朝阳区望京SOHO', + city: '北京', +); + +final geocodeResult = await AMapGeocodeManager.instance.geocode(geocodeQuery); + +if (geocodeResult.geocodeAddressList.isNotEmpty) { + final address = geocodeResult.geocodeAddressList.first; + print('地址坐标: ${address.latLonPoint.latitude}, ${address.latLonPoint.longitude}'); +} + +// 坐标转地址 +final regeocodeQuery = RegeocodeQuery( + latLonPoint: LatLng(39.9915, 116.4684), + radius: 200.0, + extensions: 'all', +); + +final regeocodeResult = await AMapGeocodeManager.instance.reverseGeocode(regeocodeQuery); +print('格式化地址: ${regeocodeResult.regeocodeAddress.formattedAddress}'); +``` + +### 输入提示示例 +```dart +// 地址输入提示 +final tipsQuery = InputTipsQuery( + keyword: '王府井', + city: '北京', + datatype: 'all', +); + +final tipsList = await AMapGeocodeManager.instance.inputTips(tipsQuery); + +for (final tip in tipsList) { + print('提示: ${tip.name}'); + print('地址: ${tip.address}'); + if (tip.point != null) { + print('坐标: ${tip.point!.latitude}, ${tip.point!.longitude}'); + } +} +``` + +## 测试策略 + +### 单元测试 +```dart +group('AMapSearch Tests', () { + test('should search POI by keyword', () async { + // Given + final searchOption = PoiKeywordSearchOption( + keyword: '测试POI', + city: '北京', + ); + + // When + final result = await AMapPoiSearchManager.instance.searchByKeyword(searchOption); + + // Then + expect(result.pois, isNotEmpty); + expect(result.pois.first.title, contains('测试POI')); + }); + + test('should calculate drive route', () async { + // Given + final query = DriveRouteQuery( + fromPoint: RouteQuery(39.9042, 116.4074), + toPoint: RouteQuery(39.9015, 116.3974), + ); + + // When + final result = await AMapRouteSearchManager.instance.calculateDriveRoute(query); + + // Then + expect(result.paths, isNotEmpty); + expect(result.paths.first.distance, greaterThan(0)); + }); +}); +``` + +### 集成测试 +```dart +group('Search Integration Tests', () { + testWidgets('complete search flow', (tester) async { + // 1. 搜索 POI + final pois = await searchNearbyPois('加油站', currentLocation); + + // 2. 选择目标 POI + final targetPoi = pois.first; + + // 3. 规划路线 + final route = await planRouteToDestination(currentLocation, targetPoi.latLng); + + // 4. 验证结果 + expect(route.paths, isNotEmpty); + expect(route.paths.first.steps, isNotEmpty); + }); +}); +``` + +## 性能优化 + +### 搜索优化 +- **搜索缓存**：缓存常用搜索结果 +- **预测搜索**：基于历史预测用户搜索 +- **分页加载**：大结果集分页加载 +- **搜索建议**：智能搜索建议减少请求 + +### 路线优化 +- **路线缓存**：缓存常用路线规划结果 +- **增量更新**：只更新路线变化部分 +- **压缩传输**：压缩路线数据减少传输量 +- **多线程处理**：并行处理多个路线请求 + +## 错误处理 + +### 搜索错误类型 +```dart +enum SearchErrorType { + networkError, // 网络错误 + apiKeyInvalid, // API Key 无效 + quotaExceeded, // 配额超限 + invalidParameter, // 参数无效 + noResult, // 无搜索结果 + serverError, // 服务器错误 + timeout // 请求超时 +} + +class SearchException implements Exception { + final SearchErrorType type; + final String message; + final int? errorCode; + + const SearchException(this.type, this.message, [this.errorCode]); +} +``` + +### 错误处理示例 +```dart +try { + final result = await AMapPoiSearchManager.instance.searchByKeyword(searchOption); + // 处理搜索结果 +} on SearchException catch (e) { + switch (e.type) { + case SearchErrorType.networkError: + showErrorDialog('网络连接失败，请检查网络设置'); + break; + case SearchErrorType.noResult: + showInfoDialog('未找到相关结果，请尝试其他关键词'); + break; + case SearchErrorType.quotaExceeded: + showErrorDialog('搜索次数已达上限，请稍后再试'); + break; + default: + showErrorDialog('搜索失败: ${e.message}'); + } +} catch (e) { + showErrorDialog('未知错误: $e'); +} +``` + +## 缓存策略 + +### 搜索结果缓存 +```dart +class SearchCache { + static const int maxCacheSize = 1000; + static const Duration cacheExpiration = Duration(hours: 1); + + // 缓存 POI 搜索结果 + static Future cachePoiResult(String key, PoiResult result); + + // 获取缓存的 POI 结果 + static Future getCachedPoiResult(String key); + + // 缓存路线规划结果 + static Future cacheRouteResult(String key, DriveRouteResult result); + + // 获取缓存的路线结果 + static Future getCachedRouteResult(String key); + + // 清理过期缓存 + static Future cleanExpiredCache(); +} +``` + +## 配额管理 + +### API 配额监控 +```dart +class QuotaManager { + // 获取当前配额使用情况 + static Future getCurrentQuota(); + + // 检查是否可以发起请求 + static Future canMakeRequest(RequestType type); + + // 记录请求使用 + static Future recordRequest(RequestType type); + + // 获取配额重置时间 + static Future getQuotaResetTime(); +} + +class QuotaInfo { + final int dailyLimit; // 日限额 + final int dailyUsed; // 日使用量 + final int monthlyLimit; // 月限额 + final int monthlyUsed; // 月使用量 + final DateTime resetTime; // 重置时间 +} +``` + +## 版本历史 + +### v3.1.22+1 (当前版本) +- 支持最新的高德地图 API +- 新增货车路线规划功能 +- 优化搜索性能和准确性 +- 修复路线规划稳定性问题 + +### v3.1.21 +- 支持室内 POI 搜索 +- 新增批量距离计算 +- 优化内存使用 +- 改进错误处理机制 + +## 依赖关系 + +### 内部依赖 +- `amap_flutter_base`: 高德地图基础库 +- `basic_network`: 网络请求服务 +- `basic_storage`: 本地存储服务 + +### 外部依赖 +- `dio`: HTTP 客户端 +- `cached_network_image`: 图片缓存 +- `sqflite`: 本地数据库 + +## 总结 + +`amap_flutter_search` 作为高德地图搜索服务的 Flutter 插件，为 OneApp 提供了全面的地理信息搜索能力。通过集成 POI 搜索、路线规划、地理编码、距离计算等功能，该插件能够满足车辆导航、位置服务、路径规划等多种业务需求。 + +插件在设计上充分考虑了性能优化、缓存管理、错误处理、配额控制等关键因素，确保在提供高质量搜索服务的同时，保持良好的用户体验和系统稳定性。这为 OneApp 的车联网和导航服务提供了强大的技术支撑。 diff --git a/app_car/app_avatar.md b/app_car/app_avatar.md new file mode 100644 index 0000000..cf4071c --- /dev/null +++ b/app_car/app_avatar.md @@ -0,0 +1,520 @@ +# App Avatar - 虚拟形象模块文档 + +## 模块概述 + +`app_avatar` 是 OneApp 的虚拟形象管理模块，为用户提供个性化的虚拟车载助手服务。该模块集成了语音克隆技术、3D 虚拟形象渲染、支付服务等功能，让用户可以创建和定制自己的专属虚拟助手。 + +### 基本信息 +- **模块名称**: app_avatar +- **版本**: 0.6.1+2 +- **仓库**: https://gitlab-rd0.maezia.com/dssomobile/oneapp/dssomobile-oneapp-app-avatar +- **Flutter 版本**: >=3.0.0 +- **Dart 版本**: >=2.16.2 <4.0.0 + +## 目录结构 + +``` +app_avatar/ +├── lib/ +│ ├── app_avatar.dart # 主导出文件 +│ └── src/ # 源代码目录 +│ ├── avatar/ # 虚拟形象核心功能 +│ │ ├── pages/ # 页面组件 +│ │ │ ├── avatar_building/ # 形象生成页面 +│ │ │ ├── avatar_copy/ # 形象复制页面 +│ │ │ ├── avatar_display/ # 形象展示页面 +│ │ │ ├── no_avatar/ # 未生成形象页面 +│ │ │ ├── prepare_resource_page/ # 资源准备页面 +│ │ │ ├── pta_camera/ # 拍照相机页面 +│ │ │ ├── pta_sex_check/ # 性别确认页面 +│ │ │ ├── rename/ # 重命名页面 +│ │ │ └── server_data_dress_up/ # 捏脸界面 +│ │ ├── provide_external/ # 对外提供组件 +│ │ └── util/ # 工具类 +│ ├── common_import.dart # 通用导入 +│ └── route_export.dart # 路由导出 +├── assets/ # 静态资源 +├── pubspec.yaml # 依赖配置 +└── README.md # 项目说明 +``` + +## 核心功能模块 + +### 1. 主导出模块 + +**文件**: `lib/app_avatar.dart` + +```dart +library app_avatar; +import 'package:basic_modular/modular.dart'; +import 'package:basic_modular_route/basic_modular_route.dart'; +import 'src/route_export.dart'; + +// 导出路由和对外组件 +export 'src/route_export.dart'; +export 'src/avatar/provide_external/in_use_avatar_icon.dart'; +export 'src/avatar/provide_external/avatar_header.dart'; +export 'src/avatar/util/config.dart'; +export 'src/avatar/util/avatar_engine_manage.dart'; + +/// App Avatar 模块定义 +class AppAvatarModule extends Module with RouteObjProvider { + @override + List get imports => []; + + @override + List get binds => []; + + @override + List get routes { + // 获取路由元数据 + final r1 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyHome); + final r4 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiAvatarDisplayPage); + final r7 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiPtaAvatarCamera); + final r8 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiBuilding); + final r10 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiDressUpServerDataPage); + final r11 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiNonAvatar); + final r12 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiRename); + final r13 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiStep2GenderCheck); + final r14 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiAvatarCopy); + final r15 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiPrepareResourcePage); + + // 返回子路由列表 + return [ + ChildRoute(r1.path, child: (_, args) => r1.provider(args).as()), + ChildRoute(r4.path, child: (_, args) => r4.provider(args).as()), + ChildRoute(r7.path, child: (_, args) => r7.provider(args).as()), + ChildRoute(r8.path, child: (_, args) => r8.provider(args).as()), + ChildRoute(r10.path, child: (_, args) => r10.provider(args).as()), + ChildRoute(r11.path, child: (_, args) => r11.provider(args).as()), + ChildRoute(r12.path, child: (_, args) => r12.provider(args).as()), + ChildRoute(r13.path, child: (_, args) => r13.provider(args).as()), + ChildRoute(r14.path, child: (_, args) => r14.provider(args).as()), + ChildRoute(r15.path, child: (_, args) => r15.provider(args).as()), + ]; + } +} +``` + +### 2. 路由导出管理 + +## 核心功能与实现 + +### 1. 页面路由系统 + +app_avatar 模块基于真实的路由系统实现，主要包含以下功能页面： + +#### 核心页面组件 +- **AvatarReplaceChild**: 虚拟形象展示页面 +- **PtaAvatarCamera**: 拍照相机页面 +- **AvatarBuildingPage**: 形象生成页面 +- **DressUpServerDataPage**: 捏脸编辑页面 +- **AvatarCopy**: 形象复制页面 +- **NonAvatar**: 非形象页面 + +#### 页面导航实现 +```dart +// 页面跳转示例 +class AvatarNavigationHelper { + // 跳转到虚拟形象展示页面 + static void gotoAvatarDisplay() { + Modular.to.pushNamed('/avatar/avatarDisplayPage'); + } + + // 跳转到拍照创建页面 + static void gotoPtaCamera() { + Modular.to.pushNamed('/avatar/PtaAvatarCamera'); + } + + // 跳转到捏脸编辑页面 + static void gotoDressUp() { + Modular.to.pushNamed('/avatar/DressUpServerDataPage'); + } + + // 跳转到形象生成页面 + static void gotoAvatarBuilding({ + required String sex, + required String name, + required String photoPath, + }) { + Modular.to.pushNamed('/avatar/AvatarBuildingPage', arguments: { + 'sex': sex, + 'name': name, + 'photoPath': photoPath, + }); + } +} +``` + +### 2. 模块架构设计 + +#### 基本模块结构 +```dart +// 模块入口点 +class AppAvatarModule extends Module implements RouteObjProvider { + @override + List get binds => [ + // 依赖注入配置将在这里定义 + ]; + + @override + List get routes => [ + // 路由配置通过 AvatarRouteExport 管理 + ]; + + @override + RouteCenterAPI? get routeObj => RouteCenterAPI( + routeExporter: AvatarRouteExport(), + ); +} +``` + +#### 页面状态管理 +```dart +// 简化的页面状态管理 +class AvatarPageState { + final bool isLoading; + final String? errorMessage; + final Map data; + + const AvatarPageState({ + this.isLoading = false, + this.errorMessage, + this.data = const {}, + }); + + AvatarPageState copyWith({ + bool? isLoading, + String? errorMessage, + Map? data, + }) { + return AvatarPageState( + isLoading: isLoading ?? this.isLoading, + errorMessage: errorMessage ?? this.errorMessage, + data: data ?? this.data, + ); + } +} +``` + +### 3. 核心功能实现 + +#### 虚拟形象创建流程 +虚拟形象创建遵循以下步骤： + +1. **用户拍照**: 通过 `PtaAvatarCamera` 页面获取用户照片 +2. **信息确认**: 收集用户基本信息（姓名、性别等） +3. **形象生成**: `AvatarBuildingPage` 显示生成进度 +4. **结果展示**: `AvatarReplaceChild` 展示最终形象 + +#### 形象管理功能 +- **形象展示**: 3D/2D 虚拟形象渲染展示 +- **形象编辑**: 通过捏脸系统进行外观定制 +- **形象切换**: 支持多个虚拟形象间的切换 +- **形象分享**: 虚拟形象内容的分享功能 + +### 4. 数据模型定义 + +#### 基础数据结构 +```dart +// 虚拟形象基本信息 +class AvatarInfo { + final String id; + final String name; + final String sex; + final String photoPath; + final DateTime createdAt; + final Map customData; + + const AvatarInfo({ + required this.id, + required this.name, + required this.sex, + required this.photoPath, + required this.createdAt, + this.customData = const {}, + }); + + Map toMap() { + return { + 'id': id, + 'name': name, + 'sex': sex, + 'photoPath': photoPath, + 'createdAt': createdAt.toIso8601String(), + 'customData': customData, + }; + } + + factory AvatarInfo.fromMap(Map map) { + return AvatarInfo( + id: map['id'] ?? '', + name: map['name'] ?? '', + sex: map['sex'] ?? '', + photoPath: map['photoPath'] ?? '', + createdAt: DateTime.parse(map['createdAt'] ?? DateTime.now().toIso8601String()), + customData: map['customData'] ?? const {}, + ); + } +} + +// 形象配置信息 +class AvatarConfiguration { + final String avatarId; + final Map appearanceConfig; + final Map behaviorConfig; + final DateTime updatedAt; + + const AvatarConfiguration({ + required this.avatarId, + required this.appearanceConfig, + required this.behaviorConfig, + required this.updatedAt, + }); +} +``` + +### 5. UI 组件实现 + +#### 通用 UI 组件 +```dart +// 形象展示组件 +class AvatarDisplayWidget extends StatelessWidget { + final AvatarInfo avatarInfo; + final VoidCallback? onTap; + + const AvatarDisplayWidget({ + Key? key, + required this.avatarInfo, + this.onTap, + }) : super(key: key); + + @override + Widget build(BuildContext context) { + return GestureDetector( + onTap: onTap, + child: Container( + width: 200, + height: 300, + decoration: BoxDecoration( + borderRadius: BorderRadius.circular(10), + border: Border.all(color: Colors.grey.shade300), + ), + child: Column( + children: [ + Expanded( + child: Container( + decoration: BoxDecoration( + borderRadius: BorderRadius.vertical(top: Radius.circular(10)), + image: avatarInfo.photoPath.isNotEmpty + ? DecorationImage( + image: FileImage(File(avatarInfo.photoPath)), + fit: BoxFit.cover, + ) + : null, + ), + child: avatarInfo.photoPath.isEmpty + ? Center(child: Icon(Icons.person, size: 50, color: Colors.grey)) + : null, + ), + ), + Container( + padding: EdgeInsets.all(8), + child: Text( + avatarInfo.name, + style: TextStyle(fontSize: 16, fontWeight: FontWeight.bold), + ), + ), + ], + ), + ), + ); + } +} + +// 操作按钮组件 +class AvatarActionButton extends StatelessWidget { + final String label; + final IconData icon; + final VoidCallback onPressed; + final bool isLoading; + + const AvatarActionButton({ + Key? key, + required this.label, + required this.icon, + required this.onPressed, + this.isLoading = false, + }) : super(key: key); + + @override + Widget build(BuildContext context) { + return ElevatedButton.icon( + onPressed: isLoading ? null : onPressed, + icon: isLoading + ? SizedBox( + width: 16, + height: 16, + child: CircularProgressIndicator(strokeWidth: 2) + ) + : Icon(icon), + label: Text(label), + style: ElevatedButton.styleFrom( + padding: EdgeInsets.symmetric(horizontal: 24, vertical: 12), + shape: RoundedRectangleBorder( + borderRadius: BorderRadius.circular(8), + ), + ), + ); + } +} +``` + +### 6. 错误处理与异常管理 + +#### 异常定义 +```dart +// 虚拟形象相关异常 +abstract class AvatarException implements Exception { + final String message; + const AvatarException(this.message); + + @override + String toString() => 'AvatarException: $message'; +} + +class AvatarCreationException extends AvatarException { + const AvatarCreationException(String message) : super(message); +} + +class AvatarLoadException extends AvatarException { + const AvatarLoadException(String message) : super(message); +} + +class AvatarSaveException extends AvatarException { + const AvatarSaveException(String message) : super(message); +} +``` + +#### 错误处理机制 +```dart +// 错误处理工具类 +class AvatarErrorHandler { + static void handleError( + BuildContext context, + Exception error, { + VoidCallback? onRetry, + }) { + String message = '发生未知错误'; + + if (error is AvatarException) { + message = error.message; + } + + showDialog( + context: context, + builder: (context) => AlertDialog( + title: Text('错误'), + content: Text(message), + actions: [ + if (onRetry != null) + TextButton( + onPressed: () { + Navigator.of(context).pop(); + onRetry(); + }, + child: Text('重试'), + ), + TextButton( + onPressed: () => Navigator.of(context).pop(), + child: Text('确定'), + ), + ], + ), + ); + } +} +``` +## 技术架构与设计模式 + +### 1. 模块化架构 + +app_avatar 模块采用标准的 OneApp 模块化架构： + +- **模块定义**: `AppAvatarModule` 继承自 `Module` 并实现 `RouteObjProvider` +- **路由管理**: 通过 `AvatarRouteExport` 统一管理所有路由 +- **依赖注入**: 使用 basic_modular 的依赖注入机制 +- **页面组织**: 按功能分组的页面结构 + +### 2. 核心功能实现 + +#### 虚拟形象创建流程 +1. **拍照页面**: 用户使用相机拍摄照片 +2. **信息填写**: 确认性别和姓名信息 +3. **形象生成**: 后台处理生成虚拟形象 +4. **形象展示**: 展示生成结果 + +#### 形象管理功能 +- **形象展示**: 3D/2D 虚拟形象渲染 +- **形象编辑**: 捏脸和装扮功能 +- **形象复制**: 形象模板复制功能 +- **重命名**: 形象名称管理 + +### 3. 与其他模块集成 + +```dart +// 集成示例 - 从其他模块跳转到虚拟形象相关页面 +class AvatarNavigationHelper { + // 跳转到虚拟形象展示页面 + static void gotoAvatarDisplay() { + Modular.to.pushNamed('/avatar/avatarDisplayPage'); + } + + // 跳转到拍照创建页面 + static void gotoPtaCamera() { + Modular.to.pushNamed('/avatar/PtaAvatarCamera'); + } + + // 跳转到捏脸编辑页面 + static void gotoDressUp() { + Modular.to.pushNamed('/avatar/DressUpServerDataPage'); + } +} +``` + +## 依赖管理与技术栈 + +### 核心依赖 +- **basic_modular**: 模块化框架 +- **basic_modular_route**: 路由管理 +- **flutter**: Flutter 框架 + +### UI 组件 +- **Material Design**: 基础 UI 组件 +- **Custom Widgets**: 虚拟形象专用组件 + +### 数据存储 +- **SharedPreferences**: 配置信息本地存储 +- **文件系统**: 图片和资源文件存储 + +## 最佳实践与规范 + +### 1. 代码组织 +- 页面文件统一放在 `src/avatar/pages/` 目录 +- 按功能模块分别组织（拍照、生成、编辑、展示） +- 对外组件放在 `provide_external` 目录 + +### 2. 路由管理 +- 采用 `RouteExporter` 接口统一路由导出 +- 使用 `RouteMeta` 配置路由元数据 +- 支持路由参数传递和嵌套路由 + +### 3. 用户体验优化 +- 流畅的页面转场动画 +- 友好的加载进度提示 +- 响应式布局适配不同屏幕 + +### 4. 性能优化 +- 合理的资源加载和释放 +- 动画性能优化 +- 内存使用管理 diff --git a/app_car/app_car.md b/app_car/app_car.md new file mode 100644 index 0000000..5681d9d --- /dev/null +++ b/app_car/app_car.md @@ -0,0 +1,934 @@ +# App Car - 车辆控制主模块文档 + +## 模块概述 + +`app_car` 是 OneApp 车辆功能的核心模块，提供完整的车辆控制、状态监控、远程操作等功能。该模块集成了车联网通信、车辆状态管理、空调控制、车门锁控制、充电管理等核心车辆服务。 + +### 基本信息 +- **模块名称**: app_car +- **版本**: 0.6.48+4 +- **仓库**: https://gitlab-rd0.maezia.com/dssomobile/oneapp/dssomobile-oneapp-car-app +- **Flutter 版本**: >=3.0.0 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 目录结构 + +``` +app_car/ +├── lib/ +│ ├── app_car.dart # 主导出文件 +│ ├── app_car_temp.dart # 临时配置文件 +│ ├── generated/ # 代码生成文件 +│ ├── l10n/ # 国际化文件 +│ └── src/ # 源代码目录 +│ ├── ai_chat/ # AI 聊天集成 +│ ├── app_ingeek_mdk/ # 车钥匙 MDK 集成 +│ ├── bloc/ # 状态管理（BLoC） +│ ├── car_animation/ # 车辆动画效果 +│ ├── car_charging_center/ # 充电中心功能 +│ ├── car_charging_profiles/# 充电配置文件 +│ ├── car_climatisation/ # 空调控制 +│ ├── car_climatisation_50/ # 空调控制（5.0版本） +│ ├── car_common_widget/ # 车辆通用组件 +│ ├── car_digital_key_renewal/# 数字钥匙更新 +│ ├── car_enum/ # 车辆相关枚举 +│ ├── car_finder_card/ # 车辆查找卡片 +│ ├── car_health_status/ # 车辆健康状态 +│ ├── car_lock_unlock/ # 车门锁控制 +│ ├── car_vehicle_status/ # 车辆状态管理 +│ ├── constants/ # 常量定义 +│ ├── dbr_card/ # DBR 卡片组件 +│ ├── models/ # 数据模型 +│ ├── pages/ # 页面组件 +│ ├── res/ # 资源文件 +│ ├── utils/ # 工具类 +│ ├── common_import.dart # 通用导入 +│ ├── route_dp.dart # 路由配置 +│ └── route_export.dart # 路由导出 +├── assets/ # 静态资源 +├── pubspec.yaml # 依赖配置 +└── README.md # 项目说明 +``` + +## 核心功能模块 + +### 1. 车辆控制核心 (Vehicle Control Core) + +基于真实的OneApp项目实现，使用统一的Vehicle服务和BLoC状态管理。 + +#### 远程车辆状态管理 (`bloc/home/bloc_rvs.dart`) +```dart +// 实际的远程车辆状态BLoC +class RemoteVehicleStateBloc + extends Bloc { + + RemoteVehicleStateBloc( + RvsService rvs, + ClimatizationService climatization, + int index, + String? noticeVin, + BuildContext? context, + ) : super( + RemoteVehicleState( + rvs: rvs, + climatization: climatization, + index: index, + isRefreshing: false, + ), + ) { + on(_onEnterManualRefreshEvent); + on(_onExecuteManualRefreshEvent); + on(_conditionerEvent); + on(_lockEvent); + on(_unlockEvent); + on(_vehicleOverallStatusEvent); + + // 检查权限 + checkPermission(); + + // 首次进来的时候获取默认车辆信息更新到Vehicle + Vehicle.updateUserVehicleInfo(VehicleUtils.assembleDefaultVehicleLocal()); + + // 拉取页面数据 + refreshHomeData(RvsAction.refresh); + } +} + +// 实际的远程车辆状态数据模型 +@freezed +class RemoteVehicleState with _$RemoteVehicleState { + const factory RemoteVehicleState({ + required RvsService rvs, + required ClimatizationService climatization, + required int index, + required bool isRefreshing, + VehicleRemoteStatus? status, + double? temperature, + ClimatisationStatus? climatisationStatus, + ClimatizationParameter? cParameter, + bool? actionStart, + bool? actionStop, + bool? actionSetting, + bool? actionLock, + RluLockState? lockState, + CfMessage? cfMessage, + bool? locationPermission, + bool? isLocationOpen, + double? distance, + String? searchGeocode, + VhrWarningListMessage? primitiveVhrWarningListMessage, + List? vhrWarningListMessage, + List? vehicleDtos, + }) = _RemoteVehicleState; +} +``` + +#### 车辆服务观察者模式 +```dart +// 实际的车辆服务监听机制 +class Vehicle { + /// 添加服务观察者 + static ObserverClient addServiceObserver( + ServiceType serviceType, + Function(UpdateEvent event, ConnectorAction action, dynamic value) callback, + ) { + return ServiceUtils.getServiceByType(serviceType)?.addObserver(callback); + } + + /// 更新用户车辆信息 + static void updateUserVehicleInfo(VehicleDto? vehicleDto) { + if (vehicleDto != null) { + _currentVehicle = vehicleDto; + } + } +} +``` + +### 2. 车辆状态管理 (`car_vehicle_status/`) + +#### 实时状态监控 +```dart +// 车辆状态管理器 +class VehicleStatusManager { + Stream get statusStream => _statusController.stream; + + final StreamController _statusController = + StreamController.broadcast(); + + // 启动状态监控 + void startStatusMonitoring() { + _statusTimer = Timer.periodic( + Duration(seconds: 30), + (_) => _fetchVehicleStatus(), + ); + } + + Future _fetchVehicleStatus() async { + try { + final status = await _vehicleConnector.getVehicleStatus(); + status.fold( + (failure) => _handleStatusError(failure), + (vehicleStatus) => _statusController.add(vehicleStatus), + ); + } catch (e) { + _handleStatusError(VehicleFailure.networkError(e.toString())); + } + } +} +``` + +#### 车辆健康状态 (`car_health_status/`) +```dart +// 车辆健康状态模型 +class VehicleHealthStatus { + final BatteryHealth batteryHealth; + final EngineHealth engineHealth; + final List maintenanceAlerts; + final List diagnosticCodes; + final DateTime lastCheckTime; + + const VehicleHealthStatus({ + required this.batteryHealth, + required this.engineHealth, + required this.maintenanceAlerts, + required this.diagnosticCodes, + required this.lastCheckTime, + }); + + // 获取整体健康评分 + HealthScore get overallScore { + final scores = [ + batteryHealth.score, + engineHealth.score, + ]; + final average = scores.reduce((a, b) => a + b) / scores.length; + return HealthScore.fromValue(average); + } +} +``` + +### 3. 充电管理 (`car_charging_center/`, `car_charging_profiles/`) + +基于真实项目的充电管理实现，使用Vehicle服务和ChargingOverall状态模型。 + +#### 充电中心控制 (`car_charging_center_bloc.dart`) +```dart +// 实际的充电中心BLoC +class CarChargingCenterBloc + extends Bloc { + + CarChargingCenterBloc() : super(const CarChargingCenterState()) { + on(_refreshChargingEvent); + on(_chargingCenterClearEvent); + + // 注册充电服务 + chargingService(); + + // 先获取内存中的值进行显示 + final cService = ServiceUtils.getChargingService(); + final ChargingOverall? cs = + cService.status == null ? null : cService.status as ChargingOverall; + emit(state.copyWith(chargingOverall: cs)); + + // 刷新充电数据 + add(const CarChargingCenterEvent.refreshCharging()); + } + + /// 充电服务观察者 + ObserverClient? chargingClient; + + /// 充电服务监听 + void chargingService() { + chargingClient = Vehicle.addServiceObserver( + ServiceType.remoteCharging, + (UpdateEvent event, ConnectorAction action, dynamic value) { + if (event == UpdateEvent.onStatusChange) { + if (value != null) { + final chargingOverall = value as ChargingOverall; + emit(state.copyWith(chargingOverall: chargingOverall)); + } + } + }, + ); + } +} + +// 实际的充电状态模型 +@freezed +class CarChargingCenterState with _$CarChargingCenterState { + const factory CarChargingCenterState({ + ChargingOverall? chargingOverall, + bool? isRefreshing, + }) = _CarChargingCenterState; +} +``` + +#### 充电配置文件管理 (`car_charging_profiles_bloc.dart`) +```dart +// 实际的充电配置BLoC +class CarChargingProfilesBloc + extends Bloc { + + CarChargingProfilesBloc() : super(const CarChargingProfilesState()) { + on(_refreshEvent); + on(_deleteEvent); + + // 注册服务监听 + chargingProfilesService(); + + // 首次加载配置文件列表 + add(const CarChargingProfilesEvent.refreshEvent()); + } + + /// 充电配置服务 + void chargingProfilesService() { + chargingClient = Vehicle.addServiceObserver( + ServiceType.remoteCharging, + (UpdateEvent event, ConnectorAction action, dynamic value) { + if (event == UpdateEvent.onStatusChange) { + // 处理充电配置状态变更 + _handleChargingProfilesUpdate(value); + } + }, + ); + } +} +``` + +### 4. 数字钥匙管理 (`car_digital_key_renewal/`, `app_ingeek_mdk/`) + +#### 数字钥匙服务 +```dart +// 数字钥匙管理服务 +class DigitalKeyService { + // 数字钥匙续期 + Future> renewDigitalKey() async { + try { + final result = await _ingeekMdk.renewKey(); + if (result.isSuccess) { + await _updateLocalKeyInfo(result.keyInfo); + return Right(unit); + } else { + return Left(DigitalKeyFailure.renewalFailed(result.error)); + } + } catch (e) { + return Left(DigitalKeyFailure.networkError(e.toString())); + } + } + + // 检查钥匙状态 + Future> checkKeyStatus() async { + try { + final keyInfo = await _ingeekMdk.getKeyInfo(); + return Right(DigitalKeyStatus.fromKeyInfo(keyInfo)); + } catch (e) { + return Left(DigitalKeyFailure.statusCheckFailed(e.toString())); + } + } + + // 激活数字钥匙 + Future> activateDigitalKey(String activationCode) async { + return await _ingeekMdk.activateKey(activationCode); + } +} +``` + +### 5. 车辆查找功能 (`car_finder_card/`) + +#### 车辆定位服务 +```dart +// 车辆查找服务 +class CarFinderService { + // 获取车辆位置 + Future> getVehicleLocation() async { + return await _vehicleConnector.getVehicleLocation(); + } + + // 闪灯鸣笛 + Future> flashAndHonk() async { + return await _vehicleConnector.sendCommand( + VehicleCommand.flashAndHonk(), + ); + } + + // 计算到车辆的距离 + Future> calculateDistanceToVehicle( + UserLocation userLocation, + ) async { + final vehicleLocationResult = await getVehicleLocation(); + return vehicleLocationResult.map((vehicleLocation) { + return Distance.calculate(userLocation, vehicleLocation.coordinates); + }); + } +} +``` + +## 状态管理架构 (`bloc/`) + +基于真实项目的BLoC架构和Flutter Modular依赖注入框架。 + +### 模块化架构实现 +```dart +// 实际的车辆控制模块（app_car.dart） +class CarControlModule extends Module with RouteObjProvider { + @override + List get imports => []; + + @override + List get binds => [ + Bind((i) => CarBloc(), export: true), + ]; + + @override + List get routes { + final r1 = RouteCenterAPI.routeMetaBy(CarControlRouteExport.keyHome); + final r2 = RouteCenterAPI.routeMetaBy(CarControlRouteExport.keyClimatization); + final r3 = RouteCenterAPI.routeMetaBy(CarControlRouteExport.keyCharging); + final r4 = RouteCenterAPI.routeMetaBy(CarControlRouteExport.keyChargingProfile); + // ... 更多路由配置 + + return [ + ChildRoute(r1.path, child: (_, args) => r1.provider(args).as()), + ChildRoute(r2.path, child: (_, args) => r2.provider(args).as()), + ChildRoute(r3.path, child: (_, args) => r3.provider(args).as()), + ChildRoute(r4.path, child: (_, args) => r4.provider(args).as()), + // ... 更多路由实现 + ]; + } +} + +// 实际的CarBloc实现 +class CarBloc extends Bloc { + CarBloc() : super(CarState().getInstance()) { + on((event, emit) { + // 处理车辆相关事件 + }); + } +} +``` + +### 车辆状态BLoC实现 +```dart +// 实际的车辆状态管理BLoC +class CarVehicleBloc extends Bloc { + CarVehicleBloc() : super(const CarVehicleState()) { + on(_initEvent); + on(_refreshEvent); + + // 初始化车辆服务 + initVehicleService(); + } + + void initVehicleService() { + // 注册车辆状态观察者 + Vehicle.addServiceObserver( + ServiceType.remoteVehicleStatus, + (UpdateEvent event, ConnectorAction action, dynamic value) { + if (event == UpdateEvent.onStatusChange) { + final status = value as VehicleRemoteStatus; + emit(state.copyWith(vehicleStatus: status)); + } + }, + ); + } +} +``` + +## 数据模型 (`models/`) + +### 车辆状态模型 +```dart +// 车辆状态模型 +class VehicleStatus { + final String vehicleId; + final LockStatus lockStatus; + final BatteryStatus batteryStatus; + final ClimatisationStatus climatisationStatus; + final ChargingStatus chargingStatus; + final VehicleLocation? location; + final DateTime lastUpdated; + + const VehicleStatus({ + required this.vehicleId, + required this.lockStatus, + required this.batteryStatus, + required this.climatisationStatus, + required this.chargingStatus, + this.location, + required this.lastUpdated, + }); + + factory VehicleStatus.fromJson(Map json) { + return VehicleStatus( + vehicleId: json['vehicle_id'], + lockStatus: LockStatus.fromString(json['lock_status']), + batteryStatus: BatteryStatus.fromJson(json['battery_status']), + climatisationStatus: ClimatisationStatus.fromJson(json['climatisation_status']), + chargingStatus: ChargingStatus.fromJson(json['charging_status']), + location: json['location'] != null + ? VehicleLocation.fromJson(json['location']) + : null, + lastUpdated: DateTime.parse(json['last_updated']), + ); + } +} +``` + +### 车辆控制命令模型 +```dart +// 车辆控制命令 +abstract class VehicleCommand { + const VehicleCommand(); + + // 车门锁命令 + factory VehicleCommand.lock() = LockCommand; + factory VehicleCommand.unlock() = UnlockCommand; + + // 空调命令 + factory VehicleCommand.startClimatisation({ + required double temperature, + AirConditioningMode mode, + }) = StartClimatisationCommand; + + factory VehicleCommand.stopClimatisation() = StopClimatisationCommand; + + // 充电命令 + factory VehicleCommand.startCharging({ + ChargingProfile? profile, + }) = StartChargingCommand; + + factory VehicleCommand.stopCharging() = StopChargingCommand; + + // 车辆查找命令 + factory VehicleCommand.flashAndHonk() = FlashAndHonkCommand; +} +``` + +## 枚举定义 (`car_enum/`) + +### 车辆状态枚举 +```dart +// 车门锁状态 +enum LockStatus { + locked, + unlocked, + unknown; + + static LockStatus fromString(String value) { + switch (value.toLowerCase()) { + case 'locked': + return LockStatus.locked; + case 'unlocked': + return LockStatus.unlocked; + default: + return LockStatus.unknown; + } + } +} + +// 充电状态 +enum ChargingStatus { + notConnected, + connected, + charging, + chargingComplete, + chargingError; + + bool get isCharging => this == ChargingStatus.charging; + bool get isConnected => this != ChargingStatus.notConnected; +} + +// 空调模式 +enum AirConditioningMode { + auto, + heat, + cool, + ventilation, + defrost; + + String get displayName { + switch (this) { + case AirConditioningMode.auto: + return '自动'; + case AirConditioningMode.heat: + return '制热'; + case AirConditioningMode.cool: + return '制冷'; + case AirConditioningMode.ventilation: + return '通风'; + case AirConditioningMode.defrost: + return '除霜'; + } + } +} +``` + +## UI 组件 (`car_common_widget/`) + +### 车辆状态卡片 +```dart +// 车辆状态卡片组件 +class VehicleStatusCard extends StatelessWidget { + final VehicleStatus status; + final VoidCallback? onRefresh; + + const VehicleStatusCard({ + Key? key, + required this.status, + this.onRefresh, + }) : super(key: key); + + @override + Widget build(BuildContext context) { + return Card( + child: Padding( + padding: EdgeInsets.all(16), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + _buildHeader(), + SizedBox(height: 16), + _buildStatusGrid(), + SizedBox(height: 16), + _buildActionButtons(), + ], + ), + ), + ); + } + + Widget _buildStatusGrid() { + return GridView.count( + shrinkWrap: true, + physics: NeverScrollableScrollPhysics(), + crossAxisCount: 2, + children: [ + _buildStatusItem('车门', status.lockStatus.displayName), + _buildStatusItem('电量', '${status.batteryStatus.percentage}%'), + _buildStatusItem('空调', status.climatisationStatus.displayName), + _buildStatusItem('充电', status.chargingStatus.displayName), + ], + ); + } +} +``` + +### 车辆控制面板 +```dart +// 车辆控制面板 +class VehicleControlPanel extends StatelessWidget { + final VehicleStatus status; + final Function(VehicleCommand) onCommand; + + const VehicleControlPanel({ + Key? key, + required this.status, + required this.onCommand, + }) : super(key: key); + + @override + Widget build(BuildContext context) { + return Column( + children: [ + _buildLockControls(), + SizedBox(height: 16), + _buildClimatisationControls(), + SizedBox(height: 16), + _buildChargingControls(), + SizedBox(height: 16), + _buildFinderControls(), + ], + ); + } + + Widget _buildLockControls() { + return Row( + children: [ + Expanded( + child: ElevatedButton.icon( + onPressed: status.lockStatus == LockStatus.unlocked + ? () => onCommand(VehicleCommand.lock()) + : null, + icon: Icon(Icons.lock), + label: Text('上锁'), + ), + ), + SizedBox(width: 8), + Expanded( + child: ElevatedButton.icon( + onPressed: status.lockStatus == LockStatus.locked + ? () => onCommand(VehicleCommand.unlock()) + : null, + icon: Icon(Icons.lock_open), + label: Text('解锁'), + ), + ), + ], + ); + } +} +``` + +## 动画效果 (`car_animation/`) + +### 车辆控制动画 +```dart +// 车辆控制动画控制器 +class VehicleAnimationController extends ChangeNotifier { + late AnimationController _lockAnimationController; + late AnimationController _chargingAnimationController; + + Animation get lockAnimation => _lockAnimationController; + Animation get chargingAnimation => _chargingAnimationController; + + void initialize(TickerProvider vsync) { + _lockAnimationController = AnimationController( + duration: Duration(milliseconds: 500), + vsync: vsync, + ); + + _chargingAnimationController = AnimationController( + duration: Duration(milliseconds: 1500), + vsync: vsync, + )..repeat(); + } + + void playLockAnimation() { + _lockAnimationController.forward().then((_) { + _lockAnimationController.reverse(); + }); + } + + void startChargingAnimation() { + _chargingAnimationController.repeat(); + } + + void stopChargingAnimation() { + _chargingAnimationController.stop(); + } +} +``` + +## AI 聊天集成 (`ai_chat/`) + +### AI 聊天车辆控制 +```dart +// AI 聊天车辆控制集成 +class AIChatVehicleIntegration { + final VehicleControlRepository _vehicleRepository; + final AIChatAssistant _aiAssistant; + + AIChatVehicleIntegration(this._vehicleRepository, this._aiAssistant); + + // 处理车辆控制语音命令 + Future handleVehicleCommand(String command) async { + final intent = await _aiAssistant.parseIntent(command); + + switch (intent.type) { + case VehicleIntentType.lock: + return await _handleLockCommand(); + case VehicleIntentType.unlock: + return await _handleUnlockCommand(); + case VehicleIntentType.startAC: + return await _handleStartACCommand(intent.parameters); + case VehicleIntentType.stopAC: + return await _handleStopACCommand(); + default: + return AIChatResponse.error('未识别的车辆控制命令'); + } + } + + Future _handleLockCommand() async { + final result = await _vehicleRepository.lockVehicle(); + return result.fold( + (failure) => AIChatResponse.error('车辆上锁失败：${failure.message}'), + (_) => AIChatResponse.success('车辆已成功上锁'), + ); + } +} +``` + +## 依赖管理 + +基于实际的pubspec.yaml配置，展示真实的项目依赖关系。 + +### 核心依赖 +```yaml +# 车辆连接和服务依赖 +dependencies: + car_connector: ^0.4.11 # 车联网连接服务 + car_vehicle: ^0.6.4+1 # 车辆基础服务 + car_vur: ^0.1.12 # 车辆更新记录 + flutter_ingeek_carkey: 1.6.2 # 数字钥匙 SDK + + # 框架依赖 + basic_modular: ^0.2.3 # 模块化框架 + basic_modular_route: ^0.2.1 # 路由管理 + basic_intl: ^0.2.0 # 国际化支持 + basic_storage: ^0.2.2 # 本地存储 + + # 业务服务依赖 + clr_mno: ^0.2.2 # MNO 服务 + clr_geo: ^0.2.16+1 # 地理位置服务 + + # 功能性依赖 + dartz: ^0.10.1 # 函数式编程支持 + freezed_annotation: ^2.2.0 # 不可变类生成 + json_annotation: ^4.9.0 # JSON 序列化 + + # AI功能集成 + ai_chat_assistant: # AI 聊天助手模块 + path: ../ai_chat_assistant + + # UI组件依赖 + carousel_slider: ^4.2.1 # 轮播图组件 + flutter_slidable: ^3.1.2 # 滑动组件 + overlay_support: ^2.1.0 # 覆盖层支持 + provider: ^6.0.5 # 状态管理 +``` + +### 模块间依赖关系 +```dart +// 实际的模块依赖结构（基于项目配置） +app_car/ +├── car_connector: 车辆连接服务 (核心通信) +├── car_vehicle: 车辆基础服务 (状态管理) +├── car_vur: 车辆更新记录 (版本控制) +├── flutter_ingeek_carkey: 数字钥匙SDK (安全认证) +├── ai_chat_assistant: AI聊天助手 (智能交互) +├── clr_mno: MNO服务 (网络运营商) +├── clr_geo: 地理位置服务 (定位功能) +└── basic_*: 基础框架模块群 +``` + +## 路由配置 (`route_dp.dart`, `route_export.dart`) + +### 路由定义 +```dart +// 车辆模块路由配置 +class CarRoutes { + static const String vehicleStatus = '/car/status'; + static const String vehicleControl = '/car/control'; + static const String chargingCenter = '/car/charging'; + static const String digitalKey = '/car/digital-key'; + static const String carFinder = '/car/finder'; + static const String climatisation = '/car/climatisation'; + + static List get routes => [ + ChildRoute( + vehicleStatus, + child: (context, args) => VehicleStatusPage(), + ), + ChildRoute( + vehicleControl, + child: (context, args) => VehicleControlPage(), + ), + ChildRoute( + chargingCenter, + child: (context, args) => ChargingCenterPage(), + ), + ChildRoute( + digitalKey, + child: (context, args) => DigitalKeyPage(), + ), + ChildRoute( + carFinder, + child: (context, args) => CarFinderPage(), + ), + ChildRoute( + climatisation, + child: (context, args) => ClimatisationPage(), + ), + ]; +} +``` + +## 常量定义 (`constants/`) + +### 车辆常量 +```dart +// 车辆控制常量 +class CarConstants { + // 温度范围 + static const double minTemperature = 16.0; + static const double maxTemperature = 32.0; + static const double defaultTemperature = 22.0; + + // 充电相关 + static const int minChargingTarget = 20; + static const int maxChargingTarget = 100; + static const int defaultChargingTarget = 80; + + // 动画时长 + static const Duration lockAnimationDuration = Duration(milliseconds: 500); + static const Duration statusUpdateInterval = Duration(seconds: 30); + + // 错误重试 + static const int maxRetryCount = 3; + static const Duration retryDelay = Duration(seconds: 2); +} +``` + +## 错误处理 + +### 车辆特定异常 +```dart +// 车辆操作异常 +abstract class VehicleFailure { + const VehicleFailure(); + + factory VehicleFailure.networkError(String message) = NetworkFailure; + factory VehicleFailure.authenticationError() = AuthenticationFailure; + factory VehicleFailure.vehicleNotFound() = VehicleNotFoundFailure; + factory VehicleFailure.commandTimeout() = CommandTimeoutFailure; + factory VehicleFailure.vehicleOffline() = VehicleOfflineFailure; + factory VehicleFailure.insufficientBattery() = InsufficientBatteryFailure; +} + +class NetworkFailure extends VehicleFailure { + final String message; + const NetworkFailure(this.message); +} + +class VehicleOfflineFailure extends VehicleFailure { + const VehicleOfflineFailure(); +} +``` + +## 性能优化 + +### 状态缓存策略 +- 车辆状态本地缓存 +- 智能刷新机制 +- 后台状态同步 + +### 网络优化 +- 命令队列管理 +- 批量请求处理 +- 离线命令缓存 + +### UI 优化 +- 状态变更动画 +- 加载状态指示 +- 错误状态处理 + +## 测试策略 + +### 单元测试 +- BLoC 状态管理测试 +- 服务类功能测试 +- 模型序列化测试 + +### 集成测试 +- 车联网通信测试 +- 状态同步测试 +- 命令执行测试 + +### UI 测试 +- 控制面板交互测试 +- 状态显示测试 +- 错误场景测试 + +## 总结 + +`app_car` 模块是 OneApp 车辆功能的核心，提供了完整的车辆控制和状态管理功能。模块采用 BLoC 模式进行状态管理，具有清晰的分层架构和良好的可扩展性。通过集成 AI 聊天助手和数字钥匙技术，为用户提供了智能化和便捷的车辆操作体验。 diff --git a/app_car/app_carwatcher.md b/app_car/app_carwatcher.md new file mode 100644 index 0000000..3a99670 --- /dev/null +++ b/app_car/app_carwatcher.md @@ -0,0 +1,625 @@ +# App Carwatcher 车辆监控模块 + +## 模块概述 + +`app_carwatcher` 是 OneApp 车联网生态中的车辆监控模块，负责实时监控车辆状态、位置信息、安全警报等功能。该模块为用户提供全方位的车辆安全监控服务，确保车辆的安全性和用户的使用体验。 + +### 基本信息 +- **模块名称**: app_carwatcher +- **版本**: 0.1.2 +- **描述**: 车辆监控应用模块 +- **Flutter 版本**: >=2.10.5 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **实时车辆监控** + - 车辆位置实时追踪 + - 车辆状态监控（锁车状态、车窗状态等） + - 车辆异常报警 + +2. **地理围栏管理** + - 围栏设置和编辑 + - 围栏事件监控 + - POI 地点搜索 + +3. **历史报告查看** + - 日报详情查看 + - 事件详情展示 + - 事件过滤功能 + +4. **地图集成** + - 车辆位置可视化 + - 历史轨迹查看 + - 地理围栏设置 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── app_carwatcher.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── app_carwatcher_module.dart # 模块定义和依赖注入 +│ ├── route_dp.dart # 路由配置 +│ ├── route_export.dart # 路由导出 +│ ├── blocs/ # 状态管理 +│ ├── constants/ # 常量定义 +│ ├── pages/ # 页面组件 +│ │ ├── home/ # 首页 +│ │ ├── geo_fence_list/ # 地理围栏列表 +│ │ ├── geo_fence_detail/ # 地理围栏详情 +│ │ ├── geo_fence_search_poi/ # POI搜索 +│ │ ├── daily_report/ # 日报详情 +│ │ ├── event_detail/ # 事件详情 +│ │ └── event_filter/ # 事件过滤 +│ └── utils/ # 工具类 +├── generated/ # 代码生成文件 +└── l10n/ # 国际化文件 +``` + +## 核心实现 + +### 1. 模块入口文件 + +**文件**: `lib/app_carwatcher.dart` + +```dart +/// Carwatcher APP +library app_carwatcher; + +export 'src/app_carwatcher_module.dart'; +export 'src/route_dp.dart'; +export 'src/route_export.dart'; +``` + +### 2. 模块定义与路由配置 + +**文件**: `src/app_carwatcher_module.dart` + +```dart +import 'package:basic_modular/modular.dart'; +import 'package:basic_modular_route/basic_modular_route.dart'; + +import 'route_export.dart'; + +/// Module负责的页面 +class AppCarwatcherModule extends Module with RouteObjProvider { + @override + List get routes { + final moduleHome = RouteCenterAPI.routeMetaBy(AppCarwatcherRouteExport.keyModule); + final carWatcherHomePage = RouteCenterAPI.routeMetaBy(AppCarwatcherRouteExport.keyCarWatcherHomePage); + final geoFenceListPage = RouteCenterAPI.routeMetaBy(AppCarwatcherRouteExport.keyGeoFenceListPage); + final geoFenceDetailPage = RouteCenterAPI.routeMetaBy(AppCarwatcherRouteExport.keyGeoFenceDetailPage); + final searchPoiPage = RouteCenterAPI.routeMetaBy(AppCarwatcherRouteExport.keyGeoFenceSearchPOIPage); + final dailyReportDetailPage = RouteCenterAPI.routeMetaBy(AppCarwatcherRouteExport.keyDailyReportPage); + final eventFilterPage = RouteCenterAPI.routeMetaBy(AppCarwatcherRouteExport.keyEventFilterPage); + final reportDetailPage = RouteCenterAPI.routeMetaBy(AppCarwatcherRouteExport.keyReportDetailPage); + + return [ + ChildRoute(moduleHome.path, child: (_, args) => moduleHome.provider(args).as()), + ChildRoute(carWatcherHomePage.path, child: (_, args) => carWatcherHomePage.provider(args).as()), + ChildRoute(geoFenceListPage.path, child: (_, args) => geoFenceListPage.provider(args).as()), + ChildRoute(geoFenceDetailPage.path, child: (_, args) => geoFenceDetailPage.provider(args).as()), + ChildRoute(searchPoiPage.path, child: (_, args) => searchPoiPage.provider(args).as()), + ChildRoute(dailyReportDetailPage.path, child: (_, args) => dailyReportDetailPage.provider(args).as()), + ChildRoute(eventFilterPage.path, child: (_, args) => eventFilterPage.provider(args).as()), + ChildRoute(reportDetailPage.path, child: (_, args) => reportDetailPage.provider(args).as()), + ]; + } +} +``` + +### 3. 路由导出管理 + +**文件**: `src/route_export.dart` + +```dart +import 'package:basic_modular/modular.dart'; +import 'package:clr_carwatcher/clr_carwatcher.dart'; +import 'package:ui_mapview/ui_mapview.dart'; + +import 'app_carwatcher_module.dart'; +import 'pages/daily_report/daily_report_detail_page.dart'; +import 'pages/event_detail/report_event_detail_page.dart'; +import 'pages/event_filter/event_filter_page.dart'; +import 'pages/geo_fence_detail/geo_fence_detail_page.dart'; +import 'pages/geo_fence_list/geo_fence_list_page.dart'; +import 'pages/geo_fence_search_poi/geo_fence_search_poi_page.dart'; +import 'pages/home/car_watcher_home_page.dart'; + +/// app_carwatcher的路由管理 +class AppCarwatcherRouteExport implements RouteExporter { + // 路由常量定义 + static const String keyModule = 'app_carWatcher'; + static const String keyCarWatcherHomePage = 'app_carWatcher.carWatcher_home'; + static const String keyGeoFenceListPage = 'app_carWatcher.geoFenceList'; + static const String keyGeoFenceDetailPage = 'app_carWatcher.geoFenceDetail'; + static const String keyGeoFenceSearchPOIPage = 'app_carWatcher.poiSearch'; + static const String keyDailyReportPage = 'app_carWatcher.dailyReport'; + static const String keyEventFilterPage = 'app_carWatcher.eventFilter'; + static const String keyReportDetailPage = 'app_carWatcher.reportDetail'; + + @override + List exportRoutes() { + final r0 = RouteMeta(keyModule, '/app_carWatcher', (args) => AppCarwatcherModule(), null); + + final r1 = RouteMeta(keyCarWatcherHomePage, '/carWatcher_home', + (args) => CarWatcherHomePage(args.data['vin'] as String), r0); + + final r2 = RouteMeta(keyGeoFenceListPage, '/geoFenceList', + (args) => GeoFenceListPage(args.data['vin'] as String), r0); + + final r3 = RouteMeta(keyGeoFenceDetailPage, '/geoFenceDetail', + (args) => GeoFenceDetailPage( + args.data['vin'] as String, + args.data['fenceId'] as String?, + args.data['fenceOnCount'] as int, + ), r0); + + final r4 = RouteMeta(keyGeoFenceSearchPOIPage, '/poiSearch', + (args) => GeoFenceSearchPOIPage( + args.data['province'] as String?, + args.data['city'] as String?, + args.data['cityCode'] as String?, + args.data['fenceLatLng'] as LatLng?, + ), r0); + + final r5 = RouteMeta(keyDailyReportPage, '/dailyReport', + (args) => DailyReportDetailPage( + args.data['vin'] as String, + args.data['reportId'] as String, + ), r0); + + final r6 = RouteMeta(keyEventFilterPage, '/eventFilter', + (args) => EventFilterPage(args.data['eventTypes'] as List?), r0); + + final r7 = RouteMeta(keyReportDetailPage, '/reportDetail', + (args) => ReportEventDetailPage( + args.data['vin'] as String, + args.data['eventId'] as String, + ), r0); + + return [r0, r1, r2, r3, r4, r5, r6, r7]; + } +} +``` + +## 核心页面功能 + +### 1. 车辆监控首页 + +**文件**: `pages/home/car_watcher_home_page.dart` + +```dart +import 'package:app_consent/app_consent.dart'; +import 'package:basic_intl/intl.dart'; +import 'package:basic_logger/basic_logger.dart'; +import 'package:basic_modular/modular.dart'; +import 'package:flutter/material.dart'; +import 'package:ui_basic/pull_to_refresh.dart'; +import 'package:ui_basic/screen_util.dart'; +import 'package:ui_basic/ui_basic.dart'; + +/// CarWatcher首页 +class CarWatcherHomePage extends StatefulWidget with RouteObjProvider { + const CarWatcherHomePage(this.vin, {Key? key}) : super(key: key); + + /// 车辆vin码 + final String vin; + + @override + State createState() => _CarWatcherHomeState(); +} + +class _CarWatcherHomeState extends State { + final CarWatcherHomeBloc _bloc = CarWatcherHomeBloc(); + late List images = []; + + @override + void initState() { + super.initState(); + + // 初始化banner数据 + images.add(BannerBean( + imageUrl: 'packages/app_carwatcher/assets/images/icon_banner1.png', + title: '车辆监控横幅1', + )); + + images.add(BannerBean( + imageUrl: 'packages/app_carwatcher/assets/images/icon_banner2.png', + title: '车辆监控横幅2', + )); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('车辆监控')), + body: RefreshIndicator( + onRefresh: () async { + _bloc.add(RefreshDataEvent()); + }, + child: SingleChildScrollView( + child: Column( + children: [ + // Banner轮播 + HomeBannerWidget(images: images), + + // 功能入口区域 + _buildFunctionEntries(), + + // 车辆状态信息 + _buildVehicleStatus(), + + // 最近事件列表 + _buildRecentEvents(), + ], + ), + ), + ), + ); + } + + Widget _buildFunctionEntries() { + return Container( + padding: EdgeInsets.all(16), + child: GridView.count( + shrinkWrap: true, + physics: NeverScrollableScrollPhysics(), + crossAxisCount: 2, + children: [ + _buildFunctionCard( + icon: Icons.location_on, + title: '地理围栏', + onTap: () => _navigateToGeoFenceList(), + ), + _buildFunctionCard( + icon: Icons.event_note, + title: '历史报告', + onTap: () => _navigateToDailyReport(), + ), + ], + ), + ); + } + + Widget _buildFunctionCard({ + required IconData icon, + required String title, + required VoidCallback onTap, + }) { + return Card( + child: InkWell( + onTap: onTap, + child: Column( + mainAxisAlignment: MainAxisAlignment.center, + children: [ + Icon(icon, size: 48, color: Colors.blue), + SizedBox(height: 8), + Text(title, style: TextStyle(fontSize: 16)), + ], + ), + ), + ); + } + + void _navigateToGeoFenceList() { + Modular.to.pushNamed('/app_carWatcher/geoFenceList', arguments: {'vin': widget.vin}); + } + + void _navigateToDailyReport() { + Modular.to.pushNamed('/app_carWatcher/dailyReport', arguments: {'vin': widget.vin}); + } +} +``` + +### 2. 地理围栏功能 + +#### 围栏列表页面 +```dart +/// 地理围栏列表页面 +class GeoFenceListPage extends StatefulWidget { + const GeoFenceListPage(this.vin, {Key? key}) : super(key: key); + + final String vin; + + @override + State createState() => _GeoFenceListPageState(); +} + +class _GeoFenceListPageState extends State { + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar( + title: Text('地理围栏'), + actions: [ + IconButton( + icon: Icon(Icons.add), + onPressed: () => _navigateToCreateFence(), + ), + ], + ), + body: ListView.builder( + itemCount: fenceList.length, + itemBuilder: (context, index) { + final fence = fenceList[index]; + return ListTile( + title: Text(fence.name), + subtitle: Text(fence.address), + trailing: Switch( + value: fence.isEnabled, + onChanged: (value) => _toggleFence(fence, value), + ), + onTap: () => _navigateToFenceDetail(fence), + ); + }, + ), + ); + } + + void _navigateToCreateFence() { + Modular.to.pushNamed('/app_carWatcher/geoFenceDetail', arguments: { + 'vin': widget.vin, + 'fenceId': null, + 'fenceOnCount': 0, + }); + } +} +``` + +#### 围栏详情页面 +```dart +/// 地理围栏详情页面 +class GeoFenceDetailPage extends StatefulWidget { + const GeoFenceDetailPage(this.vin, this.fenceId, this.fenceOnCount, {Key? key}) + : super(key: key); + + final String vin; + final String? fenceId; + final int fenceOnCount; + + @override + State createState() => _GeoFenceDetailPageState(); +} + +class _GeoFenceDetailPageState extends State { + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar( + title: Text(widget.fenceId == null ? '新建围栏' : '编辑围栏'), + actions: [ + TextButton( + onPressed: _saveFence, + child: Text('保存'), + ), + ], + ), + body: Column( + children: [ + // 地图显示区域 + Expanded( + flex: 2, + child: Container( + color: Colors.grey[300], + child: Center(child: Text('地图显示区域')), + ), + ), + + // 设置区域 + Expanded( + flex: 1, + child: Padding( + padding: EdgeInsets.all(16), + child: Column( + children: [ + TextField( + decoration: InputDecoration( + labelText: '围栏名称', + border: OutlineInputBorder(), + ), + ), + SizedBox(height: 16), + Row( + children: [ + Text('半径(米): '), + Expanded( + child: Slider( + min: 100, + max: 5000, + value: 500, + onChanged: (value) {}, + ), + ), + Text('500'), + ], + ), + ], + ), + ), + ), + ], + ), + ); + } + + void _saveFence() { + // 保存围栏逻辑 + Navigator.of(context).pop(); + } +} +``` + +### 3. POI搜索功能 + +```dart +/// POI搜索页面 +class GeoFenceSearchPOIPage extends StatefulWidget { + const GeoFenceSearchPOIPage( + this.province, + this.city, + this.cityCode, + this.fenceLatLng, { + Key? key, + }) : super(key: key); + + final String? province; + final String? city; + final String? cityCode; + final LatLng? fenceLatLng; + + @override + State createState() => _GeoFenceSearchPOIPageState(); +} + +class _GeoFenceSearchPOIPageState extends State { + final TextEditingController _searchController = TextEditingController(); + List _searchResults = []; + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar( + title: TextField( + controller: _searchController, + decoration: InputDecoration( + hintText: '搜索地点', + border: InputBorder.none, + suffixIcon: IconButton( + icon: Icon(Icons.search), + onPressed: _performSearch, + ), + ), + onSubmitted: (_) => _performSearch(), + ), + ), + body: ListView.builder( + itemCount: _searchResults.length, + itemBuilder: (context, index) { + final poi = _searchResults[index]; + return ListTile( + title: Text(poi.name), + subtitle: Text(poi.address), + onTap: () => _selectPOI(poi), + ); + }, + ), + ); + } + + void _performSearch() { + // 执行POI搜索 + setState(() { + _searchResults = [ + // 模拟搜索结果 + POIItem(name: '示例地点1', address: '示例地址1'), + POIItem(name: '示例地点2', address: '示例地址2'), + ]; + }); + } + + void _selectPOI(POIItem poi) { + Navigator.of(context).pop(poi); + } +} + +class POIItem { + final String name; + final String address; + + POIItem({required this.name, required this.address}); +} +``` + +## 状态管理 + +### BLoC状态管理模式 +```dart +// CarWatcher首页状态管理 +class CarWatcherHomeBloc extends Bloc { + CarWatcherHomeBloc() : super(CarWatcherHomeInitial()) { + on(_onLoadData); + on(_onRefreshData); + } + + Future _onLoadData(LoadDataEvent event, Emitter emit) async { + emit(CarWatcherHomeLoading()); + + try { + // 加载车辆数据 + final vehicleData = await loadVehicleData(event.vin); + emit(CarWatcherHomeLoaded(vehicleData)); + } catch (e) { + emit(CarWatcherHomeError(e.toString())); + } + } + + Future _onRefreshData(RefreshDataEvent event, Emitter emit) async { + // 刷新数据逻辑 + } +} + +// 事件定义 +abstract class CarWatcherHomeEvent {} + +class LoadDataEvent extends CarWatcherHomeEvent { + final String vin; + LoadDataEvent(this.vin); +} + +class RefreshDataEvent extends CarWatcherHomeEvent {} + +// 状态定义 +abstract class CarWatcherHomeState {} + +class CarWatcherHomeInitial extends CarWatcherHomeState {} + +class CarWatcherHomeLoading extends CarWatcherHomeState {} + +class CarWatcherHomeLoaded extends CarWatcherHomeState { + final VehicleData data; + CarWatcherHomeLoaded(this.data); +} + +class CarWatcherHomeError extends CarWatcherHomeState { + final String message; + CarWatcherHomeError(this.message); +} +``` + +## 依赖管理 + +### 核心依赖 +- **clr_carwatcher**: 车辆监控服务SDK +- **ui_mapview**: 地图视图组件 +- **app_consent**: 用户授权管理 + +### 框架依赖 +- **basic_modular**: 模块化框架 +- **basic_modular_route**: 路由管理 +- **basic_intl**: 国际化支持 +- **basic_logger**: 日志服务 + +### UI 组件依赖 +- **ui_basic**: 基础UI组件 +- **flutter/material**: Material Design组件 + +## 最佳实践 + +### 1. 代码组织 +- 按功能模块组织页面和组件 +- 统一的路由管理和导航 +- 清晰的状态管理模式 + +### 2. 用户体验 +- 响应式设计适配不同屏幕 +- 友好的加载和错误提示 +- 流畅的页面转场 + +### 3. 性能优化 +- 合理的状态管理避免不必要的重建 +- 地图资源的合理加载和释放 +- 网络请求的优化和缓存 diff --git a/app_car/app_charging.md b/app_car/app_charging.md new file mode 100644 index 0000000..06619c7 --- /dev/null +++ b/app_car/app_charging.md @@ -0,0 +1,899 @@ +# App Charging - 充电管理模块文档 + +## 模块概述 + +`app_charging` 是 OneApp 的充电管理核心模块，提供完整的电动车充电功能，包括充电地图、充电站查找、订单管理、支付结算等全流程充电服务。该模块集成了高德地图服务、BLoC状态管理、路由导航等，为用户提供便捷的充电体验。 + +### 基本信息 +- **模块名称**: app_charging +- **路径**: oneapp_app_car/app_charging/ +- **依赖**: car_services, car_vehicle, clr_charging, basic_modular +- **主要功能**: 充电地图、充电站搜索、订单管理、智能寻桩 + +## 目录结构 + +``` +app_charging/ +├── lib/ +│ ├── app_charging.dart # 主导出文件 +│ ├── generated/ # 代码生成文件 +│ ├── l10n/ # 国际化文件 +│ └── src/ # 源代码目录 +│ ├── app_charging_module.dart # 充电模块配置 +│ ├── blocs/ # 状态管理（BLoC） +│ ├── carfinder/ # 车辆查找功能 +│ ├── constants/ # 常量定义 +│ ├── pages/ # 页面组件 +│ │ └── public_charging/ # 公共充电页面 +│ │ ├── charging_map_home_page/ # 充电地图首页 +│ │ ├── charging_station_detail_page/ # 充电站详情 +│ │ ├── charging_query_order_list_page/ # 订单列表 +│ │ ├── charging_report_page/ # 充电报告 +│ │ ├── charging_smart_pile_finding_page/ # 智能寻桩 +│ │ └── ... # 其他充电功能页面 +│ ├── utils/ # 工具类 +│ ├── route_dp.dart # 路由配置 +│ ├── route_export.dart # 路由导出 +│ └── switch_vehicle.dart # 车辆切换功能 +├── assets/ # 静态资源 +└── README.md # 项目说明 +``` + +# App Charging - 充电管理模块文档 + +## 模块概述 + +`app_charging` 是 OneApp 的充电管理核心模块，提供完整的电动车充电功能，包括充电地图、充电站查找、订单管理、支付结算等全流程充电服务。该模块集成了高德地图服务、BLoC状态管理、路由导航等，为用户提供便捷的充电体验。 + +### 基本信息 +- **模块名称**: app_charging +- **路径**: oneapp_app_car/app_charging/ +- **依赖**: car_services, car_vehicle, clr_charging, basic_modular +- **主要功能**: 充电地图、充电站搜索、订单管理、智能寻桩 + +## 目录结构 + +``` +app_charging/ +├── lib/ +│ ├── app_charging.dart # 主导出文件 +│ ├── generated/ # 代码生成文件 +│ ├── l10n/ # 国际化文件 +│ └── src/ # 源代码目录 +│ ├── app_charging_module.dart # 充电模块配置 +│ ├── blocs/ # 状态管理（BLoC） +│ ├── carfinder/ # 车辆查找功能 +│ ├── constants/ # 常量定义 +│ ├── pages/ # 页面组件 +│ │ └── public_charging/ # 公共充电页面 +│ │ ├── charging_map_home_page/ # 充电地图首页 +│ │ ├── charging_station_detail_page/ # 充电站详情 +│ │ ├── charging_query_order_list_page/ # 订单列表 +│ │ ├── charging_report_page/ # 充电报告 +│ │ ├── charging_smart_pile_finding_page/ # 智能寻桩 +│ │ ├── charging_coupon_page/ # 充电优惠券 +│ │ ├── charging_power_monitor_page/ # 功率监控 +│ │ └── ... # 其他充电功能页面 +│ ├── utils/ # 工具类 +│ ├── route_dp.dart # 路由配置 +│ ├── route_export.dart # 路由导出 +│ └── switch_vehicle.dart # 车辆切换功能 +├── assets/ # 静态资源 +└── README.md # 项目说明 +``` + +## 核心实现 + +### 1. 模块主导出文件 + +**文件**: `lib/app_charging.dart` + +```dart +/// charging pages +library app_charging; + +export 'package:car_services/services.dart'; +export 'package:car_vehicle/vehicle.dart'; + +export 'src/app_charging_module.dart'; +export 'src/pages/public_charging/charging_map_card/charging_map_card.dart'; +export 'src/pages/public_charging/charging_map_home_page/charging_map_home_page.dart'; +export 'src/pages/public_charging/charging_query_order_list_page/charging_query_order_list_page.dart'; + +// 路由键导出 +export 'src/route_dp.dart' show ChargingReservationRouteKey; +export 'src/route_dp.dart' show CarChargingCouponRouteKey; +export 'src/route_dp.dart' show ChargingCpoCollectionRouteKey; +export 'src/route_dp.dart' show ChargingDetectiveRouteKey; +export 'src/route_dp.dart' show ChargingMapHomeNonOwnerRouteKey; +export 'src/route_dp.dart' show ChargingMapHomeRouteKey; +export 'src/route_dp.dart' show ChargingPowerMonitorResultRouteKey; +export 'src/route_dp.dart' show ChargingPowerMonitorRouteKey; +export 'src/route_dp.dart' show ChargingPrePaySettingRouteKey; +export 'src/route_dp.dart' show ChargingQueryOrderDetailRouteKey; +export 'src/route_dp.dart' show ChargingQueryOrderListRouteKey; +export 'src/route_dp.dart' show ChargingQueryRatingRouteKey; +export 'src/route_dp.dart' show ChargingReportRouteKey; +export 'src/route_dp.dart' show ChargingSmartPileFindingRouteKey; +export 'src/route_dp.dart' show ChargingStationDetailRouteKey; +export 'src/route_dp.dart' show ChargingStationGuideRouteKey; +export 'src/route_dp.dart' show ChargingVehicleReportRouteKey; +export 'src/route_export.dart'; +``` + +### 2. 模块定义与依赖管理 + +**文件**: `src/app_charging_module.dart` + +```dart +import 'package:basic_logger/basic_logger.dart'; +import 'package:basic_modular/modular.dart'; +import 'package:basic_modular_route/basic_modular_route.dart'; +import 'package:clr_account/account.dart'; +import 'package:clr_charging/clr_charging.dart'; +import 'package:ui_basic/ui_basic.dart'; + +import 'constants/module_constant.dart'; +import 'route_export.dart'; + +/// 充电模块定义 +class AppChargingModule extends Module with RouteObjProvider, AppLifeCycleListener { + @override + List> get binds => []; + + @override + List get imports => [AccountConModule(), ClrChargingModule()]; + + @override + List get routes { + // 模块首页 + final moduleHome = RouteCenterAPI.routeMetaBy(AppChargingRouteExport.keyModule); + + // 充电地图首页 + final chargingMapHome = RouteCenterAPI.routeMetaBy(AppChargingRouteExport.keyChargingMapHome); + + // 搜索首页 + final searchHome = RouteCenterAPI.routeMetaBy(AppChargingRouteExport.keySearchHome); + + // CPO收藏页面 + final cpoCollection = RouteCenterAPI.routeMetaBy(AppChargingRouteExport.keyChargingCpoCollection); + + // 充电站详情页面 + final stationDetailPage = RouteCenterAPI.routeMetaBy(AppChargingRouteExport.keyStationDetailPage); + + // 电价页面 + final electricPricePage = RouteCenterAPI.routeMetaBy(AppChargingRouteExport.keyStationElectricPricePage); + + return [ + ChildRoute(moduleHome.path, child: (_, args) => moduleHome.provider(args).as()), + ChildRoute(chargingMapHome.path, child: (_, args) => chargingMapHome.provider(args).as()), + ChildRoute(searchHome.path, child: (_, args) => searchHome.provider(args).as()), + ChildRoute(cpoCollection.path, child: (_, args) => cpoCollection.provider(args).as()), + ChildRoute(stationDetailPage.path, child: (_, args) => stationDetailPage.provider(args).as()), + ChildRoute(electricPricePage.path, child: (_, args) => electricPricePage.provider(args).as()), + // 更多路由配置... + ]; + } +} +``` + +### 3. 路由导出管理 + +**文件**: `src/route_export.dart` + +```dart +import 'dart:convert'; + +import 'package:amap_flutter_base/amap_flutter_base.dart'; +import 'package:basic_logger/basic_logger.dart'; +import 'package:basic_modular/modular.dart'; +import 'package:clr_charging/clr_charging.dart'; +import 'package:clr_geo/clr_geo.dart'; + +import 'app_charging_module.dart'; +import 'pages/public_charging/charging_map_home_page/charging_map_home_page.dart'; +import 'pages/public_charging/charging_station_detail_page/charging_station_detail_page.dart'; +import 'pages/public_charging/charging_query_order_list_page/charging_query_order_list_page.dart'; +import 'pages/public_charging/charging_smart_pile_finding_page/charging_smart_pile_finding_page.dart'; +// ... 更多页面导入 + +/// app_charging的路由管理 +class AppChargingRouteExport implements RouteExporter { + // 路由键常量定义 + static const String keyModule = 'charging'; + static const String keyChargingMapHome = 'charging.map_home'; + static const String keySearchHome = 'charging.search_home'; + static const String keyChargingCpoCollection = 'charging.cpo_collection'; + static const String keyStationDetailPage = 'charging.station_detail'; + static const String keyStationElectricPricePage = 'charging.electric_price'; + static const String keyQueryOrderListPage = 'charging.order_list'; + static const String keySmartPileFinding = 'charging.smart_pile_finding'; + static const String keyChargingReport = 'charging.report'; + static const String keyPowerMonitor = 'charging.power_monitor'; + // ... 更多路由键定义 + + @override + List exportRoutes() { + // 模块根路由 + final r0 = RouteMeta(keyModule, '/charging', (args) => AppChargingModule(), null); + + // 充电地图首页 + final r1 = RouteMeta( + keyChargingMapHome, + '/map_home', + (args) => ChargingMapHomePage(args.data['vin'] as String?), + r0, + ); + + // 充电站详情页面 + final r2 = RouteMeta( + keyStationDetailPage, + '/station_detail', + (args) => ChargingStationDetailPage( + stationID: args.data['stationID'] as String, + chargingVin: args.data['chargingVin'] as String?, + ), + r0, + ); + + // 智能寻桩页面 + final r3 = RouteMeta( + keySmartPileFinding, + '/smart_pile_finding', + (args) => ChargingSmartPileFindingPage( + vin: args.data['vin'] as String, + ), + r0, + ); + + // 订单列表页面 + final r4 = RouteMeta( + keyQueryOrderListPage, + '/order_list', + (args) => ChargingQueryOrderListPage( + vin: args.data['vin'] as String, + ), + r0, + ); + + return [r0, r1, r2, r3, r4]; + } +} +``` + +## 核心功能模块 + +### 1. 充电地图首页 + +**文件**: `pages/public_charging/charging_map_home_page/charging_map_home_page.dart` + +```dart +import 'package:flutter/material.dart'; +import 'package:amap_flutter_map/amap_flutter_map.dart'; +import 'package:basic_modular/modular.dart'; + +/// 充电地图首页 +class ChargingMapHomePage extends StatefulWidget { + const ChargingMapHomePage(this.vin, {Key? key}) : super(key: key); + + final String? vin; + + @override + State createState() => _ChargingMapHomePageState(); +} + +class _ChargingMapHomePageState extends State { + AMapController? _mapController; + List _chargingStations = []; + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar( + title: Text('充电地图'), + actions: [ + IconButton( + icon: Icon(Icons.search), + onPressed: _openSearch, + ), + IconButton( + icon: Icon(Icons.filter_list), + onPressed: _openFilter, + ), + ], + ), + body: Stack( + children: [ + // 地图组件 + AMapWidget( + onMapCreated: _onMapCreated, + markers: Set.from(_buildMarkers()), + ), + + // 功能按钮区域 + Positioned( + bottom: 100, + right: 16, + child: Column( + children: [ + FloatingActionButton( + heroTag: "locate", + onPressed: _locateUser, + child: Icon(Icons.my_location), + ), + SizedBox(height: 10), + FloatingActionButton( + heroTag: "smart_find", + onPressed: _smartPileFinding, + child: Icon(Icons.electric_bolt), + ), + ], + ), + ), + + // 底部信息卡片 + _buildBottomSheet(), + ], + ), + ); + } + + void _onMapCreated(AMapController controller) { + _mapController = controller; + _loadChargingStations(); + } + + List _buildMarkers() { + return _chargingStations.map((station) { + return Marker( + markerId: MarkerId(station.id), + position: LatLng(station.latitude, station.longitude), + infoWindow: InfoWindow(title: station.name), + onTap: () => _showStationDetail(station), + ); + }).toList(); + } + + void _loadChargingStations() { + // 加载充电站数据 + } + + void _openSearch() { + Modular.to.pushNamed('/charging/search_home'); + } + + void _openFilter() { + Modular.to.pushNamed('/charging/filter'); + } + + void _locateUser() { + // 定位到用户位置 + } + + void _smartPileFinding() { + if (widget.vin != null) { + Modular.to.pushNamed('/charging/smart_pile_finding', arguments: { + 'vin': widget.vin, + }); + } + } + + void _showStationDetail(ChargingStation station) { + Modular.to.pushNamed('/charging/station_detail', arguments: { + 'stationID': station.id, + 'chargingVin': widget.vin, + }); + } + + Widget _buildBottomSheet() { + return Positioned( + bottom: 0, + left: 0, + right: 0, + child: Container( + height: 80, + decoration: BoxDecoration( + color: Colors.white, + borderRadius: BorderRadius.vertical(top: Radius.circular(16)), + boxShadow: [ + BoxShadow( + color: Colors.black.withOpacity(0.1), + blurRadius: 8, + offset: Offset(0, -2), + ), + ], + ), + child: Row( + mainAxisAlignment: MainAxisAlignment.spaceEvenly, + children: [ + _buildBottomAction(Icons.list, '订单', _openOrderList), + _buildBottomAction(Icons.assessment, '报告', _openReport), + _buildBottomAction(Icons.settings, '设置', _openSettings), + ], + ), + ), + ); + } + + Widget _buildBottomAction(IconData icon, String label, VoidCallback onTap) { + return InkWell( + onTap: onTap, + child: Column( + mainAxisAlignment: MainAxisAlignment.center, + children: [ + Icon(icon, color: Colors.blue), + SizedBox(height: 4), + Text(label, style: TextStyle(fontSize: 12)), + ], + ), + ); + } + + void _openOrderList() { + if (widget.vin != null) { + Modular.to.pushNamed('/charging/order_list', arguments: { + 'vin': widget.vin, + }); + } + } + + void _openReport() { + if (widget.vin != null) { + Modular.to.pushNamed('/charging/report', arguments: { + 'vin': widget.vin, + }); + } + } + + void _openSettings() { + Modular.to.pushNamed('/charging/settings'); + } +} + +// 充电站数据模型 +class ChargingStation { + final String id; + final String name; + final double latitude; + final double longitude; + final int totalPiles; + final int availablePiles; + + ChargingStation({ + required this.id, + required this.name, + required this.latitude, + required this.longitude, + required this.totalPiles, + required this.availablePiles, + }); +} +``` + +### 2. 充电站详情页面 + +```dart +/// 充电站详情页面 +class ChargingStationDetailPage extends StatefulWidget { + const ChargingStationDetailPage({ + Key? key, + required this.stationID, + this.chargingVin, + }) : super(key: key); + + final String stationID; + final String? chargingVin; + + @override + State createState() => _ChargingStationDetailPageState(); +} + +class _ChargingStationDetailPageState extends State { + ChargingStationDetail? _stationDetail; + bool _isLoading = true; + + @override + void initState() { + super.initState(); + _loadStationDetail(); + } + + @override + Widget build(BuildContext context) { + if (_isLoading) { + return Scaffold( + appBar: AppBar(title: Text('充电站详情')), + body: Center(child: CircularProgressIndicator()), + ); + } + + if (_stationDetail == null) { + return Scaffold( + appBar: AppBar(title: Text('充电站详情')), + body: Center(child: Text('加载失败')), + ); + } + + return Scaffold( + appBar: AppBar( + title: Text(_stationDetail!.name), + actions: [ + IconButton( + icon: Icon(Icons.share), + onPressed: _shareStation, + ), + ], + ), + body: SingleChildScrollView( + child: Column( + children: [ + // 充电站基本信息 + _buildStationInfo(), + + // 充电桩列表 + _buildChargingPilesList(), + + // 服务设施 + _buildFacilities(), + + // 电价信息 + _buildPriceInfo(), + + // 评价与评论 + _buildRatingsSection(), + ], + ), + ), + bottomNavigationBar: Container( + padding: EdgeInsets.all(16), + child: Row( + children: [ + Expanded( + child: ElevatedButton( + onPressed: _navigateToStation, + child: Text('导航'), + ), + ), + SizedBox(width: 16), + Expanded( + child: ElevatedButton( + onPressed: _bookChargingPile, + style: ElevatedButton.styleFrom( + backgroundColor: Colors.green, + ), + child: Text('预约充电'), + ), + ), + ], + ), + ), + ); + } + + Widget _buildStationInfo() { + return Container( + padding: EdgeInsets.all(16), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text(_stationDetail!.name, style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold)), + SizedBox(height: 8), + Text(_stationDetail!.address, style: TextStyle(color: Colors.grey[600])), + SizedBox(height: 16), + Row( + children: [ + _buildInfoChip('总桩数', '${_stationDetail!.totalPiles}'), + SizedBox(width: 16), + _buildInfoChip('可用桩数', '${_stationDetail!.availablePiles}'), + ], + ), + ], + ), + ); + } + + Widget _buildInfoChip(String label, String value) { + return Container( + padding: EdgeInsets.symmetric(horizontal: 12, vertical: 6), + decoration: BoxDecoration( + color: Colors.blue.withOpacity(0.1), + borderRadius: BorderRadius.circular(16), + ), + child: Text('$label: $value', style: TextStyle(color: Colors.blue)), + ); + } + + void _loadStationDetail() { + // 加载充电站详情数据 + Future.delayed(Duration(seconds: 1), () { + setState(() { + _stationDetail = ChargingStationDetail( + id: widget.stationID, + name: '示例充电站', + address: '示例地址', + totalPiles: 10, + availablePiles: 6, + ); + _isLoading = false; + }); + }); + } + + void _navigateToStation() { + Modular.to.pushNamed('/charging/station_guide', arguments: { + 'stationID': widget.stationID, + }); + } + + void _bookChargingPile() { + Modular.to.pushNamed('/charging/reservation', arguments: { + 'stationID': widget.stationID, + 'vin': widget.chargingVin, + }); + } +} + +// 充电站详情数据模型 +class ChargingStationDetail { + final String id; + final String name; + final String address; + final int totalPiles; + final int availablePiles; + + ChargingStationDetail({ + required this.id, + required this.name, + required this.address, + required this.totalPiles, + required this.availablePiles, + }); +} +``` + +### 3. 智能寻桩页面 + +```dart +/// 智能寻桩页面 +class ChargingSmartPileFindingPage extends StatefulWidget { + const ChargingSmartPileFindingPage({ + Key? key, + required this.vin, + }) : super(key: key); + + final String vin; + + @override + State createState() => _ChargingSmartPileFindingPageState(); +} + +class _ChargingSmartPileFindingPageState extends State { + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('智能寻桩')), + body: Column( + children: [ + // 车辆信息卡片 + _buildVehicleInfoCard(), + + // 推荐充电站列表 + Expanded( + child: ListView.builder( + itemCount: _recommendedStations.length, + itemBuilder: (context, index) { + final station = _recommendedStations[index]; + return _buildStationRecommendCard(station); + }, + ), + ), + ], + ), + ); + } + + Widget _buildVehicleInfoCard() { + return Container( + margin: EdgeInsets.all(16), + padding: EdgeInsets.all(16), + decoration: BoxDecoration( + color: Colors.white, + borderRadius: BorderRadius.circular(12), + boxShadow: [BoxShadow(color: Colors.black.withOpacity(0.1), blurRadius: 4)], + ), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text('当前车辆', style: TextStyle(fontSize: 16, fontWeight: FontWeight.bold)), + SizedBox(height: 8), + Text('VIN: ${widget.vin}'), + Text('当前电量: 30%'), + Text('续航里程: 120km'), + ], + ), + ); + } + + Widget _buildStationRecommendCard(RecommendedStation station) { + return Container( + margin: EdgeInsets.symmetric(horizontal: 16, vertical: 8), + child: Card( + child: ListTile( + title: Text(station.name), + subtitle: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text('距离: ${station.distance}km'), + Text('可用桩数: ${station.availablePiles}'), + Text('预计费用: ¥${station.estimatedCost}'), + ], + ), + trailing: ElevatedButton( + onPressed: () => _selectStation(station), + child: Text('选择'), + ), + ), + ), + ); + } + + void _selectStation(RecommendedStation station) { + Modular.to.pushNamed('/charging/station_detail', arguments: { + 'stationID': station.id, + 'chargingVin': widget.vin, + }); + } +} + +// 推荐充电站数据模型 +class RecommendedStation { + final String id; + final String name; + final double distance; + final int availablePiles; + final double estimatedCost; + + RecommendedStation({ + required this.id, + required this.name, + required this.distance, + required this.availablePiles, + required this.estimatedCost, + }); +} +``` + +## 状态管理 (BLoC) + +### 充电地图状态管理 +```dart +// 充电地图状态管理 +class ChargingMapHomeBloc extends Bloc { + final ChargingService _chargingService; + + ChargingMapHomeBloc(this._chargingService) : super(ChargingMapHomeInitial()) { + on(_onLoadChargingStations); + on(_onFilterStations); + on(_onSearchStations); + } + + Future _onLoadChargingStations( + LoadChargingStationsEvent event, + Emitter emit, + ) async { + emit(ChargingMapHomeLoading()); + + try { + final stations = await _chargingService.getNearbyStations( + latitude: event.latitude, + longitude: event.longitude, + radius: event.radius, + ); + + emit(ChargingMapHomeLoaded(stations)); + } catch (e) { + emit(ChargingMapHomeError(e.toString())); + } + } + + Future _onFilterStations( + FilterStationsEvent event, + Emitter emit, + ) async { + if (state is ChargingMapHomeLoaded) { + final currentState = state as ChargingMapHomeLoaded; + final filteredStations = _applyFilter(currentState.stations, event.filter); + emit(ChargingMapHomeLoaded(filteredStations)); + } + } + + List _applyFilter(List stations, StationFilter filter) { + return stations.where((station) { + if (filter.onlyAvailable && station.availablePiles == 0) return false; + if (filter.maxDistance != null && station.distance > filter.maxDistance!) return false; + return true; + }).toList(); + } +} + +// 事件定义 +abstract class ChargingMapHomeEvent {} + +class LoadChargingStationsEvent extends ChargingMapHomeEvent { + final double latitude; + final double longitude; + final double radius; + + LoadChargingStationsEvent(this.latitude, this.longitude, this.radius); +} + +class FilterStationsEvent extends ChargingMapHomeEvent { + final StationFilter filter; + FilterStationsEvent(this.filter); +} + +// 状态定义 +abstract class ChargingMapHomeState {} + +class ChargingMapHomeInitial extends ChargingMapHomeState {} + +class ChargingMapHomeLoading extends ChargingMapHomeState {} + +class ChargingMapHomeLoaded extends ChargingMapHomeState { + final List stations; + ChargingMapHomeLoaded(this.stations); +} + +class ChargingMapHomeError extends ChargingMapHomeState { + final String message; + ChargingMapHomeError(this.message); +} + +// 过滤器模型 +class StationFilter { + final bool onlyAvailable; + final double? maxDistance; + final List? supportedConnectors; + + StationFilter({ + this.onlyAvailable = false, + this.maxDistance, + this.supportedConnectors, + }); +} +``` + +## 依赖管理 + +### 核心依赖 +- **clr_charging**: 充电服务SDK +- **car_services**: 车辆服务 +- **car_vehicle**: 车辆管理 +- **amap_flutter_map**: 高德地图 + +### 框架依赖 +- **basic_modular**: 模块化框架 +- **basic_modular_route**: 路由管理 +- **basic_logger**: 日志服务 +- **ui_basic**: 基础UI组件 + +### 账户与支付 +- **clr_account**: 账户管理 +- **clr_geo**: 地理位置服务 + +## 最佳实践 + +### 1. 代码组织 +- 按业务功能模块化组织 +- 统一的路由管理和页面导航 +- 清晰的状态管理模式 + +### 2. 用户体验 +- 地图加载优化和缓存策略 +- 实时充电桩状态更新 +- 智能推荐算法 + +### 3. 性能优化 +- 地图资源合理加载释放 +- 充电站数据分页加载 +- 网络请求优化和重试机制 diff --git a/app_car/app_composer.md b/app_car/app_composer.md new file mode 100644 index 0000000..09f9750 --- /dev/null +++ b/app_car/app_composer.md @@ -0,0 +1,337 @@ +# App Composer 车辆编排模块 + +## 模块概述 + +`app_composer` 是 OneApp 车联网生态中的车辆编排模块，负责车辆功能的组合编排、自定义场景设置、智能控制流程等功能。该模块为用户提供个性化的车辆控制体验，通过可视化的方式让用户自定义车辆操作流程。 + +### 基本信息 +- **模块名称**: app_composer +- **版本**: 0.2.9+21 +- **描述**: 车辆功能编排应用模块 +- **Flutter 版本**: >=2.5.0 +- **Dart 版本**: >=2.17.0 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **场景编排** + - 自定义车辆控制场景 + - 多步骤操作流程设计 + - 条件触发逻辑设置 + - 场景模板管理 + +2. **智能控制** + - 基于时间的自动控制 + - 基于位置的触发控制 + - 基于状态的条件控制 + - 多设备联动控制 + +3. **可视化编辑** + - 拖拽式流程设计 + - 可视化逻辑编排 + - 实时预览效果 + - 错误检查提示 + +4. **场景执行** + - 场景一键执行 + - 执行状态监控 + - 执行结果反馈 + - 异常处理机制 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── app_composer.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── config/ # 配置管理 +│ ├── constants/ # 常量定义 +│ ├── global/ # 全局状态管理 +│ ├── pages/ # 页面组件 +│ ├── router/ # 路由配置 +│ ├── util/ # 工具类 +│ └── widgets/ # 自定义组件 +├── const/ # 模块常量 +├── generated/ # 代码生成文件 +└── l10n/ # 国际化文件 +``` + +### 依赖关系 + +#### 核心依赖 +- `basic_modular: ^0.2.1` - 模块化框架 +- `basic_modular_route: ^0.2.0` - 路由管理 +- `basic_intl: ^0.2.0` - 国际化支持 +- `basic_logger: ^0.2.0` - 日志系统 + +#### 业务依赖 +- `ui_basic: ^0.2.43+5` - 基础UI组件 +- `clr_composer: ^0.2.6+7` - 编排服务SDK +- `clr_account: ^0.2.8` - 账户服务SDK + +#### 第三方依赖 +- `json_annotation: ^4.6.0` - JSON序列化 +- `dartz: ^0.10.1` - 函数式编程 +- `uuid: ^3.0.7` - UUID生成 +- `crypto: ^3.0.3` - 加密功能 +- `path_provider: ^2.0.15` - 文件路径 +- `bottom_sheet: ^4.0.0` - 底部弹窗 + +## 核心模块分析 + +### 1. 模块入口 (`app_composer.dart`) + +**功能职责**: +- 模块对外接口统一导出 +- 核心组件和服务暴露 + +### 2. 配置管理 (`src/config/`) + +**功能职责**: +- 编排引擎配置 +- 场景模板配置 +- 执行策略配置 +- 性能参数配置 + +**主要配置**: +- `ComposerConfig` - 编排引擎配置 +- `SceneConfig` - 场景配置 +- `ExecutionConfig` - 执行配置 +- `TemplateConfig` - 模板配置 + +### 3. 常量定义 (`src/constants/`) + +**功能职责**: +- 编排常量定义 +- 操作类型枚举 +- 状态码定义 +- 错误消息常量 + +**主要常量**: +- 操作类型常量 +- 触发条件常量 +- 执行状态常量 +- UI配置常量 + +### 4. 全局状态管理 (`src/global/`) + +**功能职责**: +- 编排状态全局管理 +- 场景数据缓存 +- 执行状态监控 +- 数据同步协调 + +**主要状态**: +- `ComposerState` - 编排器状态 +- `SceneState` - 场景状态 +- `ExecutionState` - 执行状态 +- `TemplateState` - 模板状态 + +### 5. 页面组件 (`src/pages/`) + +**功能职责**: +- 用户界面展示 +- 用户交互处理 +- 编排操作界面 + +**主要页面**: +- `ComposerHomePage` - 编排主页 +- `SceneEditorPage` - 场景编辑页 +- `SceneListPage` - 场景列表页 +- `ExecutionMonitorPage` - 执行监控页 +- `TemplateGalleryPage` - 模板库页面 + +### 6. 路由配置 (`src/router/`) + +**功能职责**: +- 模块内部路由定义 +- 页面导航管理 +- 路由参数传递 +- 导航守卫设置 + +### 7. 工具类 (`src/util/`) + +**功能职责**: +- 编排逻辑工具 +- 数据处理辅助 +- 文件操作工具 +- 加密解密工具 + +**主要工具**: +- `SceneBuilder` - 场景构建器 +- `ExecutionEngine` - 执行引擎 +- `DataConverter` - 数据转换器 +- `FileManager` - 文件管理器 + +### 8. 自定义组件 (`src/widgets/`) + +**功能职责**: +- 编排专用UI组件 +- 可视化编辑组件 +- 交互控制组件 +- 状态展示组件 + +**主要组件**: +- `FlowChart` - 流程图组件 +- `NodeEditor` - 节点编辑器 +- `ConditionBuilder` - 条件构建器 +- `ExecutionProgress` - 执行进度组件 + +## 业务流程 + +### 场景编排流程 +```mermaid +graph TD + A[创建场景] --> B[选择模板] + B --> C[添加操作节点] + C --> D[设置节点参数] + D --> E[配置触发条件] + E --> F[连接节点关系] + F --> G[预览场景流程] + G --> H{验证是否通过} + H -->|是| I[保存场景] + H -->|否| J[修正错误] + J --> F + I --> K[场景测试] + K --> L{测试是否通过} + L -->|是| M[发布场景] + L -->|否| N[调试修改] + N --> G +``` + +### 场景执行流程 +```mermaid +graph TD + A[触发场景] --> B[验证执行条件] + B --> C{条件是否满足} + C -->|是| D[开始执行] + C -->|否| E[等待或跳过] + D --> F[执行当前节点] + F --> G[检查执行结果] + G --> H{是否成功} + H -->|是| I[执行下一节点] + H -->|否| J[执行错误处理] + J --> K{是否继续} + K -->|是| I + K -->|否| L[终止执行] + I --> M{是否还有节点} + M -->|是| F + M -->|否| N[执行完成] + E --> O[记录日志] + L --> O + N --> O +``` + +## 编排引擎设计 + +### 节点类型 +1. **控制节点** + - 车辆解锁/上锁 + - 车窗控制 + - 空调控制 + - 灯光控制 + +2. **条件节点** + - 时间条件 + - 位置条件 + - 状态条件 + - 传感器条件 + +3. **逻辑节点** + - 分支判断 + - 循环控制 + - 延时等待 + - 并行执行 + +4. **通知节点** + - 推送通知 + - 短信通知 + - 邮件通知 + - 语音提醒 + +### 执行策略 +- **串行执行**: 按顺序逐个执行 +- **并行执行**: 同时执行多个操作 +- **条件执行**: 基于条件判断执行 +- **循环执行**: 重复执行指定次数 + +## 安全特性 + +### 权限控制 +- 操作权限验证 +- 用户身份认证 +- 设备授权检查 +- 场景访问控制 + +### 数据安全 +- 场景数据加密 +- 执行日志保护 +- 敏感信息脱敏 +- 数据传输安全 + +## 性能优化 + +### 执行优化 +- 节点缓存机制 +- 批量操作优化 +- 异步执行策略 +- 资源复用设计 + +### 内存管理 +- 场景数据懒加载 +- 执行上下文管理 +- 内存泄漏防护 +- 大场景分片处理 + +## 扩展性设计 + +### 插件化架构 +- 自定义节点插件 +- 第三方服务集成 +- 扩展操作类型 +- 自定义触发器 + +### 模板系统 +- 预设场景模板 +- 用户自定义模板 +- 模板分享机制 +- 模板版本管理 + +## 测试策略 + +### 单元测试 +- 节点逻辑测试 +- 执行引擎测试 +- 数据模型测试 +- 工具类测试 + +### 集成测试 +- 场景执行测试 +- 服务集成测试 +- 数据流测试 +- 权限流程测试 + +### 场景测试 +- 复杂场景测试 +- 异常场景测试 +- 性能压力测试 +- 用户体验测试 + +## 部署和维护 + +### 配置管理 +- 环境配置分离 +- 功能开关控制 +- 性能参数调优 +- 错误恢复策略 + +### 监控指标 +- 场景执行成功率 +- 执行响应时间 +- 用户使用频率 +- 异常错误统计 + +## 总结 + +`app_composer` 模块作为 OneApp 的智能编排中心，为用户提供了强大的车辆功能定制能力。通过可视化的编排界面、灵活的执行引擎和丰富的节点类型，用户可以创建个性化的车辆控制场景，提升用车体验的智能化水平。模块具有良好的扩展性和可维护性，能够适应不断变化的智能车联网需求。 diff --git a/app_car/app_maintenance.md b/app_car/app_maintenance.md new file mode 100644 index 0000000..258fc7d --- /dev/null +++ b/app_car/app_maintenance.md @@ -0,0 +1,423 @@ +# App Maintenance - 维护保养模块文档 + +## 模块概述 + +`app_maintenance` 是 OneApp 车辆模块群中的维护保养核心模块，提供车辆保养预约管理、经销商选择、时间预约、历史记录查询等功能。该模块集成了地图服务、经销商查询、预约管理等，为用户提供完整的车辆维护保养预约体验。 + +### 基本信息 +- **模块名称**: app_maintenance +- **路径**: oneapp_app_car/app_maintenance/ +- **依赖**: clr_maintenance, basic_modular, basic_modular_route +- **主要功能**: 维保预约、经销商选择、时间管理、历史记录 + +## 目录结构 + +``` +app_maintenance/ +├── lib/ +│ ├── app_maintenance.dart # 主导出文件 +│ └── src/ # 源代码目录 +│ ├── pages/ # 维护保养页面 +│ │ ├── maintenance_home_page/ # 维保信息首页 +│ │ ├── appointment_create_page/ # 创建预约页面 +│ │ ├── appointment_detail_page/ # 预约详情页面 +│ │ ├── appointment_history_page/ # 预约历史页面 +│ │ ├── dealer_select_page/ # 经销商选择页面 +│ │ ├── time_select_page/ # 时间选择页面 +│ │ └── carPlate_binding_page/ # 车牌绑定页面 +│ ├── blocs/ # 状态管理（BLoC） +│ ├── model/ # 数据模型 +│ ├── constants/ # 常量定义 +│ ├── route_dp.dart # 路由配置 +│ └── route_export.dart # 路由导出 +├── assets/ # 静态资源 +├── uml.puml/svg # UML 设计图 +├── pubspec.yaml # 依赖配置 +└── README.md # 项目说明 +``` + +## 核心功能模块 + +### 1. 主控制模块 + +```dart +library app_maintenance; + +import 'package:basic_logger/basic_logger.dart'; +import 'package:basic_modular/modular.dart'; +import 'package:basic_modular_route/basic_modular_route.dart'; + +import 'src/route_export.dart'; + +export 'src/route_dp.dart'; +export 'src/route_export.dart'; + +/// 维护保养控制模块 +class MaintenanceControlModule extends Module with RouteObjProvider { + @override + List get routes { + // 维保模块主页 + final RouteMeta maintenance = + RouteCenterAPI.routeMetaBy(MaintenanceRouteExport.keyModule); + // 维保信息首页Route + final RouteMeta maintenanceHome = + RouteCenterAPI.routeMetaBy(MaintenanceRouteExport.keyMaintenanceHome); + // 预约详情页Route + final RouteMeta appointmentDetail = + RouteCenterAPI.routeMetaBy(MaintenanceRouteExport.keyAppointmentDetail); + // 绑定车牌页Route + final RouteMeta bindingPlateNo = + RouteCenterAPI.routeMetaBy(MaintenanceRouteExport.keyBindingPlateNo); + // 创建预约Route + final RouteMeta createAppointment = + RouteCenterAPI.routeMetaBy(MaintenanceRouteExport.keyAppointmentCreate); + // 经销商选择页Route + final RouteMeta selectDealerList = + RouteCenterAPI.routeMetaBy(MaintenanceRouteExport.keySelectDealerList); + // 选择时间页Route + final RouteMeta selectTime = + RouteCenterAPI.routeMetaBy(MaintenanceRouteExport.keySelectTime); + // 预约历史页Route + final RouteMeta appointmentHistory = RouteCenterAPI.routeMetaBy( + MaintenanceRouteExport.keyAppointmentHistory, + ); + // 选择时间_更多页Route + final RouteMeta selectTimeMore = + RouteCenterAPI.routeMetaBy(MaintenanceRouteExport.keySelectTimeMore); + // 搜索经销商 + final RouteMeta searchDealerList = + RouteCenterAPI.routeMetaBy(MaintenanceRouteExport.keySearchDealerList); + + return [ + // 维保模块主页 + ChildRoute( + maintenance.path, + child: (_, args) => maintenance.provider(args).as(), + ), + // 维保信息首页 + ChildRoute( + maintenanceHome.path, + child: (_, args) => maintenanceHome.provider(args).as(), + ), + // 维保详情页 + ChildRoute( + appointmentDetail.path, + child: (_, args) => appointmentDetail.provider(args).as(), + ), + // 车牌设置页 + ChildRoute( + bindingPlateNo.path, + child: (_, args) => bindingPlateNo.provider(args).as(), + ), + // 创建预约页 + ChildRoute( + createAppointment.path, + child: (_, args) => createAppointment.provider(args).as(), + ), + // 选择经销商页 + ChildRoute( + selectDealerList.path, + child: (_, args) => selectDealerList.provider(args).as(), + ), + // 选择时间页 + ChildRoute( + selectTime.path, + child: (_, args) => selectTime.provider(args).as(), + ), + // 预约历史页 + ChildRoute( + appointmentHistory.path, + child: (_, args) => appointmentHistory.provider(args).as(), + ), + // 选择时间_更多页 + ChildRoute( + selectTimeMore.path, + child: (_, args) => selectTimeMore.provider(args).as(), + ), + // 搜索经销商 + ChildRoute( + searchDealerList.path, + child: (_, args) => searchDealerList.provider(args).as(), + ), + ]; + } + + @override + void dispose() { + Logger.i('AppMaintenance dispose'); + super.dispose(); + } +} +``` + +### 2. 路由导出配置 + +实际的维保模块路由配置： + +```dart +/// 维保页面路由 +class MaintenanceRouteExport implements RouteExporter { + /// 模块主页 + static const String keyModule = 'maintenance'; + /// 维保首页 + static const String keyMaintenanceHome = 'maintenance.home'; + /// 详情页 + static const String keyAppointmentDetail = 'maintenance.appointmentDetail'; + /// 绑定/修改车牌页 + static const String keyBindingPlateNo = 'maintenance.bindingPlateNo'; + /// 创建维修保养页 + static const String keyAppointmentCreate = 'maintenance.appointmentCreate'; + /// 选择经销商列表页 + static const String keySelectDealerList = 'maintenance.selectDealerList'; + /// 搜索经销商列表页 + static const String keySearchDealerList = 'maintenance.keySearchDealerList'; + /// 选择时间 + static const String keySelectTime = 'maintenance.selectTime'; + /// 选择时间更多 + static const String keySelectTimeMore = 'maintenance.selectTimeMore'; + /// 预约历史 + static const String keyAppointmentHistory = 'maintenance.appointmentHistory'; + + @override + List exportRoutes() { + // 各种路由配置...包括维保首页、预约创建、经销商选择等 + return [r1, r2, r3, r4, r5, r6, r7, r8, r9, r10]; + } +} +``` + +### 3. 维保信息首页 + +```dart +/// 维保信息页 +class MaintenanceHomePage extends StatelessWidget with RouteObjProvider { + /// 初始化 + /// [vin] 页面相关车辆vin码 + MaintenanceHomePage({ + required this.vin, + Key? key, + }) : super(key: key); + + /// vin null时请求会取默认车辆vin码 + String? vin; + + @override + Widget build(BuildContext context) => BlocProvider( + create: (context) => + MaintenanceHomeBloc()..add(const MaintenanceHomeEvent.init()), + child: BlocConsumer( + builder: _buildLayout, + listener: (context, state) {}, + ), + ); + + /// 标题栏 + CommonTitleBar titleBar(BuildContext context, MaintenanceHomeState state) => + CommonTitleBar( + titleText: homePage_titleWidget_title, + backgroundColor: OneColors.bgc, + actions: [ + Container( + color: OneColors.bgc, + width: (16 * 2 + 20).w, + child: Center( + child: OneIcons.iconHistory(20.r), + ), + ).withOnTap(() async { + Logger.i('点击预约历史'); + // 获取车牌 + String? plateNo; + if (state.maintenanceDetailLast == null && + state.maintenanceInFoModel == null) { + // 详情与最后一个预约记录全部为null + plateNo = null; + } else { + // 预约详情车牌权重比最后一次高，因为用户可能会更新 + // 最后一个预约有车牌 + if (state.maintenanceDetailLast != null) { + plateNo = state.maintenanceDetailLast?.plateNo; + } + // 预约详情有车牌 + if (state.maintenanceInFoModel != null) { + plateNo = null; + plateNo = state.maintenanceInFoModel?.vehicleHealth.plateNo; + } + } + + // 前往历史列表页面 + final res = await Modular.to.pushNamed( + RouteCenterAPI.getRoutePathBy( + const AppointmentHistoryPageRouteKey(), + ), + arguments: { + // 当前是否存在预约 + 'isExistAppointmen': state.isAppointment, + // vin + 'vin': vin ?? + Modular.get().getDefaultVehicleVin() ?? + '', + // 车牌 + 'plateNo': plateNo, + }, + ); + // 预约历史页面返回刷新数据 + if (res is bool && res) { + Logger.i('预约历史页面返回刷新数据'); + context + .read() + .add(const MaintenanceHomeEvent.init()); + } + }), + ], + ); +} +``` + +### 4. 主要功能页面 + +#### 4.1 预约创建页面 +支持多种预约创建场景： +- **安装预约** (`isInstallAppointmen`) - 从安装服务跳转创建预约 +- **创建预约** (`isCreateAppointmen`) - 普通维保预约创建 +- **再次预约** (`isAgainAppointmen`) - 基于历史记录再次预约 +- **修改预约** (`isAmendAppointmen`) - 修改现有预约信息 + +```dart +AppointmentCreatePage( + vin: args.data['vin'] as String?, + isCreateAppointmen: true, + plateNo: args.data['plateNo'] as String?, + detailModel: args.data['model'] as MaintenanceDetailModel?, +); +``` + +#### 4.2 经销商选择页面 +- **经销商列表页** (`DealerSelectListPage`) - 显示附近经销商列表 +- **经销商搜索页** (`DealerSearchListPage`) - 支持按地理位置搜索经销商 + +#### 4.3 时间选择页面 +- **时间选择页** (`TimeSelectPage`) - 选择预约时间段 +- **时间选择更多页** (`TimeSelectMorePage`) - 更多可选时间段展示 + +#### 4.4 预约管理页面 +- **预约详情页** (`AppointmentDetailPage`) - 查看预约详细信息 +- **预约历史页** (`AppointmentHistoryPage`) - 历史预约记录管理 +- **车牌绑定页** (`LicensePlatePage`) - 车牌号码设置和修改 + +### 5. 核心功能特性 + +#### 5.1 预约流程管理 +- 支持根据VIN码和车牌号创建预约 +- 提供预约修改、再次预约等功能 +- 集成经销商信息和时间选择功能 +- 支持预约历史记录查询 + +#### 5.2 经销商服务 +- 基于地理位置的经销商推荐 +- 经销商详细信息展示（联系方式、地址等） +- 支持经销商搜索和筛选功能 + +#### 5.3 时间预约系统 +- 经销商可用时间段查询 +- 支持多时间段选择 +- 提供更多时间选项扩展功能 + +```dart +// 导航到维保首页 +Modular.to.pushNamed( + RouteCenterAPI.getRoutePathBy(MaintenanceRouteExport.keyMaintenanceHome), + arguments: { + 'vin': vehicleVin, // 车辆VIN码 + }, +); + +// 创建新预约 +Modular.to.pushNamed( + RouteCenterAPI.getRoutePathBy(MaintenanceRouteExport.keyAppointmentCreate), + arguments: { + 'isCreateAppointmen': true, + 'vin': vehicleVin, + 'plateNo': plateNumber, + 'model': previousDetailModel, // 携带上一次预约信息 + }, +); + +// 修改现有预约 +Modular.to.pushNamed( + RouteCenterAPI.getRoutePathBy(MaintenanceRouteExport.keyAppointmentCreate), + arguments: { + 'isAmendAppointmen': true, + 'plateNo': plateNumber, + 'model': currentDetailModel, + }, +); + +// 查看预约详情 +Modular.to.pushNamed( + RouteCenterAPI.getRoutePathBy(MaintenanceRouteExport.keyAppointmentDetail), + arguments: { + 'number': appointmentNumber, + 'vin': vehicleVin, + 'isExistAppointmen': true, + 'model': detailModel, + }, +); + +// 选择经销商 +Modular.to.pushNamed( + RouteCenterAPI.getRoutePathBy(MaintenanceRouteExport.keySelectDealerList), +); + +// 选择预约时间 +Modular.to.pushNamed( + RouteCenterAPI.getRoutePathBy(MaintenanceRouteExport.keySelectTime), + arguments: { + 'dealerCode': selectedDealerCode, + }, +); + +// 查看预约历史 +Modular.to.pushNamed( + RouteCenterAPI.getRoutePathBy(MaintenanceRouteExport.keyAppointmentHistory), + arguments: { + 'tabKey': 'hasAppointment', // 或 'noAppointment' + 'plateNo': plateNumber, + }, +); + +// 安装服务预约（deeplink支持） +// oneapp://dssomobile/launch?routePath=/maintenance/createAppointment&isInstallAppointmen=1&vin=$vin&dealer=$dealer&dealerCode=$dealerCode&dealerPhone=$dealerPhone +``` + +## 依赖关系 + +该模块依赖以下包： +- `clr_maintenance` - 维保业务逻辑核心 +- `basic_modular` - 模块化架构支持 +- `basic_modular_route` - 路由管理 +- `basic_logger` - 日志记录 +- `basic_intl` - 国际化支持 +- `basic_track` - 埋点追踪 +- `clr_account` - 账户管理 +- `ui_basic` - 基础UI组件 +- `app_car` - 车辆相关功能 + +## 总结 + +app_maintenance 模块是 OneApp 维保功能的核心实现，提供了完整的维保预约管理体验： + +### 主要特性 +1. **多场景预约支持** - 支持创建预约、修改预约、再次预约、安装服务预约等多种业务场景 +2. **完整预约流程** - 从经销商选择到时间预约的完整用户体验 +3. **历史记录管理** - 提供预约历史查询和管理功能 +4. **车辆信息管理** - 支持车牌绑定和车辆信息管理 +5. **地理位置集成** - 基于位置的经销商推荐和搜索功能 + +### 技术架构 +- **BLoC状态管理** - 使用BLoC模式管理复杂的预约业务状态 +- **模块化路由** - 采用基于路由中心的模块化架构设计 +- **参数传递机制** - 灵活的路由参数传递支持各种业务场景 +- **业务逻辑分离** - 依赖clr_maintenance提供核心业务逻辑 + +### 业务价值 +该模块通过标准化的维保预约流程，为用户提供便捷的维保服务体验，同时支持经销商管理和时间调度等复杂业务需求。 \ No newline at end of file diff --git a/app_car/app_order.md b/app_car/app_order.md new file mode 100644 index 0000000..0e31247 --- /dev/null +++ b/app_car/app_order.md @@ -0,0 +1,597 @@ +# App Order - 订单管理模块文档 + +## 模块概述 + +`app_order` 是 OneApp 车辆模块群中的订单管理核心模块，提供完整的订单生命周期管理，包括订单详情查看、发票管理、退款处理、订单历史等功能。该模块与支付系统、账户系统深度集成，为用户提供统一的订单管理体验。 + +### 基本信息 +- **模块名称**: app_order +- **路径**: oneapp_app_car/app_order/ +- **依赖**: clr_order, basic_modular, basic_modular_route, ui_basic +- **主要功能**: 订单详情、发票管理、退款处理、订单中心 + +## 目录结构 + +``` +app_order/ +├── lib/ +│ ├── app_order.dart # 主导出文件 +│ └── src/ # 源代码目录 +│ ├── pages/ # 订单页面 +│ │ ├── order_center_page.dart # 订单中心页面 +│ │ ├── orderdetail/ # 订单详情页面 +│ │ ├── orderlist/ # 订单列表页面 +│ │ ├── invoice/ # 发票相关页面 +│ │ │ ├── invoiceChooseManagePage/ # 发票选择管理 +│ │ │ ├── invoiceDetailsPage/ # 发票详情 +│ │ │ ├── invoiceHistoryCenterPage/ # 发票历史 +│ │ │ └── ... # 其他发票功能 +│ │ └── refunddetail/ # 退款详情页面 +│ ├── bloc/ # 状态管理（BLoC） +│ ├── models/ # 数据模型 +│ ├── utils/ # 工具类 +│ ├── constants/ # 常量定义 +│ ├── order_module.dart # 订单模块配置 +│ ├── route_dp.dart # 路由配置 +│ └── route_export.dart # 路由导出 +├── assets/ # 静态资源 +├── uml.puml/png/svg # UML 设计图 +├── pubspec.yaml # 依赖配置 +└── README.md # 项目说明 +``` + +## 核心功能模块 + +### 1. 主导出模块 + +**文件**: `lib/app_order.dart` + +```dart +library app_order; + +// 页面导出 +export 'src/pages/order_center_page.dart'; +export 'src/pages/orderdetail/orderdetail_page.dart'; +export 'src/pages/orderlist/orderlist_page.dart'; +export 'src/pages/invoice/invoiceChooseManagePage/invoiceChooseManage_page.dart'; +export 'src/pages/invoice/invoiceDetailsPage/invoiceDetails_page.dart'; +export 'src/pages/invoice/invoiceHistoryCenterPage/invoiceHistoryCenter_page.dart'; +export 'src/pages/refunddetail/refunddetail_page.dart'; + +// 模块配置导出 +export 'src/order_module.dart'; +export 'src/route_dp.dart'; +export 'src/route_export.dart'; +``` + +### 2. 订单模块配置 + +**文件**: `src/order_module.dart` + +```dart +import 'package:basic_modular/basic_modular.dart'; +import 'package:flutter/material.dart'; +import 'route_dp.dart'; + +/// App Order 模块定义 +class AppOrderModule extends Module { + @override + String get name => "app_order"; + + @override + List get binds => []; + + @override + List get routes => OrderRouteController.routes; +} +``` + +### 3. 路由导出管理 + +**文件**: `src/route_export.dart` + +```dart +import 'package:basic_modular_route/basic_modular_route.dart'; + +class AppOrderRouteExport { + /// 订单中心路径 + static const String orderCenter = "/order-center"; + + /// 订单详情路径 + static const String orderDetail = "/order-detail"; + + /// 订单列表路径 + static const String orderList = "/order-list"; + + /// 发票管理路径 + static const String invoiceManage = "/invoice-manage"; + + /// 发票详情路径 + static const String invoiceDetail = "/invoice-detail"; + + /// 发票历史中心路径 + static const String invoiceHistoryCenter = "/invoice-history-center"; + + /// 退款详情路径 + static const String refundDetail = "/refund-detail"; + + /// 跳转到订单中心 + static Future gotoOrderCenter( + ModularRouteInformation information, + ) { + return information.pushNamed(orderCenter); + } + + /// 跳转到订单详情 + static Future gotoOrderDetail( + ModularRouteInformation information, { + required String orderId, + }) { + return information.pushNamed( + orderDetail, + arguments: {'orderId': orderId}, + ); + } + + /// 跳转到发票管理页面 + static Future gotoInvoiceManage( + ModularRouteInformation information, + ) { + return information.pushNamed(invoiceManage); + } + + /// 跳转到发票详情页面 + static Future gotoInvoiceDetail( + ModularRouteInformation information, { + required String invoiceId, + }) { + return information.pushNamed( + invoiceDetail, + arguments: {'invoiceId': invoiceId}, + ); + } + + /// 跳转到退款详情页面 + static Future gotoRefundDetail( + ModularRouteInformation information, { + required String refundId, + }) { + return information.pushNamed( + refundDetail, + arguments: {'refundId': refundId}, + ); + } +} +``` + +### 4. 订单中心页面 + +**文件**: `src/pages/order_center_page.dart` + +```dart +import 'package:flutter/material.dart'; +import 'package:basic_modular_route/basic_modular_route.dart'; +import 'package:ui_basic/ui_basic.dart'; +import '../bloc/order_center_bloc.dart'; + +class OrderCenterPage extends StatefulWidget { + @override + _OrderCenterPageState createState() => _OrderCenterPageState(); +} + +class _OrderCenterPageState extends State + with TickerProviderStateMixin { + late TabController _tabController; + int _currentIndex = 0; + + final List _tabTitles = [ + '全部订单', + '待付款', + '已付款', + '已完成', + '已取消', + ]; + + @override + void initState() { + super.initState(); + _tabController = TabController( + length: _tabTitles.length, + vsync: this, + ); + + _tabController.addListener(() { + if (!_tabController.indexIsChanging) { + setState(() { + _currentIndex = _tabController.index; + }); + } + }); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar( + title: Text('订单中心'), + backgroundColor: Colors.white, + elevation: 0.5, + bottom: TabBar( + controller: _tabController, + tabs: _tabTitles.map((title) => Tab(text: title)).toList(), + indicatorColor: Theme.of(context).primaryColor, + labelColor: Theme.of(context).primaryColor, + unselectedLabelColor: Colors.grey, + isScrollable: false, + ), + ), + body: TabBarView( + controller: _tabController, + children: _tabTitles.map((title) => _buildOrderList(title)).toList(), + ), + ); + } + + Widget _buildOrderList(String tabTitle) { + return Container( + child: RefreshIndicator( + onRefresh: () async { + // 刷新订单列表 + await _refreshOrderList(tabTitle); + }, + child: ListView.builder( + padding: EdgeInsets.all(16), + itemBuilder: (context, index) => _buildOrderCard(index), + itemCount: 10, // 示例数量 + ), + ), + ); + } + + Widget _buildOrderCard(int index) { + return Card( + margin: EdgeInsets.only(bottom: 12), + child: Padding( + padding: EdgeInsets.all(16), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Row( + mainAxisAlignment: MainAxisAlignment.spaceBetween, + children: [ + Text( + '订单号：20231201${(index + 1000)}', + style: TextStyle( + fontWeight: FontWeight.bold, + fontSize: 16, + ), + ), + Text( + '已付款', + style: TextStyle( + color: Colors.green, + fontWeight: FontWeight.w500, + ), + ), + ], + ), + SizedBox(height: 8), + Text( + '服务内容：车辆充电服务', + style: TextStyle(color: Colors.grey[600]), + ), + SizedBox(height: 4), + Text( + '金额：￥${(index * 50 + 100)}.00', + style: TextStyle( + color: Colors.red, + fontWeight: FontWeight.w500, + fontSize: 16, + ), + ), + SizedBox(height: 8), + Row( + mainAxisAlignment: MainAxisAlignment.spaceBetween, + children: [ + Text( + '下单时间：2023-12-0${index % 9 + 1} 14:30', + style: TextStyle( + color: Colors.grey[500], + fontSize: 12, + ), + ), + Row( + children: [ + TextButton( + onPressed: () => _viewOrderDetail(index), + child: Text('查看详情'), + ), + TextButton( + onPressed: () => _manageInvoice(index), + child: Text('发票管理'), + ), + ], + ), + ], + ), + ], + ), + ), + ); + } + + Future _refreshOrderList(String tabTitle) async { + // 模拟刷新延时 + await Future.delayed(Duration(seconds: 1)); + } + + void _viewOrderDetail(int index) { + ModularRouteInformation.of(context).pushNamed('/order-detail', + arguments: {'orderId': '20231201${(index + 1000)}'}); + } + + void _manageInvoice(int index) { + ModularRouteInformation.of(context).pushNamed('/invoice-manage', + arguments: {'orderId': '20231201${(index + 1000)}'}); + } + + @override + void dispose() { + _tabController.dispose(); + super.dispose(); + } +} +``` + +### 5. 路由配置系统 + +**文件**: `src/route_dp.dart` + +```dart +import 'package:basic_modular/modular.dart'; +import 'route_export.dart'; + +/// 订单中心页面路由key +class OrderCenterRouteKey implements RouteKey { + /// 默认构造器 + const OrderCenterRouteKey(); + + @override + String get routeKey => AppOrderRouteExport.keyOrderCenter; +} + +/// 订单详情页面路由key +class OrderDetailRouteKey implements RouteKey { + /// 默认构造器 + const OrderDetailRouteKey(); + + @override + String get routeKey => AppOrderRouteExport.keyOrderDetail; +} + +/// 订单退款详情页面路由key +class RefundDetailRouteKey implements RouteKey { + /// 默认构造器 + const RefundDetailRouteKey(); + + @override + String get routeKey => AppOrderRouteExport.keyRefundDetail; +} + +/// 发票抬头选择管理页路由key +class InvoiceTitleCMRouteKey implements RouteKey { + /// 默认构造器 + const InvoiceTitleCMRouteKey(); + + @override + String get routeKey => AppOrderRouteExport.keyInvoiceCM; +} + +/// 开具发票抬头提交页/发票抬头详情页 +class InvoiceTitleDetailsRouteKey implements RouteKey { + /// 默认构造器 + const InvoiceTitleDetailsRouteKey(); + + @override + String get routeKey => AppOrderRouteExport.keyInvoiceTitleDetails; +} + +/// 发票历史 +class InvoiceHistoryRouteKey implements RouteKey { + /// 默认构造器 + const InvoiceHistoryRouteKey(); + + @override + String get routeKey => AppOrderRouteExport.keyInvoiceHistory; +} + +/// 发票详情页 +class InvoiceDetailsRouteKey implements RouteKey { + /// 默认构造器 + const InvoiceDetailsRouteKey(); + + @override + String get routeKey => AppOrderRouteExport.keyInvoiceDetails; +} + +/// 可开发票列表页 +class OpenInvoiceOrderChooseRouteKey implements RouteKey { + /// 默认构造器 + const OpenInvoiceOrderChooseRouteKey(); + + @override + String get routeKey => AppOrderRouteExport.keyOpneInvoiceOrderChoose; +} +``` + +## 实际项目集成 + +### 依赖配置 + +**文件**: `pubspec.yaml` + +```yaml +name: app_order +description: OneApp 订单管理模块 + +dependencies: + flutter: + sdk: flutter + + # 基础依赖 + basic_modular: + path: ../../oneapp_basic_utils/base_mvvm + basic_modular_route: + path: ../../oneapp_basic_utils/basic_modular_route + ui_basic: + path: ../../oneapp_basic_uis/ui_basic + + # 订单核心依赖 + clr_order: + path: ../clr_order + + # 其他依赖 + flutter_bloc: ^8.1.3 + equatable: ^2.0.5 + dio: ^5.3.2 + cached_network_image: ^3.3.0 + +dev_dependencies: + flutter_test: + sdk: flutter + flutter_lints: ^2.0.0 + +flutter: + uses-material-design: true + assets: + - assets/images/ + - assets/icons/ +``` + +### 模块集成流程 + +#### 1. 模块注册 + +在主应用中注册订单模块： + +```dart +// main_app 集成代码 +import 'package:app_order/app_order.dart'; + +void setupOrderModule() { + // 注册订单模块 + Modular.bindModule(AppOrderModule()); + + // 配置路由 + Get.routing.add( + AppOrderRouteExport.keyOrderCenter, + page: () => OrderCenterPage(), + binding: OrderCenterBinding(), + ); +} +``` + +#### 2. 功能特性 + +- **多状态订单管理**: 支持待付款、已付款、已完成、已取消等多种状态 +- **发票系统集成**: 完整的发票申请、管理、历史查看功能 +- **退款处理**: 订单退款申请和详情查看 +- **实时状态更新**: TabController 实现的多 Tab 订单分类浏览 +- **响应式设计**: 支持刷新和分页加载的订单列表 +- **模块化架构**: 基于 basic_modular 的标准化模块设计 + +#### 3. 与其他模块的集成 + +```dart +// 与其他车辆服务模块的集成示例 +class OrderIntegrationService { + // 从充电模块创建订单 + Future createChargingOrder(ChargingSession session) async { + await AppOrderRouteExport.gotoOrderCenter( + ModularRouteInformation.current(), + ); + } + + // 从维保模块创建订单 + Future createMaintenanceOrder(MaintenanceAppointment appointment) async { + await AppOrderRouteExport.gotoOrderDetail( + ModularRouteInformation.current(), + orderId: appointment.orderId, + ); + } +} +``` + +## 技术架构与设计模式 + +### 1. 模块化架构 + +app_order 模块采用标准的 OneApp 模块化架构： + +- **模块定义**: `AppOrderModule` 继承自 `basic_modular.Module` +- **路由管理**: 通过 `AppOrderRouteExport` 统一管理所有路由 +- **依赖注入**: 使用 basic_modular 的依赖注入机制 +- **状态管理**: 基于 BLoC 模式的响应式状态管理 + +### 2. 核心功能实现 + +#### 订单中心页面特性 +- **TabController**: 5个标签页（全部、待付款、已付款、已完成、已取消） +- **响应式设计**: 支持下拉刷新的 RefreshIndicator +- **卡片列表**: 每个订单展示为 Card 组件 +- **导航集成**: 与订单详情页和发票管理页面的路由跳转 + +#### 发票管理系统 +- **发票选择管理**: `invoiceChooseManagePage` +- **发票详情页面**: `invoiceDetailsPage` +- **发票历史中心**: `invoiceHistoryCenterPage` +- **发票抬头管理**: 支持个人和企业发票抬头 + +#### 退款处理流程 +- **退款详情页**: `refunddetail_page.dart` +- **退款状态跟踪**: 支持退款进度查看 +- **退款原因记录**: 详细的退款申请理由 + +### 3. 与其他模块集成 + +```dart +// 集成示例 - 从其他模块跳转到订单相关页面 +class OrderNavigationHelper { + // 从充电模块跳转到订单中心 + static void gotoOrderCenterFromCharging() { + AppOrderRouteExport.gotoOrderCenter( + ModularRouteInformation.current(), + ); + } + + // 从维保模块跳转到具体订单详情 + static void gotoOrderDetailFromMaintenance(String orderId) { + AppOrderRouteExport.gotoOrderDetail( + ModularRouteInformation.current(), + orderId: orderId, + ); + } +} +``` + +## 最佳实践与规范 + +### 1. 代码组织 +- 页面文件统一放在 `src/pages/` 目录 +- 按功能模块分别组织（订单、发票、退款） +- 共享组件复用，减少代码重复 + +### 2. 状态管理 +- 采用 BLoC 模式管理复杂状态 +- TabController 管理标签页切换状态 +- RefreshIndicator 处理列表刷新状态 + +### 3. 用户体验优化 +- 支持下拉刷新和上拉加载 +- 响应式布局适配不同屏幕尺寸 +- 错误状态友好提示 + +### 4. 性能优化 +- 列表项懒加载，避免一次性加载过多数据 +- 图片缓存和占位符处理 +- 合理的状态更新频率控制 diff --git a/app_car/app_rpa.md b/app_car/app_rpa.md new file mode 100644 index 0000000..7709e47 --- /dev/null +++ b/app_car/app_rpa.md @@ -0,0 +1,350 @@ +# App RPA 自动化模块 + +## 模块概述 + +`app_rpa` 是 OneApp 车联网生态中的 RPA（Robotic Process Automation）自动化模块，负责车辆操作的自动化流程、智能任务调度、批量操作处理等功能。该模块通过自动化技术提升用户的车辆管理效率，减少重复性操作。 + +### 基本信息 +- **模块名称**: app_rpa +- **版本**: 0.1.7 +- **描述**: RPA自动化应用模块 +- **Flutter 版本**: >=2.10.5 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **自动化任务** + - 定时任务调度 + - 批量操作执行 + - 条件触发自动化 + - 智能任务优化 + +2. **流程自动化** + - 车辆状态自动检查 + - 维护提醒自动化 + - 数据同步自动化 + - 报告生成自动化 + +3. **智能调度** + - 任务优先级管理 + - 资源冲突解决 + - 执行时间优化 + - 失败重试机制 + +4. **监控管理** + - 任务执行监控 + - 性能指标统计 + - 异常告警处理 + - 日志记录分析 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── app_rpa.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── automation/ # 自动化引擎 +│ ├── scheduler/ # 任务调度器 +│ ├── tasks/ # 任务定义 +│ ├── monitors/ # 监控组件 +│ ├── pages/ # 页面组件 +│ ├── models/ # 数据模型 +│ └── utils/ # 工具类 +├── generated/ # 代码生成文件 +└── l10n/ # 国际化文件 +``` + +### 依赖关系 + +#### 核心依赖 +- `basic_modular: ^0.2.3` - 模块化框架 +- `basic_modular_route: ^0.2.1` - 路由管理 +- `basic_intl: ^0.2.0` - 国际化支持 +- `basic_theme: ^0.2.5` - 主题系统 +- `basic_track: ^0.1.3` - 数据埋点 + +#### 业务依赖 +- `car_rpa: ^0.1.5` - RPA服务SDK +- `location_service_check: ^1.0.1` - 位置服务检查 +- `amap_flutter_location: ^3.0.3` - 高德定位服务 + +#### 第三方依赖 +- `json_annotation: ^4.8.1` - JSON序列化 +- `dartz: ^0.10.1` - 函数式编程 +- `shared_preferences: ^2.2.2` - 本地存储 +- `flutter_constraintlayout: ^1.7.0-stable` - 约束布局 +- `url_launcher: ^6.1.11` - URL启动 + +## 核心模块分析 + +### 1. 模块入口 (`app_rpa.dart`) + +**功能职责**: +- 模块对外接口统一导出 +- RPA服务初始化 +- 自动化引擎启动 + +### 2. 自动化引擎 (`src/automation/`) + +**功能职责**: +- 自动化任务执行引擎 +- 流程控制逻辑 +- 条件判断处理 +- 异常恢复机制 + +**主要组件**: +- `AutomationEngine` - 自动化引擎核心 +- `ProcessController` - 流程控制器 +- `ConditionEvaluator` - 条件评估器 +- `ErrorHandler` - 错误处理器 + +### 3. 任务调度器 (`src/scheduler/`) + +**功能职责**: +- 任务时间调度 +- 优先级队列管理 +- 资源分配控制 +- 并发执行协调 + +**主要组件**: +- `TaskScheduler` - 任务调度器 +- `PriorityQueue` - 优先级队列 +- `ResourceManager` - 资源管理器 +- `ConcurrencyController` - 并发控制器 + +### 4. 任务定义 (`src/tasks/`) + +**功能职责**: +- 预定义任务模板 +- 自定义任务创建 +- 任务参数配置 +- 任务生命周期管理 + +**主要任务类型**: +- `VehicleCheckTask` - 车辆状态检查任务 +- `MaintenanceReminderTask` - 维护提醒任务 +- `DataSyncTask` - 数据同步任务 +- `ReportGenerationTask` - 报告生成任务 + +### 5. 监控组件 (`src/monitors/`) + +**功能职责**: +- 任务执行监控 +- 性能指标收集 +- 异常检测告警 +- 统计数据分析 + +**主要监控器**: +- `ExecutionMonitor` - 执行监控器 +- `PerformanceMonitor` - 性能监控器 +- `ExceptionMonitor` - 异常监控器 +- `StatisticsCollector` - 统计收集器 + +### 6. 页面组件 (`src/pages/`) + +**功能职责**: +- 用户界面展示 +- 任务管理界面 +- 监控仪表板 +- 配置设置页面 + +**主要页面**: +- `RPAHomePage` - RPA主页 +- `TaskManagementPage` - 任务管理页 +- `MonitorDashboardPage` - 监控仪表板 +- `AutomationConfigPage` - 自动化配置页 + +### 7. 数据模型 (`src/models/`) + +**功能职责**: +- 任务数据模型 +- 执行结果模型 +- 配置参数模型 +- 统计数据模型 + +**主要模型**: +- `Task` - 任务模型 +- `ExecutionResult` - 执行结果模型 +- `AutomationConfig` - 自动化配置模型 +- `MonitoringData` - 监控数据模型 + +### 8. 工具类 (`src/utils/`) + +**功能职责**: +- RPA工具方法 +- 数据处理辅助 +- 时间计算工具 +- 配置解析工具 + +**主要工具**: +- `TaskBuilder` - 任务构建器 +- `CronParser` - 定时表达式解析器 +- `DataProcessor` - 数据处理器 +- `ConfigValidator` - 配置验证器 + +## 业务流程 + +### 任务调度流程 +```mermaid +graph TD + A[创建任务] --> B[任务验证] + B --> C{验证是否通过} + C -->|是| D[添加到调度队列] + C -->|否| E[返回错误信息] + D --> F[等待调度执行] + F --> G[检查执行条件] + G --> H{条件是否满足} + H -->|是| I[开始执行任务] + H -->|否| J[延迟或跳过] + I --> K[监控执行过程] + K --> L{执行是否成功} + L -->|是| M[记录成功结果] + L -->|否| N[执行重试逻辑] + N --> O{重试次数是否超限} + O -->|是| P[标记为失败] + O -->|否| I + J --> Q[更新任务状态] + M --> Q + P --> Q + Q --> R[通知结果] +``` + +### 自动化执行流程 +```mermaid +graph TD + A[触发自动化] --> B[加载任务配置] + B --> C[初始化执行环境] + C --> D[开始执行步骤] + D --> E[执行当前步骤] + E --> F[检查步骤结果] + F --> G{是否成功} + G -->|是| H[执行下一步骤] + G -->|否| I[执行错误处理] + I --> J{是否可恢复} + J -->|是| K[尝试恢复] + J -->|否| L[终止执行] + K --> M{恢复是否成功} + M -->|是| H + M -->|否| L + H --> N{是否还有步骤} + N -->|是| E + N -->|否| O[执行完成] + L --> P[清理资源] + O --> P + P --> Q[生成执行报告] +``` + +## RPA引擎设计 + +### 任务类型 +1. **定时任务** + - 周期性检查任务 + - 定时报告生成 + - 数据备份任务 + - 清理维护任务 + +2. **事件驱动任务** + - 状态变化触发 + - 异常检测触发 + - 用户操作触发 + - 外部系统触发 + +3. **条件任务** + - 基于位置的任务 + - 基于时间的任务 + - 基于状态的任务 + - 基于数据的任务 + +4. **流程任务** + - 多步骤流程 + - 分支判断流程 + - 循环执行流程 + - 并行处理流程 + +### 执行策略 +- **立即执行**: 任务创建后立即执行 +- **延迟执行**: 指定时间后执行 +- **周期执行**: 按周期重复执行 +- **条件执行**: 满足条件时执行 + +## 安全特性 + +### 权限控制 +- 任务执行权限验证 +- 敏感操作授权检查 +- 用户身份认证 +- 操作审计日志 + +### 数据安全 +- 任务配置加密存储 +- 执行日志安全保护 +- 敏感数据脱敏处理 +- 传输数据加密 + +## 性能优化 + +### 执行优化 +- 任务批量处理 +- 并发执行控制 +- 资源池管理 +- 缓存机制优化 + +### 内存管理 +- 任务数据懒加载 +- 执行上下文清理 +- 大数据分片处理 +- 内存泄漏监控 + +## 扩展性设计 + +### 插件化架构 +- 自定义任务插件 +- 第三方服务集成 +- 扩展触发器类型 +- 自定义执行器 + +### 配置化管理 +- 任务模板可配置 +- 执行策略可调整 +- 监控规则可定制 +- 告警机制可配置 + +## 测试策略 + +### 单元测试 +- 任务执行逻辑测试 +- 调度器功能测试 +- 数据模型测试 +- 工具类方法测试 + +### 集成测试 +- 端到端任务执行测试 +- 服务集成测试 +- 数据流测试 +- 异常场景测试 + +### 性能测试 +- 并发执行压力测试 +- 长时间运行稳定性测试 +- 内存使用测试 +- 响应时间测试 + +## 部署和维护 + +### 配置管理 +- 环境配置分离 +- 任务参数配置 +- 性能调优参数 +- 监控阈值配置 + +### 监控指标 +- 任务执行成功率 +- 平均执行时间 +- 系统资源使用率 +- 异常错误统计 + +## 总结 + +`app_rpa` 模块作为 OneApp 的自动化中枢，为用户提供了强大的车辆管理自动化能力。通过智能的任务调度、可靠的执行引擎和完善的监控机制，用户可以实现车辆管理的自动化和智能化，显著提升管理效率。模块具有良好的扩展性和可维护性，能够适应不断变化的自动化需求。 diff --git a/app_car/app_touchgo.md b/app_car/app_touchgo.md new file mode 100644 index 0000000..3f3f286 --- /dev/null +++ b/app_car/app_touchgo.md @@ -0,0 +1,380 @@ +# App TouchGo 触控交互模块 + +## 模块概述 + +`app_touchgo` 是 OneApp 车联网生态中的触控交互模块，负责车辆的触控操作、手势识别、快捷操作等功能。该模块为用户提供直观便捷的车辆交互体验，通过手势和触控操作简化车辆控制流程。 + +### 基本信息 +- **模块名称**: app_touchgo +- **版本**: 0.1.5 +- **描述**: 触控交互应用模块 +- **Flutter 版本**: >=2.5.0 +- **Dart 版本**: >=2.16.2 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **触控交互** + - 多点触控识别 + - 手势操作识别 + - 快捷操作设置 + - 触控反馈优化 + +2. **桌面小组件** + - 车辆状态小组件 + - 快捷控制小组件 + - 信息展示小组件 + - 自定义小组件 + +3. **地理位置集成** + - 基于位置的操作 + - 地理围栏触发 + - 位置相关提醒 + - 地图触控交互 + +4. **车辆服务集成** + - 车辆控制接口 + - 状态信息获取 + - 服务调用优化 + - 实时数据同步 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── app_touchgo.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── gestures/ # 手势识别 +│ ├── widgets/ # 桌面小组件 +│ ├── controllers/ # 控制器 +│ ├── services/ # 服务层 +│ ├── pages/ # 页面组件 +│ ├── models/ # 数据模型 +│ └── utils/ # 工具类 +├── generated/ # 代码生成文件 +└── l10n/ # 国际化文件 +``` + +### 依赖关系 + +#### 核心依赖 +- `basic_modular: ^0.2.3` - 模块化框架 +- `basic_modular_route: ^0.2.1` - 路由管理 +- `basic_intl_flutter: ^0.2.2+1` - 国际化Flutter支持 +- `basic_intl: ^0.2.0` - 国际化基础 +- `basic_logger: ^0.2.2` - 日志系统 + +#### 业务依赖 +- `ui_basic: ^0.2.17` - 基础UI组件 +- `car_services: ^0.6.1` - 车辆服务 +- `car_vehicle: ^0.6.4+1` - 车辆控制 +- `clr_geo: ^0.2.16+1` - 地理位置服务 +- `clr_touchgo: ^0.1.3` - 触控服务SDK + +#### 第三方依赖 +- `json_annotation: ^4.8.1` - JSON序列化 +- `dartz: ^0.10.1` - 函数式编程 +- `home_widget: ^0.6.0` - 桌面小组件 +- `amap_flutter_base: ^3.0.4` - 高德地图基础 +- `amap_flutter_search: ^0.0.17` - 高德地图搜索 + +## 核心模块分析 + +### 1. 模块入口 (`app_touchgo.dart`) + +**功能职责**: +- 模块对外接口统一导出 +- 触控服务初始化 +- 手势识别引擎启动 + +### 2. 手势识别 (`src/gestures/`) + +**功能职责**: +- 多点触控处理 +- 手势模式识别 +- 自定义手势定义 +- 手势事件分发 + +**主要组件**: +- `GestureDetector` - 手势检测器 +- `TouchProcessor` - 触控处理器 +- `GestureRecognizer` - 手势识别器 +- `CustomGestureBuilder` - 自定义手势构建器 + +**支持的手势类型**: +- 单击/双击 +- 长按操作 +- 滑动手势 +- 缩放手势 +- 旋转手势 +- 多指操作 + +### 3. 桌面小组件 (`src/widgets/`) + +**功能职责**: +- 原生桌面小组件 +- 车辆信息展示 +- 快捷操作入口 +- 实时数据更新 + +**主要小组件**: +- `VehicleStatusWidget` - 车辆状态小组件 +- `QuickControlWidget` - 快捷控制小组件 +- `LocationWidget` - 位置信息小组件 +- `BatteryWidget` - 电池状态小组件 + +### 4. 控制器 (`src/controllers/`) + +**功能职责**: +- 触控事件处理 +- 车辆操作控制 +- 状态管理协调 +- 数据流控制 + +**主要控制器**: +- `TouchController` - 触控控制器 +- `VehicleController` - 车辆控制器 +- `WidgetController` - 小组件控制器 +- `GestureController` - 手势控制器 + +### 5. 服务层 (`src/services/`) + +**功能职责**: +- 车辆服务接口 +- 地理位置服务 +- 小组件数据服务 +- 触控数据处理 + +**主要服务**: +- `VehicleService` - 车辆服务 +- `LocationService` - 位置服务 +- `WidgetDataService` - 小组件数据服务 +- `TouchDataService` - 触控数据服务 + +### 6. 页面组件 (`src/pages/`) + +**功能职责**: +- 用户界面展示 +- 交互配置页面 +- 手势设置页面 +- 小组件管理页面 + +**主要页面**: +- `TouchGoHomePage` - 触控主页 +- `GestureConfigPage` - 手势配置页 +- `WidgetManagementPage` - 小组件管理页 +- `TouchSettingsPage` - 触控设置页 + +### 7. 数据模型 (`src/models/`) + +**功能职责**: +- 触控数据模型 +- 手势配置模型 +- 小组件数据模型 +- 车辆状态模型 + +**主要模型**: +- `TouchEvent` - 触控事件模型 +- `GestureConfig` - 手势配置模型 +- `WidgetData` - 小组件数据模型 +- `VehicleStatus` - 车辆状态模型 + +### 8. 工具类 (`src/utils/`) + +**功能职责**: +- 触控工具方法 +- 手势计算工具 +- 数据转换工具 +- 性能优化工具 + +**主要工具**: +- `TouchCalculator` - 触控计算器 +- `GestureAnalyzer` - 手势分析器 +- `WidgetRenderer` - 小组件渲染器 +- `PerformanceOptimizer` - 性能优化器 + +## 业务流程 + +### 手势识别流程 +```mermaid +graph TD + A[接收触控事件] --> B[预处理触控数据] + B --> C[分析触控模式] + C --> D{是否为已知手势} + D -->|是| E[匹配手势类型] + D -->|否| F[记录未知模式] + E --> G[执行对应操作] + G --> H[提供触觉反馈] + H --> I[记录操作日志] + F --> J[学习新手势] + J --> K{是否需要用户确认} + K -->|是| L[请求用户确认] + K -->|否| M[自动学习] + L --> N{用户是否确认} + N -->|是| O[保存新手势] + N -->|否| P[丢弃手势] + M --> O + O --> Q[更新手势库] + P --> R[结束处理] + I --> R + Q --> R +``` + +### 小组件更新流程 +```mermaid +graph TD + A[数据变化事件] --> B[检查小组件订阅] + B --> C{是否有订阅小组件} + C -->|是| D[获取最新数据] + C -->|否| E[忽略更新] + D --> F[格式化数据] + F --> G[渲染小组件] + G --> H[更新系统桌面] + H --> I[验证更新结果] + I --> J{更新是否成功} + J -->|是| K[记录成功日志] + J -->|否| L[执行重试机制] + L --> M{重试次数是否超限} + M -->|是| N[记录失败日志] + M -->|否| G + K --> O[通知订阅者] + N --> P[发送错误报告] + O --> Q[结束更新] + P --> Q + E --> Q +``` + +## 触控交互设计 + +### 手势类型 +1. **基础手势** + - 单击：快速操作 + - 双击：确认操作 + - 长按：菜单操作 + - 滑动：切换操作 + +2. **复合手势** + - 双指缩放：调整参数 + - 三指滑动：切换模式 + - 多指点击：组合操作 + - 自定义手势：个性化操作 + +3. **上下文手势** + - 基于位置的手势 + - 基于时间的手势 + - 基于状态的手势 + - 基于场景的手势 + +### 反馈机制 +- **触觉反馈**: 震动反馈 +- **视觉反馈**: 动画效果 +- **听觉反馈**: 提示音效 +- **语音反馈**: 语音确认 + +## 小组件设计 + +### 小组件类型 +1. **信息展示类** + - 车辆状态展示 + - 电池电量显示 + - 位置信息显示 + - 天气信息显示 + +2. **快捷操作类** + - 一键锁车/解锁 + - 空调控制 + - 充电控制 + - 导航启动 + +3. **监控类** + - 安全状态监控 + - 异常告警显示 + - 维护提醒 + - 服务通知 + +### 更新策略 +- **实时更新**: 关键状态信息 +- **定时更新**: 定期刷新数据 +- **事件更新**: 状态变化触发 +- **手动更新**: 用户主动刷新 + +## 安全特性 + +### 权限控制 +- 触控操作权限验证 +- 敏感功能授权检查 +- 用户身份认证 +- 操作审计记录 + +### 数据保护 +- 触控数据加密存储 +- 手势模式隐私保护 +- 敏感操作二次确认 +- 数据传输安全 + +## 性能优化 + +### 触控优化 +- 触控事件去抖动 +- 手势识别算法优化 +- 响应时间优化 +- 内存使用优化 + +### 小组件优化 +- 数据缓存机制 +- 增量更新策略 +- 渲染性能优化 +- 电池续航优化 + +## 扩展性设计 + +### 插件化架构 +- 自定义手势插件 +- 第三方小组件集成 +- 扩展触控功能 +- 自定义反馈机制 + +### 配置化管理 +- 手势灵敏度配置 +- 反馈强度设置 +- 小组件布局配置 +- 个性化定制 + +## 测试策略 + +### 单元测试 +- 手势识别算法测试 +- 触控事件处理测试 +- 数据模型测试 +- 工具类方法测试 + +### 集成测试 +- 车辆服务集成测试 +- 小组件功能测试 +- 地理位置集成测试 +- 完整交互流程测试 + +### 用户体验测试 +- 手势响应速度测试 +- 操作准确性测试 +- 用户满意度测试 +- 易用性评估 + +## 部署和维护 + +### 配置管理 +- 手势库配置 +- 小组件模板配置 +- 性能参数调优 +- 权限策略配置 + +### 监控指标 +- 手势识别准确率 +- 触控响应时间 +- 小组件更新成功率 +- 用户操作频率 + +## 总结 + +`app_touchgo` 模块作为 OneApp 的触控交互中心，为用户提供了直观便捷的车辆操作体验。通过先进的手势识别技术、丰富的桌面小组件和智能的触控反馈，用户可以更自然地与车辆进行交互。模块具有良好的扩展性和个性化能力，能够适应不同用户的使用习惯和需求。 diff --git a/app_car/app_vur.md b/app_car/app_vur.md new file mode 100644 index 0000000..2df028c --- /dev/null +++ b/app_car/app_vur.md @@ -0,0 +1,351 @@ +# App VUR 车辆更新记录模块 + +## 模块概述 + +`app_vur` 是 OneApp 车联网生态中的 VUR（Vehicle Update Record）车辆更新记录模块，负责车辆软件更新、固件升级、系统维护记录等功能。该模块为用户提供完整的车辆更新历史追踪和管理服务。 + +### 基本信息 +- **模块名称**: app_vur +- **版本**: 0.1.25 +- **描述**: 车辆更新记录应用模块 +- **Flutter 版本**: >=2.5.0 +- **Dart 版本**: >=2.16.2 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **更新记录管理** + - 软件更新历史记录 + - 固件升级跟踪 + - 系统维护日志 + - 版本变更记录 + +2. **更新进度监控** + - 实时更新进度显示 + - 更新状态跟踪 + - 错误信息收集 + - 回滚操作支持 + +3. **版本信息展示** + - 当前系统版本信息 + - 可用更新检查 + - 版本差异对比 + - 更新说明展示 + +4. **分享和导出** + - 更新记录分享 + - 日志文件导出 + - 报告生成功能 + - 技术支持数据 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── app_vur.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── records/ # 记录管理 +│ ├── updates/ # 更新处理 +│ ├── versions/ # 版本管理 +│ ├── monitoring/ # 监控组件 +│ ├── pages/ # 页面组件 +│ ├── models/ # 数据模型 +│ └── utils/ # 工具类 +├── generated/ # 代码生成文件 +└── l10n/ # 国际化文件 +``` + +### 依赖关系 + +#### 核心依赖 +- `basic_modular: ^0.2.3` - 模块化框架 +- `basic_modular_route: ^0.2.1` - 路由管理 +- `basic_intl: ^0.2.0` - 国际化基础 +- `basic_intl_flutter: ^0.2.2+1` - 国际化Flutter支持 + +#### 业务依赖 +- `car_vur: ^0.1.12` - VUR服务SDK +- `basic_webview: ^0.2.4` - WebView组件 +- `app_consent: ^0.2.19` - 用户同意模块 +- `basic_consent: ^0.2.17` - 基础同意框架 +- `basic_share: ^0.2.1` - 基础分享服务 +- `ui_share: ^0.2.0` - 分享UI组件 + +#### 第三方依赖 +- `json_annotation: ^4.8.1` - JSON序列化 +- `dartz: ^0.10.1` - 函数式编程 +- `super_tooltip: ^2.0.8` - 提示框组件 +- `just_the_tooltip: ^0.0.12` - 轻量级提示框 + +## 核心模块分析 + +### 1. 模块入口 (`app_vur.dart`) + +**功能职责**: +- 模块对外接口统一导出 +- VUR服务初始化 +- 更新监控启动 + +### 2. 记录管理 (`src/records/`) + +**功能职责**: +- 更新记录存储和管理 +- 历史数据查询 +- 记录分类和筛选 +- 数据备份和恢复 + +**主要组件**: +- `RecordManager` - 记录管理器 +- `RecordStorage` - 记录存储 +- `RecordQuery` - 记录查询 +- `RecordBackup` - 记录备份 + +### 3. 更新处理 (`src/updates/`) + +**功能职责**: +- 更新任务处理 +- 更新进度跟踪 +- 更新状态管理 +- 异常处理和恢复 + +**主要组件**: +- `UpdateProcessor` - 更新处理器 +- `ProgressTracker` - 进度跟踪器 +- `StatusManager` - 状态管理器 +- `ErrorHandler` - 错误处理器 + +### 4. 版本管理 (`src/versions/`) + +**功能职责**: +- 版本信息管理 +- 版本比较和分析 +- 兼容性检查 +- 依赖关系处理 + +**主要组件**: +- `VersionManager` - 版本管理器 +- `VersionComparator` - 版本比较器 +- `CompatibilityChecker` - 兼容性检查器 +- `DependencyResolver` - 依赖解析器 + +### 5. 监控组件 (`src/monitoring/`) + +**功能职责**: +- 更新过程监控 +- 性能指标收集 +- 异常检测和报告 +- 系统健康状态监控 + +**主要监控器**: +- `UpdateMonitor` - 更新监控器 +- `PerformanceCollector` - 性能收集器 +- `HealthChecker` - 健康检查器 +- `AlertManager` - 告警管理器 + +### 6. 页面组件 (`src/pages/`) + +**功能职责**: +- 用户界面展示 +- 更新记录展示 +- 版本信息页面 +- 设置配置页面 + +**主要页面**: +- `VURHomePage` - VUR主页 +- `UpdateHistoryPage` - 更新历史页 +- `VersionInfoPage` - 版本信息页 +- `UpdateProgressPage` - 更新进度页 +- `SettingsPage` - 设置页面 + +### 7. 数据模型 (`src/models/`) + +**功能职责**: +- 更新记录数据模型 +- 版本信息模型 +- 进度状态模型 +- 配置参数模型 + +**主要模型**: +- `UpdateRecord` - 更新记录模型 +- `VersionInfo` - 版本信息模型 +- `UpdateProgress` - 更新进度模型 +- `VURConfig` - VUR配置模型 + +### 8. 工具类 (`src/utils/`) + +**功能职责**: +- VUR工具方法 +- 数据处理辅助 +- 文件操作工具 +- 格式化工具 + +**主要工具**: +- `RecordFormatter` - 记录格式化器 +- `DataExporter` - 数据导出器 +- `LogAnalyzer` - 日志分析器 +- `ReportGenerator` - 报告生成器 + +## 业务流程 + +### 更新记录流程 +```mermaid +graph TD + A[检测到更新] --> B[创建更新记录] + B --> C[记录初始状态] + C --> D[开始更新过程] + D --> E[实时记录进度] + E --> F[监控更新状态] + F --> G{更新是否成功} + G -->|是| H[记录成功状态] + G -->|否| I[记录失败信息] + H --> J[更新版本信息] + I --> K[保存错误日志] + J --> L[生成更新报告] + K --> M[触发异常处理] + L --> N[通知用户结果] + M --> O[记录恢复操作] + N --> P[保存完整记录] + O --> P + P --> Q[更新历史列表] +``` + +### 版本检查流程 +```mermaid +graph TD + A[启动版本检查] --> B[获取当前版本] + B --> C[查询可用更新] + C --> D{是否有新版本} + D -->|是| E[获取版本详情] + D -->|否| F[记录检查结果] + E --> G[检查兼容性] + G --> H{是否兼容} + H -->|是| I[显示更新提示] + H -->|否| J[记录兼容性问题] + I --> K[用户确认更新] + K --> L{用户是否同意} + L -->|是| M[开始更新流程] + L -->|否| N[记录用户拒绝] + J --> O[提供解决方案] + F --> P[结束检查] + M --> P + N --> P + O --> P +``` + +## VUR系统设计 + +### 记录类型 +1. **软件更新记录** + - 应用程序更新 + - 系统软件更新 + - 驱动程序更新 + - 配置文件更新 + +2. **固件升级记录** + - ECU固件升级 + - 传感器固件更新 + - 通信模块更新 + - 安全模块升级 + +3. **维护记录** + - 系统诊断记录 + - 性能优化记录 + - 清理维护记录 + - 配置修改记录 + +4. **回滚记录** + - 更新回滚操作 + - 版本降级记录 + - 恢复操作日志 + - 紧急修复记录 + +### 状态管理 +- **待更新**: 检测到可用更新 +- **下载中**: 正在下载更新包 +- **准备中**: 准备安装更新 +- **安装中**: 正在安装更新 +- **验证中**: 验证更新结果 +- **完成**: 更新成功完成 +- **失败**: 更新过程失败 +- **回滚**: 执行回滚操作 + +## 安全特性 + +### 数据完整性 +- 更新记录数字签名 +- 数据校验和验证 +- 记录篡改检测 +- 备份数据验证 + +### 隐私保护 +- 敏感信息加密存储 +- 用户数据脱敏处理 +- 访问权限控制 +- 数据传输加密 + +## 性能优化 + +### 存储优化 +- 记录数据压缩 +- 过期数据清理 +- 索引优化设计 +- 查询性能优化 + +### 内存管理 +- 大数据分页加载 +- 缓存机制优化 +- 内存使用监控 +- 资源及时释放 + +## 扩展性设计 + +### 插件化架构 +- 自定义记录类型 +- 第三方更新源集成 +- 扩展监控功能 +- 自定义报告格式 + +### 配置化管理 +- 记录保留策略配置 +- 监控规则可配置 +- 报告模板定制 +- 告警阈值设置 + +## 测试策略 + +### 单元测试 +- 记录管理逻辑测试 +- 版本比较算法测试 +- 数据模型测试 +- 工具类方法测试 + +### 集成测试 +- 更新流程端到端测试 +- 服务集成测试 +- 数据持久化测试 +- 异常场景测试 + +### 性能测试 +- 大量记录处理测试 +- 查询性能测试 +- 内存使用测试 +- 并发访问测试 + +## 部署和维护 + +### 配置管理 +- 记录存储配置 +- 更新策略配置 +- 监控参数设置 +- 性能调优参数 + +### 监控指标 +- 更新成功率 +- 记录查询响应时间 +- 存储空间使用率 +- 异常错误统计 + +## 总结 + +`app_vur` 模块作为 OneApp 的车辆更新记录中心，为用户提供了完整的车辆软硬件更新历史追踪服务。通过详细的记录管理、实时的进度监控和完善的版本管理，用户可以全面了解车辆的更新状态和历史变更。模块具有良好的数据完整性保障和性能优化设计，能够可靠地记录和管理车辆的各类更新信息。 diff --git a/app_car/app_wallbox.md b/app_car/app_wallbox.md new file mode 100644 index 0000000..89867c9 --- /dev/null +++ b/app_car/app_wallbox.md @@ -0,0 +1,359 @@ +# App Wallbox 充电墙盒模块 + +## 模块概述 + +`app_wallbox` 是 OneApp 车联网生态中的充电墙盒管理模块，负责家用充电桩（墙盒）的管理、安装、配置和监控等功能。该模块为用户提供完整的家庭充电解决方案管理服务。 + +### 基本信息 +- **模块名称**: app_wallbox +- **版本**: 0.2.29 +- **描述**: 充电墙盒应用模块 +- **Flutter 版本**: >=2.10.5 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **墙盒设备管理** + - 设备注册和绑定 + - 设备状态监控 + - 设备配置管理 + - 设备固件升级 + +2. **安装服务** + - 安装预约申请 + - 安装进度跟踪 + - 安装城市选择 + - 安装文件上传 + +3. **充电管理** + - 远程充电控制 + - 充电计划设置 + - 充电记录查看 + - 电费统计分析 + +4. **智能功能** + - 智能充电调度 + - 电网负荷优化 + - 太阳能集成 + - 能源管理优化 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── app_wallbox.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── devices/ # 设备管理 +│ ├── installation/ # 安装服务 +│ ├── charging/ # 充电控制 +│ ├── monitoring/ # 监控组件 +│ ├── smart/ # 智能功能 +│ ├── pages/ # 页面组件 +│ ├── models/ # 数据模型 +│ └── utils/ # 工具类 +├── generated/ # 代码生成文件 +└── l10n/ # 国际化文件 +``` + +### 依赖关系 + +#### 核心依赖 +- `basic_modular: ^0.2.3` - 模块化框架 +- `basic_modular_route: ^0.2.1` - 路由管理 +- `basic_resource: ^0.2.10` - 资源管理 +- `basic_intl: ^0.2.0` - 国际化支持 +- `basic_storage: ^0.2.2` - 本地存储 +- `basic_network: ^0.2.3+3` - 网络通信 +- `basic_track: ^0.1.3` - 数据埋点 + +#### 业务依赖 +- `ui_business: ^0.2.23` - 业务UI组件 + +#### 第三方依赖 +- `json_annotation: ^4.6.0` - JSON序列化 +- `dartz: ^0.10.1` - 函数式编程 +- `extended_image: ^8.2.3` - 增强图片组件 +- `url_launcher: ^6.1.4` - URL启动 +- `collection: ^1.17.1` - 集合工具 +- `path_provider: ^2.0.15` - 文件路径 +- `path: ^1.8.3` - 路径操作 + +## 核心模块分析 + +### 1. 模块入口 (`app_wallbox.dart`) + +**功能职责**: +- 模块对外接口统一导出 +- 墙盒服务初始化 +- 设备管理启动 + +### 2. 设备管理 (`src/devices/`) + +**功能职责**: +- 墙盒设备注册和绑定 +- 设备状态实时监控 +- 设备配置参数管理 +- 设备固件和软件升级 + +**主要组件**: +- `DeviceManager` - 设备管理器 +- `DeviceRegistry` - 设备注册表 +- `StatusMonitor` - 状态监控器 +- `ConfigManager` - 配置管理器 +- `FirmwareUpdater` - 固件升级器 + +### 3. 安装服务 (`src/installation/`) + +**功能职责**: +- 安装服务预约和申请 +- 安装进度实时跟踪 +- 安装城市和地区选择 +- 安装相关文件上传管理 + +**主要组件**: +- `InstallationService` - 安装服务 +- `ProgressTracker` - 进度跟踪器 +- `CityPicker` - 城市选择器 +- `UploadManager` - 文件上传管理器 +- `AppointmentManager` - 预约管理器 + +### 4. 充电控制 (`src/charging/`) + +**功能职责**: +- 远程充电启停控制 +- 充电计划和策略设置 +- 充电过程监控 +- 充电数据记录和分析 + +**主要组件**: +- `ChargingController` - 充电控制器 +- `ScheduleManager` - 计划管理器 +- `ProcessMonitor` - 过程监控器 +- `DataRecorder` - 数据记录器 + +### 5. 监控组件 (`src/monitoring/`) + +**功能职责**: +- 设备运行状态监控 +- 充电过程实时监控 +- 异常检测和告警 +- 性能指标收集 + +**主要监控器**: +- `DeviceMonitor` - 设备监控器 +- `ChargingMonitor` - 充电监控器 +- `AlertManager` - 告警管理器 +- `MetricsCollector` - 指标收集器 + +### 6. 智能功能 (`src/smart/`) + +**功能职责**: +- 智能充电调度算法 +- 电网负荷平衡优化 +- 可再生能源集成 +- 能源成本优化 + +**主要组件**: +- `SmartScheduler` - 智能调度器 +- `LoadBalancer` - 负荷均衡器 +- `EnergyOptimizer` - 能源优化器 +- `GridInterface` - 电网接口 + +### 7. 页面组件 (`src/pages/`) + +**功能职责**: +- 用户界面展示 +- 设备管理界面 +- 充电控制界面 +- 安装服务界面 + +**主要页面**: +- `WallboxHomePage` - 墙盒主页 +- `DeviceManagementPage` - 设备管理页 +- `ChargingControlPage` - 充电控制页 +- `InstallationPage` - 安装服务页 +- `MonitoringDashboard` - 监控仪表板 + +### 8. 数据模型 (`src/models/`) + +**功能职责**: +- 设备信息数据模型 +- 充电数据模型 +- 安装服务模型 +- 配置参数模型 + +**主要模型**: +- `WallboxDevice` - 墙盒设备模型 +- `ChargingSession` - 充电会话模型 +- `InstallationOrder` - 安装订单模型 +- `DeviceConfig` - 设备配置模型 + +### 9. 工具类 (`src/utils/`) + +**功能职责**: +- 墙盒工具方法 +- 数据处理辅助 +- 文件操作工具 +- 计算辅助工具 + +**主要工具**: +- `PowerCalculator` - 功率计算器 +- `EnergyAnalyzer` - 能源分析器 +- `FileUploader` - 文件上传器 +- `DataFormatter` - 数据格式化器 + +## 业务流程 + +### 设备安装流程 +```mermaid +graph TD + A[用户申请安装] --> B[选择安装城市] + B --> C[填写安装信息] + C --> D[上传相关文件] + D --> E[提交安装申请] + E --> F[系统审核申请] + F --> G{审核是否通过} + G -->|是| H[安排安装服务] + G -->|否| I[通知修改申请] + H --> J[派遣安装团队] + J --> K[现场安装施工] + K --> L[设备调试测试] + L --> M{测试是否通过} + M -->|是| N[设备注册绑定] + M -->|否| O[问题排查修复] + N --> P[安装完成] + O --> L + I --> C + P --> Q[用户验收] +``` + +### 智能充电流程 +```mermaid +graph TD + A[用户设置充电需求] --> B[系统分析用电负荷] + B --> C[获取电价信息] + C --> D[检查电网状态] + D --> E[计算最优充电策略] + E --> F[生成充电计划] + F --> G[用户确认计划] + G --> H{用户是否同意} + H -->|是| I[执行充电计划] + H -->|否| J[调整计划参数] + I --> K[监控充电过程] + K --> L[动态调整功率] + L --> M{是否达到目标} + M -->|是| N[充电完成] + M -->|否| O[继续充电] + J --> E + O --> K + N --> P[生成充电报告] +``` + +## 墙盒系统设计 + +### 设备类型 +1. **家用标准墙盒** + - 7kW交流充电 + - 单相/三相供电 + - WiFi/以太网连接 + - 基础智能功能 + +2. **商用快充墙盒** + - 22kW交流快充 + - 三相供电 + - 有线网络连接 + - 高级智能功能 + +3. **智能墙盒** + - 可变功率充电 + - 太阳能集成 + - 储能系统集成 + - AI优化算法 + +### 通信协议 +- **OCPP**: 开放充电点协议 +- **Modbus**: 工业通信协议 +- **HTTP/HTTPS**: Web API通信 +- **MQTT**: 物联网消息协议 + +## 安全特性 + +### 设备安全 +- 设备身份认证 +- 通信数据加密 +- 固件签名验证 +- 安全升级机制 + +### 用户安全 +- 用户身份验证 +- 操作权限控制 +- 敏感数据保护 +- 安全审计日志 + +## 性能优化 + +### 通信优化 +- 数据压缩传输 +- 断线重连机制 +- 离线数据缓存 +- 网络自适应 + +### 能效优化 +- 智能功率调节 +- 负荷均衡算法 +- 能源损耗最小化 +- 电网友好充电 + +## 扩展性设计 + +### 协议支持 +- 多种通信协议适配 +- 标准协议兼容 +- 自定义协议扩展 +- 协议版本升级 + +### 设备兼容 +- 多厂商设备支持 +- 不同型号适配 +- 新设备快速接入 +- 设备能力自动识别 + +## 测试策略 + +### 单元测试 +- 充电控制逻辑测试 +- 设备通信测试 +- 数据模型测试 +- 算法功能测试 + +### 集成测试 +- 设备集成测试 +- 系统端到端测试 +- 协议兼容性测试 +- 性能压力测试 + +### 现场测试 +- 实际设备测试 +- 网络环境测试 +- 用户场景测试 +- 长期稳定性测试 + +## 部署和维护 + +### 设备管理 +- 设备远程配置 +- 固件OTA升级 +- 故障远程诊断 +- 预防性维护 + +### 系统监控 +- 设备在线率监控 +- 充电成功率统计 +- 系统性能监控 +- 用户满意度跟踪 + +## 总结 + +`app_wallbox` 模块作为 OneApp 的家庭充电解决方案中心，为用户提供了完整的充电墙盒管理服务。通过智能的设备管理、便捷的安装服务和高效的充电控制，用户可以享受到安全、智能、经济的家庭充电体验。模块具有良好的设备兼容性和扩展能力，能够适应不断发展的充电技术和用户需求。 diff --git a/app_car/car_services.md b/app_car/car_services.md new file mode 100644 index 0000000..d05b52e --- /dev/null +++ b/app_car/car_services.md @@ -0,0 +1,374 @@ +# Car Services 车辆服务模块 + +## 模块概述 + +`car_services` 是 OneApp 车联网生态中的车辆服务模块，负责车辆核心服务的统一接口封装、车辆数据处理、服务调用管理和业务逻辑抽象等功能。该模块为上层应用提供了统一的车辆服务接口。 + +### 基本信息 +- **模块名称**: car_services +- **版本**: 0.6.25 +- **描述**: 车辆服务统一接口模块 +- **Flutter 版本**: >=2.10.5 +- **Dart 版本**: >=3.0.0 <4.0.08 + +## 功能特性 + +### 核心功能 +1. **服务接口统一** + - 车辆控制接口封装 + - 数据查询接口标准化 + - 异步调用管理 + - 错误处理统一 + +2. **数据模型管理** + - 车辆状态数据模型 + - 服务请求响应模型 + - 配置参数模型 + - 业务实体模型 + +3. **服务调用优化** + - 请求缓存机制 + - 批量操作支持 + - 超时重试机制 + - 并发控制管理 + +4. **业务逻辑抽象** + - 领域驱动设计 + - 服务层解耦 + - 依赖注入支持 + - 模块化架构 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── car_services.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── services/ # 服务实现 +│ ├── models/ # 数据模型 +│ ├── repositories/ # 数据仓库 +│ ├── interfaces/ # 接口定义 +│ ├── utils/ # 工具类 +│ └── constants/ # 常量定义 +├── test/ # 测试文件 +└── generated/ # 代码生成文件 +``` + +### 依赖关系 + +#### 核心框架依赖 +- `basic_modular: ^0.2.3` - 模块化框架 +- `basic_modular_route: ^0.2.1` - 路由管理 +- `basic_network: ^0.2.3+4` - 网络通信框架 +- `basic_intl: ^0.2.0` - 国际化支持 + +#### 业务依赖 +- `car_connector: ^0.4.11` - 车联网连接器 + +#### 工具依赖 +- `dartz: ^0.10.1` - 函数式编程 +- `freezed_annotation: ^2.2.0` - 数据类注解 + +#### 开发依赖 +- `build_runner: ^2.4.9` - 代码生成引擎 +- `freezed: ^2.4.7` - 不可变类生成 +- `json_serializable: ^6.7.0` - JSON序列化 +- `mockito: ^5.4.1` - 测试模拟框架 + +## 核心模块分析 + +### 1. 模块入口 (`car_services.dart`) + +**功能职责**: +- 服务模块对外接口导出 +- 依赖注入配置 +- 模块初始化管理 + +### 2. 服务实现 (`src/services/`) + +**功能职责**: +- 车辆控制服务实现 +- 数据查询服务实现 +- 状态监控服务实现 +- 配置管理服务实现 + +**主要服务**: +- `VehicleControlService` - 车辆控制服务 +- `VehicleDataService` - 车辆数据服务 +- `VehicleStatusService` - 车辆状态服务 +- `VehicleConfigService` - 车辆配置服务 +- `DiagnosticService` - 诊断服务 + +### 3. 数据模型 (`src/models/`) + +**功能职责**: +- 业务数据模型定义 +- 请求响应模型 +- 状态信息模型 +- 配置参数模型 + +**主要模型**: +- `VehicleInfo` - 车辆信息模型 +- `VehicleStatus` - 车辆状态模型 +- `ControlCommand` - 控制命令模型 +- `ServiceRequest` - 服务请求模型 +- `ServiceResponse` - 服务响应模型 + +### 4. 数据仓库 (`src/repositories/`) + +**功能职责**: +- 数据访问层抽象 +- 本地缓存管理 +- 远程数据获取 +- 数据同步控制 + +**主要仓库**: +- `VehicleRepository` - 车辆数据仓库 +- `ConfigRepository` - 配置数据仓库 +- `StatusRepository` - 状态数据仓库 +- `HistoryRepository` - 历史数据仓库 + +### 5. 接口定义 (`src/interfaces/`) + +**功能职责**: +- 服务接口抽象定义 +- 依赖倒置实现 +- 接口规范约束 +- 扩展性支持 + +**主要接口**: +- `IVehicleService` - 车辆服务接口 +- `IDataRepository` - 数据仓库接口 +- `IStatusProvider` - 状态提供者接口 +- `IConfigManager` - 配置管理接口 + +### 6. 工具类 (`src/utils/`) + +**功能职责**: +- 数据转换工具 +- 验证工具方法 +- 缓存工具 +- 网络工具 + +**主要工具**: +- `DataConverter` - 数据转换器 +- `Validator` - 数据验证器 +- `CacheHelper` - 缓存助手 +- `NetworkHelper` - 网络助手 + +### 7. 常量定义 (`src/constants/`) + +**功能职责**: +- 服务常量定义 +- 错误码管理 +- 配置常量 +- API端点定义 + +**主要常量**: +- `ServiceConstants` - 服务常量 +- `ErrorCodes` - 错误码定义 +- `ApiEndpoints` - API端点 +- `ConfigKeys` - 配置键值 + +## 业务流程 + +### 服务调用流程 +```mermaid +graph TD + A[应用发起请求] --> B[服务接口层] + B --> C[参数验证] + C --> D{验证是否通过} + D -->|否| E[返回验证错误] + D -->|是| F[检查本地缓存] + F --> G{缓存是否有效} + G -->|是| H[返回缓存数据] + G -->|否| I[调用远程服务] + I --> J[网络请求] + J --> K{请求是否成功} + K -->|是| L[处理响应数据] + K -->|否| M[错误处理] + L --> N[更新本地缓存] + N --> O[返回处理结果] + M --> P[重试机制] + P --> Q{是否需要重试} + Q -->|是| I + Q -->|否| R[返回错误结果] + E --> S[记录日志] + H --> S + O --> S + R --> S +``` + +### 数据同步流程 +```mermaid +graph TD + A[触发数据同步] --> B[获取本地数据版本] + B --> C[请求远程数据版本] + C --> D{版本是否一致} + D -->|是| E[无需同步] + D -->|否| F[下载增量数据] + F --> G[验证数据完整性] + G --> H{验证是否通过} + H -->|是| I[更新本地数据] + H -->|否| J[重新下载] + I --> K[更新版本信息] + K --> L[触发数据更新事件] + J --> M{重试次数是否超限} + M -->|否| F + M -->|是| N[同步失败] + E --> O[同步完成] + L --> O + N --> P[记录错误日志] +``` + +## 服务设计模式 + +### 领域驱动设计(DDD) +1. **实体层(Entity)** + - 车辆实体 + - 用户实体 + - 订单实体 + - 配置实体 + +2. **值对象层(Value Object)** + - 车辆状态 + - 位置信息 + - 时间范围 + - 配置项 + +3. **服务层(Service)** + - 领域服务 + - 应用服务 + - 基础设施服务 + +4. **仓库层(Repository)** + - 数据访问抽象 + - 缓存策略 + - 数据同步 + +### 依赖注入模式 +- **接口抽象**: 定义服务契约 +- **实现分离**: 具体实现与接口分离 +- **生命周期管理**: 单例、瞬态、作用域 +- **配置驱动**: 通过配置控制依赖关系 + +## 缓存策略 + +### 多级缓存架构 +1. **内存缓存** + - 热点数据缓存 + - LRU淘汰策略 + - 容量限制管理 + - 过期时间控制 + +2. **本地存储缓存** + - 持久化数据存储 + - 离线数据支持 + - 增量更新机制 + - 数据压缩存储 + +3. **远程缓存** + - CDN内容分发 + - 边缘节点缓存 + - 区域化数据 + - 负载均衡 + +### 缓存一致性 +- **写通策略**: 同时更新缓存和数据源 +- **写回策略**: 延迟写入数据源 +- **失效策略**: 主动失效过期数据 +- **版本控制**: 数据版本管理 + +## 错误处理机制 + +### 错误分类 +1. **网络错误** + - 连接超时 + - 网络不可达 + - 服务不可用 + - 限流熔断 + +2. **业务错误** + - 参数验证失败 + - 业务规则违反 + - 权限不足 + - 数据不存在 + +3. **系统错误** + - 内存不足 + - 存储空间不够 + - 系统异常 + - 未知错误 + +### 处理策略 +- **重试机制**: 指数退避重试 +- **熔断保护**: 快速失败机制 +- **降级处理**: 服务降级策略 +- **监控告警**: 异常监控报警 + +## 性能优化 + +### 请求优化 +- **批量请求**: 减少网络往返 +- **数据压缩**: 减少传输量 +- **连接复用**: HTTP连接池 +- **并发控制**: 限制并发数量 + +### 缓存优化 +- **预加载**: 预测性数据加载 +- **懒加载**: 按需数据加载 +- **缓存预热**: 系统启动预热 +- **缓存穿透保护**: 空值缓存 + +## 扩展性设计 + +### 插件化架构 +- **服务插件**: 自定义服务实现 +- **数据源插件**: 多数据源支持 +- **缓存插件**: 自定义缓存策略 +- **网络插件**: 网络适配器 + +### 配置化管理 +- **服务配置**: 服务参数可配置 +- **缓存配置**: 缓存策略可调整 +- **网络配置**: 网络参数可设置 +- **业务配置**: 业务规则可定制 + +## 测试策略 + +### 单元测试 +- **服务逻辑测试**: 业务逻辑正确性 +- **数据模型测试**: 序列化反序列化 +- **工具类测试**: 工具方法功能 +- **接口测试**: 接口契约验证 + +### 集成测试 +- **服务集成测试**: 端到端流程 +- **数据库集成测试**: 数据访问层 +- **网络集成测试**: 网络通信 +- **缓存集成测试**: 缓存机制 + +### 性能测试 +- **压力测试**: 高并发场景 +- **负载测试**: 正常负载下性能 +- **容量测试**: 系统容量极限 +- **稳定性测试**: 长时间运行 + +## 部署和维护 + +### 配置管理 +- **环境配置**: 开发、测试、生产 +- **服务配置**: API地址、超时设置 +- **缓存配置**: 缓存策略参数 +- **业务配置**: 业务规则参数 + +### 监控指标 +- **性能指标**: 响应时间、吞吐量 +- **错误指标**: 错误率、失败次数 +- **资源指标**: CPU、内存使用率 +- **业务指标**: 调用次数、成功率 + +## 总结 + +`car_services` 模块作为 OneApp 的车辆服务统一接口层，通过领域驱动设计和模块化架构，为上层应用提供了稳定、高效、可扩展的车辆服务能力。模块具有完善的缓存机制、错误处理和性能优化策略，能够满足大规模车联网应用的服务需求。 diff --git a/app_car/clr_avatarcore.md b/app_car/clr_avatarcore.md new file mode 100644 index 0000000..b747aa9 --- /dev/null +++ b/app_car/clr_avatarcore.md @@ -0,0 +1,372 @@ +# CLR AvatarCore 虚拟形象核心服务 + +## 模块概述 + +`clr_avatarcore` 是 OneApp 车联网生态中的虚拟形象核心服务模块，负责虚拟形象的渲染、动画处理、资源管理和交互控制等核心功能。该模块为车载虚拟助手提供底层的形象生成和控制能力。 + +### 基本信息 +- **模块名称**: clr_avatarcore +- **版本**: 0.4.0+2 +- **描述**: 虚拟形象核心服务SDK +- **Flutter 版本**: >=1.17.0 +- **Dart 版本**: >=2.16.2 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **形象渲染引擎** + - 3D虚拟形象渲染 + - 实时动画播放 + - 光照和材质处理 + - 表情和动作同步 + +2. **资源管理系统** + - 形象资源下载和缓存 + - 动画资源压缩和解压 + - 资源版本管理 + - 本地存储优化 + +3. **动画控制系统** + - 表情动画控制 + - 语音同步动画 + - 手势和动作驱动 + - 情绪表达映射 + +4. **交互处理** + - 语音输入响应 + - 触控交互处理 + - 环境感知适配 + - 智能行为生成 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── clr_avatarcore.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── rendering/ # 渲染引擎 +│ ├── animation/ # 动画系统 +│ ├── resources/ # 资源管理 +│ ├── interaction/ # 交互处理 +│ ├── models/ # 数据模型 +│ └── utils/ # 工具类 +├── assets/ # 资源文件 +└── native/ # 原生代码接口 +``` + +### 依赖关系 + +#### 核心依赖 +- `car_connector: ^0.4.11` - 车联网连接器 +- `basic_intl: ^0.2.0` - 国际化支持 +- `basic_logger: ^0.2.0` - 日志系统 + +#### 网络和存储 +- `dio: ^5.2.0` - HTTP客户端 +- `path_provider: ^2.0.11` - 文件路径 +- `shared_preferences: ^2.1.1` - 本地存储 +- `flutter_archive: ^5.0.0` - 文件压缩解压 + +#### 工具依赖 +- `crypto: ^3.0.3` - 加密功能 +- `fluttertoast: ^8.2.5` - 提示组件 +- `flutter_screenutil: ^5.9.0` - 屏幕适配 + +## 核心模块分析 + +### 1. 模块入口 (`clr_avatarcore.dart`) + +**功能职责**: +- 虚拟形象服务初始化 +- 渲染引擎启动 +- 资源管理系统配置 + +### 2. 渲染引擎 (`src/rendering/`) + +**功能职责**: +- 3D形象渲染管道 +- 实时画面生成 +- 性能优化控制 +- 渲染质量管理 + +**主要组件**: +- `RenderEngine` - 渲染引擎核心 +- `SceneManager` - 场景管理器 +- `MaterialProcessor` - 材质处理器 +- `LightingSystem` - 光照系统 +- `CameraController` - 摄像机控制器 + +### 3. 动画系统 (`src/animation/`) + +**功能职责**: +- 角色动画播放 +- 表情动画控制 +- 动作序列管理 +- 动画混合和过渡 + +**主要组件**: +- `AnimationController` - 动画控制器 +- `ExpressionManager` - 表情管理器 +- `MotionBlender` - 动作混合器 +- `Timeline` - 时间轴管理 +- `BehaviorTree` - 行为树系统 + +### 4. 资源管理 (`src/resources/`) + +**功能职责**: +- 形象资源下载 +- 文件缓存管理 +- 资源版本控制 +- 内存使用优化 + +**主要组件**: +- `ResourceManager` - 资源管理器 +- `DownloadManager` - 下载管理器 +- `CacheManager` - 缓存管理器 +- `AssetLoader` - 资源加载器 +- `VersionController` - 版本控制器 + +### 5. 交互处理 (`src/interaction/`) + +**功能职责**: +- 用户交互响应 +- 语音输入处理 +- 手势识别处理 +- 环境适应控制 + +**主要组件**: +- `InteractionHandler` - 交互处理器 +- `VoiceProcessor` - 语音处理器 +- `GestureRecognizer` - 手势识别器 +- `EmotionMapper` - 情绪映射器 +- `BehaviorGenerator` - 行为生成器 + +### 6. 数据模型 (`src/models/`) + +**功能职责**: +- 形象数据模型 +- 动画数据结构 +- 配置参数模型 +- 状态信息模型 + +**主要模型**: +- `AvatarModel` - 虚拟形象模型 +- `AnimationData` - 动画数据模型 +- `SceneConfig` - 场景配置模型 +- `InteractionState` - 交互状态模型 + +### 7. 工具类 (`src/utils/`) + +**功能职责**: +- 数学计算工具 +- 文件处理工具 +- 性能监控工具 +- 调试辅助工具 + +**主要工具**: +- `MathUtils` - 数学计算工具 +- `FileUtils` - 文件操作工具 +- `PerformanceMonitor` - 性能监控器 +- `DebugUtils` - 调试工具 + +## 业务流程 + +### 虚拟形象初始化流程 +```mermaid +graph TD + A[启动形象服务] --> B[检查本地资源] + B --> C{资源是否完整} + C -->|是| D[加载形象模型] + C -->|否| E[下载缺失资源] + E --> F[解压资源文件] + F --> G[验证资源完整性] + G --> H{验证是否通过} + H -->|是| D + H -->|否| I[重新下载资源] + I --> F + D --> J[初始化渲染引擎] + J --> K[加载动画数据] + K --> L[设置默认状态] + L --> M[启动交互监听] + M --> N[形象准备就绪] +``` + +### 动画播放流程 +```mermaid +graph TD + A[接收动画指令] --> B[解析动画类型] + B --> C[查找动画资源] + C --> D{资源是否存在} + D -->|是| E[加载动画数据] + D -->|否| F[下载动画资源] + F --> E + E --> G[计算动画参数] + G --> H[开始动画播放] + H --> I[实时渲染更新] + I --> J{动画是否结束} + J -->|否| I + J -->|是| K[恢复默认状态] + K --> L[释放动画资源] +``` + +## 渲染系统设计 + +### 渲染管道 +1. **几何处理阶段** + - 顶点变换 + - 骨骼动画 + - 形变处理 + - 裁剪优化 + +2. **光栅化阶段** + - 像素着色 + - 纹理映射 + - 光照计算 + - 阴影处理 + +3. **后处理阶段** + - 抗锯齿 + - 色彩校正 + - 特效合成 + - 输出优化 + +### 性能优化策略 +- **LOD系统**: 距离层次细节 +- **遮挡剔除**: 视锥体剔除 +- **批量渲染**: 减少绘制调用 +- **纹理压缩**: 内存使用优化 + +## 动画系统设计 + +### 动画类型 +1. **骨骼动画** + - 关节旋转控制 + - 骨骼层次结构 + - 动作混合 + - 逆向运动学 + +2. **表情动画** + - 面部肌肉控制 + - 表情混合 + - 实时表情捕捉 + - 情绪表达映射 + +3. **程序动画** + - 物理模拟 + - 粒子系统 + - 布料模拟 + - 头发动画 + +### 动画状态机 +- **状态定义**: 待机、说话、思考、响应 +- **状态转换**: 平滑过渡控制 +- **条件触发**: 基于输入的状态切换 +- **优先级管理**: 动画播放优先级 + +## 资源管理系统 + +### 资源类型 +1. **模型资源** + - 3D几何模型 + - 纹理贴图 + - 材质定义 + - 骨骼数据 + +2. **动画资源** + - 关键帧数据 + - 动作序列 + - 表情数据 + - 音频同步 + +3. **配置资源** + - 场景配置 + - 行为定义 + - 参数设置 + - 皮肤主题 + +### 缓存策略 +- **多级缓存**: 内存+磁盘缓存 +- **LRU算法**: 最近最少使用淘汰 +- **压缩存储**: 减少存储空间 +- **增量更新**: 仅更新变化部分 + +## 安全特性 + +### 数据安全 +- 资源文件加密存储 +- 传输数据加密 +- 数字签名验证 +- 防篡改检测 + +### 隐私保护 +- 本地数据保护 +- 用户行为数据脱敏 +- 敏感信息加密 +- 访问权限控制 + +## 性能优化 + +### 渲染优化 +- GPU资源管理 +- 绘制批次优化 +- 着色器缓存 +- 内存池管理 + +### 动画优化 +- 动画数据压缩 +- 关键帧插值优化 +- 动画LOD系统 +- 预计算优化 + +## 扩展性设计 + +### 插件化架构 +- 自定义渲染器 +- 扩展动画系统 +- 第三方资源集成 +- 自定义交互模式 + +### 配置化管理 +- 渲染质量可配置 +- 动画参数可调节 +- 资源策略可定制 +- 性能阈值可设置 + +## 测试策略 + +### 单元测试 +- 渲染算法测试 +- 动画逻辑测试 +- 资源管理测试 +- 数据模型测试 + +### 性能测试 +- 渲染性能测试 +- 内存使用测试 +- 电池续航测试 +- 热量控制测试 + +### 兼容性测试 +- 不同设备测试 +- 不同分辨率测试 +- 不同GPU测试 +- 系统版本兼容测试 + +## 部署和维护 + +### 资源部署 +- CDN资源分发 +- 区域化部署 +- 版本管理 +- 灰度发布 + +### 监控指标 +- 渲染帧率 +- 资源加载时间 +- 内存使用率 +- 崩溃率统计 + +## 总结 + +`clr_avatarcore` 模块作为 OneApp 的虚拟形象核心引擎，提供了完整的3D虚拟形象渲染和交互能力。通过高效的渲染管道、智能的动画系统和完善的资源管理，为用户提供了生动逼真的虚拟助手体验。模块具有良好的性能优化和扩展能力，能够适应不同硬件环境和业务需求。 diff --git a/app_car/clr_order.md b/app_car/clr_order.md new file mode 100644 index 0000000..a5690ce --- /dev/null +++ b/app_car/clr_order.md @@ -0,0 +1,704 @@ +# CLR Order - 订单服务 SDK + +## 模块概述 + +`clr_order` 是 OneApp 车辆订单管理的核心服务 SDK，提供了完整的订单生命周期管理功能。该模块封装了订单创建、支付、状态跟踪、取消退款等核心业务逻辑，为上层应用模块提供统一的订单服务接口。 + +## 核心功能 + +### 1. 订单管理 +- **订单创建**：支持多种类型订单的创建和初始化 +- **订单查询**：提供订单详情查询和列表获取功能 +- **订单更新**：支持订单状态和信息的实时更新 +- **订单取消**：处理订单取消和退款流程 + +### 2. 支付集成 +- **支付方式管理**：支持多种支付渠道的集成 +- **支付状态跟踪**：实时监控支付进度和结果 +- **退款处理**：自动化的退款流程处理 +- **支付安全**：确保支付过程的安全性和可靠性 + +### 3. 订单类型支持 +- **充电订单**：电动车充电服务订单 +- **维保订单**：车辆维护保养服务订单 +- **配件订单**：车辆配件和用品订单 +- **服务订单**：各类增值服务订单 + +## 技术架构 + +### 架构设计 +``` +┌─────────────────────────────────────┐ +│ 应用层 │ +│ (app_order, app_charging, etc.) │ +├─────────────────────────────────────┤ +│ CLR Order SDK │ +│ ┌─────────────┬─────────────────┐ │ +│ │ 订单管理 │ 支付服务 │ │ +│ ├─────────────┼─────────────────┤ │ +│ │ 状态机制 │ 安全认证 │ │ +│ └─────────────┴─────────────────┘ │ +├─────────────────────────────────────┤ +│ 网络层 │ +│ (RESTful API / GraphQL) │ +├─────────────────────────────────────┤ +│ 后端服务 │ +│ ┌─────────────┬─────────────────┐ │ +│ │ 订单服务 │ 支付网关 │ │ +│ └─────────────┴─────────────────┘ │ +└─────────────────────────────────────┘ +``` + +### 核心组件 + +#### 1. 订单管理器 (OrderFacade) +```dart +/// 订单服务接口 +abstract class IOrderFacade { + /// 创建订单 + Future> createOrder({ + required OrderCreateParams params, + }); + + /// 批量获取订单 + Future> fetchOrders({ + required int pageIndex, + required OrderQueryType orderQueryType, + int pageSize = 10, + OrderRefundQueryType? orderRefundQueryType, + }); + + /// 取消订单 + Future> cancelOrder(String orderId); + + /// 删除订单 + Future> delOrder(String orderId); + + /// 获取订单详情 + Future> fetchOrderDetail( + String orderId, { + bool realTimePull = false, + }); + + /// 获取退款详情 + Future> fetchRefundDetail(String orderId); + + /// 获取待支付的总数 + Future> fetchAllUnpaidNum(); + + /// 获取订单状态 + Future> fetchOrderStatus(String orderId); +} + +class OrderFacade implements IOrderFacade { + final OrderRemoteApi? remoteApi; + final String? environment; + + OrderFacade(this.remoteApi, this.environment) { + remoteApi ??= OrderRemoteApi(Impl()); + environment ??= defaultOption.environment; + OrderModuleConfig.setUp(environment ?? ''); + } + + @override + Future> createOrder({ + required OrderCreateParams params, + }) async { + try { + final orderDetail = await remoteApi!.createOrder(params: params); + return right(orderDetail); + } catch (e) { + return left(OrderError.createOrderError(obj: 'create order failed, $e')); + } + } + + // 其他方法实现... +} +``` + +#### 2. 发票门面 (InvoiceFacade) +```dart +/// 发票服务接口 +abstract class IInvoiceFacade { + /// 获取发票抬头详情 + Future> getInvoiceTitleDetails( + String titleId, + ); + + /// 新增/修改发票抬头 + Future> submitInvoiceTitleDetails( + InvoiceTitleDetailsDo invoiceTitleDetails, + ); + + /// 删除发票抬头 + Future> delInvoiceTitleDetails(String titleId); + + /// 获取发票抬头列表 + Future>> + getInvoiceTitleDetailsList(); + + /// 获取发票详情 + Future> getInvoiceDetails( + String invoiceId, + ); + + /// 获取发票历史列表 + Future>> getInvoiceList({ + required int pageIndex, + required int pageSize, + }); + + /// 申请开具发票 + Future> submitInvoice(InvoiceOptionsDo invoiceOptions); + + /// 获取可开发票的订单列表 + Future>> getNoOpenInvoiceOrderList({ + required int pageIndex, + required int pageSize, + }); +} +``` + +#### 3. 订单状态和类型枚举 +```dart +/// 订单状态枚举 +enum OrderStatus { + unpaid, // 未付款 + paid, // 已付款 + processing, // 处理中 + completed, // 已完成 + cancelled, // 已取消 + refunding, // 退款中 + refunded // 已退款 +} + +/// 订单查询类型 +enum OrderQueryType { + all, // 全部 + unpaid, // 待付款 + paid, // 已付款 + completed, // 已完成 + cancelled // 已取消 +} + +/// 订单退款查询类型 +enum OrderRefundQueryType { + refunding, // 退款中 + refunded, // 已退款 + refundFailed // 退款失败 +} +``` + +## 数据模型 + +### 订单模型 +```dart +/// 订单领域模型 +class Order { + /// 订单ID + final String id; + + /// 订单价格 + final double price; + + /// 订单标题 + final String title; + + /// 创建时间 + final DateTime createTime; + + /// 订单状态 + final OrderStatus status; + + /// 支付金额 + final double payAmount; + + /// 订单来源 + final OrderSource orderSource; + + /// 订单类型 + final OrderType orderType; + + /// 折扣金额 + final double discountAmount; + + /// 订单项总数量 + final int orderItemTotalQuantity; + + Order({ + required this.id, + required this.price, + required this.title, + required this.createTime, + required this.status, + required this.payAmount, + required this.orderSource, + required this.orderType, + required this.discountAmount, + required this.orderItemTotalQuantity, + }); + + /// 从DTO转换为DO + factory Order.fromDto(OrderDto dto) => Order( + id: dto.orderNo, + price: dto.orderAmount, + title: dto.title, + createTime: DateTime.fromMillisecondsSinceEpoch(dto.orderCreateTime), + status: OrderStatusEx.valueFromBackend(dto.orderState), + payAmount: dto.payAmount, + orderSource: OrderSourceEx.valueFromBackend(dto.orderSource), + orderType: OrderSourceTypeEx.valueFromBackend(dto.orderType), + discountAmount: dto.discountAmount, + orderItemTotalQuantity: dto.orderItemTotalQuantity, + ); +} + +/// 订单详情模型 +class OrderDetail { + final String id; + final double orderPrice; + final List products; + final DateTime createTime; + final OrderStatus status; + final double payAmount; + final OrderSource orderSource; + final OrderType orderType; + final double discountAmount; + final int orderItemTotalQuantity; + + // 构造方法和工厂方法... +} + +/// 产品模型 +class Product { + final String productId; + final String productName; + final String productImage; + final double price; + final int quantity; + + // 构造方法... +} +``` + +### 发票模型 +```dart +/// 发票详情模型 +class InvoiceDetailsDo { + final String invoiceId; + final String invoiceNumber; + final String invoiceTitle; + final double invoiceAmount; + final DateTime createTime; + final InvoiceStatus status; + final String downloadUrl; + + // 构造方法和工厂方法... +} + +/// 发票抬头模型 +class InvoiceTitleDetailsDo { + final String titleId; + final String invoiceTitle; + final InvoiceType invoiceType; + final String taxNumber; + final String address; + final String phone; + final String bankName; + final String bankAccount; + + // 构造方法和工厂方法... +} + +/// 发票选项模型 +class InvoiceOptionsDo { + final String orderId; + final String titleId; + final String invoiceType; + final String email; + + // 构造方法... +} + +/// 可开发票订单模型 +class NoOpenInvoiceOrderDo { + final String orderId; + final String orderTitle; + final double amount; + final DateTime createTime; + final bool canInvoice; + + // 构造方法... +} +``` + +## API 接口 + +### 订单接口 +```dart +/// 订单服务接口 +abstract class IOrderFacade { + /// 创建订单 + /// DSSOMOBILE-ONEAPP-ORDER-3001 + Future> createOrder({ + required OrderCreateParams params, + }); + + /// 批量获取订单 + /// DSSOMOBILE-ONEAPP-ORDER-3002 + Future> fetchOrders({ + required int pageIndex, + required OrderQueryType orderQueryType, + int pageSize = 10, + OrderRefundQueryType? orderRefundQueryType, + }); + + /// 获取订单详情 + /// DSSOMOBILE-ONEAPP-ORDER-3003 + Future> fetchOrderDetail( + String orderId, { + bool realTimePull = false, + }); + + /// 删除订单 + /// DSSOMOBILE-ONEAPP-ORDER-3004 + Future> delOrder(String orderId); + + /// 取消订单 + /// DSSOMOBILE-ONEAPP-ORDER-3005 + Future> cancelOrder(String orderId); + + /// 获取待支付订单数量 + /// DSSOMOBILE-ONEAPP-ORDER-3006 + Future> fetchAllUnpaidNum(); + + /// 获取订单状态 + /// DSSOMOBILE-ONEAPP-ORDER-3007 + Future> fetchOrderStatus(String orderId); + + /// 获取退款详情 + Future> fetchRefundDetail(String orderId); +} +``` + +### 发票接口 +```dart +/// 发票服务接口 +abstract class IInvoiceFacade { + /// 获取发票抬头详情 + Future> getInvoiceTitleDetails( + String titleId, + ); + + /// 新增/修改发票抬头 + Future> submitInvoiceTitleDetails( + InvoiceTitleDetailsDo invoiceTitleDetails, + ); + + /// 删除发票抬头 + Future> delInvoiceTitleDetails(String titleId); + + /// 获取发票抬头列表 + Future>> + getInvoiceTitleDetailsList(); + + /// 获取发票详情 + Future> getInvoiceDetails( + String invoiceId, + ); + + /// 获取发票历史列表 + Future>> getInvoiceList({ + required int pageIndex, + required int pageSize, + }); + + /// 申请开具发票 + Future> submitInvoice(InvoiceOptionsDo invoiceOptions); + + /// 获取可开发票的订单列表 + Future>> getNoOpenInvoiceOrderList({ + required int pageIndex, + required int pageSize, + }); +} +``` + +## 配置管理 + +### 环境配置 +```dart +class OrderConfig { + static const String baseUrl = String.fromEnvironment('ORDER_API_BASE_URL'); + static const String apiKey = String.fromEnvironment('ORDER_API_KEY'); + static const int timeoutSeconds = 30; + static const int maxRetries = 3; +} +``` + +### 支付配置 +```dart +class PaymentConfig { + static const Map providers = { + PaymentMethod.creditCard: PaymentProviderConfig( + provider: 'stripe', + publicKey: 'pk_live_...', + ), + PaymentMethod.digitalWallet: PaymentProviderConfig( + provider: 'alipay', + appId: 'app_...', + ), + }; +} +``` + +## 错误处理 + +### 订单错误类型 +```dart +enum OrderErrorType { + invalidRequest, // 无效请求 + orderNotFound, // 订单未找到 + paymentFailed, // 支付失败 + insufficientStock, // 库存不足 + orderExpired, // 订单过期 + unauthorized, // 未授权 + networkError, // 网络错误 + serverError // 服务器错误 +} + +class OrderException implements Exception { + final OrderErrorType type; + final String message; + final Map? details; + + const OrderException(this.type, this.message, [this.details]); +} +``` + +## 使用示例 + +### 创建订单 +```dart +final orderFacade = buildOrderFacadeImpl(); + +try { + final orderCreateParams = OrderCreateParams( + products: [ + OrderProduct( + productId: 'charging_session', + quantity: 1, + price: 25.0, + ), + ], + deliveryAddress: '北京市朝阳区...', + paymentMethod: 'alipay', + ); + + final result = await orderFacade.createOrder(params: orderCreateParams); + + result.fold( + (error) => print('订单创建失败: ${error.message}'), + (orderDetail) => print('订单创建成功: ${orderDetail.id}'), + ); +} catch (e) { + print('订单创建异常: $e'); +} +``` + +### 查询订单列表 +```dart +final orderFacade = buildOrderFacadeImpl(); + +try { + final result = await orderFacade.fetchOrders( + pageIndex: 1, + orderQueryType: OrderQueryType.all, + pageSize: 20, + ); + + result.fold( + (error) => print('查询订单失败: ${error.message}'), + (orderList) { + print('查询订单成功，共 ${orderList.orders.length} 条记录'); + for (final order in orderList.orders) { + print('订单: ${order.id} - ${order.title} - ${order.status}'); + } + }, + ); +} catch (e) { + print('查询订单异常: $e'); +} +``` + +### 获取订单详情 +```dart +final orderFacade = buildOrderFacadeImpl(); + +try { + final result = await orderFacade.fetchOrderDetail('order_123'); + + result.fold( + (error) => print('获取订单详情失败: ${error.message}'), + (orderDetail) { + print('订单详情获取成功:'); + print('订单ID: ${orderDetail.id}'); + print('订单状态: ${orderDetail.status}'); + print('订单金额: ${orderDetail.orderPrice}'); + print('产品列表: ${orderDetail.products.map((p) => p.productName).join(', ')}'); + }, + ); +} catch (e) { + print('获取订单详情异常: $e'); +} +``` + +## 测试策略 + +### 单元测试 +```dart +group('OrderManager Tests', () { + test('should create order successfully', () async { + // Given + final request = CreateOrderRequest(/* ... */); + + // When + final result = await orderManager.createOrder(request); + + // Then + expect(result.isSuccess, true); + expect(result.data.status, OrderStatus.created); + }); + + test('should handle payment failure', () async { + // Given + final request = PaymentRequest(/* invalid data */); + + // When & Then + expect( + () => paymentProcessor.initiatePayment(request), + throwsA(isA()), + ); + }); +}); +``` + +### 集成测试 +```dart +group('Order Integration Tests', () { + testWidgets('complete order flow', (tester) async { + // 1. 创建订单 + final order = await createTestOrder(); + + // 2. 处理支付 + final payment = await processTestPayment(order.id); + + // 3. 验证订单状态 + final updatedOrder = await getOrder(order.id); + expect(updatedOrder.status, OrderStatus.completed); + }); +}); +``` + +## 性能优化 + +### 缓存策略 +- **订单缓存**：本地缓存常用订单信息 +- **支付状态缓存**：缓存支付状态避免频繁查询 +- **配置缓存**：缓存支付配置和费率信息 + +### 网络优化 +- **请求合并**：合并多个订单查询请求 +- **分页加载**：大量订单数据分页获取 +- **压缩传输**：启用 gzip 压缩减少传输量 + +## 安全考虑 + +### 数据安全 +- **敏感信息加密**：支付信息和个人数据加密存储 +- **传输安全**：使用 HTTPS 和证书绑定 +- **访问控制**：基于角色的权限控制 + +### 支付安全 +- **PCI DSS 合规**：遵循支付卡行业数据安全标准 +- **令牌化**：敏感支付信息使用令牌替换 +- **风险控制**：实时风险评估和欺诈检测 + +## 监控和分析 + +### 业务指标 +- **订单转化率**：从创建到完成的转化率 +- **支付成功率**：支付处理的成功率 +- **平均订单价值**：订单金额统计分析 +- **退款率**：退款订单占比 + +### 技术指标 +- **API 响应时间**：接口性能监控 +- **错误率**：系统错误和异常监控 +- **可用性**：服务可用性监控 +- **吞吐量**：系统处理能力监控 + +## 版本历史 + +### v0.2.6+3 (当前版本) +- 新增加密货币支付支持 +- 优化订单状态机逻辑 +- 修复支付回调处理问题 +- 改进错误处理机制 + +### v0.2.5 +- 支持批量订单操作 +- 新增订单搜索功能 +- 优化支付流程 +- 修复已知 bug + +### v0.2.4 +- 支持多币种订单 +- 新增订单模板功能 +- 改进性能和稳定性 + +## 依赖关系 + +### 内部依赖 +- `basic_network`: 网络请求基础库 +- `basic_storage`: 本地存储服务 +- `basic_error`: 错误处理框架 +- `basic_track`: 埋点统计服务 + +### 外部依赖 +- `dio`: HTTP 客户端 +- `json_annotation`: JSON 序列化 +- `rxdart`: 响应式编程支持 + +## 部署说明 + +### 环境变量 +```bash +ORDER_API_BASE_URL=https://api.oneapp.com/order +ORDER_API_KEY=your_api_key_here +PAYMENT_PROVIDER_STRIPE_KEY=pk_live_... +PAYMENT_PROVIDER_ALIPAY_APP_ID=app_... +``` + +### 配置文件 +```yaml +order: + timeout: 30s + retry_count: 3 + cache_ttl: 300s + +payment: + providers: + - stripe + - alipay + - wechat_pay + security: + encryption: aes256 + signature: hmac_sha256 +``` + +## 总结 + +`clr_order` 作为订单服务的核心 SDK，提供了完整的订单生命周期管理能力。通过统一的接口设计、可靠的支付处理、完善的错误处理和安全保障，为 OneApp 的各个业务模块提供了稳定高效的订单服务支持。 + +该模块在设计上充分考虑了可扩展性、安全性和性能要求，能够很好地支撑车辆相关的各种订单业务场景，是 OneApp 电商和服务体系的重要基础设施。 diff --git a/app_car/clr_touchgo.md b/app_car/clr_touchgo.md new file mode 100644 index 0000000..f3d717f --- /dev/null +++ b/app_car/clr_touchgo.md @@ -0,0 +1,533 @@ +# CLR TouchGo - Touch&Go 服务 SDK + +## 模块概述 + +`clr_touchgo` 是 OneApp Touch&Go 智能交互功能的核心服务 SDK，提供了免接触式车辆操作和智能感知服务。该模块集成了先进的传感器技术、手势识别、语音控制等多种交互方式，为用户提供更便捷、更智能的车辆控制体验。 + +## 核心功能 + +### 1. 手势控制 +- **手势识别**：支持多种手势的实时识别和响应 +- **动作映射**：将手势动作映射到具体的车辆控制指令 +- **精度优化**：高精度的手势识别算法 +- **自定义手势**：支持用户自定义手势指令 + +### 2. 语音交互 +- **语音识别**：高精度的语音识别引擎 +- **语义理解**：智能理解用户意图和指令 +- **语音合成**：自然流畅的语音反馈 +- **多语言支持**：支持多种语言的语音交互 + +### 3. 智能感知 +- **环境感知**：感知车辆周围环境状态 +- **用户识别**：识别和认证授权用户 +- **行为预测**：基于历史数据预测用户行为 +- **场景适配**：根据不同场景自动调整交互方式 + +### 4. 免接触操作 +- **远程控制**：支持远距离的车辆控制 +- **自动执行**：基于条件自动执行预设操作 +- **安全验证**：多重安全验证确保操作安全 +- **实时反馈**：操作结果的实时反馈 + +## 技术架构 + +### 架构设计 +``` +┌─────────────────────────────────────┐ +│ 应用层 │ +│ (app_touchgo, app_car) │ +├─────────────────────────────────────┤ +│ CLR TouchGo SDK │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 手势识别 │ 语音控制 │ 智能感知 │ │ +│ ├──────────┼──────────┼──────────┤ │ +│ │ 传感器 │ AI引擎 │ 安全模块 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 硬件抽象层 │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 摄像头 │ 麦克风 │ 距离传感 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 车载系统 │ +│ (CAN Bus, ECU, etc.) │ +└─────────────────────────────────────┘ +``` + +### 核心组件 + +#### 1. 手势识别引擎 (GestureEngine) +```dart +class GestureEngine { + // 初始化手势识别 + Future initialize(); + + // 开始手势检测 + Future startDetection(); + + // 停止手势检测 + Future stopDetection(); + + // 注册手势处理器 + void registerGestureHandler(GestureType type, GestureHandler handler); + + // 校准手势识别 + Future calibrateGesture(GestureType type); +} +``` + +#### 2. 语音控制引擎 (VoiceEngine) +```dart +class VoiceEngine { + // 初始化语音引擎 + Future initialize(VoiceConfig config); + + // 开始语音监听 + Future startListening(); + + // 停止语音监听 + Future stopListening(); + + // 语音合成 + Future speak(String text, VoiceSettings settings); + + // 设置语音识别语言 + Future setLanguage(String languageCode); +} +``` + +#### 3. 智能感知管理器 (SensingManager) +```dart +class SensingManager { + // 开始环境感知 + Future startEnvironmentSensing(); + + // 用户身份识别 + Future identifyUser(); + + // 获取环境状态 + Future getEnvironmentState(); + + // 预测用户行为 + Future> predictUserActions(); +} +``` + +#### 4. 安全验证模块 (SecurityModule) +```dart +class SecurityModule { + // 生物特征验证 + Future verifyBiometrics(BiometricData data); + + // 多因子认证 + Future multiFactorAuth(List factors); + + // 操作权限检查 + Future checkPermission(String userId, Operation operation); + + // 安全日志记录 + Future logSecurityEvent(SecurityEvent event); +} +``` + +## 数据模型 + +### 手势模型 +```dart +enum GestureType { + swipeLeft, // 左滑 + swipeRight, // 右滑 + swipeUp, // 上滑 + swipeDown, // 下滑 + pinch, // 捏合 + spread, // 展开 + tap, // 点击 + longPress, // 长按 + circle, // 画圈 + custom // 自定义 +} + +class Gesture { + final GestureType type; + final List trajectory; + final double confidence; + final DateTime timestamp; + final Map metadata; +} +``` + +### 语音模型 +```dart +class VoiceCommand { + final String text; + final String intent; + final Map entities; + final double confidence; + final String languageCode; + final DateTime timestamp; +} + +class VoiceResponse { + final String text; + final VoiceSettings settings; + final Duration duration; + final AudioFormat format; +} +``` + +### 感知模型 +```dart +class EnvironmentState { + final double lighting; + final double noise; + final double temperature; + final List objects; + final List persons; + final DateTime timestamp; +} + +class UserIdentity { + final String userId; + final String name; + final double confidence; + final BiometricData biometrics; + final List permissions; +} +``` + +## API 接口 + +### 手势控制接口 +```dart +abstract class GestureService { + // 配置手势识别 + Future> configureGesture(GestureConfig config); + + // 执行手势指令 + Future> executeGestureCommand(GestureCommand command); + + // 获取支持的手势列表 + Future>> getSupportedGestures(); + + // 训练自定义手势 + Future> trainCustomGesture(CustomGestureData data); +} +``` + +### 语音控制接口 +```dart +abstract class VoiceService { + // 处理语音指令 + Future> processVoiceCommand(VoiceCommand command); + + // 获取语音配置 + Future> getVoiceConfig(); + + // 更新语音设置 + Future> updateVoiceSettings(VoiceSettings settings); + + // 获取支持的语言 + Future>> getSupportedLanguages(); +} +``` + +### 智能感知接口 +```dart +abstract class SensingService { + // 获取环境状态 + Future> getEnvironmentState(); + + // 识别用户身份 + Future> identifyUser(BiometricData data); + + // 获取行为预测 + Future>> getPredictedActions(String userId); + + // 更新感知配置 + Future> updateSensingConfig(SensingConfig config); +} +``` + +## 配置管理 + +### 手势配置 +```dart +class GestureConfig { + final double sensitivity; + final double timeoutMs; + final bool enableCustomGestures; + final Map gestureSettings; + + static const GestureConfig defaultConfig = GestureConfig( + sensitivity: 0.8, + timeoutMs: 3000, + enableCustomGestures: true, + gestureSettings: { + GestureType.swipeLeft: GestureSettings(threshold: 50.0), + GestureType.swipeRight: GestureSettings(threshold: 50.0), + // ... other gestures + }, + ); +} +``` + +### 语音配置 +```dart +class VoiceConfig { + final String languageCode; + final double noiseReduction; + final bool continuousListening; + final VoiceModel model; + final Map customSettings; + + static const VoiceConfig defaultConfig = VoiceConfig( + languageCode: 'zh-CN', + noiseReduction: 0.7, + continuousListening: false, + model: VoiceModel.enhanced, + customSettings: {}, + ); +} +``` + +## 算法和模型 + +### 手势识别算法 +```dart +class GestureRecognitionAlgorithm { + // 特征提取 + List extractFeatures(List trajectory); + + // 模式匹配 + GestureMatch matchPattern(List features); + + // 置信度计算 + double calculateConfidence(GestureMatch match); + + // 模型训练 + Future trainModel(List data); +} +``` + +### 语音识别模型 +```dart +class VoiceRecognitionModel { + // 音频预处理 + AudioFeatures preprocessAudio(AudioData audio); + + // 语音转文本 + String speechToText(AudioFeatures features); + + // 意图识别 + Intent recognizeIntent(String text); + + // 实体抽取 + Map extractEntities(String text); +} +``` + +## 使用示例 + +### 手势控制示例 +```dart +// 初始化手势引擎 +final gestureEngine = GestureEngine.instance; +await gestureEngine.initialize(); + +// 注册手势处理器 +gestureEngine.registerGestureHandler( + GestureType.swipeLeft, + (gesture) async { + // 执行左滑操作：打开车门 + await CarController.instance.openDoor(DoorPosition.driver); + }, +); + +// 开始手势检测 +await gestureEngine.startDetection(); +``` + +### 语音控制示例 +```dart +// 初始化语音引擎 +final voiceEngine = VoiceEngine.instance; +await voiceEngine.initialize(VoiceConfig.defaultConfig); + +// 设置语音指令处理器 +voiceEngine.onVoiceCommand.listen((command) async { + switch (command.intent) { + case 'start_engine': + await CarController.instance.startEngine(); + await voiceEngine.speak('引擎已启动'); + break; + case 'open_window': + await CarController.instance.openWindow(); + await voiceEngine.speak('车窗已打开'); + break; + } +}); + +// 开始语音监听 +await voiceEngine.startListening(); +``` + +### 智能感知示例 +```dart +// 初始化感知管理器 +final sensingManager = SensingManager.instance; + +// 开始环境感知 +await sensingManager.startEnvironmentSensing(); + +// 监听用户接近事件 +sensingManager.onUserApproaching.listen((user) async { + // 用户接近时自动解锁车辆 + if (user.isAuthorized) { + await CarController.instance.unlockVehicle(); + + // 根据用户偏好调整车内环境 + final preferences = await getUserPreferences(user.id); + await CarController.instance.applyPreferences(preferences); + } +}); +``` + +## 测试策略 + +### 单元测试 +```dart +group('GestureEngine Tests', () { + test('should recognize swipe left gesture', () async { + // Given + final trajectory = [ + Point(100, 50), + Point(80, 50), + Point(60, 50), + Point(40, 50), + Point(20, 50), + ]; + + // When + final gesture = await gestureEngine.recognizeGesture(trajectory); + + // Then + expect(gesture.type, GestureType.swipeLeft); + expect(gesture.confidence, greaterThan(0.8)); + }); +}); +``` + +### 集成测试 +```dart +group('TouchGo Integration Tests', () { + testWidgets('complete gesture control flow', (tester) async { + // 1. 初始化系统 + await TouchGoService.initialize(); + + // 2. 模拟手势输入 + await tester.simulateGesture(GestureType.swipeLeft); + + // 3. 验证车辆响应 + verify(mockCarController.openDoor(DoorPosition.driver)); + }); +}); +``` + +## 性能优化 + +### 算法优化 +- **特征缓存**：缓存常用的特征计算结果 +- **模型压缩**：使用轻量级的识别模型 +- **并行处理**：多线程处理音视频数据 +- **增量学习**：在线学习优化识别精度 + +### 资源管理 +- **内存管理**：及时释放不需要的音视频数据 +- **CPU调度**：智能调度 AI 计算任务 +- **电池优化**：根据电量自动调整功能 +- **热量控制**：防止长时间运行过热 + +## 安全和隐私 + +### 数据安全 +- **本地处理**：敏感数据本地处理，不上传云端 +- **数据加密**：生物特征数据加密存储 +- **访问控制**：严格的权限控制机制 +- **审计日志**：完整的操作审计记录 + +### 隐私保护 +- **数据最小化**：只收集必要的数据 +- **用户授权**：明确的用户授权机制 +- **数据销毁**：及时删除过期数据 +- **匿名化**：敏感数据匿名化处理 + +## 监控和诊断 + +### 性能监控 +- **识别精度**：手势和语音识别的准确率 +- **响应时间**：从输入到执行的延迟 +- **资源使用**：CPU、内存、电池使用情况 +- **错误率**：系统错误和异常统计 + +### 用户体验监控 +- **使用频率**：各功能的使用频率统计 +- **用户满意度**：用户反馈和评分 +- **学习效果**：个性化学习的改进效果 +- **场景适配**：不同场景下的表现 + +## 版本历史 + +### v0.2.6+7 (当前版本) +- 新增多语言语音支持 +- 优化手势识别算法 +- 改进低光环境下的识别能力 +- 修复已知稳定性问题 + +### v0.2.5 +- 支持自定义手势训练 +- 新增语音情感识别 +- 优化电池使用效率 +- 改进安全验证流程 + +### v0.2.4 +- 支持离线语音识别 +- 新增环境自适应功能 +- 优化识别精度 +- 修复兼容性问题 + +## 依赖关系 + +### 内部依赖 +- `basic_platform`: 平台抽象层 +- `basic_error`: 错误处理框架 +- `basic_storage`: 本地存储服务 +- `kit_native_uikit`: 原生 UI 组件 + +### 外部依赖 +- `camera`: 摄像头访问 +- `microphone`: 麦克风访问 +- `sensors_plus`: 传感器数据 +- `tflite_flutter`: TensorFlow Lite 模型 + +## 硬件要求 + +### 最低要求 +- **摄像头**: 前置摄像头，分辨率 ≥ 720p +- **麦克风**: 数字麦克风，降噪支持 +- **处理器**: ARM64 架构，≥ 1.5GHz +- **内存**: ≥ 2GB RAM +- **存储**: ≥ 500MB 可用空间 + +### 推荐配置 +- **摄像头**: 1080p 前置摄像头，红外夜视 +- **麦克风**: 阵列麦克风，回声消除 +- **处理器**: ≥ 2.0GHz 多核处理器 +- **内存**: ≥ 4GB RAM +- **传感器**: 距离传感器、环境光传感器 + +## 总结 + +`clr_touchgo` 作为 Touch&Go 智能交互的核心 SDK，通过集成先进的 AI 技术和传感器融合，为用户提供了自然、便捷、安全的车辆交互体验。该模块不仅支持传统的手势和语音控制，还具备智能感知和预测能力，能够主动为用户提供个性化的服务。 + +通过持续的算法优化和用户体验改进，TouchGo 技术将继续引领车辆智能交互的发展方向，为 OneApp 用户带来更加智能化的出行体验。 diff --git a/app_car/clr_wallbox.md b/app_car/clr_wallbox.md new file mode 100644 index 0000000..d556cb5 --- /dev/null +++ b/app_car/clr_wallbox.md @@ -0,0 +1,364 @@ +# CLR Wallbox 充电墙盒服务SDK + +## 模块概述 + +`clr_wallbox` 是 OneApp 车联网生态中的充电墙盒服务SDK，负责充电墙盒设备的通信协议、数据处理、状态管理和业务逻辑封装等功能。该模块为充电墙盒应用提供底层的设备控制和数据服务能力。 + +### 基本信息 +- **模块名称**: clr_wallbox +- **版本**: 0.2.14 +- **描述**: 充电墙盒服务SDK +- **Flutter 版本**: >=2.10.5 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **设备通信协议** + - OCPP协议支持 + - Modbus通信协议 + - WebSocket实时通信 + - HTTP RESTful API + +2. **数据处理服务** + - 充电数据解析 + - 设备状态处理 + - 配置参数管理 + - 历史数据存储 + +3. **业务逻辑封装** + - 充电会话管理 + - 计费逻辑处理 + - 安全验证机制 + - 异常处理流程 + +4. **状态监控系统** + - 实时状态监控 + - 健康状态检查 + - 异常告警处理 + - 性能指标统计 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── clr_wallbox.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── protocols/ # 通信协议 +│ ├── services/ # 业务服务 +│ ├── models/ # 数据模型 +│ ├── repositories/ # 数据仓库 +│ ├── processors/ # 数据处理器 +│ └── utils/ # 工具类 +├── test/ # 测试文件 +└── generated/ # 代码生成文件 +``` + +### 依赖关系 + +#### 核心框架依赖 +- `basic_modular: ^0.2.3` - 模块化框架 +- `basic_network: ^0.2.3+4` - 网络通信框架 +- `basic_storage: ^0.2.2` - 本地存储框架 +- `basic_track: ^0.1.3` - 数据埋点 + +#### 工具依赖 +- `json_annotation: ^4.6.0` - JSON序列化 +- `dartz: ^0.10.1` - 函数式编程 +- `freezed_annotation: ^2.0.3` - 数据类注解 +- `path_provider: ^2.1.3` - 文件路径 +- `charset_converter: ^2.1.1` - 字符编码转换 + +## 核心模块分析 + +### 1. 模块入口 (`clr_wallbox.dart`) + +**功能职责**: +- SDK对外接口导出 +- 服务初始化配置 +- 依赖注入管理 + +### 2. 通信协议 (`src/protocols/`) + +**功能职责**: +- 充电设备通信协议实现 +- 消息编码解码处理 +- 协议版本管理 +- 连接状态维护 + +**主要协议**: +- `OCPPProtocol` - OCPP充电协议 +- `ModbusProtocol` - Modbus工业协议 +- `WebSocketProtocol` - WebSocket实时协议 +- `HTTPProtocol` - HTTP REST协议 + +**协议特性**: +- **OCPP 1.6/2.0**: 开放充电点协议 +- **Modbus RTU/TCP**: 工业标准协议 +- **自定义协议**: 厂商特定协议 +- **协议适配**: 多协议统一接口 + +### 3. 业务服务 (`src/services/`) + +**功能职责**: +- 充电业务逻辑封装 +- 设备管理服务 +- 用户认证服务 +- 计费结算服务 + +**主要服务**: +- `ChargingService` - 充电服务 +- `DeviceService` - 设备服务 +- `AuthService` - 认证服务 +- `BillingService` - 计费服务 +- `MonitoringService` - 监控服务 + +### 4. 数据模型 (`src/models/`) + +**功能职责**: +- 充电设备数据模型 +- 协议消息模型 +- 业务实体模型 +- 配置参数模型 + +**主要模型**: +- `WallboxDevice` - 墙盒设备模型 +- `ChargingSession` - 充电会话模型 +- `OCPPMessage` - OCPP消息模型 +- `DeviceStatus` - 设备状态模型 +- `ChargingConfig` - 充电配置模型 + +### 5. 数据仓库 (`src/repositories/`) + +**功能职责**: +- 设备数据持久化 +- 充电记录存储 +- 配置信息管理 +- 缓存数据处理 + +**主要仓库**: +- `DeviceRepository` - 设备数据仓库 +- `SessionRepository` - 会话数据仓库 +- `ConfigRepository` - 配置数据仓库 +- `LogRepository` - 日志数据仓库 + +### 6. 数据处理器 (`src/processors/`) + +**功能职责**: +- 协议数据解析 +- 业务数据转换 +- 状态数据处理 +- 异常数据过滤 + +**主要处理器**: +- `MessageProcessor` - 消息处理器 +- `StatusProcessor` - 状态处理器 +- `DataConverter` - 数据转换器 +- `ExceptionHandler` - 异常处理器 + +### 7. 工具类 (`src/utils/`) + +**功能职责**: +- 协议工具方法 +- 数据验证工具 +- 加密解密工具 +- 时间处理工具 + +**主要工具**: +- `ProtocolUtils` - 协议工具 +- `CryptoUtils` - 加密工具 +- `ValidationUtils` - 验证工具 +- `TimeUtils` - 时间工具 + +## 业务流程 + +### 充电启动流程 +```mermaid +graph TD + A[用户请求充电] --> B[设备状态检查] + B --> C{设备是否可用} + C -->|否| D[返回设备不可用] + C -->|是| E[用户身份验证] + E --> F{验证是否通过} + F -->|否| G[返回认证失败] + F -->|是| H[发送充电启动指令] + H --> I[设备响应处理] + I --> J{启动是否成功} + J -->|是| K[创建充电会话] + J -->|否| L[返回启动失败] + K --> M[开始充电监控] + M --> N[记录充电数据] + N --> O[更新充电状态] + O --> P{充电是否完成} + P -->|否| N + P -->|是| Q[结束充电会话] + Q --> R[生成充电报告] +``` + +### OCPP消息处理流程 +```mermaid +graph TD + A[接收OCPP消息] --> B[消息格式验证] + B --> C{格式是否正确} + C -->|否| D[返回格式错误] + C -->|是| E[解析消息内容] + E --> F[识别消息类型] + F --> G[路由到对应处理器] + G --> H[执行业务逻辑] + H --> I[生成响应消息] + I --> J[序列化响应] + J --> K[发送响应消息] + K --> L[记录处理日志] +``` + +## OCPP协议设计 + +### 消息类型 +1. **核心消息** + - `Authorize` - 授权验证 + - `StartTransaction` - 开始充电 + - `StopTransaction` - 停止充电 + - `Heartbeat` - 心跳消息 + +2. **状态消息** + - `StatusNotification` - 状态通知 + - `MeterValues` - 电表数值 + - `BootNotification` - 启动通知 + - `DataTransfer` - 数据传输 + +3. **配置消息** + - `ChangeConfiguration` - 修改配置 + - `GetConfiguration` - 获取配置 + - `Reset` - 重置设备 + - `UnlockConnector` - 解锁连接器 + +### 消息结构 +```json +{ + "messageTypeId": 2, + "uniqueId": "19223201", + "action": "Heartbeat", + "payload": {} +} +``` + +## 数据存储设计 + +### 本地存储 +1. **设备配置** + - 设备基本信息 + - 通信参数 + - 充电参数 + - 安全配置 + +2. **充电记录** + - 充电会话数据 + - 电量消耗记录 + - 时间戳信息 + - 用户信息 + +3. **状态数据** + - 设备当前状态 + - 错误信息 + - 性能指标 + - 诊断数据 + +### 数据同步 +- **增量同步**: 仅同步变化数据 +- **全量同步**: 定期全量同步 +- **冲突解决**: 数据冲突处理策略 +- **版本控制**: 数据版本管理 + +## 安全机制 + +### 通信安全 +- **TLS加密**: 传输层安全 +- **证书验证**: 设备身份验证 +- **消息签名**: 消息完整性验证 +- **防重放**: 防止重放攻击 + +### 数据安全 +- **敏感数据加密**: 本地数据加密 +- **访问控制**: 数据访问权限 +- **审计日志**: 操作审计记录 +- **安全擦除**: 数据安全删除 + +## 性能优化 + +### 通信优化 +- **连接池**: 复用网络连接 +- **消息批处理**: 批量处理消息 +- **压缩传输**: 数据压缩传输 +- **异步处理**: 非阻塞消息处理 + +### 存储优化 +- **数据压缩**: 存储空间优化 +- **索引优化**: 查询性能优化 +- **缓存策略**: 热点数据缓存 +- **清理机制**: 过期数据清理 + +## 错误处理 + +### 错误分类 +1. **通信错误** + - 网络连接失败 + - 协议解析错误 + - 超时错误 + - 服务不可用 + +2. **业务错误** + - 认证失败 + - 参数无效 + - 状态冲突 + - 资源不足 + +3. **系统错误** + - 内存不足 + - 存储空间不够 + - 系统异常 + - 硬件故障 + +### 处理策略 +- **重试机制**: 自动重试失败操作 +- **降级处理**: 服务降级策略 +- **补偿机制**: 事务补偿处理 +- **告警通知**: 异常情况告警 + +## 测试策略 + +### 单元测试 +- **协议解析测试**: 消息编解码 +- **业务逻辑测试**: 充电流程 +- **数据模型测试**: 序列化反序列化 +- **工具类测试**: 工具方法功能 + +### 集成测试 +- **协议集成测试**: 设备通信 +- **数据库集成测试**: 数据持久化 +- **服务集成测试**: 端到端流程 +- **第三方集成测试**: 外部系统 + +### 兼容性测试 +- **设备兼容性**: 不同厂商设备 +- **协议版本**: OCPP不同版本 +- **网络环境**: 不同网络条件 +- **并发测试**: 多设备并发 + +## 部署和维护 + +### 配置管理 +- **环境配置**: 开发、测试、生产 +- **协议配置**: 协议参数设置 +- **安全配置**: 证书和密钥管理 +- **性能配置**: 性能调优参数 + +### 监控指标 +- **设备在线率**: 设备连接状态 +- **消息处理量**: 消息吞吐量 +- **错误率**: 错误发生频率 +- **响应时间**: 消息处理延迟 + +## 总结 + +`clr_wallbox` 模块作为 OneApp 的充电墙盒服务SDK，提供了完整的充电设备通信和管理能力。通过标准化的协议支持、稳定的数据处理和完善的安全机制，为充电基础设施的数字化管理提供了可靠的技术支撑。模块具有良好的扩展性和兼容性，能够适应不同厂商的充电设备和多样化的部署环境。 diff --git a/app_car/kit_rpa_plugin.md b/app_car/kit_rpa_plugin.md new file mode 100644 index 0000000..89fff4d --- /dev/null +++ b/app_car/kit_rpa_plugin.md @@ -0,0 +1,391 @@ +# Kit RPA Plugin RPA自动化插件 + +## 模块概述 + +`kit_rpa_plugin` 是 OneApp 车联网生态中的 RPA（Robotic Process Automation）原生插件，负责为 Flutter 应用提供原生平台的自动化操作能力。该插件通过平台通道实现 Flutter 与 Android/iOS 原生代码的交互，为 RPA 自动化任务提供底层支持。 + +### 基本信息 +- **模块名称**: kit_rpa_plugin +- **版本**: 0.1.8+1 +- **类型**: Flutter Plugin（原生插件） +- **Flutter 版本**: >=2.10.5 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **原生自动化操作** + - 屏幕点击模拟 + - 键盘输入模拟 + - 手势操作模拟 + - 应用启动控制 + +2. **系统信息获取** + - 设备信息查询 + - 应用状态监控 + - 系统资源获取 + - 权限状态检查 + +3. **文件系统操作** + - 文件读写操作 + - 目录遍历 + - 权限管理 + - 路径解析 + +4. **网络状态监控** + - 网络连接状态 + - 网络类型检测 + - 流量使用统计 + - 连接质量评估 + +## 技术架构 + +### 目录结构 +``` +kit_rpa_plugin/ +├── lib/ # Dart代码 +│ ├── kit_rpa_plugin.dart # 插件入口 +│ ├── src/ # 源代码 +│ │ ├── platform_interface.dart # 平台接口定义 +│ │ ├── method_channel.dart # 方法通道实现 +│ │ └── models/ # 数据模型 +│ └── kit_rpa_plugin_platform_interface.dart +├── android/ # Android原生代码 +│ ├── src/main/kotlin/ +│ │ └── com/oneapp/kit_rpa_plugin/ +│ │ ├── KitRpaPlugin.kt # 主插件类 +│ │ ├── AutomationHandler.kt # 自动化处理器 +│ │ ├── SystemInfoProvider.kt # 系统信息提供者 +│ │ └── FileOperationHandler.kt # 文件操作处理器 +│ └── build.gradle +├── ios/ # iOS原生代码 +│ ├── Classes/ +│ │ ├── KitRpaPlugin.swift # 主插件类 +│ │ ├── AutomationHandler.swift # 自动化处理器 +│ │ ├── SystemInfoProvider.swift # 系统信息提供者 +│ │ └── FileOperationHandler.swift # 文件操作处理器 +│ └── kit_rpa_plugin.podspec +├── example/ # 示例应用 +└── test/ # 测试文件 +``` + +### 依赖关系 + +#### 核心依赖 +- `plugin_platform_interface: ^2.0.2` - 插件平台接口 +- `device_info_plus: ^9.1.1` - 设备信息获取 + +## 核心模块分析 + +### 1. Flutter端实现 + +#### 插件入口 (`lib/kit_rpa_plugin.dart`) +**功能职责**: +- 插件对外API导出 +- 平台通道初始化 +- 方法调用封装 + +#### 平台接口 (`lib/src/platform_interface.dart`) +**功能职责**: +- 定义插件抽象接口 +- 规范方法签名 +- 支持多平台实现 + +#### 方法通道 (`lib/src/method_channel.dart`) +**功能职责**: +- 实现平台通道通信 +- 处理异步方法调用 +- 管理回调和异常 + +### 2. Android端实现 + +#### 主插件类 (`KitRpaPlugin.kt`) +```kotlin +class KitRpaPlugin: FlutterPlugin, MethodCallHandler { + private lateinit var channel: MethodChannel + private lateinit var context: Context + private lateinit var automationHandler: AutomationHandler + private lateinit var systemInfoProvider: SystemInfoProvider + private lateinit var fileOperationHandler: FileOperationHandler + + override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) { + channel = MethodChannel(binding.binaryMessenger, "kit_rpa_plugin") + context = binding.applicationContext + initializeHandlers() + channel.setMethodCallHandler(this) + } + + override fun onMethodCall(call: MethodCall, result: Result) { + when (call.method) { + "simulateClick" -> automationHandler.simulateClick(call, result) + "getSystemInfo" -> systemInfoProvider.getSystemInfo(call, result) + "performFileOperation" -> fileOperationHandler.performOperation(call, result) + else -> result.notImplemented() + } + } +} +``` + +#### 自动化处理器 (`AutomationHandler.kt`) +**功能职责**: +- 屏幕点击模拟 +- 键盘输入模拟 +- 手势操作模拟 +- 无障碍服务集成 + +**主要方法**: +- `simulateClick(x: Float, y: Float)` - 模拟屏幕点击 +- `simulateKeyInput(text: String)` - 模拟键盘输入 +- `simulateSwipe(startX: Float, startY: Float, endX: Float, endY: Float)` - 模拟滑动 +- `simulateLongPress(x: Float, y: Float, duration: Long)` - 模拟长按 + +#### 系统信息提供者 (`SystemInfoProvider.kt`) +**功能职责**: +- 设备硬件信息获取 +- 系统版本信息 +- 应用状态监控 +- 权限状态检查 + +**主要方法**: +- `getDeviceInfo()` - 获取设备信息 +- `getSystemVersion()` - 获取系统版本 +- `getInstalledApps()` - 获取已安装应用 +- `checkPermissions()` - 检查权限状态 + +#### 文件操作处理器 (`FileOperationHandler.kt`) +**功能职责**: +- 文件系统访问 +- 文件读写操作 +- 目录管理 +- 存储权限处理 + +**主要方法**: +- `readFile(path: String)` - 读取文件 +- `writeFile(path: String, content: String)` - 写入文件 +- `listDirectory(path: String)` - 列出目录内容 +- `createDirectory(path: String)` - 创建目录 + +### 3. iOS端实现 + +#### 主插件类 (`KitRpaPlugin.swift`) +```swift +public class KitRpaPlugin: NSObject, FlutterPlugin { + private var automationHandler: AutomationHandler! + private var systemInfoProvider: SystemInfoProvider! + private var fileOperationHandler: FileOperationHandler! + + public static func register(with registrar: FlutterPluginRegistrar) { + let channel = FlutterMethodChannel(name: "kit_rpa_plugin", + binaryMessenger: registrar.messenger()) + let instance = KitRpaPlugin() + instance.initializeHandlers() + registrar.addMethodCallDelegate(instance, channel: channel) + } + + public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) { + switch call.method { + case "simulateClick": + automationHandler.simulateClick(call: call, result: result) + case "getSystemInfo": + systemInfoProvider.getSystemInfo(call: call, result: result) + case "performFileOperation": + fileOperationHandler.performOperation(call: call, result: result) + default: + result(FlutterMethodNotImplemented) + } + } +} +``` + +#### 自动化处理器 (`AutomationHandler.swift`) +**功能职责**: +- 利用 UIKit 进行界面操作 +- 集成 Accessibility 框架 +- 手势识别和模拟 +- 应用控制操作 + +#### 系统信息提供者 (`SystemInfoProvider.swift`) +**功能职责**: +- 利用 UIDevice 获取设备信息 +- 系统版本和硬件信息 +- 应用状态监控 +- 权限状态查询 + +#### 文件操作处理器 (`FileOperationHandler.swift`) +**功能职责**: +- 文件系统访问 +- 沙盒目录操作 +- 文档目录管理 +- 安全文件操作 + +## 业务流程 + +### 自动化操作流程 +```mermaid +graph TD + A[Flutter发起自动化请求] --> B[方法通道传递参数] + B --> C[原生端接收调用] + C --> D{判断操作类型} + D -->|点击操作| E[屏幕点击处理] + D -->|输入操作| F[键盘输入处理] + D -->|手势操作| G[手势模拟处理] + E --> H[执行原生操作] + F --> H + G --> H + H --> I{操作是否成功} + I -->|是| J[返回成功结果] + I -->|否| K[返回错误信息] + J --> L[Flutter端接收结果] + K --> L + L --> M[更新UI状态] +``` + +### 权限检查流程 +```mermaid +graph TD + A[检查操作权限] --> B{是否需要特殊权限} + B -->|否| C[直接执行操作] + B -->|是| D[检查权限状态] + D --> E{权限是否已授予} + E -->|是| C + E -->|否| F[请求用户授权] + F --> G{用户是否同意} + G -->|是| H[获得权限] + G -->|否| I[权限被拒绝] + H --> C + I --> J[返回权限错误] + C --> K[执行自动化操作] +``` + +## 平台特性实现 + +### Android特性 +1. **无障碍服务(Accessibility Service)** + - 应用界面元素访问 + - 自动化操作执行 + - 界面变化监听 + - 全局手势模拟 + +2. **系统权限管理** + - 动态权限申请 + - 特殊权限处理 + - 权限状态监控 + - 权限组管理 + +3. **文件系统访问** + - 外部存储访问 + - 应用私有目录 + - 分区存储适配 + - 文件提供者集成 + +### iOS特性 +1. **Accessibility框架** + - UI元素识别 + - 辅助功能集成 + - 自动化测试支持 + - 界面操作模拟 + +2. **沙盒安全机制** + - 应用沙盒限制 + - 文件访问权限 + - 数据保护机制 + - 隐私权限管理 + +3. **系统集成** + - UIKit框架集成 + - Core Foundation使用 + - 系统服务调用 + - 设备信息获取 + +## 安全考虑 + +### 权限控制 +- **最小权限原则**: 仅申请必要权限 +- **动态权限**: 运行时权限申请 +- **权限说明**: 清晰的权限使用说明 +- **权限回收**: 不需要时释放权限 + +### 数据安全 +- **敏感数据保护**: 避免记录敏感信息 +- **数据传输安全**: 加密敏感数据传输 +- **本地存储安全**: 安全的本地数据存储 +- **隐私合规**: 遵守隐私保护法规 + +## 性能优化 + +### 操作效率 +- **批量操作**: 减少方法通道调用次数 +- **异步处理**: 避免阻塞主线程 +- **操作缓存**: 缓存重复操作结果 +- **资源复用**: 复用系统资源 + +### 内存管理 +- **及时释放**: 及时释放不需要的资源 +- **内存监控**: 监控内存使用情况 +- **垃圾回收**: 配合系统垃圾回收 +- **循环引用避免**: 避免内存泄漏 + +## 错误处理 + +### 异常类型 +1. **权限异常** + - 权限未授予 + - 权限被撤销 + - 系统权限限制 + - 特殊权限要求 + +2. **操作异常** + - 目标元素不存在 + - 操作被系统阻止 + - 界面状态异常 + - 硬件功能不支持 + +3. **系统异常** + - 系统版本不兼容 + - 硬件功能缺失 + - 资源不足 + - 系统服务异常 + +### 处理策略 +- **优雅降级**: 功能不可用时的替代方案 +- **错误重试**: 临时错误的重试机制 +- **用户提示**: 清晰的错误信息提示 +- **日志记录**: 详细的错误日志记录 + +## 测试策略 + +### 单元测试 +- **方法通道测试**: 通信接口测试 +- **数据模型测试**: 序列化反序列化 +- **工具类测试**: 辅助功能测试 +- **异常处理测试**: 错误场景测试 + +### 集成测试 +- **平台集成测试**: 原生功能集成 +- **权限流程测试**: 权限申请流程 +- **文件操作测试**: 文件系统操作 +- **自动化功能测试**: 自动化操作验证 + +### 兼容性测试 +- **设备兼容性**: 不同设备型号 +- **系统版本**: 不同操作系统版本 +- **权限策略**: 不同权限策略 +- **性能表现**: 不同性能水平设备 + +## 部署和维护 + +### 版本管理 +- **API版本控制**: 兼容不同版本 +- **功能开关**: 新功能渐进式发布 +- **回滚机制**: 问题版本快速回滚 +- **升级策略**: 平滑升级路径 + +### 监控指标 +- **调用成功率**: 方法调用成功率 +- **响应时间**: 操作响应延迟 +- **错误率**: 异常发生频率 +- **权限授予率**: 用户权限授予情况 + +## 总结 + +`kit_rpa_plugin` 作为 OneApp 的RPA自动化原生插件，为Flutter应用提供了强大的原生平台自动化操作能力。通过平台通道机制，实现了Flutter与Android/iOS原生代码的无缝集成，为RPA自动化任务提供了可靠的底层支持。插件设计考虑了安全性、性能和兼容性，能够在保证用户隐私和系统安全的前提下，提供高效的自动化操作能力。 diff --git a/app_car/one_app_cache_plugin.md b/app_car/one_app_cache_plugin.md new file mode 100644 index 0000000..d635ab7 --- /dev/null +++ b/app_car/one_app_cache_plugin.md @@ -0,0 +1,527 @@ +# OneApp Cache Plugin 缓存插件 + +## 模块概述 + +`one_app_cache_plugin` 是 OneApp 车联网生态中的原生缓存插件，负责为 Flutter 应用提供高效的原生缓存能力。该插件通过平台通道实现 Flutter 与 Android/iOS 原生缓存系统的交互，为应用数据缓存提供底层支持。 + +### 基本信息 +- **模块名称**: one_app_cache_plugin +- **版本**: 0.0.4 +- **类型**: Flutter Plugin（原生插件） +- **Flutter 版本**: >=3.3.0 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **多级缓存系统** + - 内存缓存（L1 Cache） + - 磁盘缓存（L2 Cache） + - 网络缓存（L3 Cache） + - 分布式缓存支持 + +2. **缓存策略管理** + - LRU（最近最少使用）淘汰 + - LFU（最少使用频率）淘汰 + - TTL（生存时间）过期 + - 自定义淘汰策略 + +3. **数据类型支持** + - 字符串数据缓存 + - 二进制数据缓存 + - JSON对象缓存 + - 文件资源缓存 + +4. **性能优化** + - 异步操作支持 + - 批量操作优化 + - 预加载机制 + - 智能压缩存储 + +## 技术架构 + +### 目录结构 +``` +one_app_cache_plugin/ +├── lib/ # Dart代码 +│ ├── one_app_cache_plugin.dart # 插件入口 +│ ├── src/ # 源代码 +│ │ ├── cache_manager.dart # 缓存管理器 +│ │ ├── cache_strategy.dart # 缓存策略 +│ │ ├── cache_models.dart # 数据模型 +│ │ └── platform_interface.dart # 平台接口 +│ └── one_app_cache_plugin_platform_interface.dart +├── android/ # Android原生代码 +│ ├── src/main/kotlin/ +│ │ └── com/oneapp/cache/ +│ │ ├── OneAppCachePlugin.kt # 主插件类 +│ │ ├── MemoryCache.kt # 内存缓存 +│ │ ├── DiskCache.kt # 磁盘缓存 +│ │ ├── CacheStrategy.kt # 缓存策略 +│ │ └── CacheUtils.kt # 缓存工具 +│ └── build.gradle +├── ios/ # iOS原生代码 +│ ├── Classes/ +│ │ ├── OneAppCachePlugin.swift # 主插件类 +│ │ ├── MemoryCache.swift # 内存缓存 +│ │ ├── DiskCache.swift # 磁盘缓存 +│ │ ├── CacheStrategy.swift # 缓存策略 +│ │ └── CacheUtils.swift # 缓存工具 +│ └── one_app_cache_plugin.podspec +├── example/ # 示例应用 +└── test/ # 测试文件 +``` + +### 依赖关系 + +#### 核心依赖 +- `plugin_platform_interface: ^2.0.2` - 插件平台接口 + +## 核心模块分析 + +### 1. Flutter端实现 + +#### 插件入口 (`lib/one_app_cache_plugin.dart`) +```dart +class OneAppCachePlugin { + static const MethodChannel _channel = MethodChannel('one_app_cache_plugin'); + + /// 获取缓存数据 + static Future get(String key) async { + return await _channel.invokeMethod('get', {'key': key}); + } + + /// 设置缓存数据 + static Future set(String key, String value, {Duration? ttl}) async { + final result = await _channel.invokeMethod('set', { + 'key': key, + 'value': value, + 'ttl': ttl?.inMilliseconds, + }); + return result ?? false; + } + + /// 删除缓存数据 + static Future delete(String key) async { + final result = await _channel.invokeMethod('delete', {'key': key}); + return result ?? false; + } + + /// 清空所有缓存 + static Future clear() async { + final result = await _channel.invokeMethod('clear'); + return result ?? false; + } + + /// 获取缓存统计信息 + static Future getStats() async { + final result = await _channel.invokeMethod('getStats'); + return CacheStats.fromMap(result); + } +} +``` + +#### 缓存管理器 (`lib/src/cache_manager.dart`) +```dart +class CacheManager { + static final CacheManager _instance = CacheManager._internal(); + factory CacheManager() => _instance; + CacheManager._internal(); + + /// 配置缓存策略 + Future configure(CacheConfig config) async { + await OneAppCachePlugin.configure(config); + } + + /// 智能缓存获取 + Future getOrSet( + String key, + Future Function() valueFactory, { + Duration? ttl, + CacheLevel level = CacheLevel.all, + }) async { + // 先尝试从缓存获取 + final cached = await get(key, level: level); + if (cached != null) return cached; + + // 缓存未命中，获取新值并缓存 + final value = await valueFactory(); + await set(key, value, ttl: ttl, level: level); + return value; + } + + /// 批量操作 + Future> getBatch(List keys) async { + return await OneAppCachePlugin.getBatch(keys); + } + + /// 预热缓存 + Future preload(Map data) async { + await OneAppCachePlugin.preload(data); + } +} +``` + +### 2. Android端实现 + +#### 主插件类 (`OneAppCachePlugin.kt`) +```kotlin +class OneAppCachePlugin: FlutterPlugin, MethodCallHandler { + private lateinit var context: Context + private lateinit var memoryCache: MemoryCache + private lateinit var diskCache: DiskCache + private lateinit var cacheStrategy: CacheStrategy + + override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) { + context = binding.applicationContext + initializeCaches() + + val channel = MethodChannel(binding.binaryMessenger, "one_app_cache_plugin") + channel.setMethodCallHandler(this) + } + + private fun initializeCaches() { + memoryCache = MemoryCache(context) + diskCache = DiskCache(context) + cacheStrategy = CacheStrategy() + } + + override fun onMethodCall(call: MethodCall, result: Result) { + when (call.method) { + "get" -> handleGet(call, result) + "set" -> handleSet(call, result) + "delete" -> handleDelete(call, result) + "clear" -> handleClear(call, result) + "getStats" -> handleGetStats(call, result) + "configure" -> handleConfigure(call, result) + else -> result.notImplemented() + } + } + + private fun handleGet(call: MethodCall, result: Result) { + val key = call.argument("key") + if (key == null) { + result.error("INVALID_ARGUMENT", "Key cannot be null", null) + return + } + + // 多级缓存查找 + var value = memoryCache.get(key) + if (value == null) { + value = diskCache.get(key) + if (value != null) { + // 将磁盘缓存的数据提升到内存缓存 + memoryCache.set(key, value) + } + } + + result.success(value) + } + + private fun handleSet(call: MethodCall, result: Result) { + val key = call.argument("key") + val value = call.argument("value") + val ttl = call.argument("ttl") + + if (key == null || value == null) { + result.error("INVALID_ARGUMENT", "Key and value cannot be null", null) + return + } + + val success = try { + memoryCache.set(key, value, ttl) + diskCache.set(key, value, ttl) + true + } catch (e: Exception) { + false + } + + result.success(success) + } +} +``` + +#### 内存缓存 (`MemoryCache.kt`) +```kotlin +class MemoryCache(private val context: Context) { + private val cache = LruCache(getMaxMemoryCacheSize()) + + fun get(key: String): String? { + val entry = cache.get(key) ?: return null + + // 检查是否过期 + if (entry.isExpired()) { + cache.remove(key) + return null + } + + return entry.value + } + + fun set(key: String, value: String, ttl: Long? = null) { + val expiryTime = ttl?.let { System.currentTimeMillis() + it } + val entry = CacheEntry(value, expiryTime) + cache.put(key, entry) + } + + private fun getMaxMemoryCacheSize(): Int { + val maxMemory = (Runtime.getRuntime().maxMemory() / 1024).toInt() + return maxMemory / 8 // 使用最大内存的1/8作为缓存大小 + } +} + +data class CacheEntry( + val value: String, + val expiryTime: Long? = null +) { + fun isExpired(): Boolean { + return expiryTime?.let { System.currentTimeMillis() > it } ?: false + } +} +``` + +#### 磁盘缓存 (`DiskCache.kt`) +```kotlin +class DiskCache(private val context: Context) { + private val cacheDir = File(context.cacheDir, "one_app_cache") + private val metadataFile = File(cacheDir, "metadata.json") + private val metadata = mutableMapOf() + + init { + if (!cacheDir.exists()) { + cacheDir.mkdirs() + } + loadMetadata() + } + + fun get(key: String): String? { + val meta = metadata[key] ?: return null + + // 检查是否过期 + if (meta.isExpired()) { + delete(key) + return null + } + + val file = File(cacheDir, meta.filename) + return if (file.exists()) { + try { + file.readText() + } catch (e: Exception) { + null + } + } else null + } + + fun set(key: String, value: String, ttl: Long? = null) { + val filename = generateFilename(key) + val file = File(cacheDir, filename) + + try { + file.writeText(value) + val expiryTime = ttl?.let { System.currentTimeMillis() + it } + metadata[key] = CacheMetadata(filename, expiryTime, System.currentTimeMillis()) + saveMetadata() + } catch (e: Exception) { + // 处理写入错误 + } + } + + private fun generateFilename(key: String): String { + return key.hashCode().toString() + ".cache" + } +} +``` + +### 3. iOS端实现 + +#### 主插件类 (`OneAppCachePlugin.swift`) +```swift +public class OneAppCachePlugin: NSObject, FlutterPlugin { + private var memoryCache: MemoryCache! + private var diskCache: DiskCache! + + public static func register(with registrar: FlutterPluginRegistrar) { + let channel = FlutterMethodChannel(name: "one_app_cache_plugin", + binaryMessenger: registrar.messenger()) + let instance = OneAppCachePlugin() + instance.initializeCaches() + registrar.addMethodCallDelegate(instance, channel: channel) + } + + private func initializeCaches() { + memoryCache = MemoryCache() + diskCache = DiskCache() + } + + public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) { + switch call.method { + case "get": + handleGet(call: call, result: result) + case "set": + handleSet(call: call, result: result) + case "delete": + handleDelete(call: call, result: result) + case "clear": + handleClear(call: call, result: result) + default: + result(FlutterMethodNotImplemented) + } + } + + private func handleGet(call: FlutterMethodCall, result: @escaping FlutterResult) { + guard let args = call.arguments as? [String: Any], + let key = args["key"] as? String else { + result(FlutterError(code: "INVALID_ARGUMENT", + message: "Key is required", + details: nil)) + return + } + + // 多级缓存查找 + if let value = memoryCache.get(key: key) { + result(value) + return + } + + if let value = diskCache.get(key: key) { + // 提升到内存缓存 + memoryCache.set(key: key, value: value) + result(value) + return + } + + result(nil) + } +} +``` + +## 缓存策略设计 + +### 淘汰策略 +1. **LRU (Least Recently Used)** + - 淘汰最近最少使用的数据 + - 适用于访问模式相对稳定的场景 + - 实现简单，性能良好 + +2. **LFU (Least Frequently Used)** + - 淘汰使用频率最低的数据 + - 适用于热点数据明显的场景 + - 需要维护访问频率统计 + +3. **TTL (Time To Live)** + - 基于时间的自动过期 + - 适用于时效性数据 + - 可与其他策略组合使用 + +4. **FIFO (First In First Out)** + - 先进先出的简单策略 + - 实现简单但效果有限 + - 适用于对缓存效果要求不高的场景 + +### 多级缓存架构 +``` +应用层 + ↓ +Flutter缓存管理器 + ↓ +L1: 内存缓存 (NSCache/LruCache) + ↓ +L2: 磁盘缓存 (本地文件系统) + ↓ +L3: 网络缓存 (HTTP缓存/CDN) +``` + +## 性能优化 + +### 内存优化 +- **智能大小调整**: 根据可用内存动态调整缓存大小 +- **内存压力监控**: 监听系统内存压力事件 +- **延迟加载**: 按需加载缓存数据 +- **压缩存储**: 对大数据进行压缩存储 + +### 磁盘优化 +- **异步I/O**: 所有磁盘操作异步执行 +- **批量操作**: 批量读写减少I/O次数 +- **文件压缩**: 压缩存储节省空间 +- **定期清理**: 定期清理过期和无效文件 + +### 网络优化 +- **预加载**: 预测性数据预加载 +- **增量更新**: 仅传输变化数据 +- **并发控制**: 限制并发网络请求 +- **断点续传**: 支持大文件断点续传 + +## 数据安全 + +### 加密存储 +- **敏感数据加密**: 对敏感缓存数据进行加密 +- **密钥管理**: 安全的密钥存储和管理 +- **完整性验证**: 数据完整性校验 +- **安全擦除**: 安全删除敏感数据 + +### 权限控制 +- **访问控制**: 基于权限的缓存访问 +- **沙盒隔离**: 应用间缓存数据隔离 +- **审计日志**: 缓存访问审计记录 +- **异常监控**: 异常访问行为监控 + +## 监控和诊断 + +### 性能指标 +```dart +class CacheStats { + final int hitCount; // 命中次数 + final int missCount; // 未命中次数 + final int evictionCount; // 淘汰次数 + final double hitRate; // 命中率 + final int size; // 当前大小 + final int maxSize; // 最大大小 + + double get hitRate => hitCount / (hitCount + missCount); +} +``` + +### 诊断工具 +- **缓存命中率监控**: 实时监控缓存效果 +- **内存使用分析**: 分析内存使用模式 +- **性能分析器**: 分析缓存操作性能 +- **调试界面**: 可视化缓存状态 + +## 测试策略 + +### 单元测试 +- **缓存操作测试**: 基本CRUD操作 +- **过期策略测试**: TTL和淘汰策略 +- **并发安全测试**: 多线程访问安全 +- **边界条件测试**: 极限情况处理 + +### 集成测试 +- **平台集成测试**: 原生平台功能 +- **性能测试**: 大数据量性能 +- **稳定性测试**: 长时间运行稳定性 +- **兼容性测试**: 不同设备和系统版本 + +### 压力测试 +- **高并发测试**: 大量并发访问 +- **大数据测试**: 大容量数据处理 +- **内存压力测试**: 低内存环境测试 +- **存储压力测试**: 存储空间不足测试 + +## 最佳实践 + +### 使用建议 +1. **合理设置TTL**: 根据数据特性设置合适的过期时间 +2. **选择合适策略**: 根据访问模式选择淘汰策略 +3. **监控缓存效果**: 定期检查命中率和性能指标 +4. **控制缓存大小**: 避免缓存过大影响性能 + +### 性能优化建议 +1. **预加载热点数据**: 应用启动时预加载重要数据 +2. **批量操作**: 尽量使用批量API减少开销 +3. **异步操作**: 避免阻塞主线程 +4. **合理清理**: 定期清理过期和不需要的缓存 + +## 总结 + +`one_app_cache_plugin` 作为 OneApp 的原生缓存插件，为Flutter应用提供了高效、可靠的多级缓存能力。通过智能的缓存策略、完善的性能优化和安全的数据保护，显著提升了应用的数据访问性能和用户体验。插件设计考虑了跨平台兼容性和可扩展性，能够适应不同的应用场景和性能要求。 diff --git a/app_car/ui_avatarx.md b/app_car/ui_avatarx.md new file mode 100644 index 0000000..f77a67b --- /dev/null +++ b/app_car/ui_avatarx.md @@ -0,0 +1,446 @@ +# UI AvatarX 虚拟形象UI组件 + +## 模块概述 + +`ui_avatarx` 是 OneApp 车联网生态中的虚拟形象UI组件库，负责虚拟形象的界面展示、交互控制、动画效果和用户体验优化等功能。该模块为虚拟助手提供了丰富的UI组件和交互体验。 + +### 基本信息 +- **模块名称**: ui_avatarx +- **版本**: 0.4.7+3 +- **描述**: 虚拟形象UI组件库 +- **Flutter 版本**: >=2.5.0 +- **Dart 版本**: >=2.16.2 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **虚拟形象展示** + - 3D虚拟形象渲染 + - 2D头像展示 + - 表情动画播放 + - 状态指示器 + +2. **交互组件** + - 语音交互界面 + - 手势控制组件 + - 触控反馈效果 + - 情绪表达控件 + +3. **动画效果** + - 流畅的转场动画 + - 表情切换动画 + - 状态变化动画 + - 自定义动画序列 + +4. **主题定制** + - 多种形象主题 + - 可定制外观 + - 响应式布局 + - 暗黑模式支持 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── ui_avatarx.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── widgets/ # UI组件 +│ ├── animations/ # 动画效果 +│ ├── themes/ # 主题配置 +│ ├── controllers/ # 控制器 +│ ├── models/ # 数据模型 +│ └── utils/ # 工具类 +├── assets/ # 资源文件 +└── examples/ # 示例代码 +``` + +### 依赖关系 + +#### 核心依赖 +- `basic_logger` - 日志系统（本地路径依赖） + +#### Flutter框架 +- `flutter` - Flutter SDK + +## 核心模块分析 + +### 1. 模块入口 (`ui_avatarx.dart`) + +**功能职责**: +- UI组件对外接口导出 +- 主题配置初始化 +- 组件注册管理 + +### 2. UI组件 (`src/widgets/`) + +**功能职责**: +- 虚拟形象展示组件 +- 交互控制组件 +- 状态指示组件 +- 自定义装饰组件 + +**主要组件**: +- `AvatarXWidget` - 主虚拟形象组件 +- `AvatarXHead` - 头像组件 +- `ExpressionPanel` - 表情控制面板 +- `VoiceIndicator` - 语音指示器 +- `EmotionSelector` - 情绪选择器 +- `AvatarXContainer` - 形象容器 +- `InteractionOverlay` - 交互覆盖层 + +### 3. 动画效果 (`src/animations/`) + +**功能职责**: +- 表情动画控制 +- 转场动画实现 +- 自定义动画序列 +- 动画状态管理 + +**主要动画**: +- `ExpressionAnimation` - 表情动画 +- `TransitionAnimation` - 转场动画 +- `IdleAnimation` - 待机动画 +- `InteractionAnimation` - 交互动画 +- `EmotionAnimation` - 情绪动画 + +### 4. 主题配置 (`src/themes/`) + +**功能职责**: +- 主题样式定义 +- 颜色配置管理 +- 尺寸规范设置 +- 响应式配置 + +**主要主题**: +- `DefaultAvatarTheme` - 默认主题 +- `DarkAvatarTheme` - 暗黑主题 +- `CustomAvatarTheme` - 自定义主题 +- `ResponsiveTheme` - 响应式主题 + +### 5. 控制器 (`src/controllers/`) + +**功能职责**: +- 虚拟形象状态控制 +- 动画播放控制 +- 交互事件处理 +- 生命周期管理 + +**主要控制器**: +- `AvatarXController` - 主控制器 +- `AnimationController` - 动画控制器 +- `InteractionController` - 交互控制器 +- `ThemeController` - 主题控制器 + +### 6. 数据模型 (`src/models/`) + +**功能职责**: +- 虚拟形象数据模型 +- 动画配置模型 +- 主题配置模型 +- 状态信息模型 + +**主要模型**: +- `AvatarXModel` - 虚拟形象模型 +- `ExpressionModel` - 表情模型 +- `AnimationConfig` - 动画配置模型 +- `ThemeConfig` - 主题配置模型 +- `InteractionState` - 交互状态模型 + +### 7. 工具类 (`src/utils/`) + +**功能职责**: +- 动画工具方法 +- 主题工具函数 +- 布局计算工具 +- 性能优化工具 + +**主要工具**: +- `AnimationUtils` - 动画工具 +- `ThemeUtils` - 主题工具 +- `LayoutUtils` - 布局工具 +- `PerformanceUtils` - 性能工具 + +## 组件设计 + +### 核心组件详解 + +#### AvatarXWidget +```dart +class AvatarXWidget extends StatefulWidget { + final AvatarXModel avatar; + final AvatarXController? controller; + final AvatarTheme? theme; + final double? width; + final double? height; + final bool enableInteraction; + final VoidCallback? onTap; + final Function(String)? onExpressionChanged; + + const AvatarXWidget({ + Key? key, + required this.avatar, + this.controller, + this.theme, + this.width, + this.height, + this.enableInteraction = true, + this.onTap, + this.onExpressionChanged, + }) : super(key: key); + + @override + State createState() => _AvatarXWidgetState(); +} +``` + +**主要功能**: +- 虚拟形象渲染展示 +- 交互事件处理 +- 动画状态管理 +- 主题样式应用 + +#### ExpressionPanel +```dart +class ExpressionPanel extends StatelessWidget { + final List expressions; + final String? currentExpression; + final Function(String) onExpressionSelected; + final bool showLabels; + final Axis direction; + + const ExpressionPanel({ + Key? key, + required this.expressions, + this.currentExpression, + required this.onExpressionSelected, + this.showLabels = true, + this.direction = Axis.horizontal, + }) : super(key: key); +} +``` + +**主要功能**: +- 表情选择界面 +- 表情预览功能 +- 选择状态指示 +- 可定制布局方向 + +#### VoiceIndicator +```dart +class VoiceIndicator extends StatefulWidget { + final bool isListening; + final bool isSpeaking; + final double amplitude; + final Color? color; + final double size; + final VoiceIndicatorStyle style; + + const VoiceIndicator({ + Key? key, + this.isListening = false, + this.isSpeaking = false, + this.amplitude = 0.0, + this.color, + this.size = 60.0, + this.style = VoiceIndicatorStyle.wave, + }) : super(key: key); +} +``` + +**主要功能**: +- 语音状态可视化 +- 音频波形显示 +- 实时振幅反映 +- 多种视觉样式 + +## 动画系统 + +### 动画类型 +1. **表情动画** + - 面部表情切换 + - 眼部动作 + - 嘴部动作 + - 眉毛表情 + +2. **身体动画** + - 头部转动 + - 肩膀动作 + - 手势动作 + - 姿态变化 + +3. **交互动画** + - 点击反馈 + - 悬停效果 + - 拖拽响应 + - 状态转换 + +4. **环境动画** + - 背景变化 + - 光照效果 + - 粒子效果 + - 氛围营造 + +### 动画控制 +```dart +class AnimationController { + Future playExpression(String expression, { + Duration duration = const Duration(milliseconds: 500), + Curve curve = Curves.easeInOut, + }); + + Future playSequence(List steps); + + void pauseAnimation(); + void resumeAnimation(); + void stopAnimation(); + + Stream get animationState; +} +``` + +## 主题系统 + +### 主题配置 +```dart +class AvatarTheme { + final Color primaryColor; + final Color secondaryColor; + final Color backgroundColor; + final TextStyle labelStyle; + final EdgeInsets padding; + final BorderRadius borderRadius; + final BoxShadow? shadow; + final AvatarSize size; + + const AvatarTheme({ + required this.primaryColor, + required this.secondaryColor, + required this.backgroundColor, + required this.labelStyle, + this.padding = const EdgeInsets.all(8.0), + this.borderRadius = const BorderRadius.all(Radius.circular(8.0)), + this.shadow, + this.size = AvatarSize.medium, + }); +} +``` + +### 响应式设计 +- **屏幕尺寸适配**: 自动调整组件大小 +- **密度适配**: 支持不同像素密度 +- **方向适配**: 横竖屏自适应 +- **平台适配**: iOS/Android样式适配 + +## 性能优化 + +### 渲染优化 +- **组件缓存**: 缓存渲染结果 +- **差分更新**: 仅更新变化部分 +- **懒加载**: 按需加载资源 +- **预加载**: 预测性资源加载 + +### 内存管理 +- **资源释放**: 及时释放不需要的资源 +- **内存池**: 复用对象减少GC +- **弱引用**: 避免内存泄漏 +- **监控告警**: 内存使用监控 + +### 动画优化 +- **硬件加速**: 利用GPU加速 +- **帧率控制**: 智能帧率调节 +- **插值优化**: 高效插值算法 +- **批量更新**: 批量处理动画更新 + +## 交互设计 + +### 手势支持 +1. **点击手势** + - 单击激活 + - 双击特殊功能 + - 长按菜单 + - 多点触控 + +2. **滑动手势** + - 水平滑动切换 + - 垂直滑动控制 + - 旋转手势 + - 缩放手势 + +3. **自定义手势** + - 手势识别器 + - 手势回调 + - 手势反馈 + - 手势组合 + +### 反馈机制 +- **视觉反馈**: 动画和颜色变化 +- **触觉反馈**: 震动反馈 +- **听觉反馈**: 音效提示 +- **语音反馈**: 语音确认 + +## 可访问性 + +### 无障碍支持 +- **语义标签**: 为屏幕阅读器提供标签 +- **焦点管理**: 键盘导航支持 +- **对比度**: 高对比度模式 +- **字体缩放**: 支持系统字体缩放 + +### 国际化支持 +- **多语言**: 支持多语言界面 +- **RTL布局**: 从右到左文字支持 +- **文化适配**: 不同文化的视觉适配 +- **时区处理**: 时间显示本地化 + +## 测试策略 + +### 单元测试 +- **组件渲染测试**: Widget渲染正确性 +- **动画逻辑测试**: 动画状态转换 +- **主题应用测试**: 主题配置正确性 +- **工具类测试**: 工具方法功能 + +### Widget测试 +- **交互测试**: 用户交互响应 +- **状态测试**: 组件状态变化 +- **布局测试**: 响应式布局 +- **性能测试**: 渲染性能 + +### 集成测试 +- **端到端测试**: 完整用户流程 +- **兼容性测试**: 不同设备适配 +- **性能测试**: 真实设备性能 +- **可访问性测试**: 无障碍功能 + +## 部署和维护 + +### 版本管理 +- **API稳定性**: 向后兼容保证 +- **渐进式升级**: 平滑版本升级 +- **功能开关**: 新功能渐进发布 +- **回滚策略**: 问题版本快速回滚 + +### 监控指标 +- **组件使用率**: 各组件使用频率 +- **性能指标**: 渲染性能和内存使用 +- **用户体验**: 交互响应时间 +- **错误率**: 组件异常发生率 + +## 最佳实践 + +### 开发建议 +1. **组件复用**: 优先使用现有组件 +2. **主题一致**: 遵循设计系统 +3. **性能考虑**: 避免过度渲染 +4. **可测试性**: 编写可测试代码 + +### 使用指南 +1. **合理选择**: 根据场景选择合适组件 +2. **配置优化**: 合理配置组件参数 +3. **资源管理**: 注意资源生命周期 +4. **用户体验**: 关注用户交互体验 + +## 总结 + +`ui_avatarx` 模块作为 OneApp 的虚拟形象UI组件库，提供了丰富的虚拟形象展示和交互能力。通过模块化的组件设计、灵活的主题系统和流畅的动画效果，为用户提供了优秀的虚拟助手交互体验。模块具有良好的性能优化和可访问性支持，能够适应不同的设备和使用场景。 diff --git a/assets/css/extra.css b/assets/css/extra.css new file mode 100644 index 0000000..11b4c77 --- /dev/null +++ b/assets/css/extra.css @@ -0,0 +1,318 @@ +/* OneApp 文档站点自定义样式 */ + +/* 全局样式优化 */ +.md-content { + max-width: none; +} + +.md-main__inner { + max-width: 1200px; + margin: 0 auto; +} + +/* Mermaid 图表样式优化 */ +.mermaid { + text-align: center; + margin: 20px 0; + background: transparent; +} + +.mermaid svg { + max-width: 100%; + height: auto; + border-radius: 6px; + background: var(--md-code-bg-color, #f6f8fa); + padding: 16px; + box-shadow: 0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.24); +} + +[data-md-color-scheme="slate"] .mermaid svg { + background: var(--md-code-bg-color, #161b22); +} + +/* 代码块样式优化 */ +.md-typeset pre { + background: var(--md-code-bg-color); + border-radius: 6px; + border: 1px solid var(--md-default-fg-color--lightest); +} + +.md-typeset code { + background: var(--md-code-bg-color); + border-radius: 3px; + padding: 0.1em 0.3em; + font-size: 0.85em; +} + +/* 表格样式优化 - GitHub风格 */ +.md-typeset table { + border-collapse: collapse; + border-spacing: 0; + display: block; + width: max-content; + max-width: 100%; + overflow: auto; + border: 1px solid var(--md-default-fg-color--lightest); + border-radius: 6px; +} + +.md-typeset table th, +.md-typeset table td { + border: 1px solid var(--md-default-fg-color--lightest); + padding: 6px 13px; +} + +.md-typeset table th { + background: var(--md-default-fg-color--lightest); + font-weight: 600; + text-align: left; +} + +.md-typeset table tr:nth-child(2n) { + background: var(--md-code-bg-color, #f6f8fa); +} + +[data-md-color-scheme="slate"] .md-typeset table tr:nth-child(2n) { + background: var(--md-code-bg-color, #161b22); +} + +/* 引用块样式优化 */ +.md-typeset blockquote { + border-left: 4px solid var(--md-primary-fg-color); + background: var(--md-code-bg-color, #f6f8fa); + padding: 16px 20px; + margin: 16px 0; + border-radius: 0 6px 6px 0; +} + +[data-md-color-scheme="slate"] .md-typeset blockquote { + background: var(--md-code-bg-color, #161b22); +} + +/* 标题样式优化 */ +.md-typeset h1, +.md-typeset h2, +.md-typeset h3, +.md-typeset h4, +.md-typeset h5, +.md-typeset h6 { + font-weight: 600; + line-height: 1.25; + margin-bottom: 16px; + border-bottom: none; +} + +.md-typeset h1 { + font-size: 2em; + border-bottom: 1px solid var(--md-default-fg-color--lightest); + padding-bottom: 0.3em; +} + +.md-typeset h2 { + font-size: 1.5em; + border-bottom: 1px solid var(--md-default-fg-color--lightest); + padding-bottom: 0.3em; +} + +/* 列表样式优化 */ +.md-typeset ul, +.md-typeset ol { + padding-left: 2em; +} + +.md-typeset li { + margin: 0.25em 0; +} + +/* 图片样式优化 */ +.md-typeset img { + max-width: 100%; + border-radius: 6px; + box-shadow: 0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.24); +} + +/* 内联代码优化 */ +.md-typeset p code, +.md-typeset li code, +.md-typeset td code { + background: var(--md-code-bg-color, rgba(175,184,193,0.2)); + padding: 0.1em 0.4em; + border-radius: 3px; + font-size: 85%; + color: var(--md-code-fg-color); +} + +[data-md-color-scheme="slate"] .md-typeset p code, +[data-md-color-scheme="slate"] .md-typeset li code, +[data-md-color-scheme="slate"] .md-typeset td code { + background: var(--md-code-bg-color, rgba(110,118,129,0.4)); +} + +/* 警告框样式优化 */ +.md-typeset .admonition { + border-radius: 6px; + border-left: 4px solid; + margin: 16px 0; + padding: 0 12px; +} + +/* 响应式设计 */ +@media screen and (max-width: 768px) { + .md-main__inner { + max-width: 100%; + padding: 0 16px; + } + + .mermaid svg { + padding: 8px; + } + + .md-typeset table { + font-size: 14px; + } + + .md-typeset pre { + padding: 8px; + overflow-x: auto; + } +} + +/* 导航样式优化 */ +.md-nav__title { + font-weight: 600; +} + +.md-nav__item--active > .md-nav__link { + color: var(--md-primary-fg-color); + font-weight: 600; +} + +/* 搜索结果优化 */ +.md-search-result__teaser { + color: var(--md-default-fg-color--light); + font-size: 0.8rem; +} + +/* 目录样式优化 */ +.md-nav--secondary .md-nav__title { + font-weight: 700; + color: var(--md-default-fg-color); +} + +/* 语法高亮优化 */ +.md-typeset .highlight pre { + background: var(--md-code-bg-color) !important; +} + +/* 页脚样式 */ +.md-footer { + background: var(--md-footer-bg-color); +} + +/* 打印样式 */ +@media print { + .md-header, + .md-sidebar, + .md-footer { + display: none !important; + } + + .md-main__inner { + max-width: 100% !important; + margin: 0 !important; + } + + .mermaid svg { + break-inside: avoid; + } + + .md-typeset table { + break-inside: avoid; + } +} + +/* 深色模式特定优化 */ +[data-md-color-scheme="slate"] { + --md-code-bg-color: #161b22; + --md-default-fg-color--lightest: #21262d; +} + +/* 滚动条样式 */ +::-webkit-scrollbar { + width: 8px; + height: 8px; +} + +::-webkit-scrollbar-track { + background: var(--md-default-bg-color); +} + +::-webkit-scrollbar-thumb { + background: var(--md-default-fg-color--light); + border-radius: 4px; +} + +::-webkit-scrollbar-thumb:hover { + background: var(--md-default-fg-color); +} + +/* 修复导航栏和目录滚动问题 */ +.md-sidebar { + height: calc(100vh - 2.4rem); + overflow: hidden; +} + +.md-sidebar__scrollwrap { + height: 100%; + overflow-y: auto; + overflow-x: hidden; + scrollbar-width: thin; + scrollbar-color: var(--md-default-fg-color--light) transparent; +} + +.md-nav { + max-height: none; +} + +.md-nav__list { + padding-bottom: 2rem; +} + +/* 修复右侧目录滚动 */ +.md-nav--secondary { + max-height: calc(100vh - 6rem); + overflow-y: auto; + overflow-x: hidden; +} + +.md-nav--secondary .md-nav__list { + padding-bottom: 3rem; + max-height: none; +} + +/* 移动端滚动优化 */ +@media screen and (max-width: 76.1875em) { + .md-nav--primary .md-nav__list { + padding-bottom: 2rem; + } + + .md-sidebar { + height: calc(100vh - 3rem); + } +} + +/* Tab 样式优化 */ +.md-typeset .tabbed-set { + border-radius: 6px; + border: 1px solid var(--md-default-fg-color--lightest); + overflow: hidden; +} + +.md-typeset .tabbed-labels { + background: var(--md-code-bg-color, #f6f8fa); + border-bottom: 1px solid var(--md-default-fg-color--lightest); +} + +[data-md-color-scheme="slate"] .md-typeset .tabbed-labels { + background: var(--md-code-bg-color, #161b22); +} \ No newline at end of file diff --git a/assets/js/mermaid.js b/assets/js/mermaid.js new file mode 100644 index 0000000..26b2bdb --- /dev/null +++ b/assets/js/mermaid.js @@ -0,0 +1,170 @@ +// OneApp Mermaid 配置 - 简化版 +(function() { + 'use strict'; + + // 等待页面加载完成 + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', initializeMermaid); + } else { + initializeMermaid(); + } + + function initializeMermaid() { + // 检查Mermaid是否已加载 + if (typeof mermaid === 'undefined') { + console.warn('Mermaid not loaded'); + return; + } + + // 配置Mermaid + mermaid.initialize({ + startOnLoad: true, + theme: 'default', + themeVariables: { + primaryColor: '#1976d2', + primaryTextColor: '#000000', + primaryBorderColor: '#1976d2', + lineColor: '#333333', + secondaryColor: '#ffffff', + tertiaryColor: '#ffffff' + }, + flowchart: { + useMaxWidth: true, + htmlLabels: true, + curve: 'basis' + }, + sequence: { + useMaxWidth: true, + wrap: true, + width: 150, + height: 65 + }, + gantt: { + useMaxWidth: true + }, + journey: { + useMaxWidth: true + }, + timeline: { + useMaxWidth: true + } + }); + + // 主题切换支持 + setupThemeToggle(); + } + + function setupThemeToggle() { + // 监听主题变化 - 改进版本 + const observer = new MutationObserver(function(mutations) { + mutations.forEach(function(mutation) { + if (mutation.type === 'attributes' && + mutation.attributeName === 'data-md-color-scheme') { + console.log('Theme changed to:', mutation.target.getAttribute('data-md-color-scheme')); // 调试信息 + reinitializeMermaid(); + } + }); + }); + + // 同时观察body和documentElement的属性变化 + observer.observe(document.body, { + attributes: true, + attributeFilter: ['data-md-color-scheme'] + }); + + observer.observe(document.documentElement, { + attributes: true, + attributeFilter: ['data-md-color-scheme'] + }); + + // 额外监听系统主题偏好变化 + if (window.matchMedia) { + const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)'); + mediaQuery.addEventListener('change', function() { + console.log('System theme changed'); // 调试信息 + reinitializeMermaid(); + }); + } + + // 监听Material主题切换按钮点击 + document.addEventListener('click', function(event) { + if (event.target.closest('[data-md-color-accent]') || + event.target.closest('[data-md-color-primary]') || + event.target.closest('.md-header__button.md-icon')) { + setTimeout(reinitializeMermaid, 50); // 延时确保主题已切换 + } + }); + } + + function reinitializeMermaid() { + // 检测当前主题 - 修复主题检测逻辑 + const isDark = document.body.getAttribute('data-md-color-scheme') === 'slate' || + document.documentElement.getAttribute('data-md-color-scheme') === 'slate' || + window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches; + + console.log('Theme detection - isDark:', isDark); // 调试信息 + + // 重新配置主题 + const theme = isDark ? 'dark' : 'default'; + const themeVariables = isDark ? { + primaryColor: '#bb86fc', + primaryTextColor: '#ffffff', + primaryBorderColor: '#bb86fc', + lineColor: '#ffffff', + secondaryColor: '#1f1f1f', + tertiaryColor: '#333333', + background: '#0d1117', + mainBkg: '#161b22', + secondBkg: '#21262d' + } : { + primaryColor: '#1976d2', + primaryTextColor: '#000000', + primaryBorderColor: '#1976d2', + lineColor: '#333333', + secondaryColor: '#ffffff', + tertiaryColor: '#ffffff', + background: '#ffffff', + mainBkg: '#ffffff', + secondBkg: '#f6f8fa' + }; + + // 重新初始化Mermaid + mermaid.initialize({ + startOnLoad: false, + theme: theme, + themeVariables: themeVariables, + flowchart: { + useMaxWidth: true, + htmlLabels: true, + curve: 'basis' + }, + sequence: { + useMaxWidth: true, + wrap: true + }, + gantt: { + useMaxWidth: true + } + }); + + // 重新渲染所有图表 + setTimeout(renderAllDiagrams, 100); + } + + function renderAllDiagrams() { + const elements = document.querySelectorAll('.mermaid, pre.mermaid'); + elements.forEach(function(element, index) { + const code = element.textContent || element.innerText; + if (code && code.trim()) { + try { + element.innerHTML = ''; + element.textContent = code.trim(); + mermaid.init(undefined, element); + } catch (error) { + console.error('Mermaid渲染错误:', error); + element.innerHTML = '
图表渲染失败: ' + error.message + '
'; + } + } + }); + } +})(); \ No newline at end of file diff --git a/assets/js/search-fix.js b/assets/js/search-fix.js new file mode 100644 index 0000000..8197bad --- /dev/null +++ b/assets/js/search-fix.js @@ -0,0 +1,57 @@ +// OneApp 文档站点搜索功能修复 +(function() { + 'use strict'; + + // 等待搜索功能加载 + document.addEventListener('DOMContentLoaded', function() { + // 延时确保Material主题的搜索组件已初始化 + setTimeout(function() { + initializeSearchFix(); + }, 500); + }); + + function initializeSearchFix() { + // 检查搜索输入框是否存在 + const searchInput = document.querySelector('.md-search__input'); + if (searchInput) { + console.log('Search input found, search is working'); + + // 改善搜索体验 + searchInput.addEventListener('focus', function() { + document.body.setAttribute('data-md-search-focus', ''); + }); + + searchInput.addEventListener('blur', function() { + setTimeout(function() { + document.body.removeAttribute('data-md-search-focus'); + }, 200); + }); + } else { + console.warn('Search input not found'); + } + + // 检查搜索结果容器 + const searchResults = document.querySelector('.md-search-result'); + if (searchResults) { + console.log('Search results container found'); + } + } + + // 主题切换时确保搜索功能正常 + const observer = new MutationObserver(function(mutations) { + mutations.forEach(function(mutation) { + if (mutation.type === 'attributes' && + mutation.attributeName === 'data-md-color-scheme') { + // 主题切换后重新检查搜索功能 + setTimeout(initializeSearchFix, 100); + } + }); + }); + + // 观察主题变化 + observer.observe(document.body, { + attributes: true, + attributeFilter: ['data-md-color-scheme'] + }); + +})(); \ No newline at end of file diff --git a/basic_uis/README.md b/basic_uis/README.md new file mode 100644 index 0000000..b34c479 --- /dev/null +++ b/basic_uis/README.md @@ -0,0 +1,349 @@ +# Basic UIs 基础UI组件模块群 + +## 模块群概述 + +Basic UIs 模块群是 OneApp 的用户界面基础设施，提供了完整的UI组件生态系统。该模块群包含了基础UI组件、业务UI组件和通用UI组件，为整个应用提供统一的设计语言和用户体验。 + +## 子模块列表 + +### 核心UI组件 +1. **[ui_basic](./ui_basic.md)** - 基础UI组件库 + - 按钮、输入框、卡片等基础组件 + - 布局容器和交互组件 + - 主题系统和响应式设计 + +2. **[ui_business](./ui_business.md)** - 业务UI组件库 + - 车辆状态展示组件 + - 消息中心组件 + - 地理位置组件 + - 用户同意组件 + +3. **[basic_uis](./basic_uis.md)** - 通用UI组件集合 + - 组件库整合和统一导出 + - 跨模块UI组件管理 + - 全局UI配置和工具 + +4. **[general_ui_component](./general_ui_component.md)** - 通用UI组件 + - 可复用的通用组件 + - 跨业务场景组件 + - 第三方组件封装 + +## 模块架构 + +### 分层设计 +``` +应用层 UI 组件 + ↓ +业务层 UI 组件 (ui_business) + ↓ +基础层 UI 组件 (ui_basic) + ↓ +Flutter Framework +``` + +### 组件分类 + +#### 1. 基础组件层 (ui_basic) +- **原子组件**: Button, TextField, Icon, Text +- **分子组件**: Card, ListTile, AppBar, Dialog +- **布局组件**: Container, Row, Column, Stack +- **交互组件**: GestureDetector, InkWell, RefreshIndicator + +#### 2. 业务组件层 (ui_business) +- **车辆组件**: VehicleStatusCard, VehicleControlPanel +- **消息组件**: MessageListView, MessageTile +- **位置组件**: LocationPicker, MapView +- **表单组件**: BusinessForm, ConsentDialog + +#### 3. 通用组件层 (basic_uis & general_ui_component) +- **复合组件**: SearchBar, NavigationDrawer +- **特效组件**: AnimatedWidget, TransitionWidget +- **工具组件**: LoadingOverlay, ErrorBoundary + +## 设计原则 + +### 1. 一致性原则 +- **视觉一致性**: 统一的颜色、字体、间距规范 +- **交互一致性**: 统一的交互模式和反馈机制 +- **行为一致性**: 相同功能组件的行为保持一致 + +### 2. 可访问性原则 +- **语义标签**: 为屏幕阅读器提供清晰的语义 +- **键盘导航**: 支持键盘和辅助设备导航 +- **对比度**: 满足无障碍对比度要求 +- **字体缩放**: 支持系统字体缩放设置 + +### 3. 响应式原则 +- **屏幕适配**: 适应不同屏幕尺寸和密度 +- **方向适配**: 支持横竖屏切换 +- **设备适配**: 针对手机、平板的优化 +- **性能适配**: 根据设备性能调整渲染策略 + +### 4. 可扩展性原则 +- **插件化**: 支持组件插件化扩展 +- **主题化**: 支持多主题和自定义主题 +- **国际化**: 支持多语言和本地化 +- **配置化**: 通过配置控制组件行为 + +## 主题系统 + +### 主题架构 +```dart +class OneAppTheme { + // 颜色系统 + static ColorScheme get colorScheme => ColorScheme.fromSeed( + seedColor: const Color(0xFF1976D2), + ); + + // 字体系统 + static TextTheme get textTheme => const TextTheme( + displayLarge: TextStyle(fontSize: 32, fontWeight: FontWeight.bold), + titleLarge: TextStyle(fontSize: 20, fontWeight: FontWeight.w600), + bodyLarge: TextStyle(fontSize: 16, fontWeight: FontWeight.normal), + ); + + // 组件主题 + static ThemeData get lightTheme => ThemeData( + useMaterial3: true, + colorScheme: colorScheme, + textTheme: textTheme, + appBarTheme: const AppBarTheme(/* ... */), + elevatedButtonTheme: ElevatedButtonThemeData(/* ... */), + ); +} +``` + +### 设计令牌 (Design Tokens) +```dart +class DesignTokens { + // 间距系统 + static const double spacingXs = 4.0; + static const double spacingSm = 8.0; + static const double spacingMd = 16.0; + static const double spacingLg = 24.0; + static const double spacingXl = 32.0; + + // 圆角系统 + static const double radiusXs = 4.0; + static const double radiusSm = 8.0; + static const double radiusMd = 12.0; + static const double radiusLg = 16.0; + + // 阴影系统 + static const List shadowSm = [ + BoxShadow( + color: Color(0x0D000000), + blurRadius: 2, + offset: Offset(0, 1), + ), + ]; +} +``` + +## 组件开发规范 + +### 1. 组件结构 +```dart +class ExampleComponent extends StatelessWidget { + // 1. 必需参数 + final String title; + + // 2. 可选参数 + final String? subtitle; + final VoidCallback? onTap; + + // 3. 样式参数 + final TextStyle? titleStyle; + final EdgeInsets? padding; + + // 4. 构造函数 + const ExampleComponent({ + Key? key, + required this.title, + this.subtitle, + this.onTap, + this.titleStyle, + this.padding, + }) : super(key: key); + + @override + Widget build(BuildContext context) { + return Container(/* 实现 */); + } +} +``` + +### 2. 命名规范 +- **组件名称**: 使用PascalCase，如 `VehicleStatusCard` +- **参数名称**: 使用camelCase，如 `onPressed` +- **常量名称**: 使用camelCase，如 `defaultPadding` +- **枚举名称**: 使用PascalCase，如 `ButtonType` + +### 3. 文档规范 +```dart +/// 车辆状态卡片组件 +/// +/// 用于展示车辆的基本状态信息，包括电量、里程、锁定状态等。 +/// 支持点击交互和自定义样式。 +/// +/// 示例用法： +/// ```dart +/// VehicleStatusCard( +/// status: vehicleStatus, +/// onTap: () => Navigator.push(...), +/// ) +/// ``` +class VehicleStatusCard extends StatelessWidget { + /// 车辆状态数据 + final VehicleStatus status; + + /// 点击回调函数 + final VoidCallback? onTap; +} +``` + +## 性能优化策略 + +### 1. 渲染优化 +- **Widget缓存**: 缓存不变的Widget实例 +- **RepaintBoundary**: 隔离重绘区域 +- **Const构造**: 使用const构造函数 +- **Build优化**: 避免在build方法中创建对象 + +### 2. 内存优化 +- **资源释放**: 及时释放Controller和Stream +- **图片缓存**: 合理使用图片缓存策略 +- **对象池**: 复用频繁创建的对象 +- **弱引用**: 避免内存泄漏 + +### 3. 加载优化 +- **懒加载**: 按需加载组件和资源 +- **预加载**: 预测性加载关键资源 +- **分包加载**: 大型组件分包异步加载 +- **缓存策略**: 智能缓存机制 + +## 测试策略 + +### 1. 单元测试 +```dart +testWidgets('VehicleStatusCard displays correct information', (tester) async { + const status = VehicleStatus( + vehicleName: 'Test Vehicle', + batteryLevel: 80, + isLocked: true, + ); + + await tester.pumpWidget( + MaterialApp( + home: VehicleStatusCard(status: status), + ), + ); + + expect(find.text('Test Vehicle'), findsOneWidget); + expect(find.text('80%'), findsOneWidget); + expect(find.byIcon(Icons.lock), findsOneWidget); +}); +``` + +### 2. Widget测试 +- **渲染测试**: 验证组件正确渲染 +- **交互测试**: 测试用户交互响应 +- **状态测试**: 测试状态变化 +- **样式测试**: 验证样式正确应用 + +### 3. 集成测试 +- **页面流程测试**: 测试完整用户流程 +- **性能测试**: 测试组件性能表现 +- **兼容性测试**: 测试不同设备兼容性 +- **可访问性测试**: 测试无障碍功能 + +## 构建和发布 + +### 1. 版本管理 +- **语义化版本**: 遵循 semver 规范 +- **变更日志**: 详细的变更记录 +- **向后兼容**: 保证API向后兼容 +- **废弃通知**: 提前通知API废弃 + +### 2. 发布流程 +```bash +# 1. 运行测试 +flutter test + +# 2. 更新版本号 +# 编辑 pubspec.yaml + +# 3. 更新变更日志 +# 编辑 CHANGELOG.md + +# 4. 发布包 +flutter pub publish +``` + +## 使用指南 + +### 1. 快速开始 +```dart +import 'package:ui_basic/ui_basic.dart'; +import 'package:ui_business/ui_business.dart'; + +class MyApp extends StatelessWidget { + @override + Widget build(BuildContext context) { + return MaterialApp( + theme: OneAppTheme.lightTheme, + home: MyHomePage(), + ); + } +} +``` + +### 2. 组件使用 +```dart +// 基础组件使用 +BasicButton( + text: '确定', + type: ButtonType.primary, + onPressed: () {}, +) + +// 业务组件使用 +VehicleStatusCard( + status: vehicleStatus, + onTap: () {}, +) +``` + +### 3. 主题定制 +```dart +MaterialApp( + theme: OneAppTheme.lightTheme.copyWith( + primarySwatch: Colors.green, + // 其他自定义配置 + ), +) +``` + +## 最佳实践 + +### 1. 组件设计 +- **单一职责**: 每个组件功能单一明确 +- **可组合性**: 支持组件组合使用 +- **可配置性**: 提供丰富的配置选项 +- **可预测性**: 相同输入产生相同输出 + +### 2. API设计 +- **直观性**: API命名直观易理解 +- **一致性**: 相似功能API保持一致 +- **扩展性**: 预留扩展空间 +- **文档化**: 提供完整文档和示例 + +### 3. 性能考虑 +- **懒加载**: 按需加载减少初始化开销 +- **缓存策略**: 合理使用缓存提升性能 +- **异步处理**: 避免阻塞UI线程 +- **资源管理**: 及时释放不需要的资源 + +## 总结 + +Basic UIs 模块群为 OneApp 提供了完整的UI基础设施，通过分层设计、统一规范和完善的工具链，实现了高效的UI开发和一致的用户体验。模块群具有良好的可扩展性和可维护性，能够支撑大型应用的UI需求，并为未来的功能扩展提供了坚实的基础。 diff --git a/basic_uis/basic_uis.md b/basic_uis/basic_uis.md new file mode 100644 index 0000000..b5e2db5 --- /dev/null +++ b/basic_uis/basic_uis.md @@ -0,0 +1,737 @@ +# Basic UIs 通用UI组件集合模块 + +## 模块概述 + +`basic_uis` 是 OneApp 基础UI模块群中的通用UI组件集合模块，负责整合和统一管理所有的UI组件库。该模块提供了一站式的UI组件解决方案，包含了动画效果、权限管理、分享功能、地图集成等丰富的UI功能组件。 + +### 基本信息 +- **模块名称**: basic_uis +- **版本**: 0.0.7 +- **描述**: 通用UI组件集合包 +- **Flutter 版本**: >=1.17.0 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **UI组件整合** + - 统一的UI组件导出 + - 组件库版本管理 + - 跨模块组件协调 + - 全局UI配置管理 + +2. **高级UI组件** + - 下拉刷新组件集成 + - Lottie动画支持 + - WebView组件封装 + - 地图视图集成 + +3. **用户交互组件** + - 权限管理UI组件 + - 分享功能UI集成 + - 图片保存组件 + - 设置页面组件 + +4. **系统集成组件** + - 位置服务UI + - 应用设置界面 + - 用户同意组件 + - Toast消息提示 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── basic_uis.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── components/ # 通用组件 +│ ├── animations/ # 动画组件 +│ ├── permissions/ # 权限组件 +│ ├── sharing/ # 分享组件 +│ ├── webview/ # WebView组件 +│ ├── location/ # 位置组件 +│ ├── settings/ # 设置组件 +│ └── utils/ # 工具类 +├── widgets/ # Widget导出 +└── themes/ # 主题配置 +``` + +### 依赖关系 + +#### UI框架依赖 +- `easy_refresh: ^3.0.5` - 下拉刷新组件 +- `lottie: ^3.1.0` - Lottie动画 +- `fluttertoast: ^8.2.2` - Toast提示 +- `helpers: ^1.2.3+1` - 辅助工具 + +#### 功能组件依赖 +- `basic_webview: ^0.2.4+4` - WebView组件 +- `permission_handler: ^10.4.5` - 权限管理 +- `image_gallery_saver: any` - 图片保存 +- `share_plus: 7.2.1` - 分享功能 +- `flutter_inappwebview: ^6.0.0` - 应用内WebView + +#### 业务组件依赖 +- `app_consent: ^0.2.19` - 用户同意组件 +- `ui_mapview: ^0.2.18` - 地图视图组件 +- `app_settings: ^4.3.1` - 应用设置 +- `location: ^6.0.1` - 位置服务 + +#### 内部依赖 +- `basic_utils` - 基础工具（本地路径） + +## 核心组件分析 + +### 1. 模块入口 (`basic_uis.dart`) + +**功能职责**: +- 统一导出所有UI组件 +- 初始化全局UI配置 +- 管理组件生命周期 + +```dart +library basic_uis; + +// 基础组件导出 +export 'src/components/enhanced_refresh_indicator.dart'; +export 'src/components/lottie_animation_widget.dart'; +export 'src/components/permission_request_dialog.dart'; +export 'src/components/share_action_sheet.dart'; + +// WebView组件导出 +export 'src/webview/enhanced_webview.dart'; +export 'src/webview/webview_controller.dart'; + +// 位置组件导出 +export 'src/location/location_picker_widget.dart'; +export 'src/location/map_integration_widget.dart'; + +// 设置组件导出 +export 'src/settings/app_settings_page.dart'; +export 'src/settings/permission_settings_widget.dart'; + +// 工具类导出 +export 'src/utils/ui_helpers.dart'; +export 'src/utils/toast_utils.dart'; + +class BasicUIs { + static bool _isInitialized = false; + + /// 初始化Basic UIs模块 + static Future initialize() async { + if (_isInitialized) return; + + // 初始化Toast配置 + await _initializeToast(); + + // 初始化权限处理器 + await _initializePermissions(); + + // 初始化分享服务 + await _initializeShare(); + + // 初始化WebView配置 + await _initializeWebView(); + + _isInitialized = true; + } +} +``` + +### 2. 增强下拉刷新组件 (`src/components/enhanced_refresh_indicator.dart`) + +```dart +class EnhancedRefreshIndicator extends StatefulWidget { + final Widget child; + final Future Function() onRefresh; + final Future Function()? onLoadMore; + final RefreshIndicatorConfig? config; + final bool enablePullUp; + final bool enablePullDown; + + const EnhancedRefreshIndicator({ + Key? key, + required this.child, + required this.onRefresh, + this.onLoadMore, + this.config, + this.enablePullUp = true, + this.enablePullDown = true, + }) : super(key: key); + + @override + State createState() => _EnhancedRefreshIndicatorState(); +} + +class _EnhancedRefreshIndicatorState extends State { + late EasyRefreshController _controller; + + @override + Widget build(BuildContext context) { + return EasyRefresh( + controller: _controller, + onRefresh: widget.enablePullDown ? _onRefresh : null, + onLoad: widget.enablePullUp && widget.onLoadMore != null ? _onLoad : null, + header: _buildRefreshHeader(), + footer: _buildLoadFooter(), + child: widget.child, + ); + } + + Widget _buildRefreshHeader() { + return ClassicHeader( + dragText: '下拉刷新', + armedText: '释放刷新', + readyText: '正在刷新...', + processingText: '正在刷新...', + processedText: '刷新完成', + noMoreText: '没有更多数据', + failedText: '刷新失败', + messageText: '最后更新于 %T', + ); + } + + Widget _buildLoadFooter() { + return ClassicFooter( + dragText: '上拉加载', + armedText: '释放加载', + readyText: '正在加载...', + processingText: '正在加载...', + processedText: '加载完成', + noMoreText: '没有更多数据', + failedText: '加载失败', + ); + } +} +``` + +### 3. Lottie动画组件 (`src/animations/lottie_animation_widget.dart`) + +```dart +class LottieAnimationWidget extends StatefulWidget { + final String assetPath; + final double? width; + final double? height; + final bool repeat; + final bool autoPlay; + final AnimationController? controller; + final VoidCallback? onComplete; + + const LottieAnimationWidget({ + Key? key, + required this.assetPath, + this.width, + this.height, + this.repeat = true, + this.autoPlay = true, + this.controller, + this.onComplete, + }) : super(key: key); + + @override + State createState() => _LottieAnimationWidgetState(); +} + +class _LottieAnimationWidgetState extends State + with TickerProviderStateMixin { + late AnimationController _animationController; + + @override + void initState() { + super.initState(); + + _animationController = widget.controller ?? + AnimationController(vsync: this); + + if (widget.autoPlay) { + _animationController.forward(); + } + + _animationController.addStatusListener((status) { + if (status == AnimationStatus.completed) { + widget.onComplete?.call(); + if (widget.repeat) { + _animationController.repeat(); + } + } + }); + } + + @override + Widget build(BuildContext context) { + return Lottie.asset( + widget.assetPath, + width: widget.width, + height: widget.height, + controller: _animationController, + onLoaded: (composition) { + _animationController.duration = composition.duration; + if (widget.autoPlay) { + _animationController.forward(); + } + }, + ); + } + + @override + void dispose() { + if (widget.controller == null) { + _animationController.dispose(); + } + super.dispose(); + } +} +``` + +### 4. 权限请求对话框 (`src/permissions/permission_request_dialog.dart`) + +```dart +class PermissionRequestDialog extends StatelessWidget { + final Permission permission; + final String title; + final String description; + final String? rationale; + final VoidCallback? onGranted; + final VoidCallback? onDenied; + + const PermissionRequestDialog({ + Key? key, + required this.permission, + required this.title, + required this.description, + this.rationale, + this.onGranted, + this.onDenied, + }) : super(key: key); + + @override + Widget build(BuildContext context) { + return AlertDialog( + title: Row( + children: [ + Icon(_getPermissionIcon(), color: Theme.of(context).primaryColor), + const SizedBox(width: 12), + Expanded(child: Text(title)), + ], + ), + content: Column( + mainAxisSize: MainAxisSize.min, + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text(description), + if (rationale != null) ...[ + const SizedBox(height: 16), + Container( + padding: const EdgeInsets.all(12), + decoration: BoxDecoration( + color: Colors.blue.withOpacity(0.1), + borderRadius: BorderRadius.circular(8), + ), + child: Row( + children: [ + Icon(Icons.info_outline, + color: Colors.blue, size: 20), + const SizedBox(width: 8), + Expanded( + child: Text( + rationale!, + style: TextStyle( + color: Colors.blue[700], + fontSize: 14, + ), + ), + ), + ], + ), + ), + ], + ], + ), + actions: [ + TextButton( + onPressed: () { + Navigator.of(context).pop(); + onDenied?.call(); + }, + child: const Text('拒绝'), + ), + ElevatedButton( + onPressed: () async { + Navigator.of(context).pop(); + final status = await permission.request(); + if (status.isGranted) { + onGranted?.call(); + } else { + onDenied?.call(); + if (status.isPermanentlyDenied) { + _showSettingsDialog(context); + } + } + }, + child: const Text('允许'), + ), + ], + ); + } + + IconData _getPermissionIcon() { + switch (permission) { + case Permission.camera: + return Icons.camera_alt; + case Permission.microphone: + return Icons.mic; + case Permission.location: + return Icons.location_on; + case Permission.storage: + return Icons.storage; + case Permission.photos: + return Icons.photo_library; + default: + return Icons.security; + } + } + + void _showSettingsDialog(BuildContext context) { + showDialog( + context: context, + builder: (context) => AlertDialog( + title: const Text('权限设置'), + content: const Text('请在设置中手动开启所需权限'), + actions: [ + TextButton( + onPressed: () => Navigator.of(context).pop(), + child: const Text('取消'), + ), + ElevatedButton( + onPressed: () { + Navigator.of(context).pop(); + openAppSettings(); + }, + child: const Text('去设置'), + ), + ], + ), + ); + } +} +``` + +### 5. 分享操作表 (`src/sharing/share_action_sheet.dart`) + +```dart +class ShareActionSheet extends StatelessWidget { + final ShareContent content; + final List platforms; + final Function(SharePlatform)? onPlatformSelected; + + const ShareActionSheet({ + Key? key, + required this.content, + required this.platforms, + this.onPlatformSelected, + }) : super(key: key); + + @override + Widget build(BuildContext context) { + return Container( + padding: const EdgeInsets.all(20), + decoration: const BoxDecoration( + color: Colors.white, + borderRadius: BorderRadius.vertical(top: Radius.circular(20)), + ), + child: Column( + mainAxisSize: MainAxisSize.min, + children: [ + _buildHandle(), + const SizedBox(height: 20), + Text( + '分享到', + style: Theme.of(context).textTheme.titleMedium, + ), + const SizedBox(height: 20), + _buildPlatformGrid(context), + const SizedBox(height: 20), + _buildMoreActions(context), + ], + ), + ); + } + + Widget _buildPlatformGrid(BuildContext context) { + return GridView.builder( + shrinkWrap: true, + physics: const NeverScrollableScrollPhysics(), + gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount( + crossAxisCount: 4, + childAspectRatio: 1, + crossAxisSpacing: 20, + mainAxisSpacing: 20, + ), + itemCount: platforms.length, + itemBuilder: (context, index) { + final platform = platforms[index]; + return _buildPlatformItem(context, platform); + }, + ); + } + + Widget _buildPlatformItem(BuildContext context, SharePlatform platform) { + return GestureDetector( + onTap: () { + Navigator.of(context).pop(); + onPlatformSelected?.call(platform); + _shareToplatform(platform); + }, + child: Column( + children: [ + Container( + width: 60, + height: 60, + decoration: BoxDecoration( + color: platform.color.withOpacity(0.1), + borderRadius: BorderRadius.circular(12), + ), + child: Icon( + platform.icon, + color: platform.color, + size: 30, + ), + ), + const SizedBox(height: 8), + Text( + platform.name, + style: Theme.of(context).textTheme.bodySmall, + textAlign: TextAlign.center, + ), + ], + ), + ); + } + + Future _shareToplatform(SharePlatform platform) async { + try { + switch (platform.type) { + case SharePlatformType.system: + await Share.share(content.text, subject: content.title); + break; + case SharePlatformType.wechat: + // 微信分享逻辑 + break; + case SharePlatformType.weibo: + // 微博分享逻辑 + break; + case SharePlatformType.qq: + // QQ分享逻辑 + break; + } + } catch (e) { + ToastUtils.showError('分享失败: $e'); + } + } +} +``` + +## 工具类 + +### Toast工具类 (`src/utils/toast_utils.dart`) + +```dart +class ToastUtils { + static void showSuccess(String message) { + Fluttertoast.showToast( + msg: message, + toastLength: Toast.LENGTH_SHORT, + gravity: ToastGravity.CENTER, + backgroundColor: Colors.green, + textColor: Colors.white, + fontSize: 16.0, + ); + } + + static void showError(String message) { + Fluttertoast.showToast( + msg: message, + toastLength: Toast.LENGTH_SHORT, + gravity: ToastGravity.CENTER, + backgroundColor: Colors.red, + textColor: Colors.white, + fontSize: 16.0, + ); + } + + static void showInfo(String message) { + Fluttertoast.showToast( + msg: message, + toastLength: Toast.LENGTH_SHORT, + gravity: ToastGravity.CENTER, + backgroundColor: Colors.blue, + textColor: Colors.white, + fontSize: 16.0, + ); + } + + static void showWarning(String message) { + Fluttertoast.showToast( + msg: message, + toastLength: Toast.LENGTH_SHORT, + gravity: ToastGravity.CENTER, + backgroundColor: Colors.orange, + textColor: Colors.white, + fontSize: 16.0, + ); + } +} +``` + +## 使用示例 + +### 基础使用 +```dart +class BasicUIsExample extends StatefulWidget { + @override + _BasicUIsExampleState createState() => _BasicUIsExampleState(); +} + +class _BasicUIsExampleState extends State { + @override + void initState() { + super.initState(); + _initializeBasicUIs(); + } + + Future _initializeBasicUIs() async { + await BasicUIs.initialize(); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('Basic UIs Example')), + body: EnhancedRefreshIndicator( + onRefresh: _handleRefresh, + onLoadMore: _handleLoadMore, + child: ListView( + children: [ + // Lottie动画示例 + LottieAnimationWidget( + assetPath: 'assets/animations/loading.json', + width: 100, + height: 100, + ), + + // 权限请求示例 + ListTile( + title: Text('请求相机权限'), + onTap: () => _requestCameraPermission(), + ), + + // 分享功能示例 + ListTile( + title: Text('分享内容'), + onTap: () => _showShareSheet(), + ), + + // Toast示例 + ListTile( + title: Text('显示Toast'), + onTap: () => ToastUtils.showSuccess('操作成功'), + ), + ], + ), + ), + ); + } + + Future _handleRefresh() async { + await Future.delayed(Duration(seconds: 2)); + ToastUtils.showSuccess('刷新完成'); + } + + Future _handleLoadMore() async { + await Future.delayed(Duration(seconds: 1)); + } + + void _requestCameraPermission() { + showDialog( + context: context, + builder: (context) => PermissionRequestDialog( + permission: Permission.camera, + title: '相机权限', + description: '需要相机权限来拍照和录制视频', + rationale: '此权限用于扫描二维码和拍照功能', + onGranted: () => ToastUtils.showSuccess('权限已授予'), + onDenied: () => ToastUtils.showError('权限被拒绝'), + ), + ); + } + + void _showShareSheet() { + showModalBottomSheet( + context: context, + builder: (context) => ShareActionSheet( + content: ShareContent( + title: 'OneApp', + text: '快来体验OneApp的强大功能！', + url: 'https://oneapp.com', + ), + platforms: [ + SharePlatform.system(), + SharePlatform.wechat(), + SharePlatform.weibo(), + SharePlatform.qq(), + ], + onPlatformSelected: (platform) { + ToastUtils.showInfo('分享到${platform.name}'); + }, + ), + ); + } +} +``` + +## 性能优化 + +### 组件优化 +- **懒加载**: 按需加载重型组件 +- **Widget缓存**: 缓存不变的Widget实例 +- **动画优化**: 合理使用动画避免过度渲染 +- **内存管理**: 及时释放资源和控制器 + +### 集成优化 +- **依赖管理**: 避免重复依赖和版本冲突 +- **包大小**: 优化资源文件减少包大小 +- **初始化**: 异步初始化避免阻塞启动 +- **缓存策略**: 合理使用缓存提升性能 + +## 测试策略 + +### Widget测试 +- **组件渲染测试**: 验证组件正确渲染 +- **交互测试**: 测试用户交互响应 +- **动画测试**: 测试动画效果 +- **权限测试**: 测试权限请求流程 + +### 集成测试 +- **模块集成测试**: 测试模块间协作 +- **第三方服务测试**: 测试外部服务集成 +- **性能测试**: 测试组件性能表现 +- **兼容性测试**: 测试平台兼容性 + +## 最佳实践 + +### 组件使用 +1. **统一入口**: 通过BasicUIs统一初始化 +2. **配置管理**: 集中管理组件配置 +3. **错误处理**: 完善的错误处理机制 +4. **用户体验**: 注重用户交互体验 + +### 开发规范 +1. **代码规范**: 遵循统一的代码规范 +2. **文档完善**: 提供详细的使用文档 +3. **版本管理**: 合理的版本发布策略 +4. **测试覆盖**: 保证充分的测试覆盖 + +## 总结 + +`basic_uis` 模块作为 OneApp 的通用UI组件集合，整合了丰富的UI功能组件和第三方服务，为应用开发提供了一站式的UI解决方案。通过统一的管理和标准化的接口，大大提升了开发效率和用户体验的一致性。模块具有良好的扩展性和可维护性，能够适应不断变化的UI需求。 diff --git a/basic_uis/general_ui_component.md b/basic_uis/general_ui_component.md new file mode 100644 index 0000000..d7d1dbc --- /dev/null +++ b/basic_uis/general_ui_component.md @@ -0,0 +1,446 @@ +# General UI Component 通用UI组件模块 + +## 模块概述 + +`general_ui_component` 是 OneApp 基础UI模块群中的通用UI组件模块，专门提供可复用的通用界面组件。该模块实现了通用的项目组件和分享对话框等核心功能。 + +### 基本信息 +- **模块名称**: general_ui_component +- **版本**: 0.0.1 +- **描述**: 通用UI组件库 +- **Flutter 版本**: >=1.17.0 + +## 核心组件 + +### 1. 项目组件 (ItemAComponent) + +基于真实项目代码的通用项目展示组件： + +```dart +/// 通用项目组件A，用于显示带图标和标题的项目 +class ItemAComponent extends StatelessWidget { + /// Logo图片URL + String logoImg = ''; + + /// 标题文本 + String title = ''; + + /// 点击回调函数 + OnItemAClick onItemAClick; + + /// 项目索引 + int index; + + /// 自定义尺寸（可选） + double? size; + + ItemAComponent({ + required this.title, + required this.logoImg, + required this.onItemAClick, + required this.index, + this.size, + }); + + @override + Widget build(BuildContext context) { + return InkWell( + highlightColor: Colors.transparent, + splashColor: Colors.transparent, + child: Column( + children: [ + Stack( + alignment: Alignment.center, + children: [ + // 圆形背景 + Container( + width: width(designWidgetWidth: 48), + height: width(designWidgetWidth: 48), + decoration: BoxDecoration( + shape: BoxShape.circle, + color: OneColors.bgcSub2, + ), + ), + // 图标图片 + SizedBox( + height: size ?? width(designWidgetWidth: 40), + width: size ?? width(designWidgetWidth: 40), + child: CacheImageComponent( + imageUrl: logoImg, + ), + ), + ], + ), + // 标题文本 + Padding( + padding: EdgeInsets.only(top: 5.0), + child: Text( + title, + style: OneTextStyle.content( + color: const Color(0xFF7C7F81), + ), + ), + ) + ], + ), + onTap: () => onItemAClick(index), + ); + } +} + +/// 项目点击回调函数类型定义 +typedef OnItemAClick = Function(int index); +``` + +### 2. 分享对话框 (ShareDialog) + +基于真实项目代码的分享功能对话框： + +```dart +/// 分享对话框组件 +class Sharedialog extends StatelessWidget { + /// 项目点击回调 + OnItemAClick onItemAClick; + + /// 分享项目名称列表 + List itemNameList; + + /// 底部操作组件（可选） + Widget? bottomActionWidget; + + Sharedialog({ + required this.onItemAClick, + required this.itemNameList, + this.bottomActionWidget, + }); + + @override + Widget build(BuildContext context) { + if (itemNameList.isNotEmpty) { + List itemWidgetList = []; + + for (int i = 0; i < itemNameList.length; i++) { + // 添加间距 + if (bottomActionWidget != null) { + itemWidgetList.add(SizedBox( + width: width(designWidgetWidth: 36), + )); + } + + // 根据类型创建不同的分享项目 + switch (itemNameList[i]) { + case 'weibo': + itemWidgetList.add(_createShareItem( + title: BasicUisIntlDelegate.current.Weibo, + logoImg: 'packages/basic_uis/assets/icon/weibo.png', + index: i, + )); + break; + case 'weixin': + itemWidgetList.add(_createShareItem( + title: BasicUisIntlDelegate.current.WeChat, + logoImg: 'packages/basic_uis/assets/icon/wechat.png', + index: i, + )); + break; + case 'friends': + itemWidgetList.add(_createShareItem( + title: BasicUisIntlDelegate.current.FriendCircle, + logoImg: 'packages/basic_uis/assets/icon/moments.png', + index: i, + )); + break; + case 'copy': + itemWidgetList.add(_createShareItem( + title: BasicUisIntlDelegate.current.copyLink, + logoImg: 'packages/basic_uis/assets/icon/copy_link.png', + index: i, + size: width(designWidgetWidth: 20), + )); + break; + } + } + + return Container( + child: Wrap( + children: itemWidgetList, + ), + ); + } + return Container(); + } + + /// 创建分享项目组件 + Widget _createShareItem({ + required String title, + required String logoImg, + required int index, + double? size, + }) { + return ItemAComponent( + title: title, + logoImg: logoImg, + index: index, + size: size, + onItemAClick: (int index) => onItemAClick(index), + ); + } +} +``` + +## 技术架构 + +### 目录结构 + +基于实际项目结构： + +``` +lib/ +├── ItemAComponent.dart # 通用项目组件 +└── share/ # 分享功能相关 + ├── dialog/ # 分享对话框 + │ └── ShareDialog.dart # 分享对话框实现 + └── util/ # 分享工具类 +``` + +### 依赖关系 + +基于实际项目依赖： + +```dart +// 国际化支持 +import 'package:basic_uis/generated/l10n.dart'; +import 'package:basic_utils/generated/l10n.dart'; + +// UI基础组件 +import 'package:ui_basic/ui_basic.dart'; + +// 基础工具 +import 'package:basic_utils/basic_utils.dart'; + +// 缓存图片组件 +import 'package:basic_uis/src/common_components/cache_image_component.dart'; +``` + +## 使用指南 + +### 1. ItemAComponent 使用示例 + +```dart +import 'package:general_ui_component/ItemAComponent.dart'; + +class ServiceGridPage extends StatelessWidget { + final List services = [ + ServiceItem('充电服务', 'assets/icons/charging.png'), + ServiceItem('维修保养', 'assets/icons/maintenance.png'), + ServiceItem('道路救援', 'assets/icons/rescue.png'), + ]; + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('服务中心')), + body: GridView.builder( + padding: EdgeInsets.all(16.0), + gridDelegate: SliverGridDelegateWithFixedCrossAxisCount( + crossAxisCount: 3, + childAspectRatio: 1.0, + crossAxisSpacing: 16.0, + mainAxisSpacing: 16.0, + ), + itemCount: services.length, + itemBuilder: (context, index) { + final service = services[index]; + return ItemAComponent( + title: service.name, + logoImg: service.iconUrl, + index: index, + onItemAClick: _handleServiceClick, + ); + }, + ), + ); + } + + void _handleServiceClick(int index) { + final service = services[index]; + print('选择了服务: ${service.name}'); + // 处理服务选择逻辑 + } +} + +class ServiceItem { + final String name; + final String iconUrl; + + ServiceItem(this.name, this.iconUrl); +} +``` + +### 2. ShareDialog 分享功能使用 + +```dart +import 'package:general_ui_component/share/dialog/ShareDialog.dart'; + +class ShareExample extends StatelessWidget { + @override + Widget build(BuildContext context) { + return ElevatedButton( + onPressed: () => _showShareDialog(context), + child: Text('分享内容'), + ); + } + + void _showShareDialog(BuildContext context) { + showModalBottomSheet( + context: context, + builder: (context) => Sharedialog( + itemNameList: ['weixin', 'friends', 'weibo', 'copy'], + onItemAClick: _handleShareAction, + bottomActionWidget: Padding( + padding: EdgeInsets.all(16.0), + child: Text('选择分享方式'), + ), + ), + ); + } + + void _handleShareAction(int index) { + switch (index) { + case 0: + print('分享到微信'); + break; + case 1: + print('分享到朋友圈'); + break; + case 2: + print('分享到微博'); + break; + case 3: + print('复制链接'); + break; + } + } +} + +## 依赖配置 + +### pubspec.yaml 关键依赖 + +```yaml +dependencies: + flutter: + sdk: flutter + + # 国际化支持 + basic_uis: + path: ../basic_uis + + # 基础工具 + basic_utils: + path: ../../oneapp_basic_utils/basic_utils + + # UI基础组件 + ui_basic: + path: ../ui_basic + +dev_dependencies: + build_runner: any + freezed: ^2.3.5 + flutter_lints: ^5.0.0 +``` + +## 最佳实践 + +### 1. 组件复用 +```dart +// 推荐：创建配置化的服务列表 +Widget buildServiceGrid({ + required List services, + required OnItemAClick onItemClick, +}) { + return GridView.builder( + gridDelegate: SliverGridDelegateWithFixedCrossAxisCount( + crossAxisCount: 3, + childAspectRatio: 1.0, + ), + itemCount: services.length, + itemBuilder: (context, index) { + final service = services[index]; + return ItemAComponent( + title: service.name, + logoImg: service.iconUrl, + index: index, + onItemAClick: onItemClick, + ); + }, + ); +} +``` + +### 2. 分享功能集成 +```dart +// 推荐：封装分享功能 +class ShareHelper { + static void showShareDialog( + BuildContext context, + String content, { + List platforms = const ['weixin', 'friends', 'weibo', 'copy'], + }) { + showModalBottomSheet( + context: context, + builder: (context) => Sharedialog( + itemNameList: platforms, + onItemAClick: (index) => _handleShare(context, content, platforms[index]), + ), + ); + } + + static void _handleShare(BuildContext context, String content, String platform) { + // 实际分享逻辑实现 + Navigator.pop(context); + } +} +``` + +### 3. 主题适配 +```dart +// 推荐：支持主题切换 +ItemAComponent( + title: service.name, + logoImg: service.iconUrl, + index: index, + onItemAClick: onItemClick, + // 自动适配当前主题 +) +``` + +## 项目集成 + +### 模块依赖关系 + +```dart +// 实际项目中的依赖导入 +import 'package:basic_uis/generated/l10n.dart'; // 国际化 +import 'package:basic_utils/basic_utils.dart'; // 工具类 +import 'package:ui_basic/ui_basic.dart'; // UI基础 +import 'package:flutter/material.dart'; // Flutter核心 +``` + +### 使用建议 + +1. **性能优化**：使用`const`构造函数优化重建性能 +2. **内存管理**：及时释放不用的控制器和监听器 +3. **主题一致性**：使用OneColors主题颜色系统 +4. **国际化支持**：使用BasicUisIntlDelegate进行文本国际化 + +## 总结 + +`general_ui_component` 模块提供了OneApp项目中的核心通用UI组件，包括： + +- **ItemAComponent**: 通用项目展示组件，支持圆形图标和文本标题 +- **ShareDialog**: 分享功能对话框，支持微信、朋友圈、微博、复制等分享方式 +- **完整的依赖管理**: 与OneApp其他模块的良好集成 +- **国际化支持**: 完整的中英文多语言支持 + +这些组件为OneApp提供了统一的UI设计语言和交互模式，确保了应用界面的一致性和可维护性。 diff --git a/basic_uis/ui_basic.md b/basic_uis/ui_basic.md new file mode 100644 index 0000000..ce7c5c6 --- /dev/null +++ b/basic_uis/ui_basic.md @@ -0,0 +1,407 @@ +# UI Basic 基础UI组件模块 + +## 模块概述 + +`ui_basic` 是 OneApp 基础UI模块群中的核心组件库，提供了应用开发中常用的基础UI组件和交互元素。该模块封装了通用的界面组件、布局容器、表单元素等，为整个应用提供统一的设计语言和用户体验。 + +### 基本信息 +- **模块名称**: ui_basic +- **版本**: 0.2.45 +- **仓库**: https://gitlab-rd0.maezia.com/dssomobile/oneapp/dssomobile-oneapp-ui-basic +- **Flutter 版本**: >=1.17.0 +- **Dart 版本**: >=2.17.0 <4.0.0 +- **发布服务器**: http://175.24.250.68:4000/ + +## 功能特性 + +### 核心功能 +基于实际项目的UI组件库，包含丰富的组件和第三方集成。 + +1. **基础组件库** + - 按钮组件（OneIconButton、CommonButton） + - 输入组件（BasicTextField、BasicMultiTextField、VehiclePlateField） + - 展示组件（OneTag、OneCard、ProgressWidget） + - 导航组件（CommonTitleBar、CommonTabbar） + +2. **交互组件** + - 上拉下拉刷新（pull_to_refresh集成） + - 轮播图组件（OneSwiper、carousel_slider集成） + - 对话框和弹窗（OneDialogX、CommonBottomSheet） + - 加载指示器（LoadingWidget、CommonLoadingWidget） + +3. **多媒体组件** + - 图片组件（GlinettImage、ImageWidget、CachedNetworkImage集成） + - 扫码组件（QrScannerWidget、flutter_scankit集成） + - 相机组件（CameraWidget、camera集成） + - SVG支持（flutter_svg集成） + +4. **富文本和图表** + - HTML富文本渲染（flutter_html集成） + - 图表组件（OneChart、fl_chart集成） + - ECharts集成（FlutterEcharts） + - 评分组件（RatingWidget、flutter_rating_bar集成） + +## 技术架构 + +### 目录结构 +``` +lib/ +├── ui_basic.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── components/ # 基础组件 +│ ├── containers/ # 布局容器 +│ ├── interactions/ # 交互组件 +│ ├── themes/ # 主题配置 +│ ├── utils/ # 工具类 +│ └── constants/ # 常量定义 +├── widgets/ # 组件导出 +└── themes/ # 主题文件 +``` + +### 依赖关系 + +基于实际项目的pubspec.yaml配置，展示真实的依赖架构。 + +#### 框架依赖 +```yaml +# 核心框架依赖 +dependencies: + basic_network: ^0.2.3+4 # 网络通信基础 + basic_modular: ^0.2.3 # 模块化框架 + basic_modular_route: ^0.2.1 # 路由管理 + basic_intl_flutter: ^0.2.2+1 # 国际化支持 + basic_theme_core: ^0.2.5 # 主题核心 + ui_basic_annotation: ^0.2.0 # UI框架注解 +``` + +#### UI和交互依赖 +```yaml +# UI组件和交互依赖 +dependencies: + provider: ^6.0.5 # 状态管理 + flutter_html: ^3.0.0-beta.2 # HTML富文本渲染 + badges: ^3.1.1 # 角标组件 + pull_to_refresh: ^2.0.0 # 上拉下拉刷新 + carousel_slider: ^4.2.1 # 轮播图组件 + cached_network_image: ^3.3.0 # 缓存网络图片 + flutter_svg: ^2.0.6 # SVG图片支持 + flutter_smart_dialog: ^4.9.1 # 智能对话框 + visibility_detector: ^0.4.0+2# 可见性检测 + fl_chart: ^0.x.x # 图表组件 +``` + +#### 多媒体和工具依赖 +```yaml +# 多媒体和工具依赖 +dependencies: + camera: ^0.10.5+2 # 相机功能 + image_picker: ^1.1.2 # 图片选择 + image_cropper: ^9.1.0 # 图片裁剪 + flutter_image_compress: ^2.0.3# 图片压缩 + flutter_scankit: 2.0.3+1 # 扫码工具 + url_launcher: ^6.1.11 # URL跳转 + flutter_rating_bar: ^4.0.1 # 评分组件 + sprintf: ^7.0.0 # 字符串格式化 + dartz: ^0.10.1 # 函数式编程 + rxdart: ^0.27.7 # 响应式编程 +``` + +## 核心组件分析 + +### 1. 模块入口 (`ui_basic.dart`) + +基于真实项目的模块导出结构，包含大量第三方库集成和自定义组件。 + +**功能职责**: +- 统一导出所有UI组件和第三方库 +- 集成badge、cached_network_image、flutter_html等核心UI库 +- 导出自定义组件如OneColors、OneTextStyle、OneIcons +- 提供car_func_block等车辆相关UI组件 + +```dart +// 实际的模块导出结构（ui_basic.dart） +library ui_basic; + +// 第三方UI库集成 +export 'package:badges/badges.dart'; +export 'package:cached_network_image/cached_network_image.dart'; +export 'package:flutter_html/flutter_html.dart'; +export 'package:flutter_svg/flutter_svg.dart'; +export 'package:visibility_detector/visibility_detector.dart'; +export 'package:bottom_sheet/bottom_sheet.dart'; +export 'package:fl_chart/fl_chart.dart'; + +// 自定义组件导出 +export 'src/colors/colors.dart' show OneColors; +export 'src/fonts/fonts.dart' show OneTextStyle, TextFont, OneBasicText; +export 'src/icon/icon.dart' show OneIcons; + +// UI组件导出 +export 'src/components/appbar/common_title_bar.dart'; +export 'src/components/button/buttons.dart'; +export 'src/components/dialog/dialog_export.dart'; +export 'src/components/loading/loading_widget.dart'; +export 'src/components/text_field/basic_text_field.dart'; +export 'src/components/cards/cards_export.dart'; + +// 车辆功能组件 +export 'src/car_func_block/car_func_block_class.dart'; +export 'src/car_func_block/car_func_block_manager.dart'; + +// 工具类导出 +export 'src/utils/qr_scanner_util/qr_scanner_util.dart'; +export 'src/utils/image_util/image_util.dart'; +export 'src/utils/launcher/launch_util.dart'; +``` + +### 2. 主题颜色系统 (`src/colors/colors.dart`) + +基于主题核心框架的动态颜色系统，支持主题切换和自定义颜色。 + +```dart +// 实际的颜色系统实现 +class OneColors { + /// 主题色 Primary Color + static Color get primary => + theme.ofStandard().themeData?.appColors?.primary ?? + const Color(0xFFEED484); + + /// 背景色 Bgc + static Color get bgc => + theme.ofStandard().themeData?.appColors?.backgroundColors.bgc ?? + const Color(0xFFFFFFFF); + + /// 背景色 辅助1-5 + static Color get bgcSub1 => + theme.ofStandard().themeData?.appColors?.backgroundColors.bgcSub1 ?? + const Color(0xFFFFFFFF); + // ... 更多背景色变体 + + /// 动态主题获取 + static ITheme get theme => uiBasicPlatformInfoDeps.theme != null + ? uiBasicPlatformInfoDeps.theme! + : DefaultTheme( + DefaultStandardResource(), + DefaultUiKitResource(), + ); +} +``` + +### 4. 按钮组件 (`src/components/button/buttons.dart`) + +基于真实项目的按钮组件实现，支持多种按钮类型和状态管理。 + +```dart +// 实际的按钮状态枚举 +enum BtnLoadingStatus { + /// 初始化 + idle, + /// 加载中 + loading, +} + +/// 按钮类型枚举 +enum BtnType { + /// TextButton + text, + /// ElevatedButton + elevated, + /// OutlineButton + outline, +} + +/// 实际的图标按钮组件 +class OneIconButton extends StatelessWidget { + const OneIconButton({ + required this.child, + this.iconSize, + this.cubit, + this.onPress, + this.style, + Key? key, + }) : super(key: key); + + /// 按钮内容 + final Widget child; + /// 字体大小 + final double? iconSize; + /// 状态管理 + final OneIconButtonCubit? cubit; + /// 点击回调 + final VoidCallback? onPress; + /// 样式配置 + final ButtonStyle? style; + + @override + Widget build(BuildContext context) { + // 实际的按钮实现逻辑 + // 支持状态管理和样式定制 + } +} + +/// 通用按钮组件 +class CommonButton extends StatelessWidget { + // 支持加载状态、不同按钮类型、自定义样式等 + // 集成BLoC状态管理和主题系统 +} +``` + +### 5. 文本输入组件 (`src/components/text_field/`) + +包含多种文本输入组件的真实实现。 + +```dart +// 基础文本输入字段 +export 'src/components/text_field/basic_text_field.dart'; +export 'src/components/text_field/basic_multi_text_field.dart'; +export 'src/components/text_field/clear_text_field.dart'; +export 'src/components/text_field/edit_text/edit_text.dart'; + +// 特殊用途文本字段 +export 'src/components/text_field/vehicle_plate_field/vehicle_plate_field_widget.dart'; + +// 实际支持的功能： +// - 基础文本输入 +// - 多行文本输入 +// - 带清除按钮的文本输入 +// - 车牌号输入专用组件 +// - 集成表单验证和状态管理 +``` + +### 7. 第三方UI库集成 + +ui_basic模块集成了大量优秀的第三方UI库，提供开箱即用的功能。 + +```dart +// 图标和标记组件 +export 'package:badges/badges.dart'; // 角标组件 +export 'package:font_awesome_flutter/font_awesome_flutter.dart'; // FontAwesome图标 + +// 图片和多媒体 +export 'package:cached_network_image/cached_network_image.dart'; // 缓存网络图片 +export 'package:flutter_svg/flutter_svg.dart'; // SVG支持 +export 'package:dd_js_util/dd_js_util.dart'; // 九宫格图片选择 + +// 富文本和格式化 +export 'package:flutter_html/flutter_html.dart'; // HTML渲染 +export 'package:sprintf/sprintf.dart'; // 字符串格式化 +export 'package:auto_size_text/auto_size_text.dart'; // 自适应文本 + +// 交互组件 +export 'package:bottom_sheet/bottom_sheet.dart'; // 底部弹出框 +export 'package:visibility_detector/visibility_detector.dart'; // 可见性检测 +export 'package:extended_tabs/extended_tabs.dart'; // 扩展Tab组件 + +// 图表组件 +export 'package:fl_chart/fl_chart.dart'; // Flutter图表库 + +// 轮播组件 +export 'package:flutter_swiper_null_safety_flutter3/flutter_swiper_null_safety_flutter3.dart'; +``` + +### 8. 工具类组件 (`src/utils/`) + +丰富的工具类支持，涵盖图片处理、扫码、启动器等功能。 + +```dart +// 图片相关工具 +export 'src/utils/image_util/image_util.dart'; +export 'src/utils/image_solution/image_solution_tools.dart'; +export 'src/utils/image_cropper_util/nativate_image_cropper.dart'; + +// 扫码相关 +export 'src/utils/qr_processor/qr_processor.dart'; +export 'src/utils/qr_scanner_util/qr_scanner_util.dart'; + +// 系统交互 +export 'src/utils/launcher/launch_util.dart'; // URL启动器 +export 'src/utils/imm/custom_imm.dart'; // 输入法管理 + +// 订单管理 +export 'src/utils/order_category_manager/order_category_factory.dart'; +export 'src/utils/order_category_manager/order_category_manager.dart'; + +// 其他工具 +export 'src/utils/keep_alive.dart'; // KeepAlive包装器 +export 'src/utils/widget_utils.dart'; // Widget工具类 +export 'src/utils/methods.dart' show formatDate; // 格式化方法 +``` + +### 9. 特色组件 + +针对OneApp应用特点开发的专用组件。 + +```dart +// 车牌号相关 +export 'src/components/one_license_plate_number/one_license_plate_number.dart'; +export 'src/components/text_field/vehicle_plate_field/vehicle_plate_field_widget.dart'; + +// 车辆HVAC相关 +export 'src/components/widgets/car_hvac_other_widget.dart'; + +// 香氛组件 +export 'src/components/fragrance/fragrance_widget.dart'; + +// 步进器组件 +export 'src/components/stepper/stepper_widget.dart'; + +// 验证码组件 +export 'src/components/verification_code/verification_box.dart'; +export 'src/components/verification_code/code_widget.dart'; + +// 时间选择器 +export 'src/components/time_picker/common_time_picker.dart'; +export 'src/components/time_picker/ym_time_picker.dart'; + +// 可扩展GridView +export 'src/components/gridview/expandable_gridview.dart'; + +// 瀑布流ScrollView +export 'src/components/widgets/staggered_scrollview_widget.dart'; +export 'src/components/widgets/reorderable_staggered_scroll_view_widget.dart'; +``` + +## 性能优化 + +### 组件优化策略 +- **Widget缓存**: 缓存不变的Widget实例 +- **局部更新**: 使用Consumer精确控制更新范围 +- **延迟构建**: 使用Builder延迟构建复杂组件 +- **内存管理**: 及时释放资源和控制器 + +### 渲染优化 +- **RepaintBoundary**: 隔离重绘区域 +- **ListView.builder**: 使用懒加载列表 +- **Image优化**: 合理使用缓存和压缩 +- **动画优化**: 使用硬件加速动画 + +## 测试策略 + +### Widget测试 +- **组件渲染测试**: 验证组件正确渲染 +- **交互测试**: 测试用户交互响应 +- **主题测试**: 验证主题正确应用 +- **响应式测试**: 测试不同屏幕尺寸适配 + +### 单元测试 +- **工具类测试**: 测试工具方法功能 +- **状态管理测试**: 测试状态变化逻辑 +- **数据模型测试**: 测试数据序列化 + +## 最佳实践 + +### 组件设计原则 +1. **单一职责**: 每个组件功能单一明确 +2. **可复用性**: 设计通用的可复用组件 +3. **可配置性**: 提供丰富的配置选项 +4. **一致性**: 保持设计风格一致 + +### 使用建议 +1. **主题使用**: 优先使用主题颜色和样式 +2. **响应式设计**: 考虑不同屏幕尺寸适配 +3. **无障碍访问**: 添加语义标签和辅助功能 +4. **性能考虑**: 避免不必要的重建和重绘 + +## 总结 + +`ui_basic` 模块作为 OneApp 的基础UI组件库，提供了丰富的界面组件和交互元素。通过统一的设计语言、灵活的主题系统和完善的组件生态，为整个应用提供了一致的用户体验。模块具有良好的可扩展性和可维护性，能够满足各种界面开发需求。 diff --git a/basic_uis/ui_business.md b/basic_uis/ui_business.md new file mode 100644 index 0000000..7d64087 --- /dev/null +++ b/basic_uis/ui_business.md @@ -0,0 +1,549 @@ +# UI Business - 业务UI组件模块文档 + +## 模块概述 + +`ui_business` 是 OneApp 基础UI模块群中的业务UI组件库，提供与具体业务场景相关的UI组件和工具。该模块包含账户相关组件、订单相关组件、同意书组件等业务特定的界面元素和交互逻辑。 + +### 基本信息 +- **模块名称**: ui_business +- **模块路径**: oneapp_basic_uis/ui_business +- **类型**: Flutter Package Module +- **主要功能**: 业务UI组件、账户组件、订单组件、同意书组件 + +### 核心特性 +- **账户UI组件**: 提供登录、短信验证、证书拍照等账户相关UI +- **订单UI组件**: 订单相关的业务界面组件 +- **同意书组件**: 用户协议和同意书相关UI +- **国际化支持**: 支持中英文多语言 +- **表单验证**: 集成表单验证和数据处理 +- **路由守卫**: 业务路由保护和权限控制 + +## 目录结构 + +``` +ui_business/ +├── lib/ +│ ├── ui_account.dart # 账户相关组件导出 +│ ├── ui_order.dart # 订单相关组件导出 +│ ├── ui_consent.dart # 同意书相关组件导出 +│ ├── ui_common.dart # 通用业务组件导出 +│ ├── route_guard.dart # 路由守卫 +│ ├── customer_care.dart # 客服相关 +│ ├── poi_to_car.dart # POI到车功能 +│ ├── src/ # 源代码目录 +│ │ ├── ui_account/ # 账户相关组件 +│ │ │ ├── widgets/ # 账户UI组件 +│ │ │ │ ├── sms_auth/ # 短信验证组件 +│ │ │ │ ├── check_spin/ # 验证转动组件 +│ │ │ │ ├── certificates_photo/ # 证书拍照 +│ │ │ │ └── time_picker/ # 时间选择器 +│ │ │ ├── models/ # 账户数据模型 +│ │ │ ├── mgmt/ # 账户管理 +│ │ │ └── ui_config.dart # UI配置 +│ │ ├── ui_order/ # 订单相关组件 +│ │ └── constants/ # 常量定义 +│ ├── generated/ # 生成的国际化文件 +│ └── l10n/ # 国际化资源 +├── assets/ # 资源文件 +└── pubspec.yaml # 依赖配置 +``` + +## 核心架构组件 + +### 1. 短信验证组件 (SmsAuthWidget) + +提供短信验证码输入和验证功能的完整UI组件： + +```dart +/// 短信验证组件 +class SmsAuthWidget extends StatelessWidget { + /// 构造器 + /// + /// [verificationType] 验证码类型：1-登录注册 2-重置密码 3-设置/重置spin + /// [callback] 事件回调 + /// [formKey] 表单键 + /// [onSubmitBtnLockChanged] 确认按钮锁定回调 + /// [smsCallbackOverride] 覆盖默认操作 + /// [lockPhoneEdit] 是否锁定手机号修改 + SmsAuthWidget({ + required this.verificationType, + required this.formKey, + required this.callback, + required this.lockPhoneEdit, + this.onSubmitBtnLockChanged, + this.smsCallbackOverride, + Key? key, + }) : super(key: key); + + /// 默认超时时间 + static const defaultTimeout = 60; + + /// 类型：1-登录注册 2-重置密码 3-设置/重置spin + final String verificationType; + + /// 表单键 + final SmsAuthFormKey formKey; + + /// 结果回调 + final void Function(SmsAuthResult result) callback; + + /// 确认按钮锁定状态变化回调 + final OnSubmitBtnLockChanged? onSubmitBtnLockChanged; + + /// 短信校验覆盖回调 + final SmsCallbackOverride? smsCallbackOverride; + + /// 是否锁定手机号修改 + final bool lockPhoneEdit; + + @override + Widget build(BuildContext context) => BlocProvider( + create: (ctx) => _bloc = SmsAuthBloc(smsCallbackOverride) + ..add(const SmsAuthEvent.getLocalProfile()), + child: BlocConsumer( + listener: _pageListener, + builder: _createLayout, + ), + ); +} +``` + +### 2. 回调类型定义 + +```dart +/// 确认按钮锁定状态变化回调 +typedef OnSubmitBtnLockChanged = void Function(bool locked); + +/// 用于覆盖短信校验接口的回调 +typedef SmsCallbackOverride = Future Function( + PhoneNumber phone, + VerificationCode smsCode, +); +``` + +### 3. 手机号掩码扩展 + +```dart +extension _PhoneStringExtension on String { + /// 手机号掩码显示，中间4位用*替换 + String get maskPhone { + final buffer = StringBuffer(); + int i = 0; + for (final c in characters) { + if ([3, 4, 5, 6].contains(i)) { + buffer.write('*'); + } else { + buffer.write(c); + } + i++; + } + return buffer.toString(); + } +} +``` + +### 4. 通用项目组件 (ItemAComponent) + +来自general_ui_component模块的通用组件： + +```dart +/// 通用项目组件A +class ItemAComponent extends StatelessWidget { + ItemAComponent({ + required this.title, + required this.logoImg, + required this.onItemAClick, + required this.index, + this.size, + }); + + /// Logo图片URL + String logoImg = ''; + + /// 标题文本 + String title = ''; + + /// 点击回调 + OnItemAClick onItemAClick; + + /// 索引 + int index; + + /// 自定义尺寸 + double? size; + + @override + Widget build(BuildContext context) { + return InkWell( + highlightColor: Colors.transparent, + splashColor: Colors.transparent, + child: Column( + children: [ + Stack( + alignment: Alignment.center, + children: [ + Container( + width: width(designWidgetWidth: 48), + height: width(designWidgetWidth: 48), + decoration: BoxDecoration( + shape: BoxShape.circle, + color: OneColors.bgcSub2, + ), + ), + SizedBox( + height: size ?? width(designWidgetWidth: 40), + width: size ?? width(designWidgetWidth: 40), + child: CacheImageComponent( + imageUrl: logoImg, + ), + ), + ], + ), + Padding( + padding: EdgeInsets.only(top: 5.0), + child: Text( + title, + style: OneTextStyle.content( + color: const Color(0xFF7C7F81), + ), + ), + ) + ], + ), + onTap: () => onItemAClick(index), + ); + } +} + +typedef OnItemAClick = Function(int index); +``` + +## 使用指南 + +### 1. 短信验证组件使用 + +```dart +import 'package:ui_business/ui_account.dart'; + +class LoginPage extends StatefulWidget { + @override + _LoginPageState createState() => _LoginPageState(); +} + +class _LoginPageState extends State { + late SmsAuthFormKey _formKey; + bool _submitBtnLocked = true; + + @override + void initState() { + super.initState(); + _formKey = SmsAuthFormKey(); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('短信验证')), + body: Padding( + padding: EdgeInsets.all(16.0), + child: Column( + children: [ + SmsAuthWidget( + verificationType: '1', // 登录注册类型 + formKey: _formKey, + lockPhoneEdit: false, + callback: _handleSmsResult, + onSubmitBtnLockChanged: (locked) { + setState(() { + _submitBtnLocked = locked; + }); + }, + ), + SizedBox(height: 20), + ElevatedButton( + onPressed: _submitBtnLocked ? null : _handleSubmit, + child: Text('确认'), + ), + ], + ), + ), + ); + } + + void _handleSmsResult(SmsAuthResult result) { + switch (result.state) { + case SmsAuthResultEnum.success: + // 验证成功，处理登录逻辑 + print('验证成功，UUID: ${result.uuid}'); + Navigator.pushReplacementNamed(context, '/home'); + break; + case SmsAuthResultEnum.failed: + // 验证失败 + ScaffoldMessenger.of(context).showSnackBar( + SnackBar(content: Text('验证失败，请重试')), + ); + break; + } + } + + void _handleSubmit() { + // 触发表单验证和提交 + _formKey.controllerList.forEach((controller) => controller()); + } +} +``` + +### 2. 自定义短信验证回调 + +```dart +// 自定义短信验证逻辑 +Future customSmsVerification( + PhoneNumber phone, + VerificationCode smsCode +) async { + try { + // 调用自定义API进行验证 + final response = await MyApiService.verifySms( + phone: phone.value, + code: smsCode.value, + ); + return response.success; + } catch (e) { + print('短信验证异常: $e'); + return false; + } +} + +// 使用自定义验证回调 +SmsAuthWidget( + verificationType: '1', + formKey: _formKey, + lockPhoneEdit: false, + callback: _handleSmsResult, + smsCallbackOverride: customSmsVerification, // 使用自定义验证 +) +``` + +### 3. 通用组件列表使用 + +```dart +import 'package:general_ui_component/ItemAComponent.dart'; + +class ServiceListPage extends StatelessWidget { + final List services = [ + ServiceItem('充电服务', 'assets/images/charging.png'), + ServiceItem('维修保养', 'assets/images/maintenance.png'), + ServiceItem('道路救援', 'assets/images/rescue.png'), + ]; + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('服务列表')), + body: GridView.builder( + padding: EdgeInsets.all(16.0), + gridDelegate: SliverGridDelegateWithFixedCrossAxisCount( + crossAxisCount: 3, + childAspectRatio: 1.0, + crossAxisSpacing: 16.0, + mainAxisSpacing: 16.0, + ), + itemCount: services.length, + itemBuilder: (context, index) { + final service = services[index]; + return ItemAComponent( + title: service.name, + logoImg: service.iconUrl, + index: index, + onItemAClick: _handleServiceClick, + ); + }, + ), + ); + } + + void _handleServiceClick(int index) { + final service = services[index]; + print('点击了服务: ${service.name}'); + // 处理服务点击逻辑 + } +} +``` + +### 4. 国际化支持 + +```dart +import 'package:ui_business/generated/l10n.dart'; + +class LocalizedWidget extends StatelessWidget { + @override + Widget build(BuildContext context) { + return Column( + children: [ + Text(S.of(context).smsVerificationPage_hint_code), + Text(S.of(context).smsVerificationPage_btn_get), + ], + ); + } +} +``` + +## 依赖配置 + +### pubspec.yaml 关键依赖 + +```yaml +dependencies: + flutter: + sdk: flutter + + # 基础UI组件 + ui_basic: + path: ../ui_basic + + # 基础工具 + basic_utils: + path: ../../oneapp_basic_utils/basic_utils + + # 模块化路由 + basic_modular: + path: ../../oneapp_basic_utils/basic_modular + + # 账户服务 + clr_account: + path: ../../oneapp_account/clr_account + + # 状态管理 + flutter_bloc: ^8.0.0 + + # 国际化 + flutter_localizations: + sdk: flutter + intl: ^0.17.0 + +dev_dependencies: + # 国际化代码生成 + intl_utils: ^2.8.0 +``` + +## 国际化配置 + +### l10n/intl_zh.arb (中文) +```json +{ + "smsVerificationPage_hint_code": "请输入验证码", + "smsVerificationPage_btn_get": "获取验证码", + "smsVerificationsPage_error_invalidCode": "验证码格式不正确" +} +``` + +### l10n/intl_en.arb (英文) +```json +{ + "smsVerificationPage_hint_code": "Please enter verification code", + "smsVerificationPage_btn_get": "Get Code", + "smsVerificationsPage_error_invalidCode": "Invalid verification code format" +} +``` + +## 表单验证 + +### SmsAuthFormKey 使用 + +```dart +class CustomFormPage extends StatefulWidget { + @override + _CustomFormPageState createState() => _CustomFormPageState(); +} + +class _CustomFormPageState extends State { + late SmsAuthFormKey _formKey; + + @override + void initState() { + super.initState(); + _formKey = SmsAuthFormKey(); + } + + @override + Widget build(BuildContext context) { + return Form( + key: _formKey, + child: Column( + children: [ + // 表单字段 + ElevatedButton( + onPressed: () { + if (_formKey.validate()) { + _formKey.save(); + // 使用表单数据 + print('手机号: ${_formKey.phone}'); + print('短信码: ${_formKey.sms}'); + } + }, + child: Text('提交'), + ), + ], + ), + ); + } +} +``` + +## 最佳实践 + +### 1. 错误处理 +```dart +// 推荐：完整的错误处理 +void _handleSmsResult(SmsAuthResult result) { + switch (result.state) { + case SmsAuthResultEnum.success: + // 成功处理 + _navigateToNextPage(result); + break; + case SmsAuthResultEnum.failed: + // 失败处理，显示用户友好的错误信息 + _showErrorMessage('验证失败，请检查验证码是否正确'); + break; + case SmsAuthResultEnum.timeout: + // 超时处理 + _showErrorMessage('验证超时，请重新获取验证码'); + break; + } +} +``` + +### 2. 资源管理 +```dart +// 推荐：及时释放资源 +@override +void dispose() { + _formKey.dispose(); + super.dispose(); +} +``` + +### 3. 无障碍支持 +```dart +// 推荐：添加语义标签 +Semantics( + label: '验证码输入框', + hint: '请输入6位数字验证码', + child: SmsAuthWidget( + // 配置参数 + ), +) +``` + +## 问题排查 + +### 常见问题 +1. **验证码收不到**: 检查手机号格式和网络连接 +2. **倒计时不工作**: 确认CountDownButton状态管理正确 +3. **国际化文本不显示**: 检查l10n配置和S.of(context)使用 + +### 调试技巧 +- 使用Flutter Inspector查看Widget树 +- 检查BLoC状态变化日志 +- 验证表单验证逻辑 + diff --git a/basic_utils/README.md b/basic_utils/README.md new file mode 100644 index 0000000..f2383d2 --- /dev/null +++ b/basic_utils/README.md @@ -0,0 +1,70 @@ +# Basic Utils 基础工具模块群 + +## 模块群概述 + +Basic Utils 模块群是 OneApp 的基础工具集合，提供了应用开发中必需的底层工具和通用组件。该模块群包含了网络通信、日志系统、配置管理、平台适配、推送服务等核心基础设施。 + +## 子模块列表 + +### 核心基础模块 +1. **[basic_network](./basic_network.md)** - 网络通信模块 +2. **[basic_logger](./basic_logger.md)** - 日志系统模块 +3. **[basic_config](./basic_config.md)** - 配置管理模块 +4. **[basic_platform](./basic_platform.md)** - 平台适配模块 +5. **[basic_push](./basic_push.md)** - 推送服务模块 +6. **[basic_utils](./basic_utils.md)** - 基础工具模块 + +### 架构框架模块 +7. **[base_mvvm](./base_mvvm.md)** - MVVM架构模块 + +### 下载和监控模块 +8. **[flutter_downloader](./flutter_downloader.md)** - 文件下载器模块 +9. **[kit_app_monitor](./kit_app_monitor.md)** - 应用监控工具包 + +### 第三方集成模块 +10. **[flutter_plugin_mtpush_private](./flutter_plugin_mtpush_private.md)** - 美团云推送插件 + +## 使用指南 + +### 基础依赖配置 +```yaml +dependencies: + basic_utils: + path: ../oneapp_basic_utils/basic_utils + basic_config: + path: ../oneapp_basic_utils/basic_config + basic_logger: + path: ../oneapp_basic_utils/basic_logger + basic_network: + path: ../oneapp_basic_utils/basic_network + basic_platform: + path: ../oneapp_basic_utils/basic_platform +``` + +### 初始化配置 +```dart +// 应用初始化时配置基础模块 +await BasicUtils.initialize(); +await BasicConfig.initialize(); +await BasicLogger.initialize(); +await BasicNetwork.initialize(); +await BasicPlatform.initialize(); +``` + +## 开发规范 + +### 模块设计原则 +1. **单一职责**: 每个模块只负责特定的功能领域 +2. **接口抽象**: 提供清晰的接口定义，隐藏实现细节 +3. **配置驱动**: 通过配置控制模块行为，提高灵活性 +4. **错误处理**: 统一的错误处理和日志记录机制 + +### 代码规范 +- 遵循 Dart 官方编码规范 +- 使用静态分析工具检查代码质量 +- 编写完整的单元测试和文档 +- 版本化管理和变更日志 + +## 总结 + +`oneapp_basic_utils` 模块群为 OneApp 提供了坚实的技术基础，通过模块化设计和统一抽象，实现了基础功能的复用和标准化。这些模块不仅支撑了当前的业务需求，也为未来的功能扩展提供了良好的基础架构。 diff --git a/basic_utils/base_mvvm.md b/basic_utils/base_mvvm.md new file mode 100644 index 0000000..d44c26b --- /dev/null +++ b/basic_utils/base_mvvm.md @@ -0,0 +1,504 @@ +# Base MVVM - 基础MVVM架构模块文档 + +## 模块概述 + +`base_mvvm` 是 OneApp 基础工具模块群中的MVVM架构基础模块，提供了完整的Model-View-ViewModel架构模式实现。该模块封装了状态管理、数据绑定、Provider模式等核心功能，为应用提供了统一的架构规范和基础组件。 + +### 基本信息 +- **模块名称**: base_mvvm +- **模块路径**: oneapp_basic_utils/base_mvvm +- **类型**: Flutter Package Module +- **主要功能**: MVVM架构基础、状态管理、数据绑定 + +### 核心特性 +- **状态管理**: 基于Provider的响应式状态管理 +- **视图状态**: 统一的页面状态管理(idle/busy/empty/error) +- **列表刷新**: 封装下拉刷新和上拉加载更多 +- **数据绑定**: 双向数据绑定支持 +- **错误处理**: 统一的错误类型和处理机制 +- **日志工具**: 集成日志记录功能 + +## 目录结构 + +``` +base_mvvm/ +├── lib/ +│ ├── base_mvvm.dart # 模块入口文件 +│ ├── provider/ # Provider相关 +│ │ ├── provider_widget.dart # Provider封装组件 +│ │ ├── view_state_model.dart # 视图状态模型 +│ │ ├── view_state_list_model.dart # 列表状态模型 +│ │ ├── view_state_refresh_list_model.dart # 刷新列表模型 +│ │ └── view_state.dart # 状态枚举定义 +│ ├── utils/ # 工具类 +│ │ ├── logs/ # 日志工具 +│ │ │ └── log_utils.dart +│ │ └── rxbus.dart # 事件总线 +│ └── widgets/ # 基础组件 +│ ├── glides/ # 图片组件 +│ │ └── glide_image_view.dart +│ └── refresh/ # 刷新组件 +│ └── base_easy_refresh.dart +└── pubspec.yaml # 依赖配置 +``` + +## 核心架构组件 + +### 1. 视图状态枚举 (ViewState) + +定义了应用中通用的页面状态： + +```dart +/// 页面状态类型 +enum ViewState { + idle, // 空闲状态 + busy, // 加载中 + empty, // 无数据 + error, // 加载失败 +} + +/// 错误类型 +enum ViewStateErrorType { + none, + defaultError, + networkTimeOutError, // 网络超时 + disconnectException, // 断网 + noNetworkSignal, // 无网络信号 +} +``` + +### 2. 基础视图状态模型 (ViewStateModel) + +所有ViewModel的基础类，提供统一的状态管理： + +```dart +class ViewStateModel with ChangeNotifier { + /// 防止页面销毁后异步任务才完成导致报错 + bool _disposed = false; + + /// 当前页面状态，默认为idle + ViewState _viewState = ViewState.idle; + + /// 错误类型 + ViewStateErrorType _viewStateError = ViewStateErrorType.none; + + /// 构造函数，可指定初始状态 + ViewStateModel({ViewState? viewState}) + : _viewState = viewState ?? ViewState.idle; + + // 状态获取器 + ViewState get viewState => _viewState; + ViewStateErrorType get viewStateError => _viewStateError; + + // 状态判断方法 + bool get isBusy => viewState == ViewState.busy; + bool get isIdle => viewState == ViewState.idle; + bool get isEmpty => viewState == ViewState.empty; + bool get isError => viewState == ViewState.error; + + // 状态设置方法 + void setIdle() => viewState = ViewState.idle; + void setBusy() => viewState = ViewState.busy; + void setEmpty() => viewState = ViewState.empty; + + @override + void notifyListeners() { + if (!_disposed) { + super.notifyListeners(); + } + } + + @override + void dispose() { + _disposed = true; + super.dispose(); + } +} +``` + +### 3. Provider封装组件 (ProviderWidget) + +简化Provider使用的封装组件： + +```dart +class ProviderWidget extends StatefulWidget { + final ValueWidgetBuilder builder; + final T model; + final Widget? child; + final Function(T model)? onModelReady; + final bool autoDispose; + + const ProviderWidget({ + super.key, + required this.builder, + required this.model, + this.child, + this.onModelReady, + this.autoDispose = true + }); + + @override + _ProviderWidgetState createState() => _ProviderWidgetState(); +} + +class _ProviderWidgetState + extends State> { + late T model; + + @override + void initState() { + model = widget.model; + widget.onModelReady?.call(model); + super.initState(); + } + + @override + void dispose() { + if (widget.autoDispose) { + model.dispose(); + } + super.dispose(); + } + + @override + Widget build(BuildContext context) { + return ChangeNotifierProvider.value( + value: model, + child: Consumer(builder: widget.builder, child: widget.child) + ); + } +} +``` + +### 4. 多Provider支持 (ProviderWidget2) + +支持同时管理两个Model的组件： + +```dart +class ProviderWidget2 + extends StatefulWidget { + final Widget Function(BuildContext context, A model1, B model2, Widget? child) builder; + final A model1; + final B model2; + final Widget? child; + final Function(A model1, B model2)? onModelReady; + final bool autoDispose; + + // ... 实现与ProviderWidget类似，支持双Model管理 +} +``` + +### 5. 刷新列表状态模型 (ViewStateRefreshListModel) + +专门用于处理列表数据的刷新和加载更多功能： + +```dart +abstract class ViewStateRefreshListModel extends ViewStateListModel { + /// 分页配置 + static const int pageNumFirst = 1; + static const int pageSize = 10; + + /// 列表刷新控制器 + final EasyRefreshController _refreshController; + EasyRefreshController get refreshController => _refreshController; + + /// 当前页码 + int _currentPageNum = pageNumFirst; + + ViewStateRefreshListModel({super.viewState, bool isMore = true}) + : _refreshController = EasyRefreshController( + controlFinishLoad: isMore, + controlFinishRefresh: true); + + /// 下拉刷新 + @override + Future> refresh({bool init = false}) async { + try { + _currentPageNum = pageNumFirst; + var data = await loadData(pageNum: pageNumFirst); + refreshController.finishRefresh(); + + if (data.isEmpty) { + refreshController.finishLoad(IndicatorResult.none); + list.clear(); + setEmpty(); + } else { + onCompleted(data); + list.clear(); + list.addAll(data); + + // 小于分页数量时禁止上拉加载更多 + if (data.length < pageSize) { + Future.delayed(const Duration(milliseconds: 100)).then((value) { + refreshController.finishLoad(IndicatorResult.noMore); + }); + } + setIdle(); + } + return data; + } catch (e) { + if (init) list.clear(); + refreshController.finishLoad(IndicatorResult.fail); + setEmpty(); + return []; + } + } + + /// 上拉加载更多 + Future> loadMore() async { + try { + var data = await loadData(pageNum: ++_currentPageNum); + refreshController.finishRefresh(); + + if (data.isEmpty) { + _currentPageNum--; + refreshController.finishLoad(IndicatorResult.noMore); + } else { + onCompleted(data); + list.addAll(data); + + if (data.length < pageSize) { + refreshController.finishLoad(IndicatorResult.noMore); + } else { + refreshController.finishLoad(); + } + notifyListeners(); + } + return data; + } catch (e) { + _currentPageNum--; + refreshController.finishLoad(IndicatorResult.fail); + return []; + } + } + + /// 抽象方法：加载数据 + @override + Future> loadData({int? pageNum}); + + @override + void dispose() { + _refreshController.dispose(); + super.dispose(); + } +} +``` + +## 使用指南 + +### 1. 基础ViewModel示例 + +创建一个继承ViewStateModel的ViewModel： + +```dart +class UserProfileViewModel extends ViewStateModel { + UserInfo? _userInfo; + UserInfo? get userInfo => _userInfo; + + Future loadUserProfile(String userId) async { + setBusy(); // 设置加载状态 + + try { + _userInfo = await userRepository.getUserProfile(userId); + setIdle(); // 设置空闲状态 + } catch (e) { + setError(); // 设置错误状态 + } + } +} +``` + +### 2. 在UI中使用ProviderWidget + +```dart +class UserProfilePage extends StatelessWidget { + @override + Widget build(BuildContext context) { + return ProviderWidget( + model: UserProfileViewModel(), + onModelReady: (model) => model.loadUserProfile("123"), + builder: (context, model, child) { + if (model.isBusy) { + return Center(child: CircularProgressIndicator()); + } + + if (model.isEmpty) { + return Center(child: Text('暂无数据')); + } + + if (model.isError) { + return Center(child: Text('加载失败')); + } + + return Column( + children: [ + Text(model.userInfo?.name ?? ''), + Text(model.userInfo?.email ?? ''), + ], + ); + }, + ); + } +} +``` + +### 3. 列表刷新示例 + +```dart +class NewsListViewModel extends ViewStateRefreshListModel { + final NewsRepository _repository = NewsRepository(); + + @override + Future> loadData({int? pageNum}) async { + return await _repository.getNewsList( + page: pageNum ?? 1, + pageSize: ViewStateRefreshListModel.pageSize, + ); + } +} + +// UI使用 +class NewsListPage extends StatelessWidget { + @override + Widget build(BuildContext context) { + return ProviderWidget( + model: NewsListViewModel(), + onModelReady: (model) => model.refresh(init: true), + builder: (context, model, child) { + return EasyRefresh( + controller: model.refreshController, + onRefresh: () => model.refresh(), + onLoad: () => model.loadMore(), + child: ListView.builder( + itemCount: model.list.length, + itemBuilder: (context, index) { + final item = model.list[index]; + return ListTile( + title: Text(item.title), + subtitle: Text(item.summary), + ); + }, + ), + ); + }, + ); + } +} +``` + +### 4. 双Model管理示例 + +```dart +class DashboardPage extends StatelessWidget { + @override + Widget build(BuildContext context) { + return ProviderWidget2( + model1: UserViewModel(), + model2: NotificationViewModel(), + onModelReady: (userModel, notificationModel) { + userModel.loadUserInfo(); + notificationModel.loadNotifications(); + }, + builder: (context, userModel, notificationModel, child) { + return Scaffold( + body: Column( + children: [ + // 用户信息区域 + if (userModel.isBusy) + CircularProgressIndicator() + else + UserInfoWidget(user: userModel.currentUser), + + // 通知区域 + if (notificationModel.isBusy) + CircularProgressIndicator() + else + NotificationListWidget(notifications: notificationModel.notifications), + ], + ), + ); + }, + ); + } +} +``` + +## 依赖配置 + +### pubspec.yaml 关键依赖 + +```yaml +dependencies: + flutter: + sdk: flutter + + # 状态管理 + provider: ^6.0.0 + + # 列表刷新 + easy_refresh: ^3.0.0 + + # 日志记录 + # (自定义日志工具类) + +dev_dependencies: + flutter_test: + sdk: flutter +``` + +## 最佳实践 + +### 1. ViewModel设计原则 +- 继承ViewStateModel获得基础状态管理能力 +- 将业务逻辑封装在ViewModel中，保持View的简洁 +- 合理使用状态枚举，提供良好的用户体验反馈 +- 及时释放资源，避免内存泄漏 + +### 2. 错误处理策略 +- 使用ViewStateErrorType枚举区分不同错误类型 +- 在UI层根据错误类型提供相应的用户提示 +- 网络错误提供重试机制 + +### 3. 列表优化建议 +- 使用ViewStateRefreshListModel处理列表数据 +- 合理设置分页大小，平衡性能和用户体验 +- 实现适当的缓存策略减少不必要的网络请求 + +### 4. 内存管理 +- ProviderWidget默认开启autoDispose，自动管理Model生命周期 +- 在Model的dispose方法中清理定时器、流订阅等资源 +- 避免在已销毁的Model上调用notifyListeners + +## 扩展开发 + +### 1. 自定义状态类型 +可以扩展ViewState枚举添加业务特定的状态： + +```dart +enum CustomViewState { + idle, + busy, + empty, + error, + networkError, // 自定义网络错误状态 + authRequired, // 自定义需要认证状态 +} +``` + +### 2. 自定义刷新组件 +基于base_mvvm的基础组件，可以创建适合特定业务场景的刷新组件。 + +### 3. 状态持久化 +结合SharedPreferences等持久化方案，实现ViewState的持久化存储。 + +## 问题排查 + +### 常见问题 +1. **Model未正确释放**: 检查ProviderWidget的autoDispose设置 +2. **状态更新无效**: 确认notifyListeners调用时机 +3. **列表刷新异常**: 检查EasyRefreshController的状态管理 + +### 调试技巧 +- 使用LogUtils记录关键状态变更 +- 通过ViewState枚举值判断当前页面状态 +- 利用Flutter Inspector查看Provider状态 diff --git a/basic_utils/basic_config.md b/basic_utils/basic_config.md new file mode 100644 index 0000000..5f6fce0 --- /dev/null +++ b/basic_utils/basic_config.md @@ -0,0 +1,513 @@ +# Basic Config - 基础配置管理模块文档 + +## 模块概述 + +`basic_config` 是 OneApp 基础工具模块群中的配置管理模块，提供了应用配置的统一管理、API服务管控、版本控制等功能。该模块采用领域驱动设计(DDD)架构，支持动态配置更新、服务白名单管理和API访问控制。 + +### 基本信息 +- **模块名称**: basic_config +- **模块路径**: oneapp_basic_utils/basic_config +- **类型**: Flutter Package Module +- **架构模式**: DDD (Domain Driven Design) +- **主要功能**: 配置管理、API服务管控、版本管理 + +### 核心特性 +- **API服务管控**: 基于正则表达式的API路径匹配和访问控制 +- **服务白名单**: 支持白名单机制，允许特定服务绕过管控 +- **动态配置更新**: 支持运行时更新服务规则列表 +- **版本管理**: 内置版本比较和管理功能 +- **缓存优化**: 使用LRU缓存提升查询性能 +- **项目隔离**: 支持多项目代码隔离的配置管理 + +## 目录结构 + +``` +basic_config/ +├── lib/ +│ ├── basic_config.dart # 模块入口文件 +│ └── src/ +│ ├── constants/ # 常量定义 +│ │ └── module_constant.dart +│ ├── dependency/ # 依赖注入 +│ │ └── i_config_deps.dart +│ ├── domains/ # 领域层 +│ │ ├── basic_config_facade.dart # 配置门面服务 +│ │ ├── entities/ # 实体对象 +│ │ │ ├── config_service_failures.dart +│ │ │ ├── config_versions.dart +│ │ │ └── project_services.dart +│ │ ├── interfaces/ # 接口定义 +│ │ │ └── app_api_services_interface.dart +│ │ └── value_objects/ # 值对象 +│ │ └── project_code.dart +│ └── infrastructure/ # 基础设施层 +│ └── repositories/ +│ └── app_api_seervices_repository.dart +└── pubspec.yaml # 依赖配置 +``` + +## 核心架构组件 + +### 1. 版本管理 (Version) + +提供语义化版本号的解析和比较功能： + +```dart +mixin Version { + /// 转成字符串格式 + String get toStr => '$major.$minor.$revision'; + + /// 版本比较 - 大于 + bool greaterThan(Version other) { + if (major > other.major) return true; + if (minor > other.minor && major == other.major) return true; + if (revision > other.revision && + major == other.major && + minor == other.minor) return true; + return false; + } + + /// 主版本号 + int get major; + /// 次版本号 + int get minor; + /// 修订版本号 + int get revision; + + @override + String toString() => toStr; + + /// 解析版本字符串 (格式: x.x.x) + static Version parseFrom(String versionStr) { + final split = versionStr.split('.'); + if (split.length != 3) { + throw UnsupportedError('parse version From $versionStr failed'); + } + + final int major = int.parse(split[0]); + final int minor = int.parse(split[1]); + final int revision = int.parse(split[2]); + + return _VersionImpl(major, minor, revision); + } +} +``` + +### 2. 项目服务实体 (ProjectServicesDo) + +定义单个项目的服务配置信息： + +```dart +class ProjectServicesDo { + /// 构造函数 + /// [projectCode] 项目编号 + /// [ruleList] api path 正则规则 + /// [disableServiceList] 下架的服务列表 + ProjectServicesDo({ + required this.projectCode, + required this.ruleList, + required this.disableServiceList, + }) : _ruleListRegex = ruleList.map(RegExp.new).toList(growable: false); + + /// 项目编号 + final ProjectCodeVo projectCode; + + /// 该项目对应的规则列表 + final List ruleList; + + /// 对应正则表达式 + final List _ruleListRegex; + + /// 下架的服务 + final List disableServiceList; + + /// 检查路径是否匹配规则 + bool isMatchBy(String s) { + bool match = false; + for (final rule in _ruleListRegex) { + match = rule.hasMatch(s); + if (match) break; + } + return match; + } +} +``` + +### 3. 应用项目管理 (AppProjectsDo) + +管理所有项目的服务配置： + +```dart +class AppProjectsDo { + /// 构造函数 + AppProjectsDo(this.version, this.projects) { + for (final project in projects) { + _projectsMap[project.projectCode.id] = project; + } + } + + /// 版本号 + final int version; + + /// app所有项目的信息 + List projects; + + /// 项目映射表 + final Map _projectsMap = {}; + + /// 根据项目代码查找项目 + ProjectServicesDo? findBy(String projectCode) => _projectsMap[projectCode]; + + /// 检查服务是否已下架 + bool isServiceDisabled({ + required String projectCode, + required String service, + }) { + try { + final project = _projectsMap[projectCode]; + project!.disableServiceList.firstWhere((e) => e == service); + return true; + } catch (e) { + return false; + } + } + + /// 获取所有项目编号 + List getProjectCodes() => _projectsMap.keys.toList(growable: false); +} +``` + +### 4. 基础配置门面 (BasicConfigFacade) + +核心配置管理服务，采用单例模式： + +```dart +abstract class IBasicConfigFacade { + /// 初始化配置 + Future> initialize({ + required String versionOfConnectivity, + String jsonServiceList = '', + List whiteServiceList = const [], + IBasicConfigDeps? deps, + }); + + /// 检查API是否命中管控规则 + Either queryApiIfHit({ + String projectCode = '', + String url = '', + }); + + /// 检查API是否在白名单 + bool queryApiIfInWhiteList({required String url}); + + /// 主动更新服务规则列表 + Future updateServiceList({List projectCodes = const []}); + + /// 检查服务是否下架 + bool isServiceDisabled({ + required String projectCode, + required String service, + }); + + /// 根据项目代码查询项目信息 + Either queryProjectBy({ + String projectCode = '', + }); + + /// 获取当前连接版本 + Version get currConnVersion; +} + +/// 全局配置对象 +IBasicConfigFacade basicConfigFacade = BasicConfigFacadeImpl(); +``` + +### 5. 具体实现 (BasicConfigFacadeImpl) + +```dart +class BasicConfigFacadeImpl implements IBasicConfigFacade { + BasicConfigFacadeImpl({IAppApiServiceRepo? appApiServiceRepo}) + : _apiServiceRepo = appApiServiceRepo ?? ApiServiceListRepository(); + + static const String _tag = 'BasicConfigFacadeImpl'; + + final IAppApiServiceRepo _apiServiceRepo; + IBasicConfigDeps _deps = const DefaultConfigDeps(); + final _cache = LruCache(storage: InMemoryStorage(20)); + late Version _connVersion; + + @override + Future> initialize({ + required String versionOfConnectivity, + String jsonServiceList = '', + List whiteServiceList = const [], + IBasicConfigDeps? deps, + }) async { + if (deps != null) _deps = deps; + _connVersion = Version.parseFrom(versionOfConnectivity); + + // 初始化api管控配置列表 + final r = await _apiServiceRepo.initialize( + deps: _deps, + jsonServiceList: jsonServiceList, + whiteServiceList: whiteServiceList, + ); + + return r ? right(unit) : left(ConfigServiceFailures( + errorCodeConfigServiceInvalidLocalServiceList, + 'initialize failed', + )); + } + + @override + Either queryApiIfHit({ + String projectCode = '', + String url = '', + }) { + final appProject = _apiServiceRepo.appProject; + if (appProject == null) { + return left(ConfigServiceFailures( + errorCodeConfigServiceEmptyServiceList, + 'empty service list', + )); + } + + final findBy = appProject.findBy(projectCode); + if (findBy == null) return right(false); + + // 使用缓存优化查询性能 + final hitCache = _cache.get(url); + if (hitCache == null) { + final matchBy = findBy.isMatchBy(url); + _cache.set(url, matchBy); + return right(matchBy); + } + + return right(hitCache); + } + + // 其他方法实现... +} +``` + +## 使用指南 + +### 1. 初始化配置 + +```dart +import 'package:basic_config/basic_config.dart'; + +// 初始化基础配置 +await basicConfigFacade.initialize( + versionOfConnectivity: '1.0.0', + jsonServiceList: jsonConfigData, + whiteServiceList: ['api/health', 'api/version'], +); +``` + +### 2. API访问控制 + +```dart +// 检查API是否命中管控规则 +final result = basicConfigFacade.queryApiIfHit( + projectCode: 'oneapp_main', + url: '/api/user/profile', +); + +result.fold( + (failure) => print('查询失败: ${failure.message}'), + (isHit) => { + if (isHit) { + print('API被管控，需要特殊处理') + } else { + print('API正常访问') + } + }, +); +``` + +### 3. 白名单检查 + +```dart +// 检查API是否在白名单 +bool inWhiteList = basicConfigFacade.queryApiIfInWhiteList( + url: '/api/health' +); + +if (inWhiteList) { + // 白名单API，直接放行 + print('白名单API，允许访问'); +} +``` + +### 4. 服务状态检查 + +```dart +// 检查服务是否下架 +bool isDisabled = basicConfigFacade.isServiceDisabled( + projectCode: 'oneapp_main', + service: 'user_profile', +); + +if (isDisabled) { + // 服务已下架，显示维护页面 + showMaintenancePage(); +} +``` + +### 5. 动态更新配置 + +```dart +// 更新服务规则列表 +bool updateSuccess = await basicConfigFacade.updateServiceList( + projectCodes: ['oneapp_main', 'oneapp_car'], +); + +if (updateSuccess) { + print('配置更新成功'); +} +``` + +### 6. 版本管理 + +```dart +// 版本解析和比较 +Version currentVersion = Version.parseFrom('1.2.3'); +Version newVersion = Version.parseFrom('1.2.4'); + +if (newVersion.greaterThan(currentVersion)) { + print('发现新版本: ${newVersion.toStr}'); + // 执行更新逻辑 +} +``` + +## 配置文件格式 + +### 服务配置JSON格式 + +```json +{ + "version": 1, + "projects": [ + { + "projectCode": "oneapp_main", + "ruleList": [ + "^/api/user/.*", + "^/api/payment/.*" + ], + "disableServiceList": [ + "old_payment_service", + "deprecated_user_api" + ] + }, + { + "projectCode": "oneapp_car", + "ruleList": [ + "^/api/vehicle/.*", + "^/api/charging/.*" + ], + "disableServiceList": [] + } + ] +} +``` + +## 依赖配置 + +### pubspec.yaml 关键依赖 + +```yaml +dependencies: + flutter: + sdk: flutter + + # 函数式编程支持 + dartz: ^0.10.1 + + # 基础日志模块 + basic_logger: + path: ../basic_logger + + # 基础存储模块 + basic_storage: + path: ../basic_storage + +dev_dependencies: + flutter_test: + sdk: flutter +``` + +## 架构设计原则 + +### 1. DDD分层架构 +- **Domain层**: 包含业务实体、值对象和领域服务 +- **Infrastructure层**: 处理数据持久化和外部服务调用 +- **Application层**: 通过Facade模式提供应用服务 + +### 2. 函数式编程 +- 使用`dartz`包提供的`Either`类型处理错误 +- 避免异常抛出，通过类型系统表达可能的失败情况 + +### 3. 依赖注入 +- 通过接口定义依赖，支持测试替换 +- 使用抽象类定义服务边界 + +## 性能优化 + +### 1. 缓存策略 +- 使用LRU缓存存储API匹配结果 +- 缓存大小限制为20个条目，避免内存过度使用 + +### 2. 正则表达式优化 +- 预编译正则表达式，避免重复编译开销 +- 使用不可变列表存储编译后的正则 + +### 3. 查询优化 +- 使用Map结构优化项目查找性能 +- 短路求值减少不必要的匹配操作 + +## 最佳实践 + +### 1. 错误处理 +```dart +// 推荐：使用Either处理可能的错误 +final result = basicConfigFacade.queryApiIfHit( + projectCode: projectCode, + url: url, +); + +result.fold( + (failure) => handleFailure(failure), + (success) => handleSuccess(success), +); + +// 不推荐：使用try-catch +try { + final result = riskyOperation(); + handleSuccess(result); +} catch (e) { + handleError(e); +} +``` + +### 2. 配置管理 +- 在应用启动时初始化配置 +- 定期检查和更新远程配置 +- 为关键服务提供降级策略 + +### 3. 测试策略 +- 使用依赖注入进行单元测试 +- 模拟网络请求测试异常情况 +- 验证缓存行为的正确性 + +## 问题排查 + +### 常见问题 +1. **初始化失败**: 检查配置JSON格式和依赖注入设置 +2. **正则匹配异常**: 验证规则列表中的正则表达式语法 +3. **缓存不生效**: 确认URL格式一致性 + +### 调试技巧 +- 启用详细日志查看配置加载过程 +- 使用`basicConfigTag`过滤相关日志 +- 检查版本解析是否符合x.x.x格式 diff --git a/basic_utils/basic_logger.md b/basic_utils/basic_logger.md new file mode 100644 index 0000000..96413b1 --- /dev/null +++ b/basic_utils/basic_logger.md @@ -0,0 +1,445 @@ +# Basic Logger - 日志系统模块文档 + +## 模块概述 + +`basic_logger` 是 OneApp 基础工具模块群中的日志系统核心模块，提供统一的日志记录、管理和分析功能。该模块支持多级别日志、文件存储、网络上传、事件打点等功能，并提供了 Android 和 iOS 的原生日志监控能力。 + +### 基本信息 +- **模块名称**: basic_logger +- **模块路径**: oneapp_basic_utils/basic_logger +- **类型**: Flutter Plugin Module +- **主要功能**: 日志记录、事件打点、文件上传、原生日志监控 + +### 核心特性 +- **多级别日志**: 支持debug、info、warn、error四个级别 +- **业务标签**: 预定义车联网、账户、充电等业务场景标签 +- **文件记录**: 支持日志文件记录和轮转机制 +- **网络上传**: 支持日志文件网络上传功能 +- **事件打点**: 专门的事件日志记录能力 +- **原生监控**: Android/iOS原生日志监控和采集 +- **性能优化**: 支持日志级别过滤和调试开关 + +## 目录结构 + +``` +basic_logger/ +├── lib/ +│ ├── basic_logger.dart # 模块入口文件 +│ ├── logcat_monitor.dart # 原生日志监控 +│ ├── kit_logger_ios.dart # iOS特定实现 +│ └── src/ # 源代码目录 +│ ├── event_log/ # 事件日志 +│ │ └── one_event_log.dart +│ ├── function/ # 核心功能 +│ │ └── one_app_log.dart # 主日志类 +│ ├── model/ # 数据模型 +│ │ ├── upload_config.dart +│ │ └── upload_file_info.dart +│ ├── record/ # 记录功能 +│ │ ├── core.dart +│ │ ├── record_delegate.dart +│ │ └── impl_dart/ +│ │ ├── dart_record.dart +│ │ └── dart_file_record_.dart +│ └── upload/ # 上传功能 +│ ├── core.dart +│ └── upload_handler.dart +├── android/ # Android原生实现 +├── ios/ # iOS原生实现 +└── pubspec.yaml # 依赖配置 +``` + +## 核心架构组件 + +### 1. 日志级别枚举 (Level) + +定义应用日志的级别： + +```dart +/// Log Level +enum Level { + /// none - 无日志 + none, + /// info - 信息日志 + info, + /// debug - 调试日志 + debug, + /// warn - 警告日志 + warn, + /// error - 错误日志 + error, +} +``` + +### 2. 主日志类 (OneAppLog) + +应用日志的核心实现类： + +```dart +/// application层：日志 +class OneAppLog { + OneAppLog._(); + + /// logger flag + static const int loggerFlag = 1; + static const String _defaultTag = 'default'; + + static bool _debuggable = false; + static Level _filterLevel = Level.none; + + /// 配置日志系统 + /// [debuggable] 调试开关 + /// [filterLevel] 日志过滤级别 + static void config({ + bool debuggable = false, + Level filterLevel = Level.none, + }) { + _debuggable = debuggable; + _filterLevel = filterLevel; + } + + /// info级别日志 + /// [msg] 日志内容 + /// [tag] 日志标签 + static void i(String msg, [String tag = _defaultTag]) { + if (Level.info.index > _filterLevel.index) { + _log(Level.info, msg, tag); + } + } + + /// debug级别日志 + /// [msg] 日志内容 + /// [tag] 日志标签 + static void d(String msg, [String tag = _defaultTag]) { + if (_debuggable && Level.debug.index > _filterLevel.index) { + _log(Level.debug, msg, tag); + } + } + + /// warn级别日志 + /// [msg] 日志内容 + /// [tag] 日志标签 + static void w(String msg, [String tag = _defaultTag]) { + if (Level.warn.index > _filterLevel.index) { + _log(Level.warn, msg, tag); + } + } + + /// error级别日志 + /// [msg] 日志内容 + /// [tag] 日志标签 + static void e(String msg, [String tag = _defaultTag]) { + _log(Level.error, msg, tag); + } + + /// 上传日志文件 + /// [fileName] 文件名，如果为空内部自动生成 + /// [handler] 上传处理器 + /// [config] 上传配置 + static Future upload( + String? fileName, + UploadHandler handler, + UploadConfig config, + ) => UploadManager().upload(fileName, handler, config); + + // 内部日志记录实现 + static void _log(Level level, String msg, String tag) { + final time = DateTime.now(); + final emoji = _levelEmojis[level]; + recordIns.record(loggerFlag, '$time: $emoji[$tag] $msg'); + } +} +``` + +### 3. 业务标签定义 + +为不同业务场景预定义的日志标签： + +```dart +/// App通用标签 +const tagApp = 'App'; // App全局日志 +const tagRoute = 'Route'; // 路由跳转 +const tagNetwork = 'Network'; // 网络请求 +const tagWebView = 'WebView'; // WebView相关 + +/// 业务标签 +const tagCommunity = 'Community'; // 社区功能 +const tagCarSale = 'CarSale'; // 汽车销售 +const tagAfterSale = 'AfterSale'; // 售后服务 +const tagMall = 'Mall'; // 商城 +const tagOrder = 'Order'; // 订单 +const tagMaintenance = 'Maintenance'; // 保养维护 + +/// 车联网标签 +const tagVehicleSDK = 'VehicleSDK'; // CEA/MM SDK +const tagAccount = 'Account'; // 账户系统 +const tagCarHome = 'CarHome'; // 爱车首页 +const tagMDK = 'MDK'; // MDK相关 +const tagRemoteControl = 'RemoteControl'; // 远程控制 +const tagHVAC = 'HVAC'; // 空调系统 +const tagCarFind = 'CarFind'; // 寻车功能 +const tag3DModel = '3DModel'; // 3D模型 +const tagRPA = 'RPA'; // RPA功能 +const tagCamera = 'Camera'; // 摄像头 +const tagIntelligentScene = 'IntelligentScene'; // 智能场景 +const tagRVS = 'RVS'; // 远程车辆状态 +const tagVUR = 'VUR'; // 用车报告 +const tagAvatar = 'Avatar'; // 虚拟形象 +const tagTouchGo = 'TouchGo'; // 小组件 +const tagFridge = 'Fridge'; // 冰箱 +const tagWallbox = 'Wallbox'; // 壁挂充电盒 +const tagOTA = 'OTA'; // 空中升级 +const tagCharging = 'Charging'; // 充电功能 +const tagMessage = 'Message'; // 通知消息 +``` + +### 4. 日志级别表情符号映射 + +```dart +final Map _levelEmojis = { + Level.debug: '🐛', + Level.info: '💡💡', + Level.warn: '⚠️⚠️⚠️', + Level.error: '❌❌❌', +}; +``` + +### 5. Logger类型别名 + +```dart +typedef Logger = OneAppLog; +``` + +## 使用指南 + +### 1. 日志系统初始化 + +```dart +import 'package:basic_logger/basic_logger.dart'; + +// 配置日志系统 +OneAppLog.config( + debuggable: true, // 开启调试模式 + filterLevel: Level.debug, // 设置过滤级别 +); +``` + +### 2. 基础日志记录 + +```dart +// 使用预定义标签 +OneAppLog.i('用户登录成功', tagAccount); +OneAppLog.d('调试信息：用户ID = 12345', tagAccount); +OneAppLog.w('网络请求超时，正在重试', tagNetwork); +OneAppLog.e('登录失败：用户名或密码错误', tagAccount); + +// 使用默认标签 +OneAppLog.i('应用启动完成'); +OneAppLog.e('未知错误发生'); +``` + +### 3. 车联网业务日志 + +```dart +// 车辆控制相关 +OneAppLog.i('开始远程启动车辆', tagRemoteControl); +OneAppLog.w('车辆锁定状态异常', tagVehicleSDK); +OneAppLog.e('空调控制指令失败', tagHVAC); + +// 充电相关 +OneAppLog.i('开始充电', tagCharging); +OneAppLog.w('充电桩连接不稳定', tagCharging); +OneAppLog.e('充电异常停止', tagCharging); + +// 3D模型相关 +OneAppLog.d('3D模型加载中', tag3DModel); +OneAppLog.i('3D模型渲染完成', tag3DModel); + +// 虚拟形象相关 +OneAppLog.i('虚拟形象初始化', tagAvatar); +OneAppLog.w('虚拟形象动画加载超时', tagAvatar); +``` + +### 4. 日志文件上传 + +```dart +// 创建上传配置 +final uploadConfig = UploadConfig( + serverUrl: 'https://api.example.com/logs', + apiKey: 'your_api_key', + timeout: Duration(seconds: 30), +); + +// 创建上传处理器 +final uploadHandler = CustomUploadHandler(); + +// 上传日志文件 +try { + final result = await OneAppLog.upload( + 'app_logs_20231201.log', + uploadHandler, + uploadConfig, + ); + + if (result.success) { + OneAppLog.i('日志上传成功', tagApp); + } else { + OneAppLog.e('日志上传失败: ${result.error}', tagApp); + } +} catch (e) { + OneAppLog.e('日志上传异常: $e', tagApp); +} +``` + +### 5. 条件日志记录 + +```dart +// 仅在调试模式下记录 +if (kDebugMode) { + OneAppLog.d('这是调试信息，仅开发时可见', tagApp); +} + +// 根据业务条件记录 +void onUserAction(String action) { + OneAppLog.i('用户执行操作: $action', tagApp); + + if (action == 'high_risk_operation') { + OneAppLog.w('用户执行高风险操作', tagApp); + } +} +``` + +## 依赖配置 + +### pubspec.yaml 配置 + +```yaml +dependencies: + flutter: + sdk: flutter + + # 基础日志模块 + basic_logger: + path: ../oneapp_basic_utils/basic_logger + +dev_dependencies: + flutter_test: + sdk: flutter +``` + +## 高级功能 + +### 1. 自定义上传处理器 + +```dart +class CustomUploadHandler extends UploadHandler { + @override + Future upload( + String filePath, + UploadConfig config + ) async { + // 实现自定义上传逻辑 + try { + // 发送HTTP请求上传文件 + final response = await http.post( + Uri.parse(config.serverUrl), + headers: {'Authorization': 'Bearer ${config.apiKey}'}, + body: await File(filePath).readAsBytes(), + ); + + if (response.statusCode == 200) { + return UploadFileResult.success(); + } else { + return UploadFileResult.failure('上传失败: ${response.statusCode}'); + } + } catch (e) { + return UploadFileResult.failure('上传异常: $e'); + } + } +} +``` + +### 2. 事件日志记录 + +```dart +import 'package:basic_logger/basic_logger.dart'; + +// 记录事件日志 +OneEventLog.record({ + 'event_type': 'user_click', + 'element_id': 'login_button', + 'timestamp': DateTime.now().millisecondsSinceEpoch, + 'user_id': '12345', +}); +``` + +### 3. 原生日志监控 + +```dart +import 'package:basic_logger/logcat_monitor.dart'; + +// 开启原生日志监控 +final monitor = LogcatMonitor(); +await monitor.startMonitoring(); + +// 停止监控 +await monitor.stopMonitoring(); +``` + +## 性能优化建议 + +### 1. 日志级别管理 +- 生产环境关闭debug日志：`debuggable: false` +- 设置合适的过滤级别：`filterLevel: Level.warn` +- 避免在循环中大量打印日志 + +### 2. 文件管理 +- 定期清理过期日志文件 +- 控制日志文件大小，避免占用过多存储空间 +- 使用日志轮转机制 + +### 3. 网络上传优化 +- 在WiFi环境下上传日志 +- 压缩日志文件减少网络开销 +- 实现上传失败重试机制 + +## 最佳实践 + +### 1. 标签使用规范 +```dart +// 推荐：使用预定义业务标签 +OneAppLog.i('充电状态更新', tagCharging); + +// 避免：使用无意义的标签 +OneAppLog.i('充电状态更新', 'test'); +``` + +### 2. 敏感信息保护 +```dart +// 推荐：脱敏处理 +OneAppLog.i('用户登录: ${userId.substring(0, 3)}***', tagAccount); + +// 避免：直接记录敏感信息 +OneAppLog.i('用户登录: $userPassword', tagAccount); +``` + +### 3. 错误日志详细性 +```dart +// 推荐：提供详细上下文 +OneAppLog.e('网络请求失败: $url, 状态码: $statusCode, 错误: $error', tagNetwork); + +// 避免：信息不足的错误日志 +OneAppLog.e('请求失败', tagNetwork); +``` + +## 问题排查 + +### 常见问题 +1. **日志不显示**: 检查debuggable配置和filterLevel设置 +2. **文件上传失败**: 确认网络权限和上传配置 +3. **性能影响**: 避免高频日志输出，合理设置日志级别 + +### 调试技巧 +- 使用Android Studio/Xcode查看原生日志 +- 通过文件系统检查日志文件生成 +- 监控应用内存使用避免日志系统影响性能 diff --git a/basic_utils/basic_network.md b/basic_utils/basic_network.md new file mode 100644 index 0000000..6991cda --- /dev/null +++ b/basic_utils/basic_network.md @@ -0,0 +1,854 @@ +# Basic Network - 网络通信模块文档 + +## 模块概述 + +`basic_network` 是 OneApp 基础工具模块群中的网络通信核心模块，基于 Dio 框架封装，提供统一的 HTTP 请求接口、拦截器机制、错误处理和日志记录功能。该模块为整个应用提供标准化的网络通信能力。 + +### 基本信息 +- **模块名称**: basic_network +- **版本**: 0.2.3+4 +- **仓库**: https://gitlab-rd0.maezia.com/eziahz/oneapp/ezia-oneapp-basic-network +- **Dart 版本**: >=2.17.0 <4.0.0 + +## 目录结构 + +``` +basic_network/ +├── lib/ +│ ├── basic_network.dart # 主导出文件 +│ ├── common_dos.dart # 通用数据对象 +│ ├── common_dtos.dart # 通用数据传输对象 +│ └── src/ # 源代码目录 +│ ├── client/ # HTTP 客户端实现 +│ ├── interceptors/ # 请求拦截器 +│ ├── models/ # 数据模型 +│ ├── exceptions/ # 异常定义 +│ └── utils/ # 工具类 +├── pubspec.yaml # 依赖配置 +└── README.md # 项目说明 +``` + +## 核心功能模块 + +### 1. HTTP 客户端封装 + +基于真实项目的网络引擎架构，使用工厂模式和依赖注入。 + +#### 网络引擎初始化 (`facade.dart`) +```dart +// 实际的网络引擎初始化 +bool initNetwork({NetworkEngineOption? option, NetworkLogOutput? networkLog}) => + NetworkEngineContext().init(option: option, networkLog: networkLog); + +/// 根据自定义option获取NetworkEngine +RequestApi customNetworkEngine(NetworkEngineOption option) => + RequestApi(NetworkEngineFactory.createBy(option)); + +/// 统一的请求接口 +Future request(RequestOptions requestOptions) async => + NetworkEngineContext.networkEngine.request(requestOptions); + +/// 带回调的请求方法 +Future requestWithCallback( + RequestOptions requestOptions, + RequestOnSuccessCallback onSuccess, + RequestOnErrorCallback onError, +) async { + try { + final res = await NetworkEngineContext.networkEngine.request( + requestOptions, + ); + onSuccess(res); + } on ErrorBase catch (e) { + onError(e); + } catch (e) { + logger.e(e); + onError(ErrorGlobalCommon(GlobalCommonErrorType.other, e)); + } +} +``` + +#### 默认网络引擎配置 (`common_options.dart`) +```dart +// 实际的默认网络引擎选项 +class DefaultNetworkEngineOption extends NetworkEngineOption { + final Headers _headers = Headers(); + + final BaseDtoResponseConvertor _baseDtoResponseConvertor = + const DefaultBaseJsonResponseConvertor(); + + final GlobalErrorBusinessFactory _globalBusinessErrorFactory = + defaultGlobalBusinessErrorFactory; + + @override + BaseDtoResponseConvertor get baseDtoConvertor => _baseDtoResponseConvertor; + + @override + String get baseUrl => ''; + + @override + Headers get headers => _headers; + + @override + List get interceptors => []; + + @override + ProxyConfig? get proxyConfig => null; + + @override + int get receiveTimeout => 10000; + + @override + int get retryTime => 3; + + @override + int get sendTimeout => 10000; + + @override + int get connectTimeout => 10000; + + @override + SslConfig? get sslConfig => null; + + @override + List get globalErrorHandlers => []; + + @override + GlobalErrorBusinessFactory get globalErrorBusinessFactory => + _globalBusinessErrorFactory; + + @override + bool get debuggable => false; + + @override + String get environment => 'sit'; + + @override + List get preRequestInterceptors => []; +} +``` + +#### RequestApi 类实现 +```dart +// 实际的请求API封装类 +class RequestApi { + RequestApi(this._engine); + + final NetworkEngine _engine; + + /// 异步请求，等待结果或抛出异常 + Future request(RequestOptions requestOptions) async => + _engine.request(requestOptions); + + /// 带回调的请求方法 + Future requestWithCallback( + RequestOptions requestOptions, + RequestOnSuccessCallback onSuccess, + RequestOnErrorCallback onError, + ) async { + try { + final res = await _engine.request(requestOptions); + onSuccess(res); + } on ErrorBase catch (e) { + onError(e); + } catch (e) { + logger.e(e); + onError(ErrorGlobalCommon(GlobalCommonErrorType.other, e)); + } + } + + /// 文件下载，带进度回调 + Future download({ + required dynamic savePath, + required RequestOptions options, + ProgressCallback? onReceiveProgress, + CancelToken? cancelToken, + }) => + _engine.download( + savePath: savePath, + options: options, + onReceiveProgress: onReceiveProgress, + cancelToken: cancelToken, + ); + + /// 文件上传，带进度回调 + Future upload({ + required RequestOptions options, + CancelToken? cancelToken, + ProgressCallback? onSendProgress, + }) => + _engine.upload( + options: options, + onSendProgress: onSendProgress, + cancelToken: cancelToken, + ); + + /// 获取当前引擎配置 + NetworkEngineOption get option => _engine.option; +} +``` + +### 2. 请求拦截器系统 + +#### 请求拦截器 +```dart +// 请求拦截器 +class RequestInterceptor extends Interceptor { + @override + void onRequest(RequestOptions options, RequestInterceptorHandler handler) { + // 添加公共请求头 + _addCommonHeaders(options); + + // 添加认证信息 + _addAuthenticationHeaders(options); + + // 添加设备信息 + _addDeviceInfo(options); + + // 请求签名 + _signRequest(options); + + super.onRequest(options, handler); + } + + void _addCommonHeaders(RequestOptions options) { + options.headers.addAll({ + 'User-Agent': _getUserAgent(), + 'Accept-Language': _getAcceptLanguage(), + 'X-Request-ID': _generateRequestId(), + 'X-Timestamp': DateTime.now().millisecondsSinceEpoch.toString(), + }); + } + + void _addAuthenticationHeaders(RequestOptions options) { + final token = AuthManager.instance.accessToken; + if (token != null) { + options.headers['Authorization'] = 'Bearer $token'; + } + } + + void _addDeviceInfo(RequestOptions options) { + options.headers.addAll({ + 'X-Device-ID': DeviceInfo.instance.deviceId, + 'X-App-Version': AppInfo.instance.version, + 'X-Platform': Platform.isAndroid ? 'android' : 'ios', + }); + } +} +``` + +#### 响应拦截器 +```dart +// 响应拦截器 +class ResponseInterceptor extends Interceptor { + @override + void onResponse(Response response, ResponseInterceptorHandler handler) { + // 统一响应格式处理 + _processCommonResponse(response); + + // 更新认证状态 + _updateAuthenticationStatus(response); + + // 缓存响应数据 + _cacheResponseIfNeeded(response); + + super.onResponse(response, handler); + } + + void _processCommonResponse(Response response) { + if (response.data is Map) { + final data = response.data as Map; + + // 检查业务状态码 + final code = data['code'] as int?; + final message = data['message'] as String?; + + if (code != null && code != 0) { + throw BusinessException(code, message ?? '业务处理失败'); + } + + // 提取实际数据 + if (data.containsKey('data')) { + response.data = data['data']; + } + } + } +} +``` + +#### 错误拦截器 +```dart +// 错误拦截器 +class ErrorInterceptor extends Interceptor { + @override + void onError(DioException err, ErrorInterceptorHandler handler) { + // 网络错误处理 + if (_isNetworkError(err)) { + _handleNetworkError(err); + } + + // 认证错误处理 + if (_isAuthenticationError(err)) { + _handleAuthenticationError(err); + } + + // 服务器错误处理 + if (_isServerError(err)) { + _handleServerError(err); + } + + // 请求重试机制 + if (_shouldRetry(err)) { + _retryRequest(err, handler); + return; + } + + super.onError(err, handler); + } + + bool _shouldRetry(DioException err) { + // 网络超时重试 + if (err.type == DioExceptionType.connectionTimeout || + err.type == DioExceptionType.receiveTimeout) { + return _getRetryCount(err) < 3; + } + + // 5xx 服务器错误重试 + if (err.response?.statusCode != null && + err.response!.statusCode! >= 500) { + return _getRetryCount(err) < 2; + } + + return false; + } + + Future _retryRequest( + DioException err, + ErrorInterceptorHandler handler, + ) async { + final retryCount = _getRetryCount(err) + 1; + final delay = Duration(seconds: retryCount * 2); + + await Future.delayed(delay); + + try { + final options = err.requestOptions; + options.extra['retry_count'] = retryCount; + + final response = await Dio().request( + options.path, + data: options.data, + queryParameters: options.queryParameters, + options: Options( + method: options.method, + headers: options.headers, + extra: options.extra, + ), + ); + + handler.resolve(response); + } catch (e) { + handler.next(err); + } + } +} +``` + +### 3. 数据传输对象 (DTOs) + +#### 通用响应模型 +```dart +// 通用 API 响应模型 +@freezed +class ApiResponse with _$ApiResponse { + const factory ApiResponse({ + required int code, + required String message, + T? data, + @JsonKey(name: 'request_id') String? requestId, + @JsonKey(name: 'timestamp') int? timestamp, + }) = _ApiResponse; + + factory ApiResponse.fromJson( + Map json, + T Function(Object?) fromJsonT, + ) => _$ApiResponseFromJson(json, fromJsonT); +} + +// 分页响应模型 +@freezed +class PagedResponse with _$PagedResponse { + const factory PagedResponse({ + required List items, + required int total, + required int page, + required int pageSize, + @JsonKey(name: 'has_more') required bool hasMore, + }) = _PagedResponse; + + factory PagedResponse.fromJson( + Map json, + T Function(Object?) fromJsonT, + ) => _$PagedResponseFromJson(json, fromJsonT); +} +``` + +#### 请求参数模型 +```dart +// 分页请求参数 +@freezed +class PageRequest with _$PageRequest { + const factory PageRequest({ + @Default(1) int page, + @Default(20) int pageSize, + String? sortBy, + @Default('desc') String sortOrder, + }) = _PageRequest; + + factory PageRequest.fromJson(Map json) => + _$PageRequestFromJson(json); +} + +// 搜索请求参数 +@freezed +class SearchRequest with _$SearchRequest { + const factory SearchRequest({ + required String keyword, + List? filters, + @Default(1) int page, + @Default(20) int pageSize, + }) = _SearchRequest; + + factory SearchRequest.fromJson(Map json) => + _$SearchRequestFromJson(json); +} +``` + +### 4. 错误处理系统 + +基于真实项目的多层次错误处理架构，包含全局错误、业务错误和自定义错误。 + +#### 错误基类定义 (`model/error.dart`) +```dart +// 实际的错误基类 +abstract class ErrorBase implements Exception { + /// 调用栈 + StackTrace? stackTrace; + + /// 错误消息 + String get errorMessage; +} + +/// 全局的错误基类 +abstract class ErrorGlobal extends ErrorBase {} + +/// 通用全局错误 +class ErrorGlobalCommon extends ErrorGlobal { + ErrorGlobalCommon( + this.errorType, + this._originalCause, { + this.httpCode, + this.response, + this.message, + }) { + stackTrace = StackTrace.current; + } + + /// 封装的原始error + final dynamic _originalCause; + + /// 错误类型 + final GlobalCommonErrorType errorType; + + /// http返回的值 + final int? httpCode; + + /// 返回的response + final HttpResponse? response; + + /// 返回的消息 + late String? message; + + /// 返回原始的错误原因，如DioError + dynamic get originalCause => _originalCause; + + @override + String get errorMessage => message ?? response?.statusMessage ?? ''; + + @override + String toString() => 'ErrorGlobalCommon{_originalCause: $_originalCause, ' + 'errorType: $errorType, httpCode: $httpCode, response: $response}'; +} + +/// 业务错误通用基类 +abstract class ErrorGlobalBusiness extends ErrorGlobal { + /// 业务错误码 + String get businessCode; + + @override + String get errorMessage; + + /// 错误配置 + Map get errorConfig; + + @override + String toString() => + 'ErrorGlobalBusiness{businessCode:$businessCode, message:$errorMessage}'; +} + +/// 自定义错误 +class ErrorCustom extends ErrorBase { + // 自定义错误实现 + // ... +} +``` + +#### 全局错误处理器 +```dart +// 错误工厂方法类型定义 +typedef GlobalErrorBusinessFactory = ErrorGlobalBusiness? Function( + BaseDtoModel model, +); + +typedef CustomErrorFactory = ErrorCustom? Function(BaseDtoModel model); + +// 全局错误处理流程 +// 在网络引擎中自动调用错误处理器链 +// 支持自定义全局错误处理器扩展 +``` + +#### 错误类型枚举 +```dart +// 全局通用错误类型 +enum GlobalCommonErrorType { + timeout, + noNetwork, + serverError, + parseError, + other, +} +``` + +### 5. 缓存机制 + +#### 请求缓存管理 +```dart +// 网络缓存管理器 +class NetworkCacheManager { + static final Map _cache = {}; + static const Duration defaultCacheDuration = Duration(minutes: 5); + + // 设置缓存 + static void setCache( + String key, + dynamic data, { + Duration? duration, + }) { + _cache[key] = CacheItem( + data: data, + timestamp: DateTime.now(), + duration: duration ?? defaultCacheDuration, + ); + } + + // 获取缓存 + static T? getCache(String key) { + final item = _cache[key]; + if (item == null) return null; + + if (item.isExpired) { + _cache.remove(key); + return null; + } + + return item.data as T?; + } + + // 清除缓存 + static void clearCache([String? key]) { + if (key != null) { + _cache.remove(key); + } else { + _cache.clear(); + } + } + + // 生成缓存键 + static String generateCacheKey( + String path, + Map? queryParameters, + ) { + final uri = Uri(path: path, queryParameters: queryParameters); + return uri.toString(); + } +} + +// 缓存项 +class CacheItem { + final dynamic data; + final DateTime timestamp; + final Duration duration; + + CacheItem({ + required this.data, + required this.timestamp, + required this.duration, + }); + + bool get isExpired => DateTime.now().difference(timestamp) > duration; +} +``` + +### 6. 请求配置管理 + +#### 环境配置 +```dart +// 网络环境配置 +enum NetworkEnvironment { + development, + testing, + staging, + production, +} + +class NetworkConfig { + final String baseUrl; + final Duration connectTimeout; + final Duration receiveTimeout; + final Duration sendTimeout; + final bool enableLogging; + final bool enableCache; + final int maxRetries; + + const NetworkConfig({ + required this.baseUrl, + this.connectTimeout = const Duration(seconds: 30), + this.receiveTimeout = const Duration(seconds: 30), + this.sendTimeout = const Duration(seconds: 30), + this.enableLogging = false, + this.enableCache = true, + this.maxRetries = 3, + }); + + // 开发环境配置 + static const NetworkConfig development = NetworkConfig( + baseUrl: 'https://dev-api.oneapp.com', + enableLogging: true, + enableCache: false, + ); + + // 测试环境配置 + static const NetworkConfig testing = NetworkConfig( + baseUrl: 'https://test-api.oneapp.com', + enableLogging: true, + ); + + // 生产环境配置 + static const NetworkConfig production = NetworkConfig( + baseUrl: 'https://api.oneapp.com', + enableLogging: false, + ); + + static NetworkConfig forEnvironment(NetworkEnvironment env) { + switch (env) { + case NetworkEnvironment.development: + return development; + case NetworkEnvironment.testing: + return testing; + case NetworkEnvironment.staging: + return testing; // 使用测试环境配置 + case NetworkEnvironment.production: + return production; + } + } +} +``` + +## 使用示例 + +基于实际项目的网络请求使用方法。 + +### 基本初始化和使用 +```dart +// 初始化网络库 +final option = DefaultNetworkEngineOption() + ..baseUrl = 'https://api.oneapp.com' + ..debuggable = true + ..environment = 'production'; + +// 初始化默认网络引擎 +initNetwork(option: option); + +// 直接使用全局方法发起请求 +try { + final response = await request( + RequestOptions( + path: '/users/profile', + method: 'GET', + ), + ); + print('用户信息: ${response.name}'); +} on ErrorBase catch (e) { + print('请求失败: ${e.errorMessage}'); +} +``` + +### 使用RequestApi +```dart +// 创建自定义网络引擎 +final customOption = DefaultNetworkEngineOption() + ..baseUrl = 'https://custom-api.com' + ..retryTime = 5 + ..connectTimeout = 15000; + +final api = customNetworkEngine(customOption); + +// 使用回调方式处理请求 +await api.requestWithCallback>( + RequestOptions( + path: '/articles', + method: 'GET', + queryParameters: {'page': 1, 'limit': 20}, + ), + (articles) { + print('获取到 ${articles.length} 篇文章'); + }, + (error) { + print('请求失败: ${error.errorMessage}'); + + // 处理特定类型的错误 + if (error is ErrorGlobalBusiness) { + print('业务错误码: ${error.businessCode}'); + } + }, +); +``` + +### 文件上传和下载 +```dart +// 文件上传 +final uploadResponse = await api.upload( + options: RequestOptions( + path: '/upload', + method: 'POST', + data: FormData.fromMap({ + 'file': await MultipartFile.fromFile('/path/to/file.jpg'), + 'description': '头像上传', + }), + ), + onSendProgress: (sent, total) { + final progress = (sent / total * 100).toStringAsFixed(1); + print('上传进度: $progress%'); + }, +); + +// 文件下载 +await download( + savePath: '/path/to/save/file.pdf', + options: RequestOptions( + path: '/download/document.pdf', + method: 'GET', + ), + onReceiveProgress: (received, total) { + final progress = (received / total * 100).toStringAsFixed(1); + print('下载进度: $progress%'); + }, +); +``` + +### 自定义配置示例 +```dart +// 创建带有自定义拦截器的配置 +class MyNetworkOption extends DefaultNetworkEngineOption { + @override + String get baseUrl => 'https://my-api.com'; + + @override + List get interceptors => [ + MyAuthInterceptor(), + MyLoggingInterceptor(), + ]; + + @override + List get globalErrorHandlers => [ + MyCustomErrorHandler(), + ]; + + @override + bool get debuggable => kDebugMode; + + @override + int get retryTime => 3; +} +``` + +## 依赖管理 + +基于实际的pubspec.yaml配置，展示真实的项目依赖关系。 + +### 核心依赖 +```yaml +# 实际项目依赖配置 +dependencies: + http_parser: ^4.0.2 # HTTP 解析工具 + dio: ^5.7.0 # HTTP 客户端库（核心） + pretty_dio_logger: ^1.3.1 # 美化的请求日志 + freezed_annotation: ^2.2.0 # 不可变类注解 + json_annotation: ^4.8.1 # JSON 序列化注解 + +dev_dependencies: + json_serializable: ^6.7.0 # JSON 序列化生成器 + build_runner: ^2.4.5 # 代码生成引擎 + test: ^1.24.3 # 单元测试框架 + coverage: ^1.6.3 # 测试覆盖率工具 + freezed: ^2.3.5 # 不可变类生成器 + flutter_lints: ^5.0.0 # 代码规范检查 +``` + +### 实际的版本信息 +- **模块名称**: basic_network +- **版本**: 0.2.3+4 +- **仓库**: https://gitlab-rd0.maezia.com/eziahz/oneapp/ezia-oneapp-basic-network +- **Dart 版本**: >=2.17.0 <4.0.0 + +## 性能优化 + +### 网络性能优化 +- 连接池复用 +- HTTP/2 支持 +- 请求合并和批处理 +- 智能重试机制 + +### 缓存优化 +- 多级缓存策略 +- 缓存过期管理 +- 条件请求支持 +- 离线缓存机制 + +### 内存优化 +- 流式数据处理 +- 大文件分块传输 +- 及时释放响应数据 +- 内存泄漏检测 + +## 测试策略 + +### 单元测试 +- 网络服务接口测试 +- 拦截器功能测试 +- 错误处理测试 +- 缓存机制测试 + +### 集成测试 +- 端到端请求测试 +- 网络环境切换测试 +- 错误恢复测试 + +### Mock 测试 +- 网络请求 Mock +- 错误场景模拟 +- 性能测试 + +## 总结 + +`basic_network` 模块为 OneApp 提供了强大而灵活的网络通信能力。通过统一的接口抽象、完善的错误处理、智能的缓存机制和丰富的拦截器功能，大大简化了网络请求的开发工作，提高了应用的稳定性和用户体验。模块的设计充分考虑了可扩展性和可维护性，为大型应用的网络通信提供了坚实的基础。 diff --git a/basic_utils/basic_platform.md b/basic_utils/basic_platform.md new file mode 100644 index 0000000..c228b5a --- /dev/null +++ b/basic_utils/basic_platform.md @@ -0,0 +1,494 @@ +# Basic Platform 平台适配模块 + +## 模块概述 + +`basic_platform` 是 OneApp 基础工具模块群中的平台适配模块，负责统一处理 Android 和 iOS 平台的差异性，提供跨平台的统一接口。该模块封装了设备信息获取、权限管理、平台特性检测等功能。 + +### 基本信息 +- **模块名称**: basic_platform +- **版本**: 0.2.14+1 +- **描述**: 跨平台适配基础模块 +- **Flutter 版本**: >=2.10.5 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 功能特性 + +### 核心功能 +1. **平台信息检测** + - 操作系统类型和版本 + - 设备型号和硬件信息 + - 应用版本和构建信息 + - 网络环境检测 + +2. **权限管理统一** + - 跨平台权限申请 + - 权限状态检查 + - 权限结果处理 + - 权限设置引导 + +3. **设备特性适配** + - 屏幕方向控制 + - 设备唤醒管理 + - 平台特定功能检测 + - 硬件能力查询 + +4. **存储路径管理** + - 应用目录获取 + - 缓存目录管理 + - 外部存储访问 + - 临时文件处理 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── basic_platform.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── platform_info/ # 平台信息 +│ ├── permissions/ # 权限管理 +│ ├── device/ # 设备功能 +│ ├── storage/ # 存储管理 +│ ├── models/ # 数据模型 +│ └── utils/ # 工具类 +├── android/ # Android特定代码 +├── ios/ # iOS特定代码 +└── test/ # 测试文件 +``` + +### 依赖关系 + +#### 核心依赖 +- `basic_storage: ^0.2.2` - 基础存储框架 +- `permission_handler: ^10.4.5` - 权限处理插件 +- `native_device_orientation: ^1.2.1` - 设备方向控制 + +## 核心模块分析 + +### 1. 模块入口 (`basic_platform.dart`) + +**功能职责**: +- 平台适配服务统一导出 +- 初始化配置管理 +- 单例模式实现 + +### 2. 平台信息 (`src/platform_info/`) + +**功能职责**: +- 操作系统信息获取 +- 设备硬件信息查询 +- 应用程序信息获取 +- 环境配置检测 + +**主要组件**: +- `PlatformInfo` - 平台信息管理器 +- `DeviceInfo` - 设备信息获取器 +- `AppInfo` - 应用信息管理器 +- `SystemInfo` - 系统信息收集器 + +### 3. 权限管理 (`src/permissions/`) + +**功能职责**: +- 统一权限申请接口 +- 权限状态查询 +- 权限结果回调处理 +- 权限设置页面跳转 + +**主要组件**: +- `PermissionManager` - 权限管理器 +- `PermissionChecker` - 权限检查器 +- `PermissionRequestor` - 权限申请器 +- `PermissionGuide` - 权限引导器 + +### 4. 设备功能 (`src/device/`) + +**功能职责**: +- 设备方向控制 +- 屏幕亮度管理 +- 震动反馈控制 +- 设备唤醒管理 + +**主要组件**: +- `OrientationController` - 方向控制器 +- `BrightnessController` - 亮度控制器 +- `HapticController` - 震动控制器 +- `WakeController` - 唤醒控制器 + +### 5. 存储管理 (`src/storage/`) + +**功能职责**: +- 应用目录路径获取 +- 外部存储访问 +- 临时文件管理 +- 缓存目录处理 + +**主要组件**: +- `StorageManager` - 存储管理器 +- `PathProvider` - 路径提供器 +- `DirectoryManager` - 目录管理器 +- `TempFileManager` - 临时文件管理器 + +### 6. 数据模型 (`src/models/`) + +**功能职责**: +- 平台信息数据模型 +- 权限状态模型 +- 设备特性模型 +- 配置参数模型 + +**主要模型**: +- `PlatformData` - 平台数据模型 +- `PermissionStatus` - 权限状态模型 +- `DeviceCapability` - 设备能力模型 +- `PlatformConfig` - 平台配置模型 + +### 7. 工具类 (`src/utils/`) + +**功能职责**: +- 平台判断工具 +- 版本比较工具 +- 路径处理工具 +- 异常处理工具 + +**主要工具**: +- `PlatformUtils` - 平台工具类 +- `VersionUtils` - 版本工具类 +- `PathUtils` - 路径工具类 +- `ExceptionUtils` - 异常工具类 + +## 平台适配实现 + +### Android 平台适配 + +#### 权限处理 +```dart +class AndroidPermissionHandler { + static Future requestPermission(Permission permission) async { + final status = await permission.request(); + + switch (status) { + case PermissionStatus.granted: + return true; + case PermissionStatus.denied: + return false; + case PermissionStatus.permanentlyDenied: + await openAppSettings(); + return false; + default: + return false; + } + } + + static Future> requestMultiple( + List permissions, + ) async { + return await permissions.request(); + } +} +``` + +#### 设备信息获取 +```dart +class AndroidDeviceInfo { + static Future getDeviceInfo() async { + final deviceInfo = DeviceInfoPlugin(); + final androidInfo = await deviceInfo.androidInfo; + + return AndroidDeviceData( + manufacturer: androidInfo.manufacturer, + model: androidInfo.model, + version: androidInfo.version.release, + sdkInt: androidInfo.version.sdkInt, + brand: androidInfo.brand, + product: androidInfo.product, + ); + } +} +``` + +### iOS 平台适配 + +#### 权限处理 +```dart +class IOSPermissionHandler { + static Future requestPermission(Permission permission) async { + final status = await permission.request(); + + if (status == PermissionStatus.denied || + status == PermissionStatus.permanentlyDenied) { + return await _showPermissionDialog(permission); + } + + return status == PermissionStatus.granted; + } + + static Future _showPermissionDialog(Permission permission) async { + // 显示权限说明对话框 + // 引导用户到设置页面 + return false; + } +} +``` + +#### 设备信息获取 +```dart +class IOSDeviceInfo { + static Future getDeviceInfo() async { + final deviceInfo = DeviceInfoPlugin(); + final iosInfo = await deviceInfo.iosInfo; + + return IOSDeviceData( + name: iosInfo.name, + model: iosInfo.model, + systemName: iosInfo.systemName, + systemVersion: iosInfo.systemVersion, + identifierForVendor: iosInfo.identifierForVendor, + isPhysicalDevice: iosInfo.isPhysicalDevice, + ); + } +} +``` + +## 业务流程 + +### 权限申请流程 +```mermaid +graph TD + A[应用请求权限] --> B[检查权限状态] + B --> C{权限是否已授予} + C -->|是| D[直接使用功能] + C -->|否| E[显示权限说明] + E --> F[请求系统权限] + F --> G{用户是否同意} + G -->|是| H[权限授予成功] + G -->|否| I{是否永久拒绝} + I -->|是| J[引导用户到设置] + I -->|否| K[记录拒绝状态] + H --> D + J --> L[用户手动设置] + K --> M[功能降级处理] + L --> N[重新检查权限] + N --> C +``` + +### 平台初始化流程 +```mermaid +graph TD + A[应用启动] --> B[初始化平台模块] + B --> C[检测平台类型] + C --> D[加载平台配置] + D --> E[初始化平台服务] + E --> F[注册权限监听器] + F --> G[设置默认配置] + G --> H[平台初始化完成] + H --> I[通知上层应用] +``` + +## 权限管理系统 + +### 支持的权限类型 +1. **基础权限** + - 网络访问权限 + - 存储读写权限 + - 设备信息访问 + - 应用安装权限 + +2. **隐私权限** + - 位置信息权限 + - 相机访问权限 + - 麦克风权限 + - 通讯录权限 + +3. **系统权限** + - 电话状态权限 + - 短信发送权限 + - 系统设置修改 + - 设备管理权限 + +### 权限管理策略 +- **最小权限原则**: 仅申请必要权限 +- **延迟申请**: 在需要时才申请权限 +- **用户友好**: 提供清晰的权限说明 +- **优雅降级**: 权限拒绝时的替代方案 + +## 设备适配策略 + +### 屏幕适配 +```dart +class ScreenAdapter { + static double getScaleFactor() { + final window = WidgetsBinding.instance.window; + return window.devicePixelRatio; + } + + static Size getScreenSize() { + final window = WidgetsBinding.instance.window; + return window.physicalSize / window.devicePixelRatio; + } + + static bool isTablet() { + final size = getScreenSize(); + final diagonal = sqrt(pow(size.width, 2) + pow(size.height, 2)); + return diagonal > 1100; // 7 inch threshold + } +} +``` + +### 性能优化 +```dart +class PerformanceOptimizer { + static bool isLowEndDevice() { + if (Platform.isAndroid) { + return _checkAndroidPerformance(); + } else if (Platform.isIOS) { + return _checkIOSPerformance(); + } + return false; + } + + static bool _checkAndroidPerformance() { + // 基于 Android 设备性能指标判断 + // RAM、CPU、GPU 等参数 + return false; + } + + static bool _checkIOSPerformance() { + // 基于 iOS 设备型号判断 + // 设备代数、处理器类型等 + return false; + } +} +``` + +## 存储路径管理 + +### 路径类型 +1. **应用目录** + - 应用私有目录 + - 文档目录 + - 库目录 + - 支持文件目录 + +2. **缓存目录** + - 临时缓存 + - 图片缓存 + - 数据缓存 + - 网络缓存 + +3. **外部存储** + - 公共文档目录 + - 下载目录 + - 图片目录 + - 媒体目录 + +### 路径获取接口 +```dart +class PlatformPaths { + static Future getApplicationDocumentsDirectory() async { + final directory = await getApplicationDocumentsDirectory(); + return directory.path; + } + + static Future getTemporaryDirectory() async { + final directory = await getTemporaryDirectory(); + return directory.path; + } + + static Future getExternalStorageDirectory() async { + if (Platform.isAndroid) { + final directory = await getExternalStorageDirectory(); + return directory?.path; + } + return null; + } +} +``` + +## 异常处理机制 + +### 异常类型 +1. **权限异常** + - 权限拒绝异常 + - 权限配置错误 + - 系统权限限制 + +2. **平台异常** + - 不支持的平台功能 + - API版本不兼容 + - 硬件功能缺失 + +3. **系统异常** + - 文件系统错误 + - 网络连接异常 + - 内存不足异常 + +### 异常处理策略 +- **异常捕获**: 全面的异常捕获机制 +- **错误恢复**: 自动错误恢复策略 +- **用户提示**: 友好的错误提示信息 +- **日志记录**: 详细的错误日志记录 + +## 测试策略 + +### 单元测试 +- **平台检测测试**: 平台类型识别 +- **权限管理测试**: 权限申请和状态 +- **路径获取测试**: 各种路径获取 +- **工具类测试**: 工具方法功能 + +### 集成测试 +- **跨平台兼容测试**: 不同平台功能 +- **权限流程测试**: 完整权限流程 +- **设备适配测试**: 不同设备适配 +- **性能测试**: 模块性能表现 + +### 兼容性测试 +- **系统版本兼容**: 不同系统版本 +- **设备型号兼容**: 不同设备型号 +- **权限策略兼容**: 不同权限策略 +- **API兼容性**: 不同API版本 + +## 配置管理 + +### 平台配置 +```dart +class PlatformConfig { + static const Map androidConfig = { + 'minSdkVersion': 21, + 'targetSdkVersion': 33, + 'requiredPermissions': [ + 'android.permission.INTERNET', + 'android.permission.ACCESS_NETWORK_STATE', + ], + }; + + static const Map iosConfig = { + 'minIOSVersion': '11.0', + 'requiredCapabilities': [ + 'arm64', + ], + 'privacyDescriptions': { + 'NSLocationWhenInUseUsageDescription': 'App needs location access', + 'NSCameraUsageDescription': 'App needs camera access', + }, + }; +} +``` + +## 最佳实践 + +### 开发建议 +1. **统一接口**: 使用统一的平台接口 +2. **异步处理**: 耗时操作异步执行 +3. **异常处理**: 完善的异常处理机制 +4. **性能考虑**: 避免频繁的平台调用 + +### 使用指南 +1. **权限申请**: 在合适的时机申请权限 +2. **平台检测**: 根据平台提供不同功能 +3. **路径使用**: 正确使用各种存储路径 +4. **错误处理**: 妥善处理平台相关错误 + +## 总结 + +`basic_platform` 模块作为 OneApp 的平台适配基础模块，为应用提供了统一的跨平台接口和能力。通过封装平台差异性、统一权限管理和完善的异常处理，显著简化了跨平台开发的复杂性。模块具有良好的扩展性和兼容性，能够适应不断变化的平台环境和需求。 diff --git a/basic_utils/basic_push.md b/basic_utils/basic_push.md new file mode 100644 index 0000000..cbe678e --- /dev/null +++ b/basic_utils/basic_push.md @@ -0,0 +1,735 @@ +# Basic Push - 推送通知模块文档 + +## 模块概述 + +`basic_push` 是 OneApp 基础工具模块群中的推送通知核心模块，提供统一的推送消息接收、处理和分发功能。该模块集成了极光推送SDK、本地通知、事件总线、心跳管理等功能，支持iOS和Android平台的推送服务。 + +### 基本信息 +- **模块名称**: basic_push +- **模块路径**: oneapp_basic_utils/basic_push +- **类型**: Flutter Package Module +- **主要功能**: 推送消息接收、事件总线、本地通知、心跳管理 + +### 核心特性 +- **推送服务集成**: 集成极光推送SDK，支持远程推送消息 +- **事件总线系统**: 基于RxDart的事件发布订阅机制 +- **本地通知**: 支持本地通知的发送和管理 +- **心跳管理**: 前后台切换时的心跳上报机制 +- **用户绑定**: 用户登录后的推送设备绑定和解绑 +- **权限管理**: 推送权限检查和设置跳转 +- **多平台支持**: iOS和Android平台适配 + +## 目录结构 + +``` +basic_push/ +├── lib/ +│ ├── basic_push.dart # 模块入口文件 +│ └── src/ +│ ├── push_facade.dart # 推送门面服务 +│ ├── push_topic.dart # 主题定义 +│ ├── push_config.dart # 配置管理 +│ ├── constant.dart # 常量定义 +│ ├── connector.dart # 连接器 +│ ├── channel/ # 通道实现 +│ │ ├── core/ +│ │ │ └── i_push_channel.dart +│ │ ├── push_channel.dart +│ │ └── local_channel.dart +│ ├── domain/ # 领域对象 +│ │ ├── do/ +│ │ │ ├── push/ +│ │ │ │ ├── push_init_params.dart +│ │ │ │ └── query/ +│ │ │ │ └── setting_push_query_do.dart +│ │ │ └── setting_has_success_do.dart +│ │ ├── errors/ +│ │ │ └── setting_errors.dart +│ │ └── push_device_info.dart +│ ├── eventbus/ # 事件总线 +│ │ ├── event_bus.dart +│ │ ├── event_bus.freezed.dart +│ │ └── event_bus.g.dart +│ ├── heart_beat/ # 心跳管理 +│ │ └── heart_beat_mgmt.dart +│ ├── infrastructure/ # 基础设施层 +│ │ ├── push_repository.dart +│ │ ├── remote_api.dart +│ │ └── remoteapi/ +│ │ └── push_repository_remote.dart +│ └── push_parser/ # 消息解析 +│ └── push_message_parser.dart +├── basic_push_uml.puml # UML图定义 +├── basic_push_uml.svg # UML图 +└── pubspec.yaml # 依赖配置 +``` + +## 核心架构组件 + +### 1. 推送初始化参数 (PushInitParams) + +定义推送服务初始化所需的参数： + +```dart +/// 初始化需要的参数 +class PushInitParams { + const PushInitParams({ + this.privateCloud = true, + this.isProduction = false, + this.isDebug = false, + this.appKey = '', + this.channel = '', + this.connIp = '', + this.connHost, + this.connPort = 0, + this.reportUrl = '', + this.badgeUrl = '', + this.heartbeatInterval, + }); + + /// iOS环境：生产环境设置 + /// TestFlight/In-house/Ad-hoc/AppStore为生产环境(true) + /// Xcode直接编译为开发环境(false) + final bool isProduction; + + /// 是否是私有云 + final bool privateCloud; + + /// debug开关 + final bool isDebug; + + /// 应用Key + final String appKey; + + /// 渠道标识 + final String channel; + + /// 连接IP地址 + final String connIp; + + /// 连接主机 + final String? connHost; + + /// 连接端口 + final int connPort; + + /// 上报URL + final String reportUrl; + + /// 角标URL + final String badgeUrl; + + /// 推送心跳间隔(毫秒)，默认4分50秒 + final int? heartbeatInterval; +} +``` + +### 2. 事件总线系统 (EventBus) + +基于RxDart实现的事件发布订阅系统： + +```dart +/// 事件总线接口 +abstract class IEventBus { + /// 监听多个主题的事件 + Stream on(List topics); + + /// 发布新事件 + void fire(Event event); + + /// 销毁事件总线 + void destroy(); + + /// 获取发送端口用于连接器连接 + SendPort get sendPort; +} + +/// 事件总线实现 +class EventBus implements IEventBus { + factory EventBus({bool sync = false}) => EventBus._( + PublishSubject( + onListen: () => Logger.d('Event Bus has a listener', tag), + onCancel: () => Logger.d('Event Bus has no listener', tag), + sync: sync, + ), + ); + + @override + void fire(Event event) { + Logger.d('Fire a event, $event'); + if (_checkEvent(event)) { + streamController.add(event); + } + } + + @override + Stream on(List topics) => + streamController.stream.where((event) { + final firstWhere = topics.firstWhere( + (element) => (element & event.topic).isHit, + orElse: Topic.zero, + ); + return firstWhere != Topic.zero(); + }); +} +``` + +### 3. 事件和主题定义 (Event & Topic) + +使用Freezed定义的不可变数据类： + +```dart +/// 事件对象 +@freezed +class Event with _$Event { + const factory Event({ + required Topic topic, + required DateTime timestamp, + dynamic payload, + @Default('') String description, + @Default(EventSource.local) EventSource sources, + @Default(false) bool notificationInApp, + }) = _Event; + + factory Event.fromJson(Map json) => _$EventFromJson(json); +} + +/// 主题对象 +@freezed +class Topic with _$Topic { + const factory Topic({ + @Default(maxInt) int scope, + @Default(maxInt) int product, + @Default(maxInt) int index, + @Default(maxInt) int subIndex, + }) = _Topic; + + const Topic._(); + + factory Topic.zero() => const Topic(scope: 0, product: 0, index: 0, subIndex: 0); + + /// 主题合并操作 + Topic operator |(Topic other) => Topic( + scope: scope | other.scope, + product: product | other.product, + index: index | other.index, + subIndex: subIndex | other.subIndex, + ); + + /// 主题匹配操作 + Topic operator &(Topic other) => Topic( + scope: scope & other.scope, + product: product & other.product, + index: index & other.index, + subIndex: subIndex & other.subIndex, + ); + + /// 是否命中 + bool get isHit => scope > 0 && product > 0 && index > 0 && subIndex > 0; +} + +/// 事件来源 +enum EventSource { + /// 远程推送 + push, + /// 本地 + local, +} +``` + +### 4. 推送门面服务 (IPushFacade) + +推送模块的核心接口定义： + +```dart +/// push模块的接口 +abstract class IPushFacade { + /// 初始化模块 + /// 开启心跳上报 + void initPush({ + ILoginDeps loginDeps = const DefaultLoginDeps(), + PushInitParams pushInitParams = const PushInitParams(), + }); + + /// 系统通知权限是否授予 + bool get isNotificationEnabled; + + /// 返回推送SDK里的regId + Future get pushRegId; + + /// 调用此API跳转至系统设置中应用设置界面 + void openSettingsForNotification(); + + /// 将bizId与推送regId传至服务端绑定 + Future bindPush(); + + /// 将bizId与推送RegId传至服务端解绑 + Future unbindPush(); + + /// 发布一个事件 + void postEvent({ + required Topic topic, + dynamic payload, + String description = '', + }); + + /// 订阅对应topic的事件消息 + Stream subscribeOn({required List topics}); + + /// 取消订阅topic的事件消息 + void unsubscribe(StreamSubscription stream); + + /// 获取服务器通知开关列表 + Future> fetchPushQuery(); + + /// 设置服务器通知开关列表 + Future> fetchPushSet({ + List detailSwitchList, + }); + + /// 告知当前在前台 + void enableHearBeatForeground(); + + /// 告知当前在后台 + void enableHearBeatBackground(); + + /// 发送本地通知 + Future sendLocalNotification(LocalNotification notification); + + /// 设置应用角标 + Future setBadgeNumber(int badgeNumber); + + /// 清除缓存 + Future clearCache(); +} + +/// 全局推送门面实例 +IPushFacade get pushFacade => _pushFacade ??= biuldPushFacade(); +``` + +### 5. 预定义主题 (Push Topics) + +```dart +/// 通知点击主题 +const Topic notificationOnClickTopic = + Topic(scope: shift2, product: shift0, index: shift0); + +/// 点击事件里payload里的跳转协议 +const keyLaunchScheme = 'launchScheme'; + +/// 全部主题 +const Topic allTopic = Topic(); + +/// 零主题 +const Topic zeroTopic = Topic(scope: 0, product: 0, index: 0, subIndex: 0); +``` + +## 使用指南 + +### 1. 推送服务初始化 + +```dart +import 'package:basic_push/basic_push.dart'; + +// 配置推送初始化参数 +final pushInitParams = PushInitParams( + isProduction: true, // iOS生产环境 + privateCloud: true, // 使用私有云 + isDebug: false, // 关闭调试模式 + appKey: 'your_app_key', // 应用密钥 + channel: 'official', // 渠道标识 + connHost: 'push.example.com', // 推送服务器 + connPort: 8080, // 连接端口 + heartbeatInterval: 290000, // 心跳间隔(4分50秒) +); + +// 初始化推送服务 +pushFacade.initPush( + loginDeps: MyLoginDeps(), + pushInitParams: pushInitParams, +); +``` + +### 2. 用户绑定和解绑 + +```dart +// 用户登录后绑定推送 +try { + final success = await pushFacade.bindPush(); + if (success) { + print('推送绑定成功'); + } else { + print('推送绑定失败'); + } +} catch (e) { + print('推送绑定异常: $e'); +} + +// 用户登出时解绑推送 +try { + final success = await pushFacade.unbindPush(); + if (success) { + print('推送解绑成功'); + } else { + print('推送解绑失败'); + } +} catch (e) { + print('推送解绑异常: $e'); +} +``` + +### 3. 权限管理 + +```dart +// 检查通知权限 +if (pushFacade.isNotificationEnabled) { + print('通知权限已授予'); +} else { + print('通知权限未授予，请手动开启'); + + // 跳转到系统设置页面 + pushFacade.openSettingsForNotification(); +} + +// 获取推送注册ID +final regId = await pushFacade.pushRegId; +print('推送注册ID: $regId'); +``` + +### 4. 事件发布和订阅 + +```dart +// 发布事件 +pushFacade.postEvent( + topic: notificationOnClickTopic, + payload: { + keyLaunchScheme: 'oneapp://car/control', + 'userId': '12345', + 'action': 'open_door', + }, + description: '用户点击推送通知', +); + +// 订阅事件 +final subscription = pushFacade.subscribeOn( + topics: [notificationOnClickTopic], +).listen((event) { + print('接收到事件: ${event.description}'); + + // 处理跳转协议 + final scheme = event.payload[keyLaunchScheme] as String?; + if (scheme != null) { + handleDeepLink(scheme); + } +}); + +// 取消订阅 +pushFacade.unsubscribe(subscription); +``` + +### 5. 本地通知 + +```dart +// 发送本地通知 +final notification = LocalNotification( + title: '车辆提醒', + body: '您的车辆充电已完成', + payload: jsonEncode({ + 'type': 'charging_complete', + 'vehicleId': 'VIN123456', + }), +); + +final notificationId = await pushFacade.sendLocalNotification(notification); +print('本地通知已发送，ID: $notificationId'); + +// 设置应用角标 +await pushFacade.setBadgeNumber(5); +``` + +### 6. 应用生命周期管理 + +```dart +class _MyAppState extends State with WidgetsBindingObserver { + @override + void initState() { + super.initState(); + WidgetsBinding.instance.addObserver(this); + } + + @override + void dispose() { + WidgetsBinding.instance.removeObserver(this); + super.dispose(); + } + + @override + void didChangeAppLifecycleState(AppLifecycleState state) { + switch (state) { + case AppLifecycleState.resumed: + // 应用进入前台 + pushFacade.enableHearBeatForeground(); + break; + case AppLifecycleState.paused: + // 应用进入后台 + pushFacade.enableHearBeatBackground(); + break; + default: + break; + } + } +} +``` + +### 7. 推送设置管理 + +```dart +// 获取推送设置 +final result = await pushFacade.fetchPushQuery(); +result.fold( + (error) => print('获取推送设置失败: ${error.message}'), + (settings) => { + print('当前推送设置: ${settings.detailSwitchList}'), + // 显示推送设置界面 + }, +); + +// 更新推送设置 +final updateResult = await pushFacade.fetchPushSet( + detailSwitchList: [ + SettingDetailSwitchModel( + key: 'vehicle_notification', + enabled: true, + name: '车辆通知', + ), + SettingDetailSwitchModel( + key: 'charging_notification', + enabled: false, + name: '充电通知', + ), + ], +); + +updateResult.fold( + (error) => print('更新推送设置失败: ${error.message}'), + (success) => print('推送设置更新成功'), +); +``` + +## 依赖配置 + +### pubspec.yaml 关键依赖 + +```yaml +dependencies: + flutter: + sdk: flutter + + # 函数式编程 + dartz: ^0.10.1 + + # 响应式编程 + rxdart: ^0.27.0 + + # 不可变数据类 + freezed_annotation: ^2.0.0 + + # JSON序列化 + json_annotation: ^4.0.0 + + # 基础日志 + basic_logger: + path: ../basic_logger + + # 基础平台 + basic_platform: + path: ../basic_platform + +dev_dependencies: + # 代码生成 + freezed: ^2.0.0 + json_serializable: ^6.0.0 + build_runner: ^2.0.0 +``` + +## 高级功能 + +### 1. 自定义登录依赖 + +```dart +class MyLoginDeps with ILoginDeps { + @override + bool get isLogin { + // 实现自定义的登录状态检查逻辑 + return UserManager.instance.isLoggedIn; + } +} + +// 使用自定义登录依赖 +pushFacade.initPush( + loginDeps: MyLoginDeps(), + pushInitParams: pushInitParams, +); +``` + +### 2. 复杂主题组合 + +```dart +// 定义自定义主题 +const Topic carNotificationTopic = Topic( + scope: shift1, + product: shift2, + index: shift1, + subIndex: shift1, +); + +const Topic chargingNotificationTopic = Topic( + scope: shift1, + product: shift2, + index: shift2, + subIndex: shift1, +); + +// 组合多个主题 +final combinedTopic = carNotificationTopic | chargingNotificationTopic; + +// 订阅组合主题 +final subscription = pushFacade.subscribeOn( + topics: [combinedTopic], +).listen((event) { + // 处理车辆或充电相关的通知 +}); +``` + +### 3. 推送消息解析 + +```dart +// 自定义推送消息解析器 +class MyPushMessageParser { + static Map parse(Map rawMessage) { + // 解析推送消息的自定义格式 + return { + 'type': rawMessage['msg_type'], + 'data': jsonDecode(rawMessage['data']), + 'timestamp': DateTime.parse(rawMessage['timestamp']), + }; + } +} +``` + +## 性能优化建议 + +### 1. 事件订阅管理 +- 及时取消不需要的事件订阅，避免内存泄漏 +- 使用合适的主题过滤，减少不必要的事件处理 +- 在Widget销毁时记得取消订阅 + +### 2. 心跳优化 +- 根据应用特性调整心跳间隔 +- 在后台时降低心跳频率 +- 监听网络状态变化，暂停心跳服务 + +### 3. 本地通知限制 +- 避免频繁发送本地通知 +- 合理设置通知的声音和震动 +- 控制通知的数量和频率 + +## 最佳实践 + +### 1. 推送权限处理 +```dart +// 推荐：友好的权限请求 +void requestNotificationPermission() { + if (!pushFacade.isNotificationEnabled) { + showDialog( + context: context, + builder: (context) => AlertDialog( + title: Text('开启通知权限'), + content: Text('为了及时收到重要消息，请开启通知权限'), + actions: [ + TextButton( + onPressed: () => Navigator.pop(context), + child: Text('稍后设置'), + ), + ElevatedButton( + onPressed: () { + Navigator.pop(context); + pushFacade.openSettingsForNotification(); + }, + child: Text('去设置'), + ), + ], + ), + ); + } +} +``` + +### 2. 错误处理 +```dart +// 推荐：完整的错误处理 +Future handlePushBinding() async { + try { + final success = await pushFacade.bindPush(); + if (!success) { + // 绑定失败的用户友好提示 + showSnackBar('推送服务暂时不可用，请稍后重试'); + } + } catch (e) { + // 记录错误日志 + Logger.e('推送绑定异常: $e', tagPush); + // 用户友好的错误提示 + showSnackBar('网络连接异常，请检查网络后重试'); + } +} +``` + +### 3. 事件处理优化 +```dart +// 推荐：使用StreamBuilder处理事件 +class NotificationHandler extends StatefulWidget { + @override + _NotificationHandlerState createState() => _NotificationHandlerState(); +} + +class _NotificationHandlerState extends State { + late StreamSubscription _subscription; + + @override + void initState() { + super.initState(); + _subscription = pushFacade.subscribeOn( + topics: [notificationOnClickTopic], + ).listen(_handleNotificationClick); + } + + @override + void dispose() { + _subscription.cancel(); + super.dispose(); + } + + void _handleNotificationClick(Event event) { + // 安全的事件处理 + if (mounted && event.payload != null) { + final scheme = event.payload[keyLaunchScheme] as String?; + if (scheme != null) { + NavigationService.handleDeepLink(scheme); + } + } + } +} +``` + +## 问题排查 + +### 常见问题 +1. **推送收不到**: 检查应用权限、网络连接和推送配置 +2. **事件订阅失效**: 确认订阅没有被意外取消，检查主题匹配逻辑 +3. **心跳断开**: 检查网络稳定性和服务器配置 + +### 调试技巧 +- 启用debug模式查看详细日志 +- 使用推送测试工具验证配置 +- 监控应用生命周期事件 + diff --git a/basic_utils/basic_utils.md b/basic_utils/basic_utils.md new file mode 100644 index 0000000..1c8570a --- /dev/null +++ b/basic_utils/basic_utils.md @@ -0,0 +1,560 @@ +# Basic Utils 基础工具模块 + +## 模块概述 + +`basic_utils` 是 OneApp 基础工具模块群中的核心工具集合，提供了应用开发中常用的基础工具类、辅助方法和通用组件。该模块包含了事件总线、图片处理、分享功能、加密解密、文件上传等丰富的工具功能。 + +### 基本信息 +- **模块名称**: basic_utils +- **版本**: 0.0.3 +- **描述**: 基础工具包 +- **Flutter 版本**: >=2.10.5 +- **Dart 版本**: >=3.0.0 <4.0.08 + +## 功能特性 + +### 核心功能 +1. **事件总线系统** + - 全局事件发布订阅 + - 类型安全的事件传递 + - 事件生命周期管理 + - 异步事件处理 + +2. **图片处理工具** + - 图片选择和拍照 + - 图片压缩和格式转换 + - 图片裁剪和编辑 + - 图片缓存管理 + +3. **分享功能集成** + - 社交平台分享 + - 文件分享 + - 链接分享 + - 自定义分享内容 + +4. **加密解密服务** + - 对称加密算法 + - 非对称加密算法 + - 哈希算法 + - 数字签名 + +5. **云存储服务** + - 腾讯云COS集成 + - 文件上传下载 + - 断点续传 + - 存储管理 + +## 技术架构 + +### 目录结构 +``` +lib/ +├── basic_utils.dart # 模块入口文件 +├── src/ # 源代码目录 +│ ├── event_bus/ # 事件总线 +│ ├── image/ # 图片处理 +│ ├── share/ # 分享功能 +│ ├── crypto/ # 加密解密 +│ ├── storage/ # 云存储 +│ ├── network/ # 网络工具 +│ ├── utils/ # 通用工具 +│ └── models/ # 数据模型 +├── widgets/ # 通用组件 +└── test/ # 测试文件 +``` + +### 依赖关系 + +#### 核心框架依赖 +- `basic_modular: ^0.2.3` - 模块化框架 +- `basic_storage: 0.2.2` - 基础存储 +- `basic_webview: ^0.2.4` - WebView组件 + +#### 工具依赖 +- `event_bus: ^2.0.0` - 事件总线 +- `shared_preferences: ^2.0.17` - 本地存储 +- `http: ^1.0.0` - HTTP客户端 +- `dartz: ^0.10.1` - 函数式编程 + +#### 功能依赖 +- `image_picker: ^1.1.2` - 图片选择 +- `flutter_image_compress: 2.1.0` - 图片压缩 +- `share_plus: 7.2.1` - 分享功能 +- `fluwx: ^4.2.5` - 微信SDK +- `weibo_kit: ^4.0.0` - 微博SDK + +#### 安全依赖 +- `crypto: any` - 加密算法 +- `encrypt: any` - 加密工具 +- `pointycastle: any` - 加密库 + +#### 云服务依赖 +- `tencentcloud_cos_sdk_plugin: 1.2.0` - 腾讯云COS + +## 核心模块分析 + +### 1. 模块入口 (`basic_utils.dart`) + +**功能职责**: +- 工具模块统一导出 +- 全局配置初始化 +- 服务注册管理 + +### 2. 事件总线 (`src/event_bus/`) + +**功能职责**: +- 全局事件发布订阅机制 +- 类型安全的事件传递 +- 事件过滤和转换 +- 内存泄漏防护 + +**主要组件**: +- `GlobalEventBus` - 全局事件总线 +- `EventSubscription` - 事件订阅管理 +- `TypedEvent` - 类型化事件 +- `EventFilter` - 事件过滤器 + +**使用示例**: +```dart +// 定义事件类型 +class UserLoginEvent { + final String userId; + final String userName; + + UserLoginEvent(this.userId, this.userName); +} + +// 发布事件 +GlobalEventBus.instance.fire(UserLoginEvent('123', 'John')); + +// 订阅事件 +final subscription = GlobalEventBus.instance.on().listen((event) { + print('User ${event.userName} logged in'); +}); + +// 取消订阅 +subscription.cancel(); +``` + +### 3. 图片处理 (`src/image/`) + +**功能职责**: +- 图片选择和拍照功能 +- 图片压缩和格式转换 +- 图片编辑和处理 +- 图片缓存和管理 + +**主要组件**: +- `ImagePicker` - 图片选择器 +- `ImageCompressor` - 图片压缩器 +- `ImageEditor` - 图片编辑器 +- `ImageCache` - 图片缓存管理 + +**使用示例**: +```dart +class ImageUtils { + static Future pickImage({ + ImageSource source = ImageSource.gallery, + double? maxWidth, + double? maxHeight, + int? imageQuality, + }) async { + final picker = ImagePicker(); + final XFile? image = await picker.pickImage( + source: source, + maxWidth: maxWidth, + maxHeight: maxHeight, + imageQuality: imageQuality, + ); + + return image != null ? File(image.path) : null; + } + + static Future compressImage( + File file, { + int quality = 85, + int? minWidth, + int? minHeight, + }) async { + final result = await FlutterImageCompress.compressAndGetFile( + file.absolute.path, + '${file.parent.path}/compressed_${file.name}', + quality: quality, + minWidth: minWidth, + minHeight: minHeight, + ); + + return File(result!.path); + } +} +``` + +### 4. 分享功能 (`src/share/`) + +**功能职责**: +- 系统原生分享 +- 社交平台分享 +- 自定义分享内容 +- 分享结果回调 + +**主要组件**: +- `ShareManager` - 分享管理器 +- `WeChatShare` - 微信分享 +- `WeiboShare` - 微博分享 +- `SystemShare` - 系统分享 + +**使用示例**: +```dart +class ShareUtils { + static Future shareText(String text) async { + await Share.share(text); + } + + static Future shareFile(String filePath) async { + await Share.shareXFiles([XFile(filePath)]); + } + + static Future shareToWeChat({ + required String title, + required String description, + String? imageUrl, + String? webpageUrl, + }) async { + final model = WeChatShareWebPageModel( + webPage: webpageUrl ?? '', + title: title, + description: description, + thumbnail: WeChatImage.network(imageUrl ?? ''), + ); + + await fluwx.shareToWeChat(model); + } +} +``` + +### 5. 加密解密 (`src/crypto/`) + +**功能职责**: +- 对称加密解密 +- 非对称加密解密 +- 数字签名验证 +- 哈希算法实现 + +**主要组件**: +- `AESCrypto` - AES加密 +- `RSACrypto` - RSA加密 +- `HashUtils` - 哈希工具 +- `SignatureUtils` - 数字签名 + +**使用示例**: +```dart +class CryptoUtils { + static String md5Hash(String input) { + final bytes = utf8.encode(input); + final digest = md5.convert(bytes); + return digest.toString(); + } + + static String sha256Hash(String input) { + final bytes = utf8.encode(input); + final digest = sha256.convert(bytes); + return digest.toString(); + } + + static String aesEncrypt(String plainText, String key) { + final encrypter = Encrypter(AES(Key.fromBase64(key))); + final encrypted = encrypter.encrypt(plainText); + return encrypted.base64; + } + + static String aesDecrypt(String encryptedText, String key) { + final encrypter = Encrypter(AES(Key.fromBase64(key))); + final decrypted = encrypter.decrypt64(encryptedText); + return decrypted; + } +} +``` + +### 6. 云存储 (`src/storage/`) + +**功能职责**: +- 腾讯云COS集成 +- 文件上传下载 +- 断点续传 +- 存储空间管理 + +**主要组件**: +- `COSManager` - COS管理器 +- `FileUploader` - 文件上传器 +- `FileDownloader` - 文件下载器 +- `StorageMonitor` - 存储监控 + +**使用示例**: +```dart +class CloudStorageUtils { + static Future uploadFile( + String filePath, { + String? objectKey, + Function(int, int)? onProgress, + }) async { + try { + final result = await TencentCloudCosSdkPlugin.upload( + filePath, + objectKey ?? _generateObjectKey(filePath), + onProgress: onProgress, + ); + + return result['url'] as String?; + } catch (e) { + print('Upload failed: $e'); + return null; + } + } + + static Future downloadFile( + String url, + String savePath, { + Function(int, int)? onProgress, + }) async { + try { + await TencentCloudCosSdkPlugin.download( + url, + savePath, + onProgress: onProgress, + ); + return true; + } catch (e) { + print('Download failed: $e'); + return false; + } + } + + static String _generateObjectKey(String filePath) { + final fileName = path.basename(filePath); + final timestamp = DateTime.now().millisecondsSinceEpoch; + return 'uploads/$timestamp/$fileName'; + } +} +``` + +### 7. 网络工具 (`src/network/`) + +**功能职责**: +- HTTP请求封装 +- 网络状态检测 +- 请求重试机制 +- 响应数据处理 + +**主要组件**: +- `HttpClient` - HTTP客户端 +- `NetworkMonitor` - 网络监控 +- `RequestInterceptor` - 请求拦截器 +- `ResponseHandler` - 响应处理器 + +### 8. 通用工具 (`src/utils/`) + +**功能职责**: +- 字符串处理工具 +- 日期时间工具 +- 数学计算工具 +- 格式化工具 + +**主要工具**: +- `StringUtils` - 字符串工具 +- `DateUtils` - 日期工具 +- `MathUtils` - 数学工具 +- `FormatUtils` - 格式化工具 + +**工具方法示例**: +```dart +class StringUtils { + static bool isNullOrEmpty(String? str) { + return str == null || str.isEmpty; + } + + static bool isValidEmail(String email) { + return RegExp(r'^[^@]+@[^@]+\.[^@]+').hasMatch(email); + } + + static bool isValidPhone(String phone) { + return RegExp(r'^1[3-9]\d{9}$').hasMatch(phone); + } + + static String maskPhone(String phone) { + if (phone.length != 11) return phone; + return '${phone.substring(0, 3)}****${phone.substring(7)}'; + } +} + +class DateUtils { + static String formatDateTime(DateTime dateTime, [String? pattern]) { + pattern ??= 'yyyy-MM-dd HH:mm:ss'; + return DateFormat(pattern).format(dateTime); + } + + static DateTime? parseDateTime(String dateStr, [String? pattern]) { + try { + pattern ??= 'yyyy-MM-dd HH:mm:ss'; + return DateFormat(pattern).parse(dateStr); + } catch (e) { + return null; + } + } + + static bool isToday(DateTime dateTime) { + final now = DateTime.now(); + return dateTime.year == now.year && + dateTime.month == now.month && + dateTime.day == now.day; + } +} +``` + +## 通用组件 + +### Loading组件 +```dart +class LoadingUtils { + static OverlayEntry? _overlayEntry; + + static void show(BuildContext context, {String? message}) { + hide(); // 先隐藏之前的 + + _overlayEntry = OverlayEntry( + builder: (context) => Material( + color: Colors.black54, + child: Center( + child: Container( + padding: const EdgeInsets.all(20), + decoration: BoxDecoration( + color: Colors.white, + borderRadius: BorderRadius.circular(8), + ), + child: Column( + mainAxisSize: MainAxisSize.min, + children: [ + const CircularProgressIndicator(), + if (message != null) ...[ + const SizedBox(height: 16), + Text(message), + ], + ], + ), + ), + ), + ), + ); + + Overlay.of(context).insert(_overlayEntry!); + } + + static void hide() { + _overlayEntry?.remove(); + _overlayEntry = null; + } +} +``` + +### Toast组件 +```dart +class ToastUtils { + static void showSuccess(String message) { + Fluttertoast.showToast( + msg: message, + backgroundColor: Colors.green, + textColor: Colors.white, + toastLength: Toast.LENGTH_SHORT, + ); + } + + static void showError(String message) { + Fluttertoast.showToast( + msg: message, + backgroundColor: Colors.red, + textColor: Colors.white, + toastLength: Toast.LENGTH_SHORT, + ); + } + + static void showInfo(String message) { + Fluttertoast.showToast( + msg: message, + backgroundColor: Colors.blue, + textColor: Colors.white, + toastLength: Toast.LENGTH_SHORT, + ); + } +} +``` + +## 性能优化 + +### 内存管理 +- **事件订阅管理**: 及时取消不需要的事件订阅 +- **图片内存优化**: 合理控制图片加载和缓存 +- **对象池**: 复用常用对象减少GC压力 +- **弱引用**: 使用弱引用避免内存泄漏 + +### 网络优化 +- **请求缓存**: 缓存网络请求结果 +- **并发控制**: 控制并发请求数量 +- **超时重试**: 智能超时和重试机制 +- **数据压缩**: 压缩传输数据 + +### 存储优化 +- **文件压缩**: 压缩存储文件 +- **清理策略**: 定期清理过期文件 +- **分块上传**: 大文件分块上传 +- **断点续传**: 支持上传下载断点续传 + +## 安全特性 + +### 数据安全 +- **敏感数据加密**: 敏感信息加密存储 +- **传输加密**: HTTPS传输保护 +- **数据校验**: 数据完整性校验 +- **防篡改**: 数字签名防篡改 + +### 隐私保护 +- **权限控制**: 严格的功能权限控制 +- **数据脱敏**: 敏感数据脱敏处理 +- **本地存储**: 安全的本地数据存储 +- **清理机制**: 数据清理和销毁机制 + +## 测试策略 + +### 单元测试 +- **工具类测试**: 各种工具方法测试 +- **加密解密测试**: 加密算法正确性 +- **事件总线测试**: 事件发布订阅机制 +- **网络工具测试**: 网络请求功能 + +### 集成测试 +- **文件上传测试**: 云存储集成测试 +- **分享功能测试**: 社交分享集成测试 +- **图片处理测试**: 图片处理流程测试 +- **端到端测试**: 完整功能流程测试 + +### 性能测试 +- **内存泄漏测试**: 长时间运行检测 +- **并发性能测试**: 高并发场景测试 +- **文件处理测试**: 大文件处理性能 +- **网络性能测试**: 网络请求性能 + +## 最佳实践 + +### 开发建议 +1. **工具复用**: 优先使用现有工具方法 +2. **异常处理**: 完善的异常处理机制 +3. **资源管理**: 及时释放不需要的资源 +4. **性能考虑**: 避免不必要的操作开销 + +### 使用指南 +1. **按需导入**: 只导入需要的工具类 +2. **配置优化**: 合理配置各种参数 +3. **错误处理**: 妥善处理可能的错误 +4. **日志记录**: 记录关键操作日志 + +## 总结 + +`basic_utils` 模块作为 OneApp 的基础工具集合，提供了丰富的开发工具和辅助功能。通过事件总线、图片处理、分享功能、加密解密等核心能力，大大简化了应用开发的复杂性。模块具有良好的性能优化和安全保护机制，能够满足各种开发场景的需求。 diff --git a/basic_utils/flutter_downloader.md b/basic_utils/flutter_downloader.md new file mode 100644 index 0000000..2ec89b6 --- /dev/null +++ b/basic_utils/flutter_downloader.md @@ -0,0 +1,902 @@ +# Flutter Downloader 文件下载器模块 + +## 模块概述 + +`flutter_downloader` 是 OneApp 基础工具模块群中的文件下载器模块，基于 Flutter Community 的开源项目进行定制化。该模块提供了强大的文件下载能力，支持多平台（Android、iOS、鸿蒙）的原生下载功能，包括后台下载、断点续传、下载管理等特性。 + +### 基本信息 +- **模块名称**: flutter_downloader +- **版本**: 1.11.8 +- **描述**: 强大的文件下载插件 +- **Flutter 版本**: >=3.19.0 +- **Dart 版本**: >=3.3.0 <4.0.0 +- **原始项目**: https://github.com/fluttercommunity/flutter_downloader + +## 功能特性 + +### 核心功能 +1. **多平台下载支持** + - Android 原生下载管理器集成 + - iOS 后台下载任务支持 + - 鸿蒙（HarmonyOS）平台支持 + - 跨平台统一接口 + +2. **高级下载特性** + - 后台下载支持 + - 断点续传功能 + - 下载进度监控 + - 并发下载控制 + +3. **下载管理系统** + - 下载任务队列 + - 下载状态跟踪 + - 下载历史记录 + - 失败重试机制 + +4. **文件系统集成** + - 灵活的保存路径配置 + - 文件完整性验证 + - 存储空间检查 + - 文件权限管理 + +## 技术架构 + +### 目录结构 +``` +flutter_downloader/ +├── lib/ # Dart代码 +│ ├── flutter_downloader.dart # 主入口文件 +│ └── src/ # 源代码 +│ ├── downloader.dart # 下载器核心 +│ ├── models.dart # 数据模型 +│ ├── callback_dispatcher.dart # 回调分发器 +│ └── utils.dart # 工具类 +├── android/ # Android原生实现 +│ └── src/main/java/ +│ └── vn/hunghd/flutterdownloader/ +│ ├── FlutterDownloaderPlugin.java +│ ├── DownloadWorker.java +│ ├── TaskDbHelper.java +│ └── TaskDao.java +├── ios/ # iOS原生实现 +│ ├── Classes/ +│ │ ├── FlutterDownloaderPlugin.h +│ │ ├── FlutterDownloaderPlugin.m +│ │ ├── DBManager.h +│ │ └── DBManager.m +│ └── flutter_downloader.podspec +├── ohos/ # 鸿蒙原生实现 +└── example/ # 示例应用 +``` + +### 平台支持 +- **Android**: 使用 DownloadManager 和 WorkManager +- **iOS**: 使用 URLSessionDownloadTask +- **鸿蒙**: 使用 HarmonyOS 下载接口 + +## 核心模块分析 + +### 1. Flutter端实现 + +#### 主入口 (`lib/flutter_downloader.dart`) +```dart +class FlutterDownloader { + static const MethodChannel _channel = MethodChannel('vn.hunghd/downloader'); + static const MethodChannel _backgroundChannel = + MethodChannel('vn.hunghd/downloader_send_port'); + + /// 初始化下载器 + static Future initialize({ + bool debug = false, + bool ignoreSsl = false, + }) async { + await _channel.invokeMethod('initialize', { + 'debug': debug, + 'ignoreSsl': ignoreSsl, + }); + } + + /// 创建下载任务 + static Future enqueue({ + required String url, + required String savedDir, + String? fileName, + Map? headers, + bool showNotification = true, + bool openFileFromNotification = true, + bool requiresStorageNotLow = false, + bool saveInPublicStorage = false, + }) async { + try { + final result = await _channel.invokeMethod('enqueue', { + 'url': url, + 'saved_dir': savedDir, + 'file_name': fileName, + 'headers': headers, + 'show_notification': showNotification, + 'open_file_from_notification': openFileFromNotification, + 'requires_storage_not_low': requiresStorageNotLow, + 'save_in_public_storage': saveInPublicStorage, + }); + return result; + } catch (e) { + print('Error creating download task: $e'); + return null; + } + } + + /// 获取所有下载任务 + static Future?> loadTasks() async { + try { + final result = await _channel.invokeMethod('loadTasks'); + return (result as List?) + ?.map((item) => DownloadTask.fromMap(item)) + .toList(); + } catch (e) { + print('Error loading tasks: $e'); + return null; + } + } + + /// 取消下载任务 + static Future cancel({required String taskId}) async { + await _channel.invokeMethod('cancel', {'task_id': taskId}); + } + + /// 暂停下载任务 + static Future pause({required String taskId}) async { + await _channel.invokeMethod('pause', {'task_id': taskId}); + } + + /// 恢复下载任务 + static Future resume({required String taskId}) async { + await _channel.invokeMethod('resume', {'task_id': taskId}); + } + + /// 重试下载任务 + static Future retry({required String taskId}) async { + return await _channel.invokeMethod('retry', {'task_id': taskId}); + } + + /// 移除下载任务 + static Future remove({ + required String taskId, + bool shouldDeleteContent = false, + }) async { + await _channel.invokeMethod('remove', { + 'task_id': taskId, + 'should_delete_content': shouldDeleteContent, + }); + } + + /// 打开下载的文件 + static Future open({required String taskId}) async { + return await _channel.invokeMethod('open', {'task_id': taskId}); + } + + /// 注册下载回调 + static void registerCallback(DownloadCallback callback) { + _callback = callback; + _channel.setMethodCallHandler(_handleMethodCall); + } + + static DownloadCallback? _callback; + + static Future _handleMethodCall(MethodCall call) async { + if (call.method == 'updateProgress') { + final id = call.arguments['id'] as String; + final status = DownloadTaskStatus.values[call.arguments['status'] as int]; + final progress = call.arguments['progress'] as int; + _callback?.call(id, status, progress); + } + } +} + +typedef DownloadCallback = void Function( + String id, + DownloadTaskStatus status, + int progress, +); +``` + +#### 数据模型 (`src/models.dart`) +```dart +enum DownloadTaskStatus { + undefined, + enqueued, + running, + complete, + failed, + canceled, + paused, +} + +class DownloadTask { + final String taskId; + final String url; + final String filename; + final String savedDir; + final DownloadTaskStatus status; + final int progress; + final int timeCreated; + final bool allowCellular; + + const DownloadTask({ + required this.taskId, + required this.url, + required this.filename, + required this.savedDir, + required this.status, + required this.progress, + required this.timeCreated, + required this.allowCellular, + }); + + factory DownloadTask.fromMap(Map map) { + return DownloadTask( + taskId: map['task_id'] as String, + url: map['url'] as String, + filename: map['file_name'] as String, + savedDir: map['saved_dir'] as String, + status: DownloadTaskStatus.values[map['status'] as int], + progress: map['progress'] as int, + timeCreated: map['time_created'] as int, + allowCellular: map['allow_cellular'] as bool? ?? true, + ); + } + + Map toMap() { + return { + 'task_id': taskId, + 'url': url, + 'file_name': filename, + 'saved_dir': savedDir, + 'status': status.index, + 'progress': progress, + 'time_created': timeCreated, + 'allow_cellular': allowCellular, + }; + } +} +``` + +### 2. Android端实现 + +#### 主插件类 (`FlutterDownloaderPlugin.java`) +```java +public class FlutterDownloaderPlugin implements FlutterPlugin, MethodCallHandler { + private static final String CHANNEL = "vn.hunghd/downloader"; + private static final String BACKGROUND_CHANNEL = "vn.hunghd/downloader_send_port"; + + private Context context; + private MethodChannel channel; + private MethodChannel backgroundChannel; + private TaskDbHelper dbHelper; + + @Override + public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) { + context = binding.getApplicationContext(); + channel = new MethodChannel(binding.getBinaryMessenger(), CHANNEL); + backgroundChannel = new MethodChannel(binding.getBinaryMessenger(), BACKGROUND_CHANNEL); + channel.setMethodCallHandler(this); + dbHelper = TaskDbHelper.getInstance(context); + } + + @Override + public void onMethodCall(@NonNull MethodCall call, @NonNull Result result) { + switch (call.method) { + case "initialize": + initialize(call, result); + break; + case "enqueue": + enqueue(call, result); + break; + case "loadTasks": + loadTasks(result); + break; + case "cancel": + cancel(call, result); + break; + case "pause": + pause(call, result); + break; + case "resume": + resume(call, result); + break; + case "retry": + retry(call, result); + break; + case "remove": + remove(call, result); + break; + case "open": + open(call, result); + break; + default: + result.notImplemented(); + } + } + + private void enqueue(MethodCall call, Result result) { + String url = call.argument("url"); + String savedDir = call.argument("saved_dir"); + String fileName = call.argument("file_name"); + Map headers = call.argument("headers"); + boolean showNotification = call.argument("show_notification"); + + // 创建下载请求 + DownloadManager.Request request = new DownloadManager.Request(Uri.parse(url)); + + // 设置请求头 + if (headers != null) { + for (Map.Entry entry : headers.entrySet()) { + request.addRequestHeader(entry.getKey(), entry.getValue()); + } + } + + // 设置下载路径 + String finalFileName = fileName != null ? fileName : + URLUtil.guessFileName(url, null, null); + request.setDestinationInExternalFilesDir(context, null, + savedDir + "/" + finalFileName); + + // 设置通知 + if (showNotification) { + request.setNotificationVisibility( + DownloadManager.Request.VISIBILITY_VISIBLE_NOTIFY_COMPLETED); + } + + // 启动下载 + DownloadManager downloadManager = (DownloadManager) + context.getSystemService(Context.DOWNLOAD_SERVICE); + long downloadId = downloadManager.enqueue(request); + + // 保存任务信息到数据库 + String taskId = UUID.randomUUID().toString(); + TaskDao taskDao = new TaskDao(taskId, url, finalFileName, savedDir, + DownloadTaskStatus.ENQUEUED.ordinal(), 0, System.currentTimeMillis()); + dbHelper.insertOrUpdateNewTask(taskDao); + + result.success(taskId); + } +} +``` + +#### 下载工作器 (`DownloadWorker.java`) +```java +public class DownloadWorker extends Worker { + public DownloadWorker(@NonNull Context context, @NonNull WorkerParameters params) { + super(context, params); + } + + @NonNull + @Override + public Result doWork() { + String taskId = getInputData().getString("task_id"); + String url = getInputData().getString("url"); + + try { + // 执行下载逻辑 + downloadFile(taskId, url); + return Result.success(); + } catch (Exception e) { + return Result.failure(); + } + } + + private void downloadFile(String taskId, String url) { + // 下载实现逻辑 + // 包括进度更新、错误处理等 + } +} +``` + +### 3. iOS端实现 + +#### 主插件类 (`FlutterDownloaderPlugin.m`) +```objc +@implementation FlutterDownloaderPlugin + ++ (void)registerWithRegistrar:(NSObject*)registrar { + FlutterMethodChannel* channel = [FlutterMethodChannel + methodChannelWithName:@"vn.hunghd/downloader" + binaryMessenger:[registrar messenger]]; + FlutterDownloaderPlugin* instance = [[FlutterDownloaderPlugin alloc] init]; + [registrar addMethodCallDelegate:instance channel:channel]; +} + +- (void)handleMethodCall:(FlutterMethodCall*)call result:(FlutterResult)result { + if ([@"initialize" isEqualToString:call.method]) { + [self initialize:call result:result]; + } else if ([@"enqueue" isEqualToString:call.method]) { + [self enqueue:call result:result]; + } else if ([@"loadTasks" isEqualToString:call.method]) { + [self loadTasks:result]; + } else if ([@"cancel" isEqualToString:call.method]) { + [self cancel:call result:result]; + } else if ([@"pause" isEqualToString:call.method]) { + [self pause:call result:result]; + } else if ([@"resume" isEqualToString:call.method]) { + [self resume:call result:result]; + } else { + result(FlutterMethodNotImplemented); + } +} + +- (void)enqueue:(FlutterMethodCall*)call result:(FlutterResult)result { + NSString* url = call.arguments[@"url"]; + NSString* savedDir = call.arguments[@"saved_dir"]; + NSString* fileName = call.arguments[@"file_name"]; + NSDictionary* headers = call.arguments[@"headers"]; + + // 创建下载任务 + NSURLSessionConfiguration* config = [NSURLSessionConfiguration backgroundSessionConfigurationWithIdentifier:[[NSUUID UUID] UUIDString]]; + NSURLSession* session = [NSURLSession sessionWithConfiguration:config delegate:self delegateQueue:nil]; + + NSMutableURLRequest* request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:url]]; + + // 设置请求头 + if (headers) { + for (NSString* key in headers) { + [request setValue:headers[key] forHTTPHeaderField:key]; + } + } + + NSURLSessionDownloadTask* downloadTask = [session downloadTaskWithRequest:request]; + [downloadTask resume]; + + // 生成任务ID并保存 + NSString* taskId = [[NSUUID UUID] UUIDString]; + [[DBManager getInstance] insertTask:taskId url:url fileName:fileName savedDir:savedDir]; + + result(taskId); +} + +#pragma mark - NSURLSessionDownloadDelegate + +- (void)URLSession:(NSURLSession *)session downloadTask:(NSURLSessionDownloadTask *)downloadTask didFinishDownloadingToURL:(NSURL *)location { + // 处理下载完成 +} + +- (void)URLSession:(NSURLSession *)session downloadTask:(NSURLSessionDownloadTask *)downloadTask didWriteData:(int64_t)bytesWritten totalBytesWritten:(int64_t)totalBytesWritten totalBytesExpectedToWrite:(int64_t)totalBytesExpectedToWrite { + // 更新下载进度 + double progress = (double)totalBytesWritten / (double)totalBytesExpectedToWrite; + // 通知Flutter端进度更新 +} + +@end +``` + +## 业务流程 + +### 下载任务生命周期 +```mermaid +graph TD + A[创建下载任务] --> B[任务入队] + B --> C[开始下载] + C --> D[下载进行中] + D --> E{下载结果} + E -->|成功| F[下载完成] + E -->|失败| G[下载失败] + E -->|取消| H[任务取消] + E -->|暂停| I[任务暂停] + + F --> J[通知用户] + G --> K[错误处理] + H --> L[清理资源] + I --> M[可恢复状态] + + K --> N{是否重试} + N -->|是| C + N -->|否| L + + M --> O[恢复下载] + O --> C +``` + +### 进度更新流程 +```mermaid +graph TD + A[原生下载器] --> B[进度计算] + B --> C[方法通道传递] + C --> D[Flutter回调处理] + D --> E[UI更新] + + F[定时器] --> G[状态检查] + G --> H{状态是否变化} + H -->|是| I[通知状态更新] + H -->|否| J[继续监控] + I --> D + J --> G +``` + +## 使用示例 + +### 基础下载示例 +```dart +class DownloadExample extends StatefulWidget { + @override + _DownloadExampleState createState() => _DownloadExampleState(); +} + +class _DownloadExampleState extends State { + List _tasks = []; + + @override + void initState() { + super.initState(); + _initializeDownloader(); + } + + Future _initializeDownloader() async { + await FlutterDownloader.initialize(debug: true); + + // 注册下载回调 + FlutterDownloader.registerCallback(_downloadCallback); + + // 加载已有任务 + _loadTasks(); + } + + void _downloadCallback(String id, DownloadTaskStatus status, int progress) { + setState(() { + final taskIndex = _tasks.indexWhere((task) => task.taskId == id); + if (taskIndex != -1) { + _tasks[taskIndex] = DownloadTask( + taskId: id, + url: _tasks[taskIndex].url, + filename: _tasks[taskIndex].filename, + savedDir: _tasks[taskIndex].savedDir, + status: status, + progress: progress, + timeCreated: _tasks[taskIndex].timeCreated, + allowCellular: _tasks[taskIndex].allowCellular, + ); + } + }); + } + + Future _loadTasks() async { + final tasks = await FlutterDownloader.loadTasks(); + setState(() { + _tasks = tasks ?? []; + }); + } + + Future _startDownload(String url, String fileName) async { + final savedDir = await _getSavedDir(); + + final taskId = await FlutterDownloader.enqueue( + url: url, + savedDir: savedDir, + fileName: fileName, + showNotification: true, + openFileFromNotification: true, + ); + + if (taskId != null) { + _loadTasks(); + } + } + + Future _getSavedDir() async { + final directory = await getExternalStorageDirectory(); + return '${directory!.path}/downloads'; + } + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('Downloads')), + body: ListView.builder( + itemCount: _tasks.length, + itemBuilder: (context, index) { + final task = _tasks[index]; + return ListTile( + title: Text(task.filename), + subtitle: LinearProgressIndicator( + value: task.progress / 100.0, + ), + trailing: _buildActionButton(task), + ); + }, + ), + floatingActionButton: FloatingActionButton( + onPressed: () => _showDownloadDialog(), + child: Icon(Icons.add), + ), + ); + } + + Widget _buildActionButton(DownloadTask task) { + switch (task.status) { + case DownloadTaskStatus.running: + return IconButton( + icon: Icon(Icons.pause), + onPressed: () => FlutterDownloader.pause(taskId: task.taskId), + ); + case DownloadTaskStatus.paused: + return IconButton( + icon: Icon(Icons.play_arrow), + onPressed: () => FlutterDownloader.resume(taskId: task.taskId), + ); + case DownloadTaskStatus.failed: + return IconButton( + icon: Icon(Icons.refresh), + onPressed: () => FlutterDownloader.retry(taskId: task.taskId), + ); + case DownloadTaskStatus.complete: + return IconButton( + icon: Icon(Icons.open_in_new), + onPressed: () => FlutterDownloader.open(taskId: task.taskId), + ); + default: + return IconButton( + icon: Icon(Icons.delete), + onPressed: () => FlutterDownloader.remove( + taskId: task.taskId, + shouldDeleteContent: true, + ), + ); + } + } + + void _showDownloadDialog() { + // 显示下载URL输入对话框 + showDialog( + context: context, + builder: (context) => DownloadDialog( + onDownload: (url, fileName) => _startDownload(url, fileName), + ), + ); + } +} +``` + +### 批量下载管理 +```dart +class BatchDownloadManager { + static final BatchDownloadManager _instance = BatchDownloadManager._internal(); + factory BatchDownloadManager() => _instance; + BatchDownloadManager._internal(); + + final Map _activeTasks = {}; + final StreamController> _tasksController = + StreamController>.broadcast(); + + Stream> get tasksStream => _tasksController.stream; + + Future initialize() async { + await FlutterDownloader.initialize(); + FlutterDownloader.registerCallback(_onDownloadCallback); + await _loadExistingTasks(); + } + + Future _loadExistingTasks() async { + final tasks = await FlutterDownloader.loadTasks(); + if (tasks != null) { + _activeTasks.clear(); + for (final task in tasks) { + _activeTasks[task.taskId] = task; + } + _notifyTasksUpdate(); + } + } + + void _onDownloadCallback(String id, DownloadTaskStatus status, int progress) { + final existingTask = _activeTasks[id]; + if (existingTask != null) { + _activeTasks[id] = DownloadTask( + taskId: id, + url: existingTask.url, + filename: existingTask.filename, + savedDir: existingTask.savedDir, + status: status, + progress: progress, + timeCreated: existingTask.timeCreated, + allowCellular: existingTask.allowCellular, + ); + _notifyTasksUpdate(); + } + } + + Future addDownload({ + required String url, + required String savedDir, + String? fileName, + Map? headers, + }) async { + final taskId = await FlutterDownloader.enqueue( + url: url, + savedDir: savedDir, + fileName: fileName, + headers: headers, + showNotification: true, + ); + + if (taskId != null) { + await _loadExistingTasks(); + } + + return taskId; + } + + Future pauseDownload(String taskId) async { + await FlutterDownloader.pause(taskId: taskId); + } + + Future resumeDownload(String taskId) async { + await FlutterDownloader.resume(taskId: taskId); + } + + Future cancelDownload(String taskId) async { + await FlutterDownloader.cancel(taskId: taskId); + _activeTasks.remove(taskId); + _notifyTasksUpdate(); + } + + Future retryDownload(String taskId) async { + final newTaskId = await FlutterDownloader.retry(taskId: taskId); + if (newTaskId != null) { + await _loadExistingTasks(); + } + } + + List getTasksByStatus(DownloadTaskStatus status) { + return _activeTasks.values + .where((task) => task.status == status) + .toList(); + } + + void _notifyTasksUpdate() { + _tasksController.add(_activeTasks.values.toList()); + } + + void dispose() { + _tasksController.close(); + } +} +``` + +## 配置和优化 + +### Android配置 +```xml + + + + + + + + + +``` + +### iOS配置 +```xml + +NSAppTransportSecurity + + NSAllowsArbitraryLoads + + + +UIBackgroundModes + + background-fetch + background-processing + +``` + +### 性能优化 +```dart +class DownloadOptimizer { + static const int MAX_CONCURRENT_DOWNLOADS = 3; + static const int RETRY_ATTEMPTS = 3; + static const Duration RETRY_DELAY = Duration(seconds: 5); + + static Future configureDownloader() async { + await FlutterDownloader.initialize( + debug: kDebugMode, + ignoreSsl: false, + ); + } + + static Map getOptimizedHeaders() { + return { + 'User-Agent': 'OneApp/${getAppVersion()}', + 'Accept-Encoding': 'gzip, deflate', + 'Connection': 'keep-alive', + }; + } + + static Future smartDownload({ + required String url, + required String savedDir, + String? fileName, + }) async { + // 检查网络状态 + final connectivity = await Connectivity().checkConnectivity(); + if (connectivity == ConnectivityResult.none) { + throw Exception('No network connection'); + } + + // 检查存储空间 + final directory = Directory(savedDir); + if (!await directory.exists()) { + await directory.create(recursive: true); + } + + final freeSpace = await _getAvailableSpace(savedDir); + final fileSize = await _getFileSize(url); + if (fileSize > freeSpace) { + throw Exception('Insufficient storage space'); + } + + // 开始下载 + return await FlutterDownloader.enqueue( + url: url, + savedDir: savedDir, + fileName: fileName, + headers: getOptimizedHeaders(), + showNotification: true, + requiresStorageNotLow: true, + ); + } + + static Future _getAvailableSpace(String path) async { + // 获取可用存储空间 + return 0; // 实现细节 + } + + static Future _getFileSize(String url) async { + // 获取文件大小 + return 0; // 实现细节 + } +} +``` + +## 安全特性 + +### 文件安全 +- **路径验证**: 验证下载路径安全性 +- **文件类型检查**: 检查允许的文件类型 +- **病毒扫描**: 集成安全扫描机制 +- **权限控制**: 严格的文件访问权限 + +### 网络安全 +- **HTTPS验证**: 强制HTTPS下载 +- **证书校验**: SSL证书有效性检查 +- **请求头验证**: 防止恶意请求头 +- **下载限制**: 文件大小和类型限制 + +## 测试策略 + +### 单元测试 +- **下载逻辑测试**: 核心下载功能 +- **状态管理测试**: 任务状态转换 +- **错误处理测试**: 异常情况处理 +- **数据模型测试**: 序列化反序列化 + +### 集成测试 +- **平台兼容测试**: 不同平台下载功能 +- **网络环境测试**: 不同网络条件 +- **存储测试**: 不同存储路径和权限 +- **并发测试**: 多任务并发下载 + +### 性能测试 +- **大文件下载**: 大文件下载稳定性 +- **长时间运行**: 长期后台下载 +- **内存使用**: 内存泄漏检测 +- **电池消耗**: 下载对电池的影响 + +## 总结 + +`flutter_downloader` 模块作为 OneApp 的文件下载器，提供了强大的跨平台下载能力。通过原生实现和Flutter接口的完美结合，实现了高效、稳定的文件下载功能。模块支持后台下载、断点续传、进度监控等高级特性，能够满足各种下载场景的需求。良好的错误处理和性能优化机制确保了下载任务的可靠性和用户体验。 diff --git a/basic_utils/flutter_plugin_mtpush_private.md b/basic_utils/flutter_plugin_mtpush_private.md new file mode 100644 index 0000000..a6c3c3b --- /dev/null +++ b/basic_utils/flutter_plugin_mtpush_private.md @@ -0,0 +1,1139 @@ +# Flutter Plugin MTPush Private 美团云推送插件 + +## 模块概述 + +`flutter_plugin_mtpush_private` 是 OneApp 基础工具模块群中的美团云推送私有版插件，基于 EngageLab 的推送服务开发。该插件为 Flutter 应用提供了完整的推送消息功能，包括通知推送、透传消息、标签管理等功能，支持 Android 和 iOS 双平台。 + +### 基本信息 +- **模块名称**: flutter_plugin_mtpush_private +- **版本**: 3.0.1+2 +- **类型**: Flutter Plugin（原生插件） +- **描述**: 美团云推送私有版插件 +- **Flutter 版本**: >=1.20.0 +- **Dart 版本**: >=2.12.0 <4.0.0 +- **服务提供商**: EngageLab (https://www.engagelab.com/) + +## 功能特性 + +### 核心功能 +1. **推送消息接收** + - 通知消息接收和展示 + - 透传消息接收和处理 + - 富媒体消息支持 + - 自定义消息格式 + +2. **设备管理** + - 设备注册和注销 + - 设备别名设置 + - 设备标签管理 + - 推送开关控制 + +3. **标签和别名** + - 用户标签设置 + - 别名绑定管理 + - 标签分组推送 + - 个性化推送 + +4. **统计和分析** + - 推送到达统计 + - 用户点击统计 + - 设备活跃统计 + - 自定义事件统计 + +## 技术架构 + +### 目录结构 +``` +flutter_plugin_mtpush_private/ +├── lib/ # Dart代码 +│ ├── flutter_plugin_mtpush_private.dart # 插件入口 +│ ├── src/ # 源代码 +│ │ ├── mtpush_flutter.dart # 主要接口 +│ │ ├── mtpush_models.dart # 数据模型 +│ │ ├── mtpush_constants.dart # 常量定义 +│ │ └── mtpush_utils.dart # 工具类 +│ └── flutter_plugin_mtpush_private_platform_interface.dart +├── android/ # Android原生实现 +│ ├── src/main/kotlin/ +│ │ └── com/engagelab/privates/flutter_plugin_mtpush_private/ +│ │ ├── FlutterPluginMTPushPrivatePlugin.kt +│ │ ├── MTPushReceiver.kt +│ │ ├── NotificationHelper.kt +│ │ └── Utils.kt +│ └── build.gradle +├── ios/ # iOS原生实现 +│ ├── Classes/ +│ │ ├── FlutterPluginMTPushPrivatePlugin.h +│ │ ├── FlutterPluginMTPushPrivatePlugin.m +│ │ ├── MTPushNotificationDelegate.h +│ │ └── MTPushNotificationDelegate.m +│ └── flutter_plugin_mtpush_private.podspec +├── example/ # 示例应用 +└── test/ # 测试文件 +``` + +### 依赖关系 + +#### 核心依赖 +- Flutter SDK + +#### 原生 SDK 依赖 +- **Android**: EngageLab Android Push SDK +- **iOS**: EngageLab iOS Push SDK + +## 核心模块分析 + +### 1. Flutter端实现 + +#### 主接口 (`src/mtpush_flutter.dart`) +```dart +class MTFlutterPush { + static const MethodChannel _channel = + MethodChannel('flutter_plugin_mtpush_private'); + + static const EventChannel _eventChannel = + EventChannel('flutter_plugin_mtpush_private_event'); + + // 初始化推送服务 + static Future initialize({ + required String appKey, + required String appSecret, + String? channel, + bool enableDebug = false, + }) async { + await _channel.invokeMethod('initialize', { + 'appKey': appKey, + 'appSecret': appSecret, + 'channel': channel ?? 'default', + 'enableDebug': enableDebug, + }); + } + + // 获取设备注册ID + static Future getRegistrationId() async { + return await _channel.invokeMethod('getRegistrationId'); + } + + // 设置别名 + static Future setAlias(String alias) async { + final result = await _channel.invokeMethod('setAlias', {'alias': alias}); + return result == true; + } + + // 删除别名 + static Future deleteAlias() async { + final result = await _channel.invokeMethod('deleteAlias'); + return result == true; + } + + // 设置标签 + static Future setTags(Set tags) async { + final result = await _channel.invokeMethod('setTags', {'tags': tags.toList()}); + return result == true; + } + + // 添加标签 + static Future addTags(Set tags) async { + final result = await _channel.invokeMethod('addTags', {'tags': tags.toList()}); + return result == true; + } + + // 删除标签 + static Future deleteTags(Set tags) async { + final result = await _channel.invokeMethod('deleteTags', {'tags': tags.toList()}); + return result == true; + } + + // 清空所有标签 + static Future cleanTags() async { + final result = await _channel.invokeMethod('cleanTags'); + return result == true; + } + + // 获取所有标签 + static Future?> getAllTags() async { + final result = await _channel.invokeMethod('getAllTags'); + if (result is List) { + return result.cast().toSet(); + } + return null; + } + + // 开启推送 + static Future resumePush() async { + await _channel.invokeMethod('resumePush'); + } + + // 停止推送 + static Future stopPush() async { + await _channel.invokeMethod('stopPush'); + } + + // 检查推送是否停止 + static Future isPushStopped() async { + final result = await _channel.invokeMethod('isPushStopped'); + return result == true; + } + + // 发送本地通知 + static Future sendLocalNotification(LocalNotification notification) async { + await _channel.invokeMethod('sendLocalNotification', notification.toMap()); + } + + // 添加推送消息监听器 + static void addReceiveNotificationListener( + void Function(Map message) onReceive, + ) { + _eventChannel.receiveBroadcastStream('receiveNotification').listen((data) { + if (data is Map) { + onReceive(data); + } + }); + } + + // 添加推送消息点击监听器 + static void addReceiveOpenNotificationListener( + void Function(Map message) onOpen, + ) { + _eventChannel.receiveBroadcastStream('openNotification').listen((data) { + if (data is Map) { + onOpen(data); + } + }); + } + + // 添加透传消息监听器 + static void addReceiveMessageListener( + void Function(Map message) onMessage, + ) { + _eventChannel.receiveBroadcastStream('receiveMessage').listen((data) { + if (data is Map) { + onMessage(data); + } + }); + } + + // 设置通知栏样式 + static Future setNotificationStyle({ + int? notificationStyle, + int? notificationMaxNumber, + }) async { + await _channel.invokeMethod('setNotificationStyle', { + 'notificationStyle': notificationStyle, + 'notificationMaxNumber': notificationMaxNumber, + }); + } + + // 设置静默时间 + static Future setSilenceTime({ + required int startHour, + required int startMinute, + required int endHour, + required int endMinute, + }) async { + await _channel.invokeMethod('setSilenceTime', { + 'startHour': startHour, + 'startMinute': startMinute, + 'endHour': endHour, + 'endMinute': endMinute, + }); + } + + // 清理通知 + static Future clearAllNotifications() async { + await _channel.invokeMethod('clearAllNotifications'); + } + + // 清理指定通知 + static Future clearNotificationById(int notificationId) async { + await _channel.invokeMethod('clearNotificationById', { + 'notificationId': notificationId, + }); + } +} +``` + +#### 数据模型 (`src/mtpush_models.dart`) +```dart +class LocalNotification { + final int id; + final String title; + final String content; + final String? subtitle; + final Map? extras; + final DateTime? fireTime; + final int? builderId; + + const LocalNotification({ + required this.id, + required this.title, + required this.content, + this.subtitle, + this.extras, + this.fireTime, + this.builderId, + }); + + Map toMap() { + return { + 'id': id, + 'title': title, + 'content': content, + 'subtitle': subtitle, + 'extras': extras, + 'fireTime': fireTime?.millisecondsSinceEpoch, + 'builderId': builderId, + }; + } + + factory LocalNotification.fromMap(Map map) { + return LocalNotification( + id: map['id'] as int, + title: map['title'] as String, + content: map['content'] as String, + subtitle: map['subtitle'] as String?, + extras: map['extras'] as Map?, + fireTime: map['fireTime'] != null ? + DateTime.fromMillisecondsSinceEpoch(map['fireTime'] as int) : null, + builderId: map['builderId'] as int?, + ); + } +} + +class PushMessage { + final String messageId; + final String title; + final String content; + final Map extras; + final int platform; + final DateTime receivedTime; + + const PushMessage({ + required this.messageId, + required this.title, + required this.content, + required this.extras, + required this.platform, + required this.receivedTime, + }); + + factory PushMessage.fromMap(Map map) { + return PushMessage( + messageId: map['messageId'] as String, + title: map['title'] as String, + content: map['content'] as String, + extras: map['extras'] as Map? ?? {}, + platform: map['platform'] as int, + receivedTime: DateTime.fromMillisecondsSinceEpoch( + map['receivedTime'] as int, + ), + ); + } + + Map toMap() { + return { + 'messageId': messageId, + 'title': title, + 'content': content, + 'extras': extras, + 'platform': platform, + 'receivedTime': receivedTime.millisecondsSinceEpoch, + }; + } +} + +class TagAliasResult { + final bool success; + final String? errorMessage; + final int? errorCode; + final Set? tags; + final String? alias; + + const TagAliasResult({ + required this.success, + this.errorMessage, + this.errorCode, + this.tags, + this.alias, + }); + + factory TagAliasResult.fromMap(Map map) { + return TagAliasResult( + success: map['success'] as bool, + errorMessage: map['errorMessage'] as String?, + errorCode: map['errorCode'] as int?, + tags: (map['tags'] as List?)?.cast().toSet(), + alias: map['alias'] as String?, + ); + } +} +``` + +### 2. Android端实现 + +#### 主插件类 (`FlutterPluginMTPushPrivatePlugin.kt`) +```kotlin +class FlutterPluginMTPushPrivatePlugin: FlutterPlugin, MethodCallHandler { + private lateinit var channel: MethodChannel + private lateinit var eventChannel: EventChannel + private lateinit var context: Context + private var eventSink: EventChannel.EventSink? = null + + override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) { + channel = MethodChannel(binding.binaryMessenger, "flutter_plugin_mtpush_private") + eventChannel = EventChannel(binding.binaryMessenger, "flutter_plugin_mtpush_private_event") + + context = binding.applicationContext + channel.setMethodCallHandler(this) + + eventChannel.setStreamHandler(object : EventChannel.StreamHandler { + override fun onListen(arguments: Any?, events: EventChannel.EventSink?) { + eventSink = events + } + + override fun onCancel(arguments: Any?) { + eventSink = null + } + }) + + // 设置推送消息接收器 + MTPushReceiver.setEventSink(eventSink) + } + + override fun onMethodCall(call: MethodCall, result: Result) { + when (call.method) { + "initialize" -> initialize(call, result) + "getRegistrationId" -> getRegistrationId(result) + "setAlias" -> setAlias(call, result) + "deleteAlias" -> deleteAlias(result) + "setTags" -> setTags(call, result) + "addTags" -> addTags(call, result) + "deleteTags" -> deleteTags(call, result) + "cleanTags" -> cleanTags(result) + "getAllTags" -> getAllTags(result) + "resumePush" -> resumePush(result) + "stopPush" -> stopPush(result) + "isPushStopped" -> isPushStopped(result) + "sendLocalNotification" -> sendLocalNotification(call, result) + "setNotificationStyle" -> setNotificationStyle(call, result) + "setSilenceTime" -> setSilenceTime(call, result) + "clearAllNotifications" -> clearAllNotifications(result) + "clearNotificationById" -> clearNotificationById(call, result) + else -> result.notImplemented() + } + } + + private fun initialize(call: MethodCall, result: Result) { + val appKey = call.argument("appKey") + val appSecret = call.argument("appSecret") + val channel = call.argument("channel") ?: "default" + val enableDebug = call.argument("enableDebug") ?: false + + if (appKey == null || appSecret == null) { + result.error("INVALID_ARGUMENTS", "AppKey and AppSecret are required", null) + return + } + + try { + // 初始化美团云推送SDK + MTPushInterface.setDebugMode(enableDebug) + MTPushInterface.init(context, appKey, appSecret, channel) + + // 注册推送服务 + MTPushInterface.register(context) + + result.success(true) + } catch (e: Exception) { + result.error("INITIALIZATION_FAILED", e.message, null) + } + } + + private fun getRegistrationId(result: Result) { + val registrationId = MTPushInterface.getRegistrationId(context) + result.success(registrationId) + } + + private fun setAlias(call: MethodCall, result: Result) { + val alias = call.argument("alias") + if (alias == null) { + result.error("INVALID_ARGUMENTS", "Alias is required", null) + return + } + + MTPushInterface.setAlias(context, alias, object : TagAliasCallback { + override fun gotResult(code: Int, alias: String?, tags: MutableSet?) { + result.success(code == 0) + } + }) + } + + private fun setTags(call: MethodCall, result: Result) { + val tagsList = call.argument>("tags") + if (tagsList == null) { + result.error("INVALID_ARGUMENTS", "Tags are required", null) + return + } + + val tags = tagsList.toMutableSet() + MTPushInterface.setTags(context, tags, object : TagAliasCallback { + override fun gotResult(code: Int, alias: String?, tags: MutableSet?) { + result.success(code == 0) + } + }) + } + + private fun sendLocalNotification(call: MethodCall, result: Result) { + val id = call.argument("id") ?: 0 + val title = call.argument("title") + val content = call.argument("content") + val fireTime = call.argument("fireTime") + + if (title == null || content == null) { + result.error("INVALID_ARGUMENTS", "Title and content are required", null) + return + } + + val notification = LocalNotification.Builder(context) + .setNotificationId(id) + .setTitle(title) + .setContent(content) + + fireTime?.let { + notification.setFireTime(Date(it)) + } + + MTPushInterface.addLocalNotification(context, notification.build()) + result.success(true) + } +} +``` + +#### 推送消息接收器 (`MTPushReceiver.kt`) +```kotlin +class MTPushReceiver : BroadcastReceiver() { + companion object { + private var eventSink: EventChannel.EventSink? = null + + fun setEventSink(sink: EventChannel.EventSink?) { + eventSink = sink + } + } + + override fun onReceive(context: Context, intent: Intent) { + val bundle = intent.extras ?: return + + when (intent.action) { + MTPushInterface.ACTION_REGISTRATION_ID -> { + handleRegistration(bundle) + } + MTPushInterface.ACTION_MESSAGE_RECEIVED -> { + handleMessageReceived(bundle) + } + MTPushInterface.ACTION_NOTIFICATION_RECEIVED -> { + handleNotificationReceived(bundle) + } + MTPushInterface.ACTION_NOTIFICATION_OPENED -> { + handleNotificationOpened(bundle) + } + } + } + + private fun handleRegistration(bundle: Bundle) { + val registrationId = bundle.getString(MTPushInterface.EXTRA_REGISTRATION_ID) + // 处理注册ID + } + + private fun handleMessageReceived(bundle: Bundle) { + val message = parseMessage(bundle) + eventSink?.success(mapOf( + "event" to "receiveMessage", + "data" to message + )) + } + + private fun handleNotificationReceived(bundle: Bundle) { + val notification = parseNotification(bundle) + eventSink?.success(mapOf( + "event" to "receiveNotification", + "data" to notification + )) + } + + private fun handleNotificationOpened(bundle: Bundle) { + val notification = parseNotification(bundle) + eventSink?.success(mapOf( + "event" to "openNotification", + "data" to notification + )) + } + + private fun parseMessage(bundle: Bundle): Map { + return mapOf( + "messageId" to (bundle.getString(MTPushInterface.EXTRA_MSG_ID) ?: ""), + "title" to (bundle.getString(MTPushInterface.EXTRA_TITLE) ?: ""), + "content" to (bundle.getString(MTPushInterface.EXTRA_MESSAGE) ?: ""), + "extras" to parseExtras(bundle), + "platform" to 0, // Android + "receivedTime" to System.currentTimeMillis() + ) + } + + private fun parseNotification(bundle: Bundle): Map { + return mapOf( + "messageId" to (bundle.getString(MTPushInterface.EXTRA_MSG_ID) ?: ""), + "title" to (bundle.getString(MTPushInterface.EXTRA_NOTIFICATION_TITLE) ?: ""), + "content" to (bundle.getString(MTPushInterface.EXTRA_ALERT) ?: ""), + "extras" to parseExtras(bundle), + "platform" to 0, // Android + "receivedTime" to System.currentTimeMillis() + ) + } + + private fun parseExtras(bundle: Bundle): Map { + val extras = mutableMapOf() + val extrasString = bundle.getString(MTPushInterface.EXTRA_EXTRA) + + extrasString?.let { + try { + val jsonObject = JSONObject(it) + val keys = jsonObject.keys() + while (keys.hasNext()) { + val key = keys.next() + extras[key] = jsonObject.get(key) + } + } catch (e: JSONException) { + // 解析失败，返回空Map + } + } + + return extras + } +} +``` + +### 3. iOS端实现 + +#### 主插件类 (`FlutterPluginMTPushPrivatePlugin.m`) +```objc +@implementation FlutterPluginMTPushPrivatePlugin + ++ (void)registerWithRegistrar:(NSObject*)registrar { + FlutterMethodChannel* channel = [FlutterMethodChannel + methodChannelWithName:@"flutter_plugin_mtpush_private" + binaryMessenger:[registrar messenger]]; + + FlutterEventChannel* eventChannel = [FlutterEventChannel + eventChannelWithName:@"flutter_plugin_mtpush_private_event" + binaryMessenger:[registrar messenger]]; + + FlutterPluginMTPushPrivatePlugin* instance = [[FlutterPluginMTPushPrivatePlugin alloc] init]; + [registrar addMethodCallDelegate:instance channel:channel]; + [eventChannel setStreamHandler:instance]; +} + +- (void)handleMethodCall:(FlutterMethodCall*)call result:(FlutterResult)result { + if ([@"initialize" isEqualToString:call.method]) { + [self initialize:call result:result]; + } else if ([@"getRegistrationId" isEqualToString:call.method]) { + [self getRegistrationId:result]; + } else if ([@"setAlias" isEqualToString:call.method]) { + [self setAlias:call result:result]; + } else if ([@"setTags" isEqualToString:call.method]) { + [self setTags:call result:result]; + } else if ([@"sendLocalNotification" isEqualToString:call.method]) { + [self sendLocalNotification:call result:result]; + } else { + result(FlutterMethodNotImplemented); + } +} + +- (void)initialize:(FlutterMethodCall*)call result:(FlutterResult)result { + NSString* appKey = call.arguments[@"appKey"]; + NSString* appSecret = call.arguments[@"appSecret"]; + NSString* channel = call.arguments[@"channel"] ?: @"default"; + BOOL enableDebug = [call.arguments[@"enableDebug"] boolValue]; + + if (!appKey || !appSecret) { + result([FlutterError errorWithCode:@"INVALID_ARGUMENTS" + message:@"AppKey and AppSecret are required" + details:nil]); + return; + } + + // 初始化美团云推送SDK + [MTPushService setupWithOption:nil + appKey:appKey + appSecret:appSecret + channel:channel + apsForProduction:NO]; + + if (enableDebug) { + [MTPushService setDebugMode]; + } + + // 注册推送服务 + [MTPushService registerForRemoteNotificationTypes:(UIUserNotificationTypeBadge | + UIUserNotificationTypeSound | + UIUserNotificationTypeAlert) + categories:nil]; + + result(@YES); +} + +- (void)getRegistrationId:(FlutterResult)result { + NSString* registrationId = [MTPushService registrationID]; + result(registrationId); +} + +- (void)setAlias:(FlutterMethodCall*)call result:(FlutterResult)result { + NSString* alias = call.arguments[@"alias"]; + + [MTPushService setAlias:alias + completion:^(NSInteger iResCode, NSString *iAlias, NSInteger seq) { + result(@(iResCode == 0)); + } + seq:0]; +} + +- (void)setTags:(FlutterMethodCall*)call result:(FlutterResult)result { + NSArray* tagsArray = call.arguments[@"tags"]; + NSSet* tags = [NSSet setWithArray:tagsArray]; + + [MTPushService setTags:tags + completion:^(NSInteger iResCode, NSSet *iTags, NSInteger seq) { + result(@(iResCode == 0)); + } + seq:0]; +} + +#pragma mark - FlutterStreamHandler + +- (FlutterError*)onListenWithArguments:(id)arguments eventSink:(FlutterEventSink)events { + _eventSink = events; + return nil; +} + +- (FlutterError*)onCancelWithArguments:(id)arguments { + _eventSink = nil; + return nil; +} + +@end +``` + +## 使用示例 + +### 基础推送功能 +```dart +class PushExample extends StatefulWidget { + @override + _PushExampleState createState() => _PushExampleState(); +} + +class _PushExampleState extends State { + String? _registrationId; + List _receivedMessages = []; + + @override + void initState() { + super.initState(); + _initializePush(); + } + + Future _initializePush() async { + // 初始化推送服务 + await MTFlutterPush.initialize( + appKey: 'your_app_key', + appSecret: 'your_app_secret', + channel: 'default', + enableDebug: true, + ); + + // 获取注册ID + final regId = await MTFlutterPush.getRegistrationId(); + setState(() { + _registrationId = regId; + }); + + // 设置用户别名 + await MTFlutterPush.setAlias('user_123'); + + // 设置用户标签 + await MTFlutterPush.setTags({'VIP', 'iOS', 'Beijing'}); + + // 监听推送消息 + _setupPushListeners(); + } + + void _setupPushListeners() { + // 监听通知消息接收 + MTFlutterPush.addReceiveNotificationListener((message) { + print('Received notification: $message'); + _addMessage(PushMessage.fromMap(message)); + }); + + // 监听通知消息点击 + MTFlutterPush.addReceiveOpenNotificationListener((message) { + print('Opened notification: $message'); + _handleNotificationClick(PushMessage.fromMap(message)); + }); + + // 监听透传消息 + MTFlutterPush.addReceiveMessageListener((message) { + print('Received message: $message'); + _handleTransparentMessage(PushMessage.fromMap(message)); + }); + } + + void _addMessage(PushMessage message) { + setState(() { + _receivedMessages.insert(0, message); + }); + } + + void _handleNotificationClick(PushMessage message) { + // 处理通知点击事件 + if (message.extras.containsKey('page')) { + String targetPage = message.extras['page']; + // 根据页面参数进行跳转 + _navigateToPage(targetPage); + } + } + + void _handleTransparentMessage(PushMessage message) { + // 处理透传消息 + if (message.extras.containsKey('action')) { + String action = message.extras['action']; + switch (action) { + case 'refresh_data': + _refreshAppData(); + break; + case 'show_dialog': + _showCustomDialog(message.content); + break; + } + } + } + + void _navigateToPage(String page) { + // 页面跳转逻辑 + } + + void _refreshAppData() { + // 刷新应用数据 + } + + void _showCustomDialog(String content) { + showDialog( + context: context, + builder: (context) => AlertDialog( + title: Text('推送消息'), + content: Text(content), + actions: [ + TextButton( + onPressed: () => Navigator.of(context).pop(), + child: Text('确定'), + ), + ], + ), + ); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('推送示例')), + body: Column( + children: [ + Padding( + padding: const EdgeInsets.all(16.0), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text('注册ID: ${_registrationId ?? "获取中..."}'), + SizedBox(height: 16), + Row( + children: [ + ElevatedButton( + onPressed: _sendLocalNotification, + child: Text('发送本地通知'), + ), + SizedBox(width: 8), + ElevatedButton( + onPressed: _clearAllNotifications, + child: Text('清除所有通知'), + ), + ], + ), + ], + ), + ), + Expanded( + child: ListView.builder( + itemCount: _receivedMessages.length, + itemBuilder: (context, index) { + final message = _receivedMessages[index]; + return ListTile( + title: Text(message.title), + subtitle: Text(message.content), + trailing: Text( + DateFormat('HH:mm:ss').format(message.receivedTime), + ), + ); + }, + ), + ), + ], + ), + ); + } + + void _sendLocalNotification() { + final notification = LocalNotification( + id: DateTime.now().millisecondsSinceEpoch, + title: '本地通知', + content: '这是一条本地推送通知', + fireTime: DateTime.now().add(Duration(seconds: 5)), + ); + + MTFlutterPush.sendLocalNotification(notification); + } + + void _clearAllNotifications() { + MTFlutterPush.clearAllNotifications(); + } +} +``` + +### 高级推送管理 +```dart +class AdvancedPushManager { + static final AdvancedPushManager _instance = AdvancedPushManager._internal(); + factory AdvancedPushManager() => _instance; + AdvancedPushManager._internal(); + + bool _isInitialized = false; + String? _currentUserId; + Set _currentTags = {}; + + Future initialize() async { + if (_isInitialized) return; + + await MTFlutterPush.initialize( + appKey: Config.mtpushAppKey, + appSecret: Config.mtpushAppSecret, + enableDebug: Config.isDebugMode, + ); + + _setupMessageHandlers(); + _isInitialized = true; + } + + Future setUser({ + required String userId, + Set? tags, + Map? userInfo, + }) async { + _currentUserId = userId; + + // 设置别名 + await MTFlutterPush.setAlias(userId); + + // 设置标签 + if (tags != null) { + _currentTags = tags; + await MTFlutterPush.setTags(tags); + } + + // 可以将用户信息发送到服务器 + if (userInfo != null) { + await _uploadUserInfo(userId, userInfo); + } + } + + Future addUserTags(Set tags) async { + _currentTags.addAll(tags); + await MTFlutterPush.addTags(tags); + } + + Future removeUserTags(Set tags) async { + _currentTags.removeAll(tags); + await MTFlutterPush.deleteTags(tags); + } + + Future logout() async { + _currentUserId = null; + _currentTags.clear(); + + await MTFlutterPush.deleteAlias(); + await MTFlutterPush.cleanTags(); + } + + void _setupMessageHandlers() { + // 设置通知消息处理 + MTFlutterPush.addReceiveNotificationListener(_handleNotification); + MTFlutterPush.addReceiveOpenNotificationListener(_handleNotificationClick); + MTFlutterPush.addReceiveMessageListener(_handleTransparentMessage); + } + + void _handleNotification(Map message) { + // 记录通知接收事件 + _trackEvent('notification_received', message); + + // 更新应用角标 + _updateAppBadge(); + } + + void _handleNotificationClick(Map message) { + // 记录通知点击事件 + _trackEvent('notification_clicked', message); + + // 处理深度链接 + if (message['extras'] != null) { + final extras = message['extras'] as Map; + _handleDeepLink(extras); + } + } + + void _handleTransparentMessage(Map message) { + // 记录透传消息事件 + _trackEvent('message_received', message); + + // 处理业务逻辑 + final extras = message['extras'] as Map? ?? {}; + _processBusinessMessage(extras); + } + + void _handleDeepLink(Map extras) { + if (extras.containsKey('deeplink')) { + final deeplink = extras['deeplink'] as String; + // 处理深度链接跳转 + DeepLinkHandler.handle(deeplink); + } + } + + void _processBusinessMessage(Map extras) { + final action = extras['action'] as String?; + + switch (action) { + case 'refresh_user_info': + UserService.refreshUserInfo(); + break; + case 'update_config': + ConfigService.updateRemoteConfig(); + break; + case 'force_logout': + AuthService.forceLogout(); + break; + } + } + + void _trackEvent(String eventName, Map data) { + // 发送事件统计 + AnalyticsService.trackEvent(eventName, data); + } + + void _updateAppBadge() { + // 更新应用角标数量 + // 可以调用原生方法或使用其他插件 + } + + Future _uploadUserInfo(String userId, Map userInfo) async { + // 将用户信息上传到推送服务器 + // 用于精准推送 + } + + Future schedulePushSettings({ + int? silenceStartHour, + int? silenceStartMinute, + int? silenceEndHour, + int? silenceEndMinute, + }) async { + if (silenceStartHour != null && silenceEndHour != null) { + await MTFlutterPush.setSilenceTime( + startHour: silenceStartHour, + startMinute: silenceStartMinute ?? 0, + endHour: silenceEndHour, + endMinute: silenceEndMinute ?? 0, + ); + } + } +} +``` + +## 配置和部署 + +### Android配置 +```xml + + + + + + + + + + + + + + + + + + + + + +``` + +### iOS配置 +```xml + +UIBackgroundModes + + remote-notification + +``` + +### 推送证书配置 +- **开发环境**: 配置开发推送证书 +- **生产环境**: 配置生产推送证书 +- **证书管理**: 定期更新推送证书 + +## 安全特性 + +### 数据安全 +- **传输加密**: 推送消息传输加密 +- **身份验证**: 设备身份验证机制 +- **防重放**: 防止推送消息重放攻击 +- **数据校验**: 推送消息完整性校验 + +### 隐私保护 +- **用户同意**: 明确的推送权限申请 +- **数据最小化**: 仅收集必要的设备信息 +- **匿名化**: 用户数据匿名化处理 +- **透明度**: 清晰的隐私政策说明 + +## 性能优化 + +### 推送优化 +- **智能推送**: 基于用户行为的智能推送 +- **频率控制**: 推送频率限制机制 +- **时段控制**: 静默时间设置 +- **内容优化**: 推送内容个性化 + +### 资源管理 +- **内存优化**: 及时释放推送相关资源 +- **电池优化**: 减少推送服务电池消耗 +- **网络优化**: 优化推送网络请求 +- **存储优化**: 合理管理推送数据存储 + +## 总结 + +`flutter_plugin_mtpush_private` 模块作为 OneApp 的美团云推送私有版插件，提供了完整的跨平台推送解决方案。通过与 EngageLab 推送服务的深度集成，实现了高效、可靠的消息推送功能。模块支持丰富的推送类型、精准的用户定位和完善的统计分析，能够满足各种推送场景的需求。良好的安全保护和性能优化机制确保了推送服务的稳定性和用户体验。 diff --git a/basic_utils/kit_app_monitor.md b/basic_utils/kit_app_monitor.md new file mode 100644 index 0000000..9480b91 --- /dev/null +++ b/basic_utils/kit_app_monitor.md @@ -0,0 +1,998 @@ +# Kit App Monitor 应用监控工具包 + +## 模块概述 + +`kit_app_monitor` 是 OneApp 基础工具模块群中的应用监控工具包，负责实时监控应用的性能指标、异常情况、用户行为等关键数据。该插件通过原生平台能力，为应用提供全面的监控和分析功能。 + +### 基本信息 +- **模块名称**: kit_app_monitor +- **版本**: 0.0.2+1 +- **类型**: Flutter Plugin（原生插件） +- **描述**: 应用监控工具包 +- **Flutter 版本**: >=3.0.0 +- **Dart 版本**: >=3.0.0<4.0.0 + +## 功能特性 + +### 核心功能 +1. **性能监控** + - CPU使用率监控 + - 内存使用监控 + - 网络请求性能 + - 帧率(FPS)监控 + +2. **异常监控** + - Crash崩溃监控 + - ANR(应用无响应)检测 + - 网络异常监控 + - 自定义异常上报 + +3. **用户行为分析** + - 页面访问统计 + - 用户操作轨迹 + - 功能使用频率 + - 用户留存分析 + +4. **设备信息收集** + - 设备硬件信息 + - 系统版本信息 + - 应用版本信息 + - 网络环境信息 + +## 技术架构 + +### 目录结构 +``` +kit_app_monitor/ +├── lib/ # Dart代码 +│ ├── kit_app_monitor.dart # 插件入口 +│ ├── src/ # 源代码 +│ │ ├── platform_interface.dart # 平台接口定义 +│ │ ├── method_channel.dart # 方法通道实现 +│ │ ├── models/ # 数据模型 +│ │ │ ├── performance_data.dart +│ │ │ ├── crash_report.dart +│ │ │ └── user_behavior.dart +│ │ └── utils/ # 工具类 +│ └── kit_app_monitor_platform_interface.dart +├── android/ # Android原生代码 +│ ├── src/main/kotlin/ +│ │ └── com/cariadcn/kit_app_monitor/ +│ │ ├── KitAppMonitorPlugin.kt +│ │ ├── PerformanceMonitor.kt +│ │ ├── CrashHandler.kt +│ │ └── BehaviorTracker.kt +│ └── build.gradle +├── ios/ # iOS原生代码 +│ ├── Classes/ +│ │ ├── KitAppMonitorPlugin.swift +│ │ ├── PerformanceMonitor.swift +│ │ ├── CrashHandler.swift +│ │ └── BehaviorTracker.swift +│ └── kit_app_monitor.podspec +├── example/ # 示例应用 +└── test/ # 测试文件 +``` + +### 依赖关系 + +#### 核心依赖 +- `plugin_platform_interface: ^2.0.2` - 插件平台接口 +- `json_annotation: ^4.8.1` - JSON序列化 + +#### 开发依赖 +- `json_serializable: ^6.7.0` - JSON序列化代码生成 +- `build_runner: any` - 代码生成引擎 + +## 核心模块分析 + +### 1. Flutter端实现 + +#### 插件入口 (`lib/kit_app_monitor.dart`) +```dart +class KitAppMonitor { + static const MethodChannel _channel = MethodChannel('kit_app_monitor'); + + static bool _isInitialized = false; + static StreamController? _performanceController; + static StreamController? _crashController; + static StreamController? _behaviorController; + + /// 初始化监控 + static Future initialize({ + bool enablePerformanceMonitoring = true, + bool enableCrashReporting = true, + bool enableBehaviorTracking = true, + String? userId, + Map? customProperties, + }) async { + if (_isInitialized) return; + + await _channel.invokeMethod('initialize', { + 'enablePerformanceMonitoring': enablePerformanceMonitoring, + 'enableCrashReporting': enableCrashReporting, + 'enableBehaviorTracking': enableBehaviorTracking, + 'userId': userId, + 'customProperties': customProperties, + }); + + _setupEventChannels(); + _isInitialized = true; + } + + /// 设置用户ID + static Future setUserId(String userId) async { + await _channel.invokeMethod('setUserId', {'userId': userId}); + } + + /// 设置自定义属性 + static Future setCustomProperty(String key, dynamic value) async { + await _channel.invokeMethod('setCustomProperty', { + 'key': key, + 'value': value, + }); + } + + /// 记录自定义事件 + static Future recordEvent(String eventName, Map? parameters) async { + await _channel.invokeMethod('recordEvent', { + 'eventName': eventName, + 'parameters': parameters, + }); + } + + /// 记录页面访问 + static Future recordPageView(String pageName) async { + await _channel.invokeMethod('recordPageView', {'pageName': pageName}); + } + + /// 记录网络请求 + static Future recordNetworkRequest({ + required String url, + required String method, + required int statusCode, + required int responseTime, + int? requestSize, + int? responseSize, + }) async { + await _channel.invokeMethod('recordNetworkRequest', { + 'url': url, + 'method': method, + 'statusCode': statusCode, + 'responseTime': responseTime, + 'requestSize': requestSize, + 'responseSize': responseSize, + }); + } + + /// 手动记录异常 + static Future recordException({ + required String name, + required String reason, + String? stackTrace, + Map? customData, + }) async { + await _channel.invokeMethod('recordException', { + 'name': name, + 'reason': reason, + 'stackTrace': stackTrace, + 'customData': customData, + }); + } + + /// 获取性能数据流 + static Stream get performanceStream { + _performanceController ??= StreamController.broadcast(); + return _performanceController!.stream; + } + + /// 获取崩溃报告流 + static Stream get crashStream { + _crashController ??= StreamController.broadcast(); + return _crashController!.stream; + } + + /// 获取用户行为流 + static Stream get behaviorStream { + _behaviorController ??= StreamController.broadcast(); + return _behaviorController!.stream; + } + + /// 强制上报数据 + static Future flush() async { + await _channel.invokeMethod('flush'); + } + + /// 设置事件通道 + static void _setupEventChannels() { + const performanceChannel = EventChannel('kit_app_monitor/performance'); + const crashChannel = EventChannel('kit_app_monitor/crash'); + const behaviorChannel = EventChannel('kit_app_monitor/behavior'); + + performanceChannel.receiveBroadcastStream().listen((data) { + final performanceData = PerformanceData.fromJson(data); + _performanceController?.add(performanceData); + }); + + crashChannel.receiveBroadcastStream().listen((data) { + final crashReport = CrashReport.fromJson(data); + _crashController?.add(crashReport); + }); + + behaviorChannel.receiveBroadcastStream().listen((data) { + final userBehavior = UserBehavior.fromJson(data); + _behaviorController?.add(userBehavior); + }); + } + + /// 清理资源 + static void dispose() { + _performanceController?.close(); + _crashController?.close(); + _behaviorController?.close(); + _isInitialized = false; + } +} +``` + +#### 数据模型 (`src/models/`) + +##### 性能数据模型 +```dart +@JsonSerializable() +class PerformanceData { + final double cpuUsage; + final int memoryUsage; + final int totalMemory; + final double fps; + final int networkLatency; + final DateTime timestamp; + final String? pageName; + + const PerformanceData({ + required this.cpuUsage, + required this.memoryUsage, + required this.totalMemory, + required this.fps, + required this.networkLatency, + required this.timestamp, + this.pageName, + }); + + factory PerformanceData.fromJson(Map json) => + _$PerformanceDataFromJson(json); + + Map toJson() => _$PerformanceDataToJson(this); + + double get memoryUsagePercentage => (memoryUsage / totalMemory) * 100; + + bool get isHighCpuUsage => cpuUsage > 80.0; + + bool get isHighMemoryUsage => memoryUsagePercentage > 90.0; + + bool get isLowFps => fps < 30.0; +} +``` + +##### 崩溃报告模型 +```dart +@JsonSerializable() +class CrashReport { + final String crashId; + final String type; + final String message; + final String stackTrace; + final DateTime timestamp; + final String appVersion; + final String deviceModel; + final String osVersion; + final Map customData; + final String? userId; + + const CrashReport({ + required this.crashId, + required this.type, + required this.message, + required this.stackTrace, + required this.timestamp, + required this.appVersion, + required this.deviceModel, + required this.osVersion, + required this.customData, + this.userId, + }); + + factory CrashReport.fromJson(Map json) => + _$CrashReportFromJson(json); + + Map toJson() => _$CrashReportToJson(this); + + bool get isFatal => type.toLowerCase().contains('fatal'); + + bool get isNativeCrash => type.toLowerCase().contains('native'); +} +``` + +##### 用户行为模型 +```dart +@JsonSerializable() +class UserBehavior { + final String eventType; + final String? pageName; + final String? elementName; + final Map parameters; + final DateTime timestamp; + final String? userId; + final String sessionId; + + const UserBehavior({ + required this.eventType, + this.pageName, + this.elementName, + required this.parameters, + required this.timestamp, + this.userId, + required this.sessionId, + }); + + factory UserBehavior.fromJson(Map json) => + _$UserBehaviorFromJson(json); + + Map toJson() => _$UserBehaviorToJson(this); + + bool get isPageView => eventType == 'page_view'; + + bool get isButtonClick => eventType == 'button_click'; + + bool get isUserAction => ['click', 'tap', 'swipe', 'scroll'].contains(eventType); +} +``` + +### 2. Android端实现 + +#### 主插件类 (`KitAppMonitorPlugin.kt`) +```kotlin +class KitAppMonitorPlugin: FlutterPlugin, MethodCallHandler, ActivityAware { + private lateinit var channel: MethodChannel + private lateinit var context: Context + private var activity: Activity? = null + + private var performanceMonitor: PerformanceMonitor? = null + private var crashHandler: CrashHandler? = null + private var behaviorTracker: BehaviorTracker? = null + + private var performanceEventChannel: EventChannel? = null + private var crashEventChannel: EventChannel? = null + private var behaviorEventChannel: EventChannel? = null + + override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) { + channel = MethodChannel(binding.binaryMessenger, "kit_app_monitor") + context = binding.applicationContext + channel.setMethodCallHandler(this) + + // 设置事件通道 + setupEventChannels(binding.binaryMessenger) + } + + private fun setupEventChannels(messenger: BinaryMessenger) { + performanceEventChannel = EventChannel(messenger, "kit_app_monitor/performance") + crashEventChannel = EventChannel(messenger, "kit_app_monitor/crash") + behaviorEventChannel = EventChannel(messenger, "kit_app_monitor/behavior") + } + + override fun onMethodCall(call: MethodCall, result: Result) { + when (call.method) { + "initialize" -> initialize(call, result) + "setUserId" -> setUserId(call, result) + "setCustomProperty" -> setCustomProperty(call, result) + "recordEvent" -> recordEvent(call, result) + "recordPageView" -> recordPageView(call, result) + "recordNetworkRequest" -> recordNetworkRequest(call, result) + "recordException" -> recordException(call, result) + "flush" -> flush(result) + else -> result.notImplemented() + } + } + + private fun initialize(call: MethodCall, result: Result) { + val enablePerformanceMonitoring = call.argument("enablePerformanceMonitoring") ?: true + val enableCrashReporting = call.argument("enableCrashReporting") ?: true + val enableBehaviorTracking = call.argument("enableBehaviorTracking") ?: true + val userId = call.argument("userId") + val customProperties = call.argument>("customProperties") + + try { + if (enablePerformanceMonitoring) { + performanceMonitor = PerformanceMonitor(context) + performanceMonitor?.initialize(performanceEventChannel) + } + + if (enableCrashReporting) { + crashHandler = CrashHandler(context) + crashHandler?.initialize(crashEventChannel) + } + + if (enableBehaviorTracking) { + behaviorTracker = BehaviorTracker(context) + behaviorTracker?.initialize(behaviorEventChannel) + } + + userId?.let { setUserId(it) } + customProperties?.forEach { (key, value) -> + setCustomProperty(key, value) + } + + result.success(true) + } catch (e: Exception) { + result.error("INITIALIZATION_FAILED", e.message, null) + } + } + + private fun recordEvent(call: MethodCall, result: Result) { + val eventName = call.argument("eventName") + val parameters = call.argument>("parameters") + + behaviorTracker?.recordEvent(eventName ?: "", parameters ?: emptyMap()) + result.success(true) + } + + private fun recordPageView(call: MethodCall, result: Result) { + val pageName = call.argument("pageName") + behaviorTracker?.recordPageView(pageName ?: "") + result.success(true) + } + + override fun onAttachedToActivity(binding: ActivityPluginBinding) { + activity = binding.activity + performanceMonitor?.setActivity(activity) + behaviorTracker?.setActivity(activity) + } + + override fun onDetachedFromActivity() { + activity = null + performanceMonitor?.setActivity(null) + behaviorTracker?.setActivity(null) + } +} +``` + +#### 性能监控器 (`PerformanceMonitor.kt`) +```kotlin +class PerformanceMonitor(private val context: Context) { + private var eventSink: EventChannel.EventSink? = null + private var monitoringHandler: Handler? = null + private var activity: Activity? = null + private val updateInterval = 5000L // 5秒更新一次 + + fun initialize(eventChannel: EventChannel?) { + eventChannel?.setStreamHandler(object : EventChannel.StreamHandler { + override fun onListen(arguments: Any?, events: EventChannel.EventSink?) { + eventSink = events + startMonitoring() + } + + override fun onCancel(arguments: Any?) { + eventSink = null + stopMonitoring() + } + }) + } + + fun setActivity(activity: Activity?) { + this.activity = activity + } + + private fun startMonitoring() { + monitoringHandler = Handler(Looper.getMainLooper()) + monitoringHandler?.post(monitoringRunnable) + } + + private fun stopMonitoring() { + monitoringHandler?.removeCallbacks(monitoringRunnable) + monitoringHandler = null + } + + private val monitoringRunnable = object : Runnable { + override fun run() { + collectPerformanceData() + monitoringHandler?.postDelayed(this, updateInterval) + } + } + + private fun collectPerformanceData() { + try { + val cpuUsage = getCpuUsage() + val memoryInfo = getMemoryInfo() + val fps = getFps() + val networkLatency = getNetworkLatency() + + val performanceData = mapOf( + "cpuUsage" to cpuUsage, + "memoryUsage" to memoryInfo.first, + "totalMemory" to memoryInfo.second, + "fps" to fps, + "networkLatency" to networkLatency, + "timestamp" to System.currentTimeMillis(), + "pageName" to getCurrentPageName() + ) + + eventSink?.success(performanceData) + } catch (e: Exception) { + eventSink?.error("PERFORMANCE_ERROR", e.message, null) + } + } + + private fun getCpuUsage(): Double { + // 获取CPU使用率的实现 + return try { + val runtime = Runtime.getRuntime() + val usedMemory = runtime.totalMemory() - runtime.freeMemory() + val maxMemory = runtime.maxMemory() + (usedMemory.toDouble() / maxMemory.toDouble()) * 100 + } catch (e: Exception) { + 0.0 + } + } + + private fun getMemoryInfo(): Pair { + val activityManager = context.getSystemService(Context.ACTIVITY_SERVICE) as ActivityManager + val memoryInfo = ActivityManager.MemoryInfo() + activityManager.getMemoryInfo(memoryInfo) + + val usedMemory = memoryInfo.totalMem - memoryInfo.availMem + return Pair(usedMemory, memoryInfo.totalMem) + } + + private fun getFps(): Double { + // 获取FPS的实现 + return activity?.let { + // 使用Choreographer或其他方式计算FPS + 60.0 // 默认返回60FPS + } ?: 0.0 + } + + private fun getNetworkLatency(): Int { + // 获取网络延迟的实现 + return 0 // 默认返回0 + } + + private fun getCurrentPageName(): String? { + return activity?.let { + it.javaClass.simpleName + } + } +} +``` + +#### 崩溃处理器 (`CrashHandler.kt`) +```kotlin +class CrashHandler(private val context: Context) : Thread.UncaughtExceptionHandler { + private var eventSink: EventChannel.EventSink? = null + private var defaultExceptionHandler: Thread.UncaughtExceptionHandler? = null + + fun initialize(eventChannel: EventChannel?) { + eventChannel?.setStreamHandler(object : EventChannel.StreamHandler { + override fun onListen(arguments: Any?, events: EventChannel.EventSink?) { + eventSink = events + setupCrashHandler() + } + + override fun onCancel(arguments: Any?) { + eventSink = null + restoreDefaultHandler() + } + }) + } + + private fun setupCrashHandler() { + defaultExceptionHandler = Thread.getDefaultUncaughtExceptionHandler() + Thread.setDefaultUncaughtExceptionHandler(this) + } + + private fun restoreDefaultHandler() { + defaultExceptionHandler?.let { + Thread.setDefaultUncaughtExceptionHandler(it) + } + } + + override fun uncaughtException(thread: Thread, exception: Throwable) { + try { + val crashReport = createCrashReport(exception) + eventSink?.success(crashReport) + + // 保存崩溃信息到本地 + saveCrashToLocal(crashReport) + } catch (e: Exception) { + // 处理崩溃报告生成失败的情况 + } finally { + // 调用默认的异常处理器 + defaultExceptionHandler?.uncaughtException(thread, exception) + } + } + + private fun createCrashReport(exception: Throwable): Map { + return mapOf( + "crashId" to UUID.randomUUID().toString(), + "type" to exception.javaClass.simpleName, + "message" to (exception.message ?: ""), + "stackTrace" to getStackTraceString(exception), + "timestamp" to System.currentTimeMillis(), + "appVersion" to getAppVersion(), + "deviceModel" to Build.MODEL, + "osVersion" to Build.VERSION.RELEASE, + "customData" to getCustomData() + ) + } + + private fun getStackTraceString(exception: Throwable): String { + val stringWriter = StringWriter() + val printWriter = PrintWriter(stringWriter) + exception.printStackTrace(printWriter) + return stringWriter.toString() + } + + private fun getAppVersion(): String { + return try { + val packageInfo = context.packageManager.getPackageInfo(context.packageName, 0) + packageInfo.versionName ?: "unknown" + } catch (e: Exception) { + "unknown" + } + } + + private fun getCustomData(): Map { + return mapOf( + "freeMemory" to Runtime.getRuntime().freeMemory(), + "totalMemory" to Runtime.getRuntime().totalMemory(), + "maxMemory" to Runtime.getRuntime().maxMemory() + ) + } + + private fun saveCrashToLocal(crashReport: Map) { + // 将崩溃信息保存到本地文件 + // 用于离线上报 + } +} +``` + +### 3. iOS端实现 + +#### 主插件类 (`KitAppMonitorPlugin.swift`) +```swift +public class KitAppMonitorPlugin: NSObject, FlutterPlugin { + private var performanceMonitor: PerformanceMonitor? + private var crashHandler: CrashHandler? + private var behaviorTracker: BehaviorTracker? + + public static func register(with registrar: FlutterPluginRegistrar) { + let channel = FlutterMethodChannel(name: "kit_app_monitor", + binaryMessenger: registrar.messenger()) + let instance = KitAppMonitorPlugin() + registrar.addMethodCallDelegate(instance, channel: channel) + + instance.setupEventChannels(with: registrar.messenger()) + } + + private func setupEventChannels(with messenger: FlutterBinaryMessenger) { + let performanceChannel = FlutterEventChannel(name: "kit_app_monitor/performance", + binaryMessenger: messenger) + let crashChannel = FlutterEventChannel(name: "kit_app_monitor/crash", + binaryMessenger: messenger) + let behaviorChannel = FlutterEventChannel(name: "kit_app_monitor/behavior", + binaryMessenger: messenger) + + performanceMonitor = PerformanceMonitor() + crashHandler = CrashHandler() + behaviorTracker = BehaviorTracker() + + performanceChannel.setStreamHandler(performanceMonitor) + crashChannel.setStreamHandler(crashHandler) + behaviorChannel.setStreamHandler(behaviorTracker) + } + + public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) { + switch call.method { + case "initialize": + initialize(call: call, result: result) + case "setUserId": + setUserId(call: call, result: result) + case "recordEvent": + recordEvent(call: call, result: result) + case "recordPageView": + recordPageView(call: call, result: result) + case "flush": + flush(result: result) + default: + result(FlutterMethodNotImplemented) + } + } + + private func initialize(call: FlutterMethodCall, result: @escaping FlutterResult) { + guard let args = call.arguments as? [String: Any] else { + result(FlutterError(code: "INVALID_ARGUMENTS", + message: "Invalid arguments", + details: nil)) + return + } + + let enablePerformanceMonitoring = args["enablePerformanceMonitoring"] as? Bool ?? true + let enableCrashReporting = args["enableCrashReporting"] as? Bool ?? true + let enableBehaviorTracking = args["enableBehaviorTracking"] as? Bool ?? true + + if enablePerformanceMonitoring { + performanceMonitor?.startMonitoring() + } + + if enableCrashReporting { + crashHandler?.setupCrashHandler() + } + + if enableBehaviorTracking { + behaviorTracker?.startTracking() + } + + result(true) + } +} +``` + +## 使用示例 + +### 基础使用 +```dart +class MonitorExample extends StatefulWidget { + @override + _MonitorExampleState createState() => _MonitorExampleState(); +} + +class _MonitorExampleState extends State { + StreamSubscription? _performanceSubscription; + StreamSubscription? _crashSubscription; + + @override + void initState() { + super.initState(); + _initializeMonitoring(); + } + + Future _initializeMonitoring() async { + // 初始化监控 + await KitAppMonitor.initialize( + enablePerformanceMonitoring: true, + enableCrashReporting: true, + enableBehaviorTracking: true, + userId: 'user_123', + customProperties: { + 'app_version': '1.0.0', + 'build_number': '100', + }, + ); + + // 监听性能数据 + _performanceSubscription = KitAppMonitor.performanceStream.listen((data) { + if (data.isHighCpuUsage || data.isHighMemoryUsage || data.isLowFps) { + _handlePerformanceIssue(data); + } + }); + + // 监听崩溃报告 + _crashSubscription = KitAppMonitor.crashStream.listen((crash) { + _handleCrashReport(crash); + }); + + // 记录应用启动事件 + await KitAppMonitor.recordEvent('app_start', { + 'launch_time': DateTime.now().millisecondsSinceEpoch, + 'is_cold_start': true, + }); + } + + void _handlePerformanceIssue(PerformanceData data) { + // 处理性能问题 + print('Performance issue detected: ' + 'CPU: ${data.cpuUsage}%, ' + 'Memory: ${data.memoryUsagePercentage}%, ' + 'FPS: ${data.fps}'); + + // 记录性能问题事件 + KitAppMonitor.recordEvent('performance_issue', { + 'cpu_usage': data.cpuUsage, + 'memory_usage': data.memoryUsagePercentage, + 'fps': data.fps, + 'page_name': data.pageName, + }); + } + + void _handleCrashReport(CrashReport crash) { + // 处理崩溃报告 + print('Crash detected: ${crash.type} - ${crash.message}'); + + // 可以在这里实现自定义的崩溃处理逻辑 + // 例如发送到自定义的崩溃收集服务 + } + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('Monitor Example')), + body: Column( + children: [ + ElevatedButton( + onPressed: () => _simulateHighCpuUsage(), + child: Text('Simulate High CPU'), + ), + ElevatedButton( + onPressed: () => _simulateMemoryLeak(), + child: Text('Simulate Memory Issue'), + ), + ElevatedButton( + onPressed: () => _simulateCrash(), + child: Text('Simulate Crash'), + ), + ElevatedButton( + onPressed: () => _recordCustomEvent(), + child: Text('Record Custom Event'), + ), + ], + ), + ); + } + + void _simulateHighCpuUsage() { + // 模拟高CPU使用 + Timer.periodic(Duration(milliseconds: 1), (timer) { + // 执行密集计算 + for (int i = 0; i < 1000000; i++) { + math.sqrt(i); + } + + if (timer.tick > 1000) { + timer.cancel(); + } + }); + } + + void _simulateMemoryLeak() { + // 模拟内存泄漏 + List> memoryHog = []; + for (int i = 0; i < 1000; i++) { + memoryHog.add(List.filled(1000000, i)); + } + } + + void _simulateCrash() { + // 模拟崩溃 + throw Exception('Simulated crash for testing'); + } + + void _recordCustomEvent() { + KitAppMonitor.recordEvent('button_clicked', { + 'button_name': 'custom_event_button', + 'timestamp': DateTime.now().millisecondsSinceEpoch, + 'user_action': 'tap', + }); + } + + @override + void dispose() { + _performanceSubscription?.cancel(); + _crashSubscription?.cancel(); + super.dispose(); + } +} +``` + +### 高级监控配置 +```dart +class AdvancedMonitorConfig { + static Future setupAdvancedMonitoring() async { + // 初始化高级监控配置 + await KitAppMonitor.initialize( + enablePerformanceMonitoring: true, + enableCrashReporting: true, + enableBehaviorTracking: true, + userId: await _getUserId(), + customProperties: await _getCustomProperties(), + ); + + // 设置性能监控阈值 + _setupPerformanceThresholds(); + + // 设置自动页面跟踪 + _setupAutomaticPageTracking(); + + // 设置网络监控 + _setupNetworkMonitoring(); + } + + static void _setupPerformanceThresholds() { + KitAppMonitor.performanceStream.listen((data) { + // CPU使用率过高 + if (data.cpuUsage > 80) { + KitAppMonitor.recordEvent('high_cpu_usage', { + 'cpu_usage': data.cpuUsage, + 'page_name': data.pageName, + 'severity': 'warning', + }); + } + + // 内存使用率过高 + if (data.memoryUsagePercentage > 90) { + KitAppMonitor.recordEvent('high_memory_usage', { + 'memory_usage': data.memoryUsagePercentage, + 'total_memory': data.totalMemory, + 'severity': 'critical', + }); + } + + // FPS过低 + if (data.fps < 30) { + KitAppMonitor.recordEvent('low_fps', { + 'fps': data.fps, + 'page_name': data.pageName, + 'severity': 'warning', + }); + } + }); + } + + static void _setupAutomaticPageTracking() { + // 可以与路由系统集成，自动记录页面访问 + // 这里是一个简化的示例 + NavigatorObserver observer = RouteObserver>(); + // 实现路由监听，自动调用 KitAppMonitor.recordPageView + } + + static void _setupNetworkMonitoring() { + // 可以与网络请求库集成，自动记录网络请求 + // 例如与 Dio 集成 + // dio.interceptors.add(MonitoringInterceptor()); + } + + static Future _getUserId() async { + // 获取用户ID的逻辑 + return 'user_123'; + } + + static Future> _getCustomProperties() async { + return { + 'app_version': await _getAppVersion(), + 'device_model': await _getDeviceModel(), + 'os_version': await _getOSVersion(), + 'network_type': await _getNetworkType(), + }; + } +} +``` + +## 性能优化 + +### 数据采集优化 +- **采样策略**: 根据性能影响调整数据采集频率 +- **批量上报**: 批量发送监控数据减少网络请求 +- **本地缓存**: 离线时缓存数据，联网后上报 +- **数据压缩**: 压缩监控数据减少传输量 + +### 内存管理 +- **及时清理**: 及时清理监控数据和临时对象 +- **内存监控**: 监控自身内存使用避免影响应用 +- **弱引用**: 使用弱引用避免内存泄漏 +- **资源复用**: 复用监控相关对象 + +## 安全和隐私 + +### 数据安全 +- **敏感信息过滤**: 过滤用户敏感信息 +- **数据加密**: 加密存储和传输监控数据 +- **访问控制**: 严格的数据访问权限控制 +- **数据脱敏**: 对敏感数据进行脱敏处理 + +### 隐私合规 +- **用户同意**: 明确的数据收集用户同意 +- **数据最小化**: 仅收集必要的监控数据 +- **透明度**: 清晰的隐私政策说明 +- **用户控制**: 用户可控制监控功能开关 + +## 总结 + +`kit_app_monitor` 模块作为 OneApp 的应用监控工具包，提供了全面的应用性能监控、异常检测和用户行为分析能力。通过原生平台的深度集成，实现了高效、准确的应用监控功能。模块具有良好的性能优化和隐私保护机制，能够帮助开发团队及时发现和解决应用问题，提升用户体验。 diff --git a/build-docs.bat b/build-docs.bat new file mode 100644 index 0000000..e849e58 --- /dev/null +++ b/build-docs.bat @@ -0,0 +1,50 @@ +@echo off +chcp 65001 >nul +title OneApp 文档构建 + +echo. +echo ============================================== +echo OneApp 文档自动构建脚本 +echo ============================================== +echo. + +REM 检查PowerShell是否可用 +powershell -Command "Write-Host 'PowerShell 可用'" >nul 2>&1 +if errorlevel 1 ( + echo 错误: PowerShell 不可用，请确保系统支持PowerShell + pause + exit /b 1 +) + +REM 获取用户选择 +echo 请选择构建选项: +echo 1. 构建文档并清理docs目录 (推荐) +echo 2. 构建文档但保留docs目录 +echo 3. 显示帮助信息 +echo 4. 退出 +echo. +set /p choice="请输入选项 (1-4): " + +if "%choice%"=="1" ( + echo. + echo 开始构建文档... + powershell -ExecutionPolicy Bypass -File "%~dp0build-docs.ps1" + echo. + echo 构建完成！ +) else if "%choice%"=="2" ( + echo. + echo 开始构建文档 (保留docs目录)... + powershell -ExecutionPolicy Bypass -File "%~dp0build-docs.ps1" -KeepDocs + echo. + echo 构建完成！ +) else if "%choice%"=="3" ( + powershell -ExecutionPolicy Bypass -File "%~dp0build-docs.ps1" -Help + pause +) else if "%choice%"=="4" ( + echo 退出脚本 + exit /b 0 +) else ( + echo 无效选项，请重新运行脚本 + pause + exit /b 1 +) \ No newline at end of file diff --git a/build-docs.ps1 b/build-docs.ps1 new file mode 100644 index 0000000..9c67843 --- /dev/null +++ b/build-docs.ps1 @@ -0,0 +1,115 @@ +# OneApp Documentation Build Script +param( + [switch]$KeepDocs = $false, + [switch]$Help = $false +) + +if ($Help) { + Write-Host "OneApp Documentation Build Script" -ForegroundColor Green + Write-Host "" + Write-Host "Usage:" + Write-Host " .\build-docs.ps1 # Build docs and cleanup" + Write-Host " .\build-docs.ps1 -KeepDocs # Build but keep docs" + Write-Host " .\build-docs.ps1 -Help # Show help" + exit 0 +} + +$ErrorActionPreference = "Stop" +$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +$RootDir = $ScriptDir +$DocsDir = Join-Path $RootDir "docs" +$SiteDir = Join-Path $RootDir "site" + +Write-Host "=== OneApp Documentation Build Start ===" -ForegroundColor Green +Write-Host "Root: $RootDir" +Write-Host "Docs: $DocsDir" +Write-Host "Site: $SiteDir" +Write-Host "" + +try { + Write-Host "Step 1/4: Preparing docs directory..." -ForegroundColor Yellow + + if (Test-Path $DocsDir) { + Remove-Item $DocsDir -Recurse -Force + } + + New-Item -Path $DocsDir -ItemType Directory -Force | Out-Null + Write-Host "docs directory created" -ForegroundColor Green + + Write-Host "" + Write-Host "Step 2/4: Copying source files..." -ForegroundColor Yellow + + # Copy markdown files + Get-ChildItem -Path $RootDir -Filter "*.md" | ForEach-Object { + Copy-Item $_.FullName -Destination (Join-Path $DocsDir $_.Name) -Force + Write-Host "Copied: $($_.Name)" -ForegroundColor Gray + } + + # Copy directories + $Folders = @("account", "after_sales", "app_car", "basic_uis", "basic_utils", + "car_sales", "community", "membership", "service_component", + "setting", "touch_point", "images", "assets") + + foreach ($Folder in $Folders) { + $SourcePath = Join-Path $RootDir $Folder + if (Test-Path $SourcePath) { + Copy-Item $SourcePath -Destination (Join-Path $DocsDir $Folder) -Recurse -Force + Write-Host "Copied folder: $Folder" -ForegroundColor Gray + } + } + + Write-Host "File copy completed" -ForegroundColor Green + + Write-Host "" + Write-Host "Step 3/4: Building MkDocs..." -ForegroundColor Yellow + + try { + $null = Get-Command "python" -ErrorAction Stop + Write-Host "Python found" + } catch { + throw "Python not found. Please install Python first." + } + + Write-Host "Running: python -m mkdocs build --clean" + & python -m mkdocs build --clean + + if ($LASTEXITCODE -eq 0) { + Write-Host "Build successful!" -ForegroundColor Green + + if (Test-Path $SiteDir) { + $Files = Get-ChildItem $SiteDir -Recurse -File + $Size = [math]::Round(($Files | Measure-Object Length -Sum).Sum / 1MB, 2) + Write-Host "Files: $($Files.Count), Size: $Size MB" + } + } else { + throw "Build failed with exit code: $LASTEXITCODE" + } + + Write-Host "" + Write-Host "Step 4/4: Cleanup..." -ForegroundColor Yellow + + if ($KeepDocs) { + Write-Host "Keeping docs directory" -ForegroundColor Cyan + } else { + if (Test-Path $DocsDir) { + Remove-Item $DocsDir -Recurse -Force + Write-Host "docs directory cleaned" -ForegroundColor Green + } + } + + Write-Host "" + Write-Host "=== Build Completed ===" -ForegroundColor Green + Write-Host "Site: $SiteDir" -ForegroundColor Green + Write-Host "Open: site/index.html" -ForegroundColor Cyan + +} catch { + Write-Host "" + Write-Host "=== Build Failed ===" -ForegroundColor Red + Write-Host "Error: $($_.Exception.Message)" -ForegroundColor Red + + if ((Test-Path $DocsDir) -and (-not $KeepDocs)) { + Remove-Item $DocsDir -Recurse -Force -ErrorAction SilentlyContinue + } + + exit 1 +} \ No newline at end of file diff --git a/car_sales/README.md b/car_sales/README.md new file mode 100644 index 0000000..d3b564b --- /dev/null +++ b/car_sales/README.md @@ -0,0 +1,1027 @@ +# OneApp Car Sales - 汽车销售模块文档 + +## 模块概述 + +`oneapp_car_sales` 是 OneApp 的汽车销售核心模块，提供车型展示、在线选车、试驾预约、销售线索管理、经销商服务等功能。该模块集成了地图服务、触点管理、售后服务等，为用户提供完整的购车体验。 + +### 基本信息 +- **模块名称**: oneapp_car_sales +- **版本**: 0.0.1 +- **类型**: Flutter Package +- **Dart 版本**: >=3.0.0 <4.0.0 +- **Flutter 版本**: >=3.0.0 + +## 目录结构 + +``` +oneapp_car_sales/ +├── lib/ +│ ├── oneapp_car_sales.dart # 主导出文件 +│ └── src/ # 源代码目录 +│ ├── pages/ # 销售页面 +│ ├── widgets/ # 销售组件 +│ ├── models/ # 数据模型 +│ ├── services/ # 服务层 +│ ├── blocs/ # 状态管理 +│ ├── utils/ # 工具类 +│ └── constants/ # 常量定义 +├── assets/ # 静态资源 +├── ios/ # iOS 配置 +├── pubspec.yaml # 依赖配置 +└── README.md # 项目说明 +``` + +## 核心功能模块 + +### 1. 车型展示与选择 + +#### 车型目录服务 +```dart +// 车型目录服务 +class VehicleCatalogService { + final CatalogRepository _repository; + final ConfigurationService _configService; + + VehicleCatalogService(this._repository, this._configService); + + // 获取车型列表 + Future>> getVehicleModels({ + VehicleBrand? brand, + VehicleCategory? category, + PriceRange? priceRange, + List? features, + int page = 1, + int pageSize = 20, + }) async { + try { + final filters = VehicleFilters( + brand: brand, + category: category, + priceRange: priceRange, + features: features, + ); + + final models = await _repository.getVehicleModels( + filters: filters, + page: page, + pageSize: pageSize, + ); + + return Right(models); + } catch (e) { + return Left(SalesFailure.catalogLoadFailed(e.toString())); + } + } + + // 获取车型详情 + Future> getVehicleDetail(String modelId) async { + try { + final detail = await _repository.getVehicleDetail(modelId); + return Right(detail); + } catch (e) { + return Left(SalesFailure.detailLoadFailed(e.toString())); + } + } + + // 获取车型配置选项 + Future> getVehicleConfiguration( + String modelId, + ) async { + try { + final configuration = await _configService.getModelConfiguration(modelId); + return Right(configuration); + } catch (e) { + return Left(SalesFailure.configurationLoadFailed(e.toString())); + } + } + + // 计算车型价格 + Future> calculateVehiclePrice({ + required String modelId, + required Map selectedOptions, + String? dealerCode, + List? promotions, + }) async { + try { + final pricing = await _repository.calculatePrice( + modelId: modelId, + options: selectedOptions, + dealerCode: dealerCode, + promotions: promotions, + ); + + return Right(pricing); + } catch (e) { + return Left(SalesFailure.pricingCalculationFailed(e.toString())); + } + } +} + +// 车型数据模型 +class VehicleModel { + final String id; + final String name; + final VehicleBrand brand; + final VehicleCategory category; + final String description; + final List images; + final String mainImage; + final PriceRange priceRange; + final VehicleSpecs specifications; + final List features; + final List colors; + final double rating; + final int reviewCount; + final bool isAvailable; + final DateTime? launchDate; + + const VehicleModel({ + required this.id, + required this.name, + required this.brand, + required this.category, + required this.description, + required this.images, + required this.mainImage, + required this.priceRange, + required this.specifications, + required this.features, + required this.colors, + required this.rating, + required this.reviewCount, + required this.isAvailable, + this.launchDate, + }); + + String get displayPrice => '${priceRange.min.toStringAsFixed(1)}万起'; + bool get isNewModel => launchDate != null && + DateTime.now().difference(launchDate!).inDays < 90; +} +``` + +### 2. 试驾预约管理 + +#### 试驾预约服务 +```dart +// 试驾预约服务 +class TestDriveService { + final TestDriveRepository _repository; + final DealerService _dealerService; + final NotificationService _notificationService; + + TestDriveService( + this._repository, + this._dealerService, + this._notificationService, + ); + + // 创建试驾预约 + Future> createTestDriveAppointment({ + required String userId, + required String vehicleModelId, + required String dealerId, + required DateTime preferredDateTime, + String? alternativeDateTime, + required CustomerInfo customerInfo, + String? specialRequests, + }) async { + try { + // 检查时间段可用性 + final isAvailable = await _checkTimeSlotAvailability( + dealerId: dealerId, + dateTime: preferredDateTime, + vehicleModelId: vehicleModelId, + ); + + if (!isAvailable) { + return Left(SalesFailure.timeSlotNotAvailable()); + } + + // 创建预约 + final appointment = TestDriveAppointment( + id: generateId(), + userId: userId, + vehicleModelId: vehicleModelId, + dealerId: dealerId, + customerInfo: customerInfo, + preferredDateTime: preferredDateTime, + alternativeDateTime: alternativeDateTime != null + ? DateTime.tryParse(alternativeDateTime) + : null, + specialRequests: specialRequests, + status: TestDriveStatus.pending, + createdAt: DateTime.now(), + ); + + await _repository.createTestDriveAppointment(appointment); + + // 发送确认通知 + await _notificationService.sendTestDriveConfirmation( + userId: userId, + appointment: appointment, + ); + + // 通知经销商 + await _notifyDealer(appointment); + + return Right(appointment); + } catch (e) { + return Left(SalesFailure.appointmentCreationFailed(e.toString())); + } + } + + // 获取可用时间段 + Future>> getAvailableTimeSlots({ + required String dealerId, + required String vehicleModelId, + required DateTime date, + }) async { + try { + final dealer = await _dealerService.getDealerById(dealerId); + if (dealer == null) { + return Left(SalesFailure.dealerNotFound()); + } + + final businessHours = dealer.businessHours[date.weekday - 1]; + final bookedSlots = await _repository.getBookedTimeSlots( + dealerId: dealerId, + date: date, + ); + + final availableSlots = _generateAvailableSlots( + businessHours: businessHours, + bookedSlots: bookedSlots, + vehicleModelId: vehicleModelId, + ); + + return Right(availableSlots); + } catch (e) { + return Left(SalesFailure.timeSlotsLoadFailed(e.toString())); + } + } + + // 获取用户试驾历史 + Future>> getUserTestDriveHistory( + String userId, + ) async { + try { + final appointments = await _repository.getUserTestDriveAppointments(userId); + return Right(appointments); + } catch (e) { + return Left(SalesFailure.historyLoadFailed(e.toString())); + } + } +} + +// 试驾预约模型 +class TestDriveAppointment { + final String id; + final String userId; + final String vehicleModelId; + final String dealerId; + final CustomerInfo customerInfo; + final DateTime preferredDateTime; + final DateTime? alternativeDateTime; + final String? specialRequests; + final TestDriveStatus status; + final DateTime createdAt; + final DateTime? confirmedAt; + final DateTime? completedAt; + final String? salesRepId; + final TestDriveFeedback? feedback; + + const TestDriveAppointment({ + required this.id, + required this.userId, + required this.vehicleModelId, + required this.dealerId, + required this.customerInfo, + required this.preferredDateTime, + this.alternativeDateTime, + this.specialRequests, + required this.status, + required this.createdAt, + this.confirmedAt, + this.completedAt, + this.salesRepId, + this.feedback, + }); + + bool get isUpcoming => status == TestDriveStatus.confirmed && + preferredDateTime.isAfter(DateTime.now()); + + bool get isPast => completedAt != null || + (status == TestDriveStatus.confirmed && + preferredDateTime.isBefore(DateTime.now().subtract(Duration(hours: 2)))); +} +``` + +### 3. 经销商管理 + +#### 经销商服务 +```dart +// 经销商服务 +class DealerService { + final DealerRepository _repository; + final LocationService _locationService; + + DealerService(this._repository, this._locationService); + + // 查找附近经销商 + Future>> findNearbyDealers({ + required LatLng userLocation, + double radiusKm = 50, + VehicleBrand? brand, + List? services, + }) async { + try { + final dealers = await _repository.findDealersNearLocation( + location: userLocation, + radius: radiusKm, + brand: brand, + services: services, + ); + + // 计算距离并排序 + final dealersWithDistance = dealers.map((dealer) { + final distance = _locationService.calculateDistance( + userLocation, + dealer.location, + ); + return DealerWithDistance(dealer: dealer, distance: distance); + }).toList(); + + dealersWithDistance.sort((a, b) => a.distance.compareTo(b.distance)); + + return Right(dealersWithDistance.map((d) => d.dealer).toList()); + } catch (e) { + return Left(SalesFailure.dealerSearchFailed(e.toString())); + } + } + + // 获取经销商详情 + Future> getDealerDetail(String dealerId) async { + try { + final dealer = await _repository.getDealerById(dealerId); + if (dealer == null) { + return Left(SalesFailure.dealerNotFound()); + } + + final detail = DealerDetail( + dealer: dealer, + salesReps: await _repository.getDealerSalesReps(dealerId), + reviews: await _repository.getDealerReviews(dealerId), + inventory: await _repository.getDealerInventory(dealerId), + ); + + return Right(detail); + } catch (e) { + return Left(SalesFailure.dealerDetailLoadFailed(e.toString())); + } + } + + // 获取经销商库存 + Future>> getDealerInventory({ + required String dealerId, + String? modelId, + bool availableOnly = true, + }) async { + try { + final inventory = await _repository.getDealerInventory( + dealerId, + modelId: modelId, + availableOnly: availableOnly, + ); + return Right(inventory); + } catch (e) { + return Left(SalesFailure.inventoryLoadFailed(e.toString())); + } + } +} + +// 经销商数据模型 +class Dealer { + final String id; + final String name; + final String code; + final VehicleBrand primaryBrand; + final List supportedBrands; + final DealerType type; + final Address address; + final LatLng location; + final ContactInfo contactInfo; + final List businessHours; + final List services; + final double rating; + final int reviewCount; + final List certifications; + final List images; + final bool isAuthorized; + final bool isActive; + + const Dealer({ + required this.id, + required this.name, + required this.code, + required this.primaryBrand, + required this.supportedBrands, + required this.type, + required this.address, + required this.location, + required this.contactInfo, + required this.businessHours, + required this.services, + required this.rating, + required this.reviewCount, + required this.certifications, + required this.images, + required this.isAuthorized, + required this.isActive, + }); + + bool get isOpen { + final now = DateTime.now(); + final todayHours = businessHours[now.weekday - 1]; + return todayHours.isOpen(now); + } + + bool get supportsTestDrive => services.contains(DealerService.testDrive); + bool get supportsService => services.contains(DealerService.afterSales); +} +``` + +### 4. 销售线索管理 + +#### 线索管理服务 +```dart +// 销售线索管理服务 +class SalesLeadService { + final LeadRepository _repository; + final CrmIntegrationService _crmService; + final NotificationService _notificationService; + + SalesLeadService( + this._repository, + this._crmService, + this._notificationService, + ); + + // 创建销售线索 + Future> createSalesLead({ + required String userId, + required LeadSource source, + required String vehicleModelId, + String? dealerId, + required CustomerInfo customerInfo, + LeadType type = LeadType.inquiry, + String? notes, + Map? metadata, + }) async { + try { + final lead = SalesLead( + id: generateId(), + userId: userId, + source: source, + type: type, + vehicleModelId: vehicleModelId, + dealerId: dealerId, + customerInfo: customerInfo, + status: LeadStatus.new_, + priority: _calculateLeadPriority(source, type, customerInfo), + notes: notes, + metadata: metadata, + createdAt: DateTime.now(), + ); + + await _repository.createSalesLead(lead); + + // 同步到 CRM 系统 + await _crmService.syncLead(lead); + + // 分配给销售代表 + await _assignToSalesRep(lead); + + return Right(lead); + } catch (e) { + return Left(SalesFailure.leadCreationFailed(e.toString())); + } + } + + // 更新线索状态 + Future> updateLeadStatus({ + required String leadId, + required LeadStatus status, + String? salesRepId, + String? notes, + }) async { + try { + await _repository.updateLeadStatus( + leadId: leadId, + status: status, + salesRepId: salesRepId, + notes: notes, + updatedAt: DateTime.now(), + ); + + // 发送状态更新通知 + await _notificationService.sendLeadStatusUpdate( + leadId: leadId, + status: status, + ); + + return Right(unit); + } catch (e) { + return Left(SalesFailure.leadUpdateFailed(e.toString())); + } + } + + // 获取用户销售线索 + Future>> getUserSalesLeads(String userId) async { + try { + final leads = await _repository.getUserSalesLeads(userId); + return Right(leads); + } catch (e) { + return Left(SalesFailure.leadsLoadFailed(e.toString())); + } + } + + // 计算线索优先级 + LeadPriority _calculateLeadPriority( + LeadSource source, + LeadType type, + CustomerInfo customerInfo, + ) { + int score = 0; + + // 根据来源计分 + switch (source) { + case LeadSource.testDrive: + score += 40; + break; + case LeadSource.configurationTool: + score += 30; + break; + case LeadSource.dealerInquiry: + score += 35; + break; + case LeadSource.websiteBrowsing: + score += 20; + break; + } + + // 根据类型计分 + switch (type) { + case LeadType.purchaseIntent: + score += 30; + break; + case LeadType.testDriveRequest: + score += 25; + break; + case LeadType.priceInquiry: + score += 20; + break; + case LeadType.generalInquiry: + score += 10; + break; + } + + // 根据客户信息计分 + if (customerInfo.hasValidPhone) score += 10; + if (customerInfo.hasValidEmail) score += 10; + if (customerInfo.preferredContactTime != null) score += 5; + + if (score >= 70) return LeadPriority.high; + if (score >= 50) return LeadPriority.medium; + return LeadPriority.low; + } +} + +// 销售线索模型 +class SalesLead { + final String id; + final String userId; + final LeadSource source; + final LeadType type; + final String vehicleModelId; + final String? dealerId; + final CustomerInfo customerInfo; + final LeadStatus status; + final LeadPriority priority; + final String? notes; + final Map? metadata; + final DateTime createdAt; + final DateTime? updatedAt; + final String? salesRepId; + final List activities; + + const SalesLead({ + required this.id, + required this.userId, + required this.source, + required this.type, + required this.vehicleModelId, + this.dealerId, + required this.customerInfo, + required this.status, + required this.priority, + this.notes, + this.metadata, + required this.createdAt, + this.updatedAt, + this.salesRepId, + this.activities = const [], + }); + + bool get isActive => ![LeadStatus.closed, LeadStatus.lost].contains(status); + bool get hasAssignedRep => salesRepId != null; + Duration get age => DateTime.now().difference(createdAt); +} +``` + +## 页面组件设计 + +### 车型展示页面 +```dart +// 车型展示页面 +class VehicleCatalogPage extends StatefulWidget { + @override + _VehicleCatalogPageState createState() => _VehicleCatalogPageState(); +} + +class _VehicleCatalogPageState extends State { + late VehicleCatalogBloc _catalogBloc; + final SwiperController _swiperController = SwiperController(); + + @override + void initState() { + super.initState(); + _catalogBloc = context.read(); + _catalogBloc.add(LoadVehicleModels()); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + body: CustomScrollView( + slivers: [ + _buildAppBar(), + _buildFilterSection(), + _buildVehicleGrid(), + ], + ), + ); + } + + Widget _buildVehicleGrid() { + return BlocBuilder( + builder: (context, state) { + if (state is VehicleCatalogLoaded) { + return SliverGrid( + gridDelegate: SliverGridDelegateWithFixedCrossAxisCount( + crossAxisCount: 2, + childAspectRatio: 0.75, + crossAxisSpacing: 16, + mainAxisSpacing: 16, + ), + delegate: SliverChildBuilderDelegate( + (context, index) { + return VehicleCard( + vehicle: state.vehicles[index], + onTap: () => _navigateToVehicleDetail(state.vehicles[index]), + ); + }, + childCount: state.vehicles.length, + ), + ); + } + return SliverToBoxAdapter(child: VehicleGridSkeleton()); + }, + ); + } +} + +// 车型卡片组件 +class VehicleCard extends StatelessWidget { + final VehicleModel vehicle; + final VoidCallback? onTap; + + const VehicleCard({ + Key? key, + required this.vehicle, + this.onTap, + }) : super(key: key); + + @override + Widget build(BuildContext context) { + return Card( + elevation: 4, + shape: RoundedRectangleBorder( + borderRadius: BorderRadius.circular(12), + ), + child: InkWell( + onTap: onTap, + borderRadius: BorderRadius.circular(12), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + _buildImageSection(), + _buildInfoSection(), + _buildActionSection(), + ], + ), + ), + ); + } + + Widget _buildImageSection() { + return Expanded( + flex: 3, + child: Container( + width: double.infinity, + decoration: BoxDecoration( + borderRadius: BorderRadius.vertical(top: Radius.circular(12)), + image: DecorationImage( + image: NetworkImage(vehicle.mainImage), + fit: BoxFit.cover, + ), + ), + child: Stack( + children: [ + if (vehicle.isNewModel) + Positioned( + top: 8, + left: 8, + child: Container( + padding: EdgeInsets.symmetric(horizontal: 8, vertical: 4), + decoration: BoxDecoration( + color: Colors.red, + borderRadius: BorderRadius.circular(12), + ), + child: Text( + '新车', + style: TextStyle( + color: Colors.white, + fontSize: 12, + fontWeight: FontWeight.bold, + ), + ), + ), + ), + Positioned( + bottom: 8, + right: 8, + child: Container( + padding: EdgeInsets.symmetric(horizontal: 8, vertical: 4), + decoration: BoxDecoration( + color: Colors.black54, + borderRadius: BorderRadius.circular(12), + ), + child: Row( + mainAxisSize: MainAxisSize.min, + children: [ + Icon(Icons.star, color: Colors.yellow, size: 14), + SizedBox(width: 4), + Text( + vehicle.rating.toStringAsFixed(1), + style: TextStyle(color: Colors.white, fontSize: 12), + ), + ], + ), + ), + ), + ], + ), + ), + ); + } + + Widget _buildInfoSection() { + return Expanded( + flex: 2, + child: Padding( + padding: EdgeInsets.all(12), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text( + vehicle.name, + style: TextStyle( + fontSize: 16, + fontWeight: FontWeight.bold, + ), + maxLines: 1, + overflow: TextOverflow.ellipsis, + ), + SizedBox(height: 4), + Text( + vehicle.brand.name, + style: TextStyle( + fontSize: 14, + color: Colors.grey[600], + ), + ), + Spacer(), + Text( + vehicle.displayPrice, + style: TextStyle( + fontSize: 18, + fontWeight: FontWeight.bold, + color: Colors.blue, + ), + ), + ], + ), + ), + ); + } +} +``` + +### 试驾预约页面 +```dart +// 试驾预约页面 +class TestDriveBookingPage extends StatefulWidget { + final VehicleModel vehicle; + + const TestDriveBookingPage({required this.vehicle}); + + @override + _TestDriveBookingPageState createState() => _TestDriveBookingPageState(); +} + +class _TestDriveBookingPageState extends State { + late TestDriveBloc _testDriveBloc; + final _formKey = GlobalKey(); + final _customerInfoController = CustomerInfoController(); + + Dealer? _selectedDealer; + DateTime? _selectedDate; + TimeSlot? _selectedTimeSlot; + + @override + void initState() { + super.initState(); + _testDriveBloc = context.read(); + _loadNearbyDealers(); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar( + title: Text('预约试驾 - ${widget.vehicle.name}'), + ), + body: Form( + key: _formKey, + child: ListView( + padding: EdgeInsets.all(16), + children: [ + _buildVehicleSection(), + SizedBox(height: 24), + _buildDealerSelection(), + SizedBox(height: 24), + _buildDateTimeSelection(), + SizedBox(height: 24), + _buildCustomerInfoForm(), + SizedBox(height: 24), + _buildSpecialRequestsField(), + SizedBox(height: 32), + _buildSubmitButton(), + ], + ), + ), + ); + } + + Widget _buildDealerSelection() { + return Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text( + '选择经销商', + style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold), + ), + SizedBox(height: 12), + BlocBuilder( + builder: (context, state) { + if (state is DealersLoaded) { + return Column( + children: state.dealers.map((dealer) { + return DealerSelectionCard( + dealer: dealer, + isSelected: _selectedDealer?.id == dealer.id, + onSelected: () => _selectDealer(dealer), + ); + }).toList(), + ); + } + return DealerSelectionSkeleton(); + }, + ), + ], + ); + } + + Widget _buildDateTimeSelection() { + return Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text( + '选择时间', + style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold), + ), + SizedBox(height: 12), + DatePickerWidget( + onDateSelected: (date) => _selectDate(date), + minDate: DateTime.now(), + maxDate: DateTime.now().add(Duration(days: 30)), + ), + if (_selectedDate != null) ...[ + SizedBox(height: 16), + TimeSlotGrid( + availableSlots: _getAvailableTimeSlots(), + selectedSlot: _selectedTimeSlot, + onSlotSelected: (slot) => _selectTimeSlot(slot), + ), + ], + ], + ); + } +} +``` + +## 状态管理 + +### 车型目录状态管理 +```dart +// 车型目录状态 BLoC +class VehicleCatalogBloc extends Bloc { + final VehicleCatalogService _catalogService; + + VehicleCatalogBloc(this._catalogService) : super(VehicleCatalogInitial()) { + on(_onLoadVehicleModels); + on(_onFilterVehicles); + on(_onSearchVehicles); + } + + Future _onLoadVehicleModels( + LoadVehicleModels event, + Emitter emit, + ) async { + emit(VehicleCatalogLoading()); + + final result = await _catalogService.getVehicleModels( + brand: event.brand, + category: event.category, + priceRange: event.priceRange, + ); + + result.fold( + (failure) => emit(VehicleCatalogError(failure.message)), + (vehicles) => emit(VehicleCatalogLoaded(vehicles)), + ); + } +} +``` + +## 依赖管理 + +### 核心模块依赖 +- **basic_utils**: 基础工具类 +- **basic_uis**: 基础 UI 组件 +- **app_configuration**: 应用配置 +- **oneapp_after_sales**: 售后服务集成 +- **oneapp_touch_point**: 触点管理集成 + +### UI 相关依赖 +- **card_swiper**: 卡片轮播组件，用于车型图片展示 +- **flutter_pickers**: 选择器组件，用于日期时间选择 +- **ui_mapview**: 地图视图组件，用于经销商位置展示 + +### 定位相关依赖 +- **amap_flutter_location**: 高德地图定位服务 +- **permission_handler**: 权限管理 + +### 框架依赖 +- **basic_modular**: 模块化框架 +- **flutter_localizations**: 国际化支持 + +## 错误处理 + +### 销售模块异常 +```dart +// 销售功能异常 +abstract class SalesFailure { + const SalesFailure(); + + factory SalesFailure.catalogLoadFailed(String message) = CatalogLoadFailure; + factory SalesFailure.dealerNotFound() = DealerNotFoundFailure; + factory SalesFailure.timeSlotNotAvailable() = TimeSlotNotAvailableFailure; + factory SalesFailure.appointmentCreationFailed(String message) = AppointmentCreationFailure; + factory SalesFailure.leadCreationFailed(String message) = LeadCreationFailure; +} +``` + +## 总结 + +`oneapp_car_sales` 模块为 OneApp 提供了完整的汽车销售解决方案，通过车型展示、试驾预约、经销商服务和销售线索管理，构建了完整的数字化购车体验。模块与地图服务、触点管理、售后服务等深度集成，为用户和经销商提供了高效的销售服务平台。 diff --git a/community/README.md b/community/README.md new file mode 100644 index 0000000..c94fd41 --- /dev/null +++ b/community/README.md @@ -0,0 +1,218 @@ +# OneApp Community - 社区模块文档 + +## 模块概述 + +`oneapp_community` 是 OneApp 的社区模块，专注于社区发现和用户互动功能。该模块提供社区内容浏览、文章发现、动态时刻、用户主页等核心功能。 + +### 基本信息 +- **模块名称**: oneapp_community +- **版本**: 0.0.3 +- **类型**: Flutter Package + +### 核心导出组件 + +基于真实项目代码的主要导出： + +```dart +library oneapp_community; + +// 社区发现模块 +export 'src/app_modules/app_discover/pages/community_tab_page.dart'; +export 'src/app_modules/app_discover/pages/discover_tab_page.dart'; +export 'src/app_modules/app_discover/pages/community_tab_explore_page.dart'; +export 'src/app_modules/app_discover/pages/discover_article_page.dart'; +export 'src/app_modules/app_discover/pages/discovery_moment_page.dart'; + +// 用户模块 +export 'src/app_modules/app_mine/pages/user_home_page.dart'; + +// 路由和模块配置 +export 'src/community_route_dp.dart'; +export 'src/community_route_export.dart'; +export 'src/oneapp_community_module.dart'; + +// 数据模型 +export '/src/app_modules/app_mine/models/ads_space_model.dart'; + +// 组件 +export 'src/app_component/medium_component/sweep_video_bg.dart'; +``` + +## 目录结构 + +基于实际项目结构： + +``` +oneapp_community/ +├── lib/ +│ ├── oneapp_community.dart # 主导出文件 +│ ├── generated/ # 生成的国际化文件 +│ ├── l10n/ # 国际化资源文件 +│ └── src/ # 源代码目录 +│ ├── app_modules/ # 应用模块 +│ │ ├── app_discover/ # 发现模块 +│ │ │ └── pages/ # 发现页面 +│ │ └── app_mine/ # 我的模块 +│ │ ├── pages/ # 用户页面 +│ │ └── models/ # 数据模型 +│ ├── app_component/ # 应用组件 +│ │ └── medium_component/ # 媒体组件 +│ ├── community_route_dp.dart # 社区路由依赖 +│ ├── community_route_export.dart # 社区路由导出 +│ └── oneapp_community_module.dart # 社区模块定义 +├── assets/ # 静态资源 +└── pubspec.yaml # 依赖配置 +``` + +## 核心功能模块 + +### 1. 社区发现功能 + +实际项目包含的发现页面： + +- **community_tab_page.dart**: 社区标签页面 +- **discover_tab_page.dart**: 发现标签页面 +- **community_tab_explore_page.dart**: 社区探索页面 +- **discover_article_page.dart**: 发现文章页面 +- **discovery_moment_page.dart**: 发现动态页面 + +### 2. 用户相关功能 + +- **user_home_page.dart**: 用户主页页面 +- **ads_space_model.dart**: 广告位数据模型 + +### 3. 媒体组件功能 + +- **sweep_video_bg.dart**: 视频背景扫描组件 + +## 技术架构 + +### 模块化设计 + +基于OneApp的模块化架构： + +```dart +// 社区模块类（推测结构） +class OneAppCommunityModule extends Module { + @override + List get binds => [ + // 服务绑定 + ]; + + @override + List get routes => [ + // 路由配置 + ]; +} +``` + +### 路由管理 + +```dart +// 社区路由导出 +class CommunityRouteExport { + // 路由键定义 + static const String keyCommunityTab = 'Key_Community_Tab'; + static const String keyDiscoverTab = 'Key_Discover_Tab'; + static const String keyUserHome = 'Key_User_Home'; + + // 其他路由相关配置 +} +``` + +## 使用指南 + +### 1. 模块集成 + +```dart +// 在主应用中导入社区模块 +import 'package:oneapp_community/oneapp_community.dart'; + +// 注册模块 +class AppModule extends Module { + @override + List get imports => [ + OneAppCommunityModule(), + // 其他模块... + ]; +} +``` + +### 2. 页面导航 + +```dart +// 导航到社区页面 +Navigator.pushNamed(context, '/community_tab'); + +// 导航到发现页面 +Navigator.pushNamed(context, '/discover_tab'); + +// 导航到用户主页 +Navigator.pushNamed(context, '/user_home'); +``` + +### 3. 组件使用 + +```dart +// 使用视频背景组件 +SweepVideoBg( + videoUrl: 'your_video_url', + child: YourContentWidget(), +) +``` + +## 依赖配置 + +### pubspec.yaml 关键依赖 + +```yaml +dependencies: + flutter: + sdk: flutter + + # 基础模块依赖 + basic_modular: + path: ../oneapp_basic_utils/basic_modular + + # UI基础组件 + ui_basic: + path: ../oneapp_basic_uis/ui_basic + + # 国际化支持 + flutter_localizations: + sdk: flutter + intl: ^0.17.0 + +dev_dependencies: + # 国际化代码生成 + intl_utils: ^2.8.0 +``` + +## 最佳实践 + +### 1. 性能优化 +- 使用懒加载优化页面加载速度 +- 合理缓存图片和视频资源 +- 实现虚拟列表减少内存占用 + +### 2. 用户体验 +- 提供加载状态指示 +- 实现下拉刷新和上拉加载 +- 支持离线浏览缓存内容 + +### 3. 代码组织 +- 按功能模块组织代码结构 +- 使用BLoC模式管理状态 +- 实现完整的错误处理机制 + +## 问题排查 + +### 常见问题 +1. **页面加载慢**: 检查网络请求和图片加载优化 +2. **内存占用高**: 使用内存分析工具检查是否有内存泄漏 +3. **导航异常**: 检查路由配置和模块注册 + +### 调试技巧 +- 使用Flutter Inspector检查组件树 +- 启用性能监控查看帧率 +- 使用网络抓包工具检查API调用 diff --git a/debug_tools.md b/debug_tools.md new file mode 100644 index 0000000..2483b6d --- /dev/null +++ b/debug_tools.md @@ -0,0 +1,202 @@ +# Debug Tools - 调试工具集 + +## 工具集概述 + +Debug Tools 是 OneApp 开发阶段使用的调试工具集合，提供了全面的开发调试、性能监控、问题诊断等功能。这些工具仅在开发环境中使用，帮助开发团队快速定位问题、优化性能、监控应用状态。 + +## 工具列表 + +### 1. kit_debugtools (v0.2.4+1) +**核心调试工具包** +- 调试面板管理 +- 开发者选项控制 +- 调试信息展示 +- 工具集成管理 + +### 2. kit_tool_dio (v0.2.4) +**网络请求调试工具** +- HTTP请求拦截和查看 +- 请求/响应日志记录 +- 网络性能分析 +- API调试界面 + +### 3. kit_tool_console (v0.2.2) +**控制台日志工具** +- 实时日志查看 +- 日志级别过滤 +- 日志搜索功能 +- 日志导出功能 + +### 4. kit_tool_channel_monitor (v0.2.2) +**原生通道监控工具** +- Flutter与原生代码通信监控 +- Method Channel调用跟踪 +- 参数和返回值查看 +- 通信性能分析 + +### 5. kit_tool_device_info (v0.2.2) +**设备信息查看工具** +- 设备硬件信息展示 +- 系统版本信息 +- 应用安装信息 +- 运行环境状态 + +### 6. kit_tool_memory (v0.2.3) +**内存监控工具** +- 实时内存使用监控 +- 内存泄漏检测 +- 垃圾回收分析 +- 内存使用趋势图 + +### 7. kit_tool_ui (v0.2.3) +**UI调试工具** +- Widget树结构查看 +- 布局边界显示 +- 性能叠加层 +- UI渲染分析 + +### 8. kit_tool_show_code (v0.2.3) +**代码查看工具** +- 源码快速查看 +- 代码搜索功能 +- 文件结构浏览 +- 代码片段分享 + +## 主要功能 + +### 开发调试 +```dart +// 启用调试工具 +if (kDebugMode) { + DebugTools.init(); + DebugTools.showDebugPanel(); +} + +// 网络请求调试 +DioDebugTool.enableNetworkMonitoring(); + +// UI调试 +UIDebugTool.showWidgetInspector(); +``` + +### 性能监控 +```dart +// 内存监控 +MemoryTool.startMonitoring(); + +// 渲染性能 +UITool.enablePerformanceOverlay(); + +// 通道监控 +ChannelMonitor.startMonitoring(); +``` + +### 日志管理 +```dart +// 查看控制台日志 +ConsoleTool.showLogs(); + +// 过滤错误日志 +ConsoleTool.filterByLevel(LogLevel.error); + +// 导出日志文件 +ConsoleTool.exportLogs(); +``` + +## 使用场景 + +### 开发阶段 +- **问题诊断**：快速定位和分析问题 +- **性能优化**：监控性能指标，识别瓶颈 +- **功能测试**：验证新功能的正确性 +- **兼容性测试**：测试不同设备的兼容性 + +### 测试阶段 +- **回归测试**：确保新版本没有引入问题 +- **压力测试**：监控高负载下的应用表现 +- **用户体验测试**：分析用户交互流程 +- **稳定性测试**：长时间运行监控 + +### 生产前验证 +- **最终检查**：上线前的最后检查 +- **性能基准**：建立性能基准数据 +- **监控配置**：配置生产环境监控 +- **问题预防**：预防潜在问题 + +## 集成方式 + +### 开发依赖配置 +```yaml +dev_dependencies: + # 调试工具集 + kit_debugtools: ^0.2.4+1 + kit_tool_dio: ^0.2.4 + kit_tool_console: ^0.2.2 + kit_tool_channel_monitor: ^0.2.2 + kit_tool_device_info: ^0.2.2 + kit_tool_memory: ^0.2.3 + kit_tool_ui: ^0.2.3 + kit_tool_show_code: ^0.2.3 +``` + +### 初始化配置 +```dart +void main() { + // 仅在调试模式下启用调试工具 + if (kDebugMode) { + _initDebugTools(); + } + + runApp(MyApp()); +} + +void _initDebugTools() { + // 初始化调试工具包 + DebugTools.init( + enableNetworkMonitoring: true, + enableMemoryMonitoring: true, + enableUIDebugging: true, + enableConsoleLogging: true, + ); +} +``` + +## 注意事项 + +### 使用限制 +- **开发环境专用**：仅在开发和测试环境使用 +- **性能影响**：调试工具会影响应用性能 +- **内存占用**：会增加应用的内存使用 +- **安全考虑**：不应在生产环境中包含 + +### 最佳实践 +- **按需启用**：只启用需要的调试功能 +- **及时关闭**：测试完成后及时关闭调试工具 +- **版本控制**：确保生产版本不包含调试代码 +- **文档记录**：记录调试过程和发现的问题 + +## 工具特色 + +### 易用性 +- **一键启用**：简单的配置即可启用所有工具 +- **直观界面**：清晰的调试界面和信息展示 +- **快速操作**：快捷键和手势支持 +- **智能提示**：自动识别和提示潜在问题 + +### 功能完整性 +- **全面覆盖**：覆盖网络、内存、UI、日志等各个方面 +- **深度分析**：提供详细的分析数据和报告 +- **实时监控**：实时监控应用运行状态 +- **历史记录**：保存历史数据便于对比分析 + +### 扩展性 +- **插件化设计**：支持自定义调试插件 +- **API开放**：提供开放的调试API +- **配置灵活**：支持灵活的配置选项 +- **集成简单**：容易集成到现有项目中 + +## 总结 + +Debug Tools 调试工具集为 OneApp 的开发和测试提供了强大的支持。通过这套完整的调试工具，开发团队能够更高效地进行问题诊断、性能优化和质量保证，确保应用的稳定性和用户体验。 + +这些工具的设计原则是简单易用、功能全面、性能友好，帮助开发者在开发过程中快速定位问题，提升开发效率，保证代码质量。 diff --git a/images/Bloc-1.webp b/images/Bloc-1.webp new file mode 100644 index 0000000..61c19c0 Binary files /dev/null and b/images/Bloc-1.webp differ diff --git a/images/apk-image-1.png b/images/apk-image-1.png new file mode 100644 index 0000000..7b58898 Binary files /dev/null and b/images/apk-image-1.png differ diff --git a/images/apk-image-2.png b/images/apk-image-2.png new file mode 100644 index 0000000..6d1b7bb Binary files /dev/null and b/images/apk-image-2.png differ diff --git a/images/bloc_architecture_full.webp b/images/bloc_architecture_full.webp new file mode 100644 index 0000000..a9b6616 Binary files /dev/null and b/images/bloc_architecture_full.webp differ diff --git a/images/cubit_architecture_full.webp b/images/cubit_architecture_full.webp new file mode 100644 index 0000000..f4a87ed Binary files /dev/null and b/images/cubit_architecture_full.webp differ diff --git a/images/feature-architecture-example.png b/images/feature-architecture-example.png new file mode 100644 index 0000000..c0642ec Binary files /dev/null and b/images/feature-architecture-example.png differ diff --git a/images/flutter-archdiagram.png b/images/flutter-archdiagram.png new file mode 100644 index 0000000..2d34fe8 Binary files /dev/null and b/images/flutter-archdiagram.png differ diff --git a/index.html b/index.html new file mode 100644 index 0000000..bcdd0c5 --- /dev/null +++ b/index.html @@ -0,0 +1,178 @@ + + + + + OneApp 架构设计文档 + + + + + + + +
加载中...
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/main_app.md b/main_app.md new file mode 100644 index 0000000..cfbb6b1 --- /dev/null +++ b/main_app.md @@ -0,0 +1,296 @@ +# OneApp Main 主应用项目文档 + +## 项目概述 + +`oneapp_main` 是 OneApp 车主应用的主入口项目，采用 Flutter 框架开发，基于模块化架构设计。该项目作为应用的核心容器，负责整合各个功能模块、管理应用生命周期、处理路由导航以及提供统一的用户界面入口。 + +### 基本信息 +- **项目名称**: oneapp_main +- **版本**: 1.13.0+190915281 +- **Flutter 版本**: >=3.0.0 +- **Dart 版本**: >=3.0.0 <4.0.0 + +## 项目架构 + +### 应用启动流程 + +```mermaid +graph TD + A[main.dart] --> B[_realMain] + B --> C[WidgetsFlutterBinding.ensureInitialized] + C --> D[_initBasicPartWithoutPrivacy] + D --> E[wrapPrivacyCheck] + E --> F[_initBasicPartWithPrivacy] + F --> G[SystemChrome.setPreferredOrientations] + G --> H[runApp - ModularApp] +``` + +### 核心目录结构 + +``` +lib/ +├── main.dart # 应用启动入口 +├── app/ # 应用核心配置 +│ ├── app_module.dart # 主模块定义和依赖注入 +│ ├── app_widget.dart # 应用根组件 +│ ├── app_launch_handler.dart # 启动处理器 +│ └── app_privacy_widget.dart # 隐私政策组件 +├── initialize/ # 初始化配置模块 +├── app_home/ # 首页功能模块 +├── app_discover/ # 发现页功能模块 +├── app_test/ # 测试功能模块 +├── app_webview/ # WebView 功能模块 +├── business_utils/ # 业务工具类 +├── constant/ # 常量定义 +├── adapter/ # 适配器模式实现 +├── src/ # 源代码目录 +├── theme_resource/ # 主题资源 +├── generated/ # 代码生成文件 +└── l10n/ # 国际化文件 +``` + +## 详细模块分析 + +### 1. 应用入口 (`main.dart`) + +#### 功能职责 +- 应用启动引导 +- 基础服务初始化 +- 隐私合规检查 +- 系统 UI 配置 +- 模块化框架启动 + +#### 关键代码分析 + +```dart +void main() { + _realMain(); +} + +Future _realMain() async { + WidgetsFlutterBinding.ensureInitialized(); + await _initBasicPartWithoutPrivacy(); + await wrapPrivacyCheck(_initBasicPartWithPrivacy); + SystemChrome.setPreferredOrientations([DeviceOrientation.portraitUp]); + runApp(ModularApp(module: AppModule(), child: const AppWidget())); +} +``` + +#### 初始化阶段划分 + +1. **不依赖隐私合规的初始化** (`_initBasicPartWithoutPrivacy`) + - 模块状态管理初始化 + - 本地存储初始化 + - 开发配置工具 + +2. **依赖隐私合规的初始化** (`_initBasicPartWithPrivacy`) + - 网络服务初始化 + - 第三方 SDK 初始化 + - 推送服务初始化 + +### 2. 应用核心配置 (`app/`) + +#### `app_module.dart` - 主模块 +- **功能**: 应用级别的依赖注入和路由配置 +- **职责**: + - 注册全局服务 + - 配置路由表 + - 管理模块生命周期 + +#### `app_widget.dart` - 应用根组件 +- **功能**: 应用根级别的 Widget 配置 +- **职责**: + - 主题配置 + - 国际化配置 + - 全局导航配置 + +#### `app_launch_handler.dart` - 启动处理器 +- **功能**: 处理应用启动相关逻辑 +- **职责**: + - 深度链接处理 + - 启动参数解析 + - 启动页逻辑 + +#### `app_privacy_widget.dart` - 隐私政策组件 +- **功能**: 隐私政策和用户协议展示 +- **职责**: + - 隐私协议展示 + - 用户同意状态管理 + - 合规性检查 + +### 3. 初始化配置模块 (`initialize/`) + +该目录包含各个基础服务的初始化配置文件： + +#### 基础服务初始化 +- `basic_logger.dart` - 日志系统初始化 +- `basic_storage.dart` - 存储服务初始化 +- `basic_network.dart` - 网络服务初始化 +- `basic_theme.dart` - 主题系统初始化 +- `basic_modular.dart` - 模块化框架初始化 +- `basic_platform.dart` - 平台适配初始化 +- `basic_intl.dart` - 国际化初始化 +- `basic_error.dart` - 错误处理初始化 +- `basic_webview.dart` - WebView 初始化 +- `basic_share.dart` - 分享功能初始化 +- `basic_font.dart` - 字体配置初始化 +- `basic_resource.dart` - 资源管理初始化 + +#### 业务服务初始化 +- `basic_avatar.dart` - 虚拟形象服务初始化 +- `basic_vehicle.dart` - 车辆服务初始化 +- `basic_order.dart` - 订单服务初始化 +- `basic_push.dart` - 推送服务初始化 +- `basic_ttsshop.dart` - TTS 和购物服务初始化 + +#### 第三方服务初始化 +- `init_aegis_sdk.dart` - 腾讯 Aegis 监控 SDK +- `init_cos_file_sdk.dart` - 腾讯云对象存储 SDK +- `init_ingeek_carkey_sdk.dart` - 车钥匙 SDK +- `third_keys.dart` - 第三方服务密钥配置 + +#### 功能初始化 +- `init_modules.dart` - 模块注册和加载 +- `init_qr_processor.dart` - 二维码处理器初始化 +- `init_uni_link.dart` - 统一链接处理初始化 +- `kit_debugtools.dart` - 调试工具初始化 +- `configs.dart` - 应用配置初始化 +- `basic_environment.dart` - 环境配置初始化 + +### 4. 功能页面模块 + +#### `app_home/` - 首页模块 +- **功能**: 应用主界面和导航入口 +- **主要文件**: + - `route_dp.dart` - 首页路由配置 + - 首页 UI 组件 + - 首页业务逻辑 + +#### `app_discover/` - 发现页模块 +- **功能**: 发现页面和相关功能 +- **职责**: + - 内容推荐 + - 功能导航 + - 活动展示 + +#### `app_test/` - 测试功能模块 +- **功能**: 开发测试相关功能 +- **用途**: + - 功能测试入口 + - 调试工具 + - 开发辅助功能 + +#### `app_webview/` - WebView 模块 +- **功能**: WebView 相关功能封装 +- **职责**: + - WebView 容器 + - JavaScript 桥接 + - 网页交互处理 + +### 5. 工具和资源模块 + +#### `business_utils/` - 业务工具类 +- **功能**: 业务相关的工具类和帮助方法 +- **内容**: + - `privacy_check.dart` - 隐私检查工具 + - 其他业务工具类 + +#### `constant/` - 常量定义 +- **功能**: 应用级别的常量定义 +- **内容**: + - API 常量 + - 配置常量 + - 业务常量 + +#### `adapter/` - 适配器模式实现 +- **功能**: 不同服务间的适配器 +- **用途**: 解耦不同模块间的依赖 + +#### `theme_resource/` - 主题资源 +- **功能**: 主题相关的资源文件 +- **内容**: + - 颜色定义 + - 样式配置 + - 主题切换逻辑 + +#### `generated/` - 代码生成文件 +- **功能**: 自动生成的代码文件 +- **内容**: + - 国际化文件 + - JSON 序列化文件 + - 路由生成文件 + +## 依赖管理 + +### 核心依赖分类 + +#### 1. Flutter 框架依赖 +- `flutter` - Flutter SDK +- `flutter_localizations` - 国际化支持 + +#### 2. 基础框架依赖 (`basic_*`) +- `basic_network` - 网络请求框架 +- `basic_storage` - 本地存储框架 +- `basic_modular` - 模块化框架 +- `basic_theme` - 主题管理框架 +- `basic_intl` - 国际化框架 + +#### 3. 应用功能依赖 (`app_*`) +- `app_order` - 订单管理模块 +- `app_media` - 媒体处理模块 +- `app_navigation` - 导航功能模块 +- `app_consent` - 用户同意模块 + +#### 4. UI 组件依赖 (`ui_*`) +- `ui_mapview` - 地图视图组件 +- `ui_payment` - 支付界面组件 +- `ui_share` - 分享组件 + +#### 5. 服务 SDK 依赖 (`clr_*`) +- `clr_charging` - 充电服务 SDK +- `clr_payment` - 支付服务 SDK +- `clr_media` - 媒体服务 SDK + +#### 6. 车辆相关依赖 (`car_*`) +- `car_vehicle` - 车辆控制 +- `car_connector` - 车联网连接 +- `car_vur` - 车辆更新记录 + +#### 7. 第三方服务依赖 +- `amap_flutter_location` - 高德地图定位 +- `provider` - 状态管理 +- `rxdart` - 响应式编程 +- `connectivity_plus` - 网络状态检测 + +## 构建和部署 + +### 版本管理 +- **版本格式**: `major.minor.patch+buildNumber` +- **构建号规则**: `yywwddhh` (年-周-日-时) + +### 构建配置 +- **启动屏配置**: `flutter_native_splash` +- **应用图标**: 支持 Android 12 适配 +- **多环境支持**: 开发、测试、生产环境 + +### 平台特性 +- **Android**: 支持 APK/AAB 格式 +- **iOS**: 支持 TestFlight/App Store 发布 +- **权限管理**: 位置、相机、存储等权限 + +## 开发调试 + +### 调试工具 (Debug 模式) +- `kit_debugtools` - 调试工具主入口 +- `kit_tool_dio` - 网络请求监控 +- `kit_tool_memory` - 内存使用监控 +- `kit_tool_ui` - UI 调试工具 + +### 代码生成工具 +- `build_runner` - 代码生成引擎 +- `json_serializable` - JSON 序列化 +- `freezed` - 不可变类生成 + +## 总结 + +`oneapp_main` 作为 OneApp 的主入口项目，采用了清晰的分层架构和模块化设计。通过统一的初始化流程、完善的依赖管理和灵活的配置系统，为整个应用提供了稳定的基础框架。项目结构清晰，职责分明，便于团队协作开发和长期维护。 diff --git a/membership/README.md b/membership/README.md new file mode 100644 index 0000000..d711ed8 --- /dev/null +++ b/membership/README.md @@ -0,0 +1,779 @@ +# OneApp Membership - 会员系统模块文档 + +## 模块概述 + +`oneapp_membership` 是 OneApp 的会员系统核心模块，专注于积分系统和签到功能。该模块提供用户积分管理、签到中心、积分任务等功能，与社区、账户等模块深度集成。 + +### 基本信息 +- **模块名称**: oneapp_membership +- **版本**: 0.0.1 +- **类型**: Flutter Package +- **主要功能**: 积分系统、签到功能、积分任务管理 + +### 核心导出组件 + +```dart +library oneapp_membership; + +// 积分页面 +export 'src/app_modules/app_points/pages/user_points_page.dart'; +// 签到中心页面 +export 'src/app_modules/app_signin/pages/signIn_center_page.dart'; +// 会员事件 +export 'src/app_event/membership_event.dart'; +``` + +## 目录结构 + +``` +oneapp_membership/ +├── lib/ +│ ├── oneapp_membership.dart # 主导出文件 +│ ├── generated/ # 生成的国际化文件 +│ ├── l10n/ # 国际化资源文件 +│ └── src/ # 源代码目录 +│ ├── app_modules/ # 应用模块 +│ │ ├── app_points/ # 积分模块 +│ │ │ ├── pages/ # 积分页面 +│ │ │ ├── blocs/ # 积分状态管理 +│ │ │ ├── widges/ # 积分组件 +│ │ │ ├── scene/ # 积分场景 +│ │ │ └── beans/ # 积分数据模型 +│ │ └── app_signin/ # 签到模块 +│ │ └── pages/ # 签到页面 +│ ├── app_net_service/ # 网络服务 +│ └── app_event/ # 应用事件 +├── assets/ # 静态资源 +├── test/ # 测试文件 +└── pubspec.yaml # 依赖配置 +``` + +## 核心功能模块 + +### 1. 用户积分页面 (UserPointsPage) + +基于真实项目代码的用户积分管理页面： + +```dart +/// 用户积分页面 +class UserPointsPage extends BaseStatefulWidget with RouteObjProvider { + UserPointsPage({Key? key, required this.userId}); + + final String userId; + + @override + BaseStatefulWidgetState getState() => _UserPointsPageState(); +} + +class _UserPointsPageState extends BaseStatefulWidgetState + with WidgetsBindingObserver { + + /// 是否需要添加推送积分 + bool needAddPushPoints = false; + + /// 是否使用通用导航栏 + bool useCommonNavigation = false; + + @override + List get rightActions => [ + PointsRuleWidge( + lable: MemberShipIntlDelegate.current.pointsRule, + onTap: () async { + // 获取积分规则 + final rsp3 = await UserPointsTask.getRule(ruleKey: "integrationRule"); + if ((rsp3.data ?? '').isNotEmpty) { + String jumpUrl = 'oneapp://component?routeKey=Key_Community_Postdetail&postId=${rsp3.data}&userName='; + + try { + Uri uri = Uri.tryParse(jumpUrl)!; + final routeKey = uri.queryParameters['routeKey']; + final meta = RouteCenterAPI.routeMetaBy(routeKey!); + NavigatorProxy().launchMeta( + meta, + meta.routePath, + arguments: uri.queryParameters, + ); + } catch (e) { + // 处理跳转异常 + } + } else { + ToastHelper.showToast(msg: '获取文章失败'); + } + } + ) + ]; + + @override + String get titleText => MemberShipIntlDelegate.current.myPoints; + + @override + double get elevation => 0; + + @override + void initState() { + super.initState(); + WidgetsBinding.instance.addObserver(this); + addNotifyPoints(); + } + + /// 添加通知积分 + Future addNotifyPoints() async { + bool haveNotifyPermission = await Permission.notification.isGranted; + if (haveNotifyPermission) { + PointsAddCenter().addPoints(PointsOpenPush()); + } + } +} +``` + +### 2. 积分组件架构 + +实际项目包含的积分相关组件： + +- **point_score_head_section.dart**: 积分头部区域组件 +- **points_rule_widget.dart**: 积分规则组件 +- **points_task_cell.dart**: 积分任务单元格组件 +- **PointsAddCenter**: 积分添加中心 +- **points_open_push.dart**: 积分推送开启 + +### 3. 会员权益管理 + +#### 权益服务系统 +```dart +// 会员权益服务 +class MemberBenefitsService { + final BenefitsRepository _repository; + final MembershipService _membershipService; + + MemberBenefitsService(this._repository, this._membershipService); + + // 获取用户可用权益 + Future>> getUserBenefits(String userId) async { + try { + final membership = await _membershipService.getUserMembership(userId); + return membership.fold( + (failure) => Left(BenefitsFailure.membershipNotFound()), + (membershipInfo) async { + final benefits = await _repository.getBenefitsForTier( + membershipInfo.tier, + ); + return Right(benefits); + }, + ); + } catch (e) { + return Left(BenefitsFailure.loadFailed(e.toString())); + } + } + + // 使用权益 + Future> useBenefit({ + required String userId, + required String benefitId, + Map? context, + }) async { + try { + // 检查权益可用性 + final benefit = await _repository.getBenefitById(benefitId); + if (benefit == null) { + return Left(BenefitsFailure.benefitNotFound()); + } + + // 检查使用条件 + final canUseResult = await _canUseBenefit(userId, benefit); + if (canUseResult.isLeft()) { + return Left(canUseResult.fold((l) => l, (r) => throw Exception())); + } + + // 记录使用 + final usage = BenefitUsage( + id: generateId(), + userId: userId, + benefitId: benefitId, + usedAt: DateTime.now(), + context: context, + ); + + await _repository.recordBenefitUsage(usage); + + // 执行权益逻辑 + await _executeBenefitLogic(benefit, usage); + + return Right(usage); + } catch (e) { + return Left(BenefitsFailure.usageFailed(e.toString())); + } + } + + // 获取权益使用历史 + Future>> getBenefitUsageHistory({ + required String userId, + String? benefitId, + DateRange? dateRange, + int page = 1, + int pageSize = 20, + }) async { + try { + final usageHistory = await _repository.getBenefitUsageHistory( + userId: userId, + benefitId: benefitId, + dateRange: dateRange, + page: page, + pageSize: pageSize, + ); + return Right(usageHistory); + } catch (e) { + return Left(BenefitsFailure.historyLoadFailed(e.toString())); + } + } +} + +// 会员权益模型 +class MemberBenefit { + final String id; + final String name; + final String description; + final BenefitType type; + final BenefitCategory category; + final Map configuration; + final UsageLimit usageLimit; + final List eligibleTiers; + final DateTime? validFrom; + final DateTime? validUntil; + final bool isActive; + + const MemberBenefit({ + required this.id, + required this.name, + required this.description, + required this.type, + required this.category, + required this.configuration, + required this.usageLimit, + required this.eligibleTiers, + this.validFrom, + this.validUntil, + this.isActive = true, + }); + + // 免费充电权益 + factory MemberBenefit.freeCharging({int times = 1}) { + return MemberBenefit( + id: 'free_charging', + name: '免费充电', + description: '每月享受 $times 次免费充电服务', + type: BenefitType.service, + category: BenefitCategory.charging, + configuration: {'free_times': times}, + usageLimit: UsageLimit.monthly(times), + eligibleTiers: [ + MembershipTier.gold, + MembershipTier.platinum, + MembershipTier.diamond, + MembershipTier.vip, + ], + ); + } + + // 优先客服权益 + factory MemberBenefit.prioritySupport() { + return MemberBenefit( + id: 'priority_support', + name: '优先客服', + description: '享受7x24小时优先客服支持', + type: BenefitType.service, + category: BenefitCategory.support, + configuration: {'priority_level': 'high'}, + usageLimit: UsageLimit.unlimited(), + eligibleTiers: [ + MembershipTier.gold, + MembershipTier.platinum, + MembershipTier.diamond, + MembershipTier.vip, + ], + ); + } +} +``` + +### 4. 会员商城 + +#### 积分商城服务 +```dart +// 积分商城服务 +class MembershipStoreService { + final StoreRepository _repository; + final PointsService _pointsService; + final OrderService _orderService; + + MembershipStoreService( + this._repository, + this._pointsService, + this._orderService, + ); + + // 获取商品列表 + Future>> getStoreItems({ + StoreCategory? category, + MembershipTier? minTier, + int page = 1, + int pageSize = 20, + }) async { + try { + final items = await _repository.getStoreItems( + category: category, + minTier: minTier, + page: page, + pageSize: pageSize, + ); + return Right(items); + } catch (e) { + return Left(StoreFailure.loadFailed(e.toString())); + } + } + + // 兑换商品 + Future> redeemItem({ + required String userId, + required String itemId, + int quantity = 1, + String? deliveryAddress, + }) async { + try { + // 获取商品信息 + final item = await _repository.getStoreItemById(itemId); + if (item == null) { + return Left(StoreFailure.itemNotFound()); + } + + // 检查积分余额 + final totalCost = item.pointsPrice * quantity; + final pointsResult = await _pointsService.getUserPoints(userId); + + return pointsResult.fold( + (failure) => Left(StoreFailure.pointsCheckFailed()), + (balance) async { + if (balance.availablePoints < totalCost) { + return Left(StoreFailure.insufficientPoints()); + } + + // 检查库存 + if (item.stock != null && item.stock! < quantity) { + return Left(StoreFailure.insufficientStock()); + } + + // 创建订单 + final order = StoreOrder( + id: generateId(), + userId: userId, + itemId: itemId, + itemName: item.name, + quantity: quantity, + pointsPrice: item.pointsPrice, + totalPoints: totalCost, + deliveryAddress: deliveryAddress, + status: StoreOrderStatus.pending, + createdAt: DateTime.now(), + ); + + // 扣除积分 + await _pointsService.spendPoints( + userId: userId, + points: totalCost, + reason: PointsSpendReason.storeRedemption, + metadata: {'order_id': order.id, 'item_id': itemId}, + ); + + // 保存订单 + await _repository.createStoreOrder(order); + + // 更新库存 + if (item.stock != null) { + await _repository.updateItemStock(itemId, -quantity); + } + + return Right(order); + }, + ); + } catch (e) { + return Left(StoreFailure.redeemFailed(e.toString())); + } + } + + // 获取兑换记录 + Future>> getRedemptionHistory({ + required String userId, + StoreOrderStatus? status, + int page = 1, + int pageSize = 20, + }) async { + try { + final orders = await _repository.getStoreOrders( + userId: userId, + status: status, + page: page, + pageSize: pageSize, + ); + return Right(orders); + } catch (e) { + return Left(StoreFailure.historyLoadFailed(e.toString())); + } + } +} + +// 商城商品模型 +class StoreItem { + final String id; + final String name; + final String description; + final String imageUrl; + final int pointsPrice; + final StoreCategory category; + final MembershipTier? requiredTier; + final int? stock; + final bool isVirtual; + final Map? metadata; + final DateTime? validUntil; + final bool isActive; + + const StoreItem({ + required this.id, + required this.name, + required this.description, + required this.imageUrl, + required this.pointsPrice, + required this.category, + this.requiredTier, + this.stock, + this.isVirtual = false, + this.metadata, + this.validUntil, + this.isActive = true, + }); + + bool get isInStock => stock == null || stock! > 0; + bool get isExpired => validUntil != null && validUntil!.isBefore(DateTime.now()); + bool get isAvailable => isActive && isInStock && !isExpired; +} +``` + +## 页面组件设计 + +### 会员主页 +```dart +// 会员主页 +class MembershipHomePage extends StatefulWidget { + @override + _MembershipHomePageState createState() => _MembershipHomePageState(); +} + +class _MembershipHomePageState extends State { + late MembershipBloc _membershipBloc; + late PointsBloc _pointsBloc; + + @override + void initState() { + super.initState(); + _membershipBloc = context.read(); + _pointsBloc = context.read(); + + _membershipBloc.add(LoadMembershipInfo()); + _pointsBloc.add(LoadPointsBalance()); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + body: CustomScrollView( + slivers: [ + _buildAppBar(), + SliverToBoxAdapter(child: _buildMembershipCard()), + SliverToBoxAdapter(child: _buildPointsSection()), + SliverToBoxAdapter(child: _buildBenefitsSection()), + SliverToBoxAdapter(child: _buildQuickActions()), + SliverToBoxAdapter(child: _buildPromotions()), + ], + ), + ); + } + + Widget _buildMembershipCard() { + return BlocBuilder( + builder: (context, state) { + if (state is MembershipLoaded) { + return MembershipCard( + membershipInfo: state.membershipInfo, + onUpgrade: () => _navigateToUpgrade(), + ); + } + return MembershipCardSkeleton(); + }, + ); + } + + Widget _buildPointsSection() { + return BlocBuilder( + builder: (context, state) { + if (state is PointsLoaded) { + return PointsOverviewCard( + balance: state.balance, + onViewHistory: () => _navigateToPointsHistory(), + onEarnMore: () => _navigateToEarnPoints(), + ); + } + return PointsCardSkeleton(); + }, + ); + } +} +``` + +### 会员卡片组件 +```dart +// 会员卡片组件 +class MembershipCard extends StatelessWidget { + final MembershipInfo membershipInfo; + final VoidCallback? onUpgrade; + + const MembershipCard({ + Key? key, + required this.membershipInfo, + this.onUpgrade, + }) : super(key: key); + + @override + Widget build(BuildContext context) { + return Container( + margin: EdgeInsets.all(16), + padding: EdgeInsets.all(20), + decoration: BoxDecoration( + gradient: _getGradientForTier(membershipInfo.tier), + borderRadius: BorderRadius.circular(16), + boxShadow: [ + BoxShadow( + color: Colors.black.withOpacity(0.1), + blurRadius: 10, + offset: Offset(0, 4), + ), + ], + ), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + _buildHeader(), + SizedBox(height: 16), + _buildProgress(), + SizedBox(height: 16), + _buildActions(), + ], + ), + ); + } + + Widget _buildHeader() { + return Row( + children: [ + CircleAvatar( + radius: 24, + backgroundColor: Colors.white.withOpacity(0.2), + child: Icon( + _getIconForTier(membershipInfo.tier), + color: Colors.white, + size: 28, + ), + ), + SizedBox(width: 12), + Expanded( + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text( + membershipInfo.tierName, + style: TextStyle( + fontSize: 20, + fontWeight: FontWeight.bold, + color: Colors.white, + ), + ), + Text( + '会员编号: ${membershipInfo.memberNumber}', + style: TextStyle( + fontSize: 14, + color: Colors.white.withOpacity(0.8), + ), + ), + ], + ), + ), + if (membershipInfo.tier != MembershipTier.vip) + TextButton( + onPressed: onUpgrade, + child: Text( + '升级', + style: TextStyle(color: Colors.white), + ), + style: TextButton.styleFrom( + backgroundColor: Colors.white.withOpacity(0.2), + ), + ), + ], + ); + } + + Widget _buildProgress() { + if (membershipInfo.tier == MembershipTier.vip) { + return Container(); // VIP 不显示进度 + } + + final nextTier = _getNextTier(membershipInfo.tier); + final currentPoints = membershipInfo.totalPoints; + final requiredPoints = _getRequiredPointsForTier(nextTier); + final progress = currentPoints / requiredPoints; + + return Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text( + '距离${_getTierName(nextTier)}还需 ${requiredPoints - currentPoints} 积分', + style: TextStyle( + color: Colors.white.withOpacity(0.9), + fontSize: 14, + ), + ), + SizedBox(height: 8), + LinearProgressIndicator( + value: progress.clamp(0.0, 1.0), + backgroundColor: Colors.white.withOpacity(0.3), + valueColor: AlwaysStoppedAnimation(Colors.white), + ), + ], + ); + } +} +``` + +## 状态管理 + +### 会员状态管理 +```dart +// 会员状态 BLoC +class MembershipBloc extends Bloc { + final MembershipService _membershipService; + final PointsService _pointsService; + + MembershipBloc(this._membershipService, this._pointsService) + : super(MembershipInitial()) { + on(_onLoadMembershipInfo); + on(_onUpgradeMembership); + on(_onRefreshMembershipInfo); + } + + Future _onLoadMembershipInfo( + LoadMembershipInfo event, + Emitter emit, + ) async { + emit(MembershipLoading()); + + final result = await _membershipService.getUserMembership(event.userId); + result.fold( + (failure) => emit(MembershipError(failure.message)), + (membershipInfo) => emit(MembershipLoaded(membershipInfo)), + ); + } + + Future _onUpgradeMembership( + UpgradeMembership event, + Emitter emit, + ) async { + emit(MembershipUpgrading()); + + final result = await _membershipService.upgradeMembership( + userId: event.userId, + targetTier: event.targetTier, + paymentMethod: event.paymentMethod, + ); + + result.fold( + (failure) => emit(MembershipError(failure.message)), + (_) { + add(LoadMembershipInfo(event.userId)); + emit(MembershipUpgradeSuccess()); + }, + ); + } +} +``` + +## 与其他模块集成 + +### 社区集成 +```dart +// 会员社区权益服务 +class MembershipCommunityIntegration { + final MembershipService _membershipService; + final CommunityService _communityService; + + MembershipCommunityIntegration( + this._membershipService, + this._communityService, + ); + + // 检查发布权限 + Future canPublishPremiumContent(String userId) async { + final membership = await _membershipService.getUserMembership(userId); + return membership.fold( + (_) => false, + (info) => info.tier.index >= MembershipTier.gold.index, + ); + } + + // 获取会员专属话题 + Future> getMemberExclusiveTopics(String userId) async { + final membership = await _membershipService.getUserMembership(userId); + return membership.fold( + (_) => [], + (info) => _communityService.getTopicsForMemberTier(info.tier), + ); + } +} +``` + +## 依赖管理 + +### 集成模块依赖 +- **basic_utils**: 基础工具类 +- **basic_uis**: 基础 UI 组件 +- **oneapp_community**: 社区功能集成 +- **oneapp_after_sales**: 售后服务集成 +- **app_account**: 账户系统集成 + +### 第三方依赖 +- **fluwx**: 微信支付集成（会员升级付费） + +## 错误处理 + +### 会员系统异常 +```dart +// 会员系统异常 +abstract class MembershipFailure { + const MembershipFailure(); + + factory MembershipFailure.loadFailed(String message) = LoadFailure; + factory MembershipFailure.upgradeFailed(String message) = UpgradeFailure; + factory MembershipFailure.paymentFailed() = PaymentFailure; + factory MembershipFailure.upgradeNotAllowed() = UpgradeNotAllowedFailure; + factory MembershipFailure.insufficientPoints() = InsufficientPointsFailure; +} + +// 积分系统异常 +abstract class PointsFailure { + const PointsFailure(); + + factory PointsFailure.insufficientPoints() = InsufficientPointsFailure; + factory PointsFailure.earnFailed(String message) = EarnFailure; + factory PointsFailure.spendFailed(String message) = SpendFailure; +} +``` + +## 总结 + +`oneapp_membership` 模块为 OneApp 构建了完整的会员生态体系，通过等级管理、积分系统、权益服务和商城功能，提升了用户粘性和付费转化。模块与社区、账户、售后服务等模块深度集成，为用户提供了全方位的会员体验和价值认知。 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..a802e51 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,192 @@ +site_name: OneApp 架构设计文档 +site_description: OneApp Flutter应用完整技术架构设计和模块说明 +site_author: OneApp Team + +# 构建配置 +docs_dir: ./docs +site_dir: ./site +# 为静态文件部署优化URL结构 +use_directory_urls: false + +# Theme +theme: + name: material + language: zh + palette: + # 浅色模式 + - media: "(prefers-color-scheme: light)" + scheme: default + primary: blue + accent: blue + toggle: + icon: material/brightness-7 + name: 切换至深色模式 + # 深色模式 + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: blue + accent: blue + toggle: + icon: material/brightness-4 + name: 切换至浅色模式 + features: + - navigation.tabs + - navigation.tabs.sticky + - navigation.sections + - navigation.expand + - navigation.path + - navigation.top + - navigation.tracking + - search.suggest + - search.highlight + - search.share + - header.autohide + - content.code.copy + - content.code.annotate + icon: + repo: fontawesome/brands/github + font: + text: Roboto + code: Roboto Mono + +# Plugins +plugins: + - search: + lang: + - zh + - en + separator: '[\s\-\.]+' + +# Extensions +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.critic + - pymdownx.caret + - pymdownx.keys + - pymdownx.mark + - pymdownx.tilde + - pymdownx.arithmatex: + generic: true + - attr_list + - md_in_html + - tables + - footnotes + - def_list + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + # GitHub Flavored Markdown 扩展 + - nl2br + - sane_lists + - smarty + - toc: + permalink: true + baselevel: 1 + separator: "_" + +# Extra +extra: + version: + provider: mike + +# Extra JavaScript - 使用最新版本的Mermaid +extra_javascript: + - https://cdn.jsdelivr.net/npm/mermaid@10.9.1/dist/mermaid.min.js + - assets/js/mermaid.js + - assets/js/search-fix.js + +# Extra CSS +extra_css: + - assets/css/extra.css + +# Navigation - 根据实际文档内容优化 +nav: + - 首页: README.md + - 架构设计文档: OneApp架构设计文档.md + - AI聊天助手: CODE_ANALYSIS.md + - 主应用架构: main_app.md + - 调试工具: debug_tools.md + - 账户模块: + - 概览: account/README.md + - CLR账户服务: account/clr_account.md + - 极光验证: account/jverify.md + # - 售后服务: + # - 概览: after_sales/README.md + # - CLR售后服务: after_sales/clr_after_sales.md + # - 售后应用: after_sales/oneapp_after_sales.md + - 车辆服务: + - 概览: app_car/README.md + - 应用层组件: + - AI聊天助手: app_car/ai_chat_assistant.md + - 应用头像: app_car/app_avatar.md + - 车辆管理: app_car/app_car.md + - 车辆监控: app_car/app_carwatcher.md + - 充电服务: app_car/app_charging.md + - 应用组合: app_car/app_composer.md + - 维修保养: app_car/app_maintenance.md + - 订单管理: app_car/app_order.md + - RPA服务: app_car/app_rpa.md + - TouchGo: app_car/app_touchgo.md + - VUR服务: app_car/app_vur.md + - Wallbox: app_car/app_wallbox.md + - 服务层SDK: + - CLR虚拟形象: app_car/clr_avatarcore.md + - CLR订单服务: app_car/clr_order.md + - CLR TouchGo: app_car/clr_touchgo.md + - CLR Wallbox: app_car/clr_wallbox.md + - 地图服务: + - 高德定位: app_car/amap_flutter_location.md + - 高德搜索: app_car/amap_flutter_search.md + - 插件和工具: + - 车辆服务: app_car/car_services.md + - RPA插件: app_car/kit_rpa_plugin.md + - 缓存插件: app_car/one_app_cache_plugin.md + - 头像UI: app_car/ui_avatarx.md + - 基础UI组件: + - 概览: basic_uis/README.md + - 基础UI: basic_uis/basic_uis.md + - 通用组件: basic_uis/general_ui_component.md + - UI基础: basic_uis/ui_basic.md + - UI业务: basic_uis/ui_business.md + - 基础工具库: + - 概览: basic_utils/README.md + - 核心基础: + - MVVM基础: basic_utils/base_mvvm.md + - 基础配置: basic_utils/basic_config.md + - 基础工具: basic_utils/basic_utils.md + - 平台基础: basic_utils/basic_platform.md + - 网络和通信: + - 网络基础: basic_utils/basic_network.md + - 推送基础: basic_utils/basic_push.md + - MT推送: basic_utils/flutter_plugin_mtpush_private.md + - 工具服务: + - 日志系统: basic_utils/basic_logger.md + - 下载器: basic_utils/flutter_downloader.md + # - 汽车销售: + # - 概览: car_sales/README.md + # - 社区功能: + # - 概览: community/README.md + # - 会员服务: + # - 概览: membership/README.md + # - 服务组件: + # - 概览: service_component/README.md + # - 设置功能: + # - 概览: setting/README.md + # - 触点模块: + # - 概览: touch_point/README.md \ No newline at end of file diff --git a/service_component/GlobalSearch.md b/service_component/GlobalSearch.md new file mode 100644 index 0000000..f9a2eaa --- /dev/null +++ b/service_component/GlobalSearch.md @@ -0,0 +1,609 @@ +# GlobalSearch - 全局搜索模块 + +## 模块概述 + +`GlobalSearch` 是 OneApp 的全局搜索模块，提供了跨模块的统一搜索功能。该模块支持多种内容类型的搜索，包括智能搜索建议、搜索历史管理、搜索结果优化等功能，为用户提供高效、精准的搜索体验。 + +## 核心功能 + +### 1. 跨模块内容搜索 +- **统一搜索入口**：提供全局统一的搜索接口 +- **多模块索引**：聚合各模块的可搜索内容 +- **内容分类**：按类型分类搜索结果 +- **权限控制**：基于用户权限过滤搜索结果 + +### 2. 智能搜索建议 +- **实时建议**：输入时实时提供搜索建议 +- **热门搜索**：展示热门搜索关键词 +- **个性化推荐**：基于用户行为的个性化建议 +- **拼写纠错**：智能纠正搜索词拼写错误 + +### 3. 搜索历史管理 +- **历史记录**：保存用户搜索历史 +- **快速访问**：快速访问历史搜索结果 +- **清理管理**：支持清理搜索历史 +- **隐私保护**：敏感搜索历史加密存储 + +### 4. 搜索结果优化 +- **相关性排序**：按相关性智能排序 +- **结果聚合**：相似结果智能聚合 +- **高亮显示**：关键词高亮显示 +- **分页加载**：大量结果分页展示 + +## 技术架构 + +### 架构设计 +``` +┌─────────────────────────────────────┐ +│ 搜索界面层 │ +│ (Search UI Components) │ +├─────────────────────────────────────┤ +│ GlobalSearch 模块 │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 搜索引擎 │ 索引管理 │ 结果处理 │ │ +│ ├──────────┼──────────┼──────────┤ │ +│ │ 建议系统 │ 历史管理 │ 缓存层 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 模块搜索接口 │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 车辆模块 │ 订单模块 │ 设置模块 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 数据存储层 │ +│ (Local DB + Remote Index) │ +└─────────────────────────────────────┘ +``` + +### 核心组件 + +#### 1. 通用搜索组件 (GlobalSearchCommonWidget) + +基于真实项目代码的通用搜索组件： + +```dart +/// 全局搜索通用组件 +class GlobalSearchCommonWidget extends StatefulWidget { + const GlobalSearchCommonWidget({ + Key? key, + required this.selectCommonSearchItem + }) : super(key: key); + + final SelectCommonSearch selectCommonSearchItem; + + @override + State createState() => + _GlobalSearchCommonWidgetState(); +} + +/// 搜索项目数据模型 +class SearchItemBean { + String name; + String event; + + SearchItemBean({required this.name, required this.event}); +} + +/// 选择通用搜索项回调 +typedef SelectCommonSearch = void Function(SearchItemBean commonSearchItem); +``` + +#### 2. 搜索组件实现 + +```dart +class _GlobalSearchCommonWidgetState extends State { + List commonSearchBeanList = []; + String tips = ''; + + @override + Widget build(BuildContext context) { + if (commonSearchBeanList.isEmpty) { + return Container(); + } + return Column( + mainAxisSize: MainAxisSize.min, + children: [ + Container( + padding: EdgeInsets.fromLTRB(15, 15, 12, 0), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Row( + mainAxisAlignment: MainAxisAlignment.spaceBetween, + children: [ + Text( + tips, + style: OneTextStyle.content(color: OneColors.tc), + ), + ], + ), + SizedBox(height: 10), + Wrap( + spacing: 8, + runSpacing: 12, + children: _buildHistoryTag(commonSearchBeanList), + ), + ], + ), + ), + ], + ); + } + + /// 构建历史搜索标签 + List _buildHistoryTag(List historys) { + List historyWidgets = []; + for (int i = 0; i < historys.length; i++) { + var displayName = historys[i].name; + if (displayName.length > 8) { + displayName = displayName.substring(0, 8) + '...'; + } + historyWidgets.add(InkWell( + onTap: () { + widget.selectCommonSearchItem(historys[i]); + }, + child: Container( + padding: EdgeInsets.fromLTRB(5, 0, 5, 0), + decoration: BoxDecoration( + color: OneColors.bgcSub1, + borderRadius: BorderRadius.all(Radius.circular(2)), + ), + child: Text( + displayName, + style: OneTextStyle.content( + color: OneColors.tc.withOpacity(0.55), + ), + ), + ), + )); + } + return historyWidgets; + } + + @override + void initState() { + super.initState(); + getCommonSearchResult(); + } + + /// 获取通用搜索结果 + void getCommonSearchResult() { + // 实际项目中的搜索数据获取逻辑 + } +} +``` + +#### 3. 搜索组件架构 + +实际项目包含的搜索组件： + +- **QuicklyAccess.dart**: 快速访问组件 +- **search_all_result_widget.dart**: 全部搜索结果组件 +- **search_common_widget.dart**: 通用搜索组件 +- **search_event_result_widget.dart**: 事件搜索结果组件 +- **search_history_widget.dart**: 搜索历史组件 +- **search_input_TextField_widget.dart**: 搜索输入框组件 +- **search_mall_result_widget.dart**: 商城搜索结果组件 +- **search_post_result_widget.dart**: 帖子搜索结果组件 +- **search_result_widget.dart**: 搜索结果组件 + +## 数据模型 + +### 搜索查询模型 +```dart +class SearchQuery { + final String keyword; + final List categories; + final SearchScope scope; + final SortOption sortBy; + final int page; + final int pageSize; + final Map filters; + final bool includeHistory; +} + +enum SearchScope { + all, // 全部内容 + vehicle, // 车辆相关 + order, // 订单相关 + service, // 服务相关 + settings, // 设置相关 + help // 帮助文档 +} + +enum SortOption { + relevance, // 相关性 + time, // 时间 + popularity, // 热度 + alphabetical // 字母顺序 +} +``` + +### 搜索结果模型 +```dart +class SearchResult { + final String query; + final int totalCount; + final List items; + final List suggestions; + final Duration searchTime; + final Map categoryCount; + final bool hasMore; +} + +class SearchResultItem { + final String id; + final String title; + final String? subtitle; + final String? description; + final String category; + final String moduleId; + final String? imageUrl; + final double relevanceScore; + final DateTime? timestamp; + final Map metadata; + final List highlights; +} +``` + +### 搜索建议模型 +```dart +class SearchSuggestion { + final String text; + final SuggestionType type; + final String? category; + final int frequency; + final double relevance; + final Map? metadata; +} + +enum SuggestionType { + keyword, // 关键词建议 + history, // 历史搜索 + popular, // 热门搜索 + completion, // 自动补全 + correction // 拼写纠错 +} +``` + +## API 接口 + +### 搜索接口 +```dart +abstract class GlobalSearchService { + // 执行全局搜索 + Future> search(SearchRequest request); + + // 获取搜索建议 + Future>> getSuggestions(SuggestionRequest request); + + // 获取热门搜索 + Future>> getPopularSearches(); + + // 获取搜索历史 + Future>> getSearchHistory(HistoryRequest request); +} +``` + +### 索引管理接口 +```dart +abstract class SearchIndexService { + // 更新搜索索引 + Future> updateSearchIndex(UpdateIndexRequest request); + + // 删除搜索索引 + Future> deleteSearchIndex(DeleteIndexRequest request); + + // 获取索引状态 + Future> getIndexStatus(String moduleId); +} +``` + +### 搜索提供者接口 +```dart +abstract class SearchProvider { + // 搜索提供者ID + String get providerId; + + // 支持的搜索类别 + List get supportedCategories; + + // 执行搜索 + Future> search(SearchQuery query); + + // 获取可搜索项目 + Future> getSearchableItems(); + + // 获取搜索建议 + Future> getSuggestions(String input); +} +``` + +## 配置管理 + +### 搜索配置 +```dart +class GlobalSearchConfig { + final int maxResults; + final int suggestionLimit; + final bool enableHistory; + final bool enableSuggestions; + final Duration cacheExpiry; + final List enabledModules; + final Map categoryWeights; + + static const GlobalSearchConfig defaultConfig = GlobalSearchConfig( + maxResults: 100, + suggestionLimit: 10, + enableHistory: true, + enableSuggestions: true, + cacheExpiry: Duration(minutes: 30), + enabledModules: ['vehicle', 'order', 'service', 'settings'], + categoryWeights: { + 'vehicle': 1.0, + 'order': 0.8, + 'service': 0.9, + 'settings': 0.6, + }, + ); +} +``` + +### 索引配置 +```dart +class SearchIndexConfig { + final bool enableRealTimeIndex; + final Duration indexUpdateInterval; + final int maxIndexSize; + final List indexedFields; + final Map fieldWeights; + + static const SearchIndexConfig defaultIndexConfig = SearchIndexConfig( + enableRealTimeIndex: true, + indexUpdateInterval: Duration(minutes: 5), + maxIndexSize: 10000, + indexedFields: ['title', 'description', 'tags', 'content'], + fieldWeights: { + 'title': 3, + 'description': 2, + 'tags': 2, + 'content': 1, + }, + ); +} +``` + +## 使用示例 + +### 基本搜索功能 +```dart +// 初始化全局搜索 +final globalSearch = GlobalSearchEngine.instance; +await globalSearch.initialize(GlobalSearchConfig.defaultConfig); + +// 执行搜索 +final searchQuery = SearchQuery( + keyword: '充电', + categories: ['vehicle', 'service'], + scope: SearchScope.all, + sortBy: SortOption.relevance, + page: 1, + pageSize: 20, +); + +final searchResult = await globalSearch.search(searchQuery); + +// 处理搜索结果 +for (final item in searchResult.items) { + print('${item.title}: ${item.description}'); + print('类别: ${item.category}, 相关性: ${item.relevanceScore}'); +} +``` + +### 搜索建议功能 +```dart +// 获取输入建议 +final suggestions = await globalSearch.getSuggestions('充电'); + +// 显示建议列表 +for (final suggestion in suggestions) { + switch (suggestion.type) { + case SuggestionType.completion: + print('补全: ${suggestion.text}'); + break; + case SuggestionType.history: + print('历史: ${suggestion.text}'); + break; + case SuggestionType.popular: + print('热门: ${suggestion.text}'); + break; + } +} + +// 获取热门搜索 +final popularSearches = await globalSearch.getPopularSearches(); +print('热门搜索: ${popularSearches.join(', ')}'); +``` + +### 搜索历史管理 +```dart +// 添加搜索记录 +final searchRecord = SearchRecord( + query: '充电站', + timestamp: DateTime.now(), + resultCount: 25, + category: 'vehicle', +); + +await SearchHistoryManager.instance.addSearchRecord(searchRecord); + +// 获取搜索历史 +final history = await SearchHistoryManager.instance.getSearchHistory(limit: 10); + +for (final record in history) { + print('${record.query} - ${record.timestamp}'); +} + +// 清空搜索历史 +await SearchHistoryManager.instance.clearSearchHistory(); +``` + +### 注册搜索提供者 +```dart +// 实现搜索提供者 +class VehicleSearchProvider extends SearchProvider { + @override + String get providerId => 'vehicle_search'; + + @override + List get supportedCategories => ['vehicle', 'charging', 'maintenance']; + + @override + Future> search(SearchQuery query) async { + // 实现车辆相关内容搜索 + final vehicles = await vehicleService.searchVehicles(query.keyword); + + return vehicles.map((vehicle) => SearchResultItem( + id: vehicle.id, + title: vehicle.name, + description: vehicle.description, + category: 'vehicle', + moduleId: 'app_car', + relevanceScore: calculateRelevance(query.keyword, vehicle), + )).toList(); + } + + @override + Future> getSuggestions(String input) async { + // 返回车辆相关搜索建议 + return vehicleService.getSearchSuggestions(input); + } +} + +// 注册搜索提供者 +globalSearch.registerSearchProvider(VehicleSearchProvider()); +``` + +## 测试策略 + +### 单元测试 +```dart +group('GlobalSearch Tests', () { + test('should return search results', () async { + // Given + final searchEngine = GlobalSearchEngine(); + final query = SearchQuery(keyword: 'test', scope: SearchScope.all); + + // When + final result = await searchEngine.search(query); + + // Then + expect(result.items, isNotEmpty); + expect(result.query, 'test'); + }); + + test('should provide search suggestions', () async { + // Given + final suggestionSystem = SearchSuggestionSystem(); + + // When + final suggestions = await suggestionSystem.generateSuggestions('cha'); + + // Then + expect(suggestions, isNotEmpty); + expect(suggestions.first.text, contains('cha')); + }); +}); +``` + +### 集成测试 +```dart +group('Search Integration Tests', () { + testWidgets('complete search flow', (tester) async { + // 1. 输入搜索关键词 + await tester.enterText(find.byKey(Key('search_input')), '充电'); + + // 2. 验证搜索建议显示 + expect(find.text('充电站'), findsOneWidget); + expect(find.text('充电桩'), findsOneWidget); + + // 3. 执行搜索 + await tester.tap(find.byKey(Key('search_button'))); + await tester.pumpAndSettle(); + + // 4. 验证搜索结果 + expect(find.byType(SearchResultItem), findsWidgets); + }); +}); +``` + +## 性能优化 + +### 搜索性能优化 +- **索引优化**：使用倒排索引提高搜索速度 +- **缓存策略**：热门搜索结果缓存 +- **分页加载**：大结果集分页加载 +- **异步处理**：搜索操作异步处理 + +### 内存优化 +- **结果限制**：限制搜索结果数量 +- **懒加载**：搜索结果懒加载 +- **对象池**：复用搜索对象 +- **内存回收**：及时回收不用的搜索数据 + +## 算法和策略 + +### 相关性算法 +```dart +class RelevanceCalculator { + // 计算文本相关性 + double calculateTextRelevance(String query, String text); + + // 计算标题权重 + double calculateTitleWeight(String query, String title); + + // 计算类别权重 + double calculateCategoryWeight(String category); + + // 计算综合得分 + double calculateFinalScore(Map scores); +} +``` + +### 搜索优化策略 +- **查询扩展**：同义词和相关词扩展 +- **模糊匹配**：支持模糊匹配搜索 +- **权重调整**：动态调整搜索权重 +- **个性化排序**：基于用户行为的个性化排序 + +## 版本历史 + +### v0.3.2+5 (当前版本) +- 新增语义搜索功能 +- 优化搜索性能和准确性 +- 支持多语言搜索 +- 修复搜索结果排序问题 + +### v0.3.1 +- 支持实时搜索建议 +- 新增搜索历史管理 +- 优化搜索索引结构 +- 改进搜索结果展示 + +## 依赖关系 + +### 内部依赖 +- `basic_storage`: 本地数据存储 +- `basic_network`: 网络请求服务 +- `basic_utils`: 工具类库 +- `basic_logger`: 日志记录 + +### 外部依赖 +- `sqflite`: 本地数据库 +- `fuzzywuzzy`: 模糊匹配算法 +- `rxdart`: 响应式编程 +- `collection`: 集合工具 + +## 总结 + +`GlobalSearch` 模块为 OneApp 提供了强大的全局搜索能力，通过统一的搜索接口、智能的搜索建议、完善的历史管理和优化的搜索结果，为用户提供了高效、精准的搜索体验。该模块的设计充分考虑了可扩展性、性能优化和用户体验，能够很好地支撑应用的搜索需求。 diff --git a/service_component/README.md b/service_component/README.md new file mode 100644 index 0000000..8c9b1c7 --- /dev/null +++ b/service_component/README.md @@ -0,0 +1,272 @@ +# Service Component 服务组件模块群 + +## 模块群概述 + +Service Component 模块群是 OneApp 的服务组件集合，提供了各种通用的业务服务组件和工具。该模块群包含了配置管理、全局搜索、伴侣应用、弹窗管理、分享功能等跨模块的通用服务组件。 + +## 子模块列表 + +### 核心服务组件 +1. **[app_configuration](./app_configuration.md)** - 应用配置管理模块 + - 远程配置管理 + - 本地配置缓存 + - 配置热更新 + - 环境配置切换 + +2. **[clr_configuration](./clr_configuration.md)** - 配置服务SDK + - 配置API封装 + - 配置数据模型 + - 配置同步机制 + - 配置变更通知 + +3. **[GlobalSearch](./GlobalSearch.md)** - 全局搜索模块 + - 跨模块内容搜索 + - 智能搜索建议 + - 搜索历史管理 + - 搜索结果优化 + +4. **[oneapp_companion](./oneapp_companion.md)** - 伴侣应用模块 + - 多设备协同 + - 数据同步 + - 远程控制 + - 设备管理 + +5. **[oneapp_popup](./oneapp_popup.md)** - 弹窗管理模块 + - 统一弹窗管理 + - 弹窗优先级控制 + - 弹窗样式定制 + - 弹窗生命周期 + +6. **[ShareToFriends](./ShareToFriends.md)** - 分享功能模块 + - 社交平台分享 + - 自定义分享内容 + - 分享统计分析 + - 分享权限控制 + +## 功能特性 + +### 核心功能 +1. **配置管理服务** + - 集中化配置管理 + - 动态配置下发 + - 配置版本控制 + - 配置回滚机制 + +2. **搜索服务** + - 全文搜索引擎 + - 智能搜索推荐 + - 搜索结果排序 + - 搜索性能优化 + +3. **设备协同服务** + - 多设备数据同步 + - 跨设备操作控制 + - 设备状态监控 + - 设备权限管理 + +4. **用户交互服务** + - 弹窗统一管理 + - 分享功能集成 + - 用户反馈收集 + - 交互体验优化 + +## 技术架构 + +### 服务架构图 +``` +应用层 (App Layer) + ↓ +服务组件层 (Service Components) + ↓ +基础服务层 (Basic Services) + ↓ +平台能力层 (Platform Capabilities) +``` + +### 组件交互图 +```mermaid +graph TD + A[App Configuration] --> B[Configuration SDK] + C[Global Search] --> D[Search Engine] + E[Companion App] --> F[Sync Service] + G[Popup Manager] --> H[UI Controller] + I[Share Service] --> J[Platform APIs] + + B --> K[Basic Storage] + D --> K + F --> L[Basic Network] + H --> M[Basic UI] + J --> N[Basic Platform] +``` + +## 设计原则 + +### 1. 模块化设计 +- **独立部署**: 每个组件可独立部署和更新 +- **接口标准**: 统一的服务接口规范 +- **依赖管理**: 清晰的依赖关系定义 +- **版本兼容**: 向后兼容的版本策略 + +### 2. 服务化架构 +- **微服务**: 服务组件微服务化 +- **API网关**: 统一的API入口 +- **服务发现**: 动态服务发现机制 +- **负载均衡**: 服务负载均衡 + +### 3. 数据一致性 +- **事务管理**: 跨服务事务协调 +- **数据同步**: 多服务数据同步 +- **冲突解决**: 数据冲突解决策略 +- **最终一致性**: 最终一致性保证 + +## 通用能力 + +### 配置管理能力 +```dart +// 获取配置 +final config = await ConfigService.getConfig('feature_flags'); + +// 监听配置变化 +ConfigService.onConfigChanged('feature_flags').listen((newConfig) { + // 处理配置变化 +}); + +// 本地配置缓存 +await ConfigService.setCachedConfig('user_preferences', userConfig); +``` + +### 搜索能力 +```dart +// 全局搜索 +final results = await GlobalSearchService.search( + query: '车辆', + categories: ['vehicle', 'service', 'help'], +); + +// 搜索建议 +final suggestions = await GlobalSearchService.getSuggestions('车'); + +// 搜索历史 +final history = await GlobalSearchService.getSearchHistory(); +``` + +### 弹窗管理能力 +```dart +// 显示弹窗 +PopupManager.show( + popup: CustomPopup( + title: '提示', + content: '是否确认操作？', + priority: PopupPriority.high, + ), +); + +// 弹窗队列管理 +PopupManager.enqueue(popupList); + +// 弹窗生命周期 +PopupManager.onPopupShown.listen((popup) { + // 弹窗显示回调 +}); +``` + +## 详细模块文档 + +- [App Configuration - 应用配置管理](./app_configuration.md) +- [CLR Configuration - 配置服务SDK](./clr_configuration.md) +- [Global Search - 全局搜索](./GlobalSearch.md) +- [OneApp Companion - 伴侣应用](./oneapp_companion.md) +- [OneApp Popup - 弹窗管理](./oneapp_popup.md) +- [Share To Friends - 分享功能](./ShareToFriends.md) + +## 开发指南 + +### 环境要求 +- Flutter >=3.0.0 +- Dart >=3.0.0 <4.0.0 +- Android SDK >=21 +- iOS >=11.0 + +### 依赖管理 +```yaml +dependencies: + # 服务组件 + app_configuration: + path: ../oneapp_service_component/app_configuration + oneapp_companion: + path: ../oneapp_service_component/oneapp_companion + oneapp_popup: + path: ../oneapp_service_component/oneapp_popup +``` + +### 服务初始化 +```dart +Future initializeServiceComponents() async { + // 初始化配置服务 + await ConfigurationService.initialize(); + + // 初始化搜索服务 + await GlobalSearchService.initialize(); + + // 初始化伴侣应用服务 + await CompanionService.initialize(); + + // 初始化弹窗管理器 + PopupManager.initialize(); + + // 初始化分享服务 + await ShareService.initialize(); +} +``` + +## 性能优化 + +### 1. 缓存策略 +- **配置缓存**: 本地配置缓存减少网络请求 +- **搜索缓存**: 搜索结果智能缓存 +- **数据预加载**: 关键数据预加载 +- **懒加载**: 按需加载服务组件 + +### 2. 网络优化 +- **请求合并**: 批量请求减少网络开销 +- **数据压缩**: 传输数据压缩 +- **CDN加速**: 静态资源CDN分发 +- **离线支持**: 关键功能离线可用 + +### 3. 内存管理 +- **资源释放**: 及时释放不需要的资源 +- **内存监控**: 监控内存使用情况 +- **对象池**: 复用频繁创建的对象 +- **弱引用**: 避免内存泄漏 + +## 监控和诊断 + +### 服务监控 +- **服务健康检查**: 定期检查服务状态 +- **性能指标监控**: 监控关键性能指标 +- **错误日志收集**: 收集和分析错误日志 +- **用户行为分析**: 分析用户使用模式 + +### 故障诊断 +- **链路追踪**: 跟踪服务调用链路 +- **异常告警**: 异常情况实时告警 +- **故障恢复**: 自动故障恢复机制 +- **降级策略**: 服务降级保证可用性 + +## 安全考虑 + +### 数据安全 +- **数据加密**: 敏感数据加密存储和传输 +- **访问控制**: 基于角色的访问控制 +- **审计日志**: 详细的操作审计日志 +- **数据脱敏**: 敏感数据脱敏处理 + +### 隐私保护 +- **用户同意**: 明确的用户数据使用同意 +- **数据最小化**: 仅收集必要的用户数据 +- **匿名化**: 用户数据匿名化处理 +- **数据删除**: 用户数据删除权支持 + +## 总结 + +Service Component 模块群为 OneApp 提供了丰富的通用服务组件，通过模块化设计和服务化架构，实现了高内聚、低耦合的服务体系。这些组件不仅提升了开发效率，也保证了服务的一致性和可维护性，为整个应用生态提供了坚实的技术支撑。 diff --git a/service_component/ShareToFriends.md b/service_component/ShareToFriends.md new file mode 100644 index 0000000..173736f --- /dev/null +++ b/service_component/ShareToFriends.md @@ -0,0 +1,566 @@ +# ShareToFriends - 分享功能模块 + +## 模块概述 + +`ShareToFriends` 是 OneApp 的分享功能模块，提供了完整的社交分享解决方案。该模块支持多种社交平台分享、自定义分享内容、分享统计分析和权限控制等功能，为用户提供便捷的内容分享体验。 + +## 核心功能 + +### 1. 社交平台分享 +- **多平台支持**：支持微信、QQ、微博、抖音等主流平台 +- **原生集成**：深度集成各平台原生分享能力 +- **格式适配**：自动适配各平台的内容格式要求 +- **状态跟踪**：跟踪分享状态和结果反馈 + +### 2. 自定义分享内容 +- **内容模板**：提供丰富的分享内容模板 +- **动态生成**：根据分享内容动态生成分享素材 +- **多媒体支持**：支持文字、图片、视频、链接分享 +- **品牌定制**：支持品牌元素的自定义添加 + +### 3. 分享统计分析 +- **分享数据统计**：统计分享次数、平台分布等数据 +- **用户行为分析**：分析用户分享行为和偏好 +- **转化率跟踪**：跟踪分享带来的转化效果 +- **热点内容识别**：识别热门分享内容 + +### 4. 分享权限控制 +- **内容权限**：控制可分享的内容范围 +- **用户权限**：基于用户角色的分享权限 +- **平台限制**：特定平台的分享限制 +- **敏感内容过滤**：过滤敏感或不当内容 + +## 技术架构 + +### 架构设计 +``` +┌─────────────────────────────────────┐ +│ 应用界面层 │ +│ (Share UI Components) │ +├─────────────────────────────────────┤ +│ ShareToFriends │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 分享管理 │ 内容生成 │ 平台适配 │ │ +│ ├──────────┼──────────┼──────────┤ │ +│ │ 统计分析 │ 权限控制 │ 缓存管理 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 平台SDK层 │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 微信SDK │ QQ SDK │ 微博SDK │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 系统分享接口 │ +│ (System Share APIs) │ +└─────────────────────────────────────┘ +``` + +### 核心组件 + +#### 1. 分享管理器 (ShareManager) +```dart +class ShareManager { + // 执行分享 + Future share(ShareRequest request); + + // 获取可用的分享平台 + Future> getAvailablePlatforms(); + + // 检查平台可用性 + Future isPlatformAvailable(SharePlatformType platform); + + // 注册分享平台 + void registerPlatform(SharePlatform platform); +} +``` + +#### 2. 内容生成器 (ContentGenerator) +```dart +class ShareContentGenerator { + // 生成分享内容 + Future generateContent(ContentTemplate template, Map data); + + // 创建分享图片 + Future createShareImage(ShareImageConfig config); + + // 生成分享链接 + Future generateShareLink(ShareLinkConfig config); + + // 格式化分享文本 + String formatShareText(String template, Map variables); +} +``` + +#### 3. 平台适配器 (PlatformAdapter) +```dart +class SharePlatformAdapter { + // 适配分享内容 + ShareContent adaptContent(ShareContent content, SharePlatformType platform); + + // 验证内容格式 + ValidationResult validateContent(ShareContent content, SharePlatformType platform); + + // 获取平台限制 + PlatformLimitations getPlatformLimitations(SharePlatformType platform); + + // 转换内容格式 + ShareContent convertContentFormat(ShareContent content, ContentFormat targetFormat); +} +``` + +#### 4. 统计分析器 (ShareAnalytics) +```dart +class ShareAnalytics { + // 记录分享事件 + Future recordShareEvent(ShareEvent event); + + // 获取分享统计 + Future getShareStatistics(StatisticsQuery query); + + // 分析用户分享行为 + Future analyzeUserBehavior(String userId); + + // 获取热门分享内容 + Future> getPopularContent(TimeRange timeRange); +} +``` + +## 数据模型 + +### 分享请求模型 +```dart +class ShareRequest { + final String id; + final ShareContent content; + final SharePlatformType platform; + final ShareOptions options; + final String? userId; + final Map metadata; + final DateTime timestamp; +} + +class ShareContent { + final String? title; + final String? description; + final String? text; + final List images; + final String? video; + final String? url; + final String? thumbnailUrl; + final ContentType type; + final Map extras; +} + +enum ContentType { + text, // 纯文本 + image, // 图片 + video, // 视频 + link, // 链接 + miniProgram, // 小程序 + music, // 音乐 + file // 文件 +} +``` + +### 分享平台模型 +```dart +enum SharePlatformType { + wechat, // 微信好友 + wechatMoments, // 微信朋友圈 + qq, // QQ好友 + qzone, // QQ空间 + weibo, // 新浪微博 + douyin, // 抖音 + system, // 系统分享 + copy, // 复制链接 + email, // 邮件 + sms // 短信 +} + +class SharePlatform { + final SharePlatformType type; + final String name; + final String packageName; + final String iconUrl; + final bool isInstalled; + final bool isEnabled; + final PlatformLimitations limitations; + final Map config; +} +``` + +### 分享结果模型 +```dart +class ShareResult { + final bool isSuccess; + final SharePlatformType platform; + final String? shareId; + final String? errorMessage; + final int? errorCode; + final DateTime timestamp; + final Map extraData; +} + +class ShareStatistics { + final int totalShares; + final Map platformDistribution; + final Map contentTypeDistribution; + final List trends; + final double averageSharesPerUser; + final List topContent; +} +``` + +## API 接口 + +### 分享接口 +```dart +abstract class ShareService { + // 执行分享 + Future> executeShare(ShareRequest request); + + // 获取分享平台列表 + Future>> getSharePlatforms(); + + // 预览分享内容 + Future> previewShare(PreviewRequest request); + + // 获取分享历史 + Future>> getShareHistory(HistoryQuery query); +} +``` + +### 内容生成接口 +```dart +abstract class ShareContentService { + // 生成分享内容 + Future> generateShareContent(ContentGenerationRequest request); + + // 创建分享海报 + Future> createSharePoster(PosterCreationRequest request); + + // 获取内容模板 + Future>> getContentTemplates(String category); +} +``` + +### 统计分析接口 +```dart +abstract class ShareAnalyticsService { + // 获取分享统计数据 + Future> getShareStatistics(StatisticsRequest request); + + // 获取用户分享行为 + Future> getUserShareBehavior(String userId); + + // 获取热门分享内容 + Future>> getPopularContent(PopularContentRequest request); +} +``` + +## 配置管理 + +### 分享配置 +```dart +class ShareConfig { + final List enabledPlatforms; + final bool enableAnalytics; + final bool enableContentGeneration; + final int maxImageSize; + final Duration shareTimeout; + final Map platformConfigs; + + static const ShareConfig defaultConfig = ShareConfig( + enabledPlatforms: [ + SharePlatformType.wechat, + SharePlatformType.wechatMoments, + SharePlatformType.qq, + SharePlatformType.qzone, + SharePlatformType.weibo, + SharePlatformType.system, + ], + enableAnalytics: true, + enableContentGeneration: true, + maxImageSize: 1024 * 1024 * 2, // 2MB + shareTimeout: Duration(seconds: 30), + platformConfigs: {}, + ); +} +``` + +### 内容配置 +```dart +class ContentConfig { + final String appName; + final String appDescription; + final String defaultShareUrl; + final String logoUrl; + final Map shareTemplates; + final List sensitiveWords; + + static const ContentConfig defaultContentConfig = ContentConfig( + appName: 'OneApp', + appDescription: '智能车联网应用', + defaultShareUrl: 'https://oneapp.com', + logoUrl: 'https://oneapp.com/logo.png', + shareTemplates: { + 'vehicle': '我在OneApp发现了一款不错的车辆：{vehicleName}', + 'charging': '在OneApp找到了便宜的充电站，分享给你：{stationName}', + }, + sensitiveWords: ['敏感词1', '敏感词2'], + ); +} +``` + +## 使用示例 + +### 基本分享功能 +```dart +// 分享文本内容 +final shareRequest = ShareRequest( + id: 'share_text_${DateTime.now().millisecondsSinceEpoch}', + content: ShareContent( + text: '我在使用OneApp，感觉很不错！', + url: 'https://oneapp.com', + type: ContentType.text, + ), + platform: SharePlatformType.wechat, + options: ShareOptions( + enableAnalytics: true, + autoGenerateImage: false, + ), +); + +final result = await ShareManager.instance.share(shareRequest); + +if (result.isSuccess) { + print('分享成功'); +} else { + print('分享失败: ${result.errorMessage}'); +} +``` + +### 分享图片内容 +```dart +// 分享车辆信息 +final vehicleInfo = { + 'name': 'Model Y', + 'brand': 'Tesla', + 'price': '30万', + 'image': 'https://example.com/vehicle.jpg', +}; + +// 生成分享内容 +final shareContent = await ShareContentGenerator.instance.generateContent( + ContentTemplate.vehicle, + vehicleInfo, +); + +// 创建分享海报 +final posterPath = await ShareContentGenerator.instance.createShareImage( + ShareImageConfig( + template: 'vehicle_poster', + data: vehicleInfo, + size: Size(750, 1334), + ), +); + +// 执行分享 +final shareResult = await ShareManager.instance.share( + ShareRequest( + id: 'share_vehicle', + content: ShareContent( + title: vehicleInfo['name'], + description: '${vehicleInfo['brand']} ${vehicleInfo['name']} - ${vehicleInfo['price']}', + images: [posterPath], + url: 'https://oneapp.com/vehicle/${vehicleInfo['id']}', + type: ContentType.image, + ), + platform: SharePlatformType.wechatMoments, + ), +); +``` + +### 多平台分享 +```dart +// 获取可用的分享平台 +final availablePlatforms = await ShareManager.instance.getAvailablePlatforms(); + +// 显示分享面板 +showSharePanel( + context: context, + platforms: availablePlatforms, + content: shareContent, + onPlatformSelected: (platform) async { + final result = await ShareManager.instance.share( + ShareRequest( + content: shareContent, + platform: platform.type, + ), + ); + + if (result.isSuccess) { + showSuccessToast('分享成功'); + } else { + showErrorToast('分享失败: ${result.errorMessage}'); + } + }, +); +``` + +### 分享统计分析 +```dart +// 获取分享统计数据 +final statistics = await ShareAnalytics.instance.getShareStatistics( + StatisticsQuery( + timeRange: TimeRange.lastMonth, + groupBy: GroupBy.platform, + ), +); + +print('总分享次数: ${statistics.totalShares}'); +print('平台分布:'); +statistics.platformDistribution.forEach((platform, count) { + print(' ${platform.name}: $count次'); +}); + +// 获取热门分享内容 +final popularContent = await ShareAnalytics.instance.getPopularContent( + TimeRange.lastWeek, +); + +print('热门分享内容:'); +for (final content in popularContent) { + print(' ${content.title}: ${content.shareCount}次分享'); +} +``` + +### 自定义分享内容 +```dart +// 注册自定义内容模板 +ShareContentGenerator.instance.registerTemplate( + 'custom_vehicle', + ContentTemplate( + id: 'custom_vehicle', + name: '自定义车辆分享', + textTemplate: '我在OneApp发现了{brand} {model}，{feature}，推荐给你！', + imageTemplate: 'custom_vehicle_poster.png', + variables: ['brand', 'model', 'feature', 'price'], + ), +); + +// 使用自定义模板生成内容 +final customContent = await ShareContentGenerator.instance.generateContent( + 'custom_vehicle', + { + 'brand': 'BMW', + 'model': 'iX3', + 'feature': '续航500公里', + 'price': '40万', + }, +); +``` + +## 测试策略 + +### 单元测试 +```dart +group('ShareManager Tests', () { + test('should share content successfully', () async { + // Given + final shareManager = ShareManager(); + final shareRequest = ShareRequest( + content: ShareContent(text: 'Test share'), + platform: SharePlatformType.system, + ); + + // When + final result = await shareManager.share(shareRequest); + + // Then + expect(result.isSuccess, true); + expect(result.platform, SharePlatformType.system); + }); + + test('should generate share content from template', () async { + // Given + final generator = ShareContentGenerator(); + final template = ContentTemplate.vehicle; + final data = {'name': 'Model 3', 'brand': 'Tesla'}; + + // When + final content = await generator.generateContent(template, data); + + // Then + expect(content.title, contains('Model 3')); + expect(content.description, contains('Tesla')); + }); +}); +``` + +### 集成测试 +```dart +group('Share Integration Tests', () { + testWidgets('share flow', (tester) async { + // 1. 点击分享按钮 + await tester.tap(find.byKey(Key('share_button'))); + await tester.pumpAndSettle(); + + // 2. 验证分享面板显示 + expect(find.byType(SharePanel), findsOneWidget); + + // 3. 选择分享平台 + await tester.tap(find.byKey(Key('platform_wechat'))); + await tester.pumpAndSettle(); + + // 4. 验证分享执行 + verify(mockShareManager.share(any)).called(1); + }); +}); +``` + +## 性能优化 + +### 内容生成优化 +- **模板缓存**：缓存常用的内容模板 +- **图片压缩**：自动压缩分享图片 +- **异步处理**：异步生成分享内容 +- **批量处理**：批量处理多个分享请求 + +### 平台集成优化 +- **懒加载SDK**：按需加载平台SDK +- **连接池**：复用网络连接 +- **缓存检查**：缓存平台可用性检查结果 +- **超时控制**：合理的超时时间设置 + +## 版本历史 + +### v0.2.5+3 (当前版本) +- 新增抖音分享支持 +- 优化分享内容生成性能 +- 支持自定义分享模板 +- 修复微信分享回调问题 + +### v0.2.4 +- 支持视频内容分享 +- 新增分享统计分析 +- 优化分享面板UI +- 改进错误处理机制 + +## 依赖关系 + +### 内部依赖 +- `basic_utils`: 工具类库 +- `basic_storage`: 本地存储 +- `basic_network`: 网络请求 +- `basic_logger`: 日志记录 + +### 外部依赖 +- `fluwx`: 微信分享SDK +- `share_plus`: 系统分享 +- `image`: 图片处理 +- `path_provider`: 文件路径 + +## 总结 + +`ShareToFriends` 模块为 OneApp 提供了完整的社交分享解决方案。通过多平台支持、自定义内容生成、统计分析和权限控制等功能，该模块让用户能够便捷地分享应用内容到各大社交平台，同时为运营团队提供了有价值的分享数据分析，有助于提升用户参与度和应用传播效果。 diff --git a/service_component/app_configuration.md b/service_component/app_configuration.md new file mode 100644 index 0000000..b821a42 --- /dev/null +++ b/service_component/app_configuration.md @@ -0,0 +1,563 @@ +# App Configuration - 应用配置管理模块 + +## 模块概述 + +`app_configuration` 是 OneApp 的车辆配置管理模块，专注于车辆配置选择和管理功能。该模块提供了完整的车辆配置解决方案，包括车型选择、外观配置、内饰配置、选装配置等功能。 + +## 核心功能 + +### 1. 车辆配置管理 +- **车型配置页面**：提供完整的车辆配置选择界面 +- **配置选项管理**：支持各种车辆配置选项 +- **3D模型展示**：集成3D车辆模型展示功能 +- **配置验证**：配置有效性验证机制 + +### 2. 模块导出组件 + +基于真实项目代码的主要导出： + +```dart +library app_configuration; + +// 车辆配置页面 +export 'src/app_modules/car_configuration/pages/car_configuration_page.dart'; + +// 车辆配置状态管理 +export 'src/app_modules/car_configuration/blocs/car_configuration_bloc.dart'; + +// 配置相关组件 +export 'src/app_modules/car_configuration/widgets/car_rights_dialog_widget.dart'; +export 'src/app_modules/car_configuration/widgets/car_order_count_exception_dialog.dart'; + +// 路由导出 +export 'src/route_export.dart'; + +// 配置常量 +export 'src/app_modules/car_configuration/configuration_constant.dart'; +``` + +### 3. 车辆配置页面 (CarConfigurationPage) + +核心配置页面实现： + +```dart +/// 车辆配置页面 +class CarConfigurationPage extends StatefulWidget with RouteObjProvider { + CarConfigurationPage({ + Key? key, + this.carModelCode, + this.smallPreOrderNum, + this.carOrderNum, + this.needDepositAmount, + this.pageFrom = PageFrom.pageNone, + }) : super(key: key); + + /// 已选车型配置代码 + final String? carModelCode; + + /// 小订订单号，创建大定时可以关联小订 + final String? smallPreOrderNum; + + /// 大定修改订单原始订单号 + final String? carOrderNum; + + /// 大定修改，大定定金金额 + final double? needDepositAmount; + + /// 页面来源类型 + PageFrom? pageFrom = PageFrom.pageNone; + + @override + State createState() => _CarConfigurationPageState(); +} +``` + +### 4. 模块架构组件 + +实际项目包含的配置组件： + +- **car_3D_model_webview.dart**: 3D车辆模型WebView组件 +- **car_exterior_config.dart**: 车辆外观配置组件 +- **car_interior_config.dart**: 车辆内饰配置组件 +- **car_model_config_new.dart**: 新版车型配置组件 +- **car_option_config.dart**: 车辆选装配置组件 +- **config_bottom_bar_widget.dart**: 配置底部栏组件 +- **configuration_tab.dart**: 配置选项卡组件 + +## 技术架构 + +### 模块注册 + +```dart +/// App配置模块 +class AppConfigurationModule extends Module with RouteObjProvider { + @override + List get imports => []; + + @override + List get binds => []; + + @override + List get routes { + final r1 = RouteCenterAPI.routeMetaBy( + AppConfigurationRouteExport.keyAppConfiguration + ); + + return [ + ChildRoute( + r1.path, + child: (_, args) => r1.provider(args).as(), + guards: loginGuardList, + ), + ]; + } +} +``` + +### 目录结构 + +基于实际项目结构： + +``` +lib/ +├── app_configuration.dart # 主导出文件 +├── generated/ # 生成的国际化文件 +├── l10n/ # 国际化资源文件 +└── src/ # 源代码目录 + ├── app_modules/ # 应用模块 + │ └── car_configuration/ # 车辆配置模块 + │ ├── blocs/ # BLoC状态管理 + │ ├── model/ # 数据模型 + │ ├── pages/ # 页面组件 + │ ├── widgets/ # 配置组件 + │ └── configuration_constant.dart # 配置常量 + ├── app_defines/ # 应用定义 + └── route_export.dart # 路由导出 +``` + +### 核心组件 + +#### 1. 配置管理器 (ConfigurationManager) +```dart +class ConfigurationManager { + // 初始化配置管理器 + Future initialize(ConfigurationConfig config); + + // 获取配置值 + T? getValue(String key, {T? defaultValue}); + + // 设置配置值 + Future setValue(String key, T value); + + // 删除配置 + Future removeValue(String key); + + // 获取所有配置 + Map getAllConfigurations(); +} +``` + +#### 2. 远程配置服务 (RemoteConfigService) +```dart +class RemoteConfigService { + // 从服务端获取配置 + Future fetchRemoteConfig(); + + // 检查配置更新 + Future checkForUpdates(); + + // 应用远程配置 + Future applyRemoteConfig(Map config); + + // 获取配置版本信息 + Future getConfigVersion(); +} +``` + +#### 3. 本地缓存管理器 (LocalCacheManager) +```dart +class LocalCacheManager { + // 缓存配置到本地 + Future cacheConfiguration(String key, dynamic value); + + // 从缓存获取配置 + T? getCachedConfiguration(String key); + + // 清除缓存 + Future clearCache([String? key]); + + // 获取缓存大小 + Future getCacheSize(); + + // 压缩缓存数据 + Future compressCache(); +} +``` + +#### 4. 环境管理器 (EnvironmentManager) +```dart +class EnvironmentManager { + // 设置当前环境 + Future setCurrentEnvironment(Environment environment); + + // 获取当前环境 + Environment getCurrentEnvironment(); + + // 获取环境配置 + Map getEnvironmentConfig(Environment environment); + + // 验证环境配置 + Future validateEnvironmentConfig(Environment environment); +} +``` + +## 数据模型 + +### 配置模型 +```dart +class Configuration { + final String key; + final dynamic value; + final ConfigurationType type; + final DateTime createdAt; + final DateTime updatedAt; + final String version; + final Map metadata; + final bool isRemote; + final bool isEncrypted; +} + +enum ConfigurationType { + string, + integer, + double, + boolean, + json, + list +} +``` + +### 环境模型 +```dart +enum Environment { + development, + testing, + staging, + production +} + +class EnvironmentConfig { + final Environment environment; + final String baseUrl; + final String apiKey; + final Map headers; + final int timeout; + final bool enableLogging; + final Map features; +} +``` + +### 配置版本模型 +```dart +class ConfigVersion { + final String version; + final DateTime publishTime; + final String description; + final List changedKeys; + final Map changeset; + final bool isForced; + final DateTime expireTime; +} +``` + +## API 接口 + +### 配置管理接口 +```dart +abstract class ConfigurationService { + // 初始化配置服务 + Future> initialize(InitConfigRequest request); + + // 获取配置 + Future> getConfiguration(GetConfigRequest request); + + // 批量获取配置 + Future>> getBatchConfiguration(BatchConfigRequest request); + + // 更新配置 + Future> updateConfiguration(UpdateConfigRequest request); +} +``` + +### 远程配置接口 +```dart +abstract class RemoteConfigurationService { + // 获取远程配置 + Future>> fetchRemoteConfiguration(FetchConfigRequest request); + + // 检查配置更新 + Future> checkConfigurationUpdate(CheckUpdateRequest request); + + // 上报配置使用情况 + Future> reportConfigurationUsage(UsageReportRequest request); +} +``` + +## 配置管理 + +### 默认配置 +```dart +class DefaultConfiguration { + static const Map defaultConfig = { + 'app': { + 'name': 'OneApp', + 'version': '1.0.0', + 'debug': false, + }, + 'network': { + 'timeout': 30000, + 'retryCount': 3, + 'enableCache': true, + }, + 'ui': { + 'theme': 'auto', + 'language': 'auto', + 'animations': true, + }, + 'features': { + 'enableAnalytics': true, + 'enablePush': true, + 'enableLocation': false, + }, + }; +} +``` + +### 环境配置 +```dart +class EnvironmentConfiguration { + static const Map environments = { + Environment.development: EnvironmentConfig( + environment: Environment.development, + baseUrl: 'https://dev-api.oneapp.com', + apiKey: 'dev_api_key', + enableLogging: true, + ), + Environment.production: EnvironmentConfig( + environment: Environment.production, + baseUrl: 'https://api.oneapp.com', + apiKey: 'prod_api_key', + enableLogging: false, + ), + }; +} +``` + +## 使用示例 + +### 基本配置管理 +```dart +// 初始化配置管理器 +final configManager = ConfigurationManager.instance; +await configManager.initialize(ConfigurationConfig.defaultConfig); + +// 获取配置值 +final appName = configManager.getValue('app.name', defaultValue: 'OneApp'); +final timeout = configManager.getValue('network.timeout', defaultValue: 30000); +final enableAnalytics = configManager.getValue('features.enableAnalytics', defaultValue: true); + +// 设置配置值 +await configManager.setValue('ui.theme', 'dark'); +await configManager.setValue('features.enablePush', false); + +// 监听配置变化 +configManager.onConfigurationChanged.listen((change) { + print('配置变更: ${change.key} = ${change.newValue}'); +}); +``` + +### 远程配置更新 +```dart +// 检查远程配置更新 +final remoteConfigService = RemoteConfigService.instance; +final hasUpdate = await remoteConfigService.checkForUpdates(); + +if (hasUpdate) { + // 获取远程配置 + final remoteConfig = await remoteConfigService.fetchRemoteConfig(); + + if (remoteConfig.isSuccess) { + // 应用远程配置 + await remoteConfigService.applyRemoteConfig(remoteConfig.data); + print('远程配置已更新'); + } +} + +// 监听远程配置更新 +remoteConfigService.onRemoteConfigUpdated.listen((config) { + print('收到远程配置更新'); + // 处理配置更新逻辑 +}); +``` + +### 环境配置切换 +```dart +// 获取当前环境 +final currentEnv = EnvironmentManager.instance.getCurrentEnvironment(); +print('当前环境: $currentEnv'); + +// 切换到测试环境 +await EnvironmentManager.instance.setCurrentEnvironment(Environment.testing); + +// 获取环境配置 +final envConfig = EnvironmentManager.instance.getEnvironmentConfig(Environment.testing); +print('测试环境配置: $envConfig'); + +// 验证环境配置 +final isValid = await EnvironmentManager.instance.validateEnvironmentConfig(Environment.testing); +if (!isValid) { + print('环境配置验证失败'); +} +``` + +### 配置缓存管理 +```dart +// 缓存配置 +final cacheManager = LocalCacheManager.instance; +await cacheManager.cacheConfiguration('user_preferences', userPreferences); + +// 获取缓存配置 +final cachedPreferences = cacheManager.getCachedConfiguration>('user_preferences'); + +// 获取缓存大小 +final cacheSize = await cacheManager.getCacheSize(); +print('缓存大小: ${cacheSize}KB'); + +// 清理缓存 +if (cacheSize > 1024 * 1024) { // 超过1MB + await cacheManager.compressCache(); +} +``` + +## 测试策略 + +### 单元测试 +```dart +group('ConfigurationManager Tests', () { + test('should get and set configuration values', () async { + // Given + final configManager = ConfigurationManager(); + await configManager.initialize(ConfigurationConfig.defaultConfig); + + // When + await configManager.setValue('test.key', 'test_value'); + final value = configManager.getValue('test.key'); + + // Then + expect(value, 'test_value'); + }); + + test('should return default value when key not found', () { + // Given + final configManager = ConfigurationManager(); + + // When + final value = configManager.getValue('nonexistent.key', defaultValue: 'default'); + + // Then + expect(value, 'default'); + }); +}); +``` + +### 集成测试 +```dart +group('Configuration Integration Tests', () { + testWidgets('configuration update flow', (tester) async { + // 1. 初始化配置 + await ConfigurationManager.instance.initialize(ConfigurationConfig.defaultConfig); + + // 2. 模拟远程配置更新 + final mockRemoteConfig = {'feature.newFeature': true}; + await RemoteConfigService.instance.applyRemoteConfig(mockRemoteConfig); + + // 3. 验证配置已更新 + final newFeatureEnabled = ConfigurationManager.instance.getValue('feature.newFeature'); + expect(newFeatureEnabled, true); + }); +}); +``` + +## 性能优化 + +### 缓存策略 +- **内存缓存**：热点配置内存缓存 +- **磁盘缓存**：所有配置磁盘持久化 +- **缓存过期**：配置缓存过期机制 +- **预加载**：应用启动时预加载关键配置 + +### 网络优化 +- **增量同步**：只同步变化的配置项 +- **压缩传输**：配置数据压缩传输 +- **批量操作**：批量获取和更新配置 +- **连接池**：网络连接池优化 + +## 安全考虑 + +### 数据安全 +- **配置加密**：敏感配置加密存储 +- **传输加密**：配置传输使用HTTPS +- **签名验证**：配置数据签名验证 +- **访问控制**：配置访问权限控制 + +### 隐私保护 +- **数据最小化**：只收集必要的配置数据 +- **匿名化**：用户相关配置匿名化 +- **数据清理**：定期清理过期配置 +- **透明度**：配置使用透明化 + +## 监控和诊断 + +### 性能监控 +- **配置使用统计**：统计配置项使用频率 +- **更新性能**：监控配置更新性能 +- **缓存命中率**：监控缓存命中率 +- **网络性能**：监控配置网络请求性能 + +### 故障诊断 +- **配置验证**：配置数据有效性验证 +- **更新失败恢复**：配置更新失败自动恢复 +- **异常监控**：配置相关异常监控 +- **健康检查**：配置服务健康检查 + +## 版本历史 + +### v0.2.6+8 (当前版本) +- 新增配置热更新功能 +- 优化缓存性能 +- 支持配置分组管理 +- 修复环境切换问题 + +### v0.2.5 +- 支持远程配置灰度发布 +- 新增配置使用统计 +- 优化配置同步机制 +- 改进错误处理 + +## 依赖关系 + +### 内部依赖 +- `clr_configuration`: 配置服务SDK +- `basic_storage`: 本地存储服务 +- `basic_network`: 网络请求服务 +- `basic_error`: 错误处理框架 + +### 外部依赖 +- `shared_preferences`: 本地配置存储 +- `dio`: HTTP客户端 +- `encrypt`: 数据加密 +- `rxdart`: 响应式编程 + +## 总结 + +`app_configuration` 作为应用配置管理的核心模块，提供了完整的配置管理解决方案。通过远程配置、本地缓存、热更新和环境切换等功能，为 OneApp 提供了灵活、可靠、高效的配置管理能力，确保应用能够快速响应业务需求变化，同时保证用户体验的一致性和稳定性。 diff --git a/service_component/clr_configuration.md b/service_component/clr_configuration.md new file mode 100644 index 0000000..e5f7b5c --- /dev/null +++ b/service_component/clr_configuration.md @@ -0,0 +1,570 @@ +# CLR Configuration - 配置服务SDK + +## 模块概述 + +`clr_configuration` 是 OneApp 配置服务的核心 SDK，为应用配置管理提供底层的 API 封装和数据处理能力。该 SDK 封装了配置服务的网络接口、数据模型、同步机制和变更通知等功能，为上层的配置管理模块提供稳定可靠的服务支撑。 + +## 核心功能 + +### 1. 配置 API 封装 +- **RESTful API**：配置服务 REST API 封装 +- **GraphQL API**：配置查询 GraphQL 接口 +- **WebSocket API**：实时配置更新接口 +- **批量操作**：配置批量读写操作 + +### 2. 配置数据模型 +- **数据结构**：标准化的配置数据结构 +- **类型系统**：强类型配置值系统 +- **序列化**：配置数据序列化和反序列化 +- **验证机制**：配置数据有效性验证 + +### 3. 配置同步机制 +- **增量同步**：配置变更增量同步 +- **冲突解决**：配置冲突解决策略 +- **版本控制**：配置版本管理机制 +- **事务支持**：配置操作事务保证 + +### 4. 配置变更通知 +- **事件驱动**：基于事件的变更通知 +- **订阅机制**：配置变更订阅管理 +- **推送通知**：实时推送配置变更 +- **回调处理**：配置变更回调处理 + +## 技术架构 + +### 架构设计 +``` +┌─────────────────────────────────────┐ +│ 配置管理应用层 │ +│ (app_configuration) │ +├─────────────────────────────────────┤ +│ CLR Configuration │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ API封装 │ 数据模型 │ 同步引擎 │ │ +│ ├──────────┼──────────┼──────────┤ │ +│ │ 事件系统 │ 缓存层 │ 安全模块 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 网络通信层 │ +│ (HTTP/WebSocket/GraphQL) │ +├─────────────────────────────────────┤ +│ 配置服务后端 │ +│ (Configuration Server) │ +└─────────────────────────────────────┘ +``` + +### 核心组件 + +#### 1. API 客户端 (ApiClient) +```dart +class ConfigurationApiClient { + // 获取配置 + Future> getConfiguration(GetConfigRequest request); + + // 设置配置 + Future> setConfiguration(SetConfigRequest request); + + // 批量获取配置 + Future>> getBatchConfiguration(BatchGetRequest request); + + // 订阅配置变更 + Stream subscribeConfigurationChanges(String key); +} +``` + +#### 2. 数据模型管理器 (DataModelManager) +```dart +class ConfigurationDataModel { + // 序列化配置数据 + Map serialize(ConfigData data); + + // 反序列化配置数据 + ConfigData deserialize(Map json); + + // 验证配置数据 + ValidationResult validate(ConfigData data); + + // 转换配置数据类型 + T convertValue(dynamic value, ConfigType targetType); +} +``` + +#### 3. 同步引擎 (SyncEngine) +```dart +class ConfigurationSyncEngine { + // 开始同步 + Future startSync(SyncOptions options); + + // 增量同步 + Future incrementalSync(String lastSyncVersion); + + // 解决冲突 + Future resolveConflict(ConfigurationConflict conflict); + + // 回滚配置 + Future rollbackConfiguration(String version); +} +``` + +#### 4. 事件系统 (EventSystem) +```dart +class ConfigurationEventSystem { + // 发布事件 + void publishEvent(ConfigurationEvent event); + + // 订阅事件 + StreamSubscription subscribe(EventHandler handler); + + // 取消订阅 + void unsubscribe(StreamSubscription subscription); + + // 清理事件 + void clearEvents([String? eventType]); +} +``` + +## 数据模型 + +### 配置数据模型 +```dart +class ConfigData { + final String key; + final dynamic value; + final ConfigType type; + final String version; + final DateTime timestamp; + final Map metadata; + final List tags; + final ConfigScope scope; + final bool isEncrypted; + final String? description; +} + +enum ConfigType { + string, + integer, + double, + boolean, + json, + array, + binary +} + +enum ConfigScope { + global, + user, + device, + session +} +``` + +### 配置变更模型 +```dart +class ConfigurationChange { + final String key; + final dynamic oldValue; + final dynamic newValue; + final ChangeType changeType; + final String version; + final DateTime timestamp; + final String? userId; + final String? source; + final Map context; +} + +enum ChangeType { + created, + updated, + deleted, + restored +} +``` + +### API 请求模型 +```dart +class GetConfigRequest { + final String key; + final ConfigScope? scope; + final String? version; + final bool includeMetadata; + final List? tags; +} + +class SetConfigRequest { + final String key; + final dynamic value; + final ConfigType type; + final ConfigScope scope; + final Map? metadata; + final List? tags; + final bool encrypt; +} +``` + +## API 接口 + +### 配置操作接口 +```dart +abstract class ConfigurationApi { + // 获取单个配置 + Future> getConfig(String key, {ConfigScope? scope}); + + // 设置单个配置 + Future> setConfig(String key, dynamic value, {ConfigType? type, ConfigScope? scope}); + + // 删除配置 + Future> deleteConfig(String key, {ConfigScope? scope}); + + // 检查配置是否存在 + Future> hasConfig(String key, {ConfigScope? scope}); +} +``` + +### 批量操作接口 +```dart +abstract class BatchConfigurationApi { + // 批量获取配置 + Future>> getBatchConfigs(List keys); + + // 批量设置配置 + Future> setBatchConfigs(Map configs); + + // 批量删除配置 + Future> deleteBatchConfigs(List keys); +} +``` + +### 同步接口 +```dart +abstract class ConfigurationSyncApi { + // 获取配置版本 + Future> getConfigVersion(); + + // 同步配置 + Future> syncConfigurations(SyncRequest request); + + // 获取配置变更历史 + Future>> getChangeHistory(ChangeHistoryRequest request); +} +``` + +## 配置管理 + +### SDK 配置 +```dart +class ConfigurationSdkConfig { + final String serverUrl; + final String apiKey; + final String clientId; + final Duration timeout; + final int maxRetries; + final bool enableCache; + final bool enableEncryption; + final LogLevel logLevel; + + static const ConfigurationSdkConfig defaultConfig = ConfigurationSdkConfig( + serverUrl: 'https://config-api.oneapp.com', + timeout: Duration(seconds: 30), + maxRetries: 3, + enableCache: true, + enableEncryption: true, + logLevel: LogLevel.info, + ); +} +``` + +### 缓存配置 +```dart +class CacheConfig { + final Duration ttl; + final int maxSize; + final bool enableCompression; + final CacheEvictionPolicy evictionPolicy; + + static const CacheConfig defaultCacheConfig = CacheConfig( + ttl: Duration(minutes: 30), + maxSize: 1000, + enableCompression: true, + evictionPolicy: CacheEvictionPolicy.lru, + ); +} +``` + +## 使用示例 + +### 基本配置操作 +```dart +// 初始化 SDK +final configSdk = ConfigurationSdk.instance; +await configSdk.initialize(ConfigurationSdkConfig.defaultConfig); + +// 获取配置 +try { + final config = await configSdk.getConfig('app.theme'); + print('当前主题: ${config.value}'); +} catch (e) { + print('获取配置失败: $e'); +} + +// 设置配置 +await configSdk.setConfig( + 'user.language', + 'zh-CN', + type: ConfigType.string, + scope: ConfigScope.user, +); + +// 删除配置 +await configSdk.deleteConfig('temp.data'); +``` + +### 批量配置操作 +```dart +// 批量获取配置 +final keys = ['app.theme', 'app.language', 'app.version']; +final batchResult = await configSdk.getBatchConfigs(keys); + +for (final entry in batchResult.entries) { + print('${entry.key}: ${entry.value.value}'); +} + +// 批量设置配置 +final batchConfigs = { + 'ui.showTips': true, + 'ui.animationSpeed': 1.0, + 'ui.darkMode': false, +}; + +await configSdk.setBatchConfigs(batchConfigs); +``` + +### 配置变更监听 +```dart +// 监听特定配置变更 +configSdk.subscribeConfigurationChanges('app.theme').listen((change) { + print('主题配置变更: ${change.oldValue} -> ${change.newValue}'); + // 应用新的主题配置 + applyThemeConfig(change.newValue); +}); + +// 监听所有配置变更 +configSdk.onConfigurationChanged.listen((change) { + print('配置变更: ${change.key}'); + logConfigurationChange(change); +}); +``` + +### 配置同步 +```dart +// 检查是否有配置更新 +final currentVersion = await configSdk.getConfigVersion(); +final hasUpdate = await configSdk.checkForUpdates(currentVersion.version); + +if (hasUpdate) { + // 执行增量同步 + final syncResult = await configSdk.incrementalSync(currentVersion.version); + + if (syncResult.isSuccess) { + print('配置同步成功，更新了 ${syncResult.updatedCount} 个配置'); + } else { + print('配置同步失败: ${syncResult.error}'); + } +} +``` + +## 测试策略 + +### 单元测试 +```dart +group('ConfigurationSdk Tests', () { + test('should get configuration successfully', () async { + // Given + final sdk = ConfigurationSdk(); + await sdk.initialize(ConfigurationSdkConfig.defaultConfig); + + // When + final result = await sdk.getConfig('test.key'); + + // Then + expect(result.key, 'test.key'); + expect(result.value, isNotNull); + }); + + test('should handle configuration not found', () async { + // Given + final sdk = ConfigurationSdk(); + + // When & Then + expect( + () => sdk.getConfig('nonexistent.key'), + throwsA(isA()), + ); + }); +}); +``` + +### 集成测试 +```dart +group('Configuration Integration Tests', () { + testWidgets('configuration sync flow', (tester) async { + // 1. 初始化 SDK + await ConfigurationSdk.instance.initialize(testConfig); + + // 2. 设置配置 + await ConfigurationSdk.instance.setConfig('test.sync', 'value1'); + + // 3. 模拟远程配置变更 + await simulateRemoteConfigChange('test.sync', 'value2'); + + // 4. 执行同步 + final syncResult = await ConfigurationSdk.instance.sync(); + + // 5. 验证同步结果 + expect(syncResult.isSuccess, true); + + final updatedConfig = await ConfigurationSdk.instance.getConfig('test.sync'); + expect(updatedConfig.value, 'value2'); + }); +}); +``` + +## 性能优化 + +### 缓存策略 +- **多级缓存**：内存 + 磁盘多级缓存 +- **智能预加载**：预测性配置预加载 +- **缓存压缩**：配置数据压缩存储 +- **缓存更新**：增量缓存更新机制 + +### 网络优化 +- **连接复用**：HTTP 连接池复用 +- **请求合并**：相关配置请求合并 +- **数据压缩**：传输数据 gzip 压缩 +- **离线模式**：离线配置访问支持 + +## 错误处理 + +### 错误类型 +```dart +abstract class ConfigurationException implements Exception { + final String message; + final String? errorCode; + final Map? details; + + const ConfigurationException(this.message, [this.errorCode, this.details]); +} + +class ConfigurationNotFoundException extends ConfigurationException { + const ConfigurationNotFoundException(String key) + : super('Configuration not found: $key', 'CONFIG_NOT_FOUND'); +} + +class ConfigurationValidationException extends ConfigurationException { + const ConfigurationValidationException(String message, Map details) + : super(message, 'VALIDATION_ERROR', details); +} + +class ConfigurationSyncException extends ConfigurationException { + const ConfigurationSyncException(String message) + : super(message, 'SYNC_ERROR'); +} +``` + +### 重试机制 +```dart +class RetryConfig { + final int maxRetries; + final Duration initialDelay; + final double backoffMultiplier; + final Duration maxDelay; + + static const RetryConfig defaultRetryConfig = RetryConfig( + maxRetries: 3, + initialDelay: Duration(seconds: 1), + backoffMultiplier: 2.0, + maxDelay: Duration(seconds: 30), + ); +} +``` + +## 安全机制 + +### 数据加密 +```dart +class ConfigurationEncryption { + // 加密配置值 + String encryptValue(String value, String key); + + // 解密配置值 + String decryptValue(String encryptedValue, String key); + + // 生成加密密钥 + String generateEncryptionKey(); + + // 验证数据完整性 + bool verifyIntegrity(String data, String signature); +} +``` + +### 访问控制 +```dart +class ConfigurationAccessControl { + // 检查读权限 + bool hasReadPermission(String key, String userId); + + // 检查写权限 + bool hasWritePermission(String key, String userId); + + // 检查删除权限 + bool hasDeletePermission(String key, String userId); + + // 获取用户权限 + List getUserPermissions(String userId); +} +``` + +## 监控和诊断 + +### 性能监控 +- **API 响应时间**：配置 API 响应时间监控 +- **缓存命中率**：配置缓存命中率统计 +- **错误率**：配置操作错误率监控 +- **同步性能**：配置同步性能指标 + +### 使用统计 +- **配置访问频率**：统计配置项访问频率 +- **热点配置**：识别热点配置项 +- **用户行为**：分析用户配置使用模式 +- **性能瓶颈**：识别性能瓶颈点 + +## 版本历史 + +### v0.2.8+5 (当前版本) +- 新增 GraphQL 查询支持 +- 优化配置同步性能 +- 支持配置数据压缩 +- 修复并发访问问题 + +### v0.2.7 +- 支持配置数据加密 +- 新增批量操作接口 +- 优化缓存机制 +- 改进错误处理 + +## 依赖关系 + +### 内部依赖 +- `basic_network`: 网络请求基础库 +- `basic_storage`: 本地存储服务 +- `basic_error`: 错误处理框架 +- `basic_logger`: 日志记录服务 + +### 外部依赖 +- `dio`: HTTP 客户端 +- `json_annotation`: JSON 序列化 +- `encrypt`: 数据加密库 +- `rxdart`: 响应式编程支持 + +## 总结 + +`clr_configuration` 作为配置服务的核心 SDK，为 OneApp 的配置管理提供了强大的底层支撑。通过标准化的 API 接口、完善的数据模型、可靠的同步机制和实时的变更通知，该 SDK 确保了配置服务的高性能、高可用和高安全性，为上层应用提供了稳定可靠的配置管理能力。 diff --git a/service_component/oneapp_companion.md b/service_component/oneapp_companion.md new file mode 100644 index 0000000..f5baecc --- /dev/null +++ b/service_component/oneapp_companion.md @@ -0,0 +1,544 @@ +# OneApp Companion - 伴侣应用模块 + +## 模块概述 + +`oneapp_companion` 是 OneApp 的伴侣应用模块，提供多设备协同功能。该模块支持手机、平板、智能手表、车载设备等多种设备间的数据同步、远程控制和设备管理，为用户提供无缝的跨设备体验。 + +## 核心功能 + +### 1. 多设备协同 +- **设备发现**：自动发现附近的伴侣设备 +- **设备配对**：安全的设备配对和认证 +- **状态同步**：设备状态实时同步 +- **会话共享**：跨设备会话状态共享 + +### 2. 数据同步 +- **实时同步**：关键数据实时同步 +- **增量同步**：高效的增量数据同步 +- **冲突解决**：数据冲突智能解决 +- **离线同步**：离线状态下的数据缓存和同步 + +### 3. 远程控制 +- **车辆控制**：远程控制车辆功能 +- **应用控制**：远程控制应用操作 +- **媒体控制**：跨设备媒体播放控制 +- **权限管理**：远程操作权限控制 + +### 4. 设备管理 +- **设备注册**：新设备注册和绑定 +- **设备监控**：设备状态监控和管理 +- **设备配置**：设备配置同步和管理 +- **设备安全**：设备安全策略和控制 + +## 技术架构 + +### 架构设计 +``` +┌─────────────────────────────────────┐ +│ 主应用设备 │ +│ (Primary Device) │ +├─────────────────────────────────────┤ +│ OneApp Companion │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 设备管理 │ 数据同步 │ 远程控制 │ │ +│ ├──────────┼──────────┼──────────┤ │ +│ │ 通信协议 │ 安全模块 │ 状态管理 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 通信协议层 │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ Bluetooth│ WiFi │ Cellular │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 伴侣设备群 │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 手机/平板│ 智能手表 │ 车载设备 │ │ +│ └──────────┴──────────┴──────────┘ │ +└─────────────────────────────────────┘ +``` + +### 核心组件 + +#### 1. 设备管理器 (DeviceManager) +```dart +class CompanionDeviceManager { + // 发现设备 + Future> discoverDevices(); + + // 配对设备 + Future pairDevice(String deviceId); + + // 获取已配对设备 + Future> getPairedDevices(); + + // 断开设备连接 + Future disconnectDevice(String deviceId); +} +``` + +#### 2. 数据同步器 (DataSynchronizer) +```dart +class CompanionDataSynchronizer { + // 同步数据到设备 + Future syncToDevice(String deviceId, SyncData data); + + // 从设备同步数据 + Future syncFromDevice(String deviceId); + + // 批量同步 + Future> batchSync(List requests); + + // 解决同步冲突 + Future resolveConflicts(List conflicts); +} +``` + +#### 3. 远程控制器 (RemoteController) +```dart +class CompanionRemoteController { + // 发送远程指令 + Future sendCommand(String deviceId, RemoteCommand command); + + // 批量发送指令 + Future> sendBatchCommands(String deviceId, List commands); + + // 监听远程指令 + Stream listenForCommands(); + + // 响应远程指令 + Future respondToCommand(RemoteCommand command); +} +``` + +#### 4. 连接管理器 (ConnectionManager) +```dart +class CompanionConnectionManager { + // 建立连接 + Future establishConnection(CompanionDevice device); + + // 维持连接 + Future maintainConnection(String deviceId); + + // 监控连接状态 + Stream monitorConnection(String deviceId); + + // 重连设备 + Future reconnectDevice(String deviceId); +} +``` + +## 数据模型 + +### 设备模型 +```dart +class CompanionDevice { + final String id; + final String name; + final DeviceType type; + final String model; + final String version; + final DeviceStatus status; + final DateTime lastSeen; + final Map capabilities; + final SecurityInfo security; + final ConnectionInfo connection; +} + +enum DeviceType { + smartphone, // 智能手机 + tablet, // 平板电脑 + smartwatch, // 智能手表 + carDisplay, // 车载显示器 + desktop, // 桌面应用 + other // 其他设备 +} + +enum DeviceStatus { + online, // 在线 + offline, // 离线 + connecting, // 连接中 + syncing, // 同步中 + error // 错误状态 +} +``` + +### 同步数据模型 +```dart +class SyncData { + final String id; + final SyncDataType type; + final Map data; + final DateTime timestamp; + final String version; + final List targetDevices; + final SyncPriority priority; +} + +enum SyncDataType { + userPreferences, // 用户偏好 + vehicleStatus, // 车辆状态 + mediaPlaylist, // 媒体播放列表 + navigationRoute, // 导航路线 + chargingSession, // 充电会话 + configuration // 配置信息 +} + +enum SyncPriority { + low, // 低优先级 + normal, // 普通优先级 + high, // 高优先级 + critical // 关键优先级 +} +``` + +### 远程指令模型 +```dart +class RemoteCommand { + final String id; + final CommandType type; + final Map parameters; + final String sourceDeviceId; + final String targetDeviceId; + final DateTime timestamp; + final bool requiresConfirmation; + final Duration timeout; +} + +enum CommandType { + vehicleControl, // 车辆控制 + mediaControl, // 媒体控制 + navigationControl, // 导航控制 + appControl, // 应用控制 + systemControl, // 系统控制 + dataRequest // 数据请求 +} +``` + +## API 接口 + +### 设备管理接口 +```dart +abstract class CompanionDeviceService { + // 发现附近设备 + Future>> discoverNearbyDevices(); + + // 配对设备 + Future> pairDevice(PairDeviceRequest request); + + // 获取设备列表 + Future>> getDeviceList(); + + // 更新设备信息 + Future> updateDeviceInfo(UpdateDeviceRequest request); +} +``` + +### 数据同步接口 +```dart +abstract class CompanionSyncService { + // 同步数据 + Future> syncData(SyncDataRequest request); + + // 获取同步状态 + Future> getSyncStatus(String deviceId); + + // 解决同步冲突 + Future> resolveConflict(ConflictResolutionRequest request); +} +``` + +### 远程控制接口 +```dart +abstract class CompanionRemoteService { + // 发送远程命令 + Future> sendRemoteCommand(RemoteCommandRequest request); + + // 获取命令状态 + Future> getCommandStatus(String commandId); + + // 取消远程命令 + Future> cancelCommand(String commandId); +} +``` + +## 配置管理 + +### 伴侣应用配置 +```dart +class CompanionConfig { + final bool autoDiscovery; + final Duration discoveryInterval; + final int maxPairedDevices; + final bool enableRemoteControl; + final List enabledSyncTypes; + final SecurityLevel securityLevel; + + static const CompanionConfig defaultConfig = CompanionConfig( + autoDiscovery: true, + discoveryInterval: Duration(minutes: 5), + maxPairedDevices: 10, + enableRemoteControl: true, + enabledSyncTypes: [ + SyncDataType.userPreferences, + SyncDataType.vehicleStatus, + SyncDataType.mediaPlaylist, + ], + securityLevel: SecurityLevel.high, + ); +} +``` + +### 同步配置 +```dart +class SyncConfig { + final bool enableRealTimeSync; + final Duration syncInterval; + final int maxSyncRetries; + final bool enableIncrementalSync; + final Map typeSettings; + + static const SyncConfig defaultSyncConfig = SyncConfig( + enableRealTimeSync: true, + syncInterval: Duration(minutes: 1), + maxSyncRetries: 3, + enableIncrementalSync: true, + typeSettings: { + SyncDataType.vehicleStatus: SyncSettings(priority: SyncPriority.high), + SyncDataType.userPreferences: SyncSettings(priority: SyncPriority.normal), + }, + ); +} +``` + +## 使用示例 + +### 设备发现和配对 +```dart +// 初始化伴侣应用管理器 +final companionManager = CompanionDeviceManager.instance; +await companionManager.initialize(CompanionConfig.defaultConfig); + +// 发现附近设备 +final nearbyDevices = await companionManager.discoverDevices(); + +for (final device in nearbyDevices) { + print('发现设备: ${device.name} (${device.type})'); + + // 配对兼容设备 + if (device.capabilities.containsKey('oneapp_support')) { + final paired = await companionManager.pairDevice(device.id); + if (paired) { + print('设备配对成功: ${device.name}'); + } + } +} + +// 监听设备状态变化 +companionManager.onDeviceStatusChanged.listen((device) { + print('设备状态变更: ${device.name} -> ${device.status}'); +}); +``` + +### 数据同步 +```dart +// 同步用户偏好到所有设备 +final userPreferences = await getUserPreferences(); +final syncData = SyncData( + id: 'user_prefs_${DateTime.now().millisecondsSinceEpoch}', + type: SyncDataType.userPreferences, + data: userPreferences.toJson(), + timestamp: DateTime.now(), + priority: SyncPriority.normal, +); + +final pairedDevices = await companionManager.getPairedDevices(); +for (final device in pairedDevices) { + if (device.status == DeviceStatus.online) { + final result = await CompanionDataSynchronizer.instance.syncToDevice(device.id, syncData); + print('同步到 ${device.name}: ${result.isSuccess}'); + } +} + +// 监听同步状态 +CompanionDataSynchronizer.instance.onSyncProgress.listen((progress) { + print('同步进度: ${progress.percentage}%'); +}); +``` + +### 远程控制 +```dart +// 远程启动车辆 +final startEngineCommand = RemoteCommand( + id: 'start_engine_${DateTime.now().millisecondsSinceEpoch}', + type: CommandType.vehicleControl, + parameters: { + 'action': 'start_engine', + 'duration': 300, // 5分钟 + }, + sourceDeviceId: 'smartphone_001', + targetDeviceId: 'car_display_001', + requiresConfirmation: true, + timeout: Duration(seconds: 30), +); + +final result = await CompanionRemoteController.instance.sendCommand( + 'car_display_001', + startEngineCommand, +); + +if (result.isSuccess) { + print('远程启动指令发送成功'); +} else { + print('远程启动失败: ${result.error}'); +} + +// 监听远程指令 +CompanionRemoteController.instance.listenForCommands().listen((command) { + print('收到远程指令: ${command.type}'); + // 处理远程指令 + handleRemoteCommand(command); +}); +``` + +### 连接管理 +```dart +// 监控设备连接状态 +final connectionManager = CompanionConnectionManager.instance; + +for (final device in pairedDevices) { + connectionManager.monitorConnection(device.id).listen((status) { + switch (status.state) { + case ConnectionState.connected: + print('${device.name} 已连接'); + break; + case ConnectionState.disconnected: + print('${device.name} 已断开，尝试重连...'); + connectionManager.reconnectDevice(device.id); + break; + case ConnectionState.error: + print('${device.name} 连接错误: ${status.error}'); + break; + } + }); +} +``` + +## 测试策略 + +### 单元测试 +```dart +group('CompanionDevice Tests', () { + test('should discover nearby devices', () async { + // Given + final deviceManager = CompanionDeviceManager(); + + // When + final devices = await deviceManager.discoverDevices(); + + // Then + expect(devices, isNotEmpty); + expect(devices.first.type, isA()); + }); + + test('should sync data successfully', () async { + // Given + final synchronizer = CompanionDataSynchronizer(); + final syncData = SyncData( + id: 'test_sync', + type: SyncDataType.userPreferences, + data: {'theme': 'dark'}, + timestamp: DateTime.now(), + priority: SyncPriority.normal, + ); + + // When + final result = await synchronizer.syncToDevice('test_device', syncData); + + // Then + expect(result.isSuccess, true); + }); +}); +``` + +### 集成测试 +```dart +group('Companion Integration Tests', () { + testWidgets('device pairing flow', (tester) async { + // 1. 启动设备发现 + await CompanionDeviceManager.instance.startDiscovery(); + + // 2. 模拟发现设备 + final mockDevice = createMockDevice(); + await simulateDeviceDiscovered(mockDevice); + + // 3. 执行配对 + final paired = await CompanionDeviceManager.instance.pairDevice(mockDevice.id); + + // 4. 验证配对结果 + expect(paired, true); + + final pairedDevices = await CompanionDeviceManager.instance.getPairedDevices(); + expect(pairedDevices, contains(mockDevice)); + }); +}); +``` + +## 性能优化 + +### 连接优化 +- **连接池**：设备连接池管理 +- **心跳机制**：定期心跳保持连接 +- **重连策略**：智能重连机制 +- **负载均衡**：多设备负载均衡 + +### 同步优化 +- **增量同步**：只同步变化的数据 +- **压缩传输**：数据压缩减少传输量 +- **批量操作**：批量同步提高效率 +- **优先级队列**：按优先级处理同步任务 + +## 安全考虑 + +### 设备安全 +- **设备认证**：设备身份认证和授权 +- **加密通信**：端到端加密通信 +- **权限控制**：细粒度权限控制 +- **安全审计**：操作安全审计日志 + +### 数据安全 +- **数据加密**：敏感数据加密存储和传输 +- **访问控制**：基于角色的数据访问控制 +- **数据完整性**：数据完整性验证 +- **隐私保护**：用户隐私数据保护 + +## 版本历史 + +### v0.0.7 (当前版本) +- 新增智能手表支持 +- 优化设备发现性能 +- 支持批量数据同步 +- 修复连接稳定性问题 + +### v0.0.6 +- 支持车载设备连接 +- 新增远程控制功能 +- 优化同步机制 +- 改进设备管理界面 + +## 依赖关系 + +### 内部依赖 +- `basic_platform`: 平台抽象层 +- `basic_network`: 网络通信服务 +- `basic_storage`: 本地存储服务 +- `basic_security`: 安全服务 + +### 外部依赖 +- `nearby_connections`: 设备发现和连接 +- `encrypt`: 数据加密 +- `rxdart`: 响应式编程 +- `shared_preferences`: 配置存储 + +## 总结 + +`oneapp_companion` 模块为 OneApp 提供了完整的多设备协同解决方案。通过设备发现、数据同步、远程控制和连接管理等功能，该模块实现了跨设备的无缝体验，让用户能够在不同设备间自由切换，享受一致的应用体验和便捷的远程控制功能。 diff --git a/service_component/oneapp_popup.md b/service_component/oneapp_popup.md new file mode 100644 index 0000000..a65367d --- /dev/null +++ b/service_component/oneapp_popup.md @@ -0,0 +1,611 @@ +# OneApp Popup - 弹窗管理模块 + +## 模块概述 + +`oneapp_popup` 是 OneApp 的统一弹窗管理模块，提供了全局弹窗管理、优先级控制、样式定制和生命周期管理等功能。该模块确保应用中所有弹窗的一致性体验，避免弹窗冲突，并提供灵活的弹窗展示策略。 + +## 核心功能 + +### 1. 统一弹窗管理 +- **全局队列**：统一管理所有弹窗显示队列 +- **弹窗注册**：注册和管理不同类型的弹窗 +- **显示控制**：控制弹窗的显示和隐藏 +- **状态管理**：跟踪弹窗的显示状态 + +### 2. 弹窗优先级控制 +- **优先级排序**：按优先级排序弹窗显示顺序 +- **抢占机制**：高优先级弹窗抢占显示 +- **队列管理**：智能管理弹窗等待队列 +- **冲突解决**：解决弹窗显示冲突 + +### 3. 弹窗样式定制 +- **主题适配**：自动适配应用主题 +- **样式继承**：支持样式继承和覆盖 +- **动画效果**：丰富的弹窗动画效果 +- **响应式设计**：适配不同屏幕尺寸 + +### 4. 弹窗生命周期 +- **生命周期钩子**：完整的生命周期回调 +- **自动销毁**：弹窗自动销毁机制 +- **内存管理**：防止内存泄漏 +- **状态恢复**：应用重启后状态恢复 + +## 技术架构 + +### 架构设计 +``` +┌─────────────────────────────────────┐ +│ 应用界面层 │ +│ (Application UI) │ +├─────────────────────────────────────┤ +│ OneApp Popup │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 弹窗管理 │ 队列控制 │ 样式系统 │ │ +│ ├──────────┼──────────┼──────────┤ │ +│ │ 生命周期 │ 事件系统 │ 动画引擎 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ UI 渲染层 │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ Overlay │ Dialog │ BottomSheet │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ Flutter Framework │ +│ (Widget System) │ +└─────────────────────────────────────┘ +``` + +### 核心组件 + +#### 1. 弹窗管理器 (PopupManager) +```dart +class PopupManager { + // 显示弹窗 + Future show(Popup popup); + + // 隐藏弹窗 + Future hide(String popupId); + + // 隐藏所有弹窗 + Future hideAll(); + + // 获取当前弹窗 + Popup? getCurrentPopup(); + + // 获取弹窗队列 + List getPopupQueue(); +} +``` + +#### 2. 弹窗队列控制器 (PopupQueueController) +```dart +class PopupQueueController { + // 添加弹窗到队列 + void enqueue(Popup popup); + + // 从队列移除弹窗 + bool dequeue(String popupId); + + // 按优先级排序队列 + void sortByPriority(); + + // 处理下一个弹窗 + Future processNext(); +} +``` + +#### 3. 弹窗样式管理器 (PopupStyleManager) +```dart +class PopupStyleManager { + // 应用弹窗主题 + PopupTheme applyTheme(PopupStyle style, AppTheme theme); + + // 创建弹窗样式 + PopupStyle createStyle(PopupType type); + + // 自定义样式 + PopupStyle customizeStyle(PopupStyle base, StyleOverrides overrides); + + // 获取默认样式 + PopupStyle getDefaultStyle(PopupType type); +} +``` + +#### 4. 弹窗生命周期管理器 (PopupLifecycleManager) +```dart +class PopupLifecycleManager { + // 注册生命周期监听器 + void registerLifecycleListener(String popupId, PopupLifecycleListener listener); + + // 触发生命周期事件 + void triggerLifecycleEvent(String popupId, PopupLifecycleEvent event); + + // 清理弹窗资源 + void cleanupPopup(String popupId); + + // 恢复弹窗状态 + Future restorePopupState(); +} +``` + +## 数据模型 + +### 弹窗模型 +```dart +class Popup { + final String id; + final PopupType type; + final Widget content; + final PopupPriority priority; + final PopupStyle? style; + final PopupOptions options; + final Map data; + final DateTime createdAt; + final Duration? autoHideDelay; + final List actions; +} + +enum PopupType { + dialog, // 对话框 + bottomSheet, // 底部弹窗 + toast, // 吐司消息 + overlay, // 覆盖层 + modal, // 模态框 + banner, // 横幅 + snackbar // 快捷消息 +} + +enum PopupPriority { + low, // 低优先级 + normal, // 普通优先级 + high, // 高优先级 + critical, // 关键优先级 + emergency // 紧急优先级 +} +``` + +### 弹窗样式模型 +```dart +class PopupStyle { + final Color? backgroundColor; + final BorderRadius? borderRadius; + final EdgeInsets? padding; + final EdgeInsets? margin; + final BoxShadow? shadow; + final TextStyle? textStyle; + final PopupAnimation? animation; + final Alignment? alignment; + final Size? size; + final bool? barrierDismissible; +} + +class PopupAnimation { + final AnimationType type; + final Duration duration; + final Curve curve; + final Offset? slideDirection; + final double? scaleStart; +} + +enum AnimationType { + fade, // 淡入淡出 + slide, // 滑动 + scale, // 缩放 + rotate, // 旋转 + bounce, // 弹跳 + none // 无动画 +} +``` + +### 弹窗选项模型 +```dart +class PopupOptions { + final bool barrierDismissible; + final Color? barrierColor; + final String? barrierLabel; + final bool useRootNavigator; + final RouteSettings? routeSettings; + final Offset? anchorPoint; + final PopupGravity gravity; + final Duration? showDuration; + final Duration? hideDuration; +} + +enum PopupGravity { + center, // 居中 + top, // 顶部 + bottom, // 底部 + left, // 左侧 + right, // 右侧 + topLeft, // 左上 + topRight, // 右上 + bottomLeft, // 左下 + bottomRight // 右下 +} +``` + +## API 接口 + +### 弹窗管理接口 +```dart +abstract class PopupService { + // 显示弹窗 + Future> showPopup(ShowPopupRequest request); + + // 隐藏弹窗 + Future> hidePopup(HidePopupRequest request); + + // 获取弹窗状态 + Future> getPopupStatus(String popupId); + + // 清理弹窗 + Future> clearPopups(ClearPopupsRequest request); +} +``` + +### 弹窗样式接口 +```dart +abstract class PopupStyleService { + // 获取弹窗主题 + Future> getPopupTheme(String themeId); + + // 更新弹窗样式 + Future> updatePopupStyle(UpdateStyleRequest request); + + // 获取样式模板 + Future>> getStyleTemplates(); +} +``` + +## 配置管理 + +### 弹窗配置 +```dart +class PopupConfig { + final int maxConcurrentPopups; + final Duration defaultAnimationDuration; + final bool enableGlobalQueue; + final bool autoHideOnAppBackground; + final Map typeConfigs; + final PopupTheme defaultTheme; + + static const PopupConfig defaultConfig = PopupConfig( + maxConcurrentPopups: 3, + defaultAnimationDuration: Duration(milliseconds: 300), + enableGlobalQueue: true, + autoHideOnAppBackground: true, + typeConfigs: { + PopupType.dialog: PopupTypeConfig( + maxInstances: 1, + defaultPriority: PopupPriority.high, + ), + PopupType.toast: PopupTypeConfig( + maxInstances: 5, + defaultPriority: PopupPriority.low, + ), + }, + defaultTheme: PopupTheme.defaultTheme, + ); +} +``` + +### 主题配置 +```dart +class PopupTheme { + final PopupStyle dialogStyle; + final PopupStyle toastStyle; + final PopupStyle bottomSheetStyle; + final PopupStyle overlayStyle; + final Map customStyles; + + static const PopupTheme defaultTheme = PopupTheme( + dialogStyle: PopupStyle( + backgroundColor: Colors.white, + borderRadius: BorderRadius.circular(8.0), + padding: EdgeInsets.all(16.0), + animation: PopupAnimation( + type: AnimationType.scale, + duration: Duration(milliseconds: 300), + ), + ), + toastStyle: PopupStyle( + backgroundColor: Colors.black87, + borderRadius: BorderRadius.circular(24.0), + padding: EdgeInsets.symmetric(horizontal: 16.0, vertical: 8.0), + animation: PopupAnimation( + type: AnimationType.slide, + duration: Duration(milliseconds: 200), + ), + ), + ); +} +``` + +## 使用示例 + +### 基本弹窗显示 +```dart +// 显示对话框 +final result = await PopupManager.instance.show( + Popup( + id: 'confirm_dialog', + type: PopupType.dialog, + priority: PopupPriority.high, + content: AlertDialog( + title: Text('确认操作'), + content: Text('是否确认执行此操作？'), + actions: [ + TextButton( + onPressed: () => Navigator.of(context).pop(false), + child: Text('取消'), + ), + TextButton( + onPressed: () => Navigator.of(context).pop(true), + child: Text('确认'), + ), + ], + ), + ), +); + +if (result == true) { + print('用户确认操作'); +} +``` + +### 吐司消息 +```dart +// 显示成功消息 +PopupManager.instance.show( + Popup( + id: 'success_toast', + type: PopupType.toast, + priority: PopupPriority.normal, + content: Container( + padding: EdgeInsets.all(16.0), + decoration: BoxDecoration( + color: Colors.green, + borderRadius: BorderRadius.circular(8.0), + ), + child: Row( + mainAxisSize: MainAxisSize.min, + children: [ + Icon(Icons.check, color: Colors.white), + SizedBox(width: 8.0), + Text('操作成功', style: TextStyle(color: Colors.white)), + ], + ), + ), + options: PopupOptions( + gravity: PopupGravity.top, + barrierDismissible: false, + ), + autoHideDelay: Duration(seconds: 3), + ), +); +``` + +### 底部弹窗 +```dart +// 显示底部选择弹窗 +final selectedOption = await PopupManager.instance.show( + Popup( + id: 'bottom_sheet_options', + type: PopupType.bottomSheet, + priority: PopupPriority.normal, + content: Column( + mainAxisSize: MainAxisSize.min, + children: [ + ListTile( + leading: Icon(Icons.camera), + title: Text('拍照'), + onTap: () => Navigator.of(context).pop('camera'), + ), + ListTile( + leading: Icon(Icons.photo_library), + title: Text('从相册选择'), + onTap: () => Navigator.of(context).pop('gallery'), + ), + ListTile( + leading: Icon(Icons.cancel), + title: Text('取消'), + onTap: () => Navigator.of(context).pop(null), + ), + ], + ), + style: PopupStyle( + backgroundColor: Colors.white, + borderRadius: BorderRadius.vertical(top: Radius.circular(16.0)), + ), + ), +); + +print('用户选择: $selectedOption'); +``` + +### 自定义弹窗样式 +```dart +// 创建自定义样式弹窗 +final customStyle = PopupStyle( + backgroundColor: Colors.blue.shade50, + borderRadius: BorderRadius.circular(12.0), + padding: EdgeInsets.all(20.0), + shadow: BoxShadow( + color: Colors.black26, + blurRadius: 10.0, + offset: Offset(0, 4), + ), + animation: PopupAnimation( + type: AnimationType.bounce, + duration: Duration(milliseconds: 500), + curve: Curves.elasticOut, + ), +); + +PopupManager.instance.show( + Popup( + id: 'custom_popup', + type: PopupType.modal, + priority: PopupPriority.high, + style: customStyle, + content: Container( + width: 300, + child: Column( + mainAxisSize: MainAxisSize.min, + children: [ + Icon(Icons.info, size: 48, color: Colors.blue), + SizedBox(height: 16), + Text('自定义弹窗', style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)), + SizedBox(height: 8), + Text('这是一个自定义样式的弹窗示例'), + SizedBox(height: 16), + ElevatedButton( + onPressed: () => PopupManager.instance.hide('custom_popup'), + child: Text('关闭'), + ), + ], + ), + ), + ), +); +``` + +### 弹窗队列管理 +```dart +// 批量添加弹窗到队列 +final popups = [ + Popup( + id: 'popup_1', + type: PopupType.toast, + priority: PopupPriority.low, + content: Text('消息1'), + ), + Popup( + id: 'popup_2', + type: PopupType.dialog, + priority: PopupPriority.high, + content: Text('重要消息'), + ), + Popup( + id: 'popup_3', + type: PopupType.toast, + priority: PopupPriority.normal, + content: Text('消息3'), + ), +]; + +// 按优先级添加到队列 +for (final popup in popups) { + PopupManager.instance.enqueue(popup); +} + +// 监听弹窗队列变化 +PopupManager.instance.onQueueChanged.listen((queue) { + print('当前队列长度: ${queue.length}'); +}); +``` + +## 测试策略 + +### 单元测试 +```dart +group('PopupManager Tests', () { + test('should show popup successfully', () async { + // Given + final popupManager = PopupManager(); + final popup = Popup( + id: 'test_popup', + type: PopupType.dialog, + content: Text('Test'), + ); + + // When + final result = await popupManager.show(popup); + + // Then + expect(popupManager.getCurrentPopup()?.id, 'test_popup'); + }); + + test('should manage popup queue by priority', () { + // Given + final queueController = PopupQueueController(); + final lowPriorityPopup = Popup(id: 'low', priority: PopupPriority.low); + final highPriorityPopup = Popup(id: 'high', priority: PopupPriority.high); + + // When + queueController.enqueue(lowPriorityPopup); + queueController.enqueue(highPriorityPopup); + queueController.sortByPriority(); + + // Then + final queue = queueController.getQueue(); + expect(queue.first.id, 'high'); + expect(queue.last.id, 'low'); + }); +}); +``` + +### 集成测试 +```dart +group('Popup Integration Tests', () { + testWidgets('popup display flow', (tester) async { + // 1. 显示弹窗 + await PopupManager.instance.show(testPopup); + await tester.pumpAndSettle(); + + // 2. 验证弹窗显示 + expect(find.byKey(Key('test_popup')), findsOneWidget); + + // 3. 点击关闭按钮 + await tester.tap(find.byKey(Key('close_button'))); + await tester.pumpAndSettle(); + + // 4. 验证弹窗关闭 + expect(find.byKey(Key('test_popup')), findsNothing); + }); +}); +``` + +## 性能优化 + +### 渲染优化 +- **懒加载**：弹窗内容懒加载 +- **复用机制**：弹窗组件复用 +- **动画优化**：高效的动画实现 +- **内存管理**：及时释放弹窗资源 + +### 队列优化 +- **智能调度**：智能弹窗调度算法 +- **优先级合并**：相同优先级弹窗合并 +- **批量处理**：批量处理弹窗队列 +- **负载控制**：控制同时显示的弹窗数量 + +## 版本历史 + +### v0.3.1+2 (当前版本) +- 新增弹窗主题系统 +- 优化动画性能 +- 支持自定义弹窗样式 +- 修复内存泄漏问题 + +### v0.3.0 +- 重构弹窗管理架构 +- 新增优先级队列系统 +- 支持多种弹窗类型 +- 改进生命周期管理 + +## 依赖关系 + +### 内部依赖 +- `basic_theme`: 主题管理系统 +- `basic_utils`: 工具类库 +- `basic_logger`: 日志记录 + +### 外部依赖 +- `flutter/material`: Material 设计组件 +- `flutter/cupertino`: iOS 风格组件 +- `rxdart`: 响应式编程支持 + +## 总结 + +`oneapp_popup` 模块为 OneApp 提供了完整的弹窗管理解决方案。通过统一的弹窗管理、智能的优先级控制、灵活的样式定制和完善的生命周期管理，该模块确保了应用中所有弹窗的一致性体验，提高了用户界面的专业性和用户体验的流畅性。 diff --git a/setting/README.md b/setting/README.md new file mode 100644 index 0000000..6951dd5 --- /dev/null +++ b/setting/README.md @@ -0,0 +1,803 @@ +# OneApp Setting - 应用设置模块文档 + +## 模块概述 + +`app_setting` 是 OneApp 的应用设置管理模块，提供用户偏好设置、系统配置、通知管理、隐私设置等功能。该模块采用模块化设计，支持动态配置更新和多语言切换，为用户提供个性化的应用体验。 + +### 基本信息 +- **模块名称**: app_setting +- **版本**: 0.2.26 +- **仓库**: https://gitlab-rd0.maezia.com/dssomobile/oneapp/dssomobile-oneapp-app-setting +- **Flutter 版本**: >=2.10.5 +- **Dart 版本**: >=2.16.2 <4.0.0 + +## 目录结构 + +``` +app_setting/ +├── lib/ +│ ├── app_setting.dart # 主导出文件 +│ ├── route_dp.dart # 路由配置 +│ ├── route_export.dart # 路由导出 +│ ├── generated/ # 代码生成文件 +│ ├── l10n/ # 国际化文件 +│ └── src/ # 源代码目录 +│ ├── pages/ # 设置页面 +│ ├── widgets/ # 设置组件 +│ ├── models/ # 数据模型 +│ ├── services/ # 服务层 +│ └── constants/ # 常量定义 +├── assets/ # 静态资源 +├── set_notification_uml.puml # 通知设置 UML 图 +├── set_notification_uml.svg # 通知设置 UML 图 +├── pubspec.yaml # 依赖配置 +└── README.md # 项目说明 +``` + +## 核心功能模块 + +### 1. 用户偏好设置 + +#### 个人信息设置 +```dart +// 个人信息设置服务 +class ProfileSettingsService { + final SettingRepository _settingRepository; + final StorageService _storageService; + + ProfileSettingsService(this._settingRepository, this._storageService); + + // 获取用户个人信息设置 + Future> getUserProfileSettings() async { + try { + final settings = await _settingRepository.getUserProfileSettings(); + return Right(settings); + } catch (e) { + return Left(SettingFailure.loadFailed(e.toString())); + } + } + + // 更新用户头像 + Future> updateUserAvatar(String avatarUrl) async { + try { + await _settingRepository.updateUserAvatar(avatarUrl); + await _storageService.setString('user_avatar', avatarUrl); + return Right(unit); + } catch (e) { + return Left(SettingFailure.updateFailed(e.toString())); + } + } + + // 更新用户昵称 + Future> updateUserNickname(String nickname) async { + try { + await _settingRepository.updateUserNickname(nickname); + await _storageService.setString('user_nickname', nickname); + return Right(unit); + } catch (e) { + return Left(SettingFailure.updateFailed(e.toString())); + } + } +} +``` + +#### 应用偏好设置 +```dart +// 应用偏好设置模型 +class AppPreferenceSettings { + final String language; + final String theme; + final bool enableDarkMode; + final bool enableAutoStart; + final bool enableBackgroundRefresh; + final double fontSize; + final bool enableHapticFeedback; + final bool enableSoundEffects; + + const AppPreferenceSettings({ + required this.language, + required this.theme, + required this.enableDarkMode, + required this.enableAutoStart, + required this.enableBackgroundRefresh, + required this.fontSize, + required this.enableHapticFeedback, + required this.enableSoundEffects, + }); + + factory AppPreferenceSettings.fromJson(Map json) { + return AppPreferenceSettings( + language: json['language'] ?? 'zh-CN', + theme: json['theme'] ?? 'system', + enableDarkMode: json['enable_dark_mode'] ?? false, + enableAutoStart: json['enable_auto_start'] ?? true, + enableBackgroundRefresh: json['enable_background_refresh'] ?? true, + fontSize: (json['font_size'] ?? 16.0).toDouble(), + enableHapticFeedback: json['enable_haptic_feedback'] ?? true, + enableSoundEffects: json['enable_sound_effects'] ?? true, + ); + } +} + +// 应用偏好设置服务 +class AppPreferenceService { + final StorageService _storageService; + + AppPreferenceService(this._storageService); + + // 获取应用偏好设置 + Future getAppPreferences() async { + final json = await _storageService.getObject('app_preferences') ?? {}; + return AppPreferenceSettings.fromJson(json); + } + + // 保存应用偏好设置 + Future saveAppPreferences(AppPreferenceSettings settings) async { + await _storageService.setObject('app_preferences', settings.toJson()); + + // 通知其他模块设置变更 + _notifySettingsChanged(settings); + } + + // 更新语言设置 + Future updateLanguage(String language) async { + final settings = await getAppPreferences(); + final updatedSettings = settings.copyWith(language: language); + await saveAppPreferences(updatedSettings); + } + + // 更新主题设置 + Future updateTheme(String theme, bool enableDarkMode) async { + final settings = await getAppPreferences(); + final updatedSettings = settings.copyWith( + theme: theme, + enableDarkMode: enableDarkMode, + ); + await saveAppPreferences(updatedSettings); + } +} +``` + +### 2. 通知设置管理 + +#### 通知偏好配置 +```dart +// 通知设置模型 +class NotificationSettings { + final bool enablePushNotification; + final bool enableSoundNotification; + final bool enableVibrationNotification; + final bool enableLEDNotification; + final NotificationTime quietHours; + final Map typeSettings; + + const NotificationSettings({ + required this.enablePushNotification, + required this.enableSoundNotification, + required this.enableVibrationNotification, + required this.enableLEDNotification, + required this.quietHours, + required this.typeSettings, + }); + + factory NotificationSettings.defaultSettings() { + return NotificationSettings( + enablePushNotification: true, + enableSoundNotification: true, + enableVibrationNotification: true, + enableLEDNotification: false, + quietHours: NotificationTime.defaultQuietHours(), + typeSettings: { + NotificationType.system: true, + NotificationType.charging: true, + NotificationType.maintenance: true, + NotificationType.security: true, + NotificationType.social: false, + NotificationType.marketing: false, + }, + ); + } +} + +// 通知设置服务 +class NotificationSettingsService { + final SettingRepository _settingRepository; + final PushNotificationService _pushService; + + NotificationSettingsService(this._settingRepository, this._pushService); + + // 获取通知设置 + Future> getNotificationSettings() async { + try { + final settings = await _settingRepository.getNotificationSettings(); + return Right(settings); + } catch (e) { + return Left(SettingFailure.loadFailed(e.toString())); + } + } + + // 更新通知设置 + Future> updateNotificationSettings( + NotificationSettings settings, + ) async { + try { + await _settingRepository.updateNotificationSettings(settings); + + // 同步到推送服务 + await _syncNotificationSettingsToPushService(settings); + + return Right(unit); + } catch (e) { + return Left(SettingFailure.updateFailed(e.toString())); + } + } + + // 切换通知类型开关 + Future> toggleNotificationType( + NotificationType type, + bool enabled, + ) async { + try { + final currentSettings = await getNotificationSettings(); + return currentSettings.fold( + (failure) => Left(failure), + (settings) async { + final updatedTypeSettings = Map.from( + settings.typeSettings, + ); + updatedTypeSettings[type] = enabled; + + final updatedSettings = settings.copyWith( + typeSettings: updatedTypeSettings, + ); + + return await updateNotificationSettings(updatedSettings); + }, + ); + } catch (e) { + return Left(SettingFailure.updateFailed(e.toString())); + } + } +} +``` + +### 3. 隐私安全设置 + +#### 隐私设置管理 +```dart +// 隐私设置模型 +class PrivacySettings { + final bool enableLocationSharing; + final bool enableDataAnalytics; + final bool enablePersonalizedAds; + final bool enableContactSync; + final bool enableBiometricAuth; + final bool enableAutoLock; + final Duration autoLockDuration; + final List blockedContacts; + + const PrivacySettings({ + required this.enableLocationSharing, + required this.enableDataAnalytics, + required this.enablePersonalizedAds, + required this.enableContactSync, + required this.enableBiometricAuth, + required this.enableAutoLock, + required this.autoLockDuration, + required this.blockedContacts, + }); + + factory PrivacySettings.defaultSettings() { + return PrivacySettings( + enableLocationSharing: true, + enableDataAnalytics: false, + enablePersonalizedAds: false, + enableContactSync: false, + enableBiometricAuth: false, + enableAutoLock: true, + autoLockDuration: Duration(minutes: 5), + blockedContacts: [], + ); + } +} + +// 隐私设置服务 +class PrivacySettingsService { + final SettingRepository _settingRepository; + final ConsentService _consentService; + final BiometricService _biometricService; + + PrivacySettingsService( + this._settingRepository, + this._consentService, + this._biometricService, + ); + + // 获取隐私设置 + Future> getPrivacySettings() async { + try { + final settings = await _settingRepository.getPrivacySettings(); + return Right(settings); + } catch (e) { + return Left(SettingFailure.loadFailed(e.toString())); + } + } + + // 更新隐私设置 + Future> updatePrivacySettings( + PrivacySettings settings, + ) async { + try { + // 检查权限变更 + await _handlePrivacyPermissionChanges(settings); + + await _settingRepository.updatePrivacySettings(settings); + return Right(unit); + } catch (e) { + return Left(SettingFailure.updateFailed(e.toString())); + } + } + + // 启用生物识别认证 + Future> enableBiometricAuth() async { + try { + // 检查生物识别可用性 + final isAvailable = await _biometricService.isAvailable(); + if (!isAvailable) { + return Left(SettingFailure.biometricNotAvailable()); + } + + // 验证生物识别 + final isAuthenticated = await _biometricService.authenticate( + localizedReason: '请验证生物识别以启用此功能', + ); + + if (!isAuthenticated) { + return Left(SettingFailure.biometricAuthFailed()); + } + + // 更新设置 + final currentSettings = await getPrivacySettings(); + return currentSettings.fold( + (failure) => Left(failure), + (settings) async { + final updatedSettings = settings.copyWith( + enableBiometricAuth: true, + ); + return await updatePrivacySettings(updatedSettings); + }, + ); + } catch (e) { + return Left(SettingFailure.updateFailed(e.toString())); + } + } +} +``` + +### 4. 系统设置 + +#### 系统信息与设置 +```dart +// 系统设置服务 +class SystemSettingsService { + final PackageInfo _packageInfo; + final StorageService _storageService; + final NetworkService _networkService; + + SystemSettingsService( + this._packageInfo, + this._storageService, + this._networkService, + ); + + // 获取应用信息 + AppInfo getAppInfo() { + return AppInfo( + appName: _packageInfo.appName, + packageName: _packageInfo.packageName, + version: _packageInfo.version, + buildNumber: _packageInfo.buildNumber, + ); + } + + // 获取存储信息 + Future getStorageInfo() async { + final cacheSize = await _getCacheSize(); + final userData = await _getUserDataSize(); + final tempFiles = await _getTempFilesSize(); + + return StorageInfo( + cacheSize: cacheSize, + userDataSize: userData, + tempFilesSize: tempFiles, + totalUsage: cacheSize + userData + tempFiles, + ); + } + + // 清理缓存 + Future> clearCache() async { + try { + // 清理网络缓存 + await _networkService.clearCache(); + + // 清理图片缓存 + await _clearImageCache(); + + // 清理临时文件 + await _clearTempFiles(); + + return Right(unit); + } catch (e) { + return Left(SettingFailure.clearCacheFailed(e.toString())); + } + } + + // 检查更新 + Future> checkForUpdates() async { + try { + final updateInfo = await _networkService.checkAppUpdate( + currentVersion: _packageInfo.version, + ); + return Right(updateInfo); + } catch (e) { + return Left(SettingFailure.updateCheckFailed(e.toString())); + } + } + + // 导出用户数据 + Future> exportUserData() async { + try { + final userData = await _collectUserData(); + final exportPath = await _saveDataToFile(userData); + return Right(exportPath); + } catch (e) { + return Left(SettingFailure.exportFailed(e.toString())); + } + } +} +``` + +## 页面组件设计 + +### 主设置页面 +```dart +// 主设置页面 +class SettingsMainPage extends StatefulWidget { + @override + _SettingsMainPageState createState() => _SettingsMainPageState(); +} + +class _SettingsMainPageState extends State { + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar( + title: Text('设置'), + ), + body: ListView( + children: [ + _buildUserSection(), + _buildAppSection(), + _buildPrivacySection(), + _buildNotificationSection(), + _buildSystemSection(), + _buildAboutSection(), + ], + ), + ); + } + + Widget _buildUserSection() { + return SettingsSection( + title: '账户', + children: [ + SettingsTile.navigation( + leading: Icon(Icons.person), + title: Text('个人信息'), + subtitle: Text('头像、昵称等'), + onPressed: (context) => _navigateToProfile(), + ), + SettingsTile.navigation( + leading: Icon(Icons.security), + title: Text('安全设置'), + subtitle: Text('密码、生物识别'), + onPressed: (context) => _navigateToSecurity(), + ), + ], + ); + } + + Widget _buildAppSection() { + return SettingsSection( + title: '应用', + children: [ + SettingsTile.navigation( + leading: Icon(Icons.language), + title: Text('语言'), + subtitle: Text('中文（简体）'), + onPressed: (context) => _navigateToLanguage(), + ), + SettingsTile.navigation( + leading: Icon(Icons.palette), + title: Text('主题'), + subtitle: Text('跟随系统'), + onPressed: (context) => _navigateToTheme(), + ), + SettingsTile.switchTile( + leading: Icon(Icons.dark_mode), + title: Text('深色模式'), + initialValue: false, + onToggle: (value) => _toggleDarkMode(value), + ), + ], + ); + } +} +``` + +### 通知设置页面 +```dart +// 通知设置页面 +class NotificationSettingsPage extends StatefulWidget { + @override + _NotificationSettingsPageState createState() => _NotificationSettingsPageState(); +} + +class _NotificationSettingsPageState extends State { + late NotificationSettingsBloc _bloc; + + @override + void initState() { + super.initState(); + _bloc = context.read(); + _bloc.add(LoadNotificationSettings()); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text('通知设置')), + body: BlocBuilder( + builder: (context, state) { + if (state is NotificationSettingsLoaded) { + return _buildSettingsList(state.settings); + } else if (state is NotificationSettingsError) { + return _buildErrorState(state.message); + } else { + return _buildLoadingState(); + } + }, + ), + ); + } + + Widget _buildSettingsList(NotificationSettings settings) { + return ListView( + children: [ + SettingsSection( + title: '通知开关', + children: [ + SettingsTile.switchTile( + leading: Icon(Icons.notifications), + title: Text('推送通知'), + subtitle: Text('接收应用推送消息'), + initialValue: settings.enablePushNotification, + onToggle: (value) => _togglePushNotification(value), + ), + SettingsTile.switchTile( + leading: Icon(Icons.volume_up), + title: Text('声音'), + initialValue: settings.enableSoundNotification, + onToggle: (value) => _toggleSoundNotification(value), + ), + SettingsTile.switchTile( + leading: Icon(Icons.vibration), + title: Text('振动'), + initialValue: settings.enableVibrationNotification, + onToggle: (value) => _toggleVibrationNotification(value), + ), + ], + ), + SettingsSection( + title: '通知类型', + children: [ + ...settings.typeSettings.entries.map( + (entry) => SettingsTile.switchTile( + leading: _getNotificationTypeIcon(entry.key), + title: Text(_getNotificationTypeName(entry.key)), + initialValue: entry.value, + onToggle: (value) => _toggleNotificationType(entry.key, value), + ), + ), + ], + ), + SettingsSection( + title: '免打扰', + children: [ + SettingsTile.navigation( + leading: Icon(Icons.schedule), + title: Text('免打扰时间'), + subtitle: Text('${settings.quietHours.startTime} - ${settings.quietHours.endTime}'), + onPressed: (context) => _navigateToQuietHours(), + ), + ], + ), + ], + ); + } +} +``` + +## 状态管理 + +### 设置状态管理 +```dart +// 设置状态 BLoC +class SettingsBloc extends Bloc { + final AppPreferenceService _preferenceService; + final NotificationSettingsService _notificationService; + final PrivacySettingsService _privacyService; + + SettingsBloc( + this._preferenceService, + this._notificationService, + this._privacyService, + ) : super(SettingsInitial()) { + on(_onLoadAllSettings); + on(_onUpdateAppPreference); + on(_onUpdateNotificationSettings); + on(_onUpdatePrivacySettings); + } + + Future _onLoadAllSettings( + LoadAllSettings event, + Emitter emit, + ) async { + emit(SettingsLoading()); + + try { + final appPreferences = await _preferenceService.getAppPreferences(); + final notificationSettings = await _notificationService.getNotificationSettings(); + final privacySettings = await _privacyService.getPrivacySettings(); + + final allSettings = AllSettings( + appPreferences: appPreferences, + notificationSettings: notificationSettings.getOrElse(() => NotificationSettings.defaultSettings()), + privacySettings: privacySettings.getOrElse(() => PrivacySettings.defaultSettings()), + ); + + emit(SettingsLoaded(allSettings)); + } catch (e) { + emit(SettingsError('加载设置失败: $e')); + } + } +} +``` + +## 路由配置 + +### 设置模块路由 +```dart +// 设置模块路由配置 +class SettingRoutes { + static const String main = '/settings'; + static const String profile = '/settings/profile'; + static const String notification = '/settings/notification'; + static const String privacy = '/settings/privacy'; + static const String security = '/settings/security'; + static const String language = '/settings/language'; + static const String theme = '/settings/theme'; + static const String about = '/settings/about'; + + static List get routes => [ + ChildRoute( + main, + child: (context, args) => SettingsMainPage(), + ), + ChildRoute( + profile, + child: (context, args) => ProfileSettingsPage(), + ), + ChildRoute( + notification, + child: (context, args) => NotificationSettingsPage(), + ), + ChildRoute( + privacy, + child: (context, args) => PrivacySettingsPage(), + ), + ChildRoute( + security, + child: (context, args) => SecuritySettingsPage(), + ), + ChildRoute( + language, + child: (context, args) => LanguageSettingsPage(), + ), + ChildRoute( + theme, + child: (context, args) => ThemeSettingsPage(), + ), + ChildRoute( + about, + child: (context, args) => AboutPage(), + ), + ]; +} +``` + +## 依赖管理 + +### 核心依赖 +- **basic_network**: 网络请求服务 +- **basic_storage**: 本地存储 +- **basic_modular**: 模块化框架 +- **basic_intl**: 国际化支持 + +### 服务依赖 +- **clr_setting**: 设置服务 SDK +- **clr_media**: 媒体服务 +- **app_consent**: 用户同意管理 + +### 系统依赖 +- **package_info**: 应用信息获取 +- **cupertino_icons**: iOS 风格图标 + +## 数据持久化 + +### 设置存储策略 +```dart +// 设置存储管理器 +class SettingsStorageManager { + final StorageService _storageService; + + SettingsStorageManager(this._storageService); + + // 保存设置到本地 + Future saveSettings(String key, T settings) async { + await _storageService.setObject(key, settings.toJson()); + } + + // 从本地加载设置 + Future loadSettings( + String key, + T Function(Map) fromJson, + ) async { + final json = await _storageService.getObject(key); + if (json != null) { + return fromJson(json); + } + return null; + } + + // 同步设置到云端 + Future syncSettingsToCloud() async { + // 实现云端同步逻辑 + } +} +``` + +## 错误处理 + +### 设置特定异常 +```dart +// 设置功能异常 +abstract class SettingFailure { + const SettingFailure(); + + factory SettingFailure.loadFailed(String message) = LoadFailure; + factory SettingFailure.updateFailed(String message) = UpdateFailure; + factory SettingFailure.clearCacheFailed(String message) = ClearCacheFailure; + factory SettingFailure.biometricNotAvailable() = BiometricNotAvailableFailure; + factory SettingFailure.biometricAuthFailed() = BiometricAuthFailure; +} + +class LoadFailure extends SettingFailure { + final String message; + const LoadFailure(this.message); +} +``` + +## 总结 + +`app_setting` 模块为 OneApp 提供了完整的应用设置管理功能，涵盖用户偏好、通知管理、隐私安全等各个方面。模块采用清晰的分层架构和模块化设计，支持多语言、主题切换和云端同步，为用户提供个性化和安全的设置体验。通过完善的状态管理和错误处理机制，确保了设置功能的稳定性和用户体验。 diff --git a/touch_point/README.md b/touch_point/README.md new file mode 100644 index 0000000..fccea3b --- /dev/null +++ b/touch_point/README.md @@ -0,0 +1,144 @@ +# Touch Point 触点服务模块群 + +## 模块群概述 + +Touch Point 模块群是 OneApp 的用户触点管理系统，负责管理用户与应用的各种交互触点。该模块群提供了统一的用户体验管理、触点数据收集、用户行为分析等功能，帮助优化用户旅程和提升用户体验。 + +## 子模块列表 + +### 核心模块 +1. **[oneapp_touch_point](./oneapp_touch_point.md)** - 触点服务主模块 + - 用户触点数据收集和管理 + - 触点事件跟踪和分析 + - 用户行为路径记录 + +## 功能特性 + +### 核心业务功能 +1. **触点数据收集** + - 用户交互事件收集 + - 页面访问路径跟踪 + - 用户行为数据记录 + - 设备和环境信息采集 + +2. **用户体验分析** + - 用户旅程分析 + - 转化漏斗分析 + - 用户留存分析 + - 行为热力图生成 + +3. **个性化推荐** + - 基于行为的内容推荐 + - 个性化界面适配 + - 智能消息推送 + - 用户偏好学习 + +4. **体验优化** + - A/B测试支持 + - 用户反馈收集 + - 性能监控和优化 + - 异常行为检测 + +## 技术架构 + +### 模块架构图 +``` +触点服务应用层 (oneapp_touch_point) + ↓ +数据收集层 (Event Collection) + ↓ +数据处理层 (Data Processing) + ↓ +分析引擎层 (Analytics Engine) + ↓ +存储层 (Data Storage) +``` + +### 主要依赖 +- **基础框架**: basic_modular, basic_intl +- **网络通信**: dio +- **数据处理**: encrypt, common_utils +- **UI组件**: basic_webview, photo_view +- **文件处理**: path_provider, filesize +- **媒体处理**: video_thumbnail +- **权限管理**: permission_handler + +## 数据流向 + +### 触点数据流 +```mermaid +graph TD + A[用户交互] --> B[事件收集器] + B --> C[数据预处理] + C --> D[数据验证] + D --> E[数据加密] + E --> F[本地缓存] + F --> G[批量上传] + G --> H[服务器处理] + H --> I[数据分析] + I --> J[反馈优化] +``` + +### 用户体验优化流程 +```mermaid +graph TD + A[收集用户数据] --> B[行为分析] + B --> C[识别痛点] + C --> D[制定优化方案] + D --> E[A/B测试] + E --> F[效果评估] + F --> G[方案迭代] + G --> H[全量发布] +``` + +## 详细模块文档 + +- [OneApp Touch Point - 触点服务主模块](./oneapp_touch_point.md) + +## 开发指南 + +### 环境要求 +- Flutter >=2.10.5 +- Dart >=3.0.0 <4.0.0 +- Android SDK >=21 +- iOS >=11.0 + +### 快速开始 +```dart +// 初始化触点服务 +await TouchPointService.initialize(); + +// 记录用户行为事件 +TouchPointService.trackEvent( + eventName: 'page_view', + properties: { + 'page_name': 'home', + 'timestamp': DateTime.now().millisecondsSinceEpoch, + }, +); + +// 记录用户操作 +TouchPointService.trackAction( + actionType: 'button_click', + actionTarget: 'login_button', + context: {'page': 'login'}, +); +``` + +## 隐私和合规 + +### 数据保护 +- 用户数据加密存储和传输 +- 敏感信息脱敏处理 +- 用户同意管理 +- 数据最小化原则 + +### 合规要求 +- GDPR合规支持 +- 用户数据删除权 +- 数据导出功能 +- 隐私政策透明化 + +## 总结 + +Touch Point 模块群为 OneApp 提供了全面的用户触点管理能力，通过科学的数据收集和分析方法，帮助产品团队深入了解用户行为，持续优化用户体验，提升产品价值。 diff --git a/touch_point/oneapp_touch_point.md b/touch_point/oneapp_touch_point.md new file mode 100644 index 0000000..5c860ba --- /dev/null +++ b/touch_point/oneapp_touch_point.md @@ -0,0 +1,593 @@ +# OneApp Touch Point - 触点服务主模块 + +## 模块概述 + +`oneapp_touch_point` 是 OneApp 的触点服务主模块，负责用户触点数据的收集、管理和分析。该模块通过跟踪用户在应用中的各种交互行为，构建完整的用户行为路径，为用户体验优化、个性化推荐和业务决策提供数据支撑。 + +## 核心功能 + +### 1. 用户触点数据收集 +- **行为事件跟踪**：记录用户的点击、滑动、停留等行为 +- **页面访问跟踪**：跟踪用户的页面访问路径和时长 +- **功能使用统计**：统计各功能模块的使用频率 +- **异常行为监控**：监控和记录异常的用户行为 + +### 2. 触点事件跟踪和分析 +- **事件分类管理**：对触点事件进行分类和标签管理 +- **实时事件处理**：实时处理和响应触点事件 +- **事件关联分析**：分析事件之间的关联关系 +- **趋势分析**：分析用户行为的趋势变化 + +### 3. 用户行为路径记录 +- **用户旅程映射**：构建完整的用户旅程地图 +- **转化漏斗分析**：分析用户在关键流程中的转化情况 +- **路径优化建议**：基于数据分析提供路径优化建议 +- **异常路径识别**：识别和分析异常的用户行为路径 + +## 技术架构 + +### 架构设计 +``` +┌─────────────────────────────────────┐ +│ 应用界面层 │ +│ (Application UI) │ +├─────────────────────────────────────┤ +│ OneApp Touch Point │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 数据收集 │ 事件处理 │ 行为分析 │ │ +│ ├──────────┼──────────┼──────────┤ │ +│ │ 路径跟踪 │ 数据存储 │ 报告生成 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 数据处理层 │ +│ ┌──────────┬──────────┬──────────┐ │ +│ │ 数据清洗 │ 数据聚合 │ 数据分析 │ │ +│ └──────────┴──────────┴──────────┘ │ +├─────────────────────────────────────┤ +│ 数据存储层 │ +│ (Local DB + Remote Analytics) │ +└─────────────────────────────────────┘ +``` + +### 核心组件 + +#### 1. 触点数据收集器 (TouchPointCollector) +```dart +class TouchPointCollector { + // 记录触点事件 + Future trackEvent(TouchPointEvent event); + + // 记录页面访问 + Future trackPageView(PageViewEvent event); + + // 记录用户行为 + Future trackUserAction(UserActionEvent event); + + // 批量上传数据 + Future uploadBatchData(); +} +``` + +#### 2. 事件分析器 (EventAnalyzer) +```dart +class TouchPointEventAnalyzer { + // 分析用户行为模式 + Future analyzeUserBehavior(String userId, TimeRange timeRange); + + // 生成用户旅程 + Future generateUserJourney(String userId, String sessionId); + + // 计算转化率 + Future calculateConversionRate(ConversionFunnel funnel); + + // 识别异常行为 + Future> detectAnomalousEvents(AnalysisConfig config); +} +``` + +#### 3. 路径跟踪器 (PathTracker) +```dart +class UserPathTracker { + // 开始路径跟踪 + Future startPathTracking(String userId); + + // 记录路径节点 + Future recordPathNode(String sessionId, PathNode node); + + // 结束路径跟踪 + Future endPathTracking(String sessionId); + + // 获取用户路径历史 + Future> getUserPathHistory(String userId, int limit); +} +``` + +#### 4. 数据管理器 (TouchPointDataManager) +```dart +class TouchPointDataManager { + // 存储触点数据 + Future storeTouchPointData(TouchPointData data); + + // 查询触点数据 + Future> queryTouchPointData(DataQuery query); + + // 清理过期数据 + Future cleanupExpiredData(Duration retentionPeriod); + + // 导出数据 + Future exportData(ExportConfig config); +} +``` + +## 数据模型 + +### 触点事件模型 +```dart +class TouchPointEvent { + final String id; + final String userId; + final String sessionId; + final EventType type; + final String category; + final String action; + final String? target; + final Map properties; + final DateTime timestamp; + final String pageUrl; + final String? referrer; + final DeviceInfo deviceInfo; + final LocationInfo? locationInfo; +} + +enum EventType { + click, // 点击事件 + view, // 查看事件 + scroll, // 滚动事件 + input, // 输入事件 + search, // 搜索事件 + purchase, // 购买事件 + share, // 分享事件 + download, // 下载事件 + upload, // 上传事件 + custom // 自定义事件 +} +``` + +### 用户路径模型 +```dart +class UserPath { + final String id; + final String userId; + final String sessionId; + final DateTime startTime; + final DateTime endTime; + final List nodes; + final Duration totalDuration; + final String? goalAchieved; + final Map metadata; +} + +class PathNode { + final String id; + final String pageUrl; + final String pageName; + final DateTime entryTime; + final DateTime? exitTime; + final Duration? duration; + final List events; + final String? exitMethod; + final Map pageData; +} +``` + +### 用户行为分析模型 +```dart +class UserBehaviorPattern { + final String userId; + final TimeRange analysisPeriod; + final List frequentPages; + final List preferredFeatures; + final Map actionCounts; + final List insights; + final double engagementScore; + final UserSegment segment; +} + +class ConversionFunnel { + final String name; + final List steps; + final Map metrics; + final DateTime analysisTime; +} + +class ConversionMetric { + final int totalUsers; + final int convertedUsers; + final double conversionRate; + final Duration averageTime; + final List dropOffReasons; +} +``` + +## API 接口 + +### 数据收集接口 +```dart +abstract class TouchPointTrackingService { + // 跟踪事件 + Future> trackEvent(TrackEventRequest request); + + // 批量跟踪事件 + Future> trackBatchEvents(BatchTrackRequest request); + + // 跟踪页面访问 + Future> trackPageView(PageViewRequest request); + + // 跟踪用户会话 + Future> trackUserSession(SessionRequest request); +} +``` + +### 数据分析接口 +```dart +abstract class TouchPointAnalyticsService { + // 获取用户行为分析 + Future> getUserBehaviorAnalysis(BehaviorAnalysisRequest request); + + // 获取转化漏斗分析 + Future> getConversionAnalysis(ConversionAnalysisRequest request); + + // 获取用户旅程分析 + Future> getUserJourneyAnalysis(JourneyAnalysisRequest request); + + // 获取实时分析数据 + Future> getRealtimeAnalytics(); +} +``` + +### 数据管理接口 +```dart +abstract class TouchPointDataService { + // 查询触点数据 + Future>> queryTouchPointData(DataQueryRequest request); + + // 导出触点数据 + Future> exportTouchPointData(ExportRequest request); + + // 删除用户数据 + Future> deleteUserData(DeleteUserDataRequest request); + + // 获取数据统计 + Future> getDataStatistics(StatisticsRequest request); +} +``` + +## 配置管理 + +### 触点跟踪配置 +```dart +class TouchPointConfig { + final bool enableTracking; + final bool enableRealTimeAnalysis; + final int batchUploadSize; + final Duration uploadInterval; + final List trackedEventTypes; + final Duration dataRetentionPeriod; + final bool enableLocationTracking; + final PrivacyLevel privacyLevel; + + static const TouchPointConfig defaultConfig = TouchPointConfig( + enableTracking: true, + enableRealTimeAnalysis: true, + batchUploadSize: 100, + uploadInterval: Duration(minutes: 5), + trackedEventTypes: [ + EventType.click, + EventType.view, + EventType.search, + EventType.purchase, + ], + dataRetentionPeriod: Duration(days: 90), + enableLocationTracking: false, + privacyLevel: PrivacyLevel.standard, + ); +} +``` + +### 分析配置 +```dart +class AnalyticsConfig { + final bool enableBehaviorAnalysis; + final bool enablePathAnalysis; + final bool enableConversionTracking; + final Duration analysisInterval; + final int maxPathLength; + final List conversionGoals; + final Map eventWeights; + + static const AnalyticsConfig defaultAnalyticsConfig = AnalyticsConfig( + enableBehaviorAnalysis: true, + enablePathAnalysis: true, + enableConversionTracking: true, + analysisInterval: Duration(hours: 1), + maxPathLength: 50, + conversionGoals: ['purchase', 'registration', 'subscription'], + eventWeights: { + 'click': 1.0, + 'view': 0.5, + 'search': 1.5, + 'purchase': 5.0, + }, + ); +} +``` + +## 使用示例 + +### 基本事件跟踪 +```dart +// 初始化触点服务 +final touchPointService = TouchPointCollector.instance; +await touchPointService.initialize(TouchPointConfig.defaultConfig); + +// 跟踪页面访问 +await touchPointService.trackPageView( + PageViewEvent( + userId: 'user123', + sessionId: 'session456', + pageUrl: '/home', + pageName: '首页', + timestamp: DateTime.now(), + properties: { + 'source': 'direct', + 'previous_page': '/login', + }, + ), +); + +// 跟踪用户行为 +await touchPointService.trackEvent( + TouchPointEvent( + userId: 'user123', + sessionId: 'session456', + type: EventType.click, + category: 'navigation', + action: 'menu_click', + target: 'vehicle_menu', + properties: { + 'menu_position': 'top', + 'menu_index': 2, + }, + timestamp: DateTime.now(), + pageUrl: '/home', + ), +); +``` + +### 用户路径跟踪 +```dart +// 开始用户路径跟踪 +final pathTracker = UserPathTracker.instance; +final sessionId = await pathTracker.startPathTracking('user123'); + +// 记录路径节点 +await pathTracker.recordPathNode( + sessionId, + PathNode( + id: 'node1', + pageUrl: '/vehicle/list', + pageName: '车辆列表', + entryTime: DateTime.now(), + pageData: { + 'filter': 'electric', + 'sort': 'price', + }, + ), +); + +// 记录页面内的事件 +await pathTracker.recordPathNode( + sessionId, + PathNode( + id: 'node2', + pageUrl: '/vehicle/detail/123', + pageName: '车辆详情', + entryTime: DateTime.now(), + events: [ + TouchPointEvent( + type: EventType.view, + action: 'image_view', + target: 'vehicle_gallery', + ), + ], + ), +); + +// 结束路径跟踪 +final userPath = await pathTracker.endPathTracking(sessionId); +print('用户路径总时长: ${userPath.totalDuration}'); +``` + +### 用户行为分析 +```dart +// 分析用户行为模式 +final analyzer = TouchPointEventAnalyzer.instance; +final behaviorPattern = await analyzer.analyzeUserBehavior( + 'user123', + TimeRange.lastMonth, +); + +print('用户参与度评分: ${behaviorPattern.engagementScore}'); +print('常访问页面: ${behaviorPattern.frequentPages}'); +print('偏好功能: ${behaviorPattern.preferredFeatures}'); + +// 生成用户旅程 +final userJourney = await analyzer.generateUserJourney('user123', 'session456'); +print('旅程步骤数: ${userJourney.steps.length}'); + +// 计算转化率 +final conversionFunnel = ConversionFunnel( + name: '购车转化漏斗', + steps: [ + FunnelStep(name: '浏览车辆', event: 'vehicle_view'), + FunnelStep(name: '查看详情', event: 'vehicle_detail'), + FunnelStep(name: '预约试驾', event: 'test_drive_booking'), + FunnelStep(name: '下单购买', event: 'purchase'), + ], +); + +final conversionRate = await analyzer.calculateConversionRate(conversionFunnel); +print('总体转化率: ${conversionRate.overallConversionRate}%'); +``` + +### 数据导出和管理 +```dart +// 查询触点数据 +final dataManager = TouchPointDataManager.instance; +final touchPointData = await dataManager.queryTouchPointData( + DataQuery( + userId: 'user123', + timeRange: TimeRange.lastWeek, + eventTypes: [EventType.click, EventType.view], + ), +); + +print('查询到 ${touchPointData.length} 条数据'); + +// 导出数据 +final exportPath = await dataManager.exportData( + ExportConfig( + format: ExportFormat.csv, + timeRange: TimeRange.lastMonth, + includePersonalData: false, + ), +); + +print('数据已导出到: $exportPath'); + +// 清理过期数据 +final cleanedCount = await dataManager.cleanupExpiredData( + Duration(days: 90), +); + +print('清理了 $cleanedCount 条过期数据'); +``` + +## 测试策略 + +### 单元测试 +```dart +group('TouchPointCollector Tests', () { + test('should track event successfully', () async { + // Given + final collector = TouchPointCollector(); + final event = TouchPointEvent( + userId: 'test_user', + type: EventType.click, + action: 'button_click', + ); + + // When + await collector.trackEvent(event); + + // Then + final storedEvents = await collector.getStoredEvents(); + expect(storedEvents, contains(event)); + }); + + test('should analyze user behavior correctly', () async { + // Given + final analyzer = TouchPointEventAnalyzer(); + final userId = 'test_user'; + + // When + final pattern = await analyzer.analyzeUserBehavior(userId, TimeRange.lastWeek); + + // Then + expect(pattern.userId, userId); + expect(pattern.engagementScore, greaterThan(0)); + }); +}); +``` + +### 集成测试 +```dart +group('TouchPoint Integration Tests', () { + testWidgets('complete tracking flow', (tester) async { + // 1. 初始化触点服务 + await TouchPointCollector.instance.initialize(TouchPointConfig.defaultConfig); + + // 2. 模拟用户操作 + await tester.tap(find.byKey(Key('vehicle_button'))); + await tester.pumpAndSettle(); + + // 3. 验证事件被跟踪 + final trackedEvents = await TouchPointCollector.instance.getStoredEvents(); + expect(trackedEvents, isNotEmpty); + + // 4. 验证用户路径记录 + final userPaths = await UserPathTracker.instance.getUserPathHistory('test_user', 10); + expect(userPaths, isNotEmpty); + }); +}); +``` + +## 性能优化 + +### 数据收集优化 +- **批量上传**：批量上传触点数据减少网络请求 +- **数据压缩**：压缩数据减少存储空间和传输量 +- **异步处理**：异步处理数据收集和上传 +- **本地缓存**：本地缓存数据防止数据丢失 + +### 分析性能优化 +- **增量分析**：只分析新增的数据 +- **并行处理**：并行处理多个分析任务 +- **结果缓存**：缓存分析结果避免重复计算 +- **数据预聚合**：预聚合常用的分析指标 + +## 隐私和合规 + +### 数据隐私保护 +- **数据匿名化**：敏感数据匿名化处理 +- **用户同意管理**：用户数据收集同意管理 +- **数据加密**：敏感数据加密存储和传输 +- **访问控制**：严格的数据访问权限控制 + +### 合规要求 +- **GDPR合规**：支持GDPR数据保护要求 +- **数据删除权**：支持用户数据删除请求 +- **数据导出权**：支持用户数据导出请求 +- **透明度报告**：提供数据使用透明度报告 + +## 版本历史 + +### v0.3.2+8 (当前版本) +- 新增实时行为分析功能 +- 优化数据收集性能 +- 支持用户路径可视化 +- 修复数据同步问题 + +### v0.3.1 +- 支持转化漏斗分析 +- 新增异常行为检测 +- 优化数据存储结构 +- 改进隐私保护机制 + +## 依赖关系 + +### 内部依赖 +- `basic_storage`: 本地数据存储 +- `basic_network`: 网络请求服务 +- `basic_logger`: 日志记录服务 +- `basic_utils`: 工具类库 + +### 外部依赖 +- `sqflite`: 本地数据库 +- `dio`: HTTP客户端 +- `uuid`: 唯一标识符生成 +- `path_provider`: 文件路径管理 + +## 总结 + +`oneapp_touch_point` 模块为 OneApp 提供了完整的用户触点管理和分析能力。通过全面的数据收集、智能的行为分析和详细的路径跟踪，该模块帮助产品团队深入了解用户行为，优化用户体验，提升产品价值。同时，模块严格遵循隐私保护原则，确保用户数据的安全和合规使用。