筑安 StructSafe

校园建筑结构健康监测 · HarmonyOS 应用（双数据源：本地模拟演示引擎 + 南向实时采集，设置页一键切换）。

演示声明：模拟模式下的全部设备、读数、告警、统计数据均为明确标注的模拟演示数据，不构成真实建筑安全评估依据；实时模式下数据来自南向板卡经聚合服务转发的真实采集值。

工程信息

项	值
工程路径	`D:\StructSafe`
SDK / 目标	HarmonyOS 6.0.1(21) · Stage 模型 · Phone
技术栈	ArkTS + ArkUI（声明式），无 WebView、无 H5 套壳
包名	`com.example.structsafe`
入口	`entry/src/main/ets/entryability/EntryAbility.ets` → `pages/Index.ets`
持久化	`@kit.ArkData` relationalStore（本地 SQLite：devices / measurements / events / event_actions / demo_config）
交付产物	`dist/entry-default-unsigned.hap`（未签名，模拟器可直装）

功能总览

4 个主 Tab：总览 / 监测 / 告警 / 分析
8 个二级页：设备详情、指标详情、告警详情、处置表单、系统设置 + 首次引导流
双数据源（设置页运行时切换，配置持久化）：
- 模拟引擎：1 秒采样节拍器，平滑漂移模型生成细微稳定扰动
- 实时采集：HTTP 轮询聚合服务 /hist（5Hz 原始帧 → 1Hz 落库），指数退避容错（1s→2s→4s→15s）、单板掉线「数据陈旧」、回前台立即补拉
7 个监测指标：倾角 / 振动 / 烟雾（告警型，南向同源阈值）+ 人体 / 光照 / 温度 / 湿度（观测型，仅展示）
告警闭环：连续 3 采样超限触发 → 连续越限自动升级（含 ESCALATE 审计）→ 确认 → 处置归档 → 台账；conditionStatus（异常/恢复）与 handlingStatus（待确认/处理中/已归档）解耦
统计图表：Canvas 原生绘制折线（空洞断开、点选读数）/ 柱状 / 环形，7 天 / 30 天切换；均值 / 极值 / 超限次数全部来自本地真实样本 SQL 聚合
历史真实：趋势数据以 SQLite measurements 为唯一跨重启来源，重启后立即恢复完整历史波形
重置机制：重置并装载可预测种子 / 清空为干净状态，均有二次确认

目录结构

entry/src/main/ets/
├── entryability/EntryAbility.ets   # 应用入口 + 数据源生命周期
├── pages/                          # Index + 10 个业务页面
├── components/                     # Icons / AppIcon / Widgets / Charts
├── hardware/                       # 【预留硬件接口层】数据源与协议
│   ├── IDataSource.ets             #   数据源接口 + 链路状态
│   ├── DataSourceFactory.ets       #   运行时切源（配置持久化）
│   ├── MockDataSource.ets          #   模拟数据源（包装演示引擎）
│   ├── HardwareDataSource.ets      #   实时数据源（HTTP 轮询 /hist）
│   ├── HardwareProtocol.ets        #   固件 ASCII 报文解析
│   ├── TelemetryBuilder.ets        #   判级与建筑聚合（两源共用）
│   └── LiveBridge.ets              #   5Hz 实时帧 → 1Hz 落库桥
├── data/
│   ├── AppStore.ets                # 单一状态源（AppStorage 广播刷新）
│   ├── DemoRepository.ets          # 业务逻辑（落库、规则、事件、审计）
│   ├── DemoEngine.ets              # 1s 采样节拍器（模拟模式）
│   ├── LocalDatabase.ets           # relationalStore 封装（建表/事务/聚合查询）
│   ├── SeedData.ets                # 可预测演示种子
│   └── NavBus.ets                  # 导航传参
├── services/                       # MetricCatalog / DateService / AggregationService
├── theme/Theme.ets                 # Design Tokens（颜色/尺寸/字号）
└── models/Models.ets               # 枚举与接口

构建与运行

DevEco Studio（推荐）

用 DevEco Studio 6.0.1 打开 D:\StructSafe，等待 Sync 完成。
连接模拟器（如 Mate 70 Pro）或真机，点击 Run。

命令行（hvigor）

