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变量使用原则
**❌ 错误示例**
```css
.sidebar {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 20%);  /* 硬编码颜色 */
  width: 280px;  /* 硬编码尺寸 */
}
```

**✅ 正确做法**
```css
.sidebar {
  background: var(--gradient-brand);  /* 使用已定义变量 */
  width: var(--sidebar-width);        /* 复用尺寸变量 */
}
```

#### 2. 元素尺寸控制
**❌ 错误：巨大元素**
- 标题字号 60px+
- 图标尺寸 80-100px
- 按钮高度 60px+

**✅ 正确：精致设计**
- 页面标题：24-32px
- 导航图标：16-18px（容器40px）
- 按钮高度：36-44px
- 数字展示：32-48px（特殊强调）

#### 3. 布局基础原则
**❌ 严重错误**
```css
.sidebar {
  position: relative;  /* 导致侧边栏随页面滚动 */
}
```

**✅ 必须这样**
```css
.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. 使用真实、专业的内容填充