提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/后端开发指南/API路由实现/基础数据接口.md
+++ b/.qoder/repowiki/zh/content/后端开发指南/API路由实现/基础数据接口.md
@@ -0,0 +1,438 @@
+# 基础数据接口
+
+<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)
+
+## 结论
+本系统通过清晰的分层架构与统一的数据契约，实现了基础数据管理的核心能力。科室管理支持树形结构与层级维护，员工管理提供灵活的查询与状态管理，指标管理具备模板导入与权重配置能力，工资管理覆盖从生成到确认的完整流程。建议后续在高并发场景引入缓存与异步处理，并持续完善数据校验与审计日志。