# 手环位置功能开发文档

## 功能概述

为学生端增加了获取手环位置的功能入口，支持基站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规范编写，确保类型安全和兼容性。