2026秋软工实践 我说的都队——项目原型设计+概要设计
| 项目 | 内容 |
|---|---|
| 作业所属课程 | 202601 软件工程 |
| 作业要求 | 团队作业（二）原型设计与概要设计 |
| 作业的目标 | 完成问径 408 的前后台原型，确定系统模块、关键流程和数据结构，并安排下一阶段开发。 |
| 团队名称 | 我说的都队 |
| 团队成员学号-名字 | 102401234 黄俊凡、102401309 叶凯乐、102401331 林明亮、102401333 周玘晖、102401330 高一鹏、102401225 王圣杰、102401233 郑志銮、102401334 王翔鹏、102401227 林子涵、102401212 沈雷、102400412 龚巍斌 |
一、项目与设计范围
问径 408 面向计算机考研复习，提供搜题、答疑和个人资料辅助学习。学生输入一道题和自己的思路后，可以选择直接看解析，也可以跟着提示逐步推导。维护端负责整理题目、来源和考点，记录答案核验过程。
这次设计围绕两条主线展开。一条从学生输入题目开始，经过检索、讲解和追问，最后留下本题的学习记录；另一条从题库资料导入开始，经过字段整理、错误修正和核验，形成可使用的题目。前后台原型、UML 和数据库设计都围绕这两条流程衔接。
二、原型设计
2.1 用户端
用户端使用 Figma，包含知识问答、我的资料、学习记录和模型设置。打开用户端原型
搜题结果先交代依据。 原题命中时展示题干、来源和核验状态；出现相似题时保留用户输入，提供候选参考；未收录时提示补充题目或资料。这样进入讲解前，学生就能看到本次答疑有哪些可用依据。
讲解分成直接与引导两种方式。 直接讲解展示完整解析和计算结果。引导页先给当前步骤的提示，学生可以继续追问、展开下一步，也可以主动查看答案。切换到另一道题时，新题单独保存作答、消息和揭示状态。
资料导入保留修正入口。 导入摘要展示成功内容和失败项，用户可以重试失败页或手动补充，再确认加入资料库。历史记录则提供继续答疑入口，恢复该题的学习模式和对话。
用户端的主要流程如下：
| 场景 | 操作顺序 | 关键反馈 |
|---|---|---|
| 搜题与直接讲解 | 输入题目和思路 → 查看检索结果 → 进入直接讲解 | 展示题源、核验状态、解析与计算依据。 |
| 引导学习 | 选择引导模式 → 阅读当前提示 → 追问或展开下一步 → 主动查看答案 | 提示逐步展开，查看答案后更新本题揭示状态。 |
| 资料与记录 | 导入资料 → 检查摘要 → 修正失败项 → 确认保存；从历史继续答疑 | 保留失败项处理入口，按题恢复学习模式与对话。 |
原型以预设题目和回复展示识别、追问、保存等操作反馈，后端接口与联调安排见概要设计。
2.2 后台管理端
后台使用墨刀分享页展示，覆盖题库列表、题目详情与编辑、答案核验、知识点管理和批量导入。打开后台原型
题库列表把来源、考点和核验状态放在同一行，便于维护人员筛选待处理题目。核验分为待核验、已核验和有争议，提交时填写依据，有争议时补充说明。
核验页把题目内容、参考答案和核验依据放在一起。维护人员检查后提交结论，列表同步显示核验状态，并给出提交反馈。
导入流程分为选择文件、字段映射、校验修正和结果摘要。必填字段缺失、重复题号、未知知识点以及格式错误都能定位到行，维护人员修正或跳过后再次校验。演示文件有 11 行，首次校验通过 6 行、需修正 5 行。将冲突题号 Q002 改为 Q112 后，通过数增加到 7。
后台的核验结论、导入校验和题库版本也对应到数据库设计：核验记录保存状态变化与依据，导入摘要保留成功和跳过数量，发布时选择生效版本。
后台配图取自本次交付的 WorkBuddy 交互演示版，在线展示入口使用墨刀分享页。
三、概要设计
3.1 系统架构
前端负责输入、结果呈现、对话和本地记录，后端通过 FastAPI 提供检索、答疑和资料解析。题库启动时载入内存，检索与答疑共用题目对象；Agent 组织当前题目、用户思路和资料片段，再调用适用的计算工具和模型服务。
| 模块 | 主要工作 |
|---|---|
| 学习端 | 接收题目与思路，切换学习模式，展示回复并保存本题状态。 |
| 题库检索 | 用文本检索召回候选，结合题干身份、参数和核验状态返回原题、相似题或未命中。 |
| 答疑 Agent | 取题、计算、组织提示、调用模型，并检查引导输出和来源说明。 |
| 资料解析 | 提取可用文本，返回失败明细，交给前端预览和确认保存。 |
| 推荐练习 | 按共享考点或章节找候选，排除当前题和已做题，返回推荐范围。 |
| 内容维护 | 通过原型确定题库编辑、核验、考点和导入规则，后续接入维护接口与持久化。 |
本次说明书按主干 003b459 和推荐分支 9e19063 组织设计。主干基线包含 16 道联调题，推荐分支提供 80 道待核验题。11 月 7 日，推荐前端 PR #15 已合入主干；11 月 8 日，同考点推荐后端与题库 v1.1（81 题）也已合入主干。推荐前端 PR #15 · 题库 v1.1 PR #19
3.2 UML 与 Agent 运行流程
UML 交付共 17 张图，分别说明系统组成、参与者、业务流程、运行对象和状态变化。正文展示主要图型，并展开一次答疑的调用过程；完整的 17 张图及说明收录在系统设计说明书中。
| 图的类型 | 本项目关注的内容 |
|---|---|
| 用例图 | 学生查题、答疑和资料管理，维护人员编辑、核验与导入。 |
| 活动图 | 学习流程的分支，以及后台导入失败后的修正与重试。 |
| 类图 | 题库加载、检索、Agent、模型客户端，以及会话和资料对象的关系。 |
| 时序图 | 一次答疑的调用顺序，推荐切题后的会话隔离。 |
| 协作图 | Agent 与题库、计算工具和模型客户端之间的消息传递。 |
| 状态图 | 题目核验状态、单题答案揭示状态。 |
用例与活动。 学生端用例从查题展开，连接答疑、资料和学习记录，也标出个人记忆、知识画像等后续功能。后台活动图展开批量导入：字段缺失时补充映射，行级校验失败时修正或跳过，再确认有效数据。
核心类与接口。 QuestionStore 提供题目，RetrievalService 处理检索，AgentService 组织答疑上下文。模型调用通过 LLMClient 接口接入，计算工具的状态和结果由 CalculationOutcome 返回。
对象协作。 学习端向答疑路由发送请求，路由调用 Agent；Agent 读取题目、执行适用的计算并调用模型。回复返回后，学习端保存当前题目的记录。协作图用消息编号表达调用顺序。
答疑时序。 一次答疑先按题号取题，对适用题型运行计算工具，再按模式和已有资料组织提示，最后调用模型并检查回复。以 Cache 地址划分题为例，工具先计算组数与地址位数，直接讲解时把计算依据一并呈现。引导模式先给步骤提示，学生主动查看后展示完整结果。
缺少绑定题目和可用资料时，当前服务提示补充。模型调用失败时保留输入和已有会话，便于重试。个人记忆、知识画像和变式生成列入后续设计，下一阶段先把搜题、答疑和推荐切题接好。
3.3 数据库设计
数据分为题库与用户学习过程两部分。题库当前由 JSON 文件加载，关系化方案使用 SQLite；学习记录保存在浏览器 history:v1，资料和切片保存在 materials:v1。答疑时选取相关片段随请求发送，回复、工具结果与引用随本题会话管理。
| 关系表 | 保存内容 |
|---|---|
| question_bank_version | 题库版本、发布状态、导入与跳过统计。 |
| question | 按版本保存的题干、选项、答案、解析和核验状态。 |
| knowledge_point | 统一的考点字典。 |
| question_knowledge_point | 题目与考点的关联。 |
| source | 题源、使用权限和核验资料。 |
| question_source | 某一版本题目对应的来源。 |
| question_review | 核验前后状态、执行人、时间、依据和内容标识。 |
题目以版本和题号共同定位，发布时选择一个生效版本。核验记录与题目状态在同一事务更新，内容修订通过新版本检查和发布。ORM 方案采用 SQLAlchemy，QuestionBankVersion、Question、KnowledgePoint、Source 和 QuestionReview 分别映射对应表。题目主键由 bank_version_id 与 question_id 组成，考点关联再加入 kp_id；核验记录用 previous_state 和 conclusion 保存前后状态。加载层将关系实体还原为后端题目对象，再交给检索和答疑服务。
推荐默认筛选已核验题，按共享考点数排序；同考点候选为空时按章节兜底。考点归并和核验会直接影响推荐结果，因此下一阶段先形成可用于联调的题组。
四、团队协作记录
4.1 预期开发安排
接下来先完成考点整理和推荐联调，再集中检查答疑、资料处理与异常恢复。以下为拟定安排，负责人和验收日期在发布前确认。
每周安排
| 时间 | 工作与负责人 | 产出与里程碑 |
|---|---|---|
| 11 月 10—16 日 | 林明亮核对题库考点与来源，完成核验记录和推荐题组；周玘晖复核题库接入、阈值和推荐范围；叶凯乐统一接口样例及维护规则；黄俊凡组织联调与进度检查。 | 形成可加载题库版本、题组与载入统计，完成推荐接口样例及异常规则定稿。 |
| 11 月 17—23 日 | 王翔鹏联调推荐与切题；郑志銮完善资料导入导出与记录恢复；高一鹏检查解析失败反馈；王圣杰验证直接与引导讲解；沈雷根据测试报告跟进修复复测；龚巍斌独立复核；林子涵发布并记录版本；黄俊凡组织验收。 | 跑通搜题、答疑、推荐新题、资料部分失败四条路径，修复已登记问题并交付回归记录与演示版本。 |
逐人分工
| 成员 | 下一阶段具体工作 | 预期交付 |
|---|---|---|
| 黄俊凡 | 汇总依赖、组织联调与阶段验收 | 任务进度、验收结论及材料清单 |
| 叶凯乐 | 确认接口与维护规则，更新调用样例 | 接口契约、异常与字段样例 |
| 林明亮 | 核对题库内容、来源及核验记录，整理 2～3 组同考点练习题，并与题库接入人确认字段映射 | 核验后的题库文件、来源与核验记录、考点对应表及同考点题组 |
| 周玘晖 | 题库加载、检索阈值和推荐后端联调 | 加载统计、检索与推荐结果 |
| 王圣杰 | 核对计算工具、引导与直接输出 | 典型题回复与工具核验记录 |
| 高一鹏 | 核对文字资料和部分失败场景 | 解析样例及失败项说明 |
| 郑志銮 | 完善资料导入导出和记录恢复 | 可恢复的资料文件与学习页面 |
| 王翔鹏 | 联调推荐范围、新题打开与会话隔离 | 推荐与切题完整路径 |
| 林子涵 | 更新部署、检查接口与记录版本 | 演示地址及发布记录 |
| 沈雷 | 根据第二轮测试报告跟进各模块修复，在修复版本上复测并更新缺陷状态 | 测试报告、缺陷清单和证据已通过 PR #17 合并；后续补复测结论 |
| 龚巍斌 | 独立复核接口、设计与页面一致性 | 复核结论与修正建议 |
4.2 本次作业记录
本次原型与概要设计的分工如下：
| 成员 | 本次负责内容 | 交付材料 |
|---|---|---|
| 黄俊凡 | 任务协调、材料汇总、说明书复查与博客整理 | 交付清单、说明书归档和团队博客 |
| 郑志銮 | 用户端页面、功能、主要流程与异常状态整理，原型验收 | 用户端原型及展示材料 |
| 王翔鹏 | 后台管理对象、核验与导入流程整理，原型验收 | 后台原型及展示材料 |
| 龚巍斌 | UML 图与文字说明 | 17 张 UML 图及说明 |
| 周玘晖 | 数据库设计说明书 | ER 图、关系模式、字段与 ORM 映射 |
| 叶凯乐 | 系统架构、模块和运行流程设计，汇总 UML | 系统设计说明书 |
原型部分按用户学习和后台维护两条流程整理页面、操作反馈与异常状态。概要设计汇总系统架构、UML 和数据库设计，再统一题目、核验状态、资料及会话等名称，核对图示与正文的对应关系。
两份设计说明书已通过 PR #16 归档到团队仓库。系统说明书汇总架构、模块和 UML，数据库说明书展开关系模式、字段与映射。
4.3 成员已有的 GitHub 贡献
下表列出仓库中已有的项目贡献记录，并链接到对应 PR。
| 成员 | 项目工作与进展 | 记录 |
|---|---|---|
| 黄俊凡 | 接口说明、后端 CI，以及本次设计材料归档 | 接口说明 #6、后端 CI #7、说明书归档 #16 |
| 叶凯乐 | 仓库整理；接口与数据规范、推荐方案及系统说明书交付 | 仓库整理 #9，设计交付见本次说明书 |
| 郑志銮 | 学习端输入、检索结果、本地问答历史与资料入口 | 学习端 #2 |
| 王翔鹏 | 答疑页面、学习模式及推荐切题前端 | 答疑页面 #8、推荐前端 #15 |
| 龚巍斌 | 独立复核与修正，本次完成 UML 设计交付 | 复核修正 #13，UML 收录于系统说明书 |
| 周玘晖 | 题库检索链路，本次完成数据库设计交付 | 题库检索 #3，数据库说明书见文末 |
| 林明亮 | 正式题库数据整理与交付：v1.0 80 题已由后端接入；v1.1 扩充至 81 题（四科 20/20/21/20），重写 4 道需变式题、新增 OS021，整理 3 组同考点推荐题（9 题）并输出题库核验与推荐题组记录；题库 v1.1 已接入主干 | 题库 v1.1 #19（已合并，同考点推荐后端一并合入） |
| 王圣杰 | Agent 答疑、计算核验与异常处理 | 答疑服务 #5、质量改进 #14 |
| 高一鹏 | 上传解析接口、支持范围与调用样例 | 解析实现 #10、调用说明 #12 |
| 林子涵 | 演示环境部署与发布维护 | 部署地址 #11 |
| 沈雷 | 第二轮统一测试、测试报告与证据归档 | 测试报告 #17 |
项目开发中的衔接记录
上传接口先统一失败信息。 解析端按文件和页面收集失败说明，前端据此展示摘要与重试入口。统一规范将 failure_details 定为字符串数组，配套文档列出成功、部分失败和错误请求样例。解析实现 #10 · 接口说明 #12
答疑质量结合工具和页面状态处理。 Agent 侧完善计算核验、引导输出和异常处理，前端保留学生输入、切换学习方式，并按题保存揭示状态。相关改进分别进入代码和 UML 时序、状态设计。Agent 改进 #14
推荐前端与题库整理相互衔接。 推荐方案约定 scope 表达同考点、同章节或空结果，前端据此显示标签。80 题交付件中的考点名称还需归并，核验完成后才能形成稳定的练习题组。推荐前端已在 11 月 7 日合入；11 月 8 日题库 v1.1（81 题）与同考点推荐后端一并合入主干，考点归并与已核验题独立复核列为后续工作。推荐前端 #15 · 题库 v1.1 #19
五、提交材料
- 问径 408 团队仓库
- 我说的都队_系统设计说明书.pdf
- 我说的都队_数据库设计说明书.pdf
- 原型设计展示
用户端和后台原型入口见第二节。两份说明书收录系统架构、UML、数据库关系模式和映射细节。