项目说明：本文根据当前 SmartCampusAI 项目的真实目录、数据库模型、接口、测试和部署配置整理。需要特别说明的是，当前源码实际采用 Vue 3 + FastAPI + SQLAlchemy + DeepSeek，并非 Django。本文会在对应章节补充 Django + Django REST Framework 的实现映射，方便将项目改造成 Vue3 + Django + Python + DeepSeek 技术路线，但不会把尚不存在的 Django 代码描述成已经完成的成果。

一、项目背景

随着高校信息化系统不断增加，学生往往需要在教务系统、校园门户、通知平台、学习平台和就业平台之间频繁切换。传统系统虽然能够提供数据查询功能，但通常依赖固定菜单和关键词搜索，难以理解自然语言问题，也无法将分散的校园资料统一组织起来。

SmartCampusAI 的建设目标，是开发一套面向学生和校园管理人员的智能服务平台。用户可以通过自然语言咨询课程考试、奖学金、宿舍、校园生活、实习就业等问题，也可以上传 PDF、Word、PPT、TXT 等资料，由系统完成知识提取、内容总结、知识点整理、思维导图生成和智能问答。

项目不仅接入 DeepSeek 大语言模型，还引入 RAG 检索增强生成和多智能体路由机制，使 AI 回答能够优先依据校园知识库和个人资料，而不是完全依赖模型自身知识。

二、项目需求分析

系统用户主要分为学生和管理员两类。

学生用户需要完成账号注册、登录认证、个人资料维护、密码修改、AI 对话、历史会话管理、个人资料上传、知识库检索、学习资料分析、通知总结、待办管理和偏好设置等操作。管理员除具备普通用户能力外，还需要管理校园公共知识库、查看用户列表、启用或停用账号，并通过数据看板了解用户数量、文档数量、AI 对话次数和 Token 消耗情况。

AI 对话模块需要支持多轮上下文、Markdown 内容、代码高亮、流式输出、历史记录和知识库引用。系统应能够根据问题内容自动判断问题属于教务、学习、校园生活还是就业方向，并交给对应的专业 Agent 处理。

知识库模块应支持 PDF、DOCX、PPTX、TXT 和 Markdown 文件。文件上传后需要经过格式检查、大小限制、安全命名、文本解析、内容切片、向量化和 ChromaDB 入库。普通学生只能维护个人知识库，管理员可以维护全校共享知识库。

非功能需求主要包括安全性、可维护性、可靠性和扩展性。密码不能明文保存，业务接口必须进行 JWT 鉴权，管理员接口必须验证角色；API 密钥不能写入源码；大模型服务发生超时、限流或网络错误时，系统必须返回明确且统一的错误信息；前后端、数据库、向量库和缓存服务应保持模块边界，便于后续替换。

三、项目可行性分析

从技术角度看，Vue 3、Django/FastAPI、DeepSeek 和 MySQL 都具有成熟的生态。DeepSeek 提供与 OpenAI 风格兼容的接口，可以通过 LangChain 的 ChatOpenAI 适配器接入。ChromaDB 能够满足中小型校园知识库的向量检索需求，后期也可以替换为 Milvus、Elasticsearch 或其他向量数据库。

从经济角度看，Vue、Python、Django、FastAPI、MySQL、Redis、ChromaDB 和 Nginx 均可免费使用。主要运行成本来自服务器、数据库存储和大模型 Token 调用。通过限制上传大小、控制上下文长度、缓存热点统计、记录 Token 用量，可以有效控制成本。

从操作角度看，系统采用统一工作台设计。学生只需要登录后选择校园助手、学习助手、知识库或通知总结，不需要理解模型、向量或提示词等技术概念。管理员通过可视化页面完成用户和知识库管理，具有较低的使用门槛。

需要关注的风险包括校园资料的隐私保护、AI 回答的不确定性、第三方模型不可用以及上传文件中的恶意内容。因此，系统应明确标注 AI 回答仅供参考，对敏感操作保留人工确认，并通过文件白名单、权限隔离、URL 清洗、异常降级和审计统计降低风险。

四、系统总体架构设计

系统采用前后端分离的模块化单体架构。浏览器访问 Vue 3 前端，前端通过 /api/v1 调用 Python REST API；后端负责身份认证、权限控制、业务编排、数据库访问、知识库检索和大模型调用；MySQL 保存结构化业务数据，ChromaDB 保存文档向量，Redis负责缓存和后续限流扩展；生产环境由 Nginx 提供静态资源并反向代理 API。

