医路相伴·愈见安康——多发伤康复全周期管理随访系统
RESTful API 接口文档 v1.0.0

康复训练与康复动作疗法综合管理平台 — 涵盖三端（用户/基层医生/上级医生）的 35+ 接口

35+
接口数
14
资源模块
3
角色权限
JWT
鉴权方式

总览

Base URL

https://api.yun-clinic.example.com/api/v1

请求/响应格式

鉴权机制

除登录、科普文章公开列表外，所有接口需携带 JWT：

Authorization: Bearer <token>

Token 有效期 7 天，过期返回 401，前端需重新登录。

通用约定

统一响应结构

{
  "code": 0,           // 0 = 成功，非 0 = 业务错误
  "message": "ok",     // 描述
  "data": { ... }       // 业务数据，列表类为 { list, total, page, pageSize }
}

分页参数（GET 列表类通用）

参数类型必填默认说明
pageinteger否1页码，从 1 开始
pageSizeinteger否20每页条数，最大 100
keywordstring否—按姓名/手机号模糊搜索
sortstring否-createdAt排序字段，前缀 - 表示倒序

🔐 认证模块

1. 用户登录

POST/api/auth/login

根据角色返回对应的用户信息和 JWT Token，前端根据 role 跳转到对应主页。

请求参数

字段类型必填说明
usernamestring必填用户名
passwordstring必填密码（明文，HTTPS 传输）
roleenum否patient | doctor | superior，默认 patient

请求示例

POST /api/auth/login
Content-Type: application/json

{
  "username": "patient1",
  "password": "123456",
  "role": "patient"
}

成功响应

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 604800,
    "user": {
      "id": 1,
      "username": "patient1",
      "name": "张三",
      "role": "patient",
      "gender": "男",
      "age": 56,
      "phone": "13800138001",
      "avatar": "https://...",
      "doctorId": 4
    }
  }
}

2. 退出登录

POST/api/auth/logout

使当前 Token 失效（加入服务端黑名单）。

响应

{ "code": 0, "message": "已退出" }

3. 获取当前用户

GET/api/auth/me

根据 Token 解析当前登录用户完整信息。常用于页面初始化。

响应

{
  "code": 0,
  "data": { "id": 1, "name": "张三", "role": "patient", /* ... */ }
}

👥 用户管理（Users）

4. 用户列表

GET/api/users

基层医生/上级医生可用。医生只能看到自己管辖的患者；上级医生能看到所有下级医生及其患者。

Query 参数

参数类型说明
roleenum按角色过滤：patient | doctor | superior
doctorIdinteger按主管医生过滤
page, pageSize, keyword—见通用分页

响应

{
  "code": 0,
  "data": {
    "list": [
      { "id": 1, "name": "张三", "role": "patient", "phone": "138...", "gender": "男", "age": 56, "doctorId": 4 }
    ],
    "total": 3, "page": 1, "pageSize": 20
  }
}

5. 新建用户

POST/api/users

请求体

字段类型必填说明
usernamestring必填唯一
passwordstring必填≥6 位
namestring必填姓名
roleenum必填patient | doctor | superior
phonestring必填手机号
gender, age, idCard, address—可选患者扩展信息
department, title, hospital, bio—可选医生扩展信息
doctorId / superiorIdinteger可选归属关系

6. 用户详情 / 7. 更新 / 8. 删除

GET /api/users/:id
PUT /api/users/:id
DELETE /api/users/:id

PUT 提交需变更字段，未提交字段保持不变。DELETE 为软删除（标记 isDeleted）。

📅 预约 · 会诊 · 病历 · 治疗记录

9. 预约（Appointments）

GET /api/appointments?patientId=&doctorId=&status=&dateFrom=&dateTo=
POST /api/appointments
PUT /api/appointments/:id — 医生填写诊断、treatmentPlan、status=completed

Appointment 对象

