Files

T

peanut e2b41f23b0 feat(mini-program): 添加 H5 开发工作流支持

实施内容:
- 创建 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 模式日常开发 + 小程序模式最终验证

2026-04-07 21:12:46 +08:00

9.1 KiB

Raw Blame History

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)

# 进入后端目录
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)

# 进入前端目录
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)

# 进入目录
cd web-admin

# 安装依赖
npm install

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

# 类型检查
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
# 或使用启动脚本
start-h5-dev.bat

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

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

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 状态管理
前端访问后端通过网关统一调用

验证规则（强制）

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

验证步骤

使用浏览器工具打开对应页面
- 使用 agent-browser skill 或 MCP 工具
- 前台页面：通常是 http://localhost:5173 或项目指定端口
- 管理端页面：通常是 http://localhost:5174 或项目指定路径
验证标准（全部满足才算通过）
- ✅ 前端修改已生效
- ✅ 页面没有报错
- ✅ 可以正常访问
- ✅ 浏览器 Console 中没有任何错误
只有验证通过才算任务完成

热加载规则（强制）

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

判断逻辑

不需要重启的场景（热加载自动生效）
- 前端：修改 .vue、.tsx、.ts、.js、.css、.scss 等源码文件
- 后端：修改业务逻辑、API 接口、组件代码等支持热更新的文件
- 样式、模板、静态资源等修改
需要重启的场景（热加载无法生效）
- 前端：修改 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 级别日志

9.1 KiB Raw Blame History Unescape Escape

CLAUDE.md

项目概述

项目结构

常用命令

后端 (backend-single)

用户前端 (web)

管理后台 (web-admin)

UniApp/小程序

mini-program（推荐开发模式）

一键部署

技术栈

后端

前端

移动端

架构规范

后端分层架构

接口设计规范

前端架构

验证规则（强制）

验证步骤

热加载规则（强制）

判断逻辑

操作原则

语言规则（强制）

Git 提交规范

开发规范（来自 Cursor Rules）

基础设置

代码规范

架构规范

接口设计规范

数据库规范

安全规范

性能规范

日志规范

9.1 KiB

Raw Blame History