学生/管理员
     |
     v
Vue 3 + TypeScript + Element Plus
     |
     | REST API / SSE
     v
Python Web API
     |
     +-- 用户认证与角色权限
     +-- 用户及管理后台
     +-- 会话和聊天记录
     +-- LangGraph 多智能体路由
     +-- DeepSeek 大模型适配
     +-- 文件解析与 RAG 检索
     |
     +-- MySQL / SQLite
     +-- Redis
     +-- ChromaDB

当前源码的后端分为 api、services、models、schemas、agent、ai、rag、database 和 utils 等目录。API 层只负责 HTTP 参数、鉴权和响应；Service 层处理业务流程；Model 层定义数据实体；Agent 层完成问题分类和专业智能体编排；RAG 层处理文档解析、向量化和检索。相关设计可以参见 [ARCHITECTURE.md](C:/Users/Administrator/OneDrive/Desktop/red/SmartCampusAI/docs/ARCHITECTURE.md)。

五、前后端技术栈

前端采用 Vue 3、TypeScript 和 Vite。Vue Router 负责登录页、聊天页、学习助手、知识库、通知总结、历史记录、后台管理等页面路由；Pinia 维护登录状态和界面偏好；Axios 统一发送 API 请求并附加 JWT；Element Plus 提供基础组件；ECharts 用于管理统计图表；Marked 和 Highlight.js 用于渲染 Markdown 与代码块；Vitest 用于前端单元测试。

当前后端采用 Python 3.11、FastAPI、SQLAlchemy 2、Pydantic、PyJWT 和 Argon2。FastAPI 提供 REST API、参数校验、依赖注入、Swagger 和 SSE 响应，SQLAlchemy 负责关系数据库访问。

如果必须使用 Django，可将这一层替换为 Django 5 + Django REST Framework：SQLAlchemy Model 对应 Django Model，Pydantic Schema 对应 DRF Serializer，FastAPI Router 对应 DRF ViewSet 或 APIView，鉴权层可使用 SimpleJWT，角色控制可使用 Permission Class，SSE 接口则使用 Django ASGI 与 StreamingHttpResponse。Vue、DeepSeek、LangGraph、ChromaDB 和数据库结构基本不需要变化。

六、数据库与数据表设计

数据库设计遵循“用户是业务主体、会话是聊天容器、文档与向量分离、AI 用量单独统计”的原则。本地开发使用 SQLite 降低环境门槛，生产环境使用 MySQL 8，并采用 utf8mb4 字符集保存中文和特殊字符。

数据表	主要字段	设计目的
users	id、username、password、email、role、is_active、create_time	保存用户、加密密码、角色和账号状态
conversations	id、user_id、title、create_time、update_time	管理多轮会话及其排序
chat_history	conversation_id、user_id、question、answer、agent、sources	保存问题、回答、Agent 类型和知识来源
documents	owner_id、original_name、stored_name、file_type、file_size、scope、status	管理个人或校园文档及处理状态
ai_usage	user_id、provider、model、feature、prompt_tokens、completion_tokens	统计调用量和成本
navigation_badges	user_id、menu_id、kind、create_time、read_time	保存未读提醒和待处理状态

表关系方面，一个用户可以创建多个会话，一个会话包含多条聊天记录；删除会话时级联删除对应聊天记录。文档所有者被删除后，文档可通过 SET NULL 保留，避免校园公共资料丢失。用户名、邮箱和文件存储名设置唯一约束，常用外键、时间及状态字段建立索引。

向量数据不直接存入 MySQL。文档正文完成切片后写入 ChromaDB，并携带 document_id、文件名、作用域和所有者编号等元数据。查询时根据用户身份过滤个人资料和校园公共资料，防止跨用户检索。

七、环境搭建与项目初始化

开发环境建议使用 Python 3.11、Node.js 20 或 22、npm、Git，并根据部署方式准备 MySQL、Redis 和 Docker Desktop。项目提供了 Windows 初始化脚本，可以创建 backend/.venv、安装依赖并生成开发配置。

cd C:\Users\Administrator\OneDrive\Desktop\red\SmartCampusAI
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup-dev.ps1
start.bat

