# 运维管理台（Ops Console）

设备/系统运维管理台移动端，覆盖 **Android / iOS / HarmonyOS (OpenHarmony)** 三端，共用同一套 `lib/` Dart 代码。  
默认对接真实「爱视后台」（PHP/CodeIgniter），同时保留 mock 开关供无后端时演示。

## 技术栈

- **Flutter 3.22+**（Dart 3）
- **go_router** —— 声明式路由（登录重定向、底部导航多分支）
- **flutter_riverpod** —— 状态管理（登录态 / 设备与告警数据 / 主题模式）
- **dio** —— HTTP 客户端（Bearer 鉴权 + 统一信封解包 + 401 刷新重试；可选 mock 拦截器）
- **intl** —— 日期时间格式化

## API 配置（lib/utils/constants.dart）

| 常量           | 默认值                   | 说明                                               |
| ------------ | --------------------- | ------------------------------------------------ |
| `useMock`    | `false`               | `false` 对接真实后端；`true` 由 MockInterceptor 本地返回示例数据 |
| `apiBaseUrl` | `http://58.220.83.58` | 真实后端 origin                                      |
| `apiPrefix`  | `/api`                | 接口统一前缀；最终 URL = `apiBaseUrl + /api + path`       |

## HTTP 通用规则

- **鉴权**：请求头 `Authorization: Bearer <token>`，不使用 Cookie。
- **Content-Type**：`application/json; charset=utf-8`。
- **防缓存**：GET 参数与 POST body 均自动附加 `t` = 毫秒时间戳。
- **统一响应**：`{ code:int, msg:string, data:T }`，成功码 `code ∈ {0, 200}`，  
  由 `ApiInterceptor` 自动解包（service 层拿到的即 `data`）；非成功码抛出 `ApiException(code, msg)`。
- **401 处理**：业务 `code=401` 或 HTTP 401 时，自动用 refreshToken 调  
  `POST /api/sys/refresh {refreshToken}` 换新 token 并**原样重试一次**；  
  仍失败则清空登录态并跳转登录页（经 `ApiClient.onUnauthorized` → `authProvider` → 路由 redirect）。

## 真实接口清单

| 接口                              | 方法   | 说明                                                                                                                                          |
| ------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sys/login`                | POST | 登录，body `{username,password,captcha,uuid}` → `{token,expire,refreshToken,refreshExpire,orgId,orgType,superAdmin,roleNames}`                 |
| `/api/sys/refresh`              | POST | 刷新令牌，body `{refreshToken}` → `{token,expire,refreshToken,refreshExpire}`（拦截器自动调用）                                                           |
| `/api/sys/logout`               | POST | 登出                                                                                                                                          |
| `/api/sys/user/info`            | GET  | 当前用户信息（登录后自动拉取补充显示名）                                                                                                                        |
| `/api/device/info/list`         | GET  | 设备列表，params `page,limit,status,mac,deviceSn,deviceUid,groupId,storeOrgId`；响应 `{list,totalCount}` / `{page:{list,totalCount}}` / 直接数组三种形态均兼容 |
| `/api/device/info/info/{id}`    | GET  | 设备详情                                                                                                                                        |
| `/api/device/command/sendByMac` | POST | 按 MAC 下发指令，body `{mac,command,data}`                                                                                                        |
| `/api/device/command/sendByOrg` | POST | 按组织批量下发指令，body `{orgId,command,data}`                                                                                                       |

指令 `command` 取值（见 `DeviceCommand` 常量）：`powerOff` / `reboot` / `screenshot` /  
`themeUpdate` / `versionUpdate` / `marqueeUpdate` / `weatherUpdate` / `mediaZoneVol` /  
`defaultVol` / `themeClear` / `cacheClear` / `storeExpire` / `storeDisable` /  
`passwordUpdate` / `worldAd`。

**指令下发 UI 属下一轮迭代**：当前仅实现 `DeviceService.sendCommandByMac/sendCommandByOrg`  
service 方法，界面未接入按钮。

## 告警推导（real 模式）

真实后端无 alerts 端点。real 模式下告警由设备列表推导：  
`offline → critical`（设备离线）、`warning → warning`（设备指标异常），  
在线设备映射为 `info` 级别但不产生告警条目。mock 模式仍使用内置示例告警。

## ⚠️ 权威构建路径（必读）

本仓库中的 `android/`、`ios/`、`ohos/` 原生壳是**手写的参考起点**，已包含可资源编译的最小配置  
（图标、启动页、storyboard、媒体占位资源等）。但以下内容**只能由 Flutter 工具链生成，无法手写**：

| 生成物                                                                  | 所属平台      | 生成命令                                       |
| -------------------------------------------------------------------- | --------- | ------------------------------------------ |
| `gradlew` / `gradle-wrapper.jar` / `local.properties`                | Android   | `flutter create`                           |
| `Runner.xcodeproj` / `Generated.xcconfig` / `AppFrameworkInfo.plist` | iOS       | `flutter create`                           |
| `hvigorfile.ts` / `oh_modules` 依赖链接                                  | HarmonyOS | `flutter create --platforms=ohos`（鸿蒙分支工具链） |

**因此首次构建前，必须在本机 Flutter 环境执行一次 `flutter create` 补齐工具链生成物：**

```bash
cd ops-console