{
  "id": 1, "patientId": 1, "doctorId": 4,
  "patientName": "张三", "doctorName": "杨医生",
  "appointmentDate": "2026-06-10 09:00",
  "symptom": "入睡困难、心悸",
  "diagnosis": "焦虑失眠型不寐",
  "treatmentPlan": "康复训练+康复动作疗法",
  "superiorId": 6,
  "status": "completed",          // pending | completed | cancelled
  "createdAt": "2026-06-01T08:00:00Z",
  "completedAt": "2026-06-10T09:30:00Z"
}

10. 会诊方案（Consultations）

GET /api/consultations?appointmentId=&superiorId=&status=
POST /api/consultations — 基层医生发起向上会诊
PUT /api/consultations/:id/audit — 上级医生审核（status → audited，附 feedback）

Consultation 对象（康复评估数据）

{
  "id": 1, "appointmentId": 1,
  "patientId": 1, "doctorId": 4, "superiorId": 6,
  "topSyndrome": "焦虑失眠型",       // 康复评估结论
  "element": "火旺",                // 训练强度
  "phq9Score": 18, "phq9Level": "中重度抑郁",
  "music": {
    "tune": "放松训练", "wuxing": "水",
    "duration": "20-25分钟",
    "tracks": "《梅花三弄》《二泉映月》"
  },
  "points": {
    "add": ["小肠", "内分泌", "肾", "内生殖器", "胃", "耳尖"],
    "effect": "缓解焦虑、改善睡眠"
  },
  "emotion": {
    "name": "恐胜喜（水克火）",
    "method": "以适度恐惧克制焦虑失眠过喜"
  },
  "status": "audited", "feedback": "方案合理"
}

11. 电子病历（Medical Records）

GET /api/medical-records?patientId=
POST /api/medical-records

字段：chiefComplaint / presentIllness / pastHistory / allergyHistory / tongue / pulse / tcmDiagnosis / wmDiagnosis

12. 治疗记录（Treatment Records）

GET /api/treatment-records?patientId=&medicalRecordId=
POST /api/treatment-records

字段：type（music / earpoint / medicine） / detail / effect / operatorId

🎵 康复训练 · 📚 康复动作库

13. 康复训练处方（Music Therapies）

GET /api/music-therapies?patientId=
POST /api/music-therapies
PUT /api/music-therapies/:id/play — 用户每次播放自增 completedCount

14. 康复动作处方（Ear Acupoints）

GET /api/ear-acupoints?patientId=
POST /api/ear-acupoints

15. 康复动作库（Ear Acupoint KB）

GET /api/ear-acupoint-kb?category=&wuxing=&keyword=
POST /api/ear-acupoint-kb — 仅上级医生/管理员

16. 健康科普文章（Health Education）

GET /api/health-education?category= — 公开
GET /api/health-education/:id
POST /api/health-education — 管理员

📊 量表 · 问卷

17. 量表模板（Scale Templates）

GET /api/scale-templates

返回内置 PHQ-9、GAD-7 等量表结构（questions + options + scoring 规则）。

18. 量表评分提交（Scale Results）

POST /api/scale-results
// 请求
{
  "patientId": 1,
  "scaleId": 1,
  "scaleCode": "PHQ-9",
  "answers": { "1": 2, "2": 2, /* ... */ }
}
// 服务端自动计算 score=18, level="中重度抑郁"

19. 评分历史（Scales）

GET /api/scales?patientId=&type=&dateFrom=&dateTo=

20. 问卷（Questionnaires）

GET /api/questionnaires?status=active
POST /api/questionnaire-responses — 用户提交答卷

⚠️ 错误码

HTTPcode说明
2000成功
40010001参数校验失败
40110002未登录 / Token 过期
40310003无权限（角色不符）
40410004资源不存在
40910005资源冲突（如用户名重复）
50020000服务器错误

📘 枚举字典

role 用户角色

patient 用户 · doctor 基层医生 · superior 上级医生

appointment.status

pending 待就诊 · completed 已完成 · cancelled 已取消

consultation.status

reviewing 审核中 · audited 已审核 · rejected 已驳回

康复训练 wuxing 康复分期

金(平衡训练) · 木(肌力训练) · 水(放松训练) · 火(耐力训练) · 土(关节活动训练)

— 文档结束 · 医路相伴·愈见安康 API v1.0.0 · 2026-07-02 —