工地模块 V2 版本架构设计与实现文档

AI 开发 架构升级

1. 概述

本文档详细描述了工地模块（Construction Site）V2 版本的架构设计与实现。新架构采用了 MVVM 模式，结合状态管理和中介者模式，实现了高内聚低耦合的代码结构，提高了代码可维护性和可扩展性，并优化了用户体验。

2. 架构设计目标

  • 关注点分离：清晰划分视图层、控制器层、状态管理层和数据层

  • 状态一致性：确保各组件状态同步，提供一致的用户体验

  • 代码复用：抽象共用逻辑，减少代码冗余

  • 性能优化：减少不必要的重建和网络请求

  • 易于扩展：支持新功能快速集成，无需大规模重构

  • 错误处理：提供完善的错误处理机制

3. 核心架构组件

3.1 架构概览

classDiagram class ConstructMainPage { -AnalyticsService _analyticsService -UserService _userService -FilterStates _filterStates -Controllers _controllers -UI _components +initState() +build() -_onTabTap() -_onFilterTap() -_onRefresh() -_onLoading() -_onItemTap() } class ConstructionSiteController { -ConstructionSiteVM _vm -FilterMediator _filterMediator -ConstructionSiteListVM _listVM -ConstructionFilterCountVM _countVM -WorkTypeController _workTypeController -bool _isLoadingData +loadTabData(int selectedIndex) +loadData(bool showToast, bool isLoadMore) +toggleFilter(int index) +retry() -_onFilterStateChanged() -_loadWorkTypeData() } class WorkTypeController { -ConstructionWorkTypeVM _workTypeVM -ConstructionGroupLeaderVM _groupLeaderVM -String _userRole -List~WorkTypeModel~ _groupLeaders -List~WorkTypeModel~ _works -FilterMediator filterMediator +initialize() -_getUserRole() -_requestWorkType() +resetSelections() } class FilterMediator { -ProgressFilterState progressFilterState -LightFilterState lightFilterState -ScheduleFilterState scheduleFilterState -OtherFilterState otherFilterState -int _currentPage -List~ConstructionSiteModel~ _listData -ConstructionFilterCountModel _countData +Map~String,dynamic~ requestParams +initDefaultStatus() +updateCurrentCode() +resetFilters() +loadMore() +updateListData() +updateCountData() -_onFilterStateChanged() } class BaseFilterState { <> +bool hasActiveFilters +Map~String,dynamic~ params +reset() } class ProgressFilterState { -FilterItem _selectedItem -String _currentStatus +select(FilterItem item) +initDefaultStatus() +updateStatusEnum() } class ConstructionSiteVM { +load() +buildModel() } class ConstructionSiteListVM { -Map~String,dynamic~ paramsDic +load() +loadMore() +buildModel() +buildItem() } class ConstructionListBody { +build() -_buildListView() -_buildLoadingWidget() -_buildEmptyWidget() -_buildErrorWidget() } %% 关系连接 ConstructMainPage --> ConstructionSiteController : 创建和使用 ConstructMainPage --> WorkTypeController : 创建和使用 ConstructMainPage --> FilterMediator : 创建和使用 ConstructMainPage --> ConstructionListBody : 渲染列表 ConstructionSiteController --> ConstructionSiteVM : 使用 ConstructionSiteController --> ConstructionSiteListVM : 使用 ConstructionSiteController --> FilterMediator : 依赖 ConstructionSiteController --> WorkTypeController : 依赖 WorkTypeController --> FilterMediator : 依赖 FilterMediator --> ProgressFilterState : 包含 FilterMediator --> LightFilterState : 包含 FilterMediator --> ScheduleFilterState : 包含 FilterMediator --> OtherFilterState : 包含 ProgressFilterState --|> BaseFilterState : 继承 LightFilterState --|> BaseFilterState : 继承 ScheduleFilterState --|> BaseFilterState : 继承 OtherFilterState --|> BaseFilterState : 继承

3.2 视图层

视图层主要由以下组件构成：

  • ConstructMainPage：主页面，负责整体布局和组件组装

  • ConstructionHeader：头部组件，显示标签页和标题

  • ConstructionFilterSection：筛选区域组件，显示筛选栏和筛选计数

  • ConstructionListBody：列表主体组件，负责显示工地列表

  • ConstructionSiteItemWidget：列表项组件，显示单个工地信息

3.3 控制器层

控制器层负责业务逻辑处理和状态管理：

  • ConstructionSiteController：主控制器，负责协调整体数据流和操作

  • WorkTypeController：工作类型控制器，负责处理与工作类型相关的逻辑

  • FilterOverlayController：筛选浮层控制器，管理筛选浮层的显示和隐藏

3.4 状态管理层

状态管理层负责维护应用状态和状态间的协调：

  • FilterMediator：筛选状态中介者，协调不同筛选状态间的交互

  • ProgressFilterState：进度筛选状态

  • LightFilterState：红黄灯筛选状态

  • ScheduleFilterState：计划排程筛选状态

  • OtherFilterState：其他筛选状态

