软件工程实践团队作业第二次——原型设计 & 需求分析（DevPulse 智能问答助手）

本博客为 2601_FZU_SE 软件工程实践团队作业第二次提交。内容包括团队项目整体计划与里程碑、关键点难点与风险分析、组员分工与工作量比例、成员协作方式，以及《需求规格说明书》、界面原型设计、需求分析 PPT、界面原型设计答辩 PPT 的链接。

项目	内容
这个作业属于哪个课程	2601_FZU_SE 软件工程实践社区
这个作业要求在哪里	软件工程实践团队作业第二次——原型设计&需求分析
团队名称	DevPulse
这个作业的目标	完成团队项目的需求分析与界面原型设计，产出符合国标规范的《需求规格说明书》、可交互界面原型与两份答辩 PPT，并通过博客记录项目计划、难点风险与团队协作过程
其他参考文献	[1] GB/T 9385-2008《计算机软件需求规格说明规范》 [2] 邹欣.《构建之法》[M]. 人民邮电出版社 [3] Lewis P, et al. Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks. NeurIPS 2020 [4] LangChain 官方文档 [5] Milvus 官方文档

目录

---

一、团队项目计划

1.1 项目概述

项目名称： DevPulse 智能问答助手

一句话描述： 把团队文档、课程资料和常见问题整理成可检索、可追溯、可反馈的知识库，通过检索增强生成（Retrieval-Augmented Generation，RAG）技术提供可信回答的 Web 应用。

目标用户： 课程班级、学生团队、社团、实验室小组和小型项目组。

核心链路： 上传资料 → 混合检索 → 重排序 → 模型生成 → 带引用回答 → 用户反馈。这条链路是项目的验收底线，任何阶段都不能让它中断。

1.2 项目整体计划与阶段划分

项目自组队确定选题后分为四个阶段推进，每个阶段必须留下可演示、可评审的成果。

阶段	时间安排	主要任务	阶段成果与验收方式
第一阶段	9 月下旬	团队组建、选题论证、NABCD 分析、团队绩效考核方案	选题说明文档与选题答辩 PPT，已通过课堂选题答辩
第二阶段	10 月上旬	需求分析、界面原型设计、类图与数据建模、接口约定	本博客对应的四份交付物，可评审、可演示
第三阶段	10 月下旬至 11 月	文档解析与入库、向量化、混合检索、单轮问答与引用展示	上传资料后可以被检索到，提问能得到带来源的答案
第四阶段	11 月至期末	多轮对话、用户反馈、权限管理、测试、部署与演示准备	可访问、可复现、可讲解的完整成品

flowchart LR
    A["阶段一：选题与团队建设<br/>9 月下旬 · 已完成"] --> B["阶段二：需求分析与原型设计<br/>10 月上旬 · 本次作业"]
    B --> C["阶段三：知识入库与检索问答<br/>10 月下旬至 11 月"]
    C --> D["阶段四：反馈闭环与测试部署<br/>11 月至期末"]

1.3 本次作业的里程碑安排

本次作业周期为 10 月 9 日至 10 月 15 日，10 月 16 日课堂答辩，因此采用倒排方式安排里程碑，每个里程碑都有明确的日期与可交付成果。

里程碑	截止时间	交付成果	负责人
M0 计划冻结	10-09 24:00	术语表初稿、页面清单（P01 至 P10）、任务看板卡片	全体成员
M1 需求冻结	10-10 24:00	4 个用户场景与用例、信息架构图、类图初稿	郑宇凌、郑栋兴
M2 原型 v1	10-11 24:00	P01 至 P10 全部页面的可点击原型、类图定稿	陈仕杰、张幼
M3 首稿完成	10-12 24:00	《需求规格说明书》初稿、需求分析 PPT 初稿	郑宇凌、郑栋兴
M4 全部定稿	10-13 24:00	说明书定稿、界面原型设计答辩 PPT 完稿	全体成员
M5 博客发布	10-14 20:00	本博客发布，四份交付物上传华为云仓库并取回链接	郑天一
M6 提交完成	10-15 20:00	按检查清单交叉核对并提交作业页面	全体成员
M7 课堂答辩	10-16	需求分析 PPT 与界面原型设计答辩 PPT 各彩排一次并现场讲述	全体成员

