tangxiaohui/CloudHome-Ops
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
main
CloudHome-Ops/README.md

12 KiB
Raw Permalink Blame History

运维管理台（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 补齐工具链生成物：

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 鸿蒙分支）

构建命令

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

Android

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

iOS（需 macOS + Xcode）

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

HarmonyOS (OpenHarmony)

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

# 补齐/校验 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 后自动生成。