# API接口文档

<cite>
**本文档引用的文件**
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/core/security.py](file://backend/app/core/security.py)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py)
- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py)
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py)
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介

本文件为医院绩效管理系统API接口的完整文档。系统采用FastAPI + SQLAlchemy 2.0架构，支持异步IO操作，提供RESTful API接口，涵盖认证授权、基础数据管理、绩效考核、工资核算、财务统计、系统管理等核心功能模块。

系统采用JWT令牌认证机制，支持管理员(admin)、经理(manager)、普通员工(staff)三种角色权限控制，确保数据安全和业务流程的规范性。

## 项目结构

后端采用模块化架构设计，主要目录结构如下：

```mermaid
graph TB
subgraph "后端应用结构"
A["app/"] --> B["api/v1/"]
A --> C["core/"]
A --> D["models/"]
A --> E["services/"]
A --> F["schemas/"]
B --> B1["认证接口(auth.py)"]
B --> B2["基础数据(departments.py, staff.py, indicators.py)"]
B --> B3["考核管理(performance_plans.py, assessments.py)"]
B --> B4["工资核算(salary.py)"]
B --> B5["财务核算(finance.py)"]
B --> B6["统计分析(stats.py)"]
B --> B7["系统管理(menus.py, templates.py)"]
C --> C1["安全配置(security.py)"]
C --> C2["数据库配置(database.py)"]
C --> C3["配置管理(config.py)"]
D --> D1["数据模型(models.py)"]
F --> F1["数据模式(schemas.py)"]
end
```

**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)

**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)

## 核心组件

### 认证与安全机制

系统采用JWT令牌进行身份认证，支持多种权限级别：

- **用户认证**: OAuth2密码模式，支持用户名密码登录
- **权限控制**: 
  - 普通用户: 仅能查看和基本操作
  - 经理用户: 可进行数据维护和审批操作
  - 管理员: 拥有系统完全管理权限
- **密码安全**: 使用bcrypt进行密码哈希存储

### 数据模型架构

系统采用SQLAlchemy ORM映射，核心实体包括：

- **基础实体**: 科室、员工、指标
- **业务实体**: 考核记录、工资记录、绩效计划
- **系统实体**: 用户、菜单、指标模板

**章节来源**
- [backend/app/core/security.py](file://backend/app/core/security.py#L18-L110)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)

## 架构概览

```mermaid
graph TB
subgraph "客户端层"
Web[Web前端]
Mobile[移动端]
API[第三方系统]
end
subgraph "API网关层"
FastAPI[FastAPI应用]
CORS[CORS中间件]
Router[路由分发]
end
subgraph "业务逻辑层"
Auth[认证模块]
Services[业务服务层]
Security[安全控制]
end
subgraph "数据访问层"
DB[(PostgreSQL数据库)]
ORM[SQLAlchemy ORM]
end
subgraph "配置层"
Config[应用配置]
Logging[日志配置]
end
Web --> FastAPI
Mobile --> FastAPI
API --> FastAPI
FastAPI --> CORS
FastAPI --> Router
FastAPI --> Auth
FastAPI --> Services
FastAPI --> Security
Services --> ORM
ORM --> DB
FastAPI --> Config
Auth --> Config
Security --> Config
Logging --> Config
```

**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L19-L48)
- [backend/app/core/security.py](file://backend/app/core/security.py#L21-L53)

## 详细组件分析

### 认证接口模块

#### 用户登录
- **HTTP方法**: POST
- **URL模式**: `/api/v1/auth/login`
- **请求参数**: 
  - username: 字符串，最小长度3，最大长度50
  - password: 字符串，最小长度6，最大长度100
- **响应格式**: 
  ```json
  {
    "access_token": "字符串",
    "token_type": "bearer"
  }
  ```
- **错误码**: 401(用户名或密码错误)，403(账户已禁用)

#### 用户注册
- **HTTP方法**: POST  
- **URL模式**: `/api/v1/auth/register`
- **请求参数**:
  - username: 字符串，唯一性约束
  - password: 字符串，密码哈希处理
  - staff_id: 整数，关联员工信息
  - role: 字符串，角色类型
- **响应格式**: 
  ```json
  {
    "code": 200,
    "message": "注册成功",
    "data": {"id": 1}
  }
  ```

#### 获取当前用户信息
- **HTTP方法**: GET
- **URL模式**: `/api/v1/auth/me`
- **权限要求**: 需要有效JWT令牌
- **响应格式**: 用户基本信息

**章节来源**
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)

### 基础数据接口模块

#### 科室管理接口

##### 获取科室列表
- **HTTP方法**: GET
- **URL模式**: `/api/v1/departments`
- **查询参数**:
  - dept_type: 科室类型过滤
  - is_active: 是否启用过滤
  - page/page_size: 分页参数