关键路径： 术语表 → 类图 → 说明书第 3 章；页面清单 → 界面原型 → 说明书第 4 章；场景与用例 → 功能需求编号 → 验收标准；说明书与原型 → 两份答辩 PPT → 博客。四组前置关系不能颠倒，其中类图是三条支线共同的上游，因此被安排在 M1 阶段优先完成。

每日节奏： 每晚 21:00 进行一次 15 分钟站会，每人只回答三个问题——昨天完成了什么、今天计划做什么、当前有什么阻塞。

---

二、项目关键点、难点与风险分析

2.1 三个关键点

关键点一：需求粒度必须可验收。

需求分析最常见的失败方式是写出一份"功能愿望清单"——读起来很完整，但无法判断做没做完。我们的对策是让每条功能需求都携带编号、描述、输入、输出、异常流程、优先级和来源场景，并在附录中提供需求追溯矩阵，把"用户场景 → 功能需求 → 原型页面 → 验收用例"串成一条可回溯的链路。这样助教抽查任意一条需求，都能在三分钟内定位到它的来源和验收方式。

关键点二：界面原型必须能倒推回需求。

原型设计容易变成"凭审美画画"，最后与需求文档脱节。我们在界面原型设计答辩 PPT 中专门保留一页，展示每个页面与需求编号的对应关系，用可核查的映射证明界面是为需求服务的。

关键点三：RAG 类产品的需求必须用指标表达。

"回答要准确""系统要快"这类描述无法验收。我们把它们翻译成五个可测量指标：检索命中率、引用准确率、回答一致性、响应时间、反馈闭环率，并把每个指标的定义、测量方式和目标值写进《需求规格说明书》的非功能需求章节。

2.2 四个难点与应对思路

难点	为什么难	我们的应对
类图与需求难以保持一致	类图很容易画成技术架构图，出现消息队列、缓存等与业务需求无关的类，导致与需求对不上	先冻结术语表与实体清单，类图只画业务实体及其关系；画完后再逐条回读功能需求做交叉检查，删掉无需求支撑的类
用户场景容易写成空话	缺少真实用户输入，写出来的场景往往是团队自己的想象	以本班同学、课程助教和小组自身为样本做 5 至 8 人小范围访谈，把真实提问原话整理进场景描述，并在文档中标注场景来源
界面原型范围容易膨胀	10 个页面乘以 4 种状态等于 40 个画板，按课程周期根本画不完	分级投入：主链路 5 个页面做高保真，管理类页面做中保真，状态设计只在核心问答页完整展开
周期紧且有两轮答辩	10 月 15 日交作业，10 月 16 日就要课堂答辩，几乎没有缓冲	原型与 PPT 并行推进；说明书 10 月 13 日定稿，博客 10 月 14 日必须发布；四份交付物各设一名备份负责人

2.3 风险分析与应对措施

风险	影响程度	应对措施
博客审核延迟，帖子显示 404	高	10 月 14 日提前发布；若发布后仍显示 404，先在班级作业页面提交链接，等待审核通过，避免被判定为伪造提交
华为云仓库链接权限设置错误	高	每份文件上传后用无痕窗口逐个验证链接可访问，确认无误后再写入博客
Word 文档排版样式不统一	中	指定唯一排版负责人，先确定样式模板再合并各章内容，图表统一编号
说明书、PPT、博客三处口径不一致	中	抽出"术语表 + 需求编号表 + 指标定义"三份单一事实来源，三处均引用同一份，避免同义不同表述
临近期末成员投入度下降	中	任务看板每张卡片都有负责人与截止时间，关键模块设置备份负责人；阻塞超过 24 小时即升级为全组讨论
方案被质疑为通用聊天机器人套壳	中	在需求文档中把"来源引用、无依据时拒答、反馈闭环、知识缺口分析"写成显式需求项，答辩时直接用需求编号回应质疑
模型或检索组件不可用	低	需求文档中明确模型通过兼容接口调用、向量库可替换，避免技术选型绑死单一厂商

---

三、项目分工

3.1 组员分工与工作量比例

本次作业的分工按"交付物主责制"划分，每份交付物有且只有一名主责人、一名协作人，避免出现多人同时改一份文件导致版本混乱。

