butubb/yuyueguahao
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
butubb
2026-07-05 14:43:34 +08:00
commit 17a8027b20
277 changed files with 63794 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/CHANGELOG.md
+37
View File
@@ -0,0 +1,37 @@
# API 变更日志
所有非破坏性变更记录在此，**重大变更必须先经过设计评审**。
## [1.2.0] - 2026-06-14
### Added
- ✨ **Phase 3**：新增 `leads` 表（`phone + source` 唯一索引）
- ✨ **Phase 3**：`POST /api/v1/leads` 公开提交意向客户（自主问卷）
- ✨ **Phase 3**：`GET /api/v1/leads/stats` 鉴权统计
- ✨ **Phase 3**：`GET /api/v1/admin/leads` 鉴权列表（phone/source/keyword/时间过滤 + 分页）
- ✨ **Phase 3**：`GET /api/v1/admin/leads/:id` 详情
- ✨ **Phase 3**：`PUT /api/v1/admin/leads/:id/remark` 改备注
- ✨ **Phase 3**：`DELETE /api/v1/admin/leads/:id` 删除
## [1.1.0] - 2026-06-14
### Added
- ✨ **Phase 1**：后端按业务域重构为 `modules/{route,service,dto,README}` 四件套
- ✨ **Phase 1**：所有接口统一加 `/api/v1` 前缀，URL 路径升级
- ✨ **Phase 2**：Swagger UI 文档（`/api/docs`）和 OpenAPI 3.0 JSON 端点
- ✨ **Phase 2**：Appointment 模块新增 `GET /api/v1/appointments/stats` 鉴权接口
### Changed
- 修改：所有接口路径前缀从 `/api/...` 改为 `/api/v1/...`
- 修改：业务错误响应中，**资源不存在** 仍使用 HTTP 404，但响应体保持 `{code, message, data}` 结构
- 修改：管理后台自动给 `/api/` 路径加 `/v1` 前缀，调用方无需修改
### Removed
- 删除：`/api/hospitals` `/api/departments` 等无版本前缀的接口
## [1.0.0] - 2026-06-13
- 初始版本
- 7 个业务域：hospital / department / doctor / appointment / expert / banner / config
- 1 个鉴权域：adminAuth
- 同进程静态托管 `/admin` 管理后台
docs/api/README.md
+68
View File
@@ -0,0 +1,68 @@
# API 接口文档
> **在线浏览**：http://124.221.67.199:3000/api/docs/
> **OpenAPI JSON**：http://124.221.67.199:3000/api/docs.json
## 基础约定
| 项 | 约定 |
|---|---|
| **基地址** | `http://<host>:3000/api/v1` |
| **版本** | `v1`（Phase 1 起所有接口） |
| **请求方法** | GET / POST / PUT / DELETE |
| **请求格式** | `Content-Type: application/json` |
| **字符集** | UTF-8 |
## 统一响应结构
```jsonc
{
"code": 0, // 0 = 成功，其他 = 业务错误
"message": "ok", // 业务消息
"data": { ... } // 业务数据
}
```
## 状态码
| 状态码 | 含义 | 出现场景 |
|---|---|---|
| 200 | 成功 | 接口正常返回 |
| 400 | 参数错误 | 缺字段、格式不对、校验失败 |
| 401 | 鉴权失败 | token 缺失/失效/密码错误 |
| 404 | 资源不存在 | 找不到 ID 对应的资源 |
| 500 | 服务器内部错误 | 异常抛出 |
> 业务错误统一用 HTTP 200 + `code !== 0` 表示，**仅在资源未找到时使用 404**。
## 鉴权
管理后台接口需要 JWT Bearer Token：
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx
```
通过 `POST /api/v1/admin/auth/login` 获得 token。
## 业务模块
| 模块 | 路径前缀 | 文档 |
|---|---|---|
| Hospital | `/hospitals` | [hospital.md](v1/hospital.md) |
| Department | `/departments` | [department.md](v1/department.md) |
| Doctor | `/doctors` | [doctor.md](v1/doctor.md) |
| Appointment | `/appointments` | [appointment.md](v1/appointment.md) |
| Expert | `/experts` | [expert.md](v1/expert.md) |
| Banner | `/banners` | [banner.md](v1/banner.md) |
| Config | `/config` | [config.md](v1/config.md) |
| AdminAuth | `/admin/auth` | [admin-auth.md](v1/admin-auth.md) |
| Lead | `/leads` · `/admin/leads` | [lead.md](v1/lead.md) |
## 变更日志
详见 [CHANGELOG.md](CHANGELOG.md)
## 同步机制
后端改接口 → 见 [SYNC.md](SYNC.md) 工作流（Phase 5 实施）
docs/api/v1/admin-auth.md
+48
View File
@@ -0,0 +1,48 @@
# AdminAuth · 管理员鉴权
JWT (jsonwebtoken)。请求时 Header `Authorization: Bearer <token>`。
## 接口表
| Method | Path | 鉴权 | 说明 |
|---|---|---|---|
| POST | `/api/v1/admin/auth/login` | - | 登录 |
| GET | `/api/v1/admin/auth/me` | ✅ | 当前账号 |
| POST | `/api/v1/admin/auth/change-password` | ✅ | 修改密码 |
## POST /api/v1/admin/auth/login
**请求体**
```json
{ "username": "admin", "password": "Yygh@2026#Admin" }
```
**响应**
```json
{
"code": 0,
"message": "登录成功",
"data": {
"token": "eyJhbGc...",
"admin": { "id": "u-001", "username": "admin", "nickname": "系统管理员", "role": "super" }
}
}
```
**错误码**
- 400 用户名 / 密码必填
- 401 用户名或密码错误
- 500 服务器内部错误
## POST /api/v1/admin/auth/change-password
**请求体**
```json
{ "oldPassword": "...", "newPassword": "新密码至少 8 位" }
```
**错误码**
- 400 原密码 / 新密码必填
- 400 新密码至少 8 位
- 400 原密码错误
- 404 账号不存在
docs/api/v1/appointment.md
+63
View File
@@ -0,0 +1,63 @@
# Appointment · 预约挂号
## 接口表
| Method | Path | 鉴权 | 说明 |
|---|---|---|---|
| GET | `/api/v1/appointments` | - | 预约列表 |
| GET | `/api/v1/appointments/stats` | ✅ | 统计 |
| GET | `/api/v1/appointments/:id` | - | 详情 |
| POST | `/api/v1/appointments` | - | 创建 |
| PUT | `/api/v1/appointments/:id/cancel` | - | 取消 |
| PUT | `/api/v1/appointments/:id/confirm` | ✅ | 确认（管理后台） |
| PUT | `/api/v1/appointments/:id/complete` | ✅ | 完成（管理后台） |
| PUT | `/api/v1/appointments/:id` | ✅ | 更新备注 |
| DELETE | `/api/v1/appointments/admin/:id` | ✅ | 删除（管理后台） |
## GET /api/v1/appointments
**Query**
- `phone` - 按手机号过滤
- `status` - 'pending' / 'confirmed' / 'completed' / 'cancelled'
## POST /api/v1/appointments
**请求体**
```json
{
"patientName": "张三",
"patientAge": 30,
"patientPhone": "13800138000",
"date": "2026-06-14",
"departmentName": "肛肠",
"doctorId": "doc-001",
"doctorName": "李医生",
"timeSlot": "上午",
"symptom": "便血"
}
```
**校验规则**
- `patientName` 必填，长度 1-20
- `patientAge` 必填，1-149
- `patientPhone` 必填，匹配 `^1[3-9]\d{9}$`
- `date` 必填，ISO 日期 `YYYY-MM-DD`
- `departmentName` 必填，仅支持 `肛肠` / `胃肠`
- `doctorId` / `doctorName` / `timeSlot` / `symptom` 可选
**错误码**
- 400 缺少必填参数
- 400 手机号格式不正确
- 400 年龄参数错误
- 400 科室参数仅支持：肛肠 / 胃肠
- 500 服务器内部错误
## 状态机
```
pending ──confirm──► confirmed ──complete──► completed
│ │
└─cancel──► cancelled └─cancel──► cancelled
```
completed 状态不可取消；cancelled 状态不可确认/完成。
docs/api/v1/banner.md
+14
View File
@@ -0,0 +1,14 @@
# Banner · 轮播图
## 接口表
| Method | Path | 鉴权 | 说明 |
|---|---|---|---|
| GET | `/api/v1/banners` | - | 列表 |
| POST | `/api/v1/banners` | ✅ | 新增 |
| PUT | `/api/v1/banners/:id` | ✅ | 更新 |
| DELETE | `/api/v1/banners/:id` | ✅ | 删除 |
## 字段
`id` / `title` / `subtitle` / `image` / `link` / `sort` / `enabled` / `createdAt` / `updatedAt`
docs/api/v1/config.md
+39
View File
@@ -0,0 +1,39 @@
# Config · 首页整体配置
存储在 `home_config.data` JSON 列。**单行单列，固定 `id=1`**。
## 接口表
| Method | Path | 鉴权 | 说明 |
|---|---|---|---|
| GET | `/api/v1/config/home` | - | 读取首页配置 |
| PUT | `/api/v1/config/home` | ✅ | 整体更新 |
| PUT | `/api/v1/config/home/hero` | ✅ | 更新 Hero 区 |
| PUT | `/api/v1/config/home/features` | ✅ | 整体替换功能卡 |
| PUT | `/api/v1/config/home/expert-team` | ✅ | 整体替换专家团队 |
| PUT | `/api/v1/config/home/info-banner` | ✅ | 更新信息条 |
| PUT | `/api/v1/config/home/hero-experts` | ✅ | 整体替换 Hero 专家 |
## GET /api/v1/config/home
**响应** `data` 形态：
```json
{
"hero": {
"title": "...",
"subtitle": "...",
"bgImage": "...",
"primaryCta": { "text": "...", "link": "/pages/appointment/index" }
},
"features": [
{ "icon": "🩺", "title": "..." , "link": "..." }
],
"expertTeam": [
{ "id": "he-001", "name": "...", "title": "...", "avatar": "..." }
],
"infoBanner": { "enabled": true, "texts": ["..."] },
"heroExperts": [
{ "id": "he-001", "name": "...", "title": "...", "avatar": "..." }
]
}
```
docs/api/v1/department.md
+34
View File
@@ -0,0 +1,34 @@
# Department · 科室
## 接口表
| Method | Path | 鉴权 | 说明 |
|---|---|---|---|
| GET | `/api/v1/departments` | - | 科室列表 |
## GET /api/v1/departments
**Query 参数**
- `hospitalId` (string, 可选) - 按医院过滤
- `enabled` ('true' | 'false', 可选) - 按启用状态过滤
**响应示例**
```json
{
"code": 0,
"message": "ok",
"data": [
{
"id": "d-001",
"name": "肛肠中心",
"icon": "🩺",
"description": "肛肠疾病专科",
"doctorCount": 5,
"sort": 1,
"enabled": true,
"createdAt": "...",
"updatedAt": "..."
}
]
}
```
docs/api/v1/doctor.md
+39
View File
@@ -0,0 +1,39 @@
# Doctor · 医生
## 接口表
| Method | Path | 鉴权 | 说明 |
|---|---|---|---|
| GET | `/api/v1/doctors` | - | 医生列表 |
| GET | `/api/v1/doctors/:id` | - | 医生详情 |
| POST | `/api/v1/doctors/admin` | ✅ | 新增 |
| PUT | `/api/v1/doctors/admin/:id` | ✅ | 更新 |
| DELETE | `/api/v1/doctors/admin/:id` | ✅ | 删除 |
## GET /api/v1/doctors
**Query 参数**
- `departmentId` (string) - 按科室 ID
- `departmentName` (string) - 按科室名
- `enabled` (string) - 'true' / 'false'
**响应** - `data` 是 `Doctor[]`
## Doctor 字段
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 医生 ID |
| name | string | 姓名 |
| title | string | 职称 |
| departmentId | string \| null | 所属科室 ID |
| departmentName | string \| null | 所属科室名 |
| avatar | string | 头像 URL |
| specialty | string | 专长 |
| intro | string | 简介 |
| fee | number | 挂号费 |
| rating | number | 评分 |
| availableDates | string[] | 可预约日期（ISO） |
| enabled | boolean | 启用状态 |
| createdAt | string | ISO datetime |
| updatedAt | string | ISO datetime |
docs/api/v1/expert.md
+16
View File
@@ -0,0 +1,16 @@
# Expert · 专家资源
## 接口表
| Method | Path | 鉴权 | 说明 |
|---|---|---|---|
| GET | `/api/v1/experts` | - | 列表（?enabled=true） |
| GET | `/api/v1/experts/:id` | - | 详情 |
| POST | `/api/v1/experts` | ✅ | 新增 |
| PUT | `/api/v1/experts/:id` | ✅ | 更新 |
| DELETE | `/api/v1/experts/:id` | ✅ | 删除 |
| POST | `/api/v1/experts/upload` | ✅ | 上传（url / base64） |
## 字段
`id` / `name` / `title` / `avatar` / `department` / `intro` / `sort` / `enabled` / `createdAt` / `updatedAt`
docs/api/v1/hospital.md
+46
View File
@@ -0,0 +1,46 @@
# Hospital · 医院信息
## 接口表
| Method | Path | 鉴权 | 说明 |
|---|---|---|---|
| GET | `/api/v1/hospitals` | - | 医院列表 |
| GET | `/api/v1/hospitals/:id` | - | 医院详情 |
## GET /api/v1/hospitals
**响应示例**
```json
{
"code": 0,
"message": "ok",
"data": [
{
"id": "h-001",
"name": "苏州肛泰中医院",
"level": "三甲",
"address": "苏州市姑苏区吴中西路 888 号",
"phone": "0512-6586-3999",
"intro": "胃肠肛肠专科医院 · 三甲名医亲诊",
"description": "...",
"banner": "https://...",
"logo": "https://...",
"established": "1998",
"departments": 12,
"doctors": 35,
"beds": 200,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
]
}
```
## GET /api/v1/hospitals/:id
**路径参数**
- `id` (string, 必填) - 医院 ID
**错误响应**
- 404 医院不存在
- 500 服务器内部错误
docs/api/v1/hospitalImage.md
+22
View File
@@ -0,0 +1,22 @@
# HospitalImage · 医院图片
维护医院"简介"栏目展示的图片 (轮播/单图)。小程序 `hospital` 页"医院简介" tab 直接拉取启用项展示。
## 接口
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /api/v1/hospital-images | 否 | 列表 (支持 `?enabled=true` 过滤) |
| GET | /api/v1/hospital-images/:id | 否 | 详情 |
| POST | /api/v1/hospital-images | 是 | 新增 |
| PUT | /api/v1/hospital-images/:id | 是 | 更新 |
| DELETE | /api/v1/hospital-images/:id | 是 | 删除 |
| POST | /api/v1/uploads/image | 是 | 通用图片上传 (base64 → dataURL) |
## DTO 字段
- `hospitalId` 关联医院 id (默认 h-001)
- `image` 图片 URL 或 dataURL
- `caption` 图片说明
- `sort` 排序 (升序)
- `enabled` 是否启用
docs/api/v1/lead.md
+113
View File
@@ -0,0 +1,113 @@
# Lead · 意向客户（Phase 3）
> 自主问卷用户信息采集的统一入口，落到 `leads` 表，供管理后台跟进。
## 接口表
| Method | Path | 鉴权 | 说明 |
|---|---|---|---|
| POST | `/api/v1/leads` | - | 提交（小程序自测问卷、首页落地等） |
| GET | `/api/v1/leads/stats` | ✅ | 统计：总数 / 24h / 按 source 分组 |
| GET | `/api/v1/admin/leads` | ✅ | 列表，支持 phone / source / keyword / 时间过滤 |
| GET | `/api/v1/admin/leads/:id` | ✅ | 详情 |
| PUT | `/api/v1/admin/leads/:id/remark` | ✅ | 修改备注 |
| DELETE | `/api/v1/admin/leads/:id` | ✅ | 删除 |
## POST /api/v1/leads
**请求体**
```json
{
"name": "张三",
"phone": "13800138000",
"symptom": "便血近 1 周，伴有肛门坠胀",
"questionnaire": {
"total": 5,
"answers": { "0": "sometimes", "1": "no" },
"createdAt": "2026-06-14T08:30:00.000Z"
},
"source": "self-test",
"score": 5
}
```
**校验规则**
- `name` 必填，1-20 字符
- `phone` 必填，匹配 `^1[3-9]\d{9}$`
- `symptom` 可选，≤ 500 字
- `questionnaire` 必填，任意 JSON 对象
- `source` 可选，枚举 `self-test` / `home` / `appointment` / `other`，默认 `self-test`
- `score` 可选，0-100
**响应**
```json
{ "code": 0, "message": "提交成功", "data": { "id": "lead-1781398800000", "createdAt": "2026-06-14 16:30:00" } }
```
**错误码**
| HTTP | code | message |
|---|---|---|
| 400 | 1 | 姓名必填 / 姓名长度需在 1-20 字符 |
| 400 | 1 | 手机号必填 / 手机号格式不正确 |
| 400 | 1 | 症状描述不超过 500 字 |
| 400 | 1 | 问卷答案 questionnaire 必填且为对象 |
| 400 | 1 | source 仅支持：self-test / home / appointment / other |
| 400 | 1 | 该手机号在同渠道已提交过，请勿重复 |
| 500 | 500 | 服务器内部错误 |
## GET /api/v1/admin/leads
**Query**
- `phone` 手机号精确匹配
- `source` 渠道
- `keyword` 姓名模糊匹配
- `startDate` / `endDate` 时间范围（`YYYY-MM-DD`）
- `limit` 默认 50,最大 200
- `offset` 默认 0
**响应**
```json
{
"code": 0,
"message": "ok",
"data": {
"list": [
{
"id": "lead-1781398800000",
"name": "张三",
"phone": "13800138000",
"symptom": "便血近 1 周",
"questionnaire": { "total": 5, "answers": {} },
"source": "self-test",
"score": 5,
"remark": "",
"createdAt": "2026-06-14 16:30:00",
"updatedAt": "2026-06-14 16:30:00"
}
],
"total": 1,
"limit": 50,
"offset": 0
}
}
```
## 数据表
```sql
CREATE TABLE leads (
id VARCHAR(32) PRIMARY KEY,
name VARCHAR(50) NOT NULL,
phone VARCHAR(20) NOT NULL,
symptom TEXT,
questionnaire JSON NOT NULL,
source VARCHAR(20) NOT NULL DEFAULT 'self-test',
score INT DEFAULT 0,
remark VARCHAR(500),
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uniq_phone_source (phone, source)
);
```
唯一约束 `(phone, source)`：同手机号在同一渠道只保留一条。