|
|
# 康策 CSM 系统 API 接口文档
|
|
|
|
|
|
> 自动生成时间：2025-07-11
|
|
|
> Swagger UI：http://localhost:5276/swagger
|
|
|
> 基地址：http://localhost:5276
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📋 接口概览
|
|
|
|
|
|
| Controller | 路由前缀 | 接口数 | 是否需要认证 |
|
|
|
|---|---|---|---|
|
|
|
| AdminController | `/api/admin` | 14 | 除登录外均需 JWT |
|
|
|
| HospitalController | `/api/hospital` | 9 | 除登录外均需 JWT |
|
|
|
| UploadController | `/api/upload` | 2 | 上传需 JWT |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🔐 认证说明
|
|
|
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
- 调用登录接口获取 Token
|
|
|
- Token 有效期：1440 分钟（24 小时）
|
|
|
- 签发者：CSM_System
|
|
|
- 受众：CSM_Client
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📐 统一响应格式
|
|
|
|
|
|
所有接口均返回 `ApiResponse` 或 `ApiResponse<T>`：
|
|
|
|
|
|
```json
|
|
|
// 成功
|
|
|
{ "code": 200, "message": "success", "data": { ... } }
|
|
|
|
|
|
// 错误
|
|
|
{ "code": 400, "message": "参数错误", "data": null }
|
|
|
{ "code": 401, "message": "未授权", "data": null }
|
|
|
{ "code": 403, "message": "无权限", "data": null }
|
|
|
{ "code": 404, "message": "资源不存在", "data": null }
|
|
|
{ "code": 500, "message": "服务器内部错误", "data": null }
|
|
|
```
|
|
|
|
|
|
分页接口返回 `ApiResponse<PagedResult<T>>`：
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"message": "success",
|
|
|
"data": {
|
|
|
"total": 100,
|
|
|
"page": 1,
|
|
|
"pageSize": 10,
|
|
|
"list": [...]
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 一、管理端 API — `/api/admin`
|
|
|
|
|
|
### 1.1 登录
|
|
|
|
|
|
> **POST** `/api/admin/login` · 无需认证
|
|
|
|
|
|
**请求体：**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| username | string | 是 | 用户名 |
|
|
|
| password | string | 是 | 密码 |
|
|
|
|
|
|
**请求示例：**
|
|
|
```json
|
|
|
{ "username": "admin", "password": "123456" }
|
|
|
```
|
|
|
|
|
|
**响应数据：**
|
|
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|
|---|---|---|
|
|
|
| token | string | JWT Token |
|
|
|
| userId | int | 用户 ID |
|
|
|
| userName | string | 用户名 |
|
|
|
| userType | string | 用户类型（Admin/Hospital） |
|
|
|
| hospitalId | int? | 所属医院 ID（Admin 为 null） |
|
|
|
| hospitalName | string | 所属医院名称 |
|
|
|
| role | string | 角色 |
|
|
|
| name | string | 姓名 |
|
|
|
|
|
|
> ⚠️ 仅允许 `userType == "Admin"` 的账号登录，否则返回 403
|
|
|
|
|
|
---
|
|
|
|
|
|
### 1.2 服务工单
|
|
|
|
|
|
#### 获取工单列表
|
|
|
> **GET** `/api/admin/orders` · ✅ 需认证
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| page | int | 否 | 页码，默认 1 |
|
|
|
| pageSize | int | 否 | 每页条数，默认 10 |
|
|
|
| status | string | 否 | 状态筛选 |
|
|
|
| priority | string | 否 | 优先级筛选（高/中/低） |
|
|
|
| type | string | 否 | 服务类型筛选 |
|
|
|
| keyword | string | 否 | 关键词搜索 |
|
|
|
| startDate | string | 否 | 开始时间 |
|
|
|
| endDate | string | 否 | 结束时间 |
|
|
|
| hospitalId | int | 否 | 医院 ID 筛选 |
|
|
|
|
|
|
#### 获取工单详情
|
|
|
> **GET** `/api/admin/orders/{id}` · ✅ 需认证
|
|
|
|
|
|
| 路径参数 | 类型 | 说明 |
|
|
|
|---|---|---|
|
|
|
| id | int | 工单 ID |
|
|
|
|
|
|
#### 管理端提交工单
|
|
|
> **POST** `/api/admin/orders` · ✅ 需认证
|
|
|
|
|
|
**请求体：**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| title | string | 是 | 工单标题 |
|
|
|
| priority | string | 是 | 优先级（高/中/低） |
|
|
|
| serviceType | string | 是 | 服务类型 |
|
|
|
| description | string | 是 | 详细描述（HTML） |
|
|
|
| department | string | 否 | 科室 |
|
|
|
| submitter | string | 否 | 提交人 |
|
|
|
| colorTag | string | 否 | 颜色标签 |
|
|
|
| hospitalId | int | 否 | 指定医院 ID |
|
|
|
|
|
|
#### 处理工单
|
|
|
> **PUT** `/api/admin/orders/{id}/process` · ✅ 需认证
|
|
|
|
|
|
**路径参数：** `id` — 工单 ID
|
|
|
|
|
|
**请求体：**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| processRemark | string | 是 | 处理备注（HTML） |
|
|
|
| status | string | 是 | 目标状态（如"已完成"） |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 1.3 医院信息
|
|
|
|
|
|
#### 获取医院列表
|
|
|
> **GET** `/api/admin/hospitals` · ✅ 需认证
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| page | int | 否 | 页码，默认 1 |
|
|
|
| pageSize | int | 否 | 每页条数，默认 10 |
|
|
|
| keyword | string | 否 | 关键词搜索 |
|
|
|
| category | string | 否 | 类别筛选 |
|
|
|
|
|
|
#### 获取医院详情
|
|
|
> **GET** `/api/admin/hospitals/{id}` · ✅ 需认证
|
|
|
|
|
|
| 路径参数 | 类型 | 说明 |
|
|
|
|---|---|---|
|
|
|
| id | int | 医院 ID |
|
|
|
|
|
|
#### 添加医院
|
|
|
> **POST** `/api/admin/hospitals` · ✅ 需认证
|
|
|
|
|
|
**请求体：**
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| name | string | 是 | 医院名称 |
|
|
|
| customerCategory | string | 是 | 客户类别（如 A） |
|
|
|
| contactDept | string | 否 | 联系部门 |
|
|
|
| contactPerson | string | 否 | 联系人 |
|
|
|
| contactPosition | string | 否 | 联系人职位 |
|
|
|
| contactPhone | string | 否 | 联系电话 |
|
|
|
| signDate | DateTime | 是 | 签约日期 |
|
|
|
| acceptDate | DateTime | 是 | 验收日期 |
|
|
|
| contractYears | int | 是 | 合同年限 |
|
|
|
| maintenanceEnd | DateTime | 是 | 维保到期日 |
|
|
|
| managerId | int | 否 | 负责人 ID |
|
|
|
| remark | string | 否 | 备注 |
|
|
|
|
|
|
#### 更新医院信息
|
|
|
> **PUT** `/api/admin/hospitals/{id}` · ✅ 需认证
|
|
|
|
|
|
请求体同「添加医院」
|
|
|
|
|
|
---
|
|
|
|
|
|
### 1.4 账号管理
|
|
|
|
|
|
#### 获取账号列表
|
|
|
> **GET** `/api/admin/accounts` · ✅ 需认证
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| type | string | 否 | 用户类型（Admin/Hospital） |
|
|
|
| page | int | 否 | 页码 |
|
|
|
| pageSize | int | 否 | 每页条数 |
|
|
|
| keyword | string | 否 | 关键词搜索 |
|
|
|
|
|
|
#### 添加账号
|
|
|
> **POST** `/api/admin/accounts` · ✅ 需认证
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| username | string | 是 | 用户名 |
|
|
|
| password | string | 是 | 密码 |
|
|
|
| name | string | 是 | 姓名 |
|
|
|
| gender | string | 否 | 性别 |
|
|
|
| userType | string | 是 | 类型（Admin/Hospital） |
|
|
|
| hospitalId | int | 否 | 所属医院 ID |
|
|
|
| role | string | 否 | 角色 |
|
|
|
|
|
|
#### 编辑账号
|
|
|
> **PUT** `/api/admin/accounts/{id}` · ✅ 需认证
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| name | string | 否 | 姓名 |
|
|
|
| gender | string | 否 | 性别 |
|
|
|
| hospitalId | int | 否 | 所属医院 ID |
|
|
|
| role | string | 否 | 角色 |
|
|
|
|
|
|
#### 切换账号状态
|
|
|
> **PUT** `/api/admin/accounts/{id}/status` · ✅ 需认证
|
|
|
|
|
|
切换启用/禁用状态，无需请求体。
|
|
|
|
|
|
#### 重置密码
|
|
|
> **POST** `/api/admin/accounts/{id}/reset-password` · ✅ 需认证
|
|
|
|
|
|
重置为默认密码 `123456`，无需请求体。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 二、医院端 API — `/api/hospital`
|
|
|
|
|
|
### 2.1 登录
|
|
|
|
|
|
> **POST** `/api/hospital/login` · 无需认证
|
|
|
|
|
|
请求体同管理端登录。
|
|
|
|
|
|
> ⚠️ 仅允许 `userType == "Hospital"` 的账号登录，否则返回 403
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2.2 工作台
|
|
|
|
|
|
#### 获取统计数据
|
|
|
> **GET** `/api/hospital/workbench` · ✅ 需认证
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| period | string | 否 | 统计周期（month） |
|
|
|
| start | DateTime | 否 | 开始日期 |
|
|
|
| end | DateTime | 否 | 结束日期 |
|
|
|
|
|
|
**响应数据：**
|
|
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|
|---|---|---|
|
|
|
| totalOrders | int | 总工单数 |
|
|
|
| completedOrders | int | 已完成数 |
|
|
|
| pendingOrders | int | 待处理数 |
|
|
|
| highPriorityOrders | int | 高优先级数 |
|
|
|
| trendData | array | 趋势图数据 `[{ date, submitCount, completeCount }]` |
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2.3 工单管理
|
|
|
|
|
|
#### 我的工单列表
|
|
|
> **GET** `/api/hospital/orders` · ✅ 需认证
|
|
|
|
|
|
查询参数同管理端工单列表（不含 `hospitalId`，自动绑定当前医院）
|
|
|
|
|
|
#### 工单详情
|
|
|
> **GET** `/api/hospital/orders/{id}` · ✅ 需认证
|
|
|
|
|
|
| 路径参数 | 类型 | 说明 |
|
|
|
|---|---|---|
|
|
|
| id | int | 工单 ID |
|
|
|
|
|
|
返回工单详情（含附件列表 + 状态流转日志）
|
|
|
|
|
|
#### 快速提交工单
|
|
|
> **POST** `/api/hospital/orders` · ✅ 需认证
|
|
|
|
|
|
请求体同管理端提交工单（不含 `hospitalId`，自动绑定当前医院）
|
|
|
|
|
|
#### 编辑工单
|
|
|
> **PUT** `/api/hospital/orders/{id}` · ✅ 需认证
|
|
|
|
|
|
#### 取消工单
|
|
|
> **DELETE** `/api/hospital/orders/{id}` · ✅ 需认证
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2.4 积分
|
|
|
|
|
|
#### 积分总览
|
|
|
> **GET** `/api/hospital/points` · ✅ 需认证
|
|
|
|
|
|
**响应：**
|
|
|
```json
|
|
|
{ "totalPoints": 0, "rewardCount": 0 }
|
|
|
```
|
|
|
|
|
|
#### 积分明细
|
|
|
> **GET** `/api/hospital/points/details` · ✅ 需认证
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| page | int | 否 | 页码，默认 1 |
|
|
|
| pageSize | int | 否 | 每页条数，默认 10 |
|
|
|
|
|
|
**响应：**
|
|
|
```json
|
|
|
[{ "source": "string", "orderNo": "string", "changeAmount": 0, "description": "string", "createdAt": "2025-01-01" }]
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 三、附件上传下载 — `/api/upload`
|
|
|
|
|
|
### 3.1 上传附件
|
|
|
|
|
|
> **POST** `/api/upload` · ✅ 需认证
|
|
|
|
|
|
**请求格式：** `multipart/form-data`
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| orderNo | string | 是 | 关联工单号 |
|
|
|
| files | file[] | 是 | 文件列表 |
|
|
|
|
|
|
- 单文件最大：50 MB
|
|
|
- 存储路径：`Uploads/Attachments/`
|
|
|
|
|
|
### 3.2 下载/预览附件
|
|
|
|
|
|
> **GET** `/api/upload/{fileName}` · 无需认证
|
|
|
|
|
|
| 路径参数 | 类型 | 说明 |
|
|
|
|---|---|---|
|
|
|
| fileName | string | 文件名 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🏷️ 附录：状态码说明
|
|
|
|
|
|
| 状态码 | 说明 |
|
|
|
|---|---|
|
|
|
| 200 | 请求成功 |
|
|
|
| 400 | 参数校验失败 |
|
|
|
| 401 | 未登录或 Token 过期 |
|
|
|
| 403 | 无操作权限 |
|
|
|
| 404 | 资源不存在 |
|
|
|
| 500 | 服务器内部错误 |
|