.

.gitignore

@@ -50,3 +50,9 @@ app.*.map.json
 
 # ai相关
 ai_work/
+
+## 文档相关
+测试方案.md
+对接方案.md
+技术方案.md
+上手帮助.md
\ No newline at end of file

技术方案.md

-# 智慧酒店 App 技术方案
+# 智慧酒店 App 技术方案
@@ -149,6 +149,58 @@ lib/
 
 ---
 
+## 3.1 数据模型（BO）规范
+
+所有业务数据模型统一定义在 `models/bo/` 目录下，按模块分文件。**当前状态**：大部分数据模型散落在各页面的 `state.dart` 文件中（如 `AlarmItem`、`InspectionDevice`、`RoomInfo` 等），需要在对接时迁移到 `models/bo/`。
+
+### 建议的 BO 文件组织
+
+```
+models/bo/
+├── user_info_bo.dart          # 用户信息（已有）
+├── alarm_bo.dart              # 告警相关：AlarmItem, AlarmInfo, AlarmDetail
+├── device_bo.dart             # 设备相关：DeviceInfo, EquipmentItem, RoomDevice
+├── inspection_bo.dart         # 巡检相关：InspectionDevice, InspectionRecord, InspectionItem
+├── topology_bo.dart           # 拓扑相关：TopologyNode
+├── energy_bo.dart             # 能耗相关：ZoneData, EnergyOverview, MeterData
+├── room_bo.dart               # 房间相关：RoomInfo, RoomDeviceStatus, RoomStatus
+├── rule_bo.dart               # 规则相关：RuleInfo
+└── report_bo.dart             # 报告相关：ReportMetrics, WeeklyPowerData
+```
+
+### BO 模型定义规范
+
+```dart
+// 必须使用 Equatable，提供 copyWith
+class SomeBO extends Equatable {
+  final String id;
+  final String name;
+  // ... 字段
+
+  const SomeBO({required this.id, required this.name});
+
+  // 从 JSON 反序列化（用于 API 响应解析）
+  factory SomeBO.fromJson(Map<String, dynamic> json) {
+    return SomeBO(
+      id: json['id'] as String,
+      name: json['name'] as String,
+    );
+  }
+
+  // 序列化为 JSON（用于 API 请求体）
+  Map<String, dynamic> toJson() => {'id': id, 'name': name};
+
+  // copyWith（用于状态更新）
+  SomeBO copyWith({String? id, String? name}) =>
+      SomeBO(id: id ?? this.id, name: name ?? this.name);
+
+  @override
+  List<Object?> get props => [id, name];
+}
+```
+
+---
+
 ## 4. 核心技术说明
 
 ### 4.1 状态管理：BLoC + Cubit
@@ -343,6 +395,47 @@ Token 过期:
 | 房间能耗 | `ReportRoomDetailRoute` | 楼层选择、房间网格、详情卡片 |
 | 规则管理 | `ReportRuleManagementRoute` | 规则卡片管理 |
 
+### 5.4 当前状态：Mock 数据阶段
+
+**页面 View 层已完成开发**，所有页面 UI 可正常渲染，但数据全部为硬编码 mock 数据。
+
+**现状分析**：
+
+| 层级 | 状态 | 说明 |
+|------|------|------|
+| View 层 | 已完成 | 所有页面 UI 组件已完成 |
+| State 层 | 已完成 | 各页面 State + copyWith 已定义 |
+| Cubit 层 | Mock 阶段 | `initData()` 中直接塞入 mock 数据，未调用 Service |
+| Service 层 | 仅 Auth | 只有 `AuthService` 存在，页面级 Service 全部缺失 |
+| Repository 层 | 仅 Auth | 只有 `AuthRepository` 存在，页面级 Repository 全部缺失 |
+| BO 模型 | 散落 | 数据模型定义在 state 文件中，未统一到 `models/bo/` |
+
+### 5.5 对接改造步骤（View 层不变）
+
+每个页面模块的改造遵循统一流程，**View 层代码无需修改**（因为 Cubit/State 接口不变）：
+
+```
+第一步：将 State 中的数据模型提取到 models/bo/ 目录
+第二步：新增 Repository（API 调用）
+第三步：新增 Service（业务逻辑）
+第四步：修改 Cubit：将 initData() 中的 mock 数据替换为 Service 调用
+第五步：在 main.dart 中注入 Service/Repository（如需要全局单例）
+```
+
+**改造示例**（以告警列表页为例）：
+
+```
+改造前：
+  AbnormalListCubit.initData() → 直接 emit(mockData)
+
+改造后：
+  AbnormalListCubit.loadData() → AbnormalListService.getAlarms()
+    → AbnormalListRepository.getAlarms() → DioRequest.get('/api/alarms')
+      → ResponseModel.data → AlarmListBO.fromJson() → emit(realData)
+```
+
+详细对接规范见 [对接方案.md](./对接方案.md)。
+
 ---
 
 ## 6. 依赖库清单