# backend

**Repository Path**: psychology_agent/backend

## Basic Information

- **Project Name**: backend
- **Description**: springboot后端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-04
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Psychology 后端

`psychology` 是一个多模块 Spring Boot 后端，用于支撑青少年心理健康对话系统。它负责认证鉴权、对话管理、心理测评、情绪识别、周数据、后台管理，以及与外部 FastAPI Agent、MySQL、Redis、阿里云 TTS 的集成。

## 当前架构

```text
Frontend (Vue3 / Web)
        |
        v
psychology (Spring Boot, port 8080)
        |
        +-- MySQL
        +-- Redis
        +-- FastAPI Agent (SSE)
        +-- Aliyun TTS
```

当前代码中的关键链路：

- 登录和注册由 `psychology-auth` 提供。
- 聊天接口由 `psychology-agent` 提供，聊天内容转发到外部 FastAPI 服务。
- 心理测评、用户档案、后台统计等数据落在 MySQL。
- 对话映射、登录限流等依赖 Redis。
- 流式聊天在句子边界触发异步 TTS，音频事件通过 SSE 回传前端。

## 模块结构

```text
psychology/
├── psychology-admin/    # 管理员接口与统计
├── psychology-agent/    # 对话、情绪识别、会话管理
├── psychology-auth/     # 登录、注册、JWT、安全配置
├── psychology-boot/     # 启动模块、配置文件、schema.sql
├── psychology-common/   # Result、异常处理、公共 Web 配置
├── psychology-data/     # 周睡眠 / 周压力数据
├── psychology-system/   # 用户档案、心理测评
└── psychology-tts/      # TTS 配置与合成接口
```

## 技术栈

- Java 17
- Spring Boot 3.5.11
- Spring Security 6.4.3
- Spring Web MVC + Spring WebFlux
- MyBatis 3.0.5
- Redis
- MySQL 8
- JWT (`jjwt 0.12.6`)
- Resilience4j
- Spring AI Ollama 1.1.2
- SpringDoc OpenAPI UI 2.3.0
- 阿里云 NLS TTS SDK

## 当前接口概览

真实控制器路径以代码为准，当前接口分组如下：

| 模块 | 基础路径 | 说明 |
| --- | --- | --- |
| 认证 | `/api/auth` | 登录、注册 |
| 用户档案 | `/api/auth/profile` | 获取 / 保存用户档案 |
| 心理测评 | `/api/system/assessments` | 查询 / 提交测评 |
| 对话 | `/api/agent` | 普通聊天、SSE 流式聊天、历史记录、会话列表、清空会话 |
| 情绪识别 | `/api/agent/emotion` | 表情分析与历史记录 |
| 周数据 | `/api/agent/weekly` | 周睡眠 / 周压力数据 |
| 管理端 | `/api/admin` | 用户管理、风险评估、系统统计 |
| TTS | `/api/tts` | 测试与单句语音合成 |

更详细的接口字段和返回示例见 [API_DOCUMENT.md](/X:/Work/Projects/psychology/API_DOCUMENT.md)。

## 鉴权与返回格式

### 鉴权规则

- 只有 `/api/auth/login` 和 `/api/auth/register` 是匿名可访问。
- 其它接口都要求 `Authorization: Bearer <token>`。
- `AdminController` 整体要求 `ADMIN` 角色。
- `UserProfileController` 额外做了“本人或管理员”校验。

### 统一响应

除 TTS 控制器外，绝大多数接口返回：

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

注意：

- `TTS` 的 `GET /api/tts/test` 直接返回纯文本 `"TTS服务正常"`。
- `TTS` 的 `POST /api/tts/synthesize` 直接返回 JSON 对象，不包 `Result<T>`。
- 业务异常由全局异常处理器统一转换，部分业务失败场景会出现 HTTP 200，但响应体中的 `code != 200`。

## 配置说明

主配置文件位于：

- `psychology-boot/src/main/resources/application.yml`
- `psychology-boot/src/main/resources/application-dev.yml`
- `psychology-boot/src/main/resources/application-prod.yml`

### 关键配置项

