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

项目	内容
这个作业属于哪个课程	课程社区
这个作业的要求在哪里	作业要求
我在这个课程的目标是	团队合作，分工完成软件的完整开发流程
这个作业在哪个具体方面帮助我实现目标	讨论确定服务器等基础设施准备

技术规格说明书

一、概念与术语

术语	定义
日程（Event）	本文档中指"统一日程实体"，包含课程、考试、作业 DDL、博雅活动、比赛、社团事务等所有具有时间属性的事项。
课程（Course）	特指从教务系统导入、具备上课周次（week_pattern）与节次（time_slot）结构的排课信息。
RAG	检索增强生成：先通过向量检索找到相关知识片段，再交由大模型生成答案的技术路线。
智慧日程	本项目特指融合了课表、考试、DDL、博雅、比赛等多类型日程，并支持 AI 辅助生成的统一日程管理模块。
智能学习助手	本项目特指基于 RAG 的课程知识问答与学习计划生成模块。其知识库绑定用户上传的教材讲义，输出的学习计划可直接回填到智慧日程。

二、技术栈

2.1 程序设计语言

用途	语言
前端（微信小程序）
后端服务	Python
数据库脚本	SQL（PostgreSQL 方言）

2.2 开发框架与核心依赖

层级	选型	选型理由
前端框架	uni-app（Vue 3 + TypeScript）	一套代码支持微信小程序，后期可扩展 H5/App；TS 提升可维护性
后端框架	FastAPI	原生 async/await，AI 流式响应不阻塞；Pydantic 模型自带参数校验；自动生成 OpenAPI 文档
ORM	SQLAlchemy 2.0	异步 ORM 支持，与 FastAPI 生态兼容
数据库迁移	Alembic	与 SQLAlchemy 配套的版本化迁移工具
关系数据库	PostgreSQL	支持 JSONB 字段，事务可靠，适合复杂日程与 POI 数据
缓存	Redis	Token 缓存、限流计数器、静态数据（校历、校车表）热缓存
向量存储	Chroma	纯 Python 实现，可嵌入 FastAPI 进程，部署成本低
地图 SDK	腾讯地图微信小程序 SDK	原生适配微信小程序，支持 Marker、定位、路径规划
大语言模型	DeepSeek API	中文能力强、国内直连、成本可控
日志	loguru	API 简洁，支持结构化日志与文件轮转
任务队列（可选）	APScheduler / Celery	用于定时推送、缓存刷新
测试框架	pytest + pytest-asyncio（后端）/ Vitest（前端）	主流选择，社区支持好

2.3 运行环境要求

服务端：

• 操作系统：Ubuntu 22.04 LTS
• CPU / 内存：≥ 2 核 4GB（上线初期），压力测试后按需升级
• Python 3.11 运行时

用户端：

• 微信版本 ≥ 8.0.30（对应基础库 2.27.0+，支持订阅消息、地图组件最新特性）
• 设备系统：iOS 12+ / Android 7.0+

三、软件架构

3.1 总体架构

系统采用前后端分离 + AI 服务解耦的分层架构，整体划分为四个子系统：

graph TB subgraph 客户端子系统 A[微信小程序前端<br/>uni-app + Vue 3] end subgraph 服务端子系统 B[API 网关/Nginx] C[FastAPI 业务服务] D[定时任务调度器] end subgraph 数据存储子系统 E[(PostgreSQL<br/>结构化数据)] F[(Redis<br/>缓存 & 限流)] G[(Chroma<br/>向量库)] end subgraph AI 服务子系统 H[AI Service 封装层] I[DeepSeek API] J[Embedding 模型] end subgraph 外部依赖 K[微信开放平台] L[腾讯地图 SDK] M[北航教务系统/邮件] end A -->|HTTPS/JSON| B A -->|SDK 调用| L A -->|授权登录| K B --> C C --> E C --> F C --> H C --> M D --> C H --> G H --> I H --> J

3.2 子系统职责

子系统	主要职责	工作模式
客户端子系统	UI 渲染、用户交互、本地缓存、地图可视化、订阅消息触发	通过 HTTPS 调用服务端 API；直接调用腾讯地图 SDK 与微信 API
服务端子系统	业务逻辑、数据持久化、鉴权、课表爬取/解析、冲突检测、调度 AI 服务	无状态 HTTP 服务，水平可扩展
数据存储子系统	结构化数据、缓存、向量数据持久化	PostgreSQL 主库 + Redis + 嵌入式 Chroma
AI 服务子系统	大模型调用封装、RAG 检索、流式输出、Prompt 管理	作为服务端的内部模块运行；对外透明

3.3 服务端模块划分

服务端（FastAPI）内部按领域划分为以下模块（采用分层 + 领域隔离原则）：

