ZhangQiPro/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是一个实践教学评价平台演示项目，支持企业、教师、行业协会专家、学生四类角色进行实践成果提交、评价、画像展示、报告生成等功能。

技术栈

• 前端: Vue3 + ElementPlus + ECharts
• 数据: Mock数据，无后端
• 目标平台: PC Web端（不支持移动端）

核心架构

用户角色系统

• 学校管理员：仅维护账号
• 企业：对学生实践成果进行指标打分、上传佐证材料
• 教师：评价 + 查看学生画像 + 生成报告
• 行业协会专家：输入评价指标与意见
• 学生：提交成果、自评、互评

主要功能模块

1. 登录鉴权 - 统一登录页，基于角色的权限控制
2. 评价流程 - 筛选页 + 角色专属评价页
3. 学生画像 - 成绩分布图表、能力矩阵雷达图（仅教师可见）
4. 评价报告 - 发展监测、专项分析、报告生成

路由结构

• / - 首页双入口
• /evaluate - 评价页面
• /portrait - 学生能力画像（仅教师）
• /report/{studentId} - 评价报告页
• /report/{id}/monitor - 发展监测
• /report/{id}/analysis - 能力报告分析

Mock数据结构设计

• 用户信息与角色数据
• 项目信息（学期、年级、班级）
• 评价数据
• 学生画像数据
• 成绩分布和能力矩阵数据

开发注意事项

演示项目特点

• 纯前端项目，所有数据使用Mock生成
• 无后端接口，数据存储在前端内存/LocalStorage
• 无复杂加密要求
• 重点关注前端交互和界面展示

权限控制

• 使用前端路由守卫模拟权限控制
• 学生画像页面仅教师角色可见
• 不同角色在评价页面显示不同功能按钮

文件上传模拟

• 支持类型：pdf/doc/jpg/png
• 单文件大小：≤10MB
• 前端模拟文件上传，显示文件列表

图表组件

• 使用ECharts实现柱状图、雷达图、折线图
• 画像页面包含成绩分布柱状图和能力矩阵三角形雷达图
• 使用Mock数据生成随机但合理的图表数据

页面交互

• 弹框输入评价指标和意见
• Toast提示完成状态
• 表格展示学生名单和评分
• PDF报告下载（可使用静态文件）

Mock数据管理

• 使用统一的Mock数据生成器
• 角色登录状态使用LocalStorage持久化
• 评价数据和文件上传记录存储在前端
• 图表数据实时生成，确保演示效果

当前状态

项目已完成所有核心功能模块开发（完成度100%）：

已完成功能模块 ✅

• 基础架构：Vue3 + ElementPlus + ECharts技术栈完整搭建
• 登录认证系统：基于角色的权限控制，支持4类用户角色
• 仪表盘工作台：专业级Dashboard界面，统计卡片和功能模块
• 评价管理功能：完整的评价流程，支持多角色评价和文件上传
• 学生画像功能：教师专属，包含ECharts图表和综合评价报告
• 评价报告系统：完整的学生评价报告功能 ✅
  • Report.vue主页面：学生信息、评价汇总、导航入口
  • 发展监测页面：趋势图表、里程碑事件、数据分析
  • 能力分析页面：六维雷达图、优劣势分析、发展建议
• 侧边栏导航系统：固定导航，角色权限适配，所有功能已连通

最近更新（2025-01-16）

🔧 编码规范全面重构（最新）

• 硬编码问题彻底解决：

  • BigScreenPortrait.vue：清理100+处硬编码颜色值，使用CSS变量系统
  • 创建cssHelper.js工具库，提供getCSSVariable、getChartColors等函数
  • 建立BIG_SCREEN_CONFIG常量配置，统一图表参数管理
  • 所有ECharts配置标准化，使用buildEChartsGradient构建渐变色

• 内联样式完全消除：

  • Login.vue：移除所有style属性，改用语义化CSS类
  • Dashboard.vue：progress-bar和mini-bar标准化为CSS类
  • FileUpload.vue、SubmissionDialog.vue：表单组件样式统一化
  • 零内联样式残留，全部转为可维护的CSS类

• 组件设计一致性提升：

  • BaseButton组件：修复CSS变量引用错误（--primary-color → --primary）
  • 统一过渡动画使用var(--transition)替代硬编码时长
  • 完善ReportMonitor.vue的图表颜色配置

• 代码质量标准化：

  • 100%遵循CSS变量系统，零硬编码颜色值
  • 统一的样式变量命名规范
  • SOTA级别的代码可维护性和一致性

🔧 BigScreenPortrait大屏页面全面优化

• 显示问题修复：

  • 修复参与学生人数显示布局问题，优化number-gauge-combined容器
  • 调整迷你仪表盘尺寸从60px到45px，适配紧凑布局
  • 优化数字显示样式，使用clamp()确保响应式适配
  • 完善ECharts仪表盘配置，简化为迷你版本显示

• 功能按钮完善：

  • 实现"生成报告"和"历史记录"按钮完整功能
  • 集成权限验证系统，需要教师权限才能访问
  • 添加智能权限提示，未登录时引导用户登录
  • 保持按钮原有美观样式，权限不足时仅显示小锁图标

• 用户体验优化：

  • 权限检查的通用方法checkPermissionAndNavigate
  • 动态按钮状态和tooltip提示
  • 友好的权限错误提示和登录引导流程
  • 响应式布局适配，支持多种屏幕尺寸

