Twinsia · 项目笔记

小型 IoT 数字孪生系统（~/twinsia）：面向居家 / 养老院 / 病房的健康监测，把 Zigbee 传感器 + 智能床垫统一接入，管理状态与历史，供上层 2D 看板与 3D 孪生稳定消费。

定位

• 数据接入：MQTT（Zigbee2MQTT）+ TCP（智能床垫）+ 内置模拟器（无需真机跑通全链）。
• 统一领域模型：每个适配器产出 NormalizedMessage；业务层只认 Device / Capability / DeviceState / TelemetryRecord / DeviceSource。
• 状态 + 历史：device_states（设备×能力唯一）与 telemetry（按能力 persistHistory 开关）。
• 对外：REST 快照 + WebSocket 增量（state.updated / device.availability / 告警）。
• 展示：Mantine + ECharts 看板；数据驱动 React Three Fiber 3D 场景（门开合 / 床占用 / 存在脉冲），内置场景编辑器、设备「附魔」绑定、/bigscreen 大屏。

架构与数据流

MQTT(Z2M) / TCP床垫 / 模拟器
  → 适配器(decoder → normalizer → deriver)
  → IngestEnvelope(NormalizedMessage)
  → 设备解析 / 能力校验
  → 状态归约器
  → device_states / telemetry / WebSocket (+ Alarm 域)
  → REST(快照) + WS(增量) → React(Mantine + ECharts + R3F)

技术栈

• Monorepo（Bun workspaces）：apps/server（Elysia 后端）、apps/web（React 前端）、packages/contracts（领域契约）、packages/shared。
• 后端：Elysia（REST+WS）+ MQTT.js + Drizzle ORM + PostgreSQL。
• 前端：React 19 + Vite + Mantine 9 + TanStack Query + Zustand + ECharts + R3F/Drei。
• 基础设施：Docker Compose（postgres / mosquitto / zigbee2mqtt / app）。

核心设计要点

• 接入层抽象：新协议 = 实现 ProtocolDecoder / PayloadNormalizer / CapabilityDeriver 三接口 + 探针表注册；归一化是显式映射表，哨兵值 / 降噪在归一化层完成。
• 契约先行：能力 / 事件 / 接口先落 packages/contracts，前后端 import type { App } from "@twinsia/server"（Eden 端到端推导），禁止重复定义类型。
• 阶段一只读：无「系统 → 设备」下行指令；告警 / 派生能力 / 分析属监测侧（对数据做判断并产生记录 / 推送），允许实现。
• 红线：协议只在适配器层；业务层不碰传输细节；前端不直连 MQTT/TCP；不过度工程（不引入微服务 / K8s / GraphQL / 消息总线 / 规则引擎）。
• 范式单一：设备→场景唯一权威 device.sceneId；业务数据只经 IngestEnvelope；设备分组只经 spaceNodeGroups.ts 派生。
• 床垫协议：已启用 HT msgpack（0xABCD + CRC8 + MessagePack）；v1-demo（MAT）已移除；IOMTea 字段仅历史参考；sleep_state 为启发式（非临床用途）。

近期重点与路线图

原则：不删除、不回退已实现功能（冻结 = 停止新增，≠ 移除）；增量优先，复用既有契约 / 管道 / 派生器。先做跨场景通用人侧地基，具象功能作其消费方：

• P0：CareRelation（照护关系）/ CareEvent（事件存储）/ Notification（通知接口）。
• P1：呼叫一等事件、班次交接区、人员健康档案、告警详情上下文、睡眠/健康报告、虚拟人落位孪生、床垫浮窗、大屏联动。
• P2（按需）：Zigbee 真机标定、区域级权限 + WS 按区域过滤、移动端推送、报告模板化。

边界与不做

• 删除 / 重构已有功能；系统→设备反向控制、联动规则、自动化编排；多租户 / SSO / OIDC；临床诊断 / 治疗建议 / 评分算法；分布式 / 时序引擎替代 / 消息总线。

部署与门禁

• 单目标部署：build once → deploy once。推 v* tag → CI 构建单镜像（server + web）→ GHCR → SSH 唯一主机 → docker compose up -d → /api/health 健康检查，失败自动回滚上一镜像。
• 预部署 pg_dump 备份（失败即中止）；回滚只退镜像、不回滚 DB schema（迁移类事故需手动迁移 / 从备份恢复）。
• 门禁：Husky（pre-commit lint-staged + typecheck；pre-push 全量 check：typecheck/lint/test/build/db:check/docs:check/device-packs）+ commitlint；CI 在 PR 跑完整 check；pre-push 自动 db:smoke（临时 PostgreSQL 全链迁移 + schema 断言）。

情报来源

• ~/twinsia/README.md、AGENTS.md、TODO.md、docs/02-设计/*、docs/03-产品与路线/*。

更新动向

• 2026-08-28：建档笔记，记录定位 / 架构 / 技术栈 / P0-P2 主线与部署门禁。