项目状态:准备公开源码,欢迎接力。 受个人时间和运行资源限制,作者目前无法承诺持续托管在线服务或持续维护。 仓库保留应用代码、数据库结构、公开业务目录与验收记录,供自行部署、学习和继续开发。 本机与部分云端流程已有验收记录,完整生产部署尚未验收;不提供长期在线演示承诺。
公开前的隐私复核结果见代码与历史审计:当前文件和发布历史中的已知私人运营信息均已脱敏。
选课前,我们常常想知道一门课的作业量、课堂要求,以及老师的授课风格。 小石子希望把分散的课堂体验整理成有结构、可参考的反馈:通过教师与课程检索, 找到对应的课堂,再查看或提交经过审核的六维评价。
| 模块 | 已实现的能力 |
|---|---|
| 教师与课程 | 按学院检索教师、查看教师详情与开课关系 |
| 六维课堂反馈 | 考勤宽松度、给分宽松度、努力回报、作业轻松度、师生亲和力、教学质量 |
| 评价生命周期 | 提交、审核、驳回、修改、重新提交、作者撤回/删除 |
| 社区互动 | 评价点赞、每日签到与积分记录 |
| 账号与权限 | 学生邮箱准入、邮箱验证、数据库行级安全策略(RLS) |
| 管理与治理 | 受控管理员邀请、TOTP/AAL2、资料纠错和治理队列 |
| 访问保护 | 可选 Cloudflare Turnstile、预发布注册开关 |
公开展示设有至少 5 位评价者的门槛。公开投影限制身份字段,匿名展示不代表系统不保存账号关联。 课表推荐、教务通知、经验攻略入口当前关闭,AI 问答与模型服务已移除。
- 前端:React 19、TypeScript、Vite、Tailwind CSS 4、Motion、Lucide。
- 后端:Supabase Auth、PostgreSQL、RLS、数据库函数(RPC)。
- 可选服务:
server/提供 Express + Redis 缓存 API,默认关闭。 - 数据工具:Node.js 导入/校验脚本,Python 课表解析器。
默认架构为浏览器直连 Supabase,无需常驻 Node.js 应用服务器。数据库、认证和邮件服务仍需要运行资源。
需要 Node.js 22+、npm,以及一个由你控制的 Supabase 项目。以下命令适用于新克隆仓库, 不会自动连接作者的数据库,也不会自动导入教师数据。
git clone https://github.com/dlam12138/xiaoshizi.git
cd xiaoshizi
npm ci在新建、空的 Supabase 项目的 SQL Editor 中,依次整份执行:
supabase/upc-init.sql:应用表、17 个教学单位种子、权限策略、治理函数和导入函数。supabase/cloud/grants.sql:托管 Supabase 的应用角色授权。
已有业务数据的库应使用升级流程,避免重复执行初始化。仅创建表还不足以开放注册:
还需配置 Auth 的邮箱确认、回调 URL、before_user_created_hook、邮件投递和管理员 MFA。
具体步骤见托管迁移操作单。
该文档包含原作者的迁移记录,项目地址、账号和域名均需替换为自己的配置。
复制 .env.example 为 .env.local(PowerShell 用 Copy-Item .env.example .env.local),填写:
VITE_SUPABASE_URL="https://your-project.supabase.co"
VITE_SUPABASE_ANON_KEY="your-anon-public-key"
VITE_CACHE_API_ENABLED="false"npm run dev打开 http://localhost:3000。缺少配置时页面会提示配置缺口,不会回退到其他项目或展示模拟教师。
VITE_* 会进入浏览器构建,只能填写公开客户端配置;service_role、数据库密码和邮件密钥只放服务端。
可选:导入仓库中的教师与课程数据
复制 .env.import.example 为 .env.import.local,
填写自己的 SUPABASE_URL 和 SUPABASE_SERVICE_ROLE_KEY,然后先校验、再试运行、最后导入:
npm run import:upc -- data/upc/chemistry-2026-2027-1/import.json --validate-only
npm run import:upc -- data/upc/chemistry-2026-2027-1/import.json --dry-run
npm run import:upc -- data/upc/chemistry-2026-2027-1/import.json以上仅导入化学基线批次。多学院及身份补充批次的顺序、来源、稳定键和冲突处理见
数据导入说明。导入脚本一次接收一个 JSON 文件,不会自动展开通配符。
data/upc/release/ 是公开目录快照,不能直接作为导入脚本的输入。
配置好前端和导入两份环境变量后,可运行 npm run check:supabase 检查项目与密钥配置是否一致。
可选:使用本地 Supabase
仓库保留了原作者使用的 WSL/native 测试栈脚本,详见本机环境记录。 它依赖特定的 CLI 安装路径与运行环境,不是跨平台的一键安装器。 文档中“本机已初始化”的描述只针对原作者环境,新克隆仓库不带已有数据库、账号或环境变量。
课表解析还需要 Python 及 scripts/upc-timetable/requirements.txt 中的依赖。
原始 XLS/ZIP 不随仓库发布;使用已有的解析后 JSON 导入不需要重新解析原件。
仓库包含学期 2026-2027-1 的公开业务目录快照:
| 教学单位 | 教师身份 | 课程 | 开课关系 |
|---|---|---|---|
| 17 | 1,555 | 1,342 | 2,946 |
其中 1,382 个身份经公开官方 profile 核实,173 个为 tt- 前缀的课表来源身份。
这些数字不代表全校完整师资,也不能全部称为官方已核实教师;课表来源单位不等同于人事归属。
学期未标记为当前学期,数据也不会自动更新。
公开目录不包含用户账号、评价、积分、点赞、管理员凭据或数据库备份。 文件校验和与排除范围见目录发布说明及清单。 学校与学院信息的来源链接保留在学院字典,课表与身份核对过程见数据报告。
公开来源数据和学校相关标识不因代码公开而自动获得额外授权。复用时请保留来源、核对时效, 并单独确认数据和标识的使用权限。资料有误可通过 Issue 提供公开来源链接,请勿提交私人联系方式或学生身份信息。
npm run build
npm run previewdist/ 是静态构建产物,可部署到支持单页应用路由回退的静态托管或 Nginx。
npm run preview 用于本地检查构建结果。生产运行还需自行管理 Supabase、邮件投递、备份、
审核与纠错;即使前端使用静态托管,持续运营也需要有人维护。
仓库提供了 Docker 配置和云端部署准备文档。 Docker 配置只构建和托管前端,不会一起启动 Supabase;部署文档中的原有服务器、域名和路径不是公共服务承诺。 外部 SMTP、完整云端端到端测试、生产域名/TLS 及发布回滚演练仍需由部署者自行完成验收。
npm --prefix server ci
npm run verify:local该命令生成 SQL 并执行类型检查、根测试、前端构建及可选 API 的测试。
Python 解析器测试单独运行 npm run test:parser。
真实 Auth/RLS、邮件投递与部署环境的验收需要连接自己的 Supabase,不包含在上述离线检查中。
| 路径 | 内容 |
|---|---|
src/ |
前端页面、组件、配置与 Supabase 服务层 |
supabase/ |
数据库结构、RLS、RPC、种子与升级脚本 |
data/upc/ |
学院字典、解析后的导入批次与来源报告 |
scripts/ |
数据导入、SQL 生成、环境检查与验证工具 |
server/ |
默认关闭的缓存 API |
docs/ |
安全治理、数据、部署与验收文档 |
docs/project-history.md |
原 README 的阶段记录与详细验收索引 |
欢迎通过 Issues 报告问题、讨论接手维护或提出改进, 也欢迎提交 Pull Request。建议先说明具体场景、复现步骤和预期行为;涉及数据库变更时,请一并提供迁移与验证说明。
优先欢迎部署文档完善、跨平台启动支持、无障碍体验和公开数据纠错。 作者无法承诺固定响应时间;如果你愿意继续运营,可以 Fork 后独立维护,并清楚标明自己的服务与数据责任。
采用个人非商业源码许可 1.0:适用部分允许个人免费学习、修改和非商业使用,商业及组织生产使用须另行获得书面授权。
这是限制商业使用的源码可用许可,不是 OSI 开源许可证。许可仅覆盖授权人有权许可的部分; 既有贡献、依赖、公开数据及学校标识的权利边界见第三方与贡献归属。 商业授权或接力维护请通过 Issues 联系。