开发地址分别为 Vue http://127.0.0.1:5173、后端 http://127.0.0.1:8000、Swagger http://127.0.0.1:8000/docs。项目必须使用 backend/.venv/Scripts/python.exe，避免全局 Python 版本或依赖不一致。

标准 Git 流程可采用 main + develop + feature 模式。开发需求从 develop 创建 feature/auth、feature/ai-chat 等分支；每完成一个可独立验证的功能，执行测试后提交；通过代码审查后合并到 develop，发布时再合并到 main 并打版本标签。.env、数据库文件、虚拟环境、node_modules、上传文件和运行日志必须由 .gitignore 排除。

八、模块分步开发流程

用户模块首先建立 User 模型和注册、登录、个人信息、修改密码接口。注册时检查用户名和邮箱唯一性，密码使用 Argon2 哈希；登录成功后签发包含用户编号、角色、签发时间和过期时间的 JWT。前端使用 Pinia 保存登录信息，路由守卫阻止未登录用户访问业务页面。账号被管理员停用后，即使持有旧 Token，也不能继续访问系统。

管理模块在普通鉴权之上增加管理员角色校验。管理员可以查询用户列表、切换账号状态和查看统计数据。统计接口聚合用户数、文档数、聊天数、Token 总量和近七日趋势，并使用 Redis 或本地缓存减少重复计算。系统禁止管理员停用自己，避免管理入口被意外锁死。

AI 聊天模块先建立 Conversation 和 ChatHistory 模型，再实现普通对话、SSE 流式对话、会话列表、消息详情和会话删除接口。每次提问最多读取最近六轮历史，避免上下文无限增长。LangGraph 根据关键词将问题分配给教务、学习、生活或就业 Agent，再组合历史、RAG 资料和用户问题调用 DeepSeek。回答完成后，系统保存内容、知识来源、Agent 类型及 Token 用量。

业务功能模块包括知识库、学习资料分析、通知总结、历史记录、文档导出、待办提醒和个人偏好。文档上传后先检查扩展名和大小，再用 UUID 生成存储名，解析文本并建立向量索引。学习助手可以完成资料总结、知识点提取、Mermaid 思维导图、测试题生成和资料问答。通知总结固定输出标题、发布时间、重要事项、截止时间、注意事项和建议行动，便于学生快速获取关键信息。

九、DeepSeek 大模型接入

首先在 DeepSeek 平台创建 API Key，然后只将密钥写入 [backend/.env](C:/Users/Administrator/OneDrive/Desktop/red/SmartCampusAI/backend/.env)，不能写入 Python、Vue 源码或 Git 仓库。

LLM_PROVIDER=deepseek
LLM_MODEL=deepseek-chat
DEEPSEEK_API_KEY=此处填写实际密钥

后端读取配置后，根据 LLM_PROVIDER 创建不同模型适配器。DeepSeek 使用 https://api.deepseek.com 作为基础地址，通过 OpenAI 兼容协议发送模型、消息、温度和流式参数。业务层不直接依赖某一家供应商，因此后续可以切换 OpenAI、通义千问或本地模型。

大模型调用可能出现密钥缺失、401 鉴权失败、429 限流、网络超时、余额不足、模型不存在和响应格式异常。配置错误应返回 LLM_CONFIG_ERROR，模型不可用统一转换为 HTTP 503 和 LLM_UNAVAILABLE，前端再显示可理解的提示。日志只能记录供应商、模型、请求编号和错误类型，禁止打印完整 API Key、JWT 或用户敏感内容。

配置修改后必须重启后端，因为 Pydantic 配置对象会被缓存。可以通过以下脱敏命令检查最终生效值：

cd backend
.\.venv\Scripts\python.exe -c "from app.config import settings; print(settings.llm_provider, settings.llm_model, bool(settings.deepseek_api_key))"

正确结果应类似 deepseek deepseek-chat True。这里只输出密钥是否存在，不输出密钥内容。

十、测试、BUG 修复与优化迭代

测试应覆盖单元测试、接口测试、集成测试、前端构建、浏览器验收和部署配置检查。后端重点测试注册登录、重复用户、密码修改、JWT、角色权限、会话隔离、文档权限、大模型异常和文件处理失败；前端重点测试状态管理、API 错误转换、Markdown URL 安全、路由守卫和响应式布局。

