Files

T

peanut 504ff8191a docs: 小程序 H5 测试登录凭证写入 CLAUDE.md 和 AGENTS.md

- 测试手机号固定使用 19928748688
- 测试验证码固定使用 123456（后端短信通道在测试模式下固定返回）
- 写入登录流程说明，便于每次做小程序功能验收直接参考

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-28 21:54:35 +08:00

17 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

项目结构

.
├── 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。

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

小程序 H5 测试登录凭证（强制默认）

所有小程序功能的 H5 验收必须使用以下测试账号，禁止在测试中使用真实手机号或重复触发验证码接口：

手机号：19928748688（固定测试账号，11 位中国大陆手机号格式）
验证码：123456（固定 6 位数字，生产环境短信通道返回此固定值便于测试）

登录流程（参考 mini-program/src/pages/login/index.vue + mini-program/src/services/auth.js）：

浏览器访问 http://localhost:5180，进入登录页
在手机号输入框填写 19928748688
点击「获取验证码」按钮，调用 GET /api/auth/sms-code?phone=19928748688，后端返回 data.code: "123456"
在验证码输入框填写 123456
点击「登录」按钮，调用 POST /api/auth/login，后端返回 JWT
Token 写入 uni.setStorageSync('access_token', ...)（下划线键名）

为什么固定这两个值：

后端短信通道在测试模式下总是返回 123456，避免真实短信下发和验证码频繁失效
19928748688 是项目的固定测试账号，已绑定测试数据，避免污染真实用户数据

小程序页面固定端口

小程序 H5 固定端口 5180（参考 前端端口管理规则）

一键部署

# 部署所有服务（后端 + 前端 + 管理后台）到生产服务器
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）必须使用服务器上部署的后端服务，禁止使用本地后端服务验收。

强制流程

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

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

各前端验收方式

前端	验收方式
小程序	本地 `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 修复完成后，必须按以下顺序操作：

本地验证：在本地开发环境中完成功能开发和自测，确认无报错。
验收通过：按"服务器端验收强制规则"完成验收，确认功能正常。
执行部署：验收通过后，立即执行部署脚本将应用部署到服务器：
- 后端：python deploy.py backend
- 前端：python deploy.py frontend
- 管理后台：python deploy.py admin
- 全部：python deploy.py all
部署验证：部署完成后，在服务器上验证功能正常，无报错。

禁止行为

❌ 禁止本地开发完成后不部署到服务器就认为任务完成
❌ 禁止跳过验收直接部署
❌ 禁止部署后不验证就结束任务
❌ 禁止在编译或验收有报错的情况下部署

允许的唯一例外

✅ 纯文档修改（不涉及代码变更）
✅ 仅在本地运行的脚本工具（不涉及线上服务）

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

启动、重启、停止本地前后端服务时，必须使用项目根目录下的 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

热加载规则

不需要重启的场景（热加载自动生效）
- 前端：修改 .vue、.tsx、.ts、.js、.css、.scss 等源码文件
- 样式、模板、静态资源等修改
需要重启的场景
- 前端：修改 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 层：参数校验失败时返回友好错误提示
前端：接口调用前做空值检查，避免发送无效请求

17 KiB Raw Blame History Unescape Escape

CLAUDE.md

项目概述

项目结构

常用命令

后端 (server)

用户前端 (web)

管理后台 (web-admin)

UniApp/小程序

mini-program（推荐开发模式）

小程序 H5 测试登录凭证（强制默认）

小程序页面固定端口

一键部署

技术栈

后端

前端

移动端

架构规范

后端分层架构

接口设计规范

前端架构

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

强制流程

各前端验收方式

禁止行为

允许的唯一例外

deploy.py 模块名速查

验收通过标准

自动验证验收规则（最高优先级，不可违反）

自动触发条件

验证方式（按受影响端选择）

禁止行为

验收通过标准

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

强制流程

禁止行为

允许的唯一例外

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

强制要求

前端/H5 固定端口

禁止无意义重启

热加载规则

语言规则（强制）

Git 提交规范

开发规范（来自 Cursor Rules）

基础设置

代码规范

架构规范

接口设计规范

数据库规范

安全规范

性能规范

日志规范

日志排查规则（强制）

1. 检查 conversationId 是否为空

2. 检查权限匹配

3. 常见原因

4. 快速定位方法

5. 防御性编程原则

17 KiB

Raw Blame History