# 一次性补齐三端原生壳的缺失文件（不会覆盖已存在的自定义文件）
flutter create --platforms=android,ios,ohos .
```

> 注意：
>
> 1. `flutter create` 只补缺、不覆盖已有文件，仓库中已定制的  
>    `android/app/build.gradle`（applicationId、JDK 17）、`AndroidManifest.xml`（应用名「运维管理台」）  
>    会被保留。
> 2. HarmonyOS 端需使用 **Flutter OpenHarmony SDK**（`flutter-flutter` 鸿蒙分支）执行上述命令；  
>    标准 Flutter SDK 不认识 `--platforms=ohos`。

## 环境要求

| 项目          | 要求                                                              |
| ----------- | --------------------------------------------------------------- |
| Flutter SDK | 3.22 及以上（`flutter --version` 确认，Dart >= 3.4）                    |
| Android     | Android Studio + Android SDK（API 21+），JDK 17                    |
| iOS         | macOS + Xcode 15+、CocoaPods                                     |
| HarmonyOS   | DevEco Studio + Flutter OpenHarmony SDK（`flutter-flutter` 鸿蒙分支） |

## 构建命令

```bash
# 0. 首次：补齐全端工具链生成物 + 安装依赖
flutter create --platforms=android,ios,ohos .
flutter pub get
```

### Android

```bash
flutter run            # 连接设备或模拟器后直接运行
flutter build apk      # 打包 APK（debug 签名，正式发布需配置签名）
```

### iOS（需 macOS + Xcode）

```bash
flutter pub get
cd ios && pod install && cd ..   # 安装 CocoaPods 依赖
flutter run
flutter build ios
```

### HarmonyOS (OpenHarmony)

需使用 **Flutter OpenHarmony SDK**（鸿蒙分支的 flutter 工具链）：

```bash
# 补齐/校验 ohos 平台工程
flutter create --platforms=ohos .

# 运行（连接鸿蒙设备/模拟器）
flutter run

