# 基础数据接口

<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/salary.py](file://backend/app/api/v1/salary.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/salary_service.py](file://backend/app/services/salary_service.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.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/salary.js](file://frontend/src/api/salary.js)
</cite>

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

## 简介
本文件面向基础数据接口的详细文档，涵盖以下模块：
- 科室管理：支持树形结构的增删改查、层级关系维护与权限控制
- 员工管理：支持员工信息的CRUD、按科室检索与状态管理
- 考核指标管理：支持指标分类、权重设置、计算公式与模板导入
- 工资相关接口：支持工资记录的CRUD、批量生成与确认、业务规则校验

文档同时说明RESTful设计原则、统一响应格式、分页查询、条件筛选、排序规则、数据导入导出与批量操作的实现思路，以及错误处理策略。

## 项目结构
后端采用FastAPI + SQLAlchemy 2.0 + 异步数据库访问，遵循分层架构：
- API层：定义路由与请求参数校验
- 服务层：封装业务逻辑与数据访问
- 模型层：定义数据库实体与关系
- 模式层：定义Pydantic数据结构用于序列化与校验
- 前端层：通过Axios封装的API调用

```mermaid
graph TB
subgraph "前端"
FE_Dep["department.js"]
FE_Staff["staff.js"]
FE_Ind["indicator.js"]
FE_Sal["salary.js"]
end
subgraph "后端"
API_Dep["departments.py"]
API_Staff["staff.py"]
API_Ind["indicators.py"]
API_Sal["salary.py"]
SVC_Dep["department_service.py"]
SVC_Staff["staff_service.py"]
SVC_Ind["indicator_service.py"]
SVC_Sal["salary_service.py"]
MODELS["models.py"]
SCHEMAS["schemas.py"]
MAIN["main.py"]
end
FE_Dep --> API_Dep
FE_Staff --> API_Staff
FE_Ind --> API_Ind
FE_Sal --> API_Sal
API_Dep --> SVC_Dep
API_Staff --> SVC_Staff
API_Ind --> SVC_Ind
API_Sal --> SVC_Sal
SVC_Dep --> MODELS
SVC_Staff --> MODELS
SVC_Ind --> MODELS
SVC_Sal --> MODELS
API_Dep --> SCHEMAS
API_Staff --> SCHEMAS
API_Ind --> SCHEMAS
API_Sal --> SCHEMAS
MAIN --> API_Dep
MAIN --> API_Staff
MAIN --> API_Ind
MAIN --> API_Sal
```

图表来源
- [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/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)

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

## 核心组件
- API路由层：定义RESTful端点，负责参数解析、权限校验与统一响应包装
- 服务层：封装业务逻辑，处理数据访问、复杂查询与事务控制
- 模型层：定义实体关系、索引与约束，支撑树形结构与多对多关系
- 模式层：定义输入输出结构，确保前后端数据一致性与校验

章节来源
- [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/salary.py](file://backend/app/api/v1/salary.py#L17-L156)
- [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/salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L231)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L311)

## 架构概览
系统采用分层架构，API层仅负责协议转换与权限控制，服务层承担业务规则，模型层承载数据结构与约束。统一响应格式包含状态码、消息、数据体、分页信息；异常通过全局处理器记录并抛出。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API路由"
participant Service as "服务层"
participant DB as "数据库"
Client->>API : "HTTP请求"
API->>API : "参数校验/权限检查"
API->>Service : "调用业务逻辑"
Service->>DB : "SQLAlchemy查询/写入"
DB-->>Service : "返回结果"
Service-->>API : "业务结果"
API-->>Client : "统一响应格式"
```

图表来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L40)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L49)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L41)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L20-L51)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L43)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L49)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L46)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L20-L58)

## 详细组件分析

### 科室管理接口
- 功能范围
  - 列表查询：支持按类型、启用状态过滤，分页与排序
  - 树形结构：按层级与排序生成树形结构，便于前端渲染
  - 单条查询：按ID获取详情
  - 新增/更新/删除：新增时自动计算层级，删除前检查是否存在子节点
  - 权限控制：新增、更新、删除需管理员或经理权限

- 数据模型与关系
  - Department实体支持自引用父-子关系，维护level与sort_order
  - 通过索引优化dept_type与parent_id查询

- 统一响应与分页
  - 响应包含code、message、data、total、page、page_size
  - 列表默认按sort_order与id排序

- 错误处理
  - 未找到资源返回404
  - 删除失败（存在子节点）返回400

```mermaid
classDiagram
class Department {
+int id
+string name
+string code
+DeptType dept_type
+int parent_id
+int level
+int sort_order
+bool is_active
+string description
+datetime created_at
+datetime updated_at
+Department parent
+Staff[] staff
}
class DepartmentService {
+get_list(...)
+get_tree(...)
+get_by_id(...)
+get_by_code(...)
+create(...)
+update(...)
+delete(...)
}
DepartmentService --> Department : "读写"
```

图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L13-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-L85)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L64-L103)

### 员工管理接口
- 功能范围
  - 列表查询：支持按科室、状态、关键词（姓名/工号）过滤，分页与排序
  - 单条查询：按ID获取详情，附加科室名称
  - 新增/更新/删除：新增前检查工号唯一性
  - 科室员工查询：按科室ID获取在职员工列表

- 数据模型与关系
  - Staff与Department为多对一关系，支持按状态与部门ID高效查询
  - 提供索引优化department_id与status字段

- 统一响应与分页
  - 响应包含code、message、data、total、page、page_size
  - 列表默认按id倒序

- 错误处理
  - 未找到资源返回404

```mermaid
classDiagram
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+string title
+string phone
+string email
+float base_salary
+float performance_ratio
+StaffStatus status
+datetime hire_date
+datetime created_at
+datetime updated_at
+Department department
+Assessment[] assessments
+SalaryRecord[] salary_records
}
class StaffService {
+get_list(...)
+get_by_id(...)
+get_by_employee_id(...)
+create(...)
+update(...)
+delete(...)
+get_by_department(...)
}
StaffService --> Staff : "读写"
```

图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-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-L114)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L107-L149)

### 考核指标管理接口
- 功能范围
  - 列表查询：支持按指标类型、BSC维度、启用状态过滤，分页与排序
  - 启用指标查询：获取全部启用的指标
  - 单条查询：按ID获取详情
  - 新增/更新/删除：新增前检查指标编码唯一性
  - 模板管理：提供模板列表与导入能力，支持覆盖策略

- 数据模型与关系
  - Indicator实体包含指标类型、BSC维度、权重、最高分值、目标值与单位、计算方法、适用科室类型等
  - 提供索引优化indicator_type字段与权重约束

- 统一响应与分页
  - 响应包含code、message、data、total、page、page_size
  - 列表默认按indicator_type与id排序

- 模板导入流程
  - 按模板dept_type批量导入指标，支持覆盖已有指标

```mermaid
flowchart TD
Start(["开始导入"]) --> LoadTemplate["加载模板数据"]
LoadTemplate --> Iterate["遍历指标项"]
Iterate --> Exists{"指标已存在？"}
Exists --> |是且覆盖| Update["更新现有指标"]
Exists --> |是不覆盖| Skip["跳过该指标"]
Exists --> |否| Create["创建新指标"]
Update --> Next["下一个指标"]
Skip --> Next
Create --> Next
Next --> Done(["完成导入"])
```

图表来源
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)

章节来源
- [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-L192)

### 工资核算管理接口
- 功能范围
  - 列表查询：支持按员工、科室、年度、月份、状态过滤，分页与排序
  - 单条查询：按ID获取详情，附加员工与科室名称
  - 新增/更新：创建时计算总工资，更新时重新计算总工资
  - 生成工资：根据已确认的考核记录生成工资记录
  - 批量生成：按科室批量生成工资记录
  - 确认工资：单条与批量确认，状态变更

- 业务规则
  - 工资 = 基本工资 + 绩效奖金 + 补贴 - 扣款
  - 绩效奖金 = 固定基数 × (绩效得分/100) × 员工绩效系数
  - 仅允许对“待确认”状态进行更新与确认

- 统一响应与分页
  - 响应包含code、message、data、total、page、page_size
  - 列表默认按年度、月份、id倒序

- 批量操作
  - 批量生成与批量确认均支持按科室过滤

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "salary.py"
participant Service as "salary_service.py"
participant DB as "数据库"
Client->>API : "POST /salary/generate?staff_id=&period_year=&period_month="
API->>Service : "generate_from_assessment(...)"
Service->>DB : "查询员工与已确认考核记录"
DB-->>Service : "返回员工与考核记录"
Service->>Service : "计算绩效奖金与总工资"
Service->>DB : "插入工资记录"
DB-->>Service : "返回新记录"
Service-->>API : "返回记录ID"
API-->>Client : "统一响应"
```

