天生一队-冲刺总结
天生一队-冲刺总结
| 项目 | 内容 |
|---|---|
| 这个作业属于哪个课程 | 2026-01 软件工程与软件工程实践(福州大学 计算机与大数据学院) 班级链接:https://edu.cnblogs.com/campus/fzu/2026-01SoftwareEngineeringandSoftwareEngineeringPractice |
| 这个作业要求在哪里 | 作业要求的链接 |
| 第一次作业 | 26软工实践天生一队团队展示与选题报告 |
| 第二次作业 | 天生一队:原型设计 + 概要设计 |
| 冲刺计划 | 天生一队-冲刺计划 |
| 团队名称 | 天生一队 |
| 团队成员-学号 | 蔡靖熹 102402116、吴政迅 102402138、庄剑钇 102402152、沈文驰 032401135、梁倩 102401607、王可人 102402104、陈瑀涵 102402107、吴雅晴 102402103、张佩琪 102402102、章玲 102402101、徐张睿 102402139、陈佳慧 052405110 |
| 这个作业的目标 | 在已上线的课件笔记整理 Agent 基础上,把智能自测、错题本、图形化思维导图三个功能落地为可演示的学习闭环;完成冲刺计划、冲刺总结、vlog、答辩 PPT 与仓库版本管理,配合 15 分钟内的现场答辩演示。 |
一、项目背景与本次冲刺目标
1.1 我们在解决什么问题
项目面向理工科本科生的课件复习场景。前期问卷回收 64 份校内样本:76.56% 的同学反映知识点分散、串不起来,75% 认为材料多、整理耗时,60.94% 不易提取重点。通用大模型能给出一段总结,但不会把课件拆成一条条可核对的知识点,也可能补出课件里没有的内容;笔记软件只负责存结果,不负责核对来源。本项目要补的正是这一段:学生上传课件后,系统产出绑定原文页码与引文的结构化笔记、考点清单和思维导图,并支持在材料范围内问答。
前两轮作业已经把基础链路跑通:多格式解析、结构化笔记生成、考点清单、文本思维导图、带出处问答、Markdown/LaTeX/Word 导出与历史记录。首轮实测知识点覆盖率 66.67%(24/36),无依据陈述比例 0%,问答正确率 83.33%(5/6),6 页课件整理约 12 秒。
1.2 本次冲刺做什么
本次 Alpha 冲刺自 11 月 7 日启动,11 月 22 日 00:00 截止,周期 16 天,满足作业不少于 14 天的要求。增量集中在巩固链的三个功能:
- U14 智能自测:按已整理任务组卷,单选、判断,服务端判分,答案不提前下发;
- U13 错题本:自测错题自动入库,按知识点聚合薄弱度,重做连对两次标记掌握;
- U15 图形化思维导图:由现有笔记派生树形结构,可缩放、折叠,点节点查看摘要与出处页码。
三个功能对应 4 张新表、9 个新接口、3 条验收演示路径,交付版本 v1.2.0。线上演示:http://47.114.55.115:8000/ (演示账号 verify_37777bd6,密码 verify123)。
二、冲刺计划改进项的落实情况
冲刺计划在 11 月 13 日至 15 日复盘后,把前期遗留问题归成协作流程、技术方案和风险降级三类。下面逐条对照计划说明落地情况。
2.1 协作流程改进
契约先行再并行。 11 月 16 日先冻结 4 张新表结构和 9 个接口字段,写成接口契约文档,后端、前端、测试拿同一套口径后再开工,避免接口没定互相等待。11.16 形成 1.0.0 基线。
分支协作、固定窗口合并。 每人在特性分支上开发,main 只由后端组长在固定窗口合入,避免半成品进主干;提交信息按「类型(模块): 说明」书写,例如 feat(自测): 新增交卷判分接口、fix(错题): 修正重复计数。
测试前置。 测试同学从 11.17 起按接口编写用例,不等代码全部写完再集中找问题;合并前先跑全量用例,自测、错题、导图都有对应用例。
全程留痕。 每日约 10 分钟站会只汇报昨天完成、今天计划、有无卡住,不在会上讨论细节;站会记录、分工截图、提交记录和演示录屏当天归档,同时作为 vlog 素材和总结证据。
2.2 技术方案改进
| 计划措施 | 落地情况与验证 |
|---|---|
| 答案只存服务端 | 取卷接口只返回题干与选项,answer、analysis 仅判分后随结果返回;用例 A16 覆盖未批改不泄露答案。 |
| 交卷单事务与幂等 | 分数、逐题对错、错题回填在同一事务内完成;仅 ready 状态可判分,重复提交返回上次结果。串行路径通过 BE45–BE48、A16–A18;并发交卷仍有缺陷,见 6.1 的 A33。 |
| 错题唯一键去重 | wrong_questions 以 (user_id, source_type, source_id) 为唯一约束,重复答错只累加 wrong_count,不新增记录;BE54、A24 覆盖。 |
| 版本快照与出处一致 | 题目、错题、导图节点都存 evidence_chunk_key 与页码;出处只在知识点与原文块之间维护一次,下游功能自动继承;A25、A27 核对页码一致性。 |
| 分层落库红线 | Agent 只返回结构化结果与评分,不持有数据库连接、不跨层写业务表,落库统一经后端服务层完成。 |
2.3 三个功能落地情况
| 功能 | 计划 MVP 边界 | 实际完成 |
|---|---|---|
| U14 智能自测 | 按任务组卷出 5 题;单选、判断;自动判分,答案不下发;交卷后给出逐题对错、答案、解析与出处页码 | 已完成。建卷、取卷、交卷、列表 4 个接口;支持单选与判断;判分与出处回查打通,答案不提前下发前端。 |
| U13 错题本 | 自测错题自动入库、同一题不重复计数;按知识点聚合薄弱度;重做连对 2 次标记掌握;详情跳回原文出处 | 已完成。错题 3 个接口;薄弱度按错题数与掌握状态聚合;连对 2 次自动掌握,掌握后再答错撤销掌握。 |
| U15 图形化导图 | 树形渲染,缩放、拖动、折叠;点节点看摘要与出处;数据来自现有笔记结构 | 已完成。导图 2 个接口;邻接表转嵌套树;前端组件支持缩放折叠,节点带摘要与出处页码。 |
U14 智能自测