学号	工作内容	贡献度
102400135 郑宇凌	需求规格说明书主笔（引言、总体描述、具体要求）；类图建模与关系说明；数据需求与接口需求编写	23%
102400210 陈仕杰	界面原型设计主责（信息架构、P01 至 P10 页面、可交互原型制作）；界面原型设计答辩 PPT	23%
102400335 郑栋兴	需求规格说明书协作（用户场景、功能描述、验收验证标准）；需求分析报告 PPT	18%
102400334 张幼	界面原型协作（视觉规范、关键页面细化、四种状态设计）；需求规格说明书排版与图表统一	18%
152402114 郑天一	博客撰写与发布；界面原型设计评审表与需求分析评审表；术语表维护与需求追溯矩阵核对	18%

3.2 工作量比例的计算依据

工作量比例不是平均分配，也不是主观拍板，而是按"主责交付物的分值权重 × 实际投入工时"综合确定，并与任务看板卡片、Git 提交记录一一对应，做到可追溯、可申诉。

交付物	主要工作投入	主责人	协作人
需求规格说明书	章节撰写、类图建模、关系说明、排版与图表统一	郑宇凌	郑栋兴、张幼
界面原型设计	信息架构、页面绘制、交互与状态设计、设计规范	陈仕杰	张幼
团队项目计划、难点风险、分工与协作描述	素材整理、统稿、博客排版与发布	郑天一	全员提供素材
需求分析报告 PPT	大纲设计、页面制作、讲稿撰写与现场讲述	郑栋兴	郑宇凌
界面原型设计答辩 PPT	大纲设计、原型走查编排、讲稿撰写与现场讲述	陈仕杰	张幼
两份评审表	模板调整、腾讯共享文档维护、排名汇总	郑天一	全员

本次作业的评分重心集中在《需求规格说明书》（本博客对应章节合计 44 分，含国标规范）与博客本身（合计 36 分，含团队协作描述），界面原型同时服务于说明书第 4 章与界面原型设计答辩 PPT，两份答辩 PPT 合计 20 分。结合分值权重与实际投入工时，最终形成上表中 24%、22%、20%、18%、16% 的贡献度比例。若后续出现成员临时请假或任务调整，比例会在阶段复盘时同步修订，并保留修订记录。

3.3 每位成员的具体工作内容

郑宇凌（102400135）

1. 编写《需求规格说明书》第 1 章引言，含编写目的、项目背景、术语与缩写定义、参考资料。
2. 编写第 2 章总体描述，含产品目标、用户特征、运行环境与约束、假设与依赖、非目标。
3. 主导第 3 章具体要求中的类图设计，使用 PlantUML 编写类图源码，并在正文中逐条解释类之间的关联关系与多重性。
4. 编写数据需求与非功能需求（可用性、安全性、性能、可维护性）。
5. 参与两次内部评审，负责核对术语一致性。

陈仕杰（102400210）

1. 设计界面原型的信息架构与导航结构，输出页面地图。
2. 使用 Figma 完成 P01 至 P10 共 10 个页面的中高保真原型，主链路 5 个页面做高保真。
3. 负责核心问答页 P05 与引用溯源页 P06 的交互细节，包括流式输出、引用卡片、抽屉展开等。
4. 制作界面原型设计答辩 PPT，并配合完成课堂讲述。
5. 输出可交互原型链接，供其他成员与助教直接点击体验。

郑栋兴（102400335）

1. 负责用户调研，访谈 5 至 8 位同学与助教，整理用户画像与 4 个典型场景。
2. 编写《需求规格说明书》第 2.3 节用户场景与用例描述表。
3. 编写第 5 章功能描述及验收验证标准，含输入输出格式、界面验收标准与功能验收标准。
4. 制作需求分析报告 PPT，负责现场讲述中的需求与类图部分。

张幼（102400334）

1. 制定界面设计规范，包括主色、辅助色、字号阶梯、间距与常用组件样式。
2. 负责知识库管理类页面与四种状态（空态、加载态、错误态、无权限态）的视觉设计。
3. 负责《需求规格说明书》的最终排版：统一标题样式、正文宋体小四、1.5 倍行距、图表编号与页眉页脚。
4. 负责全部图表在文档中的统一呈现，确保字体与线宽风格一致。

郑天一（152402114）

1. 撰写并发布本博客，负责把各章节素材统稿为统一口径。
2. 制作界面原型设计评审表与需求分析评审表，并维护腾讯共享文档的权限。
3. 从测试视角核对验收验证标准的可判定性，指出不可量化的条目并要求修订。
4. 维护术语表，核对需求追溯矩阵中场景、需求、原型页面、验收用例四者的对应关系。

---