# 构建 hap/app 包
flutter build ohos
```

也可在 DevEco Studio 中打开 `ohos/` 目录进行签名配置与构建（`build-profile.json5` 中的  
`signingConfigs` 为空，需在 DevEco 中配置签名后才能出 release 包）。

## 目录结构

```
ops-console/
├── pubspec.yaml                  # 依赖声明
├── analysis_options.yaml         # 静态分析规则（flutter_lints）
├── lib/
│   ├── main.dart                 # 入口：ProviderScope + MaterialApp.router
│   ├── app/
│   │   ├── theme.dart            # 浅色/深色主题（主色科技蓝 #2E7DFF）
│   │   └── router.dart           # go_router 路由表 + 未登录重定向
│   ├── utils/
│   │   ├── constants.dart        # 全局常量（useMock / apiBaseUrl / mock 账号等）
│   │   └── formatters.dart       # 时间/百分比/字节/运行时长格式化
│   ├── models/
│   │   ├── device.dart           # Device + DeviceStatus + DeviceMetrics + DeviceCommand
│   │   ├── alert.dart            # Alert + AlertLevel(critical/warning/info)
│   │   └── user.dart             # User
│   ├── services/
│   │   ├── api_client.dart       # Dio 单例 + ApiInterceptor（Bearer/t/解包/401重试）
│   │   │                         #   + MockInterceptor（useMock=true 时）+ TokenStore（内存态）
│   │   ├── auth_service.dart     # 登录/登出/用户信息（真实接口）
│   │   └── device_service.dart   # 设备列表/详情/指令/告警推导
│   ├── providers/
│   │   ├── auth_provider.dart    # 登录态（authProvider，注册 onUnauthorized）
│   │   ├── devices_provider.dart # 设备/告警数据（devicesProvider 等）
│   │   └── theme_provider.dart   # 主题模式（默认深色）
│   ├── widgets/
│   │   ├── status_chip.dart      # 状态标签
│   │   ├── metric_card.dart      # 指标卡片
│   │   ├── device_list_tile.dart # 设备列表项
│   │   └── app_bottom_nav.dart   # 底部导航（设备/告警/设置）
│   └── screens/
│       ├── login/login_page.dart        # 登录页
│       ├── home/device_list_page.dart   # 首页：搜索 + 设备列表
│       ├── home/device_detail_page.dart # 设备详情：指标卡（real 模式显示 “—”）
│       ├── alerts/alerts_page.dart      # 告警列表
│       └── profile/settings_page.dart   # 设置：主题/语言占位/关于/退出
├── android/                      # Android 壳（Gradle + Manifest + res 资源）
├── ios/                          # iOS 壳（Runner + Flutter xcconfig + Podfile）
└── ohos/                         # OpenHarmony 壳（stage 模型）
```

## 路由表

| 路径            | 页面   | 说明            |
| ------------- | ---- | ------------- |
| `/login`      | 登录页  | 未登录时自动重定向到此   |
| `/`           | 设备列表 | 底部导航第 1 个 tab |
| `/device/:id` | 设备详情 | 从设备列表进入       |
| `/alerts`     | 告警中心 | 底部导航第 2 个 tab |
| `/settings`   | 设置   | 底部导航第 3 个 tab |

## Mock 数据说明

- 将 `AppConstants.useMock` 改为 `true` 即进入演示模式：所有请求由  
  `MockInterceptor` 本地拦截，返回与真实后端一致的 `{code,msg,data}` 信封  
  （5 台设备含示例运行指标、5 条示例告警），不发起真实网络请求。
- mock 演示登录账号：`admin` / `123456`。
- 真实模式（默认）下请使用后端分配的账号登录。

## 主题

- 默认 **深色** 主题，主色科技蓝 `#2E7DFF`。
- 在「设置 → 主题模式」可切换 深色 / 浅色 / 跟随系统。

## 已知限制

1. **token 仅内存态**：为规避鸿蒙端插件兼容问题未引入 shared_preferences，  
   应用重启后需重新登录（持久化属后续迭代，需评估鸿蒙插件支持度）。
2. **验证码占位**：登录接口的 `captcha/uuid` 字段当前传空串（登录页 UI 无验证码输入，  
   属下一轮迭代）；若后端强制校验验证码，需先补 UI。
3. **运行指标缺失**：真实后端不提供 CPU/内存/磁盘/网络指标，real 模式设备详情页  
   指标卡显示 “—”；`useMock=true` 时显示示例指标。
4. **指令下发 UI 未接入**：service 层已实现，界面按钮属下一轮迭代。
5. **图标为占位资源**（Android 自适应图标 / iOS 空 AppIcon / ohos 1x1 PNG），正式发布前请替换。
6. `android/gradlew`、`ios/Runner.xcodeproj`、`ohos/hvigorfile.ts` 等工具链生成物未入库，  
   按上文「权威构建路径」执行 `flutter create` 后自动生成。