happy-life-star/CLAUDE.md

CLAUDE.md

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

---

项目概述

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

生产环境地址: lifescript.happylifeos.com

• 用户前端：https://lifescript.happylifeos.com/
• 管理后台：https://lifescript.happylifeos.com/emotion-museum-admin/
• 后端 API：https://lifescript.happylifeos.com/api
• WebSocket：wss://lifescript.happylifeos.com/ws

---

项目结构

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

---

常用命令

后端 (server)

# 进入后端目录
cd server

# 编译打包
mvn clean package -DskipTests

# 本地运行（必须使用 dev-services.py）
python dev-services.py start server

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

# 运行测试
mvn test

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

用户前端 (web)

# 进入前端目录
cd web

# 安装依赖
npm install

# 启动开发服务器（必须使用 dev-services.py，固定端口 5178）
python dev-services.py start web

# 类型检查
npm run type-check

# 代码检查
npm run lint

# 构建生产版本
npm run build

# 运行测试
npm run test

# E2E 测试
npm run test:e2e

管理后台 (web-admin)

# 进入目录
cd web-admin

# 安装依赖
npm install

# 启动开发服务器（必须使用 dev-services.py，固定端口 5179）
python dev-services.py start web-admin

# 类型检查
npm run type-check

# 代码检查
npm run lint

# 构建生产版本
npm run build

UniApp/小程序

# 进入目录
cd UniApp

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

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

# 开发 H5
npm run dev:h5

# 构建 H5
npm run build:h5

mini-program（推荐开发模式）

H5 开发模式（日常开发，推荐）：

cd mini-program
# 或使用 dev-services.py 启动（固定端口 5180）
python dev-services.py start mini-program

访问 http://localhost:5180，登录态保留，支持热更新。

微信小程序开发模式（仅用于小程序特性验证）：

cd mini-program
npm run dev:mp-weixin

在微信开发者工具中打开 unpackage/dist/dev/mp-weixin。

开发工作流说明：详见 小程序开发工作流程设计

一键部署

# 部署所有服务（后端 + 前端 + 管理后台）到生产服务器
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 状态管理
• 前端访问后端通过网关统一调用

---

服务器端验收强制规则（最高优先级，不可违反）

所有前端功能验收（小程序、用户端 web、管理后台 admin）必须使用服务器上部署的后端服务，禁止使用本地后端服务验收。

强制流程

修改任意后端代码后，必须按以下顺序操作：

1. 编译验证：本地 mvn clean install -DskipTests -am 必须通过，零报错。
2. 部署到服务器：执行 python deploy.py backend（或其他对应模块名），确保部署成功、无报错。
3. 服务器验收：在服务器上已部署的应用进行功能验收。

各前端验收方式

前端	验收方式
小程序	本地 npm run dev:h5 启动 H5（.env.development 已默认指向 lifescript.happylifeos.com），浏览器访问本地 H5 URL，后端请求走服务器
用户端 web	直接访问服务器 URL（https://lifescript.happylifeos.com/）验收
管理后台 admin	直接访问服务器 URL（https://lifescript.happylifeos.com/emotion-museum-admin/）验收

禁止行为

• ❌ 禁止使用 localhost / 127.0.0.1 后端服务做功能验收
• ❌ 禁止绕过 deploy.py 手动部署
• ❌ 禁止在后端编译有报错的情况下部署
• ❌ 禁止部署后不验收就认为任务完成

允许的唯一例外

• ✅ 单元测试 / 集成测试（测试代码可连本地或测试数据库）
• ✅ 纯前端样式/UI 调整（不涉及后端接口，可本地启动 H5 自测）
• ✅ 后端开发阶段的结构验证（仅 mvn 编译，不部署不验收）

deploy.py 模块名速查

• backend — 部署后端到服务器
• frontend — 部署用户端 web
• admin — 部署管理后台
• all — 部署所有服务
• verify — 验证部署状态

验收通过标准

• 浏览器 Console 无任何错误
• 服务器接口响应正常（Network 面板查看）
• 业务功能按预期工作
• 只有验收通过才算任务完成

---

本地服务管理规则（强制）

启动、重启、停止本地前后端服务时，必须使用项目根目录下的 dev-services.py 脚本。

强制要求

• ✅ 必须使用：python dev-services.py [start|stop|restart|status|discover|logs] [服务名]
• ❌ 禁止直接使用 npm run dev / pnpm run dev 启动前端
• ❌ 禁止直接使用 npm run dev:h5 启动小程序 H5
• ❌ 禁止直接使用 mvn spring-boot:run 启动后端
• ❌ 禁止无意义重启支持热加载的服务

前端/H5 固定端口

服务	目录	固定端口
web	web/	5178
web-admin	web-admin/	5179
mini-program	mini-program/	5180
life-script	life-script/	5181

后端服务端口保持原有配置不变。

禁止无意义重启

• 只有修改必须重启才能生效的文件时，才允许执行 restart
• 修改源码文件（.vue、.tsx、.ts、.js、.css、.scss 等）时，dev-services.py restart 会拒绝重启
• 确需强制重启时，使用 python dev-services.py restart --force

热加载规则

1. 不需要重启的场景（热加载自动生效）

   • 前端：修改 .vue、.tsx、.ts、.js、.css、.scss 等源码文件
   • 样式、模板、静态资源等修改

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 级别日志