akmon/pages/sport/README.md

# Sport Training System - UTSJSONObject Architecture

## 概述 (Overview)

这是一个完全基于 UTSJSONObject 的AI监测系统，专为解决 UTS Android 平台上的类型转换问题而设计。系统采用安全的数据访问模式，避免了传统 TypeScript 接口在 Android 平台上可能出现的 ClassCastException 错误。

## 系统架构 (System Architecture)

### 核心设计原则

1. **UTSJSONObject 优先**: 所有数据处理都使用 UTSJSONObject，避免复杂的类型转换
2. **安全访问模式**: 使用 `safeGet()` 函数进行所有属性访问
3. **Android 兼容性**: 专门优化以在 UTS Android 平台上稳定运行
4. **类型安全**: 通过工具函数确保类型安全，而不依赖泛型转换

### 目录结构

```
pages/sport/
├── index.uvue                    # 主入口页面
├── types.uts                     # 核心类型系统和工具函数
├── SUPACLINET_GUIDE.md          # 直接使用 supaClient 链式调用指南
├── teacher/                      # 教师端功能
│   ├── dashboard.uvue           # 教师工作台
│   ├── projects.uvue            # 项目管理
│   ├── project-detail.uvue      # 项目详情
│   ├── assignments.uvue         # 作业管理
│   ├── create-assignment.uvue   # 创建作业
│   ├── analytics.uvue           # 数据分析
│   └── records.uvue             # 记录管理
└── student/                      # 学生端功能
    ├── dashboard.uvue           # 学生主页
    ├── assignments.uvue         # 作业列表 (已更新为 supaClient)
    ├── assignment-detail.uvue   # 作业详情
    ├── training-record.uvue     # 训练记录
    ├── record-detail.uvue       # 记录详情
    ├── records.uvue             # 训练历史
    ├── simple-records.uvue      # 简化记录管理 (supaClient 示例)
    ├── progress.uvue            # 进度跟踪
    └── achievements.uvue        # 成就系统
```

## 核心组件说明

### 1. types.uts - 类型系统

这是整个系统的核心，提供了：

#### 安全访问函数
```typescript
// 安全获取属性值
function safeGet(obj: UTSJSONObject, key: string, defaultValue: any): any

// 项目相关访问器
function getProjectId(project: UTSJSONObject): string
function getProjectDisplayName(project: UTSJSONObject): string
function getProjectDescription(project: UTSJSONObject): string

// 作业相关访问器
function getAssignmentId(assignment: UTSJSONObject): string
function getAssignmentDisplayName(assignment: UTSJSONObject): string
function getAssignmentStatus(assignment: UTSJSONObject): string
```

#### 格式化函数
```typescript
function formatDate(dateString: string, format?: string): string
function formatDifficulty(difficulty: string): string
function formatProjectStatus(status: string): string
```

#### Android 优化工具
```typescript
function processUTSJSONArray(data: any): Array<UTSJSONObject>
function createEmptyUTSJSONObject(): UTSJSONObject
function validateUTSJSONObject(obj: any): boolean
```

## ️ 系统架构

### 核心文件
- `types.uts` - UTSJSONObject 类型系统和安全访问函数
- `index.uvue` - 主入口，角色导航
- `SUPACLINET_GUIDE.md` - 直接使用 supaClient 的完整指南

### 数据访问模式
** 直接使用 AkSupa 链式调用**
- 移除了 API 包装层，直接使用 `supaClient` 进行数据库操作
- 链式调用语法简洁：`supaClient.from('table').select('*').eq('id', value).execute()`
- 支持实时订阅、文件上传、认证等完整功能
- 参考 `SUPACLINET_GUIDE.md` 获取详细使用说明

### 数据库表结构
- `ak_training_projects` - 训练项目表
- `ak_assignments` - 作业分配表  
- `ak_training_records` - 训练记录表
- `ak_users` - 用户信息表

## 使用指南

### 1. 数据访问模式

**❌ 错误的方式 (会在 Android 上出错):**
```typescript
const project = response.data as Project
const title = project.title  // 可能导致 ClassCastException
```

**✅ 正确的方式:**
```typescript
const project = response.data as UTSJSONObject
const title = getProjectDisplayName(project)  // 安全访问
```

### 2. 组件中的数据处理

**在模板中:**
```vue
<template>
  <view class="project-card">
    <text class="title">{{ getProjectDisplayName(project) }}</text>
    <text class="status">{{ formatProjectStatus(getProjectStatus(project)) }}</text>
  </view>
</template>
```

**在脚本中:**
```typescript
import { safeGet, getProjectId, getProjectDisplayName } from '../types.uts'

const projects = ref<Array<UTSJSONObject>>([])

function handleProjectsData(data: UTSJSONObject) {
  const projectList = safeGet(data, 'projects', [])
  if (projectList instanceof Array) {
    projects.value = projectList.map(item => item as UTSJSONObject)
  }
}
```

### 3. API 调用示例

