# 基础数据接口

<cite>
**本文档引用的文件**
- [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/templates.py](file://backend/app/api/v1/templates.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/main.py](file://backend/app/main.py)
- [frontend/src/api/department.js](file://frontend/src/api/department.js)
- [frontend/src/api/staff.js](file://frontend/src/api/staff.js)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js)
- [frontend/src/api/template.js](file://frontend/src/api/template.js)
</cite>

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

## 简介
本文件为医院绩效管理系统的"基础数据管理接口"提供全面的API文档，覆盖以下四大模块：
- 科室管理：支持科室的增删改查、树形结构查询、层级计算与父子关系维护
- 员工管理：支持员工的增删改查、按科室筛选、状态管理与关联查询
- 考核指标管理：支持指标的增删改查、启用状态管理、模板导入与批量操作
- 指标模板管理：支持模板的增删改查、模板类型与BSC维度枚举、模板指标的增删改查与批量添加

文档详细说明每个模块的接口规范、数据验证规则、关联关系处理、级联操作、分页查询、搜索过滤、排序功能、数据导入导出与批量操作的使用方法。

## 项目结构
后端采用FastAPI + SQLAlchemy 2.0 + 异步数据库访问，遵循分层架构：
- API层：定义路由与请求/响应处理
- 服务层：封装业务逻辑与数据访问
- 模型层：定义数据库表结构与关系
- 模式层：定义Pydantic数据模式与枚举类型
- 前端层：通过统一请求封装调用后端接口

```mermaid
graph TB
subgraph "前端"
FE_API["前端API封装<br/>department.js / staff.js / indicator.js / template.js"]
end
subgraph "后端"
MAIN["FastAPI应用<br/>app/main.py"]
API_DEPT["科室API<br/>api/v1/departments.py"]
API_STAFF["员工API<br/>api/v1/staff.py"]
API_INDICATOR["指标API<br/>api/v1/indicators.py"]
API_TEMPLATE["模板API<br/>api/v1/templates.py"]
SVC_DEPT["科室服务<br/>services/department_service.py"]
SVC_STAFF["员工服务<br/>services/staff_service.py"]
SVC_INDICATOR["指标服务<br/>services/indicator_service.py"]
SVC_TEMPLATE["模板服务<br/>services/template_service.py"]
MODELS["数据模型<br/>models/models.py"]
SCHEMAS["数据模式<br/>schemas/schemas.py"]
end
FE_API --> MAIN
MAIN --> API_DEPT
MAIN --> API_STAFF
MAIN --> API_INDICATOR
MAIN --> API_TEMPLATE
API_DEPT --> SVC_DEPT
API_STAFF --> SVC_STAFF
API_INDICATOR --> SVC_INDICATOR
API_TEMPLATE --> SVC_TEMPLATE
SVC_DEPT --> MODELS
SVC_STAFF --> MODELS
SVC_INDICATOR --> MODELS
SVC_TEMPLATE --> MODELS
API_DEPT --> SCHEMAS
API_STAFF --> SCHEMAS
API_INDICATOR --> SCHEMAS
API_TEMPLATE --> SCHEMAS
```

**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L17-L108)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L17-L124)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L17-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L19-L272)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L13-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L13-L197)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L200)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L10-L743)

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

## 核心组件
- 数据模型与枚举
  - 科室类型：包含临床、医技、护理、行政、后勤等类型
  - 员工状态：在职、休假、离职、退休
  - 指标类型：质量、数量、效率、服务、成本
  - 平衡计分卡维度：财务、客户、内部流程、学习与成长
  - 考核状态：草稿、已提交、已审核、已确认、已驳回
- 数据模式
  - 基础模式：定义字段约束、长度限制、取值范围
  - 创建/更新模式：用于请求体校验
  - 响应模式：用于序列化输出，包含额外字段如部门名称、指标名称等
