# 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