feat: 信标设备绑定 + 蓝牙模式管理 + 系统管理增强 + 数据导出

- 新增 DeviceBeaconBinding 模型，信标-设备多对多绑定 CRUD - 蓝牙打卡模式批量配置/恢复正常模式 API - 反向同步: 查询设备 BTMACSET 配置更新数据库绑定 (独立 session 解决事务隔离) - 设备列表快捷操作弹窗修复 (fire-and-forget IIFE 替代阻塞轮询) - 保存按钮防抖: 围栏/信标绑定保存点击后 disabled + 转圈防重复提交 - 审计日志中间件 + 系统配置/备份/固件 API - 设备分组管理 + 告警规则配置 - 5个数据导出 API (CSV UTF-8 BOM) - 位置热力图 + 告警条件删除 + 位置清理 via [HAPI](https://hapi.run) Co-Authored-By: HAPI <noreply@hapi.run>
2026-04-01 07:06:37 +00:00
parent 9daa81621c
commit 9cd9dd9d76
19 changed files with 3403 additions and 100 deletions
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -18,6 +18,7 @@ KKS P240/P241 蓝牙工牌管理后台，基于 FastAPI + SQLAlchemy + asyncio T
 │
 ├── app/
 │   ├── main.py                 # FastAPI 应用入口, 挂载静态文件, 启动TCP服务器, /api/system/overview, /api/system/cleanup
+│   ├── middleware.py            # AuditMiddleware — 自动记录 POST/PUT/DELETE 操作到 audit_logs 表
 │   ├── config.py               # 配置 (pydantic-settings, .env支持, 端口/API密钥/缓存/限流)
 │   ├── database.py             # SQLAlchemy async 数据库连接
 │   ├── dependencies.py         # FastAPI 依赖 (多API Key认证 + 权限控制: read/write/admin)
@@ -38,10 +39,11 @@ KKS P240/P241 蓝牙工牌管理后台，基于 FastAPI + SQLAlchemy + asyncio T
 │   │   ├── device_service.py       # 设备 CRUD
 │   │   ├── command_service.py      # 指令日志 CRUD
 │   │   ├── location_service.py     # 位置记录查询
-│   │   ├── beacon_service.py       # 蓝牙信标 CRUD
+│   │   ├── beacon_service.py       # 蓝牙信标 CRUD + 设备绑定 + 蓝牙模式配置/恢复 + 反向同步
 │   │   ├── fence_service.py        # 电子围栏 CRUD + 设备绑定管理
 │   │   ├── fence_checker.py        # 围栏自动考勤引擎 (几何判定+状态机+自动打卡)
-│   │   └── tcp_command_service.py  # TCP指令抽象层 (解耦routers↔tcp_server)
+│   │   ├── tcp_command_service.py  # TCP指令抽象层 (解耦routers↔tcp_server)
+│   │   └── export_utils.py         # CSV导出工具 (build_csv_content, csv_filename)
 │   │
 │   ├── routers/
 │   │   ├── devices.py          # /api/devices (含 /stats增强, /batch, /batch-delete, /all-latest-locations)
@@ -51,11 +53,14 @@ KKS P240/P241 蓝牙工牌管理后台，基于 FastAPI + SQLAlchemy + asyncio T
 │   │   ├── attendance.py       # /api/attendance (含 /stats增强, /report, /device/{id}, attendance_source过滤)
 │   │   ├── bluetooth.py        # /api/bluetooth (含 /stats, beacon_mac过滤, /batch-delete)
 │   │   ├── heartbeats.py       # /api/heartbeats (含 /stats, /batch-delete, 心跳记录查询)
-│   │   ├── beacons.py          # /api/beacons (信标管理 CRUD)
+│   │   ├── beacons.py          # /api/beacons (信标管理 CRUD + 设备绑定 + 蓝牙模式/恢复/反向同步)
 │   │   ├── fences.py           # /api/fences (含 /stats, /{id}/events, /all-active, 设备绑定CRUD)
 │   │   ├── geocoding.py        # /api/geocode (POI搜索代理 /search, 逆地理编码 /reverse)
 │   │   ├── api_keys.py         # /api/keys (API密钥管理 CRUD, admin only)
-│   │   └── ws.py               # /ws (WebSocket实时推送, topic订阅)
+│   │   ├── ws.py               # /ws (WebSocket实时推送, topic订阅)
+│   │   ├── device_groups.py    # /api/groups (设备分组管理 CRUD + 成员管理)
+│   │   ├── alert_rules.py      # /api/alert-rules (告警规则 CRUD)
+│   │   └── system.py           # /api/system (审计日志/运行时配置/数据库备份/固件信息)
 │   │
 │   └── static/
 │       └── admin.html          # 管理后台 SPA (暗色主题, 10个页面)
@@ -367,6 +372,7 @@ KKS 二进制协议，详见 `doc/KKS_Protocol_P240_P241.md`

 ### 蓝牙信标管理
 - **BeaconConfig 表**: 注册蓝牙信标，配置 MAC/UUID/Major/Minor/楼层/区域/经纬度/地址
+- **DeviceBeaconBinding 表**: 设备-信标多对多绑定 (device_id + beacon_id 唯一约束)
 - **自动关联**: 0xB2 打卡和 0xB3 定位时，根据 beacon_mac 查询 beacon_configs 表
 - **位置写入**: 将已注册信标的经纬度写入 BluetoothRecord 的 latitude/longitude
 - **多信标定位**: 0xB3 多信标场景，取 RSSI 信号最强的已注册信标位置
@@ -374,6 +380,13 @@ KKS 二进制协议，详见 `doc/KKS_Protocol_P240_P241.md`
 - **已验证信标**: MAC=`C3:00:00:34:43:5E`, UUID=FDA50693-A4E2-4FB1-AFCF-C6EB07647825, Major=10001, Minor=19641
 - **注意**: 信标需配置经纬度/地址，否则打卡记录中位置为空
 - **制造商**: 几米物联 (Jimi IoT / jimiiot.com.cn)，P240/P241 智能电子工牌系列
+- **蓝牙模式 API**:
+  - `POST /api/beacons/setup-bluetooth-mode` — 批量配置蓝牙打卡模式 (CLOCKWAY,3# + MODE,2# + BTMACSET + BTMP3SW,1#)
+  - `POST /api/beacons/restore-normal-mode` — 批量恢复智能模式 (CLOCKWAY,1# + MODE,3# + BTMP3SW,0#)
+  - `POST /api/beacons/reverse-sync` — 查询设备 BTMACSET 配置，反向更新数据库绑定
+  - `POST /api/beacons/sync-device/{id}` — 同步绑定信标 MAC 到指定设备
+  - `GET/POST/DELETE /api/beacons/{id}/devices` — 信标设备绑定 CRUD
+- **反向同步事务隔离**: 使用独立 session 创建 CommandLog 并 commit，轮询用独立 session 避免 SQLAlchemy greenlet 错误

 ### P241 蓝牙模式配置指南 (设备端)
 设备蓝牙模式通过在线指令 (0x80) 配置，需依次完成以下步骤：
@@ -824,40 +837,59 @@ remotePort = 5001
 194. **总览低精度过滤** - 独立的低精度按钮，切换时自动重新加载轨迹（跳过LBS点重连折线）
 195. **离线设备支持** - batch-latest 查数据库历史位置（不限在线），取消勾选的设备点击名称仍可定位+查轨迹

+### 数据导出 API + 前端导出按钮 (2026-04-01)
+196. **export_utils.py** - 新建共享 CSV 导出工具模块 (build_csv_content + csv_filename)，UTF-8 BOM 编码确保 Excel 兼容
+197. **设备导出** - `GET /api/devices/export` 导出设备列表 CSV，支持 status/search 筛选
+198. **位置导出** - `GET /api/locations/export` 导出位置记录 CSV，支持 device_id/location_type/时间筛选，最多 50000 条
+199. **告警导出** - `GET /api/alarms/export` 导出告警记录 CSV，支持 alarm_type/acknowledged/时间筛选
+200. **考勤导出** - `GET /api/attendance/export` 导出考勤记录 CSV，支持 attendance_type/attendance_source/时间筛选
+201. **蓝牙导出** - `GET /api/bluetooth/export` 导出蓝牙记录 CSV，支持 record_type/beacon_mac/时间筛选
+202. **考勤报表导出** - `GET /api/attendance/report/export` 导出考勤日报表 CSV (设备×日期汇总)
+203. **前端导出按钮** - 设备/位置/告警/考勤/蓝牙 5 个页面工具栏新增导出按钮，携带当前筛选条件，fetch+blob 下载
+
+### 批量操作 + 筛选增强 (2026-04-01)
+204. **告警条件删除** - `POST /api/alarms/batch-delete` 增强为双模式: 按 alarm_ids 列表删除 (最多500) 或按条件删除 (device_id/alarm_type/acknowledged/时间范围)，使用 sql_delete 高效执行
+205. **位置记录清理** - 新增 `POST /api/locations/cleanup`，按天数删除旧记录 (1-365天)，支持 device_id/location_type 筛选，返回删除条数
+206. **设备分组管理** - 新增 DeviceGroup + DeviceGroupMember 模型，Device 增加 group_id 字段；完整 CRUD API (`/api/groups`)，支持组内设备管理 (添加/移除/查看)，设备计数通过 outerjoin 聚合
+207. **位置热力图** - 新增 `GET /api/locations/heatmap`，坐标网格聚合 (precision 参数控制精度)，返回 [{lat, lng, weight}]；前端使用高德 HeatMap 插件渲染，含 WGS84→GCJ02 偏移
+208. **告警规则配置** - 新增 AlertRule 模型 (name/rule_type/conditions JSON/is_active/device_ids/group_id)，5种规则类型 (low_battery/no_heartbeat/fence_stay/speed_limit/offline_duration)；完整 CRUD API (`/api/alert-rules`)
+209. **前端告警条件删除** - 告警页面工具栏新增"条件删除"按钮，弹窗支持按设备/类型/状态/时间范围批量删除
+210. **前端位置清理** - 位置页面工具栏新增"清理旧数据"按钮，弹窗输入天数+可选设备ID/定位类型筛选
+211. **前端热力图** - 位置页面工具栏新增"热力图"按钮，弹窗选择设备和时间范围，高德 HeatMap 插件全屏渲染
+212. **前端分组管理** - 设备页面工具栏新增"分组管理"按钮，弹窗展示分组列表 (含设备数)，支持创建/删除分组、管理组内设备
+213. **前端告警规则** - 告警页面工具栏新增"告警规则"按钮，弹窗展示规则列表，支持创建/启用禁用/删除规则
+
+### 系统管理增强 (2026-04-01)
+214. **操作审计日志** - 新增 AuditLog 模型 + AuditMiddleware 中间件，自动记录所有 /api/ POST/PUT/DELETE 操作 (方法/路径/状态码/操作人/IP/请求体/耗时)，敏感字段自动脱敏
+215. **审计日志 API** - `GET /api/system/audit-logs` 分页查询 (支持方法/路径/操作人/时间筛选)，`DELETE /api/system/audit-logs?days=N` 清理旧日志
+216. **系统配置 API** - `GET /api/system/config` 查看运行时配置，`PUT /api/system/config` 修改 (数据保留天数/清理间隔/TCP超时/围栏参数等)，仅影响当前进程，重启恢复 .env 值
+217. **数据库备份 API** - `POST /api/system/backup` SQLite online backup + 文件下载，`GET /api/system/backups` 列出备份，`DELETE /api/system/backups/{name}` 删除备份
+218. **设备固件信息 API** - `GET /api/system/firmware` 获取所有设备型号/ICCID/IMSI/登录时间等信息，支持按状态筛选
+219. **前端系统管理** - 仪表盘工具栏新增: 系统配置弹窗 (运行时参数编辑)、审计日志弹窗 (分页+筛选+清理)、备份管理弹窗 (创建+下载+删除)、固件信息弹窗 (设备列表+批量VERSION#查询)
+
+### 信标设备绑定 + 蓝牙模式管理 (2026-04-01)
+220. **DeviceBeaconBinding 模型** - 设备-信标多对多绑定表 (device_id + beacon_id 唯一约束)，支持 CRUD
+221. **信标绑定 API** - `GET/POST/DELETE /api/beacons/{id}/devices` 管理信标绑定的设备列表
+222. **设备信标同步** - `POST /api/beacons/sync-device/{id}` 将绑定的信标 MAC 通过 BTMACSET 指令写入设备 (5 slot × 10 MAC)
+223. **蓝牙打卡模式** - `POST /api/beacons/setup-bluetooth-mode` 批量配置设备蓝牙打卡 (CLOCKWAY,3# → MODE,2# → BTMACSET → BTMP3SW,1#)
+224. **恢复正常模式** - `POST /api/beacons/restore-normal-mode` 批量恢复设备到智能模式 (CLOCKWAY,1# → MODE,3# → BTMP3SW,0#)
+225. **反向同步** - `POST /api/beacons/reverse-sync` 查询所有在线设备的 BTMACSET 配置并更新数据库绑定关系，独立 session 解决事务隔离问题
+226. **信标绑定矩阵 UI** - 信标管理页面 Tab 切换 (信标列表 + 设备绑定)，设备绑定 Tab 含绑定矩阵 checkbox 表格、保存更改按钮
+227. **设备列表蓝牙操作** - 工具栏新增"蓝牙打卡模式"(紫色)和"恢复正常模式"(绿色)按钮；每行设备新增"蓝牙"和"正常"快捷按钮
+228. **快捷操作弹窗修复** - `_devQuickCmd` 重写: 移除按钮 disabled/spinner，改为立即弹窗显示进度，轮询移入 fire-and-forget IIFE 不阻塞
+229. **保存按钮防抖** - 围栏绑定和信标绑定的"保存更改"按钮点击后立即 disabled + 转圈，防止重复提交；信标保存还显示"同步指令到设备..."阶段提示
+
 ## 待完成功能

-### 第一优先级 — API 增强 (用于系统集成)
-
-#### 第二批: 数据导出 API
-5. **设备数据导出** - `GET /api/devices/export?format=csv` — 导出设备列表 CSV/Excel，支持状态/类型筛选
-6. **位置数据导出** - `GET /api/locations/export?format=csv` — 导出位置记录 CSV，支持设备/时间/类型筛选
-7. **告警数据导出** - `GET /api/alarms/export?format=csv` — 导出告警记录 CSV，支持类型/状态/时间筛选
-8. **考勤数据导出** - `GET /api/attendance/export?format=csv` — 导出考勤记录 CSV，支持设备/来源/时间筛选
-9. **蓝牙数据导出** - `GET /api/bluetooth/export?format=csv` — 导出蓝牙记录 CSV
-10. **考勤报表导出** - `GET /api/attendance/report/export?format=csv` — 导出考勤日报表 (每设备每天汇总)
-
-#### 第三批: 批量操作 + 筛选增强
-11. **告警批量删除增强** - 支持按时间范围/类型/设备批量删除 (不限于选中 ID)
-12. **位置记录清理增强** - `POST /api/locations/cleanup` — 删除N天前旧记录，支持按定位类型筛选
-13. **设备分组管理** - 新增 DeviceGroup 模型，支持设备分组、按组查询、按组批量操作
-14. **位置数据聚合** - `GET /api/locations/heatmap?device_id=&start_time=&end_time=` — 返回热力图数据 (经纬度+权重)
-15. **告警规则配置** - 新增告警规则 API，支持自定义告警阈值 (低电量阈值、围栏停留时间等)
-
-#### 第四批: 系统管理增强
-16. **操作审计日志** - 新增 AuditLog 模型，记录所有 POST/PUT/DELETE 操作 (操作人/IP/端点/参数/时间)
-17. **系统配置 API** - `GET/PUT /api/system/config` — 运行时配置查看和修改 (数据保留天数、清理间隔等)
-18. **数据库备份 API** - `POST /api/system/backup` — 触发 SQLite 数据库备份，返回下载链接
-19. **设备固件管理** - 新增固件版本记录 API，支持批量查询设备固件版本
-
-### 第二优先级 — 前端与体验
+### 第一优先级 — 前端与体验

 20. **前端 WebSocket 集成** - admin.html Dashboard 改用 WebSocket 替代 30s 轮询，报警页实时通知弹窗
 21. **考勤报表页面** - 前端新增考勤报表 Tab，调用 `GET /api/attendance/report` 展示每设备每天签到汇总
 22. **心跳统计页面** - 数据日志页面心跳 Tab 增加统计面板，调用 `GET /api/heartbeats/stats` 展示设备活跃/异常/电量分布
 23. **位置统计页面** - 位置追踪页面增加统计面板，调用 `GET /api/locations/stats` 展示定位类型分布/小时趋势
-24. **导出按钮集成** - 各数据页面工具栏添加"导出 CSV"按钮 (需先完成第二批导出 API)
+24. ~~**导出按钮集成**~~ - ✅ 已完成 (随第二批导出 API 一起实现)

-### 第三优先级 — 性能与架构
+### 第二优先级 — 性能与架构

 25. **性能优化第三批** - 迁移 PostgreSQL、多worker部署 (几千台设备时)
 26. **API 版本化** - 添加 `/api/v1/` 前缀，为将来 v2 预留兼容空间
@@ -866,6 +898,40 @@ remotePort = 5001
 27. **心跳扩展模块解析** - 计步器、外部电压等模块未解析 (已存原始 hex，按需解析)
 28. **协议层深度统一** - tcp_server.py 辅助方法 (_parse_gps, _parse_datetime 等) 逐步迁移到 protocol/parser.py (代码重构)

+### 已完成的 API 增强 (第四批 — 系统管理增强，2026-04-01)
+- ✅ AuditLog 模型 + AuditMiddleware — 自动记录 /api/ POST/PUT/DELETE 操作 (方法/路径/状态码/操作人/IP/请求体/耗时)
+- ✅ `GET /api/system/audit-logs` — 审计日志分页查询 (方法/路径/操作人/时间筛选)
+- ✅ `DELETE /api/system/audit-logs?days=N` — 清理N天前审计日志
+- ✅ `GET /api/system/config` — 查看运行时配置参数
+- ✅ `PUT /api/system/config` — 更新运行时配置 (进程级，重启恢复)
+- ✅ `POST /api/system/backup` — SQLite online backup + 文件下载
+- ✅ `GET /api/system/backups` — 列出已有备份文件
+- ✅ `DELETE /api/system/backups/{filename}` — 删除指定备份
+- ✅ `GET /api/system/firmware` — 设备固件信息列表 (型号/ICCID/IMSI等)
+- ✅ 前端: 仪表盘系统配置弹窗、审计日志弹窗、备份管理弹窗、固件信息弹窗
+- ✅ 新增文件: app/middleware.py (审计中间件), app/routers/system.py (系统管理路由)
+
+### 已完成的 API 增强 (第三批 — 批量操作+筛选增强，2026-04-01)
+- ✅ `POST /api/alarms/batch-delete` 增强 — 双模式删除: 按ID列表 或 按条件 (设备/类型/状态/时间范围)
+- ✅ `POST /api/locations/cleanup` — 位置记录清理，按天数+设备+定位类型筛选删除旧记录
+- ✅ `GET /api/locations/heatmap` — 位置热力图数据，坐标网格聚合，precision 参数控制精度
+- ✅ `/api/groups` CRUD — 设备分组管理 (创建/更新/删除/列表+设备计数)
+- ✅ `/api/groups/{id}/devices` — 分组设备管理 (查看/添加/移除，幂等添加)
+- ✅ `/api/alert-rules` CRUD — 告警规则配置 (5种规则类型，conditions JSON，启用/禁用)
+- ✅ 新增 ORM 模型: DeviceGroup, DeviceGroupMember, AlertRule; Device 增加 group_id
+- ✅ 前端: 告警条件删除弹窗、位置清理弹窗、热力图 (高德HeatMap插件)、分组管理弹窗、告警规则弹窗
+
+### 已完成的 API 增强 (第二批 — 数据导出，2026-04-01)
+- ✅ `GET /api/devices/export` — 导出设备列表 CSV，支持状态/搜索筛选
+- ✅ `GET /api/locations/export` — 导出位置记录 CSV，支持设备/类型/时间筛选 (最多50000条)
+- ✅ `GET /api/alarms/export` — 导出告警记录 CSV，支持类型/状态/时间筛选 (最多50000条)
+- ✅ `GET /api/attendance/export` — 导出考勤记录 CSV，支持设备/类型/来源/时间筛选 (最多50000条)
+- ✅ `GET /api/bluetooth/export` — 导出蓝牙记录 CSV，支持设备/类型/信标/时间筛选 (最多50000条)
+- ✅ `GET /api/attendance/report/export` — 导出考勤日报表 CSV (每设备每天汇总)
+- ✅ 前端 admin.html: 设备/位置/告警/考勤/蓝牙 页面工具栏新增"导出"按钮，支持当前筛选条件导出
+- ✅ CSV 使用 UTF-8 BOM 编码，Excel 可直接打开中文不乱码
+- ✅ 共享 export_utils.py 工具模块 (build_csv_content + csv_filename)
+
 ### 已完成的 API 增强 (第一批 — 统计/聚合，2026-03-31)
 - ✅ `GET /api/system/overview` — 系统总览 (设备在线率/今日统计/表记录数/DB大小)
 - ✅ `GET /api/devices/stats` 增强 — 新增 by_type, battery_distribution, signal_distribution, online_rate