MedServLink API

医疗设备远程服务管理平台 · API 接口文档

Version 0.1.0Base URL: https://www.medservlink.cn/api Auth: JWT Bearer TokenLast Updated: 2026-08-07
认证用户管理设备管理 工单管理远程会话TRTC 数据模型错误处理

1. 认证 Auth

POST /api/auth/register 公开

注册新用户,成功返回 JWT Token。

{
  "username": "engineer01",
  "password": "pass123",
  "role": "engineer",
  "name": "张工"
}

role: admin | manufacturer | engineer | hospital

Response 201:

{
  "access_token": "eyJhbG...",
  "user": {
    "id": "uuid",
    "username": "engineer01",
    "role": "engineer",
    "name": "张工"
  }
}
POST /api/auth/login 公开

用户登录,返回 JWT Token。Token 有效期 7 天。

{
  "username": "admin",
  "password": "admin123"
}

Response 200 / 401

GET /api/auth/me 需认证

获取当前登录用户信息。

Headers: Authorization: Bearer <token>

{
  "id": "uuid",
  "username": "admin",
  "role": "admin",
  "name": "Andrew",
  "email": null,
  "phone": null,
  "company": null,
  "active": true,
  "createdAt": "2026-08-06T..."
}

2. 用户管理 Users 需认证 (admin)

GET /api/users

获取所有用户列表。

GET /api/users/:id

获取单个用户详情。

POST /api/users

创建新用户。注意:密码不会经过 bcrypt 哈希(直接调用 UsersService),建议通过 /api/auth/register 创建。

PUT /api/users/:id

更新用户信息。

DELETE /api/users/:id

删除用户。

3. 设备管理 Devices 需认证

GET /api/devices

获取所有设备列表。

POST /api/devices

注册新设备。

{
  "name": "非接触式眼压计",
  "model": "TX-20",
  "category": "眼科-眼压计",
  "manufacturerId": "uuid",
  "serialNumber": "SN-2026-001",
  "status": "active"
}
GET/api/devices/:id
PUT/api/devices/:id
DELETE/api/devices/:id

4. 工单管理 Orders 需认证

GET /api/orders ?status=pending|accepted|in_progress|completed|cancelled

获取工单列表。可选 ?status=xxx 过滤。

POST/api/orders
{
  "title": "眼压计校准故障",
  "description": "设备显示E02错误代码...",
  "deviceCategory": "眼科-眼压计",
  "deviceModel": "TX-20",
  "manufacturerId": "uuid",
  "engineerId": "uuid",
  "priority": "medium",
  "status": "pending"
}

status: pendingacceptedin_progresscompleted | cancelled

priority: low | medium | high | urgent

GET/api/orders/:id
PUT/api/orders/:id
DELETE/api/orders/:id

5. 远程会话 Sessions 需认证

GET/api/sessions
POST/api/sessions
{
  "orderId": "uuid",
  "manufacturerUserId": "uuid",
  "engineerUserId": "uuid",
  "trtcRoomId": "room-123",
  "notes": "眼压计主板故障排查"
}
GET/api/sessions/:id
PUT/api/sessions/:id
DELETE/api/sessions/:id

6. TRTC 音视频 需认证

POST /api/trtc/usersig

生成 TRTC UserSig,用于客户端进入音视频房间。

{
  "userId": "engineer-01"
}
{
  "sdkAppId": 1600155894,
  "userId": "engineer-01",
  "userSig": "eJwt..."
}

SDKAppID: 1600155894,UserSig 有效期默认 7 天。

7. 数据模型 Entities

User

字段类型说明
idUUID主键
usernamestring唯一,登录名
passwordstringbcrypt 哈希,API 不返回
roleenumadmin/manufacturer/engineer/hospital
namestring?真实姓名
companystring?公司/医院名称
phonestring?手机号
emailstring?邮箱
activeboolean账号是否启用

Device

字段类型说明
idUUID主键
namestring设备名称
modelstring设备型号
categorystring设备类别(如"眼科-眼压计")
manufacturerIdstring生产厂商用户ID
hospitalIdstring?医院用户ID
serialNumberstring?设备序列号
installDateDate?安装日期
warrantyExpiryDate?保修到期日
statusstringactive/inactive

Order

字段类型说明
idUUID主键
titlestring工单标题
descriptiontext?问题描述
deviceCategorystring设备类别
deviceModelstring?设备型号
manufacturerIdstring厂商ID
engineerIdstring?指派工程师ID
hospitalIdstring?医院ID
statusenumpending/accepted/in_progress/completed/cancelled
prioritystring?low/medium/high/urgent
scheduledAtDate?计划服务时间
completedAtDate?完成时间

Session

字段类型说明
idUUID主键
orderIdstring关联工单ID
manufacturerUserIdstring厂商用户ID
engineerUserIdstring工程师用户ID
trtcRoomIdstring?TRTC 房间号
recordingboolean是否录像
notestext?会话备注
startedAtDate?开始时间
endedAtDate?结束时间
durationSecondsnumber通话时长(秒)

8. 错误处理

认证错误:所有需要认证的端点,无 token 返回 401 Unauthorized
Token 过期:返回 401,前端自动跳转登录页。
验证错误:返回 400 Bad Request,body 包含 { "message": "..." }

部署信息

项目
服务器Alibaba Cloud ECS 47.253.228.219
Web 服务Nginx 1.24.0
后端NestJS + TypeORM + sql.js (SQLite)
进程管理PM2 (medservlink-backend)
HTTPSLet's Encrypt (www.medservlink.cn)
TRTC SDKAppID1600155894
源码位置/opt/medservlink/backend/
构建命令cd /opt/medservlink/backend && npm run build && pm2 restart medservlink-backend --update-env
日志位置~/.pm2/logs/medservlink-backend-*.log
数据库/opt/medservlink/data/medservlink.db