海外园区宿舍管理系统：给上万人混住的园区做一套住得下、查得清的平台

这是我目前做得最完整、也最能说明「我能干什么」的一个系统：面向印尼中苏拉威西工业园区自建宿舍的企业级管理平台。8 栋楼、近 3,000 张床位、上万名中方与印尼籍员工混住，已经上线在跑。

🔗 在线演示#
管理端 — https://dm.free—china.com　|　员工自助端 — https://dm.free—china.com/m（手机打开，或把浏览器调成手机宽度）
演示账号密码统一 dorm@2026：

账号角色建议先看
admin 系统管理员全部功能，含集成对接与批量导入
dorm.chief 宿舍主管全园区视角、审批、降标
warden.a A 栋宿管 只看得到 A 栋 —— 和 admin 对比同一张看板的数字差异
hr01 / ehs01 人力资源 / 安全环保权限收窄后的界面
员工自助端不发密码，用工号 + 手机验证码登录（短信渠道未接入时验证码直接回显）。演示工号：CN00001（中方，中文界面）、ID00003（印尼籍，Bahasa 界面）。
演示环境数据全部为程序生成的模拟数据，无任何真实人员信息。

账号	角色	建议先看
`admin`	系统管理员	全部功能，含集成对接与批量导入
`dorm.chief`	宿舍主管	全园区视角、审批、降标
`warden.a`	A 栋宿管	只看得到 A 栋 —— 和 `admin` 对比同一张看板的数字差异
`hr01` / `ehs01`	人力资源 / 安全环保	权限收窄后的界面

它不是练手项目。它要解决的是一组真实的、错了要出事的约束。

为什么市面上的方案都不能用#

搜「宿舍管理系统」，开源的基本都是学生宿舍课程设计。海外工业园区的约束和它们完全不是一回事：

约束	后果
上万人且流动快	入职、离职、休假、调岗天天发生，人工台账三天就失真
多国籍混住	中方与印尼籍的作息、饮食、语言、宗教都不同，分区不是”可选功能”
合规压力是实的	消防疏散要的是此刻准确的在住名单；护照 / KITAS 过期等于非法居留
数据一旦不准就全废	人走了床位没释放，一个月后系统显示满床、实际空着几百张

最后一条是最致命的。宿舍系统的核心竞争力不是功能多，是数据准。 整套设计都是围着这一点转的。

五条地基设计#

这五条是改动代价最高的部分，也是这个系统和”能跑就行”的区别所在。

1. 最小可分配单位是「床位」，不是房间#

上下铺各自独立成一个铺位；夫妻房的双人床也按两个铺位建模，保持「一人一铺位」这个不变量。

把房间当最小单位的系统，三件事全做不了：三班倒排不了班次隔离、事故追溯查不到具体是谁睡哪、空床数永远对不上。

2. 入住是「带时间区间的记录」，永不覆盖#

调宿 = 关掉旧记录 + 新建一条新记录，两条都留着。一张床的历史，就是这张表的多行。

这个决定后来救了很多场景：事故追溯、传染病密接排查、警方与劳工部检查——全靠它。密接排查功能几乎是免费得来的：查某人某时间窗内的同房间 / 同楼层接触者，时间区间模型天生就支持。

3. 三个「人数」是三件不同的事#

园区里「四人间实际住三人」是常态（空调制冷量不够、面积不足、主管批准降标）。所以人数必须拆成三个字段：

	含义
标称规格	「四人间」就是 4
核定人数	这间实际按几人住，可以是 3
物理床位	屋里真有几张床

降标后多余的床标记为停用并记录原因，不再被排人进去，但仍然留痕。混成一个字段的系统，第一次降标就开始对不上账。

4. 住宿的人不只有员工#

还有家属随迁（配偶、子女）、长期访客、实习生、承包商工人。消防名单、房间占用、门禁都必须算上他们。这一条决定了人员模型不能直接复用 HR 的员工表。

5. 所有业务口径都在配置表里，不写死在代码#

国籍、部门、职级（含各自的休假周期）、班次、宗教、承包商、18 种房型、17 条排宿规则的松紧——全部在设置页改，改完立即生效，不用改代码、不用重启。

园区的规矩会变，而且是由不写代码的人来定。口径写死在代码里，等于每次调整都要排一次发版。

排宿规则引擎#

17 条规则，每条三档：关闭 / 仅提醒 / 强制拦截。

男女不同房、夫妻房须有配偶关系、家属须与挂靠员工同房、房型职级门槛、上下铺限制（有人不能睡上铺）、无障碍需求、国籍归属、同房同班次、同房同部门、自有与承包商不混住、饮食禁忌一致、吸烟习惯一致、房内语言可沟通……

