Dorm Mate — 宿舍协同系统

帮一个班级/年级完成「生活习惯问卷 → 自由组队 → 分寝建议 → 发布结果」的完整流程。 系统只为辅导员提供分寝建议，最终名单始终由辅导员确认后发布，不为学生开放在线抢床位。

起源：2026 年 9 月为一所职业院校工业机器人专业 4 个班搭建，辅导员实际使用完成了新生分寝协同。现已剥离真实数据并开源。

功能

学生端

• 名单核验登录：班级 + 班级填写码 + 姓名 + 学号四重匹配，绑定本人云开发账号
• 生活习惯问卷：作息、噪音（游戏/开麦/外放/键盘）、吸烟与烟味接受度、打呼、温度、卫生、学习、访客、矛盾处理方式等 40+ 个字段
• 自由组队：发起/接受邀请、2–3 人已确认小组整体补位、4 人全员确认后锁定为固定组
• 查看已发布的寝室号与室友

辅导员端

• 完成率看板、学生问卷摘要（学号自动脱敏显示）
• 一键生成分寝建议，权重可调（默认：吸烟 5 / 作息 4 / 噪音 4 / 卫生 2 / 打呼 2 / 游戏 2 / 学习 1）
• 强冲突检测：吸烟习惯与烟味接受度不相容的学生不会被安排进同一间新寝室
• 已确认组队不拆散；组队内部已有的冲突保留但明确显示复核提醒
• 特殊床位需求审批与优先满足；跨班/未满员情况进入待处理清单
• 发布结果后学生的既有分配不会因系统升级而变化

分寝算法（shared/allocation-core.js）

1. 同班、同性别独立分配；四人固定组直接保留。
2. 剩余组队单元按人数从多到少，以每个单元为种子，穷举可凑满 4 人的组合。
3. 两两计算加权生活习惯兼容分（0–100），存在吸烟硬冲突的组合直接淘汰。
4. 取兼容分最高的组合成寝；无法凑满的进入待处理清单，不会漏人。
5. 床位分配使用可复现的种子随机：有审批特殊需求的学生优先匹配对应床位，其余随机。

兼容分、冲突规则均为纯函数，带完整单元测试（含 200 人规模的性能回归），可以脱离腾讯云单独复用。规模性能：全年级 1600 人（每班 400）约 5 秒完成；极端数据触发单班 8 秒时间预算后自动降级为贪心装箱，保证辅导员总能拿到结果，而不是整班挂起。

架构

静态网页（原生 HTML/CSS/JS，构建时注入配置）
        │  CloudBase WebSDK 匿名登录 / 辅导员密码登录
        ▼
CloudBase PostgreSQL（7 张业务表 + 安全存储过程 RPC，行级安全保护）

• 网页通过数据库**安全函数（RPC）**直接完成全部业务：所有写操作走 SECURITY DEFINER 存储过程并在事务中完成，数据库从登录令牌读取真实用户 UID，无法通过伪造前端参数冒充他人，关键动作写入审计表。
• cloudfunctions/dorm-api 是预留的服务端入口（Node.js 20 + zod 校验），当前网页不依赖它，部署时可以暂不部署云函数。
• 网页与云函数共享同一份分寝核心代码（shared/ → 构建时同步到 cloudfunctions/，有测试保证两份一致）。

拿到代码后怎么用

路线 A：5 分钟本地体验（不注册任何账号）

前置要求：Node.js 20 或更新版本（node -v 能查到版本即可）。无需 Python、无需先 npm install。

npm run serve

浏览器打开 http://127.0.0.1:8770/：

• 学生端：班级下拉选一个（如 工业机器人1班）、填写码填 01，姓名和学号随便填，即可体验问卷、组队、邀请的完整流程。
• 辅导员端：演示密码 fdy2026（只在本机演示模式有效，登录页也会提示；正式部署后以你自己设置的密码为准）。
• 演示模式的组队是单机模拟：邀请对象是内置示例同学，再次点击可模拟对方接受；真实的多人联机组队需要走路线 B 部署。

演示数据只保存在浏览器 localStorage 里，不连接任何服务器（云端 SDK 也是点进云端功能时才按需加载）。页面打不开时，先关掉旧的终端窗口再启动——端口被占用会给出明确提示。npm run build 构建出的 dist/ 在未配置环境时同样是演示模式。

路线 B：完整部署到腾讯云 CloudBase（免费档可跑）

详细步骤见 docs/CloudBase免费部署步骤.md，概要：

1. 注册腾讯云并开通 CloudBase，创建环境（地域选上海），开启「匿名登录」和「用户名密码登录」，在「静态网站托管」完成首次开通，创建辅导员账号并记下其 UID。
2. 复制 .env.example 为 .env.local，填入环境 ID、地域和辅导员 UID。
3. npm install 安装 CloudBase CLI（就在开发依赖里，不要用 --omit=dev；国内网络慢可加 --registry=https://registry.npmmirror.com）。
4. npx cloudbase login 完成浏览器授权登录（全新电脑必做的一步，换电脑后要重新登录；用 npx cloudbase env list 能列出环境即已登录）。
5. node scripts/apply-database.mjs 建表（自动把 .env.local 中的 UID 注入 SQL）。
6. 名单按 data/students-template.csv 整理为 data/students.csv，先用 node scripts/import-students.mjs data/students.csv --dry-run 试运行检查，确认无误后去掉该参数正式导入。
7. npm run build，然后 node node_modules/@cloudbase/cli/bin/tcb hosting deploy dist / -e 你的环境ID 发布静态网站（网页全部业务走数据库 RPC，不依赖云函数）。
8. 设置辅导员密码（Windows 自带 PowerShell 即可）：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/set-counselor-password.ps1

部署后第一周怎么用

1. 辅导员把班级填写码告诉学生（如 1 班填写码 01）。
2. 学生用手机打开学生端，通过名单核验后填写生活习惯问卷。
3. 学生互相邀请组队，2–3 人确认后整体补位，4 人全确认锁定为固定组。
4. 辅导员在工作台查看完成率，审批特殊床位需求。
5. 一键生成分寝建议，检查强冲突提醒与未满员清单，可手动调整。
6. 确认后发布结果，学生在学生端看到自己的寝室号与室友。

业务规则（组队优先级、匹配权重、隐私红线）详见 docs/试点业务规则.md。

数据隐私

• 仓库不含任何真实学生数据：名单文件、系统截图、环境 ID、账号 UID 均已移除，测试与文档全部使用示例数据。
• .env.local、data/*.xlsx、部署状态目录已在 .gitignore 中排除，克隆后填入自己的配置即可。
• 学生问卷仅用于分寝参考；学号在管理端展示时中间位自动打码。
• 系统不给吸烟学生贴「风险」「违规」标签，只在双方自愿填报的基础上比较生活习惯相容度。

项目结构

├── index.html            # 总入口（学生/辅导员分流）
├── student/              # 学生端页面
├── admin/                # 辅导员工作台
├── shared/               # 前后端共享：分寝核心、API 封装、配置
├── cloudfunctions/
│   └── dorm-api/         # 云函数（接口路由 + 分寝核心）
├── database/             # 12 个 PostgreSQL 迁移（表、RPC、行级安全）
├── scripts/              # 建库、构建、验收、名单导入等脚本
├── tests/                # node:test 单元测试
├── data/                 # 名单导入模板（CSV）
└── docs/                 # 部署步骤与业务规则说明

License

MIT