# TimeKeeperDesk **Repository Path**: a1664573841/TimeKeeperDesk ## Basic Information - **Project Name**: TimeKeeperDesk - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-05 - **Last Updated**: 2026-08-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 拾光台 · 班主任工作站 为周南望城学校廖老师定制的班主任工作站，默认班级为初一（7）班。打开即可使用，不需要账号、登录或应用密码；数据保存在本机 SQLite 数据库和附件目录中。 ## 技术结构 - 前端：React 19、TypeScript、Vite、React Router、TanStack Query - 服务端：Fastify、Zod - 数据库：SQLite、Drizzle Schema 与版本迁移 - 文件：本地 `data/attachments/`，支持教学 PPT、Word、PDF、图片、音频、视频等资料 - AI：服务端 DeepSeek / OpenAI 兼容接口，默认 DeepSeek V4 Flash 浏览器只保存临时界面状态。学生、成绩、作业、请假、行为、谈话、家校沟通、提醒、座位方案和工作记录全部通过业务接口保存到规范化数据库，不再整包覆盖 JSON。 桌面侧栏固定为“今日、学生、教学、班务、AI、系统”六个中心，原有页面地址继续有效；中心内的具体功能通过顶栏下方二级导航切换。手机端使用“今日、学生、AI、教学、全部”五项底栏。 ## v2.1 智能排座 “班务 → 智能排座”已升级为随机约束排座：每次使用独立随机种子生成大量候选方案，再根据硬约束与软偏好择优，不再按固定姓名或属性顺序排列。同一个随机编号可复现同一结果，重新随机会得到不同方案。 支持自定义行列、过道和空座；可锁定单个或全部座位、拖拽互换，手机端也可依次点选两名学生完成交换。硬约束支持禁配同桌和指定学生必须靠前，软偏好支持视力与靠前照顾、身高前低后高、同桌性别均衡、避开上次同桌和尽量更换原座。系统会自动对比最近一次保存的方案，并显示方案综合分、硬约束、照顾完成率、混合性别同桌、重复同桌、锁定数和未满足原因。 50 名学生默认自动适配为 8×7 网格并完整显示空座，不再因容量不足而无法生成。历史方案会完整保存随机参数、优化选项、约束和锁定位置，可载入为副本、删除、打印或导出高清 PNG；班级和学期切换时会清空未保存草稿，避免跨班误保存。 ## v2.0 智能教学与班级运营 - `教学 → 资料知识库`：PDF、Word、PowerPoint、TXT 和音频转写稿统一分块索引，支持中文全文检索与带原文定位的引用问答。PDF 保留页码，PPT 保留幻灯片号，Word 保留章节位置；回答只能使用老师选择的已解析资料。 - `教学 → AI 作业批改`：建立批改批次后，可上传 JPG/PNG/WebP 原稿或直接手工录入。图片默认先由服务器本地 Tesseract 识别，本地失败时才尝试可选视觉模型；DeepSeek V4 Flash 继续负责识别文字后的错因分析。AI 判断先进入草稿，老师核对分数、评语和错因后才保存；确认数据可汇总为讲评要点，导出可编辑 PPTX 讲评课件和 Word 分层练习。 - `班务 → 考勤·值日·量化`：每日考勤支持正常、迟到、缺勤、请假和早退批量登记；值日可按日期生成并逐项完成；班级量化支持自定义规则、加减分流水、排行榜及 Excel/Word 导出。 上述模块均使用现有班级与学期范围、10 条分页、版本冲突保护、审计记录和 ZIP 完整备份。AI 不可用时，资料检索、手工作答、考勤值日量化以及基于规则的分层练习仍可继续使用。 ## Windows 一键运行 1. 双击 `启动拾光台.bat`。 2. 首次运行会安装依赖、迁移旧数据、完成生产构建并打开浏览器。 3. 本地地址为 `http://127.0.0.1:3210`。 4. 双击 `停止拾光台.bat` 停止服务，数据不会删除。 首次 v2 启动会先把旧版工作区快照备份到 `data/backups/`，再在事务中迁移。迁移失败会回滚，原快照不会丢失。 ## 开发运行 ```bash npm install npm run setup npm run dev ``` 开发模式中，Vite 页面使用 3210 端口，Fastify API 使用 3211 端口并由 Vite 自动代理。 ## 生产运行 ```bash npm run build npm start ``` 生产模式由 Fastify 同时提供 API、附件鉴权读取和 Vite 静态文件。 ## AI 配置 编辑 `.env.local`： ```dotenv AI_PROVIDER=deepseek AI_BASE_URL=https://api.deepseek.com AI_API_KEY=你的_DeepSeek_API_Key AI_MODEL=deepseek-v4-flash AI_THINKING=disabled ``` 如图片批改需要使用单独的视觉模型，可增加 `AI_VISION_MODEL`。也可以安装 Tesseract 作为完全在服务器本地运行的 OCR 兜底；中文作业建议同时安装 `chi_sim` 和 `eng` 语言包： ```dotenv GRADING_OCR_MODE=local-first TESSERACT_BIN=tesseract TESSERACT_LANG=chi_sim+eng TESSERACT_TIMEOUT_MS=60000 TESSERACT_OUTPUT_LIMIT=262144 TESSERACT_MAX_CONCURRENCY=2 TESSERACT_QUEUE_LIMIT=8 ``` 默认 `local-first` 会先在服务器本地识别，只有本地 OCR 失败时才尝试视觉模型，避免为 DeepSeek V4 Flash 每张图片发送一次不受支持的请求；如确有可用视觉模型，可以改为 `GRADING_OCR_MODE=vision-first`。Tesseract 只读取当前上传的作业图片，命令使用无 Shell 参数调用，并限制输入大小、执行时长、输出量、并发数和等待队列。能力检测也会核对配置的语言包是否存在。识别来源和模型会写入 AI 运行日志；本地 OCR 结果仍必须由老师核对确认。未安装或识别不到文字时，页面会提示改用更清晰的图片或手工录入。 音频自动转写为可选的本地能力，服务器安装 ffmpeg、ffprobe、whisper.cpp 及模型后配置： ```dotenv FFMPEG_BIN=ffmpeg FFPROBE_BIN=ffprobe WHISPER_BIN=whisper-cli WHISPER_MODEL=/opt/models/ggml-base.bin ``` 未安装本地转写组件时，可在知识库直接粘贴人工转写稿建立全文索引，不影响 PDF、Word、PPT 和 TXT。 API Key 只在服务端读取，不进入浏览器、数据库、日志或构建文件。服务端按当前班级、学期和可选学生读取成绩、作业、请假、行为、谈话、家校沟通、提醒及工作留痕摘要，先匿名化姓名，不发送家长电话、住址或附件。AI 输出必须先预览和确认，不能直接写入业务记录。 “系统设置 → AI 服务”可以查看当前服务商和模型并执行最小化连通测试。AI 助手支持全班或单个学生范围、二十种生成能力、Markdown 排版、数据依据展示、Word 导出，以及确认后保存到工作留痕。其中家校沟通提纲、家长通知、问题说明、回访建议和阶段总结可以带入沟通记录，由老师修改后确认保存。 “AI 对话”提供可连续追问的传统聊天界面，可新建、重命名和删除历史对话，也可选择是否读取当前班级的匿名摘要。对话与助手结果都能导出为适合继续编辑的 Word 文档。 ## 备课与课件 “教学 → 备课与课件”允许独立维护任教课程，因此除班主任班级外，还可添加其他授课班级、学科和学期。新增或编辑教案会进入宽屏备课工作室：左侧管理课题、学情、教材页码和授课信息，中间按“教学目标、教学过程、学习评价、课件大纲、作业与反思”分区编辑，右侧固定显示教材资料和 AI 辅助区；手机端自动变为单列编辑。 编辑器支持 Markdown 编辑、阅读和分栏预览，常用标题、列表、表格与活动模板可一键插入。每个分区都有“AI 强化本节”，会自动勾选适合当前分区的目标字段并生成针对性指令；结果必须先预览，再选择字段应用，可随时撤销，不会直接覆盖已经保存的教案。AI 对话中的讨论仍可通过“转为备课”进入待审核草稿。 PDF 教材上传后会在服务器本地建立逐页文本索引。老师可精确选择教材页码，AI 只读取所选页面并在结果中列出引用页和生成时间；单次最多选择 20 页，避免把整本教材和无关附件发送给模型。系统不会虚构“教材原声”或附件内容，未提供音频时只会给出教师朗读或另行准备音频的建议。 资料库支持 PPT/PPTX、Word、Excel、PDF、图片、MP3/WAV/M4A/OGG 音频、MP4/WebM 视频、TXT 和 ZIP，单文件最大 200 MB；可按课程、教案、分类和标签归档，音视频可在页面内播放。保存教案后可以导出适合打印修改的 Word，也可选择“深海蓝、靛青、暖橙、极简白”四种课件主题并导出完全可编辑的 PowerPoint `.pptx`。PPTX 由服务器本地生成，不要求额外的 Canva 或 Gamma 账号，也不会把教学资料发送给其他课件平台。 ## 教学日历与课表 “教学 → 我的教学课表”是跟随老师的全局课表，不受当前班主任班级或学期切换影响。桌面端采用清晰的“节次 × 星期”方块网格，手机端自动切换为按日议程；默认内置早读、七节正课、午间辅导、午自习、课后服务和晚自习共 12 个参考时段，名称、数量及上下课时间均可新增、编辑、删除和重新排序。 每个格子都能直接登记任教课程，也可以只填写“培优、值班、会议”等自由安排。课表支持固定重复规则、按周独立调整、复制上周、恢复固定课表、周末显示和高亮模式；高亮会区分今天、当前时段、下一节课、冲突、缺教案和缺课件。修改本周不会连带改变其他周，历史周也会保留当时的节次时间快照。当前显示周可一键导出为 Excel，文件包含可直接打印的教师周课表和完整课表明细两个工作表。 任课课程可以关联现有班级，也可以仅填写自由班级名称。关联后，月历会汇总该班级的作业、考试和提醒；点击课表格子可创建或打开关联教案、查看课件完整度、填写课后反思并标记已授课。停课、调课、临时加课、课程作业、测验和教学提醒继续集中在月历管理，系统按上海时区动态展开，冲突或备课缺失只做明确提示，不会自动修改数据。 AI 课前准备助手可检查所选日期范围内的备课缺失项和冲突，生成 Markdown 备课清单。它只读取课表、教案状态和资料数量，不会读取文件正文；输出仍需老师审核，不会自动创建或覆盖记录。 ## 管理与办公导出 “家校沟通中心”按学生、监护人、渠道、时间和状态管理沟通记录，支持附件、回访提醒、学生成长时间线、Excel/Word 导出和 AI 草稿。 “管理中心”集中汇总学生、作业、提醒、请假、行为、谈话、家校沟通和工作留痕，可搜索、修改、归档或删除；原业务页面入口保持不变。日常清单和月度未交作业汇总提供 Excel、Word 导出，不再使用 CSV 作为办公交付格式。 学生名单、月度未交汇总、作业逐人登记、管理中心以及教案和课件资料库均默认每页显示 10 条，筛选后自动回到第一页；Excel/Word 导出仍包含完整筛选结果，而不是仅导出当前页。 ## 界面主题 右上角调色板或“系统设置 → 界面主题”可切换淡雾蓝、纯净白、雾松绿、暖米白和夜墨黑。每套主题都会同步调整页面背景、侧栏、卡片、表单、状态色与图表色；选择仅保存在当前浏览器中，不影响业务数据和其他设备。 通知面板支持“一键全部已读”。已读状态按班级和学期持久保存；当关联作业、回访或提醒内容发生变化时，会以新通知重新出现。 ## 数据和完整备份 - 数据库：`data/zhiban.sqlite` - 附件：`data/attachments/` - 自动迁移备份：`data/backups/` “数据中心”可导出包含数据库、附件和版本清单的 ZIP 完整备份。恢复流程为“上传预检 → 检查数量 → 输入确认 → 自动安全备份 → 恢复”。 班级和学期采用回收站模式。普通删除前会显示关联数据数量并要求输入完整名称，最后一个有效班级或学期不可删除；永久删除还需输入带前缀的确认文本，系统会先自动生成完整 ZIP 安全备份。 ## Docker ```bash docker compose up -d --build ``` 容器对外映射 3210 端口，并把 `./data` 持久化到宿主机。应用本身不含登录系统；部署到服务器时请通过 Nginx、VPN 或访问网关限制访问范围。 ## 检查 ```bash npm run typecheck npm run lint npm test ``` 测试覆盖成绩排名、空分处理、日期、排座约束、迁移、API 保存、版本冲突、单双周课表、周课表隔离与复制、旧节次安全升级、时间格式与重叠校验、停调加课、课程冲突、AI 匿名化与越权阻断、教材跨课程访问阻断、PDF/Word/PPT/TXT 解析与引用、作业图片校验与老师确认、竞赛排名、讲评 Office 导出、考勤批量登记、值日、班级量化，以及生产 JS/CSS 资源。