[T.15] 团队项目：Beta 阶段项目计划

[T.15] 团队项目：Beta 阶段项目计划

项目	内容
这个作业属于哪个课程	北航 2026 年春季软件工程
这个作业的要求在哪里	[T.15] 团队项目：Beta 阶段项目计划
我在这个课程的目标是	体验完整的软件开发与工程管理流程，交付能切实解决同学痛点的智能学习平台
这个作业在哪个具体方面帮助我实现目标	明确 Beta 阶段的需求与技术方案更新，合理划分 WBS，将任务落实到 Issue 并责任到人

一、 Alpha 阶段回顾与反馈整理

在 Alpha 阶段，“启元知微”智能学习平台搭建完成了知识问答、题库资料、学习论坛、实用工具的核心功能闭环，并成功进行了 Web 部署。然而，经过第一阶段的实际体验和测试反馈，我们发现系统仍然存在不少待解决的痛点和已知限制：

1. AI 问答溯源机制空缺：目前的 RAG 问答虽能检索课程知识库，但在流式输出答案时无法在正文中标记具体的参考来源。同学在考前复习时，无法便捷地对照教材或讲义原文进行二次核对。
2. 错题复练体验不完善：Alpha 阶段开放了错题本的基本入口，但“错题”与“练习”没有打通。同学只能被动看错题，无法一键筛选错题并快速生成专项测试卷。
3. 运营数据与埋点缺席：作为教学辅助应用，我们缺乏自动化度量用户行为的埋点，无法客观评估各功能模块的使用热度。
4. 论坛治理机制缺失：虽然前端支持举报违规内容，但缺少相应的后台管理工具，对于违规内容的处理高度依赖团队人工直接修改数据库。
5. 体验与适配问题：移动端部分排版在大段公式和表格下依然存在溢出或错位。

二、 功能规格说明书更新

我们对原《功能规格说明书》进行了以下修订，新增并细化了 Beta 阶段拟实现的功能：

2.1 新增功能矩阵

序号	归属模块	功能点	功能描述	优先级
1	知识问答	**引用溯源 **	在 RAG AI 答复中，流式渲染带编号的引用角标。点击该角标，可悬浮展示参考的课件、讲义片段、页码等元数据。	P0
2	知识问答	资料库扩充	丰富知识库资源，扩充录入《操作系统》、《编译原理》、《计算机组成原理》等北航核心专业课的高质量资料。	P0
3	题库资料	错题复练与高级筛选	允许用户在错题本中按课程、错题频次进行复合筛选；支持“一键生成错题复练卷”并进行限时模拟。	P1
4	题库资料	AI 辅助解题增强	在题目详情页面，提供“AI 深度解析”一键流式生成功能，帮助无法得出答案的同学直接通过 RAG 关联上下文学习解题步骤。	P1
5	学习论坛	极简管理员后台	补全前台举报向后台的管理流转。管理员可一键屏蔽/删除违规帖子和回复，并支持临时对账号实施禁言。	P1
6	数据埋点	行为数据统计	记录用户的每日活跃状态、使用习惯，支撑内部运营看板，为后续迭代提供数据客观参照。	P0
7	基础体验	自适应与暗色适配	针对问答页、论坛长帖排版和 Markdown 解析器进行 CSS 重构，提升移动端多设备和暗色模式下的阅读舒适度。	P1

2.2 典型用户场景更新

【场景：基于错题本与引用溯源的闭环复习】

• 用户：小明，北航大三学生。
• 复习痛点：期末备考《操作系统》时间紧迫，手里积攒的错题很多，看解释依然似懂非懂，反复查讲义很浪费时间。
• 使用过程：
  1. 小明打开发布地址登录“启元知微”，进入题库资料 -> 错题本。
  2. 他勾选“操作系统”，将错题频次大于 2 次的题目筛选出来，点击“错题复练”，系统提取这 5 道错题一键生成错题专项检测。
  3. 在作答到其中一道涉及“虚拟内存页面置换”的题目时，小明再次答错。他点击“AI 辅助深度解析”。
  4. 解析流式生成，其中对于概念“工作集”的解释旁出现了一个高亮的引用标识。
  5. 小明点击标识，页面悬浮展示了资料库中《操作系统讲义_Chapter 9》第 43 页的内容原文。
  6. 他结合原文豁然开朗，不仅纠正了错误，还可以顺手将该题解析导出，整理进自己的本地复习笔记中。

三、 技术规格说明书更新

为支撑功能演进、降低生成开销，我们在原《技术规格说明书》基础上，对架构、协议以及数据表进行了升级：

3.1 架构与协议更新

1. RAG 引用元数据流式协议

