[T.5] 团队项目：功能规格说明书
功能规格说明书
| 项目 | 内容 |
|---|---|
| 这个作业属于哪个课程 | 2026 年北航软件工程 |
| 这个作业的要求在哪里 | [T.6] 团队项目：技术规格说明书 |
| 我们在这个课程的目标是 | 完整参与一套成熟软件的开发过程，提升自己的工程能力和技术能力 |
| 这个作业在哪个具体方面帮助我实现目标 | 熟悉项目功能 |
1. 概念和术语
1.1 术语与缩写
| 词条 | 英文或缩写 | 含义 |
|---|---|---|
| 启元知微 | — | 本产品名称；课程场景下的智能学习 Web 产品。 |
| 访客 | Guest | 未登录用户；可浏览部分公开内容，受功能限制。 |
| 注册用户 / 学员 | User | 已创建账号并登录的终端用户。 |
| 知识问答 | Q&A with RAG | 用户围绕课程与知识库发起多轮提问，系统结合检索与生成返回答案；支持流式展示。 |
| 会话 | Conversation | 用户侧一次连续的问答主题线程，有列表、标题与删除等管理能力。 |
| 课程上下文 | Course Context | 用户当前选中的课程或资源范围，影响检索与展示标签，不等同于教务系统中的正式课表。 |
| 流式输出 | Streaming | 回答内容分块逐步呈现，用户无需等待整段生成完毕。 |
| 笔记生成 | Note Generation | 在检索与模型辅助下将材料整理为结构化 Markdown 等形式的笔记。 |
| 题库 | Question Bank | 与课程关联的试卷与题目资源；支持浏览、组卷、模拟考试等。 |
| 学习论坛 | Forum | 按课程分区的讨论区，含发帖、回帖、点赞、举报。 |
| 管理员 | Admin | 可管理用户、课程、文档等后台能力的一类账户；本说明书仅约定存在性与权限方向，细粒度以实现为准。 |
| JWT | JSON Web Token | 访问与刷新双令牌体系下的身份凭据。 |
| SSE | Server-Sent Events | 服务端向浏览器单向推送流式数据的技术。 |
| P0 / P1 / P2 | Priority | 需求优先级；P0 为 Alpha 前必须，P1 为 Beta 核心增强，P2 为提升项或课后续期。 |
| DAU | Daily Active Users | 统计日内至少一次有效使用产品的去重用户数。 |
1.2 特殊定义
以下术语在本文中具有特定工程与产品含义，与日常用语若有出入以本节为准：用户界面所选、用于限制检索与分区展示者为课程上下文；由 RAG 子系统管理、可与课程多对多映射的检索数据集为知识库；系统内对试卷的一次作答与记录、不等同于学校正式机考与成绩认定者，为模拟考试。
1.3 易混淆概念对照
| 概念 A | 概念 B | 区别 |
|---|---|---|
| 登录用户 | 访客 | 数据写入、个人会话、模考等能力仅对登录用户开放。 |
| 知识问答与笔记 | 学习论坛 | 前者是人与系统之间的问答与生成；后者是用户与用户之间的 UGC 讨论。 |
| 会话消息列表 | 论坛帖子 | 前者私密、可删、侧重复习对话；后者公开、可搜索、强调社区讨论。 |
| 题库题目 | 论坛中的题目讨论 | 前者为结构化卷面与选项；后者为自由文本，答案正确性不保证。 |
2. 产品描述
2.1 项目简述
启元知微面向高校工科类课程学习场景，将课程与文献沉淀为可检索的知识资源，在浏览器中提供知识问答、笔记整理、往年真题与模拟考、分课程学习论坛等能力。产品减轻学生在多源资料中检索与总结的负担，用可追踪的对话与社区讨论补充传统单向阅读；技术形态为 Web 应用，不替代正式教学评价与考试认定。
背景与意义：专业课程知识密集、资料分散，大语言模型与 RAG 的成熟使有据可查的答疑在成本可控时可行。产品把检索、生成、讨论与自测收拢到统一入口，服务预习、复习与备考周期中的高频任务。
3. 用户与应用场景
3.1 用户类型概览
| 类型 | 角色说明 | 估计潜在用户量与占比 | 使用习惯与吸引力 |
|---|---|---|---|
| 本科在读学生 | 修读计算机类课程，需理解概念与完成平时作业与备考 | 占潜在用户主体，约 70% | 周中晚间与课前后使用，频次中等偏高；流式问答、分课程检索、模考吸引力强。 |
| 研究生或进阶自学用户 | 同一课程体系的深化学习或补基础 | 约 20% | 周频次较高、单次时长长；深度问答与笔记、论坛精华帖吸引力强。 |
| 课程助教或志愿服务者 | 维护讨论区、反馈资料问题、非课官方答疑 | 约 10% | 不定期集中上线；论坛管理与举报闭环、内容可见性重要。 |
| 教务或教师 | 以课程为单元配置资源与空间 | 小样本 | 低频；课程与资料上架、权限是核心。 |
上表潜在总量为课程可触达人群的上界估算，不表示实际周活或已注册量；真实统计见 §9 数据定义。
期望与收益：在可控时间内得到可引用的要点整理与错题巩固路径；在论坛获得同学视角的解释与避坑信息。
代价与付出：课程作品阶段默认不收费；若后续增加增值服务，以团队商业决策另文规定，本说明书不锁定价格。非物质上，用户需投入时间维护会话与阅读论坛，对对话答案需自主核实；发帖与回复会留下公开记录，需具备基本网络礼仪与信息辨别。
3.2 用户画像详述一：本科在读学生赵志勇
- 身份：计算机相关专业高年级，住校。
- 潜在占比：在全体潜在用户中按 §3.1 粗估占多数。
- 使用习惯：晚自习与周末下午打开站点；以手机或笔记本浏览器完成；每周多次短问答与考前一周长会话与模考。
- 期望：用自然语言问清概念、对照课件与参考书，减少在多个 PDF 和聊天窗口间切换。
- 可接受代价：愿意花 10–20 分钟整理一次会话为复习提纲；不期望产品为课程作业直接生成可交稿的抄袭级全文。
3.3 用户画像详述二：研究生刘词怡
- 身份：补修或深化本科核心课。
- 使用习惯：实验室固定机位、浏览器常驻标签；偏好长对话与导出或复制笔记；论坛以浏览为主、发帖较少。
- 期望：快速定位易混概念对比与大题思路，减少重复问助教。
- 可接受代价：接受较高密度文本阅读；对答案是否标明引用来源较敏感。
3.4 用户画像详述三：志愿者助教王赫
- 身份：高年级学生，课程指定协助讨论区秩序。
- 使用习惯：每两至三天集中处理举报与重复问题引导。
- 期望：违规内容有入口与可追溯；若优质帖可标记或置顶，可减轻重复劳动。
- 可接受代价：非全职运营，流程须短，课程期内不落地复杂审核后台。
4. 典型应用场景
4.1 场景类型划分
- 场景 A 预习与随堂疑难点：单用户与系统，短时问答。
- 场景 B 期中大复习：单用户，长会话、笔记与题库。
- 场景 C 备考自测：单用户，浏览真题与模拟卷。
- 场景 D 互助讨论：多用户，论坛发帖回帖与轻互动。
- 场景 E 资源维护：少用户，上传资料与课程配置。
4.2 场景 A：周三晚预习操作系统「进程与线程」
袁子轩同学在宿舍用笔记本登录启元知微，在知识问答中新建会话，选择操作系统课程，输入「用户态和内核态切换开销主要来自哪里」。系统流式返回答案并引用检索片段。他追问「和上下文切换是同一回事吗」，对话续在同一会话内。学习结束前他删除几次试错提问留下的会话条目，以保持列表整洁。
- 涉及用户：登录学员。
- 服务方式：RAG+生成，会话持久化。
- 用户间关系：无。
- 好处与感受：节省翻书时间；答案可能不完整，须自行对照课件。
主流交互步骤：登录 → 进入知识问答 → 新建会话 → 选课程 → 输入问题 → 阅读流式回答 → 多轮追问 → 离开或返回列表。
4.3 场景 B：期中考前周日下午整理半学期数据库笔记
赵志勇同学打开知识问答中旧会话，通过笔记入口或约定指令，在选定「数据库系统」后提交「把前三章关于范式的易混点列成表」。系统返回 Markdown 结构内容，他复制到本地笔记软件。他打开学习论坛，只读他人关于「自然连接」的讨论帖。全程无多用户同时编辑同一文档的协同需求。
- 涉及用户：登录学员。
- 服务方式：生成与只读社区。
- 用户间关系：讨论内容对所有人可见，赵志勇未参与写帖。
- 好处与感受：输出结构化；须警惕模型杜撰术语对比，与教材核对。
主流交互步骤：登录 → 知识问答或笔记能力 → 选课程与输入需求 → 等待生成 → 复制或下载按实现支持 → 可选进入论坛关键词浏览。
4.4 场景 C：考前用题库做一套模拟卷
罗浩宇同学在题库入口选择课程与试卷，进入模考答题界面，客观题在页内即时反馈对错；交卷后查看记录与解析路径按实现。他与线下纸笔试卷无关联。
- 涉及用户：登录学员。
- 服务方式：读题库数据、记考试记录。
- 用户间关系：无直接互动；成绩与记录为私密。
- 好处与感受：时间盒练习；正式成绩以学校认定为准。
主流交互步骤：登录 → 题库 → 选课程与试卷或组卷方式 → 答题 → 交卷 → 查记录或解析。
4.5 场景 D：课程论坛发帖问实验环境报错
刘词怡同学在论坛对应课程下发帖，附 Markdown 与报错说明。李昊霖回帖指出一条配置项；刘词怡点赞并标记问题已解。王赫若发现重复帖，在回复中引导至已有帖；发现违规时点击举报并选择原因。
- 涉及用户：多名登录学员、助教。
- 服务方式：UGC 存储与展示、点赞与举报。
- 用户间关系：公开讨论，弱社交；课程内不强制做关注链。
- 好处与感受：同伴支持；信息质量参差，需自辨。
主流交互步骤：登录 → 论坛 → 选课程区 → 发帖或打开帖子 → 回复或点赞 → 可选举报。
4.6 场景 E：新章节讲义上传
正高级教授李昊宸在课程下上传本地上周发布的 PDF 或经授权的文本资料，由后端触发入库与索引，学员在后续问答中可检索到更新内容。本场景在课程与文档管理开关开放时存在。
- 涉及用户：具备权限的教师或维护账户。
- 服务方式：文件上传、异步建索引。
- 用户间关系：提供资源的一方与消费资源的一方。
- 好处与感受：材料集中；上传权限须严控，注意版权与涉密。
主流交互步骤：具备权限的账户按实现进入管理侧或课程页 → 选课程 → 上传 → 等处理完成 → 由学员侧验证检索是否命中。
5. 界面与原型
本阶段采用线框与页面结构描述；团队可用 Figma、墨刀、即时设计等补图，草图不阻塞本说明书定稿。下列布局与当前前端工程路由可对照校核：首页、知识问答 qa、学习论坛 forum、题库 bank、登录与注册、个人相关页。
| 区域 | 布局要点 |
|---|---|
| 全局 | 顶栏为品牌、主导航、登录态；子工作区左侧可侧栏列表，主区为内容。 |
| 知识问答 | 主区上下结构：上为消息区，用户与助手左右分栏；下为输入区、课程选择、发送与可选附件。历史会话在可折叠侧栏列出，支持新建与删除单条。 |
| 论坛列表 | 顶区课程筛选与排序；下方卡片列表，展示标题、作者、回复数、最后活跃时间。 |
| 帖子详情 | 上为标题与正文，下为回复列表与回帖框；作者可编辑与删除本人内容。 |
| 题库与模考 | 子导航区分资料浏览、模拟考试、历史记录；答题页题号与选项区清晰分区；交卷有确认。 |
| 注册登录 | 独立页或弹窗由实现选择；字段与校验与 §6 一致。 |
原型产出的最低要求：每个 P0 模块至少一屏线框或书面标注截图，在仓库 docs 或设计目录存档并在评审会上走查。
6. 产品功能、验收与阶段安排
功能分为基础与增量；基础对应 Alpha 可演示闭环，增量按 Beta 与后续迭代收束。
6.1 总表
| 功能域 | 基础 / 增量 | 对应场景 | Alpha / Beta 建议 | 主要依赖与副作用 |
|---|---|---|---|---|
| 用户注册、登录、刷新、登出 | 基础 | 全部 | Alpha | 邮件与 SMTP；验证码频控。 |
| 个人资料与头像 | 增量 | A–E | Beta | 对象存储与大小限制；头像与版权由用户责任条款约定。 |
| 知识问答：多轮、课程上下文、流式、历史、删除 | 基础 | A、B | Alpha | RAG 与 LLM 可用性；界面须提示模型可能幻觉。 |
| 笔记生成 | 增量 | B | Beta | 与问答共享后端能力；长文本导出对浏览器内存有影响。 |
| 题库：浏览、试卷、模拟考、历史 | 基础浏览、增量模考 | C | Alpha 浏览；Beta 模考闭环 | 题库数据质量与版权；文案须与正式考试脱钩。 |
| 学习论坛：浏览、发帖、回帖、点赞、举报、编辑、删帖 | 增量 | D | Beta | UGC 合规；引战、抄袭、广告等需治理策略。 |
| 课程与文档上传、索引 | 增量 | E | Beta 及以后 | 权限与版权；可分阶段实现。 |
| 管理端用户与课程 | 增量 | E | 课后续期或最小管理员 | 越权风险高，须配合审计日志方向。 |
6.2 验收标准
Alpha 可演示标准
- 新用户可完成注册与登录并在刷新页面后保持登录态。
- 知识问答中可新建会话、选择课程、发送问题、看到流式回答、查看历史、删除单条会话。
- 题库至少可按课程浏览试卷与题目结构，只读展示，无致命空白页。
- 全路径无未处理的前端白屏与明显交互死锁；失败有可理解中文提示。
- 在小组评审设备上，使用本说明书 §7 列出的主浏览器之一完整走通上述路径一次。
Beta 可接受标准
- 在 Alpha 标准之上，模拟考试可完成一次完整交卷与记录回看；论坛在真数据上可发帖、回帖、点赞、举报、编辑与删除本人内容。
- 笔记在至少一种交互入口下成功生成，并可复制或下载至少一种。
- 与 RAG 或模型服务短暂不可用时，有降级或重试提示，不静默失败。
增量功能完成判据：具备与 §4 场景对应的最少操作步骤可跑通，并在 PR 或迭代记录中附截图或录屏。
6.3 单功能简表
| 功能 | 行为概要 | 验收要点 |
|---|---|---|
| 注册 | 邮箱、密码、验证码流程 | 重复邮箱、错误验证码、弱密码均被拦截。 |
| 登录 | 邮箱+密码、令牌刷新 | 错误密码、未注册邮箱提示明确。 |
| 知识问答 | 多轮、流式、会话管理 | 空发送拦截；超时有提示；来源引用在 UI 展示时须可读或可点。 |
| 题库浏览 | 课程→试卷→题目结构 | 无数据时空态说明。 |
| 模考 | 答题、交卷、记录 | 刷新或断网后状态行为符合设计。 |
| 论坛 | 发帖、回、赞、报 | 长文、空内容、越权操作均有对应反馈。 |
7. 能力边界
7.1 用户与并发
- 注册用户总量：课程作品阶段不承诺具体上限；达到部署或数据库容量告警时，以只读或拒绝新注册为预案，须在运维侧提前定义，本功能规格仅要求对用户提示维护中。
- 同一用户短时间内高频率调问答接口时，限流与稍后再试提示由服务策略决定，不应以沉默失败为唯一表现。
- 业务高峰以考试周、发布日前夜为典型；高峰下不保证每次问答首字延迟在固定秒内，须保证失败可感知、可重试。
7.2 输入与输出内容
- 单条用户提问长度、单帖正文长度、附件大小有上界；上界在界面与接口上成对出现；越界拒绝提交并提示。
- 空输入、全空白不得触发付费级模型调用。
- 多模态若仅部分实现，不支持的类型在选择器或上传处禁用并说明。
7.3 浏览器与入口
- 主支持：当前代 Chrome、Edge、Firefox、Safari 的最近两个大版本；以《技术规格说明书》中的 CI 与人工矩阵为准。
- 不支持的旧版浏览器应看到可读的升级提示页或顶栏，不以布局崩坏且无声为唯一表现。
- 入口：本课程交付形态为 Web，无须区分 App 与 Web 能力差异；移动浏览器不单独优化布局时，以可用为底线，可在页脚声明建议桌面访问。
7.4 能力上限声明
- 问答不保证与教材或教师表述字句一致；不作为任何正式评分依据。
- 论坛无实名校验即不承诺身份真实性。
- 题库与真题若来自往年公开整理，版权与准确性以数据源与课程约定为准。
8. 产品目标
本学期课程内可检验的产品目标如下，数字为目标值，统计口径须一致且防刷；若暂不具备埋点，以手动日志与演示数据在答辩材料中披露方法与局限。
| 目标项 | 说明 | 建议目标值与可信度 |
|---|---|---|
| 真实注册用户 | 以校园邮箱、邀请码或学号验证过的账户计为「高可信」；其他为「低可信」分别统计。 | 目标：高可信不少于 30 人，或全量注册不少于 50 人，满足其一可答辩；来源表须可追溯。 |
| DAU | 日去重登录或一次有效操作，定义在埋点或日志规范中写死一条。 | 目标：课程最后两周平均 DAU ≥ 8，或说明样本不足原因。 |
| 内容资产 | 论坛帖子数+回复数、题库可用试卷数、知识库文档篇数。 | 目标：每类有非零贡献；至少 20 条有效 UGC 或等价资料条目。 |
| 移动应用与公开包 | 本课程不要求上应用商店、不要求发 npm 包。 | 目标：可写明不纳入。 |
9. 产品发布、数据收集与分析
9.1 非预期与风险
| 状况 | 风险 | 应对 |
|---|---|---|
| 大模型事实错误 | 用户误信、学业受损 | 界面免责声明；引用展示；教师不对模型输出背书 |
| 论坛引战、抄袭、广告 | 舆情与责任 | 举报、删帖、频控、必要时关发帖只读模式 |
| API 被滥用 | 成本与可用性 | 登录后限流、验证码、异常告警 |
| 资料涉密或侵权 | 法律与校纪 | 上传授权与仅教学声明、下撤流程 |
| 大考周服务拥堵 | 体验崩塌 | 排队提示、非核心能力降级、只读 |
9.2 应收集与可选收集数据
| 数据 | 目的 | 必收 / 选收 |
|---|---|---|
| 注册时间、课程角色、是否验证邮箱 | 用户结构与留存 | 必收最小集 |
| 每日登录与关键事件 | DAU 与功能渗透 | 必收，口径见 §8 |
| 单会话轮数、失败与超时次数 | 质量与排障 | 选收，日志中不全文明文用户正文 |
| 论坛举报与处理结果 | 社区健康 | 管理流程存在时必收 |
与目标的关系：DAU、注册数、内容量直接对应 §8；失败率用于解释未达留存时原因。
9.3 数据准备工作
- 事件命名与去重规则文档一页。
- 若无分析平台，CSV 导出脱敏周志也可用于课程答辩。
- 隐私：不向第三方出售；团内最小权限看板。
9.4 与功能副作用的再归纳
- 强生成会削弱手抄记忆；应对为鼓励对照教材的提示与自测结合。
- 论坛可能替代当面问；课堂规则由课程教师定，产品不替代考勤与互动。
- 刷题可能只背选项；应对为在资料允许下补充解析与变式。
10. 设计带来的问题与合预期与不对等情况
| 问题或副作用 | 应对 |
|---|---|
| 学生依赖答案不思考 | 产品文案与课堂引导；不对「代做作业」做一键优化作为卖点。 |
| 资源投入不均导致某课程论坛空 | 种子帖与助教首周发帖；不作虚假数据。 |
| 多版本资料检索冲突 | 展示时间与课程；后续可加版本元数据。 |
不合预期状况：模型突然全拒答、论坛被刷屏、模考判分与标准答案不一致；预案为公告、回滚、只读、人工勘误入口，按优先级由 PM 在事故单中指派。
浙公网安备 33010602011771号