U13 错题本

U15 图形化导图

三、实际架构与技术选型
3.1 分层结构
系统同源单服务部署,前端构建产物由后端挂静态目录,不额外引入网关与容器。一次请求从浏览器到数据分为六层:
- 展示层:学生端与管理端浏览器,Vue 3 + Vite + Element Plus,负责路由、组件、出处角标与状态管理;
- 接口层:REST 接口,签名令牌走 Cookie + Bearer,统一响应
{code, message, data}; - 服务层:解析、入库、FTS5 检索与覆盖率重排、导出、增量合并、模型客户端、判分与错题聚合等模块;
- 智能体层:六段管线编排(抽取 → 校验 → 归并 → 补全 → 生成 → 自评),提示词版本化,证据校验把引文回查原文;
- 数据层:
business.db业务库与kb.db领域知识库物理分离,原始课件存storage/uploads,FTS5 维护全文索引; - 运行环境:阿里云 ECS 2 核 4G,Ubuntu 22.04,systemd 守护、开机自启、崩溃重启,单 worker,安全组放行 8000/22,模型走 DeepSeek 外部调用。
3.2 几个关键取舍
检索用 FTS5 二元组加覆盖率重排,不上向量库。 单门课程只有几百个分块,BM25 量级足够;引入向量库要多一个需要运维和解释的组件。FTS5 的 OR 查询只要命中任一二元组就召回,比如问「量子力学的不确定性原理」可能因命中「力学」把导数章节召回,所以粗召回后再用二元组覆盖率本地重排,低于阈值就返回空。向量检索保留为开关 ENABLE_VECTOR,当前关闭。
存储用 SQLite,不换 MySQL。 业务库与知识库物理分离,单文件可整包迁移,适合课程演示与复现;代价是并发写弱,因此保持单 worker。
模型调用做了兜底。 DeepSeek 走 OpenAI 兼容协议,temperature 0.2;客户端支持多 key 轮换、指数退避,JSON 解析有三重兜底(response_format → 抠代码块片段 → 重试),单块失败跳过不拖垮整单任务。
证据校验前置。 每条知识点必须带原文连续引文,回查不到就整个丢弃并计入 dropped_items,不接受同义改写充当出处。这也是「无依据陈述比例」能算成指标的原因。
四、遇到的问题与解决
冲刺中遇到的故障大多不是崩溃,而是「本机看起来正常、测试也全绿」,这类问题最难查。下面三个是典型案例,每条都配了可执行的验证动作和防复发机制。
| 问题 | 现象与根因 | 解决与验证 | 固化机制 |
|---|---|---|---|
| 跑一次单元测试把开发库清空 | pytest 跑完本地账号、任务、笔记全没,被清过两次;conftest.py 没有隔离存储目录,测试里直接重建了开发库,且全程不报错 |
在 import app 之前把存储目录指向临时目录并强制 AGENT_STUB=1;跑测试前后核对 users 数量不变 |
conftest 统一接管存储与外部依赖,测试禁止指向默认 STORAGE_DIR |
.env 行内注释让功能开关静默失效 |
结果页质量自评卡片一直不出现,配置里明明写着 ENABLE_QUALITY_EVAL=1;python-dotenv 把「1 # 注释」整行读进值,与「1」比较不等,开关被当成关闭 |
读配置前先按 # 截掉注释再解析,数值非法回退默认值;补带注释、非法数值、空值的回归用例 |
配置只走一个解析入口:截注释 → 校验类型 → 给默认值 |
| 三方代码合到一起跑不起来 | 导图页面 404、接口 ImportError、两个页面显示假数据、建库 CHECK 约束失败;路由放在仓库根目录没被扫描,两个依赖模块没进交付包,前端两页 USE_MOCK=true,两套 DDL 冲突 |
以接口契约为合并依据,按主责文件切分,共享文件只收最小 patch,补齐 DDL 迁移;部署前后核对账号数 7 → 7,三条验收路径逐条走通 | 合并 checklist:契约 → 主责 → DDL → 对账,缺一项不合 |
此外还修复过导图生成 500(占位符与参数数量不一致)、自测接口 500(缺 error_message 列、CHECK 不含 failed)、组卷后取卷为空(前端轮询到 ready 再渲染)、交卷字段别名不一致、重做缺选项、节点标题撑爆(名称清洗截断 20 字)、导出 Word 中文文件名与控制字符崩溃等问题,记录在仓库 README 缺陷表与 CHANGELOG 中。
五、项目亮点
把课件从「一份文件」推进到可复习的结构,本期最直接的成果是巩固链接通了:自测发现薄弱点,错题本自动归集,重做两次答对即标记掌握,导图给出章节框架,三者挂在同一批知识点上,薄弱度口径一致。
每条结论都能回查原文。知识点、题目、错题、导图节点都绑定分块标识与页码,回查不到依据的内容入库前就被拦截;同一份 68 页课件、同一模型对比,知识点覆盖率 66.67%(24/36,裸模型 38.89%,高出 27.78 个百分点),无依据陈述从裸模型 100% 降到 0%,问答正确率 83.33%(5/6,自动关键词判定,偏保守),质量自评 82.1 分(85/10/5 加权)。
工程上几个约定贯穿全程:契约先冻结再并行,Agent 不直接写业务表,出处只维护一次,新版本不覆盖旧记录。部署、发版、迁移都有脚本固化(deploy.sh、release.py、migrate_backup.sh),不是手敲命令。成本与时延方面,6 页课件整理约 12 秒,68 页全章约 111.7 秒、49,167 tokens,单次全章调用约 1~2 元。
六、现存不足与后续计划
6.1 尚未闭环的 3 条测试用例
本期共执行 95 条测试记录,3 条未通过,根因与修复方向如实记录如下。
| 编号 | 现象 | 根因 | 修复方向 |
|---|---|---|---|
| A30 | 草稿试卷交卷返回 200,预期 409 | 状态机漏草稿分支校验,草稿/failed 状态未拦截 | 交卷前补状态校验,非 ready 一律拒绝并返回 409。 |
| A32 | 请求 5 题返回 4 题,仍置为 ready | 知识点不足以兑现题量时没有明确拒绝,少给题仍放行 | 题量不足时返回明确错误并说明,不允许少给题就置 ready。 |
| A33 | 两次并发交卷错题次数翻倍 | 两请求同时读到 ready,事务内无行锁或版本号拦截 | 交卷增加数据库行锁或乐观版本号,拒绝过期提交。 |
6.2 已知边界
- 检索:向量检索保留为开关但默认关闭,同义改写问题召回不足;当前先用覆盖率重排保证零召回正确。
- 识别:手写公式 OCR 未启用,扫描件与图片需配置 OCR 密钥后方可识别。
- 核验:暂无事实核验能力,多份材料冲突时并列保留各自出处,不判断谁对谁错。
- 运行:单 worker,并发整理会排队;本期未做并发压测。
- 测试:前端没有 UI 自动化,靠手测与验收动线;覆盖率为保守文本匹配,不是人工语义覆盖率;问答正确率为自动关键词判定,未做人工双评。
- 数据:领域知识库(kb.db)仅建表、未灌数据,问答基于上传课件。
- 本期不做:记忆卡片与 SM-2 间隔重复、复习清单、简答题判分、错题多维筛选、节点编辑、跨课程合并导图。
6.3 后续迭代优先级
先修复 A30、A32、A33 三个缺陷;再补向量检索融合排序,启用手写公式 OCR;落地记忆卡片与复习闭环;增加事实核验与材料冲突标注;改造任务队列与多 worker;管理端治理页面逐步补齐。
七、实际进度与燃尽复盘
进度口径:12 个工作包按计划工作量占比折算权重,合计 100 点,工作包验收通过当日计入累计完成度。数据截至 2026 年 11 月 20 日 24:00,11.21 与 11.22 为计划与截止日值。
| 日期 | 当日里程碑 | 计划累计% | 实际累计% | 偏差(计划-实际) |
|---|---|---|---|---|
| 11-07 | 冲刺启动 | 0 | 0 | 0 |
| 11-09 | 第二次作业博客发布、验收报告补齐 | 6 | 6 | 0 |
| 11-15 | 复盘与改进方案定稿(MVP 边界、降级预案、分工) | 14 | 14 | 0 |
| 11-16 | 契约冻结:4 表 9 接口;1.0.0 基线 | 20 | 20 | 0 |
| 11-17 | 计划后端骨架跑通;实际仅站会与 readme 更新 | 40 | 20 | 20 |
| 11-18 | 计划前后端联调;实际无代码合入 | 72 | 20 | 52 |
| 11-19 | 错题本、出题/导图路由、前端三页合入 | 80 | 60 | 20 |
| 11-20 | 三方合并:补齐自测、部署、58 项测试、1.2.0 打包 | 95 | 95 | 0 |
| 11-21 | 预计:博客定稿、vlog、PPT 入库、打 release | 100 | 100 | 0 |
11 月 17 日至 18 日进度落后计划,11.18 计划累计 72%、实际仅 20%。原因是并行开发初期,前后端联调与三方合并问题集中在 11.19 晚爆发;11.19 至 11.20 通过集中合并、补齐自测后端与部署回归把进度追回,11.20 实际 95% 与计划持平。整体没有出现里程碑失控,计划中的风险降级预案本期未触发。
项目实际进度曲线图