- **响应格式**: 分页响应，包含科室列表和统计信息

##### 创建科室
- **HTTP方法**: POST
- **URL模式**: `/api/v1/departments`
- **权限要求**: 管理员或经理权限
- **请求验证**: 科室编码唯一性检查

##### 更新科室
- **HTTP方法**: PUT
- **URL模式**: `/api/v1/departments/{dept_id}`

##### 删除科室
- **HTTP方法**: DELETE
- **URL模式**: `/api/v1/departments/{dept_id}`
- **权限要求**: 管理员或经理权限
- **业务规则**: 无法删除存在子科室的科室

#### 员工管理接口

##### 获取员工列表
- **HTTP方法**: GET
- **URL模式**: `/api/v1/staff`
- **查询参数**:
  - department_id: 科室ID过滤
  - status: 员工状态过滤
  - keyword: 搜索关键词
- **响应格式**: 包含科室名称的员工列表

##### 创建员工
- **HTTP方法**: POST
- **URL模式**: `/api/v1/staff`
- **权限要求**: 管理员或经理权限
- **请求验证**: 工号唯一性检查

##### 获取科室员工
- **HTTP方法**: GET
- **URL模式**: `/api/v1/staff/department/{department_id}`

#### 指标管理接口

##### 获取指标列表
- **HTTP方法**: GET
- **URL模式**: `/api/v1/indicators`
- **查询参数**:
  - indicator_type: 指标类型
  - bs_dimension: 平衡计分卡维度
  - is_active: 是否启用

##### 创建指标
- **HTTP方法**: POST
- **URL模式**: `/api/v1/indicators`
- **权限要求**: 管理员或经理权限
- **请求验证**: 指标编码唯一性检查

##### 指标模板管理
- **HTTP方法**: GET
- **URL模式**: `/api/v1/indicators/templates/list`
- **业务功能**: 获取可用的指标模板列表

**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L108)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L124)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)

### 考核管理接口模块

#### 绩效计划管理

##### 获取计划列表
- **HTTP方法**: GET
- **URL模式**: `/api/v1/plans`
- **查询参数**:
  - plan_level: 计划层级
  - plan_year: 计划年度
  - department_id: 科室ID
  - status: 状态过滤

##### 创建绩效计划
- **HTTP方法**: POST
- **URL模式**: `/api/v1/plans`
- **请求参数**: 计划基本信息和KPI关联

##### 提交计划
- **HTTP方法**: POST
- **URL模式**: `/api/v1/plans/{plan_id}/submit`

##### 审批计划
- **HTTP方法**: POST
- **URL模式**: `/api/v1/plans/{plan_id}/approve`
- **权限要求**: 管理员或经理权限

##### 激活计划
- **HTTP方法**: POST
- **URL模式**: `/api/v1/plans/{plan_id}/activate`
- **权限要求**: 管理员或经理权限

#### 绩效考核管理

##### 获取考核列表
- **HTTP方法**: GET
- **URL模式**: `/api/v1/assessments`
- **查询参数**:
  - staff_id: 员工ID
  - department_id: 科室ID
  - period_year: 年度
  - period_month: 月份
  - status: 状态

##### 创建考核记录
- **HTTP方法**: POST
- **URL模式**: `/api/v1/assessments`

##### 批量创建考核
- **HTTP方法**: POST
- **URL模式**: `/api/v1/assessments/batch-create`
- **权限要求**: 管理员或经理权限

##### 审核考核
- **HTTP方法**: POST
- **URL模式**: `/api/v1/assessments/{assessment_id}/review`
- **权限要求**: 管理员或经理权限

**章节来源**
- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L21-L310)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)

### 工资核算接口模块

#### 工资记录管理

##### 获取工资记录列表
- **HTTP方法**: GET
- **URL模式**: `/api/v1/salary`
- **查询参数**:
  - staff_id: 员工ID
  - department_id: 科室ID
  - period_year: 年度
  - period_month: 月份
  - status: 状态

##### 创建工资记录
- **HTTP方法**: POST
- **URL模式**: `/api/v1/salary`
- **权限要求**: 管理员或经理权限

##### 根据考核生成工资
- **HTTP方法**: POST
- **URL模式**: `/api/v1/salary/generate`
- **权限要求**: 管理员或经理权限

##### 批量生成工资
- **HTTP方法**: POST
- **URL模式**: `/api/v1/salary/batch-generate`
- **权限要求**: 管理员或经理权限

##### 确认工资
- **HTTP方法**: POST
- **URL模式**: `/api/v1/salary/{record_id}/confirm`
- **权限要求**: 管理员或经理权限

**章节来源**
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L20-L156)