四、成员协作方式

4.1 沟通工具与沟通节奏

场景	工具	约定
日常异步沟通、问题求助	微信群	工作时间内 12 小时内响应，紧急事项直接在群里 @ 对应负责人
周例会、交付前站会	腾讯会议	每周一次 30 分钟例会，每个里程碑前增加一次 15 分钟站会
文档协作与评审	腾讯共享文档	评审表、会议记录共用，链接统一放在群公告
原型协作	Figma 团队项目	按页面编号划分画板责任人，跨页面改动先在群里同步
代码与文档托管	华为云仓库 / Git	仓库为唯一事实来源，本地文件不作为交付依据

会议记录要求：每次会议结束后 30 分钟内产出记录，包含结论、待办事项、负责人、截止时间四要素，发布到群并归档到仓库 docs/meetings/ 目录，文件名使用 YYYY-MM-DD-主题.md 格式。

4.2 版本仓库协作

分支模型。 主分支 main 只保留可交付版本，任何中间状态不允许直接提交到 main。每位成员从 main 拉取 feat/模块名 分支开展自己的工作，完成后提交 Pull Request 申请合并。

目录约定。

devpulse/
├── docs/            # 需求规格说明书、会议记录、决策记录
│   ├── meetings/
│   └── decisions/
├── diagrams/        # 类图、流程图等 PlantUML / Mermaid 源码与导出图
├── prototype/       # 原型导出文件与截图
├── slides/          # 两份答辩 PPT 及导出的 PDF
└── README.md        # 项目说明与交付物索引

提交信息规范。 统一采用「类型: 内容」格式，便于按提交追溯每个人的工作量。常用类型包括 docs（文档）、design（设计）、slides（演示材料）、fix（修正）。

docs: 完成需求规格说明书第3章类图与关系说明
design: 完成原型 P05 智能问答页与引用卡片交互
slides: 完成界面原型设计答辩PPT初稿
fix: 修正验收标准中不可量化的响应时间描述

合并前检查。 每次 Pull Request 必须由一名非作者的成员 Review 后才能合并，避免自审自合。Review 重点看三件事：内容是否与术语表口径一致、是否引入未定义缩写、是否与已有章节重复或冲突。

4.3 冲突处理

文档冲突。 《需求规格说明书》按章节拆分为多个文件，每人只修改自己负责的章节，最后由排版负责人统一合并为 Word 成稿。如果两人需要修改同一章节，先在群里说明修改范围再动手。

原型冲突。 Figma 画板按页面编号划分责任人，每人只改自己负责的画板。若某次改动会影响其他页面（例如统一修改主色），先改设计规范文件，再由各责任人同步到自己的画板。

需求分歧。 当成员对某个需求是否该做、该怎么做产生分歧时，处理顺序是：先回到用户场景和验收标准寻找判断依据；如果仍然无法一致，由该交付物的主责人拍板，并把决策原因记录到 docs/decisions/ 目录，格式为"背景、可选方案、最终决定、理由"，供后续复盘和答辩使用。

进度冲突。 如果某位成员的任务阻塞影响到下游（例如类图未定稿导致说明书无法推进），阻塞超过 24 小时即升级为全组讨论，由备份负责人接手或调整任务优先级。

4.4 任务同步机制

任务看板。 使用看板工具按"待办 / 进行中 / 待评审 / 已完成"四列管理任务。每张卡片必须包含任务描述、负责人、截止时间、验收标准四项信息，缺少任意一项的卡片不允许进入"进行中"。

每日站会。 每晚 21:00 用 15 分钟回答三个问题：昨天完成了什么、今天计划做什么、当前有什么阻塞。站会不做技术讨论，具体问题会后单独拉群解决。

周期同步。 每周日更新一次进度表与风险表，把看板数据直接写进博客的里程碑进度小节，做到博客中描述的进度有据可查，而不是事后补写。

交付前核对。 每个里程碑到达时，由非主责人按检查清单逐条核对，核对结果记录在看板卡片评论中。

4.5 贡献度如何做到可追溯

博客中给出的工作量比例来源于三类客观记录：任务看板卡片的完成情况、Git 提交与 Pull Request 记录、成员互评结果。三者出现不一致时，以任务看板与 Git 记录为准，成员可在结果公布后 24 小时内提出异议，由团队共同复核。这一规则在选题阶段的团队绩效考核方案中已经公开，本次作业只是把它落到具体记录上。

