Files

txh 685fff27c8 ops-console v1.0.2 (versionCode 8) 源码入库

2026-09-03 18:01:05 +08:00

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 .

注意：

flutter create 只补缺、不覆盖已有文件，仓库中已定制的
android/app/build.gradle（applicationId、JDK 17）、AndroidManifest.xml（应用名「运维管理台」）
会被保留。

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。
在「设置 → 主题模式」可切换深色 / 浅色 / 跟随系统。

已知限制

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

12 KiB Raw Permalink Blame History Unescape Escape