3.5 数据层

数据层负责数据获取和处理：

  • ConstructionSiteVM：获取工地配置数据

  • ConstructionSiteListVM：获取工地列表数据

  • ConstructionFilterCountVM：获取筛选计数数据

  • ConstructionWorkTypeVM：获取工作类型数据

4. 数据流程

4.1 完整数据流程图

graph TD subgraph "初始化流程" A[页面初始化 initState] --> B[状态初始化 _initializeState] A --> C[服务初始化 _initializeServices] A --> D[数据初始化 _loadInitialData] A --> E[浮层初始化 _initializeOverlayController] B --> B1[创建筛选状态 ProgressFilterState等] B --> B2[创建中介者 FilterMediator] B --> B3[创建工作类型控制器 WorkTypeController] B --> B4[创建主控制器 ConstructionSiteController] D --> D1[加载标签页数据 loadTabData] D --> D2[初始化工作类型数据 initialize] end subgraph "数据加载流程" F[loadTabData] --> F1[暂停筛选监听] F1 --> F2[加载标签页配置 _vm.load] F2 --> F3{加载成功?} F3 -->|是| F4[重置筛选条件] F4 --> F5[初始化默认状态] F5 --> F6[加载工作类型数据] F6 --> F7[添加工作类型筛选组] F7 --> F8[加载初始列表数据] F3 -->|否| F9[设置错误状态] F8 --> F10[恢复筛选监听] F9 --> F10 G[加载列表数据 loadData] --> G1[设置加载状态] G1 --> G2[构建请求参数] G2 --> G3{是否加载更多?} G3 -->|否| G4[加载计数数据 _countVM.load] G3 -->|是| G5[跳过计数加载] G4 --> G6[加载列表数据 _listVM.load] G5 --> G7[加载更多数据 _listVM.loadMore] G6 --> G8[更新列表数据] G7 --> G8 G8 --> G9[重置加载状态] end subgraph "筛选流程" H[筛选状态管理] --> H1[进度筛选 ProgressFilterState] H --> H2[红黄灯筛选 LightFilterState] H --> H3[计划排程筛选 ScheduleFilterState] H --> H4[其他筛选 OtherFilterState] H1 --> H5[中介者协调 FilterMediator] H2 --> H5 H3 --> H5 H4 --> H5 I[筛选参数构建] --> I1[添加分页信息] I1 --> I2[合并各筛选状态参数] I2 --> I3[构建matchMap] I3 --> I4[添加特殊参数] I4 --> I5[返回完整参数] J[筛选UI交互] --> J1[显示筛选栏] J1 --> J2[点击筛选项] J2 --> J3[显示筛选浮层] J3 --> J4[确认筛选] J4 --> J5[更新筛选状态] J5 --> J6[触发数据重新加载] end subgraph "数据展示流程" K[列表渲染 ConstructionListBody] --> K1{检查控制器状态} K1 -->|加载中| K2[显示加载组件] K1 -->|空数据| K3[显示空状态组件] K1 -->|错误| K4[显示错误组件] K1 -->|有数据| K5[显示列表内容] K5 --> K6[渲染列表项] L[用户交互] --> L1[下拉刷新] L --> L2[上拉加载更多] L --> L3[列表项点击] L1 --> L4[重置页码并重新加载] L2 --> L5[增加页码并加载更多] L3 --> L6[记录埋点并处理点击] end %% 流程连接 F10 --> G J6 --> G G9 --> K L4 --> G L5 --> G %% 样式 classDef init fill:#d4f1f9,stroke:#05a4de classDef data fill:#ffe6cc,stroke:#d79b00 classDef filter fill:#d5e8d4,stroke:#82b366 classDef display fill:#e1d5e7,stroke:#9673a6 class A,B,C,D,E,B1,B2,B3,B4,D1,D2 init class F,F1,F2,F3,F4,F5,F6,F7,F8,F9,F10,G,G1,G2,G3,G4,G5,G6,G7,G8,G9 data class H,H1,H2,H3,H4,H5,I,I1,I2,I3,I4,I5,J,J1,J2,J3,J4,J5,J6 filter class K,K1,K2,K3,K4,K5,K6,L,L1,L2,L3,L4,L5,L6 display

4.2 初始化流程

  1. 页面初始化：在 ConstructMainPage 的 initState() 中启动整个初始化流程

  2. 状态初始化：创建各种筛选状态、中介者和控制器

  3. 服务初始化：初始化用户服务和分析服务

  4. 数据初始化：加载标签页配置和工作类型数据

  5. 浮层初始化：初始化筛选浮层控制器

4.3 数据加载流程

  1. 标签页数据加载：

  • 暂停筛选监听，避免在状态重置期间触发不必要的数据加载

  • 加载标签页配置数据

  • 重置筛选条件

  • 初始化默认状态

  • 加载工作类型数据

  • 添加工作类型相关的筛选组

  • 加载初始列表数据

  • 恢复筛选监听

  1. 工作类型数据加载：

  • 获取用户角色

  • 根据角色加载相应的工作类型数据

  • 创建工作类型筛选组

  • 添加到自定义筛选组

  1. 列表数据加载：

  • 构建请求参数，包含筛选条件和分页信息

  • 加载筛选计数数据（非加载更多时）

  • 加载列表数据

  • 更新筛选状态和列表数据