```typescript
import { projectAPI, handleAPIError } from '../api.uts'

async function loadProjects() {
  try {
    const response = await projectAPI.getProjects({
      category: 'athletics',
      status: 'active'
    } as UTSJSONObject)
    
    if (isAPISuccess(response)) {
      const data = getAPIData(response)
      handleProjectsData(data)
    }
  } catch (error) {
    const errorInfo = handleAPIError(error)
    console.error('Load projects failed:', getAPIMessage(errorInfo))
  }
}
```

## 页面功能详解

### 教师端功能

#### 1. 教师工作台 (teacher/dashboard.uvue)
- 统计概览卡片
- 快速操作入口
- 近期活动展示
- 响应式设计

#### 2. 项目管理 (teacher/projects.uvue)
- 项目的增删改查
- 高级筛选和搜索
- 统计数据计算
- 卡片式布局

#### 3. 作业管理 (teacher/assignments.uvue)
- 作业的创建和管理
- 批改状态跟踪
- 进度可视化
- 筛选和搜索功能

#### 4. 数据分析 (teacher/analytics.uvue)
- 训练数据统计
- 成绩趋势分析
- 学生表现排名
- 图表数据展示

### 学生端功能

#### 1. 学生主页 (student/dashboard.uvue)
- 个人进度展示
- 待完成作业
- 快速操作入口
- 训练记录概览

#### 2. 训练记录 (student/training-record.uvue)
- 计时器功能
- 成绩录入表单
- 动态字段适配
- 实时数据保存

#### 3. 训练历史 (student/records.uvue)
- 历史记录查看
- 时间线展示
- 筛选和搜索
- 成绩趋势分析

#### 4. 成就系统 (student/achievements.uvue)
- 成就列表展示
- 进度跟踪
- 积分和等级系统
- 激励机制

## 最佳实践

### 1. 数据安全访问

始终使用工具函数访问数据：
```typescript
// 而不是直接访问 object.property
const value = safeGet(object, 'property', defaultValue)
```

### 2. 错误处理

使用统一的错误处理模式：
```typescript
try {
  const result = await someAPI()
  // 处理成功结果
} catch (error) {
  const errorInfo = handleAPIError(error)
  // 处理错误
}
```

### 3. 组件状态管理

使用 ref 和 UTSJSONObject：
```typescript
const data = ref<UTSJSONObject>({})
const list = ref<Array<UTSJSONObject>>([])
```

### 4. API 响应处理

检查 API 响应状态：
```typescript
if (isAPISuccess(response)) {
  const data = getAPIData(response)
  // 处理数据
} else {
  const message = getAPIMessage(response)
  // 处理错误消息
}
```

## 性能优化

### 1. 数据处理优化

- 使用 `processUTSJSONArray()` 处理大型数组
- 避免深层嵌套的对象访问
- 合理使用默认值减少空值检查

### 2. 内存管理

- 及时清理不需要的数据引用
- 使用分页加载大量数据
- 避免循环引用

### 3. 网络优化

- 实现请求去重
- 使用适当的缓存策略
- 合并多个小请求

## 部署和配置

### 1. 环境配置

在 `api.uts` 中配置 API 基础 URL：
```typescript
const API_BASE_URL = 'https://your-api-domain.com/api/v1'
```

### 2. 路由注册

在 `pages.json` 中注册所有页面路由（已完成）。

### 3. 权限配置

根据用户角色配置页面访问权限。

## 故障排除

### 常见问题

1. **ClassCastException 错误**
   - 确保使用 UTSJSONObject 而不是接口类型
   - 使用 `safeGet()` 函数访问属性

2. **数据显示为空**
   - 检查 API 响应格式
   - 验证数据访问路径
   - 确认默认值设置

3. **Android 平台特定问题**
   - 使用 Android 优化的工具函数
   - 避免复杂的泛型操作
   - 简化数据结构

### 调试技巧

1. 使用 `console.log()` 输出 UTSJSONObject 内容
2. 检查 API 响应的原始数据格式
3. 验证数据类型转换过程
4. 测试不同 Android 设备的兼容性

## 扩展开发

### 添加新功能

1. 在 `types.uts` 中添加新的访问器函数
2. 在 `api.uts` 中添加相应的 API 接口
3. 创建新的页面组件
4. 在 `pages.json` 中注册路由

### 自定义组件

遵循 UTSJSONObject 数据处理模式：
```typescript
// 组件 props 接收 UTSJSONObject
props: {
  data: {
    type: Object as PropType<UTSJSONObject>,
    required: true
  }
}

// 在组件中安全访问数据
const title = computed(() => safeGet(props.data, 'title', ''))
```

## 总结

这个基于 UTSJSONObject 的AI监测系统提供了：

- **稳定性**: 完全兼容 UTS Android 平台
- **安全性**: 避免类型转换错误
- **可维护性**: 统一的数据访问模式
- **可扩展性**: 模块化的架构设计
- **用户体验**: 现代化的 UI 设计

通过遵循本文档中的最佳实践，开发者可以安全地扩展系统功能，同时保持在所有平台上的稳定运行。