文章 on 紙上集

Operations and Hospital Collaboration Guide

Sat, 05 Sep 2026 00:00:00 +0000

Traditional Chinese version: [[content/posts/operations-hospital-collaboration-guide]]

1. Purpose

This guide is intended for the TAMS Backend, Hospital Integration, RMF/Robot Integration, QA, and Operations teams. It describes the actual boundaries of the current Modular Monolith, how Operations and Hospital communicate, and the rules that all contributors must follow when changing the codebase.

The system is still deployed as one NestJS process, one npm package, and one versioned release. Modules communicate through NestJS dependency injection and in-process method calls. There are no internal HTTP calls, message brokers, or additional worker frameworks between modules.

Operations 與 Hospital 協作開發指南

Sat, 05 Sep 2026 00:00:00 +0000

English version: [[Users/rubinette/Vaults/notes/content/posts/operations-hospital-collaboration-guide-en]]

1. 文件目的

本文件提供給 TAMS Backend、Hospital Integration、RMF/Robot Integration、QA 與維運團隊，說明目前 Modular Monolith 的實際程式邊界、Operations 與 Hospital 的互動方式，以及修改程式時必須共同遵守的規則。

本架構仍部署為單一 NestJS process、單一 npm package 與單一版本。模組之間使用 NestJS dependency injection 與記憶體內方法呼叫，不透過內部 HTTP、message broker 或額外 worker framework。

核心原則如下：

Hospital 決定「醫院流程要求什麼」，Operations 保證「機器人任務如何安全執行」，Adapters 處理「如何與外部技術系統溝通」。

2. 快速判斷：程式應該放在哪裡

需求	所屬位置	範例
通用任務、機器人或設施規則	`src/operations/<feature>`	任務取消、派工、機器人可用性、充電站查找
跨多個 Operations feature 的背景流程	`src/operations/workflows`	Queue Worker、Robot Keeper
CSH/CMP/HIS 或醫院專屬流程	`src/csh-hospital`	緊急返回藥局、員工同步、藥品查詢
HTTP validation 與 response mapping	`src/product-api`、`src/csh-hospital/api` 或現有 controller	DTO、guard、Swagger decorator
MongoDB、Redis、RMF、Axios、ROS、Socket.IO	`src/adapters` 或既有 infrastructure layer	repository、RMF adapter、robot-control adapter
登入、JWT、RBAC、session、audit	`src/access`	Actor、permission、使用者管理
多個模組共同使用的純粹型別	`src/domain`	與單一 Operations feature 無關的共用型別

若需求包含醫院名稱判斷，例如 if (hospital === 'CSH')，不要直接加入 Operations。先確認差異是否能由 Hospital config 表達；只有行為真的不同時，才建立小而明確的跨模組契約。

多醫院機器人平台

Thu, 03 Sep 2026 00:00:00 +0000

1. 架構定位

採用：

Modular Monolith + Hexagonal Architecture + Clean Dependency Rule

原則：

目前維持單一 NestJS 應用。
使用模組邊界隔離業務能力。
使用 Ports & Adapters 隔離外部系統。
程式碼依賴只能指向 Application、Domain 與 Ports。
不拆微服務、不拆資料庫。
第二家醫院出現前，不建立額外 npm packages 或 repositories。

2. 目標結構

src/
├── operations/
│ ├── task/
│ ├── robot/
│ ├── fleet/
│ ├── device/
│ ├── maps/
│ ├── facility/
│ ├── charging/
│ ├── application/
│ ├── domain/
│ ├── ports/
│ └── operations.module.ts
│
├── access/
│ ├── authentication/
│ ├── authorization/
│ ├── users/
│ ├── sessions/
│ ├── audit/
│ └── access.module.ts
│
├── product-api/
│ ├── controllers/
│ ├── gateways/
│ ├── dto/
│ └── product-api.module.ts
│
├── adapters/
│ ├── rmf/
│ ├── robot-control/
│ ├── fleet-manager/
│ ├── mongo/
│ ├── redis/
│ ├── websocket/
│ ├── scheduler/
│ └── adapters.module.ts
│
├── hospital/
│ └── csh/
│ ├── controllers/
│ ├── workflows/
│ ├── policies/
│ ├── integrations/
│ ├── config/
│ └── csh-hospital.module.ts
│
├── app.module.ts
└── main.ts

