# TEM Receiver — 瞬变电磁接收机手机 App

六通道瞬变电磁（TEM）接收机的移动端控制与数据采集软件，通过 WiFi TCP 连接设备，实现参数配置、实时波形显示、数据管理与导出。

## 功能概述

- **设备连接** — WiFi TCP 自动连接/重连/心跳保活
- **参数配置** — 通道数、发射频率、采样率、叠加次数、增益等全部参数下发
- **实时采集** — 单次/连续采集，实时波形显示（LIN/LOG 模式）
- **波形交互** — 全屏查看、双指缩放、单指拖拽、横屏支持
- **数据管理** — 工程-测线-测点三级管理，支持新建/删除/切换
- **数据导出** — CSV 导出、.tem 工程打包导出，支持分享到微信等 App
- **数据导入** — 导入 .tem 工程文件，恢复全部测线和波形数据
- **主题适配** — 自动跟随系统深色/浅色模式
- **设备状态** — 实时显示发射电流、电池电压、温度、GPS、SD 卡、姿态角

## 技术栈

| 类别 | 技术 |
|------|------|
| 框架 | React Native 0.85 + Expo SDK 56 |
| 语言 | TypeScript 6.0 |
| 路由 | expo-router (文件式路由) |
| 状态管理 | Zustand 5 (持久化) |
| 数据库 | expo-sqlite (SQLite WAL 模式) |
| 图表 | @shopify/react-native-skia |
| 手势 | react-native-gesture-handler + react-native-reanimated |
| TCP 通信 | react-native-tcp-socket |
| 文件压缩 | fflate (ZIP 压缩/解压) |

## 环境要求

| 工具 | 版本 |
|------|------|
| Node.js | >= 18 |
| npm | >= 9 |
| Android Studio | 最新版（含 Android SDK） |
| JDK | Android Studio 内置 JBR |
| ADB | Android SDK platform-tools |

### 环境变量（Windows）

```
JAVA_HOME = D:\Program Files\Android\Android Studio\jbr
ANDROID_HOME = D:\ProgramData\AndroidSdk
PATH += %JAVA_HOME%\bin;%ANDROID_HOME%\platform-tools
```

## 快速开始

### 1. 安装依赖

```bash
cd TriloopTem_App
npm install
```

### 2. Debug 运行

手机通过 USB 连接电脑，开启 USB 调试：

```bash
npx expo run:android
```

或使用项目自带脚本：

```bash
run-android.bat
```

### 3. Release 构建

双击 `build-release.bat`，或手动执行：

```powershell
$env:JAVA_HOME = "D:\Program Files\Android\Android Studio\jbr"
cd android
.\gradlew.bat assembleRelease
```

APK 输出路径：`android/app/build/outputs/apk/release/app-release.apk`

### 4. 安装到手机

```bash
adb uninstall com.triloop.temreceiver
adb install android/app/build/outputs/apk/release/app-release.apk
```

### 5. iOS 构建

需要 macOS + Xcode + Apple Developer 账号：

```bash
npx expo prebuild --platform ios
npx react-native run-ios
```

或使用 EAS 云构建（无需 Mac）：

```bash
npx eas build --platform ios
```

## 代码结构