### 财务核算接口模块

#### 财务数据查询

##### 获取科室收入
- **HTTP方法**: GET
- **URL模式**: `/api/v1/finance/revenue`

##### 获取科室支出
- **HTTP方法**: GET
- **URL模式**: `/api/v1/finance/expense`

##### 获取收支结余
- **HTTP方法**: GET
- **URL模式**: `/api/v1/finance/balance`

##### 按类别统计收入/支出
- **HTTP方法**: GET
- **URL模式**: `/api/v1/finance/revenue/by-category`
- **URL模式**: `/api/v1/finance/expense/by-category`

##### 获取财务汇总
- **HTTP方法**: GET
- **URL模式**: `/api/v1/finance/summary`

#### 财务记录管理

##### 创建财务记录
- **HTTP方法**: POST
- **URL模式**: `/api/v1/finance`
- **权限要求**: 管理员或经理权限
- **请求验证**: 类别有效性检查

##### 更新财务记录
- **HTTP方法**: PUT
- **URL模式**: `/api/v1/finance/{record_id}`
- **权限要求**: 管理员或经理权限

##### 删除财务记录
- **HTTP方法**: DELETE
- **URL模式**: `/api/v1/finance/{record_id}`
- **权限要求**: 管理员或经理权限

**章节来源**
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L21-L217)

### 统计分析接口模块

#### 绩效统计分析

##### BSC维度分析
- **HTTP方法**: GET
- **URL模式**: `/api/v1/stats/bsc-dimension`

##### 科室绩效统计
- **HTTP方法**: GET
- **URL模式**: `/api/v1/stats/department`

##### 趋势分析
- **HTTP方法**: GET
- **URL模式**: `/api/v1/stats/trend`
- **查询参数**: months(最近几个月)

##### 周期统计
- **HTTP方法**: GET
- **URL模式**: `/api/v1/stats/period`

##### 关键指标仪表盘
- **HTTP方法**: GET
- **URL模式**: `/api/v1/stats/kpi-gauges`

#### 排名统计

##### 科室绩效排名
- **HTTP方法**: GET
- **URL模式**: `/api/v1/stats/department-ranking`

##### 绩效排名
- **HTTP方法**: GET
- **URL模式**: `/api/v1/stats/ranking`

#### 指标完成度
- **HTTP方法**: GET
- **URL模式**: `/api/v1/stats/completion`

**章节来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L242)

### 系统管理接口模块

#### 菜单管理

##### 获取菜单树
- **HTTP方法**: GET
- **URL模式**: `/api/v1/menus/tree`
- **查询参数**: visible_only(是否只返回可见菜单)

##### 获取菜单列表
- **HTTP方法**: GET
- **URL模式**: `/api/v1/menus`

##### 创建菜单
- **HTTP方法**: POST
- **URL模式**: `/api/v1/menus`
- **权限要求**: 管理员或经理权限

##### 更新菜单
- **HTTP方法**: PUT
- **URL模式**: `/api/v1/menus/{menu_id}`
- **权限要求**: 管理员或经理权限

##### 删除菜单
- **HTTP方法**: DELETE
- **URL模式**: `/api/v1/menus/{menu_id}`
- **权限要求**: 管理员或经理权限

##### 初始化默认菜单
- **HTTP方法**: POST
- **URL模式**: `/api/v1/menus/init`
- **权限要求**: 管理员权限

#### 指标模板管理

##### 获取模板列表
- **HTTP方法**: GET
- **URL模式**: `/api/v1/templates`

##### 获取模板类型列表
- **HTTP方法**: GET
- **URL模式**: `/api/v1/templates/types`

##### 获取BSC维度列表
- **HTTP方法**: GET
- **URL模式**: `/api/v1/templates/dimensions`

##### 创建模板
- **HTTP方法**: POST
- **URL模式**: `/api/v1/templates`
- **权限要求**: 管理员或经理权限

##### 添加模板指标
- **HTTP方法**: POST
- **URL模式**: `/api/v1/templates/{template_id}/indicators`
- **权限要求**: 管理员或经理权限

##### 批量添加模板指标
- **HTTP方法**: POST
- **URL模式**: `/api/v1/templates/{template_id}/indicators/batch`
- **权限要求**: 管理员或经理权限

**章节来源**
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L17-L164)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L272)

## 依赖关系分析