3. 核心依賴方向

flowchart TB
 API["Product API"] --> APP["Application Services"]
 HOSPITAL["Hospital Workflows"] --> APP
 WORKER["Workers / Schedulers"] --> APP
 RMF_IN["RMF State Listener"] --> APP

 APP --> DOMAIN["Domain Rules"]
 APP --> PORTS["Ports"]

 RMF_OUT["RMF Adapter"] --> PORTS
 ROBOT["Robot Control Adapter"] --> PORTS
 FLEET["Fleet Manager Adapter"] --> PORTS
 MONGO["Mongo Adapter"] --> PORTS
 REDIS["Redis Adapter"] --> PORTS
 WS["WebSocket Adapter"] --> PORTS

允許：

PolyMedX HTTPS Edge Proxy 教學

Mon, 17 Aug 2026 00:00:00 +0000

這個 Nginx proxy 安裝在 TAMS 主機上，統一處理 HTTPS/WSS，並依網域將流量送往 TAMS、HMI 與 rosbridge。

網址	目的地
`https://tams.hospital.internal`	TAMS frontend、backend、Swagger、Socket.IO
`https://hmi-amr701.hospital.internal`	HMI frontend、backend、Swagger、Socket.IO
`wss://amr701.hospital.internal`	AMR rosbridge

以下命令都從 PolyMedX workspace 根目錄執行。

前置條件

Docker 與 Docker Compose 已啟動。
TAMS 主機可連到 AMR 的 5173、3000、9090。
主機的 80、443 尚未被其他程式占用；測試時也可改用 8080、8443。
TAMS backend 與 frontend 使用同一個 tams-network。

建立設定

make edge-init

這會建立 workspace-config/edge-proxy/.env；若檔案已存在則保留原檔，不會覆寫。

開發環境範例：

SSL_BASE_DOMAIN=hospital.internal

TAMS_DOMAIN=tams.hospital.internal
HMI_DOMAIN=hmi-amr701.hospital.internal
AMR_DOMAIN=amr701.hospital.internal

TAMS_APP_UPSTREAM=frontend:80
TAMS_API_UPSTREAM=backend:3000
TAMS_API_PREFIX=/api

AMR_IP=172.18.35.29
HMI_APP_UPSTREAM=${AMR_IP}:5173
HMI_API_UPSTREAM=${AMR_IP}:3000
ROS_BRIDGE_UPSTREAM=${AMR_IP}:9090

SELF_SIGNED=true
HSTS_MAX_AGE=0

HTTP_PORT=80
HTTPS_PORT=443

注意：

MongoDB 完整資料庫備份與還原教學

Mon, 10 Aug 2026 00:00:00 +0000

此流程會將來源資料庫完整備份，再還原到目標 MongoDB，並可改成新的資料庫名稱。

設定環境變數

請依實際環境替換以下的內容，參考 production.env。

export SOURCE_MONGODB_URI='mongodb://<username>:<password>@<source-host>:27017/?authSource=<auth-database>'

export TARGET_MONGODB_URI='mongodb://<username>:<password>@<target-host>:27017/?authSource=<auth-database>'

export SOURCE_DATABASE='tams'
export TARGET_DATABASE='tams'
export BACKUP_DIRECTORY="$HOME/db/backup"

SOURCE_MONGODB_URI：來源 MongoDB 的連線字串。
TARGET_MONGODB_URI：目標 MongoDB 的連線字串。
authSource：帳號建立所在的驗證資料庫，通常是 admin 或應用資料庫本身。
密碼如包含 @、:、/、?、# 等特殊字元，必須先進行 URL encoding。

