# CLAUDE.md

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

---

## 项目概述

情绪博物馆 (Emotion Museum) 是一款基于 AI 技术的心理健康应用，通过智能对话、情绪分析、个性化成长方案等功能，帮助用户建立健康的情绪管理习惯。

**生产环境地址**: `101.200.208.45`
- 用户前端：http://101.200.208.45/emotion-museum/
- 管理后台：http://101.200.208.45/emotion-museum-admin/
- 后端 API：http://101.200.208.45:19089/api
- WebSocket：ws://101.200.208.45:19089/ws

---

## 项目结构

```
.
├── backend-single/          # Spring Boot 单体后端服务
├── web/                     # 用户前端 (Vue3 + TS + Vite)
├── web-admin/               # 管理后台 (Vue3 + TS + Element Plus)
├── UniApp/                  # 跨平台移动应用 (微信小程序/H5)
├── mini-program/            # 小程序项目
├── course-web/              # 课程 Web 项目
├── life-script/             # 生活脚本工具
└── tools/                   # 工具脚本
```

---

## 常用命令

### 后端 (backend-single)

```bash
# 进入后端目录
cd backend-single

# 编译打包
mvn clean package -DskipTests

# 本地运行
mvn spring-boot:run

# 或直接运行 JAR
java -jar target/backend-single-1.0.0.jar

# 运行测试
mvn test

# 运行单个测试类
mvn test -Dtest=ClassNameTest
```

### 用户前端 (web)

```bash
# 进入前端目录
cd web

# 安装依赖
npm install

# 启动开发服务器 (端口 5173)
npm run dev

# 类型检查
npm run type-check

# 代码检查
npm run lint

# 构建生产版本
npm run build

# 运行测试
npm run test

# E2E 测试
npm run test:e2e
```

### 管理后台 (web-admin)

```bash
# 进入目录
cd web-admin

# 安装依赖
npm install

# 启动开发服务器 (端口 5174)
npm run dev

# 类型检查
npm run type-check

# 代码检查
npm run lint

# 构建生产版本
npm run build
```

### UniApp/小程序

```bash
# 进入目录
cd UniApp

# 开发微信小程序
npm run dev:mp-weixin

# 构建微信小程序
npm run build:mp-weixin

# 开发 H5
npm run dev:h5

# 构建 H5
npm run build:h5
```

### 一键部署

```bash
# 部署所有服务（后端 + 前端 + 管理后台）到生产服务器
bash deploy-all.sh

# 仅部署后端
bash deploy-all.sh backend

# 仅部署前端
bash deploy-all.sh frontend

# 仅部署管理后台
bash deploy-all.sh admin
```

---

## 技术栈

### 后端
- **框架**: Spring Boot 2.7.18
- **ORM**: MyBatis-Plus 3.5.3.1
- **数据库**: MySQL 8.0.33
- **缓存**: Redis 7.0+
- **JWT**: io.jsonwebtoken 0.11.5
- **构建**: Maven 3.6+
- **JDK**: 17

### 前端
- **框架**: Vue 3.4.x + TypeScript 5.x
- **构建**: Vite 5.x
- **UI**: Element Plus 2.4.x
- **样式**: Tailwind CSS 3.4.x
- **状态管理**: Pinia 2.1.x
- **路由**: Vue Router 4.2.x
- **HTTP**: Axios 1.6.x
- **实时通信**: @stomp/stompjs + SockJS
- **图表**: ECharts 5.4.x
- **包管理**: npm 9+

### 移动端
- **框架**: UniApp (Vue 3)
- **平台**: 微信小程序、H5

---

## 架构规范

### 后端分层架构
- **Controller 层**: 接口定义，参数校验，禁止业务逻辑
- **Service 层**: 业务逻辑实现
- **Mapper 层**: 数据访问层
- **Entity 层**: 数据实体
- **Request/Response 层**: 入参出参封装
- **Config 层**: 配置类

### 接口设计规范
- Controller 层路由禁止添加 `/api` 前缀
- 使用 `@RequestParam` 传递路径参数，禁止使用 `@PathVariable`
- 接口方法参数不超过两个，超出时使用 Request/DTO 对象封装
- 使用项目已有的 `Result` 作为统一接口返回
- 禁止使用枚举类型作为接口入参

### 前端架构
- 使用 Vue 3 Composition API (`<script setup>`)
- 使用 TypeScript 进行类型检查
- 组件通信优先使用 Pinia 状态管理
- 前端访问后端通过网关统一调用

---

## 验证规则（强制）

**修改任何前后端代码后，必须使用浏览器进行验证**

### 验证步骤

