一、项目背景作为大学课程的助教每学期末都要面对一项极具挑战性的工作将课后作业分、课前预习分、课堂报告分和班级名单合并为每个学生生成个性化的反馈评语最后导出 Excel 上交。这个流程的痛点很明确表格多至少 3 份 Excel上百行数据规则复杂不同分数段生成不同话术课前/课后/课堂三个维度各有逻辑容易出错手动拼姓名、对分数稍有不慎就张冠李戴不易复用下个学期换个课程又要重做于是我花了几个周末从零写了一个纯前端的助教反馈生成工具。这篇文章就来讲讲它的架构设计和技术细节。二、项目概览2.1 一句话定位浏览器内一键合并多份教学表格批量生成学生个性化反馈评语支持 Excel 导出。2.2 核心功能清单功能说明 多文件上传拖拽或浏览上传课后作业、课前预习、课堂报告、班级名单 课次自动识别从文件名智能提取课次支持手动微调✍️ 反馈话术生成按分数段 学生表现模板批量生成 成绩统计图表Chart.js 驱动的分布直方图 课堂积分饼图 多周趋势分析历史数据对比趋势诊断与评语时间线 AI 辅助评语自封装 OpenAI 兼容客户端支持 5 种 Provider 多格式导出Excel带样式、截图图片、仅导出已选姓名 免交管理免交名单在线同步自动跳过免交学生 深浅双主题CSS 变量 Tailwind 暗色模式无缝切换 毛玻璃 UIbackdrop-filter 玻璃质感 p5.js Perlin 噪声纹理 猫咪彩蛋点击 Logo 召唤一只摇尾巴的小猫2.3 技术栈一览层次技术选型说明前端框架无框架原生 JSIIFE 模块零构建打开即用UI 样式Tailwind CSS v3 CDN 内联 CSS 变量~600 行样式双主题表格解析SheetJS (xlsx.js) 0.18.5读取 Excel/CSV表格导出ExcelJS 4.3.0带样式的 .xlsx 导出图表Chart.js 4.4.1直方图 饼图截图导出html2canvas 1.4.1DOM → 图片OCRTesseract.js 4.1.1图片文字识别PDF 解析PDF.js 3.11.174AI 评语 PDF 提取Word 解析Mammoth.js 1.9.0AI 评语 docx 提取生成艺术p5.js 1.9.0图表 Perlin 噪声纹理庆祝动画canvas-confetti 1.6.0生成成功纸屑AI 客户端自封装 OpenAI 兼容接口支持 GPT/千问/豆包/智谱/DeepSeek部署Vercel 静态托管零服务端配置三、架构设计3.1 整体分层┌─────────────────────────────────────────────────────┐ │ CDN 依赖层 │ │ SheetJS ExcelJS Chart.js Tesseract p5.js ... │ ├─────────────────────────────────────────────────────┤ │ index.html │ │ ┌─────────┐ ┌──────────┐ ┌──────┐ ┌─────────┐ │ │ │ 选择页 │ │ 上传区 │ │反馈区 │ │ 设置页 │ │ │ │(寒暑假/ │ │(4列上传) │ │(生成 │ │(AI配置 │ │ │ │ 春秋季) │ │ │ │ 导出) │ │ 免交) │ │ │ └─────────┘ └──────────┘ └──────┘ └─────────┘ │ ├─────────────────────────────────────────────────────┤ │ js/app/ 业务模块 │ │ ┌────────────────────────────────────────────────┐ │ │ │ main.js (11,111 行87%) │ │ │ │ 课次管理 | 上传处理 | 反馈生成 | 导出 | 趋势 │ │ │ │ AI交互 | 免交管理 | 设置持久化 │ │ │ └────────────────────────────────────────────────┘ │ │ lesson-number analytics ai-client virtual-list │ │ exempt-api logger config dom-utils │ │ browser-utils │ ├─────────────────────────────────────────────────────┤ │ server/ 服务端 │ │ exempt-http.mjs (免交名单同步 API) │ └─────────────────────────────────────────────────────┘3.2 命名空间设计所有模块挂载在全局window.TA对象下隔离各模块作用域window.TA{Config,// 常量与配置Logger,// 分级日志BrowserUtils,// FileReader/CORS 代理DOMUtils,// DOM 操作小工具VirtualList,// 虚拟滚动渲染器Analytics,// Chart.js 图表管理AIClient,// AI API 客户端ExemptAPI,// 免交名单同步// main.js 中的全局状态与方法...};3.3 脚本加载顺序顺序敏感config.js → logger.js → browser-utils.js → dom-utils.js → virtual-list.js → lesson-number.js → analytics.js → ai-client.js → exempt-api.js → main.js所有模块通过 IIFE 在DOMContentLoaded前完成初始化main.js 最后加载并通过DOMContentLoaded/load事件绑定 UI 交互。四、核心模块深度解析4.1 课次自动识别系统这是整个工具最精巧的部分之一。来源文件如第6课课后作业.xlsx上传后需要自动提取课次同时支持手动 ±1 微调。实现要点文件名校验通过正则匹配文件名中的数字模式支持「第 N 课」「专题N」「L#N」等多种命名中文数字映射numberToChinese()函数将阿拉伯数字转为中文1→一11→十一多课次重叠当课后、预习、报告三个来源的课次不一致时自动检测并在反馈话术中体现差异严格输入解析parseStrictLessonInput()支持单值6和区间8-9两种课次输入模式关键代码结构lesson-number.js338 行// 阿拉伯数字 → 中文数字functionnumberToChinese(n){constdigits零一二三四五六七八九;// 个位数直接映射if(n9)returndigits[n];// 十位数特殊处理consttensMath.floor(n/10);constonesn%10;return(tens1?digits[tens]:)十(ones?digits[ones]:);}4.2 反馈话术引擎这是整个应用的心脏位于 main.js 的generateFeedbackText()函数中。打分规则概览维度数据来源评分范围课前预习预习表格上传0–2 分含优秀分数线课后作业作业表格上传0–10 分课堂报告课堂统计表格0–6 分参与分话术映射逻辑functiongenerateFeedbackText(student,scores,template){letlines[];// 课前预习维度if(scores.previewexcellentLine){lines.push(template.preview.excellent);}elseif(scores.preview1){lines.push(template.preview.good);}else{lines.push(template.preview.needImprove);}// 课后作业维度if(scores.homework9)lines.push(template.homework.excellent);elseif(scores.homework7)lines.push(template.homework.good);elseif(scores.homework5)lines.push(template.homework.average);elselines.push(template.homework.needImprove);// 课堂参与维度...returnlines.join(\n);}4.3 虚拟滚动列表当班级人数超过 50 人时反馈结果列表可能非常长。项目实现了一个自研虚拟滚动virtual-list.js370 行核心算法只渲染可视区域 ± 预载区的 DOM 节点行高自适应支持不定高的反馈卡片滚动定位支持按学生序号快速跳转选中态保持虚拟滚动过程中保持 checkbox 状态不丢失4.4 AI 客户端封装ai-client.js164 行封装了一个 OpenAI 兼容的通用客户端// 支持 5 种 Provider 一键切换constAI_PROVIDERS{openai:{endpoint:https://api.openai.com/v1,models:[...]},qwen:{endpoint:https://dashscope.aliyuncs.com/compatible-mode/v1,...},doubao:{endpoint:https://ark.cn-beijing.volces.com/api/v3,...},zhipu:{endpoint:https://open.bigmodel.cn/api/paas/v4,...},deepseek:{endpoint:https://api.deepseek.com/v1,...},};AI 在项目中的应用场景工作表洞察自动分析上传表格的表头结构给出数据建议评语辅助根据学生得分数据AI 生成初版评语供助教参考关键字补全通过aiRecoverSectionByKeywords()从评语文本中智能恢复缺失段落4.5 免交名单云端同步exempt-api.js140 行配合server/exempt-http.mjs118 行实现免交名单的多设备同步本地优先所有操作先落 localStorage再异步同步冲突处理基于时间戳的 Last-Write-Wins 策略断网可用服务端不可达时降级为纯本地模式4.6 毛玻璃 UI 系统CSS 变量设计index.html内联style约 600 行:root{--bg:#f0f2f8;--text:#1a1a2e;--surface:rgba(255,255,255,0.72);--border:rgba(255,255,255,0.55);--shadow:0 12px 40pxrgba(0,0,0,0.09);--accent:99,102,241;--radius:16px;}.dark{--bg:#0f0f1a;--text:#e0e0e0;--surface:rgba(30,30,50,0.72);--border:rgba(255,255,255,0.08);}玻璃面板实现.card{background:var(--surface);backdrop-filter:blur(18px);border:1px solidvar(--border);border-radius:var(--radius);box-shadow:var(--shadow);}p5.js 图表纹理在 Chart.js 图表上层叠加低不透明度 Perlin 噪声营造「纸的质感」增强数据可视化的质感。五、技术亮点5.1 零构建开箱即用没有package.json没有webpack/vite没有npm install。双击index.html即可运行。所有第三方库通过 CDN 引入最大程度降低使用门槛。5.2 巨型单文件的分层组织main.js虽然达到 11,111 行但内部通过 IIFE 闭包 功能域注释分区实现了清晰的分层// 课次管理子系统 // 文件上传与处理 // 反馈生成引擎 // 导出功能 // 趋势分析 // AI 功能 // 设置与持久化 // UI 事件绑定 5.3 多 Provider AI 无缝切换5 种大模型 Provider 在同一个 UI 中一键切换自动填充 endpoint 和模型列表。API Key 通过 localStorage 加密存储支持多 Key 槽位切换。5.4 深浅色双主题通过 CSS 变量 body.dark类切换所有组件包括 Chart.js 图表、p5.js 纹理均支持深色模式自动适配。5.5 可访问性全站按钮有aria-label上传区支持键盘导航滚动列表支持焦点管理响应式适配 320px ~ 4K 分辨率六、部署指南6.1 本地运行# 方式一直接双击打开双击 index.html# 方式二用任意 HTTP 服务python-mhttp.server8080# 或npx serve.6.2 Vercel 部署# 安装 Vercel CLInpmi-gvercel# 在项目根目录执行vercel--prod项目根目录已配置vercel.json部署后即可通过 Vercel 域名访问。6.3 自定义配置编辑js/app/config.jsconstConfig{APP_NAME:助教反馈生成工具,MAX_FILE_SIZE:50*1024*1024,// 50MBFEEDBACK_PREVIEW_LIMIT:5,// 预览条数VIRTUAL_SCROLL_BUFFER:5,// 虚拟滚动预载行数// ...};七、总结这个项目是一个典型的「用最朴素的技术解决最实际的痛点」的案例。没有引入 React/Vue没有微服务没有数据库就是一个 HTML 一堆 JS 几个 CDN 库但它完成了助教工作中最繁琐的表格合并和反馈生成工作。统计一下~16,000 行代码前端 JS 12,819 HTML 2,910 服务端 26612 个 CDN 外部依赖67 个核心函数6 大功能模块课次/上传/反馈/导出/趋势/AI零构建部署如果你也是助教或者需要做类似的批量数据处理工具这个项目的架构思路或许能给你一些启发。附录项目结构表格工具网页/ ├── index.html # 入口页面2,910 行 ├── README.md # 项目说明 ├── vercel.json # Vercel 部署配置 ├── docs/ │ └── CODE_WIKI.md # 代码百科文档 ├── js/ │ ├── selection-handler.js │ └── app/ │ ├── config.js # 全局配置 │ ├── logger.js # 日志系统 │ ├── main.js # 主业务逻辑11,111 行 │ ├── lesson-number.js # 课次解析 │ ├── analytics.js # 图表统计 │ ├── ai-client.js # AI 客户端 │ ├── exempt-api.js # 免交名单 API │ ├── virtual-list.js # 虚拟滚动 │ ├── browser-utils.js # 浏览器工具 │ └── dom-utils.js # DOM 工具 └── server/ ├── exempt-http.mjs # 免交同步服务 └── exempt-http-deploy.mjs # 部署版服务如果你对这个项目感兴趣或有改进建议欢迎在评论区交流讨论。