[T.6] 团队项目：技术规格说明书

技术规格说明书

项目	内容
这个作业属于哪个课程	2026 年北航软件工程
这个作业的要求在哪里	[T.6] 团队项目：技术规格说明书
我们在这个课程的目标是	完整参与一套成熟软件的开发过程，提升自己的工程能力和技术能力
这个作业在哪个具体方面帮助我实现目标	凝练团队对多仓库、多服务技术方案的共识；为实现阶段提供统一技术依据与质量出口标准

1. 概念和术语

1.1 术语表

术语	英文	含义
启元知微	—	本产品名称；面向课程学习的 Web 产品，能力包括：账户与认证、知识检索问答与笔记、题库与模拟考、学习论坛等。
前端子系统	Frontend (Vue SPA)	浏览器内 Vue 3 + Vite 单页应用，通过 REST 与 SSE 调用后端。
后端子系统	Backend (API)	FastAPI 异步服务：鉴权、业务规则、MySQL 持久化，对 RAG、LLM、OSS、邮件等的编排。
RAG 子系统	RAG Service / Agent 微服务	独立 FastAPI 进程（默认端口 9000），提供检索与生成链；与 Backend 以 HTTP 契约集成。
知识库	Knowledge Base (KB)	RAG 侧可检索数据集的逻辑单元，可与 course_id、目录名 kb 等映射；元数据见 RAG 侧 knowledge_bases/registry.json 等。
课程	Course	业务教学单元，与文档、对话、论坛、试卷等关联。
对话 / 会话	Conversation	用户与助手的多轮线程，落库在 Conversation / Message 等表（以 ORM 为准）。
流式回答	Streaming (SSE)	使用 Server-Sent Events 分块下发生成文本。
远程 RAG 链路	Remote RAG	USE_REMOTE_RAG=true 时，Backend 通过 HTTP 调用 RAG 的 /v1/chat、/v1/retrieve 等。
本地 RAG 链路	Local RAG	USE_REMOTE_RAG=false 时，部分检索/生成在 Backend 与 Chroma 等路径上完成。
题库	Question Bank	与 qb_* 等表及浏览、组卷、模拟考相关。
学习论坛	Forum	帖子、回复、点赞、举报等；FORUM_STUB=true 时为内存桩，仅开发用。
双令牌	Access / Refresh Token	JWT 机制中短期 Access 与长期 Refresh 的配合；见 /auth/refresh。

1.2 易混淆术语对比