- 服务层方法
  - 列表查询：支持分页、过滤条件、排序
  - 详情查询：支持关联加载
  - 创建/更新/删除：包含唯一性校验与级联检查
  - 树形结构：手动构建树避免懒加载问题

**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L16-L61)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L10-L743)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L23-L293)

## 架构概览
后端采用分层架构，API层负责路由与权限控制，服务层封装业务逻辑，模型层定义数据库结构，模式层定义数据校验与序列化。前端通过统一的请求封装调用后端接口。

```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "API路由"
participant SVC as "服务层"
participant DB as "数据库"
FE->>API : 发起HTTP请求
API->>SVC : 调用业务方法
SVC->>DB : 执行SQL查询/更新
DB-->>SVC : 返回结果
SVC-->>API : 返回业务结果
API-->>FE : 返回标准化响应
```

**图表来源**
- [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)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L272)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L23-L293)

## 详细组件分析

### 科室管理接口
- 接口列表
  - GET /departments：获取科室列表（支持类型过滤、启用状态过滤、分页）
  - GET /departments/tree：获取科室树形结构（支持类型过滤）
  - GET /departments/{dept_id}：获取科室详情
  - POST /departments：创建科室（需管理员或经理权限）
  - PUT /departments/{dept_id}：更新科室（需管理员或经理权限）
  - DELETE /departments/{dept_id}：删除科室（需管理员或经理权限，存在子科室时拒绝删除）
- 数据验证规则
  - 编码唯一性：创建前检查编码是否已存在
  - 层级计算：根据父级科室自动计算层级
  - 权限控制：创建、更新、删除接口要求管理员或经理角色
- 关联关系与级联
  - 科室与员工：一对多关系，删除前检查是否存在子科室
  - 树形结构：手动构建避免懒加载问题
- 分页、搜索与排序
  - 分页：页码与每页数量参数，支持最小1、最大100
  - 过滤：类型、启用状态
  - 排序：按排序字段与ID排序
- 响应结构
  - 列表接口返回分页响应对象，包含总数、当前页、每页数量与数据数组
  - 详情接口返回单个实体对象

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "departments.py"
participant Service as "DepartmentService"
participant DB as "数据库"
Client->>API : GET /departments?dept_type=&is_active=&page=&page_size=
API->>Service : get_list(dept_type, is_active, page, page_size)
Service->>DB : 查询科室列表
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应
Client->>API : POST /departments
API->>Service : create(dept_data)
Service->>DB : 插入新科室
DB-->>Service : 返回新记录
Service-->>API : 返回创建结果
API-->>Client : 返回成功响应
```

**图表来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L108)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L150)

**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L108)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L150)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L64-L103)

### 员工管理接口
- 接口列表
  - GET /staff：获取员工列表（支持科室ID、状态、关键词搜索、分页）
  - GET /staff/{staff_id}：获取员工详情（包含部门名称）
  - POST /staff：创建员工（需管理员或经理权限）
  - PUT /staff/{staff_id}：更新员工（需管理员或经理权限）
  - DELETE /staff/{staff_id}：删除员工（需管理员或经理权限）
  - GET /staff/department/{department_id}：获取指定科室所有员工
- 数据验证规则
  - 工号唯一性：创建前检查工号是否已存在
  - 状态枚举：仅允许预定义状态
  - 权限控制：创建、更新、删除接口要求管理员或经理角色
- 关联关系与级联
  - 员工与科室：多对一关系，查询时加载部门信息
  - 状态过滤：默认仅显示在职员工
- 分页、搜索与排序
  - 分页：页码与每页数量参数，支持最小1、最大100
  - 过滤：科室ID、状态
  - 搜索：姓名或工号模糊匹配
  - 排序：按ID倒序
- 响应结构
  - 列表接口返回分页响应对象，数据数组中包含部门名称字段
  - 详情接口返回单个实体对象，包含部门名称字段

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "staff.py"
participant Service as "StaffService"
participant DB as "数据库"
Client->>API : GET /staff?department_id=&status=&keyword=&page=&page_size=
API->>Service : get_list(department_id, status, keyword, page, page_size)
Service->>DB : 查询员工列表含部门信息
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应含部门名称
Client->>API : POST /staff
API->>Service : create(staff_data)
Service->>DB : 插入新员工
DB-->>Service : 返回新记录
Service-->>API : 返回创建结果
API-->>Client : 返回成功响应
```

