peanut/happy-life-star
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
00f17d2f472f7e713b2d2052f6ea54728aa8cfff
happy-life-star/CLAUDE.md
T

14 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

项目结构

.
├── 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 面板查看）
  • 业务功能按预期工作
  • 只有验收通过才算任务完成

部署强制规则（最高优先级，不可违反）

本地开发完成、验证通过、验收没有问题后，必须执行 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 脚本下载服务器日志：

# 下载完整日志
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 层：参数校验失败时返回友好错误提示
  • 前端：接口调用前做空值检查，避免发送无效请求
Reference in New Issue View Git Blame Copy Permalink