工程上关键的一点是硬约束和软约束走不同的返回：

硬约束不通过 → 400 直接拦下，带 force 参数也越不过去
软约束不通过 → 409 带提醒返回，宿管确认后可以继续

这个区分很重要。全做成硬拦截，现场会想尽办法绕过系统；全做成提醒，规则就等于没有。

国籍策略还要逐级继承（房间 > 楼层 > 楼栋），才能表达「一二层印尼籍、三四层中方、五六层不限」这种楼层级混住。

让宿管真的愿意用#

系统再严谨，宿管不用也是废的。所以做了几个很”土”但有效的东西：

楼层平面图：走廊两侧排布，房间格子里画出真实床位小方块，哪张床空着一眼看到，可按入住率 / 国籍分区 / 房型三种口径着色
楼栋剖面图：一屏看完全园区
房门二维码：管理端可整层批量打印，员工扫码直达自己房间并一键报修
夜间查寝自动生成该层在住点名清单，不用手抄

15 类主动告警#

这些都是「不主动查就发现不了，但迟早会出事」的地方：

离职未退宿（数据失真头号原因，支持一键批量清退含物品结算）、证件即将到期（护照 / KITAS 过期 = 非法居留）、报修超 SLA、房间超住、夫妻房异常、家属未与员工同房、休假即将到期、违规积分超限、访客超期未离开、物品未归还、已分配超期未入住、状态口径不一致、降标与床位不一致、功能房被占住……

这一块才是系统的价值所在。 录入功能谁都会写，能主动告诉你”哪里已经不对了”的才叫管理系统。

两拨用户，两种登录#

管理端几十人，账号密码；员工上万人，不发密码——工号 + 手机验证码，或企业平台扫码。

员工自助端在 /m，与管理端完全隔离：独立 token、独立路由、独立样式。越权在入口一次堵死——员工 token 只能访问 /api/self/*，其余一律 403。

权限模型是 模块:动作 的权限点，外加楼栋数据范围贯穿看板 / 花名册 / 疏散 / 全部告警。A 栋宿管和宿舍主管打开同一张看板，看到的数字是不一样的。

集成：按能力建模，不按厂商建模#

预留了 15 个集成平台占位（企业微信 / 钉钉 / 飞书 / Teams / 泛微 / 致远 / 用友金蝶 HR / 通用 OA / 海康威视 / 大华 / LDAP / 短信 / 邮件 / WhatsApp / 通用 Webhook），但不是按厂商写 15 套代码，而是抽象成六种能力：SSO、人员同步、消息推送、审批流、视频接入、门禁联动。

通知中心同理：业务代码只管”发生了什么”，不管发到哪个平台；按收件人国籍自动选中文 / Bahasa / English；一条事件扇出到多渠道，渠道未启用时记录原因而不是静默丢弃。

视频接入这块的边界是刻意划的：楼 / 层 / 房间的空间树上可以挂设备（摄像头、门禁、电表），但主应用只存”空间↔设备”的映射和鉴权，不碰码流——码流走独立网关服务。园区网络有内网限制，监控流不能出园区，这个边界一开始就得留出来。

技术栈#

层	选型
后端	Node.js ≥20 · TypeScript · Fastify 5 · Prisma 6（单进程，无外部依赖服务）
数据库	SQLite / PostgreSQL（schema 按 PG 兼容写法，切换只改 provider）
前端	React 18 · Vite 6 · Ant Design 5（管理端与移动自助端同一 SPA）
认证	自实现 JWT（HMAC-SHA256）+ scrypt
语言	中文 / Bahasa Indonesia / English 三语，界面与通知模板都是

认证有意没用第三方库：JWT 签验和密码哈希用 node:crypto 手写不到 80 行，行为完全可控，也少一层供应链风险。

这个项目说明了什么#

我的本职是网络、系统和信息化交付。这套系统真正体现的能力，其实和写代码本身关系不大：

能把现场的模糊需求翻译成不会崩的数据模型——床位而不是房间、时间区间而不是覆盖、三个人数字段而不是一个
知道合规要求会落到哪张表上——消防名单、证件到期、密接排查，都是设计时就想清楚的，不是后来补的
懂园区的实际约束——内网限制、监控流不出园、多国籍混住、不写代码的人要改口径
能自己把它交付到上线，而不是只画个方案交给集成商

这也是我做园区信息化项目十几年攒下来的东西，只不过这一次，是我自己一行行写出来的。