```mermaid
graph TB
subgraph "API层"
AuthAPI[认证API]
BasicAPI[基础数据API]
AssessmentAPI[考核API]
SalaryAPI[工资API]
FinanceAPI[财务API]
StatsAPI[统计API]
MenuAPI[菜单API]
TemplateAPI[模板API]
end
subgraph "服务层"
AuthService[认证服务]
DeptService[科室服务]
StaffService[员工服务]
IndService[指标服务]
PlanService[计划服务]
AssessService[考核服务]
SalaryService[工资服务]
FinanceService[财务服务]
StatsService[统计服务]
MenuService[菜单服务]
TemplateService[模板服务]
end
subgraph "数据层"
UserModel[用户模型]
DeptModel[科室模型]
StaffModel[员工模型]
IndModel[指标模型]
PlanModel[计划模型]
AssessModel[考核模型]
SalaryModel[工资模型]
FinanceModel[财务模型]
MenuModel[菜单模型]
TemplateModel[模板模型]
end
AuthAPI --> AuthService
BasicAPI --> DeptService
BasicAPI --> StaffService
BasicAPI --> IndService
AssessmentAPI --> PlanService
AssessmentAPI --> AssessService
SalaryAPI --> SalaryService
FinanceAPI --> FinanceService
StatsAPI --> StatsService
MenuAPI --> MenuService
TemplateAPI --> TemplateService
AuthService --> UserModel
DeptService --> DeptModel
StaffService --> StaffModel
IndService --> IndModel
PlanService --> PlanModel
AssessService --> AssessModel
SalaryService --> SalaryModel
FinanceService --> FinanceModel
MenuService --> MenuModel
TemplateService --> TemplateModel
```

**图表来源**
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L1-L217)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L164)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)

**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)

## 性能考虑

### 数据库优化策略

1. **索引优化**
   - 关键查询字段建立复合索引
   - 时间范围查询优化
   - 多条件过滤查询优化

2. **查询优化**
   - 分页查询避免全表扫描
   - 连接查询优化
   - 子查询优化

3. **缓存策略**
   - 配置热点数据缓存
   - 结果集缓存
   - 查询结果缓存

### 异步处理

系统采用异步IO架构，支持高并发请求处理：

- **异步数据库操作**: SQLAlchemy 2.0异步支持
- **异步文件处理**: 日志和配置文件异步读取
- **异步任务队列**: 后台任务处理

### 安全考虑

1. **认证安全**
   - JWT令牌过期时间控制
   - 密码哈希存储
   - 会话管理

2. **授权控制**
   - 基于角色的访问控制(RBAC)
   - 请求权限验证
   - 数据访问权限控制

3. **输入验证**
   - 参数类型验证
   - 长度和范围验证
   - 格式验证

## 故障排除指南

### 常见错误码

| 错误码 | 描述 | 可能原因 |
|--------|------|----------|
| 400 | 请求参数错误 | 参数类型不正确或缺失 |
| 401 | 未授权 | JWT令牌无效或过期 |
| 403 | 禁止访问 | 权限不足或账户被禁用 |
| 404 | 资源不存在 | 请求的资源不存在 |
| 422 | 数据验证错误 | 业务规则验证失败 |
| 500 | 服务器内部错误 | 服务器异常 |

### 调试步骤

1. **检查认证状态**
   - 验证JWT令牌有效性
   - 检查用户权限级别
   - 确认账户状态正常

2. **验证请求参数**
   - 检查必填参数
   - 验证参数格式
   - 确认参数范围

3. **查看系统日志**
   - 应用程序日志
   - 数据库查询日志
   - 错误日志分析

4. **测试API端点**
   - 使用Swagger UI测试
   - 编写单元测试
   - 集成测试验证

**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L58-L75)

## 结论

本API接口文档涵盖了医院绩效管理系统的核心功能模块，提供了完整的RESTful API规范。系统采用现代化的技术栈，具备良好的扩展性和安全性。通过清晰的权限控制和数据验证机制，确保了系统的稳定运行。

建议在实际部署时：
1. 配置适当的环境变量和数据库连接
2. 设置合理的JWT令牌过期时间
3. 实施监控和日志记录
4. 定期备份数据库
5. 进行安全审计和渗透测试

## 附录

### API版本管理

系统采用URL前缀版本控制：
- 版本前缀: `/api/v1`
- 开放API文档: `/api/v1/docs`
- Redoc文档: `/api/v1/redoc`

### 速率限制

系统支持多种速率限制策略：
- 基于IP的请求频率限制
- 基于用户的API调用限制
- 针对敏感操作的额外限制

### 请求响应示例

#### 成功响应格式
```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "total": 0,
  "page": 1,
  "page_size": 20
}
```

#### 错误响应格式
```json
{
  "code": 400,
  "message": "错误描述",
  "data": null
}
```

### 参数验证规则

1. **字符串类型**: 最小长度、最大长度、字符集验证
2. **数值类型**: 最小值、最大值、精度验证
3. **日期时间**: 格式验证、范围验证
4. **枚举类型**: 值域验证
5. **复合类型**: 结构验证、嵌套验证