# 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-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Psychology - 青少年心理健康对话 Agent 后端

## 项目介绍

`psychology` 是一个基于 Spring Boot 构建的心理健康聊天机器人后端系统，作为整个应用的核心业务层，它负责用户认证、对话管理、数据持久化以及与 AI 智能体的交互。

### 核心价值

- **专业的青少年心理咨询支持**: 为青少年提供安全、私密、专业的心理咨询服务
- **智能对话体验**: 通过 SSE 流式输出技术，提供如打字机般流畅的对话体验
- **全方位心理健康管理**: 支持心理测评、情绪识别、健康数据追踪等功能
- **安全可靠的架构**: 采用 JWT 无状态认证、角色权限控制，确保用户数据安全

### 在系统中的作用

```
前端 (Vue3) ←→ psychology (SpringBoot) ←→ psychology_agent (FastAPI)
                                    ↓
                                MySQL/Redis
```

- 作为前端的统一 API 网关
- 作为 AI Agent 的业务代理层
- 负责数据持久化和业务逻辑处理

---

## 技术架构

### 技术选型

| 技术 | 说明 | 优势 |
|------|------|------|
| **Spring Boot 3.5.11** | 核心应用框架 | 快速开发、自动配置、生态丰富 |
| **Spring Security 6.4.3** | 安全框架 | 细粒度权限控制、易于集成 |
| **Spring AI (Ollama)** | AI 模型集成 | 简化 LLM 集成、支持流式输出 |
| **Spring WebFlux** | 响应式 Web 框架 | 支持 SSE、高并发场景 |
| **MyBatis 3.0.5** | ORM 框架 | 灵活 SQL、性能优秀 |
| **JWT (jjwt 0.12.6)** | 令牌认证 | 无状态、跨域友好 |
| **Lombok** | 代码简化 | 减少样板代码、提高可读性 |
| **Maven** | 构建工具 | 依赖管理、多模块支持 |

### 架构分层

```
┌─────────────────────────────────────────┐
│           Controller 层                  │  ← HTTP 接口
│  (AuthController, AgentController...)    │
├─────────────────────────────────────────┤
│           Service 层                     │  ← 业务逻辑
│  (AuthService, AgentService...)          │
├─────────────────────────────────────────┤
│           Mapper 层                      │  ← 数据访问
│  (UserMapper, ConversationMapper...)     │
├─────────────────────────────────────────┤
│         Entity / DTO 层                  │  ← 数据模型
│  (User, Conversation, Message...)        │
└─────────────────────────────────────────┘
```

---

## 项目结构

### 模块划分

```
psychology/
├── psychology-admin/       # 后台管理模块
│   ├── controller/         # 管理接口控制器
│   ├── service/            # 管理业务逻辑
│   └── dto/                # 数据传输对象
│
├── psychology-auth/        # 认证授权模块
│   ├── controller/         # 登录/注册接口
│   ├── service/            # 认证服务
│   ├── jwt/                # JWT 令牌工具
│   ├── filter/             # 认证过滤器
│   ├── entity/             # 用户实体
│   └── dto/                # 认证请求/响应
│
├── psychology-agent/       # 智能体代理模块
│   ├── controller/         # 对话/情绪分析接口
│   ├── service/            # 对话服务、记忆管理
│   ├── client/             # FastAPI 客户端
│   ├── entity/             # 对话/消息实体
│   └── dto/                # 对话请求/响应
│
├── psychology-system/      # 系统业务模块
│   ├── controller/         # 用户档案/测评接口
│   ├── service/            # 档案/测评服务
│   ├── entity/             # 档案/测评实体
│   └── dto/                # 档案请求/响应
│
├── psychology-data/        # 健康数据模块
│   ├── controller/         # 睡眠/压力数据接口
│   ├── service/            # 数据服务
│   └── entity/             # 睡眠/压力实体
│
├── psychology-tts/         # TTS文本转语音模块
│   ├── controller/         # TTS接口控制器
│   ├── service/            # TTS合成服务
│   ├── config/             # TTS客户端配置
│   └── dto/                # TTS请求/响应
│
├── psychology-common/      # 公共模块
│   ├── common-core/        # 核心工具类
│   │   └── Result.java    # 统一响应封装
│   └── common-web/         # Web 通用配置
│
└── psychology-boot/        # 启动模块
    └── application.yml     # 应用配置
```

### 主要包说明

| 包名 | 职责 |
|------|------|
| `controller` | REST API 接口定义，处理 HTTP 请求 |
| `service` | 核心业务逻辑实现 |
| `mapper` | MyBatis 数据访问接口 |
| `entity` | 数据库实体类 |
| `dto` | 数据传输对象（请求/响应） |
| `jwt` | JWT 令牌生成与验证 |
| `filter` | Spring Security 过滤器 |
| `config` | 配置类（安全、异步等） |

