peanut/happy-life-star
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
script-favorite
happy-life-star/AGENTS.md
T

12 KiB
Raw Permalink 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

项目结构

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

# 本地运行
mvn spring-boot:run

# 或直接运行 JAR
java -jar target/server-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）必须使用服务器上部署的后端服务，禁止使用本地后端服务验收。

强制流程

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

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

热加载规则（强制）

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

判断逻辑

  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 级别日志

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

执行任何 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
  • 重启前必须告知用户原因
Reference in New Issue View Git Blame Copy Permalink