• Alpha 方案：RAG API 返回生成的纯文本流，前端直接作为 Markdown 解析并渲染。
• Beta 方案：
  1. 在 RAG 服务端检索阶段，保留检索文档块的元数据（包括：源文件名、对应页码、文本摘要、相关度分值）。
  2. 后端返回 SSE 数据流时，首先在会话的开头事件包中传输 references_meta JSON 结构，分配唯一的 cite_id。
  3. LLM 在生成回复时被指令约束（通过 Few-shot Prompt），在引用了对应知识块的内容处，必须规范化输出标记，如 <cite id="1"/>。
  4. 前端接收到数据后，通过自定义的渲染规则拦截 <cite id="x"/> 并替换成可交互的点击按钮。点击后从本地缓存的 references_meta 中读取该 id 对应的段落内容，以此实现流式回复与溯源的统一。

2. 数据埋点与可观测性方案

• 设计原则：降低对高频数据库 IO 的开销，避免同步写入拖慢主业务性能。
• 实现路径：
  • 前端利用局部埋点上报中间件发送操作埋点。
  • 后端提供轻量上报接口，将事件推入 Redis 列表作为消息缓冲。
  • 引入定时任务，每隔 15 分钟将 Redis 中的计数、点击和留存日志批量写入 user_activity_logs MySQL 汇总表中，供看板直接查询。

3.2 数据库模式变化

我们在原有表结构上，新增以下表设计以支持 Beta 新功能：

-- 错题本表：wrong_questions
CREATE TABLE wrong_questions (
    id INT AUTO_INCREMENT PRIMARY KEY,
    user_id INT NOT NULL,
    question_id INT NOT NULL,
    wrong_count INT DEFAULT 1,
    last_wrong_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    status VARCHAR(20) DEFAULT 'unresolved', -- 'unresolved' (未掌握), 'resolved' (已掌握)
    FOREIGN KEY (user_id) REFERENCES users(id),
    FOREIGN KEY (question_id) REFERENCES questions(id)
);

-- 用户行为日志汇总表：user_activity_logs
CREATE TABLE user_activity_logs (
    id INT AUTO_INCREMENT PRIMARY KEY,
    user_id INT,
    event_type VARCHAR(50) NOT NULL, -- 'login', 'qa_session', 'quiz_submit', 'forum_post'
    event_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    ip_address VARCHAR(45)
);

四、 Beta 阶段 WBS 工作分解

我们将 Beta 阶段的工作分解为如下 4 个大方向，拆分并确保每个底层叶子任务工时均不大于 8h：

Beta 交付目标
├── 1. 深度复习链路深化 (Deepening Core Flow)
│   ├── 1.1 RAG 引用元数据格式协议制定与后端改造 (Backend / RAG)
│   ├── 1.2 前端引用交互卡片与流式拦截渲染实现 (Frontend)
│   ├── 1.3 错题数据落库与基础 CRUD、掌握状态管理 (Backend)
│   ├── 1.4 错题专项智能组卷算法与 Session 初始化 (Backend)
│   ├── 1.5 错题本多维筛选与答题检测交互重构 (Frontend)
│   ├── 1.6 AI 题目深度解析流式 Prompt 与接口联调 (Backend / RAG)
│   └── 1.7 核心课程（《操作系统》、《编译原理》）高精准知识向量重建 (RAG)
├── 2. 数据看板与治理支撑 (Operation & Telemetry)
│   ├── 2.1 用户行为日志数据表设计与 Redis 缓冲队列中间件 (Backend)
│   ├── 2.2 DAU、周留存率及各板块点击热度聚合统计 API (Backend)
│   ├── 2.3 举报信息管理与管理员极简操作后台（下架、禁言） (Backend)
│   ├── 2.4 管理员前台违规审查面板开发 (Frontend)
│   └── 2.5 后端 API 路由级别限流防御实现 (FastAPI-Limiter / Backend)
├── 3. 自适应与细节优化 (UI & UX)
│   ├── 3.1 移动端屏幕下论坛列表、长帖展示适配 (Frontend)
│   ├── 3.2 错题本与个人中心移动端布局微调 (Frontend)
│   └── 3.3 markdown/Mermaid 加载态及暗色主题对比度修正 (Frontend)
└── 4. 质量保障与部署 (QA & DevOps)
    ├── 4.1 埋点、错题本核心单元测试与 pytest CI 集成 (DevOps)
    ├── 4.2 数据库定期安全自动备份机制与快速回滚验证 (DevOps)
    └── 4.3 联合功能回归测试与 Beta 正式环境平滑上线 (PM / QA)

五、 团队角色与 Beta 阶段任务分配

延续 Alpha 阶段的分工，我们保持原有开发团队的角色映射，并通过 PERT 对以下 Issue 进行了工时评估。所有任务已在 Github 对应仓库以 Milestone: Beta 的形式建立了 Issues 跟踪。

