提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/员工信息表.md
+++ b/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/员工信息表.md
@@ -0,0 +1,362 @@
+# 员工信息表
+
+<cite>
+**本文档引用的文件**
+- [models.py](file://backend/app/models/models.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [staff.py](file://backend/app/api/v1/staff.py)
+- [staff_service.py](file://backend/app/services/staff_service.py)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py)
+- [database.md](file://docs/database.md)
+- [salary.py](file://backend/app/api/v1/salary.py)
+- [salary_service.py](file://backend/app/services/salary_service.py)
+- [Staff.vue](file://frontend/src/views/basic/Staff.vue)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件围绕员工信息表（staff）展开，系统性说明字段的业务含义、状态枚举值、与科室表的一对多关系，以及在考核与工资核算中的应用。同时提供索引设计与数据完整性约束说明，并给出典型使用场景与最佳实践。
+
+## 项目结构
+员工信息表位于后端数据模型层，配合服务层、API层与前端页面协同工作，形成“数据模型—服务—接口—视图”的完整链路。
+
+```mermaid
+graph TB
+subgraph "后端"
+M["models.py<br/>数据模型"]
+S["staff_service.py<br/>员工服务"]
+API["staff.py<br/>员工API"]
+SAL_API["salary.py<br/>工资API"]
+SAL_SVC["salary_service.py<br/>工资服务"]
+SCH["schemas.py<br/>数据模式"]
+end
+subgraph "前端"
+FE["Staff.vue<br/>员工管理页面"]
+end
+M --> S
+S --> API
+API --> FE
+SAL_API --> SAL_SVC
+SAL_SVC --> M
+SCH --> API
+SCH --> SAL_API
+```
+
+图表来源
+- [models.py](file://backend/app/models/models.py#L88-L115)
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
+- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
+- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
+
+章节来源
+- [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#L13-L112)
+- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
+- [database.md](file://docs/database.md#L117-L136)
+
+## 核心组件
+- 数据模型：定义员工表结构、字段约束、索引与关系。
+- 服务层：封装员工查询、创建、更新、删除等业务逻辑。
+- API层：对外暴露REST接口，处理请求与响应。
+- 数据模式：定义请求/响应的数据结构与校验规则。
+- 前端页面：提供员工信息的增删改查与筛选能力。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L88-L115)
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
+- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
+
+## 架构总览
+员工信息表与科室表构成一对多关系：一个科室可包含多名员工；一名员工仅属于一个科室。员工表还与考核记录表、工资记录表存在一对多关系，用于支撑绩效考核与工资核算。
+
+```mermaid
+erDiagram
+DEPARTMENTS {
+int id PK
+string name
+string code UK
+enum dept_type
+int parent_id FK
+int level
+int sort_order
+bool is_active
+text description
+datetime created_at
+datetime updated_at
+}
+STAFF {
+int id PK
+string employee_id UK
+string name
+int department_id FK
+string position
+string title
+string phone
+string email
+numeric base_salary
+numeric performance_ratio
+enum status
+datetime hire_date
+datetime created_at
+datetime updated_at
+}
+ASSESSMENTS {
+int id PK
+int staff_id FK
+int period_year
+int period_month
+string period_type
+numeric total_score
+numeric weighted_score
+enum status
+int assessor_id FK
+int reviewer_id FK
+datetime submit_time
+datetime review_time
+text remark
+datetime created_at
+datetime updated_at
+}
+SALARY_RECORDS {
+int id PK
+int staff_id FK
+int period_year
+int period_month
+numeric base_salary
+numeric performance_score
+numeric performance_bonus
+numeric deduction
+numeric allowance
+numeric total_salary
+string status
+text remark
+datetime created_at
+datetime updated_at
+}
+DEPARTMENTS ||--o{ STAFF : "拥有"
+STAFF ||--o{ ASSESSMENTS : "产生"
+STAFF ||--o{ SALARY_RECORDS : "产生"
+```
+
+图表来源
+- [models.py](file://backend/app/models/models.py#L62-L86)
+- [models.py](file://backend/app/models/models.py#L88-L115)
+- [models.py](file://backend/app/models/models.py#L149-L178)
+- [models.py](file://backend/app/models/models.py#L205-L231)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L64)
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L62-L86)
+- [models.py](file://backend/app/models/models.py#L88-L115)
+- [models.py](file://backend/app/models/models.py#L149-L178)
+- [models.py](file://backend/app/models/models.py#L205-L231)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L64)
+
+## 详细组件分析
+
+### 字段业务含义与约束
+- 工号(employee_id)：唯一标识员工，用于跨系统识别与关联。
+- 姓名(name)：员工真实姓名。
+- 所属科室(department_id)：外键关联科室表，限定员工归属。
+- 职位(position)：员工在岗位上的职责描述。
+- 职称(title)：专业技术或管理职称。
+- 联系电话(phone)、邮箱(email)：通讯信息。
+- 基本工资(base_salary)：固定薪酬基数，参与工资核算。
+- 绩效系数(performance_ratio)：影响绩效奖金的浮动系数，数值越大，奖金越高。
+- 状态(status)：员工状态枚举，见下节。
+- 入职日期(hire_date)：记录入职时间。
+- created_at/updated_at：记录创建与更新时间戳。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L88-L115)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
+- [database.md](file://docs/database.md#L117-L136)
+
+### 状态枚举与作用机制
+- 在职(active)：正常在岗，参与考核与工资核算。
+- 休假(leave)：暂时离岗，通常不参与当期考核或按规则折算。
+- 离职(resigned)：已离开医院，一般不再参与后续考核与工资核算。
+- 退休(retired)：达到退休年龄，通常不再参与日常考核与工资核算。
+
+在服务层与API层中，状态常用于过滤查询与业务判断，例如：
+- 列表查询时按状态筛选；
+- 生成工资时仅对在职员工进行计算；
+- 前端展示时对不同状态使用不同标签样式。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L37-L43)
+- [staff_service.py](file://backend/app/services/staff_service.py#L17-L49)
+- [staff.py](file://backend/app/api/v1/staff.py#L20-L49)
+- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L13-L18)
+
+### 绩效系数的作用机制
+- 绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数
+- 绩效系数越大，相同绩效得分能获得更高奖金，体现对高绩效员工的激励。
+- 工资服务层提供计算方法，支持按员工的绩效系数与考核得分生成绩效奖金。
+
+章节来源
+- [salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
+- [salary_service.py](file://backend/app/services/salary_service.py#L167-L170)
+- [salary.py](file://backend/app/api/v1/salary.py#L96-L129)
+
+### 与科室表的一对多关系
+- 一个科室可包含多名员工；
+- 一名员工仅属于一个科室；
+- 员工表通过外键department_id关联科室表；
+- 前端页面在展示员工列表时，会补充显示科室名称，便于直观查看。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L62-L86)
+- [models.py](file://backend/app/models/models.py#L88-L115)
+- [staff.py](file://backend/app/api/v1/staff.py#L35-L41)
+- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L27)
+
+### 在考核与工资核算中的应用
+- 考核记录表(assessments)与员工表(staff)是一对多关系，用于记录每位员工的考核周期、得分与状态。
+- 工资记录表(salary_records)与员工表(staff)是一对多关系，用于记录每月工资构成与状态。
+- 工资生成流程：根据已确认的考核记录，读取员工的基本工资与绩效系数，计算绩效奖金并生成工资记录。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端页面"
+participant API as "工资API"
+participant SVC as "工资服务"
+participant DB as "数据库"
+participant ST as "员工表"
+participant AS as "考核记录表"
+FE->>API : "POST /salary/generate?staff_id&period_year&period_month"
+API->>SVC : "generate_from_assessment(staff_id, year, month)"
+SVC->>DB : "查询员工信息(含performance_ratio)"
+DB-->>SVC : "返回员工(含基本工资、系数)"
+SVC->>DB : "查询已确认的考核记录(weighted_score)"
+DB-->>SVC : "返回考核记录"
+SVC->>SVC : "计算绩效奖金 = 基数×(得分/100)×系数"
+SVC->>DB : "插入工资记录(total_salary=基本工资+奖金)"
+DB-->>SVC : "返回工资记录"
+SVC-->>API : "返回工资记录ID"
+API-->>FE : "生成成功"
+```
+
+图表来源
+- [salary.py](file://backend/app/api/v1/salary.py#L96-L111)
+- [salary_service.py](file://backend/app/services/salary_service.py#L127-L191)
+- [models.py](file://backend/app/models/models.py#L88-L115)
+- [models.py](file://backend/app/models/models.py#L149-L178)
+
+### 典型使用场景
+- 人员管理：新增/编辑/删除员工，按科室、状态、关键词筛选，分页展示。
+- 考核分配：为员工生成考核任务，记录考核结果与状态流转。
+- 工资计算：根据考核结果与员工基本信息，自动生成工资记录，支持批量生成与确认。
+
+章节来源
+- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [salary.py](file://backend/app/api/v1/salary.py#L20-L156)
+- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
+- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
+
+### 索引设计与数据完整性约束
+- 员工表索引
+  - idx_staff_dept：加速按科室查询；
+  - idx_staff_status：加速按状态查询。
+- 员工表约束
+  - 唯一约束：employee_id；
+  - 外键约束：department_id 引用 departments.id。
+- 迁移脚本与文档一致，确保索引与约束在数据库中正确创建。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L111-L114)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
+- [database.md](file://docs/database.md#L117-L136)
+
+## 依赖分析
+- 模型层依赖SQLAlchemy ORM定义实体与关系；
+- 服务层依赖模型层进行数据访问与业务计算；
+- API层依赖服务层与数据模式进行请求处理与响应构造；
+- 前端页面依赖API层进行数据交互。
+
+```mermaid
+graph LR
+FE["Staff.vue"] --> API["staff.py"]
+API --> SVC["staff_service.py"]
+SVC --> MODELS["models.py"]
+API --> SCH["schemas.py"]
+SAL_FE["工资API调用"] --> SAL_API["salary.py"]
+SAL_API --> SAL_SVC["salary_service.py"]
+SAL_SVC --> MODELS
+```
+
+图表来源
+- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [models.py](file://backend/app/models/models.py#L88-L115)
+- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
+- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
+
+章节来源
+- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [models.py](file://backend/app/models/models.py#L88-L115)
+- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
+- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
+
+## 性能考虑
+- 查询优化：利用idx_staff_dept与idx_staff_status索引，避免全表扫描；
+- 分页与排序：服务层对列表查询进行分页与排序，减轻前端压力；
+- 关联查询：使用selectinload按需加载关联数据，避免N+1查询问题；
+- 批量操作：工资模块提供批量生成与批量确认，提升大规模数据处理效率。
+
+章节来源
+- [staff_service.py](file://backend/app/services/staff_service.py#L26-L49)
+- [salary_service.py](file://backend/app/services/salary_service.py#L32-L58)
+- [salary_service.py](file://backend/app/services/salary_service.py#L193-L219)
+
+## 故障排查指南
+- 工号重复：创建员工时若工号已存在，接口会返回错误；
+- 员工不存在：更新或删除员工时若找不到对应记录，接口会返回错误；
+- 考核未确认：根据考核生成工资时，要求考核状态为已确认，否则无法生成；
+- 状态限制：更新工资记录时仅允许对“待确认”状态进行修改；
+- 权限限制：创建、更新、删除员工与生成/确认工资均需管理员或经理权限。
+
+章节来源
+- [staff.py](file://backend/app/api/v1/staff.py#L75-L81)
+- [staff_service.py](file://backend/app/services/staff_service.py#L79-L91)
+- [salary.py](file://backend/app/api/v1/salary.py#L104-L110)
+- [salary_service.py](file://backend/app/services/salary_service.py#L104-L124)
+- [salary_service.py](file://backend/app/services/salary_service.py#L222-L231)
+
+## 结论
+员工信息表是医院绩效系统的基础数据之一，承载着人员管理、考核与工资核算的关键信息。通过合理的字段设计、状态枚举与索引策略，以及完善的前后端协作，能够有效支撑系统的高效运行与业务闭环。
+
+## 附录
+- 员工状态枚举值对照
+  - active：在职
+  - leave：休假
+  - resigned：离职
+  - retired：退休
+- 绩效系数范围：默认1.0，最大不超过5.0，前端输入也做了相应限制。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L37-L43)
+- [schemas.py](file://backend/app/schemas/schemas.py#L117)
+- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L111-L113)
--- a/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/工资核算记录表.md
+++ b/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/工资核算记录表.md
@@ -0,0 +1,382 @@
+# 工资核算记录表
+
+<cite>
+**本文档引用的文件**
+- [models.py](file://backend/app/models/models.py)
+- [salary_service.py](file://backend/app/services/salary_service.py)
+- [salary.py](file://backend/app/api/v1/salary.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py)
+- [Salary.vue](file://frontend/src/views/salary/Salary.vue)
+- [init_db.py](file://backend/init_db.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+工资核算记录表（salary_records）是医院绩效管理系统中的核心数据表，用于记录和管理员工的工资核算信息。该表通过与员工信息表（staff）、考核记录表（assessments）等关键表的关联，实现了从绩效考核到工资发放的完整业务流程。
+
+本表支持按月度周期进行工资核算，包含基本工资、绩效奖金、补贴、扣款等多个维度的工资构成要素，并通过状态字段实现了工资记录的生命周期管理。
+
+## 项目结构
+
+工资核算记录表在系统中的位置和作用如下：
+
+```mermaid
+graph TB
+subgraph "数据模型层"
+SR[SalaryRecord<br/>工资核算记录表]
+ST[Staff<br/>员工信息表]
+AS[Assessment<br/>考核记录表]
+end
+subgraph "服务层"
+SS[SalaryService<br/>工资核算服务]
+end
+subgraph "API层"
+API[Salary API<br/>工资核算接口]
+end
+subgraph "前端界面"
+UI[Salary.vue<br/>工资管理界面]
+end
+ST --> SR
+AS --> SS
+SS --> SR
+SS --> API
+API --> UI
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L205-L230)
+- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
+- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L205-L230)
+- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
+
+## 核心组件
+
+### 数据模型定义
+
+工资核算记录表采用SQLAlchemy ORM映射，具有以下核心特性：
+
+- **主键标识**：自增整数ID作为唯一标识符
+- **外键关联**：关联到员工信息表（staff_id）
+- **索引优化**：针对员工ID和工资周期建立复合索引
+- **数据精度**：使用Numeric类型确保财务数据的精确性
+
+### 字段详细说明
+
+| 字段名 | 数据类型 | 默认值 | 业务含义 | 精度要求 |
+|--------|----------|--------|----------|----------|
+| id | Integer | 自增 | 工资记录唯一标识 | 无 |
+| staff_id | Integer | 无 | 员工ID | 外键约束 |
+| period_year | Integer | 无 | 年度 | 无 |
+| period_month | Integer | 无 | 月份 | 1-12 |
+| base_salary | Numeric(10,2) | 0.00 | 基本工资 | 精确到分 |
+| performance_score | Numeric(5,2) | 0.00 | 绩效得分 | 0-100分 |
+| performance_bonus | Numeric(10,2) | 0.00 | 绩效奖金 | 精确到分 |
+| deduction | Numeric(10,2) | 0.00 | 扣款 | 精确到分 |
+| allowance | 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 | 当前时间 | 更新时间 | 时间戳 |
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L205-L230)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
+
+## 架构概览
+
+工资核算系统的整体架构采用分层设计，确保了业务逻辑的清晰分离和数据的一致性：
+
+```mermaid
+sequenceDiagram
+participant UI as 前端界面
+participant API as API接口
+participant Service as 服务层
+participant Model as 数据模型
+participant DB as 数据库
+UI->>API : 查询工资记录
+API->>Service : get_list()
+Service->>Model : 查询SalaryRecord
+Model->>DB : 执行SQL查询
+DB-->>Model : 返回结果集
+Model-->>Service : SalaryRecord对象
+Service-->>API : 处理后的数据
+API-->>UI : 响应结果
+Note over UI,DB : 异步数据库操作
+```
+
+**图表来源**
+- [salary.py](file://backend/app/api/v1/salary.py#L20-L51)
+- [salary_service.py](file://backend/app/services/salary_service.py#L21-L58)
+
+**章节来源**
+- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
+
+## 详细组件分析
+
+### 工资计算公式
+
+工资核算的核心计算逻辑遵循以下公式：
+
+```
+应发工资 = 基本工资 + 绩效奖金 + 补贴 - 扣款
+```
+
+其中，绩效奖金的计算采用以下公式：
+
+```
+绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数
+```
+
+系统中预设的绩效基数为3000.0元，这一数值可以根据医院的实际情况进行调整。
+
+### 状态管理机制
+
+工资记录的状态流转遵循严格的业务规则：
+
+```mermaid
+stateDiagram-v2
+[*] --> 待确认
+待确认 --> 已确认 : 确认操作
+已确认 --> 待确认 : 状态重置不支持
+note right of 待确认
+新创建的工资记录默认状态
+可进行编辑和确认
+end note
+note right of 已确认
+已确认的工资记录
+不允许再次编辑
+end note
+```
+
+**图表来源**
+- [salary_service.py](file://backend/app/services/salary_service.py#L222-L231)
+- [salary_service.py](file://backend/app/services/salary_service.py#L234-L259)
+
+### 业务流程详解
+
+#### 单个工资记录生成流程
+
+```mermaid
+flowchart TD
+Start([开始]) --> GetAssessment["获取考核记录"]
+GetAssessment --> CheckAssessment{"是否存在已确认的<br/>考核记录？"}
+CheckAssessment --> |否| ReturnNull["返回空值"]
+CheckAssessment --> |是| CheckExist["检查是否已存在<br/>工资记录"]
+CheckExist --> |已存在| ReturnNull
+CheckExist --> |不存在| CalcBonus["计算绩效奖金"]
+CalcBonus --> CalcTotal["计算应发工资"]
+CalcTotal --> CreateRecord["创建工资记录"]
+CreateRecord --> SetPending["设置状态为待确认"]
+SetPending --> End([结束])
+ReturnNull --> End
+```
+
+**图表来源**
+- [salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
+
+#### 批量工资生成流程
+
+```mermaid
+sequenceDiagram
+participant Manager as 管理员
+participant API as 批量生成接口
+participant Service as 服务层
+participant DB as 数据库
+Manager->>API : 请求批量生成
+API->>Service : batch_generate_for_department()
+Service->>DB : 查询已确认考核记录
+DB-->>Service : 考核记录列表
+Service->>Service : 逐条生成工资记录
+Service->>DB : 批量插入工资记录
+DB-->>Service : 插入结果
+Service-->>API : 返回生成统计
+API-->>Manager : 显示生成结果
+```
+
+**图表来源**
+- [salary_service.py](file://backend/app/services/salary_service.py#L193-L219)
+
+**章节来源**
+- [salary_service.py](file://backend/app/services/salary_service.py#L71-L190)
+
+### 数据一致性保证
+
+系统通过多种机制确保数据的一致性和完整性：
+
+#### 数据验证机制
+- **前端验证**：使用Element Plus组件进行输入验证
+- **后端验证**：Pydantic模型进行数据格式和范围验证
+- **数据库约束**：Numeric类型确保财务数据精度
+
+#### 事务处理
+- **异步事务**：使用SQLAlchemy异步会话确保操作原子性
+- **批量操作**：支持批量生成和批量确认操作
+- **错误回滚**：异常情况下自动回滚事务
+
+#### 并发控制策略
+
+```mermaid
+flowchart TD
+Request[并发请求] --> CheckStatus{"检查记录状态"}
+CheckStatus --> |待确认| Proceed[执行操作]
+CheckStatus --> |已确认| Reject[拒绝操作]
+Proceed --> UpdateDB[更新数据库]
+UpdateDB --> Commit[提交事务]
+Reject --> ErrorResp[返回错误]
+Commit --> Success[操作成功]
+```
+
+**图表来源**
+- [salary_service.py](file://backend/app/services/salary_service.py#L104-L124)
+- [salary_service.py](file://backend/app/services/salary_service.py#L222-L231)
+
+**章节来源**
+- [salary_service.py](file://backend/app/services/salary_service.py#L104-L124)
+- [salary_service.py](file://backend/app/services/salary_service.py#L222-L231)
+
+## 依赖关系分析
+
+### 数据模型依赖
+
+```mermaid
+classDiagram
+class SalaryRecord {
+int id
+int staff_id
+int period_year
+int period_month
+float base_salary
+float performance_score
+float performance_bonus
+float deduction
+float allowance
+float total_salary
+string status
+datetime created_at
+datetime updated_at
+staff : Staff
+}
+class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+string title
+float base_salary
+float performance_ratio
+StaffStatus status
+datetime hire_date
+SalaryRecord[] salary_records
+}
+class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+float total_score
+float weighted_score
+AssessmentStatus status
+datetime created_at
+datetime updated_at
+}
+SalaryRecord --> Staff : "外键关联"
+Staff --> SalaryRecord : "一对多关系"
+Assessment --> Staff : "外键关联"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L88-L114)
+- [models.py](file://backend/app/models/models.py#L205-L230)
+
+### 服务层依赖
+
+```mermaid
+graph LR
+API[Salary API] --> Service[SalaryService]
+Service --> Model[SalaryRecord模型]
+Service --> StaffModel[Staff模型]
+Service --> AssessmentModel[Assessment模型]
+Service --> Schema[SalaryRecordSchema]
+```
+
+**图表来源**
+- [salary.py](file://backend/app/api/v1/salary.py#L14-L15)
+- [salary_service.py](file://backend/app/services/salary_service.py#L10-L11)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L205-L230)
+- [salary_service.py](file://backend/app/services/salary_service.py#L10-L11)
+
+## 性能考虑
+
+### 查询优化
+
+系统通过以下索引优化查询性能：
+- **员工索引**：`idx_salary_staff` - 加速按员工查询
+- **周期索引**：`idx_salary_period` - 加速按年月查询
+- **组合索引**：支持复杂的多条件查询
+
+### 批量操作优化
+
+- **批量生成**：支持按科室批量生成工资记录
+- **批量确认**：支持按年月批量确认工资记录
+- **分页查询**：默认每页20条记录，支持最大100条/页
+
+### 内存管理
+
+- **异步处理**：使用async/await避免阻塞
+- **流式查询**：Large result set使用流式处理
+- **连接池**：数据库连接复用减少开销
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+#### 工资记录状态错误
+**问题**：尝试编辑已确认的工资记录失败
+**原因**：状态检查机制阻止了对已确认记录的修改
+**解决方案**：先将状态重置为待确认，再进行编辑
+
+#### 绩效奖金计算异常
+**问题**：绩效奖金计算结果不正确
+**原因**：绩效基数或绩效系数设置不当
+**解决方案**：检查员工的绩效系数设置，确认绩效基数配置
+
+#### 工资记录重复生成
+**问题**：同一员工同一个月重复生成工资记录
+**原因**：系统未检测到已存在的工资记录
+**解决方案**：检查数据库中是否存在重复记录，清理后重新生成
+
+**章节来源**
+- [salary_service.py](file://backend/app/services/salary_service.py#L104-L124)
+- [salary_service.py](file://backend/app/services/salary_service.py#L155-L164)
+
+## 结论
+
+工资核算记录表作为医院绩效管理系统的核心组件，通过严谨的数据模型设计、完善的业务流程控制和可靠的技术实现，为医院的薪酬管理提供了完整的解决方案。
+
+系统的主要优势包括：
+- **完整的生命周期管理**：从生成到确认的完整状态流转
+- **灵活的计算机制**：支持多种工资构成要素的动态计算
+- **强大的扩展性**：支持批量操作和复杂查询需求
+- **严格的数据一致性**：通过多种机制确保数据的准确性和完整性
+
+通过合理使用本系统，医院可以实现绩效工资的自动化核算，提高薪酬管理的效率和准确性，为建立科学合理的绩效管理体系奠定坚实基础。
--- a/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/核心业务表.md
+++ b/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/核心业务表.md
@@ -0,0 +1,463 @@
+# 核心业务表
+
+<cite>
+**本文引用的文件**
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.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/assessments.py](file://backend/app/api/v1/assessments.py)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py)
+- [backend/init_db.py](file://backend/init_db.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件聚焦于系统核心业务表的完整结构与使用说明，覆盖以下五张表：
+- 科室信息表(departments)
+- 员工信息表(staff)
+- 考核记录表(assessments)
+- 考核明细表(assessment_details)
+- 工资核算记录表(salary_records)
+
+内容包括：字段定义（数据类型、约束、默认值、业务含义）、主键/外键关系、表间关联关系图、典型使用场景与数据流转过程、索引设计与性能考虑。
+
+## 项目结构
+后端采用FastAPI + SQLAlchemy 2.x异步ORM + PostgreSQL，模型定义位于models.py，迁移脚本由Alembic生成，服务层封装业务逻辑，API层提供REST接口。
+
+```mermaid
+graph TB
+subgraph "后端"
+A["models/models.py<br/>定义核心模型与关系"]
+B["alembic/versions/001_initial.py<br/>初始迁移脚本"]
+C["services/*<br/>业务服务层"]
+D["api/v1/*<br/>REST API"]
+E["core/database.py<br/>异步引擎与会话"]
+F["core/config.py<br/>配置项"]
+end
+A --> C
+B --> A
+C --> D
+E --> A
+F --> E
+```
+
+图表来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
+
+## 核心组件
+- 科室信息表(departments)
+  - 主键: id
+  - 外键: parent_id → departments.id（自关联，形成树形组织结构）
+  - 约束: code唯一；level默认1；is_active默认true
+  - 索引: idx_dept_type, idx_dept_parent
+- 员工信息表(staff)
+  - 主键: id
+  - 外键: department_id → departments.id
+  - 约束: employee_id唯一；status枚举；base_salary/performance_ratio默认值
+  - 索引: idx_staff_dept, idx_staff_status
+- 考核记录表(assessments)
+  - 主键: id
+  - 外键: staff_id → staff.id；assessor_id/reviewer_id → staff.id（自关联）
+  - 约束: period_year/period_month组合用于周期标识；status枚举；默认草稿
+  - 索引: idx_assessment_staff, idx_assessment_period, idx_assessment_status
+- 考核明细表(assessment_details)
+  - 主键: id
+  - 外键: assessment_id → assessments.id；indicator_id → indicators.id
+  - 约束: 默认score为0；证据与备注支持空值
+  - 索引: idx_detail_assessment, idx_detail_indicator
+- 工资核算记录表(salary_records)
+  - 主键: id
+  - 外键: staff_id → staff.id
+  - 约束: period_year/period_month组合；默认pending；total_salary为派生字段（base+bonus+allowance-deduction）
+  - 索引: idx_salary_staff, idx_salary_period
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L154)
+
+## 架构总览
+核心业务表围绕“科室-员工-考核-工资”主线展开，形成如下关系：
+
+```mermaid
+erDiagram
+DEPARTMENTS {
+int id PK
+string name
+string code UK
+string dept_type
+int parent_id FK
+int level
+int sort_order
+boolean is_active
+text description
+datetime created_at
+datetime updated_at
+}
+STAFF {
+int id PK
+string employee_id UK
+string name
+int department_id FK
+string position
+string title
+string phone
+string email
+numeric base_salary
+numeric performance_ratio
+string status
+datetime hire_date
+datetime created_at
+datetime updated_at
+}
+ASSESSMENTS {
+int id PK
+int staff_id FK
+int period_year
+int period_month
+string period_type
+numeric total_score
+numeric weighted_score
+string status
+int assessor_id FK
+int reviewer_id FK
+datetime submit_time
+datetime review_time
+text remark
+datetime created_at
+datetime updated_at
+}
+ASSESSMENT_DETAILS {
+int id PK
+int assessment_id FK
+int indicator_id FK
+numeric actual_value
+numeric score
+text evidence
+text remark
+datetime created_at
+datetime updated_at
+}
+SALARY_RECORDS {
+int id PK
+int staff_id FK
+int period_year
+int period_month
+numeric base_salary
+numeric performance_score
+numeric performance_bonus
+numeric deduction
+numeric allowance
+numeric total_salary
+string status
+text remark
+datetime created_at
+datetime updated_at
+}
+DEPARTMENTS ||--o{ STAFF : "拥有"
+STAFF ||--o{ ASSESSMENTS : "产生"
+STAFF ||--o{ SALARY_RECORDS : "对应"
+ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "包含"
+ASSESSMENTS }o--|| STAFF : "被考核者"
+ASSESSMENTS }o--|| STAFF : "考核人/审核人(自关联)"
+```
+
+图表来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L154)
+
+## 详细组件分析
+
+### 科室信息表(departments)
+- 字段与约束
+  - id: 主键，自增
+  - name: 非空，科室名称
+  - code: 非空且唯一，科室编码
+  - dept_type: 非空，枚举类型（含临床、医技、护理、行政、财务、后勤等）
+  - parent_id: 可空，指向自身id，支持树形层级
+  - level: 默认1，层级
+  - sort_order: 默认0，排序
+  - is_active: 默认true，是否启用
+  - description: 描述
+  - created_at/updated_at: 时间戳
+- 关系
+  - 自关联父子关系（一对多）
+  - 与staff一对多（反向backref: children）
+- 典型使用场景
+  - 获取科室树形结构（API: GET /api/v1/departments/tree）
+  - 列表查询与筛选（API: GET /api/v1/departments）
+  - 新建/更新/删除（需管理员或经理权限）
+- 索引
+  - idx_dept_type：按类型过滤
+  - idx_dept_parent：树形查询与层级遍历
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L41)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L51)
+
+### 员工信息表(staff)
+- 字段与约束
+  - id: 主键，自增
+  - employee_id: 非空且唯一，工号
+  - name: 非空，姓名
+  - department_id: 非空，外键→departments.id
+  - position/title/phone/email: 基本信息
+  - base_salary: 默认0，基本工资
+  - performance_ratio: 默认1.0，绩效系数
+  - status: 枚举，默认active
+  - hire_date: 入职日期
+  - created_at/updated_at: 时间戳
+- 关系
+  - belongs_to: department（一对一反向：department.staff）
+  - has_many: assessments（按staff_id反向）
+  - has_many: salary_records（按staff_id反向）
+- 典型使用场景
+  - 查询某科室员工列表（API: GET /api/v1/staff/department/{department_id}）
+  - 列表与筛选（API: GET /api/v1/staff）
+  - 新建/更新/删除（需管理员或经理权限）
+- 索引
+  - idx_staff_dept：按科室过滤
+  - idx_staff_status：按状态过滤
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L115)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+
+### 考核记录表(assessments)
+- 字段与约束
+  - id: 主键，自增
+  - staff_id: 非空，外键→staff.id
+  - period_year/month: 非空，周期标识
+  - period_type: 默认monthly
+  - total_score/weighted_score: 数值型，默认0
+  - status: 枚举，默认draft
+  - assessor_id/reviewer_id: 外键→staff.id（自关联）
+  - submit_time/review_time: 审核流程时间
+  - remark: 备注
+  - created_at/updated_at: 时间戳
+- 关系
+  - belongs_to: staff（正向），反向：staff.assessments
+  - belongs_to: staff（assessor/reviewer，自关联）
+  - has_many: details（AssessmentDetail，级联删除）
+- 典型使用场景
+  - 列表与筛选（API: GET /api/v1/assessments）
+  - 详情（带指标名称回填）
+  - 提交/审核/确认（API: POST /{id}/submit, /{id}/review, /{id}/finalize）
+  - 批量创建（按科室与指标集合）
+- 索引
+  - idx_assessment_staff：按员工过滤
+  - idx_assessment_period：按年月周期过滤
+  - idx_assessment_status：按状态过滤
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L179)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L87-L113)
+- [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-L56)
+
+### 考核明细表(assessment_details)
+- 字段与约束
+  - id: 主键，自增
+  - assessment_id: 非空，外键→assessments.id
+  - indicator_id: 非空，外键→indicators.id
+  - actual_value: 实际值
+  - score: 默认0
+  - evidence/remark: 佐证材料与备注
+  - created_at/updated_at: 时间戳
+- 关系
+  - belongs_to: assessment（反向：details）
+  - belongs_to: indicator（反向：assessment_details）
+- 典型使用场景
+  - 创建/更新考核时批量写入明细
+  - 读取详情时携带指标名称
+- 索引
+  - idx_detail_assessment：按考核记录过滤
+  - idx_detail_indicator：按指标过滤
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L181-L203)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L132)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L71-L109)
+
+### 工资核算记录表(salary_records)
+- 字段与约束
+  - id: 主键，自增
+  - staff_id: 非空，外键→staff.id
+  - period_year/month: 非空，周期标识
+  - base_salary/performance_score/performance_bonus/deduction/allowance: 数值型，默认0
+  - total_salary: 默认0，派生字段（base+bonus+allowance−deduction）
+  - status: 默认pending
+  - remark: 备注
+  - created_at/updated_at: 时间戳
+- 关系
+  - belongs_to: staff（反向：salary_records）
+- 典型使用场景
+  - 列表与筛选（API: GET /api/v1/salary）
+  - 详情（带员工与科室名称）
+  - 从已确认考核生成工资（API: POST /generate）
+  - 批量生成/确认
+- 索引
+  - idx_salary_staff：按员工过滤
+  - idx_salary_period：按年月周期过滤
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
+- [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#L21-L59)
+
+## 依赖分析
+- 数据库连接与引擎
+  - 使用异步SQLAlchemy引擎与会话工厂，PostgreSQL驱动
+- 迁移与建表
+  - 初始迁移脚本创建上述五张核心表，并建立相应索引
+- 服务层依赖
+  - AssessmentService与SalaryService分别封装考核与工资的业务逻辑
+- API层依赖
+  - 各API路由调用对应服务层方法，返回标准化响应
+
+```mermaid
+graph LR
+CFG["config.py<br/>DATABASE_URL等配置"] --> DB["database.py<br/>异步引擎/会话"]
+DB --> MODELS["models.py<br/>核心模型"]
+MIG["001_initial.py<br/>迁移脚本"] --> MODELS
+MODELS --> SVC_ASSESS["assessment_service.py"]
+MODELS --> SVC_SALARY["salary_service.py"]
+SVC_ASSESS --> API_ASSESS["assessments.py"]
+SVC_SALARY --> API_SALARY["salary.py"]
+API_DEPT["departments.py"] --> SVC_ASSESS
+API_STAFF["staff.py"] --> SVC_SALARY
+```
+
+图表来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
+- [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/assessments.py](file://backend/app/api/v1/assessments.py#L17-L166)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L17-L156)
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
+- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
+- [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/assessments.py](file://backend/app/api/v1/assessments.py#L17-L166)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L17-L156)
+
+## 性能考量
+- 索引策略
+  - departments：按dept_type与parent_id建立索引，支撑类型筛选与树形查询
+  - staff：按department_id与status建立索引，支撑科室与状态过滤
+  - assessments：按staff_id、period_year+period_month、status建立索引，支撑员工周期与状态查询
+  - assessment_details：按assessment_id与indicator_id建立索引，支撑明细查询
+  - salary_records：按staff_id与period_year+period_month建立索引，支撑员工周期查询
+- 数据类型选择
+  - 数值型采用numeric(precision, scale)，确保财务与评分精度
+  - 日期时间统一使用DateTime，便于排序与范围查询
+- 查询优化建议
+  - 列表查询尽量结合索引列过滤（如period、status、dept_id）
+  - 使用selectinload或joinedload减少N+1查询（服务层已示范）
+  - 批量操作使用flush/commit合并事务，降低往返开销
+- 并发与连接池
+  - 通过配置项设置连接池大小与溢出，避免高并发下的连接争用
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L111-L114)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L174-L178)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L199-L202)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L227-L230)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
+
+## 故障排查指南
+- 数据库连接问题
+  - 检查DATABASE_URL、数据库是否存在、凭据是否正确
+  - 参考：[QWEN.md](file://QWEN.md#L535-L540)
+- 迁移失败
+  - 查看迁移状态与历史，必要时降级再升级
+  - 参考：[QWEN.md](file://QWEN.md#L541-L552)
+- 重复唯一键
+  - 科室编码重复：departments.code唯一
+  - 员工工号重复：staff.employee_id唯一
+  - 参考：API层在创建时进行存在性检查
+- 业务状态限制
+  - 考核仅允许在草稿或驳回状态下更新
+  - 工资仅允许在pending状态下更新
+  - 参考：服务层状态判断逻辑
+- 初始化数据
+  - 可运行初始化脚本创建默认科室、员工、指标与管理员账户
+  - 参考：[init_db.py](file://backend/init_db.py#L11-L83)
+
+章节来源
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L74-L78)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L75-L79)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L117-L119)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L107-L108)
+- [backend/init_db.py](file://backend/init_db.py#L11-L83)
+- [QWEN.md](file://QWEN.md#L535-L552)
+
+## 结论
+本文系统梳理了核心业务表的结构、关系与使用方式，明确了索引设计与性能要点，并提供了常见问题的排查路径。基于该模型，系统实现了从“科室组织—员工—考核—工资”的闭环管理，满足医院绩效管理的关键需求。
+
+## 附录
+- 数据流转示例（从考核到工资）
+  - 考核流程：创建→提交→审核→确认（状态变更）
+  - 工资生成：根据已确认考核与员工绩效系数计算绩效奖金，生成工资记录
+  - 确认发放：批量或单条确认，进入待发放状态
+
+```mermaid
+sequenceDiagram
+participant API as "API 层"
+participant SvcAssess as "AssessmentService"
+participant SvcSalary as "SalaryService"
+participant DB as "数据库"
+API->>SvcAssess : "创建/提交/审核/确认 考核"
+SvcAssess->>DB : "写入assessments与assessment_details"
+API->>SvcSalary : "根据staff_id+period生成工资"
+SvcSalary->>DB : "读取staff与finalized assessment"
+SvcSalary->>SvcSalary : "计算绩效奖金与总工资"
+SvcSalary->>DB : "写入salary_records"
+API->>SvcSalary : "确认工资"
+SvcSalary->>DB : "更新status=pending→confirmed"
+```
+
+图表来源
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L80-L146)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L143)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L71-L206)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L231)
--- a/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/科室信息表.md
+++ b/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/科室信息表.md
@@ -0,0 +1,402 @@
+# 科室信息表
+
+<cite>
+**本文档引用的文件**
+- [models.py](file://backend/app/models/models.py)
+- [departments.py](file://backend/app/api/v1/departments.py)
+- [department_service.py](file://backend/app/services/department_service.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py)
+- [Departments.vue](file://frontend/src/views/basic/Departments.vue)
+- [database.md](file://docs/database.md)
+- [api.md](file://docs/api.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+科室信息表是医院绩效管理系统中的核心基础数据表，用于存储医院各个科室的基本信息和组织架构关系。该表实现了完整的树形结构管理，支持多层级的科室组织关系，并为绩效考核、员工管理、财务核算等功能提供基础数据支撑。
+
+## 项目结构
+
+科室信息表在项目中的位置和相关组件分布如下：
+
+```mermaid
+graph TB
+subgraph "后端架构"
+A[models.py<br/>数据模型定义]
+B[department_service.py<br/>业务逻辑层]
+C[departments.py<br/>API路由层]
+D[schemas.py<br/>数据模式定义]
+end
+subgraph "前端界面"
+E[Departments.vue<br/>科室管理界面]
+end
+subgraph "数据库"
+F[departments表<br/>实际数据存储]
+G[idx_dept_type<br/>类型索引]
+H[idx_dept_parent<br/>父级索引]
+end
+A --> B
+B --> C
+C --> E
+A --> F
+F --> G
+F --> H
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L62-L85)
+- [department_service.py](file://backend/app/services/department_service.py#L13-L150)
+- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L62-L85)
+- [department_service.py](file://backend/app/services/department_service.py#L13-L150)
+- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+
+## 核心组件
+
+### 数据模型定义
+
+科室信息表采用SQLAlchemy ORM映射，定义了完整的字段结构和约束条件：
+
+| 字段名 | 类型 | 约束 | 说明 |
+|--------|------|------|------|
+| id | Integer | 主键, 自增 | 科室唯一标识符 |
+| name | String(100) | 非空 | 科室名称 |
+| code | String(20) | 唯一, 非空 | 科室编码，全局唯一 |
+| dept_type | Enum | 非空 | 科室类型枚举 |
+| parent_id | Integer | 外键 | 上级科室ID，自关联 |
+| level | Integer | 默认1 | 层级深度，从1开始 |
+| sort_order | Integer | 默认0 | 排序权重 |
+| is_active | Boolean | 默认True | 是否启用状态 |
+| description | Text | 可空 | 科室描述信息 |
+| created_at | DateTime | 默认当前时间 | 创建时间戳 |
+| updated_at | DateTime | 默认当前时间 | 更新时间戳 |
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L62-L85)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L23-L40)
+
+### 科室类型枚举
+
+系统定义了9种科室类型，每种类型都有明确的业务含义：
+
+```mermaid
+graph TD
+A[科室类型枚举] --> B[临床科室]
+A --> C[医技科室]
+A --> D[医辅科室]
+A --> E[护理单元]
+A --> F[行政科室]
+A --> G[财务科室]
+A --> H[后勤保障科室]
+B --> B1[手术临床科室]
+B --> B2[非手术有病房科室]
+B --> B3[非手术无病房科室]
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L16-L26)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L16-L26)
+- [schemas.py](file://backend/app/schemas/schemas.py#L12-L22)
+
+## 架构概览
+
+科室信息表的完整架构包括数据模型、业务逻辑、API接口和前端界面四个层次：
+
+```mermaid
+sequenceDiagram
+participant UI as 前端界面
+participant API as API层
+participant Service as 业务服务层
+participant Model as 数据模型层
+participant DB as 数据库
+UI->>API : GET /departments/tree
+API->>Service : get_tree()
+Service->>Model : 查询所有科室
+Model->>DB : SELECT * FROM departments
+DB-->>Model : 科室数据
+Model-->>Service : Department对象列表
+Service->>Service : 构建树形结构
+Service-->>API : DepartmentTree列表
+API-->>UI : 树形数据
+Note over UI,DB : 树形结构构建过程
+```
+
+**图表来源**
+- [departments.py](file://backend/app/api/v1/departments.py#L43-L51)
+- [department_service.py](file://backend/app/services/department_service.py#L113-L149)
+
+**章节来源**
+- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+- [department_service.py](file://backend/app/services/department_service.py#L113-L149)
+
+## 详细组件分析
+
+### 数据模型类分析
+
+```mermaid
+classDiagram
+class Department {
+int id
+string name
+string code
+DeptType dept_type
+int parent_id
+int level
+int sort_order
+bool is_active
+string description
+datetime created_at
+datetime updated_at
+Department parent
+Staff[] staff
+}
+class DeptType {
+<<enumeration>>
+CLINICAL_SURGICAL
+CLINICAL_NONSURGICAL_WARD
+CLINICAL_NONSURGICAL_NOWARD
+MEDICAL_TECH
+MEDICAL_AUXILIARY
+NURSING
+ADMIN
+FINANCE
+LOGISTICS
+}
+class DepartmentService {
+get_list() Department[]
+get_by_id(int) Department
+get_by_code(string) Department
+create(DepartmentCreate) Department
+update(int, DepartmentUpdate) Department
+delete(int) bool
+get_tree() DepartmentTree[]
+}
+Department --> DeptType : 使用
+DepartmentService --> Department : 操作
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L62-L85)
+- [models.py](file://backend/app/models/models.py#L16-L26)
+- [department_service.py](file://backend/app/services/department_service.py#L13-L150)
+
+### 树形结构实现机制
+
+系统通过自关联外键实现树形结构，核心实现逻辑如下：
+
+```mermaid
+flowchart TD
+A[获取所有科室] --> B[创建ID映射表]
+B --> C[初始化树节点]
+C --> D[遍历所有科室]
+D --> E{是否存在父节点?}
+E --> |是| F[添加到父节点children]
+E --> |否| G[添加到根节点列表]
+F --> H[继续下一个科室]
+G --> H
+H --> I[返回根节点列表]
+```
+
+**图表来源**
+- [department_service.py](file://backend/app/services/department_service.py#L124-L149)
+
+**章节来源**
+- [department_service.py](file://backend/app/services/department_service.py#L113-L149)
+
+### 层级计算机制
+
+层级计算采用递归继承的方式，确保树形结构的完整性：
+
+```mermaid
+flowchart TD
+A[创建新科室] --> B[检查parent_id是否存在]
+B --> |存在| C[查询父科室]
+C --> D[level = parent.level + 1]
+B --> |不存在| E[level = 1]
+D --> F[保存科室记录]
+E --> F
+F --> G[返回新科室]
+```
+
+**图表来源**
+- [department_service.py](file://backend/app/services/department_service.py#L62-L78)
+
+**章节来源**
+- [department_service.py](file://backend/app/services/department_service.py#L62-L78)
+
+### API接口设计
+
+系统提供了完整的CRUD接口，支持多种查询和操作场景：
+
+| 接口 | 方法 | 路径 | 功能描述 |
+|------|------|------|----------|
+| 获取科室列表 | GET | /departments | 分页获取科室列表，支持过滤和排序 |
+| 获取科室树 | GET | /departments/tree | 获取完整的树形结构 |
+| 获取科室详情 | GET | /departments/{id} | 根据ID获取科室详情 |
+| 创建科室 | POST | /departments | 创建新的科室记录 |
+| 更新科室 | PUT | /departments/{id} | 更新现有科室信息 |
+| 删除科室 | DELETE | /departments/{id} | 删除指定科室（带安全检查） |
+
+**章节来源**
+- [departments.py](file://backend/app/api/v1/departments.py#L20-L107)
+- [api.md](file://docs/api.md#L80-L131)
+
+### 前端集成实现
+
+前端界面提供了完整的科室管理功能，包括：
+
+- **数据展示**：表格形式展示科室基本信息
+- **树形选择**：使用el-tree-select实现上级科室选择
+- **类型标签**：不同科室类型显示不同颜色标签
+- **状态管理**：支持启用/停用状态切换
+- **权限控制**：仅管理员和经理可以进行CRUD操作
+
+**章节来源**
+- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L1-L290)
+
+## 依赖关系分析
+
+### 数据库索引设计
+
+科室信息表采用了合理的索引策略来优化查询性能：
+
+```mermaid
+graph LR
+A[departments表] --> B[idx_dept_type]
+A --> C[idx_dept_parent]
+A --> D[idx_code_unique]
+B --> E[类型查询优化]
+C --> F[父子关系查询优化]
+D --> G[编码唯一性保证]
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L82-L85)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L39-L40)
+
+### 外部依赖关系
+
+```mermaid
+graph TB
+subgraph "外部依赖"
+A[SQLAlchemy ORM]
+B[FastAPI框架]
+C[Element UI]
+D[PostgreSQL数据库]
+end
+subgraph "内部模块"
+E[models.py]
+F[department_service.py]
+G[departments.py]
+H[schemas.py]
+end
+A --> E
+B --> G
+C --> I[Departments.vue]
+D --> E
+E --> F
+F --> G
+G --> I
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L1-L13)
+- [departments.py](file://backend/app/api/v1/departments.py#L4-L15)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L1-L13)
+- [departments.py](file://backend/app/api/v1/departments.py#L4-L15)
+
+## 性能考虑
+
+### 查询优化策略
+
+1. **索引优化**
+   - `idx_dept_type`：优化按科室类型查询
+   - `idx_dept_parent`：优化树形结构查询
+   - `unique(code)`：确保编码唯一性，支持快速查找
+
+2. **查询模式优化**
+   - 使用`ORDER BY sort_order, id`确保稳定排序
+   - 分页查询避免一次性加载大量数据
+   - 树形结构构建时使用内存映射减少数据库访问
+
+3. **缓存策略**
+   - 树形结构结果可以考虑缓存
+   - 常用查询结果可以使用Redis缓存
+
+### 数据一致性保证
+
+- **事务处理**：所有CRUD操作都在事务中执行
+- **约束检查**：删除操作前检查是否有子科室
+- **并发控制**：使用数据库锁防止并发冲突
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+1. **科室编码重复**
+   - 现象：创建科室时报错"科室编码已存在"
+   - 解决：检查是否存在重复的编码，确保唯一性
+
+2. **树形结构异常**
+   - 现象：科室树显示不正确或出现循环引用
+   - 解决：检查parent_id字段，确保没有自引用或循环引用
+
+3. **删除失败**
+   - 现象：删除科室时报错"无法删除，科室下存在子科室"
+   - 解决：先删除子科室，再删除父科室
+
+4. **层级计算错误**
+   - 现象：新创建科室层级不正确
+   - 解决：检查父科室是否存在，确保正确计算level
+
+**章节来源**
+- [departments.py](file://backend/app/api/v1/departments.py#L74-L77)
+- [department_service.py](file://backend/app/services/department_service.py#L96-L110)
+
+### 调试技巧
+
+1. **数据库层面调试**
+   ```sql
+   -- 查看所有科室及其层级关系
+   SELECT id, name, code, parent_id, level FROM departments ORDER BY level, sort_order;
+   
+   -- 检查树形结构完整性
+   SELECT parent_id, COUNT(*) as child_count 
+   FROM departments 
+   GROUP BY parent_id 
+   HAVING parent_id IS NOT NULL;
+   ```
+
+2. **API层面调试**
+   - 使用Postman测试各种接口
+   - 检查响应状态码和错误信息
+   - 验证数据格式和约束条件
+
+## 结论
+
+科室信息表作为医院绩效管理系统的基础数据表，具有以下特点：
+
+1. **完整的树形结构**：支持多层级的科室组织关系
+2. **灵活的类型管理**：涵盖医院各类科室类型
+3. **完善的权限控制**：基于角色的CRUD权限管理
+4. **良好的扩展性**：为后续功能扩展提供基础支撑
+
+通过合理的设计和实现，该表能够有效支撑医院的绩效管理、员工管理、财务核算等多个业务领域，为医院的数字化转型提供坚实的数据基础。
--- a/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核指标表.md
+++ b/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核指标表.md
@@ -0,0 +1,299 @@
+# 考核指标表
+
+<cite>
+**本文引用的文件**
+- [models.py](file://backend/app/models/models.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [indicators.py](file://backend/app/api/v1/indicators.py)
+- [indicator_service.py](file://backend/app/services/indicator_service.py)
+- [init_indicator_templates.py](file://backend/init_indicator_templates.py)
+- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue)
+- [详细设计.md](file://docs/详细设计.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件围绕“考核指标表（indicators）”进行系统化说明，涵盖字段的业务含义、指标类型与平衡计分卡维度的枚举值、权重约束与一票否决机制的设计原理，并结合系统中的模板初始化与前后端交互，给出典型配置场景与使用示例。
+
+## 项目结构
+- 后端采用 FastAPI + SQLAlchemy 异步 ORM，指标模型、序列化与 API 路由分别位于 models、schemas、api/v1 与 services 层。
+- 前端 Vue 页面负责指标的增删改查与状态切换。
+- 初始化脚本用于批量导入模板指标，便于快速搭建不同科室的指标库。
+
+```mermaid
+graph TB
+FE["前端页面<br/>Indicators.vue"] --> API["API 路由<br/>indicators.py"]
+API --> SVC["服务层<br/>indicator_service.py"]
+SVC --> MODEL["数据模型<br/>models.py"]
+INIT["初始化脚本<br/>init_indicator_templates.py"] --> MODEL
+```
+
+图表来源
+- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
+- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
+- [models.py](file://backend/app/models/models.py#L117-L147)
+- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L1-L375)
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L117-L147)
+- [schemas.py](file://backend/app/schemas/schemas.py#L151-L193)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
+- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
+- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L1-L375)
+- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
+
+## 核心组件
+- 模型层（数据模型）：定义指标表结构、枚举类型（指标类型、BSC 维度、科室类型）、约束与索引。
+- 序列化层（Pydantic）：定义指标的请求/响应模型与字段校验规则。
+- 服务层（业务逻辑）：提供指标列表查询、启用状态筛选、创建/更新/删除、模板导入等能力。
+- API 层（接口）：暴露指标 CRUD 与模板导入接口，带权限控制。
+- 前端页面：提供指标列表展示、搜索过滤、新增/编辑/删除、状态开关等交互。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L54-L61)
+- [schemas.py](file://backend/app/schemas/schemas.py#L39-L44)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
+- [indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)
+- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L17-L118)
+
+## 架构总览
+以下类图展示指标相关的核心类与关系，以及与枚举类型的绑定。
+
+```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 IndicatorType {
+<<enum>>
+quality
+quantity
+efficiency
+service
+cost
+}
+class BSCDimension {
+<<enum>>
+financial
+customer
+internal_process
+learning_growth
+}
+class DeptType {
+<<enum>>
+clinical_surgical
+clinical_nonsurgical_ward
+clinical_nonsurgical_noward
+medical_tech
+medical_auxiliary
+nursing
+admin
+finance
+logistics
+}
+Indicator --> IndicatorType : "使用"
+Indicator --> BSCDimension : "使用"
+Indicator --> DeptType : "适用科室类型(JSON)"
+```
+
+图表来源
+- [models.py](file://backend/app/models/models.py#L54-L61)
+- [models.py](file://backend/app/models/models.py#L117-L147)
+
+## 详细组件分析
+
+### 字段业务含义与约束
+- 指标编码（code）：唯一标识指标，用于模板导入与关联，API 层在创建时会校验唯一性。
+- 指标名称（name）：指标的中文名称，用于展示与报表。
+- 指标类型（indicator_type）：质量、数量、效率、服务、成本五类，决定评分方法与目标方向。
+- 平衡计分卡维度（bs_dimension）：财务、客户、内部流程、学习与成长四个维度，用于归类与权重分配。
+- 权重（weight）：指标在所属维度内的权重，模型层包含正数约束；服务层与前端对权重范围做了进一步限制。
+- 最高分值（max_score）：指标可能获得的最高得分，用于评分换算与上限控制。
+- 目标值（target_value）与单位（target_unit）：目标值及其单位，配合评分方法使用。
+- 计算方法（calculation_method）：实际值的计算公式或口径说明。
+- 考核方法（assessment_method）：数据采集与认定方式（如统计报表、问卷调查、系统统计等）。
+- 扣分标准（deduction_standard）：针对扣分法的扣分细则，便于人工复核与申诉处理。
+- 数据来源（data_source）：数据来自哪个系统或部门，确保可追溯。
+- 适用科室类型（applicable_dept_types）：JSON 数组，限定该指标对哪些科室生效。
+- 是否一票否决（is_veto）：当指标为否决项时，若未达标直接判定考核不通过。
+- 启用状态（is_active）：控制指标是否参与当前周期的考核。
+- 创建/更新时间（created_at/updated_at）：审计与版本追踪。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L117-L147)
+- [schemas.py](file://backend/app/schemas/schemas.py#L153-L193)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L71-L112)
+- [indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)
+
+### 指标类型与平衡计分卡维度
+- 指标类型（质量、数量、效率、服务、成本）：用于区分指标性质与评分方法选择。
+- BSC 四个维度：
+  - 财务维度：关注收入、成本、结余等财务指标。
+  - 客户维度：关注患者满意度、投诉处理等客户服务指标。
+  - 内部流程维度：关注病历质量、院感控制、制度执行等内部运营指标。
+  - 学习与成长维度：关注培训参与、继续教育等能力建设指标。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L54-L61)
+- [models.py](file://backend/app/models/models.py#L29-L34)
+
+### 权重约束与一票否决机制
+- 权重约束：
+  - 数据库层：通过约束保证权重大于 0。
+  - 服务层与前端：对权重范围做了更严格的限制（如前端最小 0.1、最大 10），避免极端权重影响整体平衡。
+- 一票否决（is_veto）：
+  - 当某指标被标记为否决项时，若未达到目标，直接判定该考核记录不通过，无需计算其他指标得分。
+  - 该机制常用于安全、合规类关键指标（如院感控制达标率）。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L144-L146)
+- [schemas.py](file://backend/app/schemas/schemas.py#L158-L158)
+- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L180-L196)
+
+### API 流程与调用链
+以下序列图展示从前端到后端的关键调用链，包括创建指标与模板导入。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端页面<br/>Indicators.vue"
+participant API as "API 路由<br/>indicators.py"
+participant SVC as "服务层<br/>indicator_service.py"
+participant DB as "数据库"
+FE->>API : "POST /api/v1/indicators"
+API->>API : "校验权限与编码唯一性"
+API->>SVC : "create(indicator_data)"
+SVC->>DB : "插入新指标记录"
+DB-->>SVC : "返回持久化后的指标"
+SVC-->>API : "返回指标对象"
+API-->>FE : "返回创建成功与数据"
+FE->>API : "POST /api/v1/indicators/templates/import?overwrite=false"
+API->>SVC : "import_template(template_data, overwrite)"
+SVC->>DB : "按模板创建/更新指标"
+DB-->>SVC : "提交事务"
+SVC-->>API : "返回创建数量"
+API-->>FE : "返回导入结果"
+```
+
+图表来源
+- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L201-L273)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L71-L142)
+- [indicator_service.py](file://backend/app/services/indicator_service.py#L67-L154)
+
+### 典型配置场景与使用示例
+- 场景一：为“临床手术科室”批量导入模板指标
+  - 使用模板导入接口，传入模板数据与科室类型，系统将根据模板生成指标并设置适用科室类型。
+  - 示例字段：指标编码、名称、类型、维度、权重、最高分值、目标值、计算方法、数据来源、是否否决等。
+- 场景二：新增自定义指标
+  - 前端填写指标基本信息，后端校验编码唯一性与字段合法性，创建后可在考核中启用。
+- 场景三：启用/停用指标
+  - 前端通过开关切换 is_active，后端提供按状态筛选的列表查询接口。
+- 场景四：否决项设置
+  - 对关键安全/合规指标（如院感达标率）设置 is_veto=true，确保未达标即不通过。
+
+章节来源
+- [indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
+- [indicator_service.py](file://backend/app/services/indicator_service.py#L106-L197)
+- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L22-L375)
+- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L179-L273)
+
+### 评分方法与权重换算（概念流程）
+系统提供了多种评分方法，用于将实际值转换为得分。以下流程图展示常见方法的决策过程（概念示意）：
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> CheckVeto{"是否为否决项<br/>is_veto = true?"}
+CheckVeto --> |是| Vetofail["未达标则直接不通过"]
+CheckVeto --> |否| ChooseMethod["选择评分方法"]
+ChooseMethod --> Ratio["比值法<br/>实际值/目标值"]
+ChooseMethod --> Range["区间法<br/>趋高/趋低/趋中"]
+ChooseMethod --> Deduct["扣分法<br/>权重-扣分"]
+ChooseMethod --> Bonus["加分法<br/>权重+加分"]
+Ratio --> WeightCalc["乘以权重得到得分"]
+Range --> WeightCalc
+Deduct --> CapZero["扣完为止，不低于0"]
+Bonus --> CapMax["加分不超过权重50%"]
+WeightCalc --> End(["结束"])
+CapZero --> End
+CapMax --> End
+Vetofail --> End
+```
+
+图表来源
+- [详细设计.md](file://docs/详细设计.md#L328-L400)
+
+## 依赖关系分析
+- 模型层依赖枚举类型（IndicatorType、BSCDimension、DeptType）与 SQLAlchemy 的类型系统。
+- 服务层依赖模型层进行数据库操作，并对输入数据进行清洗与转换（如适用科室类型 JSON 序列化）。
+- API 层依赖服务层与权限中间件，提供统一的 HTTP 接口。
+- 前端依赖 API 提供的数据结构，进行表格展示与表单编辑。
+
+```mermaid
+graph LR
+ENUM["枚举类型<br/>IndicatorType/BSCDimension/DeptType"] --> MODEL["数据模型<br/>models.py"]
+MODEL --> SVC["服务层<br/>indicator_service.py"]
+SVC --> API["API 路由<br/>indicators.py"]
+API --> FE["前端页面<br/>Indicators.vue"]
+```
+
+图表来源
+- [models.py](file://backend/app/models/models.py#L54-L61)
+- [models.py](file://backend/app/models/models.py#L117-L147)
+- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
+- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
+- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
+
+## 性能考量
+- 查询性能：指标列表接口支持按类型、维度、启用状态筛选与分页，建议在高频查询场景下利用数据库索引（模型层已定义相关索引）。
+- 写入性能：模板导入采用批量写入与事务提交，减少往返开销；注意在大量导入时控制并发与内存占用。
+- 前端渲染：表格分页与按需加载有助于提升大列表的交互体验。
+
+## 故障排查指南
+- 编码重复：创建指标时若编码已存在，接口会返回错误；请更换唯一编码。
+- 权重异常：若权重小于等于 0 或超出范围，数据库约束或前端校验会拦截；请调整至有效范围。
+- 否决项判定：若某指标为否决项且未达标，需先满足该指标目标再进入后续评分。
+- 数据来源缺失：若数据源不可用，建议在计算方法与数据来源字段中明确口径与系统对接方式。
+
+章节来源
+- [indicators.py](file://backend/app/api/v1/indicators.py#L78-L84)
+- [models.py](file://backend/app/models/models.py#L144-L146)
+- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L180-L196)
+
+## 结论
+考核指标表是医院绩效管理的基础配置单元。通过明确的字段语义、严谨的权重约束与一票否决机制，系统能够支撑多维度、多科室的差异化考核需求。结合模板导入与前后端协同，可高效完成指标库的构建与维护。
+
+## 附录
+- 初始化脚本示例：展示了如何为不同科室批量创建指标模板，便于快速落地。
+- 前端页面示例：展示了指标的增删改查与状态切换，便于一线人员日常维护。
+
+章节来源
+- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L22-L375)
+- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L179-L273)
--- a/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核明细表.md
+++ b/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核明细表.md
@@ -0,0 +1,351 @@
+# 考核明细表
+
+<cite>
+**本文引用的文件**
+- [models.py](file://backend/app/models/models.py)
+- [assessment_service.py](file://backend/app/services/assessment_service.py)
+- [assessments.py](file://backend/app/api/v1/assessments.py)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue)
+- [assessment.js](file://frontend/src/api/assessment.js)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件围绕“考核明细表（assessment_details）”进行系统化说明，涵盖字段业务含义、与考核记录表（assessments）的多对一关系、与指标表（indicators）的一对一关系、得分计算逻辑、数据验证规则、典型使用场景以及索引与查询优化建议。文档同时结合后端模型定义、服务层实现、API接口与前端交互，帮助读者全面理解该表在医院绩效系统中的作用与实现细节。
+
+## 项目结构
+- 后端模型定义位于 models.py，包含 AssessmentDetail 的字段、索引与关系。
+- 服务层 assessment_service.py 实现了明细的增删改查、加权得分计算与批量初始化。
+- API 层 assessments.py 提供考核与明细的对外接口。
+- 数据库迁移脚本 001_initial.py 定义了 assessment_details 的建表语句与索引。
+- 前端 AssessmentDetail.vue 与 assessment.js 展示了明细的录入、校验与提交流程。
+
+```mermaid
+graph TB
+subgraph "后端"
+M["models.py<br/>定义 AssessmentDetail 字段/索引/关系"]
+S["assessment_service.py<br/>明细增删改/加权计算/批量初始化"]
+A["assessments.py<br/>API 接口"]
+end
+subgraph "前端"
+V["AssessmentDetail.vue<br/>明细展示/编辑/提交"]
+JS["assessment.js<br/>HTTP 请求封装"]
+end
+DB["数据库<br/>assessment_details 表"]
+V --> JS
+JS --> A
+A --> S
+S --> M
+M --> DB
+```
+
+图表来源
+- [models.py](file://backend/app/models/models.py#L181-L202)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L36-L82)
+- [assessment.js](file://frontend/src/api/assessment.js#L8-L36)
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L181-L202)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L36-L82)
+- [assessment.js](file://frontend/src/api/assessment.js#L8-L36)
+
+## 核心组件
+- 考核明细表（AssessmentDetail）
+  - 字段与业务含义：
+    - assessment_id：考核记录ID，用于将明细归集到具体考核记录，形成“明细-记录”的多对一关系。
+    - indicator_id：指标ID，用于将明细与具体指标绑定，形成“明细-指标”的一对一关系。
+    - actual_value：实际值，记录该指标的实际测量结果，支持小数点后两位精度。
+    - score：得分，记录该指标的最终得分，支持小数点后一位精度，默认为0。
+    - evidence：佐证材料，记录支撑该得分的相关证明材料（如截图、报表链接、文件名等）。
+    - remark：备注，用于记录审核意见、补充说明等。
+  - 索引与约束：
+    - idx_detail_assessment：assessment_id 上的索引，加速按考核记录查询明细。
+    - idx_detail_indicator：indicator_id 上的索引，加速按指标查询明细。
+  - 关系：
+    - 与 Assessment 多对一：每个明细属于一个考核记录。
+    - 与 Indicator 一对一：每个明细对应一个指标。
+
+- 考核记录表（Assessment）
+  - 与 AssessmentDetail 的一对多关系：一个考核记录包含多个明细项。
+  - 总分与加权得分由服务层在创建/更新时计算并写入。
+
+- 指标表（Indicator）
+  - 与 AssessmentDetail 的一对多关系：一个指标可出现在多个明细中（不同考核记录）。
+  - 服务层在计算加权得分时会读取指标权重。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L181-L202)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
+
+## 架构概览
+后端采用“模型-服务-接口-前端”分层架构：
+- 模型层：定义 AssessmentDetail 的字段、索引与关系。
+- 服务层：负责明细的创建/更新、删除旧明细、计算总分与加权得分、批量初始化。
+- 接口层：提供获取详情、创建、更新、提交、审核、确认等 API。
+- 前端：展示明细、允许编辑实际值与得分、提交审核、审核通过/驳回、确认。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端页面"
+participant API as "API 接口"
+participant SVC as "服务层"
+participant DB as "数据库"
+FE->>API : GET /assessments/{id}
+API->>SVC : get_by_id(assessment_id)
+SVC->>DB : 查询 Assessment + selectinload details + indicator
+DB-->>SVC : 返回 Assessment 及明细
+SVC-->>API : Assessment 对象
+API-->>FE : 返回详情含明细
+FE->>API : PUT /assessments/{id}更新明细
+API->>SVC : update(assessment_id, details)
+SVC->>DB : 删除旧明细按 assessment_id
+SVC->>DB : 插入新明细并计算总分/加权得分
+DB-->>SVC : 提交事务
+SVC-->>API : 返回更新后的 Assessment
+API-->>FE : 返回成功
+```
+
+图表来源
+- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L57-L156)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L160-L175)
+
+章节来源
+- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L57-L156)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L160-L175)
+
+## 详细组件分析
+
+### 字段业务含义与约束
+- assessment_id
+  - 类型：整数，外键指向 assessments.id。
+  - 业务含义：标识该明细所属的考核记录，形成“明细-记录”的多对一关系。
+  - 约束：非空；需与现有考核记录关联。
+- indicator_id
+  - 类型：整数，外键指向 indicators.id。
+  - 业务含义：标识该明细对应的指标，形成“明细-指标”的一对一关系。
+  - 约束：非空；需与现有指标关联。
+- actual_value
+  - 类型：数值（最多10位，小数点后2位），可为空。
+  - 业务含义：该指标的实际测量值，用于支撑评分或作为输入数据。
+  - 约束：可为空；服务层不强制必填。
+- score
+  - 类型：数值（最多5位，小数点后1位），默认0。
+  - 业务含义：该指标的最终得分，用于计算总分与加权得分。
+  - 约束：非负；服务层在更新时会累加总分，并按指标权重计算加权得分。
+- evidence
+  - 类型：文本，可为空。
+  - 业务含义：佐证材料，如图片、文件名、链接等，便于审计与复核。
+  - 约束：可为空。
+- remark
+  - 类型：文本，可为空。
+  - 业务含义：备注，可用于记录审核意见、调整说明等。
+  - 约束：可为空。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L181-L202)
+- [schemas.py](file://backend/app/schemas/schemas.py#L196-L218)
+
+### 关系与数据一致性
+- 与 Assessment 的多对一关系
+  - 一个考核记录可包含多个明细；删除考核记录时，明细通过级联删除（由 Assessment 的 cascade 配置决定）。
+- 与 Indicator 的一对一关系
+  - 一个指标可在多个明细中出现（不同考核记录），但单条明细仅对应一个指标。
+- 服务层在创建/更新时的处理
+  - 创建：直接插入明细，总分=sum(score)，加权得分=Σ(score × 指标权重)。
+  - 更新：先删除旧明细，再插入新明细，重新计算总分与加权得分。
+  - 批量初始化：为某个科室的每位在职员工生成相同指标集合的明细，初始得分为0。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L173-L173)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L207-L262)
+
+### 得分计算逻辑
+- 总分（Assessment.total_score）
+  - 计算方式：明细的 score 之和。
+- 加权得分（Assessment.weighted_score）
+  - 计算方式：Σ(detail.score × detail.indicator.weight)。
+  - 服务层在创建/更新时读取指标权重并累加。
+- 一票否决（Indicator.is_veto）
+  - 该字段存在于指标表，用于表示是否为一票否决指标。若存在此类指标且其得分导致不达标，可能触发整体否决流程（具体逻辑取决于业务规则与前端/服务层实现）。当前明细表未直接存储 is_veto，但服务层在计算加权得分时会读取指标权重，体现权重影响。
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> LoadDetails["加载明细列表"]
+LoadDetails --> SumScore["sum(score) 计算总分"]
+SumScore --> GetWeights["逐条读取指标权重"]
+GetWeights --> WeightedCalc["Σ(score × 指标权重) 计算加权得分"]
+WeightedCalc --> SaveAssessment["保存 Assessment.total_score 与 weighted_score"]
+SaveAssessment --> End(["结束"])
+```
+
+图表来源
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L74-L84)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L129-L149)
+
+章节来源
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
+
+### 数据验证规则
+- Pydantic 模式（后端）
+  - AssessmentDetailCreate/AssessmentDetailResponse 中对字段进行了范围与类型约束：
+    - score：默认0，最小≥0。
+    - actual_value：可为空，数值类型。
+    - evidence/remark：可为空，字符串类型。
+- SQL 约束（数据库）
+  - 字段类型与精度：numeric(10,2)/numeric(5,2) 等，确保存储精度。
+  - 非空约束：assessment_id、indicator_id 非空。
+  - 索引：assessment_id、indicator_id 上的索引，提升查询性能。
+- 前端校验（前端）
+  - 明细表格中对实际值与得分设置了输入范围与精度：
+    - actual_value：数值，精度2位。
+    - score：数值，最小0，最大为指标最高分，精度1位。
+  - 状态控制：仅草稿状态下允许编辑明细，提交后只读显示。
+
+章节来源
+- [schemas.py](file://backend/app/schemas/schemas.py#L196-L218)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L45-L70)
+
+### 典型使用场景
+- 详细评分
+  - 在前端页面中，用户可编辑 actual_value 与 score，服务层据此计算总分与加权得分。
+- 证据管理
+  - evidence 字段用于记录佐证材料，便于后续审计与复核。
+- 数据追溯
+  - 通过 assessment_id 可快速定位某次考核的所有明细；通过 indicator_id 可查看某指标在不同考核记录中的表现。
+- 批量初始化
+  - 服务层支持为某个科室的在职员工批量创建明细，初始得分为0，便于后续统一评分。
+
+章节来源
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L207-L262)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L36-L82)
+
+### API 与前端交互
+- 获取详情
+  - API 返回 Assessment 及其明细，前端渲染明细表格并注入指标名称。
+- 更新明细
+  - 前端提交包含 indicator_id、actual_value、score、evidence 的数组，服务层删除旧明细并插入新明细，重新计算总分与加权得分。
+- 提交/审核/确认
+  - 前端调用提交、审核、确认接口，服务层更新状态并持久化。
+
+章节来源
+- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L160-L213)
+- [assessment.js](file://frontend/src/api/assessment.js#L8-L36)
+
+## 依赖关系分析
+- AssessmentDetail 与 Assessment 的多对一
+  - 通过 assessment_id 外键关联，Assessment.details 为反向关系。
+- AssessmentDetail 与 Indicator 的一对一
+  - 通过 indicator_id 外键关联，Indicator.assessment_details 为反向关系。
+- 服务层依赖
+  - 服务层在创建/更新时读取指标权重，计算加权得分；在批量初始化时遍历在职员工并为每个员工生成明细。
+
+```mermaid
+classDiagram
+class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+float total_score
+float weighted_score
+string status
+AssessmentDetail[] details
+}
+class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
+Assessment assessment
+Indicator indicator
+}
+class Indicator {
+int id
+string name
+string code
+float weight
+AssessmentDetail[] assessment_details
+}
+Assessment "1" <-- "many" AssessmentDetail : "details"
+Indicator "1" <-- "many" AssessmentDetail : "assessment_details"
+```
+
+图表来源
+- [models.py](file://backend/app/models/models.py#L149-L178)
+- [models.py](file://backend/app/models/models.py#L181-L202)
+- [models.py](file://backend/app/models/models.py#L117-L146)
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L149-L202)
+
+## 性能考量
+- 索引设计
+  - idx_detail_assessment：按 assessment_id 查询明细时使用，适合按考核记录聚合明细。
+  - idx_detail_indicator：按指标查询明细时使用，适合按指标维度统计。
+- 查询优化建议
+  - 按考核记录查询明细：优先使用 assessment_id 进行过滤与排序。
+  - 按指标查询明细：优先使用 indicator_id 进行过滤与排序。
+  - 分页与排序：结合数据库索引与分页参数，避免全表扫描。
+  - 批量操作：批量创建/更新明细时，尽量减少往返次数，使用服务层提供的批量接口。
+- 大体量数据的性能考虑
+  - 使用索引覆盖查询，避免隐式转换与函数包裹。
+  - 对高频查询（如按年月/状态/科室）考虑复合索引或物化视图（视数据库能力而定）。
+  - 控制单次明细数量，避免一次性加载过多明细导致内存压力。
+
+章节来源
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L207-L262)
+
+## 故障排查指南
+- 常见问题
+  - 无法提交/审核/确认：检查考核记录状态是否符合要求（草稿、已提交、已审核）。
+  - 明细更新无效：确认前端处于草稿状态，且提交的数据包含完整的 indicator_id、actual_value、score、evidence。
+  - 得分异常：检查指标权重是否正确，以及服务层是否正确读取并参与加权计算。
+- 排查步骤
+  - 查看 API 返回的状态码与错误信息。
+  - 检查数据库中 assessment_details 的 assessment_id 与 indicator_id 是否有效。
+  - 核对前端传参与后端模式约束是否匹配。
+  - 在服务层增加日志，打印明细集合与计算过程的关键变量。
+
+章节来源
+- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
+
+## 结论
+考核明细表是连接“考核记录”与“指标”的桥梁，承担着记录实际值、得分与佐证材料的关键职责。通过明确的字段定义、严格的索引设计与服务层的加权计算逻辑，系统能够稳定地支持详细评分、证据管理与数据追溯等核心业务场景。对于大体量数据，建议结合索引与分页策略，持续优化查询路径，确保系统在高并发下的稳定性与性能。
+
+## 附录
+- 建议的索引与查询模式
+  - 按 assessment_id 查询明细：使用 idx_detail_assessment。
+  - 按 indicator_id 查询明细：使用 idx_detail_indicator。
+  - 按年月/状态/科室聚合：结合 assessments 表的索引与分页参数进行高效查询。
--- a/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核记录表.md
+++ b/.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核记录表.md
@@ -0,0 +1,597 @@
+# 考核记录表
+
+<cite>
+**本文档引用的文件**
+- [assessments.py](file://backend/app/api/v1/assessments.py)
+- [models.py](file://backend/app/models/models.py)
+- [assessment_service.py](file://backend/app/services/assessment_service.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [assessment.js](file://frontend/src/api/assessment.js)
+- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
+- [database.md](file://docs/database.md)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py)
+- [security.py](file://backend/app/core/security.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+考核记录表(assessments)是医院绩效管理系统的核心数据表，用于存储员工的绩效考核信息。该表实现了完整的考核生命周期管理，包括考核创建、提交、审核、确认等流程，并支持多层级的权限控制和状态管理。
+
+## 项目结构
+
+考核记录表相关的代码分布在以下层次：
+
+```mermaid
+graph TB
+subgraph "前端层"
+FE_API[assessment.js]
+FE_VIEW[Assessments.vue]
+end
+subgraph "后端层"
+API[assessments.py]
+SERVICE[assessment_service.py]
+MODELS[models.py]
+SCHEMAS[schemas.py]
+SECURITY[security.py]
+end
+subgraph "数据库层"
+DB[assessments表]
+DETAIL[assessment_details表]
+INDEX[idx_assessment_staff<br/>idx_assessment_period<br/>idx_assessment_status]
+end
+FE_API --> API
+FE_VIEW --> FE_API
+API --> SERVICE
+SERVICE --> MODELS
+MODELS --> DB
+DB --> DETAIL
+DB --> INDEX
+```
+
+**图表来源**
+- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+- [models.py](file://backend/app/models/models.py#L149-L178)
+
+**章节来源**
+- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [models.py](file://backend/app/models/models.py#L149-L178)
+
+## 核心组件
+
+### 数据模型定义
+
+考核记录表采用SQLAlchemy ORM映射，定义了完整的字段结构和关系：
+
+```mermaid
+classDiagram
+class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+string period_type
+float total_score
+float weighted_score
+AssessmentStatus status
+int assessor_id
+int reviewer_id
+datetime submit_time
+datetime review_time
+string remark
+datetime created_at
+datetime updated_at
+staff : Staff
+assessor : Staff
+reviewer : Staff
+details : AssessmentDetail[]
+}
+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 : Assessment[]
+salary_records : SalaryRecord[]
+}
+class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
+datetime created_at
+datetime updated_at
+assessment : Assessment
+indicator : Indicator
+}
+Assessment --> Staff : "staff_id"
+Assessment --> Staff : "assessor_id"
+Assessment --> Staff : "reviewer_id"
+Assessment --> AssessmentDetail : "details"
+AssessmentDetail --> Indicator : "indicator_id"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L149-L178)
+- [models.py](file://backend/app/models/models.py#L181-L202)
+
+### 字段业务含义详解
+
+#### 基础字段
+- **staff_id**: 员工ID，外键关联到员工表，标识被考核的员工
+- **period_year**: 考核年度，支持2020-2100年的范围
+- **period_month**: 考核月份，支持1-12的范围
+- **period_type**: 考核周期类型，默认为"monthly"(月度)，支持其他周期类型扩展
+
+#### 绩效计算字段
+- **total_score**: 总分，所有考核指标得分的简单相加
+- **weighted_score**: 加权得分，根据指标权重计算的加权平均分
+
+#### 状态管理字段
+- **status**: 考核状态，使用AssessmentStatus枚举管理
+- **assessor_id**: 考核人ID，负责创建和维护考核记录
+- **reviewer_id**: 审核人ID，负责审核和批准考核结果
+
+#### 时间戳字段
+- **submit_time**: 提交时间，记录考核提交到审核阶段的时间
+- **review_time**: 审核时间，记录考核审核完成的时间
+
+#### 备注字段
+- **remark**: 备注信息，用于记录审核意见或其他说明
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L149-L178)
+- [schemas.py](file://backend/app/schemas/schemas.py#L220-L270)
+
+## 架构概览
+
+考核记录表的完整架构包括API层、服务层、数据模型层和数据库层：
+
+```mermaid
+sequenceDiagram
+participant Client as 前端客户端
+participant API as API路由层
+participant Service as 服务层
+participant DB as 数据库
+participant Model as 数据模型
+Client->>API : GET /assessments
+API->>Service : get_list()
+Service->>DB : 查询assessments表
+DB->>Model : 返回ORM对象
+Model->>Service : Assessment对象列表
+Service->>API : Assessment列表
+API->>Client : JSON响应
+Client->>API : POST /assessments/{id}/submit
+API->>Service : submit()
+Service->>DB : 更新状态为SUBMITTED
+DB->>Model : 返回更新后的Assessment
+Service->>API : Assessment对象
+API->>Client : 提交成功
+```
+
+**图表来源**
+- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L52)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L18-L55)
+
+**章节来源**
+- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+
+## 详细组件分析
+
+### 状态枚举和转换机制
+
+考核状态枚举定义了完整的状态转换流程：
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿 : 创建考核
+草稿 --> 已提交 : 提交考核
+已提交 --> 已审核 : 审核通过
+已提交 --> 已驳回 : 审核驳回
+已审核 --> 已确认 : 确认考核
+已确认 --> [*]
+已驳回 --> 草稿 : 修改后重新提交
+```
+
+**状态转换规则**：
+- 草稿状态只能由创建者修改，支持重新编辑
+- 已提交状态只能由审核人处理，不可直接修改
+- 已审核状态可以被确认，进入最终状态
+- 已驳回状态可以返回草稿状态进行修正
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L45-L52)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
+
+### 自关联关系实现
+
+考核记录表实现了复杂的自关联关系：
+
+```mermaid
+erDiagram
+ASSESSMENTS {
+int id PK
+int staff_id FK
+int assessor_id FK
+int reviewer_id FK
+int period_year
+int period_month
+string period_type
+float total_score
+float weighted_score
+string status
+datetime submit_time
+datetime review_time
+text remark
+datetime created_at
+datetime updated_at
+}
+STAFF {
+int id PK
+string employee_id UK
+string name
+int department_id FK
+string position
+string title
+string phone
+string email
+decimal base_salary
+decimal performance_ratio
+string status
+datetime hire_date
+datetime created_at
+datetime updated_at
+}
+ASSESSMENTS ||--|| STAFF : "staff_id"
+ASSESSMENTS ||--|| STAFF : "assessor_id"
+ASSESSMENTS ||--|| STAFF : "reviewer_id"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L149-L178)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L169-L173)
+
+### 权限控制和身份验证
+
+系统实现了多层级的权限控制机制：
+
+```mermaid
+flowchart TD
+Start([用户请求]) --> CheckAuth["验证用户身份"]
+CheckAuth --> CheckRole{"检查用户角色"}
+CheckRole --> |普通员工| CheckStatus{"检查考核状态"}
+CheckRole --> |管理员| AllowAdmin["允许所有操作"]
+CheckRole --> |经理| CheckManager{"检查操作类型"}
+CheckStatus --> |草稿状态| AllowEdit["允许编辑"]
+CheckStatus --> |已提交状态| DenyEdit["拒绝编辑"]
+CheckStatus --> |已审核状态| DenyEdit
+CheckManager --> |提交/审核| AllowManager["允许审核操作"]
+CheckManager --> |确认| AllowManager
+CheckManager --> |创建| DenyManager["拒绝创建"]
+AllowAdmin --> End([授权通过])
+AllowEdit --> End
+AllowManager --> End
+DenyEdit --> End
+DenyManager --> End
+```
+
+**权限控制规则**：
+- 普通员工只能操作自己的草稿状态考核
+- 经理和管理员可以进行审核和确认操作
+- 不同状态下的操作权限严格限制
+
+**章节来源**
+- [security.py](file://backend/app/core/security.py#L94-L109)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
+
+### API接口设计
+
+系统提供了完整的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 | 管理员/经理 | 批量创建考核 |
+
+**章节来源**
+- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
+
+### 前端集成和使用场景
+
+前端提供了完整的用户界面和交互体验：
+
+```mermaid
+graph LR
+subgraph "前端界面"
+LIST[考核列表页面]
+DETAIL[考核详情页面]
+BATCH[批量创建弹窗]
+end
+subgraph "API调用"
+GET_LIST[getAssessments]
+GET_DETAIL[getAssessment]
+CREATE[createAssessment]
+UPDATE[updateAssessment]
+SUBMIT[submitAssessment]
+REVIEW[reviewAssessment]
+FINALIZE[finalizeAssessment]
+BATCH_CREATE[batchCreateAssessments]
+end
+LIST --> GET_LIST
+DETAIL --> GET_DETAIL
+LIST --> CREATE
+LIST --> UPDATE
+LIST --> SUBMIT
+LIST --> REVIEW
+LIST --> FINALIZE
+BATCH --> BATCH_CREATE
+```
+
+**典型使用场景**：
+
+1. **流程审批场景**：
+   - 员工创建草稿考核
+   - 直接提交到上级审核
+   - 审核通过后自动进入确认阶段
+
+2. **状态跟踪场景**：
+   - 实时显示考核状态变化
+   - 支持按状态筛选和排序
+   - 提供状态变更历史记录
+
+3. **数据统计场景**：
+   - 按科室统计平均分
+   - 按时间段分析趋势
+   - 生成绩效报告和图表
+
+**章节来源**
+- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
+- [assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+
+## 依赖关系分析
+
+### 数据库依赖关系
+
+```mermaid
+erDiagram
+DEPARTMENTS {
+int id PK
+string name
+string code UK
+string dept_type
+int parent_id FK
+int level
+int sort_order
+boolean is_active
+text description
+datetime created_at
+datetime updated_at
+}
+STAFF {
+int id PK
+string employee_id UK
+string name
+int department_id FK
+string position
+string title
+string phone
+string email
+decimal base_salary
+decimal performance_ratio
+string status
+datetime hire_date
+datetime created_at
+datetime updated_at
+}
+ASSESSMENTS {
+int id PK
+int staff_id FK
+int period_year
+int period_month
+string period_type
+decimal total_score
+decimal weighted_score
+string status
+int assessor_id FK
+int reviewer_id FK
+datetime submit_time
+datetime review_time
+text remark
+datetime created_at
+datetime updated_at
+}
+ASSESSMENT_DETAILS {
+int id PK
+int assessment_id FK
+int indicator_id FK
+decimal actual_value
+decimal score
+text evidence
+text remark
+datetime created_at
+datetime updated_at
+}
+INDICATORS {
+int id PK
+string name
+string code UK
+string indicator_type
+decimal weight
+decimal max_score
+decimal target_value
+string unit
+text calculation_method
+text description
+boolean is_active
+datetime created_at
+datetime updated_at
+}
+DEPARTMENTS ||--o{ STAFF : "1:N"
+STAFF ||--o{ ASSESSMENTS : "1:N"
+ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "1:N"
+INDICATORS ||--o{ ASSESSMENT_DETAILS : "1:N"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L62-L85)
+- [models.py](file://backend/app/models/models.py#L88-L114)
+- [models.py](file://backend/app/models/models.py#L149-L178)
+- [models.py](file://backend/app/models/models.py#L181-L202)
+- [models.py](file://backend/app/models/models.py#L117-L146)
+
+### 服务层依赖关系
+
+```mermaid
+graph TD
+API[API路由层] --> Service[AssessmentService]
+Service --> Model[Assessment模型]
+Service --> DetailModel[AssessmentDetail模型]
+Service --> StaffModel[Staff模型]
+Service --> IndicatorModel[Indicator模型]
+Service --> Schema[Pydantic Schema]
+Schema --> CreateSchema[AssessmentCreate]
+Schema --> UpdateSchema[AssessmentUpdate]
+Schema --> ResponseSchema[AssessmentResponse]
+API --> Security[安全验证]
+Security --> CurrentUser[get_current_active_user]
+Security --> ManagerUser[get_current_manager_user]
+Security --> AdminUser[get_current_admin_user]
+```
+
+**图表来源**
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L11)
+- [schemas.py](file://backend/app/schemas/schemas.py#L228-L270)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L1-L438)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+
+## 性能考虑
+
+### 数据库索引设计
+
+系统采用了多层次的索引策略来优化查询性能：
+
+```mermaid
+graph LR
+subgraph "主表索引"
+IDX_STAFF[idx_assessment_staff]
+IDX_PERIOD[idx_assessment_period]
+IDX_STATUS[idx_assessment_status]
+end
+subgraph "明细表索引"
+IDX_DETAIL_ASSESS[idx_detail_assessment]
+IDX_DETAIL_INDICATOR[idx_detail_indicator]
+end
+subgraph "查询优化"
+OPTIMIZE1[按员工ID查询]
+OPTIMIZE2[按考核周期查询]
+OPTIMIZE3[按状态过滤]
+OPTIMIZE4[按指标ID查询明细]
+end
+IDX_STAFF --> OPTIMIZE1
+IDX_PERIOD --> OPTIMIZE2
+IDX_STATUS --> OPTIMIZE3
+IDX_DETAIL_ASSESS --> OPTIMIZE4
+```
+
+**索引策略说明**：
+- `idx_assessment_staff`: 优化按员工查询的性能
+- `idx_assessment_period`: 优化按考核周期查询的性能
+- `idx_assessment_status`: 优化按状态过滤的性能
+- `idx_detail_assessment`: 优化明细查询的性能
+
+### 查询优化策略
+
+1. **分页查询**：默认每页20条记录，支持最大100条/页
+2. **条件过滤**：支持按员工ID、科室ID、年度、月份、状态等条件过滤
+3. **预加载关系**：使用selectinload优化N+1查询问题
+4. **批量操作**：支持批量创建和批量查询
+
+### 缓存策略
+
+虽然当前实现未使用缓存，但建议在以下场景考虑缓存：
+- 高频查询的考核统计结果
+- 员工基本信息
+- 指标模板数据
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L174-L178)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L28-L55)
+
+## 故障排除指南
+
+### 常见问题和解决方案
+
+#### 状态转换错误
+**问题**：尝试在错误状态下进行操作
+**解决方案**：检查当前考核状态，确保状态转换符合业务规则
+
+#### 权限不足错误
+**问题**：403 Forbidden错误
+**解决方案**：确认用户角色是否具有相应权限，检查当前操作是否在允许范围内
+
+#### 数据完整性错误
+**问题**：外键约束违反
+**解决方案**：确保关联的员工、指标等数据存在且有效
+
+#### 性能问题
+**问题**：查询响应缓慢
+**解决方案**：检查索引使用情况，优化查询条件，考虑分页和缓存策略
+
+### 调试工具和方法
+
+1. **日志分析**：查看后端日志文件定位问题
+2. **数据库监控**：使用EXPLAIN分析慢查询
+3. **API测试**：使用Swagger UI测试接口功能
+4. **前端调试**：使用浏览器开发者工具调试前端逻辑
+
+**章节来源**
+- [assessments.py](file://backend/app/api/v1/assessments.py#L60-L102)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
+
+## 结论
+
+考核记录表作为医院绩效管理系统的核心组件，实现了完整的考核生命周期管理和多层级权限控制。通过合理的数据模型设计、完善的API接口、严格的权限控制和优化的数据库索引，系统能够高效地支持医院的绩效管理工作。
+
+系统的自关联关系设计使得考核人、审核人和被考核员工的身份验证和权限控制变得清晰明确。状态枚举和状态转换机制确保了考核流程的规范性和可追溯性。
+
+未来可以在现有基础上进一步优化：
+- 增加缓存机制提升查询性能
+- 扩展更多统计分析功能
+- 增强审计日志功能
+- 支持更多类型的考核周期和指标