Initial commit of akmon project
This commit is contained in:
359
pages/sport/README.md
Normal file
359
pages/sport/README.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# 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 设计
|
||||
|
||||
通过遵循本文档中的最佳实践，开发者可以安全地扩展系统功能，同时保持在所有平台上的稳定运行。
|
||||
Reference in New Issue
Block a user