1. **使用浏览器工具打开对应页面**
   - 使用 `agent-browser` skill 或 MCP 工具
   - 前台页面：通常是 `http://localhost:5173` 或项目指定端口
   - 管理端页面：通常是 `http://localhost:5174` 或项目指定路径

2. **验证标准**（全部满足才算通过）
   - ✅ 前端修改已生效
   - ✅ 页面没有报错
   - ✅ 可以正常访问
   - ✅ 浏览器 Console 中没有任何错误

3. **只有验证通过才算任务完成**

---

## 热加载规则（强制）

**修改前后端代码后，优先利用热加载，避免不必要的重启**

### 判断逻辑

1. **不需要重启的场景**（热加载自动生效）
   - 前端：修改 `.vue`、`.tsx`、`.ts`、`.js`、`.css`、`.scss` 等源码文件
   - 后端：修改业务逻辑、API 接口、组件代码等支持热更新的文件
   - 样式、模板、静态资源等修改

2. **需要重启的场景**（热加载无法生效）
   - 前端：修改 `vite.config.ts`、`tsconfig.json`、`.env`、`package.json`、别名配置等
   - 后端：修改启动配置、数据库连接、中间件注册、环境变量等
   - 新增或删除依赖包后

### 操作原则

- 修改后先观察终端输出，确认热加载是否成功
- 只有修改了必须重启才能生效的配置时，才执行重启操作
- 重启前后端服务前，需告知用户

---

## 语言规则（强制）

- 所有对话和文档使用**中文**
- 代码内容（变量名、函数名、注释）使用英文
- 技术术语保持英文（API、HTTP、JSON 等）

---

## Git 提交规范

- 使用中文提交
- 格式：`类型：描述`
- 类型包括：feat, fix, docs, style, refactor, test, chore

---

## 开发规范（来自 Cursor Rules）

### 基础设置
- 保持对话语言为中文
- 不允许在未经允许的情况下删除代码和文件
- 不允许破坏正常的业务代码
- 执行终端命令时要关注执行情况，避免无效等待

### 代码规范
- 生成代码时必须添加类级和函数级注释
- 使用 `import` 导包，禁止使用全限定名称引用类
- 禁止使用枚举类型作为 Entity、Request、Response、DTO 对象的字段
- 禁止以枚举类作为方法的入参
- 新增数据的 id 使用已存在的雪花算法生成器生成

### 架构规范
- Controller 层禁止添加业务逻辑
- 使用全局异常处理，禁止使用 try-catch
- 前端接口访问尽可能走网关调用

### 接口设计规范
- Controller 层接口定义：
  - 入参使用 request 封装传递到 service 层
  - service 层方法命名与 controller 层保持一致
  - 出参使用 response 封装由 service 层传递到 controller 层
  - 禁止在 controller 层做 entity 与 request/response 的转换
  - 使用项目已有的 `Result` 做接口返回
- 接口和方法参数不允许超过两个，超过时使用 request 或 DTO 对象封装
- Controller 层路由禁止添加 `/api` 前缀
- Controller 层 `@RequestMapping` 的 value 属性值不允许重复且不允许为空
- 必须明确指定 value 属性值且使用驼峰结构命名，避免使用下划线
- 禁止使用 `@GetMapping()` 或 `@PostMapping` 等空注解形式
- 用户相关接口禁止直接传递用户 id，需要后端根据 token 获取当前登录用户信息
- 禁止使用 `/{param}` 格式的路径参数，避免网关路由冲突
- 路径参数统一使用 `@RequestParam` 而非 `@PathVariable`
- 接口路径命名应具有明确的语义，避免使用通用词汇如 `/get`、`/list` 等
- 批量操作接口应使用专门的 Request 对象封装参数，而非直接传递 List
- 接口路径应避免层级过深，建议不超过 3 级路径结构

### 数据库规范
- 所有数据表必须包含 `create_time` 和 `update_time` 字段
- 删除操作优先使用逻辑删除，添加 `deleted` 字段标识
- 数据库字段命名使用下划线分隔，Java 实体类使用驼峰命名
- 优先使用 `LambdaQueryWrapper` 构造条件查询
- 使用 Lambda 表达式引用实体类属性，提高代码可维护性
- 复杂查询条件应使用 `LambdaQueryWrapper` 的链式调用

### 安全规范
- 所有外部输入必须进行参数校验
- 敏感信息不得在日志中输出
- 数据库操作必须使用参数化查询，防止 SQL 注入

### 性能规范
- 避免 N+1 查询问题，合理使用批量查询
- 大数据量查询必须分页处理
- 缓存策略要考虑数据一致性问题

### 日志规范
- 关键业务操作必须记录操作日志
- 异常信息要包含足够的上下文信息
- 生产环境禁止输出 debug 级别日志