术语 A	术语 B	区别
RAG 仓库的全功能 CLI（app.py 等）	RAG HTTP 微服务（src.rag_service.main）	前者含图谱、组卷、魔鬼训练等脚本能力；与启元知微 Web 联调的主要是 /v1/* HTTP 契约；二者同仓库、可不同部署单元。
Chroma（Backend 或部署中的向量客户端）	RAG 侧内置向量与索引目录	随远程/本地与部署方式而变，本文档不假设唯一物理路径。
知识库（RAG 检索集）	课程（业务实体）	多对多/映射关系；请求里可同时出现 course_id 与 kb_names；见 docs/rag_integration.md。
会话（持久化 Conversation）	RAG 请求中的 history / conversation_id	前者为业务与审计主数据；后者为单次调用上下文，契约字段以后端与 RAG 协商为准。

---

2. 技术栈

2.1 程序设计语言

子系统	语言与约束	选择理由（概要）
Backend	Python 3.12（与 CI 一致；本地可略低但建议对齐）	生态成熟；与 FastAPI、异步 ORM、AI SDK 配合好。
Frontend	TypeScript（tsconfig 与 Vue 工程约定）	与 Vue 3 + Vite 配套；提升协作与可维护性。
RAG	Python 3.10+（建议与 CI 3.12 对齐）	与 PyTorch/Transformers、Chroma 等库一致。

强约束（建议）：Backend 中业务路径保持 async/await 一致；Pydantic v2 模型与 OpenAPI 同步；前端在 CI 中通过 vue-tsc 与 vite build。

2.2 应用开发框架

类别	选型	版本（以各仓依赖为准）	作用
Web 框架（Backend）	FastAPI	^0.115	异步 API、自动 OpenAPI
ORM（Backend）	SQLAlchemy 2 异步 + aiomysql	^2.0 / ^0.2	访问 MySQL
迁移（Backend）	Alembic	^1.13	表结构版本化
前端框架	Vue 3 + Vite + Vue Router + Pinia	见 Frontend/package.json	SPA、构建、状态
RAG 服务	FastAPI + 自研链	见 RAG/requirements.txt	检索、重排、对话编排
测试	pytest	≥8.0	Backend、RAG 单元/接口测

基础设施依赖：MySQL、Redis、Chroma（视部署）；LLM/Embedding 为 OpenAI 兼容 HTTP API（后续可能会更换为本地模型）。

2.3 运行环境

2.3.1 开发环境

项	要求
Python	3.10+，推荐 3.12 与 CI 一致
Node.js	见 Frontend/package.json 的 engines（^20.19.0 或 >=22.12.0；CI 使用 22）
包管理（前端）	pnpm
操作系统	Windows / macOS / Linux（团队已用 Windows 开发）
推荐编辑器	VS Code + Python / Vue 插件

2.3.2 用户运行环境

形态	最低要求
浏览器	现代 Chromium / Firefox / Safari；无独立移动端 App 要求
网络	可访问已部署的前端静态资源与后端 HTTPS；RAG/LLM 在服务器侧调用，不强制对用户暴露

2.3.3 测试 / CI 环境

仓库	运行器与步骤（概要）
Backend	ubuntu-latest；Python 3.12；pip install -r requirements.txt；pytest tests/ -q
RAG	同上；pytest tests/ -q
Frontend	ubuntu-latest；pnpm 9 + Node 22；pnpm install --frozen-lockfile；pnpm run build（含 type-check）

2.4 核心命令

命令（目录）	作用
uvicorn app.main:app --reload（Backend）	启动 API（默认与 README 中端口一致，常见 8080）
alembic upgrade head（Backend）	应用数据库迁移
pnpm dev（Frontend）	Vite 开发服务器（常见 5173）
pnpm run build（Frontend）	类型检查 + 生产构建
uvicorn src.rag_service.main:app --port 9000（RAG）	启动 RAG 微服务

---

3. 软件架构

启元知微是 B/S + 多服务架构：浏览器只访问 Backend 暴露的 HTTPS API 与 SSE；RAG 与 LLM 在服务端侧，不对终端用户直接开放端口；MySQL、Redis 为共享基础设施。

3.1 子系统划分

3.1.1 总体架构图

flowchart LR subgraph client [用户浏览器] FE[Vue SPA] end subgraph server [服务器侧] API[Backend FastAPI] RAG[RAG FastAPI] DB[(MySQL)] RD[(Redis)] end subgraph external [外部] LLM[LLM / Embedding API] end FE -->|HTTPS REST / SSE| API API --> DB API --> RD API -->|HTTP 契约| RAG RAG --> LLM

文字化分层（自顶向下：用户可见 → 基础依赖）：

层次	说明
展示层	Vue 页面、组件、Pinia、路由
应用 API 层	Backend app/api/v1/endpoints
业务与编排	Backend app/services；RAG 侧链路与路由
数据与状态	ORM 模型、MySQL；Redis 缓存/预留
智能与检索	RAG 检索器、重排、Prompt；外部 LLM

3.1.2 各子系统的功能任务

#	子系统	代码路径 / 说明	功能任务
1	前端子系统	Frontend/src	路由、鉴权前 UI、SSE 消费、论坛与题库、静态资源构建
2	后端子系统	Backend/app	用户/课程/对话/论坛/题库等业务；JWT；调用 RAG；OpenAPI
3	RAG 子系统	RAG/src/rag_service + src/* 链路基座	health、retrieve、chat 与流式；索引构建 CLI 可独立运行
4	基础设施	运维	MySQL、Redis、（可选）对象存储、反向代理/网关

3.1.3 子系统间的关系与工作模式

• 前端仅与 Backend 的 API_V1_PREFIX（默认 /api/v1）通信。
• Backend 按 USE_REMOTE_RAG 选择 HTTP 调 RAG 或本地检索路径；RAG 再调用 LLM。
• 契约见 docs/rag_integration.md；可选请求头 X-RAG-API-KEY 与 RAG_SERVICE_API_KEY 对齐。

分层依赖原则（与 Backend README 一致）：

• Endpoint 薄、Service 厚：业务规则在 services，不在 endpoints 堆叠。
• 前端不直连 RAG、不直连 MySQL。
• RAG 的 HTTP 面 与 CLI/批处理 解耦，避免把运维脚本与线上请求路径混为一谈。

3.2 各子系统内部模块

3.2.1 模块清单与功能任务

Backend

层次	主要路径	功能任务
API	app/api/v1/endpoints	参数校验、鉴权、响应组装
业务	app/services	用例、事务、RAG/邮件/OSS 编排
模型	app/models	ORM 与表
数据访问	app/db	引擎、Session、迁移入口配合
横切	app/core	配置、安全、Redis、日志配置
RAG 适配	app/rag 等	与远程 RAG 或本地管线的对接

RAG

层次	说明	功能任务
HTTP	src/rag_service/api/routes/v1	版本化 API：health、kb、retrieve、chat / stream
编排与链	rag_chain、services	Prompt、流式封装、与检索器组合
算法与数据	hybrid_retriever、vector_store、embeddings 等	可独立单元测试
CLI/工具	build_index.py、app.py 等	建索引、交互学习；不与 Web 产品一一对应

Frontend

区域	功能任务
src/views	首页、知识问答、论坛、题库、认证等页面
src/components	布局、论坛、题库等可复用块
src/api	Axios 封装
src/stores	Pinia（如 auth）
src/router	导航守卫、登录弹窗等

3.2.2 设计原则在代码中的体现

原则	落地方式（概要）
抽象	Pydantic / TS 类型描述 API 与 DTO；RAG 契约在 rag_integration.md 固化。
内聚/耦合/模块化	按域划分 services 与 endpoints；RAG 链路与路由分离。
信息隐藏	通过 Settings 与环境变量隐藏密钥；OSS 等可选能力用开关。
界面与业务分离	Vue 不直连 DB/RAG；Backend endpoint 不写复杂规则。
系统错误记录	Python logging；不向日志写密钥与全文密码。
应对需求变化	ENABLE_*、FORUM_STUB 等 feature flag；API /v1 版本前缀。

---

4. 软件设计和实现

4.1 功能点与代码编写任务

按优先级 P0（发布 MVP 必做或已为核心路径）→ P1（增强与工程化）→ P2（后续）排序，与当前代码状态对齐，随迭代在 PR 中更新本表。

优先级	域	功能	涉及位置（参考）
P0	全栈	用户注册/登录/刷新 Token、个人资料	auth endpoints & services；Frontend 登录注册
P0	全栈	知识问答：非流式/流式、历史会话、删除	knowledge + RAG 客户端；KnowledgeQA.vue 等
P0	工程	三仓 CI 绿（Backend/RAG pytest；Frontend build）	各仓 .github/workflows/ci.yml
P0	运维	可复现的部署说明：.env、迁移、RAG 端口、LLM	README、本说明书 §7
P1	全栈	学习论坛真库联调（关闭 Stub、迁移 forum_*）	forum；FORUM_* 配置
P1	全栈	题库浏览与模拟考路径稳定	question_bank；views/bank/*
P1	工程	集成测试或 docker compose 一键起全栈	待补充脚本 / tests/
P1	工程	契约测试（RAG/ OpenAPI 漂移防护）	CI 或独立任务
P2	前端	E2E（Playwright 等）关键路径	待引入
P2	产品	课程/文档全链路、笔记生成增强、运营工具	依 ENABLE_* 与需求

4.2 系统文档编写清单

文档	详细程度
本《技术规格说明书》	子系统、技术栈、架构、测试与出口、风险、部署
docs/功能文档.md	功能与页面级需求（非本说明书重复展开）
各仓 README.md	安装、环境变量、核心命令
docs/rag_integration.md	Backend 与 RAG 之间请求/响应与错误约定
docs/database.md、Alembic 版本	表结构说明与变更历史
OpenAPI / *.openapi.json	HTTP 契约；线上 /api/v1/docs 可交互
实现后补充	详细逻辑说明可落在 PR 说明 + 关键函数 docstring；不强制与代码重复的独立长篇文档

4.3 功能的详细逻辑设计

按课程要求，本节在规格阶段不做细表化，将在实现阶段以源码、docs/功能文档.md 更新、PR 描述共同固化。建议形式：关键算法以函数 + 注释；多轮/流式状态机在 service 中注明；RAG 与后端的字段映射在 rag_integration.md 同步。

4.4 数据库和 API 接口设计

本节在规格阶段不做逐字段展开。权威来源：

• 表结构：alembic/versions + docs/database.md
• REST 契约：OpenAPI 与 rag_integration.md（RAG 子域）

特殊情况说明：启元知微有中心数据库 MySQL 与对外 API（Backend /api/v1）；RAG 为内网/服务间 HTTP，不面向浏览器公网直调。

4.5 输入假设与异常处理

输入来源	假设	不满足时的处理
浏览器请求	符合 OpenAPI 与大小/类型 约束	4xx + 明确 message
鉴权	合法 JWT；权限与角色与 endpoint 要求一致	401/403
下游 RAG/LLM	可连、在超时内返回；密钥有效	记录日志；504/502 或业务降级文案；慎对 POST 自动重试
邮件 SMTP	配置正确、网络可达	注册验证码失败时提示，不在响应中暴露 SMTP 原文错误
论坛 Stub 与真库	FORUM_STUB 与迁移状态一致	避免生产误开 Stub 导致数据不持久；文档与 checklist 标红

业务流程层面：LLM 输出可能幻觉，产品侧在 功能文档 或界面承担非绝对事实提示；UGC 论坛需举报与封禁等流程与人工策略配合。

---

5. 软件测试和性能量度

5.1 测试计划

5.1.1 测试设计总览

层级	目的	执行者
单元测试	隔离模块：工具、RAG 客户端、校验逻辑等	CI 自动
集成测试	Backend + MySQL + Redis + RAG + LLM 替身或沙箱	CI 或定时（待加强）
压力测试	只读 API 与并发；RAG+LLM 全链路的容量与限流	预生产，k6 / Locust 等
真实/探索性测试	注册、问答、论坛、题库手测	每迭代/发布前
安全与健壮性	鉴权绕越、RAG 密钥、SQL 注入面（由 ORM 减轻）等	发布前检查清单

5.1.2 单元测试

模块/方向	重点内容	目标（可随项目提高）
Backend	RAG HTTP 客户端错误与超时、鉴权辅助	核心路径覆盖逐步提升
RAG	/v1/health、请求体验证	与 tests/ 现状一致并扩展
Frontend	组件/组合式函数	待引入 Vitest 等后设阈值；当前以 type-check + build 为闸

整体覆盖率：建议在 Beta 前设定团队阈值（如行覆盖 ≥50% 起步，随迭代提高）；以不降低 CI 绿为前提。

5.1.3 压力测试

启元知微为在线多用户系统，压力测试包含：

场景	测量指标	具体压力指标（初定通过线，须环境标定后更新）
无 LLM 的只读 API	P95 延迟、错误率	例：P95 ≤ 500 ms、并发 ≥ 50（内网、SSD、局域 DB，无重负载 LLM）
SSE / 长连接	同时在线连接数、首字延迟	受 RAG/LLM 与反向代理超时限制，以不大量 504 为底线
RAG+LLM 全链路	吞吐、429/5xx 比例	以供应商限额为硬顶，不虚构「本机 QPS=模型能力」

说明：终版数字写在压测报告（可放 docs/ 或 Wiki），本说明书只保留维度与方法。

5.1.4 真实测试

类型	具体细节	频率
功能走查	注册→登录→问答（流式/非流式）→论坛或题库至少一条	每里程碑 / 发版前
多浏览器	Chrome / Edge / Firefox 各一	大版本发版前
兼容性	新迁移部署后，旧数据可读与回滚演练	有 DB 大改时

5.2 软件性能

5.2.1 性能量度方式

指标	目标/关注点	测量方式
API 可用性	探活、5xx 比例	/health、网关统计
延迟	P50 / P95	APM 或 Nginx/网关日志
对话体验	首包、整答完成时间	前端与（可选）后端 timing
资源	CPU/内存、MySQL 连接数、RAG GPU/显存	系统监控、容器指标

环境声明：低于基准配的环境「能跑」即可，不与教学服务器 SLA 强绑定，但须在说明书中诚实写清。

5.2.2 能力边界

维度	边界	依据
并发与延迟	瓶颈常在 LLM/嵌入 API 限额与网络	非仅 CPU
单节点 RAG（本地大模型）	显存/内存为硬顶；并发排队	可水平加 RAG 副本（需无状态与负载均衡）
多轮长上下文	Token 成本与超时风险上升	限轮数、截断、摘要（产品策略）
论坛 UGC	需举报、审计扩展；不替代内容审核政策	合规与运营

5.3 出口条件

阶段	发布条件
Alpha	三仓 CI 通过；Backend + RAG 健康检查可用；核心路径手测（注册/登录+至少一种问答方式）；.env 无默认秘钥检查清单；迁移 Alembic 已应用或文档说明
Beta	论坛/题库等本版本范围内功能在真数据上可用（非 Stub 则已关 Stub）；RAG 契约与 rag_integration.md 一致；压测初稿或至少并发冒烟通过；已知 P0 缺陷已修复或书面豁免
Release	回归与多浏览器手测；回滚演练；依赖安全扫描与修复计划；监控/日志可达；文档与版本号同步

说明：压力指标终版可作为 Release 强化条件，由团队自行决定是否绑死。

---

6. 技术风险识别和评估

概率：高 / 中 / 低（未来可能发生）；已发生 = 已观察到的现状。
严重度：高 = 阻塞发布或重大体验问题；中 = 部分功能或返工；低 = 可接受或易缓解。

风险	严重度	概率	应对
外部 LLM/Embedding 不可用或涨价	高	中	多 Key/多供应商、限流、缓存检索结果、降级提示
Backend 与 RAG 契约漂移	高	中	契约测试；PR 同时改代码与 rag_integration.md；保留 /v1
向量维/模型更换导致检索质量崩	中	中	BM25 回退、重建索引流程、文档化
MySQL 单点/连接池耗尽	中	中	连接池、限流、读写分离（后期）
自动化测试偏少	中	已发生	扩展 pytest、集成测、E2E 路线图见 §4.1 P2
密钥进入仓库或日志	高	低	秘钥管理、.gitignore、日志脱敏、PR 检查
论坛垃圾/攻击	中	中	限流、验证码、举报、WAF/网关（运维）

---

7. 软件部署和维护

7.1 部署环境

目标单元	运行环境	产物 / 说明
前端	静态 HTTP(S) 托管；Nginx / OSS+CDN / 任意静态站	pnpm run build 产出 dist/
Backend	Linux 服务器 / 容器；前置 Nginx/网关 终止 TLS	uvicorn 或 gunicorn+uvicorn workers；镜像见团队 ACR
RAG	与 Backend 同网段或内网可路由；算力独立为佳	容器或裸机；端口 9000（可配置）
MySQL / Redis	云 RDS 或自建	与 Backend 同区降延迟
配置	环境变量、.env 不提交	SECRET_KEY、DATABASE_URL、RAG_SERVICE_API_KEY 等

7.2 部署流程

git push
    → 触发 GitHub Actions（各仓 test / build）
    → 通过后可由 deploy workflow 构建/推送镜像（以各仓 `deploy.yml` 为准）
    → 服务器上 docker pull + compose 或等效
    → 健康检查 + Alembic migrate
    → 对外灰度/全量

启元知微三服务（前端静态 + Backend + RAG + DB）的实际 compose 与 .env 以服务器目录为真源（参见 Backend/deploy.example 等说明）。

7.3 运行与维护

• 日志：应用 stdout/结构化日志；生产级别以 ERROR/WARN 为主定位故障；不含秘钥。
• 用户反馈与缺陷：Issue/项目管理工具由团队定。
• 可复现：RAG/对话问题可记录时间、用户、conversation_id、请求 ID（若引入）协助排查。
• 文档同步：本技术设计文档与代码同步更新；修改按课程要求通知全员（见文首说明）。
• 备份与迁移：MySQL 定期全量+增量；RAG 索引可由文档与 build_index 重建时，在运维手册写明。

---

修订记录

日期	版本	作者	变更摘要
2026-04-07	0.1	团队	初稿（三仓架构、工程与质量）
2026-04-22	0.2	团队	按课程模板重排；产品名启元知微