---

五、软件需求规格说明书

《需求规格说明书》链接：

5.1 文档结构

文档参考 GB/T 9385-2008《计算机软件需求规格说明规范》组织，在国标规定目录的基础上补充了"术语与缩写"和"非目标"两节：前者用于满足国标对缩写必须先定义的要求，后者用于明确需求边界，避免范围蔓延。

章节	内容
1 引言	编写目的、项目背景、术语与缩写、参考资料
2 总体描述	产品目标、用户特征、用户场景、运行环境与约束、假设与依赖、非目标
3 具体要求	类图、数据需求、接口需求、非功能需求
4 界面原型	信息架构与导航、页面清单、关键交互流程、界面设计规范
5 功能描述及验收验证标准	具体功能描述、输入输出格式、界面验收标准、功能验收标准
附录 A	需求追溯矩阵
附录 B	原型页面索引

5.2 用户场景

我们对 5 位同学和 1 位课程助教进行了小范围访谈，整理出 4 个典型场景。每个场景都记录"谁、在什么情况下、想做什么、当前痛点、期望结果"，并向下对应到具体功能需求编号。

编号	角色	触发情境	用户目标	当前痛点	期望结果	对应需求
SC-01	新加入的组员	第一次拿到仓库地址，准备本地运行项目	知道项目怎么在本地启动	部署说明散在聊天记录和三份不同文档里，翻半小时还没找到完整步骤	一次提问得到部署步骤，并可点击溯源到原始文档	FR-03、FR-04
SC-02	项目开发成员	修改某个接口时发现设计不符合直觉	了解这个接口为什么这样设计	当初的决策只存在于会议聊天里，当事人已经记不清	检索到历史决策记录，看到原文片段和日期	FR-02、FR-04
SC-03	课程助教	有学生重复询问作业提交格式	快速给出准确答复	需要在一份长文档里手动查找，每次都要重新读一遍	直接得到带原文引用的答案，并可直接转发给学生	FR-03、FR-04
SC-04	知识库管理员	发现近一周同类问题被问了六次	知道知识库里缺了什么	缺少汇总机制，只能凭印象判断	看到高频未命中问题清单，并能跳转补充对应文档	FR-05、FR-06

5.3 类图

类图只描述业务实体及其关系，不包含缓存、消息队列等技术组件。图中每个类的属性与关系在文档第 3.1 节均有文字说明，这里给出简化版。

classDiagram
    class User {
        +Long userId
        +String account
        +String passwordHash
        +String role
        +String status
    }
    class KnowledgeBase {
        +Long kbId
        +String name
        +String description
        +String visibility
        +Long ownerId
    }
    class KbMember {
        +Long kbId
        +Long userId
        +String permission
    }
    class Document {
        +Long docId
        +Long kbId
        +String fileName
        +String fileType
        +Long fileSize
        +String fileHash
        +String parseStatus
        +Long uploaderId
        +DateTime uploadTime
    }
    class DocumentVersion {
        +Long versionId
        +Long docId
        +Int versionNo
        +DateTime updateTime
        +String changeNote
    }
    class Chunk {
        +Long chunkId
        +Long docId
        +Int seqNo
        +String content
        +Int pageNo
        +Int tokenCount
        +String vectorId
    }
    class Conversation {
        +Long convId
        +Long kbId
        +Long userId
        +String title
        +DateTime createTime
    }
    class Message {
        +Long msgId
        +Long convId
        +String role
        +String content
        +DateTime createTime
    }
    class Citation {
        +Long citationId
        +Long msgId
        +Long chunkId
        +Double score
        +Int rankNo
    }
    class Feedback {
        +Long feedbackId
        +Long msgId
        +Long userId
        +String type
        +String reason
        +DateTime createTime
    }

    User "1" --> "0..*" KnowledgeBase : 创建
    User "0..*" -- "0..*" KnowledgeBase : 成员授权
    KnowledgeBase "1" --> "0..*" Document : 包含
    Document "1" --> "0..*" DocumentVersion : 拥有版本
    Document "1" --> "0..*" Chunk : 切分为
    KnowledgeBase "1" --> "0..*" Conversation : 承载会话
    Conversation "1" --> "0..*" Message : 包含消息
    Message "1" --> "0..*" Citation : 引用多个片段
    Chunk "1" --> "0..*" Citation : 被多处引用
    Message "1" --> "0..*" Feedback : 获得反馈

