213 lines
5.2 KiB
Markdown
213 lines
5.2 KiB
Markdown
|
# 现场上报模块使用说明
|
|||
|
|
|
|||
|
|
## 快速开始
|
|||
|
|
|
|||
|
|
### 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<Either<Failure, bool>> 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<ReportCubit>().selectDevice(device);
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 实现真实的相机/相册功能
|
|||
|
|
|
|||
|
|
添加依赖：
|
|||
|
|
```yaml
|
|||
|
|
dependencies:
|
|||
|
|
image_picker: ^1.1.2
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
修改 `MediaUploader`:
|
|||
|
|
|
|||
|
|
```dart
|
|||
|
|
final ImagePicker picker = ImagePicker();
|
|||
|
|
|
|||
|
|
Future<void> _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. 添加草稿保存功能
|