图表来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L111)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L190)

章节来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L20-L156)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L20-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L274-L311)

## 依赖分析
- API层依赖服务层与安全中间件，统一响应包装
- 服务层依赖模型层进行数据持久化
- 模式层为API与服务层提供数据契约
- 前端通过Axios封装的API与后端交互

```mermaid
graph LR
FE_Dep["frontend/src/api/department.js"] --> API_Dep["backend/app/api/v1/departments.py"]
FE_Staff["frontend/src/api/staff.js"] --> API_Staff["backend/app/api/v1/staff.py"]
FE_Ind["frontend/src/api/indicator.js"] --> API_Ind["backend/app/api/v1/indicators.py"]
FE_Sal["frontend/src/api/salary.js"] --> API_Sal["backend/app/api/v1/salary.py"]
API_Dep --> SVC_Dep["backend/app/services/department_service.py"]
API_Staff --> SVC_Staff["backend/app/services/staff_service.py"]
API_Ind --> SVC_Ind["backend/app/services/indicator_service.py"]
API_Sal --> SVC_Sal["backend/app/services/salary_service.py"]
SVC_Dep --> MODELS["backend/app/models/models.py"]
SVC_Staff --> MODELS
SVC_Ind --> MODELS
SVC_Sal --> MODELS
API_Dep --> SCHEMAS["backend/app/schemas/schemas.py"]
API_Staff --> SCHEMAS
API_Ind --> SCHEMAS
API_Sal --> SCHEMAS
```