关系说明摘录：一个用户可以创建多个知识库，同时可以通过成员授权访问他人创建的知识库，因此用户与知识库之间既有"创建"的 1 对多关系，也有"成员授权"的多对多关系；一份文档被切分为多个文本片段，一个片段又可能被多条回答反复引用，因此消息与片段之间通过引用实体构成多对多关系，引用实体上额外记录相似度与排序，用于前端按相关度展示。

5.4 功能描述与验收验证标准

每条功能需求使用统一模板记录，示例如下：

FR-03 智能问答
  描述：用户用自然语言提问，系统返回基于知识库的答案及引用来源。
  输入：知识库 ID、用户问题文本、会话上下文
  处理：混合检索 → 重排序 → 提示词组装 → 模型生成
  输出：答案文本、引用片段列表（含文档名、页码、相似度）
  异常：检索为空时提示知识库中没有相关内容，并记录未命中问题
  优先级：高
  来源场景：SC-01、SC-02、SC-03

验收验证标准部分分为功能与非功能两类，全部写成可执行、可判定的形式：

需求编号	验收项	前置条件	操作步骤	预期结果	判定方式
FR-01	文档上传	已登录且拥有知识库权限	上传一份 PDF 文档	文档出现在列表中，状态由"解析中"变为"已入库"	功能测试
FR-03	带引用问答	知识库中已有相关文档	输入一个业务问题	返回答案，答案下方引用卡片可点击并定位原文片段	功能测试
FR-03	无依据时拒答	知识库中无相关内容	输入超出知识范围的问题	明确提示知识库中没有相关内容，不编造答案	功能测试
FR-05	反馈记录	已产生至少一条回答	对回答点击"无用"并填写原因	反馈入库，管理员端可见该条低分记录	功能测试
NFR-01	响应时间	知识库含 50 篇文档	连续提问 10 次并记录耗时	百分之九十五的请求端到端响应不超过 8 秒	性能测试
NFR-02	权限隔离	用户 A 无知识库 B 的访问权限	直接用链接访问知识库 B	返回无权限提示，不泄露任何文档内容	安全测试
NFR-03	引用准确率	固定测试集 30 道题	人工核对引用片段是否支持结论	引用支持结论的比例不低于 90%	抽查评审

5.5 需求分析过程中的设计思路、问题与解决方式

设计思路。 我们没有直接从"要做哪些页面"出发，而是先回答"谁在什么情况下遇到什么困难"，再逐步收敛为功能需求，最后才落到界面原型。整个推导链条是：用户调研 → 用户画像与场景 → 功能需求编号 → 类图与数据模型 → 界面原型 → 验收标准。这样能保证每一张原型页面都能追溯到一条具体需求，而不是为了凑页面数量而画。

问题一：需求描述过于模糊，无法验收。 初稿中出现了"系统要快速响应""答案要准确"这类表述。解决办法是把主观描述逐一翻译成可测量指标，例如把"准确"拆成检索命中率和引用准确率，并明确测量方法为固定问题集的前 5 条结果命中比例。

问题二：类图混入了技术组件。 初稿类图里出现了缓存、向量库、调度器等与业务实体无关的类，导致类图更像架构图，与需求对应不上。解决办法是先冻结术语表与业务实体清单，明确类图只描述业务实体及其关系，技术组件改由接口需求章节描述。

问题三：用户场景缺乏真实依据。 第一版场景是团队内部讨论写出来的，读起来合理但无法验证。解决办法是补做小范围访谈，把真实提问的原话整理进场景描述，并在文档中标注场景来源，同时删除没有访谈支撑的臆测场景。

问题四：文档章节之间口径不一致。 不同成员负责不同章节，出现了同一概念多种叫法的情况，例如"片段"与"块"、"知识库"与"文档库"混用。解决办法是建立术语表作为单一事实来源，所有章节在写作前先查术语表，合并时由排版负责人统一核查一次。

---

六、界面原型设计

界面原型设计链接： https://gitee.com/chen-shijie00/devpulse-prototype

原型共 10 个页面与 4 种状态。用浏览器打开即可浏览，无需登录：仓库首页按页面顺序展示全部截图，并附页面清单、界面设计规范与团队分工。

6.1 设计目标与设计原则

界面原型要回答一个问题：一个完全没参与过这个项目的人，能不能在不看说明书的情况下完成"上传资料到拿到带引用答案"的全过程。围绕这个目标，我们确定了四条设计原则。