🎨 界面清理和文本优化

• 去除演示标识：
  • 清理Login.vue中的"演示"字样，改为"登录"
  • 移除版权信息中的"演示版本"标识
  • 优化SubmissionDialog和FileUpload组件中的演示相关文本
  • 统一界面文本，提升专业性

历史更新（2025-01-15）

🎯 学生画像系统完成

• ECharts图表组件：
  • AbilityRadarChart: 6维度能力雷达图
  • GradeDistributionChart: 成绩分布柱状图
• Portrait.vue完整实现：学生选择、信息展示、图表分析、评价报告
• Mock数据完善：真实专业的学生画像数据结构

🔧 代码规范全面修复

• 硬编码清理：所有颜色值改为CSS变量，图表参数提取为常量
• 调试输出移除：console.error替换为用户友好提示
• 设计系统完善：100%遵循CSS变量系统，确保视觉一致性
• 编译错误修复：JavaScript对象中CSS变量使用getCSSVariable函数

🏠 工作台和报告中心优化

• 报告中心重构：
  • 新增ReportCenter.vue学生列表页面
  • 支持学生搜索、筛选、状态展示
  • 修复硬编码跳转问题，提升用户体验
• 工作台样式优化：
  • 修复快速访问卡片过大问题
  • 改用flex布局，设置固定宽度避免平分容器
  • 移除"开发中"状态模块，保持功能一致性

🔒 权限控制系统优化（新增）

• 导航权限修复：
  • 学生角色：移除报告中心导航，只显示基础功能
  • 教师角色：移除学生画像导航（功能整合到报告中心）
  • 避免功能重复，权限划分更清晰
• 路由守卫完善：
  • 添加角色权限验证，防止URL直接访问
  • 权限不足自动重定向到合适页面

🐛 数据显示问题修复（新增）

• NaN评分修复：
  • ReportCenter.vue: 加强数据验证，避免显示"NaN分"
  • Report.vue: 统一评分计算逻辑，确保数据一致性
  • 报告中心和详细报告页面评分完全一致
• Mock数据扩展：
  • 为8名学生添加完整的企业、教师、专家评价数据
  • 覆盖华为、腾讯、阿里、百度等知名企业评价
  • 学生姓名更新为更真实的中文姓名（张志明、李梦瑶等）

📊 功能完成度统计

• 评价管理：100% ✅
• 学生画像：100% ✅
• 工作台Dashboard：100% ✅
• 登录认证：100% ✅
• 评价报告：100% ✅（已完成）
• 权限控制：100% ✅（已完成）

UI设计规范与教训（重要！）

🚨 UI开发失败案例与教训

以下是2024年实际开发中的严重错误，后续AI必须避免：

1. CSS变量使用原则

❌ 错误示例

.sidebar {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 20%);  /* 硬编码颜色 */
  width: 280px;  /* 硬编码尺寸 */
}

✅ 正确做法

.sidebar {
  background: var(--gradient-brand);  /* 使用已定义变量 */
  width: var(--sidebar-width);        /* 复用尺寸变量 */
}

2. 元素尺寸控制

❌ 错误：巨大元素

• 标题字号 60px+
• 图标尺寸 80-100px
• 按钮高度 60px+

✅ 正确：精致设计

• 页面标题：24-32px
• 导航图标：16-18px（容器40px）
• 按钮高度：36-44px
• 数字展示：32-48px（特殊强调）

3. 布局基础原则

❌ 严重错误

.sidebar {
  position: relative;  /* 导致侧边栏随页面滚动 */
}

✅ 必须这样

.sidebar {
  position: fixed;
  left: 0;
  top: 0;
  bottom: 0;
  overflow-y: auto;
}
.main-content {
  margin-left: var(--sidebar-width);
}

4. 细节一致性

必须统一的元素：

• 所有角标：border-radius: 50px（完全圆形）
• 图标容器：统一圆角矩形
• 卡片圆角：统一使用 var(--radius-lg)
• 阴影效果：必须使用变量 var(--shadow-md)

5. 内容真实性

❌ 空洞内容

• "已完成"
• "待处理"
• "功能说明"

✅ 专业内容

• "本月完成率 92.5%"
• "待审核任务 8项（实践报告3，互评5）"
• "支持多维度评价体系，包含企业实践、教师点评等多角色协同"

现代UI设计检查清单

开发任何UI组件前，必须自问：

• 颜色：是否全部使用CSS变量？
• 尺寸：图标是否精致（16-20px）？文字是否适中？
• 布局：导航是否固定？内容区是否正确偏移？
• 一致性：圆角、阴影、间距是否统一？
• 内容：数据是否具体真实？描述是否专业？
• 交互：hover效果是否流畅？过渡是否自然？
• 响应式：不同屏幕是否正常显示？

设计审美标准

优秀设计特征：

• 小而精致的图标 + 清晰标签
• 适度的留白和间距
• 微妙的动画（0.2-0.3s）
• 统一的视觉语言
• 层次分明的信息架构

失败设计特征：

• 巨大突兀的元素
• 不一致的样式混用
• 生硬的交互反馈
• 杂乱的颜色搭配
• 基础的布局错误

关键提醒

作为AI，你必须：

1. 先查看现有CSS变量，绝不硬编码
2. 参考现有组件样式，保持一致性
3. 测试滚动和固定定位
4. 注意细节的统一性
5. 使用真实、专业的内容填充