{"openapi":"3.0.3","info":{"title":"苏州肛泰中医院 · 预约挂号 API","version":"1.0.0","description":"RESTful API · 基地址 `/api/v1` · 业务约定 `{code, message, data}` 统一响应","contact":{"name":"YuyueGuahao Backend","email":"dev@yuyueguahao.local"}},"servers":[{"url":"/api/v1","description":"当前版本 v1"}],"tags":[{"name":"Hospital","description":"医院信息"},{"name":"Department","description":"科室"},{"name":"Doctor","description":"医生"},{"name":"Appointment","description":"预约挂号"},{"name":"Expert","description":"专家资源"},{"name":"Banner","description":"Banner 轮播图"},{"name":"Config","description":"首页配置"},{"name":"AdminAuth","description":"管理员鉴权"},{"name":"Lead","description":"意向客户 leads"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"管理后台登录后获得的 token"}},"schemas":{"ApiResponse":{"type":"object","properties":{"code":{"type":"integer","example":0,"description":"0 成功 / 其他业务错误码"},"message":{"type":"string","example":"ok"},"data":{"nullable":true}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","example":1},"message":{"type":"string","example":"参数错误"},"data":{"nullable":true,"example":null}}},"Hospital":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"level":{"type":"string"},"address":{"type":"string"},"phone":{"type":"string"},"intro":{"type":"string"},"description":{"type":"string"},"banner":{"type":"string"},"logo":{"type":"string"},"established":{"type":"string"},"departments":{"type":"integer"},"doctors":{"type":"integer"},"beds":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Department":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"icon":{"type":"string"},"description":{"type":"string"},"doctorCount":{"type":"integer"},"sort":{"type":"integer"},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Doctor":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"departmentId":{"type":"string","nullable":true},"departmentName":{"type":"string","nullable":true},"avatar":{"type":"string"},"specialty":{"type":"string"},"intro":{"type":"string"},"fee":{"type":"number"},"rating":{"type":"number"},"availableDates":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Appointment":{"type":"object","properties":{"id":{"type":"string"},"hospitalId":{"type":"string"},"hospitalName":{"type":"string"},"departmentName":{"type":"string","enum":["肛肠","胃肠"]},"doctorId":{"type":"string","nullable":true},"doctorName":{"type":"string","nullable":true},"patientName":{"type":"string"},"patientAge":{"type":"integer"},"patientPhone":{"type":"string"},"date":{"type":"string","example":"2026-06-14"},"timeSlot":{"type":"string","nullable":true},"symptom":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed","completed","cancelled"]},"remark":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Expert":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"avatar":{"type":"string"},"department":{"type":"string"},"intro":{"type":"string"},"sort":{"type":"integer"},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Banner":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"image":{"type":"string"},"link":{"type":"string"},"sort":{"type":"integer"},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/hospitals":{"get":{"tags":["Hospital"],"summary":"医院列表","responses":{"200":{"description":"ok"}}}},"/hospitals/{id}":{"get":{"tags":["Hospital"],"summary":"医院详情","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"},"404":{"description":"医院不存在"}}}},"/departments":{"get":{"tags":["Department"],"summary":"科室列表","parameters":[{"in":"query","name":"hospitalId","schema":{"type":"string"}},{"in":"query","name":"enabled","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"ok"}}}},"/doctors":{"get":{"tags":["Doctor"],"summary":"医生列表","parameters":[{"in":"query","name":"departmentId","schema":{"type":"string"}},{"in":"query","name":"departmentName","schema":{"type":"string"}},{"in":"query","name":"enabled","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"ok"}}}},"/doctors/{id}":{"get":{"tags":["Doctor"],"summary":"医生详情","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"},"404":{"description":"医生不存在"}}}},"/appointments":{"get":{"tags":["Appointment"],"summary":"预约列表","parameters":[{"in":"query","name":"phone","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","enum":["pending","confirmed","completed","cancelled"]}}],"responses":{"200":{"description":"ok"}}},"post":{"tags":["Appointment"],"summary":"创建预约","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["patientName","patientAge","patientPhone","date","departmentName"],"properties":{"patientName":{"type":"string"},"patientAge":{"type":"integer"},"patientPhone":{"type":"string","example":"13800138000"},"date":{"type":"string","example":"2026-06-14"},"departmentName":{"type":"string","enum":["肛肠","胃肠"]},"doctorId":{"type":"string"},"doctorName":{"type":"string"},"timeSlot":{"type":"string"},"symptom":{"type":"string"}}}}}},"responses":{"200":{"description":"预约成功"},"400":{"description":"参数错误（手机号/年龄/科室）"}}}},"/appointments/stats":{"get":{"tags":["Appointment"],"summary":"预约统计（管理后台）","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ok"}}}},"/appointments/{id}":{"get":{"tags":["Appointment"],"summary":"预约详情","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"},"404":{"description":"预约不存在"}}}},"/appointments/{id}/cancel":{"put":{"tags":["Appointment"],"summary":"取消预约","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"已取消"},"400":{"description":"不可取消"},"404":{"description":"预约不存在"}}}},"/appointments/{id}/confirm":{"put":{"tags":["Appointment"],"summary":"确认（管理后台）","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"已确认"},"400":{"description":"已取消的不可确认"},"404":{"description":"预约不存在"}}}},"/appointments/{id}/complete":{"put":{"tags":["Appointment"],"summary":"完成（管理后台）","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"已标记完成"},"400":{"description":"已取消的不可完成"},"404":{"description":"预约不存在"}}}},"/experts":{"get":{"tags":["Expert"],"summary":"专家列表","parameters":[{"in":"query","name":"enabled","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"ok"}}}},"/experts/{id}":{"get":{"tags":["Expert"],"summary":"专家详情","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"},"404":{"description":"专家不存在"}}}},"/banners":{"get":{"tags":["Banner"],"summary":"Banner 列表","parameters":[{"in":"query","name":"enabled","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"ok"}}}},"/config/home":{"get":{"tags":["Config"],"summary":"首页配置","responses":{"200":{"description":"ok"}}}},"/admin/auth/login":{"post":{"tags":["AdminAuth"],"summary":"管理员登录","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","password"],"properties":{"username":{"type":"string"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"登录成功"},"400":{"description":"参数错误"},"401":{"description":"用户名或密码错误"}}}},"/admin/auth/me":{"get":{"tags":["AdminAuth"],"summary":"当前登录账号","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ok"},"401":{"description":"未登录"}}}},"/admin/auth/change-password":{"post":{"tags":["AdminAuth"],"summary":"修改密码","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["oldPassword","newPassword"],"properties":{"oldPassword":{"type":"string"},"newPassword":{"type":"string","minLength":8}}}}}},"responses":{"200":{"description":"密码修改成功"},"400":{"description":"参数错误或原密码错误"},"401":{"description":"未登录"}}}},"/leads":{"post":{"tags":["Lead"],"summary":"提交意向客户（小程序自测问卷等）","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","phone","questionnaire"],"properties":{"name":{"type":"string"},"phone":{"type":"string"},"symptom":{"type":"string"},"questionnaire":{"type":"object","additionalProperties":true},"source":{"type":"string","enum":["self-test","home","appointment","other"]},"score":{"type":"integer"}}}}}},"responses":{"200":{"description":"提交成功"},"400":{"description":"参数错误"}}}},"/leads/stats":{"get":{"tags":["Lead"],"summary":"leads 统计（管理后台）","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"ok"}}}},"/admin/leads":{"get":{"tags":["Lead"],"summary":"意向客户列表（管理后台）","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"phone","schema":{"type":"string"}},{"in":"query","name":"source","schema":{"type":"string","enum":["self-test","home","appointment","other"]}},{"in":"query","name":"keyword","schema":{"type":"string"}},{"in":"query","name":"startDate","schema":{"type":"string"}},{"in":"query","name":"endDate","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200}},{"in":"query","name":"offset","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"ok"}}}},"/admin/leads/{id}":{"get":{"tags":["Lead"],"summary":"Lead 详情","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"},"404":{"description":"不存在"}}},"delete":{"tags":["Lead"],"summary":"删除 Lead","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok"},"404":{"description":"不存在"}}}},"/admin/leads/{id}/remark":{"put":{"tags":["Lead"],"summary":"修改备注","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["remark"],"properties":{"remark":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"ok"},"400":{"description":"参数错误"},"404":{"description":"不存在"}}}}}}