企业官网建设流程全解析

本项目是专为门诊场景设计的实时就诊指引 Web 系统，面向医院信息科、门诊部及导诊服务团队，解决患者在挂号后「不知道下一步去哪、等多久、是否要换楼换层」的核心动线困惑。系统以挂号 ID 为唯一入口，自动串联 HIS 叫号状态、检查预约时间、科室布局配置与平均接诊时长，输出结构化指引：包括当前所处环节（如初诊完成）、下一步目的地（心电图室 3F-208）、窗口编号（B07）、预计等待时长（约 12 分钟）及倒计时提示。支持多步骤流程（抽血→B超→回诊室）、大屏候诊模式（按科室展示排队人数），提供 Web 页面、CLI 命令行工具、RESTful API 三种交付形态。技术栈采用 Node.js + TypeScript + Express 后端，SQLite 模拟 HIS 数据源，前端为零框架原生 HTML/CSS/JS 实现，兼顾部署轻量性与医疗环境兼容性。

定位与能力范围

我们不做全院级 HIMS 替代，也不做移动端 App 封装。本项目的边界非常清晰：它是一套「挂号 ID 驱动的动线翻译器」，把后台系统里分散的叫号状态、预约记录、科室排班、空间布局等结构化数据，实时翻译成患者能一眼看懂的自然语言指引。不采集生物信息，不修改 HIS 记录，不介入医嘱或处方流程，只读取、只计算、只呈现。

适用典型场景包括：
- 患者扫码进入自助终端或打开候诊大厅网页，输入挂号 ID，即刻获得下一步动作；
- 导诊护士通过 CLI 快速查询某患者全流程节点，辅助人工引导；
- 门诊办调用/api/queue/:dept接口获取各科室实时排队人数，用于动态调度；
- 信息科用npm run init-db初始化模拟库后，直接基于 config.yaml 配置科室楼层、检查室坐标、平均耗时，无需二次开发即可适配本院物理动线。

它不是通用低代码平台，也不是 AI 问诊助手；它的价值锚点就落在「ID 输入 → 地点+时间+步骤」这一条确定性链路上，所有模块设计都围绕这个闭环展开。

核心功能

系统能力全部围绕「让患者少问一句、少走一步、少等一分」展开，不堆砌概念，只落地可感知的交互点：

• 单 ID 全流程牵引

  ：输入一个挂号 ID，自动拉取该患者在本次就诊中已发生的环节（如已签到、已缴费）、当前所处状态（如正在叫号队列第3位）、下一步明确动作（前往放射科 2F-112 做胸部CT）、以及该动作的时空预期（窗口 B12，预计等待 8 分钟，倒计时实时更新）；

• 多步骤路径显性化

  ：对含多个检查项的复诊患者（如：抽血→尿检→心电图→回诊室），系统不只显示“下一步”，而是渲染完整路径卡片流，当前步骤高亮，后续步骤灰显但可展开查看每步所需位置与预估耗时；

• 候诊大厅大屏模式

  ：启用/web/screen.html即进入全屏视图，按科室分组滚动展示排队人数、当前叫号、平均等待时长（如：内科-1诊室，排队 5 人，当前叫 12 号，均等 6 分钟），字体放大、色彩分区，适配 55 英寸以上公共显示屏；

• 脱敏与合规前置

  ：患者姓名自动脱敏为「张*明」，身份证号、手机号仅保留末四位，所有日志不落盘敏感字段，符合《医疗卫生机构网络安全管理办法》对前端展示的基本要求；

• 离线可用基础能力

  ：SQLite 数据库随包发布，npm run init-db后即自带模拟 HIS 数据，无网络依赖亦可启动本地服务并演示全流程，方便院内培训与应急演练。

使用与配置

上手只需三步：安装依赖、初始化数据库、启动服务。整个过程不依赖 Docker、不需 Nginx 反向代理、不强制 HTTPS，一台普通办公电脑即可跑通全链路。

cd patient-guide-web npm install npm run init-db npm run dev

服务启动后，默认监听http://localhost:3000，打开浏览器访问/web/index.html即可输入挂号 ID 测试。生产环境部署时，执行npm run build生成dist/目录，再运行node dist/api/server.js即可。

所有业务规则由config.yaml统一驱动，无需改代码：

