教学平台技术架构设计 V0.1

状态：技术工作稿
依据：教学平台产品共识 V0.1
目标：支持首期两家校区网页端上线，并为后续多校区和多端扩展保留路径
日期：2026-08-02

---

一、架构判断

首期采用 Web First、API First、单体全栈 架构。

这里的“单体”是一次部署、一个主代码仓库，不是把页面、权限、业务规则和数据访问混写。代码内部仍按页面层、接口层、业务模块和数据层分层；从首期开始提供稳定 API，以便后续 Android 原生端和 Windows Electron 客户端复用。

当前不拆独立 Java/Python 后端、不采用微服务、不开发原生客户端。原因是团队主要依靠 AI 开发，首期功能以账户、课程、任务、答题、提交和作品空间为主，减少技术栈数量比过早拆分更重要。

二、已选技术栈

范围	首期选择	作用
Web 框架	Next.js + React + TypeScript	总部、校区、教师、学生四类网页与 API
UI	Tailwind CSS + shadcn/ui	后台表单、表格、课程节点编辑界面
数据库	PostgreSQL	组织、账号、课程、任务、提交、作品等关系数据
数据访问	Prisma	数据模型、迁移、类型安全查询
文件存储	国内 S3 兼容对象存储	图片、视频、文件、HTML/ZIP 包
HTML 运行	独立课件域名 + iframe 沙箱	隔离课件与学生 HTML 作品
部署	Docker + 国内云服务器	开发、测试、正式环境部署
版本管理	Git	AI 开发过程可追溯、可回退
基础测试	单元测试 + Playwright 关键流程测试	上线前验证登录、发布、答题、提交

三、系统结构

Android 平板浏览器 / Windows 浏览器
                ↓
       Next.js 教学平台
       ├── 管理、教研、教师、学生网页
       ├── 版本化 API：/api/v1/...
       └── 业务模块与权限校验
                ↓
       PostgreSQL ── 对象存储
                          ↓
                 独立 HTML 课件域名

主平台处理登录、权限、课程、任务、提交和作品空间。对象存储仅保存文件本体；文件归属、版本、访问权限和业务记录必须保存在 PostgreSQL 中。

HTML 课件和 HTML 作品运行在独立域名或子域名下，例如：

平台主站：app.example.com
课件运行域名：courseware.example.com

HTML 内容不得直接获得主平台 Cookie、学生登录凭证或系统权限。主平台使用 iframe 沙箱加载 HTML。当前授课中的 HTML 环节只下发运行，不回收答案、完成状态或内部行为；课件通信协议仅作为未来可选能力保留。

四、代码组织

首期保持一个仓库、一个 Web 项目。建议按业务模块组织，而不是按页面堆放代码：

src/
├── app/                 页面与 API 路由
├── modules/
│   ├── identity/        账号、登录、角色与权限
│   ├── organization/    总部、校区、班级与成员
│   ├── curriculum/      课程体系、课程包、课程与内容版本
│   ├── task/            任务发布、补发、撤回
│   ├── submission/      答题、文字、图片、文件提交
│   ├── portfolio/       学生作品空间
│   └── courseware/      智能课件环节、媒体播放器、HTML 运行与通信协议
├── components/          通用界面组件
├── lib/                 数据库、存储、日志、校验等基础能力
└── prisma/              数据模型与迁移记录

页面不能直接操作数据库；页面调用 API 或服务层，服务层统一完成权限、业务规则和数据访问。

五、核心数据模型

首期至少建立以下实体：

总部 / 校区 / 用户 / 学生档案 / 班级 / 班级成员
课程体系 / 课程包 / 课程 / 智能课件 / 教学环节 / 内容版本
任务模板 / 任务发布记录 / 接收学生
题目 / 答案 / 自动评分结果 / 学生提交
文件资产 / HTML 包 / HTML 作品版本
学生作品空间 / 作品 / 作品附件

关键原则：

• 学生账号、学生档案与班级成员关系分开；
• 课程标准内容与教师实际发布记录分开；
• 任务提交与长期作品分开；
• 文件物理地址与文件业务权限分开；
• 任何课程、任务、课件和作品都保留创建者、归属校区、版本与时间信息。

六、接口原则

从首期开始使用版本化接口：

/api/v1/auth
/api/v1/campuses
/api/v1/classes
/api/v1/students
/api/v1/courses
/api/v1/coursewares
/api/v1/tasks
/api/v1/submissions
/api/v1/portfolio

网页端首先使用这些接口；未来 Android 和 Electron 直接复用。接口返回数据不得携带无权限学生的信息，文件访问地址应为短期签名地址或由平台代理鉴权后返回。

七、HTML 课件协议

教研独立制作 HTML，产研提供 SDK、模板、示例和上传校验。课件接入后可通过浏览器标准消息机制回传：

ready / started / save / submit / completed / error

平台向课件提供一次性会话标识、任务标识和必要配置，不提供学生真实姓名或长期账号凭证。未接入 SDK 的 HTML 可运行，但不能要求平台自动识别其内部答案或分数。

八、环境与上线

必须保留三套环境：

环境	用途
开发环境	AI 开发、功能自测与模拟数据
测试环境	教研、校区和教师验证真实流程
正式环境	两家校区实际课堂使用

正式环境至少具备：

• HTTPS；
• 数据库每日备份与可恢复演练；
• 对象存储备份或版本保护；
• 上传文件类型、大小和病毒检查策略；
• 错误日志与访问日志；
• 上线前数据库迁移检查；
• 关键账号、发布、答题、提交流程的自动化测试。

九、后续演进

阶段	触发条件	演进方向
两校区稳定运行	课程、任务与作品流程通过真实课堂验证	优化智能课件和教师工作流
校区开始增加	管理、权限、内容版本需求上升	增强多校区治理、监控和批量管理
Android 原生端启动	平板端需要更强体验或设备能力	Kotlin + Jetpack Compose，复用 API
Windows 客户端启动	需要稳定桌面容器或本地能力	Electron，复用 Web 界面与 API
后台任务变复杂	视频、HTML、通知、文件处理明显增长	抽离队列和后台任务服务
多端与研发团队扩张	独立部署、扩容或协作成为瓶颈	从模块边界逐步拆出独立后端服务

十、当前不确定项

以下事项在进入部署实施前确认，不影响当前技术栈：

• 具体国内云服务商和域名；
• 首期预计学生、教师、班级和文件容量；
• 视频是否自行存储或使用外部视频服务；
• Git 远程托管位置与 AI 开发协作方式；
• 监护人访问学生账号的具体辅助机制；
• Android 原生端和 Electron 客户端的启动时间。

---

本工作稿不替代《AI 时代创造教育体系教学平台产品共识 V0.1》；前者描述实现边界，后者定义产品范围与业务判断。