557 lines
8.3 KiB
Markdown
557 lines
8.3 KiB
Markdown
# API接口文档
|
|
|
|
## 基础信息
|
|
|
|
- **Base URL**: `http://localhost:8000/api/v1`
|
|
- **认证方式**: JWT Bearer Token
|
|
- **响应格式**: JSON
|
|
|
|
## 通用响应格式
|
|
|
|
### 成功响应
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": { ... }
|
|
}
|
|
```
|
|
|
|
### 分页响应
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": [ ... ],
|
|
"total": 100,
|
|
"page": 1,
|
|
"page_size": 20
|
|
}
|
|
```
|
|
|
|
### 错误响应
|
|
```json
|
|
{
|
|
"detail": "错误信息"
|
|
}
|
|
```
|
|
|
|
## 认证接口
|
|
|
|
### 登录
|
|
```
|
|
POST /auth/login
|
|
```
|
|
|
|
**请求体**:
|
|
```json
|
|
{
|
|
"username": "admin",
|
|
"password": "admin123"
|
|
}
|
|
```
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
"token_type": "bearer"
|
|
}
|
|
```
|
|
|
|
### 获取当前用户
|
|
```
|
|
GET /auth/me
|
|
Authorization: Bearer {token}
|
|
```
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"username": "admin",
|
|
"role": "admin",
|
|
"is_active": true
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 科室管理
|
|
|
|
### 获取科室列表
|
|
```
|
|
GET /departments
|
|
```
|
|
|
|
**查询参数**:
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| name | string | 科室名称(模糊搜索) |
|
|
| dept_type | string | 科室类型 |
|
|
| is_active | boolean | 是否启用 |
|
|
| page | int | 页码 |
|
|
| page_size | int | 每页数量 |
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "内科",
|
|
"code": "NK001",
|
|
"dept_type": "clinical",
|
|
"parent_id": null,
|
|
"level": 1,
|
|
"sort_order": 1,
|
|
"is_active": true,
|
|
"created_at": "2024-01-01T00:00:00",
|
|
"updated_at": "2024-01-01T00:00:00"
|
|
}
|
|
],
|
|
"total": 10,
|
|
"page": 1,
|
|
"page_size": 20
|
|
}
|
|
```
|
|
|
|
### 获取科室树
|
|
```
|
|
GET /departments/tree
|
|
```
|
|
|
|
**响应**: 返回树形结构的科室列表
|
|
|
|
### 创建科室
|
|
```
|
|
POST /departments
|
|
```
|
|
|
|
**请求体**:
|
|
```json
|
|
{
|
|
"name": "内科",
|
|
"code": "NK001",
|
|
"dept_type": "clinical",
|
|
"parent_id": null,
|
|
"level": 1,
|
|
"sort_order": 1,
|
|
"description": "内科科室"
|
|
}
|
|
```
|
|
|
|
### 更新科室
|
|
```
|
|
PUT /departments/{id}
|
|
```
|
|
|
|
### 删除科室
|
|
```
|
|
DELETE /departments/{id}
|
|
```
|
|
|
|
---
|
|
|
|
## 员工管理
|
|
|
|
### 获取员工列表
|
|
```
|
|
GET /staff
|
|
```
|
|
|
|
**查询参数**:
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| name | string | 姓名(模糊搜索) |
|
|
| employee_id | string | 工号 |
|
|
| department_id | int | 科室ID |
|
|
| status | string | 状态 |
|
|
| page | int | 页码 |
|
|
| page_size | int | 每页数量 |
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"employee_id": "EMP001",
|
|
"name": "张三",
|
|
"department_id": 1,
|
|
"department_name": "内科",
|
|
"position": "医师",
|
|
"title": "主治医师",
|
|
"phone": "13800138000",
|
|
"email": "zhangsan@example.com",
|
|
"base_salary": 5000.00,
|
|
"performance_ratio": 1.2,
|
|
"status": "active",
|
|
"hire_date": "2020-01-01T00:00:00",
|
|
"created_at": "2024-01-01T00:00:00",
|
|
"updated_at": "2024-01-01T00:00:00"
|
|
}
|
|
],
|
|
"total": 50,
|
|
"page": 1,
|
|
"page_size": 20
|
|
}
|
|
```
|
|
|
|
### 创建员工
|
|
```
|
|
POST /staff
|
|
```
|
|
|
|
**请求体**:
|
|
```json
|
|
{
|
|
"employee_id": "EMP001",
|
|
"name": "张三",
|
|
"department_id": 1,
|
|
"position": "医师",
|
|
"title": "主治医师",
|
|
"phone": "13800138000",
|
|
"email": "zhangsan@example.com",
|
|
"base_salary": 5000.00,
|
|
"performance_ratio": 1.2,
|
|
"status": "active",
|
|
"hire_date": "2020-01-01T00:00:00"
|
|
}
|
|
```
|
|
|
|
### 更新员工
|
|
```
|
|
PUT /staff/{id}
|
|
```
|
|
|
|
### 删除员工
|
|
```
|
|
DELETE /staff/{id}
|
|
```
|
|
|
|
---
|
|
|
|
## 考核指标
|
|
|
|
### 获取指标列表
|
|
```
|
|
GET /indicators
|
|
```
|
|
|
|
**查询参数**:
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| name | string | 指标名称(模糊搜索) |
|
|
| indicator_type | string | 指标类型 |
|
|
| is_active | boolean | 是否启用 |
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "门诊量",
|
|
"code": "IND001",
|
|
"indicator_type": "quantity",
|
|
"weight": 1.0,
|
|
"max_score": 100.0,
|
|
"target_value": 500.0,
|
|
"unit": "人次",
|
|
"calculation_method": "实际值/目标值*100",
|
|
"description": "月度门诊接诊量",
|
|
"is_active": true,
|
|
"created_at": "2024-01-01T00:00:00",
|
|
"updated_at": "2024-01-01T00:00:00"
|
|
}
|
|
],
|
|
"total": 20,
|
|
"page": 1,
|
|
"page_size": 20
|
|
}
|
|
```
|
|
|
|
### 创建指标
|
|
```
|
|
POST /indicators
|
|
```
|
|
|
|
### 更新指标
|
|
```
|
|
PUT /indicators/{id}
|
|
```
|
|
|
|
### 删除指标
|
|
```
|
|
DELETE /indicators/{id}
|
|
```
|
|
|
|
---
|
|
|
|
## 考核管理
|
|
|
|
### 获取考核列表
|
|
```
|
|
GET /assessments
|
|
```
|
|
|
|
**查询参数**:
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| staff_id | int | 员工ID |
|
|
| department_id | int | 科室ID |
|
|
| period_year | int | 年度 |
|
|
| period_month | int | 月份 |
|
|
| status | string | 状态 |
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"staff_id": 1,
|
|
"staff_name": "张三",
|
|
"department_name": "内科",
|
|
"period_year": 2024,
|
|
"period_month": 1,
|
|
"period_type": "monthly",
|
|
"total_score": 85.5,
|
|
"weighted_score": 85.5,
|
|
"status": "submitted",
|
|
"created_at": "2024-01-15T00:00:00"
|
|
}
|
|
],
|
|
"total": 30,
|
|
"page": 1,
|
|
"page_size": 20
|
|
}
|
|
```
|
|
|
|
### 获取考核详情
|
|
```
|
|
GET /assessments/{id}
|
|
```
|
|
|
|
**响应**: 包含考核明细的完整信息
|
|
|
|
### 创建考核
|
|
```
|
|
POST /assessments
|
|
```
|
|
|
|
**请求体**:
|
|
```json
|
|
{
|
|
"staff_id": 1,
|
|
"period_year": 2024,
|
|
"period_month": 1,
|
|
"period_type": "monthly",
|
|
"details": [
|
|
{
|
|
"indicator_id": 1,
|
|
"actual_value": 450,
|
|
"score": 90,
|
|
"evidence": "门诊系统导出数据",
|
|
"remark": ""
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 更新考核
|
|
```
|
|
PUT /assessments/{id}
|
|
```
|
|
|
|
### 提交考核
|
|
```
|
|
POST /assessments/{id}/submit
|
|
```
|
|
|
|
### 审核考核
|
|
```
|
|
POST /assessments/{id}/review
|
|
```
|
|
|
|
**请求体**:
|
|
```json
|
|
{
|
|
"approved": true,
|
|
"remark": "审核通过"
|
|
}
|
|
```
|
|
|
|
### 删除考核
|
|
```
|
|
DELETE /assessments/{id}
|
|
```
|
|
|
|
---
|
|
|
|
## 工资核算
|
|
|
|
### 获取工资列表
|
|
```
|
|
GET /salary
|
|
```
|
|
|
|
**查询参数**:
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| staff_id | int | 员工ID |
|
|
| department_id | int | 科室ID |
|
|
| period_year | int | 年度 |
|
|
| period_month | int | 月份 |
|
|
| status | string | 状态 |
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"staff_id": 1,
|
|
"staff_name": "张三",
|
|
"department_name": "内科",
|
|
"period_year": 2024,
|
|
"period_month": 1,
|
|
"base_salary": 5000.00,
|
|
"performance_score": 85.5,
|
|
"performance_bonus": 3000.00,
|
|
"deduction": 0,
|
|
"allowance": 500.00,
|
|
"total_salary": 8500.00,
|
|
"status": "pending",
|
|
"created_at": "2024-02-01T00:00:00"
|
|
}
|
|
],
|
|
"total": 50,
|
|
"page": 1,
|
|
"page_size": 20
|
|
}
|
|
```
|
|
|
|
### 生成工资记录
|
|
```
|
|
POST /salary/generate
|
|
```
|
|
|
|
**请求体**:
|
|
```json
|
|
{
|
|
"period_year": 2024,
|
|
"period_month": 1
|
|
}
|
|
```
|
|
|
|
### 更新工资记录
|
|
```
|
|
PUT /salary/{id}
|
|
```
|
|
|
|
### 确认工资
|
|
```
|
|
POST /salary/{id}/confirm
|
|
```
|
|
|
|
---
|
|
|
|
## 统计报表
|
|
|
|
### 科室绩效统计
|
|
```
|
|
GET /stats/departments
|
|
```
|
|
|
|
**查询参数**:
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| period_year | int | 年度 |
|
|
| period_month | int | 月份 |
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "success",
|
|
"data": [
|
|
{
|
|
"department_id": 1,
|
|
"department_name": "内科",
|
|
"staff_count": 20,
|
|
"avg_score": 85.5,
|
|
"total_bonus": 60000.00
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 员工绩效排名
|
|
```
|
|
GET /stats/ranking
|
|
```
|
|
|
|
**查询参数**:
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| period_year | int | 年度 |
|
|
| period_month | int | 月份 |
|
|
| department_id | int | 科室ID(可选) |
|
|
| limit | int | 返回数量 |
|
|
|
|
### 趋势分析
|
|
```
|
|
GET /stats/trend
|
|
```
|
|
|
|
**查询参数**:
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| start_year | int | 开始年度 |
|
|
| start_month | int | 开始月份 |
|
|
| end_year | int | 结束年度 |
|
|
| end_month | int | 结束月份 |
|
|
|
|
### 绩效分布
|
|
```
|
|
GET /stats/distribution
|
|
```
|
|
|
|
**查询参数**:
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| period_year | int | 年度 |
|
|
| period_month | int | 月份 |
|
|
|
|
---
|
|
|
|
## 错误码
|
|
|
|
| 状态码 | 说明 |
|
|
|--------|------|
|
|
| 200 | 成功 |
|
|
| 400 | 请求参数错误 |
|
|
| 401 | 未授权/Token过期 |
|
|
| 403 | 权限不足 |
|
|
| 404 | 资源不存在 |
|
|
| 422 | 数据验证失败 |
|
|
| 500 | 服务器内部错误 |
|
|
|
|
## API文档访问
|
|
|
|
启动后端服务后，可访问：
|
|
- Swagger UI: http://localhost:8000/api/v1/docs
|
|
- ReDoc: http://localhost:8000/api/v1/redoc
|