团队成员角色

• PM / 部署：袁子轩
• 后端开发：罗浩宇、李昊霖、李昊宸、赵志勇
• 前端开发：王赫、刘诗怡

Issue 任务分配表

Issue ID	任务标题	归属模块	负责人	优先级	估时(h)	依赖任务
#beta-01	后端设计 user_activity_logs 结构及 Redis 写入缓冲中间件	Telemetry (BE)	罗浩宇	P0	6	无
#beta-02	开发 DAU / 功能热度聚合统计 API 并输出埋点看板数据	Telemetry (BE)	罗浩宇	P0	6	#beta-01
#beta-03	RAG 检索协议重构，使流式输出中带 Metadata 及 cite 角标	RAG / BE	李昊宸	P0	8	无
#beta-04	设计高精准向量数据，补充录入《操作系统》与《编译原理》资料	RAG	李昊宸	P0	5	无
#beta-05	前端正则解析 <cite id="x"> 并支持点击悬浮详情弹卡	Frontend	王赫	P0	7	#beta-03
#beta-06	错题本数据库设计，错题状态更新与只读筛选 API 开发	Bank (BE)	赵志勇	P0	6	无
#beta-07	错题复练：支持基于错题集智能组织临时测试 Session 的 API	Bank (BE)	赵志勇	P1	6	#beta-06
#beta-08	错题本前端页面：按科目筛选错题并一键触发复练的前端开发	Frontend	刘诗怡	P1	7	#beta-06
#beta-09	题目详情页“AI 辅助深度解析”流式 prompt 调优及接口开发	Q&A (BE)	李昊霖	P1	5	#beta-03
#beta-10	论坛管理端：开发违规帖子下架、高频举报拉黑等管理员 API	Forum (BE)	李昊霖	P1	5	无
#beta-11	极简管理员面板：前台举报一键下架、封禁等轻量视图实现	Frontend	刘诗怡	P1	6	#beta-10
#beta-12	API 限流防护：基于 FastAPI-Limiter 限制 AI 解析接口频次	Telemetry (BE)	罗浩宇	P1	4	无
#beta-13	移动端体验适配：重点适配论坛列表、问答和错题复练组件样式	Frontend	王赫	P1	6	无
#beta-14	编写数据库异地备份脚本，更新 Beta 部署 docker-compose 描述	DevOps	袁子轩	P0	5	无
#beta-15	针对埋点缓冲及错题组卷逻辑补充核心 pytest API 单元测试	QA / PM	袁子轩	P0	6	无

六、 Beta 阶段周进度规划 (Gantt-like Schedule)

Beta 阶段将按照三周的敏捷迭代周期（2026.05.25 - 2026.06.14）进行安排：

gantt title 启元知微 Beta 阶段进度规划表 dateFormat YYYY-MM-DD section 第一周 (底层搭建与核心改造) RAG引用协议与后端设计 :active, 2026-05-25, 2026-05-31 错题本与埋点底层接口开发 :active, 2026-05-25, 2026-05-31 专业课知识库重新切片索引 :active, 2026-05-27, 2026-05-31 section 第二周 (前后端联调与功能合流) 前端渲染拦截与悬浮卡片 :after RAG引用协议与后端设计, 5d 错题专项组卷联调 :2026-06-01, 2026-06-07 论坛管理与举报后台系统联调 :2026-06-02, 2026-06-07 移动端CSS适配优化 :2026-06-03, 2026-06-07 section 第三周 (回归测试、发布与总结) 编写自动化测试与灰度回归 :2026-06-08, 2026-06-12 数据定期备份与部署脚本整理 :2026-06-09, 2026-06-12 Beta发布与演示总结 :2026-06-13, 2026-06-14

1. 第一周（2026.05.25 - 2026.05.31）：骨干链路改造与数据库迁移

• 目标：打通引用溯源与行为埋点的底层接口设计，建立错题本的独立库表，完成新增专业课的资料清洗。
• 里程碑点：后端与 RAG 实现带 Metadata 引用标的 API 传输；错题库结构迁移完毕。

2. 第二周（2026.06.01 - 2026.06.07）：前后端联调与交互呈现

• 目标：实现错题本复练在前端的答题渲染；前端可以完整解析流式响应并高亮引用标；完成论坛举报和管理系统的联动；优化移动端展示。
• 里程碑点：错题专项复练及 AI 解析链、知识问答引用溯源联调闭环。

3. 第三周（2026.06.08 - 2026.06.14）：全面回归测试、压力测试与 Beta 发布

• 目标：补齐单元测试，组织全组同学进行边界条件的黑盒测试，修复联调中的各类 Bug。
• 里程碑点：通过发布流水线平滑上线 Beta 版，输出 Beta 发布说明及项目计划总结报告。