项目调试过程中曾出现“Vue 页面能打开，但登录提示网络错误”。最终定位到前端 5173 返回 200，但后端 8000 未监听，根因是误用了全局 Python 3.14，且缺少 jwt 依赖。解决方式是固定 Python 3.11、创建独立虚拟环境并通过启动脚本统一管理。

另一个典型问题是 Vite 返回 200，但页面仍然空白。浏览器网络面板显示 /src/router/index.js 和 /src/store/index.js 返回 404，页面中的 #app 没有挂载内容。原因是 TypeScript 构建曾在源码目录生成 JavaScript 文件，旧 Vite 进程仍缓存过期模块路径。修复时应保持 noEmit: true、清理错误产物并彻底重启 Vite。由此可见，HTTP 200 只能证明服务器响应，不能证明 Vue 已经正确渲染。

DeepSeek 配置问题也曾表现为页面始终显示 mock / gpt-4o-mini。根因是后端读取了错误位置的 .env。配置加载路径固定为 backend/.env 后，需要重新启动 FastAPI，再分别验证有效配置、供应商直连和应用聊天接口。

优化阶段还应包括：限制上下文和上传大小、缓存统计数据、保存真实 Token 用量、清洗 Markdown 中的 javascript: 和危险 data: URL、处理多 Worker 初始化竞争、为失败文档返回 422、为模型故障返回 503，并在移动端检查横向溢出和组件重叠。

十一、项目部署

生产部署采用 Docker Compose 编排 MySQL、Redis、后端和前端四类服务。Vue 在 Node 构建阶段生成 dist，再由 Nginx 提供静态文件；Nginx 将 /api/、/docs 和 /openapi.json 反向代理到 Python 后端；后端通过 Gunicorn 和 Uvicorn Worker 运行；上传文件、Chroma 数据、MySQL 数据和 Redis 数据分别使用持久化卷。

Copy-Item .env.example .env
# 修改数据库密码、SECRET_KEY、管理员密码和 DeepSeek API Key
docker compose config
docker compose up --build -d

生产环境必须关闭调试模式，替换默认 SECRET_KEY 和管理员密码，限制 CORS 域名，启用 HTTPS，设置数据库备份、日志轮转、容器健康检查和最小权限网络策略。当前 Dockerfile 与 Compose 配置已经具备部署结构，但项目历史验收时 Docker Desktop 不可用，因此只完成了静态配置检查，不能将其描述为已经完成容器运行验收。

十二、最终成品效果

系统最终形成了统一的校园 AI 工作台：登录页提供账号认证入口；主界面通过侧边栏进入校园助手、学习助手、知识库、通知总结、历史记录、文档导出、待办提醒、偏好设置和管理后台；AI 对话支持 Markdown、代码高亮、历史会话、RAG 开关和流式展示；管理员能够查看用户、资料、对话及 Token 统计。

项目历史验收记录显示，后端测试 11 项、前端测试 24 项、前端生产构建和 Python 编译曾通过；真实 DeepSeek 登录与聊天请求曾返回 HTTP 200，并产生非空回答和 Token 统计；桌面端与移动端浏览器检查未发现控制台错误和横向溢出。上述属于历史验证结果，并非本次重新执行测试的结果。

在github上面我们也发表了这个项目的源码，有兴趣想试试的都可以去下载玩一玩，体验一下，https://github.com/CodingTab88/zhixiaoyuan-ai-platform  这个是下载项目网址打开github进去就可以搜到。

十三、项目总结

SmartCampusAI 的核心价值并不只是“在网页中调用一次大模型”，而是将用户权限、业务数据、校园知识库、多轮会话、RAG 检索、多智能体编排、异常治理、调用统计和容器化部署组合成完整的软件工程闭环。

在实际开发中，最重要的经验是保持分层边界清晰、配置与代码分离、密钥永不进入仓库，并使用真实浏览器和认证 API 验证最终链路。只有页面能够渲染、用户能够登录、受保护接口能够访问、知识库能够检索、DeepSeek 能够返回有效结果，才能认为智慧校园 AI 项目真正达到可交付标准。

本次仅进行了只读检查，没有创建、修改或删除 SmartCampusAI 内的任何文件。当前工作区原有未提交内容也保持不变。