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 - 类型系统

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

安全访问函数

// 安全获取属性值
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

格式化函数

function formatDate(dateString: string, format?: string): string
function formatDifficulty(difficulty: string): string
function formatProjectStatus(status: string): string

Android 优化工具

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 上出错):

const project = response.data as Project
const title = project.title  // 可能导致 ClassCastException

✅ 正确的方式:

const project = response.data as UTSJSONObject
const title = getProjectDisplayName(project)  // 安全访问

2. 组件中的数据处理

在模板中:

<template>
  <view class="project-card">
    <text class="title">{{ getProjectDisplayName(project) }}</text>
    <text class="status">{{ formatProjectStatus(getProjectStatus(project)) }}</text>
  </view>
</template>

在脚本中:

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 调用示例

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. 数据安全访问

始终使用工具函数访问数据：

// 而不是直接访问 object.property
const value = safeGet(object, 'property', defaultValue)

2. 错误处理

使用统一的错误处理模式：

try {
  const result = await someAPI()
  // 处理成功结果
} catch (error) {
  const errorInfo = handleAPIError(error)
  // 处理错误
}

3. 组件状态管理

使用 ref 和 UTSJSONObject：

const data = ref<UTSJSONObject>({})
const list = ref<Array<UTSJSONObject>>([])

4. API 响应处理

检查 API 响应状态：

if (isAPISuccess(response)) {
  const data = getAPIData(response)
  // 处理数据
} else {
  const message = getAPIMessage(response)
  // 处理错误消息
}

性能优化

1. 数据处理优化

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

2. 内存管理

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

3. 网络优化

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

部署和配置

1. 环境配置

在 api.uts 中配置 API 基础 URL：

const API_BASE_URL = 'https://your-api-domain.com/api/v1'

2. 路由注册

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

3. 权限配置

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

故障排除

常见问题

ClassCastException 错误
- 确保使用 UTSJSONObject 而不是接口类型
- 使用 safeGet() 函数访问属性
数据显示为空
- 检查 API 响应格式
- 验证数据访问路径
- 确认默认值设置
Android 平台特定问题
- 使用 Android 优化的工具函数
- 避免复杂的泛型操作
- 简化数据结构

调试技巧

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

扩展开发

添加新功能

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

自定义组件

遵循 UTSJSONObject 数据处理模式：

// 组件 props 接收 UTSJSONObject
props: {
  data: {
    type: Object as PropType<UTSJSONObject>,
    required: true
  }
}

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

总结

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

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

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

README.md Unescape Escape

Sport Training System - UTSJSONObject Architecture

概述 (Overview)

系统架构 (System Architecture)

核心设计原则

目录结构