205 lines
5.5 KiB
Markdown
205 lines
5.5 KiB
Markdown
# 手环位置功能开发文档
|
||
|
||
## 功能概述
|
||
|
||
为学生端增加了获取手环位置的功能入口，支持基站ID、位置信息和fence（围栏）功能。
|
||
|
||
## 新增文件
|
||
|
||
### 1. 位置服务 (`utils/locationService.uts`)
|
||
|
||
包含以下主要功能：
|
||
- **获取当前位置**: `getCurrentLocation(deviceId: string)`
|
||
- **获取基站列表**: `getBaseStations()`
|
||
- **围栏管理**: `getFences()`, `createFence()`, `updateFence()`, `deleteFence()`
|
||
- **位置历史**: `getLocationHistory()`
|
||
- **围栏事件**: `getFenceEvents()`, `markEventAsRead()`
|
||
|
||
#### 数据结构
|
||
|
||
```typescript
|
||
// 基站信息
|
||
interface BaseStationInfo {
|
||
id: string
|
||
name: string
|
||
location: string
|
||
longitude: number
|
||
latitude: number
|
||
signalStrength: number
|
||
isOnline: boolean
|
||
range: number
|
||
}
|
||
|
||
// 位置信息
|
||
interface LocationInfo {
|
||
deviceId: string
|
||
baseStation: BaseStationInfo | null
|
||
estimatedLocation: {
|
||
longitude: number
|
||
latitude: number
|
||
accuracy: number
|
||
} | null
|
||
lastUpdate: string
|
||
status: 'online' | 'offline' | 'unknown'
|
||
}
|
||
|
||
// 围栏信息
|
||
interface FenceInfo {
|
||
id: string
|
||
name: string
|
||
type: 'circle' | 'polygon'
|
||
center?: { longitude: number, latitude: number }
|
||
radius?: number
|
||
points?: Array<{ longitude: number, latitude: number }>
|
||
isActive: boolean
|
||
eventType: 'enter' | 'exit' | 'both'
|
||
createdAt: string
|
||
}
|
||
```
|
||
|
||
### 2. 位置详情页面 (`pages/sport/student/location.uvue`)
|
||
|
||
功能特性：
|
||
- **实时位置显示**: 显示当前连接的基站和估算位置
|
||
- **基站管理**: 查看附近基站状态和信息
|
||
- **围栏管理**: 创建、编辑、删除围栏设置
|
||
- **事件监控**: 查看围栏进入/离开事件
|
||
- **位置历史**: 查看设备位置变化历史
|
||
|
||
### 3. 测试页面 (`pages/sport/student/location-test.uvue`)
|
||
|
||
用于测试位置服务的各项功能是否正常工作。
|
||
|
||
## Dashboard 修改
|
||
|
||
### 1. 新增功能入口
|
||
|
||
在学生dashboard的快速操作区域添加了"手环位置"入口：
|
||
- 图标：📍
|
||
- 显示当前位置状态（在线/离线）
|
||
- 点击跳转到位置详情页面
|
||
|
||
### 2. 页面布局调整
|
||
|
||
- 将快速操作卡片从每行2个调整为每行2个（适应5个操作项）
|
||
- 优化卡片间距和样式
|
||
- 添加位置状态指示器
|
||
|
||
## 路由配置
|
||
|
||
在 `pages.json` 中新增路由：
|
||
```json
|
||
{
|
||
"path": "pages/sport/student/location",
|
||
"style": {
|
||
"navigationBarTitleText": "手环位置",
|
||
"navigationBarTextStyle": "white",
|
||
"navigationBarBackgroundColor": "#667eea"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 1. 从Dashboard进入
|
||
|
||
1. 打开学生dashboard
|
||
2. 在快速操作区域点击"手环位置"卡片
|
||
3. 进入位置详情页面
|
||
|
||
### 2. 功能操作
|
||
|
||
#### 查看当前位置
|
||
- 页面自动加载当前位置信息
|
||
- 显示连接的基站、信号强度、估算坐标等
|
||
- 点击"刷新位置"按钮更新信息
|
||
|
||
#### 管理围栏
|
||
- 查看现有围栏列表
|
||
- 点击"+"按钮创建新围栏（开发中）
|
||
- 编辑或删除现有围栏
|
||
|
||
#### 查看事件记录
|
||
- 自动显示最近的围栏事件
|
||
- 点击事件可标记为已读
|
||
- 支持清空所有事件
|
||
|
||
#### 位置历史
|
||
- 显示最近的位置变化记录
|
||
- 点击"查看更多"查看完整历史（开发中）
|
||
|
||
## 技术实现
|
||
|
||
### 1. 类型安全
|
||
|
||
- 所有接口返回统一的 `AkReqResponse<T>` 格式
|
||
- 使用TypeScript接口定义数据结构
|
||
- 支持泛型和类型推断
|
||
|
||
### 2. 错误处理
|
||
|
||
```typescript
|
||
// 统一错误响应格式
|
||
export function createLocationErrorResponse<T>(message: string): AkReqResponse<T> {
|
||
return createLocationResponse<T>(500, message, null)
|
||
}
|
||
```
|
||
|
||
### 3. 模拟数据
|
||
|
||
当前使用模拟数据进行演示，包括：
|
||
- 4个模拟基站（教学楼A/B栋、操场、宿舍楼）
|
||
- 3个预设围栏（校园安全区域、教学区域、危险区域）
|
||
- 模拟的位置历史和围栏事件
|
||
|
||
## 后续开发计划
|
||
|
||
### 短期目标
|
||
1. **围栏创建/编辑界面**: 实现可视化围栏设置
|
||
2. **地图集成**: 集成地图组件显示位置和围栏
|
||
3. **实时推送**: 位置变化和围栏事件的实时通知
|
||
|
||
### 中期目标
|
||
1. **数据持久化**: 连接后端API进行数据存储
|
||
2. **批量管理**: 支持批量创建和管理围栏
|
||
3. **报表功能**: 位置统计和活动报告
|
||
|
||
### 长期目标
|
||
1. **智能围栏**: 基于AI的智能围栏推荐
|
||
2. **轨迹分析**: 学生活动轨迹分析和健康建议
|
||
3. **家长端集成**: 家长端查看学生位置功能
|
||
|
||
## 测试说明
|
||
|
||
### 功能测试
|
||
1. 访问 `/pages/sport/student/location-test` 进行功能测试
|
||
2. 测试各项API接口的响应和数据格式
|
||
3. 验证错误处理和边界情况
|
||
|
||
### 页面测试
|
||
1. 从dashboard正常跳转到位置页面
|
||
2. 测试各项功能按钮和交互
|
||
3. 验证数据加载和刷新功能
|
||
|
||
## 注意事项
|
||
|
||
1. **设备ID获取**: 当前使用 `device_${userId}` 格式的模拟ID
|
||
2. **权限控制**: 需要确保学生只能查看自己的设备位置
|
||
3. **数据安全**: 位置信息属于敏感数据，需要适当的加密和权限控制
|
||
4. **性能优化**: 位置数据更新频率需要平衡实时性和电池消耗
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
h:\blews\akmon\
|
||
├── utils/
|
||
│ └── locationService.uts # 位置服务
|
||
├── pages/sport/student/
|
||
│ ├── dashboard.uvue # 学生dashboard（已修改）
|
||
│ ├── location.uvue # 位置详情页面
|
||
│ └── location-test.uvue # 功能测试页面
|
||
└── pages.json # 路由配置（已修改）
|
||
```
|
||
|
||
所有代码都按照UTS/uni-app规范编写，确保类型安全和兼容性。
|