# 现场上报模块使用说明 ## 快速开始 ### 1. 在路由中注册页面 ```dart import 'package:flutter_bloc/flutter_bloc.dart'; import 'package:maibu_satabot_v2/features/v2/report/report.dart'; // 在路由配置中添加 GoRoute( path: '/report', builder: (context, state) => BlocProvider( create: (context) => ReportDependencyInjector.createReportCubit(), child: const ReportPage(), ), ), ``` ### 2. 跳转到上报页面 ```dart context.push('/report'); ``` ## 架构说明 ### 清洁架构分层 ``` lib/features/v2/report/ ├── domain/ # 领域层(核心业务逻辑) │ ├── entities/ # 实体类 │ │ └── report_entity.dart │ ├── repositories/ # 仓储接口 │ │ └── report_repository.dart │ └── usecases/ # 用例 │ └── submit_report_usecase.dart ├── data/ # 数据层(数据获取与存储) │ ├── datasources/ # 数据源 │ │ ├── report_remote_datasource.dart │ │ └── report_remote_datasource_impl.dart │ ├── models/ # 数据模型 │ │ └── report_model.dart │ └── repositories/ # 仓储实现 │ └── report_repository_impl.dart ├── presentation/ # 表现层(UI + 状态管理) │ ├── constants/ # 常量 │ │ └── report_constants.dart │ ├── cubit/ # 状态管理 │ │ └── report_cubit.dart │ ├── states/ # 状态定义 │ │ └── report_state.dart │ ├── pages/ # 页面 │ │ └── report_page.dart │ ── widgets/ # 组件 │ ├── report_type_selector.dart │ ├── device_selector.dart │ ├── description_input.dart │ ├── media_uploader.dart │ └── level_selector.dart ├── di/ # 依赖注入 │ └── report_di.dart └── report.dart # 统一导出 ``` ## 核心功能 ### 1. 上报类型选择 - 设备故障 - 巡检记录 - 隐患上报 - 缺陷上报 ### 2. 设备选择 - 点击选择设备(需实现设备选择页面) ### 3. 问题描述 - 多行文本输入 - 最大 200 字符限制 - 实时字符计数 ### 4. 媒体上传 - 拍照上传 - 录像上传 - 图片预览 - 删除已上传图片 ### 5. 问题等级 - 一般(灰色) - 重要(橙色) - 紧急(红色) ## 表单验证 提交时自动验证以下必填项: 1. 设备选择 2. 问题描述 3. 问题等级 ## 状态管理 ### 状态类型 - `ReportInitial`: 初始状态 - `ReportFormState`: 表单数据状态 - `ReportSubmitting`: 提交中状态 - `ReportSuccess`: 提交成功状态 - `ReportFailure`: 提交失败状态 ### Cubit 方法 - `selectReportType(ReportType)`: 选择上报类型 - `selectDevice(String)`: 选择设备 - `updateDescription(String)`: 更新问题描述 - `selectProblemLevel(ProblemLevel)`: 选择问题等级 - `addMediaFile(String)`: 添加媒体文件 - `removeMediaFile(int)`: 删除媒体文件 - `submitReport()`: 提交上报 - `resetForm()`: 重置表单 ## 自定义扩展 ### 1. 对接真实 API 修改 `ReportRemoteDataSourceImpl`: ```dart class ReportRemoteDataSourceImpl implements ReportRemoteDataSource { final Dio dio; // 注入 Dio 实例 @override Future> submitReport(ReportModel report) async { try { final response = await dio.post( '/api/report/submit', data: report.toJson(), ); if (response.statusCode == 200) { return right(true); } else { return left(ServerFailure('提交失败')); } } catch (e) { return left(NetworkFailure('网络错误: $e')); } } } ``` ### 2. 实现设备选择 在 `ReportPage` 中修改 `_showDevicePicker` 方法: ```dart void _showDevicePicker(BuildContext context) { // 跳转到设备选择页面 context.push('/device-select').then((device) { if (device != null) { context.read().selectDevice(device); } }); } ``` ### 3. 实现真实的相机/相册功能 添加依赖: ```yaml dependencies: image_picker: ^1.1.2 ``` 修改 `MediaUploader`: ```dart final ImagePicker picker = ImagePicker(); Future _pickImage() async { final XFile? image = await picker.pickImage(source: ImageSource.camera); if (image != null) { cubit.addMediaFile(image.path); } } ``` ## 依赖说明 ### 项目已有依赖 - flutter_bloc: ^9.1.1 - equatable: ^2.0.8 - fpdart: ^1.2.0 ### 可选依赖(按需添加) - image_picker: ^1.1.2 (图片/视频选择) - dio: ^5.9.0 (HTTP 请求,项目已有) ## 注意事项 1. 所有颜色、尺寸常量已抽取到 `report_constants.dart` 2. 遵循清洁架构原则,内层不依赖外层 3. 使用 fpdart 进行错误处理(Either 类型) 4. 所有 UI 组件已适配 iOS 安全区 5. 模拟数据已实现,可直接运行测试 ## 后续开发建议 1. 实现真实的设备选择页面 2. 对接后端 API 3. 添加图片压缩功能 4. 实现离线缓存 5. 添加草稿保存功能