peanut/happy-life-star

Fork 0

Files

T

peanut 11f1638eef docs：添加强制规则，禁止本地后端验收，必须使用 deploy.py 部署到服务器验收

2026-06-24 22:17:06 +08:00

12 KiB

Raw Blame History

AGENTS.md

This file provides guidance to Codex (Codex.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 状态管理
前端访问后端通过网关统一调用

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

所有前端功能验收（小程序、用户端 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 面板查看）
业务功能按预期工作
只有验收通过才算任务完成

热加载规则（强制）

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

判断逻辑

不需要重启的场景（热加载自动生效）
- 前端：修改 .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 级别日志

操作系统命令执行规则（强制）

执行任何 Shell 命令前，必须根据当前操作系统（win32 / darwin / linux）选择合适的命令语法。

后台启动长期运行进程（dev server 等）

不同操作系统后台启动进程的方式完全不同，选错会导致命令阻塞或失败：

操作系统	正确方式	错误方式（禁止）
Windows	`Start-Process -FilePath "npm" -ArgumentList "run","dev" -WorkingDirectory "..." -WindowStyle Hidden`	`cmd /c "start /B npm run dev > log 2>&1"`（`cmd /c` 会阻塞等待重定向完成）
macOS/Linux	`nohup npm run dev > log 2>&1 &`

核心原则：

Windows 下 cmd /c "start /B ... > log 2>&1" 绝对禁止用于启动长期运行的后台服务。cmd /c 会等待重定向管道关闭，导致命令无限阻塞。
Windows 下启动后台进程必须使用 PowerShell 的 Start-Process cmdlet，并通过 -WindowStyle Hidden 隐藏窗口。

启动前检查（强制）

启动任何开发服务器前，必须先检查目标端口是否已被占用：

# Windows
netstat -ano | findstr "端口号"
# macOS/Linux
lsof -i :端口号

如果端口已被占用，必须先终止旧进程再启动新进程，禁止重复启动导致端口递增。

热加载优先原则

Vite / Webpack 等现代构建工具支持热更新（HMR）：

启动一次即可：npm run dev 启动后，修改源码文件会自动热更新
禁止频繁重启：除非修改了 vite.config.ts、.env、package.json 等配置文件，否则不需要重启 dev server
重启前必须告知用户原因

12 KiB Raw Blame History Unescape Escape

AGENTS.md

项目概述

项目结构

常用命令

后端 (backend-single)

用户前端 (web)

管理后台 (web-admin)

UniApp/小程序

mini-program（推荐开发模式）

一键部署

技术栈

后端

前端

移动端

架构规范

后端分层架构

接口设计规范

前端架构

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

强制流程

各前端验收方式

禁止行为

允许的唯一例外

deploy.py 模块名速查

验收通过标准

热加载规则（强制）

判断逻辑

操作原则

语言规则（强制）

Git 提交规范

开发规范（来自 Cursor Rules）

基础设置

代码规范

架构规范

接口设计规范

数据库规范

安全规范

性能规范

日志规范

操作系统命令执行规则（强制）

后台启动长期运行进程（dev server 等）

启动前检查（强制）

热加载优先原则

12 KiB

Raw Blame History