1. 主链路优先。 问答主链路的页面做高保真，管理类页面做中保真，把有限时间投到用户最高频的路径上。
2. 引用可见。 答案下方必须直接展示引用来源，不允许把出处藏在二级页面里。
3. 状态完整。 每个核心页面都设计空态、加载态、错误态和无权限态，避免出现"界面白屏但没有提示"的情况。
4. 交互一致。 全站统一按钮、输入框、卡片、提示的样式与位置，降低学习成本。

6.2 信息架构

flowchart TD
    Login["登录 / 注册"] --> KBList["知识库列表"]
    KBList --> KBDetail["知识库详情与文档管理"]
    KBDetail --> Upload["文档上传与解析"]
    KBList --> Chat["智能问答（核心）"]
    Chat --> Citation["引用溯源抽屉"]
    Chat --> Feedback["反馈评价"]
    KBList --> Gap["知识缺口分析"]
    KBList --> Member["成员与权限管理"]
    KBList --> Profile["个人中心 / 设置"]

6.3 页面清单

编号	页面名称	保真度	关键要素
P01	登录 / 注册	中保真	账号密码输入、表单校验提示、注册入口
P02	知识库列表	中保真	知识库卡片、搜索、新建知识库、可见范围标签
P03	知识库详情 / 文档管理	中保真	文档表格（文件名、类型、大小、状态、上传人、上传时间）、上传与删除操作
P04	文档上传与解析	中保真	拖拽上传区、解析进度、失败原因与重试按钮
P05	智能问答（核心页）	高保真	左侧会话列表、中间对话区、答案下方引用卡片、输入框、停止生成按钮
P06	引用溯源抽屉	高保真	原文片段、所属文档名、页码、相似度、跳转原文入口
P07	反馈评价	中保真	有用 / 无用按钮、原因选项、补充说明输入框
P08	知识缺口分析	中保真	高频未命中问题列表、低分回答列表、补充资料入口
P09	成员与权限管理	中保真	成员列表、角色设置、移除成员、邀请入口
P10	个人中心 / 设置	中保真	模型偏好设置、会话历史、账号注销

6.4 关键交互流程

主链路一：从零开始建立可用的知识库。

flowchart LR
    S1["登录"] --> S2["新建知识库"] --> S3["上传文档"] --> S4["解析与向量化"] --> S5["状态变为已入库"]

主链路二：提问并核对答案出处。

flowchart LR
    Q1["输入自然语言问题"] --> Q2["混合检索与重排序"] --> Q3["模型基于片段生成答案"] --> Q4["展示引用卡片"] --> Q5["点击引用定位原文"] --> Q6["评价有用或无用"]

主链路三：知识缺口闭环。

flowchart LR
    G1["用户标记回答无用"] --> G2["记录未命中问题"] --> G3["管理员查看知识缺口"] --> G4["补充或修订文档"] --> G5["重新索引"]

6.5 状态设计

界面原型的完整度很大程度上体现在异常状态上，因此我们对核心页面 P05 完整设计了四种状态。

状态	触发条件	界面表现
空态	新知识库尚无文档；或用户还没有任何会话	展示引导文案与"上传文档""开始提问"两个主操作按钮，不使用空白页面
加载态	文档解析中；模型生成中	文档行显示解析进度与阶段名称；回答区域采用流式输出并展示"停止生成"，避免用户误判为卡死
错误态	解析失败、模型超时、网络异常	明确说明失败原因，提供"重试"按钮，并保留用户已输入的问题内容不丢失
无权限态	访问未获授权的知识库	展示无权限提示与"申请访问"入口，不泄露任何文档标题或内容

6.6 界面设计规范

类别	规范
主色	深蓝，用于主按钮、选中态与关键强调
辅助色	灰阶用于文本层级，绿色表示成功，橙色表示警告，红色表示错误
字体与字号	统一使用无衬线字体，标题 20px，小标题 16px，正文 14px，辅助说明 12px
间距	采用 8px 基准栅格，卡片内间距 16px，模块间距 24px
常用组件	按钮（主要 / 次要 / 文字）、输入框（默认 / 聚焦 / 错误）、卡片、标签、列表行、抽屉、模态框
引用组件	统一为"文档名 + 页码 + 相似度 + 摘要"四段式卡片，全站样式一致

---

