peanut
e2b41f23b0
实施内容: - 创建 start-h5-dev.bat 快捷启动脚本 - 更新 CLAUDE.md 添加 H5 开发模式说明 - 创建微信开发者工具配置指南 配套文档: - docs/superpowers/specs/2026-04-07-mini-program-dev-workflow-design.md (设计文档) - docs/superpowers/guides/2026-04-07-wechat-devtools-config.md (配置指南) 解决 issues: 每次代码修改后需要重新登录小程序的问题 工作流：H5 模式日常开发 + 小程序模式最终验证
341 lines
9.1 KiB
Markdown
341 lines
9.1 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
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── 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
|
||
```
|
||
|
||
### mini-program（推荐开发模式）
|
||
|
||
**H5 开发模式**（日常开发，推荐）：
|
||
```bash
|
||
cd mini-program
|
||
# 或使用启动脚本
|
||
start-h5-dev.bat
|
||
```
|
||
访问 `http://localhost:5173`，登录态保留，支持热更新。
|
||
|
||
**微信小程序开发模式**（仅用于小程序特性验证）：
|
||
```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 状态管理
|
||
- 前端访问后端通过网关统一调用
|
||
|
||
---
|
||
|
||
## 验证规则（强制）
|
||
|
||
**修改任何前后端代码后，必须使用浏览器进行验证**
|
||
|
||
### 验证步骤
|
||
|
||
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 级别日志
|