# 康策 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 | 服务器内部错误 |