不要把真實帳密提交到 Git；若使用 .env 檔，請將它加入 .gitignore。

備份來源資料庫

mongodump \
 --uri="$SOURCE_MONGODB_URI" \
 --db="$SOURCE_DATABASE" \
 --out="$BACKUP_DIRECTORY"

完成後，備份會位於：

$HOME/db/backup/tams/

其中通常包含各 collection 的 .bson 資料檔與 .metadata.json 索引／設定檔。

還原成新資料庫

mongorestore \
 --uri="$TARGET_MONGODB_URI" \
 --nsInclude="$SOURCE_DATABASE.*" \
 --nsFrom="$SOURCE_DATABASE.*" \
 --nsTo="$TARGET_DATABASE.*" \
 --drop \
 "$BACKUP_DIRECTORY"

--nsFrom：指定備份中的來源資料庫及所有 collections。
--nsTo：將資料還原到目標資料庫。
--drop：先刪除目標資料庫內同名的 collection，再進行還原。
--nsInclude：只還原哪些 namespace。

若不希望覆蓋目標資料庫既有的同名 collection，請移除 --drop。

驗證還原結果

查看目標資料庫的 collections：

Log 循環紀錄部署（TAMS + HMI)

Fri, 07 Aug 2026 00:00:00 +0000

TAMS：每小時更新當天 log；每日 00:10 完整匯出前一天。
HMI：每日 12:00 從 172.18.35.29:3100 完整匯出前一天。
兩者皆保留 90 天。
輸出格式為 JSONL。
Log 儲存根目錄為 /Data/Log/。
使用 loki-readers 群組控管讀取權限。

目錄結構：

/Data/Log/
├── tams/
│ ├── 2026-08-04.jsonl
│ └── 2026-08-05.jsonl
├── hmi/
│ └── 2026-08-04.jsonl
├── loki-export-cron.log
└── loki-export-hmi-cron.log

安裝 LogCLI

已安裝者可跳過。

LogCLI 建議與 Loki 使用相同版本。以下以 Loki v2.9.2、Linux amd64 為例：

sudo apt-get update
sudo apt-get install -y curl unzip util-linux

tmp_dir="$(mktemp -d)"

curl -fL \
 https://github.com/grafana/loki/releases/download/v2.9.2/logcli-linux-amd64.zip \
 -o "$tmp_dir/logcli.zip"

unzip "$tmp_dir/logcli.zip" -d "$tmp_dir"

sudo install \
 -m 0755 \
 "$tmp_dir/logcli-linux-amd64" \
 /usr/local/bin/logcli

rm -rf "$tmp_dir"

sudo /usr/local/bin/logcli --version

建立群組授權

建議使用群組授權，不要直接開放所有帳號讀取 backend log。

PolyMedX Production 部署精簡版

Fri, 07 Aug 2026 00:00:00 +0000

正式環境：MongoDB Server（獨立） + Application Server（polymed-system）

這裏假設:

Application Server：10.10.0.10 MongoDB Server： 10.10.0.20

0. 首次取得原始碼（Application Server）

sudo mkdir -p /opt/polymedx
sudo chown "$USER" /opt/polymedx
cd /opt/polymedx

repo init \
 -u git@ssh.dev.azure.com:v3/pixsee/PolyMedX/polymedx-manifest \
 -b main \
 -m default.xml

repo sync -c -j8

1. MongoDB Server

# 1. 設定目錄
sudo mkdir -p /opt/polymedx
sudo chown "$USER" /opt/polymedx
cd /opt/polymedx

# 2. 複製檔案
# 將其中的 Application Server 中的 workspace-config/mongodb-deployment 整個目錄複製到 MongoDB Server 的 /opt/polymedx/

# 3. 確認目錄（從 Application Server 複製過來）
# /opt/polymedx/mongodb-deployment/
# ├── docker-compose.yml
# ├── production.mongodb.env.example
# └── mongo-init/

cd /opt/polymedx/mongodb-deployment