图表来源
- [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/salary.js](file://frontend/src/api/salary.js#L1-L42)
- [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/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)

## 性能考虑
- 查询优化
  - 使用索引：科室类型、父节点ID、员工部门ID、状态、指标类型、考核记录周期、工资记录周期等
  - 分页查询：限制每页最大数量，避免一次性返回大量数据
  - 关联预加载：使用selectinload减少N+1查询
- 事务与并发
  - 服务层方法内部保持事务一致性，避免脏读与丢失更新
- 缓存与异步
  - 当前实现为同步处理，如需高并发场景可引入缓存与异步任务队列

## 故障排除指南
- 常见错误
  - 404：资源不存在（科室、员工、指标、工资记录）
  - 400：业务规则不满足（删除存在子节点的科室、重复编码、状态不允许更新/确认）
- 日志与异常
  - 全局异常处理器记录HTTP异常与验证异常，便于定位问题
- 排查步骤
  - 检查请求参数与权限头
  - 查看服务层日志与数据库事务状态
  - 确认业务规则（如状态机、唯一性约束）

章节来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L62-L107)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L60-L108)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L78-L111)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L92-L142)
- [backend/app/main.py](file://backend/app/main.py#L58-L75)

## 结论
本系统通过清晰的分层架构与统一的数据契约，实现了基础数据管理的核心能力。科室管理支持树形结构与层级维护，员工管理提供灵活的查询与状态管理，指标管理具备模板导入与权重配置能力，工资管理覆盖从生成到确认的完整流程。建议后续在高并发场景引入缓存与异步处理，并持续完善数据校验与审计日志。