Initial commit of akmon project

doc_zhipao/ANALYTICS_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,127 @@
+# 训练偏好分析系统部署指南
+
+## 系统状态
+✅ **前端代码已完成** - 分析仪表板页面已创建并集成到导航中
+✅ **数据库脚本已完成** - PostgreSQL扩展脚本已修复并准备部署
+⚠️ **等待数据库部署** - 需要执行SQL脚本来启用分析功能
+
+## 部署步骤
+
+### 第一步：部署数据库扩展
+执行以下SQL文件来添加分析功能到数据库：
+
+```bash
+# 使用psql命令行工具（如果可用）
+psql -h [你的数据库主机] -U [用户名] -d [数据库名] -f preferences_analytics_extension_fixed.sql
+
+# 或者通过Supabase Dashboard、pgAdmin等GUI工具执行文件内容
+```
+
+**重要文件：**
+- `preferences_analytics_extension_fixed.sql` - 包含所有分析表和函数的完整SQL脚本
+
+### 第二步：验证数据库部署
+部署后，验证以下表和函数是否创建成功：
+
+**新建表：**
+- `ak_user_preference_history` - 用户偏好历史记录
+- `ak_goal_progress_history` - 目标进度历史
+- `ak_training_patterns` - 训练模式分析
+- `ak_personalized_recommendations` - 个性化推荐
+- `ak_user_behavior_analytics` - 用户行为分析
+
+**新建函数：**
+- `get_user_preferences_analytics(uuid)` - 获取用户偏好分析数据
+- `generate_personalized_recommendations(uuid)` - 生成个性化推荐
+- `get_user_training_trends(uuid, integer)` - 获取训练趋势数据
+- `log_user_behavior(uuid, varchar, jsonb)` - 记录用户行为
+- `update_training_pattern(uuid, varchar, jsonb)` - 更新训练模式
+
+**触发器：**
+- `preference_changes_trigger` - 偏好变更自动记录
+- `goal_progress_changes_trigger` - 目标进度变更自动记录
+
+### 第三步：测试分析功能
+1. **访问分析页面**
+   - 在学生档案页面点击"偏好分析"菜单项
+   - 检查页面是否正常加载
+
+2. **测试数据获取**
+   - 确认能正常显示用户偏好概览
+   - 检查图表和统计数据是否正确显示
+   - 验证推荐功能是否工作
+
+### 第四步：数据初始化（可选）
+SQL脚本已包含样本推荐数据的自动创建。如需更多测试数据，可以：
+- 添加更多用户偏好设置
+- 设置一些训练目标
+- 等待系统自动生成历史数据和推荐
+
+## 功能特性
+
+### 📊 数据可视化
+- **偏好概览卡片** - 收藏运动、每周训练时长、活跃目标、提醒数量
+- **运动类型分布图** - 彩色饼图显示各运动类型占比
+- **训练强度分析** - 可视化不同强度级别的分布
+- **每周训练热力图** - 显示一周内各时段的训练模式
+
+### 🎯 智能推荐
+- **运动类型推荐** - 基于用户偏好推荐新运动
+- **训练时长建议** - 根据目标调整训练时间
+- **强度优化建议** - 帮助用户提升训练强度
+- **目标设定提醒** - 鼓励用户设置更多训练目标
+
+### 📈 趋势分析
+- **训练频率趋势** - 显示训练频率的时间变化
+- **目标完成趋势** - 跟踪目标达成情况
+- **运动多样性趋势** - 分析运动类型的多样化程度
+
+## 技术实现
+
+### 前端架构
+- **Vue 3 + UniApp** - 响应式移动端界面
+- **Chart组件** - 自定义图表可视化
+- **动态数据绑定** - 实时数据更新
+- **缓存机制** - 优化性能和用户体验
+
+### 后端架构
+- **PostgreSQL函数** - 高性能数据分析
+- **JSONB数据类型** - 灵活的结构化数据存储
+- **自动触发器** - 实时数据同步
+- **RLS安全策略** - 数据安全保护
+
+## 故障排除
+
+### 常见问题
+1. **SQL语法错误提示**
+   - VS Code中的SQL语法错误是误报（它使用SQL Server解析器）
+   - PostgreSQL语法在实际数据库中会正常工作
+
+2. **分析页面空白**
+   - 检查数据库函数是否正确部署
+   - 验证用户是否有相关数据（偏好设置、目标等）
+
+3. **推荐功能不工作**
+   - 确认`generate_personalized_recommendations`函数已部署
+   - 检查用户是否有足够的基础数据
+
+### 调试方法
+```sql
+-- 检查用户偏好数据
+SELECT * FROM public.ak_user_sport_preferences WHERE user_id = '[用户ID]';
+
+-- 检查分析函数
+SELECT get_user_preferences_analytics('[用户ID]');
+
+-- 检查推荐数据
+SELECT * FROM public.ak_personalized_recommendations WHERE user_id = '[用户ID]';
+```
+
+## 下一步
+部署完成后，分析系统将：
+1. 自动收集用户行为数据
+2. 生成个性化推荐
+3. 提供深度训练分析
+4. 帮助用户优化训练计划
+
+**系统已准备就绪，请按照以上步骤部署数据库扩展！**