```
TriloopTem_App/
├── app/                          # 页面路由 (expo-router 文件式路由)
│   ├── _layout.tsx               # 根布局，初始化数据库
│   ├── connect.tsx               # 连接页面
│   ├── +not-found.tsx            # 404 页面
│   └── (tabs)/                   # Tab 页面
│       ├── _layout.tsx           # Tab 栏配置
│       ├── wave.tsx              # 波形页 — 实时采集与波形显示
│       ├── records.tsx           # 测点页 — 测点列表与数据管理
│       ├── profile.tsx           # 剖面页 — 剖面分析与门窗配置
│       └── projects.tsx          # 工程页 — 工程/测线/测点管理
│
├── src/
│   ├── protocol/                 # 设备通信协议
│   │   ├── constants.ts          # 功能码、频率表、增益表
│   │   ├── packet.ts             # 发送包构建 (Setup/Start/Stop)
│   │   ├── parser.ts             # 接收帧解析 + ADC 转换
│   │   └── types.ts              # 协议数据类型定义
│   │
│   ├── services/                 # 业务服务层
│   │   ├── TcpService.ts         # TCP 连接管理 (连接/重连/心跳)
│   │   ├── DeviceService.ts      # 设备交互 (命令发送/ACK/数据处理)
│   │   ├── StorageService.ts     # SQLite 数据持久化
│   │   ├── BinLoader.ts          # TEMF 二进制波形文件读写
│   │   └── TemBundle.ts          # .tem 工程打包/解包 (ZIP)
│   │
│   ├── stores/                   # 状态管理 (Zustand)
│   │   ├── dataStore.ts          # 会话/帧数据/工程关联
│   │   ├── deviceStore.ts        # 设备配置/遥测状态
│   │   └── connectionStore.ts    # TCP 连接状态
│   │
│   ├── components/               # 可复用组件
│   │   ├── WaveformChart.tsx     # Skia 波形图表 (缩放/拖拽)
│   │   ├── ParamForm.tsx         # 参数配置表单
│   │   ├── SessionSelector.tsx   # 测线选择器
│   │   ├── NoProjectGate.tsx     # 无工程提示页
│   │   ├── device/
│   │   │   └── GlobalStatusBar.tsx  # 全局状态栏
│   │   └── modals/
│   │       └── ConnectModal.tsx  # 连接弹窗
│   │
│   ├── hooks/                    # 自定义 Hooks
│   │   ├── useDevice.ts          # 设备操作封装
│   │   └── useWaveform.ts        # 波形数据处理与降采样
│   │
│   ├── design/
│   │   └── tokens.ts             # 主题色板 (深色/浅色) + useTheme()
│   │
│   └── utils/
│       ├── export.ts             # CSV 导出与文件分享
│       ├── format.ts             # 数值/坐标/时间格式化
│       └── storage.ts            # Zustand 持久化存储适配
│
├── assets/images/                # 图标与闪屏资源
├── docs/
│   └── commercial-audit.md       # 商业化审计报告
├── android/                      # Android 原生工程
├── app.json                      # Expo 配置
├── package.json                  # 依赖管理
├── build-release.bat             # Release 一键构建脚本
└── run-android.bat               # Debug 运行脚本
```

## 通信协议

### 帧格式

```
┌──────────┬──────┬─────┬────────────┬────────────┐
│ Magic 4B │ Flag │ CMD │ Length     │ Tail/Len   │
│ 68 68    │ FF/FE│     │ 2B or 4B  │ 68 68 / -- │
│ FF FF    │      │     │           │            │
└──────────┴──────┴─────┴────────────┴────────────┘
```

- **Flag bit0=1** (0xFF)：2 字节长度 + `68 68` 尾部（App 发送使用）
- **Flag bit0=0** (0xFE)：4 字节长度，无尾部（设备回复使用）

### 功能码

| 方向 | CMD | 说明 |
|------|-----|------|
| App→设备 | 0x01 | 参数配置 (Setup) |
| App→设备 | 0x02 | 连续采集启动 |
| App→设备 | 0x03 | 单次采集 |
| App→设备 | 0x04 | 停止采集 |
| App→设备 | 0x08 | 分帧传输 |
| 设备→App | 0x81 | 配置 ACK |
| 设备→App | 0x82 | 连续采集 ACK |
| 设备→App | 0x83 | 单次采集 ACK |
| 设备→App | 0x84 | 停止 ACK |
| 设备→App | 0x85 | 测量数据帧 |
| 设备→App | 0x95 | 组合源数据帧 |

### ADC 转换公式

```
电压(μV) = (raw_int32 / 0x7FFFFFFF) × 5.0 × 1e6 / gain
发射电流(A) = (raw_uint32 / 0x7FFFFFFF) × 5.0 × 50
```

### 设备默认参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| 通道数 | 3 | 1-6 通道 |
| 发射频率 | code 5 = 16Hz | 0.5Hz ~ 64Hz |
| 采样率 | code 0 = 250kHz | 250kHz ~ 48Hz |
| 采样深度 | 2000 | 每通道采样点数 |
| 叠加次数 | 32 | 1-16383 |
| 增益 | code 3 = 1× | 1/8× ~ 128× |
| 回传方式 | WiFi | USB/P900/WiFi |
| 补偿电阻 | 12 | |
| 补偿去使能延时 | 60 | |

## 数据管理

### 三级结构

```
工程 (Project)
 └── 测线 (Session)
      └── 测点 (Frame)
           ├── 元数据 (GPS/电流/温度/姿态角...)
           └── 波形数据 (.bin 文件)
```

### 数据库表

- `projects` — 工程信息
- `sessions` — 测线，必须归属工程
- `frames` — 测点，关联测线和 .bin 波形文件

### 导出格式

- **CSV** — 测线级导出，包含所有测点的元数据和各通道峰值
- **.tem** — 工程级导出，ZIP 压缩包含 `project.json` 和所有 `.bin` 波形文件

### TEMF 二进制格式

每个测点的波形数据存储为 `.bin` 文件（TEMF v1 格式）：
- 64 字节文件头：通道数、采样深度、GPS、电流、温度、姿态角等
- 数据区：int32 LE，按通道顺序存储