燃尽图

八、测试工作评述
8.1 测试安排与工具
测试分五个阶段:开发期(11.16–11.18)契约用例随接口同步落地,前端先用 mock 并行;合并前由后端组长统一合入,合并前先跑全量用例;代码冻结(11.19)后部署线上跑回归与端到端冒烟;测试执行(11.20)完成用例执行、数据校验与指标复算;答辩前(11.21–11.22)逐条走查三条演示路径并录制兜底录屏。
工具上以 pytest 全量作为发版门禁,按契约、解析、接口、Agent 管线、自测、错题、迁移、导图前端分组覆盖;另配端到端自检 e2e_smoke.py、学习闭环冒烟 smoke_learning_loop.py、SQL 占位符静态检查 lint_sql_params.py,以及评测脚本 eval_agent.py、bench_compare.py。
8.2 执行结果
11 月 20 日在本地临时库加占位模型下执行,结果如下。
| 组别 | 执行 | 通过 | 失败 | 说明 |
|---|---|---|---|---|
| 后端回归(BE01–BE58) | 58 | 58 | 0 | 全部通过 |
| 导图前端(FE01–FE04) | 4 | 4 | 0 | 全部通过 |
| 补充检查(A01–A33) | 33 | 30 | 3 | 3 项失败,见 6.1 |
| 合计 | 95 | 92 | 3 | 通过率 96.8%,0 跳过 |
8.3 结论与边界
五层自动化加三道人工关卡(/docs 交互抽查、浏览器手测与截图、合并窗口人工复核 diff)拦住了多个真实缺陷,其中包含会导致线上 500 的问题。同一份课件、同一模型下,覆盖率较裸模型提升 27.78 个百分点,无依据陈述从 100% 降到 0%。全量回归约 1 分钟,「改完先跑再合并」能够真正执行。
需要交代的是:覆盖率口径、UI 自动化、并发压测与 OCR 识别,是下一轮测试要补的四件事。
九、成员完成内容与工作量比例
本期按模块切分,一个人只对一组文件负责。下表占比为本阶段工作量估算,合计 100%。
| 学号 | 姓名 | 角色 | 完成内容与交付物 | 工作量占比 |
|---|---|---|---|---|
| 102402138 | 吴政迅 | 组长 / 博客 | 组织协调沟通、督促进度、查缺补漏;撰写冲刺计划与冲刺总结博客,汇总分工与工作量,统筹答辩材料。 | 10% |
| 102402139 | 徐张睿 | 后端组长 | 智能自测后端 4 个接口;接口契约定稿;交卷判分事务;特性分支合入主干。主责 routes_self_test.py、quiz.py。 |
12% |
| 032401135 | 沈文驰 | 后端 / 数据 | 错题本后端 3 个接口;错题自动入库与按知识点薄弱度聚合;重做判定、连对计数与掌握状态更新。主责 routes_wrong.py、wrong_book.py。 |
9% |
| 102402107 | 陈瑀涵 | 后端 / Agent | Agent 出题模块与出题提示词;导图树数据接口与重建接口;保证题目带出处。主责 agents/quiz.py 与导图 2 个接口。 |
9% |
| 052405110 | 陈佳慧 | 前端 | U14 自测页面与 U13 错题本页面;组卷、作答、看批改、看错题与重做的前端交互及路由。主责 SelfTestView.vue、WrongBookView.vue。 |
9% |
| 102402116 | 蔡靖熹 | 后端 / 部署 | 4 张新表迁移脚本;U15 导图组件;线上部署与回归;仓库分支与版本发布管理。主责迁移 SQL、MindMapGraph.vue、MindMapView.vue。 |
9% |
| 102402102 | 张佩琪 | 测试 / 图表 | 测试用例设计与执行、回归测试;绘制项目实际进度曲线与燃尽图;记录问题与解决过程。 | 7% |
| 102402103 | 吴雅晴 | 测试 / 图表 | 配合测试执行与数据校验;进度曲线与燃尽图绘制;核对表结构、知识点关联与出处一致性。 | 7% |
| 102402104 | 王可人 | 答辩 PPT | 与梁倩合作完成答辩 PPT:成员分工与预期计划、进度曲线与燃尽图、问题及解决、实际架构、测试安排、成员体会。 | 7% |
| 102401607 | 梁倩 | 答辩 PPT | 与王可人合作完成答辩 PPT,配合页面截图、演示流程与版式排版。 | 7% |
| 102402101 | 章玲 | 答辩演讲 | 准备答辩讲稿与现场串讲;配合 PPT 完成 10 分钟 PPT 演讲与作品演示的现场表达。 | 7% |
| 102402152 | 庄剑钇 | vlog 剪辑 | 收集每日冲刺日志、站会与队友交流素材;剪辑整合为 3–5 分钟 vlog,讲清冲刺计划、每日进度与协作过程。 | 7% |
十、成员过程体会
吴政迅(组长 / 博客)
作为组长,我负责协调分工、督促进度并撰写计划与总结博客。这次冲刺让我体会到明确分工、及时沟通与过程留痕对团队项目推进的重要性,也锻炼了统筹协调能力。
徐张睿(后端组长)
我负责先定契约再写代码,省下的是返工时间。真正难的是「看起来对」和「真的对」的差距:前端开着模拟数据时页面很完美,我的验收脚本还跑出过假通过。所以验证要分层,最后一层得真在浏览器里点一遍。别人照着文档能跑起来,才算做完。
沈文驰(后端 / 数据)
本次负责错题本后端与薄弱度聚合开发,从接口契约、表迁移到判分口径统一与联调自测,走通需求落地闭环。深刻体会到契约先行与事务边界设计对后端工程的重要性。
陈瑀涵(后端 / Agent)
我主要负责 Agent 出题模块与导图树数据接口,编写出题提示词并保证题目带出处,配合前端联调。这次冲刺让我体会到接口契约先冻结、出处统一维护对并行开发的重要性,也锻炼了结构化输出与协作排障能力。
陈佳慧(前端)
我主要负责智能自测与错题本页面及整体视觉还原。这次冲刺让我体会到契约先行、并行开发能大幅减少返工,也体会到把成果及时提交、留痕对团队协作同样重要。
蔡靖熹(后端 / 部署)
本次项目主要负责数据库迁移、思维导图前端开发及测试。通过实践,我加深了对数据库设计、前后端协作和版本管理的理解,也体会到明确接口规范与团队分工的重要性。
张佩琪(测试 / 图表)
我主要负责测试用例设计、测试与回归,以及进度曲线和燃尽图绘制。这次冲刺让我体会到数据核验、问题记录与及时沟通的重要性,也锻炼了测试分析与协作能力。
吴雅晴(测试 / 图表)
我主要负责配合测试执行与数据校验,并绘制进度曲线和燃尽图。这次冲刺让我体会到数据口径统一与问题留痕的重要性,也认识到测试前置、及时沟通才能让问题在合并前暴露。
王可人(答辩 PPT)
我主要负责答辩 PPT 的制作,与梁倩分工梳理汇报的六项内容,逐项对接取料并核对数据出处,统一版式与术语。这次冲刺让我体会到提前对齐口径、及时沟通取料对材料制作的重要性,也锻炼了协作与汇总能力。
梁倩(答辩 PPT)
我主要负责 PPT 内容的补充与完善。按答辩六项要求梳理清单,对架构部署、燃尽图、测试评述等缺口逐项对接取料,汇总后校核出处、删繁就简、统一术语,确保每页内容有据可依。
章玲(答辩演讲)
我主要负责项目的演讲与答辩。这次冲刺让我体会到,准备汇报不仅要讲清功能,还要理解实现思路和测试结果,用事实说明项目进展,也认识到提前沟通和熟悉材料的重要性。
庄剑钇(vlog)
我主要负责 vlog 的制作与剪辑,依照时间线通过视频的方式呈现每日小组会议。这次冲刺让我体会到团队合作的重要性。
十一、vlog展示
十二、相关链接
- GitHub 团队仓库:TCHHPK/FZU-SoftwareEngineeringTeamHW02
- 线上演示系统:http://47.114.55.115:8000/(演示账号 verify_37777bd6,密码 verify123)
- Figma 原型:https://www.figma.com/proto/iDdth59yZaOjSaWgHvajkQ/agent2.0
- 第一次作业博客:https://www.cnblogs.com/always111/p/23392257
- 第二次作业博客:https://www.cnblogs.com/always111/p/23606384
- 答辩PPT:https://github.com/TCHHPK/FZU-SoftwareEngineeringTeamHW02/blob/main/天生一队-Alpha冲刺答辩PPT.zip

浙公网安备 33010602011771号