提交文件

.qoder/repowiki/zh/content/API接口文档/API接口文档.md

@@ -0,0 +1,738 @@
+# 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. **复合类型**: 结构验证、嵌套验证

.qoder/repowiki/zh/content/API接口文档/基础数据接口/员工管理接口.md

@@ -0,0 +1,577 @@
+# 员工管理接口
+
+<cite>
+**本文档引用的文件**
+- [staff.py](file://backend/app/api/v1/staff.py)
+- [staff_service.py](file://backend/app/services/staff_service.py)
+- [models.py](file://backend/app/models/models.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [security.py](file://backend/app/core/security.py)
+- [database.py](file://backend/app/core/database.py)
+- [staff.js](file://frontend/src/api/staff.js)
+- [Staff.vue](file://frontend/src/views/basic/Staff.vue)
+- [request.js](file://frontend/src/api/request.js)
+- [api.md](file://docs/api.md)
+- [backend.md](file://docs/backend.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [数据模型](#数据模型)
+7. [API接口规范](#api接口规范)
+8. [权限控制机制](#权限控制机制)
+9. [员工状态管理](#员工状态管理)
+10. [导入导出功能](#导入导出功能)
+11. [性能考虑](#性能考虑)
+12. [故障排除指南](#故障排除指南)
+13. [结论](#结论)
+
+## 简介
+
+员工管理接口是医院绩效考核管理系统的核心功能模块，负责员工信息的完整生命周期管理。该系统采用现代化的前后端分离架构，后端基于FastAPI和SQLAlchemy，前端使用Vue.js和Element Plus，实现了完整的员工信息管理功能。
+
+系统支持员工信息的增删改查、多条件筛选、分页查询、状态管理等功能，并集成了完善的权限控制机制和数据验证体系。
+
+## 项目结构
+
+```mermaid
+graph TB
+subgraph "后端架构"
+A[API路由层] --> B[服务层]
+B --> C[数据模型层]
+C --> D[数据库]
+A --> E[安全认证]
+E --> F[JWT令牌]
+G[前端界面] --> H[API接口]
+H --> A
+end
+subgraph "核心模块"
+I[员工管理] --> J[科室关联]
+K[权限控制] --> L[角色管理]
+M[数据验证] --> N[Pydantic模式]
+end
+```
+
+**图表来源**
+- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
+- [models.py](file://backend/app/models/models.py#L88-L115)
+
+**章节来源**
+- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
+- [models.py](file://backend/app/models/models.py#L88-L115)
+
+## 核心组件
+
+### 后端核心组件
+
+系统采用经典的三层架构模式，包含以下核心组件：
+
+1. **API路由层**：处理HTTP请求和响应，实现RESTful接口
+2. **服务层**：封装业务逻辑，提供数据访问服务
+3. **数据模型层**：定义数据库表结构和关系映射
+4. **安全认证层**：实现JWT令牌认证和权限控制
+
+### 前端核心组件
+
+前端采用Vue.js单页面应用架构：
+
+1. **员工管理界面**：提供员工信息的CRUD操作界面
+2. **数据表格组件**：展示员工列表和操作功能
+3. **表单组件**：处理员工信息的输入和验证
+4. **API客户端**：封装HTTP请求和响应处理
+
+**章节来源**
+- [staff.py](file://backend/app/api/v1/staff.py#L17-L124)
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
+
+## 架构概览
+
+```mermaid
+sequenceDiagram
+participant Client as 客户端
+participant Frontend as 前端界面
+participant API as API路由
+participant Service as 服务层
+participant Model as 数据模型
+participant DB as 数据库
+Client->>Frontend : 用户操作
+Frontend->>API : HTTP请求
+API->>Service : 业务逻辑调用
+Service->>Model : 数据查询/更新
+Model->>DB : SQL操作
+DB-->>Model : 查询结果
+Model-->>Service : 数据对象
+Service-->>API : 处理结果
+API-->>Frontend : JSON响应
+Frontend-->>Client : 界面更新
+```
+
+**图表来源**
+- [staff.py](file://backend/app/api/v1/staff.py#L20-L108)
+- [staff_service.py](file://backend/app/services/staff_service.py#L16-L101)
+
+## 详细组件分析
+
+### 员工管理API路由
+
+员工管理API路由实现了完整的RESTful接口，包含以下主要功能：
+
+#### GET /staff - 获取员工列表
+支持多条件筛选和分页查询：
+- `department_id`：按科室ID筛选
+- `status`：按员工状态筛选  
+- `keyword`：按姓名或工号模糊搜索
+- `page`：页码，默认1
+- `page_size`：每页数量，默认20，最大100
+
+#### GET /staff/{id} - 获取员工详情
+根据员工ID获取详细信息，包含科室名称关联。
+
+#### POST /staff - 创建员工
+需要管理员或经理权限，支持批量创建。
+
+#### PUT /staff/{id} - 更新员工
+需要管理员或经理权限，支持部分字段更新。
+
+#### DELETE /staff/{id} - 删除员工
+需要管理员或经理权限。
+
+#### GET /staff/department/{department_id} - 获取科室员工
+获取指定科室的所有在职员工。
+
+**章节来源**
+- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+
+### 服务层实现
+
+服务层提供了员工数据访问和业务逻辑处理：
+
+#### 核心方法
+
+1. **get_list()**：实现多条件查询和分页
+2. **get_by_id()**：按ID获取员工信息
+3. **get_by_employee_id()**：按工号查询唯一员工
+4. **create()**：创建新员工记录
+5. **update()**：更新员工信息
+6. **delete()**：删除员工记录
+7. **get_by_department()**：获取科室员工列表
+
+#### 查询优化
+
+- 使用`selectinload`预加载关联的科室信息
+- 实现条件动态构建，支持多种筛选组合
+- 使用子查询统计总数，提高分页查询性能
+
+**章节来源**
+- [staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
+
+### 数据模型设计
+
+员工数据模型采用SQLAlchemy ORM映射：
+
+```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
++assessments List[Assessment]
++salary_records List[SalaryRecord]
+}
+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
++parent Department
++staff List[Staff]
+}
+Staff --> Department : "属于"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L88-L115)
+- [models.py](file://backend/app/models/models.py#L62-L81)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L88-L115)
+
+## 数据模型
+
+### 员工信息字段
+
+| 字段名 | 类型 | 必填 | 描述 | 默认值 |
+|--------|------|------|------|--------|
+| id | int | 否 | 员工ID | 自增 |
+| employee_id | string | 是 | 工号 | 唯一约束 |
+| name | string | 是 | 姓名 | - |
+| department_id | int | 是 | 所属科室ID | - |
+| position | string | 是 | 职位 | - |
+| title | string | 否 | 职称 | - |
+| phone | string | 否 | 联系电话 | - |
+| email | string | 否 | 邮箱 | - |
+| base_salary | float | 是 | 基本工资 | 0 |
+| performance_ratio | float | 是 | 绩效系数 | 1.0 |
+| status | enum | 是 | 员工状态 | active |
+| hire_date | datetime | 否 | 入职日期 | - |
+| created_at | datetime | 否 | 创建时间 | 当前时间 |
+| updated_at | datetime | 否 | 更新时间 | 当前时间 |
+
+### 员工状态枚举
+
+```mermaid
+stateDiagram-v2
+[*] --> ACTIVE
+ACTIVE --> LEAVE : 休假
+LEAVE --> ACTIVE : 返回
+ACTIVE --> RESIGNED : 离职
+ACTIVE --> RETIRED : 退休
+RESIGNED --> [*]
+RETIRED --> [*]
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L37-L43)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L88-L115)
+- [schemas.py](file://backend/app/schemas/schemas.py#L24-L29)
+
+## API接口规范
+
+### 通用响应格式
+
+所有API接口遵循统一的响应格式：
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {},
+  "total": 0,
+  "page": 1,
+  "page_size": 20
+}
+```
+
+### 员工管理接口详情
+
+#### 获取员工列表
+
+**请求**
+```
+GET /api/v1/staff
+Authorization: Bearer {token}
+```
+
+**查询参数**
+| 参数 | 类型 | 必填 | 描述 |
+|------|------|------|------|
+| department_id | int | 否 | 科室ID |
+| status | string | 否 | 员工状态 |
+| keyword | string | 否 | 搜索关键词 |
+| page | int | 否 | 页码，默认1 |
+| page_size | int | 否 | 每页数量，默认20 |
+
+**响应示例**
+```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 /api/v1/staff
+Authorization: Bearer {token}
+Content-Type: application/json
+```
+
+**请求体**
+```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 /api/v1/staff/{id}
+Authorization: Bearer {token}
+Content-Type: application/json
+```
+
+**请求体**（可选字段）
+```json
+{
+  "name": "李四",
+  "department_id": 2,
+  "position": "副主任医师",
+  "title": "副主任医师",
+  "phone": "13900139000",
+  "email": "lisi@example.com",
+  "base_salary": 6000.00,
+  "performance_ratio": 1.3,
+  "status": "active"
+}
+```
+
+#### 删除员工
+
+**请求**
+```
+DELETE /api/v1/staff/{id}
+Authorization: Bearer {token}
+```
+
+**章节来源**
+- [api.md](file://docs/api.md#L158-L236)
+- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+
+## 权限控制机制
+
+### 角色权限体系
+
+系统采用基于角色的访问控制（RBAC）机制：
+
+```mermaid
+graph LR
+subgraph "用户角色"
+A[普通员工] --> B[科室经理]
+B --> C[系统管理员]
+end
+subgraph "权限级别"
+D[只读权限] --> E[读写权限]
+E --> F[管理权限]
+end
+A --> D
+B --> E
+C --> F
+```
+
+### 权限验证流程
+
+```mermaid
+flowchart TD
+Start([请求到达]) --> CheckAuth["验证JWT令牌"]
+CheckAuth --> TokenValid{"令牌有效?"}
+TokenValid --> |否| Error401["返回401未授权"]
+TokenValid --> |是| GetUser["获取用户信息"]
+GetUser --> CheckActive{"用户激活?"}
+CheckActive --> |否| Error400["返回400用户禁用"]
+CheckActive --> |是| CheckRole["检查角色权限"]
+CheckRole --> RoleValid{"权限足够?"}
+RoleValid --> |否| Error403["返回403权限不足"]
+RoleValid --> |是| ProcessReq["处理业务请求"]
+ProcessReq --> Success["返回成功响应"]
+Error401 --> End([结束])
+Error400 --> End
+Error403 --> End
+Success --> End
+```
+
+**图表来源**
+- [security.py](file://backend/app/core/security.py#L55-L110)
+
+### 权限控制实现
+
+1. **get_current_active_user()**：验证用户是否激活
+2. **get_current_manager_user()**：验证是否为管理员或经理
+3. **get_current_admin_user()**：验证是否为管理员
+
+这些装饰器确保只有具备相应权限的用户才能执行敏感操作。
+
+**章节来源**
+- [security.py](file://backend/app/core/security.py#L85-L110)
+- [staff.py](file://backend/app/api/v1/staff.py#L68-L108)
+
+## 员工状态管理
+
+### 状态流转图
+
+```mermaid
+stateDiagram-v2
+[*] --> ACTIVE : 创建时默认
+ACTIVE --> LEAVE : 主动申请
+LEAVE --> ACTIVE : 返回工作
+ACTIVE --> RESIGNED : 辞职
+ACTIVE --> RETIRED : 退休
+RESIGNED --> [*] : 离职结束
+RETIRED --> [*] : 退休结束
+LEAVE --> [*] : 休假结束
+```
+
+### 状态管理策略
+
+1. **在职状态**：正常工作状态，参与绩效考核
+2. **休假状态**：临时离岗，不影响数据完整性
+3. **离职状态**：正式离开，不再参与考核
+4. **退休状态**：达到退休年龄，不再参与考核
+
+### 状态查询优化
+
+系统在查询员工列表时，会自动过滤掉离职和退休状态的员工，确保统计数据的准确性。
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L37-L43)
+- [staff_service.py](file://backend/app/services/staff_service.py#L103-L112)
+
+## 导入导出功能
+
+### 导入功能
+
+系统支持批量员工信息导入，建议采用以下最佳实践：
+
+1. **数据准备**：确保Excel文件包含所有必填字段
+2. **格式要求**：使用标准的CSV或Excel格式
+3. **数据验证**：导入前进行数据完整性检查
+4. **批量处理**：支持大量数据的分批导入
+5. **错误处理**：对无效数据进行标记和报告
+
+### 导出功能
+
+系统支持员工信息的批量导出：
+
+1. **筛选导出**：根据当前筛选条件导出结果
+2. **全量导出**：支持导出所有员工信息
+3. **格式选择**：支持Excel、CSV等多种格式
+4. **字段定制**：可选择导出的字段范围
+
+### 性能优化
+
+- **分页处理**：大数据量时采用分页导出
+- **并发处理**：支持多线程并发处理
+- **进度反馈**：提供导入导出进度显示
+
+## 性能考虑
+
+### 数据库优化
+
+1. **索引策略**：
+   - `idx_staff_dept`：按科室ID查询优化
+   - `idx_staff_status`：按状态查询优化
+   - `idx_dept_type`：按科室类型查询优化
+
+2. **查询优化**：
+   - 使用`selectinload`预加载关联数据
+   - 实现条件动态构建，避免不必要的查询
+   - 使用子查询统计总数，减少查询次数
+
+### 缓存策略
+
+1. **会话缓存**：缓存活跃用户的权限信息
+2. **数据缓存**：缓存常用的科室信息
+3. **查询缓存**：缓存频繁访问的统计数据
+
+### 异步处理
+
+系统采用异步数据库连接，支持高并发场景下的性能表现。
+
+## 故障排除指南
+
+### 常见问题
+
+1. **401 未授权**
+   - 检查JWT令牌是否正确传递
+   - 验证令牌是否过期
+   - 确认用户账户状态正常
+
+2. **403 权限不足**
+   - 验证用户角色是否具备相应权限
+   - 检查操作是否需要管理员权限
+   - 确认用户是否被禁用
+
+3. **404 资源不存在**
+   - 验证员工ID是否正确
+   - 检查数据库中是否存在该记录
+   - 确认查询条件是否准确
+
+4. **400 参数错误**
+   - 检查请求参数格式
+   - 验证字段长度和范围
+   - 确认必填字段是否完整
+
+### 调试建议
+
+1. **前端调试**：使用浏览器开发者工具查看网络请求
+2. **后端日志**：检查服务器日志获取详细错误信息
+3. **数据库查询**：直接查询数据库验证数据状态
+4. **API测试**：使用Postman或curl测试接口
+
+**章节来源**
+- [request.js](file://frontend/src/api/request.js#L28-L63)
+
+## 结论
+
+员工管理接口模块实现了完整的员工信息生命周期管理，具有以下特点：
+
+1. **功能完整**：支持员工信息的增删改查、状态管理、权限控制
+2. **性能优秀**：采用异步架构和数据库优化策略
+3. **安全可靠**：完善的JWT认证和权限控制机制
+4. **易于扩展**：清晰的架构设计便于功能扩展
+5. **用户体验良好**：前后端分离，界面友好
+
+该系统为医院的绩效考核管理提供了坚实的基础，能够满足现代医院对员工管理的各种需求。

.qoder/repowiki/zh/content/API接口文档/基础数据接口/基础数据接口.md

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

.qoder/repowiki/zh/content/API接口文档/基础数据接口/模板管理接口.md

@@ -0,0 +1,454 @@
+# 模板管理接口
+
+<cite>
+**本文档引用的文件**
+- [templates.py](file://backend/app/api/v1/templates.py)
+- [template_service.py](file://backend/app/services/template_service.py)
+- [models.py](file://backend/app/models/models.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [template.js](file://frontend/src/api/template.js)
+- [Templates.vue](file://frontend/src/views/basic/Templates.vue)
+- [init_templates.py](file://backend/app/scripts/init_templates.py)
+- [002_template.py](file://backend/alembic/versions/002_template.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+模板管理接口是医院绩效管理系统的核心功能模块，负责管理各类绩效考核模板的完整生命周期。该系统实现了基于平衡计分卡理论的多维度绩效考核模板管理，支持通用模板、手术科室模板、医技科室模板等多种模板类型，为不同科室提供定制化的绩效考核方案。
+
+系统采用FastAPI框架构建，基于异步数据库连接，确保高并发场景下的性能表现。模板管理功能涵盖了从模板创建、配置到删除的完整流程，同时支持模板指标的精细化管理，包括指标权重设置、评分方法配置等高级功能。
+
+## 项目结构
+
+模板管理模块在项目中的组织结构如下：
+
+```mermaid
+graph TB
+subgraph "后端架构"
+API[API路由层<br/>templates.py]
+Service[服务层<br/>template_service.py]
+Model[数据模型层<br/>models.py]
+Schema[数据模式层<br/>schemas.py]
+end
+subgraph "前端架构"
+FrontAPI[前端API封装<br/>template.js]
+FrontView[模板管理界面<br/>Templates.vue]
+end
+subgraph "数据层"
+DB[(数据库)]
+Alembic[Alembic迁移<br/>002_template.py]
+end
+FrontAPI --> API
+FrontView --> FrontAPI
+API --> Service
+Service --> Model
+Model --> DB
+Schema --> API
+Alembic --> DB
+```
+
+**图表来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
+- [models.py](file://backend/app/models/models.py#L387-L437)
+
+**章节来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
+- [models.py](file://backend/app/models/models.py#L387-L437)
+
+## 核心组件
+
+### 数据模型组件
+
+系统采用三层架构的数据模型设计，包含以下核心实体：
+
+#### 模板实体 (IndicatorTemplate)
+- **主键**: 自增ID
+- **模板标识**: 唯一模板编码和名称
+- **模板类型**: 支持8种预定义类型
+- **配置属性**: 维度权重、考核周期、启用状态
+- **关联关系**: 一对多关联到模板指标
+
+#### 指标实体 (TemplateIndicator)
+- **主键**: 自增ID
+- **关联属性**: 模板ID、指标ID
+- **配置属性**: 分类、目标值、权重、评分方法
+- **排序机制**: 支持自定义排序顺序
+- **唯一约束**: 模板ID+指标ID组合唯一
+
+#### 枚举类型
+- **模板类型**: 通用、手术、非手术有病房、非手术无病房、医技、护理、行政、后勤
+- **BSC维度**: 财务管理、顾客服务、内部流程、学习与成长
+- **指标类型**: 质量、数量、效率、服务、成本
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L375-L437)
+- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
+
+### 服务层组件
+
+#### TemplateService 类
+提供完整的模板管理业务逻辑：
+- **查询功能**: 列表查询、详情获取、按类型过滤
+- **CRUD操作**: 创建、更新、删除模板
+- **指标管理**: 添加、更新、删除模板指标
+- **批量操作**: 批量添加模板指标
+- **工具方法**: 类型标签转换、维度标签转换
+
+**章节来源**
+- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
+
+### API路由组件
+
+#### 模板管理路由
+- **GET /templates**: 获取模板列表，支持类型过滤和分页
+- **GET /templates/types**: 获取模板类型列表
+- **GET /templates/dimensions**: 获取BSC维度列表
+- **GET /templates/{id}**: 获取模板详情
+- **POST /templates**: 创建模板
+- **PUT /templates/{id}**: 更新模板
+- **DELETE /templates/{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**: 批量添加模板指标
+
+**章节来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L22-L272)
+
+## 架构概览
+
+系统采用分层架构设计，确保关注点分离和代码可维护性：
+
+```mermaid
+sequenceDiagram
+participant Client as 前端客户端
+participant API as API路由层
+participant Service as 服务层
+participant DB as 数据库
+participant Model as 数据模型
+Client->>API : GET /templates
+API->>Service : get_list()
+Service->>DB : 查询模板列表
+DB->>Service : 返回模板数据
+Service->>Service : 统计指标数量
+Service->>API : 返回处理后的数据
+API->>Client : JSON响应
+Note over Client,DB : 异步数据库操作，支持高并发
+```
+
+**图表来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L22-L42)
+- [template_service.py](file://backend/app/services/template_service.py#L24-L71)
+
+### 数据流架构
+
+```mermaid
+flowchart TD
+subgraph "前端层"
+FE_API[前端API调用]
+FE_VIEW[模板管理界面]
+end
+subgraph "后端层"
+ROUTER[路由处理]
+SERVICE[业务逻辑]
+VALIDATION[数据验证]
+end
+subgraph "数据层"
+MODEL[ORM模型]
+DATABASE[(数据库)]
+end
+FE_API --> ROUTER
+FE_VIEW --> FE_API
+ROUTER --> VALIDATION
+VALIDATION --> SERVICE
+SERVICE --> MODEL
+MODEL --> DATABASE
+DATABASE --> MODEL
+MODEL --> SERVICE
+SERVICE --> ROUTER
+ROUTER --> FE_API
+```
+
+**图表来源**
+- [template.js](file://frontend/src/api/template.js#L1-L62)
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+
+## 详细组件分析
+
+### 模板类型分类系统
+
+系统支持8种预定义的模板类型，每种类型针对特定的科室特点设计：
+
+#### 通用模板 (GENERAL)
+- **适用范围**: 全院各科室
+- **特点**: 基于平衡计分卡四维度设计
+- **典型权重**: 财务35%、客户30%、内部流程25%、学习成长10%
+
+#### 手术科室模板 (SURGICAL)
+- **适用范围**: 外科、妇科、眼科等手术科室
+- **特点**: 结合RBRVS和DRG理念
+- **重点指标**: DRG组数、CMI值、费用消耗指数
+
+#### 医技科室模板 (MEDICAL_TECH)
+- **适用范围**: 检验科、放射科、超声科等
+- **特点**: 质量效率双核心
+- **重点指标**: 报告准确率、危急值及时率
+
+#### 行政科室模板 (ADMIN)
+- **适用范围**: 院办、党办、医务科等
+- **特点**: 服务支持导向
+- **重点指标**: 服务态度、遵纪守法
+
+#### 后勤科室模板 (LOGISTICS)
+- **适用范围**: 总务科、设备科等
+- **特点**: 后勤保障核心
+- **重点指标**: 保障及时率、设备完好率
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L375-L384)
+- [schemas.py](file://backend/app/schemas/schemas.py#L642-L651)
+
+### 模板数据结构定义
+
+#### 模板基础结构
+| 字段名 | 类型 | 描述 | 必填 |
+|--------|------|------|------|
+| template_name | String | 模板名称 | 是 |
+| template_code | String | 模板编码 | 是 |
+| template_type | Enum | 模板类型 | 是 |
+| description | Text | 模板描述 | 否 |
+| dimension_weights | JSON | 维度权重配置 | 否 |
+| assessment_cycle | String | 考核周期 | 否 |
+| is_active | Boolean | 是否启用 | 否 |
+
+#### 模板指标结构
+| 字段名 | 类型 | 描述 | 必填 |
+|--------|------|------|------|
+| indicator_id | Integer | 指标ID | 是 |
+| category | String | 指标分类 | 否 |
+| target_value | Float | 目标值 | 否 |
+| target_unit | String | 目标值单位 | 否 |
+| weight | Float | 权重 | 否 |
+| scoring_method | String | 评分方法 | 否 |
+| scoring_params | JSON | 评分参数 | 否 |
+| sort_order | Integer | 排序 | 否 |
+| remark | Text | 备注 | 否 |
+
+**章节来源**
+- [schemas.py](file://backend/app/schemas/schemas.py#L698-L743)
+- [schemas.py](file://backend/app/schemas/schemas.py#L654-L696)
+
+### 模板继承与复用机制
+
+系统通过模板继承机制实现模板的复用和扩展：
+
+```mermaid
+classDiagram
+class IndicatorTemplate {
++Integer id
++String template_code
++String template_name
++TemplateType template_type
++String description
++String dimension_weights
++String assessment_cycle
++Boolean is_active
++DateTime created_at
++DateTime updated_at
++TemplateIndicator[] indicators
+}
+class TemplateIndicator {
++Integer id
++Integer template_id
++Integer indicator_id
++String category
++Float target_value
++String target_unit
++Float weight
++String scoring_method
++String scoring_params
++Integer sort_order
++String remark
++DateTime created_at
++DateTime updated_at
+}
+class Indicator {
++Integer id
++String code
++String name
++IndicatorType indicator_type
++BSCDimension bs_dimension
++Float weight
++Float max_score
++Float target_value
++String target_unit
++String calculation_method
++String assessment_method
++String deduction_standard
++String data_source
++Boolean is_veto
++Boolean is_active
+}
+IndicatorTemplate "1" -- "many" TemplateIndicator : "包含"
+TemplateIndicator "many" -- "1" Indicator : "关联"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L387-L437)
+
+### 版本控制实现
+
+虽然模板管理接口没有直接的版本控制功能，但系统通过以下机制实现版本管理：
+
+1. **模板历史记录**: 每个模板都有创建时间和更新时间
+2. **状态管理**: 通过`is_active`字段控制模板启用状态
+3. **数据完整性**: 使用数据库约束确保数据一致性
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L391-L400)
+
+### 批量操作功能
+
+系统提供了完善的批量操作功能：
+
+#### 批量添加模板指标
+- **接口**: POST `/templates/{template_id}/indicators/batch`
+- **功能**: 支持一次性添加多个模板指标
+- **特性**: 自动设置排序顺序，支持部分字段配置
+
+#### 批量处理流程
+```mermaid
+flowchart TD
+Start([开始批量添加]) --> Validate["验证模板ID"]
+Validate --> Loop{"遍历指标数组"}
+Loop --> |是| CheckOrder["检查排序设置"]
+CheckOrder --> AddIndicator["添加模板指标"]
+AddIndicator --> UpdateCount["增加成功计数"]
+UpdateCount --> Loop
+Loop --> |否| ReturnResult["返回处理结果"]
+ReturnResult --> End([结束])
+```
+
+**图表来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L252-L271)
+
+**章节来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L252-L271)
+
+## 依赖关系分析
+
+### 组件耦合关系
+
+```mermaid
+graph TB
+subgraph "API层"
+TPL_API[templates.py]
+end
+subgraph "服务层"
+TPL_SERVICE[template_service.py]
+end
+subgraph "模型层"
+MODELS[models.py]
+ENUMS[枚举类型]
+end
+subgraph "数据层"
+SCHEMAS[schemas.py]
+DB[(数据库)]
+end
+TPL_API --> TPL_SERVICE
+TPL_SERVICE --> MODELS
+MODELS --> ENUMS
+MODELS --> DB
+TPL_API --> SCHEMAS
+SCHEMAS --> MODELS
+```
+
+**图表来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
+
+### 外部依赖
+
+系统主要依赖以下外部组件：
+- **FastAPI**: Web框架，提供异步API支持
+- **SQLAlchemy**: ORM框架，处理数据库操作
+- **Alembic**: 数据库迁移工具
+- **Pydantic**: 数据验证和序列化
+
+**章节来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L18)
+- [template_service.py](file://backend/app/services/template_service.py#L1-L18)
+
+## 性能考虑
+
+### 数据库优化策略
+
+1. **索引优化**: 模板类型和启用状态字段建立了复合索引
+2. **查询优化**: 使用分页查询避免大数据集加载
+3. **连接池**: 异步数据库连接池提高并发性能
+
+### 缓存策略
+
+系统目前采用懒加载策略，通过`selectinload`优化N+1查询问题，减少数据库访问次数。
+
+### 并发处理
+
+- **异步操作**: 所有数据库操作都是异步的
+- **事务管理**: 自动事务提交和回滚
+- **错误处理**: 完善的异常处理机制
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+#### 模板编码重复
+**问题**: 创建模板时报错"模板编码已存在"
+**原因**: 模板编码必须唯一
+**解决**: 修改模板编码或使用系统生成的新编码
+
+#### 模板不存在
+**问题**: 更新或删除模板时报错"模板不存在"
+**原因**: 模板ID无效或已被删除
+**解决**: 检查模板ID有效性或重新获取模板列表
+
+#### 指标已存在
+**问题**: 添加模板指标时报错"指标已存在"
+**原因**: 同一模板中重复添加相同指标
+**解决**: 移除重复指标或使用新的指标ID
+
+#### 权限不足
+**问题**: 访问受保护的模板管理功能被拒绝
+**原因**: 当前用户角色不满足管理员或经理权限要求
+**解决**: 登录具有相应权限的账户或联系系统管理员
+
+**章节来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L136-L168)
+- [template_service.py](file://backend/app/services/template_service.py#L167-L182)
+
+## 结论
+
+模板管理接口为医院绩效管理系统提供了完整的模板生命周期管理能力。通过8种预定义的模板类型、灵活的指标配置和强大的批量操作功能，系统能够满足不同类型科室的绩效考核需求。
+
+系统采用现代化的架构设计，基于FastAPI和SQLAlchemy构建，确保了高性能和高可用性。模板继承机制和复用策略使得系统具有良好的扩展性和维护性。
+
+未来可以考虑的功能增强包括：
+- 模板版本控制功能
+- 模板复制和导入导出功能
+- 更丰富的模板指标评分算法
+- 模板使用统计和分析功能

.qoder/repowiki/zh/content/API接口文档/基础数据接口/科室管理接口.md

@@ -0,0 +1,849 @@
+# 科室管理接口
+
+<cite>
+**本文档引用的文件**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
+- [backend/app/services/department_service.py](file://backend/app/services/department_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/core/security.py](file://backend/app/core/security.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [frontend/src/api/department.js](file://frontend/src/api/department.js)
+- [frontend/public/test-api.html](file://frontend/public/test-api.html)
+- [docs/api.md](file://docs/api.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细接口文档](#详细接口文档)
+6. [树形结构查询实现原理](#树形结构查询实现原理)
+7. [权限控制机制](#权限控制机制)
+8. [数据模型](#数据模型)
+9. [性能考虑](#性能考虑)
+10. [故障排除指南](#故障排除指南)
+11. [结论](#结论)
+
+## 简介
+
+本文档详细介绍了医院绩效管理系统的科室管理接口。该系统基于FastAPI构建，提供了完整的科室CRUD操作，包括获取科室列表（支持按类型和状态过滤）、获取树形结构、获取科室详情、创建科室、更新科室和删除科室。系统采用JWT认证机制，支持管理员和经理两种权限级别，并提供了完整的分页查询功能。
+
+## 项目结构
+
+后端采用分层架构设计，主要包含以下层次：
+
+```mermaid
+graph TB
+subgraph "前端层"
+FE[Vue.js 前端]
+API[API 请求封装]
+end
+subgraph "接口层"
+Router[FastAPI 路由器]
+Auth[认证中间件]
+end
+subgraph "业务逻辑层"
+Service[科室服务层]
+Validation[数据验证]
+end
+subgraph "数据访问层"
+Model[数据模型]
+Schema[Pydantic 模式]
+Security[安全认证]
+end
+subgraph "基础设施"
+DB[(PostgreSQL 数据库)]
+Config[配置管理]
+end
+FE --> API
+API --> Router
+Router --> Auth
+Router --> Service
+Service --> Model
+Service --> Schema
+Auth --> Security
+Model --> DB
+Config --> DB
+```
+
+**图表来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+
+**章节来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L18)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
+
+## 核心组件
+
+### API路由器
+- **位置**: `backend/app/api/v1/departments.py`
+- **功能**: 定义所有科室管理相关的HTTP端点
+- **标签**: "科室管理"
+
+### 服务层
+- **位置**: `backend/app/services/department_service.py`
+- **职责**: 实现业务逻辑，包括数据查询、验证和操作
+- **特点**: 异步操作，支持事务处理
+
+### 数据模型
+- **位置**: `backend/app/models/models.py`
+- **实体**: Department（科室表）
+- **特性**: 支持层级关系，自引用外键
+
+### 数据验证
+- **位置**: `backend/app/schemas/schemas.py`
+- **用途**: Pydantic模型用于请求验证和响应序列化
+- **类型**: DepartmentCreate, DepartmentUpdate, DepartmentResponse
+
+**章节来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L17-L18)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L13-L15)
+- [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)
+
+## 架构概览
+
+系统采用经典的MVC架构模式，结合现代的异步编程：
+
+```mermaid
+sequenceDiagram
+participant Client as 客户端
+participant API as API路由器
+participant Auth as 认证中间件
+participant Service as 服务层
+participant DB as 数据库
+participant Model as 数据模型
+Client->>API : HTTP请求
+API->>Auth : 验证JWT令牌
+Auth->>Auth : 验证用户权限
+Auth-->>API : 通过验证
+API->>Service : 调用业务逻辑
+Service->>DB : 执行数据库操作
+DB->>Model : 映射到模型
+Model-->>DB : 返回数据
+DB-->>Service : 查询结果
+Service-->>API : 处理后的数据
+API-->>Client : JSON响应
+```
+
+**图表来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L40)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L109)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L43)
+
+## 详细接口文档
+
+### 获取科室列表
+
+**HTTP方法**: GET  
+**URL路径**: `/api/v1/departments`  
+**权限要求**: 需要激活用户权限
+
+**查询参数**:
+| 参数名 | 类型 | 必填 | 默认值 | 描述 |
+|--------|------|------|--------|------|
+| dept_type | string | 否 | 无 | 科室类型过滤 |
+| is_active | boolean | 否 | 无 | 启用状态过滤 |
+| page | int | 否 | 1 | 页码，最小值1 |
+| page_size | int | 否 | 20 | 每页数量，范围1-100 |
+
+**响应数据结构**:
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "id": 1,
+      "name": "内科",
+      "code": "NK001",
+      "dept_type": "clinical_surgical",
+      "parent_id": null,
+      "level": 1,
+      "sort_order": 1,
+      "is_active": true,
+      "description": "内科描述",
+      "created_at": "2024-01-01T00:00:00",
+      "updated_at": "2024-01-01T00:00:00"
+    }
+  ],
+  "total": 10,
+  "page": 1,
+  "page_size": 20
+}
+```
+
+**请求示例**:
+```bash
+curl -X GET "http://localhost:8000/api/v1/departments?page=1&page_size=20&dept_type=clinical_surgical&is_active=true" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "id": 1,
+      "name": "内科",
+      "code": "NK001",
+      "dept_type": "clinical_surgical",
+      "parent_id": null,
+      "level": 1,
+      "sort_order": 1,
+      "is_active": true,
+      "description": "",
+      "created_at": "2024-01-01T00:00:00",
+      "updated_at": "2024-01-01T00:00:00"
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "page_size": 20
+}
+```
+
+**错误处理**:
+- 401 未授权：无效或过期的JWT令牌
+- 403 禁止：用户权限不足
+- 404 未找到：无匹配的数据
+
+**章节来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L40)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L17-L43)
+
+### 获取科室树形结构
+
+**HTTP方法**: GET  
+**URL路径**: `/api/v1/departments/tree`  
+**权限要求**: 需要激活用户权限
+
+**查询参数**:
+| 参数名 | 类型 | 必填 | 默认值 | 描述 |
+|--------|------|------|--------|------|
+| dept_type | string | 否 | 无 | 科室类型过滤 |
+
+**响应数据结构**:
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "id": 1,
+      "name": "医院",
+      "code": "HOSPITAL",
+      "dept_type": "admin",
+      "parent_id": null,
+      "level": 1,
+      "sort_order": 1,
+      "is_active": true,
+      "description": "",
+      "created_at": "2024-01-01T00:00:00",
+      "updated_at": "2024-01-01T00:00:00",
+      "children": [
+        {
+          "id": 2,
+          "name": "内科",
+          "code": "NK001",
+          "dept_type": "clinical_surgical",
+          "parent_id": 1,
+          "level": 2,
+          "sort_order": 1,
+          "is_active": true,
+          "description": "",
+          "created_at": "2024-01-01T00:00:00",
+          "updated_at": "2024-01-01T00:00:00",
+          "children": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+**请求示例**:
+```bash
+curl -X GET "http://localhost:8000/api/v1/departments/tree?dept_type=clinical_surgical" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "id": 1,
+      "name": "医院",
+      "code": "HOSPITAL",
+      "dept_type": "admin",
+      "parent_id": null,
+      "level": 1,
+      "sort_order": 1,
+      "is_active": true,
+      "description": "",
+      "created_at": "2024-01-01T00:00:00",
+      "updated_at": "2024-01-01T00:00:00",
+      "children": [
+        {
+          "id": 2,
+          "name": "内科",
+          "code": "NK001",
+          "dept_type": "clinical_surgical",
+          "parent_id": 1,
+          "level": 2,
+          "sort_order": 1,
+          "is_active": true,
+          "description": "",
+          "created_at": "2024-01-01T00:00:00",
+          "updated_at": "2024-01-01T00:00:00",
+          "children": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+**错误处理**:
+- 401 未授权：无效或过期的JWT令牌
+- 403 禁止：用户权限不足
+
+**章节来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L43-L51)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L112-L149)
+
+### 获取科室详情
+
+**HTTP方法**: GET  
+**URL路径**: `/api/v1/departments/{dept_id}`  
+**权限要求**: 需要激活用户权限
+
+**路径参数**:
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| dept_id | int | 是 | 科室ID |
+
+**响应数据结构**:
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": 1,
+    "name": "内科",
+    "code": "NK001",
+    "dept_type": "clinical_surgical",
+    "parent_id": null,
+    "level": 1,
+    "sort_order": 1,
+    "is_active": true,
+    "description": "内科描述",
+    "created_at": "2024-01-01T00:00:00",
+    "updated_at": "2024-01-01T00:00:00"
+  }
+}
+```
+
+**请求示例**:
+```bash
+curl -X GET "http://localhost:8000/api/v1/departments/1" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": 1,
+    "name": "内科",
+    "code": "NK001",
+    "dept_type": "clinical_surgical",
+    "parent_id": null,
+    "level": 1,
+    "sort_order": 1,
+    "is_active": true,
+    "description": "",
+    "created_at": "2024-01-01T00:00:00",
+    "updated_at": "2024-01-01T00:00:00"
+  }
+}
+```
+
+**错误处理**:
+- 401 未授权：无效或过期的JWT令牌
+- 403 禁止：用户权限不足
+- 404 未找到：科室不存在
+
+**章节来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L54-L64)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L46-L51)
+
+### 创建科室
+
+**HTTP方法**: POST  
+**URL路径**: `/api/v1/departments`  
+**权限要求**: 需要管理员或经理权限
+
+**请求体参数**:
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| name | string | 是 | 科室名称，最大100字符 |
+| code | string | 是 | 科室编码，最大20字符，必须唯一 |
+| dept_type | string | 是 | 科室类型 |
+| parent_id | int | 否 | 上级科室ID |
+| level | int | 否 | 层级，默认1 |
+| sort_order | int | 否 | 排序 |
+| description | string | 否 | 描述 |
+
+**响应数据结构**:
+```json
+{
+  "code": 200,
+  "message": "创建成功",
+  "data": {
+    "id": 1,
+    "name": "内科",
+    "code": "NK001",
+    "dept_type": "clinical_surgical",
+    "parent_id": null,
+    "level": 1,
+    "sort_order": 1,
+    "is_active": true,
+    "description": "",
+    "created_at": "2024-01-01T00:00:00",
+    "updated_at": "2024-01-01T00:00:00"
+  }
+}
+```
+
+**请求示例**:
+```bash
+curl -X POST "http://localhost:8000/api/v1/departments" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "内科",
+    "code": "NK001",
+    "dept_type": "clinical_surgical",
+    "parent_id": null,
+    "sort_order": 1,
+    "description": "内科描述"
+  }'
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "创建成功",
+  "data": {
+    "id": 1,
+    "name": "内科",
+    "code": "NK001",
+    "dept_type": "clinical_surgical",
+    "parent_id": null,
+    "level": 1,
+    "sort_order": 1,
+    "is_active": true,
+    "description": "内科描述",
+    "created_at": "2024-01-01T00:00:00",
+    "updated_at": "2024-01-01T00:00:00"
+  }
+}
+```
+
+**错误处理**:
+- 400 错误请求：科室编码已存在
+- 401 未授权：无效或过期的JWT令牌
+- 403 禁止：用户权限不足
+
+**章节来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L67-L80)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L62-L78)
+
+### 更新科室
+
+**HTTP方法**: PUT  
+**URL路径**: `/api/v1/departments/{dept_id}`  
+**权限要求**: 需要管理员或经理权限
+
+**路径参数**:
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| dept_id | int | 是 | 科室ID |
+
+**请求体参数**:
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| name | string | 否 | 科室名称，最大100字符 |
+| dept_type | string | 否 | 科室类型 |
+| parent_id | int | 否 | 上级科室ID |
+| sort_order | int | 否 | 排序 |
+| is_active | boolean | 否 | 是否启用 |
+| description | string | 否 | 描述 |
+
+**响应数据结构**:
+```json
+{
+  "code": 200,
+  "message": "更新成功",
+  "data": {
+    "id": 1,
+    "name": "内科",
+    "code": "NK001",
+    "dept_type": "clinical_surgical",
+    "parent_id": null,
+    "level": 1,
+    "sort_order": 1,
+    "is_active": true,
+    "description": "更新后的描述",
+    "created_at": "2024-01-01T00:00:00",
+    "updated_at": "2024-01-01T00:00:00"
+  }
+}
+```
+
+**请求示例**:
+```bash
+curl -X PUT "http://localhost:8000/api/v1/departments/1" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "内科",
+    "description": "更新后的描述"
+  }'
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "更新成功",
+  "data": {
+    "id": 1,
+    "name": "内科",
+    "code": "NK001",
+    "dept_type": "clinical_surgical",
+    "parent_id": null,
+    "level": 1,
+    "sort_order": 1,
+    "is_active": true,
+    "description": "更新后的描述",
+    "created_at": "2024-01-01T00:00:00",
+    "updated_at": "2024-01-01T00:00:00"
+  }
+}
+```
+
+**错误处理**:
+- 401 未授权：无效或过期的JWT令牌
+- 403 禁止：用户权限不足
+- 404 未找到：科室不存在
+
+**章节来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L83-L94)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L81-L93)
+
+### 删除科室
+
+**HTTP方法**: DELETE  
+**URL路径**: `/api/v1/departments/{dept_id}`  
+**权限要求**: 需要管理员或经理权限
+
+**路径参数**:
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| dept_id | int | 是 | 科室ID |
+
+**响应数据结构**:
+```json
+{
+  "code": 200,
+  "message": "删除成功"
+}
+```
+
+**请求示例**:
+```bash
+curl -X DELETE "http://localhost:8000/api/v1/departments/1" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "删除成功"
+}
+```
+
+**错误处理**:
+- 400 错误请求：无法删除，科室下存在子科室
+- 401 未授权：无效或过期的JWT令牌
+- 403 禁止：用户权限不足
+
+**章节来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L97-L107)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L95-L110)
+
+## 树形结构查询实现原理
+
+### 数据模型设计
+
+科室表采用自引用外键设计，支持无限层级的组织结构：
+
+```mermaid
+erDiagram
+DEPARTMENTS {
+int id PK
+string name
+string code UK
+enum dept_type
+int parent_id FK
+int level
+int sort_order
+boolean is_active
+text description
+datetime created_at
+datetime updated_at
+}
+DEPARTMENTS ||--o{ DEPARTMENTS : "parent"
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
+
+### 树形构建算法
+
+服务层实现了高效的树形结构构建算法：
+
+```mermaid
+flowchart TD
+Start([开始构建树形结构]) --> LoadData["加载所有科室数据"]
+LoadData --> CreateMap["创建科室映射表<br/>ID -> Tree节点"]
+CreateMap --> InitChildren["初始化所有节点的children为空数组"]
+InitChildren --> BuildTree["遍历所有科室构建树"]
+BuildTree --> CheckParent{"是否有上级科室?"}
+CheckParent --> |是| AddToParent["添加到上级节点的children"]
+CheckParent --> |否| AddToRoots["添加到根节点列表"]
+AddToParent --> NextDept{"还有下一个科室?"}
+AddToRoots --> NextDept
+NextDept --> |是| BuildTree
+NextDept --> |否| ReturnTree["返回根节点列表"]
+ReturnTree --> End([结束])
+```
+
+**图表来源**
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L113-L149)
+
+### 层级关系处理
+
+系统自动计算和维护科室层级关系：
+
+1. **层级计算**: 新建科室时，如果指定parent_id，则level = parent.level + 1
+2. **排序规则**: 按sort_order和id进行排序
+3. **层级限制**: 支持最多5级深度
+
+**章节来源**
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L62-L78)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L69-L71)
+
+## 权限控制机制
+
+### 角色定义
+
+系统支持三种用户角色：
+- **admin**: 系统管理员，拥有最高权限
+- **manager**: 科室经理，具有业务操作权限
+- **staff**: 普通员工，只读权限
+
+### 权限验证流程
+
+```mermaid
+sequenceDiagram
+participant Client as 客户端
+participant API as API端点
+participant Auth as 认证中间件
+participant Role as 角色验证
+participant DB as 数据库
+Client->>API : 发送带JWT的请求
+API->>Auth : 验证JWT令牌
+Auth->>DB : 验证用户有效性
+DB-->>Auth : 用户信息
+Auth->>Role : 检查角色权限
+Role-->>API : 权限验证结果
+API-->>Client : 返回响应或错误
+```
+
+**图表来源**
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L109)
+
+### 权限矩阵
+
+| 操作 | 激活用户 | 管理员 | 经理 |
+|------|----------|--------|------|
+| 获取列表 | ✅ | ✅ | ✅ |
+| 获取树形结构 | ✅ | ✅ | ✅ |
+| 获取详情 | ✅ | ✅ | ✅ |
+| 创建科室 | ❌ | ✅ | ✅ |
+| 更新科室 | ❌ | ✅ | ✅ |
+| 删除科室 | ❌ | ✅ | ✅ |
+
+**章节来源**
+- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L109)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L67-L107)
+
+## 数据模型
+
+### 科室实体
+
+科室表包含以下字段：
+
+| 字段名 | 类型 | 约束 | 描述 |
+|--------|------|------|------|
+| id | int | 主键，自增 | 科室ID |
+| name | string | 非空，最大100 | 科室名称 |
+| code | string | 非空，唯一，最大20 | 科室编码 |
+| dept_type | enum | 非空 | 科室类型 |
+| parent_id | int | 外键到departments.id | 上级科室ID |
+| level | int | 默认1，范围1-5 | 层级 |
+| sort_order | int | 默认0 | 排序 |
+| is_active | boolean | 默认true | 是否启用 |
+| description | text | 可空 | 描述信息 |
+| created_at | datetime | 默认当前时间 | 创建时间 |
+| updated_at | datetime | 默认当前时间，更新时自动 | 更新时间 |
+
+### 科室类型枚举
+
+系统支持9种科室类型：
+- `clinical_surgical`: 手术临床科室
+- `clinical_nonsurgical_ward`: 非手术有病房科室
+- `clinical_nonsurgical_noward`: 非手术无病房科室
+- `medical_tech`: 医技科室
+- `medical_auxiliary`: 医辅科室
+- `nursing`: 护理单元
+- `admin`: 行政科室
+- `finance`: 财务科室
+- `logistics`: 后勤保障科室
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L16-L27)
+
+## 性能考虑
+
+### 数据库优化
+
+1. **索引策略**:
+   - `idx_dept_type`: 科室类型索引
+   - `idx_dept_parent`: 上级科室索引
+   - `idx_dept_code`: 编码唯一索引
+
+2. **查询优化**:
+   - 使用异步查询避免阻塞
+   - 分页查询限制结果集大小
+   - 批量操作减少数据库往返
+
+3. **连接池管理**:
+   - 默认池大小20，溢出10
+   - 自动事务管理和回滚
+
+### 缓存策略
+
+- **树形结构缓存**: 对于静态的组织架构数据，建议实现Redis缓存
+- **用户权限缓存**: 缓存用户角色信息减少数据库查询
+- **配置信息缓存**: 使用LRU缓存配置项
+
+### 异步处理
+
+系统采用异步编程模型：
+- 使用SQLAlchemy异步引擎
+- 异步数据库会话管理
+- 非阻塞I/O操作
+
+**章节来源**
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
+
+## 故障排除指南
+
+### 常见错误及解决方案
+
+#### 1. 认证失败
+**症状**: 401 未授权错误  
+**原因**: JWT令牌无效或过期  
+**解决方案**:
+- 重新登录获取新令牌
+- 检查令牌格式和有效期
+- 验证服务器时间同步
+
+#### 2. 权限不足
+**症状**: 403 禁止访问  
+**原因**: 用户角色不满足操作要求  
+**解决方案**:
+- 确认用户角色为admin或manager
+- 检查用户状态是否激活
+- 验证用户是否被禁用
+
+#### 3. 数据重复
+**症状**: 400 错误请求，提示编码已存在  
+**原因**: 科室编码重复  
+**解决方案**:
+- 修改唯一的科室编码
+- 检查现有数据避免冲突
+- 使用系统提供的唯一性约束
+
+#### 4. 删除失败
+**症状**: 400 错误请求，提示无法删除  
+**原因**: 科室下存在子科室  
+**解决方案**:
+- 先删除所有子科室
+- 或者调整层级关系
+- 使用树形结构查看层级
+
+### 调试工具
+
+#### 前端测试页面
+系统提供了测试页面用于调试API：
+- **路径**: `frontend/public/test-api.html`
+- **功能**: 包含健康检查、登录测试、科室列表测试等
+- **使用**: 直接在浏览器中打开测试页面
+
+#### 日志监控
+- **应用日志**: `backend/app/logs/`
+- **错误日志**: `backend/app/logs/error_*.log`
+- **数据库日志**: SQL查询语句和执行时间
+
+**章节来源**
+- [frontend/public/test-api.html](file://frontend/public/test-api.html#L1-L133)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L75-L77)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L102-L107)
+
+## 结论
+
+科室管理接口提供了完整的CRUD操作，支持复杂的树形结构查询和权限控制。系统采用现代化的技术栈，具有良好的扩展性和维护性。通过合理的数据模型设计和权限控制机制，确保了系统的安全性和稳定性。
+
+主要优势：
+1. **完整的功能覆盖**: 支持所有必要的科室管理操作
+2. **灵活的查询能力**: 支持多条件过滤和分页查询
+3. **强大的权限控制**: 细粒度的角色权限管理
+4. **高性能设计**: 异步架构和数据库优化
+5. **易于扩展**: 清晰的分层架构便于功能扩展
+
+建议后续改进方向：
+1. 添加树形结构缓存机制
+2. 实现批量操作功能
+3. 增强数据导入导出能力
+4. 完善审计日志功能

.qoder/repowiki/zh/content/API接口文档/基础数据接口/考核指标管理接口.md

@@ -0,0 +1,753 @@
+# 考核指标管理接口
+
+<cite>
+**本文档引用的文件**
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py)
+- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_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/api/v1/templates.py](file://backend/app/api/v1/templates.py)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py)
+- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py)
+- [docs/api.md](file://docs/api.md)
+- [docs/详细设计.md](file://docs/详细设计.md)
+- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js)
+- [frontend/src/views/basic/Indicators.vue](file://frontend/src/views/basic/Indicators.vue)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+
+本文件为医院绩效管理系统中的考核指标管理接口提供详细的API文档。系统基于平衡计分卡理论，实现了完整的指标生命周期管理，包括指标的创建、查询、更新、删除以及模板管理功能。
+
+系统支持四个维度的平衡计分卡指标管理：
+- **财务维度**：关注医院的经济效益和成本控制
+- **客户维度**：关注患者满意度和服务质量
+- **内部流程维度**：关注医疗质量和运营效率
+- **学习与成长维度**：关注员工发展和能力提升
+
+## 项目结构
+
+后端采用FastAPI框架，遵循MVC架构模式，主要分为以下层次：
+
+```mermaid
+graph TB
+subgraph "表现层"
+Frontend[前端Vue.js应用]
+end
+subgraph "应用层"
+API[API路由层]
+Service[业务服务层]
+end
+subgraph "数据层"
+Model[数据模型层]
+Database[(PostgreSQL数据库)]
+end
+Frontend --> API
+API --> Service
+Service --> Model
+Model --> Database
+```
+
+**图表来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
+
+**章节来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
+
+## 核心组件
+
+### 指标管理核心组件
+
+系统的核心组件包括指标模型、服务层和API路由，形成了完整的指标管理功能体系。
+
+```mermaid
+classDiagram
+class Indicator {
++int id
++string name
++string code
++IndicatorType indicator_type
++BSCDimension bs_dimension
++float weight
++float max_score
++float target_value
++string target_unit
++string calculation_method
++string assessment_method
++string deduction_standard
++string data_source
++string applicable_dept_types
++bool is_veto
++bool is_active
++datetime created_at
++datetime updated_at
+}
+class IndicatorService {
++get_list() tuple
++get_by_id() Indicator
++get_active_indicators() List[Indicator]
++create() Indicator
++update() Indicator
++delete() bool
++import_template() int
++get_templates() List[Dict]
+}
+class IndicatorRouter {
++get_indicators() Response
++get_active_indicators() Response
++get_indicator() Response
++create_indicator() Response
++update_indicator() Response
++delete_indicator() Response
++get_indicator_templates() Response
++import_indicator_template() Response
+}
+IndicatorService --> Indicator : "管理"
+IndicatorRouter --> IndicatorService : "调用"
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
+- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L13-L197)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L17-L142)
+
+### 指标类型和维度体系
+
+系统定义了完整的指标分类体系，支持多维度的指标管理：
+
+| 指标类型 | 描述 | 示例 |
+|---------|------|------|
+| quality | 质量指标 | 病历合格率、满意度 |
+| quantity | 数量指标 | 门诊量、手术量 |
+| efficiency | 效率指标 | 平均住院日、床位使用率 |
+| service | 服务指标 | 服务态度、响应时间 |
+| cost | 成本指标 | 药品占比、能耗成本 |
+
+| 平衡计分卡维度 | 权重范围 | 描述 |
+|---------------|----------|------|
+| financial | 30%-40% | 财务效益和成本控制 |
+| customer | 25%-35% | 患者满意度和市场地位 |
+| internal_process | 20%-30% | 内部流程效率和质量 |
+| learning_growth | 5%-15% | 员工能力和创新 |
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L54-L61)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L35)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L39-L44)
+
+## 架构概览
+
+系统采用分层架构设计，确保了良好的可维护性和扩展性：
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant API as "API路由层"
+participant Service as "服务层"
+participant Model as "数据模型层"
+participant DB as "数据库"
+Client->>API : GET /indicators
+API->>Service : get_list()
+Service->>Model : 查询指标
+Model->>DB : SQL查询
+DB-->>Model : 查询结果
+Model-->>Service : 指标列表
+Service-->>API : 指标数据
+API-->>Client : JSON响应
+Note over Client,DB : 异步数据库操作支持
+```
+
+**图表来源**
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L41)
+- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L46)
+
+## 详细组件分析
+
+### 指标管理API接口
+
+#### 指标列表查询
+
+**接口定义**
+- 方法：GET
+- 路径：`/indicators`
+- 权限：所有用户
+
+**查询参数**
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|-------|------|------|--------|------|
+| indicator_type | string | 否 | 无 | 指标类型过滤 |
+| bs_dimension | string | 否 | 无 | 平衡计分卡维度过滤 |
+| is_active | boolean | 否 | 无 | 是否启用过滤 |
+| page | int | 是 | 1 | 页码 |
+| page_size | int | 是 | 20 | 每页数量 |
+
+**响应结构**
+```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
+}
+```
+
+#### 启用的指标查询
+
+**接口定义**
+- 方法：GET
+- 路径：`/indicators/active`
+- 权限：所有用户
+
+**响应结构**
+```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"
+    }
+  ]
+}
+```
+
+#### 指标详情获取
+
+**接口定义**
+- 方法：GET
+- 路径：`/indicators/{indicator_id}`
+- 权限：所有用户
+
+**路径参数**
+
+| 参数名 | 类型 | 必填 | 说明 |
+|-------|------|------|------|
+| indicator_id | int | 是 | 指标ID |
+
+**响应结构**
+```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"
+  }
+}
+```
+
+#### 指标创建
+
+**接口定义**
+- 方法：POST
+- 路径：`/indicators`
+- 权限：管理员/经理
+
+**请求体结构**
+```json
+{
+  "name": "门诊量",
+  "code": "IND001",
+  "indicator_type": "quantity",
+  "weight": 1.0,
+  "max_score": 100.0,
+  "target_value": 500.0,
+  "unit": "人次",
+  "calculation_method": "实际值/目标值*100",
+  "description": "月度门诊接诊量"
+}
+```
+
+**响应结构**
+```json
+{
+  "code": 200,
+  "message": "创建成功",
+  "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"
+  }
+}
+```
+
+#### 指标更新
+
+**接口定义**
+- 方法：PUT
+- 路径：`/indicators/{indicator_id}`
+- 权限：管理员/经理
+
+**请求体结构**
+```json
+{
+  "name": "更新后的指标名称",
+  "weight": 1.5,
+  "max_score": 120.0,
+  "is_active": false
+}
+```
+
+**响应结构**
+```json
+{
+  "code": 200,
+  "message": "更新成功",
+  "data": {
+    "id": 1,
+    "name": "更新后的指标名称",
+    "code": "IND001",
+    "indicator_type": "quantity",
+    "weight": 1.5,
+    "max_score": 120.0,
+    "target_value": 500.0,
+    "unit": "人次",
+    "calculation_method": "实际值/目标值*100",
+    "description": "月度门诊接诊量",
+    "is_active": false,
+    "created_at": "2024-01-01T00:00:00",
+    "updated_at": "2024-01-01T00:00:00"
+  }
+}
+```
+
+#### 指标删除
+
+**接口定义**
+- 方法：DELETE
+- 路径：`/indicators/{indicator_id}`
+- 权限：管理员/经理
+
+**响应结构**
+```json
+{
+  "code": 200,
+  "message": "删除成功"
+}
+```
+
+**章节来源**
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L112)
+- [docs/api.md](file://docs/api.md#L239-L296)
+
+### 指标模板管理
+
+#### 模板列表查询
+
+**接口定义**
+- 方法：GET
+- 路径：`/templates`
+- 权限：所有用户
+
+**查询参数**
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|-------|------|------|--------|------|
+| template_type | string | 否 | 无 | 模板类型过滤 |
+| is_active | boolean | 否 | 无 | 是否启用过滤 |
+| page | int | 是 | 1 | 页码 |
+| page_size | int | 是 | 20 | 每页数量 |
+
+#### 模板类型列表
+
+**接口定义**
+- 方法：GET
+- 路径：`/templates/types`
+- 权限：所有用户
+
+**响应结构**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {"value": "general", "label": "通用模板"},
+    {"value": "surgical", "label": "手术临床科室"},
+    {"value": "nonsurgical_ward", "label": "非手术有病房科室"},
+    {"value": "nonsurgical_noward", "label": "非手术无病房科室"},
+    {"value": "medical_tech", "label": "医技科室"},
+    {"value": "nursing", "label": "护理单元"},
+    {"value": "admin", "label": "行政科室"},
+    {"value": "logistics", "label": "后勤科室"}
+  ]
+}
+```
+
+#### BSC维度列表
+
+**接口定义**
+- 方法：GET
+- 路径：`/templates/dimensions`
+- 权限：所有用户
+
+**响应结构**
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {"value": "financial", "label": "财务管理", "weight_range": "30%-40%"},
+    {"value": "customer", "label": "顾客服务", "weight_range": "25%-35%"},
+    {"value": "internal_process", "label": "内部流程", "weight_range": "20%-30%"},
+    {"value": "learning_growth", "label": "学习与成长", "weight_range": "5%-15%"}
+  ]
+}
+```
+
+**章节来源**
+- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L74)
+
+### 权重计算和评分规则
+
+系统支持多种评分方法和权重计算方式：
+
+#### 权重计算流程
+
+```mermaid
+flowchart TD
+Start([开始计算]) --> GetIndicators["获取指标列表"]
+GetIndicators --> CheckVeto{"是否包含一票否决"}
+CheckVeto --> |是| ApplyVeto["应用一票否决规则"]
+CheckVeto --> |否| CalcWeight["计算权重"]
+ApplyVeto --> CalcWeight
+CalcWeight --> CalcScore["计算指标得分"]
+CalcScore --> CalcFinal["计算最终得分"]
+CalcFinal --> End([结束])
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L134-L136)
+- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)
+
+#### 评分规则
+
+| 评分方法 | 适用场景 | 计算公式示例 |
+|---------|----------|-------------|
+| 目标参照法 | 有明确目标值的指标 | 得分 = min(100, 实际值/目标值 × 100) |
+| 区间法 | 有合理区间范围的指标 | 根据区间位置线性计算得分 |
+| 扣分法 | 违规或负面指标 | 得分 = 最高分 - 扣分标准 × 违规次数 |
+| 加分法 | 表现优异的指标 | 得分 = 基础分 + 超额完成奖励 |
+| 比较法 | 相对排名指标 | 根据相对排名计算得分 |
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L130-L133)
+- [docs/详细设计.md](file://docs/详细设计.md#L96-L109)
+
+### 指标模板使用方法
+
+#### 模板导入流程
+
+```mermaid
+sequenceDiagram
+participant Admin as "管理员"
+participant API as "模板API"
+participant Service as "模板服务"
+participant DB as "数据库"
+Admin->>API : POST /templates/import
+API->>Service : import_template()
+Service->>Service : 检查模板数据
+Service->>DB : 查询现有指标
+DB-->>Service : 查询结果
+Service->>Service : 判断覆盖策略
+Service->>DB : 批量插入指标
+DB-->>Service : 插入结果
+Service-->>API : 导入统计
+API-->>Admin : 导入成功响应
+```
+
+**图表来源**
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L128-L141)
+- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)
+
+#### 自定义指标创建流程
+
+**步骤1：基础信息配置**
+- 指标编码：唯一标识符，如 FIN001
+- 指标名称：简洁明了的指标描述
+- 指标类型：选择质量/数量/效率/服务/成本之一
+- 权重设置：根据重要程度设置权重值
+
+**步骤2：维度映射**
+- 平衡计分卡维度：财务/客户/内部流程/学习成长
+- 适用科室类型：选择适用的科室类型数组
+
+**步骤3：计算规则配置**
+- 计算方法：描述计算公式和步骤
+- 目标值：设定期望达到的目标值
+- 最高分值：设定指标满分对应的分值
+
+**步骤4：数据验证**
+- 数据来源：指定数据采集系统
+- 扣分标准：设定违规或不达标时的扣分规则
+- 一票否决：设置是否为强制性指标
+
+**章节来源**
+- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py#L22-L232)
+- [docs/详细设计.md](file://docs/详细设计.md#L69-L81)
+
+## 依赖关系分析
+
+系统采用清晰的依赖层次结构，确保了模块间的松耦合：
+
+```mermaid
+graph TD
+subgraph "外部依赖"
+FastAPI[FastAPI框架]
+SQLAlchemy[SQLAlchemy ORM]
+PostgreSQL[PostgreSQL数据库]
+end
+subgraph "核心模块"
+API[API路由层]
+Service[服务层]
+Model[模型层]
+Schema[数据模式层]
+end
+subgraph "业务模块"
+Indicator[指标管理]
+Template[模板管理]
+Assessment[考核管理]
+PerformancePlan[绩效计划]
+end
+FastAPI --> API
+SQLAlchemy --> Model
+PostgreSQL --> Model
+API --> Service
+Service --> Model
+Model --> Schema
+Service --> Schema
+API --> Indicator
+API --> Template
+API --> Assessment
+API --> PerformancePlan
+Indicator --> Template
+Assessment --> PerformancePlan
+```
+
+**图表来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L17)
+- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L1-L13)
+
+**章节来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L17)
+
+## 性能考虑
+
+### 数据库优化
+
+系统采用了多项数据库优化策略：
+
+1. **索引优化**
+   - 指标类型索引：加速指标类型查询
+   - 科室类型索引：优化科室相关查询
+   - 状态索引：快速筛选启用/停用指标
+
+2. **查询优化**
+   - 分页查询：避免一次性加载大量数据
+   - 条件查询：支持多维度过滤查询
+   - 异步查询：使用异步数据库连接池
+
+3. **缓存策略**
+   - 模板数据缓存：减少重复查询
+   - 权重计算缓存：避免重复计算
+
+### 前端性能优化
+
+1. **懒加载**
+   - 指标表格按需加载
+   - 模态框内容延迟渲染
+
+2. **虚拟滚动**
+   - 大数据量表格的虚拟滚动支持
+
+3. **请求去重**
+   - 避免重复的相同查询请求
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+**问题1：指标编码重复**
+- 现象：创建指标时报错"指标编码已存在"
+- 解决方案：使用唯一的指标编码，遵循系统约定的编码规则
+
+**问题2：权限不足**
+- 现象：更新或删除指标返回403权限错误
+- 解决方案：确保当前用户具有管理员或经理权限
+
+**问题3：指标不存在**
+- 现象：查询特定ID指标返回404错误
+- 解决方案：确认指标ID是否正确，检查数据库中是否存在该记录
+
+**问题4：模板导入失败**
+- 现象：模板导入接口报错
+- 解决方案：检查模板数据格式，确认必填字段完整
+
+### 日志和监控
+
+系统提供了完善的日志记录机制：
+
+1. **访问日志**：记录所有API请求的详细信息
+2. **错误日志**：捕获和记录系统异常
+3. **性能日志**：监控数据库查询性能
+4. **审计日志**：记录关键业务操作
+
+**章节来源**
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L78-L81)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L96-L98)
+
+## 结论
+
+本考核指标管理接口实现了完整的平衡计分卡指标管理体系，具有以下特点：
+
+1. **完整的指标生命周期管理**：从创建到删除的全流程支持
+2. **灵活的分类体系**：支持多维度、多类型的指标分类
+3. **强大的模板功能**：支持标准化模板的创建和导入
+4. **完善的权限控制**：基于角色的细粒度权限管理
+5. **高性能的架构设计**：采用异步处理和数据库优化
+
+系统为医院绩效管理提供了坚实的技术基础，能够满足不同科室和岗位的差异化考核需求。
+
+## 附录
+
+### API接口完整列表
+
+| 接口名称 | 方法 | 路径 | 权限 | 功能描述 |
+|---------|------|------|------|----------|
+| 获取指标列表 | GET | /indicators | 所有用户 | 查询所有考核指标 |
+| 获取启用指标 | GET | /indicators/active | 所有用户 | 获取所有启用的指标 |
+| 获取指标详情 | GET | /indicators/{id} | 所有用户 | 获取指定指标详情 |
+| 创建指标 | POST | /indicators | 管理员/经理 | 创建新的考核指标 |
+| 更新指标 | PUT | /indicators/{id} | 管理员/经理 | 更新现有指标信息 |
+| 删除指标 | DELETE | /indicators/{id} | 管理员/经理 | 删除指定指标 |
+| 获取模板列表 | GET | /templates | 所有用户 | 查询指标模板列表 |
+| 获取模板详情 | GET | /templates/{id} | 所有用户 | 获取模板详细信息 |
+| 创建模板 | POST | /templates | 管理员/经理 | 创建新的指标模板 |
+| 更新模板 | PUT | /templates/{id} | 管理员/经理 | 更新模板信息 |
+| 删除模板 | DELETE | /templates/{id} | 管理员/经理 | 删除指定模板 |
+
+### 数据模型关系图
+
+```mermaid
+erDiagram
+INDICATORS {
+int id PK
+string name
+string code UK
+enum indicator_type
+enum bs_dimension
+decimal weight
+decimal max_score
+decimal target_value
+string target_unit
+string calculation_method
+string assessment_method
+string deduction_standard
+string data_source
+string applicable_dept_types
+boolean is_veto
+boolean is_active
+datetime created_at
+datetime updated_at
+}
+INDICATOR_TEMPLATES {
+int id PK
+string template_name
+string template_code UK
+enum template_type
+text description
+text dimension_weights
+string assessment_cycle
+boolean is_active
+datetime created_at
+datetime updated_at
+}
+TEMPLATE_INDICATORS {
+int id PK
+int template_id FK
+int indicator_id FK
+string category
+decimal target_value
+string target_unit
+decimal weight
+string scoring_method
+text scoring_params
+int sort_order
+text remark
+datetime created_at
+datetime updated_at
+}
+INDICATORS ||--o{ TEMPLATE_INDICATORS : "包含"
+INDICATOR_TEMPLATES ||--o{ TEMPLATE_INDICATORS : "定义"
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L437)

.qoder/repowiki/zh/content/API接口文档/工资财务接口.md

@@ -0,0 +1,657 @@
+# 工资财务接口
+
+<cite>
+**本文档引用的文件**
+- [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/services/salary_service.py](file://backend/app/services/salary_service.py)
+- [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/app/models/finance.py](file://backend/app/models/finance.py)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [frontend/src/api/salary.js](file://frontend/src/api/salary.js)
+- [frontend/src/api/finance.js](file://frontend/src/api/finance.js)
+- [docs/api.md](file://docs/api.md)
+- [docs/database.md](file://docs/database.md)
+- [docs/详细设计.md](file://docs/详细设计.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+
+本项目是一个基于FastAPI的医院绩效管理系统，专注于工资核算和财务管理接口。系统实现了完整的工资计算流程，包括绩效奖金计算、基本工资处理、补贴扣除规则等核心功能。同时提供了全面的财务数据统计功能，涵盖收入、支出、收支结余等多维度分析。
+
+系统采用前后端分离架构，后端使用Python FastAPI框架，前端使用Vue.js，数据库采用SQLAlchemy ORM。通过RESTful API接口，实现了与考核系统的数据关联和实时更新机制。
+
+## 项目结构
+
+项目采用模块化设计，主要分为以下几个核心模块：
+
+```mermaid
+graph TB
+subgraph "前端层"
+FE_API[前端API接口]
+FE_VIEW[视图组件]
+end
+subgraph "后端层"
+API_ROUTER[API路由层]
+SERVICE_LAYER[服务层]
+MODEL_LAYER[模型层]
+SCHEMA_LAYER[数据模式层]
+end
+subgraph "数据层"
+DATABASE[(数据库)]
+ASSESSMENT_DB[考核数据库]
+SALARY_DB[工资数据库]
+FINANCE_DB[财务数据库]
+end
+FE_API --> API_ROUTER
+API_ROUTER --> SERVICE_LAYER
+SERVICE_LAYER --> MODEL_LAYER
+MODEL_LAYER --> DATABASE
+MODEL_LAYER --> ASSESSMENT_DB
+MODEL_LAYER --> SALARY_DB
+MODEL_LAYER --> FINANCE_DB
+```
+
+**图表来源**
+- [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/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)
+
+## 核心组件
+
+### 工资核算模块
+
+工资核算模块实现了完整的工资计算和管理功能，包括：
+
+- **工资计算算法**：基于基本工资、绩效得分、绩效系数计算绩效奖金
+- **工资记录管理**：支持创建、更新、查询、确认工资记录
+- **批量处理功能**：支持按科室批量生成和确认工资记录
+- **状态管理**：支持pending、confirmed等状态流转
+
+### 财务核算模块
+
+财务核算模块提供了全面的财务数据统计和分析功能：
+
+- **收入统计**：按科室、类别、时间段统计收入数据
+- **支出统计**：按科室、类别、时间段统计支出数据
+- **收支结余**：计算科室的总收入、总支出和结余
+- **财务汇总**：提供全院范围的财务数据汇总
+
+**章节来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
+- [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py#L1-L368)
+
+## 架构概览
+
+系统采用分层架构设计，确保了良好的可维护性和扩展性：
+
+```mermaid
+graph TB
+subgraph "表现层"
+Frontend[Vue.js前端]
+API_Client[API客户端]
+end
+subgraph "应用层"
+Auth_API[认证API]
+Salary_API[工资API]
+Finance_API[财务API]
+Stats_API[统计API]
+end
+subgraph "服务层"
+Auth_Service[认证服务]
+Salary_Service[工资服务]
+Finance_Service[财务服务]
+Stats_Service[统计服务]
+end
+subgraph "数据访问层"
+ORM_Models[ORM模型]
+Database[(数据库)]
+end
+Frontend --> API_Client
+API_Client --> Auth_API
+API_Client --> Salary_API
+API_Client --> Finance_API
+API_Client --> Stats_API
+Auth_API --> Auth_Service
+Salary_API --> Salary_Service
+Finance_API --> Finance_Service
+Stats_API --> Stats_Service
+Auth_Service --> ORM_Models
+Salary_Service --> ORM_Models
+Finance_Service --> ORM_Models
+Stats_Service --> ORM_Models
+ORM_Models --> Database
+```
+
+**图表来源**
+- [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)
+
+## 详细组件分析
+
+### 工资计算算法
+
+系统实现了标准化的工资计算算法，确保计算的准确性和一致性：
+
+```mermaid
+flowchart TD
+Start([开始计算]) --> GetStaff[获取员工信息]
+GetStaff --> GetAssessment[获取考核记录]
+GetAssessment --> CheckExisting{检查是否存在工资记录}
+CheckExisting --> |存在| ReturnNull[返回空值]
+CheckExisting --> |不存在| CalcBonus[计算绩效奖金]
+CalcBonus --> CalcTotal[计算总工资]
+CalcTotal --> CreateRecord[创建工资记录]
+CreateRecord --> SetPending[设置状态为pending]
+SetPending --> End([计算完成])
+ReturnNull --> End
+```
+
+**图表来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
+
+#### 绩效奖金计算公式
+
+系统采用标准化的绩效奖金计算公式：
+
+```
+绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数
+```
+
+其中：
+- **绩效基数**：固定数值，可根据医院实际情况调整
+- **绩效得分**：来自考核系统的加权得分
+- **绩效系数**：来自员工档案的个人绩效系数
+
+#### 工资总额计算
+
+```mermaid
+classDiagram
+class 工资总额计算 {
++基本工资 : float
++绩效奖金 : float
++补贴 : float
++扣款 : float
++计算公式 : 总额 = 基本工资 + 绩效奖金 + 补贴 - 扣款
+}
+class 基本工资处理 {
++从员工档案获取
++支持手动调整
++参与总额计算
+}
+class 绩效奖金处理 {
++自动计算
++基于考核结果
++参与总额计算
+}
+class 补贴处理 {
++支持多种类型
++可手动调整
++参与总额计算
+}
+class 扣款处理 {
++支持多种类型
++可手动调整
++参与总额计算
+}
+工资总额计算 --> 基本工资处理
+工资总额计算 --> 绩效奖金处理
+工资总额计算 --> 补贴处理
+工资总额计算 --> 扣款处理
+```
+
+**图表来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L85-L91)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L274-L311)
+
+**章节来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L274-L311)
+
+### 工资记录管理
+
+系统提供了完整的工资记录生命周期管理：
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿 : 创建记录
+草稿 --> 待确认 : 更新记录
+待确认 --> 已确认 : 确认操作
+已确认 --> 发放中 : 工资发放
+已确认 --> 草稿 : 修改记录
+发放中 --> 已完成 : 发放完成
+草稿 --> [*] : 删除记录
+待确认 --> [*] : 删除记录
+已确认 --> [*] : 删除记录
+```
+
+#### 工资记录状态流转
+
+| 状态 | 描述 | 权限要求 | 功能限制 |
+|------|------|----------|----------|
+| pending | 待确认 | 管理员/经理 | 可修改、可删除 |
+| confirmed | 已确认 | 管理员/经理 | 只读状态 |
+| paid | 已发放 | 管理员/经理 | 只读状态 |
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L299-L311)
+
+### 财务数据统计
+
+财务核算模块提供了多维度的财务数据分析功能：
+
+```mermaid
+graph LR
+subgraph "财务数据源"
+HIS[HIS系统]
+财务系统[财务系统]
+人事系统[人事系统]
+end
+subgraph "数据处理"
+数据采集[数据采集]
+数据清洗[数据清洗]
+数据计算[数据计算]
+end
+subgraph "统计分析"
+收入统计[收入统计]
+支出统计[支出统计]
+结余分析[结余分析]
+趋势分析[趋势分析]
+end
+HIS --> 数据采集
+财务系统 --> 数据采集
+人事系统 --> 数据采集
+数据采集 --> 数据清洗
+数据清洗 --> 数据计算
+数据计算 --> 收入统计
+数据计算 --> 支出统计
+数据计算 --> 结余分析
+数据计算 --> 趋势分析
+```
+
+**图表来源**
+- [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py#L43-L91)
+- [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py#L93-L141)
+
+#### 财务类别管理
+
+系统支持两类财务类别：
+
+**收入类别**：
+- 检查费、检验费、放射费
+- 床位费、护理费、治疗费
+- 手术费、注射费、吸氧费
+- 其他收入
+
+**支出类别**：
+- 材料费、人员支出
+- 维修费、水电费
+- 其他支出
+
+**章节来源**
+- [backend/app/models/finance.py](file://backend/app/models/finance.py#L16-L43)
+- [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py#L20-L42)
+
+### 批量处理功能
+
+系统提供了高效的批量处理能力：
+
+```mermaid
+sequenceDiagram
+participant Manager as 管理员
+participant API as 工资API
+participant Service as 工资服务
+participant DB as 数据库
+Manager->>API : POST /salary/batch-generate
+API->>Service : batch_generate_for_department()
+Service->>DB : 查询已确认考核记录
+DB-->>Service : 考核记录列表
+loop 为每个员工生成工资记录
+Service->>Service : generate_from_assessment()
+Service->>DB : 创建工资记录
+end
+Service-->>API : 工资记录列表
+API-->>Manager : 批量生成结果
+```
+
+**图表来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L192-L219)
+
+**章节来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L192-L219)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L113-L129)
+
+## 依赖关系分析
+
+系统采用了清晰的依赖层次结构，确保了模块间的松耦合：
+
+```mermaid
+graph TB
+subgraph "外部依赖"
+FastAPI[FastAPI框架]
+SQLAlchemy[SQLAlchemy ORM]
+PostgreSQL[PostgreSQL数据库]
+end
+subgraph "核心依赖"
+Pydantic[Pydantic数据验证]
+AsyncIO[异步I/O支持]
+JWT[JWT认证]
+end
+subgraph "业务依赖"
+AssessmentService[考核服务]
+StaffService[员工服务]
+DepartmentService[科室服务]
+end
+FastAPI --> Pydantic
+FastAPI --> SQLAlchemy
+FastAPI --> JWT
+SQLAlchemy --> PostgreSQL
+AssessmentService --> StaffService
+StaffService --> DepartmentService
+Pydantic --> AssessmentService
+AsyncIO --> FastAPI
+```
+
+**图表来源**
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+
+### 数据模型关系
+
+```mermaid
+erDiagram
+STAFF {
+int id PK
+string employee_id UK
+string name
+int department_id FK
+float base_salary
+float performance_ratio
+}
+ASSESSMENT {
+int id PK
+int staff_id FK
+int period_year
+int period_month
+float weighted_score
+string status
+}
+SALARY_RECORD {
+int id PK
+int staff_id FK
+int period_year
+int period_month
+float base_salary
+float performance_score
+float performance_bonus
+float allowance
+float deduction
+float total_salary
+string status
+}
+DEPARTMENT {
+int id PK
+string name
+string code
+string dept_type
+}
+STAFF ||--o{ ASSESSMENT : has
+STAFF ||--o{ SALARY_RECORD : has
+DEPARTMENT ||--o{ STAFF : has
+ASSESSMENT ||--|| SALARY_RECORD : generates
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L231)
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L231)
+- [docs/database.md](file://docs/database.md#L197-L216)
+
+## 性能考虑
+
+### 数据库优化
+
+系统在数据库层面采用了多项优化策略：
+
+- **索引优化**：为常用查询字段建立复合索引
+- **查询优化**：使用selectinload避免N+1查询问题
+- **分页处理**：支持大数据量的分页查询
+- **连接池**：使用异步连接池提高并发性能
+
+### 缓存策略
+
+```mermaid
+graph TD
+subgraph "缓存层"
+Redis[Redis缓存]
+Session[会话缓存]
+end
+subgraph "应用层"
+API[API接口]
+Service[服务层]
+CacheManager[缓存管理器]
+end
+subgraph "数据层"
+Database[(数据库)]
+end
+API --> CacheManager
+Service --> CacheManager
+CacheManager --> Redis
+CacheManager --> Session
+Redis --> Database
+Session --> Database
+```
+
+### 异步处理
+
+系统广泛采用异步编程模式：
+
+- **异步数据库操作**：使用SQLAlchemy异步引擎
+- **异步文件处理**：支持大文件的异步导入导出
+- **异步任务队列**：支持长时间运行的任务处理
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+| 问题类型 | 症状描述 | 可能原因 | 解决方案 |
+|----------|----------|----------|----------|
+| 工资生成失败 | 返回400错误 | 未找到已确认的考核记录 | 检查考核状态是否为finalized |
+| 权限不足 | 返回403错误 | 用户权限不足 | 确保用户具有管理员或经理权限 |
+| 数据重复 | 生成工资记录失败 | 工资记录已存在 | 检查是否存在重复的工资记录 |
+| 计算错误 | 工资计算结果异常 | 数据类型转换错误 | 验证输入数据的数值格式 |
+
+### 日志记录
+
+系统提供了完善的日志记录机制：
+
+```mermaid
+graph LR
+subgraph "日志级别"
+ERROR[错误日志]
+WARN[警告日志]
+INFO[信息日志]
+DEBUG[调试日志]
+end
+subgraph "日志内容"
+AUTH[认证日志]
+SALARY[工资日志]
+FINANCE[财务日志]
+SYSTEM[系统日志]
+end
+ERROR --> AUTH
+ERROR --> SALARY
+ERROR --> FINANCE
+ERROR --> SYSTEM
+WARN --> AUTH
+WARN --> SALARY
+WARN --> FINANCE
+WARN --> SYSTEM
+INFO --> AUTH
+INFO --> SALARY
+INFO --> FINANCE
+INFO --> SYSTEM
+DEBUG --> AUTH
+DEBUG --> SALARY
+DEBUG --> FINANCE
+DEBUG --> SYSTEM
+```
+
+**章节来源**
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py)
+
+## 结论
+
+本工资财务接口系统实现了医院绩效管理的核心功能，具有以下特点：
+
+1. **完整性**：涵盖了工资核算和财务管理的所有核心功能
+2. **准确性**：采用标准化的计算算法，确保计算结果的准确性
+3. **可扩展性**：模块化设计，易于功能扩展和维护
+4. **安全性**：完善的权限控制和数据验证机制
+5. **高效性**：异步处理和数据库优化，支持高并发场景
+
+系统通过与考核系统的深度集成，实现了从考核到工资发放的完整业务流程自动化，为医院的绩效管理提供了强有力的技术支撑。
+
+## 附录
+
+### API接口规范
+
+#### 工资核算接口
+
+| 接口 | 方法 | 描述 | 权限要求 |
+|------|------|------|----------|
+| `/salary` | GET | 获取工资记录列表 | 普通用户 |
+| `/salary/{id}` | GET | 获取工资记录详情 | 普通用户 |
+| `/salary` | POST | 创建工资记录 | 管理员/经理 |
+| `/salary/{id}` | PUT | 更新工资记录 | 管理员/经理 |
+| `/salary/generate` | POST | 根据考核生成工资 | 管理员/经理 |
+| `/salary/batch-generate` | POST | 批量生成工资 | 管理员/经理 |
+| `/salary/{id}/confirm` | POST | 确认工资 | 管理员/经理 |
+| `/salary/batch-confirm` | POST | 批量确认工资 | 管理员/经理 |
+
+#### 财务核算接口
+
+| 接口 | 方法 | 描述 | 权限要求 |
+|------|------|------|----------|
+| `/finance/revenue` | GET | 获取科室收入 | 普通用户 |
+| `/finance/expense` | GET | 获取科室支出 | 普通用户 |
+| `/finance/balance` | GET | 获取收支结余 | 普通用户 |
+| `/finance/revenue/by-category` | GET | 按类别统计收入 | 普通用户 |
+| `/finance/expense/by-category` | GET | 按类别统计支出 | 普通用户 |
+| `/finance/summary` | GET | 获取科室财务汇总 | 普通用户 |
+| `/finance/categories` | GET | 获取财务类别 | 普通用户 |
+| `/finance` | POST | 创建财务记录 | 管理员/经理 |
+| `/finance/{id}` | PUT | 更新财务记录 | 管理员/经理 |
+| `/finance/{id}` | DELETE | 删除财务记录 | 管理员/经理 |
+
+### 数据模型说明
+
+#### 工资记录字段
+
+| 字段名 | 类型 | 描述 | 默认值 |
+|--------|------|------|--------|
+| id | Integer | 主键 | 自增 |
+| staff_id | Integer | 员工ID | 外键 |
+| period_year | Integer | 年度 | 必填 |
+| period_month | Integer | 月份 | 必填 |
+| base_salary | Numeric(10,2) | 基本工资 | 0.00 |
+| performance_score | Numeric(5,2) | 绩效得分 | 0.00 |
+| performance_bonus | Numeric(10,2) | 绩效奖金 | 0.00 |
+| allowance | Numeric(10,2) | 补贴 | 0.00 |
+| deduction | Numeric(10,2) | 扣款 | 0.00 |
+| total_salary | Numeric(10,2) | 应发工资 | 0.00 |
+| status | String(20) | 状态 | pending |
+| remark | Text | 备注 | null |
+| created_at | DateTime | 创建时间 | 当前时间 |
+| updated_at | DateTime | 更新时间 | 当前时间 |
+
+#### 财务记录字段
+
+| 字段名 | 类型 | 描述 | 默认值 |
+|--------|------|------|--------|
+| id | Integer | 主键 | 自增 |
+| department_id | Integer | 科室ID | 外键 |
+| period_year | Integer | 年度 | 必填 |
+| period_month | Integer | 月份 | 必填 |
+| finance_type | Enum | 财务类型 | 必填 |
+| category | String(50) | 类别 | 必填 |
+| amount | Numeric(12,2) | 金额 | 0.00 |
+| source | String(100) | 数据来源 | null |
+| remark | Text | 备注 | null |
+| created_at | DateTime | 创建时间 | 当前时间 |
+| updated_at | DateTime | 更新时间 | 当前时间 |
+
+### 使用示例
+
+#### 工资计算示例
+
+```javascript
+// 获取工资列表
+const response = await getSalaryRecords({
+  department_id: 1,
+  period_year: 2024,
+  period_month: 1,
+  status: 'confirmed'
+});
+
+// 生成工资记录
+const generateResponse = await generateSalary({
+  staff_id: 1,
+  period_year: 2024,
+  period_month: 1
+});
+
+// 批量生成工资
+const batchResponse = await batchGenerateSalary({
+  department_id: 1,
+  period_year: 2024,
+  period_month: 1
+});
+```
+
+#### 财务统计示例
+
+```javascript
+// 获取收入统计
+const revenue = await getRevenue({
+  department_id: 1,
+  period_year: 2024,
+  period_month: 1
+});
+
+// 获取支出统计
+const expense = await getExpense({
+  department_id: 1,
+  period_year: 2024,
+  period_month: 1
+});
+
+// 获取收支结余
+const balance = await getBalance({
+  department_id: 1,
+  period_year: 2024,
+  period_month: 1
+});
+```
+
+**章节来源**
+- [docs/api.md](file://docs/api.md#L401-L469)
+- [docs/api.md](file://docs/api.md#L471-L538)

.qoder/repowiki/zh/content/API接口文档/系统管理接口.md

@@ -0,0 +1,563 @@
+# 系统管理接口
+
+<cite>
+**本文档引用的文件**
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_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/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/staff.py](file://backend/app/api/v1/staff.py)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py)
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py)
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js)
+- [frontend/src/views/system/Menus.vue](file://frontend/src/views/system/Menus.vue)
+- [frontend/dist/assets/menu-CltzMZXm.js](file://frontend/dist/assets/menu-CltzMZXm.js)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+本文档为医院绩效管理系统的系统管理接口提供全面的API文档。该系统采用FastAPI + SQLAlchemy 2.0架构，实现了完整的菜单权限管理、系统配置和用户角色管理功能。
+
+系统的核心特性包括：
+- **菜单权限管理**：支持树形菜单结构的增删改查操作
+- **RBAC权限控制**：基于角色的访问控制模型
+- **动态菜单生成**：根据用户权限动态生成前端路由
+- **系统配置管理**：集中化的系统参数配置
+- **日志管理和审计追踪**：完整的操作日志记录
+- **用户角色管理**：灵活的角色权限模型
+
+## 项目结构
+
+系统采用分层架构设计，主要分为以下层次：
+
+```mermaid
+graph TB
+subgraph "前端层"
+FE_Router[Vue Router]
+FE_API[API请求封装]
+FE_Components[业务组件]
+end
+subgraph "后端层"
+API_Router[FastAPI Router]
+Security[安全认证]
+Services[业务服务层]
+Models[数据模型层]
+Schemas[数据模式层]
+end
+subgraph "基础设施层"
+Database[(PostgreSQL数据库)]
+Logging[日志系统]
+Config[配置管理]
+end
+FE_Router --> FE_API
+FE_API --> API_Router
+API_Router --> Security
+API_Router --> Services
+Services --> Models
+Models --> Database
+Services --> Schemas
+API_Router --> Logging
+API_Router --> Config
+```
+
+**图表来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L16)
+
+**章节来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L16)
+
+## 核心组件
+
+### 菜单管理模块
+
+菜单管理是系统权限控制的核心组件，提供了完整的菜单树形结构管理功能：
+
+- **菜单树形结构**：支持无限级菜单嵌套
+- **权限标识**：每个菜单可绑定特定的权限标识
+- **动态显示**：根据用户权限动态过滤可见菜单
+- **排序控制**：支持菜单排序和层级管理
+
+### 用户认证与授权
+
+系统实现了基于JWT的认证机制和RBAC权限控制：
+
+- **多角色支持**：admin(管理员)、manager(经理)、staff(普通员工)
+- **权限验证**：不同操作需要不同的权限级别
+- **会话管理**：Token过期自动失效
+
+### 系统配置管理
+
+集中化的配置管理确保了系统的灵活性和可维护性：
+
+- **环境配置**：支持多种部署环境
+- **数据库连接池**：优化数据库连接性能
+- **CORS配置**：灵活的跨域访问控制
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L347-L373)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L110)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+
+## 架构概览
+
+系统采用经典的三层架构模式，确保了良好的可维护性和扩展性：
+
+```mermaid
+graph TB
+subgraph "表现层"
+Frontend[Vue.js前端]
+Router[路由系统]
+Store[状态管理]
+end
+subgraph "应用层"
+API[FastAPI API]
+Auth[认证服务]
+MenuSvc[菜单服务]
+StaffSvc[员工服务]
+DeptSvc[科室服务]
+end
+subgraph "数据层"
+ORM[SQLAlchemy ORM]
+DB[(PostgreSQL)]
+Redis[(Redis缓存)]
+end
+Frontend --> API
+API --> Auth
+API --> MenuSvc
+API --> StaffSvc
+API --> DeptSvc
+MenuSvc --> ORM
+StaffSvc --> ORM
+DeptSvc --> ORM
+ORM --> DB
+Auth --> Redis
+```
+
+**图表来源**
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L164)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
+
+## 详细组件分析
+
+### 菜单权限管理API
+
+#### 菜单树形结构查询
+
+系统提供了获取菜单树形结构的接口，支持根据权限过滤可见菜单：
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant API as "菜单API"
+participant Service as "菜单服务"
+participant DB as "数据库"
+Client->>API : GET /menus/tree?visible_only=true
+API->>Service : get_tree(visible_only=True)
+Service->>DB : 查询根菜单
+DB-->>Service : 返回菜单列表
+Service->>Service : 递归构建树形结构
+Service-->>API : 返回菜单树
+API-->>Client : 菜单树形结构
+```
+
+**图表来源**
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L17-L29)
+- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
+
+#### 菜单增删改查操作
+
+系统提供了完整的菜单管理操作接口：
+
+| 接口 | 方法 | 路径 | 权限要求 | 功能描述 |
+|------|------|------|----------|----------|
+| 获取菜单树 | GET | /menus/tree | 任意用户 | 获取完整的菜单树形结构 |
+| 获取菜单列表 | GET | /menus | 任意用户 | 获取菜单列表（可筛选） |
+| 获取菜单详情 | GET | /menus/{menu_id} | 任意用户 | 获取指定菜单详情 |
+| 创建菜单 | POST | /menus | 管理员/经理 | 创建新的菜单项 |
+| 更新菜单 | PUT | /menus/{menu_id} | 管理员/经理 | 更新现有菜单 |
+| 删除菜单 | DELETE | /menus/{menu_id} | 管理员/经理 | 删除菜单项 |
+| 初始化菜单 | POST | /menus/init | 管理员 | 初始化默认菜单结构 |
+
+**章节来源**
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L17-L164)
+
+#### 菜单数据模型
+
+菜单系统的核心数据模型定义：
+
+```mermaid
+classDiagram
+class Menu {
++int id
++int parent_id
++MenuType menu_type
++string menu_name
++string menu_icon
++string path
++string component
++string permission
++int sort_order
++bool is_visible
++bool is_active
++datetime created_at
++datetime updated_at
++Menu[] children
++Menu parent
+}
+class MenuType {
+<<enumeration>>
+MENU
+BUTTON
+}
+Menu --> MenuType : uses
+Menu --> Menu : parent_child
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L347-L373)
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L347-L373)
+
+### RBAC权限控制模型
+
+#### 角色权限架构
+
+系统实现了基于角色的访问控制(RBAC)模型：
+
+```mermaid
+graph LR
+subgraph "用户角色"
+Admin[管理员 - admin]
+Manager[经理 - manager]
+Staff[员工 - staff]
+end
+subgraph "权限级别"
+Level1[读取权限]
+Level2[写入权限]
+Level3[管理权限]
+end
+subgraph "权限矩阵"
+MenuAccess[菜单访问]
+UserManage[用户管理]
+SystemConfig[系统配置]
+end
+Admin --> Level3
+Manager --> Level2
+Staff --> Level1
+Level3 --> MenuAccess
+Level3 --> UserManage
+Level3 --> SystemConfig
+Level2 --> MenuAccess
+Level2 --> UserManage
+Level1 --> MenuAccess
+```
+
+**图表来源**
+- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L110)
+
+#### 权限验证机制
+
+系统通过装饰器实现权限验证：
+
+| 装饰器 | 权限要求 | 用途 |
+|--------|----------|------|
+| get_current_active_user | 有效用户 | 基础用户验证 |
+| get_current_manager_user | 管理员或经理 | 管理操作权限 |
+| get_current_admin_user | 管理员 | 系统管理权限 |
+
+**章节来源**
+- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L110)
+
+### 用户角色管理
+
+#### 用户认证流程
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant AuthAPI as "认证API"
+participant Security as "安全模块"
+participant DB as "用户表"
+participant Token as "JWT Token"
+Client->>AuthAPI : POST /auth/login
+AuthAPI->>Security : 验证用户名密码
+Security->>DB : 查询用户信息
+DB-->>Security : 返回用户数据
+Security->>Security : 验证密码
+Security->>Token : 生成访问令牌
+Security-->>AuthAPI : 返回Token
+AuthAPI-->>Client : {access_token, token_type}
+Note over Client,Token : 用户登录成功
+```
+
+**图表来源**
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L43)
+
+#### 员工管理API
+
+系统提供了完整的员工信息管理功能：
+
+| 接口 | 方法 | 路径 | 权限要求 | 功能描述 |
+|------|------|------|----------|----------|
+| 获取员工列表 | GET | /staff | 任意用户 | 获取员工列表（支持分页和筛选） |
+| 获取员工详情 | GET | /staff/{staff_id} | 任意用户 | 获取指定员工详情 |
+| 创建员工 | POST | /staff | 管理员/经理 | 创建新员工 |
+| 更新员工 | PUT | /staff/{staff_id} | 管理员/经理 | 更新员工信息 |
+| 删除员工 | DELETE | /staff/{staff_id} | 管理员/经理 | 删除员工 |
+| 科室员工列表 | GET | /staff/department/{department_id} | 任意用户 | 获取科室所有员工 |
+
+**章节来源**
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+
+### 科室管理API
+
+#### 科室树形结构管理
+
+```mermaid
+flowchart TD
+Start([开始]) --> GetTree["获取科室树形结构"]
+GetTree --> FilterType{"按类型筛选?"}
+FilterType --> |是| ApplyFilter["应用类型过滤条件"]
+FilterType --> |否| BuildTree["构建树形结构"]
+ApplyFilter --> BuildTree
+BuildTree --> ManualBuild["手动构建树节点"]
+ManualBuild --> CheckParent{"检查父节点"}
+CheckParent --> |有父节点| AddChild["添加到父节点"]
+CheckParent --> |无父节点| AddRoot["添加到根节点"]
+AddChild --> NextNode["处理下一个节点"]
+AddRoot --> NextNode
+NextNode --> MoreNodes{"还有节点?"}
+MoreNodes --> |是| ManualBuild
+MoreNodes --> |否| ReturnTree["返回树形结构"]
+ReturnTree --> End([结束])
+```
+
+**图表来源**
+- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L112-L149)
+
+**章节来源**
+- [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#L112-L149)
+
+### 系统配置管理
+
+#### 配置文件结构
+
+系统采用集中式配置管理：
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| APP_NAME | string | "医院绩效考核管理系统" | 应用名称 |
+| APP_VERSION | string | "1.0.0" | 应用版本 |
+| DEBUG | boolean | true | 调试模式 |
+| API_PREFIX | string | "/api/v1" | API前缀 |
+| DATABASE_URL | string | PostgreSQL连接串 | 数据库连接地址 |
+| SECRET_KEY | string | JWT密钥 | JWT签名密钥 |
+| ACCESS_TOKEN_EXPIRE_MINUTES | integer | 480 | Token过期时间(分钟) |
+
+**章节来源**
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+
+### 日志管理和审计追踪
+
+#### 日志系统架构
+
+```mermaid
+graph TB
+subgraph "日志级别"
+INFO[INFO - 控制台输出]
+DEBUG[DEBUG - 文件输出]
+ERROR[ERROR - 错误文件输出]
+end
+subgraph "日志处理器"
+ConsoleHandler[控制台处理器]
+FileHandler[文件处理器]
+ErrorHandler[错误处理器]
+end
+subgraph "日志文件"
+AppLog[app_YYYYMMDD.log]
+ErrorLog[error_YYYYMMDD.log]
+end
+INFO --> ConsoleHandler
+DEBUG --> FileHandler
+ERROR --> ErrorHandler
+ConsoleHandler --> AppLog
+FileHandler --> AppLog
+ErrorHandler --> ErrorLog
+```
+
+**图表来源**
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L26-L59)
+
+**章节来源**
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
+
+## 依赖关系分析
+
+### 前后端交互关系
+
+系统实现了前后端分离的架构模式：
+
+```mermaid
+graph LR
+subgraph "前端应用"
+Router[Vue Router]
+API[API封装]
+Components[业务组件]
+end
+subgraph "后端服务"
+FastAPI[FastAPI应用]
+Auth[认证中间件]
+MenuAPI[菜单API]
+StaffAPI[员工API]
+DeptAPI[科室API]
+end
+subgraph "外部服务"
+PostgreSQL[(PostgreSQL)]
+Redis[(Redis)]
+end
+Router --> API
+API --> FastAPI
+FastAPI --> Auth
+FastAPI --> MenuAPI
+FastAPI --> StaffAPI
+FastAPI --> DeptAPI
+MenuAPI --> PostgreSQL
+StaffAPI --> PostgreSQL
+DeptAPI --> PostgreSQL
+Auth --> Redis
+```
+
+**图表来源**
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L98-L115)
+- [frontend/src/views/system/Menus.vue](file://frontend/src/views/system/Menus.vue#L84-L102)
+
+### 菜单权限与前端路由同步
+
+系统实现了菜单权限与前端路由的实时同步机制：
+
+```mermaid
+sequenceDiagram
+participant FE as "前端应用"
+participant API as "后端API"
+participant MenuSvc as "菜单服务"
+participant Store as "状态管理"
+FE->>Store : 请求菜单权限
+Store->>API : GET /menus/tree
+API->>MenuSvc : get_tree(visible_only=True)
+MenuSvc->>MenuSvc : 过滤可见菜单
+MenuSvc->>MenuSvc : 构建权限树
+MenuSvc-->>API : 返回权限菜单树
+API-->>Store : 菜单权限数据
+Store->>Store : 更新路由配置
+Store-->>FE : 渲染权限路由
+Note over FE,Store : 实时权限更新
+```
+
+**图表来源**
+- [frontend/dist/assets/menu-CltzMZXm.js](file://frontend/dist/assets/menu-CltzMZXm.js#L1-L1)
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L17-L29)
+
+**章节来源**
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L82-L96)
+- [frontend/src/views/system/Menus.vue](file://frontend/src/views/system/Menus.vue#L84-L102)
+
+## 性能考虑
+
+### 数据库优化策略
+
+系统采用了多项数据库优化措施：
+
+- **连接池管理**：配置合理的连接池大小，避免连接过多导致的性能问题
+- **索引优化**：为常用查询字段建立索引，提高查询效率
+- **异步操作**：使用异步数据库操作，提升并发处理能力
+- **查询优化**：使用selectinload进行关联查询，避免N+1查询问题
+
+### 缓存策略
+
+系统实现了多层次的缓存机制：
+
+- **Redis缓存**：用于存储用户会话和热点数据
+- **数据库查询缓存**：缓存常用的查询结果
+- **静态资源缓存**：前端静态资源的长期缓存
+
+### 性能监控
+
+系统提供了基本的性能监控能力：
+
+- **健康检查**：提供系统健康状态检查接口
+- **日志监控**：详细的日志记录和错误追踪
+- **异常处理**：完善的异常处理和错误恢复机制
+
+## 故障排除指南
+
+### 常见问题诊断
+
+#### 认证相关问题
+
+| 问题症状 | 可能原因 | 解决方案 |
+|----------|----------|----------|
+| 登录失败 | 用户名或密码错误 | 检查用户凭据是否正确 |
+| Token过期 | 访问令牌超时 | 重新登录获取新Token |
+| 权限不足 | 用户角色权限不够 | 检查用户角色配置 |
+
+#### 菜单权限问题
+
+| 问题症状 | 可能原因 | 解决方案 |
+|----------|----------|----------|
+| 菜单不显示 | 权限过滤导致 | 检查菜单的is_visible和is_active状态 |
+| 路由无法访问 | 权限标识不匹配 | 验证菜单的permission字段 |
+| 菜单层级错误 | 父子关系配置错误 | 检查parent_id字段设置 |
+
+#### 数据库连接问题
+
+| 问题症状 | 可能原因 | 解决方案 |
+|----------|----------|----------|
+| 连接超时 | 数据库负载过高 | 检查数据库连接池配置 |
+| 查询缓慢 | 缺少索引 | 为常用查询字段添加索引 |
+| 连接数过多 | 未正确关闭连接 | 检查数据库连接管理 |
+
+**章节来源**
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L58-L74)
+
+### 系统监控接口
+
+系统提供了基本的监控和诊断接口：
+
+- **健康检查**：`GET /health` - 检查系统运行状态
+- **日志查看**：系统自动记录应用日志和错误日志
+- **配置检查**：验证系统配置的有效性
+
+## 结论
+
+本系统管理接口文档详细介绍了医院绩效管理系统的菜单权限管理、用户角色管理和系统配置功能。系统采用现代化的技术栈和架构设计，实现了：
+
+1. **完整的权限控制**：基于RBAC的细粒度权限管理
+2. **灵活的菜单系统**：支持树形结构和动态权限过滤
+3. **可靠的认证机制**：基于JWT的安全认证
+4. **完善的日志系统**：全面的操作审计和错误追踪
+5. **良好的扩展性**：清晰的分层架构便于功能扩展
+
+通过本文档，开发者可以快速理解和使用系统管理接口，同时为系统的进一步开发和维护提供了清晰的指导。

.qoder/repowiki/zh/content/API接口文档/统计分析接口.md

@@ -0,0 +1,423 @@
+# 统计分析接口
+
+<cite>
+**本文引用的文件**
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js)
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue)
+- [docs/api.md](file://docs/api.md)
+- [docs/详细设计文档.md](file://docs/详细设计文档.md)
+- [backend/init_db.py](file://backend/init_db.py)
+- [TEST_REPORT.md](file://TEST_REPORT.md)
+- [frontend/public/test-api.html](file://frontend/public/test-api.html)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向“统计分析与报表接口”的使用者与维护者，系统化梳理后端统计接口、服务层实现、数据模型与前端调用方式，并补充计算逻辑、时间范围选择、聚合方式、同比环比分析、多维交叉分析、数据钻取与筛选、报表导出、缓存策略与性能优化建议，以及移动端适配与响应时间优化思路。文档同时给出接口参数、响应结构与图表数据格式，帮助快速集成与扩展。
+
+## 项目结构
+统计分析相关代码分布在后端 API、服务层、模型与前端调用层，配合通用响应与数据模式定义，形成清晰的分层架构。
+
+```mermaid
+graph TB
+subgraph "前端"
+FE_API["frontend/src/api/stats.js"]
+FE_VIEW["frontend/src/views/reports/Reports.vue"]
+end
+subgraph "后端"
+API["backend/app/api/v1/stats.py"]
+SVC["backend/app/services/stats_service.py"]
+MODELS["backend/app/models/models.py"]
+SCHEMAS["backend/app/schemas/schemas.py"]
+end
+FE_API --> API
+FE_VIEW --> FE_API
+API --> SVC
+SVC --> MODELS
+API --> SCHEMAS
+SVC --> SCHEMAS
+```
+
+图示来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L200)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L200)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
+
+## 核心组件
+- 统计 API 路由器：提供 BSC 维度分析、科室绩效统计、趋势分析、周期统计、KPI 仪表盘、收支趋势、科室/员工排名、指标完成度等接口。
+- 统计服务层：封装 SQL 查询与聚合逻辑，负责跨表联结、条件过滤、分组统计与排序。
+- 数据模型：定义 BSC 维度、指标类型、评估状态、部门类型等枚举与实体关系。
+- 前端调用与视图：封装 axios 请求、发起多路并发请求、渲染 ECharts 图表与表格。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L16-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L61)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L112-L308)
+
+## 架构总览
+统计接口采用 FastAPI + SQLAlchemy 异步 ORM 的分层设计，前端通过统一的 API 封装进行调用，后端服务层负责复杂聚合与排序，最终以统一响应体返回。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端报表页面"
+participant API as "统计API(stats.py)"
+participant SVC as "统计服务(stats_service.py)"
+participant DB as "数据库(异步会话)"
+FE->>API : GET /stats/department?period_year&period_month
+API->>SVC : get_department_stats(...)
+SVC->>DB : 执行SQL聚合(按科室分组)
+DB-->>SVC : 聚合结果集
+SVC-->>API : 汇总后的科室统计列表
+API-->>FE : 统一响应体(data : 列表)
+```
+
+图示来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L36-L49)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L75-L146)
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+
+## 详细组件分析
+
+### BSC 维度分析
+- 接口：GET /stats/bsc-dimension
+- 功能：按财务、客户、内部流程、学习与成长四个维度统计得分、权重、指标数量与平均分。
+- 时间范围：支持按年/月过滤；未指定时返回全部。
+- 聚合方式：按维度分组，计算总分=Σ(明细得分×指标权重)，总权重=Σ权重，平均分=总分/总权重。
+- 筛选条件：可按科室过滤。
+- 响应结构：包含维度字典与统计周期字符串。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L33)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
+
+### 科室绩效统计
+- 接口：GET /stats/department
+- 功能：返回各科室的员工数、总分、平均分、最高/最低分、员工得分列表，并按平均分降序排列。
+- 时间范围：按年/月过滤；未指定则返回全部。
+- 聚合方式：按科室分组，累计加权得分，计算平均分，记录员工明细。
+- 响应结构：数组，元素包含科室信息、统计指标与员工列表。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L36-L49)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L75-L146)
+
+### 趋势分析（月度）
+- 接口：GET /stats/trend
+- 功能：按最近 N 个月的趋势统计，支持按科室过滤。
+- 时间范围：若未指定年份，默认使用当前年；按最近 N 个月聚合，跨年处理。
+- 聚合方式：按月分组，计算平均总分、平均加权分与记录数。
+- 响应结构：数组，元素包含月份、平均分与计数。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L52-L70)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L149-L199)
+
+### 周期统计
+- 接口：GET /stats/period
+- 功能：返回指定周期的汇总统计（总科室数、总员工数、平均分），并包含各科室明细。
+- 时间范围：若未指定年/月，默认使用当前年/月。
+- 聚合方式：对当期科室统计结果做二次汇总。
+- 响应结构：包含周期字符串、汇总指标与明细数组。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L93-L125)
+
+### KPI 仪表盘
+- 接口：GET /stats/kpi-gauges
+- 功能：返回关键指标仪表盘数据（床位使用率、药占比、材料占比、患者满意度等）。
+- 时间范围：若未指定年/月，默认使用当前年/月。
+- 注意：当前为演示数据，后续需替换为真实数据库查询。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L128-L153)
+
+### 收支趋势
+- 接口：GET /stats/finance-trend
+- 功能：返回最近 N 个月的收入、支出、利润趋势。
+- 时间范围：按最近 N 个月聚合。
+- 注意：当前为演示数据，后续需替换为真实数据库查询。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L156-L183)
+
+### 科室绩效排名
+- 接口：GET /stats/department-ranking
+- 功能：返回指定周期内科室的平均分排名前 N。
+- 时间范围：若未指定年/月，默认使用当前年/月。
+- 聚合方式：基于科室统计结果取前 N。
+- 响应结构：数组，元素为科室排名数据。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L186-L207)
+
+### 员工绩效排名
+- 接口：GET /stats/ranking
+- 功能：返回指定周期内员工的加权得分排名前 N。
+- 时间范围：必须提供年/月。
+- 聚合方式：按加权得分降序取前 N。
+- 响应结构：数组，元素包含员工信息与排名。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L210-L224)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L202-L244)
+
+### 指标完成度
+- 接口：GET /stats/completion
+- 功能：返回指标的平均分、最大/最小分、完成率与统计数量。
+- 时间范围：按年/月过滤；可按指标 ID 过滤。
+- 聚合方式：按指标分组，计算平均分与完成率=平均分/目标值×100（上限 100）。
+- 响应结构：包含指标数组。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L227-L241)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L247-L299)
+
+### 预警数据
+- 接口：GET /stats/alerts
+- 功能：返回预警数据（低分员工、未完成考核科室、异常数据）。
+- 注意：当前为演示数据，后续需替换为真实数据库查询。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L73-L90)
+
+## 依赖关系分析
+- API 层依赖服务层，服务层依赖模型层与异步数据库会话。
+- 前端通过封装的 API 模块调用后端接口，视图组件负责并发请求与图表渲染。
+- 统一响应体与 Pydantic 模式用于前后端契约约束。
+
+```mermaid
+classDiagram
+class StatsAPI {
++get_bsc_dimension_stats()
++get_department_stats()
++get_trend_stats()
++get_period_stats()
++get_kpi_gauges()
++get_finance_trend()
++get_department_ranking()
++get_ranking_stats()
++get_completion_stats()
+}
+class StatsService {
++get_bsc_dimension_stats()
++get_department_stats()
++get_trend_stats()
++get_ranking_stats()
++get_completion_stats()
+}
+class Models {
++Assessment
++AssessmentDetail
++Indicator
++Department
++Staff
++BSCDimension
++AssessmentStatus
+}
+StatsAPI --> StatsService : "调用"
+StatsService --> Models : "查询/聚合"
+```
+
+图示来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L200)
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L200)
+
+## 性能考虑
+- 查询优化
+  - 使用分组与聚合函数减少往返，避免在 Python 层重复计算。
+  - 对常用过滤条件建立索引（如评估状态、周期、科室等）。
+- 并发与缓存
+  - 前端并发请求多个统计接口，减少等待时间。
+  - 对热点报表（如周期统计）可引入 Redis 缓存，设置合理 TTL。
+- 分页与限制
+  - 排名类接口限制返回数量（如 limit），避免大结果集。
+- 前端渲染
+  - 图表仅在数据就绪后初始化，避免重复渲染。
+- 响应时间优化建议
+  - 后端：开启连接池、使用异步 ORM、避免 N+1 查询。
+  - 前端：懒加载图表、骨架屏、分页加载。
+
+[本节为通用性能指导，不直接分析具体文件]
+
+## 故障排查指南
+- 常见问题
+  - 参数缺失：确保提供年/月参数或允许默认使用当前年/月。
+  - 数据为空：确认数据库中存在对应周期的评估数据。
+  - 权限问题：确保携带有效 JWT Token。
+- 快速定位
+  - 使用内置测试页面与后端日志定位接口状态与错误信息。
+  - 前端 Network 标签查看失败请求详情。
+- 建议步骤
+  - 清除浏览器缓存与本地存储，硬刷新页面。
+  - 重启后端与前端服务，确认端口占用与代理配置。
+
+章节来源
+- [frontend/public/test-api.html](file://frontend/public/test-api.html#L113-L129)
+- [TEST_REPORT.md](file://TEST_REPORT.md#L62-L95)
+
+## 结论
+统计分析接口围绕“BSC 维度、科室/员工绩效、趋势与排名、指标完成度”等核心主题，提供了清晰的分层实现与统一响应格式。结合前端并发请求与 ECharts 图表渲染，能够满足日常报表与移动端展示需求。后续可在真实数据接入、缓存策略与性能优化方面持续改进。
+
+[本节为总结性内容，不直接分析具体文件]
+
+## 附录
+
+### 接口清单与参数说明
+- BSC 维度分析
+  - 方法：GET
+  - 路径：/stats/bsc-dimension
+  - 查询参数：department_id（可选）、period_year、period_month
+  - 响应：包含维度字典与周期字符串
+- 科室绩效统计
+  - 方法：GET
+  - 路径：/stats/department
+  - 查询参数：period_year、period_month
+  - 响应：科室统计数组
+- 趋势分析
+  - 方法：GET
+  - 路径：/stats/trend
+  - 查询参数：department_id（可选）、period_year（可选）、months（默认 6，范围 1-24）
+  - 响应：按月聚合的趋势数组
+- 周期统计
+  - 方法：GET
+  - 路径：/stats/period
+  - 查询参数：period_year（可选）、period_month（可选）
+  - 响应：周期汇总与明细数组
+- KPI 仪表盘
+  - 方法：GET
+  - 路径：/stats/kpi-gauges
+  - 查询参数：period_year（可选）、period_month（可选）
+  - 响应：关键指标仪表盘数据
+- 收支趋势
+  - 方法：GET
+  - 路径：/stats/finance-trend
+  - 查询参数：months（默认 6，范围 1-24）
+  - 响应：收入/支出/利润趋势数组
+- 科室绩效排名
+  - 方法：GET
+  - 路径：/stats/department-ranking
+  - 查询参数：period_year（可选）、period_month（可选）、limit（默认 10，范围 1-100）
+  - 响应：科室排名数组
+- 员工绩效排名
+  - 方法：GET
+  - 路径：/stats/ranking
+  - 查询参数：period_year、period_month、limit（默认 10，范围 1-100）
+  - 响应：员工排名数组
+- 指标完成度
+  - 方法：GET
+  - 路径：/stats/completion
+  - 查询参数：indicator_id（可选）、period_year、period_month
+  - 响应：指标完成度数组
+- 预警数据
+  - 方法：GET
+  - 路径：/stats/alerts
+  - 查询参数：limit（默认 10，范围 1-100）
+  - 响应：预警数据对象
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L241)
+- [docs/api.md](file://docs/api.md#L471-L538)
+
+### 响应数据结构与图表数据格式
+- 统一响应体
+  - 字段：code、message、data（根据接口不同而异）
+- 科室统计
+  - 字段：department_id、department_name、staff_count、avg_score、total_bonus、staff_list
+- 趋势数据
+  - 字段：month、avg_score、avg_weighted_score、count
+- KPI 仪表盘
+  - 字段：bed_usage_rate、drug_ratio、material_ratio、satisfaction_rate
+- 收支趋势
+  - 字段：period、income、expense、profit
+- 排名数据
+  - 字段：department 或 staff 的基本信息、score、weighted_score、rank
+- 指标完成度
+  - 字段：indicator_id、indicator_name、indicator_code、target_value、max_score、avg_score、completion_rate、count
+
+章节来源
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L347-L375)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L128-L183)
+
+### 计算逻辑与时间范围选择
+- BSC 维度分析
+  - 总分=Σ(明细得分×指标权重)，总权重=Σ权重，平均分=总分/总权重
+- 科室统计
+  - 平均分=总加权分/员工数；最高/最低分在员工列表中比较得出
+- 趋势分析
+  - 若未指定年份，默认使用当前年；按最近 N 个月聚合，跨年处理
+- 指标完成度
+  - 完成率=平均分/目标值×100，上限 100
+- 同比环比分析
+  - 可通过前端按月序列与后端趋势接口实现同比（同月去年）与环比（相邻月份）对比
+
+章节来源
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L75-L146)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L149-L199)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L247-L299)
+
+### 多维度交叉分析、数据钻取与筛选
+- 多维度：BSC 维度、科室类型、指标类型、评估状态等
+- 数据钻取：从周期统计到科室明细，再到员工明细
+- 筛选条件：按年/月、科室、指标 ID、状态等
+- 前端实现：报表页面通过日期选择器与并发请求实现钻取与筛选
+
+章节来源
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
+
+### 报表导出与移动端适配
+- 报表导出：建议在前端将 ECharts 图表导出为 PNG/SVG，或将表格数据导出为 Excel/CSV
+- 移动端适配：图表容器自适应窗口大小，表格采用紧凑布局与分页加载
+- 响应时间优化：后端异步查询、前端懒加载与骨架屏、缓存热点数据
+
+章节来源
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L173-L295)
+
+### 数据模型与枚举参考
+- BSC 维度：financial、customer、internal_process、learning_growth
+- 指标类型：quality、quantity、efficiency、service、cost
+- 评估状态：draft、submitted、reviewed、finalized、rejected
+- 科室类型：多种类型枚举，覆盖临床、医技、行政、护理、后勤等
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L61)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L146)
+- [docs/详细设计文档.md](file://docs/详细设计文档.md#L85-L120)

.qoder/repowiki/zh/content/API接口文档/考核管理接口.md

@@ -0,0 +1,495 @@
+# 考核管理接口
+
+<cite>
+**本文档引用的文件**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
+- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_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/api/v1/salary.py](file://backend/app/api/v1/salary.py)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py)
+- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py)
+- [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py)
+- [backend/app/models/finance.py](file://backend/app/models/finance.py)
+- [docs/详细设计.md](file://docs/详细设计.md)
+- [docs/api.md](file://docs/api.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+
+本项目是一个基于FastAPI的医院绩效管理系统，专注于构建完整的绩效考核管理接口。系统采用现代化的分层架构设计，包含三个核心功能模块：
+
+- **考核记录管理**：负责员工绩效考核的全流程管理，包括草稿保存、提交审核、审核通过、确认完成等状态转换
+- **考核明细处理**：管理具体的考核指标明细，支持批量操作和历史记录查询
+- **绩效计划管理**：涵盖医院级、科室级、个人级的多层次绩效计划制定、审批和执行
+
+系统实现了完整的绩效管理闭环，从指标定义到结果应用，支持与工资核算系统的深度集成，为医院建立科学的激励约束机制提供技术支撑。
+
+## 项目结构
+
+系统采用典型的三层架构设计，遵循RESTful API设计原则：
+
+```mermaid
+graph TB
+subgraph "表现层 (API层)"
+A[Assessment API]
+B[Performance Plan API]
+C[Salary API]
+D[Finance API]
+end
+subgraph "业务逻辑层 (Service层)"
+E[Assessment Service]
+F[Performance Plan Service]
+G[Salary Service]
+H[Finance Service]
+end
+subgraph "数据访问层 (Model层)"
+I[Assessment Model]
+J[Performance Plan Model]
+K[Salary Record Model]
+L[Finance Model]
+end
+A --> E
+B --> F
+C --> G
+D --> H
+E --> I
+F --> J
+G --> K
+H --> L
+I --> J
+K --> L
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
+
+**章节来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
+
+## 核心组件
+
+### 考核管理模块
+
+考核管理模块提供完整的绩效考核生命周期管理，支持多层级的状态流转和权限控制：
+
+- **状态管理**：草稿(draft) → 已提交(submitted) → 已审核(reviewed) → 已确认(finalized) → 已驳回(rejected)
+- **权限控制**：不同状态支持不同角色的操作权限
+- **批量操作**：支持批量创建考核记录和批量生成工资记录
+- **历史追踪**：完整的操作日志和状态变更记录
+
+### 绩效计划模块
+
+绩效计划模块实现多层次的计划管理体系：
+
+- **计划层级**：医院级(hospital) → 科室级(department) → 个人级(individual)
+- **状态流程**：草稿(draft) → 待审批(pending) → 已批准(approved) → 执行中(active) → 已完成(completed)
+- **指标关联**：支持计划与KPI指标的灵活关联和权重配置
+- **版本管理**：支持计划的版本控制和历史追溯
+
+### 工资核算模块
+
+工资核算模块与考核结果深度集成：
+
+- **自动计算**：基于考核得分自动计算绩效奖金
+- **系数应用**：结合员工绩效系数和个人基本工资
+- **批量处理**：支持科室级批量生成工资记录
+- **状态管理**：pending → confirmed 的确认流程
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L233-L242)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
+
+## 架构概览
+
+系统采用分层架构设计，确保职责分离和代码可维护性：
+
+```mermaid
+sequenceDiagram
+participant Client as 客户端
+participant API as API层
+participant Service as 服务层
+participant Model as 模型层
+participant DB as 数据库
+Client->>API : 发起考核请求
+API->>Service : 调用业务逻辑
+Service->>Model : 操作数据模型
+Model->>DB : 执行数据库操作
+DB-->>Model : 返回查询结果
+Model-->>Service : 返回业务数据
+Service-->>API : 返回处理结果
+API-->>Client : 返回响应数据
+Note over Client,DB : 完整的CRUD操作流程
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L80-L103)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
+
+系统还实现了异步数据库操作，支持高并发场景下的性能优化：
+
+```mermaid
+graph LR
+A[异步数据库连接池] --> B[SQLAlchemy AsyncSession]
+B --> C[查询操作]
+B --> D[事务处理]
+C --> E[结果返回]
+D --> E
+style A fill:#e1f5fe
+style B fill:#f3e5f5
+style E fill:#e8f5e8
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L6-L8)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L11)
+
+## 详细组件分析
+
+### 考核记录管理
+
+#### 接口设计
+
+考核管理模块提供了完整的RESTful API接口：
+
+| 功能 | 方法 | 路径 | 描述 |
+|------|------|------|------|
+| 获取考核列表 | GET | `/assessments` | 支持多条件查询和分页 |
+| 获取考核详情 | GET | `/assessments/{id}` | 返回完整考核信息 |
+| 创建考核记录 | POST | `/assessments` | 创建新的考核记录 |
+| 更新考核记录 | PUT | `/assessments/{id}` | 更新现有考核记录 |
+| 提交考核 | POST | `/assessments/{id}/submit` | 提交待审核 |
+| 审核考核 | POST | `/assessments/{id}/review` | 审核通过或驳回 |
+| 确认考核 | POST | `/assessments/{id}/finalize` | 确认完成 |
+| 批量创建 | POST | `/assessments/batch-create` | 批量创建考核 |
+
+#### 状态转换流程
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿
+草稿 --> 已提交 : 提交考核
+已提交 --> 已审核 : 审核通过
+已提交 --> 已驳回 : 审核驳回
+已审核 --> 已确认 : 确认完成
+已确认 --> [*]
+已驳回 --> 草稿 : 修改后重新提交
+note right of 草稿 : 可编辑状态
+note right of 已提交 : 等待审核
+note right of 已审核 : 审核完成
+note right of 已确认 : 最终状态
+note right of 已驳回 : 需要修改
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L159-L205)
+
+#### 评分计算逻辑
+
+系统实现了灵活的评分计算机制：
+
+```mermaid
+flowchart TD
+A[开始计算] --> B[遍历考核明细]
+B --> C[获取指标权重]
+C --> D[计算加权得分]
+D --> E[累加总分]
+E --> F[设置状态]
+F --> G[保存记录]
+G --> H[结束]
+D --> I[加权得分 = 明细得分 × 指标权重]
+E --> J[总分 = 所有明细得分之和]
+style I fill:#fff3e0
+style J fill:#fff3e0
+```
+
+**图表来源**
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L74-L84)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L129-L149)
+
+**章节来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L18-L263)
+
+### 绩效计划管理
+
+#### 计划层级结构
+
+系统支持多层级的绩效计划管理：
+
+```mermaid
+graph TD
+A[医院级计划] --> B[科室级计划]
+B --> C[个人级计划]
+A --> D[年度计划]
+A --> E[月度计划]
+B --> F[季度计划]
+B --> G[专项计划]
+C --> H[个人目标]
+C --> I[能力发展计划]
+style A fill:#ffebee
+style B fill:#e8f5e8
+style C fill:#e3f2fd
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L263-L268)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L233-L242)
+
+#### 计划审批流程
+
+```mermaid
+sequenceDiagram
+participant Creator as 计划创建者
+participant Manager as 科室负责人
+participant Leader as 分管院领导
+participant Office as 绩效办
+Creator->>Manager : 提交计划
+Manager->>Leader : 审批请求
+Leader->>Office : 最终审批
+Office->>Creator : 审批结果
+Note over Creator,Office : 多级审批流程
+```
+
+**图表来源**
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L194-L226)
+- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L144-L182)
+
+**章节来源**
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L21-L310)
+- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L18-L342)
+
+### 工资核算集成
+
+#### 薪酬计算公式
+
+系统实现了标准化的薪酬计算机制：
+
+```mermaid
+flowchart LR
+A[基本工资] --> C[总薪酬计算]
+B[绩效奖金] --> C
+D[补贴] --> C
+E[扣款] --> C
+C --> F[应发工资 = 基本工资 + 绩效奖金 + 补贴 - 扣款]
+G[绩效得分] --> H[绩效奖金计算]
+I[绩效系数] --> H
+H --> B
+H --> J[绩效奖金 = 基础基数 × (绩效得分/100) × 绩效系数]
+style J fill:#fff8e1
+style F fill:#e8f5e8
+```
+
+**图表来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
+
+#### 自动化生成流程
+
+```mermaid
+sequenceDiagram
+participant HR as 人事系统
+participant Perf as 绩效系统
+participant Payroll as 工资系统
+participant Finance as 财务系统
+HR->>Perf : 触发工资生成
+Perf->>Perf : 查询已确认考核
+Perf->>Perf : 计算绩效奖金
+Perf->>Payroll : 创建工资记录
+Payroll->>Finance : 生成发放清单
+Finance-->>HR : 薪资发放完成
+Note over HR,Finance : 完整的薪资发放流程
+```
+
+**图表来源**
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L130)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L219)
+
+**章节来源**
+- [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#L14-L260)
+
+## 依赖关系分析
+
+系统采用清晰的依赖层次结构，确保模块间的松耦合：
+
+```mermaid
+graph TB
+subgraph "外部依赖"
+A[FastAPI]
+B[SQLAlchemy]
+C[AsyncIO]
+D[Pydantic]
+end
+subgraph "核心模块"
+E[API层]
+F[服务层]
+G[模型层]
+H[Schema层]
+end
+subgraph "数据库层"
+I[Assessment表]
+J[PerformancePlan表]
+K[SalaryRecord表]
+L[Finance表]
+end
+A --> E
+B --> F
+C --> F
+D --> H
+E --> F
+F --> G
+G --> H
+G --> I
+G --> J
+G --> K
+G --> L
+style A fill:#e3f2fd
+style B fill:#e8f5e8
+style E fill:#fff3e0
+style F fill:#f3e5f5
+style G fill:#e0f2f1
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L17)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L11)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L14)
+
+### 权限控制机制
+
+系统实现了基于角色的权限控制(RBAC)：
+
+| 角色 | 权限范围 | 可执行操作 |
+|------|----------|------------|
+| staff | 普通员工 | 查看自己的考核记录 |
+| manager | 科室负责人 | 审核下级考核、管理科室计划 |
+| admin | 系统管理员 | 完全权限，包括数据维护 |
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L124-L139)
+
+## 性能考虑
+
+### 数据库优化
+
+系统采用了多项性能优化策略：
+
+1. **索引优化**：为常用查询字段建立复合索引
+2. **异步操作**：使用async/await模式提高并发处理能力
+3. **连接池**：配置数据库连接池减少连接开销
+4. **分页查询**：默认每页20条记录，支持最大100条限制
+
+### 缓存策略
+
+```mermaid
+graph LR
+A[请求缓存] --> B[查询缓存]
+B --> C[会话缓存]
+C --> D[响应缓存]
+E[热点数据] --> F[内存缓存]
+F --> G[分布式缓存]
+style A fill:#e8f5e8
+style E fill:#fff3e0
+```
+
+### 并发处理
+
+系统支持高并发场景下的稳定运行：
+
+- **异步数据库操作**：避免阻塞主线程
+- **批量操作**：减少数据库往返次数
+- **状态锁机制**：防止并发状态冲突
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+| 问题类型 | 症状 | 可能原因 | 解决方案 |
+|----------|------|----------|----------|
+| 权限错误 | 403 Forbidden | 用户权限不足 | 检查用户角色和权限配置 |
+| 数据验证错误 | 422 Unprocessable Entity | 请求数据格式不正确 | 验证请求参数和数据类型 |
+| 资源不存在 | 404 Not Found | ID不存在或已被删除 | 确认资源ID的有效性 |
+| 状态冲突 | 400 Bad Request | 状态转换不符合规则 | 检查当前状态和允许的操作 |
+
+### 日志记录
+
+系统提供了完整的日志记录机制：
+
+```mermaid
+graph TD
+A[操作请求] --> B[请求日志]
+B --> C[业务日志]
+C --> D[错误日志]
+D --> E[性能日志]
+F[审计日志] --> G[操作追踪]
+G --> H[合规记录]
+style B fill:#e8f5e8
+style D fill:#ffebee
+style F fill:#f3e5f5
+```
+
+**章节来源**
+- [docs/api.md](file://docs/api.md#L540-L551)
+
+## 结论
+
+本绩效考核管理接口系统具有以下特点：
+
+1. **完整性**：覆盖了从指标定义到结果应用的完整生命周期
+2. **灵活性**：支持多层级、多类型的绩效管理需求
+3. **可扩展性**：模块化设计便于功能扩展和维护
+4. **安全性**：完善的权限控制和数据验证机制
+5. **集成性**：与工资核算系统无缝集成，实现数据共享
+
+系统采用先进的技术栈和架构设计，能够满足现代医院对绩效管理的复杂需求，为建立科学的激励约束机制提供强有力的技术支撑。
+
+## 附录
+
+### API接口规范
+
+系统遵循RESTful API设计原则，提供统一的接口规范：
+
+- **响应格式**：统一的JSON响应格式，包含状态码、消息和数据
+- **分页机制**：支持页码和每页数量的参数配置
+- **错误处理**：标准化的错误响应格式
+- **认证机制**：JWT Bearer Token认证方式
+
+### 数据模型设计
+
+系统采用关系型数据库设计，确保数据的一致性和完整性：
+
+- **主键设计**：使用自增主键确保唯一性
+- **外键约束**：建立合理的外键关系保证数据完整性
+- **索引优化**：为查询频繁的字段建立索引
+- **数据类型**：使用合适的数据类型确保数据精度
+
+### 集成接口
+
+系统支持与其他医院信息系统(HIS)的集成：
+
+- **数据同步**：支持定时或实时的数据同步机制
+- **接口适配**：提供标准化的接口适配器
+- **错误处理**：完善的异常处理和重试机制
+- **监控告警**：实时监控接口调用状态

.qoder/repowiki/zh/content/API接口文档/认证接口.md

@@ -0,0 +1,346 @@
+# 认证接口
+
+<cite>
+**本文引用的文件**
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
+- [backend/app/core/security.py](file://backend/app/core/security.py)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py)
+- [backend/app/main.py](file://backend/app/main.py)
+- [frontend/src/api/auth.js](file://frontend/src/api/auth.js)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+
+## 简介
+本文件为“用户认证接口”的完整API文档，覆盖以下三个核心接口：
+- 用户登录
+- 用户注册
+- 获取当前用户信息
+
+内容涵盖HTTP方法、URL路径、请求参数格式、响应数据结构、错误码、JWT令牌生成机制、密码验证流程、用户权限验证、OAuth2密码模式使用方法与安全注意事项、以及令牌过期处理与刷新机制的实现细节。同时提供成功与失败场景的请求/响应示例，并给出前后端集成要点。
+
+## 项目结构
+认证相关代码主要分布在后端的API层、安全模块、数据模型与配置模块；前端通过Axios封装统一请求，自动携带Authorization头。
+
+```mermaid
+graph TB
+subgraph "后端"
+A["API路由<br/>backend/app/api/v1/auth.py"]
+B["安全模块<br/>backend/app/core/security.py"]
+C["数据模型<br/>backend/app/models/models.py"]
+D["配置<br/>backend/app/core/config.py"]
+E["数据库连接<br/>backend/app/core/database.py"]
+F["主应用入口<br/>backend/app/main.py"]
+G["API聚合<br/>backend/app/api/v1/__init__.py"]
+end
+subgraph "前端"
+H["认证API封装<br/>frontend/src/api/auth.js"]
+I["请求拦截器<br/>frontend/src/api/request.js"]
+J["用户状态存储<br/>frontend/src/stores/user.js"]
+end
+H --> I
+I --> F
+F --> G
+G --> A
+A --> B
+A --> C
+B --> D
+B --> E
+J --> H
+```
+
+图表来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L22)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L22)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
+
+## 核心组件
+- 认证路由与控制器：定义登录、注册、获取当前用户三个接口，使用OAuth2密码模式进行认证。
+- 安全模块：负责密码哈希与校验、JWT令牌生成与解析、当前用户与权限校验。
+- 数据模型：User模型包含用户名、密码哈希、角色、激活状态等字段。
+- 配置模块：提供API前缀、JWT密钥、算法、过期时间等配置。
+- 数据库连接：异步SQLAlchemy会话管理。
+- 前端请求封装：统一添加Authorization头，处理401等错误并跳转登录。
+
+章节来源
+- [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#L24-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L15-L26)
+
+## 架构概览
+认证流程采用OAuth2密码模式，客户端向登录接口发送用户名/密码，服务端验证后签发JWT访问令牌；后续请求由前端在请求头中携带Authorization: Bearer <token>，后端通过依赖注入解析并校验令牌，获取当前用户。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端应用"
+participant API as "认证接口<br/>/api/v1/auth"
+participant SEC as "安全模块<br/>JWT/密码"
+participant DB as "数据库<br/>User表"
+FE->>API : POST /api/v1/auth/login
+API->>DB : 查询用户(用户名)
+DB-->>API : 用户记录
+API->>SEC : 校验密码
+SEC-->>API : 校验结果
+API->>SEC : 生成访问令牌
+SEC-->>API : 返回JWT
+API-->>FE : {access_token, token_type}
+FE->>API : GET /api/v1/auth/me<br/>Authorization : Bearer <token>
+API->>SEC : 解析JWT并校验
+SEC->>DB : 查询用户(根据sub)
+DB-->>SEC : 用户记录
+SEC-->>API : 当前用户
+API-->>FE : 用户信息
+```
+
+图表来源
+- [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#L34-L91)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L4-L21)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L15-L26)
+
+## 详细组件分析
+
+### 接口定义与行为
+
+- 用户登录
+  - 方法与路径：POST /api/v1/auth/login
+  - 认证方式：OAuth2密码模式（form-data）
+  - 请求体字段：
+    - username: 字符串，最小长度3，最大长度50
+    - password: 字符串，最小长度6，最大长度100
+  - 成功响应：
+    - access_token: 字符串（JWT）
+    - token_type: 字符串，默认"bearer"
+  - 错误码：
+    - 401：用户名或密码错误
+    - 403：账户已禁用
+  - 处理逻辑：
+    - 根据用户名查询用户
+    - 使用bcrypt校验密码
+    - 校验用户是否激活
+    - 生成JWT访问令牌并返回
+
+- 用户注册
+  - 方法与路径：POST /api/v1/auth/register
+  - 请求体字段：
+    - username: 字符串，最小长度3，最大长度50
+    - password: 字符串，最小长度6，最大长度100
+    - staff_id: 可选整数
+    - role: 字符串，枚举(admin|manager|staff)，默认staff
+  - 成功响应：
+    - code: 整数，默认200
+    - message: 字符串，默认"注册成功"
+    - data.id: 新用户ID
+  - 错误码：
+    - 400：用户名已存在
+  - 处理逻辑：
+    - 检查用户名是否重复
+    - 生成密码哈希
+    - 创建用户记录并持久化
+
+- 获取当前用户信息
+  - 方法与路径：GET /api/v1/auth/me
+  - 认证方式：Bearer Token（Authorization头）
+  - 成功响应：
+    - id: 整数
+    - username: 字符串
+    - role: 字符串
+    - is_active: 布尔
+    - last_login: 可选时间戳
+    - created_at: 时间戳
+  - 错误码：
+    - 401：无法验证凭据（无效/过期令牌）
+    - 403：需要管理员权限（若使用管理员依赖）
+  - 处理逻辑：
+    - 通过OAuth2 Bearer Scheme获取令牌
+    - 解析JWT载荷(sub为用户ID)
+    - 查询用户并返回
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L345)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L91)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+
+### JWT令牌生成机制
+- 令牌内容：
+  - exp：过期时间（UTC）
+  - sub：用户ID（字符串）
+- 签发过程：
+  - 使用配置中的SECRET_KEY与ALGORITHM（如HS256）进行签名
+  - 默认过期时间为ACCESS_TOKEN_EXPIRE_MINUTES（8小时）
+- 解析过程：
+  - 从Authorization头提取Bearer Token
+  - 使用相同密钥与算法解码，获取payload
+  - 从payload取sub作为用户ID，查询用户是否存在且激活
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L34-L53)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L91)
+
+### 密码验证流程
+- 存储：密码以哈希形式保存（bcrypt）
+- 校验：接收明文密码与存储的哈希，使用bcrypt.checkpw进行比对
+- 注册：注册时对明文密码生成哈希再存入数据库
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L31)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L40-L65)
+
+### 用户权限验证
+- 当前用户：通过Bearer Token解析并查询用户
+- 激活状态：仅激活用户可访问受保护资源
+- 角色权限：提供管理员与经理权限校验依赖（用于特定接口）
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L109)
+
+### OAuth2密码模式使用方法与安全考虑
+- 使用方法：
+  - 前端以application/x-www-form-urlencoded方式提交username与password到/login
+  - 服务端返回access_token
+  - 后续请求在Authorization头中携带Bearer <token>
+- 安全考虑：
+  - 必须通过HTTPS传输，避免令牌被窃听
+  - 令牌过期时间较短（默认8小时），建议实现刷新机制
+  - 前端仅本地存储令牌，避免泄露
+  - 服务端严格校验令牌与用户状态
+
+章节来源
+- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L4-L11)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L15-L26)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+
+### 令牌过期处理与刷新机制
+- 过期处理：
+  - 前端在401时提示“登录已过期”，清除本地令牌并跳转登录页
+- 刷新机制：
+  - 当前实现未提供refresh_token接口
+  - 建议新增刷新令牌接口，或延长ACCESS_TOKEN_EXPIRE_MINUTES并配合短期会话策略
+
+章节来源
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L39-L57)
+
+## 依赖关系分析
+
+```mermaid
+classDiagram
+class AuthRouter{
++POST /auth/login
++POST /auth/register
++GET /auth/me
+}
+class SecurityModule{
++verify_password()
++get_password_hash()
++create_access_token()
++decode_token()
++get_current_user()
++get_current_active_user()
+}
+class UserModel{
++id
++username
++password_hash
++role
++is_active
+}
+class Config{
++SECRET_KEY
++ALGORITHM
++ACCESS_TOKEN_EXPIRE_MINUTES
++API_PREFIX
+}
+class Database{
++get_db()
+}
+AuthRouter --> SecurityModule : "依赖"
+AuthRouter --> UserModel : "读写"
+SecurityModule --> Config : "读取"
+SecurityModule --> Database : "依赖"
+```
+
+图表来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+
+## 性能考量
+- 密码哈希：bcrypt计算开销较高，建议在高并发场景下适当调整密钥迭代次数或使用更高效的硬件
+- JWT解析：每次受保护请求均需解码与用户查询，建议缓存活跃用户信息或使用Redis等缓存层
+- 数据库连接：使用异步连接池，合理设置池大小与超时，避免阻塞
+- 前端拦截器：统一处理401错误，减少重复逻辑
+
+[本节为通用指导，不直接分析具体文件]
+
+## 故障排查指南
+- 登录失败（401）：
+  - 检查用户名/密码是否正确
+  - 确认用户是否激活
+- 无法访问受保护接口（401）：
+  - 检查Authorization头是否正确携带Bearer Token
+  - 确认令牌未过期
+- 权限不足（403）：
+  - 确认用户角色是否满足接口要求
+- CORS问题：
+  - 检查CORS允许的源与预检请求
+- 前端401自动跳转：
+  - 确认本地存储的token是否被清理
+  - 检查请求拦截器是否正确添加Authorization头
+
+章节来源
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L39-L63)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L34-L39)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L36)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L91)
+
+## 结论
+该认证系统基于OAuth2密码模式与JWT实现，具备基本的用户登录、注册与当前用户信息获取能力。建议后续增强刷新令牌机制与更细粒度的权限控制，并在生产环境强化安全配置（如HTTPS、密钥轮换、令牌审计等）。