ALL-teach_sys/frontend_大健康/CLAUDE.md

项目特定配置和规范

项目结构说明

这是一个教务系统的前端项目，包含多个产业（文旅、智能制造等）的演示数据。

数据更新规范

更新数据时的重要原则

当需要更新某个数据（如班级排名、学生信息等）时，必须遵循以下步骤：

1. 全面搜索数据使用位置

   • 先使用 Grep 工具搜索数据的所有引用位置
   • 不仅搜索直接的变量名，还要搜索相关的字段名
   • 例如：更新班级排名时，搜索 "classRanking", "topStudents", "rankings", "班级排名" 等所有相关关键词

2. 理解数据结构差异

   • 检查不同位置使用的字段名是否一致
   • 例如：有些地方使用 name，有些使用 studentName
   • 确保所有必需字段都存在（如 studentId, studentName, name, avatar, score 等）

3. 一次性更新所有相关位置 需要同时更新的位置通常包括：

   • src/data/mockData.js 中的多个数据对象
     • classRanking 数组
     • ranking.topStudents 数组
     • profileOverview.ranking.rankings 数组
     • user 对象（侧边栏显示）
     • profile 对象（个人信息）
   • 组件中的硬编码数据引用
     • ClassRankModal 组件的数据源
     • ClassRankModal 中的头像映射
   • 外部数据文件引用路径

4. 保持数据一致性

   • 所有显示同一学生的地方必须使用相同的数据
   • 排名、分数、头像等信息必须在所有位置保持一致
   • 注意字段名的差异，必要时添加冗余字段（如同时提供 name 和 studentName）

5. 验证更新完整性

   • 更新后立即检查所有相关页面
   • 确认没有遗漏的"未知"、"小明"等占位数据
   • 检查弹窗、详情页等二级界面

常见数据更新场景

更新班级排名数据

涉及文件和位置：

• src/data/mockData.js:
  • classRanking 数组（Dashboard页面使用）
  • ranking.topStudents 数组（Dashboard班级排名组件使用）
  • profileOverview.ranking.rankings 数组（个人档案页面使用）
• src/components/ClassRankModal/index.jsx:
  • 数据源引用路径
  • 头像URL映射

更新个人信息数据

涉及文件和位置：

• src/data/mockData.js:
  • user 对象（侧边栏显示）
  • profile 对象（个人基本信息）
  • profileOverview 对象（个人档案完整信息）

🔴 产业数据替换严格规范（大健康产业数据替换）

⛔ 绝对禁止的操作

1. 禁止修改任何样式文件

   • 不修改任何 .css 文件
   • 不修改组件内的 style 属性
   • 不修改 className 或任何样式相关代码

2. 禁止修改数据结构

   • 保持原有的字段名不变
   • 保持原有的数据层级关系
   • 保持原有的数据格式（数组、对象等）

3. 禁止修改组件逻辑

   • 不修改 JSX 结构
   • 不修改数据获取方式
   • 不修改渲染逻辑

✅ 正确的数据替换流程

步骤1：深入分析数据引用链

在替换任何数据前，必须：

• 从页面组件开始，追踪数据是如何被引用的
• 理解完整的数据流：页面 → 组件 → service → 数据文件
• 记录所有涉及的文件路径和引用关系

步骤2：理解现有数据格式

• 仔细检查当前数据的每个字段
• 理解字段的含义和用途
• 确认数据类型（字符串、数字、布尔值等）

步骤3：准备替换数据

• 确保新数据完全符合原有格式
• 字段名必须完全一致
• 数据类型必须匹配

步骤4：执行精准替换

• 只在数据源文件中替换内容值
• 不改变任何键名或结构
• 保持所有配置不变

📝 数据替换示例

// ❌ 错误：修改了结构
原始: { name: "智能制造工程师", level: "高级" }
错误: { title: "健康管理师", grade: "高级" }  // 字段名被改变

// ✅ 正确：只替换内容
原始: { name: "智能制造工程师", level: "高级" }
正确: { name: "健康管理师", level: "高级" }  // 保持结构，只换内容

🎯 大健康产业数据源

• 数据来源：网页未导入数据/大健康产业/
• 目标：将智能制造产业数据替换为大健康产业数据
• 原则：内容替换，结构不变

项目特定注意事项

1. 数据字段兼容性

   • 部分组件使用 studentName，部分使用 name
   • 建议在数据中同时提供两个字段以确保兼容性

2. 头像资源管理

   • 所有头像URL都使用完整的CDN地址
   • 头像列表存储在 网页未导入数据/头像列表.json

3. 产业数据切换

   • 文旅产业数据：网页未导入数据/文旅产业/
   • 智能制造产业数据：网页未导入数据/智能制造产业/

4. 开发服务器

   • 端口配置在 vite.config.js
   • 当前使用端口：5151

调试技巧

1. 当页面显示"未知"时，检查：

   • 数据对象是否包含组件所需的字段名
   • 是否有多个同名数据定义导致覆盖
   • 组件是否正确引用了数据源

2. 使用 Grep 工具快速定位：

   # 搜索所有排名相关数据
   grep -r "ranking" src/
   
   # 搜索特定学生名称验证更新完整性
   grep -r "小明\|小华" src/
   

数据更新核心经验（基于智能制造数据更新实战）

🎯 数据更新黄金原则

1. 绝对不能修改任何样式文件 - 包括CSS、组件样式等
2. 必须先分析原始页面的数据引用方式 - 理解数据流向和配置位置
3. 只能在数据源文件中进行替换和修改 - 遵循原有架构

🔍 正确的数据更新流程

第1步：分析原始数据引用

• 查看页面组件如何获取数据
• 追溯数据来源（从组件 → service → 配置文件）
• 找到所有相关的配置文件

第2步：理解数据结构和映射关系

• 分析现有数据的字段名和格式
• 理解数据如何被转换和映射
• 确定组件期望的数据格式

第3步：在正确位置更新配置文件

• 保持原有数据结构不变
• 只在配置文件中添加/替换数据
• 不改变现有字段名和数据格式

❌ 错误做法（绝对避免）

• 修改组件JSX结构
• 添加新的CSS样式
• 创建新的数据获取逻辑
• 重新设计UI组件

✅ 正确做法

• 找到原有的数据配置文件
• 分析现有的数据获取函数
• 在配置文件中添加新数据
• 保持原有架构完整性

📍 关键配置文件位置

• 简历模板数据：src/mocks/resumeInterviewMock.js
• 岗位头像和等级：src/data/joblevel.json
• 岗位基础信息：src/data/companyJobsNew.json
• Mock数据转换：src/data/mockData.js
• 数据服务层：src/services/

🎯 成功案例：智能制造简历数据更新

1. 发现问题：岗位头像和等级标签不显示
2. 错误尝试：修改JobList组件和CSS（❌）
3. 正确方法：发现ResumeInterviewPage使用src/data/joblevel.json配置岗位头像和等级
4. 解决方案：在joblevel.json中添加45个智能制造岗位数据
5. 结果：头像和等级标签完美显示，无需修改任何样式

📋 数据更新检查清单

• 是否分析了原始数据引用方式？
• 是否找到了所有相关的配置文件？
• 是否保持了原有的数据结构？
• 是否避免了修改任何样式文件？
• 是否验证了数据的完整匹配？

提交前检查清单

• 所有测试数据已替换为正式数据
• 没有残留的"未知"、"小明"等占位符
• 各页面数据显示一致
• 弹窗和详情页数据正确
• 控制台无错误信息