| 配置 | 默认值 / 示例 | 说明 |
| --- | --- | --- |
| `server.port` | `8080` | 服务端口 |
| `spring.profiles.active` | `dev` | 默认启用开发环境 |
| `spring.datasource.*` | 本地 MySQL | 数据库连接 |
| `spring.data.redis.*` | `localhost:6379` | Redis 连接 |
| `fastapi.agent.base-url` | `http://localhost:8000` | FastAPI Agent 地址 |
| `fastapi.agent.chat-endpoint` | `/api/chat/stream` | FastAPI SSE 路径 |
| `tts.enabled` | `true` | 是否启用 TTS |
| `tts.dynamic-token-enabled` | `true` | 是否动态获取阿里云 Token |
| `tts.format` | `mp3` | 当前默认音频格式 |
| `tts.voice` | `zhimi_emo` | 当前默认发音人 |

### 常用环境变量

```bash
FASTAPI_URL=http://localhost:8000
FASTAPI_AGENT_URL=http://fastapi-agent:8000

ALIYUN_TTS_ACCESS_KEY=your-app-key
ALIYUN_TTS_ACCESS_TOKEN=your-static-token
ALIYUN_AK_ID=your-access-key-id
ALIYUN_AK_SECRET=your-access-key-secret

TTS_ENABLED=true
TTS_DYNAMIC_TOKEN_ENABLED=true
TTS_URL=wss://nls-gateway-cn-beijing.aliyuncs.com/ws/v1
TTS_VOICE=zhimi_emo
TTS_FORMAT=mp3
TTS_SAMPLE_RATE=16000
TTS_VOLUME=50
TTS_PITCH_RATE=0
TTS_SPEECH_RATE=50
TTS_MIN_SEND_INTERVAL=100
```

说明：

- 开发环境读取 `FASTAPI_URL`。
- 生产环境配置中使用 `FASTAPI_AGENT_URL`。
- TTS 支持“静态 Token”和“动态 Token”两种模式，当前默认走动态 Token。

## 数据库初始化

初始化脚本在：

- [schema.sql](/X:/Work/Projects/psychology/psychology-boot/src/main/resources/db/schema.sql)

执行方式：

```bash
mysql -u root -p < psychology-boot/src/main/resources/db/schema.sql
```

脚本会：

- 创建 `psychology` 数据库。
- 创建用户、档案、对话、消息、测评、情绪结果、周数据表。
- 插入默认管理员：

```text
username: admin
password: admin123
```

## 本地启动

### 环境要求

- JDK 17+
- Maven 3.6+
- MySQL 8+
- Redis 6+
- 可访问的 FastAPI Agent 服务
- 若启用 TTS，需要可用的阿里云 TTS 凭据

### 构建

```bash
mvn clean package -DskipTests
```

### 启动

```bash
mvn -pl psychology-boot -am spring-boot:run
```

或：

```bash
java -jar psychology-boot/target/psychology-boot-1.0.0-SNAPSHOT.jar
```

### 健康检查

```bash
curl http://localhost:8080/actuator/health
```

## 运行期行为补充

### 登录限流

`AuthService` 当前实现包含基于 Redis 的登录限流：

- 5 分钟窗口内最多 5 次失败尝试。
- 超限后锁定 15 分钟。

### CORS

当前允许的前端来源：

- `http://localhost:5173`
- `http://localhost:8080`

### SSE 与 TTS

流式聊天接口为 `POST /api/agent/chat/stream`，返回 `text/event-stream`。

当前实现中的音频生成逻辑：

- 仅当事件类型为 `token` 且检测到句末标点时，触发 TTS。
- 句末标点包含 `。？！.?！`。
- 音频异步生成，不阻塞文本流。
- 音频事件中的 `audioData` 为 `byte[]`，序列化到 JSON 时通常表现为 Base64 字符串。

## 当前文档已修正的主要偏差

这次更新已按代码修正以下旧信息：

- 用户档案真实路径是 `/api/auth/profile/{userId}`，不是 `/api/system/profile/{userId}`。
- 心理测评当前只有 `GET/POST /api/system/assessments`，没有旧文档中的内部保存接口。
- 用户档案字段类型已更新为 `stressLevel: Integer`、`sleepQuality: String`。
- 管理端用户创建 / 更新使用 `roles` JSON 字符串，不是单个 `role` 字段。
- 系统统计字段是 `riskHighUsers`、`riskMediumUsers`，不是单个 `riskUsers`。
- TTS 接口不走统一 `Result<T>` 包装。
- TTS 默认输出格式当前是 `mp3`，不是旧文档里的 `wav`。
- 数据库初始化脚本实际位于 `psychology-boot/src/main/resources/db/schema.sql`。