graph LR subgraph 接入层 R1[auth_router] R2[schedule_router] R3[learning_router] R4[map_router] R5[shortcut_router] end subgraph 业务层 S1[UserService] S2[EventService] S3[CourseImportService] S4[LearningService] S5[MapService] end subgraph 基础设施层 I1[AI Service] I2[Cache Service] I3[Repository/DAO] I4[Scheduler] end R1 --> S1 R2 --> S2 R2 --> S3 R3 --> S4 R4 --> S5 S1 --> I3 S2 --> I3 S2 --> I2 S3 --> I3 S4 --> I1 S5 --> I3 I4 --> S2

模块职责说明：

• 接入层（Router）：仅负责参数解析、鉴权校验、调用 Service，不含业务逻辑；
• 业务层（Service）：封装具体业务规则（如冲突检测、RRULE 展开、GPA 计算），不直接访问 ORM；
• 基础设施层：统一封装数据访问、缓存、AI 调用、定时任务，对业务层屏蔽实现细节。

3.4 设计原则

• 界面与业务分离：前端不含任何业务规则（如冲突判定、GPA 计算），全部由服务端计算后返回；
• 信息隐藏：AI Service 对业务层屏蔽底层模型差异，便于后续更换模型（如 DeepSeek ↔ Qwen）；
• 模块化与低耦合：模块间通过接口（Pydantic Schema）通信，不共享内部状态；
• 应对需求变化：日程类型（Event.type）使用枚举+字符串双重存储，新增类型不需要修改表结构；快捷入口配置走 JSON，新增入口不需发版。

四、各模块技术实现方案

4.1 用户模块

• 采用微信小程序授权登录：wx.login() 获取 code → 后端调用微信接口换取 openid 与 session_key；
• 服务端生成 JWT Token 返回前端，同时写入 Redis（key = token:<jti>，TTL = 7 天），支持主动注销；
• 用户基础资料存入 PostgreSQL users 表，学号绑定需额外的邮箱验证流程。

4.2 智慧日程模块

• 课表导入：用户输入学号 + 北航邮箱 → 服务端发送验证邮件 → 验证通过后抓取/解析教务课表（无法爬取时降级为模板导入或手动录入）；
• 冲突检测：在写入日程时进行时间段重叠校验，返回冲突列表；允许用户在确认后强制写入；
• AI 日程生成：用户自然语言输入 → Prompt 约束输出 JSON Schema → 前端预览、支持一键批量导入；
• 视图展示：前端基于日程时间段计算日/周/月视图，月视图仅拉取当月数据以降低流量。

4.3 智能学习助手模块

• 采用 RAG 架构
• 流式响应：FastAPI 使用 StreamingResponse + SSE，前端通过 EventSource 或小程序自定义协议接收；
• 学习计划生成：LLM 根据课表 + 目标输出结构化 Markdown 计划，经结构化解析后可一键回填至智慧日程。

4.4 校园地图模块

• 使用腾讯地图微信小程序 SDK 渲染底图；
• POI 数据（团队采集）存入 PostgreSQL
• 支持分类筛选、关键词搜索、详情查看、路线规划（调用腾讯地图路径规划 API）；
• 校历、校车时刻表缓存至 Redis（TTL = 24h）；
• 支持从日程模块"跳转到此地点"的导航入口。

4.5 快捷入口模块

• 入口清单以 JSON 配置形式存储于服务端，支持后台静态更新；
• 前端按分类渲染入口卡片，点击后通过 wx.navigateToMiniProgram（跳转其他小程序）或 web-view 组件（打开 H5）跳转；
• 常见生活问题 FAQ 走向量检索 + LLM 组合（复用学习助手的基础设施）。

五、软件设计与实现任务

5.1 代码编写任务

按子系统列出需要完成的主要代码工作（完整任务清单详见敏捷看板）：

前端（微信小程序）：

• 基础脚手架：路由、全局状态（Pinia）、请求封装、鉴权拦截；
• 页面：登录页、日程主页（日/周/月视图）、日程编辑页、学习助手对话页、地图页、快捷入口页、个人中心；
• 组件：日程卡片、冲突提示条、Markdown 渲染器、流式对话气泡、POI Marker 弹窗；
• 本地能力：订阅消息、文件选择上传、地图定位、缓存失效策略。

后端（FastAPI）：

• 通用中间件：鉴权、限流、统一异常处理、日志；
• Router 层：认证、日程、学习助手、地图、快捷入口、上传；
• Service 层：课表导入与 RRULE 展开、冲突检测、GPA 计算、RAG Pipeline、Prompt 模板管理；
• 基础设施：AI Service 封装、Cache Service、Repository、Scheduler；
• 数据库迁移脚本（Alembic）与种子数据脚本（POI、校历）。

AI 服务：

• Embedding / Chat 统一封装（带重试、超时、限流）；
• 知识库入库 Pipeline（文本提取 → 切片 → 向量化 → 写 Chroma）；
• 自然语言日程解析 Prompt 与输出校验器。