**图表来源**
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L124)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L112)

**章节来源**
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L124)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L115)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L107-L150)

### 考核指标管理接口
- 接口列表
  - GET /indicators：获取指标列表（支持类型、BSC维度、启用状态、分页）
  - GET /indicators/active：获取所有启用的指标
  - GET /indicators/{indicator_id}：获取指标详情
  - POST /indicators：创建指标（需管理员或经理权限）
  - PUT /indicators/{indicator_id}：更新指标（需管理员或经理权限）
  - DELETE /indicators/{indicator_id}：删除指标（需管理员或经理权限）
  - GET /indicators/templates/list：获取指标模板列表
  - POST /indicators/templates/import：导入指标模板（支持覆盖选项）
- 数据验证规则
  - 编码唯一性：创建前检查编码是否已存在
  - 权重范围：权重必须在合理范围内
  - 启用状态：支持启用/禁用切换
  - 权限控制：创建、更新、删除、模板导入接口要求管理员或经理角色
- 关联关系与级联
  - 指标与考核明细：一对多关系，删除前需确保无关联明细
  - 模板导入：支持覆盖现有指标或跳过
- 分页、搜索与排序
  - 分页：页码与每页数量参数，支持最小1、最大100
  - 过滤：类型、BSC维度、启用状态
  - 排序：按类型与ID排序
- 响应结构
  - 列表接口返回分页响应对象
  - 详情接口返回单个实体对象
  - 模板导入接口返回导入数量统计

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "indicators.py"
participant Service as "IndicatorService"
participant DB as "数据库"
Client->>API : GET /indicators?indicator_type=&bs_dimension=&is_active=&page=&page_size=
API->>Service : get_list(...)
Service->>DB : 查询指标列表
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应
Client->>API : POST /indicators/templates/import?overwrite=false
API->>Service : import_template(template_data, overwrite)
Service->>DB : 批量插入或更新指标
DB-->>Service : 返回插入数量
Service-->>API : 返回导入统计
API-->>Client : 返回成功响应含创建数量
```

**图表来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)

**章节来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L153-L193)

### 指标模板管理接口
- 接口列表
  - GET /templates：获取模板列表（支持类型、启用状态、分页）
  - GET /templates/types：获取模板类型列表
  - GET /templates/dimensions：获取BSC维度列表
  - GET /templates/{template_id}：获取模板详情（包含模板指标详情）
  - POST /templates：创建模板（需管理员或经理权限）
  - PUT /templates/{template_id}：更新模板（需管理员或经理权限）
  - DELETE /templates/{template_id}：删除模板（需管理员或经理权限）
  - GET /templates/{template_id}/indicators：获取模板指标列表
  - POST /templates/{template_id}/indicators：添加模板指标（需管理员或经理权限）
  - PUT /templates/{template_id}/indicators/{indicator_id}：更新模板指标（需管理员或经理权限）
  - DELETE /templates/{template_id}/indicators/{indicator_id}：移除模板指标（需管理员或经理权限）
  - POST /templates/{template_id}/indicators/batch：批量添加模板指标（需管理员或经理权限）
- 数据验证规则
  - 模板编码唯一性：创建前检查编码是否已存在
  - 权重范围：权重必须在合理范围内
  - 排序字段：支持自定义排序，未提供时按最大排序+1
  - 权限控制：所有模板相关接口要求管理员或经理角色
- 关联关系与级联
  - 模板与模板指标：一对多关系，支持增删改查与批量添加
  - 模板指标与指标：多对一关系，查询时加载指标详细信息
- 分页、搜索与排序
  - 分页：页码与每页数量参数，支持最小1、最大100
  - 过滤：类型、启用状态
  - 排序：按类型与ID排序
- 响应结构
  - 列表接口返回分页响应对象，包含指标数量统计
  - 详情接口返回模板对象与指标详情数组
  - 批量添加接口返回添加数量统计

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "templates.py"
participant Service as "TemplateService"
participant DB as "数据库"
Client->>API : GET /templates?template_type=&is_active=&page=&page_size=
API->>Service : get_list(...)
Service->>DB : 查询模板列表含指标数量
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应含指标数量
Client->>API : POST /templates/{template_id}/indicators/batch
API->>Service : batch_add_template_indicators(template_id, indicators_data)
Service->>DB : 批量插入模板指标
DB-->>Service : 返回插入结果
Service-->>API : 返回批量统计
API-->>Client : 返回成功响应含添加数量
```

