# OPH_monitoring

**Repository Path**: intasect_1/oph_monitoring

## Basic Information

- **Project Name**: OPH_monitoring
- **Description**: 养老院监控系统
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-10
- **Last Updated**: 2025-11-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OPH Monitoring

养老院实时数据监控系统，负责接收外部系统上传的 19 字节二进制数据、转换为十六进制字符串并写入本地 `data/data.json`，同时提供 React Dashboard 与查询工具进行人工验证。

## ✨ 功能特性

- **FastAPI + JSON 文件存储**：`POST /api/v1/data/receive` 接收数据并校验 Header、长度；`GET /api/v1/data/query` 按时间范围返回结果。
- **轻量级 TCP 接入**：默认监听 `3001` 端口，硬件仅需发送 19 字节原始帧即可，由后台转换写入 JSON。
- **全链路日志与错误处理**：统一异常拦截、跨域 (CORS) 全放开，日志写入 `logs/app.log`。
- **React 组件**：Dashboard 实时列表（支持 1s~60s 自动刷新、实时删除反馈）、ByteTable 字节解析视图、时间段查询页面（默认以“当前时间 + 向前24小时”窗口自动查询且实时倒序展示）。
- **数据维护**：Dashboard 一键“删除所有数据”，同时触发后端 `DELETE /api/v1/data` 清空 `data.json`。
- **自动化测试**：后端 38 个 Pytest 用例（含集成/CORS/存储），前端 Vitest 覆盖 Dashboard、QueryPage、TimeRangePicker 等。
- **一体化部署**：后端可直接托管前端 `dist` 到 `/dashboard`，同端口即可完成公网访问。

## 🚀 快速开始

```bash
git clone <repo>
cd oph_monitoring

# Backend
cd backend
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

# Frontend
cd ../frontend
npm install
npm run dev
```

默认 API Base URL：`http://localhost:8000/api/v1`。在前端开发模式可通过 `VITE_API_BASE_URL` 指向后端。

## 📦 部署

完整的服务器环境准备、端口开放、systemd、Nginx、测试数据传输及验证清单已在 [`DEPLOYMENT_GUIDE.md`](DEPLOYMENT_GUIDE.md) 中列出。生产环境建议：

1. 按指南创建 Python 虚拟环境并运行 `./run_tests.sh` 验证。
2. 在 `frontend` 执行 `npm run build`，保留 `dist/` 以便后端自动挂载。
3. `uvicorn app.main:app --host 0.0.0.0 --port 8000` 运行后即可通过 `/dashboard` 访问页面。
4. 云服务器开放 8000（REST + Dashboard）与 3001（TCP 接入）端口，或通过 Nginx 反代并启用 HTTPS。

## 📂 目录概览

```
backend/     # FastAPI 应用与运行脚本
frontend/    # React + Vite 前端
data/        # JSON 数据存储 (data.json)
logs/        # 后端日志
DEPLOYMENT_GUIDE.md
DEVELOPMENT_TASKS.md
```

## 🧪 测试

```bash
# Backend
cd backend
./run_tests.sh        # 自动创建虚拟环境 + pytest

# Frontend
cd frontend
npm test -- --run
```

## 🧭 API 速览

- `POST /api/v1/data/receive`
  Header: `X-Source: OPH_monitoring`
  Body: 19 字节二进制数据
  返回：`{ success, message, timestamp }`

- `GET /api/v1/data/query?start_time=&end_time=`
  缺省 start/end 时自动使用配置默认值；返回 `{ total, data: [{ timestamp, data }] }`

- `GET /health` / `GET /api/v1/health` 健康检查  
- `GET /docs` / `GET /api/v1/docs` 返回 Swagger/Redoc 文档地址

### 轻量级 TCP 接入网关（默认端口 3001）

当终端无法承载 HTTP 头部导致一次发送 >60 字节时，可通过内置 TCP 网关推送 19 字节帧：

1. 连接 `tcp://<server-ip>:3001`（环境变量 `BINARY_SERVER_HOST/BINARY_SERVER_PORT/BINARY_SERVER_ENABLED` 可覆盖）。
2. 直接发送 19 字节原始数据，服务器会立即存储并返回 `OK <timestamp>` 换行。
3. 若存储失败返回 `ERR <error>`，客户端可重发。

后续仍可用 REST API 或前端查询这些数据，二进制入口与 HTTP 接口共享同一存储文件。

### 发送 19 字节测试数据

推荐使用 `send_pyload` 脚本（跨 macOS/Windows）：
```bash
# macOS/Linux
./send_pyload --url http://az05.nick3.xyz:3000/api/v1/data/receive \
              --hex A259010F050201040207D1050907011C00ABCD

# 或使用二进制文件
./send_pyload --url http://az05.nick3.xyz:3000/api/v1/data/receive \
              --file payload.bin
```
Windows PowerShell 可执行：
```powershell
python send_pyload --url http://az05.nick3.xyz:3000/api/v1/data/receive ^
                   --hex A259010F050201040207D1050907011C00ABCD
```

若外部设备仅能发送 <=60 字节，可直接连接轻量级 TCP 网关（默认 `tcp://<host>:3001`）：

```bash
./send_pyload --transport tcp --url tcp://az05.nick3.xyz:3001 \
              --hex A259010F050201040207D1050907011C00ABCD
```

### 19 字节数据结构

| Byte | Bit | 示例 | 十六进制 | 说明 |
| --- | --- | --- | --- | --- |
| 1 | 7-0 | 头-0xA2 | `0xA2` | 帧头固定值 |
| 2 | 7-0 | 头-0x59 | `0x59` | 帧头固定值 |
| 3 | 7-0 | 1 | `0x01` | 数据包序列号（新包+1） |
| 4 | 7-0 | 15 | `0x0F` | 数据包长度（13字节数据+2字节CRC） |
| 5 | 7-2 | 1 | `0x05` | 预警系统种类 |
| 5 | 1-0 | 1 | - | 信号级别 |
| 6 | 7-0 | 2 | `0x02` | 传感器编号 |
| 7 | 7-0 | 1 | `0x01` | 大楼编号 |
| 8 | 7-0 | 4 | `0x04` | 楼层编号 |
| 9 | 7-0 | 2 | `0x02` | 门牌编号 |
| 10-11 | 15-0 | 2001 | `0x07D1` | 街道门牌号 |
| 12 | 7-0 | 5 | `0x05` | 街道名编号 |
| 13 | 7-0 | 9 | `0x09` | 乡镇编号 |
| 14 | 7-0 | 7 | `0x07` | 县编号 |
| 15 | 7-0 | 1 | `0x01` | 地级市编号 |
| 16 | 7-0 | 28 | `0x1C` | 省名编号 |
| 17 | 7-0 | 0 | `0x00` | 特殊地名编号 |
| 18 | 7-0 | - | `0xAB` | CRC16 低字节 |
| 19 | 7-0 | - | `0xCD` | CRC16 高字节 |

## 🤝 参与贡献

1. Fork 仓库并新建 feature 分支
2. 提交代码前运行后端/前端测试套件
3. 提交 PR 并在描述中附带测试结果

欢迎就部署、数据格式或功能扩展提出 Issue 与建议。谢谢！