---

## 功能分析

### 1. 用户管理功能

| 功能 | 接口 | 说明 |
|------|------|------|
| 用户登录 | `POST /api/auth/login` | 用户名密码登录，返回 JWT Token |
| 用户注册 | `POST /api/auth/register` | 新用户注册，自动登录 |
| 获取档案 | `GET /api/auth/profile/{userId}` | 获取用户档案信息 |
| 更新档案 | `POST /api/auth/profile/{userId}` | 创建或更新用户档案 |

### 2. 对话管理功能

| 功能 | 接口 | 说明 |
|------|------|------|
| 非流式对话 | `POST /api/agent/chat` | 同步对话，一次性返回响应 |
| 流式对话 | `POST /api/agent/chat/stream` | SSE 流式输出，打字机效果 |
| 对话历史 | `GET /api/agent/chat/history` | 获取指定会话的历史消息 |
| 对话列表 | `GET /api/agent/conversations` | 获取用户的所有对话记录 |
| 清空会话 | `DELETE /api/agent/chat/clear` | 清空指定会话的消息 |

### 3. 心理测评功能

| 功能 | 接口 | 说明 |
|------|------|------|
| 获取测评 | `GET /api/system/assessments` | 获取用户的测评记录 |
| 提交测评 | `POST /api/system/assessments` | 提交新的测评结果 |

### 4. 情绪识别功能

| 功能 | 接口 | 说明 |
|------|------|------|
| 情绪分析 | `POST /api/agent/emotion/analyze` | 通过人脸照片识别情绪 |
| 游戏历史 | `GET /api/agent/emotion/history` | 获取情绪游戏历史记录 |

### 5. 健康数据功能

| 功能 | 接口 | 说明 |
|------|------|------|
| 获取周数据 | `GET /api/agent/weekly/data` | 获取一周睡眠和压力数据 |
| 刷新数据 | `POST /api/agent/weekly/refresh` | 刷新模拟数据 |

### 6. TTS文本转语音功能

| 功能 | 接口 | 说明 |
|------|------|------|
| TTS合成测试 | `GET /api/tts/test` | TTS服务连通性测试 |
| 异步语音合成 | `POST /api/tts/synthesize` | 文本转语音合成接口 |
| 流式对话音频 | 通过 `/api/agent/chat/stream` SSE流 | 自动在句子边界处生成音频事件 |

**TTS集成特性：**
- **自动句子检测**：当AI回复中出现句号、问号、感叹号（中英文标点）时自动触发TTS
- **流式音频传输**：音频数据通过SSE事件实时传输到前端
- **异步处理**：TTS合成不阻塞文字流式输出
- **配置开关**：支持通过环境变量控制TTS功能开启/关闭
- **动态Token获取**：支持使用阿里云AccessKey动态获取Token，避免静态Token硬编码问题

**TTS Token获取模式：**
- **动态Token模式（推荐）**：使用阿里云AccessKey ID和Secret动态获取Token，Token在应用生命周期内缓存
- **静态Token模式**：使用预先生成的静态Token，向后兼容
- **配置灵活**：支持通过`dynamic-token-enabled`开关切换模式

### 6. 后台管理功能

| 功能 | 接口 | 说明 |
|------|------|------|
| 用户管理 | `GET/POST/PUT/DELETE /api/admin/users` | 用户 CRUD 操作 |
| 用户报告 | `GET /api/admin/users/{userId}/report` | 获取用户分析报告 |
| 风险评估 | `GET/PUT /api/admin/users/{userId}/risk` | 风险评估管理 |
| 系统统计 | `GET /api/admin/stats` | 获取系统统计数据 |

---

## 安全性分析

### 1. JWT 认证机制

- **无状态令牌**: Token 包含用户信息和过期时间，服务端无需存储会话状态
- **请求头传递**: 通过 `Authorization: Bearer {token}` 传递令牌
- **自动过期**: Token 默认 7 天有效期，过期后需重新登录

### 2. 角色权限控制

| 角色 | 权限范围 |
|------|----------|
| `USER` | 访问用户相关接口（自己的档案、对话、测评等） |
| `ADMIN` | 访问所有接口（包括后台管理功能） |
| `SERVICE` | 服务间通信专用角色 |

### 3. API 安全防护

- **防 SQL 注入**: 使用 MyBatis 参数化查询，避免 SQL 注入风险
- **参数校验**: 使用 `@Valid` 注解进行请求参数校验
- **跨域访问**: 通过 Spring Security 配置 CORS 策略
- **敏感信息保护**: 用户密码使用 BCrypt 加密存储

### 4. 数据隔离

- 普通用户只能访问/修改自己的数据
- 管理员可以访问所有用户数据
- 通过 Token 解析用户 ID，确保数据归属正确

---

## 性能与并发

### 1. 连接池配置