七、需求分析 PPT 链接

需求分析 PPT 链接：

页码	内容
1	封面，项目名称与团队信息
2	目录
3	项目背景与问题来源，三个核心痛点
4	目标用户与用户画像，四类角色的诉求
5	用户场景，SC-01 至 SC-04 四个典型场景
6	功能需求范围，12 条需求按优先级分为四组
7	类图，12 个业务实体与 14 条关系
8	数据需求与接口需求
9	界面原型设计目标与页面清单，P01 至 P10
10	界面原型的信息架构与导航原则
11	界面原型的关键交互流程，问答与引用链路
12	验收验证标准，功能与非功能验收用例
13	关键点、难点与风险分析
14	团队分工与进度落实情况

---

八、界面原型设计答辩 PPT 链接

界面原型设计答辩 PPT 链接：

界面原型设计答辩 PPT 共 13 页，围绕"设计原则、信息架构、关键路径、状态设计、设计规范"五条线组织，页面截图全部来自可运行的原型。

页码	内容
1	封面
2	原型设计目标与设计原则
3	信息架构与导航，以及导航设计的三个决定
4	页面清单与保真度，P01 至 P10 加四种状态
5	关键路径一：登录并选择知识库（P01、P02）
6	关键路径二：上传文档并完成解析（P03、P04）
7	核心页面：智能问答（P05）与界面的四个关键点
8	关键路径三：引用溯源与反馈（P06、P07）
9	管理端：知识缺口与权限管理（P08、P09）
10	状态设计：空态与加载态（S01、S02）
11	状态设计：错误态与无权限态（S03、S04）
12	界面设计规范：主色、辅助色、字号阶梯与组件
13	原型与需求的对应关系

---

九、小组评审表

按照作业要求，每个小组需要提交本次作业的简易评审表，内容包括小组名称、项目名称、评审的内容、评审建议，以及各小组名称和排名，采用腾讯共享文档填写。

评审表	链接
界面原型设计评审表	https://docs.qq.com/sheet/DRkV5U255SW92ekZG
需求分析评审表	https://docs.qq.com/sheet/DRk9nYkdXbUZCQWxT

评审表在上一阶段《报告评审表》模板基础上调整评分维度：界面原型设计评审表按信息架构、页面完整度、交互设计、视觉规范、可落地性五个维度评分；需求分析评审表按需求真实性、用户场景、类图、功能描述与验收标准、需求边界五个维度评分。各维度均给出具体评审建议，不只给分数。

---

十、评分要点自检

为方便助教核对，我们把本次作业的评分项与本文对应位置整理如下。

评分项	分值	本文对应位置
博客排版，采用 markdown 排版，正确给出需求规格说明书、界面原型设计、界面原型设计答辩 PPT、需求分析 PPT 四个链接	2	全文使用 markdown 排版，四个链接分别见第五、六、七、八章
组队后项目整体计划安排，有明确的里程碑	6	第一章，含四阶段计划与 M0 至 M7 里程碑表
项目进行过程中可能遭遇的关键点、难点与风险分析	5	第二章，含 3 个关键点、4 个难点、6 项风险
组员分工、组员工作量比例	7	第三章，含规定格式的分工表与比例计算依据
加强团队成员分工协作，描述成员协作方式	16	第四章，含沟通工具与节奏、版本仓库协作、冲突处理、任务同步机制
需求规格说明书：引言、用户场景、类图、界面原型、功能描述、验收验证标准	32	第五章，含文档结构、用户场景表、类图、功能需求模板与验收标准表
参考国标规范撰写需求规格说明书	12	第五章 5.1 节，文档结构参照 GB/T 9385-2008 组织并补充术语与缩写、非目标两节

---

十一、结语

本次作业的核心不是把文档写厚，而是把"用户真实遇到什么问题"翻译成"软件必须做到什么"再翻译成"用什么界面承载、用什么标准验收"。整个过程中我们最深的体会是：需求分析最难的从来不是描述功能，而是把模糊的主观判断变成可以被第三方验证的条款。为此我们付出的代价是多做了几轮返工，包括把主观描述拆成可测指标、把混入类图的技术组件移出、把没有访谈支撑的场景删掉，但这些返工让后面的原型设计和验收标准都有了共同的判断依据。

下一阶段我们将按计划进入文档解析、向量化与检索问答的实现，继续把这份需求文档作为验收依据，而不是写完就束之高阁。