4.4 筛选流程

  1. 筛选状态管理：

  • 四种筛选状态作为 ChangeNotifier，当状态变化时通知监听器

  • FilterMediator 监听这些状态的变化，并在变化时重置页码并通知自己的监听器

  1. 筛选参数构建：

  • 包含分页信息

  • 合并来自各筛选状态的参数

  • 构建 matchMap 用于条件匹配

  • 添加特殊参数

  1. 筛选UI交互：

  • 点击筛选栏项目，显示/隐藏筛选浮层

  • 在筛选浮层中选择筛选条件

  • 确认筛选，更新筛选状态

  • 触发数据重新加载

4.5 数据展示流程

  1. 列表渲染：

  • 根据控制器状态显示不同的UI（加载中/空状态/错误/列表内容）

  • 使用 SmartRefresher 支持下拉刷新和上拉加载更多

  • 列表项显示工地信息

  1. 用户交互处理：

  • 下拉刷新：重置页码，重新加载数据

  • 上拉加载更多：增加页码，加载更多数据

  • 列表项点击：记录埋点，打开相应页面

5. 关键设计模式与技术

5.1 MVVM 架构模式

  • Model：数据模型，如 ConstructionSiteModel、FilterItem 等

  • View：视图组件，如 ConstructMainPage、ConstructionListBody 等

  • ViewModel：数据处理层，如 ConstructionSiteVM、ConstructionSiteListVM 等

  • 控制器：业务逻辑处理，如 ConstructionSiteController、WorkTypeController 等

5.2 中介者模式

FilterMediator 作为中介者，协调不同筛选状态间的交互，避免了筛选状态之间的直接耦合，使系统更易于维护和扩展。

5.3 状态管理

使用 ChangeNotifier 和 Provider 进行状态管理，实现了状态的集中管理和传递，简化了组件间的通信。

5.4 模板方法模式

BaseFilterState 定义了筛选状态的基本接口和行为，各具体筛选状态类实现和扩展了这些行为，实现了代码复用和扩展。

5.5 组合模式

组件的层次结构使用了组合模式，大组件由小组件组成，形成树形结构，使得系统更易于理解和维护。

6. 性能优化策略

6.1 精细化重建控制

  • 使用 Consumer 精确控制需要重建的UI部分，避免整个页面重建

  • 按需通知监听器，避免不必要的重建

6.2 请求优化

  • 使用标志位（如 _isLoadingData）避免重复加载

  • 实现分页加载，避免一次性加载大量数据

  • 优化请求参数构建，减少不必要的参数

6.3 状态管理优化

  • 暂停/恢复筛选监听机制，避免触发连锁反应

  • 实现状态静默更新（silent update）机制，避免不必要的通知

  • 精确控制状态更新范围，避免全局状态变化

7. 错误处理机制

7.1 全面的错误状态管理

  • 在数据加载失败时设置错误状态

  • 在UI层显示友好的错误提示

  • 提供重试功能，允许用户快速恢复

7.2 细粒度错误处理

  • 区分网络错误和数据解析错误

  • 为不同组件提供独立的错误处理

  • 错误状态不影响其他功能的正常使用

8. 可扩展性设计

8.1 模块化设计

  • 各组件职责单一，易于替换和升级

  • 清晰的接口定义，方便集成新功能

  • 分层架构使得修改一层不影响其他层

8.2 可配置性

  • 筛选条件可通过配置动态加载

  • 工作类型筛选组可根据用户角色动态显示

  • 列表展示可根据需求灵活配置

9. 用户体验优化

9.1 状态指示

  • 加载状态清晰展示

  • 错误状态友好提示

  • 空状态适当引导

9.2 操作流畅性

  • 下拉刷新和上拉加载更多体验流畅

  • 筛选操作反馈及时

  • 列表滚动性能优化

9.3 数据一致性

  • 确保各组件状态同步

  • 避免数据不一致导致的界面错乱

  • 保持用户操作的连贯性

10. 未来展望

10.1 进一步优化方向

  • 引入缓存机制，减少重复请求

  • 优化首屏加载速度

  • 进一步减少代码耦合

10.2 功能扩展方向

  • 增强筛选能力，支持更复杂的筛选条件

  • 添加数据分析功能，提供更多数据洞察

  • 优化离线体验，支持部分离线操作

11. 总结

工地模块 V2 版本采用了 MVVM 架构模式，结合状态管理和中介者模式，实现了高内聚低耦合的代码结构。通过清晰的责任划分和数据流程设计，提高了代码可维护性和可扩展性，同时优化了用户体验。该架构为后续功能扩展和性能优化提供了良好的基础，是一次成功的架构升级。