# PowerShell（DevEco 自带工具链）
$env:NODE_HOME = "D:\DveEco Studio\DevEco Studio\tools\node"
$env:DEVECO_SDK_HOME = "D:\DveEco Studio\DevEco Studio\sdk"
& "$env:NODE_HOME\node.exe" "D:\DveEco Studio\DevEco Studio\tools\hvigor\bin\hvigorw.js" `
  --mode module -p product=default -p module=entry@default -p buildMode=debug assembleHap --no-daemon

产物：entry/build/default/outputs/default/entry-default-unsigned.hap

安装运行（模拟器，未签名 HAP）

hdc install -r entry\build\default\outputs\default\entry-default-unsigned.hap
hdc shell aa start -a EntryAbility -b com.example.structsafe

真机分发/上架需在 DevEco 中配置签名（当前 signingConfigs 留空，构建仅 WARN 跳过签名）。

实时模式部署（南向对接）

数据链路：板卡 A/B（WiFi → UDP 5000）→ PC 聚合服务 server.py → 手机/模拟器 App（HTTP 轮询 8080）

状态（2026-10-16）：双板均已改装固件并烧录完成，脱离 USB 串口桥接、纯走 WiFi 运行，App 实时采集实测 速率 4.7 包/秒 · 解析失败 0 · 板A/板B 秒级刷新。

硬件资料（`_hardware_ref/`）

南向硬件侧的完整交付快照，**详见 _hardware_ref/README.md**：

内容	路径
聚合服务（UDP 5000 → HTTP 8080，纯标准库）	`_hardware_ref/current/server.py`
板卡实时监控页（浏览器打开 `127.0.0.1:8080`）	`_hardware_ref/current/index.html`
板A 结构站固件源码（MPU6050）	`_hardware_ref/current/sensor_sim_new.c`
板B 环境站固件源码（MQ-2 / PIR / GL5516 / AHT20）	`_hardware_ref/current/sensor_env_b.c`
最终烧录固件（已打现场参数补丁，板A / 板B）	`_hardware_ref/patched_oppo/ws63-liteos-app_{A,B}_OPPO.fwpkg`

前置条件（三项必须同时成立）

项	值	说明
热点	SSID `OPPO`、密码 `Ssm060328@..`（2.4GHz）	已作为编译期常量写入两块板的固件
PC 地址	`10.91.143.69`（已钉为静态）	板卡固件 `UDP_TARGET_IP` 指向它
板卡固件	`_hardware_ref/patched_oppo/ws63-liteos-app_{A,B}_OPPO.fwpkg`	已烧录进板；换热点/换 PC 地址需重新改装并烧录

启动步骤

# 1. PC 启动聚合服务（UDP 5000 收板卡上报，HTTP 8080 供 App 拉取）
D:\StructSafe\_tools\start_server.bat

# 2. 确认双板数据在流入（每 2 秒一行，两列均应为 OK）
D:\StructSafe\_tools\heartbeat.bat

# 3. App 设置页 → 南向数据源 → 选「实时采集」→ 填服务地址 → 保存
#    实测可用：http://10.91.143.69:8080   （PC 局域网地址，电脑已钉静态）
#    备选：    http://10.0.2.2:8080       （模拟器 NAT 映射宿主回环）
#    → 点「测试连接」，应显示速率与累计帧

防火墙（关键，否则板卡数据进不来）

Windows 防火墙中「首次运行该程序」时自动生成的程序级阻止规则优先级高于放行规则，会静默丢弃板卡入站包（表现为「端口在听、规则也在、包就是不进来」）。修复工具：_tools/fw_fix_udp5000.bat（管理员，禁用 Name=Python 的入站 Block 规则，可回滚）。App 侧 HTTP 8080 入站是被同一条 TCP Block 拦截，一并解决。

常用工具（`_tools/`）

工具	用途
`start_server.bat`	启动聚合服务（后台无窗口进程）
`heartbeat.bat`	心跳监视：每 2 秒打印板A/板B 帧龄 + 速率，掉线立即标 `STALE`
`precheck.bat`	演示前四项自检（IP / 服务 / 板卡 / 数据）
`ip_pin_on.bat` / `ip_pin_off.bat`	把 PC 地址钉为静态 `10.91.143.69` / 一键还原自动获取
`dns_fix.bat`	钉静态 IP 后补回 DNS 服务器（否则本机域名解析失效）
`mock_boards.py`	无板卡时灌包替代真实板卡：`python _tools/mock_boards.py --rate 5 --scenario normal`（场景：normal / warn / crit / smoke / escalate，单板 `--board A`）
`serial_bridge.py`	备用通道：USB 串口 → UDP 127.0.0.1:5000（板卡无线不可用时使用，App/服务零改动）

真机安装需在 DevEco 中配置签名（signingConfigs 当前为空，模拟器可直装未签名 HAP）。

快速体验路径

首次启动 → 引导页 →「进入演示系统」。
总览页观察指标每秒刷新与趋势曲线累计。
设置页 →「一级预警」→ 回总览：主卡变「发现异常指标」、待处理 +1、告警角标出现。
告警中心 → 事件详情 →「确认告警」→「填写处置记录」→ 归档；台账与统计同步。
设置页 →「测点离线」→ 10 秒后总览显示离线与历史缓存值。
分析页切换 7 天 / 30 天核对计数一致性。
设置页底部「重置并装载演示种子」恢复出厂演示数据。

文档与证据

ENV_REPORT.md：环境实测（IDE/SDK/设备/构建）
TEST_REPORT.md：T01–T18 逐项 PASS/FAIL + F1–F8 南向对接实测记录 + 缺陷修复记录
提交材料/：校赛三项提交物（设计方案 .docx、演示视频录制脚本、数据库文件 .db）
_hardware_ref/README.md：南向硬件体系说明（拓扑、硬件配置、固件参数、接口、运行步骤）
docs/接口/：南北向协议规范、实施手册、P1–P5 各阶段验证报告、固件改装与烧录操作卡
docs/shots/：模拟器运行截图（按用例编号命名，含 P1–P5 与 F6 验收序列）
docs/logs/：各阶段 hvigor 构建日志