团队项目第一次作业
团队项目第一次作业
| 项目 | 内容 |
|---|---|
| 作业所属课程 | https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS |
| 作业要求 | https://www.cnblogs.com/dl-1-2/p/23594066 |
| 作业目标 | 使用智能体技术解决真实需求，完成团队展示、选题报告、需求分析和可上线作品 |
| 团队名称 | 硅基打工人 |
| 团队成员学号-名字 | 黄德朗 / 3124004133，朱海碲 / 3124004150，邓兴荣 / 3124004128 |
| 项目名称 | 知愿 · 高考志愿平台 |
| 项目形式 | Web 网站 + AI 志愿助手 |
一、团队展示
1.1 团队名称
硅基打工人
1.2 项目概述
知愿是一个面向高三考生和家长的高考志愿分析平台。网站以“真实院校分数查询 + AI 志愿分析 + 可继续追问的 AI 助手”为核心，用户可以先查询院校与专业录取分数，再让 AI 结合分数、位次和偏好梳理冲稳保方向，并随时追问不确定的问题。
项目当前已完成一个可运行的产品原型：
- 响应式 Web 站点：首页、院校分数、AI 志愿分析三个页面，以及全局 AI 助手抽屉
- 院校与专业分数实时查询自掌上高考公开数据接口
- 院校列表支持关键词、所在地、院校类型、生源省份、科类筛选与分页
- 院校详情弹窗可切换年份（2026 / 2025 / 2024）查看专业最低分、最低位次和批次
- AI 志愿分析支持流式输出、停止回答和继续追问
- 基于 LangChain4j 的流式对话、Tool Calling、Redis 对话记忆、输入护栏和聊天记录落库
- 可选 RAG：9 份本地 PDF（含 2025 年陕西 7 所院校共 458 条录取数据）经 DashScope Embedding 写入 Redis 向量库
- RAG 默认关闭，模型或向量库不可用时，院校与专业分数查询仍可正常使用
1.3 团队项目规划
| 阶段 | 目标 | 主要交付物 |
|---|---|---|
| 第一次迭代 | 完成选题、需求分析和项目骨架 | 需求文档、Spring Boot 工程、流式对话原型 |
| 第二次迭代 | 打通真实院校与专业分数查询 | 三个前端页面、院校检索接口、MySQL 旁路缓存 |
| 第三次迭代 | 完成 AI 志愿分析与上线准备 | 工具调用、对话记忆、输入护栏、可选 RAG、部署说明 |
1.4 队员风采
| 学号 | 姓名/昵称 | 性格 | 擅长技术 | 兴趣爱好 | 希望承担的软工角色 |
|---|---|---|---|---|---|
| 3124004150 | 朱海碲 | 稳重、善于统筹 | Java、Spring Boot、数据库 | 台球 | PM / 后端 |
| 3124004128 | 邓兴荣 | 细心、沟通主动 | Vue、HTML/CSS、交互设计 | 台球 | 前端 / UI |
| 3124004133 | 黄德朗 | 耐心、逻辑清晰 | LangChain4j、Tool Calling、Prompt | 台球 | AI 工程 / 后端 |
1.5 团队首次合照
1.6 团队愿景
我们希望知愿成为一个可信、克制、可解释的高考志愿分析平台。它不替学生做决定，而是把院校、专业、分数与位次讲清楚，让每个普通家庭都能获得透明、可追问的志愿分析服务。
二、选题报告
2.1 选题背景
高考志愿填报是一个典型的信息密集、决策压力大、容错率低的场景。考生和家长需要在有限时间内理解大量院校、专业组、招生章程、选科限制、历年分数和位次数据。
真实用户通常面临三个问题：
- 信息分散：院校官网、考试院、招生章程、社交平台和咨询机构各自提供一部分信息。
- 理解门槛高：一分一段表、专业组、调剂规则和批次规则并不直观。
- 决策焦虑强：家长既担心“冲不上去”，也担心“浪费分数”，还难以判断专业是否适合学生。
传统聊天机器人只能回答文字问题，无法形成完整工作流。知愿的目标是把 AI 放进真实业务流程中：既能解释规则，也能查询真实分数、整理冲稳保方向，并提示需要人工核对的信息。
2.2 目标用户与核心痛点
| 目标用户 | 核心痛点 | 知愿的解决方式 |
|---|---|---|
| 高三考生 | 不知道自己的分数适合什么学校 | 让 AI 结合分数、位次和偏好给出冲、稳、保三档方向 |
| 考生家长 | 信息太多，不知道哪些可信 | 集中呈现真实院校与专业分数，并明确数据来源 |
| 信息渠道有限的家庭 | 不知道如何比较专业和城市 | 院校检索、专业分数表和 AI 追问结合 |
| 高中生涯规划课程 | 缺少可演示、可操作的辅助工具 | 可本地部署的 Web 平台，按省份和科类切换 |
2.3 产品定位
知愿不是一个“替学生填志愿”的黑盒，而是一个面向考生和家长的志愿分析工作台。
产品重点不是让 AI 直接给出一条志愿表，而是帮助用户完成四步：
- 明确考生画像：省份、选科、分数、位次、专业偏好。
- 查询院校和专业：按关键词、地区、类型筛选，查看专业最低分和最低位次。
- 让 AI 梳理冲稳保：给出候选院校、专业、参考年份和数据依据。
- 继续追问或核对官方信息：对不确定的选项，提示到考试院和招生章程进一步核实。
2.4 杀手级功能
杀手级功能：真实录取数据驱动的可解释冲稳保分析 + 可继续追问的 AI 助手。
用户填写分数、位次和偏好后，AI 不只给出一个结论，而是：
- 必须调用工具查询真实院校与专业录取分数，以工具返回结果为准，不编造分数
- 按冲、稳、保三档组织候选院校与专业
- 每所院校说明参考年份、最低分、最低位次和推荐理由
- 明确指出哪些信息需要到省考试院或院校招生章程进一步核对
- 用流式输出边生成边展示，可随时停止
随后用户可以继续问：
“华南理工大学的计算机和深圳大学的电子信息怎么选？”
“我的方案是不是太激进了？”
“如果我想留在广东，应该删掉哪些学校？”
AI 会结合对话记忆和工具查询结果继续回答，而不是重新从零开始。
2.5 创新点
| 创新点 | 具体表现 |
|---|---|
| 真实数据工具化 | 系统提示词强制要求调用工具查询真实分数，工具查不到时如实说明 |
| 可解释分析 | 每个候选方向都有参考年份、最低分、最低位次和理由，不直接给黑盒结论 |
| 工程降级 | RAG 默认关闭；模型、Redis 或向量库异常时，院校与专业分数查询仍可用 |
| 性能与成本 | MySQL 旁路缓存 + 院校最低分 6 小时内存缓存 + 12 线程并发补充分数 |
| 产品化程度更高 | 单页三视图、全局 AI 抽屉、本地静态资源，部署后无需依赖外部前端 CDN |
2.6 适用范围与影响力
项目优先服务广东物理类考生，前端已支持切换生源省份、科类和年份。产品适用于：
- 高三学生和家长的日常志愿准备
- 高中生涯规划课程的教学演示
- 院校与专业信息的快速查询入口
- 作为可扩展的智能志愿分析原型，后续接入更多省份与批次数据
2.7 风险与边界
- 数据准确性风险：分数实时查询自第三方公开数据接口，正式上线前必须核对使用许可、接口稳定性和数据更新时间，最终以省考试院与院校招生章程为准。
- AI 幻觉风险：通过工具调用、系统提示词、输入护栏和数据提示降低风险，但不能完全消除。
- 决策责任边界：平台提供辅助分析，不替代考试院、院校招生章程和专业咨询。
- 隐私风险：考生分数、偏好和聊天记录会写入 MySQL 与 Redis，后续需要增加权限控制、脱敏和定期清理。
- 外部依赖风险：掌上高考接口、模型服务、MySQL 和 Redis 任一不可用都会影响部分功能，需要监控和降级提示。
三、需求分析
3.1 迭代记录
| 版本 | 迭代目标 | 完成内容 | 遗留问题 |
|---|---|---|---|
| V0.1 | 建立项目骨架 | Spring Boot、LangChain4j、MySQL、Redis、流式对话 | 只有单一聊天入口 |
| V0.2 | 打通真实分数查询 | 首页、院校分数、AI 志愿分析、MySQL 旁路缓存 | 数据来源说明待完善 |
| V0.3 | 完善智能体能力 | 工具调用、对话记忆、输入护栏、可选 RAG、2025 知识库 | 问卷与访谈样本待补 |
3.2 功能思维导图
mindmap
root((知愿))
首页
AI 助手入口
院校关键词搜索
热门院校实时数据
数据说明
院校分数
关键词搜索
所在地筛选
院校类型筛选
生源省份与科类
分页浏览
专业分数弹窗
年份切换与专业关键词
AI 志愿分析
考生信息表单
分数与位次校验
冲稳保分析
流式输出与停止
继续追问
AI 助手
多轮对话
真实分数工具
可选 RAG 知识库
会话记忆与会话记录
数据与降级
掌上高考公开接口
MySQL 旁路缓存
Redis 对话记忆
PDF 知识库
3.3 核心类图
classDiagram
class ChatController {
+chat(memoryId, message)
+analysis(memoryId, province, subject, score, rank, preferences, note)
}
class ChatHistoryController {
+list(sessionId)
+save(sessionId, userId, message, messageType)
}
class UniversityController {
+search(keyword, provinceId, type, page, size, scoreProvinceId, subject)
+filters()
+scores(schoolId, year, province, subject, keyword)
}
class UniversityAdmissionService {
+searchUniversities()
+getMajorScoresBySchoolId()
+getSchoolMinScore()
}
class UniversityAdmissionTool {
+searchUniversity(name)
+getMajorScores(schoolName, year, provinceName, typeName, majorKeyword)
+getSchoolMinScore(schoolId, schoolName, provinceName, subject)
}
class ChatHistoryService {
+save()
+listBySessionId()
+restoreMemory()
}
class AiRagDemoServiceFactory {
+createAiRagDemoService(memoryId)
}
class PromptSafetyInputGuardrail {
+validate(userMessage)
}
class UniversityScoreCacheMapper {
+get()
+insert()
}
class ChatHistoryMapper {
+insert()
+listBySessionId()
}
ChatController --> AiRagDemoServiceFactory
ChatController --> ChatHistoryService
ChatHistoryController --> ChatHistoryService
UniversityController --> UniversityAdmissionService
AiRagDemoServiceFactory --> UniversityAdmissionTool
AiRagDemoServiceFactory --> PromptSafetyInputGuardrail
UniversityAdmissionTool --> UniversityAdmissionService
UniversityAdmissionService --> UniversityScoreCacheMapper
ChatHistoryService --> ChatHistoryMapper
3.4 前端需求
| 页面 | 已实现功能 | 验收标准 |
|---|---|---|
| 首页 | AI 助手入口、院校关键词搜索、热门院校实时数据、数据说明 | 桌面和移动端无遮挡；热门院校加载失败时有空状态提示 |
| 院校分数 | 关键词、所在地、类型、生源省份、科类筛选，分页，院校专业分数弹窗 | 筛选条件变化后结果正确刷新；弹窗可切换年份和按专业关键词查询 |
| AI 志愿分析 | 省份、科类、分数、位次、偏好、补充关注点表单；流式结果；停止与继续追问 | 分数超出 0-750 时拦截；结果按冲稳保组织并展示数据依据 |
| AI 助手 | 全局抽屉、流式输出、停止回答、快捷问题、新建对话 | 可打开关闭；流式内容正常显示；异常时有明确提示 |
| 数据提示 | 数据来源说明、官方核对提示、AI 建议免责声明 | 页面和弹窗均可看到数据边界说明 |
3.5 后端接口
| 接口 | 方法 | 功能 |
|---|---|---|
/chat |
GET / POST | AI 流式对话，按 memoryId 维护会话记忆并保存聊天记录 |
/analysis |
GET / POST | 组装考生画像为分析指令，复用 AI 助手流式输出冲稳保分析 |
/chatHistory/list |
GET | 按 sessionId 查询聊天记录 |
/chatHistory/save |
POST | 保存一条聊天记录 |
/universities/search |
GET | 院校分页检索，补充生源省份与科类的真实最低分 |
/universities/filters |
GET | 返回省份、院校类型、科类、年份筛选项 |
/universities/{schoolId}/scores |
GET | 查询院校某年某省某科类的专业最低分与最低位次 |
后端采用 Controller -> Service -> Mapper 分层。院校数据通过 UniversityAdmissionService 调用掌上高考公开接口，并用 MySQL university_score_cache 做旁路缓存；聊天记录写入 MySQL，AI 对话记忆存入 Redis，服务重启时从 MySQL 恢复。
3.6 AI 智能体需求
智能体需要具备以下能力：
- 能聊：支持流式多轮对话，保留最近 20 条消息上下文。
- 能查：调用工具搜索院校、查询专业分数与最低分，不凭记忆编造分数。
- 能分析：结合分数、位次、选科和偏好，按冲、稳、保三档组织建议。
- 能解释：可选 RAG 检索本地 PDF，回答院校规则和专业问题。
- 能守边界：系统提示词限定志愿话题；输入护栏拦截超长、空输入、敏感词和 Prompt 注入。
- 能留痕：用户消息与 AI 回复自动落库，可按会话查询。
- 能降级：RAG 默认关闭；模型或向量库不可用时，院校与专业分数查询仍可正常使用。
3.7 数据需求
当前数据分为四类：
| 数据类型 | 当前来源 | 风险 |
|---|---|---|
| 院校信息、专业分数、最低位次 | 掌上高考公开数据接口（api.zjzw.cn） |
需要确认使用许可、接口稳定性和更新时间 |
| 专业分数缓存 | MySQL university_score_cache |
缓存过期与数据版本需要管理 |
| 对话记忆与聊天记录 | Redis + MySQL chat_history |
涉及考生分数与偏好，需要清理策略 |
| 院校规则、专业榜单 | resources/content 下的 9 份 PDF |
需要核对原文和版本 |
本地知识库当前包含：
- 7 所院校 2025 年陕西录取数据 PDF，共 458 条：西北农林科技大学、西北大学、西北工业大学、西安交通大学、西安电子科技大学、长安大学、陕西师范大学
热门专业top20.pdf与天坑专业top10.pdf两份专业榜单
RAG 开启后，PDF 经 500 字切分、100 字重叠，使用 DashScope text-embedding-v3（1024 维）写入 Redis 向量库，检索时最多返回 5 条、最低相似度 0.5。
正式上线前，数据表应补充以下字段：
数据年份、生源省份、科类、批次、专业名称、最低分、最低位次、
数据来源、来源链接、更新时间
3.8 验收标准
| 编号 | 验收项 | 通过条件 |
|---|---|---|
| A1 | 首页可访问 | 首页加载成功，热门院校和统计卡片正常展示 |
| A2 | 院校筛选 | 关键词、所在地、院校类型、生源省份、科类筛选结果符合预期 |
| A3 | 专业分数查询 | 院校弹窗可按年份查询专业最低分与最低位次，无数据时有空状态 |
| A4 | AI 志愿分析 | 输入 612 分、广东物理类、计算机偏好，可流式返回冲稳保分析 |
| A5 | AI 工具调用 | 询问具体院校分数时，AI 调用工具查询并说明参考年份与数据 |
| A6 | 输入护栏 | 空输入、超长输入、敏感词和注入语句被拒绝并给出提示 |
| A7 | 降级可用 | 关闭 RAG 或模型不可用时，院校与专业分数查询仍可使用 |
| A8 | 会话记录 | 对话结束后可按 sessionId 查询到用户与 AI 消息 |
| A9 | 构建部署 | mvn package 成功，Jar 可启动并访问页面 |
| A10 | 数据说明 | 页面明确提示数据来源与“以官方信息为准”的边界 |
四、项目实现效果
4.1 首页
4.2 院校分数
4.3 AI 志愿分析
4.4 AI 助手
五、总结
知愿从一个单一聊天页面出发，逐步扩展为包含真实院校分数查询、AI 冲稳保分析和可追问 AI 助手的 Web 产品。项目的价值不在于“接入一个大模型”，而在于把智能体能力嵌入真实业务流程：让用户可以查分数、看位次、做分析、继续追问，并且知道哪些信息还需要官方核对。
下一阶段最重要的任务不是继续堆页面，而是完成数据治理：补齐数据来源、来源链接和更新时间，明确第三方接口的使用边界，并把多省份、多科类的数据口径统一起来。只有把数据可信度做好，智能体才有可能真正进入高考志愿这种高责任场景。
浙公网安备 33010602011771号