409 lines
12 KiB
Markdown
409 lines
12 KiB
Markdown
# 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
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── server/ # Spring Boot 单体后端服务
|
||
├── web/ # 用户前端 (Vue3 + TS + Vite)
|
||
├── web-admin/ # 管理后台 (Vue3 + TS + Element Plus)
|
||
├── UniApp/ # 跨平台移动应用 (微信小程序/H5)
|
||
├── mini-program/ # 小程序项目
|
||
├── course-web/ # 课程 Web 项目
|
||
├── life-script/ # 生活脚本工具
|
||
└── tools/ # 工具脚本
|
||
```
|
||
|
||
---
|
||
|
||
## 常用命令
|
||
|
||
### 后端 (server)
|
||
|
||
```bash
|
||
# 进入后端目录
|
||
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)
|
||
|
||
```bash
|
||
# 进入前端目录
|
||
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)
|
||
|
||
```bash
|
||
# 进入目录
|
||
cd web-admin
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器 (端口 5174)
|
||
npm run dev
|
||
|
||
# 类型检查
|
||
npm run type-check
|
||
|
||
# 代码检查
|
||
npm run lint
|
||
|
||
# 构建生产版本
|
||
npm run build
|
||
```
|
||
|
||
### UniApp/小程序
|
||
|
||
```bash
|
||
# 进入目录
|
||
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 开发模式**（日常开发，推荐）：
|
||
```bash
|
||
cd mini-program
|
||
# 或使用启动脚本
|
||
start-h5-dev.bat
|
||
```
|
||
访问 `http://localhost:5173`，登录态保留，支持热更新。
|
||
|
||
**微信小程序开发模式**（仅用于小程序特性验证）：
|
||
```bash
|
||
cd mini-program
|
||
npm run dev:mp-weixin
|
||
```
|
||
在微信开发者工具中打开 `unpackage/dist/dev/mp-weixin`。
|
||
|
||
**开发工作流说明**：详见 [小程序开发工作流程设计](docs/superpowers/specs/2026-04-07-mini-program-dev-workflow-design.md)
|
||
|
||
### 一键部署
|
||
|
||
```bash
|
||
# 部署所有服务（后端 + 前端 + 管理后台）到生产服务器
|
||
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` 隐藏窗口。
|
||
|
||
### 启动前检查（强制）
|
||
|
||
**启动任何开发服务器前，必须先检查目标端口是否已被占用：**
|
||
|
||
```powershell
|
||
# Windows
|
||
netstat -ano | findstr "端口号"
|
||
# macOS/Linux
|
||
lsof -i :端口号
|
||
```
|
||
|
||
如果端口已被占用，必须先终止旧进程再启动新进程，**禁止重复启动**导致端口递增。
|
||
|
||
### 热加载优先原则
|
||
|
||
Vite / Webpack 等现代构建工具支持热更新（HMR）：
|
||
- **启动一次即可**：`npm run dev` 启动后，修改源码文件会自动热更新
|
||
- **禁止频繁重启**：除非修改了 `vite.config.ts`、`.env`、`package.json` 等配置文件，否则不需要重启 dev server
|
||
- 重启前必须告知用户原因
|