504 lines
16 KiB
Markdown
504 lines
16 KiB
Markdown
# 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)
|
||
|
||
```bash
|
||
# 进入后端目录
|
||
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)
|
||
|
||
```bash
|
||
# 进入前端目录
|
||
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)
|
||
|
||
```bash
|
||
# 进入目录
|
||
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/小程序
|
||
|
||
```bash
|
||
# 进入目录
|
||
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 开发模式**（日常开发，推荐）：
|
||
```bash
|
||
cd mini-program
|
||
# 或使用 dev-services.py 启动（固定端口 5180）
|
||
python dev-services.py start mini-program
|
||
```
|
||
访问 `http://localhost:5180`，登录态保留，支持热更新。
|
||
|
||
**微信小程序开发模式**（仅用于小程序特性验证）：
|
||
```bash
|
||
cd mini-program
|
||
npm run dev:mp-weixin
|
||
```
|
||
在微信开发者工具中打开 `unpackage/dist/dev/mp-weixin`。
|
||
|
||
**开发工作流说明**：详见 [小程序开发工作流程设计](docs/superpowers/specs/2026-04-07-mini-program-dev-workflow-design.md)
|
||
|
||
### 一键部署
|
||
|
||
```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 状态管理
|
||
- 前端访问后端通过网关统一调用
|
||
|
||
---
|
||
|
||
## 服务器端验收强制规则（最高优先级，不可违反）
|
||
|
||
**所有前端功能验收（小程序、用户端 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 面板查看）
|
||
- 业务功能按预期工作
|
||
- 只有验收通过才算任务完成
|
||
|
||
---
|
||
|
||
## 自动验证验收规则（最高优先级，不可违反）
|
||
|
||
**每次代码变更任务完成前，必须自动通过浏览器进行验证验收，无需用户额外要求。**
|
||
|
||
### 自动触发条件
|
||
|
||
以下任一种情况都视为"任务完成前"，必须自动执行验证：
|
||
|
||
- 修改了后端 Java 代码，完成部署后，必须通过 H5/浏览器调用真实接口验证
|
||
- 修改了 mini-program 前端代码，热加载生效后，必须在浏览器中操作验证
|
||
- 修改了任意代码并声称"完成"，必须走一遍受影响功能的完整体验流程
|
||
|
||
### 验证方式（按受影响端选择）
|
||
|
||
| 变更范围 | 验证方式 |
|
||
|---|---|
|
||
| 后端 Java 代码 | 部署后，通过本地 H5（连服务器 API）或 curl 验证接口 |
|
||
| mini-program（小程序） | H5 模式浏览器验证（`http://localhost:5180`） |
|
||
| web 用户端 | 浏览器访问 `http://localhost:5178` 或服务器 URL |
|
||
| web-admin 管理后台 | 浏览器访问 `http://localhost:5179` 或服务器 URL |
|
||
|
||
### 禁止行为
|
||
|
||
- ❌ 禁止代码改完就直接回复"完成"，不执行验证
|
||
- ❌ 禁止仅凭编译通过就认为任务结束
|
||
- ❌ 禁止等用户提醒后才去验证
|
||
- ❌ 禁止跳过浏览器 Console / Network 面板检查
|
||
|
||
### 验收通过标准
|
||
|
||
- 浏览器 Console 无**新增**错误（既有的已知兼容性警告除外）
|
||
- Network 面板中受影响的 API 返回正常（200 或业务预期状态码）
|
||
- 受影响的 UI 交互逻辑按预期工作（点击、切换、展示）
|
||
|
||
---
|
||
|
||
## 部署强制规则（最高优先级，不可违反）
|
||
|
||
**本地开发完成、验证通过、验收没有问题后，必须执行 `deploy.py` 部署脚本，将应用部署到服务器上。**
|
||
|
||
### 强制流程
|
||
|
||
每次功能开发或 bug 修复完成后，必须按以下顺序操作：
|
||
|
||
1. **本地验证**：在本地开发环境中完成功能开发和自测，确认无报错。
|
||
2. **验收通过**：按"服务器端验收强制规则"完成验收，确认功能正常。
|
||
3. **执行部署**：验收通过后，立即执行部署脚本将应用部署到服务器：
|
||
- 后端：`python deploy.py backend`
|
||
- 前端：`python deploy.py frontend`
|
||
- 管理后台：`python deploy.py admin`
|
||
- 全部：`python deploy.py all`
|
||
4. **部署验证**：部署完成后，在服务器上验证功能正常，无报错。
|
||
|
||
### 禁止行为
|
||
|
||
- ❌ 禁止本地开发完成后不部署到服务器就认为任务完成
|
||
- ❌ 禁止跳过验收直接部署
|
||
- ❌ 禁止部署后不验证就结束任务
|
||
- ❌ 禁止在编译或验收有报错的情况下部署
|
||
|
||
### 允许的唯一例外
|
||
|
||
- ✅ 纯文档修改（不涉及代码变更）
|
||
- ✅ 仅在本地运行的脚本工具（不涉及线上服务）
|
||
|
||
---
|
||
|
||
## 本地服务管理规则（强制）
|
||
|
||
**启动、重启、停止本地前后端服务时，必须使用项目根目录下的 `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 级别日志
|
||
|
||
---
|
||
|
||
## 日志排查规则（强制）
|
||
|
||
**遇到"对话不存在或无权限"错误时，按以下顺序排查：**
|
||
|
||
### 1. 检查 conversationId 是否为空
|
||
|
||
- **前端检查**：在浏览器 DevTools Network 面板查看请求参数 `conversationId`
|
||
- **后端检查**：查看 `UserContextHolder.getCurrentUserId()` 是否返回有效值
|
||
- **数据库检查**：执行 `SELECT * FROM t_conversation WHERE id = '<conversationId>'` 确认对话是否存在
|
||
|
||
### 2. 检查权限匹配
|
||
|
||
- **前端问题**：当前登录用户的 userId 与对话的 userId 不一致
|
||
- **后端逻辑**：`ScriptMessageServiceImpl.listByConversation` 中会校验 `conversation.getUserId().equals(currentUserId)`
|
||
- **修复方案**：确认前端传递的是正确的 conversationId，或重新创建对话
|
||
|
||
### 3. 常见原因
|
||
|
||
| 原因 | 解决方案 |
|
||
|------|----------|
|
||
| conversationId 为空字符串 | 前端增加短路保护，显示"暂无对话记录"提示 |
|
||
| 对话不存在（已删除） | 引导用户创建新对话 |
|
||
| 用户未登录 | 检查 Token 是否有效，重新登录 |
|
||
| 对话属于其他用户 | 确认前端传递的 conversationId 正确 |
|
||
|
||
### 4. 快速定位方法
|
||
|
||
使用 `tools/download-server-log.py` 脚本下载服务器日志：
|
||
|
||
```bash
|
||
# 下载完整日志
|
||
python tools/download-server-log.py latest
|
||
|
||
# 只看最近 50 条错误
|
||
python tools/download-server-log.py errors 50
|
||
|
||
# 搜索特定关键词（如 listByConversation）
|
||
python tools/download-server-log.py grep "listByConversation" 20
|
||
```
|
||
|
||
日志位置：`logs/server/` 目录
|
||
|
||
### 5. 防御性编程原则
|
||
|
||
- **Service 层**：对空参数做防御性检查，返回空列表而非抛异常
|
||
- **Controller 层**：参数校验失败时返回友好错误提示
|
||
- **前端**：接口调用前做空值检查，避免发送无效请求
|