# 4. 設定
cp production.mongodb.env.example production.mongodb.env
chmod 600 production.mongodb.env
# 編輯 production.mongodb.env（IP、帳密、INIT_CLIENT_*）

production.mongodb.env 關鍵項目：

離線部署 docker image

Fri, 07 Aug 2026 00:00:00 +0000

以下是 frontend + backend 的離線部署流程。假設建置機有外網、部署機為一般 Linux x86_64。

有外網的建置機：建立 image

在專案根目錄執行（版本號可自行替換）：

export RELEASE_TAG=20260804

Frontend：

cd tams-frontend

docker buildx build \
 --platform linux/amd64 \
 --load \
 -t tams-frontend:${RELEASE_TAG} \
 -t tams-frontend:latest \
 --build-arg VITE_WS_URL=same-origin \
 --build-arg VITE_API_URL=/api/v1 \
 --build-arg VITE_LIDAR_MODE=real \
 --build-arg VITE_LIDAR_TEST_ROBOT=true \
 --build-arg VITE_HOSPITAL_INITIAL_RELEASE=true \
 --build-arg VITE_LOW_BATTERY_THRESHOLD_MIN=20 \
 .

Backend：

cd ../tams-backend-service

docker buildx build \
 --platform linux/amd64 \
 --target production \
 --load \
 -t tams-backend:${RELEASE_TAG} \
 -t tams-backend:production \
 .

VITE_API_URL=/api/v1 會編譯進 frontend bundle，因此瀏覽器會對前端同源 /api/v1/... 發請求，再由 Nginx 轉送至 backend。

Mon, 01 Jan 0001 00:00:00 +0000

robot snapshot Log 紀錄

目前共有 6 種 robot_snapshot operation，涵蓋 API 與背景任務。

Operation	Phase	觸發來源	記錄時機
`create_task_request`	`selected`	一般建立、工程師建立、returnHome、autoCharge、RobotKeeper	Robot 選定後、TaskHistory 建立前
`create_task_by_library`	`selected`	by-library API	Robot assignment 驗證後、TaskHistory 建立前
`task_cancel`	`before_reset`	取消任務 API、院內返藥局流程	清除 robot task 資訊前
`task_continue`	`before_queue`	藥車 continue API	Robot 驗證完成、下一段 queue 建立前
`hospital_return_to_pharmacy`	`evaluating`	Hospital ReturnToErPharmacy	逐台判斷返回或等待前
`rmf_dispatch`	`before_dispatch`	TaskQueue 背景派送	通過 RMF readiness 檢查、呼叫 RMF 前

對應 API

create_task_request：

POST /api/v1/tasks
POST /api/v1/tasks/create-by-engineer
POST /api/v1/tasks/returnHome
POST /api/v1/tasks/autoCharge

此外，RobotKeeper 自動充電也會觸發，但不是 HTTP API。

polymedx-production-部署流程

Mon, 01 Jan 0001 00:00:00 +0000

Application Server + 獨立 MongoDB Server 正式環境部署指南

架構概述

正式環境採分離式架構：MongoDB 獨立運行於 MongoDB Server，Application Server 只運行應用服務群（polymed-system）。

MongoDB Server
└── polymed-mongodb

Application Server
└── polymed-system
 ├── redis
 ├── backend
 ├── frontend
 ├── rmf-api-service
 ├── loki
 └── grafana

**ℹ 說明 polymed-system 不會**啟動本機 MongoDB，而是透過網路連線至獨立 MongoDB Server。此設計便於資源隔離與獨立擴展。

首次初始化（僅 Application Server 第一次部署需要）

在 Application Server 建立完整 PolyMedX workspace：

mkdir polyMedX
cd polyMedX

repo init \
 -u git@ssh.dev.azure.com:v3/pixsee/PolyMedX/polymedx-manifest \
 -b main \
 -m default.xml

repo sync -c -j8

完成後目前目錄即為 polyMedX workspace root。接著執行：