- **HikariCP**: Spring Boot 默认数据库连接池
- **配置项**: 最大连接数、最小空闲连接数、连接超时等

### 2. Redis 缓存

- **会话管理**: 使用 Redis 存储对话工作记忆
- **摘要存储**: 对话摘要缓存，减少上下文长度
- **高性能读写**: 内存级访问速度

### 3. 无状态服务

- **JWT 无状态**: 服务端不存储会话状态，支持水平扩展
- **RESTful API**: 请求独立，支持负载均衡

### 4. 异步处理

- **Spring WebFlux**: 响应式编程模型，支持高并发
- **SSE 流式输出**: 非阻塞式数据传输
- **异步任务**: 数据库写入等耗时操作异步执行

### 5. 流式输出优化

- **打字机效果**: 逐字输出，提升用户体验
- **事件类型**: 支持 `thought`、`tool_call`、`token` 等事件
- **低延迟**: 边生成边输出，减少等待时间

---

## 快速开始

### 环境要求

| 软件 | 版本 | 说明 |
|------|------|------|
| JDK | 17+ | Java 运行环境 |
| Maven | 3.6+ | 项目构建工具 |
| MySQL | 8.0+ | 关系型数据库 |
| Redis | 6.0+ | 内存数据库 |

### 安装与配置

#### 1. 克隆项目

```bash
git clone <repository-url>
cd psychology
```

#### 2. 数据库初始化

1. 创建 MySQL 数据库：

```sql
CREATE DATABASE psychology DEFAULT CHARACTER SET utf8mb4;
```

2. 导入数据库脚本：

```bash
mysql -u root -p psychology < schema.sql
```

#### 3. 配置文件

编辑 `psychology-boot/src/main/resources/application.yml`（主配置）和 `application-dev.yml`（开发环境配置）：

**application.yml**（通用配置）：
```yaml
# Spring Boot 应用配置
spring:
  application:
    name: psychology-agent
  profiles:
    active: dev
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: GMT+8
    default-property-inclusion: non_null
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        model: llava:7b
        options:
          temperature: 0.7

# 服务器配置
server:
  port: 8080

# MyBatis 配置
mybatis:
  mapper-locations: classpath:mapper/**/*.xml
  type-aliases-package: com.xingjian.**.entity
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl

# FastAPI 智能体服务配置
fastapi:
  agent:
    base-url: http://localhost:8000
    chat-endpoint: /api/chat/stream
    connect-timeout: 5000
    read-timeout: 60000

# TTS文本转语音配置
tts:
  enabled: true  # 是否启用TTS功能

  # 静态Token配置（向后兼容）
  access-key: "${ALIYUN_TTS_ACCESS_KEY:your-access-key}"  # 阿里云TTS AppKey
  access-token: "${ALIYUN_TTS_ACCESS_TOKEN:your-access-token}"  # 阿里云TTS Token

  # 动态Token获取配置（推荐）
  access-key-id: "${ALIYUN_AK_ID:your-access-key-id}"  # 阿里云Access Key ID
  access-key-secret: "${ALIYUN_AK_SECRET:your-access-key-secret}"  # 阿里云Access Key Secret
  dynamic-token-enabled: "${TTS_DYNAMIC_TOKEN_ENABLED:true}"  # 是否启用动态Token获取

  # TTS服务参数
  url: "wss://nls-gateway-cn-beijing.aliyuncs.com/ws/v1"  # TTS服务地址
  voice: "siyue"  # 发音人
  sample-rate: 16000  # 采样率
  format: "wav"  # 音频格式
  volume: 50  # 音量 0-100
  pitch-rate: 0  # 语调 -500-500
  speech-rate: 0  # 语速 -500-500
  min-send-interval: 100  # 最小发送间隔(毫秒)

# 管理端点
management:
  endpoints:
    web:
      exposure:
        include: health,info

# 日志配置
logging:
  level:
    root: INFO
    com.xingjian: DEBUG
    org.springframework.web: DEBUG
    org.mybatis: DEBUG
```

**application-dev.yml**（开发环境配置）：
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/psychology?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      minimum-idle: 5
      maximum-pool-size: 20
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000
  data:
    redis:
      host: localhost
      port: 6379
      password:
      database: 0
      timeout: 5000ms
      lettuce:
        pool:
          max-active: 8
          max-idle: 8
          min-idle: 0
          max-wait: -1ms
```

#### 4. 构建项目

```bash
# 编译项目
mvn clean compile

# 打包项目
mvn clean package -DskipTests
```

#### 5. 启动服务

```bash
# 方式 1：使用 Maven 运行
mvn spring-boot:run -pl psychology-boot

