From ea43cb0a250317be1c5d6cf38c075485e3e34a58 Mon Sep 17 00:00:00 2001 From: levon Date: Tue, 14 Oct 2025 11:27:06 +0800 Subject: [PATCH] docs: update docs --- README.md | 150 ++++++ ...50\347\275\262\346\226\207\346\241\243.md" | 123 +++++ ...71\347\233\256\346\226\207\346\241\243.md" | 447 ++++++++++++++++++ 3 files changed, 720 insertions(+) create mode 100644 README.md create mode 100644 "docs/\351\203\250\347\275\262\346\226\207\346\241\243.md" create mode 100644 "docs/\351\241\271\347\233\256\346\226\207\346\241\243.md" diff --git a/README.md b/README.md new file mode 100644 index 0000000..13a3dd6 --- /dev/null +++ b/README.md @@ -0,0 +1,150 @@ +# 一. 功能演示 + +演示视频：[http://t313actv0.hb-bkt.clouddn.com/bandicam%202025-09-28%2023-45-36-297.mp4](http://t313actv0.hb-bkt.clouddn.com/bandicam%202025-09-28%2023-45-36-297.mp4) + + + +# 二. 项目介绍 + +语Ta(VacaTa) 一个AI驱动的实时语音角色扮演平台，用户可与哈利波特、等虚拟角色进行语音和文本对话 + ++ 语音/文本对话: 完整的语音→ 文本→ LLM → 语音链路，支持流式快速响应 ++ 多AI模型集成: 七牛云AI、硅基流动、OpenAI GPT、Google Gemini无缝切换功能模式 ++ 自定义角色: 用户可创建个性化AI角色，调节性格和对话风格。 + + + +# 三. 技术架构 + +**整体架构：** + +![](https://cdn.nlark.com/yuque/0/2025/png/29246232/1759073523877-d803a8b1-b8f2-472e-b193-361babf7cc9b.png) + +**技术栈：** + ++ 后端: Spring Boot 3.1.4 + Java 17 + MyBatis Plus + Sa-Token + WebSocket ++ 前端: Vue 3.5 + TypeScript + Vite + Element Plus + Pinia ++ 数据库: PostgreSQL 15 + Redis 7 ++ AI服务: 七牛云ASR + 七牛云AI服务商 + 科大讯飞TTS ++ 部署: GitHub Actions CI、CD + +# 四. 服务提供 + +| **服务类型** | **提供商** | +| :------------ | :--------------------------------- | +| OSS对象存储 | 七牛云 | +| STT语音识别 | 七牛云ASR、科大讯飞 | +| TTS语音合成 | 科大讯飞、火山引擎 | +| LLM大语言模型 | 七牛云AI、Gemini、OpenAI、硅基流动 | + + + +# 五.问题 + +## 1.你计划将这个应用面向什么类型的用户？这些类型的用户他们面临什么样的痛点，你设想的用户故事是什么样呢？ + +本产品的核心目标用户可归纳为四大类：**IP/角色爱好者**、**学习者**、**情感陪伴需求者**与**内容创者**。他们共同的渴望是将单向、静态的内容消费（如阅读、观影）转变为双向、动态的沉浸式互动。主要痛点集中在现有媒介缺乏互动性、学习过程枯燥、现实社交存在压力以及创作时缺少灵感。本产品旨为这些用户提供一个集娱乐、学习、陪伴和创造于一体的全新互动平台。 + + + +### IP/角色爱好者 + +对特定影视、动漫、游戏人物充满热情的年轻人（年龄以 18-38 岁为主）。他们不仅希望与心仪角色进行思想上的交流，更渴望建立更深层次的情感连接。 + +**王海(《海贼王》粉丝)**：“作为一名海米，路飞的铁杆粉丝，我觉得仅仅通过追番和看漫画来体验他的冒险故事，总感觉隔着一层屏幕，缺少了真实的互动感。我希望能真的和‘路飞’本人进行语音对话，听他用那标志性的语气兴奋地跟我聊聊最近的冒险，甚至可以问他‘当海贼王需要具备什么条件？’，这远比在论坛上猜测剧情或重温动画更能让我感受到那种身临其境的伙伴感。” + +**核心痛点** + ++ 单向互动，缺乏沉浸感 ++ 情感连接肤浅，渴望深度交流 ++ 想象无法落地，互动渠道缺失 + +### 学习者 + +学习者为两类，一类是知识学习者，如希望深入理解哲学家、历史人物、文学家的学习者或爱好者；另一类是语言学习者，需要语境环境、且无压力的环境来练习外语口语。 + +**李明(知识学习者)**：“作为一名哲学爱好者，我觉得笛卡尔的作品虽然深刻，但有些地方仅靠阅读难以完全理解。我希望能直接与‘笛卡尔’本人进行语音对话，让他用通俗的语言为我举例说明，让我能更深刻地与他的思想进行碰撞，这远比我独自钻研文本要高效和富有启发性得多。” + +**小美(语言学习者)**：“作为一名英语学习者，我觉得最大的挑战是找到一个既有真实语境、又没有社交压力的口语练习环境，而且聘请真人外教的费用实在太高了。我希望能随时随地和像‘莎士比亚’这样的AI角色进行对话，在一个虚拟的场景里围绕不同的话题进行角色扮演，这远比预约昂贵且有压力的真人外教要轻松、自由，也经济实惠得多。并且我可以勇敢地开口练习口语和听力，而不用担心因犯错而感到尴尬。” + +**核心痛点:** + ++ 知识获取枯燥 ++ 缺乏语伴与环境 + + + +### 情感陪伴需求者 + +因独居、工作繁忙、社交焦虑、失恋等原因，在情感上感到孤独，希望寻找一个随时可用、无压力且非评判性的倾诉对象的用户。 + +**小张**：“作为一名独居青年，我时常在深夜感到孤独，但很多烦心事又不敢和家人朋友说，怕给他们添麻烦。我希望能有一个随时都在、且绝不评判我的倾诉对象，能听我说说心里话，这远比一个人硬扛着所有情绪要好得多。” + +**核心痛点:** + ++ 即时性情感需求的无法满足 ++ 现实社交的“高成本”与“不确定性” ++ 对“无条件接纳”与“安全感”的渴望 + + + + + +### 内容创作者 + +Cosplay UP主、作家、编剧、游戏设计师等需要进行创意构思和角色扮演的用户。 + +小陈：“我写剧本的时候老是容易卡住，尤其是角色的对话，总觉得很僵硬、不够自然。我其实特别想能直接跟我构思的角色聊一聊，用语音问他各种问题、丢给他不同场景，看看他会怎么反应。这样碰撞出来的台词肯定更有火花，比我一个人对着文档死想或者疯狂查资料要省事儿、也更直观。” + +**核心痛点:** + ++ **灵感枯竭与创作瓶颈** ++ **塑造角色缺乏动态反馈** ++ **角色对话难以高效生成** + + + +## 2.你认为这个 APP 需要哪些功能？这些功能各自的优先级是什么？你计划本次开发哪些功能？ + +1. **基础语音对话**：STT+LLM+TTS的完整链路 +2. **3个核心角色**：苏格拉底、邓布利多、AI助手 +3. **用户认证**：简单注册/登录 +4. **基础对话管理**：保存历史记录 +5. **角色记忆系统**：记住用户偏好 （以及**角色身份边界问题**） +6. **实时字幕**：语音识别结果展示 +7. **对话中断机制**：可随时打断AI +8. **用户创建角色** +9. **多轮对话摘要（****对话历史上下文压缩策略工程****）** +10. **情感分析** +11. **...** + + + +## 3.你计划采纳哪家公司的哪个 LLM 模型能力？你对比了哪些，你为什么选择用该 LLM 模型？ + +| **模型** | **优势** | **劣势** | +| --------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------- | +| **GPT-4o** | 角色扮演能力最强、理解力最好 | 成本高、延迟较大 | +| X-fast | 速度快、长文本处理优秀，上下文长 | 成本较低 | +| gemini-2.5fast | 速度快、长文本处理优秀，上下文长 | 成本较低 | + + +## 4.你期望 AI 角色除了语音聊天外还应该有哪些技能？ + +1. **多模态交互** + - 角色形象生成（AI绘画） + - 场景渲染（如霍格沃茨大厅） + - 表情动作系统 +2. **游戏化元素** + - 角色好感度系统 + - 成就解锁 + - 剧情任务 +3. **教育功能** + - 知识点总结 + - 学习进度追踪 + - 个性化教学（如苏格拉底的哲学课） +4. **创作辅助** + - 李白：诗词创作工具 + - 哈利：魔法故事生成器 + - 苏格拉底：论文思路梳理 + diff --git "a/docs/\351\203\250\347\275\262\346\226\207\346\241\243.md" "b/docs/\351\203\250\347\275\262\346\226\207\346\241\243.md" new file mode 100644 index 0000000..ed92fe7 --- /dev/null +++ "b/docs/\351\203\250\347\275\262\346\226\207\346\241\243.md" @@ -0,0 +1,123 @@ +# VocaTa 项目运行指南 + +本文档说明如何在本地或通过容器编排运行 VocaTa 项目（后端服务、客户端前端、管理后台）。 + +## 1. 运行方式概览 +- **Docker Compose 一键启动**：适合快速体验或准备集成环境，自动拉起数据库、缓存、后端和两个前端。 +- **本地开发模式**：分别启动后端（Java + Maven）及前端项目（Vue 3 + Vite），适合调试与开发。 +- **生产部署示例**：项目根目录提供 `docker-compose.prod.yml` 可作为上线部署基础模板。 + +## 2. 环境准备 +### 2.1 通用要求 +- 操作系统：macOS / Linux / Windows（支持 Docker 或 Java 开发环境） +- Git（可选，用于克隆仓库） + +### 2.2 本地开发依赖项 +- JDK 17 及以上 +- Maven 3.6 及以上 +- Node.js 20.19 或 >= 22.12（前端 `package.json` 中的 `engines` 要求） +- npm（Node.js 自带） +- PostgreSQL 12 及以上 +- Redis 6 及以上 + +### 2.3 容器运行依赖项 +- Docker 24+ +- Docker Compose Plugin（`docker compose` 命令） + +## 3. 使用 Docker Compose 快速启动 +1. 确保 Docker Desktop 或 Docker Engine 正在运行。 +2. 在项目根目录执行： + ```bash + docker compose up -d --build + ``` + 该命令会按 `docker-compose.yml` 构建并启动以下服务： + - PostgreSQL（端口 `5432`） + - Redis（端口 `6379`） + - vocata-server（端口 `9009`，REST API `http://localhost:9009/api`） + - vocata-web（端口 `3000`，客户端 Web 入口） + - vocata-admin（端口 `3001`，管理后台入口） + - pgAdmin（端口 `5050`，数据库管理工具） + - MailHog（SMTP `1025` / Web UI `8025`，用于邮件调试） +3. 查看容器日志（可选）： + ```bash + docker compose logs -f vocata-server + ``` +4. 停止并清理容器： + ```bash + docker compose down + ``` + 如需保留数据，可保留默认定义的 `postgres_data`、`redis_data` 卷；若需要重新初始化数据，可加上 `-v` 删除数据卷。 + +## 4. 本地开发模式 +### 4.1 准备数据库与缓存 +1. 启动 PostgreSQL 与 Redis，并记录连接信息。 +2. 初始化数据库（以 README 示例为准）： + ```sql + CREATE DATABASE vocata_dev; + CREATE USER vocata_dev WITH PASSWORD 'vocata_dev'; + GRANT ALL PRIVILEGES ON DATABASE vocata_dev TO vocata_dev; + ``` + +### 4.2 配置后端（`vocata-server`） +1. 拷贝本地配置模板： + ```bash + cp src/main/resources/application-local.yml.template src/main/resources/application-local.yml + ``` +2. 根据实际环境修改数据库、Redis、邮件及第三方 AI 服务配置。若使用环境变量，也可直接设置 `DB_HOST`、`DB_USERNAME` 等变量，`application.yml` 中提供了占位符。 +3. 安装依赖并运行： + ```bash + mvn clean install + mvn spring-boot:run -Dspring-boot.run.profiles=local + ``` + 或打包后运行： + ```bash + mvn package + java -jar target/vocata-server-*.jar --spring.profiles.active=local + ``` +4. 服务默认监听 `http://localhost:9009`，健康检查接口为 `/api/health`。 + +### 4.3 启动客户端前端（`vocata-web`） +1. 安装依赖： + ```bash + npm install + ``` +2. 启动开发服务器： + ```bash + npm run dev + ``` +3. 默认访问地址为 `http://localhost:5173`（Vite 默认端口）。如需连接本地后端，请在 `.env` 或启动命令中设置 `VITE_API_BASE_URL=http://localhost:9009/api`。 +4. 生产构建： + ```bash + npm run build + npm run preview # 可选，预览构建结果 + ``` + +### 4.4 启动管理后台前端（`vocata-admin`） +流程与客户端一致： +```bash +cd vocata-admin +npm install +npm run dev +``` +同样可通过环境变量 `VITE_API_BASE_URL` 指向后端 API。 + +### 4.5 常用调试技巧 +- 后端实时日志位于 `vocata-server/logs` 目录，可根据需要调整 `application.yml` 中的日志级别。 +- 如需模拟邮件发送，可使用 MailHog（`http://localhost:8025`）。 +- 若前后端跨域问题，可检查 `vocata-server` 的 `WebConfig` 或前端代理配置。 + +## 5. 生产部署参考 +- 使用 `docker-compose.prod.yml`，提前构建或拉取镜像（如 `ghcr.io/leivik/vocata-server:latest`）。 +- 通过环境变量注入数据库、Redis、对象存储和 AI 服务密钥。 +- 建议在生产环境添加反向代理（Nginx 等）以及 HTTPS 终端。日志策略与健康检查已在 Compose 中示例配置。 + +## 6. 常见问题与排查 +- **数据库连接失败**：确认数据库容器是否就绪、账号密码与 `application-local.yml` 一致。 +- **Redis 认证错误**：本地默认无密码，如在服务器上启用密码，需要同步更新配置。 +- **前端无法请求 API**：检查 `VITE_API_BASE_URL` 是否指向正确地址/协议，并留意浏览器 CORS 报错。 +- **端口冲突**：修改对应服务的监听端口（Docker Compose 中的 `ports` 映射或 Vite 启动参数）。 +- **构建失败**：确保 Node.js 和 Maven 版本符合要求，必要时删除 `node_modules` / `target` 重装。 + +## 7. 下一步 +- 参考 `vocata-server/README.md` 获取 API 说明与模块概览。 +- 前端更多配置可查看各目录下的 `vite.config.ts` 与 `src` 代码。 diff --git "a/docs/\351\241\271\347\233\256\346\226\207\346\241\243.md" "b/docs/\351\241\271\347\233\256\346\226\207\346\241\243.md" new file mode 100644 index 0000000..a3e3741 --- /dev/null +++ "b/docs/\351\241\271\347\233\256\346\226\207\346\241\243.md" @@ -0,0 +1,447 @@ +# 我思故我码 +## 一、项目介绍 +语Ta(VacaTa) 一个AI驱动的实时语音角色扮演平台 - 用户可与Harry Potter、Socrates等虚拟角色进行语音和文本对话 + ++ 实时语音对话: 完整的语音→文本→AI→语音链路，支持流式快速响应 ++ 多AI模型集成: 七牛云AI、OpenAI GPT、Google Gemini无缝切换功能模式 ++ 自定义角色: 用户可创建个性化AI角色，调节性格和对话风格 ++ 双向通信: 支持语音和文本两种交互方式 ++ 现代化架构: 前后端分离，容器化部署，CI/CD自动化 + +## 二、功能演示 +### 2.1 整体演示 +演示视频：[http://t313actv0.hb-bkt.clouddn.com/bandicam%202025-09-28%2023-45-36-297.mp4](http://t313actv0.hb-bkt.clouddn.com/bandicam%202025-09-28%2023-45-36-297.mp4) + +### 2.2 功能模块演示 +#### 2.2.1 用户认证系统 - 注册/登录/验证码 ++ 当用户访问VocaTa平台时，系统将引导其完成身份认证流程。 ++ 用户输入邮箱地址后，系统会发送6位数字验证码到指定邮箱，验证码有效期为5分钟。 ++ 如果是新用户，验证码验证通过后需要设置登录密码，系统将自动生成用户名（格式：vocata-随机字符串）。 ++ 已注册用户可直接使用邮箱和密码进行登录，系统将颁发JWT令牌实现免登录访问。 ++ 用户可以通过忘记密码功能重置登录凭据，确保账户安全。 + + + +#### 2.2.2 用户管理模块 - 个人信息管理 ++ 用户登录后可以查看和编辑个人资料，包括昵称、个人简介等基本信息。 ++ 用户可以上传个人头像，系统支持多种图片格式，并自动生成CDN访问链接。 ++ 用户可以配置个性化偏好设置，如主题风格、消息通知等选项。 ++ 系统提供账户安全设置，用户可以修改密码、查看登录记录等安全信息。 ++ 所有个人信息修改都会实时保存，并记录操作日志确保数据安全。 + + + +#### 2.2.3 AI对话模块 - 角色对话核心功能 ++ 用户可以从角色列表中选择喜欢的AI角色（如Harry Potter、Socrates等）开始对话。 ++ 系统支持文字和语音两种输入方式，用户可以根据场景灵活选择交互模式。 ++ AI回复采用流式响应技术，用户可以实时看到AI角色逐字生成回答内容。 ++ 系统保持多轮对话的上下文记忆，确保对话的连贯性和智能性。 ++ 用户可以随时暂停、继续或重新开始对话，系统会自动保存对话进度。 + + + +#### 2.2.4 对话历史模块 - 会话记录管理 ++ 用户可以查看与不同AI角色的历史对话记录，系统按时间倒序展示对话列表。 ++ 用户可以通过关键词搜索特定的对话内容，快速定位重要的对话片段。 ++ 系统支持对话分页加载，优化大量历史记录的浏览体验。 ++ 用户可以收藏重要对话，方便后续回顾和参考。 ++ 用户可以删除不需要的对话记录，系统采用软删除机制确保数据可恢复性。 + + + +#### 2.2.5 角色管理模块 - AI角色配置 ++ 用户可以浏览平台提供的多样化AI角色库，每个角色都有独特的人格特征和专业背景。 ++ 系统展示角色的详细信息，包括人物介绍、擅长领域、对话风格等特性。 ++ 用户可以预览角色的对话样例，了解其回复风格和知识水平。 ++ 系统支持角色评价功能，用户可以为喜欢的角色点赞或评分。 ++ 管理员可以创建新角色或编辑现有角色的人格设定，丰富平台角色生态。 + + + +#### 2.2.6 后台管理模块 - 角色和普通用户管理 ++ 管理员通过专用登录入口访问后台管理系统，享有完整的平台管理权限。 ++ 管理员可以查看用户注册统计、活跃度分析等关键运营数据。 ++ 系统提供用户账户管理功能，管理员可以查看用户详情、调整账户状态。 ++ 管理员可以审核和管理AI角色内容，确保角色设定的质量和合规性。 ++ 系统提供实时监控面板，展示服务器性能、API调用量等技术指标。 + + + +#### 2.2.7 文件存储模块 - 七牛云存储集成 ++ 用户可以上传头像、图片等多种类型的文件，系统自动检测文件格式和大小。 ++ 系统集成七牛云存储服务，确保文件上传的稳定性和访问速度。 ++ 用户可以按类型管理已上传的文件，支持文件预览、下载和删除操作。 ++ 系统提供CDN加速服务，确保全球用户都能快速访问文件资源。 ++ 管理员可以监控存储使用情况，设置文件大小限制和格式白名单。 + + + +#### 2.2.8 AI模型管理模块 - 多AI提供商集成 ++ 系统集成多个AI提供商（如SiliconFlow等），提供丰富的AI模型选择。 ++ 管理员可以查看所有可用的AI模型列表，包括模型性能参数和可用状态。 ++ 系统支持手动指定AI提供商和模型进行对话测试，便于模型效果评估。 ++ 用户可以体验不同AI模型的对话风格，选择最适合的智能助手。 ++ 系统提供统一的API接口封装，屏蔽不同提供商的接口差异。 + + + +#### 2.2.9 实时语音对话模块 - WebSocket语音交互 ++ 用户可以通过WebSocket连接与AI角色进行实时语音对话，支持语音输入和语音输出的全链路处理。 ++ 系统支持实时音频流传输，用户说话时音频数据实时传送到服务器进行处理。 ++ 用户可以选择语音模式或文字模式进行对话，系统自动识别输入类型并相应处理。 ++ 系统提供音频录制开始和结束的控制，用户可以灵活控制对话节奏。 ++ 支持WebSocket心跳检测机制，确保长时间对话的连接稳定性。 + + + +#### 2.2.10 语音识别模块 - STT多平台集成 ++ 系统集成多个语音识别服务提供商，包括七牛云STT、科大讯飞等主流平台。 ++ 用户上传的音频文件支持多种格式（WAV、MP3、AAC、FLAC等），系统自动识别和转换。 ++ 支持流式语音识别和批量语音识别两种模式，适应不同场景需求。 ++ 系统提供语音识别置信度评估，确保识别结果的准确性。 ++ 支持中英文等多语言识别，用户可以使用母语与AI角色对话。 + +## 三、技术架构实现 +### 3.1 技术选型 +#### 3.1.1 前端 ++ **框架与语言：Vue 3.5.18 + TypeScript 5.8.0** + +从业务适配角度，Vue3 的 Composition API 能够灵活拆分实时语音链路的复杂逻辑，比如语音采集、转译、AI 响应接收等环节的代码组织；TypeScript 则可通过静态类型检查，保障多 AI 模型集成过程中的参数传递、数据格式一致性，降低团队协作中的 bug 率，尤其适配多模型切换时的复杂数据处理场景。 + ++ **构建工具：Vite 7.0.6** + +Vite 的毫秒级热更新特性，能大幅提升实时语音功能的开发迭代效率，减少调试时的等待时间；其支持的多环境构建（local/test/prod 模式），可直接适配项目的 CI/CD 自动化部署需求，无需额外配置复杂的环境切换逻辑，助力不同阶段（本地开发、测试验证、生产上线）的快速过渡。 + ++ **UI 组件库：Element Plus 2.11.3 + 官方图标库** + +Element Plus 提供的丰富组件能快速支撑平台核心功能页面搭建：例如用表单组件实现自定义角色的性格、对话风格配置界面，用弹窗组件开发多 AI 模型切换面板；同时其轻量化设计风格与对话界面的简洁需求匹配，搭配官方图标库可保障界面视觉统一性，减少自定义图标的开发成本。 + ++ **状态管理：Pinia 3.0.3** + +针对平台多维度状态管理需求，Pinia 的模块化设计可单独划分 “模型状态”“角色配置状态” 等独立模块，避免多 AI 模型切换、自定义角色参数变更时的状态混乱；且支持按需加载特性，能减少实时对话场景下的首屏资源体积，间接提升页面加载与交互响应速度。 + ++ **网络请求：Axios 1.12.2** + +Axios 的拦截器功能可统一处理多 AI 模型请求的 Token 验证、超时控制，保障语音与文本双向通信的稳定性，比如在请求拦截器中添加身份标识，响应拦截器中处理 401 权限失效等异常；其支持的请求取消功能，还能适配实时语音链路中断场景，避免无效请求占用资源，减少交互延迟。 + ++ **样式方案：Tailwind CSS 4.1.13 + postcss-pxtorem** + +Tailwind CSS 的原子化样式特性，可快速实现对话界面的细节设计，比如角色气泡的样式调整、语音按钮的交互效果优化，无需编写大量自定义 CSS；搭配 postcss-pxtorem 自动将 px 转换为 rem 的功能，能轻松适配 PC、平板等多端设备的交互场景，保障不同屏幕尺寸下的界面一致性。 + ++ **代码质量：ESLint 9.31.0 + Prettier 3.6.2** + +ESLint 可对实时语音链路、多 AI 模型集成等复杂逻辑代码进行语法检查与风格规范，比如禁止未定义变量、统一代码缩进；Prettier 则能统一代码格式化标准，避免团队成员因格式差异产生协作成本，尤其适配多模型集成、角色配置等多模块开发场景下的代码可读性需求。 + + + +#### 3.1.2 后端 +**核心框架** + ++ Java 版本: Java 17 (LTS 长期支持版本) ++ Spring Boot: 3.1.4 (企业级微服务框架) ++ Web 框架: + - Spring Boot Starter Web (MVC + RESTful API) + - Spring Boot Starter WebSocket (实时通信) + - Spring WebFlux (响应式编程，用于AI服务调用) + +**认证与安全** + ++ 认证框架: Sa-Token 1.37.0 (轻量级Java权限认证框架) + - Sa-Token Spring Boot3 Starter + - Sa-Token Redis Jackson (分布式会话存储) ++ 密码加密: BCrypt 0.10.2 (行业标准密码哈希) ++ 数据验证: Spring Boot Starter Validation (JSR 303/380) + +**数据访问层** + ++ ORM框架: MyBatis Plus 3.5.3.2 (MyBatis 增强工具) ++ 数据库: PostgreSQL 42.6.0 (强一致性关系型数据库) ++ 连接池: HikariCP (Spring Boot 默认高性能连接池) ++ 缓存: + - Spring Boot Starter Data Redis (Redis 集成) + - Redisson 3.23.4 (分布式锁和高级数据结构) + +**AI服务集成** + ++ 语音识别: 科大讯飞 WebSDK Java Speech 3.0.6 ++ WebSocket客户端: + - Tyrus Client 1.19 (Java WebSocket 客户端实现) + - Tyrus Container Grizzly Client 1.19 + +**第三方服务** + ++ 文件存储: 七牛云 Java SDK 7.13.1 (云存储服务) ++ 邮件服务: Spring Boot Starter Mail (163邮箱SMTP) + +**数据存储服务** + ++ 主数据库: PostgreSQL 15-alpine ++ 缓存数据库: Redis 7-alpine + +**AI服务集成** + ++ 大语言模型: + - 七牛云AI (Grok-4-Fast) + - Google Gemini + - OpenAI GPT系列 ++ 语音服务: + - 科大讯飞STT (语音转文字) + - 科大讯飞TTS (文字转语音) + - 七牛云语音识别 + +**开发运维工具** + ++ 容器化: Docker + Docker Compose ++ 数据库管理: pgAdmin 4 (Web界面数据库管理) ++ 邮件测试: MailHog (开发环境邮件测试工具) ++ CI/CD: GitHub Actions (自动化构建和测试) + +#### 3.1.3 核心服务 +| **服务名** | **作用** | +| :--- | :--- | +| **Auth 服务** | 1. 提供用户注册、登录、登出和密码重置服务
2. 基于Sa-Token提供JWT认证和权限验证服务
3.提供邮箱验证码发送和验证服务
4. 提供多端会话管理和安全登录控制 | +| **User 服务** | 1. 提供用户信息查询、修改个人资料和用户设置服务
2. 提供用户权限管理和角色分配服务
3.提供用户状态管理（启用/禁用）服务
4. 提供用户数据统计和分析服务 | +| **Character 服务** | 1. 提供AI角色创建、编辑、删除和查询服务
2. 提供角色人格设定、背景故事和对话风格配置
3.提供角色分类、搜索和推荐服务
4. 提供角色热度统计和排行榜服务 | +| **AI 服务** | 1. 集成多种LLM提供智能对话生成服务（七牛云AI、Gemini、OpenAI）
2. 提供语音识别（STT）和语音合成（TTS）服务
3.提供实时AI对话和WebSocket通信服务
4. 提供AI模型切换和参数调优服务 | +| **Conversation 服务** | 1. 提供对话会话创建、管理和历史记录服务
2. 提供消息存储、查询和上下文管理服务
3.提供对话导出、分享和收藏服务
4. 提供对话统计分析和用户行为追踪服务 | +| **Voice 服务** | 1. 提供语音文件上传、处理和格式转换服务
2. 集成科大讯飞提供语音识别和合成服务
3.提供语音质量优化和降噪处理服务
4. 提供语音播放控制和音频流管理服务 | +| **File 服务** | 1. 集成七牛云提供文件上传、存储和CDN分发服务
2. 提供图片、音频、视频等多媒体文件管理
3.提供文件安全检查和格式验证服务
4. 提供文件访问权限控制和临时链接生成 | +| **Admin 服务** | 1. 提供管理员登录认证和权限管理服务
2. 提供用户管理、角色管理和系统监控服务 | +| **Common 服务** | 1. 提供统一的响应格式封装（ApiResponse）和异常处理
2. 提供基础实体类和审计字段自动填充服务
3.提供通用工具类和常量定义服务
4. 提供跨模块共享的数据结构和枚举定义 | + + +### 3.2 结构设计 +#### 3.2.1 技术架构 +VocaTa采用现代化前后端分离架构，具备以下核心特征： + +架构设计原则 + +1. 前后端分离: 前端Vue3应用独立部署，通过RESTful API与后端通信 +2. 微服务架构: 按业务领域划分模块，支持独立开发和部署 +3. AI服务集成: 统一的AI服务抽象层，支持多厂商AI服务切换 +4. 安全为先: 基于JWT的无状态认证，细粒度权限控制 + +核心技术决策: + ++ Java 17 + Spring Boot 3.1.4: 现代化JVM生态，享受最新语言特性和性能优化 ++ PostgreSQL + Redis: 强一致性关系型数据 + 高性能缓存的混合存储架构 ++ Sa-Token + JWT: 轻量级分布式认证，支持多端会话管理 ++ Vue 3 + TypeScript: 类型安全的现代前端开发体验 ++ Docker容器化: 环境一致性保证，简化部署和运维 + + 1. 高可扩展性: 模块化设计支持水平扩展，微服务架构便于独立升级 + + 2. 高性能: Redis缓存 + 连接池优化 + 异步处理机制 + + 3. 高安全性: JWT无状态认证 + HTTPS传输 + 参数验证 + SQL注入防护 + + 4. 高可维护性: 统一的代码规范 + 完整的异常处理 + 详细的日志记录 + + 5. 云原生: Docker容器化 + 多环境配置 + CI/CD自动化 + + 6. AI集成: 统一抽象层支持多种AI服务提供商，便于切换和扩展 + + + +用户认证流程: + ++ 登录请求 → Sa-Token验证 → JWT生成 → Redis存储会话 → 返回Token → 前端存储 ++ API请求 → Token验证 → Redis查询会话 → 用户上下文构建 → 业务处理 + +AI对话流程: + ++ 语音输入 → STT(七牛云ASR) → LLM处理(七牛云AI) → TTS(科大讯飞) → 语音输出 ++ 文字输入 → LLM处理 → 结构化响应 → 对话历史存储 → 前端渲染 + + + +#### 3.2.1 前端架构图 +![](https://cdn.nlark.com/yuque/0/2025/png/29246232/1759042687429-bfd79eda-e9cd-481e-9e61-67a939f457fd.png) + +#### +3.2.3 后端架构图 +![](https://cdn.nlark.com/yuque/0/2025/png/22342544/1759074426719-e1229caa-2678-431d-913e-3075d5b502dc.png) + + + +#### 3.2.4 数据库ER图 +![](https://cdn.nlark.com/yuque/0/2025/png/26235666/1759071777570-49c69113-5c12-49c4-9118-1ddc2d549cd4.png) + +#### 3.3 项目特色介绍 ++ 前端用户体验（UE）方面 + +1. 一体化的聊天体验 + +流畅的实时对话 + +项目通过 WebSocket 实现了毫秒级响应的实时通信，确保用户与 AI 的对话体验如同与真人交流般自然。消息状态实时更新（发送中、接收中、已完成），让用户清楚了解消息处理进度。AI 回复采用流式传输和打字机效果，逐字显示回复内容，模拟真实对话节奏，增强交互的自然感。 + +多模态交互设计 + +项目支持文本和语音两种交互方式，用户可以在聊天界面中自由切换。语音功能实现了完整的音频处理流程，包括语音录制、播放和识别转换，让用户可以根据场景和偏好选择最合适的交流方式。聊天界面设计简洁直观，输入区域固定在底部，消息展示区域自适应，确保对话内容始终可见。 + +智能消息管理 + +聊天消息采用数组结构管理，支持添加新消息、加载历史消息和删除消息。系统会自动保存对话历史，用户可以随时查看之前的对话内容。消息卡片设计清晰，区分用户和 AI 的消息，使用不同的颜色和位置来区分发送方，使对话结构一目了然。 + +2. 直观的角色管理 + +视觉化角色展示 + +项目采用卡片式设计展示角色，正面显示角色基本信息（头像、名称、欢迎语和聊天次数），背面显示详细描述和操作按钮。卡片具有翻转动画效果，增加浏览的趣味性。精选角色以轮播形式展示在页面顶部，吸引用户注意，同时提供快速访问通道。 + +简化的角色创建 + +角色创建表单采用清晰的分区设计，包含必填项和选填项。用户可以通过点击上传按钮选择角色头像，系统会自动检查图片格式和大小。角色声音提供下拉选择，包含多种音色选项。表单设计直观，包含必填项验证，确保用户输入完整，同时提供实时反馈，避免提交后才发现错误。 + +智能角色搜索与筛选 + +角色搜索功能支持关键词搜索和多种筛选条件（热门、最新、我的等）。搜索结果以卡片形式展示，具有精美的翻转动画效果。列表区域提供排序选项，用户可以按热门、最新等条件排序。搜索过程提供加载状态提示，让用户了解系统正在处理请求。 + +3. 响应式设计 + +自适应布局 + +项目采用 rem 单位进行移动端适配，根据屏幕宽度动态计算根元素字体大小。使用 postcss-pxtorem 自动将 px 转换为 rem，确保在不同设备上显示一致。布局组件根据设备类型自动调整侧边栏状态，移动端默认收起侧边栏以节省空间。 + +移动端优化 + +移动端特别优化了触控操作，按钮大小适合手指点击。聊天界面在移动端会调整输入区域和消息展示区域的比例，确保良好的输入体验。侧边栏在小屏幕设备上通过汉堡菜单访问，减少对主内容的干扰。 + +设备检测与适配 + +项目通过 isMobile() 函数检测用户设备类型，根据检测结果提供不同的界面布局和交互方式。例如，在移动设备上，聊天界面会隐藏不必要的装饰元素，专注于核心功能。 + +## 四、项目接口说明 +### 4.1 项目结构 +#### 4.1.1 前端 +```plain +vocata-web/ +├── Dockerfile +├── README-ENV.md +├── README.md +├── env.d.ts +├── eslint.config.ts +├── index.html +├── package.json +├── public/ +│ └── favicon.ico +├── src/ +│ ├── App.vue +│ ├── api/ +│ │ ├── modules/ +│ │ │ ├── conversation.ts +│ │ │ ├── role.ts +│ │ │ └── user.ts +│ │ └── request.ts +│ ├── assets/ +│ │ ├── images/ +│ │ └── styles/ +│ ├── layouts/ +│ │ ├── BasicLayout.vue +│ │ ├── SliderBar.vue +│ │ └── UserInfo.vue +│ ├── main.ts +│ ├── router/ +│ │ ├── guards.ts +│ │ ├── index.ts +│ │ └── routes.ts +│ ├── store/ +│ │ ├── index.ts +│ │ └── modules/ +│ │ └── chatHistory.ts +│ ├── types/ +│ │ ├── api.ts +│ │ ├── common.ts +│ │ └── debounce.ts +│ ├── utils/ +│ │ ├── aiChat.ts +│ │ ├── isMobile.ts +│ │ ├── rem.ts +│ │ └── token.ts +│ └── views/ +│ ├── ChatPage.vue +│ ├── LoginPage.vue +│ ├── NewRole.vue +│ ├── SearchRole.vue +│ └── components/ +├── tsconfig.app.json +├── tsconfig.json +├── tsconfig.node.json +└── vite.config.ts + +``` + + +4.2.4 会话管理接口 + +## 五、项目部署 +### 5.1 前端部署 +#### 5.1.1 Vite 生产构建配置 +```typescript +import { fileURLToPath, URL } from 'node:url' + +import { defineConfig, loadEnv } from 'vite' +import vue from '@vitejs/plugin-vue' +import vueDevTools from 'vite-plugin-vue-devtools' + +// https://vite.dev/config/ +export default defineConfig(({ mode }) => { + // 根据当前模式加载对应的环境变量 + const env = loadEnv(mode, process.cwd(), '') + + return { + plugins: [ + vue(), + vueDevTools(), + ], + resolve: { + alias: { + '@': fileURLToPath(new URL('./src', import.meta.url)) + }, + }, + server: { + port: 3000, + host: true, + proxy: { + // 代理所有 /api 开头的请求到后端服务器 + '/api': { + target: env.VITE_APP_URL, + changeOrigin: true, + // secure: false, + rewrite: (path) => path.replace(/^\/client/, 'client') + + } + } + }, + } +}) +``` + +#### 5.1.2 环境变量配置 +```plain +// 环境配置文件 +// .env.development +# 开发环境配置 - 默认使用本地环境 +VITE_APP_URL=http://127.0.0.1:4523/m1/7166225-6890394-default +VUE_APP_BASE_API=/api +VUE_APP_TITLE=VocaTa - 开发环境 +VITE_APP_ENV=development + +// .env.production +# 生产环境配置 +# 注意：VITE_APP_URL 将在CI/CD构建时动态替换 +VITE_APP_URL=http://{{PRODUCTION_HOST}}:9009 +VUE_APP_BASE_API=/api +VUE_APP_TITLE=VocaTa +VITE_APP_ENV=production + +// .env.test +# 测试环境配置 +# 注意：VITE_APP_URL 将在CI/CD构建时动态替换 +VITE_APP_URL=http://101.200.141.46:9009 +VUE_APP_BASE_API=/api +VUE_APP_TITLE=VocaTa 管理后台 - 测试环境 +VITE_APP_ENV=test +``` +