database: path: "./data/his.db" api: port: 3000 departments: - name: "内科-1诊室" floor: "3F" room: "301" avg_duration_min: 15 queue_window: "A01-A05" - name: "心电图室" floor: "2F" room: "208" avg_duration_min: 8 queue_window: "B07-B09" layout: "3F": ["内科-1诊室", "内科-2诊室"] "2F": ["心电图室", "B超室"]

关键配置项均可被环境变量覆盖，例如将数据库路径指向 NAS 存储：
DATABASE_PATH=/mnt/nas/his.db npm run dev

科室平均接诊时长、楼层归属、窗口编号范围，这些才是影响指引准确性的核心参数，也是院内信息科最熟悉、最容易校准的数据项。

工程结构

目录即契约。我们把每个模块职责写进路径名，降低协作理解成本：

src/ ├── adapters/ # HIS 数据适配器：封装对不同厂商叫号接口的协议转换（如 HL7 v2.5 解析、WebSocket 心跳维持） ├── engine/ # 引擎层：等候时间估算引擎（基于当前队列长度 × 平均耗时 ÷ 开放窗口数）、路径指引引擎（根据科室布局配置生成楼层-房间-窗口三级定位） ├── api/ # Express 服务主干：路由注册、中间件（CORS、日志、脱敏）、CLI 入口（npm run cli 的实际执行体） ├── web/ # 前端资产：纯静态 HTML/CSS/JS，无构建步骤，/web/index.html 与 /web/screen.html 分别对应患者端与大屏端 └── utils/ # 工具集：含配置加载器（支持 YAML + 环境变量覆盖）、患者 ID 校验器（支持本院 8 位数字 ID 与 12 位条码 ID）、日志脱敏器

data/下的 SQLite 数据库含三张表：patients（模拟挂号信息）、queues（模拟叫号队列）、appointments（模拟检查预约），字段命名与常见 HIS 出参对齐，例如patient_id,dept_name,queue_number,scheduled_time，方便对照公开字段快速映射。

测试覆盖贯穿三层：Jest 覆盖 engine 层算法逻辑（如倒计时剩余秒数计算、跨楼层路径判断），Playwright 覆盖 web 端真实用户操作流（输入 ID → 点击查询 → 验证 DOM 中楼层号与倒计时文本），确保每次变更不破坏终端体验。

环境与运行

最低运行环境极其宽松，目标是在 Windows 10/11 笔记本、国产 Linux 信创终端、甚至老旧一体机上均可部署：

无外部服务依赖：SQLite 内嵌于进程，Express 自带 HTTP 服务器，所有静态资源内置。若需对接真实 HIS，只需在adapters/下新增适配器类，实现统一接口fetchPatientStatus(patientId): Promise<Status>，其余逻辑自动复用。

我们选择 SQLite 而非 PostgreSQL，并非轻视数据规模，而是因本系统本质是「状态缓存器」：每日就诊数据按需拉取、实时计算、即时丢弃，无需事务一致性保障，反而更看重零配置、免运维、易备份（整个data/目录复制即迁移）。

前端放弃 React/Vue，是因为导诊屏常驻运行在无 GPU 加速的工控机上，原生 JS 渲染更可控、内存占用更低、首屏加载更快（实测<100ms），且规避了框架升级带来的兼容性风险。

数据与扩展

所有业务数据均通过config.yaml与 SQLite 两层驱动，不写死代码，便于院内自主维护：

• 科室配置：增删科室只需编辑config.yaml中departments列表，重启服务即生效；

• 布局配置：调整layout映射关系，即可改变大屏科室分组逻辑；

• 模拟数据：data/下 SQL 文件可手工编辑，或用npm run cli -- list查看当前患者列表后，针对性构造测试数据；

• 接口扩展：新增 API 端点只需在src/api/routes.ts中添加一行router.get('/api/new-endpoint', handler)，无需重写服务主干。

未来可扩展方向明确而克制：
- 增加微信公众号菜单跳转能力（通过/web/index.html?patientId=xxx带参打开）；
- 输出 FHIR 标准 Observation 资源，供院内临床数据中心订阅；
- 在engine/中接入简单规则引擎，支持「若检查预约时间距现在 <30 分钟，则优先提示前往检查室」等条件逻辑。

但我们坚持一条铁律：任何扩展不得增加前端框架、不得引入新数据库、不得要求管理员学习新配置语法。所有改动必须能在config.yaml或 SQL 文件中完成。

项目地址：
https://github.com/nexorin9/patient-guide-web