# 方式 2：运行 JAR 包
java -jar psychology-boot/target/psychology-boot-1.0.0-SNAPSHOT.jar
```

#### 6. 验证启动

访问健康检查接口：

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

看到以下响应表示启动成功：

```json
{"status":"UP"}
```

---

## 开发指南

### 添加新接口

1. 在对应模块的 `controller` 包创建 Controller 类
2. 在 `service` 包创建服务类
3. 在 `mapper` 包创建数据访问接口
4. 在 `entity` 包创建实体类（如需要）
5. 在 `dto` 包创建请求/响应类

### 统一响应格式

所有接口使用 `Result<T>` 封装响应：

```java
// 成功响应
return Result.success(data);

// 带消息的成功响应
return Result.success("操作成功", data);

// 错误响应
return Result.error("错误信息");
```

### 日志配置

开发环境日志级别配置为 DEBUG：

```yaml
logging:
  level:
    root: INFO
    com.xingjian: DEBUG
    org.springframework.web: DEBUG
    org.mybatis: DEBUG
```

---

## TTS配置指南

### 动态Token获取模式（推荐）

动态Token获取模式使用阿里云AccessKey动态生成Token，避免了静态Token硬编码带来的安全问题。

#### 配置方式

1. **环境变量配置（推荐）**：
```bash
export ALIYUN_AK_ID=your-access-key-id
export ALIYUN_AK_SECRET=your-access-key-secret
export TTS_DYNAMIC_TOKEN_ENABLED=true
```

2. **YAML配置**：
```yaml
tts:
  dynamic-token-enabled: true
  access-key-id: "your-access-key-id"
  access-key-secret: "your-access-key-secret"
```

3. **Docker环境变量**：
```yaml
environment:
  - ALIYUN_AK_ID=your-access-key-id
  - ALIYUN_AK_SECRET=your-access-key-secret
  - TTS_DYNAMIC_TOKEN_ENABLED=true
```

#### 工作原理

1. 应用启动时，`AliyunTtsTokenProvider`会检查是否启用动态Token获取
2. 如果启用，使用配置的AccessKey ID和Secret调用阿里云API获取Token
3. Token在应用生命周期内缓存，避免重复请求
4. 每次NlsClient创建时使用缓存的Token

#### 获取AccessKey

1. 登录[阿里云控制台](https://ram.console.aliyun.com/users)
2. 进入"访问控制RAM" > "用户管理"
3. 创建或选择已有用户，获取AccessKey ID和Secret
4. 为该用户授权`AliyunNLSFullAccess`权限

### 静态Token模式（向后兼容）

如果您已有预先生成的静态Token，可以继续使用原有配置：

```yaml
tts:
  dynamic-token-enabled: false
  access-token: "your-pre-generated-token"
```

### 故障排除

#### TTS Token获取失败

**问题**: 应用启动时抛出`TokenException: 获取TTS Token失败`

**解决**：
1. 检查AccessKey ID和Secret是否正确
2. 确认网络可以访问阿里云API端点
3. 检查阿里云账号余额和权限配置
4. 查看应用日志获取详细错误信息

#### 动态Token获取禁用时回退

如果动态Token获取失败且未配置静态Token，系统将抛出异常。建议始终配置静态Token作为后备方案：

```yaml
tts:
  dynamic-token-enabled: true  # 优先使用动态Token
  access-token: "backup-static-token"  # 动态Token失败时的后备方案
```

### 安全建议

1. **生产环境**：使用环境变量或密钥管理服务（如Vault）存储AccessKey
2. **开发环境**：可以使用配置文件，但不要提交到代码仓库
3. **权限最小化**：为TTS服务创建专用RAM用户，仅授予必要权限
4. **定期轮换**：定期更新AccessKey，建议每90天轮换一次

---

## 常见问题

### 1. Token 无效

**问题**: 请求返回 401 未授权

**解决**:
- 检查请求头是否包含 `Authorization: Bearer {token}`
- 确认 Token 未过期
- 确认 Token 格式正确

### 2. 数据库连接失败

**问题**: 启动时报数据库连接错误

**解决**:
- 检查 MySQL 服务是否启动
- 确认 `application.yml` 中数据库连接配置正确
- 确认数据库已创建且脚本已导入

### 3. Redis 连接失败

**问题**: 对话功能异常

**解决**:
- 检查 Redis 服务是否启动
- 确认 Redis 连接配置正确
- 确认 Redis 端口 6379 可访问

### 4. TTS Token获取失败

**问题**: TTS语音合成功能无法使用

**解决**:
- 检查TTS功能是否启用 (`tts.enabled: true`)
- 确认阿里云AccessKey配置正确（动态Token模式）
- 或确认静态Token配置正确（静态Token模式）
- 检查网络是否能访问阿里云TTS服务端点
- 查看应用日志中的TTS相关错误信息
- 确认阿里云账号有足够的余额和权限

---

## 许可证

本项目为青少年心理健康研究专用，请勿用于商业用途。