**图表来源**
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L272)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L23-L293)

**章节来源**
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L272)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L23-L293)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L200)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L640-L743)

## 依赖分析
- 模块耦合
  - API层仅依赖服务层，不直接操作数据库
  - 服务层依赖模型层进行数据库操作
  - 模式层为API与服务层提供数据校验与序列化
- 外部依赖
  - FastAPI：Web框架与路由装饰器
  - SQLAlchemy 2.0：异步ORM与查询构建
  - Pydantic：数据模式与验证
- 权限控制
  - 部分接口要求管理员或经理角色
  - 使用依赖注入获取当前用户并进行权限校验

```mermaid
graph TB
API["API层<br/>departments.py / staff.py / indicators.py / templates.py"]
SVC["服务层<br/>department_service.py / staff_service.py / indicator_service.py / template_service.py"]
MODELS["模型层<br/>models.py"]
SCHEMAS["模式层<br/>schemas.py"]
API --> SVC
SVC --> MODELS
API --> SCHEMAS
SVC --> SCHEMAS
```

**图表来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L17-L108)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L17-L124)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L17-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L19-L272)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L13-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L13-L197)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L200)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L10-L743)

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

## 性能考虑
- 分页与索引
  - 列表查询均支持分页，避免一次性返回大量数据
  - 数据库表建立了必要的索引以提升查询性能
- 关联查询
  - 使用selectinload优化N+1查询问题
  - 树形结构查询手动构建，避免懒加载导致的性能问题
- 数据验证
  - Pydantic模式在请求进入业务层前完成数据验证
  - 唯一性检查在创建前执行，减少无效写入
- 异步处理
  - 使用异步数据库连接，提升并发处理能力

## 故障排除指南
- 常见错误与处理
  - 404错误：资源不存在（科室、员工、指标、模板）
  - 400错误：删除失败（存在子资源或状态不允许）
  - 400错误：创建失败（编码已存在）
  - 权限不足：需要管理员或经理角色
- 日志与异常
  - 全局异常处理器记录异常信息
  - HTTP异常与验证异常分别处理
- 前端调用参考
  - 前端通过统一的API封装调用后端接口
  - 支持分页参数传递与响应解析

**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L60-L107)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L58-L108)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L64-L111)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L83-L169)
- [backend/app/main.py](file://backend/app/main.py#L58-L75)
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L1-L32)
- [frontend/src/api/staff.js](file://frontend/src/api/staff.js#L1-L32)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)

## 结论
本API文档全面覆盖了基础数据管理的四大模块，提供了详细的接口规范、数据验证规则、关联关系处理、分页查询、搜索过滤、排序功能以及批量操作的使用方法。通过清晰的分层架构与严格的权限控制，系统能够稳定地支撑医院绩效管理的各项业务需求。建议在生产环境中结合前端封装进行集成测试，确保接口调用的正确性与性能表现。